@formscript/evaluator

Expression evaluation — the FormScript Language Specification 1.0.0 , §6.

Evaluation is total: every expression returns a value. There is no exception, no undefined, and no partial result. An operation that cannot succeed returns the error value or null, as Spec-6.1 and Spec-6.2 prescribe.

The three-valued logic

FormScript has three truth values, not two, and two kinds of absence:

and, or and ! are Kleene strong three-valued logic extended so that the two absences are the "undetermined" value and the error value is absorbed by the dominant value (Spec-6.12). The order of the rules matters: in and a false dominates an error, and in or a true does; otherwise the error dominates both absences.

import { Evaluator, toDisplayString } from '@formscript/evaluator';

const evaluator = new Evaluator({
  resolve: (path) => (path[0] === 'age' ? 36 : null),
  resolveNamespace: () => null,
  now: () => new Date(0),
  subject: () => null,
  locale: () => 'en',
});

toDisplayString(evaluator.evaluate(expression));  // the canonical text

Specification sections implemented

Public API

class Evaluator {
  constructor(environment: EvaluationEnvironment);
  readonly diagnostics: Diagnostic[];
  evaluate(expression: Expression): unknown;
}

interface EvaluationEnvironment {
  resolve(path: readonly string[]): unknown;
  resolveNamespace(namespace: string, path: readonly string[]): unknown;
  now(): Date;
  subject(): unknown;
  locale(): string;
  text?(key: string, args: readonly unknown[]): string | null;
  filledFields?(): readonly string[];
  isActive?(path: readonly string[]): boolean;
  shadow?(path: readonly string[]): unknown;
  isOverridden?(path: readonly string[]): boolean;
  formId?(): string;
}

Also exported: ERROR, isError, truthOf, valueOfTruth, strictEquals, compareValues, toDisplayString, typeNameOf, and, or, negate, dominantAbsence, builtinsFor and BUILTIN_NAMES.

Judgement calls

1. The environment is the only way in. The evaluator holds no state of its own beyond the diagnostics it produced, so the same expression evaluated against the same environment always yields the same value — which is what Spec-9.1 requires of the engine that calls it.
2. Absence is a value, not a special case. UNKNOWN and INAPPLICABLE are distinct sentinels, so x is unknown and x is inapplicable are told apart. A field that was never answered is unknown; a field whose entity is not active is inapplicable (Spec-5.5, Spec-8.2). When a strict operation has two absent operands, inapplicable dominates (Spec-6.8).
3. The error value is not a number. It is its own sentinel, so it cannot be compared with == and cannot be added to anything. An error that reaches a non-field node aborts the transaction with E-EVAL-07 (Spec-6.3), which is the engine's job, not this package's.
4. A builtin never throws. A builtin that would fail — substring with a negative index, 1 / 0 — returns the error value or null, as §6.4 documents for that builtin (Spec-6.27).
5. Numbers are exact decimals. Arithmetic goes through @formscript/decimal, so 0.1 + 0.2 is exactly 0.3 and the canonical decimal text of Spec-5.32 is what toString yields (Spec-5.33).
6. The regular-expression dialect is enforced at compile time. The evaluator compiles a pattern with the platform engine and normalises the subject to NFC (Spec-6.40); the restriction to RE2 — no backreferences, no lookaround — is checked by the analyzer's checkPattern, which reports E-BOUND-04 for a pattern outside the dialect. The evaluator therefore trusts a pattern that has passed the analyzer.

Public API

31 exported symbols.