@worksheet-js/formula 1.0.0

package/LICENSE

@@ -0,0 +1,44 @@
+# END USER LICENSE AGREEMENT (EULA)
+
+**Product:** @worksheet-js/formula
+**Copyright:** (c) 2024-present Worksheet Systems <support@worksheet.js>
+**All Rights Reserved.**
+
+IMPORTANT: PLEASE READ THIS LICENSE AGREEMENT CAREFULLY BEFORE USING THE SOFTWARE.
+
+### 1. PROPRIETARY RIGHTS
+
+The @worksheet-js/formula spreadsheet formula engine ("Software") is a proprietary product of Worksheet Systems and is protected by copyright laws and international treaty provisions. All intellectual property rights in and to the Software are and shall remain the exclusive property of Worksheet Systems.
+
+### 2. GRANT OF LICENSE
+
+Subject to the terms and conditions of this Agreement and any applicable commercial terms, Worksheet Systems grants you a non-exclusive, non-transferable license to use the Software solely for your internal business purposes or as expressly permitted in a separate written agreement.
+
+### 3. RESTRICTIONS
+
+You shall not, and shall not permit any third party to:
+
+- Copy, modify, or create derivative works of the Software.
+- Reverse engineer, decompile, or disassemble the Software, or otherwise attempt to derive the source code, except to the extent such restriction is expressly prohibited by applicable law.
+- Sublicense, rent, lease, or lend the Software to any third party.
+- Remove or alter any copyright, trademark, or other proprietary notices contained in the Software.
+
+### 4. CONFIDENTIALITY
+
+The Software, including its structure, organization, and source code, constitutes valuable trade secrets and confidential information of Worksheet Systems. You agree to hold such information in strict confidence and not to disclose it to any third party.
+
+### 5. TERMINATION
+
+This license is effective until terminated. Your rights under this License will terminate automatically without notice if you fail to comply with any term(s) of this Agreement. Upon termination, you shall cease all use of the Software and destroy all copies in your possession.
+
+### 6. NO WARRANTY
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE.
+
+### 7. LIMITATION OF LIABILITY
+
+IN NO EVENT SHALL WORKSHEET SYSTEMS BE LIABLE FOR ANY SPECIAL, INCIDENTAL, INDIRECT, OR CONSEQUENTIAL DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION, OR ANY OTHER PECUNIARY LOSS) ARISING OUT OF THE USE OF OR INABILITY TO USE THE SOFTWARE.
+
+### 8. GOVERNING LAW
+
+This Agreement shall be governed by and construed in accordance with the laws of the jurisdiction in which Worksheet Systems is established, without regard to its conflict of law principles.

package/README.md

@@ -0,0 +1,87 @@
+# @worksheet-js/formula
+
+**Industrial-grade spreadsheet formula engine for modern web applications.**
+
+`@worksheet-js/formula` is a high-performance, proprietary calculation engine designed to parse and evaluate complex spreadsheet formulas with full support for Google Sheets and Microsoft Excel implementation standards.
+
+## ✨ Key Features
+
+- **High Performance**: Optimized AST-based evaluation with intelligent dependency tracking.
+- **Rich Function Library**: 300+ functions across Math, Statistical, Financial, Logical, and Text categories.
+- **Dependency Management**: Automatically tracks cell relationships to ensure minimal re-calculation.
+- **Extensible**: Easily register custom functions to extend the engine's capabilities.
+- **Type-Safe**: Written in TypeScript with exhaustive type definitions included.
+
+## ✨ Advanced Features
+
+### 🛠️ Custom Function Registration
+
+Extend the engine with your own business logic:
+
+```typescript
+engine.registerFunction('MY_CUSTOM_LOGIC', (args) => {
+  return args[0] * 2;
+});
+```
+
+### 📈 Intelligent Dependency Tracking
+
+The engine builds a directed acyclic graph (DAG) of cell relationships. When a cell changes, only its direct and indirect dependents are recalculated, ensuring sub-millisecond updates even in massive workbooks.
+
+## 📦 Installation
+
+```bash
+pnpm add @worksheet-js/formula
+```
+
+## 🚀 Usage
+
+```typescript
+import { FormulaEngine } from '@worksheet-js/formula';
+
+// 1. Define a data provider (how the engine reads cell values)
+const provider = {
+  getValue: (x, y) => dataGrid[y][x],
+  getRange: (x1, y1, x2, y2) => {
+    /* return 2D array of values */
+  },
+  onUpdate: (x, y, value) => {
+    /* notify UI of calculated result */
+  },
+};
+
+// 2. Initialize the engine
+const engine = new FormulaEngine(provider);
+
+// 3. Evaluate a cell containing a formula (e.g., "=SUM(A1:B10)")
+const result = engine.evaluate(2, 0); // Evaluates C1
+console.log('Result:', result);
+```
+
+## 🛠️ API Reference
+
+### `FormulaEngine` Class
+
+- `constructor(provider: CellDataProvider)`: Initializes the engine with a data provider.
+- `evaluate(x: number, y: number): unknown`: Computes the final value of a cell. Results are cached.
+- `invalidate(x: number, y: number): void`: Signals that a cell's input has changed, triggering a cascade of updates for all dependents.
+- `invalidateBatch(coords: Array<{x: number, y: number}>): void`: Optimized bulk invalidation.
+- `invalidateAll(): void`: Clears all internal caches and dependency mappings.
+- `getDependents(x: number, y: number): Array<[number, number]>`: Returns cells that depend on the specified cell.
+- `remove(x: number, y: number): void`: Fully removes a cell from cache and dependency tracking.
+
+### `CellDataProvider` Interface
+
+To use the engine, you must implement a provider that mediates between your data storage and the engine.
+
+```typescript
+interface CellDataProvider {
+  getValue(x: number, y: number): string | number | boolean;
+  getRange?(x1: number, y1: number, x2: number, y2: number): any[][];
+}
+```
+
+## 📄 License
+
+Copyright (c) 2024-present Worksheet Systems. All rights reserved.
+Proprietary software. Usage is subject to the [EULA](LICENSE) terms.

package/dist/index.d.mts

@@ -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 };