call method

Effect call(void action(), { bool guard()?, int? take, void onUncaughtError(Object error, StackTrace stackTrace)?, })

Defines an explicit manifest Effect attached to the scoped targets.

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

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

• 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 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 manifest Effect bound to the scoped targets.

Warning (Anti-Pattern Prevention):

• Do NOT mutate scoped targets synchronously inside action without an exit condition.

BAD:

// [Anti-Pattern] Mutating target inside its own effect action
[counter.bloom].effect(() {
  counter.set(untracked(counter.bloom) + 1); // Triggers infinite invalidation loop!
});

GOOD:

// [Recommended] Perform external side-effects
[counter.bloom].effect(() {
  analyticsService.log(untracked(counter.bloom));
});

Examples

final effect = [user.bloom, role.bloom].effect(() {
  refreshPermissions(untracked(user.bloom), untracked(role.bloom));
});

Implementation

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