atomly #

The pure-Dart core of atomly — atomic state management with one primitive.

This package contains the runtime that powers atomly. It runs on the Dart VM, the web, and Flutter. For Flutter widgets and BuildContext extensions, also depend on atomly_flutter.

Install #

dependencies:
  atomly: ^0.1.0

import 'package:atomly/atomly.dart';

What's in the box #

Quick taste — pure Dart, no Flutter #

import 'package:atomly/atomly.dart';

final counter = Atom(0);
final doubled = Atom.computed((read) => read(counter) * 2);

void main() {
  final store = AtomStore();

  print(store.read(counter)); // 0
  print(store.read(doubled)); // 0

  store.update(counter, (v) => v + 5);

  print(store.read(counter)); // 5
  print(store.read(doubled)); // 10 — invalidated automatically
}

Async state #

final user = Atom.future<User>((read) async {
  final id = read(userIdAtom);
  return await api.fetchUser(id);
});

void main() async {
  final store = AtomStore();

  final initial = store.read(user);
  print(initial); // AtomLoading()

  await Future.delayed(const Duration(seconds: 1));

  final settled = store.read(user);
  print(settled); // AtomData(User(name: 'Alice'))

  // Re-fetch
  store.refresh(user);
}

AtomValue<T> is a sealed class — pattern-match it exhaustively:

final value = store.read(user);
switch (value) {
  case AtomData(:final value):     print('user: ${value.name}');
  case AtomLoading(:final previousData): print('loading (was: $previousData)');
  case AtomError(:final error):    print('failed: $error');
}

// Or use the helper:
value.when(
  data: (u) => print(u.name),
  loading: (prev) => print('loading'),
  error: (e, st, prev) => print('$e'),
);

Family — parameterized atoms #

final post = Atom.family<int, AtomValue<Post>>(
  (id) => Atom.future((read) => api.fetchPost(id)),
);

store.read(post(1)); // AtomLoading() then AtomData(Post(1))
store.read(post(2)); // independent — separate cached state
identical(post(1), post(1)); // true

Auto-dispose and keepAlive #

When the last subscriber unsubscribes, the atom's state is released and any registered cleanup callbacks fire:

final probe = Atom.computed((read) {
  read.onDispose(() => print('cleaning up'));
  return read(counter) * 2;
});

final dispose = store.subscribe(probe, () {});
store.read(probe); // 0
dispose();          // -> prints 'cleaning up'

Opt out:

final session = Atom('guest').keepAlive();

Overrides — test substitution #

final counter = Atom(0);
final user = Atom.future<User>((_) async => api.fetchUser());

final store = AtomStore(overrides: [
  counter.overrideWithValue(42),
  user.overrideWith(Atom.constant(AtomValue.data(testUser))),
]);

store.read(counter); // 42
store.read(user);    // AtomData(testUser) — instantly, no API call

Observers #

final store = AtomStore()
  ..addObserver(CallbackAtomObserver(
    onCreate: (atom, value) => print('+ $atom = $value'),
    onUpdate: (atom, prev, next) => print('~ $atom: $prev → $next'),
    onDispose: (atom, value) => print('- $atom'),
  ));

Implement AtomObserver for richer integrations (DevTools, structured logger, time-travel debugger).

Public API reference #

package:atomly/atomly.dart exports:

• Primitive: Atom<T>, AtomFamily<Arg, R>
• Async state: AtomValue<T>, AtomData<T>, AtomLoading<T>, AtomError<T>
• Reading inside builders: AtomReader
• Runtime: AtomStore
• Overrides: AtomOverride, plus extension methods Atom.overrideWith / Atom.overrideWithValue
• Observers: AtomObserver, CallbackAtomObserver

Tests #

This package ships with 34 unit tests covering value atoms, computed atoms, async (Future) atoms, async (Stream) atoms, families, dependency invalidation, auto-dispose cascade, keepAlive, overrides, observers, refresh, and invalidate.

cd packages/atomly
dart test

License #

MIT.