ComputedStore<T> class

An OrbitStore that computes derived state from other stores.

It automatically tracks which stores are read via the watch reader passed to its compute function, and recomputes and notifies its own listeners when any dependency changes.

By default, the recomputed value is compared with the previous one using == to decide whether to notify listeners. That's fine for primitives and value types, but if your compute function returns a fresh List/Map/Set each time (as most .where().toList()-style derivations do), == compares by identity and is always unequal — so listeners get notified on every dependency change even when the derived contents haven't actually changed. Pass equals for value-based comparison in that case, e.g. using package:collection's ListEquality/SetEquality/MapEquality.

A ComputedStore that reads another ComputedStore which (directly or transitively) reads back into the first one throws a clear StateError describing the cycle, rather than crashing with a confusing LateInitializationError.

Inheritance

Constructors

ComputedStore(T _compute(StoreReader watch), {bool equals(T previous, T next)?})
Creates a ComputedStore with the given _compute function.

Properties

hashCode → int
The hash code for this object.
no setterinherited
hasListeners → bool
Whether any listeners are currently registered.
no setterinherited
initError ↔ Object?
Set if init threw synchronously, or its returned future completed with an error. null otherwise.
getter/setter pairinherited
initStackTrace ↔ StackTrace?
The stack trace paired with initError, if any.
getter/setter pairinherited
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 setterinherited
ready → Future<void>
Completes once init finishes.
no setterinherited
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
state → T
The computed value.
no setter

Methods

addListener(VoidCallback listener) → void
Register a closure to be called when the object changes.
inherited
batch<T>(FutureOr<T> fn(), {String? label}) → FutureOr<T>
Runs fn inside a store-scoped batch.
inherited
debounce(String id, Duration duration, FutureOr<void> action()) → void
Debounces action, executing it only after duration of inactivity.
inherited
dispose() → void
Discards any resources used by the object.
inherited
inferLabelForTest(String? explicitLabel, StackTrace trace) → String?
Exposed helper for testing label inference on custom stack traces.
inherited
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.
override
mutate<R>(R action(), {String? label}) → R
Runs action, then notifies every listener that state changed.
inherited
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.
inherited
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
notifyListeners() → void
Call all the registered listeners.
inherited
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.
override
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.
inherited
removeListener(VoidCallback listener) → void
Remove a previously registered closure from the list of closures that are notified when the object changes.
inherited
snapshot() → Map<String, Object?>?
Override to return a snapshot of your state's fields.
override
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.
inherited
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.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited