@cj-tech-master/excelts 9.3.1 → 9.4.0

package/dist/esm/modules/formula/runtime/function-registry.js

@@ -9,7 +9,7 @@
  * are handled directly by the evaluator's special-form dispatch.
  */
 import { stripFunctionPrefix } from "../syntax/token-types.js";
-import { RVKind, BLANK, ERRORS, rvBoolean, rvNumber, rvString, topLeft } from "./values.js";
+import { RVKind, BLANK, ERRORS, rvBoolean, rvNumber, rvString, toNumberRV, toStringRV, topLeft } from "./values.js";
 // ============================================================================
 // Registry
 // ============================================================================
@@ -34,8 +34,17 @@ export function registerFunction(desc) {
  * `_XLFN._XLWS.` prefixed variants by stripping the prefix before lookup
  * (a no-op for plain names, so plain lookups also go through a single
  * Map.get call — avoiding the double-lookup pattern used previously).
+ *
+ * Fast-path: the overwhelming majority of lookups use plain names
+ * (`SUM`, `IF`, `VLOOKUP`, …). Checking the prefix sentinel byte up
+ * front lets those callers skip the `slice`/`startsWith` machinery in
+ * `stripFunctionPrefix` entirely.
  */
 export function lookupFunction(name) {
+    // Plain names don't start with `_` — skip the prefix-strip call.
+    if (name.length === 0 || name.charCodeAt(0) !== 95 /* `_` */) {
+        return registryMap.get(name);
+    }
     return registryMap.get(stripFunctionPrefix(name));
 }
 /**
@@ -105,20 +114,26 @@ function registerNativeInformationAndLogical() {
         if (v.kind === RVKind.Error) {
             return v;
         }
-        if (v.kind !== RVKind.Number) {
+        // Excel coerces numeric strings and booleans for ISEVEN / ISODD
+        // (e.g. `ISEVEN("3")` → FALSE, `ISODD(TRUE)` → TRUE). Only genuine
+        // non-numeric text falls through to #VALUE!. Previously we rejected
+        // every non-Number kind outright.
+        const n = toNumberRV(v);
+        if (n.kind === RVKind.Error) {
             return ERRORS.VALUE;
         }
-        return rvBoolean(Math.floor(Math.abs(v.value)) % 2 === 0);
+        return rvBoolean(Math.floor(Math.abs(n.value)) % 2 === 0);
     });
     defineEager("ISODD", 1, 1, args => {
         const v = scalar(args);
         if (v.kind === RVKind.Error) {
             return v;
         }
-        if (v.kind !== RVKind.Number) {
+        const n = toNumberRV(v);
+        if (n.kind === RVKind.Error) {
             return ERRORS.VALUE;
         }
-        return rvBoolean(Math.floor(Math.abs(v.value)) % 2 === 1);
+        return rvBoolean(Math.floor(Math.abs(n.value)) % 2 === 1);
     });
     defineEager("N", 1, 1, args => {
         const v = scalar(args);
@@ -169,6 +184,11 @@ function registerNativeInformationAndLogical() {
         return map[v.code] !== undefined ? rvNumber(map[v.code]) : ERRORS.NA;
     });
     defineEager("NA", 0, 0, () => ERRORS.NA);
+    // TRUE() and FALSE() — Excel accepts both the literal and the
+    // zero-arg function form. The tokenizer routes `TRUE(` to a Function
+    // token, so we need to register these so the call binds.
+    defineEager("TRUE", 0, 0, () => rvBoolean(true));
+    defineEager("FALSE", 0, 0, () => rvBoolean(false));
     // ── Stubs — limited implementations for functions that need runtime context ──
     // INFO returns a handful of environment-describing strings. We implement
     // the subset that's meaningful in a headless engine: `"release"` (engine
@@ -180,7 +200,10 @@ function registerNativeInformationAndLogical() {
         if (args.length === 0) {
             return ERRORS.NA;
         }
-        const t = args[0];
+        // Implicit intersection — without topLeft, passing an array would
+        // route through the default `.value = ""` branch and silently
+        // surface #VALUE! instead of using the first cell.
+        const t = topLeft(args[0]);
         if (t.kind === RVKind.Error) {
             return t;
         }
@@ -239,7 +262,10 @@ function registerNativeInformationAndLogical() {
             if (url.kind === RVKind.Error) {
                 return url;
             }
-            return rvString(url.kind === RVKind.String ? url.value : String(url));
+            // Previously `String(url)` stringified a RuntimeValue object to
+            // the literal `"[object Object]"`. Route through `toStringRV`
+            // so numbers / booleans / blanks produce the expected text.
+            return rvString(toStringRV(url));
         }
         if (display.kind === RVKind.String) {
             return display;
@@ -264,6 +290,21 @@ function registerNativeInformationAndLogical() {
         if (v.kind === RVKind.Number) {
             return rvBoolean(v.value === 0);
         }
+        // Excel accepts "TRUE" / "FALSE" strings (case-insensitive) and
+        // Blank cells (treated as FALSE). Previously any non-boolean,
+        // non-numeric kind fell through to #VALUE!.
+        if (v.kind === RVKind.Blank) {
+            return rvBoolean(true);
+        }
+        if (v.kind === RVKind.String) {
+            const upper = v.value.toUpperCase();
+            if (upper === "TRUE") {
+                return rvBoolean(false);
+            }
+            if (upper === "FALSE") {
+                return rvBoolean(true);
+            }
+        }
         return ERRORS.VALUE;
     });
     defineEager("AND", 1, 255, args => boolAggregate(args, true, (cur, val) => cur && val));
@@ -379,6 +420,11 @@ function registerNativeTextFunctions() {
     defineEager("PROPER", 1, 1, fnPROPER);
     defineEager("SUBSTITUTE", 3, 4, fnSUBSTITUTE);
     defineEager("REPLACE", 4, 4, fnREPLACE);
+    // REPLACEB is REPLACE's double-byte alias. In non-DBCS locales Excel
+    // treats them identically, so aliasing to the same implementation
+    // matches behaviour without duplicating logic (matches the existing
+    // LEFTB / RIGHTB / MIDB / LENB / FINDB / SEARCHB wiring below).
+    defineEager("REPLACEB", 4, 4, fnREPLACE);
     defineEager("FIND", 2, 3, fnFIND);
     defineEager("FINDB", 2, 3, fnFIND);
     defineEager("SEARCH", 2, 3, fnSEARCH);
@@ -674,7 +720,7 @@ function registerNativeStatisticalFunctions() {
 // ============================================================================
 // Native Math Functions
 // ============================================================================
-import { fnSUM, fnAVERAGE, fnMIN, fnMAX, fnCOUNT, fnCOUNTA, fnCOUNTBLANK, fnPRODUCT, fnSUMPRODUCT, fnABS, fnCEILING, fnFLOOR, fnINT, fnMOD, fnPOWER, fnROUND, fnROUNDDOWN, fnROUNDUP, fnSQRT, fnSQRTPI, fnLN, fnLOG, fnLOG10, fnEXP, fnPI, fnRAND, fnRANDBETWEEN, fnSIGN, fnTRUNC, fnSUMSQ, fnGCD, fnLCM, fnEVEN, fnODD, fnMROUND, fnQUOTIENT, fnBASE, fnDECIMAL, fnROMAN, fnARABIC, fnDEGREES, fnRADIANS, fnSUMX2MY2, fnSUMX2PY2, fnSUMXMY2, fnMULTINOMIAL, fnFACT as fnMathFACT, fnFACTDOUBLE as fnMathFACTDOUBLE, fnCOMBIN as fnMathCOMBIN, fnCOMBINA as fnMathCOMBINA, fnPERMUT as fnMathPERMUT, fnSIN, fnCOS, fnTAN, fnASIN, fnACOS, fnATAN, fnATAN2, fnSINH, fnCOSH, fnTANH, fnASINH, fnACOSH, fnATANH, fnSEC, fnCSC, fnCOT, fnSECH, fnCSCH, fnCOTH, fnACOT, fnACOTH, fnMMULT, fnMDETERM, fnMINVERSE, fnMUNIT, fnSERIESSUM } from "../functions/math.js";
+import { fnSUM, fnAVERAGE, fnMIN, fnMAX, fnCOUNT, fnCOUNTA, fnCOUNTBLANK, fnPRODUCT, fnSUMPRODUCT, fnABS, fnCEILING, fnCEILING_MATH, fnCEILING_PRECISE, fnFLOOR, fnFLOOR_MATH, fnFLOOR_PRECISE, fnINT, fnMOD, fnPOWER, fnROUND, fnROUNDDOWN, fnROUNDUP, fnSQRT, fnSQRTPI, fnLN, fnLOG, fnLOG10, fnEXP, fnPI, fnRAND, fnRANDBETWEEN, fnSIGN, fnTRUNC, fnSUMSQ, fnGCD, fnLCM, fnEVEN, fnODD, fnMROUND, fnQUOTIENT, fnBASE, fnDECIMAL, fnROMAN, fnARABIC, fnDEGREES, fnRADIANS, fnSUMX2MY2, fnSUMX2PY2, fnSUMXMY2, fnMULTINOMIAL, fnFACT as fnMathFACT, fnFACTDOUBLE as fnMathFACTDOUBLE, fnCOMBIN as fnMathCOMBIN, fnCOMBINA as fnMathCOMBINA, fnPERMUT as fnMathPERMUT, fnSIN, fnCOS, fnTAN, fnASIN, fnACOS, fnATAN, fnATAN2, fnSINH, fnCOSH, fnTANH, fnASINH, fnACOSH, fnATANH, fnSEC, fnCSC, fnCOT, fnSECH, fnCSCH, fnCOTH, fnACOT, fnACOTH, fnMMULT, fnMDETERM, fnMINVERSE, fnMUNIT, fnSERIESSUM } from "../functions/math.js";
 function registerNativeMathFunctions() {
     defineEager("SUM", 1, 255, fnSUM);
     defineEager("AVERAGE", 1, 255, fnAVERAGE);
@@ -692,12 +738,12 @@ function registerNativeMathFunctions() {
     defineEager("SERIESSUM", 4, 4, fnSERIESSUM);
     defineEager("ABS", 1, 1, fnABS);
     defineEager("CEILING", 2, 2, fnCEILING);
-    defineEager("CEILING.MATH", 1, 3, fnCEILING);
-    defineEager("CEILING.PRECISE", 1, 2, fnCEILING);
-    defineEager("ISO.CEILING", 1, 2, fnCEILING);
+    defineEager("CEILING.MATH", 1, 3, fnCEILING_MATH);
+    defineEager("CEILING.PRECISE", 1, 2, fnCEILING_PRECISE);
+    defineEager("ISO.CEILING", 1, 2, fnCEILING_PRECISE);
     defineEager("FLOOR", 2, 2, fnFLOOR);
-    defineEager("FLOOR.MATH", 1, 3, fnFLOOR);
-    defineEager("FLOOR.PRECISE", 1, 2, fnFLOOR);
+    defineEager("FLOOR.MATH", 1, 3, fnFLOOR_MATH);
+    defineEager("FLOOR.PRECISE", 1, 2, fnFLOOR_PRECISE);
     defineEager("INT", 1, 1, fnINT);
     defineEager("MOD", 2, 2, fnMOD);
     defineEager("POWER", 2, 2, fnPOWER);

package/dist/esm/modules/formula/runtime/values.js

@@ -112,10 +112,28 @@ export function rvArray(rows, originRow, originCol, subtotalMask, hiddenRowMask)
             }
         }
     }
+    return buildArrayValue(normalisedRows, height, width, originRow, originCol, subtotalMask, hiddenRowMask);
+}
+/**
+ * Fast-path rectangular ArrayValue constructor.
+ *
+ * Callers that have already produced strictly-rectangular `rows` (every
+ * row is the same length — the length they explicitly `new Array(width)`
+ * allocated) can skip the two-pass width-scan + padding loop in
+ * `rvArray`. Examples: `buildRangeArray`, `broadcastBinaryOp`,
+ * `evaluateArrayLiteral`, `TRANSPOSE` — they all know `width` up front.
+ *
+ * Rows MUST be rectangular; passing ragged data will silently surface as
+ * `undefined` cells downstream.
+ */
+export function rvArrayRect(rows, height, width, originRow, originCol, subtotalMask, hiddenRowMask) {
+    return buildArrayValue(rows, height, width, originRow, originCol, subtotalMask, hiddenRowMask);
+}
+function buildArrayValue(rows, height, width, originRow, originCol, subtotalMask, hiddenRowMask) {
     return originRow !== undefined
         ? {
             kind: RVKind.Array,
-            rows: normalisedRows,
+            rows,
             height,
             width,
             originRow,
@@ -125,7 +143,7 @@ export function rvArray(rows, originRow, originCol, subtotalMask, hiddenRowMask)
         }
         : {
             kind: RVKind.Array,
-            rows: normalisedRows,
+            rows,
             height,
             width,
             ...(subtotalMask ? { subtotalMask } : {}),

package/dist/esm/modules/formula/syntax/ast.js

@@ -25,4 +25,5 @@ export var NodeType;
     NodeType[NodeType["RowRangeRef"] = 14] = "RowRangeRef";
     NodeType[NodeType["StructuredRef"] = 15] = "StructuredRef";
     NodeType[NodeType["Missing"] = 16] = "Missing";
+    NodeType[NodeType["UnionRef"] = 17] = "UnionRef";
 })(NodeType || (NodeType = {}));

package/dist/esm/modules/formula/syntax/parser.js

@@ -22,9 +22,15 @@ function prefixBindingPower(op) {
     switch (op) {
         case "+":
         case "-":
-            // Must be lower than ^ (60/61) so that -2^3 parses as -(2^3), not (-2)^3.
-            // Excel: -2^2 = -4, not 4.
-            return 55;
+            // Excel's unary `-` binds TIGHTER than `^` — unique among
+            // spreadsheets and most programming languages. Microsoft's
+            // published precedence table places "Negation (as in –1)" at
+            // rank 1 (highest) and "Exponentiation" at rank 4.
+            //   =-2^2  →  (-2)^2  →  4    (NOT -(2^2) = -4)
+            //   =-2^3  →  (-2)^3  →  -8
+            // Previously we used 55 which routed via `^` (60/61) and produced
+            // `-(2^3)` — matching most languages but not Excel.
+            return 70;
         default:
             return 0;
     }
@@ -49,7 +55,11 @@ function infixBindingPower(op) {
         case "/":
             return [40, 41];
         case "^":
-            return [61, 60]; // right-associative
+            // Excel is unusual: `^` is LEFT-associative (not right-associative
+            // like the math convention). `=2^3^2` evaluates to `(2^3)^2 = 64`,
+            // not `2^(3^2) = 512`. Using right-associative precedence silently
+            // diverged from Excel for any stacked exponent.
+            return [60, 61];
         // Intersection operator — whitespace between two refs. In Excel
         // precedence this sits between `:` (range, already handled at the
         // tokenizer level) and unary +/-. Left-associative, binds tighter
@@ -246,12 +256,24 @@ class Parser {
             this.next();
             return { type: NodeType.Error, value: t.value };
         }
-        // Parenthesized expression
+        // Parenthesized expression — also the syntactic entry point for
+        // reference unions: `(A1:B2, D4:E5)` is a multi-area reference
+        // that `INDEX(..., area_num)` can index into. A single expression
+        // inside parens is just an expression group (no UnionRef wrapper).
         if (t.type === TokenType.OpenParen) {
             this.next();
-            const expr = this.parseExpr(0);
+            const first = this.parseExpr(0);
+            if (this.peek()?.type === TokenType.Comma) {
+                const areas = [first];
+                while (this.peek()?.type === TokenType.Comma) {
+                    this.next(); // consume ','
+                    areas.push(this.parseExpr(0));
+                }
+                this.expect(TokenType.CloseParen);
+                return { type: NodeType.UnionRef, areas };
+            }
             this.expect(TokenType.CloseParen);
-            return expr;
+            return first;
         }
         // Array constant: {1,2;3,4}
         if (t.type === TokenType.OpenBrace) {

package/dist/esm/modules/formula/syntax/token-types.js

@@ -47,8 +47,17 @@ export var TokenType;
  * The input may or may not already be uppercased — this helper does not
  * alter case; callers that compare against an uppercase table should
  * uppercase first (or compare case-insensitively).
+ *
+ * Fast path: plain names (99%+ of call sites) start with a letter, so
+ * checking the first code unit before the `startsWith` machinery lets
+ * those lookups skip the allocation.
  */
 export function stripFunctionPrefix(name) {
+    // `_` is code unit 95 — ASCII letters are 65..90 / 97..122. The XLFN
+    // prefix is the only legitimate name shape that begins with `_`.
+    if (name.length === 0 || name.charCodeAt(0) !== 95) {
+        return name;
+    }
     if (name.startsWith("_XLFN._XLWS.")) {
         return name.slice(12);
     }

package/dist/esm/modules/formula/syntax/tokenizer.js

@@ -442,26 +442,56 @@ export function tokenize(formula) {
         // String literals
         if (ch === '"') {
             i++; // skip opening quote
-            let str = "";
+            // Fast path: walk forward looking for a closing quote. In the common
+            // case (no escaped quotes) we emit a single `slice` rather than
+            // growing a string byte by byte. The slow path falls back to the
+            // explicit escape-aware concat when we actually see `""`.
+            const start = i;
             let closed = false;
+            let firstEscape = -1;
             while (i < len) {
                 if (formula[i] === '"') {
                     if (i + 1 < len && formula[i + 1] === '"') {
-                        // Escaped quote
-                        str += '"';
-                        i += 2;
-                    }
-                    else {
-                        i++; // skip closing quote
-                        closed = true;
+                        firstEscape = i;
                         break;
                     }
+                    closed = true;
+                    break;
                 }
-                else {
-                    str += formula[i];
-                    i++;
+                i++;
+            }
+            let str;
+            if (firstEscape !== -1) {
+                // At least one escaped quote — use the classic byte-by-byte loop
+                // starting from the first escape so the prefix can still come
+                // from `slice`.
+                str = formula.slice(start, firstEscape);
+                i = firstEscape;
+                while (i < len) {
+                    if (formula[i] === '"') {
+                        if (i + 1 < len && formula[i + 1] === '"') {
+                            str += '"';
+                            i += 2;
+                        }
+                        else {
+                            i++;
+                            closed = true;
+                            break;
+                        }
+                    }
+                    else {
+                        str += formula[i];
+                        i++;
+                    }
                 }
             }
+            else if (closed) {
+                str = formula.slice(start, i);
+                i++; // consume closing quote
+            }
+            else {
+                str = formula.slice(start, i);
+            }
             if (!closed) {
                 // Unterminated string literal — reject at tokenize time so we
                 // never hand the parser a truncated value that could alias to a
@@ -723,21 +753,48 @@ export function tokenize(formula) {
         // Quoted sheet name: 'Sheet Name'! or 3D ref 'Sheet1:Sheet3'!
         if (ch === "'") {
             i++; // skip opening quote
-            let sheetName = "";
+            // Fast path: scan to the first `'` — most sheet names don't contain
+            // an escaped quote, so we can slice the prefix verbatim instead of
+            // growing a string byte-by-byte.
+            const start = i;
+            let firstEscape = -1;
             while (i < len) {
                 if (formula[i] === "'") {
                     if (i + 1 < len && formula[i + 1] === "'") {
-                        sheetName += "'";
-                        i += 2;
+                        firstEscape = i;
+                        break;
+                    }
+                    break;
+                }
+                i++;
+            }
+            let sheetName;
+            if (firstEscape !== -1) {
+                sheetName = formula.slice(start, firstEscape);
+                i = firstEscape;
+                // Slow path from the first escape: consume `''` pairs and
+                // literal characters until the terminating single `'`.
+                while (i < len) {
+                    if (formula[i] === "'") {
+                        if (i + 1 < len && formula[i + 1] === "'") {
+                            sheetName += "'";
+                            i += 2;
+                        }
+                        else {
+                            i++;
+                            break;
+                        }
                     }
                     else {
-                        i++; // skip closing quote
-                        break;
+                        sheetName += formula[i];
+                        i++;
                     }
                 }
-                else {
-                    sheetName += formula[i];
-                    i++;
+            }
+            else {
+                sheetName = formula.slice(start, i);
+                if (i < len && formula[i] === "'") {
+                    i++; // consume closing quote
                 }
             }
             // Expect ! after