std/formula

Import from @norbital-ai/std/formula

std/formula (§3.7, D21, M1): user-edited rules as CEL text, compiled against a context declared with field-kind literals (object roots included) and evaluated over plain values. The numeric mode belongs to the context: 'decimal' (default) evaluates money and decimals exactly as Decimal, 'float' in doubles (hr's law, D21). Registered functions keep today's registerFunction signatures, so hr's law seed (.age_on(, .birthday() runs unchanged; object roots are map<string, dyn> for them, and their member paths are checked here instead.

FormulaContext type

type FormulaContext<R extends Roots = Roots, M extends Mode = Mode, D = undefined> = Site<R, M> & {
    /** M1: the typed builder from the caller's rows to this context's values, when one was declared. */
    readonly derive: D extends (rows: infer X) => unknown ? (rows: X) => ValuesOf<R> : undefined;
};

A formula context from context(): the typed roots a formula reads, the numeric mode, its registered functions and an optional typed derive from rows to root values.

Members

Name	Type	Description
roots	R
numbers	M
derive	D extends (rows: infer X) => unknown ? (rows: X) => ValuesOf<R> : undefined	M1: the typed builder from the caller's rows to this context's values, when one was declared.

Source: packages/std/src/formula.ts:79

FormulaResult type

type FormulaResult = 'bool' | 'decimal' | 'money' | 'int' | 'date' | 'text' | 'json';

The type a compiled formula must produce.

Source: packages/std/src/formula.ts:62

compile function

function compile<R extends Roots, M extends Mode, T extends FormulaResult>(ctx: Site<R, M>, text: string, result: T): Compiled<R, M, T> | { readonly error: string; }

Compiles text for a result kind; { error } names the syntax fault, the unknown path or the wrong type. Cached per (context, text, result).

Parameters

Name	Type	Description
ctx	Site<R, M>	roots: R numbers: M
text	string
result	T

Source: packages/std/src/formula.ts:244

context function

function context<const R extends Roots, M extends Mode = "decimal", D extends ((rows: never) => ValuesOf<R>) | undefined = undefined>(roots: R, opts?: { readonly numbers?: M; readonly functions?: { readonly [name: string]: Fn; }; readonly derive?: D; }): FormulaContext<R, M, D>

A formula context: its roots (field-kind literals), numeric mode, registered CEL functions ({ signature, fn }, today's registerFunction) and, for derived roots (M1), a typed derive(rows) builder.

Parameters

Name	Type	Description
roots	R
opts?	{ readonly numbers?: M; readonly functions?: { readonly [name: string]: Fn; }; readonly derive?: D; }

Source: packages/std/src/formula.ts:170

evaluate function

function evaluate<R extends Roots, M extends Mode, T extends FormulaResult>(compiled: Compiled<R, M, T>, values: ValuesOf<R>): Out<T, M>

Evaluates a compiled formula; a runtime fault (a missing value, a wrong result) throws.

Parameters

Name	Type	Description
compiled	Compiled<R, M, T>	text: string result: T context: Site<R, M> program: ParseResult
values	ValuesOf<R>

Source: packages/std/src/formula.ts:325

formula function

function formula<R extends Roots, M extends Mode>(ctx: Site<R, M>, result: FormulaResult): (text: string) => string | undefined

A value validator for stored formula text (a custom field's validate, a transform refusal): the error or undefined.

Parameters

Name	Type	Description
ctx	Site<R, M>	roots: R numbers: M
result	FormulaResult

Source: packages/std/src/formula.ts:365