@cj-tech-master/excelts 9.2.1 → 9.3.0

package/dist/esm/modules/formula/functions/conditional.js

@@ -0,0 +1,343 @@
+/**
+ * Conditional Aggregate Functions — Native RuntimeValue Implementation
+ */
+import { RVKind, ERRORS, rvNumber, toStringRV, topLeft, isArray, isError } from "../runtime/values.js";
+import { asArray, excelWildcardToRegex, getCell, hasUnescapedWildcard, unescapeExcelWildcard } from "./_shared.js";
+// ============================================================================
+// Criteria Predicate Builder (RuntimeValue version)
+// ============================================================================
+/**
+ * Build a criteria predicate from a ScalarValue.
+ * Matches Excel SUMIF/COUNTIF criteria semantics:
+ * - number → exact numeric match
+ * - boolean → exact boolean match
+ * - string with operator prefix (">5", "<=10", "<>abc") → comparison
+ * - string with wildcards (* ?) → pattern match
+ * - plain string → case-insensitive exact match (or numeric if parseable)
+ */
+export function buildCriteriaPredicateRV(criteria) {
+    if (criteria.kind === RVKind.Number) {
+        const n = criteria.value;
+        return v => v.kind === RVKind.Number && v.value === n;
+    }
+    if (criteria.kind === RVKind.Boolean) {
+        const b = criteria.value;
+        return v => v.kind === RVKind.Boolean && v.value === b;
+    }
+    if (criteria.kind === RVKind.Error) {
+        return () => false;
+    }
+    // Blank criteria: match blank/empty-string
+    if (criteria.kind === RVKind.Blank) {
+        return v => v.kind === RVKind.Blank || (v.kind === RVKind.String && v.value === "");
+    }
+    // String criteria
+    const s = criteria.kind === RVKind.String ? criteria.value : "";
+    // Operator-prefixed criteria. Order the regex alternatives longest-first
+    // so that `<>abc` matches the `<>` branch (not `<` with `>abc` as the
+    // value). Without the explicit ordering, `/^[<>]=?/` would greedily
+    // consume just `<` and silently mis-route every not-equal criterion to
+    // the `<` branch.
+    const opMatch = /^(<>|<=|>=|<|>|=)(.*)$/.exec(s);
+    if (opMatch) {
+        const [, op, valStr] = opMatch;
+        const numVal = Number(valStr);
+        const isNum = !isNaN(numVal) && valStr.trim() !== "";
+        // For numeric comparisons Excel coerces booleans (TRUE→1, FALSE→0) and
+        // blank (→0); numeric strings are NOT coerced (COUNTIF stays textual
+        // for those). Only real Number / Boolean / Blank cells participate in
+        // numeric comparisons; everything else falls back to string compare.
+        const numericOf = (v) => {
+            if (v.kind === RVKind.Number) {
+                return v.value;
+            }
+            if (v.kind === RVKind.Boolean) {
+                return v.value ? 1 : 0;
+            }
+            if (v.kind === RVKind.Blank) {
+                return 0;
+            }
+            return Number.NaN;
+        };
+        return (v) => {
+            const vn = numericOf(v);
+            const vs = toStringRV(v).toLowerCase();
+            const cs = valStr.toLowerCase();
+            switch (op) {
+                case "=":
+                    return isNum ? vn === numVal : vs === cs;
+                case "<>":
+                    return isNum ? vn !== numVal : vs !== cs;
+                case ">":
+                    return isNum ? vn > numVal : vs > cs;
+                case "<":
+                    return isNum ? vn < numVal : vs < cs;
+                case ">=":
+                    return isNum ? vn >= numVal : vs >= cs;
+                case "<=":
+                    return isNum ? vn <= numVal : vs <= cs;
+                default:
+                    return false;
+            }
+        };
+    }
+    // Wildcard match (case-insensitive). Excel treats `~*`, `~?`, `~~` as
+    // literal `*`, `?`, `~` and everything else as a regex special character
+    // that must be escaped. Only an unescaped `*` or `?` triggers the wildcard
+    // path; a pattern like `~*` matches a literal asterisk.
+    if (hasUnescapedWildcard(s)) {
+        try {
+            const re = new RegExp("^" + excelWildcardToRegex(s) + "$", "i");
+            return v => re.test(toStringRV(v));
+        }
+        catch {
+            const literal = unescapeExcelWildcard(s).toLowerCase();
+            return v => toStringRV(v).toLowerCase() === literal;
+        }
+    }
+    // No wildcards: strip any `~` escapes and do a literal case-insensitive compare.
+    const literal = unescapeExcelWildcard(s);
+    // Exact match (case-insensitive for strings, numeric for numbers)
+    const numCriteria = Number(literal);
+    if (!isNaN(numCriteria) && literal.trim() !== "") {
+        return v => v.kind === RVKind.Number && v.value === numCriteria;
+    }
+    const literalLc = literal.toLowerCase();
+    return v => toStringRV(v).toLowerCase() === literalLc;
+}
+/**
+ * Scan a criteria string for an unescaped `*` or `?`. A backslash-style
+ * escape in Excel is `~`; so `~*` and `~?` are literals, while `*` and `?`
+ * on their own or at a position not preceded by `~` count as wildcards.
+ */
+// ── Wildcard helpers live in `_shared.ts` and are re-used by SEARCH / MATCH /
+//    XLOOKUP / SUMIF / COUNTIF so every function agrees on the same escape
+//    semantics (`~*`, `~?`, `~~`). See `excelWildcardToRegex`,
+//    `hasUnescapedWildcard`, and `unescapeExcelWildcard`.
+// ============================================================================
+// Functions
+// ============================================================================
+export function fnSUMIF(args) {
+    const rangeArr = asArray(args[0]);
+    if (!rangeArr) {
+        return ERRORS.VALUE;
+    }
+    const criteriaScalar = topLeft(args[1]);
+    if (isError(criteriaScalar)) {
+        return criteriaScalar;
+    }
+    const pred = buildCriteriaPredicateRV(criteriaScalar);
+    const sumArr = args.length > 2 ? (asArray(args[2]) ?? rangeArr) : rangeArr;
+    let sum = 0;
+    for (let r = 0; r < rangeArr.height; r++) {
+        for (let c = 0; c < rangeArr.width; c++) {
+            if (pred(getCell(rangeArr, r, c))) {
+                const sv = getCell(sumArr, r, c);
+                if (sv.kind === RVKind.Number) {
+                    sum += sv.value;
+                }
+            }
+        }
+    }
+    return rvNumber(sum);
+}
+/**
+ * Scan successive `(range, criteria)` argument pairs starting at
+ * `startIdx`. Returns a list of `{ arr, pred }` ready for iteration, or
+ * an `{ error }` sentinel when a range argument is missing, a criteria
+ * value is itself an error, or a criteria range's shape does not match
+ * `target`'s shape (Excel's SUMIFS/COUNTIFS require identical shapes —
+ * silently zero-extending with `BLANK` produced wrong counts).
+ *
+ * Used by SUMIFS/COUNTIFS/AVERAGEIFS/MAXIFS/MINIFS which share the
+ * "target array + N criteria pairs" shape.
+ */
+function collectCriteriaPairs(args, startIdx, target) {
+    const pairs = [];
+    for (let i = startIdx; i < args.length - 1; i += 2) {
+        const critRange = asArray(args[i]);
+        if (!critRange) {
+            return { error: ERRORS.VALUE };
+        }
+        if (critRange.height !== target.height || critRange.width !== target.width) {
+            return { error: ERRORS.VALUE };
+        }
+        const cs = topLeft(args[i + 1]);
+        if (isError(cs)) {
+            return { error: cs };
+        }
+        pairs.push({ arr: critRange, pred: buildCriteriaPredicateRV(cs) });
+    }
+    return { pairs };
+}
+/**
+ * Walk every (row, col) position in `target` and invoke `onMatch(r, c)`
+ * whenever all criteria predicates evaluate true at that position. The
+ * criteria arrays are expected to share `target`'s shape — Excel returns
+ * `#VALUE!` at the call site if they don't, which callers can detect by
+ * checking `target.height` / `target.width` before invoking this helper.
+ */
+function iterateMultiCriteria(target, pairs, onMatch) {
+    const rows = target.height;
+    const cols = target.width;
+    for (let r = 0; r < rows; r++) {
+        for (let c = 0; c < cols; c++) {
+            let allMatch = true;
+            for (const p of pairs) {
+                if (!p.pred(getCell(p.arr, r, c))) {
+                    allMatch = false;
+                    break;
+                }
+            }
+            if (allMatch) {
+                onMatch(r, c);
+            }
+        }
+    }
+}
+export function fnSUMIFS(args) {
+    const sumArr = asArray(args[0]);
+    if (!sumArr || args.length < 3) {
+        return ERRORS.VALUE;
+    }
+    const pairs = collectCriteriaPairs(args, 1, sumArr);
+    if ("error" in pairs) {
+        return pairs.error;
+    }
+    let sum = 0;
+    iterateMultiCriteria(sumArr, pairs.pairs, (r, c) => {
+        const sv = getCell(sumArr, r, c);
+        if (sv.kind === RVKind.Number) {
+            sum += sv.value;
+        }
+    });
+    return rvNumber(sum);
+}
+export function fnCOUNTIF(args) {
+    const rangeArr = asArray(args[0]);
+    if (!rangeArr) {
+        return ERRORS.VALUE;
+    }
+    const cs = topLeft(args[1]);
+    if (isError(cs)) {
+        return cs;
+    }
+    const pred = buildCriteriaPredicateRV(cs);
+    let count = 0;
+    for (let r = 0; r < rangeArr.height; r++) {
+        for (let c = 0; c < rangeArr.width; c++) {
+            if (pred(getCell(rangeArr, r, c))) {
+                count++;
+            }
+        }
+    }
+    return rvNumber(count);
+}
+export function fnCOUNTIFS(args) {
+    if (args.length < 2 || !isArray(args[0])) {
+        return ERRORS.VALUE;
+    }
+    // The first range defines the target shape; every subsequent criteria
+    // range must match. `collectCriteriaPairs` also validates args[0]
+    // against itself (trivially passes) as a nice-to-have for consistency.
+    const target = args[0];
+    const pairs = collectCriteriaPairs(args, 0, target);
+    if ("error" in pairs) {
+        return pairs.error;
+    }
+    let count = 0;
+    iterateMultiCriteria(target, pairs.pairs, () => {
+        count++;
+    });
+    return rvNumber(count);
+}
+export function fnAVERAGEIF(args) {
+    const rangeArr = asArray(args[0]);
+    if (!rangeArr) {
+        return ERRORS.VALUE;
+    }
+    const cs = topLeft(args[1]);
+    if (isError(cs)) {
+        return cs;
+    }
+    const pred = buildCriteriaPredicateRV(cs);
+    const avgArr = args.length > 2 ? (asArray(args[2]) ?? rangeArr) : rangeArr;
+    let sum = 0;
+    let count = 0;
+    for (let r = 0; r < rangeArr.height; r++) {
+        for (let c = 0; c < rangeArr.width; c++) {
+            if (pred(getCell(rangeArr, r, c))) {
+                const sv = getCell(avgArr, r, c);
+                if (sv.kind === RVKind.Number) {
+                    sum += sv.value;
+                    count++;
+                }
+            }
+        }
+    }
+    return count === 0 ? ERRORS.DIV0 : rvNumber(sum / count);
+}
+export function fnAVERAGEIFS(args) {
+    const avgArr = asArray(args[0]);
+    if (!avgArr || args.length < 3) {
+        return ERRORS.VALUE;
+    }
+    const pairs = collectCriteriaPairs(args, 1, avgArr);
+    if ("error" in pairs) {
+        return pairs.error;
+    }
+    let sum = 0;
+    let count = 0;
+    iterateMultiCriteria(avgArr, pairs.pairs, (r, c) => {
+        const sv = getCell(avgArr, r, c);
+        if (sv.kind === RVKind.Number) {
+            sum += sv.value;
+            count++;
+        }
+    });
+    return count === 0 ? ERRORS.DIV0 : rvNumber(sum / count);
+}
+export function fnMAXIFS(args) {
+    const maxArr = asArray(args[0]);
+    if (!maxArr || args.length < 3) {
+        return ERRORS.VALUE;
+    }
+    const pairs = collectCriteriaPairs(args, 1, maxArr);
+    if ("error" in pairs) {
+        return pairs.error;
+    }
+    let result = -Infinity;
+    let found = false;
+    iterateMultiCriteria(maxArr, pairs.pairs, (r, c) => {
+        const sv = getCell(maxArr, r, c);
+        if (sv.kind === RVKind.Number) {
+            if (sv.value > result) {
+                result = sv.value;
+            }
+            found = true;
+        }
+    });
+    return rvNumber(found ? result : 0);
+}
+export function fnMINIFS(args) {
+    const minArr = asArray(args[0]);
+    if (!minArr || args.length < 3) {
+        return ERRORS.VALUE;
+    }
+    const pairs = collectCriteriaPairs(args, 1, minArr);
+    if ("error" in pairs) {
+        return pairs.error;
+    }
+    let result = Infinity;
+    let found = false;
+    iterateMultiCriteria(minArr, pairs.pairs, (r, c) => {
+        const sv = getCell(minArr, r, c);
+        if (sv.kind === RVKind.Number) {
+            if (sv.value < result) {
+                result = sv.value;
+            }
+            found = true;
+        }
+    });
+    return rvNumber(found ? result : 0);
+}

package/dist/esm/modules/formula/functions/database.js

@@ -0,0 +1,274 @@
+/**
+ * Database Functions — Native RuntimeValue Implementation
+ */
+import { RVKind, ERRORS, rvNumber, toStringRV, topLeft } from "../runtime/values.js";
+import { asArray, getCell } from "./_shared.js";
+import { buildCriteriaPredicateRV } from "./conditional.js";
+/**
+ * Collect the field-column values from every database row that satisfies the
+ * criteria range. The returned list preserves each matching cell's original
+ * `ScalarValue` (numbers, strings, booleans, blanks, errors) so that callers
+ * can decide how to aggregate — numeric aggregators filter to numbers while
+ * DGET inspects the raw value.
+ *
+ * Returns an error RuntimeValue when the inputs are malformed (invalid array
+ * shapes, unknown field name, etc.). On success, returns `ScalarValue[]`.
+ */
+function collectDatabaseMatches(args) {
+    const dbArr = asArray(args[0]);
+    const critArr = asArray(args[2]);
+    if (!dbArr || !critArr) {
+        return ERRORS.VALUE;
+    }
+    const fieldArg = topLeft(args[1]);
+    if (dbArr.height < 2 || critArr.height < 2) {
+        return ERRORS.VALUE;
+    }
+    // Determine field column index.
+    //
+    // Excel accepts the field argument as:
+    //   - a 1-based integer column index (or TRUE/FALSE coerced to 1/0)
+    //   - a string that matches one of the header cells (case-insensitive,
+    //     and trimmed so imported data with stray whitespace still matches)
+    let fieldIdx = -1;
+    if (fieldArg.kind === RVKind.Number) {
+        fieldIdx = Math.trunc(fieldArg.value) - 1;
+    }
+    else if (fieldArg.kind === RVKind.Boolean) {
+        // TRUE → 1-based column 1 (index 0); FALSE → 0 → invalid (Excel
+        // rejects FALSE with #VALUE!). Match that routing explicitly.
+        fieldIdx = fieldArg.value ? 0 : -1;
+    }
+    else if (fieldArg.kind === RVKind.String) {
+        const want = fieldArg.value.trim().toLowerCase();
+        for (let c = 0; c < dbArr.width; c++) {
+            if (toStringRV(getCell(dbArr, 0, c))
+                .trim()
+                .toLowerCase() === want) {
+                fieldIdx = c;
+                break;
+            }
+        }
+    }
+    if (fieldIdx < 0 || fieldIdx >= dbArr.width) {
+        return ERRORS.VALUE;
+    }
+    // Parse criteria: columns map to database header columns (trimmed,
+    // case-insensitive, same as the field-name path above).
+    const critColIndices = [];
+    for (let cc = 0; cc < critArr.width; cc++) {
+        const name = toStringRV(getCell(critArr, 0, cc))
+            .trim()
+            .toLowerCase();
+        let idx = -1;
+        for (let hc = 0; hc < dbArr.width; hc++) {
+            if (toStringRV(getCell(dbArr, 0, hc))
+                .trim()
+                .toLowerCase() === name) {
+                idx = hc;
+                break;
+            }
+        }
+        critColIndices.push(idx);
+    }
+    // Collect matching rows' field values
+    const matches = [];
+    for (let r = 1; r < dbArr.height; r++) {
+        let matchesAnyCritRow = false;
+        for (let cr = 1; cr < critArr.height; cr++) {
+            let allMatch = true;
+            for (let cc = 0; cc < critArr.width; cc++) {
+                const critVal = getCell(critArr, cr, cc);
+                if (critVal.kind === RVKind.Blank ||
+                    (critVal.kind === RVKind.String && critVal.value === "")) {
+                    continue;
+                }
+                const dbCol = critColIndices[cc];
+                if (dbCol < 0) {
+                    allMatch = false;
+                    break;
+                }
+                const pred = buildCriteriaPredicateRV(critVal);
+                if (!pred(getCell(dbArr, r, dbCol))) {
+                    allMatch = false;
+                    break;
+                }
+            }
+            if (allMatch) {
+                matchesAnyCritRow = true;
+                break;
+            }
+        }
+        if (matchesAnyCritRow) {
+            matches.push(getCell(dbArr, r, fieldIdx));
+        }
+    }
+    return matches;
+}
+/**
+ * Shared wrapper for numeric aggregators (DSUM, DAVERAGE, DCOUNT, DMAX, DMIN,
+ * DPRODUCT). Collects matches, filters to numeric values, and delegates to the
+ * caller-supplied reducer.
+ */
+function databaseNumericAggregate(args, aggregator) {
+    const matches = collectDatabaseMatches(args);
+    if (!Array.isArray(matches)) {
+        return matches;
+    }
+    const values = [];
+    for (const v of matches) {
+        if (v.kind === RVKind.Number) {
+            values.push(v.value);
+        }
+    }
+    return aggregator(values);
+}
+export function fnDSUM(args) {
+    return databaseNumericAggregate(args, vals => rvNumber(vals.reduce((a, b) => a + b, 0)));
+}
+export function fnDAVERAGE(args) {
+    return databaseNumericAggregate(args, vals => vals.length === 0 ? ERRORS.DIV0 : rvNumber(vals.reduce((a, b) => a + b, 0) / vals.length));
+}
+export function fnDCOUNT(args) {
+    return databaseNumericAggregate(args, vals => rvNumber(vals.length));
+}
+export function fnDMAX(args) {
+    return databaseNumericAggregate(args, vals => {
+        if (vals.length === 0) {
+            return rvNumber(0);
+        }
+        // Avoid `Math.max(...vals)` — spreading a large numeric array onto the
+        // call stack throws `RangeError: Maximum call stack size exceeded` on
+        // databases with more than ~65k matching rows.
+        let m = vals[0];
+        for (let i = 1; i < vals.length; i++) {
+            if (vals[i] > m) {
+                m = vals[i];
+            }
+        }
+        return rvNumber(m);
+    });
+}
+export function fnDMIN(args) {
+    return databaseNumericAggregate(args, vals => {
+        if (vals.length === 0) {
+            return rvNumber(0);
+        }
+        let m = vals[0];
+        for (let i = 1; i < vals.length; i++) {
+            if (vals[i] < m) {
+                m = vals[i];
+            }
+        }
+        return rvNumber(m);
+    });
+}
+export function fnDPRODUCT(args) {
+    return databaseNumericAggregate(args, vals => rvNumber(vals.length === 0 ? 0 : vals.reduce((a, b) => a * b, 1)));
+}
+export function fnDGET(args) {
+    const matches = collectDatabaseMatches(args);
+    if (!Array.isArray(matches)) {
+        return matches;
+    }
+    // DGET aggregator semantics: 0 matches → #VALUE!, exactly 1 → the value,
+    // >1 → #NUM!.
+    if (matches.length === 0) {
+        return ERRORS.VALUE;
+    }
+    if (matches.length > 1) {
+        return ERRORS.NUM;
+    }
+    return matches[0];
+}
+/**
+ * DCOUNTA(database, field, criteria) — count non-empty cells that match
+ * the criteria, in the specified field. Unlike DCOUNT (numeric-only),
+ * DCOUNTA counts any non-blank cell including text and booleans.
+ */
+export function fnDCOUNTA(args) {
+    const matches = collectDatabaseMatches(args);
+    if (!Array.isArray(matches)) {
+        return matches;
+    }
+    let count = 0;
+    for (const v of matches) {
+        // Count anything that is not Blank and not an empty string.
+        if (v.kind === RVKind.Blank) {
+            continue;
+        }
+        if (v.kind === RVKind.String && v.value === "") {
+            continue;
+        }
+        count++;
+    }
+    return rvNumber(count);
+}
+/**
+ * DSTDEV(database, field, criteria) — sample standard deviation of
+ * numeric cells matching criteria in the specified field.
+ */
+export function fnDSTDEV(args) {
+    return databaseNumericAggregate(args, vals => {
+        if (vals.length < 2) {
+            return ERRORS.DIV0;
+        }
+        const mean = vals.reduce((a, b) => a + b, 0) / vals.length;
+        let ss = 0;
+        for (const v of vals) {
+            ss += (v - mean) * (v - mean);
+        }
+        return rvNumber(Math.sqrt(ss / (vals.length - 1)));
+    });
+}
+/**
+ * DSTDEVP(database, field, criteria) — population standard deviation
+ * of numeric cells matching criteria.
+ */
+export function fnDSTDEVP(args) {
+    return databaseNumericAggregate(args, vals => {
+        if (vals.length === 0) {
+            return ERRORS.DIV0;
+        }
+        const mean = vals.reduce((a, b) => a + b, 0) / vals.length;
+        let ss = 0;
+        for (const v of vals) {
+            ss += (v - mean) * (v - mean);
+        }
+        return rvNumber(Math.sqrt(ss / vals.length));
+    });
+}
+/**
+ * DVAR(database, field, criteria) — sample variance of matching numeric
+ * cells.
+ */
+export function fnDVAR(args) {
+    return databaseNumericAggregate(args, vals => {
+        if (vals.length < 2) {
+            return ERRORS.DIV0;
+        }
+        const mean = vals.reduce((a, b) => a + b, 0) / vals.length;
+        let ss = 0;
+        for (const v of vals) {
+            ss += (v - mean) * (v - mean);
+        }
+        return rvNumber(ss / (vals.length - 1));
+    });
+}
+/**
+ * DVARP(database, field, criteria) — population variance of matching
+ * numeric cells.
+ */
+export function fnDVARP(args) {
+    return databaseNumericAggregate(args, vals => {
+        if (vals.length === 0) {
+            return ERRORS.DIV0;
+        }
+        const mean = vals.reduce((a, b) => a + b, 0) / vals.length;
+        let ss = 0;
+        for (const v of vals) {
+            ss += (v - mean) * (v - mean);
+        }
+        return rvNumber(ss / vals.length);
+    });
+}