commands library

Commands - A Flutter utility library with Result-like extensions and hooks.

This library provides:

  • AsyncSnapshot extensions for Result-like pattern matching (ok, err, pending)
  • Utility hooks for flutter_hooks (useExplicitRender, useObservable, useCancellableFuture)
  • Future utilities (fromCancellableFuture, retryFuture, asyncMap, asyncReduce)

Classes

CommandState<T>
Encapsulates the state and actions for a command.

Extensions

AsyncSnapshotResultExtension on AsyncSnapshot<T>
Extension methods on AsyncSnapshot that provide a Result-like API similar to Kotlin and Rust's Result class, but with an additional "pending" state.

Functions

asyncMap<T, TRet>(List<T> items, Future<TRet> selector(T), {int maxConcurrency = 4}) → Future<Map<T, TRet>>
Maps a list of values to a new Map using an asynchronous selector function with concurrency control.
asyncReduce<T, TAcc>(List<T> items, Future<TAcc> selector(TAcc acc, T item), TAcc seed) → Future<TAcc>
Reduces a list using an asynchronous selector function.
err<T>(Object error, [StackTrace? stackTrace]) → AsyncSnapshot<T>
Creates an AsyncSnapshot with an error (equivalent to Result.err)
fromCancellableFuture<T>(Future<T> block(CancellationToken token)) → Stream<T>
Converts a Future factory (with cancellation token) to a Stream.
fromFuture<T>(Future<T> future) → Future<AsyncSnapshot<T>>
Boxes a Future into an AsyncSnapshot (i.e. captures errors into a snapshot)
ok<T>(T value) → AsyncSnapshot<T>
Creates an AsyncSnapshot with a successful value (equivalent to Result.ok)
pending<T>() → AsyncSnapshot<T>
Creates a pending AsyncSnapshot (equivalent to Result.pending)
retryFuture<T>(Future<T> func(), {int retries = 3}) → Future<T>
Retries a Future-returning function a specified number of times.
useAsyncCallbackDedup<T>(Future<T> block(), List<Object?> keys) → Future<T?> Function()
Create a debounced callback that will only run one instance of the block at a time. If the block is already running, the callback will return null (the pending invocation's Future is NOT returned to avoid multiple awaits on the same Future causing issues).
useCancellableFuture<T>(Future<T> block(CancellationToken token), List<Object?> keys) → AsyncSnapshot<T>
A hook that consumes a cancellable Future and returns its result as an AsyncSnapshot.
useCommand<T>(Future<T> block(), List<Object?> keys, {bool runOnStart = false}) → CommandState<T>
Create a Command. A Command is a method that you can pass to an event handler like onPressed which runs an asynchronous operation (like an HTTP request) in the background, then returns a result. You can think of it as a useCancellableFuture that generates its result when an event handler happens.
useExplicitRender() → ExplicitRenderResult
Custom hook that provides explicit rendering functionality. It returns a record with a dependency value and a rerender function.
useObservable<T>(Stream<T> streamFactory(), List<Object?> keys) → AsyncSnapshot<T>
A hook that consumes a Stream and returns its latest result as an AsyncSnapshot.

Typedefs

ExplicitRenderResult = ({int dep, VoidCallback rerender})
A record containing a dependency value and a rerender function.