Effect<Value> class sealed

Describes a unit of work that can emit values, be cancelled, or compose with other units to form more elaborate workflows.

Example:

final loadUser = Effect.task(() async => await api.fetchUser());
final cancellable = loadUser.cancellable(id: "user");
final debounced = cancellable.debounce(
  id: "user",
  interval: const Duration(milliseconds: 300),
);

Constructors

Effect.asyncPeriodic(Duration interval, Future<Value> computation(int computationCount), {Value onDone()?, Value onError(Object error, StackTrace stackTrace)?, bool? cancelOnError})
Asynchronous counterpart to Effect.periodic. The computation can perform suspending work before yielding each value.
factory
Effect.cancel({required EffectID id})
Requests cancellation for any in-flight effect registered with id. This is the counterpart to Effect.cancellable.
const
factory
Effect.concatenate({required Iterable<Effect<Value>> effects})
Executes the supplied effects sequentially. Each effect starts only after the previous one completes, preserving deterministic ordering.
const
factory
Effect.delayed(Duration duration, Value computation())
Delays executing computation by duration using the default scheduler and emits the returned value once the delay completes.
factory
Effect.merge({required Iterable<Effect<Value>> effects})
Runs every effect in effects concurrently and merges their emissions into a single effect. Completion occurs once all nested effects finish.
const
factory
Effect.none()
Represents the absence of work. Running this effect completes immediately without emitting values or registering cancellations.
const
factory
Effect.periodic(Duration interval, Value computation(int computationCount), {Value onDone()?, Value onError(Object error, StackTrace stackTrace)?, bool? cancelOnError})
Emits a value on every interval using the synchronous computation. Optional callbacks allow consumers to provide completion or error values, or to opt into canceling the subscription when an error occurs.
factory
Effect.run(Value runner(), {Value onError(Object error, StackTrace stackTrace)?})
Runs the synchronous runner immediately when the effect is executed and emits its return value. Errors can be transformed via onError.
const
factory
Effect.stream({required Stream<Value> stream, Value onDone()?, Value onError(Object error, StackTrace stackTrace)?, bool? cancelOnError})
Bridges any Dart Stream into the effect system. Emissions, completion, and errors are forwarded through the provided callbacks.
const
factory
Effect.streamTask(Stream<Value> stream(), {Value onDone()?, Value onError(Object error, StackTrace stackTrace)?, bool cancelOnError = true})
Lazily constructs and subscribes to a stream returned by stream each time the effect runs. Useful when each invocation requires a new stream subscription.
factory
Effect.task(Future<Value> future(), {bool runInIsolate, Value onError(Object error, StackTrace stackTrace)?})
Wraps an asynchronous computation. The future builder is invoked when the effect runs, optionally inside a new isolate. Errors can be mapped to fallback values via onError.
const
factory
Effect.value(Value value)
Emits value synchronously when the effect is run. This is useful for sending immediate feedback without scheduling asynchronous work.
const
factory

Properties

hashCode → int
The hash code for this object.
no setterinherited
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

cancellable({required EffectID id, bool cancelInFlight = false}) → Effect<Value>
Associates this effect with id so that it can be cancelled later. Setting cancelInFlight to true cancels any currently running effect that uses the same identifier before starting this one.
concatenate({required Effect<Value> effect}) → Effect<Value>
Convenience helper for sequencing this effect with effect. Both effects run one after the other, preserving emission order.
debounce({required String id, required Duration interval}) → Effect<Value>
Debounces emissions by delaying them until no new values have arrived for the specified interval. Uses the default scheduler for timing.
debounceWithScheduler<Time, Interval>({required String id, required Interval interval, required Scheduler<Time, Interval> scheduler}) → Effect<Value>
Scheduler-aware variant of Effect.debounce that uses the provided scheduler. The same id is reused to cancel pending debounced work.
delay(Duration duration) → Effect<Value>
Delays emissions by duration on the default scheduler, allowing debounced or scheduled work without manually handling timers.
delayWithScheduler<Time, Interval>(Interval interval, Scheduler<Time, Interval> scheduler) → Effect<Value>
Scheduler-aware delay helper that uses the provided scheduler to pause for interval before running the wrapped effect.
fireAndForget<NewValue>() → Effect<NewValue>
Runs the effect but suppresses any emitted values. Useful for fire-and- forget operations where only the side effects matter.
flatMap<NewValue>(Effect<NewValue> mapper(Value value)) → Effect<NewValue>
For each emitted value, invokes mapper to create another effect and flattens the resulting sequence into a single stream of values.
map<NewValue>(NewValue mapper(Value value)) → Effect<NewValue>
Transforms emitted values using mapper before forwarding them to the reducer or downstream effect handler.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
run(EffectHandler<Value> handler) → Future<void>
Executes the effect immediately with the supplied handler. Each effect implementation defines how it schedules work, emits values, and registers disposables.
throttle({required EffectID id, required Duration interval, ThrottleDirection direction = ThrottleDirection.leading, bool emitFirst = true}) → Effect<Value>
Throttles emissions so that values are produced no more frequently than interval. The default scheduler controls the timing, and direction determines whether leading or trailing values are emitted.
throttleWithScheduler<Time, Interval>({required EffectID id, required Interval interval, required Scheduler<Time, Interval> scheduler, required ThrottleDirection direction, required bool emitFirst}) → Effect<Value>
Scheduler-aware throttle helper that allows custom timing via scheduler and fine-grained control over leading/trailing emission behavior.
toString() → String
A string representation of this object.
inherited

Operators

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

Static Methods

delayedWithScheduler<Value, Time, Interval>(Interval interval, Value computation(), Scheduler<Time, Interval> scheduler) → Effect<Value>
Scheduler-aware variant of Effect.delayed that allows a custom scheduler and interval representation.