GEL Evaluator Technical Manual

This document describes the GEL Evaluator — a core component of the General Expression Language (GEL) runtime. It assumes familiarity with the GEL manual describing the lexer, parser, and abstract syntax tree (AST).

Table of Contents

1. 1. Introduction
2. 2. GEL Evaluator Overview
3. 3. Usage & API
4. 4. Implementation Details
5. 5. GEL Engine
6. 6. Examples
7. 7. Error Handling
8. 8. References

1. Introduction

The GelEvaluator class processes a parsed GEL AST and executes it against a data record. It supports both strict and non-strict evaluation modes. In strict mode, missing fields cause an exception; in non-strict mode, they are treated as "missing value" and evaluate to false or undefined, depending on context.

This evaluator supports asynchronous function calls, enabling integration with external APIs or asynchronous computations.

2. GEL Evaluator Overview

Once an expression string is parsed (into an Expression AST), the GelEvaluator traverses that AST to produce a final value. The evaluator:

• Resolves field_reference nodes against a data record.
• Performs logical (and, or, not) and comparison (eq, lt, etc.) operations.
• Invokes configured functions from a registry (supports asynchronous calls).
• Handles [*] subscripting, producing array outputs when appropriate.
• Allows "loose" evaluation via a missing-value sentinel if strictEval = false.

3. Usage & API

Below is a summarized API reference for GelEvaluator. For more detail, see Section 4.

4. Implementation Details

The GelEvaluator includes various methods to navigate and compute values from AST nodes. Each node type from the GEL manual is handled in evaluateExpressionAsValue via a switch statement:

private async evaluateExpressionAsValue(
  expr: Expression,
  data: Record<string, unknown>,
  strictEval: boolean
): Promise<unknown> {
  switch (expr.type) {
    case "literal":
      return expr.value;

    case "field_reference":
      return this.getFieldValue(expr, data, strictEval);

    case "inset":
      // Evaluate each item in the set
      return Promise.all(expr.values.map(...));

    case "subscript":
      return this.evaluateSubscript(expr, data, strictEval);

    case "function_call":
      return this.evaluateFunctionCall(expr, data, strictEval);

    case "comparison":
      return this.evaluateComparison(expr, data, strictEval);

    case "logical":
      return this.evaluateLogical(expr, data, strictEval);

    default:
      throw new Error("Unknown expression type");
  }
}

4.1 Handling Strict vs. Non-Strict Modes

Many evaluation paths check strictEval to decide how to respond to missing fields or invalid indexes:

• Strict mode: Throw an error (e.g. UndefinedFieldError) so the caller is aware of incomplete data.
• Non-strict mode: Return a missing-value sentinel (Symbol("MISSING_VALUE")), which eventually yields false (for rules) or undefined (for transforms).

4.2 Wildcard Subscripting (arr[*])

[*] patterns produce an array of results when indexing. If a function argument has [*], the evaluator maps that function call over each element of the array. The final returned value is an array of results.

4.3 Function Registry and Async Calls

The config object defines available functions. evaluateFunctionCall looks up the function by name, then calls it asynchronously:

const fn = this.config.functions[node.functionName];
const argVals = await Promise.all(node.args.map(...));
const result = await fn.apply(null, argVals);

5. GEL Engine

The GelEngine is a higher-level utility class that combines parsing (from the other manual) and evaluation in one object:

• parse(): converts a GEL string to an AST.
• evaluate(): evaluates an AST as a rule (boolean).
• transform(): evaluates an AST as a transform (any type).
• renderTemplate(): processes {{ expr }} placeholders in a text template, substituting evaluated results.

Note: The GelParser is documented in the main GEL Technical Manual. In GelEngine, we see how the parser and evaluator integrate:

public parse(input: string): Expression {
  const parser = new GelParser(input, this.config);
  return parser.parse();
}

public evaluate(
  rule: Expression,
  data: Record<string, unknown>,
  strictMode: boolean
): Promise<boolean> {
  return this.evaluator.evaluateRule(rule, data, strictMode);
}

6. Examples

6.1 Evaluating a Boolean Rule

6.2 Handling Missing Fields

6.3 Wildcard Subscript

7. Error Handling

Errors thrown by the evaluator include:

• UndefinedFieldError: Thrown in strict mode if a required field is missing.
• Error: Generic runtime issues, e.g. invalid array indexing or unknown function calls.

In non-strict mode, the evaluator uses an internal missing value sentinel to avoid throwing. This sentinel eventually resolves to:

• false when evaluating boolean rules.
• undefined when evaluating transforms.

8. References