@cj-tech-master/excelts 9.3.1 → 9.4.0

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

@@ -3,8 +3,8 @@
  * Math / Aggregate Functions — Native RuntimeValue implementation.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.fnTRUNC = exports.fnSIGN = exports.fnRANDBETWEEN = exports.fnRAND = exports.fnPI = exports.fnEXP = exports.fnLOG10 = exports.fnLOG = exports.fnLN = exports.fnSQRTPI = exports.fnSQRT = exports.fnROUNDUP = exports.fnROUNDDOWN = exports.fnROUND = exports.fnPOWER = exports.fnMOD = exports.fnINT = exports.fnFLOOR = exports.fnCEILING = exports.fnABS = exports.fnSUMPRODUCT = exports.fnPRODUCT = exports.fnCOUNTBLANK = exports.fnCOUNTA = exports.fnCOUNT = exports.fnMAX = exports.fnMIN = exports.fnAVERAGE = exports.fnSUM = exports.fnACOTH = exports.fnACOT = exports.fnCOTH = exports.fnCSCH = exports.fnSECH = exports.fnCOT = exports.fnCSC = exports.fnSEC = exports.fnATANH = exports.fnACOSH = exports.fnASINH = exports.fnTANH = exports.fnCOSH = exports.fnSINH = exports.fnATAN2 = exports.fnATAN = exports.fnACOS = exports.fnASIN = exports.fnTAN = exports.fnCOS = exports.fnSIN = void 0;
-exports.fnSERIESSUM = exports.fnMUNIT = exports.fnMINVERSE = exports.fnMDETERM = exports.fnMMULT = exports.fnPERMUT = exports.fnCOMBINA = exports.fnCOMBIN = exports.fnFACTDOUBLE = exports.fnFACT = exports.fnMULTINOMIAL = exports.fnSUMXMY2 = exports.fnSUMX2PY2 = exports.fnSUMX2MY2 = exports.fnRADIANS = exports.fnDEGREES = exports.fnARABIC = exports.fnROMAN = exports.fnDECIMAL = exports.fnBASE = exports.fnQUOTIENT = exports.fnMROUND = exports.fnODD = exports.fnEVEN = exports.fnLCM = exports.fnGCD = exports.fnSUMSQ = void 0;
+exports.fnPI = exports.fnEXP = exports.fnLOG10 = exports.fnLOG = exports.fnLN = exports.fnSQRTPI = exports.fnSQRT = exports.fnROUNDUP = exports.fnROUNDDOWN = exports.fnROUND = exports.fnPOWER = exports.fnMOD = exports.fnINT = exports.fnFLOOR_PRECISE = exports.fnFLOOR_MATH = exports.fnFLOOR = exports.fnCEILING_PRECISE = exports.fnCEILING_MATH = exports.fnCEILING = exports.fnABS = exports.fnSUMPRODUCT = exports.fnPRODUCT = exports.fnCOUNTBLANK = exports.fnCOUNTA = exports.fnCOUNT = exports.fnMAX = exports.fnMIN = exports.fnAVERAGE = exports.fnSUM = exports.fnACOTH = exports.fnACOT = exports.fnCOTH = exports.fnCSCH = exports.fnSECH = exports.fnCOT = exports.fnCSC = exports.fnSEC = exports.fnATANH = exports.fnACOSH = exports.fnASINH = exports.fnTANH = exports.fnCOSH = exports.fnSINH = exports.fnATAN2 = exports.fnATAN = exports.fnACOS = exports.fnASIN = exports.fnTAN = exports.fnCOS = exports.fnSIN = void 0;
+exports.fnSERIESSUM = exports.fnMUNIT = exports.fnMINVERSE = exports.fnMDETERM = exports.fnMMULT = exports.fnPERMUT = exports.fnCOMBINA = exports.fnCOMBIN = exports.fnFACTDOUBLE = exports.fnFACT = exports.fnMULTINOMIAL = exports.fnSUMXMY2 = exports.fnSUMX2PY2 = exports.fnSUMX2MY2 = exports.fnRADIANS = exports.fnDEGREES = exports.fnARABIC = exports.fnROMAN = exports.fnDECIMAL = exports.fnBASE = exports.fnQUOTIENT = exports.fnMROUND = exports.fnODD = exports.fnEVEN = exports.fnLCM = exports.fnGCD = exports.fnSUMSQ = exports.fnTRUNC = exports.fnSIGN = exports.fnRANDBETWEEN = exports.fnRAND = void 0;
 const values_1 = require("../runtime/values");
 const _shared_1 = require("./_shared");
 // ============================================================================
@@ -275,15 +275,13 @@ exports.fnACOTH = fnACOTH;
 // Math / Aggregate Functions
 // ============================================================================
 const fnSUM = args => {
-    const nums = (0, _shared_1.flattenNumbers)(args);
-    const err = (0, _shared_1.firstError)(nums);
+    let sum = 0;
+    const err = (0, _shared_1.forEachNumber)(args, n => {
+        sum += n;
+    });
     if (err) {
         return err;
     }
-    let sum = 0;
-    for (const n of nums) {
-        sum += n.value;
-    }
     // Fail fast on overflow to Infinity; otherwise the result leaks into
     // any formula that aggregates it (AVERAGE, STDEV, etc.) and those
     // downstream callers would then fan #NUM! out across the graph.
@@ -291,64 +289,88 @@ const fnSUM = args => {
 };
 exports.fnSUM = fnSUM;
 const fnAVERAGE = args => {
-    const nums = (0, _shared_1.flattenNumbers)(args);
-    const err = (0, _shared_1.firstError)(nums);
+    let sum = 0;
+    let count = 0;
+    const err = (0, _shared_1.forEachNumber)(args, n => {
+        sum += n;
+        count++;
+    });
     if (err) {
         return err;
     }
-    if (nums.length === 0) {
+    if (count === 0) {
         return values_1.ERRORS.DIV0;
     }
-    let sum = 0;
-    for (const n of nums) {
-        sum += n.value;
-    }
-    const avg = sum / nums.length;
+    const avg = sum / count;
     return Number.isFinite(avg) ? (0, values_1.rvNumber)(avg) : values_1.ERRORS.NUM;
 };
 exports.fnAVERAGE = fnAVERAGE;
 const fnMIN = args => {
-    const nums = (0, _shared_1.flattenNumbers)(args);
-    const err = (0, _shared_1.firstError)(nums);
-    if (err) {
-        return err;
-    }
-    if (nums.length === 0) {
-        return (0, values_1.rvNumber)(0);
-    }
     let min = Infinity;
-    for (const n of nums) {
-        if (n.value < min) {
-            min = n.value;
+    let seen = false;
+    const err = (0, _shared_1.forEachNumber)(args, n => {
+        seen = true;
+        if (n < min) {
+            min = n;
         }
+    });
+    if (err) {
+        return err;
     }
-    return (0, values_1.rvNumber)(min);
+    return seen ? (0, values_1.rvNumber)(min) : (0, values_1.rvNumber)(0);
 };
 exports.fnMIN = fnMIN;
 const fnMAX = args => {
-    const nums = (0, _shared_1.flattenNumbers)(args);
-    const err = (0, _shared_1.firstError)(nums);
-    if (err) {
-        return err;
-    }
-    if (nums.length === 0) {
-        return (0, values_1.rvNumber)(0);
-    }
     let max = -Infinity;
-    for (const n of nums) {
-        if (n.value > max) {
-            max = n.value;
+    let seen = false;
+    const err = (0, _shared_1.forEachNumber)(args, n => {
+        seen = true;
+        if (n > max) {
+            max = n;
         }
+    });
+    if (err) {
+        return err;
     }
-    return (0, values_1.rvNumber)(max);
+    return seen ? (0, values_1.rvNumber)(max) : (0, values_1.rvNumber)(0);
 };
 exports.fnMAX = fnMAX;
 const fnCOUNT = args => {
+    // Excel's rules — intentionally asymmetric:
+    //   - Number cell / scalar → counted (direct + inside array).
+    //   - Numeric-string DIRECT scalar (`COUNT("5")`) → counted. Inside
+    //     an array, numeric strings are NOT counted.
+    //   - Boolean / non-numeric string / blank / error → NOT counted in
+    //     any context (diverges from COUNTA which counts booleans).
+    // Previously the engine flattened everything through `topLeft` and
+    // only accepted `Number` — which meant `COUNT("5")` returned 0.
     let count = 0;
-    const all = (0, _shared_1.flattenAll)(args);
-    for (const v of all) {
-        if (v.kind === 1 /* RVKind.Number */) {
-            count++;
+    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 === 1 /* RVKind.Number */) {
+                        count++;
+                    }
+                }
+            }
+        }
+        else {
+            const s = (0, values_1.topLeft)(arg);
+            if (s.kind === 1 /* RVKind.Number */) {
+                count++;
+            }
+            else if (s.kind === 2 /* RVKind.String */) {
+                // Numeric strings (including `"5"`, `"3.14"`, `"1e3"`) are
+                // counted when supplied as direct scalars. Non-numeric text
+                // is silently skipped. Route through `toNumberRV` so the same
+                // parser that `VALUE()` uses decides.
+                const nr = (0, values_1.toNumberRV)(s);
+                if (nr.kind === 1 /* RVKind.Number */) {
+                    count++;
+                }
+            }
+            // Blank, Boolean, Error, Reference, Lambda → skipped.
         }
     }
     return (0, values_1.rvNumber)(count);
@@ -358,8 +380,12 @@ const fnCOUNTA = args => {
     let count = 0;
     const all = (0, _shared_1.flattenAll)(args);
     for (const v of all) {
-        // Count everything that is not blank and not empty string
-        if (v.kind !== 0 /* RVKind.Blank */ && !(v.kind === 2 /* RVKind.String */ && v.value === "")) {
+        // Excel: COUNTA counts every non-blank cell, INCLUDING cells that
+        // hold an empty string (e.g. a formula that returned `=""`). Only
+        // the fully-blank kind is excluded. Previously we also excluded
+        // empty strings — that matched Google Sheets but diverged from
+        // Excel's documented behaviour.
+        if (v.kind !== 0 /* RVKind.Blank */) {
             count++;
         }
     }
@@ -370,6 +396,11 @@ const fnCOUNTBLANK = args => {
     let count = 0;
     const all = (0, _shared_1.flattenAll)(args);
     for (const v of all) {
+        // Excel: COUNTBLANK counts both truly-blank cells and cells
+        // containing an empty string result (e.g. `=""`). This is
+        // intentionally asymmetric with COUNTA — COUNTA+COUNTBLANK can
+        // legitimately exceed the total cell count when `=""` formulas
+        // are present, matching Excel's documented behaviour.
         if (v.kind === 0 /* RVKind.Blank */ || (v.kind === 2 /* RVKind.String */ && v.value === "")) {
             count++;
         }
@@ -378,18 +409,18 @@ const fnCOUNTBLANK = args => {
 };
 exports.fnCOUNTBLANK = fnCOUNTBLANK;
 const fnPRODUCT = args => {
-    const nums = (0, _shared_1.flattenNumbers)(args);
-    const err = (0, _shared_1.firstError)(nums);
+    let product = 1;
+    let seen = false;
+    const err = (0, _shared_1.forEachNumber)(args, n => {
+        product *= n;
+        seen = true;
+    });
     if (err) {
         return err;
     }
-    if (nums.length === 0) {
+    if (!seen) {
         return (0, values_1.rvNumber)(0);
     }
-    let product = 1;
-    for (const n of nums) {
-        product *= n.value;
-    }
     // Excel surfaces an overflow as #NUM! rather than letting Infinity
     // propagate into subsequent arithmetic.
     return isFinite(product) ? (0, values_1.rvNumber)(product) : values_1.ERRORS.NUM;
@@ -428,13 +459,23 @@ const fnSUMPRODUCT = args => {
             }
         }
     }
+    // Hoist per-array broadcast classification and row-shape out of the
+    // hot (r, c) loop — the shape is constant across all cells, but the
+    // previous code re-inspected `arr.height === 1 && arr.width === 1`
+    // per cell (arrays.length × rows × cols times).
+    const arrayCount = arrays.length;
+    const broadcasts = new Array(arrayCount);
+    for (let i = 0; i < arrayCount; i++) {
+        const arr = arrays[i];
+        broadcasts[i] = arr.height === 1 && arr.width === 1;
+    }
     let sum = 0;
     for (let r = 0; r < rows; r++) {
         for (let c = 0; c < cols; c++) {
             let product = 1;
-            for (const arr of arrays) {
-                // Broadcast 1x1 arrays to the target cell position.
-                const val = arr.height === 1 && arr.width === 1 ? arr.rows[0][0] : arr.rows[r][c];
+            for (let i = 0; i < arrayCount; i++) {
+                const arr = arrays[i];
+                const val = broadcasts[i] ? arr.rows[0][0] : arr.rows[r][c];
                 if (val.kind === 4 /* RVKind.Error */) {
                     return val;
                 }
@@ -486,6 +527,68 @@ const fnCEILING = args => {
     return (0, values_1.rvNumber)(Math.ceil(num.value / sig) * sig);
 };
 exports.fnCEILING = fnCEILING;
+/**
+ * CEILING.MATH(number, [significance], [mode]) — rounds away from zero
+ * by default, or toward zero when `mode` is non-zero AND `number` is
+ * negative. Significance is always interpreted by absolute value.
+ *
+ * Different from CEILING: negative numbers with positive significance
+ * are valid (Excel does NOT require same sign), and there is an extra
+ * `mode` switch that flips the rounding direction for negatives.
+ */
+const fnCEILING_MATH = args => {
+    const num = (0, _shared_1.argToNumber)(args[0]);
+    if ((0, values_1.isError)(num)) {
+        return num;
+    }
+    // Blank `significance` → Excel default 1 (for positive num) or -1
+    // (for negative num); either way |sig| = 1. Use 1 explicitly since
+    // the algorithm below works on `Math.abs(sig)`.
+    const sigRV = args.length > 1 && args[1].kind !== 0 /* RVKind.Blank */ ? (0, _shared_1.argToNumber)(args[1]) : (0, values_1.rvNumber)(1);
+    if ((0, values_1.isError)(sigRV)) {
+        return sigRV;
+    }
+    const sigAbs = Math.abs(sigRV.value);
+    if (sigAbs === 0) {
+        return (0, values_1.rvNumber)(0);
+    }
+    const modeRV = args.length > 2 && args[2].kind !== 0 /* RVKind.Blank */ ? (0, _shared_1.argToNumber)(args[2]) : (0, values_1.rvNumber)(0);
+    if ((0, values_1.isError)(modeRV)) {
+        return modeRV;
+    }
+    // Round away from zero by default; toward zero when `mode` is non-zero
+    // AND the number is negative. For positive numbers `mode` has no effect.
+    if (num.value >= 0) {
+        return (0, values_1.rvNumber)(Math.ceil(num.value / sigAbs) * sigAbs);
+    }
+    if (modeRV.value !== 0) {
+        // Round away from zero (toward −∞) for negatives: use `Math.floor`.
+        return (0, values_1.rvNumber)(Math.floor(num.value / sigAbs) * sigAbs);
+    }
+    // Default: round toward zero for negatives.
+    return (0, values_1.rvNumber)(Math.ceil(num.value / sigAbs) * sigAbs);
+};
+exports.fnCEILING_MATH = fnCEILING_MATH;
+/**
+ * CEILING.PRECISE / ISO.CEILING — always rounds toward +∞ (irrespective
+ * of sign), using the absolute value of significance.
+ */
+const fnCEILING_PRECISE = args => {
+    const num = (0, _shared_1.argToNumber)(args[0]);
+    if ((0, values_1.isError)(num)) {
+        return num;
+    }
+    const sigRV = args.length > 1 && args[1].kind !== 0 /* RVKind.Blank */ ? (0, _shared_1.argToNumber)(args[1]) : (0, values_1.rvNumber)(1);
+    if ((0, values_1.isError)(sigRV)) {
+        return sigRV;
+    }
+    const sigAbs = Math.abs(sigRV.value);
+    if (sigAbs === 0) {
+        return (0, values_1.rvNumber)(0);
+    }
+    return (0, values_1.rvNumber)(Math.ceil(num.value / sigAbs) * sigAbs);
+};
+exports.fnCEILING_PRECISE = fnCEILING_PRECISE;
 const fnFLOOR = args => {
     const num = (0, _shared_1.argToNumber)(args[0]);
     if ((0, values_1.isError)(num)) {
@@ -505,6 +608,60 @@ const fnFLOOR = args => {
     return (0, values_1.rvNumber)(Math.floor(num.value / sig) * sig);
 };
 exports.fnFLOOR = fnFLOOR;
+/**
+ * FLOOR.MATH(number, [significance], [mode]) — rounds toward zero by
+ * default, or away from zero when `mode` is non-zero AND `number` is
+ * negative. Uses `|significance|` so negative significance never
+ * produces #NUM!.
+ */
+const fnFLOOR_MATH = args => {
+    const num = (0, _shared_1.argToNumber)(args[0]);
+    if ((0, values_1.isError)(num)) {
+        return num;
+    }
+    const sigRV = args.length > 1 && args[1].kind !== 0 /* RVKind.Blank */ ? (0, _shared_1.argToNumber)(args[1]) : (0, values_1.rvNumber)(1);
+    if ((0, values_1.isError)(sigRV)) {
+        return sigRV;
+    }
+    const sigAbs = Math.abs(sigRV.value);
+    if (sigAbs === 0) {
+        return (0, values_1.rvNumber)(0);
+    }
+    const modeRV = args.length > 2 && args[2].kind !== 0 /* RVKind.Blank */ ? (0, _shared_1.argToNumber)(args[2]) : (0, values_1.rvNumber)(0);
+    if ((0, values_1.isError)(modeRV)) {
+        return modeRV;
+    }
+    // Positive numbers always round toward zero (down). Negative numbers
+    // default to rounding away from zero (down = further negative); `mode`
+    // non-zero flips to rounding toward zero.
+    if (num.value >= 0) {
+        return (0, values_1.rvNumber)(Math.floor(num.value / sigAbs) * sigAbs);
+    }
+    if (modeRV.value !== 0) {
+        return (0, values_1.rvNumber)(Math.ceil(num.value / sigAbs) * sigAbs);
+    }
+    return (0, values_1.rvNumber)(Math.floor(num.value / sigAbs) * sigAbs);
+};
+exports.fnFLOOR_MATH = fnFLOOR_MATH;
+/**
+ * FLOOR.PRECISE — always rounds toward −∞ using `|significance|`.
+ */
+const fnFLOOR_PRECISE = args => {
+    const num = (0, _shared_1.argToNumber)(args[0]);
+    if ((0, values_1.isError)(num)) {
+        return num;
+    }
+    const sigRV = args.length > 1 && args[1].kind !== 0 /* RVKind.Blank */ ? (0, _shared_1.argToNumber)(args[1]) : (0, values_1.rvNumber)(1);
+    if ((0, values_1.isError)(sigRV)) {
+        return sigRV;
+    }
+    const sigAbs = Math.abs(sigRV.value);
+    if (sigAbs === 0) {
+        return (0, values_1.rvNumber)(0);
+    }
+    return (0, values_1.rvNumber)(Math.floor(num.value / sigAbs) * sigAbs);
+};
+exports.fnFLOOR_PRECISE = fnFLOOR_PRECISE;
 const fnINT = args => {
     const n = (0, _shared_1.argToNumber)(args[0]);
     return (0, values_1.isError)(n) ? n : (0, values_1.rvNumber)(Math.floor(n.value));
@@ -639,7 +796,11 @@ const fnLOG = args => {
     if (n.value <= 0) {
         return values_1.ERRORS.NUM;
     }
-    const baseRV = args.length > 1 ? (0, _shared_1.argToNumber)(args[1]) : (0, values_1.rvNumber)(10);
+    // Blank 2nd arg → default base 10. Without this guard, `LOG(100, )`
+    // coerces blank → 0 via argToNumber and falls into the `<= 0` branch,
+    // incorrectly returning #NUM!. Excel treats the omitted / blank slot
+    // as "use the default".
+    const baseRV = args.length > 1 && args[1].kind !== 0 /* RVKind.Blank */ ? (0, _shared_1.argToNumber)(args[1]) : (0, values_1.rvNumber)(10);
     if ((0, values_1.isError)(baseRV)) {
         return baseRV;
     }
@@ -722,15 +883,13 @@ const fnTRUNC = args => {
 };
 exports.fnTRUNC = fnTRUNC;
 const fnSUMSQ = args => {
-    const nums = (0, _shared_1.flattenNumbers)(args);
-    const err = (0, _shared_1.firstError)(nums);
+    let sum = 0;
+    const err = (0, _shared_1.forEachNumber)(args, n => {
+        sum += n * n;
+    });
     if (err) {
         return err;
     }
-    let sum = 0;
-    for (const n of nums) {
-        sum += n.value ** 2;
-    }
     return isFinite(sum) ? (0, values_1.rvNumber)(sum) : values_1.ERRORS.NUM;
 };
 exports.fnSUMSQ = fnSUMSQ;
@@ -888,12 +1047,24 @@ const fnBASE = args => {
     if (radix.value < 2 || radix.value > 36) {
         return values_1.ERRORS.NUM;
     }
+    // Excel's BASE requires `num` in `[0, 2^53)`. Negative inputs produce
+    // a `-` prefix via JS `.toString(radix)` — Excel rejects them. Very
+    // large inputs exceed the precise integer range and would corrupt the
+    // lower digits; Excel reports #NUM! there too.
+    if (num.value < 0 || num.value >= 2 ** 53) {
+        return values_1.ERRORS.NUM;
+    }
     const minLenRV = args.length > 2 ? (0, _shared_1.argToNumber)(args[2]) : (0, values_1.rvNumber)(0);
     if ((0, values_1.isError)(minLenRV)) {
         return minLenRV;
     }
+    // `minLen` must be in `[0, 255]`; Excel rejects larger widths.
+    const minLen = Math.trunc(minLenRV.value);
+    if (minLen < 0 || minLen > 255) {
+        return values_1.ERRORS.NUM;
+    }
     const result = Math.floor(num.value).toString(Math.floor(radix.value)).toUpperCase();
-    return (0, values_1.rvString)(minLenRV.value > 0 ? result.padStart(minLenRV.value, "0") : result);
+    return (0, values_1.rvString)(minLen > 0 ? result.padStart(minLen, "0") : result);
 };
 exports.fnBASE = fnBASE;
 const fnDECIMAL = args => {
@@ -961,10 +1132,10 @@ const fnROMAN = args => {
         if ((0, values_1.isError)(f)) {
             return f;
         }
-        if (f.value === 1 && f.value === 1) {
-            // Boolean inputs flow through argToNumber as 0/1 already.
-        }
-        form = Math.floor(f.value);
+        // Excel accepts TRUE/FALSE and 0..4 for `form`. argToNumber already
+        // coerces booleans to 0/1, so nothing extra is needed here — we
+        // just truncate toward zero and bounds-check.
+        form = Math.trunc(f.value);
         if (form < 0 || form > 4) {
             return values_1.ERRORS.VALUE;
         }
@@ -1070,8 +1241,15 @@ function sumPairedArrays(args, combine) {
     if (a0.kind !== 5 /* RVKind.Array */ || a1.kind !== 5 /* RVKind.Array */) {
         return values_1.ERRORS.VALUE;
     }
-    const h = Math.min(a0.height, a1.height);
-    const w = Math.min(a0.width, a1.width);
+    // Excel requires matching shapes — `SUMX2MY2`/`SUMX2PY2`/`SUMXMY2`
+    // return `#N/A` when the two arrays have different cell counts.
+    // Previously we silently clamped to the min, producing a numeric
+    // result that quietly dropped the tail of the longer array.
+    if (a0.height !== a1.height || a0.width !== a1.width) {
+        return values_1.ERRORS.NA;
+    }
+    const h = a0.height;
+    const w = a0.width;
     let sum = 0;
     for (let r = 0; r < h; r++) {
         for (let c = 0; c < w; c++) {
@@ -1241,6 +1419,12 @@ const fnPERMUT = args => {
     let result = 1;
     for (let i = 0; i < ki; i++) {
         result *= ni - i;
+        // Excel surfaces an overflow as #NUM! rather than silently persisting
+        // Infinity. Without this guard `PERMUT(200, 50)` returns Infinity
+        // which then poisons every formula that references the cell.
+        if (!Number.isFinite(result)) {
+            return values_1.ERRORS.NUM;
+        }
     }
     return (0, values_1.rvNumber)(result);
 };