UseReducer

UseReducer is a hook that manages state using reducer function. An alternative to UseState .

Tip

UseReducer is usually preferable over UseState when you have complex state logic that involves multiple sub-values or when the next state depends on the previous one.

Syntax

UseReducer<T>(
  T reducer(T state, ReactterAction action),
  T initialValue,
);

UseReducer accepts these arguments:

• reducer : A function that takes the current state and an action, and returns a new state.
• initialState: Initial value of T type that it will hold.

Properties & Methods

UseReducer provides the following properties and methods:

• value: A getter that allows to read its state.
• dispatch : A method that allows to dispatch an action to update the state.
  • Syntax:

    void dispatch(ReactterAction action);

• Methods inherited from ReactterState (Learn more here):

  • update : A method to notify changes after run a set of instructions.
  • refresh : A method to force to notify changes.
  • * bind : A method to bind an instance to it.
  • * unbind : A method to unbind an instance to it.
  • * dispose : A method to remove all listeners and free resources.

  Note

  * These methods are unnecessary when is declared within a dependency(class registered via the dependecy injection).

Usage

Declaration

UseReducer can be initialized using the constructor class:

import 'package:reactter/reactter.dart';

class User {
  final String name;
  final int age;

  const User({required this.name, required this.age});

  @override
  String toString() => "User(name: $name, age: $age)";
}

class UserAction extends ReactterAction {
  UserAction.incrementedAge() : super(type: 'incremented_age', payload: null);
  UserAction.changedName(String name)
      : super(type: 'changed_name', payload: name);
}

User reducer(User state, ReactterAction action) {
  switch (action.type) {
    case "incremented_age":
      return User(state.name, state.age + 1);
    case "changed_name":
      return User(action.payload as String, state.age);
    default:
      return state;
  }
}

final uUser = UseReducer<User>(
  reducer,
  const User(
    name: "John Doe",
    age: 17,
  ),
);

void main() {
  print("${uUser.value}") // User(name: "John Doe", age: 17)
  uUser.dispatch(UserAction.incrementedAge());
  print("${uUser.value}"); // User(name: "John Doe", age: 18)
  uUser.dispatch(UserAction.changedName("Jane Doe"));
  print("${uUser.value}"); // User(name: "Jane Done", age: 18)
}

Note

In some cases, you may need to declare a state variable that will be initialized later. For this, you can use the late keyword. When using UseReducer as late within a dependency(class registered via the dependency injection), use Reactter.lazyState (Learn more about Lazy state binding). e.g:

user_controller.dart

class UserController {
  final String userId;

  late final uUser = Reactter.lazyState(
    () => UseReducer<User?>.withArg(this.reducer, null),
    this,
  );

  UserController(this.userId);

  User? reducer(User? state, ReactterAction action) {
    if (action is IncrementedEgeUserAction) {
      return User(name: state!.name, age: state.age + 1);
    } else if (action is ChangedNameUserAction) {
      return User(name: action.name, age: state!.age);
    }
    return state;
  }
}

Writting the action

The action is a class that inherits from the ReactterAction class.

This class contains the action type and payload that will be dispatched to the reducer method.

import 'package:reactter/reactter.dart';

class User {
  final String name;
  final int age;

  const User({required this.name, required this.age});

  @override
  String toString() => "User(name: $name, age: $age)";
}

class UserAction extends ReactterAction {
  UserAction.incrementedAge() : super(type: 'incremented_age', payload: null);
  UserAction.changedName(String name)
      : super(type: 'changed_name', payload: name);
}

User reducer(User state, ReactterAction action) {
  switch (action.type) {
    case "incremented_age":
      return User(state.name, state.age + 1);
    case "changed_name":
      return User(action.payload as String, state.age);
    default:
      return state;
  }
}

final uUser = UseReducer<User>(
  reducer,
  const User(
    name: "John Doe",
    age: 17,
  ),
);

void main() {
  print("${uUser.value}") // User(name: "John Doe", age: 17)
  uUser.dispatch(UserAction.incrementedAge());
  print("${uUser.value}"); // User(name: "John Doe", age: 18)
  uUser.dispatch(UserAction.changedName("Jane Doe"));
  print("${uUser.value}"); // User(name: "Jane Done", age: 18)
}

Writting the reducer method

The reducer method is a function that takes the current state and an action, and returns a new state. This method is responsible for updating the state based on the action dispatched. The state is immutable, so it should return a new state object.

import 'package:reactter/reactter.dart';

class User {
  final String name;
  final int age;

  const User({required this.name, required this.age});

  @override
  String toString() => "User(name: $name, age: $age)";
}

class UserAction extends ReactterAction {
  UserAction.incrementedAge() : super(type: 'incremented_age', payload: null);
  UserAction.changedName(String name)
      : super(type: 'changed_name', payload: name);
}

User reducer(User state, ReactterAction action) {
  switch (action.type) {
    case "incremented_age":
      return User(state.name, state.age + 1);
    case "changed_name":
      return User(action.payload as String, state.age);
    default:
      return state;
  }
}

final uUser = UseReducer<User>(
  reducer,
  const User(
    name: "John Doe",
    age: 17,
  ),
);

void main() {
  print("${uUser.value}") // User(name: "John Doe", age: 17)
  uUser.dispatch(UserAction.incrementedAge());
  print("${uUser.value}"); // User(name: "John Doe", age: 18)
  uUser.dispatch(UserAction.changedName("Jane Doe"));
  print("${uUser.value}"); // User(name: "Jane Done", age: 18)
}

Dispatching an action and reading the state

The dispatch method is responsible for dispatching an action to the reducer method. After dispatching an action, you can read the state using the value property.

import 'package:reactter/reactter.dart';

class User {
  final String name;
  final int age;

  const User({required this.name, required this.age});

  @override
  String toString() => "User(name: $name, age: $age)";
}

class UserAction extends ReactterAction {
  UserAction.incrementedAge() : super(type: 'incremented_age', payload: null);
  UserAction.changedName(String name)
      : super(type: 'changed_name', payload: name);
}

User reducer(User state, ReactterAction action) {
  switch (action.type) {
    case "incremented_age":
      return User(state.name, state.age + 1);
    case "changed_name":
      return User(action.payload as String, state.age);
    default:
      return state;
  }
}

final uUser = UseReducer<User>(
  reducer,
  const User(
    name: "John Doe",
    age: 17,
  ),
);

void main() {
  print("${uUser.value}") // User(name: "John Doe", age: 17)
  uUser.dispatch(UserAction.incrementedAge());
  print("${uUser.value}"); // User(name: "John Doe", age: 18)
  uUser.dispatch(UserAction.changedName("Jane Doe"));
  print("${uUser.value}"); // User(name: "Jane Done", age: 18)
}

Note

UseReducer notifies that its value has changed when the previous value is different from the current value. If its value is an Object , it does not detect internal changes, only when value is setted to another Object . Learn more about updating objects in state.

Using the action callable

The actions can be created as a callable class, extending from ReactterActionCallable e.g.:

class IncrementedEgeUserAction extends ReactterActionCallable<User, void> {
  const IncrementedEgeUserAction()
    : super(type: 'incremented_ege', payload: null);

  @override
  User call(User state) => User(name: state.name, age: state.age + 1);
}

class ChangedNameUserAction extends ReactterActionCallable<User, String> {
  final String name;

  const ChangedNameUserAction(this.name)
    : super(type: 'changed_name', payload: name);

  @override
  User call(User state) => User(name: payload, age: state.age);
}

ReactterActionCallable has a call method that returns the new state based on the state and payload.

The action callable can be applied in reducer method:

User reducer(User state, ReactterAction action) {
  if (action is ReactterActionCallable) return action(state);
  return state;
}

And dispatched as:

userState.dispatch(IncrementedEgeUserAction());
userState.dispatch(ChangedNameUserAction('Jane Doe'));

Updating the state

Use update method to notify changes after run a set of instructions:

uState.update((value) {
  uState.value = "New value";
});

Use refresh method to force to notify changes.

userState.refresh();

Listening to changes

When value has changed, the UseReducer will emit the following events(learn about it here):

• Lifecycle.willUpdate event is triggered before the value change or update , refresh methods have been invoked.
• Lifecycle.didUpdate event is triggered after the value change or update , refresh methods have been invoked.

Example of listening to changes:

Reactter.on(
  uUser,
  Lifecycle.didUpdate,
  (_, state) => print("State value has changed to: ${state.value}"),
);