@worksheet-js/formula 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,320 @@
+/**
+ * @file types.ts
+ * @description Core type definitions and interfaces for the @worksheet-js/formula engine.
+ */
+/**
+ * Interface provided to formula function implementations during evaluation.
+ * Allows functions to safely access spreadsheet data and metadata.
+ */
+interface EvalContext {
+    /**
+     * Retrieves the computed value of a cell.
+     * If the cell contains a formula, it will be evaluated recursively ($x,y$).
+     */
+    getCell(x: number, y: number): unknown;
+    /**
+     * Optional method to fetch the value of a range cell without triggering a full evaluation loop.
+     * Useful for high-performance lookup and indexing operations.
+     */
+    getRange?(x: number, y: number): unknown;
+    /** Zero-based column index of the cell currently being evaluated. */
+    currentX?: number;
+    /** Zero-based row index of the cell currently being evaluated. */
+    currentY?: number;
+    /**
+     * Executes a formula function by its canonical uppercase name.
+     * Used primarily by lambda-style functions (e.g., MAP, REDUCE).
+     */
+    call?(name: string, args: unknown[]): unknown;
+    /**
+     * Parses and evaluates a standalone formula fragment.
+     */
+    evaluate?(formula: string): unknown;
+}
+/**
+ * Represents a reference to a single cell coordinate.
+ */
+interface CellRef {
+    type: 'cell';
+    /** Zero-based column index. */
+    x: number;
+    /** Zero-based row index. */
+    y: number;
+    /** Original address string as found in the formula (e.g., "$A$1"). */
+    addr: string;
+}
+/**
+ * Represents a reference to a rectangular range of cells.
+ */
+interface RangeRef {
+    type: 'range';
+    /** Top-left column index. */
+    x1: number;
+    /** Top-left row index. */
+    y1: number;
+    /** Bottom-right column index. */
+    x2: number;
+    /** Bottom-right row index. */
+    y2: number;
+    /** Original range address string (e.g., "A1:B3"). */
+    addr: string;
+}
+/**
+ * Union type covering all possible cell and range reference structures.
+ */
+type Ref = CellRef | RangeRef;
+/**
+ * Interface provided to the formula engine by the host application.
+ */
+interface CellDataProvider {
+    /**
+     * Retrieves the raw string input of a cell.
+     * @param x - Zero-based column index.
+     * @param y - Zero-based row index.
+     */
+    getRawValue(x: number, y: number): string;
+    /**
+     * Optional callback triggered when a cell's computed value changes.
+     * @param x - Zero-based column index.
+     * @param y - Zero-based row index.
+     * @param value - The new computed result.
+     */
+    onComputed?(x: number, y: number, value: unknown): void;
+}
+/**
+ * Represents a spreadsheet formula error (e.g., #DIV/0!, #N/A).
+ */
+declare class FormulaError {
+    code: string;
+    constructor(code: string);
+    toString(): string;
+}
+/**
+ * Type definition for a function implementation.
+ */
+type FunctionImpl = (args: unknown[], ctx: EvalContext) => unknown;
+/**
+ * Supported function categories, aligned with Google Sheets and Excel standards.
+ */
+type FunctionCategory = 'Math' | 'Text' | 'Logical' | 'Lookup' | 'Date' | 'Info' | 'Statistical' | 'Engineering' | 'Financial' | 'Database' | 'Web' | 'Operator' | 'Array' | 'Google';
+/**
+ * Metadata structure for a single spreadsheet function.
+ */
+interface FunctionMeta {
+    name: string;
+    category: FunctionCategory;
+    summary: string;
+    syntax: string;
+}
+
+/**
+ * @file FormulaEngine.ts
+ * @description The core calculation engine for @worksheet-js/formula.
+ *
+ * Responsibilities:
+ * 1. AST Lifecycle: Parses formula strings into Abstract Syntax Trees (AST).
+ * 2. Evaluation: Recursively evaluates the AST against live spreadsheet data.
+ * 3. Reactive Dependency Tracking: Maintains a directed acyclic graph (DAG) of cell relationships.
+ * 4. Cache Management: Optimizes performance via result and AST memoization.
+ * 5. Re-calculation: Cascades invalidations through the dependency graph when cell data changes.
+ * 6. Error Handling: Detects circular references and parsing failures.
+ */
+
+/**
+ * The FormulaEngine orchestrates the parsing and evaluation of spreadsheet formulas.
+ *
+ * It manages an internal cache of computed results and parsed Abstract Syntax Trees (ASTs),
+ * as well as a dependency graph to enable efficient re-calculation when data changes.
+ *
+ * Supports standard arithmetic, ranges, and a comprehensive library of built-in functions.
+ */
+declare class FormulaEngine {
+    private provider;
+    /** Cache of computed results indexed by cell key. */
+    private cache;
+    /** Cache of parsed ASTs indexed by the raw formula string. */
+    private astCache;
+    /**
+     * Outbound dependencies: maps a cell key to a set of cells that depend on it.
+     * Example: if C1 has "=A1+B1", then dependents["A1"] contains "C1".
+     */
+    private dependents;
+    /**
+     * Inbound dependencies: maps a cell key to a set of cells it references.
+     * Example: if C1 has "=A1+B1", then dependsOn["C1"] contains {"A1", "B1"}.
+     */
+    private dependsOn;
+    /** Tracks cells currently in the evaluation stack to detect circular references. */
+    private evaluating;
+    /**
+     * Creates a new instance of the FormulaEngine.
+     * @param provider - An implementation of CellDataProvider.
+     */
+    constructor(provider: CellDataProvider);
+    /**
+     * Computes the final value of a specific cell coordinate.
+     *
+     * If the cell contains a formula (starts with '='), it is parsed into an AST and evaluated.
+     * Results are cached until explicitly invalidated via the `invalidate` method.
+     * Any cell references within the formula will register a dependency relationship.
+     *
+     * @param x - Zero-based column index.
+     * @param y - Zero-based row index.
+     * @returns The evaluated result (number, string, boolean, or FormulaError).
+     *
+     * @example
+     * ```typescript
+     * const val = engine.evaluate(0, 0); // Evaluates A1
+     * ```
+     */
+    evaluate(x: number, y: number): unknown;
+    /**
+     * Signals that a cell's raw input has changed.
+     * This invalidates the cell's cache and triggers a recursive invalidation of all dependents.
+     *
+     * @param x - Column index.
+     * @param y - Row index.
+     *
+     * @note Call this BEFORE updating the provider's raw value for the cell,
+     *   or alternatively use `invalidateBatch` for bulk operations. The current
+     *   raw value is read to locate and remove the old cached AST. After invalidation
+     *   the engine will re-parse on next evaluate() call.
+     */
+    invalidate(x: number, y: number): void;
+    /**
+     * Performs bulk invalidation for multiple cells.
+     * Prevents redundant re-calculations by processing the cascade in a single pass.
+     *
+     * @param coords - Array of cell coordinates.
+     */
+    invalidateBatch(coords: Array<{
+        x: number;
+        y: number;
+    }>): void;
+    /**
+     * Clears all internal caches and dependency tracking.
+     * Use this for full sheet resets or large data imports.
+     *
+     * After calling this, all cells will be re-evaluated lazily on next access.
+     * Any previously registered dependency relationships are fully discarded.
+     */
+    invalidateAll(): void;
+    /**
+     * Returns a list of cell coordinates that depend on the value of the specified cell.
+     */
+    getDependents(x: number, y: number): Array<[number, number]>;
+    /**
+     * Removes all trace of a cell from the engine (cache, AST, and dependencies).
+     */
+    remove(x: number, y: number): void;
+    /** Registers a new dependency between two cells. */
+    private _addDep;
+    /** Clears all stored dependencies for a specific cell. */
+    private _clearDepsFor;
+    /**
+     * Cascades invalidation through the dependency graph using a Breadth-First Search (BFS).
+     * Re-evaluates all affected cells and notifies the host provider.
+     */
+    private _invalidateCascade;
+}
+
+/**
+ * @file index.ts
+ * @description Central registry for all formula functions in Worksheet Systems.
+ *
+ * This module aggregates functions from all specialized modules (math, text, logic, etc.),
+ * defines their categories, and provides metadata required for the function
+ * insertion UI and documentation tooltips.
+ */
+
+/** Complete function registry keyed by uppercase name */
+declare const FUNCTIONS: Record<string, FunctionImpl>;
+/** Sorted list of all function names */
+declare const FUNCTION_NAMES: string[];
+/** All functions with category and description */
+declare const FUNCTION_REGISTRY: FunctionMeta[];
+/** Get functions by category */
+declare function getFunctionsByCategory(category: FunctionCategory | 'All'): FunctionMeta[];
+
+/**
+ * Formulas available to 'starter' plan users.
+ * 'pro' and 'enterprise' plans have full access.
+ */
+declare const BASIC_FORMULAS: Set<string>;
+
+/**
+ * @file parser.ts
+ * @description A high-performance recursive descent parser for spreadsheet formulas.
+ *
+ * Employs a Pratt-style parsing strategy to handle operator precedence and associativity
+ * across complex mathematical and logical expressions.
+ *
+ * Grammar Overview:
+ * expr        ::= comparison
+ * comparison  ::= concat ( ('='|'<>'|'<'|'>'|'<='|'>=') concat )*
+ * concat      ::= additive ( '&' additive )*
+ * additive    ::= multiplicative ( ('+' | '-') multiplicative )*
+ * multiplicative ::= power ( ('*' | '/') power )*
+ * power       ::= unary ( '^' unary )*
+ * unary       ::= ('-' | '+') unary | primary '%' | primary
+ * primary     ::= number | string | bool | error | ref | func | '(' expr ')' | '{' array '}'
+ */
+/**
+ * Represents a node in the Abstract Syntax Tree (AST).
+ */
+type AstNode = {
+    type: 'number';
+    value: number;
+} | {
+    type: 'string';
+    value: string;
+} | {
+    type: 'boolean';
+    value: boolean;
+} | {
+    type: 'error';
+    code: string;
+} | {
+    type: 'cell';
+    addr: string;
+    x: number;
+    y: number;
+} | {
+    type: 'range';
+    addr: string;
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+} | {
+    type: 'unary';
+    op: string;
+    operand: AstNode;
+} | {
+    type: 'binary';
+    op: string;
+    left: AstNode;
+    right: AstNode;
+} | {
+    type: 'call';
+    name: string;
+    args: AstNode[];
+} | {
+    type: 'array';
+    values: AstNode[][];
+} | {
+    type: 'percent';
+    operand: AstNode;
+};
+/**
+ * Parses a spreadsheet formula string into an Abstract Syntax Tree (AST).
+ *
+ * Handles literal values, cell/range references, binary operators, and
+ * built-in function calls. Automatically strips the leading '=' if present.
+ *
+ * @param formula - The raw formula string.
+ * @returns The root node of the parsed AST.
+ */
+declare function parse(formula: string): AstNode;
+
+export { type AstNode, BASIC_FORMULAS, type CellDataProvider, type CellRef, type EvalContext, FUNCTIONS, FUNCTION_NAMES, FUNCTION_REGISTRY, FormulaEngine, FormulaError, type FunctionCategory, type FunctionImpl, type FunctionMeta, type RangeRef, type Ref, getFunctionsByCategory, parse };