call method
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
- Predicate Evaluation: Executes the primary validation logic. If defined as a composite, it evaluates the local rule first.
- Short-Circuit Logic: If this rule is part of a pipeline (via
+), execution stops immediately if any segment returnsfalse. - Hierarchical Delegation: If local checks pass, the evaluation is propagated to the parent ancestor in the inheritance chain, ensuring global invariants are maintained.
- 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;
}