@xeplr/expression-handler 1.0.1

package/README.md

@@ -0,0 +1,103 @@
+# @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.
+
+## Usage
+
+```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);
+```
+
+## Expression shape
+
+```
+{ left: <operand>, op: <string>, right?: <operand> }
+```
+
+**Operand** — one of:
+
+| Form | Meaning |
+|---|---|
+| `{ 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) |
+
+`right` is omitted for unary operators (`isNull`, `isNotNull`).
+
+## Operators
+
+`eq` `neq` `isNull` `isNotNull` · `gt` `gte` `lt` `lte` `between` (`[lo,hi]`, inclusive) ·
+`contains` `notContains` `startsWith` `endsWith` · `in` `notIn`
+Aliases: `equals`, `notEquals`, `doesNotContain`.
+
+`eq`/`neq` against `{ value: null }` also work as null checks. Null-ish values make
+numeric/string comparisons return `false` (never throw).
+
+## Functions
+
+String: `upper` `lower` `trim` `length` · Date (UTC): `month` (`'January'`) `monthNum`
+`year` `day` `quarter` `weekday` (`'Monday'`).
+
+## Extending
+
+```js
+xf.registerFunction('reverse', v => String(v).split('').reverse().join(''));
+xf.registerOperator('regex', (a, b) => new RegExp(b).test(String(a)));
+```
+
+## Formula wrapper (Excel-like)
+
+Write formulas as strings; they compile to the same structured JSON.
+
+```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' } }
+
+const f = xf.formula.compile('if(score>=90,"A",if(score>=80,"B","C"))');   // nested ifs
+f({ score: 85 });   // → 'B'
+```
+
+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.
+
+`xf.formula.parse(str)` · `xf.formula.compile(str) → (row)=>value` · `xf.formula.evaluate(node, row)`
+
+## NLP wrapper (stub)
+
+`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.
+
+## API
+
+`evaluate(expr, row)` · `toPredicate(expr)` · `validate(expr) → { valid, errors }` ·
+`formula.{parse,compile,evaluate}` · `nlp` (stub) ·
+`registerFunction` · `registerOperator` · `operators()` · `functions()`
+
+Test: `npm test` (node --test, no DB). 29 tests.

package/index.js

@@ -0,0 +1,50 @@
+// @xeplr/expression-handler — level-1 structured expression evaluator.
+//
+//   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 isAdult = xf.toPredicate({ left: { field: 'age' }, op: 'gte', right: { value: 18 } });
+//   rows.filter(isAdult);
+//
+// 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');
+var nlp = require('./lib/nlp');
+
+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
+  formula: {
+    parse: parseFormula,
+    evaluate: evaluateFormula,
+    compile: compileFormula
+  },
+
+  // Natural-language wrapper — STUB (not implemented yet).
+  nlp: nlp,
+
+  registerOperator: registerOperator,
+  registerFunction: registerFunction,
+
+  // Introspection — the registered operator/function names.
+  OPERATORS: OPERATORS,
+  FUNCTIONS: FUNCTIONS,
+  operators: function () { return Object.keys(OPERATORS); },
+  functions: function () { return Object.keys(FUNCTIONS); }
+};

package/lib/evaluate.js

@@ -0,0 +1,102 @@
+// 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)
+
+var { OPERATORS } = require('./operators');
+var { FUNCTIONS, applyFunction } = require('./functions');
+
+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);
+}
+
+// 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 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);
+}
+
+// Compile an expression into a reusable row predicate (validated once up front).
+// Drops straight into Array.filter / a streaming .filter(...).
+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 + '"');
+  }
+}
+
+// Static shape check — returns { valid, errors } without touching a row.
+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) {
+      errors.push('operator "' + expr.op + '" requires a right operand');
+    } else {
+      validateOperand(expr.right, 'right', errors);
+    }
+  }
+
+  return { valid: errors.length === 0, errors: errors };
+}
+
+module.exports = { evaluate, toPredicate, validate, resolveOperand, getPath };

package/lib/formula.js

@@ -0,0 +1,196 @@
+// 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 };

package/lib/functions.js

@@ -0,0 +1,50 @@
+// Field functions — applied to an operand's resolved value before the operator
+// runs. Level 1: a function takes one value and returns one value.
+//
+// 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'
+];
+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;
+}
+
+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;
+}
+
+function applyFunction(name, value) {
+  var fn = FUNCTIONS[name];
+  if (!fn) throw new Error('Unknown function: "' + name + '"');
+  return fn(value);
+}
+
+module.exports = { FUNCTIONS, registerFunction, applyFunction };

package/lib/nlp.js

@@ -0,0 +1,16 @@
+// NLP wrapper — STUB. Future: turn a natural-language phrase into the same
+// structured expression/formula JSON the evaluator consumes, e.g.
+//   "rows where the created month is January"
+//     → { left: { fn:'month', field:'created' }, op:'eq', right:{ value:'January' } }
+//
+// Intentionally not implemented yet. Shipped as a stub so the surface exists
+// 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.');
+}
+
+module.exports = {
+  parse: parse,
+  implemented: false
+};

package/lib/operators.js

@@ -0,0 +1,69 @@
+// Operators — each is a small handler with a fixed arity:
+//   arity 2 → fn(left, right)   (eq, gt, contains, between, …)
+//   arity 1 → fn(left)          (isNull, isNotNull)
+//
+// Semantics chosen for filter/rules use, documented per operator:
+//   • null-ish (null/undefined) on a numeric/string comparison → false
+//     (except isNull/isNotNull, and eq/neq which treat null explicitly).
+//   • numeric operators coerce via Number(); non-numeric → NaN → false.
+//   • string operators coerce via String().
+
+function isNil(v) { return v === null || v === undefined; }
+function num(v) { return typeof v === 'number' ? v : Number(v); }
+function str(v) { return isNil(v) ? '' : String(v); }
+
+// Equality that treats null explicitly and compares numbers as numbers,
+// everything else as strings (so 18 == '18', 'January' == 'January').
+function looseEq(a, b) {
+  if (isNil(a) && isNil(b)) return true;
+  if (isNil(a) || isNil(b)) return false;
+  if (typeof a === 'number' && typeof b === 'number') return a === b;
+  return String(a) === String(b);
+}
+
+var OPERATORS = {
+  // equality / null — eq/neq against a null value ALSO work as is-null checks
+  eq:        { arity: 2, fn: function (a, b) { return looseEq(a, b); } },
+  neq:       { arity: 2, fn: function (a, b) { return !looseEq(a, b); } },
+  isNull:    { arity: 1, fn: function (a) { return isNil(a); } },
+  isNotNull: { arity: 1, fn: function (a) { return !isNil(a); } },
+
+  // numeric
+  gt:  { arity: 2, fn: function (a, b) { return num(a) > num(b); } },
+  gte: { arity: 2, fn: function (a, b) { return num(a) >= num(b); } },
+  lt:  { arity: 2, fn: function (a, b) { return num(a) < num(b); } },
+  lte: { arity: 2, fn: function (a, b) { return num(a) <= num(b); } },
+  between: {
+    arity: 2,
+    // right operand is a [lo, hi] pair; inclusive.
+    fn: function (a, b) {
+      if (!Array.isArray(b) || b.length < 2) return false;
+      var x = num(a), lo = num(b[0]), hi = num(b[1]);
+      return x >= lo && x <= hi;
+    }
+  },
+
+  // string
+  contains:    { arity: 2, fn: function (a, b) { return str(a).indexOf(str(b)) !== -1; } },
+  notContains: { arity: 2, fn: function (a, b) { return str(a).indexOf(str(b)) === -1; } },
+  startsWith:  { arity: 2, fn: function (a, b) { return str(a).indexOf(str(b)) === 0; } },
+  endsWith:    { arity: 2, fn: function (a, b) { var s = str(a), t = str(b); return t === '' || s.slice(-t.length) === t; } },
+
+  // set membership — right operand is an array
+  in:    { arity: 2, fn: function (a, b) { return Array.isArray(b) && b.some(function (x) { return looseEq(a, x); }); } },
+  notIn: { arity: 2, fn: function (a, b) { return !(Array.isArray(b) && b.some(function (x) { return looseEq(a, x); })); } }
+};
+
+// Friendly aliases for the phrasings a UI/user might send.
+OPERATORS.equals        = OPERATORS.eq;
+OPERATORS.notEquals     = OPERATORS.neq;
+OPERATORS.doesNotContain = OPERATORS.notContains;
+
+function registerOperator(name, def) {
+  if (typeof def === 'function') def = { arity: 2, fn: def };
+  if (!def || typeof def.fn !== 'function') throw new Error('registerOperator: needs a function or { arity, fn }');
+  if (def.arity !== 1 && def.arity !== 2) def.arity = 2;
+  OPERATORS[name] = def;
+}
+
+module.exports = { OPERATORS, registerOperator, looseEq, num, str, isNil };

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@xeplr/expression-handler",
+  "version": "1.0.1",
+  "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.",
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "lib/"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "keywords": [
+    "expression",
+    "formula",
+    "filter",
+    "predicate",
+    "rules",
+    "evaluator",
+    "xeplr"
+  ],
+  "author": "xeplr",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Xeplr/xeplr-expression-handler"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}