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 this node providing an EffectScope.

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

  • Executes action with an EffectScope in an untracked environment when this node mutates.

  • 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 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.

  • 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 unary scoped Effect bound to this node.

Examples

final room = blooming('lobby');
final effect = room.bloom.effect.scoped((scope) {
  final timer = Timer.periodic(const Duration(seconds: 1), (_) => ping());
  scope.onCleanup(timer.cancel);
});

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.unary(
      _target,
      action,
      guard: guard,
      take: take,
      onUncaughtError: onUncaughtError,
    );