call method

FutureOr<bool> call(
  1. dynamic object, {
  2. C? host,
  3. dynamic arguments,
})

Executes the Validation Predicate and orchestrates the Chain of Responsibility for this rule.

This method serves as the operational entry point for Policy Enforcement and Integrity Gate resolution. It evaluates a stimulus (object)—typically a payload or a state transition—against the governing invariants.

When to use

  • Framework Orchestration: Automatically invoked by the Nucleus or TestCell whenever a state update is proposed.
  • Unit Testing: Manually trigger validation logic to verify business rules in isolation without mounting a full reactive graph.
  • Custom Validation: Invoke within custom Modifiable implementations to gate internal state transitions.

How it works

  1. Predicate Evaluation: Executes the primary validation logic. If defined as a composite, it evaluates the local rule first.
  2. Short-Circuit Logic: If this rule is part of a pipeline (via +), execution stops immediately if any segment returns false.
  3. Hierarchical Delegation: If local checks pass, the evaluation is propagated to the parent ancestor in the inheritance chain, ensuring global invariants are maintained.
  4. Hybrid Convergence: Supports FutureOr. Synchronous checks complete at native speed, while asynchronous checks (e.g., DB lookups) safely suspend the reactive wave until completion.

Example

final ageRule = TestRule<int>((val, {host, arguments, user}) => val >= 18);

// Synchronous manual check
final canEnter = await ageRule.call(21); // returns true

// Asynchronous check (e.g., verifying against a database)
final userRule = TestRule<String>((name, {host, arguments, user}) async {
  return await db.userExists(name);
});
final exists = await userRule.call('Simon');

Parameters:

  • object: The Stimulus. The data, payload, or proposed state change being validated.
  • host: The Operational Authority. The Cell or container that owns the state being modified.
  • arguments: Forensic Metadata. Optional context or payload details derived from the original Pulse.

Returns:

A FutureOr<bool> where true indicates the operation is Accepted by policy, and false indicates it is Rejected.

See Also:

  • TestRule.chain: For building multi-stage validation pipelines.
  • TestCell: The primary engine for applying these rules to cells.

Implementation

FutureOr<bool> call(dynamic object, {C? host, dynamic arguments}) {
  FutureOr<bool> result = true;

  final rule = _rule;

  // Handle Primary Predicate
  if (rule != null) {
    try {
      result = rule(object, host: host, arguments: arguments, user: _user);
    } on Exception {
      rethrow;
    }
  } else {
    // Handle Composite Chain
    final rules = _rules;
    if (rules.isNotEmpty) {
      result = _evaluateChain(rules, 0, object, host, arguments);
    }
  }

  if (result is Future<bool>) {
    final parent = _parent;
    if (parent != null) {
      return result.then((passed) {
        if (!passed) return false;
        return parent.call(object, host: host, arguments: arguments);
      });
    }
    // Re-throw the original error so `TestCell.call`'s exception handler
    // treats async failures uniformly with the sync path. Returning the
    // caught error here (`catchError((e) => e)`) resolves the future with
    // an Object instead of a bool, producing a TypeError in the caller.
    return result.then((value) => value,
        onError: (Object e, StackTrace st) =>
            Error.throwWithStackTrace(e, st));
  } else if (!result) {
    return false;
  }

  // Handle Hierarchical Delegation
  return _parent?.call(object, host: host, arguments: arguments) ?? true;
}