@xeplr/expression-handler 2.0.0 → 2.2.0

package/README.md

@@ -171,6 +171,7 @@ const f = xf.compile('sumif(fytd(order_date), revenue)', {
 | `fiscalYearStart` | `4` (April) | `fytd` and any financial-year function |
 | `today` | now | `ytd`, `fytd` — pin it for tests and scheduled runs |
 | `missing` | `'null'` | `'error'` makes a name the row lacks an error |
+| `ignoreCase` | `false` | `true` makes `=`, `!=`, `in`, the text operators (`contains`, `startsWith`, `endsWith`, `notIn`, …) and the functions `contains()`, `startsWith()`, `endsWith()` ignore case. Numbers and null compare exactly as before. BI's report formulas set it, so a formula and the SQL it is translated into agree whatever the database's collation; Workflow's conditions leave it off |
 | `maxListItems` · `maxDistinct` · `maxSteps` · `maxLevels` | see [Limits](#limits) | |
 | `aggregate(name, args, { compile, level })` | none | supplies the rows for the group form of a total (BI) |
 

package/lib/compile.js

@@ -31,7 +31,8 @@ var DEFAULTS = {
   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
+  maxLevels: 2,           // totals inside totals
+  ignoreCase: false       // true: =, !=, in and the text operators ignore case
 };
 
 function konst(v) {
@@ -49,7 +50,10 @@ function compileTree(tree, options) {
   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 };
+  var ctx = { now: dates.todayFor(opts), fiscalYearStart: fy, ignoreCase: Boolean(opts.ignoreCase) };
+  // Equality for `=`, `in` and the word operators: exact, or folded when the
+  // caller asked (opts.ignoreCase) — see operators.IGNORE_CASE.
+  var eq = opts.ignoreCase ? operators.looseEqIgnoreCase : operators.looseEq;
   // Shared by every closure of this formula: how many list items one
   // evaluation has visited. Reset per top-level call.
   var state = { steps: 0 };
@@ -172,7 +176,7 @@ function compileTree(tree, options) {
     // 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;
+      for (var i = 0; i < b.length; i++) if (eq(a, b[i])) return true;
       return false;
     }
   };
@@ -184,7 +188,9 @@ function compileTree(tree, options) {
       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;
+    var def = opts.ignoreCase && Object.prototype.hasOwnProperty.call(operators.IGNORE_CASE, node.op)
+      ? operators.IGNORE_CASE[node.op]
+      : 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);

package/lib/functions.js

@@ -28,6 +28,9 @@ var asDate = dates.asDate;
 
 var CATEGORIES = ['Math', 'Text', 'Date', 'Logic', 'Aggregate'];
 
+// Text for a comparison: lower-cased when the formula ignores case.
+function fold(c, v) { var s = str(v); return c && c.ignoreCase ? s.toLowerCase() : s; }
+
 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 === ''; }
@@ -121,15 +124,17 @@ var LIST = [
   { 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,
+  // context: the compile option ignoreCase folds both sides, as it does for
+  // = and in — one rule for every text comparison in a formula.
+  { name: 'contains', category: 'Text', args: 'text, find', min: 2, max: 2, context: true,
     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,
+    fn: function (c, v, sub) { return fold(c, v).indexOf(fold(c, sub)) !== -1; } },
+  { name: 'startsWith', category: 'Text', args: 'text, find', min: 2, max: 2, context: true,
     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,
+    fn: function (c, v, sub) { return fold(c, v).startsWith(fold(c, sub)); } },
+  { name: 'endsWith', category: 'Text', args: 'text, find', min: 2, max: 2, context: true,
     description: 'True when the text ends with it', example: 'endsWith(file, ".pdf")',
-    fn: function (v, sub) { return str(v).endsWith(str(sub)); } },
+    fn: function (c, v, sub) { return fold(c, v).endsWith(fold(c, 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; } },

package/lib/operators.js

@@ -59,6 +59,28 @@ OPERATORS.equals        = OPERATORS.eq;
 OPERATORS.notEquals     = OPERATORS.neq;
 OPERATORS.doesNotContain = OPERATORS.notContains;
 
+// THE SAME OPERATORS, IGNORING CASE — chosen per formula (compile option
+// `ignoreCase`), never by changing the ones above: Workflow's conditions and
+// every 1.x caller keep exact matching. Only text is folded; numbers and
+// null compare exactly as before.
+function fold(v) { return typeof v === 'string' ? v.toLowerCase() : v; }
+function looseEqIgnoreCase(a, b) { return looseEq(fold(a), fold(b)); }
+function lower(v) { return str(v).toLowerCase(); }
+
+var IGNORE_CASE = {
+  eq:          { arity: 2, fn: function (a, b) { return looseEqIgnoreCase(a, b); } },
+  neq:         { arity: 2, fn: function (a, b) { return !looseEqIgnoreCase(a, b); } },
+  contains:    { arity: 2, fn: function (a, b) { return lower(a).indexOf(lower(b)) !== -1; } },
+  notContains: { arity: 2, fn: function (a, b) { return lower(a).indexOf(lower(b)) === -1; } },
+  startsWith:  { arity: 2, fn: function (a, b) { return lower(a).indexOf(lower(b)) === 0; } },
+  endsWith:    { arity: 2, fn: function (a, b) { var s = lower(a), t = lower(b); return t === '' || s.slice(-t.length) === t; } },
+  in:          { arity: 2, fn: function (a, b) { return Array.isArray(b) && b.some(function (x) { return looseEqIgnoreCase(a, x); }); } },
+  notIn:       { arity: 2, fn: function (a, b) { return !(Array.isArray(b) && b.some(function (x) { return looseEqIgnoreCase(a, x); })); } }
+};
+IGNORE_CASE.equals = IGNORE_CASE.eq;
+IGNORE_CASE.notEquals = IGNORE_CASE.neq;
+IGNORE_CASE.doesNotContain = IGNORE_CASE.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 }');
@@ -66,4 +88,4 @@ function registerOperator(name, def) {
   OPERATORS[name] = def;
 }
 
-module.exports = { OPERATORS, registerOperator, looseEq, num, str, isNil };
+module.exports = { OPERATORS, IGNORE_CASE, registerOperator, looseEq, looseEqIgnoreCase, num, str, isNil };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xeplr/expression-handler",
-  "version": "2.0.0",
+  "version": "2.2.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": [