result_command library

Result Command

Result Command is a lightweight package that brings the Command Pattern to Flutter, allowing you to encapsulate actions, track their execution state, and manage results with clarity. Perfect for simplifying complex workflows, ensuring robust error handling, and keeping your UI reactive.

Why Use Result Command?

  1. Encapsulation: Wrap your business logic into reusable commands.
  2. State Tracking: Automatically manage states like Idle, Running, Success, Failure, and Cancelled.
  3. Error Handling: Centralize how you handle successes and failures using the intuitive Result API.
  4. State History: Track state transitions with optional metadata.
  5. Timeout Support: Specify execution time limits for commands.
  6. Cancellation Support: Cancel long-running tasks when needed.
  7. UI Integration: React to command state changes directly in your Flutter widgets.

How It Works

At its core, Result Command lets you define reusable actions (commands) that manage their lifecycle. Each command:

  • Executes an action (e.g., API call, user input validation).
  • Tracks its state (Idle, Running, etc.).
  • Notifies listeners when the state changes.
  • Maintains a history of states and transitions.
  • Returns a result (Success or Failure) using the Result API.

Command State (CommandState)

Each Command exposes its current state through a CommandState. The state represents one of the following:

  • IdleCommand: The command is ready to execute.
  • RunningCommand: The command is currently executing an action.
  • SuccessCommand: The action completed successfully.
  • FailureCommand: The action failed with an error.
  • CancelledCommand: The action was explicitly stopped.

Accessing the State

You can access the current state using the value property of the command:

final command = Command0<String>(() async {
 return Success('Hello, World!');
});

// The current state of the command.
print(command.value); // Outputs: SuccessCommand<String>

Reacting to State Changes

The state updates automatically as the command executes:

  • Use addListener for manual handling.
  • Use ValueListenableBuilder to bind the state to your UI.

State History (CommandHistory)

Each command tracks a configurable history of its states, useful for debugging, auditing, and behavioral analysis.

Configuring the History

Set the maximum length of the history when creating a command:

final command = Command0<String>(
 () async => const Success('Done'),
 maxHistoryLength: 5,
);

Accessing the History

Access the history with stateHistory:

final history = command.stateHistory;
history.forEach(print);

Getters for State Checks

To simplify state management and improve code readability, the following getters are available:

  • isIdle: Checks if the command is in the idle state.
bool get isIdle => value is IdleCommand<T>;
  • isRunning: Checks if the command is currently running.
bool get isRunning => value is RunningCommand<T>;
  • isCancelled: Checks if the command has been cancelled.
bool get isCancelled => value is CancelledCommand<T>;
  • isSuccess: Checks if the command execution was successful.
bool get isSuccess => value is SuccessCommand<T>;
  • isFailure: Checks if the command execution failed.
bool get isFailure => value is FailureCommand<T>;

These getters allow you to write cleaner and more intuitive code when interacting with commands in your views or controllers.

Classes

CancelledCommand<T extends Object>
Represents the cancelled state of a command.
Command<T extends Object>
Represents a generic command with lifecycle and execution.
Command0<T extends Object>
A command that executes an action without any arguments.
Command1<T extends Object, A>
A command that executes an action with one argument.
Command2<T extends Object, A, B>
A command that executes an action with two arguments.
CommandHistoryEntry<T extends Object>
Represents a command history entry with timestamp and metadata.
CommandRef<T extends Object, W>
Represents a command that listens to changes in one or more ValueListenables and executes an action.
CommandState<T extends Object>
Base class representing the state of a command.
FailureCommand<T extends Object>
Represents a command that failed to execute successfully.
IdleCommand<T extends Object>
Represents the idle state of a command (not running).
RunningCommand<T extends Object>
Represents the running state of a command.
SuccessCommand<T extends Object>
Represents a command that executed successfully.

Mixins

CommandHistoryManager<T extends Object>
Manages the history of command states.

Typedefs

CommandAction0<T extends Object> = AsyncResult<T> Function()
A function that defines a command action with no arguments. The action returns an AsyncResult of type T.
CommandAction1<T extends Object, A> = AsyncResult<T> Function(A)
A function that defines a command action with one argument of type A. The action returns an AsyncResult of type T.
CommandAction2<T extends Object, A, B> = AsyncResult<T> Function(A, B)
A function that defines a command action with two arguments of types A and B. The action returns an AsyncResult of type T.
CommandRefAction0<W> = W Function(V <V>(ValueListenable<V> listenable))