@cj-tech-master/excelts 9.3.1 → 9.4.0

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

@@ -78,16 +78,14 @@ function quickselect(arr, k) {
     return arr[k];
 }
 const fnMEDIAN = args => {
-    const nums = (0, _shared_1.flattenNumbers)(args);
-    const err = (0, _shared_1.firstError)(nums);
-    if (err) {
-        return err;
+    const values = toNumberArray(args);
+    if (!Array.isArray(values)) {
+        return values;
     }
-    if (nums.length === 0) {
+    const n = values.length;
+    if (n === 0) {
         return values_1.ERRORS.NUM;
     }
-    const values = nums.map(n => n.value);
-    const n = values.length;
     const mid = n >> 1;
     if (n % 2 !== 0) {
         return (0, values_1.rvNumber)(quickselect(values, mid));
@@ -119,6 +117,12 @@ const fnLARGE = args => {
     // with the same shape where each cell holds LARGE at that k.
     if (args[1].kind === 5 /* RVKind.Array */) {
         const kArr = args[1];
+        // Sort once when the array contains more than a single cell — k is
+        // O(1) afterwards. quickselect per-cell would allocate a fresh
+        // `values.slice()` for every k, which quickly becomes quadratic
+        // when LARGE(A1:A100, {1;2;3;…}) evaluates over long ranges.
+        const totalCells = kArr.height * kArr.width;
+        const sortedDesc = totalCells > 1 ? values.slice().sort((a, b) => b - a) : null;
         const outRows = [];
         for (const row of kArr.rows) {
             const outRow = [];
@@ -137,10 +141,13 @@ const fnLARGE = args => {
                     outRow.push(values_1.ERRORS.NUM);
                     continue;
                 }
-                // k-th largest == (n − k)-th smallest. Use a copy — quickselect
-                // mutates the array it works on, and we need a fresh view for
-                // every cell in the output.
-                outRow.push((0, values_1.rvNumber)(quickselect(values.slice(), values.length - kInt)));
+                if (sortedDesc) {
+                    outRow.push((0, values_1.rvNumber)(sortedDesc[kInt - 1]));
+                }
+                else {
+                    // Single-cell k — quickselect is cheaper than a full sort.
+                    outRow.push((0, values_1.rvNumber)(quickselect(values.slice(), values.length - kInt)));
+                }
             }
             outRows.push(outRow);
         }
@@ -166,6 +173,10 @@ const fnSMALL = args => {
     const values = nums.map(n => n.value);
     if (args[1].kind === 5 /* RVKind.Array */) {
         const kArr = args[1];
+        // Multi-cell k → sort once ascending, index in O(1). See LARGE for
+        // the same optimisation and rationale.
+        const totalCells = kArr.height * kArr.width;
+        const sortedAsc = totalCells > 1 ? values.slice().sort((a, b) => a - b) : null;
         const outRows = [];
         for (const row of kArr.rows) {
             const outRow = [];
@@ -184,7 +195,12 @@ const fnSMALL = args => {
                     outRow.push(values_1.ERRORS.NUM);
                     continue;
                 }
-                outRow.push((0, values_1.rvNumber)(quickselect(values.slice(), kInt - 1)));
+                if (sortedAsc) {
+                    outRow.push((0, values_1.rvNumber)(sortedAsc[kInt - 1]));
+                }
+                else {
+                    outRow.push((0, values_1.rvNumber)(quickselect(values.slice(), kInt - 1)));
+                }
             }
             outRows.push(outRow);
         }
@@ -238,30 +254,39 @@ exports.fnRANK = fnRANK;
  * Returns `null` when there is no data at all (callers decide whether that
  * should be `#DIV/0!` or zero given the sample/population convention).
  */
+/**
+ * Single-pass mean + sum-of-squared-deviations using Welford's online
+ * algorithm. Returns `null` when the array is empty.
+ *
+ * Welford's recurrence keeps the sum of squared deviations numerically
+ * stable (avoids the catastrophic cancellation that bites
+ * `Σx² - (Σx)²/n` for datasets with a large mean and small variance).
+ * Costs one pass rather than two — meaningful on multi-thousand-cell
+ * ranges feeding STDEV / VAR / their variants.
+ */
 function computeMeanAndSumSq(nums) {
     const n = nums.length;
     if (n === 0) {
         return null;
     }
-    let sum = 0;
-    for (const v of nums) {
-        sum += v;
-    }
-    const mean = sum / n;
+    let mean = 0;
     let sumSq = 0;
-    for (const v of nums) {
-        sumSq += (v - mean) ** 2;
+    for (let i = 0; i < n; i++) {
+        const x = nums[i];
+        const delta = x - mean;
+        mean += delta / (i + 1);
+        // `x - mean` uses the *updated* mean — this product form is the
+        // identity that makes Welford's recurrence equal the second-pass
+        // `(x - final_mean)²` sum exactly.
+        sumSq += delta * (x - mean);
     }
     return { n, mean, sumSq };
 }
 /** Resolve {args} to `number[]` or an error. Shared by STDEV/VAR family. */
 function toNumberArray(args) {
-    const rawNums = (0, _shared_1.flattenNumbers)(args);
-    const err = (0, _shared_1.firstError)(rawNums);
-    if (err) {
-        return err;
-    }
-    return rawNums.map(n => n.value);
+    const out = [];
+    const err = (0, _shared_1.forEachNumber)(args, n => out.push(n));
+    return err ?? out;
 }
 const fnSTDEV = args => {
     const nums = toNumberArray(args);
@@ -470,9 +495,16 @@ exports.fnNORMINV = fnNORMINV;
 // PERCENTILE, QUARTILE, MODE
 // ============================================================================
 const fnPERCENTILE = args => {
-    const nums = (0, _shared_1.flattenNumbers)([args[0]])
-        .filter((v) => v.kind === 1 /* RVKind.Number */)
-        .map(n => n.value);
+    // Propagate errors from within the range — `flattenNumbers` returns
+    // both numbers and errors, and previously we silently filtered errors
+    // out by `.kind === Number`, producing a bogus percentile on ranges
+    // that contained `#N/A`. Surface the error like AVERAGE / SUM do.
+    const raw = (0, _shared_1.flattenNumbers)([args[0]]);
+    const err = (0, _shared_1.firstError)(raw);
+    if (err) {
+        return err;
+    }
+    const nums = raw.map(n => n.value);
     const k = (0, _shared_1.argToNumber)(args[1]);
     if (k.kind === 4 /* RVKind.Error */) {
         return k;
@@ -493,9 +525,12 @@ const fnPERCENTILE = args => {
 };
 exports.fnPERCENTILE = fnPERCENTILE;
 const fnPERCENTILEEXC = args => {
-    const nums = (0, _shared_1.flattenNumbers)([args[0]])
-        .filter((v) => v.kind === 1 /* RVKind.Number */)
-        .map(n => n.value);
+    const raw = (0, _shared_1.flattenNumbers)([args[0]]);
+    const err = (0, _shared_1.firstError)(raw);
+    if (err) {
+        return err;
+    }
+    const nums = raw.map(n => n.value);
     const k = (0, _shared_1.argToNumber)(args[1]);
     if (k.kind === 4 /* RVKind.Error */) {
         return k;
@@ -610,20 +645,48 @@ exports.fnMODE_MULT = fnMODE_MULT;
  * Returns the shorter prefix-length pair aligned by position.
  */
 function pairedNumbers(args, aIdx, bIdx) {
-    const flatA = (0, _shared_1.flattenNumbers)([args[aIdx]]);
-    const errA = (0, _shared_1.firstError)(flatA);
-    if (errA) {
-        return errA;
-    }
-    const flatB = (0, _shared_1.flattenNumbers)([args[bIdx]]);
-    const errB = (0, _shared_1.firstError)(flatB);
-    if (errB) {
-        return errB;
-    }
-    const xs = flatA.filter((v) => v.kind === 1 /* RVKind.Number */).map(n => n.value);
-    const ys = flatB.filter((v) => v.kind === 1 /* RVKind.Number */).map(n => n.value);
-    const n = Math.min(xs.length, ys.length);
-    return { xs: xs.slice(0, n), ys: ys.slice(0, n) };
+    // Walk both ranges in lockstep so the x/y pairing preserves the
+    // source position. Excel's CORREL / SLOPE / INTERCEPT skip any pair
+    // where either side is non-numeric (text, blank, boolean) — they do
+    // NOT drop the non-numeric cells from one side and then pair by
+    // surviving position, which would realign unrelated values.
+    const aArg = args[aIdx];
+    const bArg = args[bIdx];
+    const aCells = [];
+    const bCells = [];
+    collectCells(aArg, aCells);
+    collectCells(bArg, bCells);
+    const xs = [];
+    const ys = [];
+    const n = Math.min(aCells.length, bCells.length);
+    for (let i = 0; i < n; i++) {
+        const a = aCells[i];
+        const b = bCells[i];
+        if (a.kind === 4 /* RVKind.Error */) {
+            return a;
+        }
+        if (b.kind === 4 /* RVKind.Error */) {
+            return b;
+        }
+        if (a.kind === 1 /* RVKind.Number */ && b.kind === 1 /* RVKind.Number */) {
+            xs.push(a.value);
+            ys.push(b.value);
+        }
+    }
+    return { xs, ys };
+}
+/** Walk a runtime value and push every scalar cell (in row-major order). */
+function collectCells(arg, out) {
+    if (arg.kind === 5 /* RVKind.Array */) {
+        for (const row of arg.rows) {
+            for (const cell of row) {
+                out.push(cell);
+            }
+        }
+    }
+    else if (arg.kind !== 6 /* RVKind.Reference */ && arg.kind !== 7 /* RVKind.Lambda */) {
+        out.push(arg);
+    }
 }
 function pairedSums(xs, ys) {
     const n = xs.length;
@@ -768,43 +831,45 @@ Object.defineProperty(exports, "fnPERMUT", { enumerable: true, get: function ()
 // GEOMEAN, HARMEAN, TRIMMEAN, DEVSQ, AVEDEV
 // ============================================================================
 const fnGEOMEAN = args => {
-    const rawNums = (0, _shared_1.flattenNumbers)(args);
-    const err = (0, _shared_1.firstError)(rawNums);
+    let logSum = 0;
+    let count = 0;
+    let outOfRange = false;
+    const err = (0, _shared_1.forEachNumber)(args, n => {
+        if (n <= 0) {
+            outOfRange = true;
+            return;
+        }
+        logSum += Math.log(n);
+        count++;
+    });
     if (err) {
         return err;
     }
-    const nums = rawNums;
-    if (nums.length === 0) {
+    if (outOfRange || count === 0) {
         return values_1.ERRORS.NUM;
     }
-    let logSum = 0;
-    for (const n of nums) {
-        if (n.value <= 0) {
-            return values_1.ERRORS.NUM;
-        }
-        logSum += Math.log(n.value);
-    }
-    return (0, values_1.rvNumber)(Math.exp(logSum / nums.length));
+    return (0, values_1.rvNumber)(Math.exp(logSum / count));
 };
 exports.fnGEOMEAN = fnGEOMEAN;
 const fnHARMEAN = args => {
-    const rawNums = (0, _shared_1.flattenNumbers)(args);
-    const err = (0, _shared_1.firstError)(rawNums);
+    let recipSum = 0;
+    let count = 0;
+    let outOfRange = false;
+    const err = (0, _shared_1.forEachNumber)(args, n => {
+        if (n <= 0) {
+            outOfRange = true;
+            return;
+        }
+        recipSum += 1 / n;
+        count++;
+    });
     if (err) {
         return err;
     }
-    const nums = rawNums;
-    if (nums.length === 0) {
+    if (outOfRange || count === 0) {
         return values_1.ERRORS.NUM;
     }
-    let recipSum = 0;
-    for (const n of nums) {
-        if (n.value <= 0) {
-            return values_1.ERRORS.NUM;
-        }
-        recipSum += 1 / n.value;
-    }
-    return (0, values_1.rvNumber)(nums.length / recipSum);
+    return (0, values_1.rvNumber)(count / recipSum);
 };
 exports.fnHARMEAN = fnHARMEAN;
 const fnTRIMMEAN = args => {
@@ -932,22 +997,27 @@ exports.fnCONFIDENCE_T = fnCONFIDENCE_T;
  * side is non-numeric).
  */
 function pairedNumericValues(a, b) {
-    const xsAll = (0, _shared_1.flattenNumbers)([a]);
-    const xsErr = (0, _shared_1.firstError)(xsAll);
-    if (xsErr) {
-        return xsErr;
-    }
-    const ysAll = (0, _shared_1.flattenNumbers)([b]);
-    const ysErr = (0, _shared_1.firstError)(ysAll);
-    if (ysErr) {
-        return ysErr;
-    }
-    const n = Math.min(xsAll.length, ysAll.length);
+    // Walk both ranges in lockstep so pair alignment survives non-numeric
+    // cells. Previously `flattenNumbers` dropped text / blanks before the
+    // zip, which silently shifted the rest of the pairs and produced a
+    // spurious covariance. Excel's COVARIANCE.P / .S pair cells by
+    // position and skip only the pairs where either side is non-numeric.
+    const aCells = [];
+    const bCells = [];
+    collectCells(a, aCells);
+    collectCells(b, bCells);
     const xs = [];
     const ys = [];
+    const n = Math.min(aCells.length, bCells.length);
     for (let i = 0; i < n; i++) {
-        const x = xsAll[i];
-        const y = ysAll[i];
+        const x = aCells[i];
+        const y = bCells[i];
+        if (x.kind === 4 /* RVKind.Error */) {
+            return x;
+        }
+        if (y.kind === 4 /* RVKind.Error */) {
+            return y;
+        }
         if (x.kind === 1 /* RVKind.Number */ && y.kind === 1 /* RVKind.Number */) {
             xs.push(x.value);
             ys.push(y.value);
@@ -1094,39 +1164,26 @@ const fnAVERAGEA = args => {
     return count === 0 ? values_1.ERRORS.DIV0 : (0, values_1.rvNumber)(sum / count);
 };
 exports.fnAVERAGEA = fnAVERAGEA;
-const fnMAXA = args => {
-    const all = (0, _shared_1.flattenAll)(args);
-    let max = -Infinity;
-    let found = false;
-    for (const v of all) {
-        if (v.kind === 0 /* RVKind.Blank */) {
-            continue;
-        }
-        if (v.kind === 4 /* RVKind.Error */) {
-            return v;
-        }
-        let n;
-        if (v.kind === 1 /* RVKind.Number */) {
-            n = v.value;
-        }
-        else if (v.kind === 3 /* RVKind.Boolean */) {
-            n = v.value ? 1 : 0;
-        }
-        else {
-            n = 0;
-        }
-        if (n > max) {
-            max = n;
-        }
-        found = true;
-    }
-    return (0, values_1.rvNumber)(found ? max : 0);
-};
+const fnMAXA = args => reduceAValue(args, -Infinity, (best, n) => (n > best ? n : best));
 exports.fnMAXA = fnMAXA;
-const fnMINA = args => {
-    const all = (0, _shared_1.flattenAll)(args);
-    let min = Infinity;
+const fnMINA = args => reduceAValue(args, Infinity, (best, n) => (n < best ? n : best));
+exports.fnMINA = fnMINA;
+/**
+ * Shared MAXA / MINA reducer. Excel's `*A` variants differ from MAX / MIN
+ * only in how they treat text and booleans inside ranges:
+ *   - Number → its value
+ *   - Boolean → 1 / 0
+ *   - String → 0 (NOT skipped like MAX / MIN)
+ *   - Blank  → skipped
+ *   - Error  → propagated
+ *
+ * When no non-blank cells are seen, both return 0 (the untouched
+ * identity fallback matches Excel's historical behaviour).
+ */
+function reduceAValue(args, identity, fold) {
+    let best = identity;
     let found = false;
+    const all = (0, _shared_1.flattenAll)(args);
     for (const v of all) {
         if (v.kind === 0 /* RVKind.Blank */) {
             continue;
@@ -1134,24 +1191,12 @@ const fnMINA = args => {
         if (v.kind === 4 /* RVKind.Error */) {
             return v;
         }
-        let n;
-        if (v.kind === 1 /* RVKind.Number */) {
-            n = v.value;
-        }
-        else if (v.kind === 3 /* RVKind.Boolean */) {
-            n = v.value ? 1 : 0;
-        }
-        else {
-            n = 0;
-        }
-        if (n < min) {
-            min = n;
-        }
+        const n = v.kind === 1 /* RVKind.Number */ ? v.value : v.kind === 3 /* RVKind.Boolean */ ? (v.value ? 1 : 0) : 0; // text counts as 0 for MAXA / MINA.
+        best = fold(best, n);
         found = true;
     }
-    return (0, values_1.rvNumber)(found ? min : 0);
-};
-exports.fnMINA = fnMINA;
+    return (0, values_1.rvNumber)(found ? best : 0);
+}
 // ============================================================================
 // Private helpers for distributions (pure number → number, unchanged)
 // ============================================================================
@@ -2129,7 +2174,10 @@ const fnERF = args => {
     if (lower.kind === 4 /* RVKind.Error */) {
         return lower;
     }
-    if (args.length > 1) {
+    // Blank 2nd arg → behave like an omitted upper bound, i.e. return
+    // `erf(lower)`. Previously a blank coerced to 0 and flipped the sign
+    // of the result via `erf(0) − erf(lower)`.
+    if (args.length > 1 && args[1].kind !== 0 /* RVKind.Blank */) {
         const upper = (0, _shared_1.argToNumber)(args[1]);
         if (upper.kind === 4 /* RVKind.Error */) {
             return upper;
@@ -2838,34 +2886,36 @@ exports.fnF_INV_RT = fnF_INV_RT;
  * Formula: n / ((n-1)(n-2)) * Σ((xi-mean)/s)^3, where s is the sample stdev.
  */
 const fnSKEW = args => {
-    const nums = (0, _shared_1.flattenNumbers)(args);
-    const err = (0, _shared_1.firstError)(nums);
-    if (err) {
-        return err;
+    const xs = toNumberArray(args);
+    if (!Array.isArray(xs)) {
+        return xs;
     }
-    const xs = nums.map(n => n.value);
     const n = xs.length;
     if (n < 3) {
         return values_1.ERRORS.DIV0;
     }
+    // Single pass 1: mean.
     let sum = 0;
-    for (const v of xs) {
-        sum += v;
+    for (let i = 0; i < n; i++) {
+        sum += xs[i];
     }
     const mean = sum / n;
+    // Single pass 2: accumulate Σ(x−μ)² and Σ(x−μ)³ together. Computing
+    // the cubed normalisation after the loop (dividing by stdev³) is
+    // algebraically equivalent to Σ((x−μ)/s)³ and avoids the third pass.
     let sumSq = 0;
-    for (const v of xs) {
-        sumSq += (v - mean) ** 2;
+    let sumCube = 0;
+    for (let i = 0; i < n; i++) {
+        const d = xs[i] - mean;
+        const d2 = d * d;
+        sumSq += d2;
+        sumCube += d2 * d;
     }
     const sampleStd = Math.sqrt(sumSq / (n - 1));
     if (sampleStd === 0) {
         return values_1.ERRORS.DIV0;
     }
-    let sumCubed = 0;
-    for (const v of xs) {
-        sumCubed += ((v - mean) / sampleStd) ** 3;
-    }
-    return (0, values_1.rvNumber)((n / ((n - 1) * (n - 2))) * sumCubed);
+    return (0, values_1.rvNumber)((n / ((n - 1) * (n - 2))) * (sumCube / (sampleStd * sampleStd * sampleStd)));
 };
 exports.fnSKEW = fnSKEW;
 /**
@@ -2873,34 +2923,32 @@ exports.fnSKEW = fnSKEW;
  * Formula: (1/n) * Σ((xi-mean)/σ)^3, where σ is the population stdev.
  */
 const fnSKEW_P = args => {
-    const nums = (0, _shared_1.flattenNumbers)(args);
-    const err = (0, _shared_1.firstError)(nums);
-    if (err) {
-        return err;
+    const xs = toNumberArray(args);
+    if (!Array.isArray(xs)) {
+        return xs;
     }
-    const xs = nums.map(n => n.value);
     const n = xs.length;
     if (n < 1) {
         return values_1.ERRORS.DIV0;
     }
     let sum = 0;
-    for (const v of xs) {
-        sum += v;
+    for (let i = 0; i < n; i++) {
+        sum += xs[i];
     }
     const mean = sum / n;
     let sumSq = 0;
-    for (const v of xs) {
-        sumSq += (v - mean) ** 2;
+    let sumCube = 0;
+    for (let i = 0; i < n; i++) {
+        const d = xs[i] - mean;
+        const d2 = d * d;
+        sumSq += d2;
+        sumCube += d2 * d;
     }
     const popStd = Math.sqrt(sumSq / n);
     if (popStd === 0) {
         return values_1.ERRORS.DIV0;
     }
-    let sumCubed = 0;
-    for (const v of xs) {
-        sumCubed += ((v - mean) / popStd) ** 3;
-    }
-    return (0, values_1.rvNumber)(sumCubed / n);
+    return (0, values_1.rvNumber)(sumCube / n / (popStd * popStd * popStd));
 };
 exports.fnSKEW_P = fnSKEW_P;
 /**
@@ -2908,36 +2956,38 @@ exports.fnSKEW_P = fnSKEW_P;
  * Formula: n(n+1) / ((n-1)(n-2)(n-3)) * Σ((xi-mean)/s)^4 - 3(n-1)^2 / ((n-2)(n-3)).
  */
 const fnKURT = args => {
-    const nums = (0, _shared_1.flattenNumbers)(args);
-    const err = (0, _shared_1.firstError)(nums);
-    if (err) {
-        return err;
+    const xs = toNumberArray(args);
+    if (!Array.isArray(xs)) {
+        return xs;
     }
-    const xs = nums.map(n => n.value);
     const n = xs.length;
     if (n < 4) {
         return values_1.ERRORS.DIV0;
     }
     let sum = 0;
-    for (const v of xs) {
-        sum += v;
+    for (let i = 0; i < n; i++) {
+        sum += xs[i];
     }
     const mean = sum / n;
+    // Single pass for Σ(x−μ)² and Σ(x−μ)⁴ — the `(x−μ)/s` normalisation
+    // is factored out after the loop (divide by stdev⁴) so we don't need
+    // to know `s` ahead of time.
     let sumSq = 0;
-    for (const v of xs) {
-        sumSq += (v - mean) ** 2;
+    let sumQuad = 0;
+    for (let i = 0; i < n; i++) {
+        const d = xs[i] - mean;
+        const d2 = d * d;
+        sumSq += d2;
+        sumQuad += d2 * d2;
     }
     const sampleStd = Math.sqrt(sumSq / (n - 1));
     if (sampleStd === 0) {
         return values_1.ERRORS.DIV0;
     }
-    let sumQuad = 0;
-    for (const v of xs) {
-        sumQuad += ((v - mean) / sampleStd) ** 4;
-    }
+    const s4 = sampleStd * sampleStd;
     const term1 = (n * (n + 1)) / ((n - 1) * (n - 2) * (n - 3));
     const term2 = (3 * (n - 1) ** 2) / ((n - 2) * (n - 3));
-    return (0, values_1.rvNumber)(term1 * sumQuad - term2);
+    return (0, values_1.rvNumber)(term1 * (sumQuad / (s4 * s4)) - term2);
 };
 exports.fnKURT = fnKURT;
 // ============================================================================