@cj-tech-master/excelts 9.3.1 → 9.4.0

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

@@ -29,7 +29,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",
@@ -219,6 +219,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)
@@ -279,16 +329,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");
@@ -896,6 +944,16 @@ 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.
@@ -910,8 +968,22 @@ 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/cjs/modules/excel/workbook.browser.js

@@ -1063,6 +1063,55 @@ class Workbook {
     calculateFormulas() {
         (0, host_registry_1.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/cjs/modules/excel/xlsx/defaultnumformats.js

@@ -20,7 +20,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"月"',
@@ -78,8 +78,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" },

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

@@ -107,6 +107,8 @@ function bind(node, ctx) {
             return bindName(node.name, ctx);
         case 15 /* NodeType.StructuredRef */:
             return bindStructuredRef(node.tableName, node.columns, node.specials, ctx);
+        case 17 /* NodeType.UnionRef */:
+            return bindUnionRef(node, ctx);
         default:
             return assertNever(node);
     }
@@ -162,6 +164,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 (0, bound_ast_1.boundErrorLiteral)("#REF!");
+    }
     // 3D range reference: Sheet1:Sheet3!A1:B2
     if (node.endSheet) {
         const sheets = getSheetsInRange(ctx.snapshot, sheet, node.endSheet);
@@ -175,6 +182,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 (0, bound_ast_1.boundErrorLiteral)("#REF!");
+    }
     return (0, bound_ast_1.boundAreaRef)(sheet, top, left, bottom, right);
 }
 function bindColRangeRef(node, ctx) {
@@ -183,6 +197,12 @@ function bindColRangeRef(node, ctx) {
     const endCol = (0, address_utils_1.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 (0, bound_ast_1.boundErrorLiteral)("#REF!");
+    }
     // Validate sheet exists
     if (!ctx.snapshot.worksheetsByName.has(sheet.toLowerCase())) {
         return (0, bound_ast_1.boundErrorLiteral)("#REF!");
@@ -212,6 +232,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 (0, bound_ast_1.boundErrorLiteral)("#REF!");
+    }
     // Validate sheet exists
     if (!ctx.snapshot.worksheetsByName.has(sheet.toLowerCase())) {
         return (0, bound_ast_1.boundErrorLiteral)("#REF!");
@@ -237,6 +262,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: 16 /* BoundExprKind.UnionRef */,
+        areas: bounds
+    };
+}
+// ============================================================================
 // Name Binding
 // ============================================================================
 function bindName(name, ctx) {
@@ -326,12 +369,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/cjs/modules/formula/compile/compiled-formula.js

@@ -213,6 +213,13 @@ function walkDeps(expr, cells, areas, tablesByName, nameResolver, visitedNames)
                 }
             }
             break;
+        case 16 /* 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;
     }
 }
 // ============================================================================
@@ -279,9 +286,15 @@ function detectDynamicArrayFunction(ast, bound) {
             return true;
         }
     }
-    // Check bound expression level
-    if (bound.kind === 10 /* 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 === 10 /* BoundExprKind.Call */) {
+        const canonical = (0, token_types_1.stripFunctionPrefix)(bound.name);
+        if (DYNAMIC_ARRAY_FUNCTION_NAMES.has(canonical)) {
+            return true;
+        }
     }
     return false;
 }
@@ -302,9 +315,15 @@ function detectSubtotalOutput(ast, bound) {
             return true;
         }
     }
-    if (bound.kind === 10 /* BoundExprKind.Call */ &&
-        (bound.name === "SUBTOTAL" || bound.name === "AGGREGATE")) {
-        return true;
+    if (bound.kind === 10 /* 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 = (0, token_types_1.stripFunctionPrefix)(bound.name);
+        if (canonical === "SUBTOTAL" || canonical === "AGGREGATE") {
+            return true;
+        }
     }
     return false;
 }
@@ -323,15 +342,24 @@ function analyzeExpr(expr, nameResolver) {
     return { isVolatile, hasDynamicRefs, containsLambda };
     function walkAnalyze(e) {
         switch (e.kind) {
-            case 10 /* BoundExprKind.Call */:
-                if (VOLATILE_FUNCTIONS.has(e.name)) {
+            case 10 /* 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 = (0, token_types_1.stripFunctionPrefix)(e.name);
+                if (VOLATILE_FUNCTIONS.has(canonical)) {
                     isVolatile = true;
                 }
                 for (const arg of e.args) {
                     walkAnalyze(arg);
                 }
                 break;
+            }
             case 11 /* 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;
                 }
@@ -379,6 +407,11 @@ function analyzeExpr(expr, nameResolver) {
                     }
                 }
                 break;
+            case 16 /* BoundExprKind.UnionRef */:
+                for (const area of e.areas) {
+                    walkAnalyze(area);
+                }
+                break;
             default:
                 // Literal, CellRef, AreaRef, etc. — no children to analyze
                 break;

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

@@ -12,6 +12,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.checkError = checkError;
 exports.argToNumber = argToNumber;
 exports.flattenNumbers = flattenNumbers;
+exports.forEachNumber = forEachNumber;
 exports.flattenAll = flattenAll;
 exports.firstError = firstError;
 exports.asArray = asArray;
@@ -91,6 +92,53 @@ 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.
+ */
+function forEachNumber(args, onNumber) {
+    for (const arg of args) {
+        if (arg.kind === 5 /* RVKind.Array */) {
+            for (const row of arg.rows) {
+                for (const cell of row) {
+                    if (cell.kind === 4 /* RVKind.Error */) {
+                        return cell;
+                    }
+                    if (cell.kind === 1 /* RVKind.Number */) {
+                        onNumber(cell.value);
+                    }
+                    // Booleans, strings, blanks inside arrays are skipped.
+                }
+            }
+        }
+        else if (arg.kind === 4 /* RVKind.Error */) {
+            return arg;
+        }
+        else if (arg.kind !== 0 /* RVKind.Blank */) {
+            const n = (0, values_1.toNumberRV)(arg);
+            if (n.kind === 4 /* 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).