@devmm/puredocs-excel-formula 1.0.5 → 1.0.7

package/dist/index.d.ts

@@ -242,13 +242,98 @@ declare namespace FormulaHelper {
     };
     /** Flattens all args into FormulaValue array (expanding arrays). */
     function flattenArgs(args: FormulaNode[], ctx: FormulaContext): FormulaValue[];
+    /**
+     * A criteria string analysed once, so testing it against N values does not
+     * re-parse it N times.
+     *
+     * `kind` is what lets a caller index instead of scan: `equalsNumber` and
+     * `equalsText` are the two shapes whose matching positions can be looked up,
+     * and they are the overwhelming majority in real files (`SUMIFS(H:H, W:W, W282)`).
+     * Everything else — comparisons, wildcards — only gets the compiled `test`.
+     */
+    interface CompiledCriteria {
+        readonly kind: 'equalsNumber' | 'equalsText' | 'compareNumber' | 'other';
+        /** For `equalsNumber` and `compareNumber`: the number compared against. */
+        readonly number?: number;
+        /** For `equalsText`: the criterion, upper-cased (matching is case-insensitive). */
+        readonly text?: string;
+        /** For `compareNumber`: which comparison. */
+        readonly op?: '>' | '>=' | '<' | '<=';
+        readonly test: (value: FormulaValue) => boolean;
+    }
+    /**
+     * Compiles a criteria string into a reusable predicate.
+     *
+     * Same semantics as {@link matchesCriteria} — that function is now this one
+     * applied immediately — but the parsing, the number conversion and any wildcard
+     * RegExp happen once instead of once per cell. A SUMIFS filled down 291 rows
+     * over a 291-cell range was doing that 84 000 times.
+     */
+    function compileCriteria(criteria: string): CompiledCriteria;
     /** Matches a criteria string (e.g. ">5", "=hello", "*partial*") against a value. */
     function matchesCriteria(value: FormulaValue, criteria: string): boolean;
 }
 
+/**
+ * Memo for range reads: `(sheet, rectangle) → array value`.
+ *
+ * Why this exists. A range reference is resolved by materialising an ArrayValue
+ * and reading every cell in the rectangle. The dominant pattern in real
+ * workbooks is many formulas reading the *same* range — a SUMIFS filled down
+ * 291 rows reads its two 291-cell ranges 291 times each — so the same rectangle
+ * is rebuilt over and over. Memoising it turns O(formulas × range) into
+ * O(distinct ranges × range) for the read side, which is the difference between
+ * a recalculation that finishes and one that does not.
+ *
+ * Why invalidation is per-rectangle rather than per-sheet. During a recalc pass
+ * the engine writes a computed value after every formula, so a sheet-wide
+ * generation counter would invalidate the whole cache thousands of times per
+ * pass and never hit. Instead each cached rectangle is filed into a coarse tile
+ * grid (same shape as {@link DependencyIndex}), and a write only drops the
+ * rectangles that actually contain the written cell — writes to a column of
+ * results leave the input ranges cached.
+ *
+ * Safety. Cached values are shared, not copied, so a reader must not mutate the
+ * ArrayValue it receives. Every built-in function builds its own result array;
+ * none writes into an argument.
+ */
+
+declare class RangeCache {
+    #private;
+    hits: number;
+    misses: number;
+    constructor(maxCells?: number);
+    get size(): number;
+    get cachedCells(): number;
+    static key(sheet: string, r0: number, c0: number, r1: number, c1: number): string;
+    get(sheet: string, r0: number, c0: number, r1: number, c1: number): FormulaValue | undefined;
+    /** Memoises a rectangle's value. `cells` is its area, for the budget. */
+    set(sheet: string, r0: number, c0: number, r1: number, c1: number, value: FormulaValue, cells: number): void;
+    /** Drops every cached rectangle containing the given cell. */
+    invalidateCell(sheet: string, row: number, col: number): void;
+    clear(): void;
+}
+
 interface WorksheetLike {
     getCellValue(reference: string): unknown;
     name: string;
+    /**
+     * Optional: value of a cell by 1-based row/column. Range reads use this when
+     * present, which saves building — and re-parsing — one reference string per
+     * cell. Implementations that resolve values lazily inside getCellValue should
+     * leave it undefined to keep that path.
+     */
+    getCellValueAt?(row: number, column: number): unknown;
+    /**
+     * Optional: the populated extent of the sheet — the highest 1-based row and
+     * column that hold a cell (0 when empty). Used to bound whole-column and
+     * whole-row references (`A:A`, `1:1`), which Excel evaluates over the used
+     * range rather than all 1,048,576 rows.
+     */
+    readonly usedBounds?: {
+        rowCount: number;
+        columnCount: number;
+    };
     /** Optional: whether a 1-based row is hidden (used by SUBTOTAL/AGGREGATE). */
     isRowHidden?(row: number): boolean;
     /** Optional: formula text of a cell (used by SUBTOTAL to skip nested calls). */
@@ -277,6 +362,13 @@ declare class FormulaContext {
     formulaCol: number;
     /** Optional workbook reference for cross-sheet references. */
     workbook?: WorkbookLike;
+    /**
+     * Optional memo for range reads, supplied by whoever owns the write side —
+     * the recalculation engine, which invalidates it as it writes results. Left
+     * undefined for one-shot evaluation, where a stale entry could otherwise
+     * outlive a caller's direct edit to the model.
+     */
+    rangeCache?: RangeCache;
     /**
      * Optional named-range resolver, installed by the evaluator when the workbook
      * exposes getDefinedName. Given a name, returns its evaluated value. Left
@@ -301,8 +393,26 @@ declare class FormulaContext {
     get worksheet(): WorksheetLike;
     getCellValue(cellReference: string): FormulaValue;
     getRangeValues(startRef: string, endRef: string): FormulaValue;
+    /**
+     * Resolves a rectangle already known in coordinates. Split out from
+     * {@link getRangeValues} because whole-column references and the range memo
+     * both work in numbers, and formatting them back into `A1` strings only to
+     * re-parse them is measurable at range scale.
+     */
+    getRangeValuesByIndex(startRow: number, startCol: number, endRow: number, endCol: number): FormulaValue;
+    /**
+     * Resolves a whole-column (`A:A`) or whole-row (`1:1`) reference, bounded by
+     * the sheet's used range the way Excel does. Without a bound this would
+     * materialise a million-cell array for a sheet with twelve rows in it.
+     *
+     * A sheet that cannot report its extent yields `#REF!` rather than a guess:
+     * silently reading nothing would make SUM(A:A) return 0 on a full column.
+     */
+    getFullRangeValues(startCol: number | null, endCol: number | null, startRow: number | null, endRow: number | null): FormulaValue;
     getSheetCellValue(sheetName: string, cellReference: string): FormulaValue;
     getSheetRangeValues(sheetName: string, startRef: string, endRef: string): FormulaValue;
+    /** Whole-column/whole-row reference qualified by a sheet name. */
+    getSheetFullRangeValues(sheetName: string, startCol: number | null, endCol: number | null, startRow: number | null, endRow: number | null): FormulaValue;
     resolveNamedRange(name: string): FormulaValue;
     /**
      * Resolves a spill-range reference (A1#) to the array spilling from the anchor
@@ -383,6 +493,25 @@ declare class SheetRangeReferenceNode extends FormulaNode {
     constructor(sheetName: string, startRef: string, endRef: string);
     evaluate(ctx: FormulaContext): FormulaValue;
 }
+/**
+ * A whole-column (`A:A`, `$B:$D`) or whole-row (`1:1`, `3:7`) reference,
+ * optionally sheet-qualified (`Sheet1!A:A`).
+ *
+ * Exactly one dimension is bounded: a column range fixes the columns and leaves
+ * the rows open, a row range the reverse. The open dimension is resolved against
+ * the sheet's used range at evaluation time rather than baked in as 1..1048576 —
+ * expanding it eagerly would turn `SUM(A:A)` on a twelve-row sheet into a
+ * million-cell read, and Excel's own answer is the used range too.
+ */
+declare class FullRangeReferenceNode extends FormulaNode {
+    readonly startCol: number | null;
+    readonly endCol: number | null;
+    readonly startRow: number | null;
+    readonly endRow: number | null;
+    readonly sheetName?: string | undefined;
+    constructor(startCol: number | null, endCol: number | null, startRow: number | null, endRow: number | null, sheetName?: string | undefined);
+    evaluate(ctx: FormulaContext): FormulaValue;
+}
 declare class NamedRangeNode extends FormulaNode {
     readonly name: string;
     constructor(name: string);
@@ -452,21 +581,6 @@ declare class CallNode extends FormulaNode {
     evaluateTail(ctx: FormulaContext): FormulaValue | TailCall;
 }
 
-/**
- * Recursive descent parser converting formula tokens into an AST.
- * Port of TVE.PureDocs.Excel.Formulas.FormulaParser (C#)
- *
- * Operator precedence (low → high):
- *   Comparison: =, <>, <, <=, >, >=
- *   Concatenation: &
- *   Addition/Subtraction: +, -
- *   Multiplication/Division: *, /
- *   Unary: +, -, @ (prefix)
- *   Power: ^ (right-associative)
- *   Percent: % (postfix)
- *   Primary: literals, refs, functions, parentheses
- */
-
 declare class FormulaParser {
     #private;
     constructor(tokens: Token[]);
@@ -477,6 +591,15 @@ declare class FormulaParser {
  * Parses a formula string to an AST, with LRU caching.
  */
 declare function parseFormula(formula: string): FormulaNode;
+/**
+ * Parses a formula without consulting or populating the shared AST cache.
+ *
+ * For callers that keep the AST themselves — the recalculation engine holds one
+ * per registered formula — the cache is pure overhead: it would evict entries
+ * that are still live elsewhere once a workbook has more formulas than its
+ * capacity, paying eviction cost and retaining memory for no hits.
+ */
+declare function parseFormulaUncached(formula: string): FormulaNode;
 /**
  * Evaluates a formula string against a worksheet.
  * Mirrors FormulaEvaluator.Evaluate() in C#.
@@ -486,6 +609,22 @@ declare function evaluateFormula(formula: string, sheet: WorksheetLike, options?
     formulaRow?: number;
     formulaCol?: number;
 }): FormulaValue;
+/**
+ * Evaluates an already-parsed formula. Callers that hold onto an AST — such as
+ * the recalculation engine, which parses each formula once when it is
+ * registered — should use this so repeated evaluation never depends on the
+ * global AST cache still holding the entry.
+ */
+declare function evaluateAst(ast: FormulaNode, sheet: WorksheetLike, options?: {
+    workbook?: WorkbookLike;
+    formulaRow?: number;
+    formulaCol?: number;
+    /**
+     * Range memo shared across evaluations. Only pass one if you invalidate it
+     * on every write to the model — {@link RecalcEngine} does.
+     */
+    rangeCache?: RangeCache;
+}): FormulaValue;
 declare function clearAstCache(): void;
 declare function getAstCacheStats(): {
     size: number;
@@ -571,6 +710,11 @@ interface CoreCellLike {
 }
 interface CoreSheetLike {
     getCellValue(ref: string): unknown;
+    getCellValueAt?(row: number, column: number): unknown;
+    readonly usedBounds?: {
+        rowCount: number;
+        columnCount: number;
+    };
     getCell(ref: string): CoreCellLike;
     getCellFormula?(ref: string): string | null;
     getSpillRange?(ref: string): string | null;
@@ -591,6 +735,22 @@ declare function createWorkbookRecalcModel(workbook: CoreWorkbookLike): RecalcMo
 interface RecalcModel {
     /** Current value of a cell (raw input value, or last computed value). */
     getCellValue(sheet: string, ref: string): unknown;
+    /**
+     * Optional: value of a cell by 1-based row/column. Range reads prefer this —
+     * it saves building and re-parsing a reference string per cell, which at
+     * range scale is tens of millions of strings per recalculation. Must return
+     * the same value `getCellValue` would for that coordinate.
+     */
+    getCellValueAt?(sheet: string, row: number, column: number): unknown;
+    /**
+     * Optional: the sheet's populated extent, used to bound whole-column (`A:A`)
+     * and whole-row (`1:1`) references. Without it those references are `#REF!`,
+     * since guessing a bound would silently change what SUM(A:A) adds up.
+     */
+    getUsedBounds?(sheet: string): {
+        rowCount: number;
+        columnCount: number;
+    } | undefined;
     /** Store a computed formula result. Must NOT clear the cell's formula. */
     setCellValue(sheet: string, ref: string, value: unknown): void;
     /**
@@ -636,6 +796,37 @@ declare class RecalcEngine {
      * were evaluated. The leading '=' of the formula is optional.
      */
     setCellFormula(sheet: string, ref: string, formula: string): RecalcResult[];
+    /**
+     * Indexes many formulas **without evaluating anything**.
+     *
+     * This is the path for loading a workbook. `setCellFormula` is built for an
+     * edit: it recalculates the new cell and everything downstream of it, which is
+     * right for one keystroke and quadratic for a file — registering N formulas one
+     * by one evaluates the whole workbook N times. Here the formulas are only
+     * parsed and filed into the dependency index; call {@link recalcAll} once
+     * afterwards, or nothing at all if the cached values from the file will do.
+     *
+     * The model is deliberately **not** written to. These formulas are assumed to
+     * be the ones the model already holds (they came from the file), and persisting
+     * them again would clear each cell's cached value — leaving every formula cell
+     * blank until a full recalculation had run. Use `setCellFormula` for formulas
+     * the user is actually introducing.
+     *
+     * A formula that fails to parse is reported rather than thrown: one unsupported
+     * construct in a large workbook should not abort the load.
+     */
+    registerBulk(entries: Iterable<{
+        sheet: string;
+        ref: string;
+        formula: string;
+    }>): {
+        registered: number;
+        failed: Array<{
+            sheet: string;
+            ref: string;
+            error: string;
+        }>;
+    };
     /**
      * Removes a formula from a cell and recalculates its dependents (which may now
      * read a plain input value instead). Returns the recomputed dependent cells.
@@ -651,10 +842,71 @@ declare class RecalcEngine {
      * updated) and recalculates its dependents.
      */
     onCellChanged(sheet: string, ref: string): RecalcResult[];
-    /** Recalculates every registered formula in dependency order. */
-    recalcAll(): RecalcResult[];
+    /**
+     * Recalculates every registered formula.
+     *
+     * By default the order is derived here, with a topological sort over the
+     * dependency index. `order` — typically `workbook.calcChain` — supplies one
+     * instead, so the sort is not needed.
+     *
+     * **A supplied order is verified, not trusted.** Evaluating in a stale order
+     * makes a formula read a precedent that has not been computed yet, and the
+     * result is a plausible wrong number with nothing to distinguish it from a
+     * right one. In a calculation engine that is the worst failure available, so
+     * this checks as it goes: after each formula is written, the dependency index
+     * says who reads it, and any reader that was already evaluated is an inversion.
+     * On the first inversion the ordered attempt is abandoned and the whole
+     * recalculation is redone through the sorted path, whose result is returned;
+     * `onOrderConflict`, if given, is told which pair conflicted.
+     *
+     * The verification costs about what the sort it replaces costs, so `order` is
+     * worth roughly nothing now (measured at ~9% of a full recalculation on a
+     * 2 000-formula workbook, after the dependency index stopped being the
+     * bottleneck). It is kept because reading an order Excel already computed is a
+     * reasonable thing to want; prefer plain `recalcAll()` unless you have measured
+     * a reason not to.
+     *
+     * Registered formulas the order does not mention are evaluated afterwards
+     * through the sorted path, and a dynamic array that spills still triggers the
+     * usual fixpoint, so neither silently misses cells.
+     */
+    recalcAll(options?: {
+        order?: ReadonlyArray<{
+            sheet: string;
+            ref: string;
+        }>;
+        /** Called when the supplied order turned out to be invalid and was discarded. */
+        onOrderConflict?: (conflict: {
+            dependent: string;
+            precedent: string;
+        }) => void;
+    }): RecalcResult[];
     /** The precedents recorded for a formula cell (mainly for tests/inspection). */
     getPrecedents(sheet: string, ref: string): readonly PrecedentRef[];
+    /**
+     * Tells the engine rows were inserted on a sheet. Call AFTER the
+     * corresponding `Worksheet.insertRows` (the model must already reflect the
+     * edit). The dependency graph is translated in place — registrations,
+     * formula text and spill bookkeeping all move — and only volatile formulas
+     * are recomputed, because a pure translation changes no values.
+     *
+     * @example
+     * ws.insertRows(3, 2);
+     * engine.onRowsInserted('S1', 3, 2);
+     */
+    onRowsInserted(sheet: string, at: number, count?: number): RecalcResult[];
+    /**
+     * Tells the engine rows were deleted on a sheet. Call AFTER the
+     * corresponding `Worksheet.deleteRows`. Registrations inside the deleted
+     * band are dropped; the rest of the graph is translated, and only formulas
+     * whose precedents touched the deleted band (plus their dependents and
+     * volatiles) are recomputed.
+     */
+    onRowsDeleted(sheet: string, at: number, count?: number): RecalcResult[];
+    /** Column counterpart to {@link onRowsInserted}. */
+    onColumnsInserted(sheet: string, at: number, count?: number): RecalcResult[];
+    /** Column counterpart to {@link onRowsDeleted}. */
+    onColumnsDeleted(sheet: string, at: number, count?: number): RecalcResult[];
 }
 
 declare function registerMath(r: FunctionRegistry): void;
@@ -679,4 +931,4 @@ declare function registerAggregate(r: FunctionRegistry): void;
 
 declare function registerArray(r: FunctionRegistry): void;
 
-export { ArrayValue, BinaryOpNode, BinaryOperator, BlankNode, BooleanNode, CallNode, CellReferenceNode, ErrorNode, type ExtractResult, FormulaContext, FormulaError, FormulaException, type FormulaFunction, FormulaHelper, FormulaLexer, FormulaNode, FormulaParser, FormulaValue, type FormulaValueKind, FunctionCallNode, type FunctionDef, FunctionRegistry, ImplicitIntersectionNode, type LambdaLike, LruCache, type NameResolver, NamedRangeNode, NumberNode, type PrecedentRef, RangeReferenceNode, RecalcEngine, type RecalcModel, type RecalcResult, SheetCellReferenceNode, SheetRangeReferenceNode, SpillReferenceNode, StringNode, type Token, TokenType, UnaryOpNode, UnaryOperator, type WorkbookLike, type WorksheetLike, clearAstCache, createWorkbookRecalcModel, evaluateFormula, extractReferences, getAstCacheStats, parseFormula, refContains, registerAggregate, registerArray, registerDate, registerFinance, registerInfo, registerLogical, registerLookup, registerMath, registerMeta, registerStatistical, registerText, setAstCacheCapacity };
+export { ArrayValue, BinaryOpNode, BinaryOperator, BlankNode, BooleanNode, CallNode, CellReferenceNode, ErrorNode, type ExtractResult, FormulaContext, FormulaError, FormulaException, type FormulaFunction, FormulaHelper, FormulaLexer, FormulaNode, FormulaParser, FormulaValue, type FormulaValueKind, FullRangeReferenceNode, FunctionCallNode, type FunctionDef, FunctionRegistry, ImplicitIntersectionNode, type LambdaLike, LruCache, type NameResolver, NamedRangeNode, NumberNode, type PrecedentRef, RangeCache, RangeReferenceNode, RecalcEngine, type RecalcModel, type RecalcResult, SheetCellReferenceNode, SheetRangeReferenceNode, SpillReferenceNode, StringNode, type Token, TokenType, UnaryOpNode, UnaryOperator, type WorkbookLike, type WorksheetLike, clearAstCache, createWorkbookRecalcModel, evaluateAst, evaluateFormula, extractReferences, getAstCacheStats, parseFormula, parseFormulaUncached, refContains, registerAggregate, registerArray, registerDate, registerFinance, registerInfo, registerLogical, registerLookup, registerMath, registerMeta, registerStatistical, registerText, setAstCacheCapacity };