@cj-tech-master/excelts 9.3.1 → 9.4.0

package/dist/esm/modules/formula/compile/binder.js

@@ -105,6 +105,8 @@ export function bind(node, ctx) {
             return bindName(node.name, ctx);
         case NodeType.StructuredRef:
             return bindStructuredRef(node.tableName, node.columns, node.specials, ctx);
+        case NodeType.UnionRef:
+            return bindUnionRef(node, ctx);
         default:
             return assertNever(node);
     }
@@ -160,6 +162,11 @@ function bindRangeRef(node, ctx) {
     const bottom = Math.max(startRow, endRow);
     const left = Math.min(startCol, endCol);
     const right = Math.max(startCol, endCol);
+    // Bounds-check the rectangle against Excel's sheet limits. Defined-name
+    // strings that bypass the tokenizer can carry arbitrary addresses.
+    if (top < 1 || bottom > 1048576 || left < 1 || right > 16384) {
+        return boundErrorLiteral("#REF!");
+    }
     // 3D range reference: Sheet1:Sheet3!A1:B2
     if (node.endSheet) {
         const sheets = getSheetsInRange(ctx.snapshot, sheet, node.endSheet);
@@ -173,6 +180,13 @@ function bindRangeRef(node, ctx) {
             inner
         };
     }
+    // Validate sheet exists — matches the parity check `bindCellRef` and
+    // `bindColRangeRef` / `bindRowRangeRef` perform. Without this, a range
+    // like `NoSuchSheet!A1:B2` would silently bind to an empty-read at
+    // runtime instead of surfacing as `#REF!` at compile time.
+    if (!ctx.snapshot.worksheetsByName.has(sheet.toLowerCase())) {
+        return boundErrorLiteral("#REF!");
+    }
     return boundAreaRef(sheet, top, left, bottom, right);
 }
 function bindColRangeRef(node, ctx) {
@@ -181,6 +195,12 @@ function bindColRangeRef(node, ctx) {
     const endCol = colLetterToNumber(node.endCol);
     const leftCol = Math.min(startCol, endCol);
     const rightCol = Math.max(startCol, endCol);
+    // Excel's maximum column is 16384 (XFD). The tokenizer enforces this
+    // for plain refs, but defined-name range strings that bypass the
+    // tokenizer could carry larger letter sequences (e.g. `ZZZ`).
+    if (leftCol < 1 || rightCol > 16384) {
+        return boundErrorLiteral("#REF!");
+    }
     // Validate sheet exists
     if (!ctx.snapshot.worksheetsByName.has(sheet.toLowerCase())) {
         return boundErrorLiteral("#REF!");
@@ -210,6 +230,11 @@ function bindRowRangeRef(node, ctx) {
     const sheet = node.sheet ?? ctx.currentSheet;
     const topRow = Math.min(node.startRow, node.endRow);
     const bottomRow = Math.max(node.startRow, node.endRow);
+    // Excel's maximum row is 1048576. Re-check here because defined-name
+    // strings can bypass the tokenizer.
+    if (topRow < 1 || bottomRow > 1048576) {
+        return boundErrorLiteral("#REF!");
+    }
     // Validate sheet exists
     if (!ctx.snapshot.worksheetsByName.has(sheet.toLowerCase())) {
         return boundErrorLiteral("#REF!");
@@ -235,6 +260,24 @@ function bindRowRangeRef(node, ctx) {
     };
 }
 // ============================================================================
+// Union Reference Binding — `(A1:B2, D4:E5)`
+// ============================================================================
+function bindUnionRef(node, ctx) {
+    // Each area must bind to a reference-producing expression. If any
+    // member is a non-reference literal, the whole union collapses to
+    // `#REF!` — Excel rejects things like `(1, A1)` outright. We defer
+    // the runtime-reference check (INDIRECT/OFFSET) to the evaluator.
+    const bounds = [];
+    for (const area of node.areas) {
+        const bound = bind(area, ctx);
+        bounds.push(bound);
+    }
+    return {
+        kind: BoundExprKind.UnionRef,
+        areas: bounds
+    };
+}
+// ============================================================================
 // Name Binding
 // ============================================================================
 function bindName(name, ctx) {
@@ -324,12 +367,11 @@ function findTable(snapshot, tableName) {
     if (!tableName) {
         return null;
     }
-    // Use the pre-built tablesByName index for O(1) lookup
-    const resolved = snapshot.tablesByName.get(tableName.toLowerCase());
-    if (resolved) {
-        return { table: resolved.table, sheetName: resolved.sheetName };
-    }
-    return null;
+    // Use the pre-built tablesByName index for O(1) lookup. The snapshot's
+    // `ResolvedTable` already matches our `TableWithSheet` shape (same
+    // `{ table, sheetName }` pair), so we can return it directly instead
+    // of wrapping every hit in a fresh object.
+    return snapshot.tablesByName.get(tableName.toLowerCase()) ?? null;
 }
 function resolveStructuredRefBounds(tw, columns, specials) {
     const t = tw.table;

package/dist/esm/modules/formula/compile/bound-ast.js

@@ -51,6 +51,7 @@ export var BoundExprKind;
     BoundExprKind[BoundExprKind["NameExpr"] = 13] = "NameExpr";
     BoundExprKind[BoundExprKind["Lambda"] = 14] = "Lambda";
     BoundExprKind[BoundExprKind["StructuredRef"] = 15] = "StructuredRef";
+    BoundExprKind[BoundExprKind["UnionRef"] = 16] = "UnionRef";
 })(BoundExprKind || (BoundExprKind = {}));
 // ============================================================================
 // Constructor Helpers

package/dist/esm/modules/formula/compile/compiled-formula.js

@@ -209,6 +209,13 @@ function walkDeps(expr, cells, areas, tablesByName, nameResolver, visitedNames)
                 }
             }
             break;
+        case BoundExprKind.UnionRef:
+            // Each member of a `(a1, a2, ...)` union contributes its own
+            // dependencies — downstream reads target cells in every area.
+            for (const area of expr.areas) {
+                walkDeps(area, cells, areas, tablesByName, nameResolver, visitedNames);
+            }
+            break;
     }
 }
 // ============================================================================
@@ -275,9 +282,15 @@ export function detectDynamicArrayFunction(ast, bound) {
             return true;
         }
     }
-    // Check bound expression level
-    if (bound.kind === BoundExprKind.Call && DYNAMIC_ARRAY_FUNCTION_NAMES.has(bound.name)) {
-        return true;
+    // Check bound expression level. Strip `_XLFN.` prefix here too —
+    // `boundCall` preserves the prefix on the bound name, so without the
+    // strip a synthesised bound call (e.g. from INDIRECT re-parse) would
+    // miss detection.
+    if (bound.kind === BoundExprKind.Call) {
+        const canonical = stripFunctionPrefix(bound.name);
+        if (DYNAMIC_ARRAY_FUNCTION_NAMES.has(canonical)) {
+            return true;
+        }
     }
     return false;
 }
@@ -298,9 +311,15 @@ export function detectSubtotalOutput(ast, bound) {
             return true;
         }
     }
-    if (bound.kind === BoundExprKind.Call &&
-        (bound.name === "SUBTOTAL" || bound.name === "AGGREGATE")) {
-        return true;
+    if (bound.kind === BoundExprKind.Call) {
+        // Strip `_XLFN.` / `_XLFN._XLWS.` prefixes before matching — otherwise
+        // `_XLFN.AGGREGATE(...)` silently wouldn't be marked as a subtotal
+        // output, so an outer SUBTOTAL / AGGREGATE over its cell would
+        // double-count the aggregated value.
+        const canonical = stripFunctionPrefix(bound.name);
+        if (canonical === "SUBTOTAL" || canonical === "AGGREGATE") {
+            return true;
+        }
     }
     return false;
 }
@@ -319,15 +338,24 @@ export function analyzeExpr(expr, nameResolver) {
     return { isVolatile, hasDynamicRefs, containsLambda };
     function walkAnalyze(e) {
         switch (e.kind) {
-            case BoundExprKind.Call:
-                if (VOLATILE_FUNCTIONS.has(e.name)) {
+            case BoundExprKind.Call: {
+                // `boundCall` stores the function name uppercased but preserves
+                // any `_XLFN.` / `_XLFN._XLWS.` prefix the source text contained.
+                // Strip the prefix before VOLATILE_FUNCTIONS lookup so e.g.
+                // `_XLFN.RANDARRAY()` (an XLFN-prefixed volatile) correctly
+                // invalidates the session cache across calc cycles.
+                const canonical = stripFunctionPrefix(e.name);
+                if (VOLATILE_FUNCTIONS.has(canonical)) {
                     isVolatile = true;
                 }
                 for (const arg of e.args) {
                     walkAnalyze(arg);
                 }
                 break;
+            }
             case BoundExprKind.SpecialCall:
+                // Special-call names are already stripped of any `_XLFN.` prefix
+                // by `canonicalSpecialForm` in the binder, so no re-strip here.
                 if (DYNAMIC_REF_FUNCTIONS.has(e.name)) {
                     hasDynamicRefs = true;
                 }
@@ -375,6 +403,11 @@ export function analyzeExpr(expr, nameResolver) {
                     }
                 }
                 break;
+            case BoundExprKind.UnionRef:
+                for (const area of e.areas) {
+                    walkAnalyze(area);
+                }
+                break;
             default:
                 // Literal, CellRef, AreaRef, etc. — no children to analyze
                 break;

package/dist/esm/modules/formula/functions/_shared.js

@@ -76,6 +76,53 @@ export function flattenNumbers(args) {
     }
     return result;
 }
+/**
+ * Streaming fold over numeric arguments.
+ *
+ * Same selection rules as `flattenNumbers` (array cells contribute only
+ * Number/Error; direct scalar coercion via `toNumberRV`; blanks dropped),
+ * but the caller's `onNumber` callback fires inline — no intermediate
+ * array is allocated. On the first error encountered the scan short-
+ * circuits and returns that error.
+ *
+ * Returns:
+ *   - `null` when iteration finished without encountering an error, or
+ *   - the `ErrorValue` that aborted the scan.
+ *
+ * Prefer this over `flattenNumbers` + `firstError` + manual loop in hot
+ * aggregates (SUM / AVERAGE / MIN / MAX / …). The allocation saved is
+ * one `NumberValue | ErrorValue` array per invocation — meaningful
+ * when the engine sums tens of thousands of cells.
+ */
+export function forEachNumber(args, onNumber) {
+    for (const arg of args) {
+        if (arg.kind === RVKind.Array) {
+            for (const row of arg.rows) {
+                for (const cell of row) {
+                    if (cell.kind === RVKind.Error) {
+                        return cell;
+                    }
+                    if (cell.kind === RVKind.Number) {
+                        onNumber(cell.value);
+                    }
+                    // Booleans, strings, blanks inside arrays are skipped.
+                }
+            }
+        }
+        else if (arg.kind === RVKind.Error) {
+            return arg;
+        }
+        else if (arg.kind !== RVKind.Blank) {
+            const n = toNumberRV(arg);
+            if (n.kind === RVKind.Error) {
+                return n;
+            }
+            onNumber(n.value);
+        }
+        // Direct blank scalars are dropped.
+    }
+    return null;
+}
 /**
  * Flatten all cells from the arguments into a flat list of ScalarValue,
  * preserving every cell (including blanks, errors, booleans, strings).

package/dist/esm/modules/formula/functions/conditional.js

@@ -47,35 +47,57 @@ export function buildCriteriaPredicateRV(criteria) {
         // blank (→0); numeric strings are NOT coerced (COUNTIF stays textual
         // for those). Only real Number / Boolean / Blank cells participate in
         // numeric comparisons; everything else falls back to string compare.
-        const numericOf = (v) => {
-            if (v.kind === RVKind.Number) {
-                return v.value;
-            }
-            if (v.kind === RVKind.Boolean) {
-                return v.value ? 1 : 0;
-            }
-            if (v.kind === RVKind.Blank) {
-                return 0;
-            }
-            return Number.NaN;
-        };
+        if (isNum) {
+            // Specialised numeric-comparison path — avoids per-cell string
+            // coercion allocations that dominate the hot loop otherwise.
+            // Non-numeric cells produce NaN and fall through to the switch,
+            // where only `<>` evaluates NaN-relations to TRUE (Excel semantics).
+            return (v) => {
+                const vn = v.kind === RVKind.Number
+                    ? v.value
+                    : v.kind === RVKind.Boolean
+                        ? v.value
+                            ? 1
+                            : 0
+                        : v.kind === RVKind.Blank
+                            ? 0
+                            : Number.NaN;
+                switch (op) {
+                    case "=":
+                        return vn === numVal;
+                    case "<>":
+                        return vn !== numVal;
+                    case ">":
+                        return vn > numVal;
+                    case "<":
+                        return vn < numVal;
+                    case ">=":
+                        return vn >= numVal;
+                    case "<=":
+                        return vn <= numVal;
+                    default:
+                        return false;
+                }
+            };
+        }
+        // String-comparison path — lowercase the criterion once outside the
+        // closure so every cell only pays a single `toStringRV().toLowerCase()`.
+        const cs = valStr.toLowerCase();
         return (v) => {
-            const vn = numericOf(v);
             const vs = toStringRV(v).toLowerCase();
-            const cs = valStr.toLowerCase();
             switch (op) {
                 case "=":
-                    return isNum ? vn === numVal : vs === cs;
+                    return vs === cs;
                 case "<>":
-                    return isNum ? vn !== numVal : vs !== cs;
+                    return vs !== cs;
                 case ">":
-                    return isNum ? vn > numVal : vs > cs;
+                    return vs > cs;
                 case "<":
-                    return isNum ? vn < numVal : vs < cs;
+                    return vs < cs;
                 case ">=":
-                    return isNum ? vn >= numVal : vs >= cs;
+                    return vs >= cs;
                 case "<=":
-                    return isNum ? vn <= numVal : vs <= cs;
+                    return vs <= cs;
                 default:
                     return false;
             }
@@ -85,14 +107,19 @@ export function buildCriteriaPredicateRV(criteria) {
     // literal `*`, `?`, `~` and everything else as a regex special character
     // that must be escaped. Only an unescaped `*` or `?` triggers the wildcard
     // path; a pattern like `~*` matches a literal asterisk.
+    //
+    // Excel restricts wildcard matching to TEXT cells — a criterion like
+    // `"1*"` must not match the number 1 even though `String(1) === "1"`.
+    // Without this guard, `COUNTIF({1, 15, "15"}, "1*")` would return 3
+    // instead of the correct `1` (only the string `"15"` matches).
     if (hasUnescapedWildcard(s)) {
         try {
             const re = new RegExp("^" + excelWildcardToRegex(s) + "$", "i");
-            return v => re.test(toStringRV(v));
+            return v => v.kind === RVKind.String && re.test(v.value);
         }
         catch {
             const literal = unescapeExcelWildcard(s).toLowerCase();
-            return v => toStringRV(v).toLowerCase() === literal;
+            return v => v.kind === RVKind.String && v.value.toLowerCase() === literal;
         }
     }
     // No wildcards: strip any `~` escapes and do a literal case-insensitive compare.
@@ -133,6 +160,12 @@ export function fnSUMIF(args) {
         for (let c = 0; c < rangeArr.width; c++) {
             if (pred(getCell(rangeArr, r, c))) {
                 const sv = getCell(sumArr, r, c);
+                // Excel propagates errors from the sum-range; previously we
+                // silently skipped them, masking `#DIV/0!` / `#VALUE!` cells
+                // under the aggregation.
+                if (sv.kind === RVKind.Error) {
+                    return sv;
+                }
                 if (sv.kind === RVKind.Number) {
                     sum += sv.value;
                 }
@@ -205,12 +238,23 @@ export function fnSUMIFS(args) {
         return pairs.error;
     }
     let sum = 0;
+    let sumErr = null;
     iterateMultiCriteria(sumArr, pairs.pairs, (r, c) => {
+        if (sumErr) {
+            return;
+        }
         const sv = getCell(sumArr, r, c);
+        if (sv.kind === RVKind.Error) {
+            sumErr = sv;
+            return;
+        }
         if (sv.kind === RVKind.Number) {
             sum += sv.value;
         }
     });
+    if (sumErr) {
+        return sumErr;
+    }
     return rvNumber(sum);
 }
 export function fnCOUNTIF(args) {
@@ -268,6 +312,10 @@ export function fnAVERAGEIF(args) {
         for (let c = 0; c < rangeArr.width; c++) {
             if (pred(getCell(rangeArr, r, c))) {
                 const sv = getCell(avgArr, r, c);
+                // Propagate errors from the average-range — see SUMIF for rationale.
+                if (sv.kind === RVKind.Error) {
+                    return sv;
+                }
                 if (sv.kind === RVKind.Number) {
                     sum += sv.value;
                     count++;
@@ -288,13 +336,24 @@ export function fnAVERAGEIFS(args) {
     }
     let sum = 0;
     let count = 0;
+    let avgErr = null;
     iterateMultiCriteria(avgArr, pairs.pairs, (r, c) => {
+        if (avgErr) {
+            return;
+        }
         const sv = getCell(avgArr, r, c);
+        if (sv.kind === RVKind.Error) {
+            avgErr = sv;
+            return;
+        }
         if (sv.kind === RVKind.Number) {
             sum += sv.value;
             count++;
         }
     });
+    if (avgErr) {
+        return avgErr;
+    }
     return count === 0 ? ERRORS.DIV0 : rvNumber(sum / count);
 }
 export function fnMAXIFS(args) {
@@ -308,8 +367,16 @@ export function fnMAXIFS(args) {
     }
     let result = -Infinity;
     let found = false;
+    let maxErr = null;
     iterateMultiCriteria(maxArr, pairs.pairs, (r, c) => {
+        if (maxErr) {
+            return;
+        }
         const sv = getCell(maxArr, r, c);
+        if (sv.kind === RVKind.Error) {
+            maxErr = sv;
+            return;
+        }
         if (sv.kind === RVKind.Number) {
             if (sv.value > result) {
                 result = sv.value;
@@ -317,6 +384,9 @@ export function fnMAXIFS(args) {
             found = true;
         }
     });
+    if (maxErr) {
+        return maxErr;
+    }
     return rvNumber(found ? result : 0);
 }
 export function fnMINIFS(args) {
@@ -330,8 +400,16 @@ export function fnMINIFS(args) {
     }
     let result = Infinity;
     let found = false;
+    let minErr = null;
     iterateMultiCriteria(minArr, pairs.pairs, (r, c) => {
+        if (minErr) {
+            return;
+        }
         const sv = getCell(minArr, r, c);
+        if (sv.kind === RVKind.Error) {
+            minErr = sv;
+            return;
+        }
         if (sv.kind === RVKind.Number) {
             if (sv.value < result) {
                 result = sv.value;
@@ -339,5 +417,8 @@ export function fnMINIFS(args) {
             found = true;
         }
     });
+    if (minErr) {
+        return minErr;
+    }
     return rvNumber(found ? result : 0);
 }