@xeplr/expression-handler 1.0.6 → 2.1.0

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 };

package/lib/text.js

@@ -0,0 +1,103 @@
+// JSON tree → formula text. The other direction from parse.js, and the reason
+// it lives here: an editor that shows a stored condition back to someone has
+// to write the same language the engine reads. Written anywhere else it would
+// drift, and the drift would only show when a condition that displays fine
+// fails to compile.
+//
+//   toText(xf.parse('a=1 and upper(b)="X"'))   // → 'a = 1 and upper(b) = "X"'
+//   toText(parse(t)) parses again to the same tree (round-trip).
+//
+// Brackets go round any name that isn't a plain one, and parentheses only
+// where precedence needs them.
+
+var PLAIN = /^[\p{L}_$][\p{L}\p{N}_$]*$/u;
+var KEYWORD = /^(and|or|not|in|true|false|null)$/i;
+
+// Mirrors parse.js. A child binds looser than its parent → parenthesise.
+var PREC = { any: 2, all: 3, compare: 4, add: 5, mul: 6, unary: 7, pow: 8, atom: 9 };
+var OP_PREC = {
+  eq: PREC.compare, neq: PREC.compare, '<': PREC.compare, '<=': PREC.compare,
+  '>': PREC.compare, '>=': PREC.compare, in: PREC.compare,
+  '+': PREC.add, '-': PREC.add, '||': PREC.add,
+  '*': PREC.mul, '/': PREC.mul, '%': PREC.mul,
+  '^': PREC.pow
+};
+// The 1.x word operators have no infix spelling; they are written as text
+// (`between(x, 1, 10)`) where one exists, and otherwise left to the caller.
+var WORD_OP_TEXT = { eq: '=', equals: '=', neq: '!=', notEquals: '!=', gt: '>', gte: '>=', lt: '<', lte: '<=' };
+
+function name(n) {
+  var s = String(n);
+  return PLAIN.test(s) && !KEYWORD.test(s) ? s : '[' + s.split(']').join(']]') + ']';
+}
+
+function literal(v) {
+  if (v === null) return 'null';
+  if (typeof v === 'string') return '"' + v.split('"').join('""') + '"';
+  if (typeof v === 'number' || typeof v === 'boolean') return String(v);
+  if (Array.isArray(v)) return '(' + v.map(literal).join(', ') + ')';
+  if (v === undefined) return 'null';
+  if (v instanceof Date) return '"' + v.toISOString() + '"';
+  return '"' + String(v).split('"').join('""') + '"';
+}
+
+function precOf(node) {
+  if (!node || typeof node !== 'object') return PREC.atom;
+  if (node.any !== undefined) return PREC.any;
+  if (node.all !== undefined) return PREC.all;
+  if (node.not !== undefined || node.neg !== undefined || node.pos !== undefined) return PREC.unary;
+  if (node.op !== undefined) return OP_PREC[node.op] || PREC.compare;
+  return PREC.atom;
+}
+
+function wrap(node, min) {
+  var text = toText(node);
+  return precOf(node) < min ? '(' + text + ')' : text;
+}
+
+function toText(node) {
+  if (node === null || node === undefined) return '';
+  if (typeof node !== 'object') return literal(node);
+
+  if (node.fn !== undefined && node.call === undefined) {          // 1.x operand
+    var inner = Object.assign({}, node);
+    delete inner.fn;
+    return String(node.fn) + '(' + toText(inner) + ')';
+  }
+  if (Object.prototype.hasOwnProperty.call(node, 'value')) return literal(node.value);
+  if (node.field !== undefined) return String(node.field).split('.').map(name).join('.');
+  if (node.path !== undefined) return node.path.map(name).join('.');
+  if (node.thisrow !== undefined) return '$thisrow.' + node.thisrow.map(name).join('.');
+  if (node.list !== undefined) return '(' + node.list.map(toText).join(', ') + ')';
+  if (node.call !== undefined) return String(node.call) + '(' + (node.args || []).map(toText).join(', ') + ')';
+  if (node.if !== undefined) return 'if(' + toText(node.if) + ', ' + toText(node.then) + ', ' + toText(node.else) + ')';
+  if (node.all !== undefined) return node.all.map(function (n) { return wrap(n, PREC.all); }).join(' and ');
+  if (node.any !== undefined) return node.any.map(function (n) { return wrap(n, PREC.any); }).join(' or ');
+  if (node.not !== undefined) return 'not ' + wrap(node.not, PREC.unary);
+  if (node.neg !== undefined) return '-' + wrap(node.neg, PREC.unary);
+  if (node.pos !== undefined) return '+' + wrap(node.pos, PREC.unary);
+
+  if (node.op !== undefined) {
+    var sym = WORD_OP_TEXT[node.op] || (OP_PREC[node.op] ? node.op : null);
+    var here = precOf(node);
+    if (sym) {
+      var left = wrap(node.left, here);
+      if (node.right === undefined || node.right === null) return left + ' ' + sym;
+      // The right side of a left-associative operator needs parentheses at
+      // equal precedence: a - (b - c) is not a - b - c.
+      var right = wrap(node.right, node.op === '^' ? here : here + 1);
+      return left + ' ' + sym + ' ' + right;
+    }
+    // Word operators with no infix spelling: contains, between, isNull, in…
+    var args = [toText(node.left)];
+    if (node.right !== undefined && node.right !== null) {
+      var r = node.right;
+      if (node.op === 'between' && r && Array.isArray(r.value)) args = args.concat(r.value.map(literal));
+      else args.push(toText(r));
+    }
+    return String(node.op) + '(' + args.join(', ') + ')';
+  }
+  return '';
+}
+
+module.exports = { toText: toText };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@xeplr/expression-handler",
-  "version": "1.0.6",
-  "description": "Level-1 structured expression evaluator — apply field functions (upper/month/…) and operators (eq/contains/gt/between/isNull/…) to a data row. No parser; JSON expressions in, boolean out.",
+  "version": "2.1.0",
+  "description": "The one formula engine for xeplr: its own parser (no eval, no dependencies), one function list, compiled-once formulas, totals over lists, AND/OR conditions. Runs in Node and the browser.",
   "main": "index.js",
   "files": [
     "index.js",

package/lib/formula.js

@@ -1,196 +0,0 @@
-// Formula wrapper — parse an Excel-like formula string into the structured
-// JSON the evaluator understands, and evaluate it against a row.
-//
-//   parseFormula('if(upper(someColumn)=anotherColumn, "Yes", "No")')
-//   →
-//   { if:   { left: { fn:'upper', field:'someColumn' }, op:'eq',
-//             right: { field:'anotherColumn' } },
-//     then: { value: 'Yes' },
-//     else: { value: 'No' } }
-//
-// Rules (level 1 — no arithmetic, no AND/OR, single function nesting):
-//   • "double quoted" (or 'single quoted') → string literal   { value }
-//   • bare word                            → field reference  { field }
-//   • number / null / true / false         → literal          { value }
-//   • name(...)                            → function call (value fn like
-//       upper/month, boolean fn like contains/between/isnull, or IF)
-//   • comparisons:  =  ==  !=  <>  >  >=  <  <=
-//
-// An IF node evaluates to its then/else VALUE; a bare comparison evaluates to
-// a boolean. So compileFormula() yields a value-producer or a predicate alike.
-
-var { evaluate, resolveOperand } = require('./evaluate');
-var { FUNCTIONS } = require('./functions');
-
-// Boolean functions → operator names (arity fixed). Keys are lowercased.
-var BOOL_FUNCS = {
-  contains:       { op: 'contains',    arity: 2 },
-  notcontains:    { op: 'notContains', arity: 2 },
-  doesnotcontain: { op: 'notContains', arity: 2 },
-  startswith:     { op: 'startsWith',  arity: 2 },
-  endswith:       { op: 'endsWith',    arity: 2 },
-  isnull:         { op: 'isNull',      arity: 1 },
-  isnotnull:      { op: 'isNotNull',   arity: 1 },
-  between:        { op: 'between',      arity: 3 }
-};
-
-var OP_SYMBOLS = { '=': 'eq', '==': 'eq', '!=': 'neq', '<>': 'neq', '>': 'gt', '>=': 'gte', '<': 'lt', '<=': 'lte' };
-
-// ── tokenizer ────────────────────────────────────────────────────────────
-function tokenize(input) {
-  var tokens = [];
-  var i = 0, n = input.length;
-  while (i < n) {
-    var c = input[i];
-    if (/\s/.test(c)) { i++; continue; }
-
-    if (c === '"' || c === "'") {                 // string literal (doubled quote = escape)
-      var q = c; i++; var s = '';
-      while (i < n) {
-        if (input[i] === q) {
-          if (input[i + 1] === q) { s += q; i += 2; continue; }
-          i++; break;
-        }
-        s += input[i++];
-      }
-      tokens.push({ t: 'string', v: s });
-      continue;
-    }
-    if (c === '(') { tokens.push({ t: 'lparen' }); i++; continue; }
-    if (c === ')') { tokens.push({ t: 'rparen' }); i++; continue; }
-    if (c === ',') { tokens.push({ t: 'comma' }); i++; continue; }
-
-    var two = input.substr(i, 2);
-    if (two === '>=' || two === '<=' || two === '<>' || two === '!=' || two === '==') { tokens.push({ t: 'op', v: two }); i += 2; continue; }
-    if (c === '=' || c === '>' || c === '<') { tokens.push({ t: 'op', v: c }); i++; continue; }
-
-    if (/[0-9]/.test(c) || (c === '-' && /[0-9]/.test(input[i + 1] || ''))) {
-      var num = c; i++;
-      while (i < n && /[0-9.]/.test(input[i])) num += input[i++];
-      tokens.push({ t: 'number', v: parseFloat(num) });
-      continue;
-    }
-    if (/[A-Za-z_]/.test(c)) {
-      var id = c; i++;
-      while (i < n && /[A-Za-z0-9_.]/.test(input[i])) id += input[i++];
-      tokens.push({ t: 'ident', v: id });
-      continue;
-    }
-    throw new Error('Unexpected character "' + c + '" at position ' + i);
-  }
-  return tokens;
-}
-
-// Resolve a function name to the registry's canonical (case-insensitive) key.
-function canonicalFn(low) {
-  if (FUNCTIONS[low]) return low;
-  var keys = Object.keys(FUNCTIONS);
-  for (var i = 0; i < keys.length; i++) if (keys[i].toLowerCase() === low) return keys[i];
-  return low;   // unknown — evaluate() will throw a clear error at run time
-}
-
-function literalOf(node, ctx) {
-  if (node && Object.prototype.hasOwnProperty.call(node, 'value')) return node.value;
-  throw new Error(ctx + ' must be a literal value');
-}
-
-// ── parser (recursive descent) ─────────────────────────────────────────────
-function parseFormula(input) {
-  if (typeof input !== 'string') throw new Error('parseFormula: input must be a string');
-  var toks = tokenize(input);
-  var pos = 0;
-  function peek() { return toks[pos]; }
-  function expect(t) {
-    var tk = toks[pos];
-    if (!tk || tk.t !== t) throw new Error('Expected ' + t + ' but got ' + (tk ? (tk.t + (tk.v != null ? ' "' + tk.v + '"' : '')) : 'end of formula'));
-    return toks[pos++];
-  }
-
-  function parseExpression() {
-    var left = parsePrimary();
-    var tk = peek();
-    if (tk && tk.t === 'op') {
-      pos++;
-      var right = parsePrimary();
-      return { left: left, op: OP_SYMBOLS[tk.v], right: right };
-    }
-    return left;
-  }
-
-  function parsePrimary() {
-    var tk = peek();
-    if (!tk) throw new Error('Unexpected end of formula');
-
-    if (tk.t === 'string') { pos++; return { value: tk.v }; }
-    if (tk.t === 'number') { pos++; return { value: tk.v }; }
-    if (tk.t === 'lparen') { pos++; var e = parseExpression(); expect('rparen'); return e; }
-
-    if (tk.t === 'ident') {
-      var name = tk.v;
-      var low = name.toLowerCase();
-      var isCall = toks[pos + 1] && toks[pos + 1].t === 'lparen';
-      if (isCall) {
-        pos += 2;                                  // consume ident + '('
-        if (low === 'if') return parseIf();
-        if (BOOL_FUNCS[low]) return parseBoolFunc(low);
-        return parseValueFunc(low);
-      }
-      pos++;
-      if (low === 'null') return { value: null };
-      if (low === 'true') return { value: true };
-      if (low === 'false') return { value: false };
-      return { field: name };                      // field refs keep their case
-    }
-    throw new Error('Unexpected token: ' + tk.t);
-  }
-
-  function parseIf() {                              // 'if' + '(' already consumed
-    var cond = parseExpression();
-    expect('comma');
-    var thenNode = parseExpression();
-    expect('comma');
-    var elseNode = parseExpression();
-    expect('rparen');
-    return { if: cond, then: thenNode, else: elseNode };
-  }
-
-  function parseValueFunc(low) {                    // e.g. upper(x), month(d)
-    var arg = parseExpression();
-    expect('rparen');
-    if (arg && (arg.fn || arg.if || arg.op)) throw new Error('level-1: function "' + low + '" argument must be a field or literal');
-    return Object.assign({ fn: canonicalFn(low) }, arg);
-  }
-
-  function parseBoolFunc(low) {                     // e.g. contains(a,b), isnull(a), between(a,lo,hi)
-    var def = BOOL_FUNCS[low];
-    var args = [parseExpression()];
-    while (peek() && peek().t === 'comma') { pos++; args.push(parseExpression()); }
-    expect('rparen');
-    if (args.length !== def.arity) throw new Error(low + '() expects ' + def.arity + ' argument(s), got ' + args.length);
-    if (def.op === 'between') return { left: args[0], op: 'between', right: { value: [literalOf(args[1], 'between low bound'), literalOf(args[2], 'between high bound')] } };
-    if (def.arity === 1) return { left: args[0], op: def.op };
-    return { left: args[0], op: def.op, right: args[1] };
-  }
-
-  var result = parseExpression();
-  if (pos < toks.length) throw new Error('Unexpected trailing tokens in formula (near token ' + (pos + 1) + ')');
-  return result;
-}
-
-// ── evaluation ─────────────────────────────────────────────────────────────
-// Returns a VALUE (IF → then/else value), or a boolean (bare comparison).
-function evaluateFormula(node, row) {
-  if (node === null || node === undefined) return null;
-  if (Object.prototype.hasOwnProperty.call(node, 'if')) {
-    return evaluate(node.if, row) ? evaluateFormula(node.then, row) : evaluateFormula(node.else, row);
-  }
-  if (node.op) return evaluate(node, row);         // comparison → boolean
-  return resolveOperand(node, row);                // operand → value
-}
-
-function compileFormula(input) {
-  var node = parseFormula(input);
-  return function (row) { return evaluateFormula(node, row); };
-}
-
-module.exports = { parseFormula, evaluateFormula, compileFormula };