@rowsncolumns/fast-formula-parser 6.2.41 → 6.2.44

package/dist/cjs/index.js

@@ -5649,6 +5649,7 @@ const FORMULA_LOCALE_DATA = {
             "ISNUMBER": "ESTNUM",
             "ISO.CEILING": "ISO.PLAFOND",
             "ISODD": "EST.IMPAIR",
+            "ISOMITTED": "ISOMITTED",
             "ISOWEEKNUM": "NO.SEMAINE.ISO",
             "ISPMT": "ISPMT",
             "ISREF": "ESTREF",
@@ -10953,6 +10954,66 @@ const Criteria = Object.freeze({
         return false;
     }
   },
+
+  /**
+   * Excel's array lift for the criteria slot of the criteria aggregates. When
+   * any accepted criterion value is a multi-cell array or range
+   * (`SUMIF(rng,{"x","y"},sum)`, `SUMIFS(sum,rng,"x",rng2,{">1",">3"})`,
+   * `COUNTIF(rng,rng)`), `evaluate` runs once per broadcast element with that
+   * element parsed as a scalar criterion and the results come back as a 2-D
+   * array — so `SUM(COUNTIF(rng,{…}))` / `SUMPRODUCT(SUMIF(…,{…}))` fold it and a
+   * per-element error (`#DIV/0!` from an empty AVERAGEIF slot) stays in its
+   * slot. Vectors broadcast along a unit dimension; a slot a shorter vector
+   * does not reach is `#N/A`. A 1×1 array is a scalar. With no array criterion
+   * `evaluate` runs exactly once with the parsed scalar criteria.
+   * @param {Array} criteriaValues accepted (unparsed) criterion values
+   * @param {(parsed: Array) => *} evaluate
+   */
+  lift: (criteriaValues, evaluate) => {
+    const shapes = criteriaValues.map((v) => {
+      if (!Array.isArray(v)) return null;
+      const shape = [v.length, v[0]?.length ?? 0];
+      return shape[0] === 1 && shape[1] === 1 ? null : shape;
+    });
+    const scalarOf = (v) => (Array.isArray(v) ? v[0][0] : v);
+    if (shapes.every((shape) => shape === null)) {
+      return evaluate(criteriaValues.map((v) => Criteria.parse(scalarOf(v))));
+    }
+    let rows = 1;
+    let cols = 1;
+    for (const shape of shapes) {
+      if (!shape) continue;
+      if (shape[0] !== 1) rows = rows === 1 ? shape[0] : Math.max(rows, shape[0]);
+      if (shape[1] !== 1) cols = cols === 1 ? shape[1] : Math.max(cols, shape[1]);
+    }
+    const MISSING = Symbol("missing");
+    const pick = (v, shape, i, j) => {
+      const r = shape[0] === 1 ? 0 : i;
+      const c = shape[1] === 1 ? 0 : j;
+      return r < v.length && c < v[r].length ? v[r][c] : MISSING;
+    };
+    const out = [];
+    for (let i = 0; i < rows; i++) {
+      const row = [];
+      for (let j = 0; j < cols; j++) {
+        const elements = criteriaValues.map((v, k) =>
+          shapes[k] ? pick(v, shapes[k], i, j) : scalarOf(v),
+        );
+        if (elements.includes(MISSING)) {
+          row.push(FormulaError.NA);
+          continue;
+        }
+        try {
+          row.push(evaluate(elements.map((e) => Criteria.parse(e))));
+        } catch (e) {
+          if (e instanceof FormulaError) row.push(e);
+          else throw e;
+        }
+      }
+      out.push(row);
+    }
+    return out;
+  },
 });
 
 const Address = {
@@ -20678,23 +20739,26 @@ const StatisticalFunctions = {
     range = ranges[0];
     averageRange = ranges[1];
 
-    criteria = Criteria.parse(H$7.accept(H$7.retrieveArg(context, criteria)));
-
-    let sum = 0,
-      cnt = 0;
-    range.forEach((row, rowNum) => {
-      row.forEach((value, colNum) => {
-        const valueToAdd = averageRange[rowNum][colNum];
-        throwIfFormulaError(valueToAdd);
-        if (typeof valueToAdd !== "number") return;
-        if (Criteria.matches(criteria, value)) {
-          sum += valueToAdd;
-          cnt++;
-        }
+    const criteriaValue = H$7.accept(H$7.retrieveArg(context, criteria));
+
+    const averageMatching = (parsed) => {
+      let sum = 0,
+        cnt = 0;
+      range.forEach((row, rowNum) => {
+        row.forEach((value, colNum) => {
+          const valueToAdd = averageRange[rowNum][colNum];
+          throwIfFormulaError(valueToAdd);
+          if (typeof valueToAdd !== "number") return;
+          if (Criteria.matches(parsed, value)) {
+            sum += valueToAdd;
+            cnt++;
+          }
+        });
       });
-    });
-    if (cnt === 0) throw FormulaError.DIV0;
-    return sum / cnt;
+      if (cnt === 0) throw FormulaError.DIV0;
+      return sum / cnt;
+    };
+    return Criteria.lift([criteriaValue], ([parsed]) => averageMatching(parsed));
   },
 
   /**
@@ -20724,36 +20788,42 @@ const StatisticalFunctions = {
       assertSameShape(averageRange, criteriaRange);
       criteriaPairs.push({
         range: criteriaRange,
-        criteria: Criteria.parse(H$7.accept(H$7.retrieveArg(context, args[i + 1]))),
+        criteria: H$7.accept(H$7.retrieveArg(context, args[i + 1])),
       });
     }
 
-    let sum = 0;
-    let count = 0;
+    const averageMatching = (parsedCriteria) => {
+      let sum = 0;
+      let count = 0;
 
-    averageRange.forEach((row, rowNum) => {
-      row.forEach((valueToAdd, colNum) => {
-        throwIfFormulaError(valueToAdd);
-        if (typeof valueToAdd !== "number") {
-          return;
-        }
+      averageRange.forEach((row, rowNum) => {
+        row.forEach((valueToAdd, colNum) => {
+          throwIfFormulaError(valueToAdd);
+          if (typeof valueToAdd !== "number") {
+            return;
+          }
 
-        const meetsAllCriteria = criteriaPairs.every(({ range, criteria }) =>
-          Criteria.matches(criteria, range[rowNum][colNum]),
-        );
+          const meetsAllCriteria = criteriaPairs.every(({ range }, k) =>
+            Criteria.matches(parsedCriteria[k], range[rowNum][colNum]),
+          );
 
-        if (meetsAllCriteria) {
-          sum += valueToAdd;
-          count++;
-        }
+          if (meetsAllCriteria) {
+            sum += valueToAdd;
+            count++;
+          }
+        });
       });
-    });
 
-    if (count === 0) {
-      throw FormulaError.DIV0;
-    }
+      if (count === 0) {
+        throw FormulaError.DIV0;
+      }
 
-    return sum / count;
+      return sum / count;
+    };
+    return Criteria.lift(
+      criteriaPairs.map((pair) => pair.criteria),
+      averageMatching,
+    );
   },
 
   LARGE: (array, kth) => {
@@ -20825,34 +20895,40 @@ const StatisticalFunctions = {
       assertSameShape(maxRange, criteriaRange);
       criteriaPairs.push({
         range: criteriaRange,
-        criteria: Criteria.parse(H$7.accept(H$7.retrieveArg(context, args[i + 1]))),
+        criteria: H$7.accept(H$7.retrieveArg(context, args[i + 1])),
       });
     }
 
-    let max = Number.NEGATIVE_INFINITY;
-    let matchFound = false;
+    const maxMatching = (parsedCriteria) => {
+      let max = Number.NEGATIVE_INFINITY;
+      let matchFound = false;
 
-    maxRange.forEach((row, rowNum) => {
-      row.forEach((valueToAdd, colNum) => {
-        throwIfFormulaError(valueToAdd);
-        if (typeof valueToAdd !== "number") {
-          return;
-        }
+      maxRange.forEach((row, rowNum) => {
+        row.forEach((valueToAdd, colNum) => {
+          throwIfFormulaError(valueToAdd);
+          if (typeof valueToAdd !== "number") {
+            return;
+          }
 
-        const meetsAllCriteria = criteriaPairs.every(({ range, criteria }) =>
-          Criteria.matches(criteria, range[rowNum][colNum]),
-        );
+          const meetsAllCriteria = criteriaPairs.every(({ range }, k) =>
+            Criteria.matches(parsedCriteria[k], range[rowNum][colNum]),
+          );
 
-        if (meetsAllCriteria) {
-          if (valueToAdd > max) {
-            max = valueToAdd;
+          if (meetsAllCriteria) {
+            if (valueToAdd > max) {
+              max = valueToAdd;
+            }
+            matchFound = true;
           }
-          matchFound = true;
-        }
+        });
       });
-    });
 
-    return matchFound ? max : 0;
+      return matchFound ? max : 0;
+    };
+    return Criteria.lift(
+      criteriaPairs.map((pair) => pair.criteria),
+      maxMatching,
+    );
   },
 
   MINA: (...params) => {
@@ -20903,34 +20979,40 @@ const StatisticalFunctions = {
       assertSameShape(minRange, criteriaRange);
       criteriaPairs.push({
         range: criteriaRange,
-        criteria: Criteria.parse(H$7.accept(H$7.retrieveArg(context, args[i + 1]))),
+        criteria: H$7.accept(H$7.retrieveArg(context, args[i + 1])),
       });
     }
 
-    let min = Number.POSITIVE_INFINITY;
-    let matchFound = false;
+    const minMatching = (parsedCriteria) => {
+      let min = Number.POSITIVE_INFINITY;
+      let matchFound = false;
 
-    minRange.forEach((row, rowNum) => {
-      row.forEach((valueToAdd, colNum) => {
-        throwIfFormulaError(valueToAdd);
-        if (typeof valueToAdd !== "number") {
-          return;
-        }
+      minRange.forEach((row, rowNum) => {
+        row.forEach((valueToAdd, colNum) => {
+          throwIfFormulaError(valueToAdd);
+          if (typeof valueToAdd !== "number") {
+            return;
+          }
 
-        const meetsAllCriteria = criteriaPairs.every(({ range, criteria }) =>
-          Criteria.matches(criteria, range[rowNum][colNum]),
-        );
+          const meetsAllCriteria = criteriaPairs.every(({ range }, k) =>
+            Criteria.matches(parsedCriteria[k], range[rowNum][colNum]),
+          );
 
-        if (meetsAllCriteria) {
-          if (valueToAdd < min) {
-            min = valueToAdd;
+          if (meetsAllCriteria) {
+            if (valueToAdd < min) {
+              min = valueToAdd;
+            }
+            matchFound = true;
           }
-          matchFound = true;
-        }
+        });
       });
-    });
 
-    return matchFound ? min : 0;
+      return matchFound ? min : 0;
+    };
+    return Criteria.lift(
+      criteriaPairs.map((pair) => pair.criteria),
+      minMatching,
+    );
   },
 
   NPV: (rate, ...values) => {
@@ -23231,26 +23313,30 @@ const MathFunctions = {
     range = ranges[0];
     sumRange = ranges[1];
 
-    criteria = Criteria.parse(H$6.accept(H$6.retrieveArg(context, criteria)));
-
-    let sum = 0;
-    const rowCount = range.length;
-    for (let r = 0; r < rowCount; r++) {
-      const row = range[r];
-      const sumRow = sumRange[r];
-      const colCount = row.length;
-      for (let c = 0; c < colCount; c++) {
-        const valueToAdd = sumRow[c];
-        if (valueToAdd instanceof FormulaError) {
-          throw valueToAdd;
-        }
-        if (typeof valueToAdd !== "number") continue;
-        if (Criteria.matches(criteria, row[c])) {
-          sum += valueToAdd;
+    const criteriaValue = H$6.accept(H$6.retrieveArg(context, criteria));
+
+    const sumMatching = (parsed) => {
+      let sum = 0;
+      const rowCount = range.length;
+      for (let r = 0; r < rowCount; r++) {
+        const row = range[r];
+        const sumRow = sumRange[r];
+        const colCount = row.length;
+        for (let c = 0; c < colCount; c++) {
+          const valueToAdd = sumRow[c];
+          if (valueToAdd instanceof FormulaError) {
+            throw valueToAdd;
+          }
+          if (typeof valueToAdd !== "number") continue;
+          if (Criteria.matches(parsed, row[c])) {
+            sum += valueToAdd;
+          }
         }
       }
-    }
-    return sum;
+      return sum;
+    };
+    // An array criterion spills one total per element (SUMPRODUCT(SUMIF(rng,{…},sum))).
+    return Criteria.lift([criteriaValue], ([parsed]) => sumMatching(parsed));
   },
 
   /**
@@ -23285,37 +23371,43 @@ const MathFunctions = {
       }
       criteriaPairs.push({
         range: criteriaRange,
-        criteria: Criteria.parse(H$6.accept(H$6.retrieveArg(context, args[i + 1]))),
+        criteria: H$6.accept(H$6.retrieveArg(context, args[i + 1])),
       });
     }
 
-    let sum = 0;
-    const rowCount = sumRange.length;
-    for (let r = 0; r < rowCount; r++) {
-      const row = sumRange[r];
-      const colCount = row.length;
-      for (let c = 0; c < colCount; c++) {
-        const valueToAdd = row[c];
-        if (valueToAdd instanceof FormulaError) {
-          throw valueToAdd;
-        }
-        if (typeof valueToAdd !== "number") {
-          continue;
-        }
-        let allCriteriaMet = true;
-        for (let i = 0; i < criteriaPairs.length; i++) {
-          const { range, criteria } = criteriaPairs[i];
-          if (!Criteria.matches(criteria, range[r][c])) {
-            allCriteriaMet = false;
-            break;
+    const sumMatching = (parsedCriteria) => {
+      let sum = 0;
+      const rowCount = sumRange.length;
+      for (let r = 0; r < rowCount; r++) {
+        const row = sumRange[r];
+        const colCount = row.length;
+        for (let c = 0; c < colCount; c++) {
+          const valueToAdd = row[c];
+          if (valueToAdd instanceof FormulaError) {
+            throw valueToAdd;
+          }
+          if (typeof valueToAdd !== "number") {
+            continue;
+          }
+          let allCriteriaMet = true;
+          for (let i = 0; i < criteriaPairs.length; i++) {
+            if (!Criteria.matches(parsedCriteria[i], criteriaPairs[i].range[r][c])) {
+              allCriteriaMet = false;
+              break;
+            }
+          }
+          if (allCriteriaMet) {
+            sum += valueToAdd;
           }
-        }
-        if (allCriteriaMet) {
-          sum += valueToAdd;
         }
       }
-    }
-    return sum;
+      return sum;
+    };
+    // Array criteria spill one total per broadcast element.
+    return Criteria.lift(
+      criteriaPairs.map((pair) => pair.criteria),
+      sumMatching,
+    );
   },
 
   SUMPRODUCT: (array1, ...arrays) => {
@@ -23908,7 +24000,23 @@ const LogicalFunctions = {
         // never raw `undefined` (misreported as "Function IFNA is not
         // implemented.").
         const blankToZero = (v) => (v === undefined || v === null ? 0 : v);
-        return FormulaError.NA.equals(value.value)
+        const isNa = (cell) => cell instanceof FormulaError && FormulaError.NA.equals(cell);
+
+        // Excel lifts IFNA element-wise over an array / multi-cell range value, like IFERROR:
+        // only the #N/A elements take the fallback, every other value or error passes through
+        // (`IFNA(K1:K3,0)` → {#DIV/0!;0;0}, `SUM(IFNA(rng,0))` sums the non-#N/A cells).
+        const hasValueProp = value && typeof value === 'object' && Object.prototype.hasOwnProperty.call(value, 'value');
+        if (hasValueProp && value.isArray) {
+            const arrayValue = value.value;
+            const handleCell = (cell) => (isNa(cell) ? blankToZero(H$4.accept(valueIfNa)) : blankToZero(cell));
+            if (Array.isArray(arrayValue)) {
+                return arrayValue.map((row) => (Array.isArray(row) ? row.map(handleCell) : handleCell(row)));
+            }
+            return handleCell(arrayValue);
+        }
+
+        const actualValue = hasValueProp ? value.value : value;
+        return isNa(actualValue)
             ? blankToZero(H$4.accept(valueIfNa))
             : blankToZero(H$4.accept(value));
     },
@@ -25587,6 +25695,55 @@ const lookupEquals = (a, b) =>
     ? a.toLowerCase() === b.toLowerCase()
     : a === b;
 
+/**
+ * The sheet range a lookup table argument was read from, or undefined when the table is an
+ * array (an array constant, a spilled range or another function's result). The matrix the
+ * host returned must fit inside that range — it is a window starting at `from` (a full-column
+ * reference is trimmed to the data extent) — or no cell can be derived from a matrix index.
+ */
+const rangeOf = (arg, matrix) => {
+  const ref = arg?.position;
+  if (!ref || ref.isSpilledRange || ref.sheetEnd != null) return undefined;
+  let range;
+  if (ref.from && ref.to) {
+    range = ref;
+  } else if (ref.row != null && ref.col != null) {
+    range = {
+      sheet: ref.sheet,
+      from: { row: ref.row, col: ref.col },
+      to: { row: ref.row, col: ref.col },
+    };
+  } else {
+    return undefined;
+  }
+  const fits =
+    matrix.length <= range.to.row - range.from.row + 1 &&
+    (matrix[0]?.length ?? 0) <= range.to.col - range.from.col + 1;
+  return fits ? range : undefined;
+};
+
+/**
+ * The cell VLOOKUP/HLOOKUP found. Over a sheet range it is the cell's REFERENCE (as INDEX returns
+ * one), so the result carries `=B2` semantics by construction: a blank cell displays 0, is 0 in
+ * arithmetic and comparison, "" in text — `=VLOOKUP(…)+0` is 0, `=VLOOKUP(…)=""` is TRUE,
+ * `=VLOOKUP(…)&"x"` is "x". The engine has no blank scalar to return instead: the dispatcher reads
+ * a returned `undefined` as "function not implemented" (`#NAME?`) and `null` is the skipped-argument
+ * marker. Over an array there is no cell to point at, so a blank slot coerces to 0 as blank does in
+ * arithmetic. A cell holding `=""` is text, not blank, and comes back as "" either way.
+ */
+const matchedCell = (tableRange, tableArray, rowIdx, colIdx) => {
+  if (tableRange) {
+    return {
+      ref: {
+        sheet: tableRange.sheet,
+        row: tableRange.from.row + rowIdx,
+        col: tableRange.from.col + colIdx,
+      },
+    };
+  }
+  return tableArray[rowIdx][colIdx] ?? 0;
+};
+
 /**
  * Exact-mode match for VLOOKUP/HLOOKUP/XLOOKUP/XMATCH: wildcards when the lookup text has
  * them, otherwise case-insensitive equality.
@@ -25853,6 +26010,7 @@ const ReferenceFunctions = {
   HLOOKUP: (lookupValue, tableArray, rowIndexNum, rangeLookup) => {
     // preserve type of lookupValue
     lookupValue = H$2.accept(lookupValue);
+    const tableArg = tableArray;
     try {
       tableArray = H$2.accept(tableArray, Types.ARRAY, undefined, false);
     } catch (e) {
@@ -25864,6 +26022,7 @@ const ReferenceFunctions = {
       }
       throw e;
     }
+    const tableRange = rangeOf(tableArg, tableArray);
     rowIndexNum = H$2.accept(rowIndexNum, Types.NUMBER);
     rangeLookup = H$2.accept(rangeLookup, Types.BOOLEAN, true);
 
@@ -25876,7 +26035,7 @@ const ReferenceFunctions = {
     if (rangeLookup) {
       const index = approximateMatchIndex(tableArray[0], lookupValue);
       if (index === -1) throw FormulaError.NA;
-      return tableArray[rowIndexNum - 1][index];
+      return matchedCell(tableRange, tableArray, rowIndexNum - 1, index);
     }
     // exact lookup: case-insensitive, with wildcard support
     else {
@@ -25885,7 +26044,7 @@ const ReferenceFunctions = {
       );
       // the exact match is not found
       if (index === -1) throw FormulaError.NA;
-      return tableArray[rowIndexNum - 1][index];
+      return matchedCell(tableRange, tableArray, rowIndexNum - 1, index);
     }
   },
 
@@ -26389,6 +26548,7 @@ const ReferenceFunctions = {
   VLOOKUP: (lookupValue, tableArray, colIndexNum, rangeLookup) => {
     // preserve type of lookupValue
     lookupValue = H$2.accept(lookupValue);
+    const tableArg = tableArray;
     try {
       tableArray = H$2.accept(tableArray, Types.ARRAY, undefined, false);
     } catch (e) {
@@ -26400,6 +26560,7 @@ const ReferenceFunctions = {
       }
       throw e;
     }
+    const tableRange = rangeOf(tableArg, tableArray);
     colIndexNum = H$2.accept(colIndexNum, Types.NUMBER);
     rangeLookup = H$2.accept(rangeLookup, Types.BOOLEAN, true);
 
@@ -26415,7 +26576,7 @@ const ReferenceFunctions = {
         lookupValue,
       );
       if (index === -1) throw FormulaError.NA;
-      return tableArray[index][colIndexNum - 1] ?? "";
+      return matchedCell(tableRange, tableArray, index, colIndexNum - 1);
     }
     // exact lookup: case-insensitive, with wildcard support
     else {
@@ -26424,7 +26585,7 @@ const ReferenceFunctions = {
       );
       // the exact match is not found
       if (index === -1) throw FormulaError.NA;
-      return tableArray[index][colIndexNum - 1] ?? "";
+      return matchedCell(tableRange, tableArray, index, colIndexNum - 1);
     }
   },
 
@@ -50565,6 +50726,16 @@ class Parser extends EmbeddedActionsParser {
         ) {
           return arr[0][0];
         }
+        // Excel refuses a ragged constant (`{1,2;3}`) at entry — every row must have the width
+        // of the first. A parse-level `#ERROR!`, like any other syntax error the host stores as
+        // the cell value (rowsncolumns/spreadsheet#939 G-02).
+        const width = arr[0].length;
+        const ragged = arr.findIndex((row) => row.length !== width);
+        if (ragged !== -1) {
+          throw FormulaError.ERROR(
+            `Array constant rows must have the same length: row 1 has ${width} element(s), row ${ragged + 1} has ${arr[ragged].length}`
+          );
+        }
         const array = this.utils.toArray(arr);
         return context.async
           ? this.utils.settleArrayItems(array, $.position)
@@ -52984,8 +53155,13 @@ const normalizeNumberResult = (value, precision, epsilon, excelPrecision) => {
  * @param {*} value
  * @return {boolean}
  */
+// A name's definition text: `=…` (the OOXML `<definedName>` content), or a bare `LAMBDA(…)` —
+// the shape Excel's Name Manager and the host's "Text or Formula" names store a lambda in, which
+// the call path (`Dbl(21)`) already accepts without the leading `=` (spreadsheet#939 G-07).
+const BARE_LAMBDA_TEXT = /^(_xlfn\.)?LAMBDA\s*\(/i;
 const isNamedFormulaText = (value) =>
-  typeof value === "string" && value.trimStart().startsWith("=");
+  typeof value === "string" &&
+  (value.trimStart().startsWith("=") || BARE_LAMBDA_TEXT.test(value.trimStart()));
 
 class FormulaParser {
   /**
@@ -53354,7 +53530,8 @@ class FormulaParser {
     if (this.namedFormulaStack.has(key)) {
       return FormulaError.REF;
     }
-    const source = text.trim().slice(1).trim();
+    const trimmed = text.trim();
+    const source = (trimmed.startsWith("=") ? trimmed.slice(1) : trimmed).trim();
     if (source.length === 0) {
       return FormulaError.NAME;
     }
@@ -53363,12 +53540,18 @@ class FormulaParser {
       this.namedFormulaParser.namedFormulaStack = this.namedFormulaStack;
     }
     this.namedFormulaStack.add(key);
+    // A name bound to a LAMBDA (`Dbl` = `=LAMBDA(x,x*2)`) is the lambda VALUE wherever the
+    // name is read — `MAP(A1:A3,Dbl)`, `LET(f,Dbl,f(3))` — so the definition parser must hand
+    // it back instead of turning it into `#CALC!`; the referencing cell's own
+    // `checkFormulaResult` still makes a bare `=Dbl` `#CALC!` (spreadsheet#939 G-07).
+    this.namedFormulaParser.keepLambdaResult = true;
     try {
       return this.namedFormulaParser.parse(source, this.position, true);
     } catch (e) {
       if (e instanceof FormulaError) return e;
       return FormulaError.NAME;
     } finally {
+      this.namedFormulaParser.keepLambdaResult = false;
       this.namedFormulaStack.delete(key);
     }
   }