scoped method

Effect scoped(
  1. void action(
    1. EffectScope scope
    ), {
  2. bool guard()?,
  3. int? take,
  4. void onUncaughtError(
    1. Object error,
    2. StackTrace stackTrace
    )?,
})

Defines an explicit scoped Effect attached to the scoped targets providing an EffectScope.

  • Skips initial evaluation (0 runs upon construction/mount).

  • Executes action with an EffectScope in an untracked environment when any of the scoped targets mutate.

  • Prior to subsequent evaluations or deactivation, the previous turn's EffectScope is marked cancelled and its registered cleanup callbacks are executed in LIFO order.

  • If guard is provided and returns false, execution is skipped and take tickets are preserved.

  • If take is provided, executes at most take times and then automatically deactivates (Early Teardown).

  • If onUncaughtError is provided, it is invoked when an uncaught exception is thrown in action or guard.

  • action: The untracked callback receiving an EffectScope to invoke upon mutation.

  • guard: Optional boolean predicate gating execution and preserving tickets when false.

  • take: Optional limit on execution count before automatic deactivation.

  • onUncaughtError: Optional error recovery handler.

Requires:

  • If take is provided, it must be greater than or equal to 0.

Ensures:

  • Returns a scoped Effect with deterministic lifecycle cleanup capabilities.

Examples

final effect = (room.bloom, server.bloom).effect.scoped((scope) {
  final client = connect(untracked(room.bloom), untracked(server.bloom));
  scope.onCleanup(client.close);
});

Implementation

@pragma('vm:prefer-inline')
Effect scoped(
  void Function(EffectScope scope) action, {
  bool Function()? guard,
  int? take,
  void Function(Object error, StackTrace stackTrace)? onUncaughtError,
}) =>
    Effect.scoped(
      _targets,
      action,
      guard: guard,
      take: take,
      onUncaughtError: onUncaughtError,
    );