@rowsncolumns/fast-formula-parser 6.2.42 → 6.2.45

package/dist/esm/index.js

@@ -5645,6 +5645,7 @@ const FORMULA_LOCALE_DATA = {
             "ISNUMBER": "ESTNUM",
             "ISO.CEILING": "ISO.PLAFOND",
             "ISODD": "EST.IMPAIR",
+            "ISOMITTED": "ISOMITTED",
             "ISOWEEKNUM": "NO.SEMAINE.ISO",
             "ISPMT": "ISPMT",
             "ISREF": "ESTREF",
@@ -25690,6 +25691,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.
@@ -25956,6 +26006,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) {
@@ -25967,6 +26018,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);
 
@@ -25979,7 +26031,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 {
@@ -25988,7 +26040,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);
     }
   },
 
@@ -26492,6 +26544,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) {
@@ -26503,6 +26556,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);
 
@@ -26518,7 +26572,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 {
@@ -26527,7 +26581,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);
     }
   },
 
@@ -53173,6 +53227,11 @@ class FormulaParser {
     );
     this.onRange = config.onRange;
     this.onCell = config.onCell;
+    // Observer of every cell / range the evaluation actually reads, with the
+    // cell being evaluated. `INDIRECT` / `OFFSET` targets only exist at run
+    // time, so this is how a host learns the dynamic precedents of a formula
+    // (the dependency parser cannot see them).
+    this.onReferenceResolved = config.onReferenceResolved;
     // Optional host callback reporting row visibility for SUBTOTAL:
     // ({sheet, row}) => {hiddenByFilter?: boolean, hiddenByUser?: boolean}
     this.onRowHidden = config.onRowHidden;
@@ -53322,18 +53381,36 @@ class FormulaParser {
         const bounds = this.onSpilledRange(ref);
         if (bounds instanceof FormulaError) return bounds;
         if (bounds && bounds.from && bounds.to) {
-          return this.onRange({
+          const spilled = {
             from: bounds.from,
             to: bounds.to,
             sheet: bounds.sheet ?? ref.sheet,
-          });
+          };
+          this.noteReferenceResolved("range", spilled, finalPosition);
+          return this.onRange(spilled);
         }
       }
       return FormulaError.REF;
     }
+    this.noteReferenceResolved("cell", ref, finalPosition);
     return this.onCell(ref);
   }
 
+  /**
+   * Tell the host which reference an evaluation is about to read.
+   * @param {"cell"|"range"} kind
+   * @param ref - the resolved reference (sheet already defaulted)
+   * @param position - the cell being evaluated, when known
+   */
+  noteReferenceResolved(kind, ref, position) {
+    if (typeof this.onReferenceResolved !== "function") return;
+    try {
+      this.onReferenceResolved({ kind, ref, position });
+    } catch {
+      // An observer must never break the evaluation.
+    }
+  }
+
   /**
    * Get values from the range reference.
    * @param ref
@@ -53348,6 +53425,7 @@ class FormulaParser {
     if (ref.sheetEnd != null) {
       return this.get3DRange(ref, true);
     }
+    this.noteReferenceResolved("range", ref, finalPosition);
     return this.onRange(ref);
   }
 
@@ -53384,6 +53462,11 @@ class FormulaParser {
     for (const sheet of sheets) {
       const { sheetEnd: _ignored, ...perSheet } = ref;
       perSheet.sheet = sheet;
+      this.noteReferenceResolved(
+        isRange ? "range" : "cell",
+        perSheet,
+        this.position,
+      );
       const value = isRange ? this.onRange(perSheet) : this.onCell(perSheet);
       if (value instanceof FormulaError) return value;
       if (Array.isArray(value)) {