@xeplr/expression-handler 1.0.5 → 2.0.0

package/README.md

@@ -1,103 +1,338 @@
 # @xeplr/expression-handler
 
-Level-1 structured expression evaluator. JSON expression in, boolean out — apply
-field **functions** (`upper`, `month`, …) and **operators** (`eq`, `contains`,
-`gt`, `between`, `isNull`, …) to a data row. No parser, no nesting, no `AND`/`OR`
-combinators (by design — level 1 only). Zero dependencies.
+> **Status: 2.0 built, not released.** The code in this repo is 2.0; npm still
+> has 1.x, which does less — see [What changes from 1.x](#what-changes-from-1x).
+> BI and Workflow move over next ([Moving callers over](#moving-callers-over)).
 
-## Usage
+**The one formula engine for xeplr.** Every formula that is calculated in
+JavaScript — BI report formulas, BI text templates, Workflow conditions — is
+read, checked and run by this package, with one list of functions. Functions
+that a **database** runs (query-engine ranking, SQL formulas, warehouse cube
+aggregates) are not formulas in this sense and stay where they are.
+
+Zero dependencies. No `eval`, no `new Function`. Runs the same in Node and the
+browser.
 
 ```js
 const xf = require('@xeplr/expression-handler');
 
-// upper(name) = upper(nickName)
-xf.evaluate(
-  { left: { fn: 'upper', field: 'name' }, op: 'eq', right: { fn: 'upper', field: 'nickName' } },
-  { name: 'ada', nickName: 'ADA' }
-); // → true
-
-// month(createdAt) = 'January'
-xf.evaluate(
-  { left: { fn: 'month', field: 'createdAt' }, op: 'eq', right: { value: 'January' } },
-  { createdAt: '2026-01-15T00:00:00Z' }
-); // → true
-
-// Compile once, filter many (drops into a streaming .filter too)
-const isAdult = xf.toPredicate({ left: { field: 'age' }, op: 'gte', right: { value: 18 } });
-rows.filter(isAdult);
+const f = xf.compile('if(country = "India" and (score >= 750 or referred), "India payroll", "Offer")');
+f({ country: 'India', score: 600, referred: true });   // → 'India payroll'
 ```
 
-## Expression shape
+## API
 
-```
-{ left: <operand>, op: <string>, right?: <operand> }
-```
+| Call | Gives |
+|---|---|
+| `xf.compile(textOrTree, context?)` | `(row) → value`. Cached by text and context. |
+| `xf.parse(text)` | the JSON tree (what gets stored); throws with the position |
+| `xf.toText(tree)` | the tree back as text, for an editor showing a stored formula |
+| `xf.check(text, context?)` | `{ ok, tree, error, position }` — never throws; for editors |
+| `xf.analyze(textOrTree)` | `{ fields, fieldsOutsideTotals, thisrow, functions, aggregates, levels }` |
+| `xf.functions()` | the function list, for pickers and help |
+| `xf.implementations(context?)` | `{ name: fn }` ready to call, for a caller that wants the functions without the language |
+| `xf.registerFunction(entry)` | adds one to the list |
+| `xf.evaluate(condition, row)` | 1.x: a condition → `true` / `false` |
+| `xf.toPredicate` · `xf.validate` · `xf.formula.*` · `xf.registerOperator` | 1.x, kept |
 
-**Operand** — one of:
+## Who uses it
 
-| Form | Meaning |
+| Caller | What for |
 |---|---|
-| `{ field: 'name' }` | `row.name` |
-| `{ field: 'a.b' }` | `row.a.b` (dot path) |
-| `{ field: 'name', fn: 'upper' }` | `upper(row.name)` |
-| `{ value: 42 }` | literal (string / number / boolean / null / array) |
+| BI report-engine | per-row formulas, conditional totals (`sumif`…), the formula reference / autocomplete |
+| BI text templates | `{{ expr }}` in board text |
+| Workflow (`@xeplr/workflow`) | the condition on each arrow (`xf.evaluate(condition, row)`) |
+| Workflow designer (`@xeplr/ui-workflow`) | formula text → stored JSON (`xf.parse`) |
+
+## The language
 
-`right` is omitted for unary operators (`isNull`, `isNotNull`).
+Written the way BI formulas are written today (expr-eval's syntax), so every
+saved BI formula keeps working, with the changes listed below.
 
-## Operators
+| | |
+|---|---|
+| Numbers, text | `42` `3.5` `1e3` `"text"` `'text'` (a doubled quote or a backslash escapes) |
+| Constants | `true` `false` `null` |
+| Columns / fields | `revenue`, `café`, dotted paths `form.country` · any name in brackets: `[order month]` |
+| Maths | `+ - * / % ^` |
+| Text join | `a \|\| b` |
+| Compare | `=` `==` `!=` `<>` `<` `<=` `>` `>=` · `x in (1, 2, 3)` |
+| Logic | `and` `or` `not` · `cond ? a : b` · `if(cond, a, b)` |
+| Function call | `upper(city)`, `round(amount, 2)` — names are case-insensitive |
 
-`eq` `neq` `isNull` `isNotNull` · `gt` `gte` `lt` `lte` `between` (`[lo,hi]`, inclusive) ·
-`contains` `notContains` `startsWith` `endsWith` · `in` `notIn`
-Aliases: `equals`, `notEquals`, `doesNotContain`.
+**Precedence**, lowest first — identical to expr-eval so old formulas mean what
+they meant: `? :` → `or` → `and` → comparisons and `in` → `+ - ||` →
+`* / %` → unary `- + not` → `^` (right-associative) → calls and paths.
+One consequence to know: `not a = b` reads as `(not a) = b`. Write `not (a = b)`.
 
-`eq`/`neq` against `{ value: null }` also work as null checks. Null-ish values make
-numeric/string comparisons return `false` (never throw).
+**Rules that differ from expr-eval:**
+- `=` means **equals**. expr-eval treated it as assignment, which BI had to
+  turn into an error. There is no assignment at all here.
+- **Equality is forgiving, however it's spelled** — `=` `==` `!=` `<>` are the
+  1.x `eq` / `neq`: `18 = "18"` is true, `null = null` is true. That is what
+  Workflow's stored conditions already mean, and in BI it fixes the silent
+  `false` when a database returns a number as text (Postgres `numeric`).
+  expr-eval's `==` was strict.
+- **Nothing is never less or greater** — `null < 100` is false, as in SQL.
+  expr-eval said true, which sends a Workflow branch the wrong way.
+- `||` stays **text join**, so old formulas keep working. OR is the word `or`.
+- **A name followed by `(` is always a function; a bare name is always a
+  column.** A column called `month` and the function `month()` no longer clash
+  (BI's `formulaScope` workaround goes away).
+- `if()`, `? :`, `and`, `or` **only evaluate what they need**. expr-eval
+  evaluated both branches of every `if`.
 
-## Functions
+**Brackets name a column exactly.** `[order month]`, `[2024 sales]`, `[and]`,
+`[form.country]` (one key that contains a dot) — whatever is inside is the
+column's name, never a keyword, number or path. `]` inside a name is written
+`]]`. Paths combine them: `form.[first name]`. Bare names still work for plain
+ones (`revenue`); the column picker inserts brackets whenever a name needs
+them — a space or symbol, a leading digit, a dot, or a keyword. BI's
+`$thisrow["col"]` keeps working alongside `$thisrow.[col]`.
 
-String: `upper` `lower` `trim` `length` · Date (UTC): `month` (`'January'`) `monthNum`
-`year` `day` `quarter` `weekday` (`'Monday'`).
+**Lists are written in parentheses** — `status in ("paid", "refunded")` — because
+brackets now mean a column. (expr-eval wrote lists as `[ … ]`; no BI formula
+in the code or tests uses them, and the side-by-side test checks saved ones.)
 
-## Extending
+**A name the row doesn't have** reads as `null`. With `{ missing: 'error' }`
+in the context it is an error instead — `Unknown column "revnue"` — which is
+what a report editor wants (expr-eval raised it too).
+
+Errors say where: `Expected ")" at character 18`.
+
+## Stored form
+
+A formula is text for people and a **JSON tree** for storage and running.
+`xf.parse(text)` gives the tree; `xf.compile(textOrTree)` gives a function.
+The 1.x structured shape is a valid tree, so existing Workflow conditions load
+unchanged:
 
 ```js
-xf.registerFunction('reverse', v => String(v).split('').reverse().join(''));
-xf.registerOperator('regex', (a, b) => new RegExp(b).test(String(a)));
+{ left: { field: 'age' }, op: 'gte', right: { value: 18 } }        // 1.x — still valid
+{ op: 'eq', left: { field: 'country' }, right: { value: 'India' } } // what `country = "India"` parses to
+
+{ all: [ <condition>, <condition>, { any: [ <condition>, … ] } ] }  // AND / OR groups (new)
+{ not: <condition> }
 ```
 
-## Formula wrapper (Excel-like)
+The Workflow designer's AND / OR boxes write `all` / `any` groups directly; a
+condition can also be a formula.
+
+## Functions — the one list
 
-Write formulas as strings; they compile to the same structured JSON.
+Each function is one entry: its code **and** what the UI shows.
 
 ```js
-xf.formula.parse('if(upper(someColumn)=anotherColumn, "Yes", "No")');
-// → { if:   { left:{fn:'upper',field:'someColumn'}, op:'eq', right:{field:'anotherColumn'} },
-//     then: { value:'Yes' },
-//     else: { value:'No' } }
+{ name: 'round', category: 'Math', args: 'value, places',
+  description: 'Round to a number of decimal places', example: 'round(amount, 2)',
+  fn: (v, places) => … }
+```
 
-const f = xf.formula.compile('if(score>=90,"A",if(score>=80,"B","C"))');   // nested ifs
-f({ score: 85 });   // → 'B'
+`xf.functions()` returns the list; BI's reference panel, autocomplete and
+validation, and Workflow's condition picker are all built from it.
+`xf.registerFunction(entry)` adds one.
+
+| Category | Functions |
+|---|---|
+| Math | `round` `abs` `ceil` `floor` `sqrt` `min` `max` `pow` `trunc` `exp` `ln` `log` `log10` `log2` `cbrt` |
+| Text | `upper` `lower` `trim` `concat` `substring` `left` `right` `replace` `contains` `startsWith` `endsWith` `length` |
+| Date | `year` `month` `day` `quarter` `weekday` `datediff` `dateadd` `monthname` `monthkey` `quarterkey` `daykey` `ytd` `fytd` |
+| Logic | `if` `coalesce` `ifnull` `isnull` `between` |
+| Aggregate | `sum` `sumif` `countif` `countifunique` — see [Array formulas](#array-formulas) |
+
+`trunc` … `cbrt` were expr-eval built-ins BI never listed; they're listed now
+so saved formulas using them keep working. `log` is the **natural** log there,
+kept that way.
+
+**Behaviour — BI's rules, adopted everywhere (agreed):**
+- **Every function is total:** nonsense in → `null` out, never an exception.
+- **Text of nothing is empty:** `upper(null)` → `''`, never `"null"`.
+- **Empty counts as missing:** `coalesce('', x)` → `x`; `0` is not missing.
+- **Dates:** a date-only string `2026-05-01` is that calendar day in any time
+  zone (built from its parts, as a database driver does). `month()` is
+  `1`–`12`; `monthname()` is `'May'`. The financial year comes from the
+  [run context](#run-context) — April when none is given.
+- **Spreadsheet counting:** `substring(x, 1, 3)` counts from 1.
+
+## Run context
+
+Some answers depend on **who** the formula runs for, which the engine can't
+know. The caller passes them in:
+
+```js
+const f = xf.compile('sumif(fytd(order_date), revenue)', {
+  fiscalYearStart: 7,   // July — the workspace's / company's setting
+  today: '2026-09-19'   // optional; defaults to the current date
+});
 ```
 
-Rules: `"double"`/`'single'` quoted → string literal (doubled quote escapes); bare
-word → field ref; `number` / `null` / `true` / `false` → literals; `name(...)` →
-function (value fn `upper`/`month`…, boolean fn `contains`/`between`/`isnull`…, or
-`if`); comparisons `= == != <> > >= < <=`. Function names are case-insensitive;
-`if(...)` nests. An IF evaluates to its then/else value; a bare comparison
-(`upper(name)="ADA"`) compiles to a boolean predicate.
+| Key | Default | Used by |
+|---|---|---|
+| `fiscalYearStart` | `4` (April) | `fytd` and any financial-year function |
+| `today` | now | `ytd`, `fytd` — pin it for tests and scheduled runs |
+| `missing` | `'null'` | `'error'` makes a name the row lacks an error |
+| `maxListItems` · `maxDistinct` · `maxSteps` · `maxLevels` | see [Limits](#limits) | |
+| `aggregate(name, args, { compile, level })` | none | supplies the rows for the group form of a total (BI) |
 
-`xf.formula.parse(str)` · `xf.formula.compile(str) → (row)=>value` · `xf.formula.evaluate(node, row)`
+**The financial year is a tenant setting.** It belongs to the workspace or
+company, whichever level the app has, and the **app** stores and resolves it
+(BI: the workspace setting; a generated app: its tenancy level). This package
+only receives the value. The context is part of the compile cache key, so two
+tenants with different years never share a compiled formula.
 
-## NLP wrapper (stub)
+## Array formulas
 
-`xf.nlp` — natural language → expression JSON. **Not implemented yet**
-(`xf.nlp.implemented === false`; `xf.nlp.parse()` throws). Placeholder surface for
-a future LLM/grammar backend.
+A formula that adds up **many rows** into one value.
 
-## API
+**Where the rows come from:**
+- **BI** — the rows of the current group, implicitly:
+  `sumif(status = "paid", amount)`. The engine can't see a report's groups, so
+  the caller supplies them through the `aggregate` hook in the context; without
+  it this form is an error that shows the list form.
+- **Workflow and anything else** — a named list, as the first argument:
+  `sumif(orders, month(order_date) = 8, revenue)`. The engine runs these itself,
+  as one loop over the list. Inside the condition and the value, names read the
+  list's item.
+
+**`$thisrow`** refers to the row the formula is being worked out for, from
+inside a condition that runs over other rows:
+
+```
+if(sumif(city = $thisrow.city and month(order_date) = 8, revenue) > 10000, "High August city", "Normal")
+```
+
+— "revenue for **my** city in August; over 10K?".
+
+**Levels.** A total inside another total is one level deeper ("the highest of
+each city's August total" is 2). The `if` and `> 10000` around a total don't
+count. **Maximum: 2 levels** (agreed).
+
+### Memory rules
+
+1. **Streaming, never collecting.** Rows arrive one at a time; each total is a
+   running number (sum, count, min, max, avg) that the row is added to and
+   then forgotten. Memory depends on the number of **groups**, not rows.
+2. **One loop per total, no temporary lists.** `sumif`, and any
+   filter-then-total chain, compiles into a single loop.
+3. **`$thisrow` totals run on the result rows** (grouped, small). If one is
+   ever needed on raw rows, the query runs twice rather than holding the rows.
+4. **Only distinct values grow with the data** — `countifunique` and
+   `$thisrow` partitions keep one entry per distinct key, under a hard cap
+   (below) that ends with a clear error, not an out-of-memory crash.
+5. **Totals are mergeable** (two part-totals add into one), which keeps a later
+   split across processes possible without redesign.
+
+## Speed
+
+A formula is **compiled once** into plain JavaScript closures and then run for
+every row:
+
+1. **Names resolved at compile time.** `revenue` becomes "read `row.revenue`",
+   `upper` a direct reference — no lookup object per row, so a row allocates
+   nothing.
+2. **Constant parts computed once** — `upper("pune")` is folded at compile time.
+3. **Short-circuit** — `if`, `and`, `or` run only what they need.
+4. **Compiled once per run.** Callers compile when a run starts; `xf.compile`
+   also caches by formula text for callers that pass text per row. A test
+   asserts a report run compiles each formula exactly once.
+5. **Date strings parsed once** — the last few parsed strings are remembered,
+   since a streamed report repeats the same dates row after row.
+
+Single-threaded by decision: one report uses one core. If that stops being
+enough, the answer is a move to a compiled language (e.g. Rust), not worker
+threads.
+
+### Measured
+
+1M streamed rows, 4 row formulas (`revenue - cost`, `upper(trim(city))`, a
+nested `if`, `monthname(order_date)`), median of 3 runs, 2026-09-20. Compare
+within a column — the two columns ran under different load.
+
+| Path | Apple M4 Pro | Docker ½ CPU / 256 MB |
+|---|---|---|
+| BI before 2.0 (`enrichRow` — expr-eval, re-parses per row) | 15.5 s | 35.7 s, peak 186 MB |
+| expr-eval, parsed once | 2.2 s | 5.5 s, peak 84 MB |
+| **2.0, compiled once** | **0.38 s** | **1.19 s, peak 62 MB** |
+| 2.0, formula text passed per row (cache) | 0.45 s | 1.29 s, peak 64 MB |
+| hand-written JavaScript (the ceiling) | 0.29 s | 0.89 s, peak 62 MB |
+| August `sumif` per city — BI before 2.0 | 0.95 s | 2.3 s |
+| **August `sumif` per city — 2.0** | **0.16 s** | **0.50 s** |
+| August `sumif` per city — hand-written | 0.15 s | 0.44 s |
+
+About **40× faster** than BI's path before 2.0, and within 1.3× of
+hand-written JavaScript. `bench/run.sh` reproduces it (the expr-eval rows need
+BI checked out beside this repo).
+
+## Limits
+
+| Limit | Value | When hit |
+|---|---|---|
+| Nesting of totals (`maxLevels`) | 2 levels | error at compile time |
+| Distinct values (`maxDistinct`) | 1,000,000 per total | clear error, run stops |
+| Items in one list (`maxListItems`) | 10,000 | clear error |
+| List items visited per evaluation (`maxSteps`) | 10,000,000 | clear error — a formula can't run away |
+
+Each is a context key, so a caller can lower (or raise) it.
+
+## Security
+
+- The only callable things are the functions in the list. A value in the row
+  can never be called, and a function found on a row (inherited `toString`)
+  reads as nothing.
+- Paths through `__proto__`, `constructor` or `prototype` are refused — in
+  formula text and in stored trees.
+- No `eval` / `new Function`, no dependencies. (This removes BI's `expr-eval`,
+  which has two unpatched high-severity advisories.)
+
+## What changes from 1.x
+
+2.0 is a major version. For callers of 1.x (Workflow):
+
+| | 1.x | 2.0 |
+|---|---|---|
+| `month(d)` | `'January'` | `1` (`monthname` gives `'January'`) |
+| Dates | UTC | date-only strings are calendar days; see Functions |
+| `upper(null)` | `null` | `''` |
+| AND / OR | none | `and` / `or` / `not`, `all` / `any` groups |
+| Formula mode | one comparison, `if`, one function per value | the full language |
+| Functions | 10 | the list above |
+| `monthNum` | exists | still accepted, not listed — use `month` |
+| `formula.parse` output | `{ left: { fn, field } … }` | the 2.0 tree (`{ call, args }`) |
+| `functions()` | names | the full entries |
+| `<` `>` in formula text | `gt`, as numbers | JavaScript order (ISO dates work); nothing is never less |
+
+`evaluate(expr, row)`, `toPredicate`, `validate` and the `{ left, op, right }`
+shape keep working.
+
+## Moving callers over
+
+1. **This package — done.** Engine, 63 tests (`npm test`), `bench/`, and
+   `bench/side-by-side.mjs`: every formula in BI's source and tests, plus the
+   saved ones in `report_dataset_formulas`, through expr-eval and 2.0 against
+   five kinds of row. On 2026-09-20: 133 formulas (22 totals, left for BI's own
+   suites), 555 checks, **516 identical**; all 39 differences have a named
+   cause — 32 are expr-eval bugs (a column named like a function; a function
+   used as a value), 7 are the agreed changes (`=`, forgiving equality,
+   `length(null)`). None unexplained; the script exits 1 if one appears.
+2. **BI:** report-engine and text templates switch; `expr-eval` is removed.
+   BI's own formula suites must pass unchanged.
+3. **Workflow:** arrow conditions accept formulas and `all` / `any` groups.
+
+## Decisions (2026-09-19)
+
+- Grow this package rather than add a new one.
+- Our own parser, not a library — the syntax above fits none of them, and the
+  point is to own the security.
+- `=` means equals · `||` joins text · BI's function behaviour wins · the
+  engine lists aggregates, BI keeps the adding-up.
+- At most 2 levels of totals · single-threaded.
+- `[column name]` brackets for any column; lists as `in (a, b)`.
+- The financial year is configurable per workspace / company, passed in the run context.
+- (2026-09-20, while building) Equality is forgiving however it's spelled;
+  nothing is never less or greater. Chosen so Workflow's stored conditions
+  keep their meaning — to be confirmed.
 
-`evaluate(expr, row)` · `toPredicate(expr)` · `validate(expr) → { valid, errors }` ·
-`formula.{parse,compile,evaluate}` · `nlp` (stub) ·
-`registerFunction` · `registerOperator` · `operators()` · `functions()`
+## Open
 
-Test: `npm test` (node --test, no DB). 29 tests.
+- Where each app stores the financial-year setting (BI workspace settings; the
+  CLI's tenancy levels) — decided when those callers move over.

package/index.js

@@ -1,50 +1,165 @@
-// @xeplr/expression-handler — level-1 structured expression evaluator.
+// @xeplr/expression-handler — the one formula engine for xeplr.
 //
 //   const xf = require('@xeplr/expression-handler');
 //
-//   xf.evaluate(
-//     { left: { fn: 'upper', field: 'name' }, op: 'eq', right: { fn: 'upper', field: 'nickName' } },
-//     { name: 'ada', nickName: 'ADA' }
-//   );                                                  // → true
+//   const f = xf.compile('if(country = "India" and score >= 750, "Fast track", "Review")');
+//   f({ country: 'India', score: 800 });                       // → 'Fast track'
 //
-//   const isAdult = xf.toPredicate({ left: { field: 'age' }, op: 'gte', right: { value: 18 } });
-//   rows.filter(isAdult);
+//   xf.parse('revenue - cost')        // → JSON tree, the form that is stored
+//   xf.toText(tree)                   // → back to text, for an editor
+//   xf.analyze('sum(a) / sum(b)')     // → the fields, functions and totals it uses
+//   xf.functions()                    // → the function list, for pickers and help
 //
-// Extend with your own functions / operators:
-//   xf.registerFunction('reverse', v => String(v).split('').reverse().join(''));
-//   xf.registerOperator('regex', (a, b) => new RegExp(b).test(a));
-
-var { evaluate, toPredicate, validate, resolveOperand, getPath } = require('./lib/evaluate');
-var { OPERATORS, registerOperator } = require('./lib/operators');
-var { FUNCTIONS, registerFunction } = require('./lib/functions');
-var { parseFormula, evaluateFormula, compileFormula } = require('./lib/formula');
+//   // Run context — per tenant / per run:
+//   xf.compile('sumif(orders, fytd(date), amount)', { fiscalYearStart: 7 });
+//
+//   // 1.x conditions still work:
+//   xf.evaluate({ left: { field: 'age' }, op: 'gte', right: { value: 18 } }, row);
+//
+// See README.md for the language, the limits and what changed from 1.x.
+
+var parse = require('./lib/parse').parse;
+var compileTree = require('./lib/compile').compileTree;
+var DEFAULTS = require('./lib/compile').DEFAULTS;
+var analyzeTree = require('./lib/analyze').analyzeTree;
+var toText = require('./lib/text').toText;
+var fns = require('./lib/functions');
+var ops = require('./lib/operators');
+var ev = require('./lib/evaluate');
 var nlp = require('./lib/nlp');
 
+// ── compile, with a cache ────────────────────────────────────────────────
+// Callers that pass formula TEXT per row (rather than compiling once up
+// front) still parse each formula once: text → function, keyed by the text
+// and the run context, so two tenants with different financial years never
+// share a compiled formula. Bounded; cleared if a function is registered.
+var CACHE_MAX = 1000;
+var textCache = new Map();
+var treeCache = new WeakMap();
+
+function contextKey(options) {
+  if (!options) return '';
+  var keys = Object.keys(options).sort();
+  var parts = [];
+  for (var i = 0; i < keys.length; i++) {
+    var v = options[keys[i]];
+    if (typeof v === 'function') return null;          // a hook — can't be keyed
+    parts.push(keys[i] + '=' + JSON.stringify(v));
+  }
+  return parts.join('&');
+}
+
+// The common call — text, no context — looks the text up directly, with no
+// key to build: this is the path a caller passing text per row takes.
+var plainCache = new Map();
+
+function compile(formula, options) {
+  if (typeof formula === 'string' && options === undefined) {
+    var plain = plainCache.get(formula);
+    if (plain) return plain;
+    plain = compileTree(parse(formula));
+    if (plainCache.size >= CACHE_MAX) plainCache.clear();
+    plainCache.set(formula, plain);
+    return plain;
+  }
+  var key = contextKey(options);
+  if (typeof formula === 'string') {
+    if (key === null) return compileTree(parse(formula), options);
+    var k = key + '\u0000' + formula;
+    var hit = textCache.get(k);
+    if (hit) return hit;
+    var f = compileTree(parse(formula), options);
+    if (textCache.size >= CACHE_MAX) textCache.clear();
+    textCache.set(k, f);
+    return f;
+  }
+  if (!formula || typeof formula !== 'object') throw new Error('compile: needs formula text or a tree');
+  if (key === null) return compileTree(formula, options);
+  var byKey = treeCache.get(formula);
+  if (!byKey) { byKey = new Map(); treeCache.set(formula, byKey); }
+  var got = byKey.get(key);
+  if (!got) { got = compileTree(formula, options); byKey.set(key, got); }
+  return got;
+}
+
+/**
+ * name → a ready-to-call implementation, with the run context already bound.
+ * For callers that want the FUNCTIONS without the language — BI's dashboard
+ * text templates have their own tiny `{{ }}` reader and only need to call
+ * `monthname(x)`. Aggregates are absent: they span rows, which a caller
+ * outside a formula has none of.
+ */
+function implementations(options) {
+  var ctx = { now: require('./lib/dates').todayFor(options || {}), fiscalYearStart: (options && options.fiscalYearStart) || 4 };
+  var out = {};
+  fns.listFunctions().forEach(function (f) {
+    if (!f.fn || f.aggregate) return;
+    out[f.name] = f.context
+      ? function () { var a = [ctx]; for (var i = 0; i < arguments.length; i++) a.push(arguments[i]); return f.fn.apply(null, a); }
+      : f.fn;
+  });
+  return out;
+}
+
+/** Text or tree → what it uses. */
+function analyze(formula) {
+  return analyzeTree(typeof formula === 'string' ? parse(formula) : formula);
+}
+
+/**
+ * Text → { ok, tree, error, position } without throwing — for editors that
+ * check as the user types.
+ */
+function check(text, options) {
+  try {
+    var tree = parse(text);
+    compileTree(tree, options);
+    return { ok: true, tree: tree, error: null, position: null };
+  } catch (err) {
+    return { ok: false, tree: null, error: err.message, position: err.position === undefined ? null : err.position };
+  }
+}
+
+function registerFunction(entryOrName, fn) {
+  fns.registerFunction(entryOrName, fn);
+  plainCache.clear();
+  textCache.clear();
+  treeCache = new WeakMap();
+}
+
 module.exports = {
-  evaluate: evaluate,
-  toPredicate: toPredicate,
-  validate: validate,
-  resolveOperand: resolveOperand,
-  getPath: getPath,
-
-  // Excel-like formula wrapper → structured JSON (+ evaluate it).
-  //   xf.formula.parse('if(upper(a)=b,"Yes","No")')  → JSON
-  //   xf.formula.compile(str)(row)                    → value
+  parse: parse,
+  toText: toText,
+  compile: compile,
+  analyze: analyze,
+  check: check,
+
+  // 1.x — a condition → true / false; still what Workflow calls per arrow.
+  evaluate: ev.evaluate,
+  toPredicate: ev.toPredicate,
+  validate: ev.validate,
+  resolveOperand: ev.resolveOperand,
+  getPath: ev.getPath,
+
+  // 1.x formula namespace, kept as aliases.
   formula: {
-    parse: parseFormula,
-    evaluate: evaluateFormula,
-    compile: compileFormula
+    parse: parse,
+    compile: function (text, options) { return compile(text, options); },
+    evaluate: function (tree, row, options) { return compile(tree, options)(row); }
   },
 
-  // Natural-language wrapper — STUB (not implemented yet).
-  nlp: nlp,
-
-  registerOperator: registerOperator,
+  functions: fns.listFunctions,
+  implementations: implementations,
+  CATEGORIES: fns.CATEGORIES,
   registerFunction: registerFunction,
 
-  // Introspection — the registered operator/function names.
-  OPERATORS: OPERATORS,
-  FUNCTIONS: FUNCTIONS,
-  operators: function () { return Object.keys(OPERATORS); },
-  functions: function () { return Object.keys(FUNCTIONS); }
+  // 1.x word operators for { left, op, right } conditions.
+  OPERATORS: ops.OPERATORS,
+  registerOperator: ops.registerOperator,
+  operators: function () { return Object.keys(ops.OPERATORS); },
+
+  DEFAULTS: DEFAULTS,
+
+  // Natural-language wrapper — STUB (not implemented yet).
+  nlp: nlp
 };