@cj-tech-master/excelts 9.3.1 → 9.4.0

package/dist/browser/modules/formula/runtime/function-registry.d.ts

@@ -38,6 +38,11 @@ export declare function registerFunction(desc: FunctionDescriptor): void;
  * `_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 declare function lookupFunction(name: string): FunctionDescriptor | undefined;
 /**

package/dist/browser/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/browser/modules/formula/runtime/values.d.ts

@@ -156,6 +156,19 @@ export declare function rvString(value: string): StringValue;
 export declare function rvBoolean(value: boolean): BooleanValue;
 export declare function rvError(code: ErrorCode): ErrorValue;
 export declare function rvArray(rows: ScalarValue[][], originRow?: number, originCol?: number, subtotalMask?: readonly (readonly boolean[])[], hiddenRowMask?: readonly boolean[]): ArrayValue;
+/**
+ * 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 declare function rvArrayRect(rows: ScalarValue[][], height: number, width: number, originRow?: number, originCol?: number, subtotalMask?: readonly (readonly boolean[])[], hiddenRowMask?: readonly boolean[]): ArrayValue;
 export declare function rvRef(sheet: string, top: number, left: number, bottom: number, right: number): ReferenceValue;
 export declare function rvCellRef(sheet: string, row: number, col: number): ReferenceValue;
 export declare function rvLambda(params: string[], body: BoundExpr, closureBindings?: ReadonlyMap<string, RuntimeValue>): LambdaValue;

package/dist/browser/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/browser/modules/formula/syntax/ast.d.ts

@@ -20,7 +20,8 @@ export declare const enum NodeType {
     ColRangeRef = 13,
     RowRangeRef = 14,
     StructuredRef = 15,
-    Missing = 16
+    Missing = 16,
+    UnionRef = 17
 }
 export interface NumberNode {
     type: NodeType.Number;
@@ -126,4 +127,15 @@ export interface StructuredRefNode {
 export interface MissingNode {
     type: NodeType.Missing;
 }
-export type AstNode = NumberNode | StringNode | BooleanNode | ErrorNode | CellRefNode | RangeRefNode | BinaryOpNode | UnaryOpNode | FunctionCallNode | ArrayNode | PercentNode | NameNode | ColRangeRefNode | RowRangeRefNode | StructuredRefNode | MissingNode;
+/**
+ * A reference union produced by the comma operator inside
+ * parentheses — `(A1:B2, D4:E5)`. Each member is itself a
+ * reference-producing sub-expression. INDEX's `area_num` parameter
+ * selects which element of the union to read.
+ */
+export interface UnionRefNode {
+    type: NodeType.UnionRef;
+    /** The union members, in syntactic order. */
+    areas: AstNode[];
+}
+export type AstNode = NumberNode | StringNode | BooleanNode | ErrorNode | CellRefNode | RangeRefNode | BinaryOpNode | UnaryOpNode | FunctionCallNode | ArrayNode | PercentNode | NameNode | ColRangeRefNode | RowRangeRefNode | StructuredRefNode | MissingNode | UnionRefNode;

package/dist/browser/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/browser/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/browser/modules/formula/syntax/token-types.d.ts

@@ -148,6 +148,10 @@ export interface IntersectToken {
  * 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 declare function stripFunctionPrefix(name: string): string;
 export type Token = NumberToken | StringToken | BooleanToken | ErrorToken | CellRefToken | RangeToken | SheetRefToken | FunctionToken | OperatorToken | OpenParenToken | CloseParenToken | CommaToken | ColonToken | PercentToken | OpenBraceToken | CloseBraceToken | SemicolonToken | UnaryPrefixToken | NameToken | ColRangeToken | RowRangeToken | StructuredRefToken | AtSignToken | IntersectToken;

package/dist/browser/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/browser/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

package/dist/cjs/index.js

@@ -17,8 +17,8 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PdfError = exports.PageSizes = exports.excelToPdf = exports.pdf = exports.uint8ArrayToString = exports.stringToUint8Array = exports.toUint8Array = exports.concatUint8Arrays = exports.getRootCause = exports.getErrorChain = exports.errorToJSON = exports.toError = exports.BaseError = exports.getSupportedFormats = exports.DateFormatter = exports.DateParser = exports.xmlDecode = exports.xmlEncode = exports.uint8ArrayToBase64 = exports.base64ToUint8Array = exports.excelToDate = exports.dateToExcel = exports.encodeRange = exports.decodeRange = exports.encodeCell = exports.decodeCell = exports.encodeRow = exports.decodeRow = exports.encodeCol = exports.decodeCol = exports.DefinedNames = exports.createCsvFormatterStream = exports.createCsvParserStream = exports.CsvFormatterStream = exports.CsvParserStream = exports.createTextWatermarkImage = exports.WorksheetReader = exports.WorksheetWriter = exports.WorkbookReader = exports.WorkbookWriter = exports.FormCheckbox = exports.DataValidations = exports.Table = exports.Image = exports.Range = exports.Cell = exports.Column = exports.Row = exports.Worksheet = exports.Workbook = void 0;
-exports.MarkdownParseError = exports.MarkdownError = exports.MaxItemsExceededError = exports.ImageError = exports.TableError = exports.PivotTableError = exports.WorksheetNameError = exports.XmlParseError = exports.InvalidValueTypeError = exports.MergeConflictError = exports.RowOutOfBoundsError = exports.ColumnOutOfBoundsError = exports.InvalidAddressError = exports.ExcelStreamStateError = exports.ExcelNotSupportedError = exports.ExcelDownloadError = exports.ExcelFileError = exports.isExcelError = exports.ExcelError = exports.isPdfError = exports.PdfStructureError = exports.PdfFontError = exports.PdfRenderError = void 0;
+exports.pdf = exports.uint8ArrayToString = exports.stringToUint8Array = exports.toUint8Array = exports.concatUint8Arrays = exports.getRootCause = exports.getErrorChain = exports.errorToJSON = exports.toError = exports.BaseError = exports.getSupportedFormats = exports.DateFormatter = exports.DateParser = exports.xmlDecode = exports.xmlEncode = exports.uint8ArrayToBase64 = exports.base64ToUint8Array = exports.excelToDate = exports.dateToExcel = exports.isDateDisplayFormat = exports.formatCellValue = exports.getCellDisplayText = exports.encodeRange = exports.decodeRange = exports.encodeCell = exports.decodeCell = exports.encodeRow = exports.decodeRow = exports.encodeCol = exports.decodeCol = exports.DefinedNames = exports.createCsvFormatterStream = exports.createCsvParserStream = exports.CsvFormatterStream = exports.CsvParserStream = exports.createTextWatermarkImage = exports.WorksheetReader = exports.WorksheetWriter = exports.WorkbookReader = exports.WorkbookWriter = exports.FormCheckbox = exports.DataValidations = exports.Table = exports.Image = exports.Range = exports.Cell = exports.Column = exports.Row = exports.Worksheet = exports.Workbook = void 0;
+exports.MarkdownParseError = exports.MarkdownError = exports.MaxItemsExceededError = exports.ImageError = exports.TableError = exports.PivotTableError = exports.WorksheetNameError = exports.XmlParseError = exports.InvalidValueTypeError = exports.MergeConflictError = exports.RowOutOfBoundsError = exports.ColumnOutOfBoundsError = exports.InvalidAddressError = exports.ExcelStreamStateError = exports.ExcelNotSupportedError = exports.ExcelDownloadError = exports.ExcelFileError = exports.isExcelError = exports.ExcelError = exports.isPdfError = exports.PdfStructureError = exports.PdfFontError = exports.PdfRenderError = exports.PdfError = exports.PageSizes = exports.excelToPdf = void 0;
 var workbook_1 = require("./modules/excel/workbook.js");
 Object.defineProperty(exports, "Workbook", { enumerable: true, get: function () { return workbook_1.Workbook; } });
 var worksheet_1 = require("./modules/excel/worksheet.js");
@@ -91,6 +91,11 @@ Object.defineProperty(exports, "decodeCell", { enumerable: true, get: function (
 Object.defineProperty(exports, "encodeCell", { enumerable: true, get: function () { return address_1.encodeCell; } });
 Object.defineProperty(exports, "decodeRange", { enumerable: true, get: function () { return address_1.decodeRange; } });
 Object.defineProperty(exports, "encodeRange", { enumerable: true, get: function () { return address_1.encodeRange; } });
+// Cell display-text helpers (apply numFmt to produce an Excel-style string)
+var cell_format_1 = require("./modules/excel/utils/cell-format.js");
+Object.defineProperty(exports, "getCellDisplayText", { enumerable: true, get: function () { return cell_format_1.getCellDisplayText; } });
+Object.defineProperty(exports, "formatCellValue", { enumerable: true, get: function () { return cell_format_1.formatCellValue; } });
+Object.defineProperty(exports, "isDateDisplayFormat", { enumerable: true, get: function () { return cell_format_1.isDateDisplayFormat; } });
 // Date conversion (Excel serial dates <-> JS Date)
 var utils_base_1 = require("./utils/utils.base.js");
 Object.defineProperty(exports, "dateToExcel", { enumerable: true, get: function () { return utils_base_1.dateToExcel; } });

package/dist/cjs/modules/excel/cell.js

@@ -4,6 +4,7 @@ exports.Cell = void 0;
 const enums_1 = require("./enums.js");
 const errors_1 = require("./errors.js");
 const note_1 = require("./note.js");
+const cell_format_1 = require("./utils/cell-format.js");
 const col_cache_1 = require("./utils/col-cache.js");
 const copy_style_1 = require("./utils/copy-style.js");
 const shared_formula_1 = require("./utils/shared-formula.js");
@@ -274,6 +275,26 @@ class Cell {
     get text() {
         return this._value.toString();
     }
+    /**
+     * The cell's display text — the value formatted the way Excel would render
+     * it, applying the cell's `numFmt`. For a Date cell with `numFmt` `"mm-dd-yy"`,
+     * this returns e.g. `"04-12-19"` rather than the JS `Date.prototype.toString()`
+     * output you'd get from `cell.text`.
+     *
+     * Handles primitive values, dates, and formula results. For rich text,
+     * hyperlinks, errors, and other complex types, falls back to `cell.text`.
+     *
+     * Note: numFmt codes that are locale-dependent in Excel (e.g. built-in
+     * numFmtId 14 renders as `dd.mm.yyyy` under German locale but is stored
+     * as `mm-dd-yy`) are applied literally — excelts does not perform
+     * Excel's locale-based format substitution. If you need a specific date
+     * style across cells regardless of per-cell numFmts, call the exported
+     * {@link getCellDisplayText} helper with a `dateFormat` argument, or use
+     * `worksheet.toJSON({ dateFormat })`.
+     */
+    get displayText() {
+        return (0, cell_format_1.getCellDisplayText)(this);
+    }
     get html() {
         return (0, under_dash_1.escapeHtml)(this.text);
     }