@devmm/puredocs-excel-formula 1.0.4 → 1.0.6

package/dist/index.d.cts

@@ -477,6 +477,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 +495,17 @@ 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;
+}): FormulaValue;
 declare function clearAstCache(): void;
 declare function getAstCacheStats(): {
     size: number;
@@ -655,6 +675,30 @@ declare class RecalcEngine {
     recalcAll(): 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 +723,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, 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, evaluateAst, evaluateFormula, extractReferences, getAstCacheStats, parseFormula, parseFormulaUncached, refContains, registerAggregate, registerArray, registerDate, registerFinance, registerInfo, registerLogical, registerLookup, registerMath, registerMeta, registerStatistical, registerText, setAstCacheCapacity };

package/dist/index.d.ts

@@ -477,6 +477,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 +495,17 @@ 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;
+}): FormulaValue;
 declare function clearAstCache(): void;
 declare function getAstCacheStats(): {
     size: number;
@@ -655,6 +675,30 @@ declare class RecalcEngine {
     recalcAll(): 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 +723,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, 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, evaluateAst, evaluateFormula, extractReferences, getAstCacheStats, parseFormula, parseFormulaUncached, refContains, registerAggregate, registerArray, registerDate, registerFinance, registerInfo, registerLogical, registerLookup, registerMath, registerMeta, registerStatistical, registerText, setAstCacheCapacity };