@xeplr/expression-handler 1.0.6 → 2.0.0

package/lib/functions.js

@@ -1,50 +1,285 @@
-// Field functions — applied to an operand's resolved value before the operator
-// runs. Level 1: a function takes one value and returns one value.
+// The ONE function list — every function a formula can call, with the words
+// the UI shows for it. BI's reference panel, autocomplete and validation and
+// Workflow's condition picker are all built from this; adding a function is
+// adding one entry here.
 //
-// Dates use UTC getters (xeplr stores datetimes as UTC), and month/weekday
-// return English names so `month(dateField) eq 'January'` reads naturally.
-// null/invalid input → null (so the downstream comparison simply fails rather
-// than throwing).
-
-var MONTHS = [
-  'January', 'February', 'March', 'April', 'May', 'June',
-  'July', 'August', 'September', 'October', 'November', 'December'
+// Moved from BI's report-engine/formulaFunctions.js; its implementations and
+// their behaviour are unchanged (BI's saved reports depend on them). The 1.x
+// functions merged in: weekday, between. 1.x's monthNum is now month.
+//
+// EVERY FUNCTION IS TOTAL — nonsense in, null out, never an exception. The
+// engine only evaluates the branch an if() takes, but a function can still see
+// a missing value or a column holding text where a number was expected, and a
+// report must show an empty cell there, not fail.
+//
+// Entry shape:
+//   name, category, args, description, example   what the UI shows
+//   fn          the implementation
+//   min / max   how many arguments it takes (max: Infinity = any number)
+//   context     fn receives the run context first: fn(ctx, …args)
+//   volatile    its answer depends on more than its arguments (the date), so
+//               it is never folded to a constant at compile time
+//   aggregate   spans rows — compiled by the engine, see compile.js
+//   special     syntax rather than a function (if, $thisrow) — listed so the
+//               reference shows it, compiled by the engine
+
+var dates = require('./dates');
+var asDate = dates.asDate;
+
+var CATEGORIES = ['Math', 'Text', 'Date', 'Logic', 'Aggregate'];
+
+function str(v) { return v === null || v === undefined ? '' : String(v); }
+function num(v) { var n = Number(v); return isNaN(n) ? null : n; }
+function isEmpty(v) { return v === null || v === undefined || v === ''; }
+function math(f) { return function (v) { var n = num(v); return n === null ? null : f(n); }; }
+function minMax(pick) {
+  return function () {
+    var vals = arguments.length === 1 && Array.isArray(arguments[0]) ? arguments[0] : Array.prototype.slice.call(arguments);
+    if (!vals.length) return null;
+    var out = null;
+    for (var i = 0; i < vals.length; i++) {
+      var n = num(vals[i]);
+      if (n === null) return null;
+      out = out === null ? n : pick(out, n);
+    }
+    return out;
+  };
+}
+
+var LIST = [
+  // ── Math ──
+  { name: 'round', category: 'Math', args: 'value, places', min: 1, max: 2,
+    description: 'Round to a number of decimal places', example: 'round(amount, 2)',
+    // Nothing rounds to 0, not null — Number(null) is 0, the coercion the rest
+    // of the engine uses (`revenue - missing` is revenue). Text that isn't a
+    // number is null, not NaN.
+    fn: function (v, places) {
+      var n = num(v);
+      if (n === null) return null;
+      var p = Math.pow(10, Number(places) || 0);
+      return Math.round(n * p) / p;
+    } },
+  { name: 'abs', category: 'Math', args: 'value', min: 1, max: 1,
+    description: 'Distance from zero, ignoring sign', example: 'abs(variance)', fn: math(Math.abs) },
+  { name: 'ceil', category: 'Math', args: 'value', min: 1, max: 1,
+    description: 'Round up to a whole number', example: 'ceil(days)', fn: math(Math.ceil) },
+  { name: 'floor', category: 'Math', args: 'value', min: 1, max: 1,
+    description: 'Round down to a whole number', example: 'floor(days)', fn: math(Math.floor) },
+  { name: 'sqrt', category: 'Math', args: 'value', min: 1, max: 1,
+    description: 'Square root', example: 'sqrt(area)', fn: math(Math.sqrt) },
+  { name: 'min', category: 'Math', args: 'a, b, …', min: 1, max: Infinity,
+    description: 'Smallest of the values given — not across rows', example: 'min(price, cap)',
+    fn: minMax(function (a, b) { return b < a ? b : a; }) },
+  { name: 'max', category: 'Math', args: 'a, b, …', min: 1, max: Infinity,
+    description: 'Largest of the values given — not across rows', example: 'max(price, floor_price)',
+    fn: minMax(function (a, b) { return b > a ? b : a; }) },
+  // expr-eval shipped these unlisted, so saved formulas may use them.
+  // log is the NATURAL log there (not Excel's base 10), kept for that reason.
+  { name: 'trunc', category: 'Math', args: 'value', min: 1, max: 1,
+    description: 'Drop the decimals, toward zero', example: 'trunc(hours)', fn: math(Math.trunc) },
+  { name: 'exp', category: 'Math', args: 'value', min: 1, max: 1,
+    description: 'e raised to the value', example: 'exp(rate)', fn: math(Math.exp) },
+  { name: 'ln', category: 'Math', args: 'value', min: 1, max: 1,
+    description: 'Natural logarithm', example: 'ln(growth)', fn: math(Math.log) },
+  { name: 'log', category: 'Math', args: 'value', min: 1, max: 1,
+    description: 'Natural logarithm — the same as ln, not base 10', example: 'log(growth)', fn: math(Math.log) },
+  { name: 'log10', category: 'Math', args: 'value', min: 1, max: 1,
+    description: 'Base-10 logarithm', example: 'log10(size)', fn: math(Math.log10) },
+  { name: 'log2', category: 'Math', args: 'value', min: 1, max: 1,
+    description: 'Base-2 logarithm', example: 'log2(size)', fn: math(Math.log2) },
+  { name: 'cbrt', category: 'Math', args: 'value', min: 1, max: 1,
+    description: 'Cube root', example: 'cbrt(volume)', fn: math(Math.cbrt) },
+  { name: 'pow', category: 'Math', args: 'value, exponent', min: 2, max: 2,
+    description: 'Raise to a power', example: 'pow(rate, years)',
+    fn: function (v, e) { var a = num(v), b = num(e); return a === null || b === null ? null : Math.pow(a, b); } },
+
+  // ── Text ──
+  // Text of nothing is empty, never the word "null" — that would show in a report.
+  { name: 'upper', category: 'Text', args: 'text', min: 1, max: 1,
+    description: 'Convert to upper case', example: 'upper(city)', fn: function (v) { return str(v).toUpperCase(); } },
+  { name: 'lower', category: 'Text', args: 'text', min: 1, max: 1,
+    description: 'Convert to lower case', example: 'lower(email)', fn: function (v) { return str(v).toLowerCase(); } },
+  { name: 'trim', category: 'Text', args: 'text', min: 1, max: 1,
+    description: 'Remove leading and trailing spaces', example: 'trim(name)', fn: function (v) { return str(v).trim(); } },
+  { name: 'concat', category: 'Text', args: 'a, b, …', min: 0, max: Infinity,
+    description: 'Join values into one piece of text', example: 'concat(first, " ", last)',
+    fn: function () { var s = ''; for (var i = 0; i < arguments.length; i++) s += str(arguments[i]); return s; } },
+  // 1-based, like every spreadsheet — a report author is not a programmer.
+  { name: 'substring', category: 'Text', args: 'text, start, count', min: 2, max: 3,
+    description: 'Part of a value, counting from 1', example: 'substring(code, 1, 3)',
+    fn: function (v, start, count) {
+      var s = str(v);
+      var from = Math.max(0, (Number(start) || 1) - 1);
+      return count === undefined ? s.slice(from) : s.slice(from, from + (Number(count) || 0));
+    } },
+  { name: 'left', category: 'Text', args: 'text, count', min: 2, max: 2,
+    description: 'First few characters', example: 'left(deptCode, 3)',
+    fn: function (v, count) { return str(v).slice(0, Number(count) || 0); } },
+  { name: 'right', category: 'Text', args: 'text, count', min: 2, max: 2,
+    description: 'Last few characters', example: 'right(invoice, 4)',
+    fn: function (v, count) { var n = Number(count) || 0; return n <= 0 ? '' : str(v).slice(-n); } },
+  { name: 'replace', category: 'Text', args: 'text, find, replace with', min: 3, max: 3,
+    description: 'Swap one piece of text for another', example: 'replace(phone, "-", "")',
+    fn: function (v, find, into) { return str(v).split(str(find)).join(str(into)); } },
+  { name: 'contains', category: 'Text', args: 'text, find', min: 2, max: 2,
+    description: 'True when the text contains it', example: 'contains(notes, "urgent")',
+    fn: function (v, sub) { return str(v).indexOf(str(sub)) !== -1; } },
+  { name: 'startsWith', category: 'Text', args: 'text, find', min: 2, max: 2,
+    description: 'True when the text begins with it', example: 'startsWith(sku, "IN")',
+    fn: function (v, sub) { return str(v).startsWith(str(sub)); } },
+  { name: 'endsWith', category: 'Text', args: 'text, find', min: 2, max: 2,
+    description: 'True when the text ends with it', example: 'endsWith(file, ".pdf")',
+    fn: function (v, sub) { return str(v).endsWith(str(sub)); } },
+  { name: 'length', category: 'Text', args: 'text', min: 1, max: 1,
+    description: 'How many characters', example: 'length(name)',
+    fn: function (v) { return Array.isArray(v) ? v.length : str(v).length; } },
+
+  // ── Date ── (local time; a date-only string is that calendar day — see dates.js)
+  { name: 'year', category: 'Date', args: 'date', min: 1, max: 1,
+    description: 'The year, as a number', example: 'year(order_date)',
+    fn: function (v) { var d = asDate(v); return d ? d.getFullYear() : null; } },
+  { name: 'month', category: 'Date', args: 'date', min: 1, max: 1,
+    description: 'The month, 1–12', example: 'month(order_date)',
+    fn: function (v) { var d = asDate(v); return d ? d.getMonth() + 1 : null; } },
+  { name: 'day', category: 'Date', args: 'date', min: 1, max: 1,
+    description: 'Day of the month', example: 'day(order_date)',
+    fn: function (v) { var d = asDate(v); return d ? d.getDate() : null; } },
+  { name: 'quarter', category: 'Date', args: 'date', min: 1, max: 1,
+    description: 'The quarter, 1–4', example: 'quarter(order_date)',
+    fn: function (v) { var d = asDate(v); return d ? Math.floor(d.getMonth() / 3) + 1 : null; } },
+  { name: 'weekday', category: 'Date', args: 'date', min: 1, max: 1,
+    description: 'The day of the week by name', example: 'weekday(order_date)',
+    fn: function (v) { var d = asDate(v); return d ? dates.WEEKDAYS[d.getDay()] : null; } },
+  { name: 'datediff', category: 'Date', args: 'from, to', min: 2, max: 2,
+    description: 'Whole days between two dates', example: 'datediff(ordered, shipped)',
+    // Later minus earlier.
+    fn: function (a, b) {
+      var from = asDate(a), to = asDate(b);
+      if (!from || !to) return null;
+      return Math.round((to.getTime() - from.getTime()) / dates.MS_PER_DAY);
+    } },
+  { name: 'dateadd', category: 'Date', args: 'date, days', min: 2, max: 2,
+    description: 'Move a date by a number of days', example: 'dateadd(order_date, 30)',
+    // Built from calendar parts, not by adding milliseconds, so a DST boundary
+    // can't turn "+1 day" into 23 or 25 hours and land on the wrong date.
+    fn: function (v, days) {
+      var d = asDate(v);
+      if (!d) return null;
+      return dates.isoLocal(new Date(d.getFullYear(), d.getMonth(), d.getDate() + (Number(days) || 0)));
+    } },
+  { name: 'monthname', category: 'Date', args: 'date or month number', min: 1, max: 1,
+    description: 'The month by name. Reads well, but sorts alphabetically — group by monthkey instead', example: 'monthname(order_date)',
+    // A number is always a month, never an epoch timestamp — monthname(13)
+    // must not read as 13ms after 1970 and answer "January".
+    fn: function (v) {
+      if (typeof v === 'number') return v >= 1 && v <= 12 ? dates.MONTH_NAMES[v - 1] : null;
+      var d = asDate(v);
+      return d ? dates.MONTH_NAMES[d.getMonth()] : null;
+    } },
+  // Grouping KEYS: they sort correctly as text ("2024-06" before "2024-10"),
+  // which is what makes them safe to pivot or group on, unlike monthname.
+  { name: 'monthkey', category: 'Date', args: 'date', min: 1, max: 1,
+    description: 'The month as 2024-06 — sorts chronologically, so group or pivot by this', example: 'monthkey(order_date)',
+    fn: function (v) { var d = asDate(v); return d ? d.getFullYear() + '-' + String(d.getMonth() + 1).padStart(2, '0') : null; } },
+  { name: 'quarterkey', category: 'Date', args: 'date', min: 1, max: 1,
+    description: 'The quarter as 2024-Q2 — sorts chronologically', example: 'quarterkey(order_date)',
+    fn: function (v) { var d = asDate(v); return d ? d.getFullYear() + '-Q' + (Math.floor(d.getMonth() / 3) + 1) : null; } },
+  { name: 'daykey', category: 'Date', args: 'date', min: 1, max: 1,
+    description: 'The day as 2024-06-17 — sorts chronologically', example: 'daykey(order_date)',
+    fn: function (v) { var d = asDate(v); return d ? dates.isoLocal(d) : null; } },
+  // Predicates, not date maths — they exist to go inside sumif / countif. Both
+  // ends matter: a date later this year is NOT year-to-date. False, not null,
+  // on nothing — the honest answer, and it composes with `not`.
+  { name: 'ytd', category: 'Date', args: 'date', min: 1, max: 1, context: true, volatile: true,
+    description: 'True when the date is in this calendar year, up to today. Pair it with sumif', example: 'ytd(order_date)',
+    fn: function (ctx, v) {
+      var d = asDate(v);
+      if (!d) return false;
+      var now = ctx.now();
+      return d.getFullYear() === now.year && d.getTime() <= now.end.getTime();
+    } },
+  { name: 'fytd', category: 'Date', args: 'date', min: 1, max: 1, context: true, volatile: true,
+    description: 'True when the date is in this financial year, up to today. Pair it with sumif', example: 'fytd(order_date)',
+    fn: function (ctx, v) {
+      var d = asDate(v);
+      if (!d) return false;
+      var now = ctx.now();
+      return d.getTime() >= now.fyStart.getTime() && d.getTime() <= now.end.getTime();
+    } },
+
+  // ── Logic ──
+  { name: 'if', category: 'Logic', args: 'condition, then, otherwise', min: 3, max: 3, special: true,
+    description: 'Choose between two values. Nests freely', example: 'if(qty > 10, "bulk", "single")' },
+  // Empty text counts as missing: a database NULL and an empty cell mean the
+  // same thing to someone reading a report. Zero does not.
+  { name: 'coalesce', category: 'Logic', args: 'a, b, …', min: 1, max: Infinity,
+    description: 'First value that is not empty', example: 'coalesce(nickname, name)',
+    fn: function () { for (var i = 0; i < arguments.length; i++) if (!isEmpty(arguments[i])) return arguments[i]; return null; } },
+  { name: 'ifnull', category: 'Logic', args: 'value, fallback', min: 2, max: 2,
+    description: 'Use a fallback when the value is empty', example: 'ifnull(discount, 0)',
+    fn: function (v, fallback) { return isEmpty(v) ? fallback : v; } },
+  { name: 'isnull', category: 'Logic', args: 'value', min: 1, max: 1,
+    description: 'True when the value is empty', example: 'isnull(closed_date)',
+    fn: function (v) { return isEmpty(v); } },
+  { name: 'between', category: 'Logic', args: 'value, low, high', min: 3, max: 3,
+    description: 'True when the value is from low to high, both included', example: 'between(score, 600, 750)',
+    // Numbers compare as numbers; anything else as text, which orders ISO
+    // dates ("2026-01-31") correctly. Nothing is never between.
+    fn: function (v, lo, hi) {
+      if (isEmpty(v) || isEmpty(lo) || isEmpty(hi)) return false;
+      var x = num(v), a = num(lo), b = num(hi);
+      if (x !== null && a !== null && b !== null) return x >= a && x <= b;
+      var s = String(v);
+      return s >= String(lo) && s <= String(hi);
+    } },
+
+  // ── Aggregate ── spans ROWS; compiled by the engine (compile.js).
+  // In BI the rows are the current group: sumif(status = "paid", amount).
+  // Anywhere else the list comes first:    sumif(orders, status = "paid", amount).
+  { name: 'sum', category: 'Aggregate', args: 'value', min: 1, max: 2, aggregate: true, shape: { cond: false, value: true },
+    description: 'Total across the rows in this group', example: 'sum(amount)' },
+  { name: 'sumif', category: 'Aggregate', args: 'condition, value', min: 2, max: 3, aggregate: true, shape: { cond: true, value: true },
+    description: 'Total across the rows that match', example: 'sumif(status == "refunded", amount)' },
+  { name: 'countif', category: 'Aggregate', args: 'condition', min: 1, max: 2, aggregate: true, shape: { cond: true, value: false },
+    description: 'How many rows match', example: 'countif(qty > 10)' },
+  { name: 'countifunique', category: 'Aggregate', args: 'condition, value', min: 2, max: 3, aggregate: true, shape: { cond: true, value: true },
+    description: 'How many different values among the rows that match', example: 'countifunique(status == "paid", customer_id)' },
+  // Not a function — a reference, usable inside any aggregate's condition.
+  { name: '$thisrow.column', category: 'Aggregate', args: '', special: true,
+    description: 'This row\'s own value, so a total can cover every row sharing it', example: 'sumif(month == $thisrow.month, revenue)' }
 ];
-var WEEKDAYS = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
 
-function toDate(v) {
-  if (v === null || v === undefined) return null;
-  var d = v instanceof Date ? v : new Date(v);
-  return isNaN(d.getTime()) ? null : d;
+// Lookup by lower-cased name. A null-prototype map, so no formula can reach
+// Object.prototype through a function name.
+var FUNCTIONS = Object.create(null);
+LIST.forEach(function (f) { if (!f.special || f.name === 'if') FUNCTIONS[f.name.toLowerCase()] = f; });
+// 1.x name, kept so stored 1.x conditions still run. Not listed.
+FUNCTIONS.monthnum = Object.assign({}, FUNCTIONS.month, { name: 'monthNum', hidden: true });
+
+function lookup(name) {
+  return FUNCTIONS[String(name).toLowerCase()] || null;
 }
 
-function nil(v) { return v === null || v === undefined; }
-
-var FUNCTIONS = {
-  // ── string ──
-  upper:  function (v) { return nil(v) ? null : String(v).toUpperCase(); },
-  lower:  function (v) { return nil(v) ? null : String(v).toLowerCase(); },
-  trim:   function (v) { return nil(v) ? null : String(v).trim(); },
-  length: function (v) { return nil(v) ? null : String(v).length; },
-
-  // ── date (UTC) ──
-  month:   function (v) { var d = toDate(v); return d ? MONTHS[d.getUTCMonth()] : null; },      // 'January'
-  monthNum:function (v) { var d = toDate(v); return d ? d.getUTCMonth() + 1 : null; },           // 1–12
-  year:    function (v) { var d = toDate(v); return d ? d.getUTCFullYear() : null; },
-  day:     function (v) { var d = toDate(v); return d ? d.getUTCDate() : null; },                // 1–31
-  quarter: function (v) { var d = toDate(v); return d ? Math.floor(d.getUTCMonth() / 3) + 1 : null; }, // 1–4
-  weekday: function (v) { var d = toDate(v); return d ? WEEKDAYS[d.getUTCDay()] : null; }         // 'Monday'
-};
-
-function registerFunction(name, fn) {
-  if (typeof fn !== 'function') throw new Error('registerFunction: fn must be a function');
-  FUNCTIONS[name] = fn;
+// registerFunction(entry)  or, as in 1.x, registerFunction(name, fn).
+function registerFunction(entryOrName, fn) {
+  var entry = typeof entryOrName === 'string'
+    ? { name: entryOrName, fn: fn, category: 'Custom', args: '', description: '', example: '' }
+    : Object.assign({}, entryOrName);
+  if (!entry.name || typeof entry.fn !== 'function') throw new Error('registerFunction: needs a name and a function');
+  if (entry.min === undefined) entry.min = 0;
+  if (entry.max === undefined) entry.max = Infinity;
+  var key = entry.name.toLowerCase();
+  if (FUNCTIONS[key] && (FUNCTIONS[key].special || FUNCTIONS[key].aggregate)) {
+    throw new Error('registerFunction: "' + entry.name + '" is built into the language');
+  }
+  var at = LIST.findIndex(function (f) { return f.name.toLowerCase() === key; });
+  if (at === -1) LIST.push(entry); else LIST[at] = entry;
+  FUNCTIONS[key] = entry;
 }
 
-function applyFunction(name, value) {
-  var fn = FUNCTIONS[name];
-  if (!fn) throw new Error('Unknown function: "' + name + '"');
-  return fn(value);
+/** The list the UI renders: every visible entry, in reference order. */
+function listFunctions() {
+  return LIST.filter(function (f) { return !f.hidden; });
 }
 
-module.exports = { FUNCTIONS, registerFunction, applyFunction };
+module.exports = { FUNCTIONS: FUNCTIONS, CATEGORIES: CATEGORIES, lookup: lookup, registerFunction: registerFunction, listFunctions: listFunctions, str: str, num: num, isEmpty: isEmpty };

package/lib/nlp.js

@@ -7,7 +7,7 @@
 // and callers can feature-detect. Wire an LLM/grammar backend here later.
 
 function parse(_text, _options) {
-  throw new Error('nlp wrapper: not implemented yet (stub). Use formula.parseFormula or the structured JSON API.');
+  throw new Error('nlp wrapper: not implemented yet (stub). Use xf.parse / xf.compile or the structured JSON API.');
 }
 
 module.exports = {

package/lib/parse.js

@@ -0,0 +1,301 @@
+// Formula text → JSON tree. Our own reader: no eval, no dependencies.
+//
+// The grammar is BI's formula language (expr-eval's), with the agreed changes:
+// `=` is equals, `[any name]` is a column, lists are `in (a, b)`. Precedence,
+// lowest first — identical to expr-eval, so old formulas mean what they meant:
+//
+//   ? :   →   or   →   and   →   = == != <> < <= > >= in   →   + - ||
+//   →   * / %   →   unary - + not   →   ^ (right)   →   calls, paths
+//
+// The tree (all plain JSON — it is what gets stored):
+//   { value: 42 }                          literal
+//   { field: 'revenue' }                   a column
+//   { path: ['form', 'first name'] }       a path, or a name only brackets can write
+//   { thisrow: ['city'] }                  $thisrow.city
+//   { call: 'upper', args: [ … ] }         a function
+//   { op: '+', left, right }               + - * / % ^ || < <= > >= in
+//   { op: 'eq', left, right }              = == (and 'neq' for != <>) — the 1.x shape
+//   { neg: x }  { pos: x }  { not: x }     unary
+//   { all: [ … ] }  { any: [ … ] }         and / or
+//   { if, then, else }                     if() and ? :
+//   { list: [ … ] }                        the right side of `in (…)`
+
+var functions = require('./functions');
+
+var KEYWORDS = new Set(['and', 'or', 'not', 'in', 'true', 'false', 'null']);
+// A Set, not an object literal: `{ __proto__: 1 }` would set the prototype.
+var BLOCKED = new Set(['__proto__', 'constructor', 'prototype']);
+var ESCAPES = { n: '\n', r: '\r', t: '\t', b: '\b', f: '\f', '\\': '\\', '/': '/', '"': '"', "'": "'" };
+
+function fail(message, at) {
+  var err = new Error(message + (at === undefined ? '' : ' at character ' + (at + 1)));
+  err.position = at;
+  throw err;
+}
+
+// ── tokens ────────────────────────────────────────────────────────────────
+// { t: 'num'|'str'|'name'|'bracket'|'punct'|'end', v, at }
+function tokenize(src) {
+  var out = [];
+  var i = 0, n = src.length;
+  while (i < n) {
+    var c = src[i];
+    if (c === ' ' || c === '\t' || c === '\n' || c === '\r') { i++; continue; }
+    var at = i;
+
+    if (c === '"' || c === "'") {
+      // A backslash escapes (as expr-eval); a doubled quote escapes (as 1.x).
+      var q = c, s = '';
+      i++;
+      for (;;) {
+        if (i >= n) fail('Text is never closed — missing ' + q, at);
+        var ch = src[i];
+        if (ch === '\\') {
+          var e = src[i + 1];
+          if (e === 'u' && /^[0-9a-fA-F]{4}$/.test(src.substr(i + 2, 4))) { s += String.fromCharCode(parseInt(src.substr(i + 2, 4), 16)); i += 6; continue; }
+          if (ESCAPES[e] === undefined) fail('Unknown escape \\' + (e || ''), i);
+          s += ESCAPES[e]; i += 2; continue;
+        }
+        if (ch === q) {
+          if (src[i + 1] === q) { s += q; i += 2; continue; }
+          i++; break;
+        }
+        s += ch; i++;
+      }
+      out.push({ t: 'str', v: s, at: at });
+      continue;
+    }
+
+    if (c === '[') {
+      // Everything up to the closing ] is the name; ]] is a literal ].
+      var name = '';
+      i++;
+      for (;;) {
+        if (i >= n) fail('Column name is never closed — missing ]', at);
+        if (src[i] === ']') {
+          if (src[i + 1] === ']') { name += ']'; i += 2; continue; }
+          i++; break;
+        }
+        name += src[i++];
+      }
+      out.push({ t: 'bracket', v: name, at: at });
+      continue;
+    }
+
+    if ((c >= '0' && c <= '9') || (c === '.' && src[i + 1] >= '0' && src[i + 1] <= '9')) {
+      var m = /^(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?/.exec(src.slice(i));
+      out.push({ t: 'num', v: parseFloat(m[0]), at: at });
+      i += m[0].length;
+      continue;
+    }
+
+    // Any letter, as expr-eval allows — `café`, `größe`.
+    if (/[\p{L}_$]/u.test(c)) {
+      var id = /^[\p{L}_$][\p{L}\p{N}_$]*/u.exec(src.slice(i))[0];
+      out.push({ t: 'name', v: id, at: at });
+      i += id.length;
+      continue;
+    }
+
+    var two = src.substr(i, 2);
+    if (two === '==' || two === '!=' || two === '<>' || two === '<=' || two === '>=' || two === '||') {
+      out.push({ t: 'punct', v: two, at: at }); i += 2; continue;
+    }
+    if ('()+-*/%^,.?:=<>'.indexOf(c) !== -1) { out.push({ t: 'punct', v: c, at: at }); i++; continue; }
+    if (c === '!') fail('Use "not" rather than "!"', at);
+    fail('Unexpected character "' + c + '"', at);
+  }
+  out.push({ t: 'end', at: n });
+  return out;
+}
+
+// ── grammar ───────────────────────────────────────────────────────────────
+function parse(src) {
+  if (typeof src !== 'string') throw new Error('parse: formula must be text');
+  if (!src.trim()) fail('The formula is empty');
+  var toks = tokenize(src);
+  var pos = 0;
+
+  function peek() { return toks[pos]; }
+  function next() { return toks[pos++]; }
+  function isPunct(v) { var t = toks[pos]; return t.t === 'punct' && t.v === v; }
+  function isWord(w) { var t = toks[pos]; return t.t === 'name' && t.v.toLowerCase() === w; }
+  function describe(t) {
+    if (t.t === 'end') return 'the end of the formula';
+    if (t.t === 'str') return 'text "' + t.v + '"';
+    if (t.t === 'bracket') return '[' + t.v + ']';
+    return '"' + t.v + '"';
+  }
+  function expect(v) {
+    if (!isPunct(v)) fail('Expected "' + v + '" but found ' + describe(peek()), peek().at);
+    return next();
+  }
+
+  function conditional() {
+    var cond = or();
+    if (!isPunct('?')) return cond;
+    next();
+    var yes = conditional();
+    expect(':');
+    return { if: cond, then: yes, else: conditional() };
+  }
+
+  function or() {
+    var first = and();
+    if (!isWord('or')) return first;
+    var parts = [first];
+    while (isWord('or')) { next(); parts.push(and()); }
+    return { any: parts };
+  }
+
+  function and() {
+    var first = comparison();
+    if (!isWord('and')) return first;
+    var parts = [first];
+    while (isWord('and')) { next(); parts.push(comparison()); }
+    return { all: parts };
+  }
+
+  // Equality is the 1.x `eq` / `neq` whichever way it's spelled — forgiving
+  // (18 = "18"), and the shape Workflow's stored conditions already use.
+  var COMPARE = { '=': 'eq', '==': 'eq', '!=': 'neq', '<>': 'neq', '<': '<', '<=': '<=', '>': '>', '>=': '>=' };
+
+  function comparison() {
+    var left = addSub();
+    for (;;) {
+      var t = peek();
+      if (t.t === 'punct' && COMPARE[t.v]) { next(); left = { op: COMPARE[t.v], left: left, right: addSub() }; continue; }
+      if (isWord('in')) { next(); left = { op: 'in', left: left, right: inList() }; continue; }
+      return left;
+    }
+  }
+
+  // `in (a, b, c)` is a list; anything else is an expression holding one.
+  function inList() {
+    var t = peek();
+    if (t.t === 'bracket') fail('Lists are written in parentheses — in (' + t.v + ')', t.at);
+    if (!isPunct('(')) return addSub();
+    next();
+    var items = [];
+    if (!isPunct(')')) {
+      items.push(conditional());
+      while (isPunct(',')) { next(); items.push(conditional()); }
+    }
+    expect(')');
+    return { list: items };
+  }
+
+  function addSub() {
+    var left = term();
+    for (;;) {
+      var t = peek();
+      if (t.t === 'punct' && (t.v === '+' || t.v === '-' || t.v === '||')) { next(); left = { op: t.v, left: left, right: term() }; continue; }
+      return left;
+    }
+  }
+
+  function term() {
+    var left = factor();
+    for (;;) {
+      var t = peek();
+      if (t.t === 'punct' && (t.v === '*' || t.v === '/' || t.v === '%')) { next(); left = { op: t.v, left: left, right: factor() }; continue; }
+      return left;
+    }
+  }
+
+  function factor() {
+    if (isPunct('-')) { next(); return { neg: factor() }; }
+    if (isPunct('+')) { next(); return { pos: factor() }; }
+    if (isWord('not')) { next(); return { not: factor() }; }
+    return exponential();
+  }
+
+  function exponential() {
+    var base = atom();
+    if (!isPunct('^')) return base;
+    next();
+    return { op: '^', left: base, right: factor() };
+  }
+
+  function atom() {
+    var t = next();
+    if (t.t === 'num') return { value: t.v };
+    if (t.t === 'str') return { value: t.v };
+    if (t.t === 'punct' && t.v === '(') { var inner = conditional(); expect(')'); return inner; }
+    if (t.t === 'bracket') return pathFrom([segment(t.v, t.at)]);
+    if (t.t === 'name') {
+      var low = t.v.toLowerCase();
+      if (isPunct('(')) return call(t);
+      if (low === 'true') return { value: true };
+      if (low === 'false') return { value: false };
+      if (low === 'null') return { value: null };
+      if (KEYWORDS.has(low)) fail('"' + t.v + '" is a keyword here — write [' + t.v + '] for a column of that name', t.at);
+      if (low === '$thisrow') {
+        var rest = pathSegments([]);
+        if (!rest.length) fail('$thisrow needs a column — $thisrow.city', t.at);
+        return { thisrow: rest };
+      }
+      return pathFrom([segment(t.v, t.at)]);
+    }
+    fail('Expected a value but found ' + describe(t), t.at);
+  }
+
+  function segment(name, at) {
+    if (BLOCKED.has(name)) fail('"' + name + '" can\'t be used as a column name', at);
+    return name;
+  }
+
+  // Continues a path: .name  .[any name]  [any name]  ["name"]  [0]
+  function pathSegments(segs) {
+    for (;;) {
+      var t = peek();
+      if (t.t === 'punct' && t.v === '.') {
+        next();
+        var s = next();
+        if (s.t === 'name' || s.t === 'bracket') { segs.push(segment(s.v, s.at)); continue; }
+        fail('Expected a name after "." but found ' + describe(s), s.at);
+      }
+      if (t.t === 'bracket') {
+        next();
+        var q = /^\s*(["'])([\s\S]*)\1\s*$/.exec(t.v);
+        segs.push(segment(q ? q[2] : t.v, t.at));
+        continue;
+      }
+      return segs;
+    }
+  }
+
+  function pathFrom(segs) {
+    var start = pos;
+    segs = pathSegments(segs);
+    if (isPunct('(')) fail('Only a function name can be followed by "("', peek().at);
+    // A lone plain name keeps the 1.x { field } shape; anything else is a path,
+    // so a bracketed name containing a dot is never split into two.
+    if (segs.length === 1 && segs[0].indexOf('.') === -1 && pos === start) return { field: segs[0] };
+    return { path: segs };
+  }
+
+  function call(nameTok) {
+    var entry = functions.lookup(nameTok.v);
+    if (!entry || (entry.special && entry.name !== 'if')) fail('Unknown function "' + nameTok.v + '"', nameTok.at);
+    expect('(');
+    var args = [];
+    if (!isPunct(')')) {
+      args.push(conditional());
+      while (isPunct(',')) { next(); args.push(conditional()); }
+    }
+    expect(')');
+    if (args.length < entry.min || args.length > entry.max) {
+      var want = entry.min === entry.max ? String(entry.min) : entry.max === Infinity ? 'at least ' + entry.min : entry.min + ' to ' + entry.max;
+      fail(entry.name + '() takes ' + want + ' argument' + (want === '1' ? '' : 's') + ', not ' + args.length, nameTok.at);
+    }
+    if (entry.name === 'if') return { if: args[0], then: args[1], else: args[2] };
+    return { call: entry.name, args: args };
+  }
+
+  var tree = conditional();
+  if (peek().t !== 'end') fail('Unexpected ' + describe(peek()), peek().at);
+  return tree;
+}
+
+module.exports = { parse: parse, tokenize: tokenize, BLOCKED: BLOCKED };