@cj-tech-master/excelts 9.2.1 → 9.3.0

package/dist/types/modules/formula/compile/compiled-formula.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Compiled Formula — The output of the full compilation pipeline.
+ *
+ * A `CompiledFormula` packages together:
+ * - The original `FormulaInstance` metadata
+ * - The bound expression tree (from the binder)
+ * - Static dependency information
+ * - Metadata flags (volatile, dynamic refs, etc.)
+ *
+ * ## Static Dependency Extraction
+ *
+ * Dependencies are extracted from the `BoundExpr` tree. Since names and
+ * structured refs are already resolved by the binder, the dependency
+ * extraction is a simple tree walk that collects `BoundCellRef` and
+ * `BoundAreaRef` nodes.
+ *
+ * Runtime-dependent references (INDIRECT, OFFSET) cannot be captured
+ * statically — the `hasDynamicRefs` flag marks formulas that may have
+ * additional runtime dependencies. Those functions re-parse their dynamic
+ * arguments at evaluation time using their own parser invocation (the raw
+ * AST is not retained on the CompiledFormula).
+ */
+import type { FormulaInstance } from "../integration/formula-instance.js";
+import type { WorkbookSnapshot } from "../integration/workbook-snapshot.js";
+import type { AstNode } from "../syntax/ast.js";
+import type { BoundExpr } from "./bound-ast.js";
+/**
+ * The complete compiled representation of a formula.
+ */
+export interface CompiledFormula {
+    /** The original formula instance metadata. */
+    readonly instance: FormulaInstance;
+    /** The bound expression tree (the evaluator executes this). */
+    readonly bound: BoundExpr;
+    /** Statically extractable dependencies. */
+    readonly staticDeps: StaticDependencySet;
+    /** Whether this formula uses volatile functions (RAND, NOW, etc.). */
+    readonly isVolatile: boolean;
+    /** Whether this formula contains INDIRECT/OFFSET (runtime-dependent refs). */
+    readonly hasDynamicRefs: boolean;
+    /** Whether this formula contains any lambda expressions. */
+    readonly containsLambda: boolean;
+    /**
+     * Whether the top-level function is a known dynamic array function
+     * (FILTER, SORT, UNIQUE, SEQUENCE, etc.). Determined once at compile
+     * time — consumers should use this flag instead of re-checking the AST
+     * or bound expression.
+     */
+    readonly isDynamicArrayFunction: boolean;
+    /**
+     * Whether the top-level function is SUBTOTAL or AGGREGATE. When an
+     * outer SUBTOTAL/AGGREGATE range aggregates a cell whose formula is
+     * itself a SUBTOTAL/AGGREGATE call, that cell must be skipped so its
+     * result is not double-counted. This flag lets `buildRangeArray`
+     * mark those cells with the array's `subtotalMask`.
+     */
+    readonly isSubtotalOutput: boolean;
+}
+/**
+ * A single cell dependency.
+ */
+export interface CellDep {
+    readonly sheet: string;
+    readonly row: number;
+    readonly col: number;
+}
+/**
+ * A rectangular area dependency.
+ */
+export interface AreaDep {
+    readonly sheet: string;
+    readonly top: number;
+    readonly left: number;
+    readonly bottom: number;
+    readonly right: number;
+}
+/**
+ * All statically extractable dependencies of a formula.
+ */
+export interface StaticDependencySet {
+    /** Individual cell references. */
+    readonly cells: readonly CellDep[];
+    /** Range references. */
+    readonly areas: readonly AreaDep[];
+}
+/**
+ * Callback to resolve a defined name into its parsed/bound expression
+ * for dependency extraction. Returns the bound expression if the name
+ * resolves to a formula, or undefined if it can't be resolved.
+ */
+export type NameDepResolver = (name: string) => {
+    deps: StaticDependencySet;
+    hasDynamicRefs: boolean;
+    /**
+     * Whether the defined-name's formula (transitively) uses a volatile
+     * function like NOW/RAND/OFFSET/INDIRECT. The resolver must propagate
+     * this so the OUTER formula inherits volatility — otherwise the
+     * session result cache would hold stale values across calc runs.
+     */
+    isVolatile: boolean;
+} | undefined;
+/**
+ * Extract static dependencies from a bound expression tree.
+ *
+ * @param expr - The bound expression tree to analyze
+ * @param snapshot - Optional snapshot for resolving structured references
+ * @param nameResolver - Optional resolver for formula-based defined name dependencies
+ */
+export declare function extractStaticDeps(expr: BoundExpr, snapshot?: WorkbookSnapshot, nameResolver?: NameDepResolver): StaticDependencySet;
+/**
+ * Check if the formula's top-level expression is a known dynamic array
+ * function. Checks both the raw AST (for prefixed names like `_XLFN.FILTER`)
+ * and the bound expression (for the canonical uppercase name).
+ */
+export declare function detectDynamicArrayFunction(ast: AstNode, bound: BoundExpr): boolean;
+/**
+ * Check if the formula's top-level expression is SUBTOTAL or AGGREGATE.
+ *
+ * Excel's SUBTOTAL/AGGREGATE functions deliberately skip any cell whose
+ * own source formula is itself a SUBTOTAL or AGGREGATE call — this is
+ * what makes the classic "totals row inside a filtered range" case not
+ * double-count. `buildRangeArray` reads this flag off the compiled
+ * formula to decide whether to set `subtotalMask[r][c]`.
+ */
+export declare function detectSubtotalOutput(ast: AstNode, bound: BoundExpr): boolean;
+/**
+ * Analyze a bound expression for volatile functions and dynamic references.
+ *
+ * @param nameResolver - Optional; if a NameExpr resolves to a formula-based
+ *   defined name containing INDIRECT/OFFSET, the outer formula inherits
+ *   `hasDynamicRefs = true`.
+ */
+export declare function analyzeExpr(expr: BoundExpr, nameResolver?: NameDepResolver): {
+    isVolatile: boolean;
+    hasDynamicRefs: boolean;
+    containsLambda: boolean;
+};

package/dist/types/modules/formula/compile/dependency-analysis.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Dependency Graph for Formula Calculation
+ *
+ * Builds a dependency graph from compiled formulas' static dependencies,
+ * then produces a topological evaluation order with circular reference
+ * detection.
+ *
+ * Key exports:
+ * - `buildDependencyGraphFromDeps()` — build graph from CompiledFormula static deps
+ * - `topologicalSort()` — produce evaluation order, detecting circular refs
+ */
+/**
+ * The dependency graph structure.
+ *
+ * - `dependsOn`: formula cell key → set of cell keys it reads from
+ * - `dependedBy`: cell key → set of formula cell keys that read from it
+ * - `formulaKeys`: ordered list of all formula cell keys
+ * - `circularKeys`: set of formula cell keys involved in circular references
+ */
+export interface DependencyGraph {
+    /** Forward edges: formula → cells it depends on */
+    readonly dependsOn: ReadonlyMap<string, ReadonlySet<string>>;
+    /** Reverse edges: cell → formulas that depend on it */
+    readonly dependedBy: ReadonlyMap<string, ReadonlySet<string>>;
+    /** All formula cell keys in insertion order */
+    readonly formulaKeys: readonly string[];
+    /** Formula cell keys that are part of a circular reference cycle */
+    readonly circularKeys: ReadonlySet<string>;
+}
+/**
+ * Build a dependency graph from compiled formulas' static dependencies.
+ *
+ * Operates on the already-resolved `StaticDependencySet` from each compiled
+ * formula. Since names and structured references are already resolved by
+ * the binder, the dependency edges are complete.
+ *
+ * @param compiled - Map from formula cell key to compiled formula with static deps
+ * @param producerMap - Optional map from cell key → formula key that produces
+ *   that cell's value (via CSE distribution or dynamic-array spill). Allows
+ *   dependency edges to be added to the producer even when the target cell
+ *   isn't itself a formula.
+ * @returns The complete dependency graph
+ */
+export declare function buildDependencyGraphFromDeps(compiled: ReadonlyMap<string, {
+    instance: {
+        sheetName: string;
+        row: number;
+        col: number;
+        isDynamicArray?: boolean;
+    };
+    /**
+     * Whether this formula's top-level function is a known dynamic-
+     * array producer (SEQUENCE / FILTER / SORT / …). Used to collapse
+     * downstream `A1:A5`-style range dependencies into a single edge
+     * on the master so dependency ordering stays correct on the first
+     * calc pass (before ghost cells exist in the snapshot).
+     */
+    isDynamicArrayFunction?: boolean;
+    staticDeps: {
+        cells: readonly {
+            sheet: string;
+            row: number;
+            col: number;
+        }[];
+        areas: readonly {
+            sheet: string;
+            top: number;
+            left: number;
+            bottom: number;
+            right: number;
+        }[];
+    };
+}>, producerMap?: ReadonlyMap<string, string>): DependencyGraph;
+/**
+ * Merge runtime-discovered dynamic dependencies into a dependency graph.
+ *
+ * After evaluating formulas that contain INDIRECT/OFFSET, the runtime
+ * dependency recorder has collected the actual cell accesses. This function
+ * incorporates those dynamic edges into the graph and re-detects cycles.
+ *
+ * Returns a new graph if edges were added, or the original graph if no
+ * dynamic deps were recorded.
+ */
+export declare function mergeDynamicDeps(graph: DependencyGraph, dynamicDeps: ReadonlyMap<string, ReadonlySet<string>>): {
+    graph: DependencyGraph;
+    changed: boolean;
+};
+/**
+ * Produce a topological evaluation order for formula cells using Kahn's algorithm.
+ * Cells with no dependencies are evaluated first. Circular references are
+ * appended at the end in their original order.
+ */
+export declare function topologicalSort(graph: DependencyGraph): string[];

package/dist/types/modules/formula/compile/structured-ref-utils.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Shared utilities for structured reference (table) row-range resolution.
+ *
+ * The row-range logic for structured references is needed in three places:
+ * - binder (compile-time range resolution)
+ * - compiled-formula (static dependency extraction)
+ * - evaluator (runtime evaluation)
+ *
+ * This module provides the canonical implementation to avoid triplication.
+ */
+/**
+ * Minimum subset of table snapshot fields required to derive geometry
+ * and resolve structured-reference columns.
+ *
+ * Declared structurally (not as a nominal import of `TableSnapshot`) so
+ * this module stays dependency-free and can serve both compile- and
+ * runtime-side callers that carry their own table-shape types.
+ */
+export interface TableLike {
+    readonly topLeft: {
+        readonly row: number;
+        readonly col: number;
+    };
+    readonly dataRowCount: number;
+    readonly hasHeaderRow: boolean;
+    readonly hasTotalsRow: boolean;
+    readonly columns: readonly {
+        readonly name: string;
+    }[];
+}
+/**
+ * Table geometry needed for structured ref resolution.
+ */
+export interface TableGeometry {
+    /** Top-left row of the table (including header if present). */
+    readonly topLeftRow: number;
+    /** First row of the data body. */
+    readonly dataRowStart: number;
+    /** Last row of the data body. */
+    readonly dataRowEnd: number;
+    /** Whether the table has a header row. */
+    readonly hasHeaderRow: boolean;
+    /** Whether the table has a totals row. */
+    readonly hasTotalsRow: boolean;
+}
+/**
+ * Derive `TableGeometry` from a table's snapshot fields.
+ *
+ * The data row range excludes the header (if any) but also excludes the
+ * totals row — totals, when present, occupy `dataRowEnd + 1`.
+ */
+export declare function buildTableGeometry(table: TableLike): TableGeometry;
+/**
+ * Resolve a list of structured-reference column names to a contiguous
+ * column range `[colLeft, colRight]` in absolute sheet coordinates.
+ *
+ * @param columns - Requested column names (case-insensitive match).
+ * @param table - Table whose columns are searched.
+ * @param mode -
+ *   - `"strict"` — return `"error"` if any name is missing (used by
+ *     binder and evaluator — unknown columns are `#REF!` errors).
+ *   - `"permissive"` — ignore missing names; if ALL names are missing,
+ *     falls back to the full table width (used by static-deps extraction,
+ *     where a conservative over-estimate is acceptable).
+ * @returns `{ colLeft, colRight }`, or `"error"` in strict mode when a
+ *   column name is not found. If `columns` is empty, returns the full
+ *   table width.
+ */
+export declare function resolveStructuredRefColumns(columns: readonly string[], table: TableLike, mode: "strict" | "permissive"): {
+    colLeft: number;
+    colRight: number;
+} | "error";
+/**
+ * Result of resolving structured reference specials to a row range.
+ *
+ * - `{rowTop, rowBottom}` — resolved range
+ * - `"thisRow"` — the `#This Row` special was used; caller must resolve
+ *   using the current cell address
+ * - `"error"` — invalid special combination (e.g., #Totals on a table
+ *   without a totals row)
+ */
+export type StructuredRefRowRange = {
+    rowTop: number;
+    rowBottom: number;
+} | "thisRow" | "error";
+/**
+ * Resolve structured reference specials to a row range.
+ *
+ * This is the single source of truth for the mapping from
+ * `#All`, `#Headers`, `#Data`, `#Totals`, `#This Row` (and their
+ * combinations) to concrete row numbers.
+ */
+export declare function resolveStructuredRefRows(specials: readonly string[], geo: TableGeometry): StructuredRefRowRange;

package/dist/types/modules/formula/default-syntax-probe.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Formula-syntax probe slot.
+ *
+ * ## What this is
+ *
+ * `DefinedNames` (in the excel module) needs a way to tell whether a raw
+ * defined-name text like `OFFSET(Sheet1!$A$1,0,0,3,1)` is a parseable
+ * formula or opaque content to preserve verbatim. The only authoritative
+ * answer comes from the formula tokenizer + parser, which ship in the
+ * `@cj-tech-master/excelts/formula` subpath and are an opt-in
+ * dependency.
+ *
+ * This file is a tiny passive registration slot — a single `let` with
+ * a getter/setter pair — carrying **no** formula-engine code. Importing
+ * `DefinedNames` pulls in this slot (~0.5 KB minified) but never drags
+ * in the tokenizer, parser, or evaluator.
+ *
+ * ## Classification semantics
+ *
+ * - **No probe installed** (default): `DefinedNames` classifies any
+ *   non-range, non-wrapper text as **opaque**. The `rawText` is
+ *   preserved so XLSX round-trip bytes are stable; the entry simply
+ *   cannot be evaluated — which is correct, because no formula engine
+ *   is available anyway.
+ *
+ * - **Probe installed** (after `installFormulaEngine()`): `DefinedNames`
+ *   classifies strictly. Parseable text becomes `formula`, unparseable
+ *   text becomes `opaque`.
+ *
+ * ## Why the slot lives in the formula module
+ *
+ * Module dependency direction: `excel` may import from `formula`
+ * (layer 4 → layer 3), but `formula` must not import from `excel`. The
+ * probe slot is a *formula-module concept* (it wraps a formula
+ * tokenizer+parser) that excel consults; keeping it here preserves the
+ * one-way dependency.
+ *
+ * ## Construction-time injection is also supported
+ *
+ * `Workbook` and `DefinedNames` each accept an explicit
+ * `formulaSyntaxProbe` option. That is the preferred API for callers
+ * who want deterministic, per-instance behaviour (e.g. a test that
+ * needs a specific probe without touching process-global state). The
+ * default-probe slot here is the convenience layer for
+ * `installFormulaEngine()` — call it once at startup and every
+ * subsequent `new Workbook()` picks up strict classification
+ * automatically.
+ *
+ * ## Lookup timing
+ *
+ * `DefinedNames` reads the default probe lazily, at the moment `model`
+ * is assigned (i.e. during XLSX parsing). This means the common
+ * sequence
+ *
+ * ```ts
+ * const wb = new Workbook();
+ * installFormulaEngine();            // later
+ * await wb.xlsx.load(buffer);        // sees the installed probe
+ * ```
+ *
+ * works correctly — the probe installed before `load()` is the one
+ * used, regardless of when `Workbook` itself was constructed.
+ */
+export type SyntaxProbe = (text: string) => boolean;
+/**
+ * Install (or clear) the process-wide default syntax probe.
+ *
+ * Called from `installFormulaEngine()` in `./install`. Passing `null`
+ * uninstalls the probe — symmetric with the formula-engine registry and
+ * useful for tests that exercise the "no probe" classification path.
+ */
+export declare function setDefaultSyntaxProbe(probe: SyntaxProbe | null): void;
+/**
+ * Retrieve the currently-installed default probe, or `null` if none is
+ * installed. Consumers (chiefly `DefinedNames`) should treat `null` as
+ * a signal to use conservative (opaque) classification rather than
+ * guessing.
+ */
+export declare function getDefaultSyntaxProbe(): SyntaxProbe | null;

package/dist/types/modules/formula/functions/_date-context.d.ts

@@ -0,0 +1,4 @@
+/** Set the workbook-wide `date1904` mode for the current calculation session. */
+export declare function setDate1904(v: boolean): void;
+/** Read the workbook-wide `date1904` mode. */
+export declare function isDate1904(): boolean;

package/dist/types/modules/formula/functions/_shared.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Shared helpers for native function implementations.
+ *
+ * Centralizes small utilities that were previously duplicated across multiple
+ * function files (math, statistical, financial, text, date, engineering,
+ * conditional, dynamic-array, database, lookup). None of these change runtime
+ * semantics — they are the canonical extractions of the identical helpers that
+ * appeared in several modules.
+ */
+import type { RuntimeValue, ScalarValue, NumberValue, ErrorValue, ArrayValue } from "../runtime/values.js";
+/**
+ * Return the error value if `v` (as a scalar, extracted via `topLeft`) is an
+ * error; otherwise return `null`. Used by text / date / engineering functions
+ * for the standard "propagate first-arg error" pattern.
+ */
+export declare function checkError(v: RuntimeValue): ErrorValue | null;
+/**
+ * Coerce a single RuntimeValue argument to a number. Applies `topLeft` first
+ * so that a 1×1 (or arbitrary) array yields its top-left scalar before
+ * numeric coercion. Matches the semantics formerly found as `argToNumber` in
+ * `math.ts` and `numArg(args, idx)` in `statistical.ts`.
+ */
+export declare function argToNumber(arg: RuntimeValue): NumberValue | ErrorValue;
+/**
+ * Flatten a list of arguments into a sequence of numeric values (or errors).
+ *
+ * Array arguments contribute only their `Number` and `Error` cells — booleans,
+ * strings, and blanks inside arrays are skipped (Excel range semantics).
+ * Direct scalar arguments are coerced via `toNumberRV`, except for direct
+ * `Blank` scalars which are skipped (Excel aggregate semantics).
+ *
+ * Returns a list of `NumberValue | ErrorValue`. Callers that need raw
+ * `number[]` after an error check should map `.value` themselves.
+ */
+export declare function flattenNumbers(args: RuntimeValue[]): (NumberValue | ErrorValue)[];
+/**
+ * Flatten all cells from the arguments into a flat list of ScalarValue,
+ * preserving every cell (including blanks, errors, booleans, strings).
+ * Direct scalar arguments are projected via `topLeft`.
+ */
+export declare function flattenAll(args: RuntimeValue[]): ScalarValue[];
+/**
+ * Return the first `ErrorValue` in a list of `NumberValue | ErrorValue`,
+ * or `null` if none is present.
+ */
+export declare function firstError(values: readonly (NumberValue | ErrorValue)[]): ErrorValue | null;
+/**
+ * Narrow a RuntimeValue to an ArrayValue, returning `null` if it is not an
+ * array. Used by conditional / database / lookup / dynamic-array families.
+ */
+export declare function asArray(v: RuntimeValue): ArrayValue | null;
+/**
+ * Safe cell accessor for ArrayValue — returns `BLANK` for out-of-bounds (r, c).
+ */
+export declare function getCell(arr: ArrayValue, r: number, c: number): ScalarValue;
+/**
+ * Return `true` if `s` contains an unescaped `*` or `?`. Excel uses `~` as
+ * the escape character, so `~*` and `~?` are literals while `*` and `?` at
+ * any other position are wildcards. `~~` is an escaped tilde.
+ *
+ * Centralised here so every wildcard-consuming function (SEARCH, MATCH,
+ * XLOOKUP, SUMIF/COUNTIF/…) agrees on whether a criterion should trigger
+ * the wildcard code path.
+ */
+export declare function hasUnescapedWildcard(s: string): boolean;
+/**
+ * Convert an Excel wildcard pattern to a JavaScript regex source. Rules:
+ *   `*`     → `.*`
+ *   `?`     → `.`
+ *   `~*`    → literal `*`
+ *   `~?`    → literal `?`
+ *   `~~`    → literal `~`
+ *   `~x`    → literal `x` (any other character after `~` is treated literally,
+ *             matching Excel's tolerant behaviour)
+ *   everything else → regex-escaped literal
+ *
+ * Callers typically wrap the result in `^…$` and use the `i` flag for
+ * case-insensitive matching.
+ */
+export declare function excelWildcardToRegex(s: string): string;
+/**
+ * Strip `~` escape characters from an Excel criteria string so the remaining
+ * text can be used for a literal comparison. `~*` → `*`, `~?` → `?`,
+ * `~~` → `~`, etc. Only used when the caller has already determined that the
+ * pattern contains no unescaped wildcards.
+ */
+export declare function unescapeExcelWildcard(s: string): string;
+/**
+ * Replace every cell marked by the array's `subtotalMask` with BLANK so an
+ * outer SUBTOTAL/AGGREGATE call does not double-count the inner aggregate's
+ * result. Only ArrayValue args carrying a mask are rewritten; scalars and
+ * arrays without masks pass through unchanged.
+ *
+ * Excel behavior: SUBTOTAL and AGGREGATE deliberately skip any cell whose
+ * own formula is itself SUBTOTAL or AGGREGATE — this is how the classic
+ * "totals row inside a filtered range" case works without double-counting.
+ */
+export declare function stripSubtotalMaskedCells(args: RuntimeValue[]): RuntimeValue[];
+/**
+ * Replace every cell in a hidden row with BLANK so aggregate functions
+ * drop them during flattening. Callers: SUBTOTAL's 1xx-variant codes
+ * (101-111) and AGGREGATE with option 5 or 7.
+ *
+ * Only ArrayValue args carrying a hiddenRowMask are rewritten.
+ */
+export declare function stripHiddenRowCells(args: RuntimeValue[]): RuntimeValue[];
+/**
+ * Replace every error cell inside ArrayValue args with BLANK so
+ * aggregate functions simply skip them during flattening. Callers:
+ * AGGREGATE with option 2, 3, 6, or 7.
+ *
+ * Direct scalar error args are left alone — AGGREGATE's caller
+ * already passes them as scalars; our aggregators will surface them
+ * as-is, which matches Excel when a direct literal is an error.
+ *
+ * This is distinct from the standard error-propagation path: arrays
+ * that contain errors normally propagate those errors out of the
+ * aggregate. With option 2/3/6/7, errors inside the *arrays* are
+ * deliberately ignored.
+ */
+export declare function stripErrorCells(args: RuntimeValue[]): RuntimeValue[];

package/dist/types/modules/formula/functions/conditional.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Conditional Aggregate Functions — Native RuntimeValue Implementation
+ */
+import type { RuntimeValue, ScalarValue } from "../runtime/values.js";
+/**
+ * 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 declare function buildCriteriaPredicateRV(criteria: ScalarValue): (v: ScalarValue) => boolean;
+/**
+ * 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.
+ */
+export declare function fnSUMIF(args: RuntimeValue[]): RuntimeValue;
+export declare function fnSUMIFS(args: RuntimeValue[]): RuntimeValue;
+export declare function fnCOUNTIF(args: RuntimeValue[]): RuntimeValue;
+export declare function fnCOUNTIFS(args: RuntimeValue[]): RuntimeValue;
+export declare function fnAVERAGEIF(args: RuntimeValue[]): RuntimeValue;
+export declare function fnAVERAGEIFS(args: RuntimeValue[]): RuntimeValue;
+export declare function fnMAXIFS(args: RuntimeValue[]): RuntimeValue;
+export declare function fnMINIFS(args: RuntimeValue[]): RuntimeValue;

package/dist/types/modules/formula/functions/database.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Database Functions — Native RuntimeValue Implementation
+ */
+import type { RuntimeValue } from "../runtime/values.js";
+export declare function fnDSUM(args: RuntimeValue[]): RuntimeValue;
+export declare function fnDAVERAGE(args: RuntimeValue[]): RuntimeValue;
+export declare function fnDCOUNT(args: RuntimeValue[]): RuntimeValue;
+export declare function fnDMAX(args: RuntimeValue[]): RuntimeValue;
+export declare function fnDMIN(args: RuntimeValue[]): RuntimeValue;
+export declare function fnDPRODUCT(args: RuntimeValue[]): RuntimeValue;
+export declare function fnDGET(args: RuntimeValue[]): RuntimeValue;
+/**
+ * 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 declare function fnDCOUNTA(args: RuntimeValue[]): RuntimeValue;
+/**
+ * DSTDEV(database, field, criteria) — sample standard deviation of
+ * numeric cells matching criteria in the specified field.
+ */
+export declare function fnDSTDEV(args: RuntimeValue[]): RuntimeValue;
+/**
+ * DSTDEVP(database, field, criteria) — population standard deviation
+ * of numeric cells matching criteria.
+ */
+export declare function fnDSTDEVP(args: RuntimeValue[]): RuntimeValue;
+/**
+ * DVAR(database, field, criteria) — sample variance of matching numeric
+ * cells.
+ */
+export declare function fnDVAR(args: RuntimeValue[]): RuntimeValue;
+/**
+ * DVARP(database, field, criteria) — population variance of matching
+ * numeric cells.
+ */
+export declare function fnDVARP(args: RuntimeValue[]): RuntimeValue;

package/dist/types/modules/formula/functions/date.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Date / Time Functions — Native RuntimeValue implementation.
+ *
+ * All Date objects returned by `excelToDate()` represent an Excel serial on
+ * the UTC timeline (midnight UTC for the corresponding date). Consequently
+ * every field accessor must be the UTC variant (`getUTCFullYear`,
+ * `getUTCMonth`, …) and every `Date` constructed from y/m/d components must
+ * be built with `Date.UTC(...)`. Using local-time accessors would make
+ * results depend on the host timezone — e.g. `YEAR(DATE(2024,1,1))` would
+ * return 2023 when evaluated on a machine west of UTC at midnight UTC.
+ *
+ * Exceptions (intentionally use local time):
+ * - `TODAY` / `NOW` — read the user's wall clock, which is genuinely in the
+ *   local timezone. The Excel serial is then constructed using
+ *   `Date.UTC(year, month, day)` so that the resulting serial round-trips
+ *   correctly through `excelToDate()`.
+ */
+import type { RuntimeValue } from "../runtime/values.js";
+type NativeFn = (args: RuntimeValue[]) => RuntimeValue;
+/**
+ * TODAY — today's date (at the user's local timezone).
+ *
+ * The user's concept of "today" is based on their wall clock, so we read
+ * local-time fields from `new Date()`. The resulting y/m/d components are
+ * then packed into a UTC serial so downstream date arithmetic is consistent.
+ */
+export declare const fnTODAY: NativeFn;
+/**
+ * NOW — current date and time.
+ *
+ * Excel stores the result as an untimezoned serial, but the user expects
+ * their local wall-clock reading. `dateToExcel(new Date())` effectively
+ * takes `Date.now()` in UTC-ms; any conversion to the user's timezone
+ * would require tz metadata we do not have. We therefore keep the current
+ * UTC-ms based conversion, matching historical behaviour.
+ */
+export declare const fnNOW: NativeFn;
+export declare const fnYEAR: NativeFn;
+export declare const fnMONTH: NativeFn;
+export declare const fnDAY: NativeFn;
+export declare const fnDATE: NativeFn;
+export declare const fnTIME: NativeFn;
+export declare const fnHOUR: NativeFn;
+export declare const fnMINUTE: NativeFn;
+export declare const fnSECOND: NativeFn;
+export declare const fnWEEKDAY: NativeFn;
+export declare const fnEOMONTH: NativeFn;
+export declare const fnEDATE: NativeFn;
+export declare const fnDATEDIF: NativeFn;
+export declare const fnDAYS: NativeFn;
+export declare const fnISOWEEKNUM: NativeFn;
+export declare const fnWEEKNUM: NativeFn;
+export declare const fnNETWORKDAYS: NativeFn;
+export declare const fnWORKDAY: NativeFn;
+export declare const fnYEARFRAC: NativeFn;
+export declare const fnDATEVALUE: NativeFn;
+export declare const fnTIMEVALUE: NativeFn;
+export declare const fnDAYS360: NativeFn;
+export declare const fnNETWORKDAYS_INTL: NativeFn;
+export declare const fnWORKDAY_INTL: NativeFn;
+export {};