@svgrid/enterprise 2.5.2 → 2.6.0

package/src/expressions/evaluate.test.ts

@@ -1,111 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import { evaluatePredicate, evaluateScalar, evaluateChange } from './evaluate'
-import type { ChangeExpr, EvalContext, PredicateExpr, ScalarExpr } from './expression-types'
-
-type Row = { price: number; qty: number; name: string; region: string }
-
-const row: Row = { price: 120, qty: 3, name: 'Widget', region: 'EU' }
-const ctx = (r: Row, extra: Partial<EvalContext<Row>> = {}): EvalContext<Row> => ({ row: r, ...extra })
-
-describe('evaluateScalar', () => {
-  it('reads columns, literals and arithmetic', () => {
-    const total: ScalarExpr = { kind: 'bin', op: '*', left: { kind: 'col', id: 'price' }, right: { kind: 'col', id: 'qty' } }
-    expect(evaluateScalar(total, ctx(row))).toBe(360)
-    expect(evaluateScalar({ kind: 'lit', value: 5 }, ctx(row))).toBe(5)
-    expect(evaluateScalar({ kind: 'neg', expr: { kind: 'col', id: 'price' } }, ctx(row))).toBe(-120)
-  })
-
-  it('concatenates strings with +', () => {
-    const e: ScalarExpr = { kind: 'bin', op: '+', left: { kind: 'col', id: 'name' }, right: { kind: 'lit', value: '!' } }
-    expect(evaluateScalar(e, ctx(row))).toBe('Widget!')
-  })
-
-  it('guards divide by zero', () => {
-    const e: ScalarExpr = { kind: 'bin', op: '/', left: { kind: 'lit', value: 10 }, right: { kind: 'lit', value: 0 } }
-    expect(Number.isNaN(evaluateScalar(e, ctx(row)) as number)).toBe(true)
-  })
-
-  it('runs built-in functions', () => {
-    expect(evaluateScalar({ kind: 'func', name: 'ABS', args: [{ kind: 'lit', value: -7 }] }, ctx(row))).toBe(7)
-    expect(evaluateScalar({ kind: 'func', name: 'ROUND', args: [{ kind: 'lit', value: 3.14159 }, { kind: 'lit', value: 2 }] }, ctx(row))).toBe(3.14)
-  })
-
-  it('aggregates over the row set in scope', () => {
-    const rows: Row[] = [row, { ...row, price: 80 }, { ...row, price: 40 }]
-    const sum: ScalarExpr = { kind: 'agg', fn: 'sum', column: 'price' }
-    expect(evaluateScalar(sum, ctx(row, { rows }))).toBe(240)
-    expect(evaluateScalar({ kind: 'agg', fn: 'avg', column: 'price' }, ctx(row, { rows }))).toBe(80)
-    expect(evaluateScalar({ kind: 'agg', fn: 'count', column: 'price' }, ctx(row, { rows }))).toBe(3)
-  })
-})
-
-describe('evaluatePredicate', () => {
-  it('cmp delegates to applyExcelFilter semantics', () => {
-    const gt: PredicateExpr = { kind: 'cmp', column: 'price', op: 'greaterThan', value: 100 }
-    expect(evaluatePredicate(gt, ctx(row))).toBe(true)
-    expect(evaluatePredicate(gt, ctx({ ...row, price: 50 }))).toBe(false)
-
-    const contains: PredicateExpr = { kind: 'cmp', column: 'name', op: 'contains', value: 'idge' }
-    expect(evaluatePredicate(contains, ctx(row))).toBe(true)
-
-    const inSet: PredicateExpr = { kind: 'cmp', column: 'region', op: 'in', value: ['EU', 'US'] }
-    expect(evaluatePredicate(inSet, ctx(row))).toBe(true)
-    expect(evaluatePredicate(inSet, ctx({ ...row, region: 'APAC' }))).toBe(false)
-  })
-
-  it('combines with and/or/not', () => {
-    const expr: PredicateExpr = {
-      kind: 'and',
-      parts: [
-        { kind: 'cmp', column: 'price', op: 'greaterThan', value: 100 },
-        { kind: 'not', expr: { kind: 'cmp', column: 'region', op: 'equals', value: 'US' } },
-      ],
-    }
-    expect(evaluatePredicate(expr, ctx(row))).toBe(true)
-    expect(evaluatePredicate(expr, ctx({ ...row, region: 'US' }))).toBe(false)
-  })
-
-  it('scalarCmp compares cross-column maths', () => {
-    // price / qty >= 40  -> 120/3 = 40 -> true
-    const expr: PredicateExpr = {
-      kind: 'scalarCmp',
-      left: { kind: 'bin', op: '/', left: { kind: 'col', id: 'price' }, right: { kind: 'col', id: 'qty' } },
-      op: '>=',
-      right: { kind: 'lit', value: 40 },
-    }
-    expect(evaluatePredicate(expr, ctx(row))).toBe(true)
-    expect(evaluatePredicate(expr, ctx({ ...row, qty: 4 }))).toBe(false)
-  })
-})
-
-describe('evaluateChange', () => {
-  const change = (e: ChangeExpr, prev: Row, next: Row) => evaluateChange(e, ctx(next, { prev }))
-
-  it('detects a bare change', () => {
-    expect(change({ kind: 'changed', column: 'price' }, row, { ...row, price: 121 })).toBe(true)
-    expect(change({ kind: 'changed', column: 'price' }, row, { ...row })).toBe(false)
-  })
-
-  it('returns false with no prior snapshot', () => {
-    expect(evaluateChange({ kind: 'changed', column: 'price' }, ctx(row))).toBe(false)
-  })
-
-  it('tests absolute delta', () => {
-    const e: ChangeExpr = { kind: 'delta', column: 'price', op: '>', value: 10, abs: true }
-    expect(change(e, row, { ...row, price: 140 })).toBe(true)
-    expect(change(e, row, { ...row, price: 100 })).toBe(true) // abs of -20
-    expect(change(e, row, { ...row, price: 125 })).toBe(false)
-  })
-
-  it('tests percent change', () => {
-    const e: ChangeExpr = { kind: 'percentChange', column: 'price', op: '>', value: 5, abs: true }
-    expect(change(e, row, { ...row, price: 132 })).toBe(true) // +10%
-    expect(change(e, row, { ...row, price: 123 })).toBe(false) // +2.5%
-  })
-
-  it('detects threshold crossing', () => {
-    const above: ChangeExpr = { kind: 'crossed', column: 'price', threshold: 130, direction: 'above' }
-    expect(change(above, row, { ...row, price: 135 })).toBe(true)
-    expect(change(above, { ...row, price: 131 }, { ...row, price: 140 })).toBe(false) // already above
-  })
-})

package/src/expressions/evaluate.ts

@@ -1,237 +0,0 @@
-/**
- * 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'
-import type {
-  ChangeExpr,
-  ComparisonOp,
-  EvalContext,
-  ExprRow,
-  PredicateExpr,
-  ScalarExpr,
-} from './expression-types.js'
-
-type Scalar = number | string | boolean | null
-
-function readValue<TData>(ctx: EvalContext<TData>, row: TData, columnId: string): unknown {
-  if (ctx.getValue) return ctx.getValue(row, columnId)
-  return (row as Record<string, unknown>)?.[columnId]
-}
-
-/** Number coercion that returns NaN for blanks/non-numerics (never 0). */
-function num(v: unknown): number {
-  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: unknown, b: unknown): boolean {
-  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: Record<string, (args: Scalar[]) => Scalar> = {
-  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: ReadonlyArray<string> = Object.keys(BUILTINS)
-
-/** Whether `name` (any case) is a known built-in scalar function. */
-export function isBuiltinFunction(name: string): boolean {
-  return name.toUpperCase() in BUILTINS
-}
-
-function truthy(v: Scalar): boolean {
-  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<TData = ExprRow>(
-  expr: ScalarExpr,
-  ctx: EvalContext<TData>,
-): Scalar {
-  switch (expr.kind) {
-    case 'lit':
-      return expr.value
-    case 'col':
-      return (readValue(ctx, ctx.row, expr.id) ?? null) as Scalar
-    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: number[] = []
-      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: Scalar, op: ComparisonOp, b: Scalar): boolean {
-  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: number | string = numeric ? na : String(a ?? '')
-  const y: number | string = 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<TData = ExprRow>(
-  expr: PredicateExpr,
-  ctx: EvalContext<TData>,
-): boolean {
-  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 },
-      ) as boolean
-    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<TData = ExprRow>(
-  expr: ChangeExpr,
-  ctx: EvalContext<TData>,
-): boolean {
-  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/src/expressions/expression-columns.ts

@@ -1,133 +0,0 @@
-/**
- * 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
-}
-
-const TEXT: ExprColumnType[] = ['text']
-const NUM: ExprColumnType[] = ['number']
-const DATES: ExprColumnType[] = ['date', 'datetime']
-const ALL: ExprColumnType[] = ['text', 'number', 'date', 'datetime', 'boolean']
-
-/** The full operator catalogue, ordered as the editor should present it. */
-export const OPERATORS: ReadonlyArray<OperatorMeta> = [
-  { 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<ExcelFilterOperator, OperatorMeta>(
-  OPERATORS.map((op) => [op.value, op]),
-)
-
-/** Metadata for one operator (falls back to a plain `equals`). */
-export function operatorMeta(op: ExcelFilterOperator): OperatorMeta {
-  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: ExprColumnType | undefined): OperatorMeta[] {
-  const t = type ?? 'text'
-  return OPERATORS.filter((op) => op.types.includes(t))
-}
-
-/** Whether an operator needs no value input. */
-export function isValueless(op: ExcelFilterOperator): boolean {
-  return operatorMeta(op).valueless === true
-}
-
-/** Whether an operator takes a multi-value token list. */
-export function isSetOperator(op: ExcelFilterOperator): boolean {
-  return operatorMeta(op).set === true
-}
-
-/** Whether an operator needs a second (`valueTo`) value. */
-export function isRangeOperator(op: ExcelFilterOperator): boolean {
-  return operatorMeta(op).range === true
-}
-
-/** Look a column up by its canonical id. */
-export function columnById(
-  columns: ReadonlyArray<ExprColumn>,
-  id: string,
-): ExprColumn | undefined {
-  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: ReadonlyArray<ExprColumn>,
-  ref: string,
-): string {
-  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: ReadonlyArray<ExprColumn>,
-  id: string,
-): string {
-  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: ReadonlyArray<ExprColumn>,
-  id: string,
-): string {
-  const label = columnLabel(columns, id)
-  return /^[A-Za-z_$][\w$]*$/.test(label) ? label : `[${label}]`
-}

package/src/expressions/expression-types.ts

@@ -1,84 +0,0 @@
-/**
- * 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/src/expressions/parse.test.ts

@@ -1,106 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import {
-  ExpressionParseError,
-  collectColumnRefs,
-  parsePredicate,
-  stringifyPredicate,
-  validateExpression,
-} from './parse'
-import { evaluatePredicate } from './evaluate'
-import type { ExprColumn } from './expression-columns'
-import type { PredicateExpr } from './expression-types'
-
-const columns: ExprColumn[] = [
-  { id: 'price', name: 'Unit Price', type: 'number' },
-  { id: 'qty', name: 'Qty', type: 'number' },
-  { id: 'name', name: 'Name', type: 'text' },
-  { id: 'region', name: 'Region', type: 'text' },
-]
-
-describe('parsePredicate', () => {
-  it('parses a col-vs-literal comparison into a cmp node (grid-filter semantics)', () => {
-    const e = parsePredicate('price > 100', columns)
-    expect(e).toEqual({ kind: 'cmp', column: 'price', op: 'greaterThan', value: 100 })
-  })
-
-  it('resolves [Bracketed Name] references to ids', () => {
-    const e = parsePredicate('[Unit Price] >= 50', columns) as Extract<PredicateExpr, { kind: 'scalarCmp' }>
-    // >= has no cmp equivalent, so it becomes a scalarCmp over the resolved column id
-    expect(e.kind).toBe('scalarCmp')
-    expect(e.left).toEqual({ kind: 'col', id: 'price' })
-  })
-
-  it('parses keyword text/set/range operators', () => {
-    expect(parsePredicate('name CONTAINS "wid"', columns)).toEqual({ kind: 'cmp', column: 'name', op: 'contains', value: 'wid' })
-    expect(parsePredicate('region IN ("EU", "US")', columns)).toEqual({ kind: 'cmp', column: 'region', op: 'in', value: ['EU', 'US'] })
-    expect(parsePredicate('price BETWEEN 10 AND 20', columns)).toEqual({ kind: 'cmp', column: 'price', op: 'between', value: 10, valueTo: 20 })
-    expect(parsePredicate('name ISBLANK', columns)).toEqual({ kind: 'cmp', column: 'name', op: 'isBlank' })
-  })
-
-  it('honours AND/OR/NOT precedence and grouping', () => {
-    const e = parsePredicate('price > 100 AND (region = "EU" OR region = "US")', columns) as Extract<PredicateExpr, { kind: 'and' }>
-    expect(e.kind).toBe('and')
-    expect(e.parts[1]!.kind).toBe('or')
-  })
-
-  it('parses cross-column scalar maths', () => {
-    const e = parsePredicate('price / qty >= 40', columns) as Extract<PredicateExpr, { kind: 'scalarCmp' }>
-    expect(e.kind).toBe('scalarCmp')
-    expect(e.op).toBe('>=')
-    expect(e.left).toEqual({ kind: 'bin', op: '/', left: { kind: 'col', id: 'price' }, right: { kind: 'col', id: 'qty' } })
-  })
-
-  it('throws a positioned error on a syntax problem', () => {
-    expect(() => parsePredicate('price >', columns)).toThrow(ExpressionParseError)
-    try {
-      parsePredicate('price @ 5', columns)
-    } catch (err) {
-      expect(err).toBeInstanceOf(ExpressionParseError)
-      expect((err as ExpressionParseError).pos).toBeGreaterThan(0)
-    }
-  })
-
-  it('parsed expressions evaluate correctly end to end', () => {
-    const e = parsePredicate('price > 100 AND region = "EU"', columns)
-    expect(evaluatePredicate(e, { row: { price: 120, region: 'EU' } })).toBe(true)
-    expect(evaluatePredicate(e, { row: { price: 120, region: 'US' } })).toBe(false)
-  })
-})
-
-describe('stringifyPredicate', () => {
-  it('round-trips through parse for the common forms', () => {
-    for (const src of [
-      'price > 100',
-      'name CONTAINS "wid"',
-      'region IN ("EU", "US")',
-      'price BETWEEN 10 AND 20',
-      'name ISBLANK',
-    ]) {
-      const ast = parsePredicate(src, columns)
-      const back = stringifyPredicate(ast, columns)
-      expect(stringifyPredicate(parsePredicate(back, columns), columns)).toBe(back)
-    }
-  })
-
-  it('writes [bracketed] names when a label has spaces', () => {
-    const ast = parsePredicate('price > 100', columns)
-    expect(stringifyPredicate(ast, columns)).toBe('[Unit Price] > 100')
-  })
-})
-
-describe('validateExpression + collectColumnRefs', () => {
-  it('collects every referenced column id', () => {
-    const ast = parsePredicate('price / qty >= 40 AND region = "EU"', columns)
-    expect(collectColumnRefs(ast).sort()).toEqual(['price', 'qty', 'region'])
-  })
-
-  it('flags unknown columns and functions', () => {
-    const ast = parsePredicate('bogus > 5', columns)
-    expect(validateExpression(ast, columns)).toContain('Unknown column "bogus"')
-  })
-
-  it('passes a sound expression', () => {
-    const ast = parsePredicate('price > 100', columns)
-    expect(validateExpression(ast, columns)).toEqual([])
-  })
-})