IExpressionEvaluator Interface — Expression Engines

The Full Interface

// BizFirst.Ai.ProcessEngine.JS.Services.ExpressionEngine.IExpressionEvaluator

public interface IExpressionEvaluator
{
    /// Evaluates a JavaScript expression with security isolation.
    Task<object?> EvaluateAsync(
        string expression,
        Dictionary<string, object> executionVariables,
        ProcessElementDefinition? elementDefinition = null);

    /// Evaluates an expression as a boolean (for condition nodes).
    Task<bool> EvaluateBooleanAsync(
        string expression,
        Dictionary<string, object> executionVariables,
        ProcessElementDefinition? elementDefinition = null);

    /// Validates expression syntax without executing it.
    Task<ExpressionValidationResult> ValidateExpressionAsync(string expression);
}

Method Breakdown

Method	Used By	Notes
`EvaluateAsync`	`ConfigExpressionResolver` for each config field	Returns `object?` — the caller serialises the result back to the config value type
`EvaluateBooleanAsync`	If-Condition and Switch executors	Equivalent to `EvaluateAsync` followed by truthiness cast
`ValidateExpressionAsync`	Designer validation (pre-save lint check)	Does not execute the expression; only parses syntax

ExpressionValidationResult

public class ExpressionValidationResult
{
    public bool    IsValid      { get; set; }
    public string? ErrorMessage { get; set; }

    public static ExpressionValidationResult Valid() =>
        new() { IsValid = true };

    public static ExpressionValidationResult Invalid(string errorMessage) =>
        new() { IsValid = false, ErrorMessage = errorMessage };
}

executionVariables Parameter

The executionVariables dictionary is built by the ConfigExpressionResolver from the EvaluationContext before calling the evaluator. It maps well-known names to their current values:

// Variables injected into the evaluator
{
    "$output"  : { "node-1": { "statusCode": 200, "body": "..." }, ... },
    "$input"   : { "email": "alice@example.com", ... },
    "$var"     : { "retryCount": 3, ... },
    "$context" : { "tenantId": "42", "executionId": "...", "userId": "..." },
    "$global"  : { "triggerPayload": { ... } }
}

elementDefinition Parameter

The optional elementDefinition is passed to INodeCertificationService.GetIsolationModeAsync() to determine whether the node is certified. Certified nodes run in low-isolation mode (longer timeout, relaxed constraints); uncertified nodes run in high-isolation mode. Pass null in tests to default to high-isolation mode.

The Evaluator Is Not Called Directly by Executors Node executors do not call IExpressionEvaluator — they receive already-resolved config values. The evaluator is called internally by IConfigExpressionResolver during the EntryValidate pipeline stage, before your executor runs.

← Context Variable Reference Next: Building a Custom Engine →