via method

Effect via(
  1. FutureOr<void> action(
    1. EffectVia via,
    2. EffectScope scope
    ), {
  2. bool guard(
    1. EffectVia via
    )?,
  3. void onUncaughtError(
    1. Object error,
    2. StackTrace stackTrace
    )?,
})

Creates an explicit dynamic discovery Effect using EffectVia and EffectScope.

Schedules an initial evaluation on the microtask scheduler upon activation to discover dynamic dependencies via via(node), providing an EffectScope to register turn teardowns and observe lifecycle state.

Prior to subsequent evaluations or deactivation, the previous turn's EffectScope is disposed (marked no longer current) and its registered cleanups are executed in LIFO order.

  • Supports both synchronous and asynchronous (async) action closures: when action returns a Future, dependencies accessed via via(node) after await points are tracked for the latest active turn while superseded turns are isolated automatically.

  • If guard is provided, it is evaluated with EffectVia before each run; returning false skips execution.

  • If onUncaughtError is provided, it is invoked when an uncaught synchronous or asynchronous exception occurs.

  • action: The dynamic tracking callback receiving EffectVia and EffectScope.

  • guard: Optional boolean predicate evaluated with EffectVia prior to each execution.

  • onUncaughtError: Optional error recovery handler.

Ensures:

Examples

final e = Effect.scoped.via((via, scope) {
  final endpoint = via(apiEndpoint.bloom);
  final client = HttpClient(endpoint);
  scope.onCleanup(client.close);
});

Implementation

@pragma('vm:prefer-inline')
Effect via(
  FutureOr<void> Function(EffectVia via, EffectScope scope) action, {
  bool Function(EffectVia via)? guard,
  void Function(Object error, StackTrace stackTrace)? onUncaughtError,
}) =>
    _HandledViaEffect(
      action,
      guard: guard,
      onUncaughtError: onUncaughtError,
    );