@cj-tech-master/excelts 9.3.1 → 9.4.0

package/dist/browser/modules/formula/functions/text.js

@@ -51,8 +51,8 @@ export const fnTEXTJOIN = args => {
     if (e0) {
         return e0;
     }
-    const delimiter = toStringRV(args[0]);
-    const ignoreEmptyRV = toBooleanRV(args[1]);
+    const delimiter = toStringRV(topLeft(args[0]));
+    const ignoreEmptyRV = toBooleanRV(topLeft(args[1]));
     if (isError(ignoreEmptyRV)) {
         return ignoreEmptyRV;
     }
@@ -97,7 +97,8 @@ export const fnLEFT = args => {
     if (err) {
         return err;
     }
-    const text = toStringRV(args[0]);
+    // Implicit intersection on the text arg (see MID for rationale).
+    const text = toStringRV(topLeft(args[0]));
     let n;
     if (args.length > 1) {
         // Use `argToNumber` so array arguments get implicit-intersection to
@@ -125,7 +126,7 @@ export const fnRIGHT = args => {
     if (err) {
         return err;
     }
-    const text = toStringRV(args[0]);
+    const text = toStringRV(topLeft(args[0]));
     let n;
     if (args.length > 1) {
         // Implicit intersection via `argToNumber` — see LEFT for rationale.
@@ -152,9 +153,11 @@ export const fnMID = args => {
     if (err) {
         return err;
     }
-    const text = toStringRV(args[0]);
-    // Implicit intersection on both numeric arguments so array inputs
-    // collapse to their top-left cells before coercion.
+    // Implicit intersection on the text arg — without topLeft, passing
+    // an array would route through `toStringRV`'s default branch and
+    // silently return the empty string, making `MID(A1:A2, 1, 3)` look
+    // like an empty cell instead of a 3-char prefix of the first cell.
+    const text = toStringRV(topLeft(args[0]));
     const startNumRV = argToNumber(args[1]);
     if (isError(startNumRV)) {
         return startNumRV;
@@ -245,7 +248,7 @@ export const fnSUBSTITUTE = args => {
         return rvString(text);
     }
     if (args.length > 3) {
-        const instanceNumRV = toNumberRV(args[3]);
+        const instanceNumRV = toNumberRV(topLeft(args[3]));
         if (isError(instanceNumRV)) {
             return instanceNumRV;
         }
@@ -269,7 +272,7 @@ export const fnREPLACE = args => {
     if (err) {
         return err;
     }
-    const text = toStringRV(args[0]);
+    const text = toStringRV(topLeft(args[0]));
     // Implicit intersection on the numeric arguments — see LEFT.
     const startNumRV = argToNumber(args[1]);
     if (isError(startNumRV)) {
@@ -291,7 +294,7 @@ export const fnREPLACE = args => {
     if (e3) {
         return e3;
     }
-    const newText = toStringRV(args[3]);
+    const newText = toStringRV(topLeft(args[3]));
     return rvString(text.slice(0, startNum - 1) + newText + text.slice(startNum - 1 + numChars));
 };
 // ============================================================================
@@ -306,8 +309,9 @@ export const fnFIND = args => {
     if (err1) {
         return err1;
     }
-    const findText = toStringRV(args[0]);
-    const withinText = toStringRV(args[1]);
+    // Implicit intersection on text args so arrays collapse to top-left.
+    const findText = toStringRV(topLeft(args[0]));
+    const withinText = toStringRV(topLeft(args[1]));
     let startNum;
     if (args.length > 2) {
         // Implicit intersection so an array supplied as start_num collapses
@@ -337,8 +341,9 @@ export const fnSEARCH = args => {
     if (err1) {
         return err1;
     }
-    let findText = toStringRV(args[0]);
-    const withinText = toStringRV(args[1]);
+    // Implicit intersection on text args (see FIND for rationale).
+    let findText = toStringRV(topLeft(args[0]));
+    const withinText = toStringRV(topLeft(args[1]));
     let startNum;
     if (args.length > 2) {
         const startNumRV = argToNumber(args[2]);
@@ -378,7 +383,7 @@ export const fnREPT = args => {
         return err;
     }
     const text = toStringRV(topLeft(args[0]));
-    const timesRV = toNumberRV(args[1]);
+    const timesRV = toNumberRV(topLeft(args[1]));
     if (isError(timesRV)) {
         return timesRV;
     }
@@ -407,7 +412,7 @@ export const fnTEXT = args => {
     if (e1) {
         return e1;
     }
-    const fmt = toStringRV(args[1]);
+    const fmt = toStringRV(topLeft(args[1]));
     // "@" format = return text as-is
     if (fmt === "@") {
         return rvString(toStringRV(rawVal));
@@ -584,10 +589,52 @@ function formatNumber(val, fmt) {
         tokens.push({ kind: "literal", text: ch });
     }
     // Count integer/fraction digit slots and decide whether to group.
+    // Trailing commas after the last integer digit token — before the
+    // decimal point or end of pattern — act as a "scale by 1/1000^k"
+    // multiplier (Excel's "thousands scaling"), not thousand separators.
+    // Example: `#,##0,` → 1,234,567 → "1,235" (divide by 1000).
+    // Example: `#,##0,,` → 1,234,567,890 → "1,234" (divide by 1,000,000).
     let sawDot = false;
     const intDigitSlots = [];
     const fracDigitSlots = [];
     let hasGrouping = false;
+    // Scan for trailing commas that sit strictly after the last integer
+    // digit slot but before any dot or fractional slot. Each such comma
+    // divides the value by 1000. Scan from end-of-pattern backward to
+    // locate them.
+    let scalingFactor = 1;
+    {
+        // Find the last integer digit-slot index.
+        let lastIntDigitIdx = -1;
+        let dotIdx = -1;
+        for (let i = 0; i < tokens.length; i++) {
+            const t = tokens[i];
+            if (t.kind === "dot") {
+                dotIdx = i;
+                break;
+            }
+            if (t.kind === "digit") {
+                lastIntDigitIdx = i;
+            }
+        }
+        // Trailing commas live after `lastIntDigitIdx` and strictly before
+        // `dotIdx` (if present). They must be adjacent — only run-of-commas
+        // directly abutting the last integer digit count as scaling.
+        if (lastIntDigitIdx !== -1) {
+            const stopBefore = dotIdx === -1 ? tokens.length : dotIdx;
+            let k = lastIntDigitIdx + 1;
+            while (k < stopBefore && tokens[k].kind === "comma") {
+                scalingFactor *= 1000;
+                // Remove this comma so later logic doesn't treat it as a
+                // thousand-separator or literal artefact. We mutate the token
+                // to a no-op literal with empty text.
+                tokens[k] = { kind: "literal", text: "" };
+                k++;
+            }
+        }
+    }
+    // Apply the scaling before any other formatting work.
+    const scaledVal = val / scalingFactor;
     for (const t of tokens) {
         if (t.kind === "dot") {
             sawDot = true;
@@ -611,7 +658,7 @@ function formatNumber(val, fmt) {
         return fmt; // Nothing to format; return the (raw) pattern.
     }
     // Round to the requested fractional precision.
-    const rounded = roundHalfAwayFromZeroFmt(val, fracDigitSlots.length);
+    const rounded = roundHalfAwayFromZeroFmt(scaledVal, fracDigitSlots.length);
     const sign = rounded < 0 ? "-" : "";
     const absStr = Math.abs(rounded).toFixed(fracDigitSlots.length);
     const [intPartRaw, fracPart = ""] = absStr.split(".");
@@ -691,11 +738,19 @@ function formatNumber(val, fmt) {
             emittedOverflow = true;
         }
         const slotIdx = intCursor;
-        // Integer slots map right-to-left onto `groupedInt`'s right-to-left
-        // ordering. We'll compute the source character for this slot from
-        // the right edge.
-        const srcIdx = overflowDigits + slotIdx;
-        if (srcIdx < groupedInt.length) {
+        // Right-align the integer into the digit slots: leading `#` slots
+        // emit nothing when the value is shorter than the pattern, and
+        // leading `0` slots pad with a zero. Previously the logic treated
+        // every slot as if the integer started at slot 0 (left-align),
+        // which made `TEXT(0, "#,##0")` produce "00" instead of "0".
+        //
+        // The number of "padding" slots that must appear before the first
+        // real digit equals `totalIntSlots − groupedInt.length` when that
+        // value is positive (overflow path zeroes it out since we already
+        // prepended the overflow digits before the first slot).
+        const paddingSlots = overflowDigits > 0 ? 0 : Math.max(0, totalIntSlots - groupedInt.length);
+        const srcIdx = overflowDigits + slotIdx - paddingSlots;
+        if (srcIdx >= 0 && srcIdx < groupedInt.length) {
             out += groupedInt[srcIdx];
         }
         else if (t.char === "0") {
@@ -1018,7 +1073,7 @@ export const fnEXACT = args => {
     if (err1) {
         return err1;
     }
-    return rvBoolean(toStringRV(args[0]) === toStringRV(args[1]));
+    return rvBoolean(toStringRV(topLeft(args[0])) === toStringRV(topLeft(args[1])));
 };
 // ============================================================================
 // Additional Text Functions
@@ -1079,7 +1134,7 @@ export const fnUNICHAR = args => {
     if (err) {
         return err;
     }
-    const nRV = toNumberRV(args[0]);
+    const nRV = toNumberRV(topLeft(args[0]));
     if (isError(nRV)) {
         return nRV;
     }
@@ -1099,7 +1154,7 @@ export const fnUNICODE = args => {
     if (err) {
         return err;
     }
-    const text = toStringRV(args[0]);
+    const text = toStringRV(topLeft(args[0]));
     if (text.length === 0) {
         return ERRORS.VALUE;
     }
@@ -1111,17 +1166,17 @@ export const fnBAHTTEXT = args => {
     if (err) {
         return err;
     }
-    return rvString(toStringRV(args[0]));
+    return rvString(toStringRV(topLeft(args[0])));
 };
 export const fnDOLLAR = args => {
-    const numRV = toNumberRV(args[0]);
+    const numRV = toNumberRV(topLeft(args[0]));
     if (isError(numRV)) {
         return numRV;
     }
     const num = numRV.value;
     let decimals;
     if (args.length > 1) {
-        const decRV = toNumberRV(args[1]);
+        const decRV = toNumberRV(topLeft(args[1]));
         if (isError(decRV)) {
             return decRV;
         }
@@ -1146,14 +1201,14 @@ export const fnDOLLAR = args => {
     return rvString(num < 0 ? `($${result})` : `$${result}`);
 };
 export const fnFIXED = args => {
-    const numRV = toNumberRV(args[0]);
+    const numRV = toNumberRV(topLeft(args[0]));
     if (isError(numRV)) {
         return numRV;
     }
     const num = numRV.value;
     let decimals;
     if (args.length > 1) {
-        const decRV = toNumberRV(args[1]);
+        const decRV = toNumberRV(topLeft(args[1]));
         if (isError(decRV)) {
             return decRV;
         }
@@ -1164,7 +1219,7 @@ export const fnFIXED = args => {
     }
     let noCommas;
     if (args.length > 2) {
-        const ncRV = toBooleanRV(args[2]);
+        const ncRV = toBooleanRV(topLeft(args[2]));
         if (isError(ncRV)) {
             return ncRV;
         }
@@ -1195,7 +1250,7 @@ export const fnASC = args => {
     if (err) {
         return err;
     }
-    const text = toStringRV(args[0]);
+    const text = toStringRV(topLeft(args[0]));
     return rvString(text.replace(/[\uFF01-\uFF5E]/g, ch => String.fromCharCode(ch.charCodeAt(0) - 0xfee0)));
 };
 export const fnDBCS = args => {
@@ -1203,7 +1258,7 @@ export const fnDBCS = args => {
     if (err) {
         return err;
     }
-    const text = toStringRV(args[0]);
+    const text = toStringRV(topLeft(args[0]));
     return rvString(text.replace(/[!-~]/g, ch => String.fromCharCode(ch.charCodeAt(0) + 0xfee0)));
 };
 export const fnJIS = args => fnDBCS(args);
@@ -1221,14 +1276,15 @@ export const fnNUMBERVALUE = args => {
     if (e0) {
         return e0;
     }
-    let text = toStringRV(args[0]);
+    // Implicit intersection on every text arg.
+    let text = toStringRV(topLeft(args[0]));
     let decSep = ".";
     if (args.length > 1) {
         const e1 = checkError(args[1]);
         if (e1) {
             return e1;
         }
-        decSep = toStringRV(args[1]);
+        decSep = toStringRV(topLeft(args[1]));
     }
     let grpSep = ",";
     if (args.length > 2) {
@@ -1236,15 +1292,19 @@ export const fnNUMBERVALUE = args => {
         if (e2) {
             return e2;
         }
-        grpSep = toStringRV(args[2]);
+        grpSep = toStringRV(topLeft(args[2]));
     }
     text = text.split(grpSep).join("");
     if (decSep !== ".") {
         text = text.replace(decSep, ".");
     }
-    // Handle percentage
-    const isPct = text.endsWith("%");
-    if (isPct) {
+    // Handle percentage. Excel divides by 100 for EACH trailing `%`, so
+    // `NUMBERVALUE("50%%")` = 50 / 10000 = 0.005. Previously we only
+    // recognised the first `%` and treated `50%%` as the literal string
+    // "50%" → NaN → #VALUE!.
+    let pctCount = 0;
+    while (text.endsWith("%")) {
+        pctCount++;
         text = text.slice(0, -1);
     }
     // `Number("")` is 0, not NaN — reject empty / whitespace-only inputs
@@ -1256,7 +1316,7 @@ export const fnNUMBERVALUE = args => {
     if (isNaN(n)) {
         return ERRORS.VALUE;
     }
-    return rvNumber(isPct ? n / 100 : n);
+    return rvNumber(pctCount > 0 ? n / Math.pow(100, pctCount) : n);
 };
 // ============================================================================
 // Excel 365 Text Functions: TEXTBEFORE, TEXTAFTER, TEXTSPLIT
@@ -1274,7 +1334,7 @@ export const fnNUMBERVALUE = args => {
 function parseTextBeforeAfterTail(args) {
     let inst = 1;
     if (args.length > 2) {
-        const instRV = toNumberRV(args[2]);
+        const instRV = toNumberRV(topLeft(args[2]));
         if (isError(instRV)) {
             return instRV;
         }
@@ -1282,7 +1342,7 @@ function parseTextBeforeAfterTail(args) {
     }
     let matchMode = 0;
     if (args.length > 3) {
-        const mmRV = toNumberRV(args[3]);
+        const mmRV = toNumberRV(topLeft(args[3]));
         if (isError(mmRV)) {
             return mmRV;
         }
@@ -1294,7 +1354,7 @@ function parseTextBeforeAfterTail(args) {
     }
     let matchEnd = 0;
     if (args.length > 4) {
-        const meRV = toNumberRV(args[4]);
+        const meRV = toNumberRV(topLeft(args[4]));
         if (isError(meRV)) {
             return meRV;
         }
@@ -1316,8 +1376,8 @@ export const fnTEXTBEFORE = args => {
     if (e1) {
         return e1;
     }
-    const text = toStringRV(args[0]);
-    const delimiter = toStringRV(args[1]);
+    const text = toStringRV(topLeft(args[0]));
+    const delimiter = toStringRV(topLeft(args[1]));
     const tail = parseTextBeforeAfterTail(args);
     if ("kind" in tail && tail.kind === RVKind.Error) {
         return tail;
@@ -1370,8 +1430,8 @@ export const fnTEXTAFTER = args => {
     if (e1) {
         return e1;
     }
-    const text = toStringRV(args[0]);
-    const delimiter = toStringRV(args[1]);
+    const text = toStringRV(topLeft(args[0]));
+    const delimiter = toStringRV(topLeft(args[1]));
     const tail = parseTextBeforeAfterTail(args);
     if ("kind" in tail && tail.kind === RVKind.Error) {
         return tail;
@@ -1416,21 +1476,21 @@ export const fnTEXTSPLIT = args => {
     if (e0) {
         return e0;
     }
-    const text = toStringRV(args[0]);
+    const text = toStringRV(topLeft(args[0]));
     let colDelimiter = "";
     if (args.length > 1) {
         const e1 = checkError(args[1]);
         if (e1) {
             return e1;
         }
-        colDelimiter = toStringRV(args[1]);
+        colDelimiter = toStringRV(topLeft(args[1]));
     }
-    const rowDelimiter = args.length > 2 && args[2].kind !== RVKind.Blank ? toStringRV(args[2]) : "";
+    const rowDelimiter = args.length > 2 && args[2].kind !== RVKind.Blank ? toStringRV(topLeft(args[2])) : "";
     // `ignore_empty` (4th arg, default FALSE) — when TRUE, suppress empty
     // fragments produced by consecutive delimiters.
     let ignoreEmpty = false;
     if (args.length > 3 && args[3].kind !== RVKind.Blank) {
-        const ieRV = toBooleanRV(args[3]);
+        const ieRV = toBooleanRV(topLeft(args[3]));
         if (isError(ieRV)) {
             return ieRV;
         }
@@ -1442,7 +1502,7 @@ export const fnTEXTSPLIT = args => {
     // consistent with Excel's specification for TEXTSPLIT.
     let matchMode = 0;
     if (args.length > 4 && args[4].kind !== RVKind.Blank) {
-        const mmRV = toNumberRV(args[4]);
+        const mmRV = toNumberRV(topLeft(args[4]));
         if (isError(mmRV)) {
             return mmRV;
         }

package/dist/browser/modules/formula/integration/calculate-formulas-impl.js

@@ -168,10 +168,29 @@ export function calculateFormulasImpl(workbook) {
     let evalOrder = topologicalSort(graph);
     // ── Step 6: Evaluate ──
     const session = new EvalSession();
+    // Convert user-registered functions (keyed opaquely on WorkbookLike)
+    // into the evaluator's typed `FunctionDescriptor` shape. We take a
+    // snapshot up front so later mutations to the workbook's map during
+    // evaluation can't observe a half-built state.
+    let userFunctions;
+    if (workbook.userFunctions && workbook.userFunctions.size > 0) {
+        const adapted = new Map();
+        for (const [name, desc] of workbook.userFunctions) {
+            const upperName = name.toUpperCase();
+            adapted.set(upperName, {
+                name: upperName,
+                minArity: desc.minArity,
+                maxArity: desc.maxArity,
+                invoke: desc.invoke
+            });
+        }
+        userFunctions = adapted;
+    }
     const ctx = {
         snapshot,
         compiledFormulas: compiledMap,
-        currentSheet: snapshot.worksheets[0]?.name ?? ""
+        currentSheet: snapshot.worksheets[0]?.name ?? "",
+        userFunctions
     };
     // Evaluate in topological order
     evaluateInOrder(evalOrder, compiledMap, results, ctx, session);

package/dist/browser/modules/formula/materialize/build-writeback-plan.js

@@ -51,6 +51,13 @@ export function buildWritebackPlan(snapshot, compiled, results, previousSpills,
     // Build ghost map from previous spills (validated against snapshot)
     const ghostMap = new Map();
     for (const [srcKey, region] of previousSpills) {
+        // Hoist the worksheet lookup once per region — the previous code did
+        // `snapshot.worksheetsById.get(…)` inside the inner cell loop,
+        // paying the Map lookup cost `region.rows × region.cols` times.
+        const ws = snapshot.worksheetsById.get(region.worksheetId);
+        if (!ws) {
+            continue;
+        }
         for (let r = 0; r < region.rows; r++) {
             for (let c = 0; c < region.cols; c++) {
                 if (r === 0 && c === 0) {
@@ -60,12 +67,9 @@ export function buildWritebackPlan(snapshot, compiled, results, previousSpills,
                 const targetCol = region.sourceCol + c;
                 const targetKey = spillCellKeyFromId(region.worksheetId, targetRow, targetCol);
                 // Validate ghost cell is still unmodified
-                const ws = snapshot.worksheetsById.get(region.worksheetId);
-                if (ws) {
-                    const cell = ws.cells.get(snapshotCellKey(targetRow, targetCol));
-                    if (isGhostUnmodified(cell, targetKey, previousGhosts)) {
-                        ghostMap.set(targetKey, srcKey);
-                    }
+                const cell = ws.cells.get(snapshotCellKey(targetRow, targetCol));
+                if (isGhostUnmodified(cell, targetKey, previousGhosts)) {
+                    ghostMap.set(targetKey, srcKey);
                 }
             }
         }

package/dist/browser/modules/formula/materialize/types.d.ts

@@ -159,6 +159,21 @@ export interface WorkbookLike {
     properties?: {
         date1904?: boolean;
     };
+    /**
+     * User-registered custom functions exposed to the formula engine.
+     * Keys are uppercase canonical names; values are arity + invoke
+     * descriptors. When the evaluator encounters a call it consults this
+     * map before the global built-in registry, so users can shadow a
+     * built-in (e.g. replace `IRR` with a domain-specific variant) or
+     * add entirely new names.
+     */
+    userFunctions?: ReadonlyMap<string, {
+        minArity: number;
+        maxArity: number;
+        invoke: (args: unknown[]) => unknown;
+        /** Reserved for future volatile-function wiring. */
+        volatile?: boolean;
+    }>;
 }
 /**
  * Tracks a spill region: the source formula cell and the range of cells it

package/dist/browser/modules/formula/runtime/evaluator.d.ts

@@ -8,6 +8,7 @@
 import type { BoundExpr } from "../compile/bound-ast.js";
 import type { CompiledFormula } from "../compile/compiled-formula.js";
 import type { WorkbookSnapshot } from "../integration/workbook-snapshot.js";
+import type { FunctionDescriptor } from "./function-registry.js";
 import type { RuntimeValue } from "./values.js";
 /**
  * Cached formula evaluation result with both scalar and raw forms.
@@ -114,6 +115,13 @@ export interface EvalContext {
     };
     /** Local variable bindings from LET expressions. */
     localBindings?: Map<string, RuntimeValue>;
+    /**
+     * User-registered functions that take precedence over the built-in
+     * registry. Lookup happens in `evaluateCall` — a matching
+     * descriptor here shadows any built-in of the same name. Keys are
+     * canonical uppercase names (prefix-stripped on register).
+     */
+    readonly userFunctions?: ReadonlyMap<string, FunctionDescriptor>;
 }
 /**
  * Evaluate a BoundExpr to produce a RuntimeValue.