@xeplr/expression-handler 1.0.6 → 2.0.0

package/lib/analyze.js

@@ -0,0 +1,71 @@
+// What a formula uses, without running it — for editors (which columns does
+// this need? is it a per-row or a per-group formula?) and for validation.
+//
+//   analyze('if(sum(a) > 10, upper(city), "-")')
+//   → { fields: ['a', 'city'], fieldsOutsideTotals: ['city'], thisrow: [],
+//       functions: ['sum', 'upper'], aggregates: [{ name: 'sum', list: null, fields: ['a'] }],
+//       levels: 1 }
+//
+// `fields` are dotted names (`form.country`); a list total's own list counts
+// as a field of the row, its condition and value read the list's items.
+
+var functions = require('./functions');
+
+function analyzeTree(tree) {
+  var fields = [];
+  var outside = [];
+  var thisrow = [];
+  var fns = [];
+  var aggregates = [];
+  var levels = 0;
+
+  function add(list, v) { if (list.indexOf(v) === -1) list.push(v); }
+
+  // `into` collects the fields of the innermost total being walked, or null.
+  function walk(node, level, into) {
+    if (!node || typeof node !== 'object') return;
+    if (Array.isArray(node)) { node.forEach(function (n) { walk(n, level, into); }); return; }
+
+    if (node.fn !== undefined && node.call === undefined) add(fns, functions.lookup(node.fn) ? functions.lookup(node.fn).name : String(node.fn));
+    if (node.field !== undefined || node.path !== undefined) {
+      var name = node.field !== undefined ? String(node.field) : node.path.join('.');
+      add(fields, name);
+      if (into) add(into, name); else add(outside, name);
+    }
+    if (node.thisrow !== undefined) add(thisrow, node.thisrow.join('.'));
+
+    if (node.call !== undefined) {
+      var entry = functions.lookup(node.call);
+      var fname = entry ? entry.name : String(node.call);
+      add(fns, fname);
+      var args = node.args || [];
+      if (entry && entry.aggregate) {
+        var implicit = (entry.shape.cond ? 1 : 0) + (entry.shape.value ? 1 : 0);
+        var hasList = args.length === implicit + 1;
+        var own = [];
+        var agg = { name: entry.name, list: null, fields: own };
+        levels = Math.max(levels, level + 1);
+        if (hasList) {
+          var l = args[0];
+          agg.list = l.field !== undefined ? String(l.field) : l.path ? l.path.join('.') : null;
+          walk(l, level, into);
+        }
+        (hasList ? args.slice(1) : args).forEach(function (a) { walk(a, level + 1, own); });
+        own.forEach(function (f) { add(fields, f); if (into) add(into, f); });
+        aggregates.push(agg);
+        return;
+      }
+      walk(args, level, into);
+      return;
+    }
+
+    ['left', 'right', 'if', 'then', 'else', 'not', 'neg', 'pos', 'all', 'any', 'list'].forEach(function (k) {
+      if (node[k] !== undefined) walk(node[k], level, into);
+    });
+  }
+
+  walk(tree, 0, null);
+  return { fields: fields, fieldsOutsideTotals: outside, thisrow: thisrow, functions: fns, aggregates: aggregates, levels: levels };
+}
+
+module.exports = { analyzeTree: analyzeTree };

package/lib/compile.js

@@ -0,0 +1,323 @@
+// JSON tree → a plain JavaScript function, built ONCE and then run per row.
+//
+// Every node becomes a closure (row, top) → value, with everything that can
+// be settled up front settled here:
+//   • names — `revenue` becomes "read row.revenue", `upper` a direct
+//     reference; running a row looks nothing up and allocates nothing
+//   • constants — any part whose inputs are all fixed (`upper("pune")`,
+//     `-5`, `2 * 3`) is worked out now and becomes that value
+//   • short-circuit — if / ? : / and / or run only what they need
+//
+// `row` is what names read; `top` is the row the formula is being worked out
+// for — the same object except inside a list total, where names read the list
+// item and $thisrow still reads `top`.
+//
+// Operators behave as expr-eval's did (BI's saved formulas depend on it) —
+// `+` adds as numbers, `||` joins as text, `and` / `or` give true / false —
+// with two deliberate changes: equality is forgiving (18 = "18"; it is the 1.x
+// `eq`, which Workflow's conditions already use), and comparing nothing with
+// < > is false. The 1.x word operators (eq, gt, contains, …) keep their 1.x
+// meaning — see operators.js.
+
+var functions = require('./functions');
+var operators = require('./operators');
+var dates = require('./dates');
+var BLOCKED = require('./parse').BLOCKED;
+
+var DEFAULTS = {
+  fiscalYearStart: 4,     // April
+  today: null,            // pinned date for ytd / fytd; null = now
+  missing: 'null',        // a name the row doesn't have: 'null' or 'error'
+  maxListItems: 10000,    // items in one list a total runs over
+  maxDistinct: 1000000,   // distinct values one countifunique may hold
+  maxSteps: 10000000,     // list items visited in one evaluation
+  maxLevels: 2            // totals inside totals
+};
+
+function konst(v) {
+  var f = function () { return v; };
+  f.isConst = true;
+  f.value = v;
+  return f;
+}
+
+function fail(message) { throw new Error(message); }
+
+function compileTree(tree, options) {
+  var opts = Object.assign({}, DEFAULTS, options || {});
+  if (opts.missing !== 'null' && opts.missing !== 'error') fail('missing must be "null" or "error"');
+  var fy = Number(opts.fiscalYearStart);
+  if (!(fy >= 1 && fy <= 12 && Math.floor(fy) === fy)) fail('fiscalYearStart must be a month, 1–12');
+
+  var ctx = { now: dates.todayFor(opts), fiscalYearStart: fy };
+  // Shared by every closure of this formula: how many list items one
+  // evaluation has visited. Reset per top-level call.
+  var state = { steps: 0 };
+
+  function c(node, level) {
+    if (node === null || node === undefined || typeof node !== 'object' || Array.isArray(node)) {
+      fail('Not a formula node: ' + JSON.stringify(node));
+    }
+
+    // 1.x operand with a function: { field, fn } / { value, fn }
+    if (node.fn !== undefined && node.call === undefined) {
+      var bare = Object.assign({}, node);
+      delete bare.fn;
+      return callOf(node.fn, [c(bare, level)]);
+    }
+
+    if (Object.prototype.hasOwnProperty.call(node, 'value')) return konst(node.value);
+    if (node.field !== undefined) return getter(String(node.field).split('.'), false);
+    if (node.path !== undefined) return getter(node.path, false);
+    if (node.thisrow !== undefined) return getter(node.thisrow, true);
+    if (node.list !== undefined) return listOf(node.list.map(function (n) { return c(n, level); }));
+    if (node.if !== undefined) return ifOf(c(node.if, level), c(node.then, level), c(node.else, level));
+    if (node.all !== undefined) return allOf(node.all.map(function (n) { return c(n, level); }));
+    if (node.any !== undefined) return anyOf(node.any.map(function (n) { return c(n, level); }));
+    if (node.not !== undefined) return unary(c(node.not, level), function (a) { return !a; });
+    if (node.neg !== undefined) return unary(c(node.neg, level), function (a) { return -a; });
+    if (node.pos !== undefined) return unary(c(node.pos, level), Number);
+    if (node.call !== undefined) {
+      var entry = functions.lookup(node.call);
+      if (entry && entry.aggregate) return aggregateOf(entry, node.args || [], level);
+      return callOf(node.call, (node.args || []).map(function (n) { return c(n, level); }));
+    }
+    if (node.op !== undefined) return opOf(node, level);
+    fail('Not a formula node: ' + JSON.stringify(node));
+  }
+
+  // ── names ──────────────────────────────────────────────────────────────
+  function getter(segs, fromTop) {
+    if (!Array.isArray(segs) || !segs.length) fail('A path needs at least one name');
+    segs.forEach(function (s) {
+      if (typeof s !== 'string' && typeof s !== 'number') fail('A path is made of names');
+      if (BLOCKED.has(String(s))) fail('"' + s + '" can\'t be used as a column name');
+    });
+    var strict = opts.missing === 'error';
+    var label = segs.join('.');
+
+    // A row's own value only: a function found on it (a name like `toString`
+    // reaching the prototype) reads as nothing. Values are never called.
+    function read(obj, key) {
+      if (obj === null || obj === undefined || typeof obj !== 'object') return null;
+      var v = obj[key];
+      if (v === undefined) {
+        if (strict && !(key in obj)) fail('Unknown column "' + label + '"');
+        return null;
+      }
+      return typeof v === 'function' ? null : v;
+    }
+
+    if (segs.length === 1) {
+      var k = segs[0];
+      return fromTop
+        ? function (row, top) { return read(top, k); }
+        : function (row) { return read(row, k); };
+    }
+    return function (row, top) {
+      var v = fromTop ? top : row;
+      for (var i = 0; i < segs.length; i++) {
+        v = read(v, segs[i]);
+        if (v === null) return null;
+      }
+      return v;
+    };
+  }
+
+  // ── functions ──────────────────────────────────────────────────────────
+  function callOf(name, args) {
+    var entry = functions.lookup(name);
+    if (!entry || entry.special) fail('Unknown function "' + name + '"');
+    if (entry.aggregate) fail(entry.name + '() must be written as a call, not a { fn } operand');
+    if (args.length < entry.min || args.length > entry.max) fail(entry.name + '() takes ' + entry.min + (entry.max === entry.min ? '' : '–' + entry.max) + ' arguments, not ' + args.length);
+    var fn = entry.fn;
+    if (entry.context) {
+      var inner = fn;
+      fn = function () { var a = [ctx]; for (var i = 0; i < arguments.length; i++) a.push(arguments[i]); return inner.apply(null, a); };
+    }
+    if (!entry.volatile && args.every(function (a) { return a.isConst; })) {
+      return konst(fn.apply(null, args.map(function (a) { return a.value; })));
+    }
+    // Fixed shapes for the common arities, so a call allocates no array.
+    var a0 = args[0], a1 = args[1], a2 = args[2];
+    switch (args.length) {
+      case 0: return function () { return fn(); };
+      case 1: return function (r, t) { return fn(a0(r, t)); };
+      case 2: return function (r, t) { return fn(a0(r, t), a1(r, t)); };
+      case 3: return function (r, t) { return fn(a0(r, t), a1(r, t), a2(r, t)); };
+      default: return function (r, t) {
+        var vals = new Array(args.length);
+        for (var i = 0; i < args.length; i++) vals[i] = args[i](r, t);
+        return fn.apply(null, vals);
+      };
+    }
+  }
+
+  // ── operators ──────────────────────────────────────────────────────────
+  var SYMBOLS = {
+    '+': function (a, b) { return Number(a) + Number(b); },
+    '-': function (a, b) { return a - b; },
+    '*': function (a, b) { return a * b; },
+    '/': function (a, b) { return a / b; },
+    '%': function (a, b) { return a % b; },
+    '^': function (a, b) { return Math.pow(a, b); },
+    '||': function (a, b) { return Array.isArray(a) && Array.isArray(b) ? a.concat(b) : '' + a + b; },
+    // Ordering as JavaScript orders (numbers as numbers, ISO dates as text),
+    // except that nothing is never less or greater than anything — as in SQL.
+    // expr-eval read `null < 100` as true, which sends a branch the wrong way.
+    '<': function (a, b) { return a !== null && b !== null && a < b; },
+    '<=': function (a, b) { return a !== null && b !== null && a <= b; },
+    '>': function (a, b) { return a !== null && b !== null && a > b; },
+    '>=': function (a, b) { return a !== null && b !== null && a >= b; },
+    // Membership compares like the 1.x `in` (18 matches "18").
+    'in': function (a, b) {
+      if (!Array.isArray(b)) return false;
+      for (var i = 0; i < b.length; i++) if (operators.looseEq(a, b[i])) return true;
+      return false;
+    }
+  };
+
+  function opOf(node, level) {
+    var sym = SYMBOLS[node.op];
+    if (sym && Object.prototype.hasOwnProperty.call(SYMBOLS, node.op)) {
+      if (node.left === undefined || node.right === undefined) fail('"' + node.op + '" needs a left and a right side');
+      return binary(c(node.left, level), c(node.right, level), sym);
+    }
+    // 1.x word operators: { left, op: 'eq' | 'contains' | 'isNull' | …, right }
+    var def = Object.prototype.hasOwnProperty.call(operators.OPERATORS, node.op) ? operators.OPERATORS[node.op] : null;
+    if (!def) fail('Unknown operator: "' + node.op + '"');
+    if (node.left === undefined) fail('missing left operand');
+    var left = c(node.left, level);
+    if (def.arity === 1) return unary(left, function (a) { return !!def.fn(a); });
+    // As 1.x: a missing right side compares against nothing (validate() flags it).
+    var right = node.right === undefined || node.right === null ? konst(undefined) : c(node.right, level);
+    return binary(left, right, function (a, b) { return !!def.fn(a, b); });
+  }
+
+  function unary(a, f) {
+    if (a.isConst) return konst(f(a.value));
+    return function (r, t) { return f(a(r, t)); };
+  }
+
+  function binary(a, b, f) {
+    if (a.isConst && b.isConst) return konst(f(a.value, b.value));
+    return function (r, t) { return f(a(r, t), b(r, t)); };
+  }
+
+  function listOf(items) {
+    if (items.every(function (i) { return i.isConst; })) return konst(items.map(function (i) { return i.value; }));
+    return function (r, t) { return items.map(function (i) { return i(r, t); }); };
+  }
+
+  function ifOf(cond, yes, no) {
+    if (cond.isConst) return cond.value ? yes : no;
+    return function (r, t) { return cond(r, t) ? yes(r, t) : no(r, t); };
+  }
+
+  function allOf(parts) {
+    return function (r, t) {
+      for (var i = 0; i < parts.length; i++) if (!parts[i](r, t)) return false;
+      return true;
+    };
+  }
+
+  function anyOf(parts) {
+    return function (r, t) {
+      for (var i = 0; i < parts.length; i++) if (parts[i](r, t)) return true;
+      return false;
+    };
+  }
+
+  // ── totals over rows ─────────────────────────────────────────────────────
+  // Two ways to be written:
+  //   sumif(status = "paid", amount)           the rows of a group — the caller
+  //                                            supplies them (options.aggregate)
+  //   sumif(orders, status = "paid", amount)   a list the formula names
+  // A list total is one loop over the list: no filtered copy, no list of
+  // values — a running number, a count, or a set of distinct values.
+  function aggregateOf(entry, args, level) {
+    var implicit = (entry.shape.cond ? 1 : 0) + (entry.shape.value ? 1 : 0);
+    var inner = level + 1;
+    if (inner > opts.maxLevels) fail('A total can hold at most ' + (opts.maxLevels - 1) + ' more total inside it — ' + entry.name + '() is ' + inner + ' levels deep');
+
+    if (args.length === implicit) {
+      if (typeof opts.aggregate !== 'function') {
+        fail(entry.name + '() adds up the rows of a group. Outside a report, name the list first — ' +
+          entry.name + '(orders, ' + (entry.shape.cond ? 'condition' + (entry.shape.value ? ', value' : '') : 'value') + ')');
+      }
+      return opts.aggregate(entry.name, args, { level: inner, compile: function (n) { return c(n, inner); } });
+    }
+    if (args.length !== implicit + 1) fail(entry.name + '() takes ' + implicit + ' or ' + (implicit + 1) + ' arguments, not ' + args.length);
+
+    var list = c(args[0], level);
+    var cond = entry.shape.cond ? c(args[1], inner) : null;
+    var value = entry.shape.value ? c(args[args.length - 1], inner) : null;
+    var label = describeList(args[0]);
+    var maxItems = opts.maxListItems, maxSteps = opts.maxSteps, maxDistinct = opts.maxDistinct;
+
+    function items(r, t) {
+      var arr = list(r, t);
+      if (arr === null || arr === undefined) return null;
+      if (!Array.isArray(arr)) fail(entry.name + '(): ' + label + ' is not a list');
+      if (arr.length > maxItems) fail(label + ' has ' + arr.length + ' items; a total can run over at most ' + maxItems);
+      state.steps += arr.length;
+      if (state.steps > maxSteps) fail('This formula visited more than ' + maxSteps + ' list items in one evaluation');
+      return arr;
+    }
+
+    if (entry.name === 'countif') {
+      return function (r, t) {
+        var arr = items(r, t);
+        if (!arr) return 0;
+        var n = 0;
+        for (var i = 0; i < arr.length; i++) if (cond(arr[i], t)) n++;
+        return n;
+      };
+    }
+    if (entry.name === 'countifunique') {
+      return function (r, t) {
+        var arr = items(r, t);
+        if (!arr) return 0;
+        var seen = new Set();
+        for (var i = 0; i < arr.length; i++) {
+          if (!cond(arr[i], t)) continue;
+          var v = value(arr[i], t);
+          if (v === null || v === undefined) continue;
+          seen.add(v);
+          if (seen.size > maxDistinct) fail(entry.name + '(): more than ' + maxDistinct + ' different values');
+        }
+        return seen.size;
+      };
+    }
+    // sum / sumif — values that aren't numbers add nothing.
+    return function (r, t) {
+      var arr = items(r, t);
+      if (!arr) return 0;
+      var total = 0;
+      for (var i = 0; i < arr.length; i++) {
+        if (cond && !cond(arr[i], t)) continue;
+        var v = value(arr[i], t);
+        if (v === null || v === undefined || v === '') continue;
+        var n = Number(v);
+        if (!isNaN(n)) total += n;
+      }
+      return total;
+    };
+  }
+
+  var run = c(tree, 0);
+  var formula = function (row) {
+    state.steps = 0;
+    return run(row, row);
+  };
+  formula.isConst = !!run.isConst;
+  return formula;
+}
+
+function describeList(node) {
+  if (node.field !== undefined) return String(node.field);
+  if (node.path) return node.path.join('.');
+  return 'the list';
+}
+
+module.exports = { compileTree: compileTree, DEFAULTS: DEFAULTS };

package/lib/dates.js

@@ -0,0 +1,86 @@
+// Date coercion for the date functions — one place, rather than each function
+// guessing. Moved from BI's report-engine (formulaFunctions.js) unchanged in
+// behaviour: BI's saved reports depend on it.
+//
+// Dates arrive as strings, Date objects, or timestamps depending on the
+// driver. A date-only string "2026-05-01" is built from its parts as LOCAL
+// midnight — the spec parses it as UTC midnight, and every reader here
+// (getFullYear, getMonth, …) works in local time, so west of UTC the 1st of a
+// month would read as the last day of the one before. Built from parts, which
+// is also what a database driver does for a DATE column, the browser and the
+// server agree whatever the time zone.
+
+var DATE_ONLY = /^(\d{4})-(\d{2})-(\d{2})$/;
+
+// A streamed report repeats the same date strings row after row; parsing each
+// once is most of the cost of a date function. Bounded so a stream of unique
+// timestamps can't grow it without limit. Callers only READ the Dates.
+var cache = new Map();
+var CACHE_MAX = 512;
+
+function parseDate(v) {
+  var parts = DATE_ONLY.exec(v.trim());
+  if (parts) return new Date(Number(parts[1]), Number(parts[2]) - 1, Number(parts[3]));
+  var d = new Date(v);
+  return isNaN(d.getTime()) ? null : d;
+}
+
+function asDate(v) {
+  if (v === null || v === undefined || v === '') return null;
+  if (v instanceof Date) return isNaN(v.getTime()) ? null : v;
+  if (typeof v === 'string') {
+    var hit = cache.get(v);
+    if (hit !== undefined) return hit;
+    var d = parseDate(v);
+    if (cache.size >= CACHE_MAX) cache.clear();
+    cache.set(v, d);
+    return d;
+  }
+  var t = new Date(v);
+  return isNaN(t.getTime()) ? null : t;
+}
+
+// YYYY-MM-DD in LOCAL time. Not toISOString(), which converts to UTC first —
+// with dates parsed as local midnight that shifts the answer a day.
+function isoLocal(d) {
+  return d.getFullYear() + '-' + String(d.getMonth() + 1).padStart(2, '0') + '-' + String(d.getDate()).padStart(2, '0');
+}
+
+var MONTH_NAMES = ['January', 'February', 'March', 'April', 'May', 'June',
+  'July', 'August', 'September', 'October', 'November', 'December'];
+var WEEKDAYS = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
+var MS_PER_DAY = 86400000;
+
+// "Today" for ytd / fytd, per run context. A pinned `today` is fixed; the live
+// one is recomputed at most once a minute rather than per row — these run
+// inside accumulation loops over millions of rows.
+// Returns now() → { year, end, fyStart }.
+function todayFor(context) {
+  var fyMonth = (context.fiscalYearStart || 4) - 1;
+  if (context.today !== undefined && context.today !== null) {
+    var d = asDate(context.today);
+    if (!d) throw new Error('context.today is not a date: ' + JSON.stringify(context.today));
+    // A pinned day covers all of it, so its own timestamps count as "so far".
+    var pinned = build(new Date(d.getFullYear(), d.getMonth(), d.getDate(), 23, 59, 59, 999), fyMonth);
+    return function () { return pinned; };
+  }
+  var live = null;
+  var at = 0;
+  return function () {
+    var t = Date.now();
+    if (live && t - at < 60000) return live;
+    at = t;
+    live = build(new Date(t), fyMonth);
+    return live;
+  };
+}
+
+function build(end, fyMonth) {
+  var year = end.getFullYear();
+  // The financial year containing today began this calendar year only if we
+  // are already past its start month.
+  var fyStart = new Date(end.getMonth() >= fyMonth ? year : year - 1, fyMonth, 1);
+  return { year: year, end: end, fyStart: fyStart };
+}
+
+module.exports = { asDate: asDate, isoLocal: isoLocal, todayFor: todayFor, MONTH_NAMES: MONTH_NAMES, WEEKDAYS: WEEKDAYS, MS_PER_DAY: MS_PER_DAY };

package/lib/evaluate.js

@@ -1,102 +1,76 @@
-// Evaluate a level-1 structured expression against a data row → boolean.
-//
-// Expression shape:
-//   { left: <operand>, op: <string>, right?: <operand> }
-//
-// Operand shape (one of):
-//   { 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)
-//   { value: [1, 10] }              → literal array (for between / in)
-//
-// Unary operators (isNull / isNotNull) ignore `right`.
-//
-//   evaluate({ left:{fn:'month',field:'createdAt'}, op:'eq', right:{value:'January'} }, row)
+// The 1.x entry points, now running on the 2.0 compiler. Workflow calls
+// evaluate(condition, row) on every arrow, with conditions stored in the 1.x
+// { left, op, right } shape — those keep working, and so does any 2.0 tree.
 
-var { OPERATORS } = require('./operators');
-var { FUNCTIONS, applyFunction } = require('./functions');
+var compileTree = require('./compile').compileTree;
 
-function getPath(obj, path) {
-  if (obj === null || obj === undefined) return undefined;
-  if (path.indexOf('.') === -1) return obj[path];
-  return path.split('.').reduce(function (o, k) {
-    return (o === null || o === undefined) ? undefined : o[k];
-  }, obj);
-}
+// A tree is compiled once and remembered against the object itself, so a
+// stored condition evaluated on every run isn't rebuilt each time.
+var compiled = new WeakMap();
 
-// Resolve an operand to a concrete value against the row.
-function resolveOperand(operand, row) {
-  if (operand === null || operand === undefined) return undefined;
-  var v;
-  if (Object.prototype.hasOwnProperty.call(operand, 'value')) {
-    v = operand.value;
-  } else if (operand.field !== null && operand.field !== undefined) {
-    v = getPath(row, operand.field);
-  } else {
-    throw new Error('Invalid operand: needs "field" or "value"');
-  }
-  if (operand.fn) v = applyFunction(operand.fn, v);
-  return v;
+function compiledFor(expr) {
+  if (!expr || typeof expr !== 'object') throw new Error('expression must be an object');
+  var f = compiled.get(expr);
+  if (!f) { f = compileTree(expr); compiled.set(expr, f); }
+  return f;
 }
 
+/** A condition → true / false. */
 function evaluate(expr, row) {
-  if (!expr || typeof expr !== 'object') throw new Error('expression must be an object');
-  var opDef = OPERATORS[expr.op];
-  if (!opDef) throw new Error('Unknown operator: "' + expr.op + '"');
-
-  var left = resolveOperand(expr.left, row);
-  if (opDef.arity === 1) return !!opDef.fn(left);
-
-  var right = resolveOperand(
-    (expr.right === null || expr.right === undefined) ? { value: undefined } : expr.right,
-    row
-  );
-  return !!opDef.fn(left, right);
+  return !!compiledFor(expr)(row);
 }
 
-// Compile an expression into a reusable row predicate (validated once up front).
-// Drops straight into Array.filter / a streaming .filter(...).
+/** Compile once, filter many — drops into Array.filter or a stream. */
 function toPredicate(expr) {
   var v = validate(expr);
   if (!v.valid) throw new Error('Invalid expression: ' + v.errors.join('; '));
-  return function (row) { return evaluate(expr, row); };
-}
-
-function validateOperand(operand, side, errors) {
-  if (operand === null || operand === undefined || typeof operand !== 'object') {
-    errors.push(side + ' operand must be an object with "field" or "value"');
-    return;
-  }
-  var hasValue = Object.prototype.hasOwnProperty.call(operand, 'value');
-  if (!hasValue && (operand.field === null || operand.field === undefined)) {
-    errors.push(side + ' operand needs "field" or "value"');
-  }
-  if (operand.fn && !FUNCTIONS[operand.fn]) {
-    errors.push('unknown function: "' + operand.fn + '"');
-  }
+  var f = compiledFor(expr);
+  return function (row) { return !!f(row); };
 }
 
-// Static shape check — returns { valid, errors } without touching a row.
+/** Static check without a row → { valid, errors }. */
 function validate(expr) {
   var errors = [];
   if (!expr || typeof expr !== 'object') return { valid: false, errors: ['expression must be an object'] };
-
-  var opDef = OPERATORS[expr.op];
-  if (!opDef) errors.push('unknown operator: "' + expr.op + '"');
-
-  if (expr.left === null || expr.left === undefined) errors.push('missing left operand');
-  else validateOperand(expr.left, 'left', errors);
-
-  if (opDef && opDef.arity === 2) {
-    if (expr.right === null || expr.right === undefined) {
+  // The 1.x shape checks, kept for their messages.
+  if (expr.op !== undefined && expr.left !== undefined) {
+    ['left', 'right'].forEach(function (side) {
+      var o = expr[side];
+      if (o && typeof o === 'object' && !Object.prototype.hasOwnProperty.call(o, 'value') &&
+        o.field === undefined && o.path === undefined && o.thisrow === undefined && o.call === undefined &&
+        o.op === undefined && o.if === undefined && o.all === undefined && o.any === undefined &&
+        o.not === undefined && o.neg === undefined && o.pos === undefined && o.list === undefined) {
+        errors.push(side + ' operand needs "field" or "value"');
+      }
+    });
+    var ops = require('./operators').OPERATORS;
+    var def = Object.prototype.hasOwnProperty.call(ops, expr.op) ? ops[expr.op] : null;
+    if (def && def.arity === 2 && (expr.right === undefined || expr.right === null)) {
       errors.push('operator "' + expr.op + '" requires a right operand');
-    } else {
-      validateOperand(expr.right, 'right', errors);
     }
   }
-
+  if (!errors.length) {
+    try { compileTree(expr); } catch (err) { errors.push(err.message.charAt(0).toLowerCase() + err.message.slice(1)); }
+  }
   return { valid: errors.length === 0, errors: errors };
 }
 
-module.exports = { evaluate, toPredicate, validate, resolveOperand, getPath };
+/** 1.x: one operand's value against a row. */
+function resolveOperand(operand, row) {
+  if (operand === null || operand === undefined) return undefined;
+  if (typeof operand !== 'object' || (!Object.prototype.hasOwnProperty.call(operand, 'value') && operand.field == null && operand.path == null)) {
+    throw new Error('Invalid operand: needs "field" or "value"');
+  }
+  return compiledFor(operand)(row);
+}
+
+/** 1.x: read a dotted path. */
+function getPath(obj, path) {
+  if (obj === null || obj === undefined) return undefined;
+  if (path.indexOf('.') === -1) return obj[path];
+  return path.split('.').reduce(function (o, k) {
+    return (o === null || o === undefined) ? undefined : o[k];
+  }, obj);
+}
+
+module.exports = { evaluate: evaluate, toPredicate: toPredicate, validate: validate, resolveOperand: resolveOperand, getPath: getPath };