states_rebuilder

States in states_rebuilder can be managed at two levels:

Global State

Defined in the global scope. These states are singletons and accessible anywhere.

final myState = RM.inject(() => MyState());

Local (Scoped) State

Allows you to encapsulate state within a specific part of the widget tree. Each instance of the widget gets its own independent state. To achieve this, declare the state globally but use .inherited() in the widget tree to override it with a local instance.

To read the scoped state, use .of(context) or .inherited(context).

// 1. Declare globally with a placeholder
final myState = RM.inject(() => throw UnimplementedError());

// 2. In the widget tree, override it
myState.inherited(
  stateOverride: () => MyState(param1, param2),
  builder: (context) {
    // 3. Read the local instance
    final localState = myState.of(context);
    return Text('${localState.state}');
  },
);

An RMKey acts similarly to Flutter's GlobalKey, allowing you to control and synchronize StateBuilder observer widgets from outside their own builder closures.

By assigning an RMKey to the rmKey parameter of a StateBuilder, you can update the state from any other widget in the tree (e.g., a button in a different part of the Scaffold) by modifying the RMKey.value property. Other widgets can also subscribe to the same RMKey via the observe parameter to stay synchronized.

// 1. Define the key
final switchKey = RMKey(true);

// 2. Assign to a StateBuilder to control/notify it
StateBuilder<bool>(
  observe: () => RM.create(true),
  rmKey: switchKey,
  builder: (ctx, switchRM) {
    return Switch(
      value: switchRM.value,
      onChanged: (value) => switchRM.value = value,
    );
  },
)

// 3. Subscribe another widget to the same key
StateBuilder<bool>(
  observe: () => switchKey,
  builder: (ctx, switchRM) {
    return Switch(
      value: switchRM.value,
      onChanged: (value) => switchRM.value = value,
    );
  },
)

// 4. Update from anywhere
switchKey.value = !switchKey.value;

Instead of standard Flutter FutureBuilder or StreamBuilder, states_rebuilder provides specialized widgets that handle various state statuses more exhaustively.

Available Rebuilder Widgets

• StateBuilder: The default widget listener for state changes.
• WhenRebuilder: Exhaustively handles all available state statuses: onIdle, onWaiting, onError, and onData.
• WhenRebuilderOr: Allows selective handling of specific state statuses.
• OnSetStateListener: Used to execute side effects.

Handling Futures and Streams

When using WhenRebuilder with futures or streams, you can define the resulting type in the generic parameters. For example, WhenRebuilder<Foo>(models: [RM.future<int>(...)]) means the model is of type Foo and the resolved value is an int.

// Using WhenRebuilder with a future
WhenRebuilder<Foo>(
  models: [RM.future<int>(Injector.get<Foo>().login())],
  onIdle: () => Text('Welcoming Screen'),
  onWaiting: () => SplashScreen(),
  onError: (e) => Text('An Error has happened'),
  onData: (userId) => Text('${userId}'), // userId is the resolved int
)

// Using WhenRebuilder with a stream
WhenRebuilder<int>(
    models: [RM.stream<int>(IN.get<Foo>().fireStoreStream())],
    onIdle: () => Text('Welcoming Screen'),
    onWaiting: () => SplashScreen(),
    onError: (error) => Text('An Error has happened'),
    onData: (userId) => Text('${userId}'),
)

The Domain layer uses two types of data objects:

Entities

Entities are mutable objects with unique IDs. They represent the in-memory state of data retrieved from a data_source. They should contain the logic they control and be validated just before persistence.

Value Objects

Value objects are immutable objects that have value equality and self-validation but no IDs. They are typically used for form validation (e.g., Email, Password). A value object should either be created in a valid state or throw a ValidationException during construction.

Example: Value Object with self-validation

class Email {
  Email(this.value) {
    if (!Validators.isValidEmail(value)) {
      throw ValidationException('Enter a valid email');
    }
  }

  final String value;
}

class User {
  final String uid;
  final String email;
  final String displayName;
  final String photoUrl;

  User({
    this.uid,
    this.email,
    this.displayName,
    this.photoUrl,
  });
}