orbital_state

Reactive state mixin for OrbitalLifecycle objects in the Orbital ecosystem.

What this package contains

orbital_state provides StateMixin<T>, a small mixin that adds reactive state to any OrbitalLifecycle controller (as used by orbital_injector and orbital_router), without requiring an external state manager.

It handles:

  • lazily creating a ValueNotifier<T> on the first emit
  • rebuilding widgets via watch whenever state changes
  • subscribing other lifecycle owners via listen, with automatic cleanup through addDisposer when the owner is disposed
  • disposing the underlying notifier from onDispose

The framework does not define loading/error/empty states — model T as you need (sealed class, enum, plain class, etc.).

Quick start

class CounterController extends OrbitalLifecycle with StateMixin<int> {
  @override
  FutureOr<void> onInit() {
    emit(0);
  }

  void increment() => emit(state + 1);
}

// In a widget:
controller.watch((count) => Text('count:$count'));

watch vs listen

  • watch returns a widget that rebuilds itself whenever emit changes state.
  • listen subscribes an OrbitalLifecycle owner to another controller's state changes with a plain callback, and automatically removes the subscription when the owner is disposed. Pass fireImmediately: true to invoke the callback once with the current state when registering.

Both require at least one prior emit — emit the initial state in onInit before calling watch or listen.

More detail

See doc.md for the design rationale and lifecycle interaction with orbital_core and orbital_injector.

Libraries

orbital_state