Shard<T> class abstract

A generic state management class that holds typed state.

Shard extends ChangeNotifier and provides a clean API for managing application state with built-in lifecycle management, debounce, and throttle support via mixins.

Creating a Shard

class CounterShard extends Shard<int> {
  CounterShard() : super(0);

  void increment() => emit(state + 1);
  void decrement() => emit(state - 1);
  void reset() => emit(0);
}

State Updates

Use emit to update state and notify listeners:

void updateValue(int newValue) {
  emit(newValue);
}

Lifecycle

onInit - Called when the shard is created
dispose - Called when the shard is disposed

Observer Methods

Override these methods to handle events locally:

onChange - Called when state changes
onError - Called when an error is reported via addError

Example with Complex State

class UserShard extends Shard<UserState> {
  UserShard() : super(UserState.initial());

  Future<void> fetchUser(String id) async {
    emit(state.copyWith(isLoading: true));
    try {
      final user = await api.getUser(id);
      emit(state.copyWith(isLoading: false, user: user));
    } catch (e, st) {
      addError(e, st);
      emit(state.copyWith(isLoading: false, error: e.toString()));
    }
  }
}

Constructors

Shard(T initialState): Creates a new Shard with the given initial state.

Properties

hashCode → int: The hash code for this object.
no setterinherited
hasListeners → bool: Whether any listeners are currently registered.
no setterinherited
isDisposed → bool: Returns whether this shard has been disposed.
no setter
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
state → T: The current state of the shard.
no setter
stream → Stream<T>: A broadcast Stream of state changes.
no setter

Methods

addError(Object error, [StackTrace? stackTrace]) → void: Reports an error without blocking the execution flow.
addListener(VoidCallback listener) → void: Register a closure to be called when the object changes.
inherited
cancelAllDebounce() → void: Cancels all debounce operations.
inherited
cancelAllThrottle() → void: Cancels all throttle operations.
inherited
cancelDebounce(String key) → void: Cancels a specific debounce operation by key.
inherited
cancelThrottle(String key) → void: Cancels a specific throttle operation by key.
inherited
debounce(String key, VoidCallback callback, {Duration duration = const Duration(milliseconds: 300)}) → void: Debounces a callback with the given key.
inherited
dispose() → void: Disposes the shard and cleans up resources.
override
disposePersistenceIfEnabled() → void: Internal hook for persistence cleanup.
emit(T newState) → void: Updates the state and notifies all listeners.
emitForce(T newState) → void: Updates the state and notifies all listeners, bypassing equality check.
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
notifyListeners() → void: Call all the registered listeners.
inherited
onChange(T previousState, T currentState) → void: Called whenever the state changes.
onError(Object error, StackTrace? stackTrace) → void: Called when an error is reported via addError.
onInit() → void: Called when the shard is initialized.
removeListener(VoidCallback listener) → void: Remove a previously registered closure from the list of closures that are notified when the object changes.
inherited
setStateInternal(T newState) → void: Internal method for setting state directly.
stateEquals(T a, T b) → bool: Determines whether two state instances are equal.
throttle(String key, VoidCallback callback, {Duration duration = const Duration(milliseconds: 300)}) → bool: Throttles a callback with the given key.
inherited
toString() → String: A string representation of this object.
inherited

Operators

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

Static Properties

observer ↔ ShardObserver?: Global observer for all Shard instances.
getter/setter pair