OrbitStore class abstract

Base class for all Orbit stores.

Declare state as private fields with public getters — not public mutable fields. Only code inside the store's own file can then touch them, so every change is forced through mutate, which is what keeps rebuilds, Orbit.observe middleware, and Orbit.changeLog honest. A public mutable field can still be written directly from outside the class, silently skipping all of that.

class CounterStore extends OrbitStore {
  int _count = 0;
  int get count => _count;

  // Getters are just Dart getters — no special "computed" API
  // needed, they always read the latest fields.
  int get doubleCount => _count * 2;

  void increment() => mutate(() => _count++);

  // Optional: called once, sync or async, right after creation.
  @override
  Future<void> init() async {
    _count = await loadPersistedCount();
  }

  // Optional: cleanup when the store is disposed.
  @override
  void onDispose() => _subscription?.cancel();

  // Optional: powers Orbit.observe/changeLog diffing, and undo/redo
  // if this store also mixes in Undoable.
  @override
  Map<String, Object?> snapshot() => {'count': _count};
}

Inheritance

• Object
• ChangeNotifier
• OrbitStore

Implementers

• ComputedStore
• FutureProvider
• StreamProvider
• Undoable

Constructors

OrbitStore()

Properties

hashCode → int

The hash code for this object.

no setter, inherited

hasListeners → bool

Whether any listeners are currently registered.

no setter, inherited

initError ↔ Object?

Set if init threw synchronously, or its returned future completed with an error. null otherwise.

getter/setter pair

initStackTrace ↔ StackTrace?

The stack trace paired with initError, if any.

getter/setter pair

isReady → bool

True once ready has completed successfully. false if it hasn't completed yet, or if it completed with an error — check initError to tell those two apart.

no setter

ready → Future<void>

Completes once init finishes.

no setter

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

Methods

addListener(VoidCallback listener) → void

Register a closure to be called when the object changes.

override

batch<T>(FutureOr<T> fn(), {String? label}) → FutureOr<T>

Runs fn inside a store-scoped batch.

debounce(String id, Duration duration, FutureOr<void> action()) → void

Debounces action, executing it only after duration of inactivity.

dispose() → void

Discards any resources used by the object.

override

inferLabelForTest(String? explicitLabel, StackTrace trace) → String?

Exposed helper for testing label inference on custom stack traces.

init() → FutureOr<void>

Called exactly once, immediately after the store is first created by Orbit.use (or OrbitScope). Override to run setup logic — e.g. loading persisted state from disk, or an initial network fetch. Can be synchronous or asynchronous.

mutate<R>(R action(), {String? label}) → R

Runs action, then notifies every listener that state changed.

mutateAsync<T>({required Future<T> action(), required void apply(T result), void onError(Object error, StackTrace stack)?, String? label}) → Future<void>

Asynchronously executes action, then passes the result to apply inside mutate if successful.

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

notifyListeners() → void

Call all the registered listeners.

override

onDispose() → void

Called when this store is disposed — via Orbit.reset<T>(), Orbit.resetAll(), Orbit.override<T>(), or when an OrbitScope<T> unmounts. Override to clean up timers, stream subscriptions, and the like. Runs before the underlying ChangeNotifier is disposed.

onResume() → void

Called when the app returns to the foreground (AppLifecycleState.resumed) while this store is alive — handy for refreshing time-sensitive data. No-op by default.

removeListener(VoidCallback listener) → void

Remove a previously registered closure from the list of closures that are notified when the object changes.

override

snapshot() → Map<String, Object?>?

Override to return a snapshot of your state's fields.

throttle(String id, Duration duration, FutureOr<void> action()) → void

Throttles action, executing it immediately and rate-limiting subsequent calls to at most once per duration.

toString() → String

A string representation of this object.

inherited

watch<S extends OrbitStore>(OrbitStoreRef<S> storeRef, void onChange(S store)) → void

Watches another global store and executes onChange whenever it notifies. Automatically unsubscribes when this store is disposed.

Operators

operator ==(Object other) → bool

The equality operator.

inherited