@svgrid/enterprise 2.5.2 → 2.6.0

package/dist/expressions/evaluate.d.ts

@@ -0,0 +1,17 @@
+import type { ChangeExpr, EvalContext, ExprRow, PredicateExpr, ScalarExpr } from './expression-types.js';
+type Scalar = number | string | boolean | null;
+/** Names of the built-in scalar functions (for editor validation/autocomplete). */
+export declare const BUILTIN_FUNCTION_NAMES: ReadonlyArray<string>;
+/** Whether `name` (any case) is a known built-in scalar function. */
+export declare function isBuiltinFunction(name: string): boolean;
+/** Evaluate a scalar expression to a single value. */
+export declare function evaluateScalar<TData = ExprRow>(expr: ScalarExpr, ctx: EvalContext<TData>): Scalar;
+/** Evaluate a predicate expression to a boolean for the context's row. */
+export declare function evaluatePredicate<TData = ExprRow>(expr: PredicateExpr, ctx: EvalContext<TData>): boolean;
+/**
+ * Evaluate a change expression - true when the value moved between `ctx.prev`
+ * and `ctx.row` in the way the expression describes. Returns false when there
+ * is no prior snapshot (nothing has changed yet).
+ */
+export declare function evaluateChange<TData = ExprRow>(expr: ChangeExpr, ctx: EvalContext<TData>): boolean;
+export {};

package/dist/expressions/evaluate.js

@@ -0,0 +1,214 @@
+/**
+ * Expression evaluators - pure functions, no DOM. Predicate leaves delegate to
+ * the grid's `applyExcelFilter` so operator semantics match the filter row
+ * exactly; scalar maths and change detection are handled here.
+ */
+import { applyExcelFilter } from '@svgrid/grid/filtering';
+function readValue(ctx, row, columnId) {
+    if (ctx.getValue)
+        return ctx.getValue(row, columnId);
+    return row?.[columnId];
+}
+/** Number coercion that returns NaN for blanks/non-numerics (never 0). */
+function num(v) {
+    if (v == null || v === '')
+        return NaN;
+    if (typeof v === 'boolean')
+        return v ? 1 : 0;
+    return Number(v);
+}
+/** Loose value equality used by `changed` and `=` on non-numeric operands. */
+function looseEqual(a, b) {
+    if (a == null && b == null)
+        return true;
+    const na = num(a);
+    const nb = num(b);
+    if (Number.isFinite(na) && Number.isFinite(nb))
+        return na === nb;
+    return String(a ?? '') === String(b ?? '');
+}
+const BUILTINS = {
+    ABS: (a) => Math.abs(num(a[0])),
+    ROUND: (a) => {
+        const n = num(a[0]);
+        const d = a.length > 1 ? num(a[1]) : 0;
+        const f = 10 ** (Number.isFinite(d) ? d : 0);
+        return Math.round(n * f) / f;
+    },
+    FLOOR: (a) => Math.floor(num(a[0])),
+    CEIL: (a) => Math.ceil(num(a[0])),
+    MIN: (a) => Math.min(...a.map(num)),
+    MAX: (a) => Math.max(...a.map(num)),
+    IF: (a) => (truthy(a[0] ?? null) ? (a[1] ?? null) : (a[2] ?? null)),
+    COALESCE: (a) => a.find((v) => v != null && v !== '') ?? null,
+    CONCAT: (a) => a.map((v) => (v == null ? '' : String(v))).join(''),
+    LOWER: (a) => String(a[0] ?? '').toLowerCase(),
+    UPPER: (a) => String(a[0] ?? '').toUpperCase(),
+    LEN: (a) => String(a[0] ?? '').length,
+};
+/** Names of the built-in scalar functions (for editor validation/autocomplete). */
+export const BUILTIN_FUNCTION_NAMES = Object.keys(BUILTINS);
+/** Whether `name` (any case) is a known built-in scalar function. */
+export function isBuiltinFunction(name) {
+    return name.toUpperCase() in BUILTINS;
+}
+function truthy(v) {
+    if (typeof v === 'boolean')
+        return v;
+    if (v == null || v === '')
+        return false;
+    const n = num(v);
+    return Number.isFinite(n) ? n !== 0 : true;
+}
+/** Evaluate a scalar expression to a single value. */
+export function evaluateScalar(expr, ctx) {
+    switch (expr.kind) {
+        case 'lit':
+            return expr.value;
+        case 'col':
+            return (readValue(ctx, ctx.row, expr.id) ?? null);
+        case 'neg':
+            return -num(evaluateScalar(expr.expr, ctx));
+        case 'bin': {
+            const l = evaluateScalar(expr.left, ctx);
+            const r = evaluateScalar(expr.right, ctx);
+            if (expr.op === '+') {
+                const ln = num(l);
+                const rn = num(r);
+                if (Number.isFinite(ln) && Number.isFinite(rn))
+                    return ln + rn;
+                return String(l ?? '') + String(r ?? '');
+            }
+            const a = num(l);
+            const b = num(r);
+            switch (expr.op) {
+                case '-':
+                    return a - b;
+                case '*':
+                    return a * b;
+                case '/':
+                    return b === 0 ? NaN : a / b;
+                case '%':
+                    return b === 0 ? NaN : a % b;
+                // Rules are authored at runtime, so an operator outside the union can
+                // arrive from parsed JSON. Without this the switch falls out of its
+                // case and into `case 'agg'`, reading agg fields off a binary node.
+                default:
+                    return null;
+            }
+        }
+        case 'agg': {
+            const rows = ctx.rows ?? [ctx.row];
+            if (expr.fn === 'count')
+                return rows.length;
+            const nums = [];
+            for (const row of rows) {
+                const n = num(readValue(ctx, row, expr.column));
+                if (Number.isFinite(n))
+                    nums.push(n);
+            }
+            if (nums.length === 0)
+                return expr.fn === 'sum' ? 0 : null;
+            switch (expr.fn) {
+                case 'sum':
+                    return nums.reduce((s, n) => s + n, 0);
+                case 'avg':
+                    return nums.reduce((s, n) => s + n, 0) / nums.length;
+                case 'min':
+                    return Math.min(...nums);
+                case 'max':
+                    return Math.max(...nums);
+                // Same here: falling through to `case 'func'` would call
+                // `expr.name.toUpperCase()` on an agg node and throw.
+                default:
+                    return null;
+            }
+        }
+        case 'func': {
+            const name = expr.name.toUpperCase();
+            const args = expr.args.map((a) => evaluateScalar(a, ctx));
+            const fn = ctx.functions?.[name] ?? BUILTINS[name];
+            return fn ? fn(args) : null;
+        }
+    }
+}
+function compareScalar(a, op, b) {
+    switch (op) {
+        case '=':
+            return looseEqual(a, b);
+        case '!=':
+            return !looseEqual(a, b);
+    }
+    const na = num(a);
+    const nb = num(b);
+    const numeric = Number.isFinite(na) && Number.isFinite(nb);
+    const x = numeric ? na : String(a ?? '');
+    const y = numeric ? nb : String(b ?? '');
+    switch (op) {
+        case '>':
+            return x > y;
+        case '<':
+            return x < y;
+        case '>=':
+            return x >= y;
+        case '<=':
+            return x <= y;
+    }
+}
+/** Evaluate a predicate expression to a boolean for the context's row. */
+export function evaluatePredicate(expr, ctx) {
+    switch (expr.kind) {
+        case 'const':
+            return expr.value;
+        case 'and':
+            return expr.parts.every((p) => evaluatePredicate(p, ctx));
+        case 'or':
+            return expr.parts.some((p) => evaluatePredicate(p, ctx));
+        case 'not':
+            return !evaluatePredicate(expr.expr, ctx);
+        case 'cmp':
+            return applyExcelFilter(readValue(ctx, ctx.row, expr.column), { id: expr.column, operator: expr.op, value: expr.value, valueTo: expr.valueTo }, { locale: ctx.locale });
+        case 'scalarCmp':
+            return compareScalar(evaluateScalar(expr.left, ctx), expr.op, evaluateScalar(expr.right, ctx));
+    }
+}
+/**
+ * Evaluate a change expression - true when the value moved between `ctx.prev`
+ * and `ctx.row` in the way the expression describes. Returns false when there
+ * is no prior snapshot (nothing has changed yet).
+ */
+export function evaluateChange(expr, ctx) {
+    if (ctx.prev == null)
+        return false;
+    const next = readValue(ctx, ctx.row, expr.column);
+    const prev = readValue(ctx, ctx.prev, expr.column);
+    switch (expr.kind) {
+        case 'changed':
+            return !looseEqual(prev, next);
+        case 'delta': {
+            const p = num(prev);
+            const n = num(next);
+            if (!Number.isFinite(p) || !Number.isFinite(n))
+                return false;
+            const d = expr.abs ? Math.abs(n - p) : n - p;
+            return compareScalar(d, expr.op, expr.value);
+        }
+        case 'percentChange': {
+            const p = num(prev);
+            const n = num(next);
+            if (!Number.isFinite(p) || !Number.isFinite(n) || p === 0)
+                return false;
+            const pc = ((n - p) / Math.abs(p)) * 100;
+            return compareScalar(expr.abs ? Math.abs(pc) : pc, expr.op, expr.value);
+        }
+        case 'crossed': {
+            const p = num(prev);
+            const n = num(next);
+            if (!Number.isFinite(p) || !Number.isFinite(n))
+                return false;
+            return expr.direction === 'above'
+                ? p < expr.threshold && n >= expr.threshold
+                : p > expr.threshold && n <= expr.threshold;
+        }
+    }
+}

package/dist/expressions/expression-columns.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Column metadata for the expression layer - the small, self-contained operator
+ * catalogue the editor draws from, plus name <-> id resolution for the
+ * `[Bracketed Name]` reference syntax.
+ *
+ * The operator set mirrors the grid's own filter row (text / number / date),
+ * so an expression's operators line up with what a user already knows from the
+ * column menu. We keep a local copy rather than importing the grid's internal
+ * `filter-operators` module (which is not part of the public surface).
+ */
+import type { ExcelFilterOperator } from '@svgrid/grid';
+/** Coarse value type used to decide which operators a column offers. */
+export type ExprColumnType = 'text' | 'number' | 'date' | 'datetime' | 'boolean';
+/** A column as the expression layer sees it. */
+export type ExprColumn = {
+    /** Canonical id (the field key stored in the AST). */
+    id: string;
+    /** Human label; also the token used inside `[Bracketed Name]` references. */
+    name?: string;
+    type?: ExprColumnType;
+};
+/** One operator entry: its label and which column types it applies to. */
+export type OperatorMeta = {
+    value: ExcelFilterOperator;
+    label: string;
+    types: ReadonlyArray<ExprColumnType>;
+    /** No value input (acts on emptiness alone). */
+    valueless?: boolean;
+    /** Multi-value set membership (renders a token/chip input). */
+    set?: boolean;
+    /** Needs a second value (`valueTo`). */
+    range?: boolean;
+};
+/** The full operator catalogue, ordered as the editor should present it. */
+export declare const OPERATORS: ReadonlyArray<OperatorMeta>;
+/** Metadata for one operator (falls back to a plain `equals`). */
+export declare function operatorMeta(op: ExcelFilterOperator): OperatorMeta;
+/** Operators valid for a column type (defaults to the text set). */
+export declare function operatorsForType(type: ExprColumnType | undefined): OperatorMeta[];
+/** Whether an operator needs no value input. */
+export declare function isValueless(op: ExcelFilterOperator): boolean;
+/** Whether an operator takes a multi-value token list. */
+export declare function isSetOperator(op: ExcelFilterOperator): boolean;
+/** Whether an operator needs a second (`valueTo`) value. */
+export declare function isRangeOperator(op: ExcelFilterOperator): boolean;
+/** Look a column up by its canonical id. */
+export declare function columnById(columns: ReadonlyArray<ExprColumn>, id: string): ExprColumn | undefined;
+/**
+ * Resolve a reference (as written in an expression) to a column id. A reference
+ * matches a column id first, then a column name (case-insensitive) - so both
+ * `price` and `[Unit Price]` resolve. Returns the raw ref unchanged when
+ * nothing matches, leaving `validateExpression` to flag it.
+ */
+export declare function resolveColumnRef(columns: ReadonlyArray<ExprColumn>, ref: string): string;
+/** The display label for a column id (its name, or the id itself). */
+export declare function columnLabel(columns: ReadonlyArray<ExprColumn>, id: string): string;
+/**
+ * How a column id should be written inside an expression: `[Name]` when the
+ * label has spaces or non-word characters, otherwise the bare id.
+ */
+export declare function columnRefText(columns: ReadonlyArray<ExprColumn>, id: string): string;

package/dist/expressions/expression-columns.js

@@ -0,0 +1,72 @@
+const TEXT = ['text'];
+const NUM = ['number'];
+const DATES = ['date', 'datetime'];
+const ALL = ['text', 'number', 'date', 'datetime', 'boolean'];
+/** The full operator catalogue, ordered as the editor should present it. */
+export const OPERATORS = [
+    { value: 'equals', label: 'Equals', types: ALL },
+    { value: 'notEquals', label: 'Not equals', types: ALL },
+    { value: 'contains', label: 'Contains', types: TEXT },
+    { value: 'notContains', label: 'Not contains', types: TEXT },
+    { value: 'startsWith', label: 'Starts with', types: TEXT },
+    { value: 'endsWith', label: 'Ends with', types: TEXT },
+    { value: 'regex', label: 'Matches regex', types: TEXT },
+    { value: 'greaterThan', label: 'Greater than', types: [...NUM, ...DATES] },
+    { value: 'lessThan', label: 'Less than', types: [...NUM, ...DATES] },
+    { value: 'between', label: 'Between', types: [...NUM, ...DATES], range: true },
+    { value: 'in', label: 'In', types: ['text', 'number'], set: true },
+    { value: 'notIn', label: 'Not in', types: ['text', 'number'], set: true },
+    { value: 'isBlank', label: 'Is blank', types: ALL, valueless: true },
+    { value: 'isNotBlank', label: 'Is not blank', types: ALL, valueless: true },
+];
+const BY_VALUE = new Map(OPERATORS.map((op) => [op.value, op]));
+/** Metadata for one operator (falls back to a plain `equals`). */
+export function operatorMeta(op) {
+    return BY_VALUE.get(op) ?? { value: 'equals', label: 'Equals', types: ALL };
+}
+/** Operators valid for a column type (defaults to the text set). */
+export function operatorsForType(type) {
+    const t = type ?? 'text';
+    return OPERATORS.filter((op) => op.types.includes(t));
+}
+/** Whether an operator needs no value input. */
+export function isValueless(op) {
+    return operatorMeta(op).valueless === true;
+}
+/** Whether an operator takes a multi-value token list. */
+export function isSetOperator(op) {
+    return operatorMeta(op).set === true;
+}
+/** Whether an operator needs a second (`valueTo`) value. */
+export function isRangeOperator(op) {
+    return operatorMeta(op).range === true;
+}
+/** Look a column up by its canonical id. */
+export function columnById(columns, id) {
+    return columns.find((c) => c.id === id);
+}
+/**
+ * Resolve a reference (as written in an expression) to a column id. A reference
+ * matches a column id first, then a column name (case-insensitive) - so both
+ * `price` and `[Unit Price]` resolve. Returns the raw ref unchanged when
+ * nothing matches, leaving `validateExpression` to flag it.
+ */
+export function resolveColumnRef(columns, ref) {
+    if (columnById(columns, ref))
+        return ref;
+    const lc = ref.toLowerCase();
+    const byName = columns.find((c) => (c.name ?? '').toLowerCase() === lc);
+    return byName ? byName.id : ref;
+}
+/** The display label for a column id (its name, or the id itself). */
+export function columnLabel(columns, id) {
+    return columnById(columns, id)?.name ?? id;
+}
+/**
+ * How a column id should be written inside an expression: `[Name]` when the
+ * label has spaces or non-word characters, otherwise the bare id.
+ */
+export function columnRefText(columns, id) {
+    const label = columnLabel(columns, id);
+    return /^[A-Za-z_$][\w$]*$/.test(label) ? label : `[${label}]`;
+}

package/dist/expressions/expression-types.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Expression / query language - the model layer.
+ *
+ * A tiny, dependency-free expression language that end users author through the
+ * grid UI. It is the connective tissue behind the Alert Rules engine (and, in
+ * time, styled columns and calculated columns): one predicate/scalar/change
+ * model, evaluated the same way everywhere.
+ *
+ * The canonical, persisted form is a JSON AST (the types below) - no parser on
+ * the hot path. A light tokenizer/parser (`parse.ts`) is offered only for the
+ * editor's free-text mode; the structured builder writes the AST directly.
+ *
+ * Leaf comparisons delegate to the grid's own `applyExcelFilter`, so a rule's
+ * "greater than" is byte-for-byte the grid filter's "greater than".
+ */
+import type { ExcelFilterOperator } from '@svgrid/grid';
+/** Symbolic comparison operators used by `scalarCmp` (general value compare). */
+export type ComparisonOp = '=' | '!=' | '>' | '<' | '>=' | '<=';
+/** Arithmetic operators for `bin` scalar nodes. */
+export type ArithmeticOp = '+' | '-' | '*' | '/' | '%';
+/** Column aggregate reducers (evaluated over the row set in scope). */
+export type AggFn = 'sum' | 'avg' | 'min' | 'max' | 'count';
+/**
+ * A scalar expression - evaluates to a single value (number / string /
+ * boolean / null) for a given row (and, for aggregates, the row set).
+ */
+export type ScalarExpr = {
+    kind: 'col';
+    id: string;
+} | {
+    kind: 'lit';
+    value: string | number | boolean | null;
+} | {
+    kind: 'neg';
+    expr: ScalarExpr;
+} | {
+    kind: 'bin';
+    op: ArithmeticOp;
+    left: ScalarExpr;
+    right: ScalarExpr;
+} | {
+    kind: 'agg';
+    fn: AggFn;
+    column: string;
+} | {
+    kind: 'func';
+    name: string;
+    args: ScalarExpr[];
+};
+/**
+ * A boolean (predicate) expression - the thing an alert rule / filter needs.
+ *
+ * - `cmp` maps straight onto the grid's `applyExcelFilter` (text/set/range ops).
+ * - `scalarCmp` compares two scalar expressions with a symbolic operator, so
+ *   cross-column maths (`[filled] / [target] >= 0.9`) is expressible.
+ */
+export type PredicateExpr = {
+    kind: 'and';
+    parts: PredicateExpr[];
+} | {
+    kind: 'or';
+    parts: PredicateExpr[];
+} | {
+    kind: 'not';
+    expr: PredicateExpr;
+} | {
+    kind: 'cmp';
+    column: string;
+    op: ExcelFilterOperator;
+    value?: unknown;
+    valueTo?: unknown;
+} | {
+    kind: 'scalarCmp';
+    left: ScalarExpr;
+    op: ComparisonOp;
+    right: ScalarExpr;
+} | {
+    kind: 'const';
+    value: boolean;
+};
+/**
+ * A change (observable) expression - true when a value moves between the
+ * previous and current snapshot of a row. Powers "relative change" alerts.
+ */
+export type ChangeExpr = {
+    kind: 'changed';
+    column: string;
+} | {
+    kind: 'delta';
+    column: string;
+    op: ComparisonOp;
+    value: number;
+    abs?: boolean;
+} | {
+    kind: 'percentChange';
+    column: string;
+    op: ComparisonOp;
+    value: number;
+    abs?: boolean;
+} | {
+    kind: 'crossed';
+    column: string;
+    threshold: number;
+    direction: 'above' | 'below';
+};
+/** The shape the evaluator reads rows as (a plain field bag by default). */
+export type ExprRow = Record<string, unknown>;
+/**
+ * Everything the evaluator needs for one evaluation. `getValue` lets a caller
+ * resolve a column id to a value when it is not a plain `row[id]` field;
+ * `functions` injects extra scalar functions (e.g. delegate to HyperFormula).
+ */
+export type EvalContext<TData = ExprRow> = {
+    row: TData;
+    /** Prior snapshot of the same row - required by `ChangeExpr`. */
+    prev?: TData;
+    /** The row set in scope - required by aggregates. Defaults to `[row]`. */
+    rows?: ReadonlyArray<TData>;
+    /** Resolve a column id to its cell value. Defaults to `row[id]`. */
+    getValue?: (row: TData, columnId: string) => unknown;
+    /** BCP-47 locale(s) threaded into `applyExcelFilter` for text folding. */
+    locale?: string | ReadonlyArray<string>;
+    /** Extra scalar functions by upper-case name, merged over the builtins. */
+    functions?: Record<string, (args: Array<number | string | boolean | null>) => number | string | boolean | null>;
+};

package/dist/expressions/expression-types.js

@@ -0,0 +1 @@
+export {};

package/dist/expressions/parse.d.ts

@@ -0,0 +1,25 @@
+import type { PredicateExpr, ScalarExpr } from './expression-types.js';
+import { type ExprColumn } from './expression-columns.js';
+/** Thrown by `parsePredicate` with a character offset into the source. */
+export declare class ExpressionParseError extends Error {
+    pos: number;
+    constructor(message: string, pos: number);
+}
+/**
+ * Parse a free-text predicate into an AST. Column references (`[Name]` or a
+ * bare id) are resolved against `columns`. Throws `ExpressionParseError`
+ * (carrying a source offset) on a syntax error.
+ */
+export declare function parsePredicate(text: string, columns?: ReadonlyArray<ExprColumn>): PredicateExpr;
+/** Render a scalar expression back to source text. */
+export declare function stringifyScalar(expr: ScalarExpr, columns: ReadonlyArray<ExprColumn>): string;
+/** Render a predicate expression back to readable source text. */
+export declare function stringifyPredicate(expr: PredicateExpr, columns?: ReadonlyArray<ExprColumn>): string;
+/** Every column id referenced anywhere in a predicate (deduped, in order). */
+export declare function collectColumnRefs(expr: PredicateExpr): string[];
+/**
+ * Structurally validate an AST against a column list. Returns a list of
+ * human-readable problems (empty when the expression is sound): unknown column
+ * references and unknown function names.
+ */
+export declare function validateExpression(expr: PredicateExpr, columns: ReadonlyArray<ExprColumn>): string[];