@cj-tech-master/excelts 9.3.1 → 9.4.0

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

@@ -40,8 +40,17 @@ 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.
  */
 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((0, token_types_1.stripFunctionPrefix)(name));
 }
 /**
@@ -111,20 +120,26 @@ function registerNativeInformationAndLogical() {
         if (v.kind === 4 /* RVKind.Error */) {
             return v;
         }
-        if (v.kind !== 1 /* 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 = (0, values_1.toNumberRV)(v);
+        if (n.kind === 4 /* RVKind.Error */) {
             return values_1.ERRORS.VALUE;
         }
-        return (0, values_1.rvBoolean)(Math.floor(Math.abs(v.value)) % 2 === 0);
+        return (0, values_1.rvBoolean)(Math.floor(Math.abs(n.value)) % 2 === 0);
     });
     defineEager("ISODD", 1, 1, args => {
         const v = scalar(args);
         if (v.kind === 4 /* RVKind.Error */) {
             return v;
         }
-        if (v.kind !== 1 /* RVKind.Number */) {
+        const n = (0, values_1.toNumberRV)(v);
+        if (n.kind === 4 /* RVKind.Error */) {
             return values_1.ERRORS.VALUE;
         }
-        return (0, values_1.rvBoolean)(Math.floor(Math.abs(v.value)) % 2 === 1);
+        return (0, values_1.rvBoolean)(Math.floor(Math.abs(n.value)) % 2 === 1);
     });
     defineEager("N", 1, 1, args => {
         const v = scalar(args);
@@ -175,6 +190,11 @@ function registerNativeInformationAndLogical() {
         return map[v.code] !== undefined ? (0, values_1.rvNumber)(map[v.code]) : values_1.ERRORS.NA;
     });
     defineEager("NA", 0, 0, () => values_1.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, () => (0, values_1.rvBoolean)(true));
+    defineEager("FALSE", 0, 0, () => (0, values_1.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
@@ -186,7 +206,10 @@ function registerNativeInformationAndLogical() {
         if (args.length === 0) {
             return values_1.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 = (0, values_1.topLeft)(args[0]);
         if (t.kind === 4 /* RVKind.Error */) {
             return t;
         }
@@ -245,7 +268,10 @@ function registerNativeInformationAndLogical() {
             if (url.kind === 4 /* RVKind.Error */) {
                 return url;
             }
-            return (0, values_1.rvString)(url.kind === 2 /* 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 (0, values_1.rvString)((0, values_1.toStringRV)(url));
         }
         if (display.kind === 2 /* RVKind.String */) {
             return display;
@@ -270,6 +296,21 @@ function registerNativeInformationAndLogical() {
         if (v.kind === 1 /* RVKind.Number */) {
             return (0, values_1.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 === 0 /* RVKind.Blank */) {
+            return (0, values_1.rvBoolean)(true);
+        }
+        if (v.kind === 2 /* RVKind.String */) {
+            const upper = v.value.toUpperCase();
+            if (upper === "TRUE") {
+                return (0, values_1.rvBoolean)(false);
+            }
+            if (upper === "FALSE") {
+                return (0, values_1.rvBoolean)(true);
+            }
+        }
         return values_1.ERRORS.VALUE;
     });
     defineEager("AND", 1, 255, args => boolAggregate(args, true, (cur, val) => cur && val));
@@ -385,6 +426,11 @@ function registerNativeTextFunctions() {
     defineEager("PROPER", 1, 1, text_1.fnPROPER);
     defineEager("SUBSTITUTE", 3, 4, text_1.fnSUBSTITUTE);
     defineEager("REPLACE", 4, 4, text_1.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, text_1.fnREPLACE);
     defineEager("FIND", 2, 3, text_1.fnFIND);
     defineEager("FINDB", 2, 3, text_1.fnFIND);
     defineEager("SEARCH", 2, 3, text_1.fnSEARCH);
@@ -698,12 +744,12 @@ function registerNativeMathFunctions() {
     defineEager("SERIESSUM", 4, 4, math_1.fnSERIESSUM);
     defineEager("ABS", 1, 1, math_1.fnABS);
     defineEager("CEILING", 2, 2, math_1.fnCEILING);
-    defineEager("CEILING.MATH", 1, 3, math_1.fnCEILING);
-    defineEager("CEILING.PRECISE", 1, 2, math_1.fnCEILING);
-    defineEager("ISO.CEILING", 1, 2, math_1.fnCEILING);
+    defineEager("CEILING.MATH", 1, 3, math_1.fnCEILING_MATH);
+    defineEager("CEILING.PRECISE", 1, 2, math_1.fnCEILING_PRECISE);
+    defineEager("ISO.CEILING", 1, 2, math_1.fnCEILING_PRECISE);
     defineEager("FLOOR", 2, 2, math_1.fnFLOOR);
-    defineEager("FLOOR.MATH", 1, 3, math_1.fnFLOOR);
-    defineEager("FLOOR.PRECISE", 1, 2, math_1.fnFLOOR);
+    defineEager("FLOOR.MATH", 1, 3, math_1.fnFLOOR_MATH);
+    defineEager("FLOOR.PRECISE", 1, 2, math_1.fnFLOOR_PRECISE);
     defineEager("INT", 1, 1, math_1.fnINT);
     defineEager("MOD", 2, 2, math_1.fnMOD);
     defineEager("POWER", 2, 2, math_1.fnPOWER);

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

@@ -24,6 +24,7 @@ exports.rvString = rvString;
 exports.rvBoolean = rvBoolean;
 exports.rvError = rvError;
 exports.rvArray = rvArray;
+exports.rvArrayRect = rvArrayRect;
 exports.rvRef = rvRef;
 exports.rvCellRef = rvCellRef;
 exports.rvLambda = rvLambda;
@@ -112,10 +113,28 @@ 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.
+ */
+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: 5 /* RVKind.Array */,
-            rows: normalisedRows,
+            rows,
             height,
             width,
             originRow,
@@ -125,7 +144,7 @@ function rvArray(rows, originRow, originCol, subtotalMask, hiddenRowMask) {
         }
         : {
             kind: 5 /* RVKind.Array */,
-            rows: normalisedRows,
+            rows,
             height,
             width,
             ...(subtotalMask ? { subtotalMask } : {}),

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

@@ -23,9 +23,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;
     }
@@ -50,7 +56,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
@@ -247,12 +257,24 @@ class Parser {
             this.next();
             return { type: 4 /* 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 === 10 /* TokenType.OpenParen */) {
             this.next();
-            const expr = this.parseExpr(0);
+            const first = this.parseExpr(0);
+            if (this.peek()?.type === 12 /* TokenType.Comma */) {
+                const areas = [first];
+                while (this.peek()?.type === 12 /* TokenType.Comma */) {
+                    this.next(); // consume ','
+                    areas.push(this.parseExpr(0));
+                }
+                this.expect(11 /* TokenType.CloseParen */);
+                return { type: 17 /* NodeType.UnionRef */, areas };
+            }
             this.expect(11 /* TokenType.CloseParen */);
-            return expr;
+            return first;
         }
         // Array constant: {1,2;3,4}
         if (t.type === 15 /* TokenType.OpenBrace */) {

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

@@ -20,8 +20,17 @@ exports.stripFunctionPrefix = stripFunctionPrefix;
  * 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.
  */
 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/cjs/modules/formula/syntax/tokenizer.js

@@ -444,26 +444,56 @@ 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
@@ -725,21 +755,48 @@ 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/esm/index.js

@@ -45,6 +45,8 @@ export { DefinedNames } from "./modules/excel/defined-names.js";
 // =============================================================================
 // Cell address encoding/decoding (0-indexed)
 export { decodeCol, encodeCol, decodeRow, encodeRow, decodeCell, encodeCell, decodeRange, encodeRange } from "./modules/excel/utils/address.js";
+// Cell display-text helpers (apply numFmt to produce an Excel-style string)
+export { getCellDisplayText, formatCellValue, isDateDisplayFormat } from "./modules/excel/utils/cell-format.js";
 // Date conversion (Excel serial dates <-> JS Date)
 export { dateToExcel, excelToDate } from "./utils/utils.base.js";
 // Base64 utilities (cross-platform)

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

@@ -1,6 +1,7 @@
 import { Enums } from "./enums.js";
 import { ExcelError, InvalidValueTypeError } from "./errors.js";
 import { Note } from "./note.js";
+import { getCellDisplayText } from "./utils/cell-format.js";
 import { colCache } from "./utils/col-cache.js";
 import { copyStyle } from "./utils/copy-style.js";
 import { slideFormula } from "./utils/shared-formula.js";
@@ -271,6 +272,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 getCellDisplayText(this);
+    }
     get html() {
         return escapeHtml(this.text);
     }

package/dist/esm/modules/excel/utils/cell-format.js

@@ -20,7 +20,7 @@ const TABLE_FMT = {
     11: "0.00E+00",
     12: "# ?/?",
     13: "# ??/??",
-    14: "m/d/yy",
+    14: "mm-dd-yy",
     15: "d-mmm-yy",
     16: "d-mmm",
     17: "mmm-yy",
@@ -210,6 +210,56 @@ const MONTHS_LONG = [
 const MONTHS_LETTER = ["J", "F", "M", "A", "M", "J", "J", "A", "S", "O", "N", "D"];
 const DAYS_SHORT = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
 const DAYS_LONG = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
+/**
+ * Disambiguate each `mm` occurrence in a format string that has already been
+ * placeholder-substituted for the other date/time tokens.
+ *
+ * Excel's rule: `mm` is minutes when it's adjacent to an hour or seconds
+ * token (with no intervening date tokens); otherwise it's a zero-padded
+ * month. This must be decided per occurrence — a single format string can
+ * contain both roles (e.g. `"yyyy-mm-dd hh:mm:ss"`).
+ *
+ * The caller has already replaced `yyyy`/`yy` → `Y4/Y2`, month-name tokens
+ * `mmmmm/mmmm/mmm` → `MN5/MN4/MN3`, `dd`/`d` → `D2/D1`, `hh`/`h` → `H2/H1`,
+ * `ss`/`s` → `S2/S1`. So any remaining literal `mm` substrings here are
+ * ambiguous between minute and month.
+ *
+ * Returns the input with each `mm` replaced by either `\x00MI2\x00` (minutes)
+ * or `\x00M2\x00` (month, zero-padded).
+ */
+function resolveMonthOrMinute(s) {
+    // Tokens that, when present between an `mm` and a time anchor, break the
+    // "adjacent time context" chain and push the `mm` back into month-land.
+    const DATE_TOKEN = /\x00(?:Y[24]|D[12]|MN[345])\x00/;
+    const HOUR_TOKEN = /\x00H[12]\x00/g;
+    const SEC_TOKEN = /\x00S[12]\x00/g;
+    let out = "";
+    let work = s;
+    let idx = work.search(/mm/i);
+    while (idx !== -1) {
+        const before = work.slice(0, idx);
+        const after = work.slice(idx + 2);
+        // Find the *nearest* hour token preceding this `mm` (scan from the right).
+        let nearestHourIdx = -1;
+        let m;
+        HOUR_TOKEN.lastIndex = 0;
+        while ((m = HOUR_TOKEN.exec(before)) !== null) {
+            nearestHourIdx = m.index;
+        }
+        // Find the *nearest* seconds token following this `mm`.
+        SEC_TOKEN.lastIndex = 0;
+        const secMatch = SEC_TOKEN.exec(after);
+        const nearestSecIdx = secMatch ? secMatch.index : -1;
+        const hourInRange = nearestHourIdx !== -1 && !DATE_TOKEN.test(before.slice(nearestHourIdx));
+        const secInRange = nearestSecIdx !== -1 && !DATE_TOKEN.test(after.slice(0, nearestSecIdx));
+        const isMinutes = hourInRange || secInRange;
+        out += before + (isMinutes ? "\x00MI2\x00" : "\x00M2\x00");
+        work = after;
+        idx = work.search(/mm/i);
+    }
+    out += work;
+    return out;
+}
 /**
  * Format a date value using Excel date format
  * @param serial Excel serial number (days since 1900-01-01)
@@ -270,16 +320,14 @@ function formatDate(serial, fmt) {
     // Seconds (before mm to avoid confusion)
     result = result.replace(/ss/gi, "\x00S2\x00");
     result = result.replace(/\bs\b/gi, "\x00S1\x00");
-    // Minutes/Month mm - context dependent
-    // If near h or s, it's minutes; otherwise month
-    // For simplicity, check if we already have hour tokens nearby
-    const hasTimeContext = /\x00H[12]\x00.*mm|mm.*\x00S[12]\x00/i.test(result);
-    if (hasTimeContext) {
-        result = result.replace(/mm/gi, "\x00MI2\x00");
-    }
-    else {
-        result = result.replace(/mm/gi, "\x00M2\x00");
-    }
+    // Minutes/Month `mm` — position-dependent. Excel treats `mm` as minutes
+    // when the nearest neighboring time-token is an hour (before) or a
+    // seconds token (after); otherwise it's month. This must be decided **per
+    // occurrence**, because a single format string can contain both roles —
+    // e.g. in `"yyyy-mm-dd hh:mm:ss"` the first `mm` is month and the second
+    // is minutes. A single global `hasTimeContext` flag would miscategorise
+    // all `mm` as minutes in such mixed formats.
+    result = resolveMonthOrMinute(result);
     result = result.replace(/\bm\b/gi, "\x00M1\x00");
     // AM/PM
     result = result.replace(/AM\/PM/gi, "\x00AMPM\x00");
@@ -887,6 +935,16 @@ export function isDateDisplayFormat(fmt) {
     }
     return false;
 }
+/**
+ * Default format applied to Date values whose numFmt is `General` or empty.
+ *
+ * Excel itself substitutes a locale-dependent short date in this case (US:
+ * `m/d/yyyy`). We pick an ISO-like `yyyy-mm-dd` so consumers who never set a
+ * `numFmt` still get a sensible, unambiguous rendering instead of the raw
+ * Excel serial number.
+ */
+const DEFAULT_DATE_FORMAT = "yyyy-mm-dd";
+const DEFAULT_DATETIME_FORMAT = "yyyy-mm-dd hh:mm:ss";
 /**
  * Format a value according to the given format string.
  * Handles Date objects with timezone-independent Excel serial conversion.
@@ -901,8 +959,22 @@ export function formatCellValue(value, fmt, dateFormat) {
             }
             return format(fmt, serial);
         }
-        const actualFmt = dateFormat && isDateDisplayFormat(fmt) ? dateFormat : fmt;
-        return format(actualFmt, serial);
+        // For Date values whose numFmt is missing or General, Excel substitutes a
+        // default short-date format. Without this, `format("General", serial)`
+        // would emit the raw Excel serial (e.g. "43567") — almost never what the
+        // caller wants. Pick a datetime-aware default based on whether the value
+        // carries a non-midnight time component.
+        let effectiveFmt;
+        if (dateFormat && isDateDisplayFormat(fmt)) {
+            effectiveFmt = dateFormat;
+        }
+        else if (!fmt || isGeneral(fmt)) {
+            effectiveFmt = serial % 1 === 0 ? DEFAULT_DATE_FORMAT : DEFAULT_DATETIME_FORMAT;
+        }
+        else {
+            effectiveFmt = fmt;
+        }
+        return format(effectiveFmt, serial);
     }
     return format(fmt, value);
 }

package/dist/esm/modules/excel/workbook.browser.js

@@ -1060,6 +1060,55 @@ class Workbook {
     calculateFormulas() {
         invokeFormulaEngine(this);
     }
+    /**
+     * Register (or replace) a custom formula function on this workbook.
+     *
+     * The function becomes visible to `calculateFormulas()` on this
+     * workbook only — the built-in registry stays untouched. Names are
+     * case-insensitive (normalised to uppercase) and must not include
+     * the `_XLFN.` prefix — the engine strips that automatically.
+     *
+     * @param name    Function name (case-insensitive).
+     * @param fn      Implementation. Receives already-evaluated RuntimeValue
+     *                arguments; return a RuntimeValue. Wrap failures with
+     *                `rvError("#VALUE!")` rather than throwing — throws are
+     *                caught at the evaluator boundary and surface as
+     *                `#VALUE!` so a buggy custom function doesn't tear
+     *                down the whole calculation pass.
+     * @param options Optional arity bounds. Defaults to `minArity=0`,
+     *                `maxArity=255` (Excel's universal argument cap), so
+     *                simple variadic functions work without extra config.
+     *                Set `volatile: true` when the function should be
+     *                re-evaluated on every calc cycle (analogous to
+     *                built-in `RAND`, `NOW`). Currently reserved for
+     *                future use; the engine recomputes every formula on
+     *                each `calculateFormulas()` call regardless.
+     *
+     * ```ts
+     * import { rvNumber } from "@cj-tech-master/excelts/formula";
+     * workbook.registerFunction("DOUBLE", ([x]) => {
+     *   return rvNumber((x as any).value * 2);
+     * }, { minArity: 1, maxArity: 1 });
+     * ```
+     */
+    registerFunction(name, fn, options) {
+        if (!this.userFunctions) {
+            this.userFunctions = new Map();
+        }
+        this.userFunctions.set(name.toUpperCase(), {
+            minArity: options?.minArity ?? 0,
+            maxArity: options?.maxArity ?? 255,
+            invoke: fn,
+            volatile: options?.volatile ?? false
+        });
+    }
+    /**
+     * Remove a user-registered function. No-op when the name isn't
+     * registered; returns `true` when an entry was removed.
+     */
+    unregisterFunction(name) {
+        return this.userFunctions?.delete(name.toUpperCase()) ?? false;
+    }
     // ===========================================================================
     // Themes
     // ===========================================================================

package/dist/esm/modules/excel/xlsx/defaultnumformats.js

@@ -17,7 +17,7 @@ const defaultNumFormats = {
     19: { f: "h:mm:ss AM/PM" },
     20: { f: "h:mm" },
     21: { f: "h:mm:ss" },
-    22: { f: 'm/d/yy "h":mm' },
+    22: { f: "m/d/yy h:mm" },
     27: {
         "zh-tw": "[$-404]e/m/d",
         "zh-cn": 'yyyy"年"m"月"',
@@ -75,8 +75,8 @@ const defaultNumFormats = {
     },
     37: { f: "#,##0 ;(#,##0)" },
     38: { f: "#,##0 ;[Red](#,##0)" },
-    39: { f: "#,##0.00 ;(#,##0.00)" },
-    40: { f: "#,##0.00 ;[Red](#,##0.00)" },
+    39: { f: "#,##0.00;(#,##0.00)" },
+    40: { f: "#,##0.00;[Red](#,##0.00)" },
     45: { f: "mm:ss" },
     46: { f: "[h]:mm:ss" },
     47: { f: "mmss.0" },