@molecule/api-formula-engine 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Spreadsheet-style formula engine for molecule.dev.
+ *
+ * Pure-function parser + evaluator + dependency tracker for
+ * A1-notation formulas (`=SUM(A1:B5)`, `=IF(A1>0, "y", "n")`, etc.).
+ * Designed for the spreadsheet flagship app and for ad-hoc line-item
+ * math (e.g. invoice/billing computed columns).
+ *
+ * Capabilities:
+ * - **Arithmetic**: `+ - * / % ^` (with Excel-compatible coercions).
+ * - **Comparison**: `= <> < <= > >=` (numbers, strings, dates, booleans).
+ * - **String**: `&` and `CONCAT()` / `CONCATENATE()`.
+ * - **References**: `A1`, `$A$1`, `BC42`, ranges `A1:B5`.
+ * - **Aggregations**: `SUM`, `AVERAGE`/`AVG`, `MIN`, `MAX`, `COUNT`,
+ *   `COUNTA`, `COUNTIF`, `SUMIF`.
+ * - **Conditionals**: `IF`, `AND`, `OR`, `NOT`, `IFS`, `SWITCH`,
+ *   `IFERROR`, `ISERROR`, `ISNUMBER`, `ISBLANK`.
+ * - **Math**: `ROUND`, `ABS`, `MOD`, `POWER`, `SQRT`, `INT`, `CEILING`,
+ *   `FLOOR`.
+ * - **Dates**: `DATE`, `TODAY`, `NOW`, `YEAR`, `MONTH`, `DAY`,
+ *   `DATEDIFF`/`DATEDIF` (units: D/M/Y/H/MIN/S).
+ * - **Text**: `LEFT`, `RIGHT`, `MID`, `LEN`, `TRIM`, `UPPER`, `LOWER`,
+ *   `SUBSTITUTE`.
+ * - **Errors**: `#DIV/0!`, `#VALUE!`, `#REF!`, `#NAME?`, `#NUM!`,
+ *   `#N/A`, plus engine-emitted `#CIRC!` for circular references.
+ *
+ * The `Sheet` class wraps the lower-level helpers and provides
+ * incremental recompute (only the transitive dependents of a changed
+ * cell are re-evaluated). Use `parseFormula` + `evaluate` directly for
+ * stateless one-shot math.
+ *
+ * Pure functions, zero I/O, zero DB access, zero hardcoded UI text.
+ *
+ * @example
+ * ```typescript
+ * import { Sheet, parseFormula, evaluate } from '@molecule/api-formula-engine'
+ *
+ * // Stateful: a small in-memory spreadsheet.
+ * const sheet = new Sheet()
+ * sheet.setValue('A1', 10)
+ * sheet.setValue('A2', 20)
+ * sheet.setFormula('A3', '=SUM(A1:A2)')
+ * sheet.getValue('A3') // → 30
+ *
+ * sheet.setValue('A1', 100)
+ * sheet.getValue('A3') // → 120 (auto-recomputed)
+ *
+ * // Stateless: ad-hoc evaluation against a lookup function.
+ * const ast = parseFormula('=A1 * 1.0875')
+ * const lineTotal = evaluate(ast, (coord) =>
+ *   coord.col === 0 && coord.row === 0 ? 49.99 : null,
+ * )
+ * ```
+ *
+ * @module
+ */
+export * from './browser-guard.js';
+export * from './dependencies.js';
+export * from './evaluator.js';
+export * from './functions.js';
+export * from './parser.js';
+export * from './references.js';
+export * from './sheet.js';
+export * from './tokenizer.js';
+export * from './types.js';
+export * from './values.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,mBAAmB,CAAA;AACjC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,aAAa,CAAA;AAC3B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,YAAY,CAAA;AAC1B,cAAc,aAAa,CAAA"}

package/dist/index.js

@@ -0,0 +1,66 @@
+/**
+ * Spreadsheet-style formula engine for molecule.dev.
+ *
+ * Pure-function parser + evaluator + dependency tracker for
+ * A1-notation formulas (`=SUM(A1:B5)`, `=IF(A1>0, "y", "n")`, etc.).
+ * Designed for the spreadsheet flagship app and for ad-hoc line-item
+ * math (e.g. invoice/billing computed columns).
+ *
+ * Capabilities:
+ * - **Arithmetic**: `+ - * / % ^` (with Excel-compatible coercions).
+ * - **Comparison**: `= <> < <= > >=` (numbers, strings, dates, booleans).
+ * - **String**: `&` and `CONCAT()` / `CONCATENATE()`.
+ * - **References**: `A1`, `$A$1`, `BC42`, ranges `A1:B5`.
+ * - **Aggregations**: `SUM`, `AVERAGE`/`AVG`, `MIN`, `MAX`, `COUNT`,
+ *   `COUNTA`, `COUNTIF`, `SUMIF`.
+ * - **Conditionals**: `IF`, `AND`, `OR`, `NOT`, `IFS`, `SWITCH`,
+ *   `IFERROR`, `ISERROR`, `ISNUMBER`, `ISBLANK`.
+ * - **Math**: `ROUND`, `ABS`, `MOD`, `POWER`, `SQRT`, `INT`, `CEILING`,
+ *   `FLOOR`.
+ * - **Dates**: `DATE`, `TODAY`, `NOW`, `YEAR`, `MONTH`, `DAY`,
+ *   `DATEDIFF`/`DATEDIF` (units: D/M/Y/H/MIN/S).
+ * - **Text**: `LEFT`, `RIGHT`, `MID`, `LEN`, `TRIM`, `UPPER`, `LOWER`,
+ *   `SUBSTITUTE`.
+ * - **Errors**: `#DIV/0!`, `#VALUE!`, `#REF!`, `#NAME?`, `#NUM!`,
+ *   `#N/A`, plus engine-emitted `#CIRC!` for circular references.
+ *
+ * The `Sheet` class wraps the lower-level helpers and provides
+ * incremental recompute (only the transitive dependents of a changed
+ * cell are re-evaluated). Use `parseFormula` + `evaluate` directly for
+ * stateless one-shot math.
+ *
+ * Pure functions, zero I/O, zero DB access, zero hardcoded UI text.
+ *
+ * @example
+ * ```typescript
+ * import { Sheet, parseFormula, evaluate } from '@molecule/api-formula-engine'
+ *
+ * // Stateful: a small in-memory spreadsheet.
+ * const sheet = new Sheet()
+ * sheet.setValue('A1', 10)
+ * sheet.setValue('A2', 20)
+ * sheet.setFormula('A3', '=SUM(A1:A2)')
+ * sheet.getValue('A3') // → 30
+ *
+ * sheet.setValue('A1', 100)
+ * sheet.getValue('A3') // → 120 (auto-recomputed)
+ *
+ * // Stateless: ad-hoc evaluation against a lookup function.
+ * const ast = parseFormula('=A1 * 1.0875')
+ * const lineTotal = evaluate(ast, (coord) =>
+ *   coord.col === 0 && coord.row === 0 ? 49.99 : null,
+ * )
+ * ```
+ *
+ * @module
+ */
+export * from './browser-guard.js';
+export * from './dependencies.js';
+export * from './evaluator.js';
+export * from './functions.js';
+export * from './parser.js';
+export * from './references.js';
+export * from './sheet.js';
+export * from './tokenizer.js';
+export * from './types.js';
+export * from './values.js';

package/dist/parser.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Recursive-descent parser for formula expressions.
+ *
+ * Produces an AST consumable by the evaluator. Operator precedence
+ * follows Excel:
+ *
+ *   1. `:` (range) — handled at tokenizer level
+ *   2. unary `+`/`-`
+ *   3. `%` (postfix)
+ *   4. `^`
+ *   5. `*`, `/`
+ *   6. `+`, `-`
+ *   7. `&`
+ *   8. `=`, `<>`, `<`, `<=`, `>`, `>=`
+ *
+ * Pure function — no I/O, no globals.
+ *
+ * @module
+ */
+import type { AstNode } from './types.js';
+/**
+ * Parse a formula string into an AST.
+ *
+ * @param input - Formula text (with or without a leading `=`).
+ * @returns Root AST node.
+ */
+export declare function parseFormula(input: string): AstNode;
+//# sourceMappingURL=parser.d.ts.map

package/dist/parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../src/parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAKH,OAAO,KAAK,EAAE,OAAO,EAAkB,MAAM,YAAY,CAAA;AAEzD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAcnD"}

package/dist/parser.js

@@ -0,0 +1,255 @@
+/**
+ * Recursive-descent parser for formula expressions.
+ *
+ * Produces an AST consumable by the evaluator. Operator precedence
+ * follows Excel:
+ *
+ *   1. `:` (range) — handled at tokenizer level
+ *   2. unary `+`/`-`
+ *   3. `%` (postfix)
+ *   4. `^`
+ *   5. `*`, `/`
+ *   6. `+`, `-`
+ *   7. `&`
+ *   8. `=`, `<>`, `<`, `<=`, `>`, `>=`
+ *
+ * Pure function — no I/O, no globals.
+ *
+ * @module
+ */
+import { parseCellRange, parseCellReference } from './references.js';
+import { tokenize } from './tokenizer.js';
+/**
+ * Parse a formula string into an AST.
+ *
+ * @param input - Formula text (with or without a leading `=`).
+ * @returns Root AST node.
+ */
+export function parseFormula(input) {
+    const body = input.trimStart().startsWith('=') ? input.trimStart().slice(1) : input;
+    const tokens = tokenize(body);
+    if (tokens.length === 0) {
+        throw new Error('Empty formula');
+    }
+    const parser = new Parser(tokens);
+    const node = parser.parseExpression();
+    if (!parser.atEnd()) {
+        throw new Error(`Unexpected token '${parser.peek().value}' at position ${parser.peek().position}`);
+    }
+    return node;
+}
+/**
+ * Recursive-descent parser that converts a token stream into an AST.
+ */
+class Parser {
+    tokens;
+    pos = 0;
+    constructor(tokens) {
+        this.tokens = tokens;
+    }
+    /**
+     * Returns true when all tokens have been consumed.
+     */
+    atEnd() {
+        return this.pos >= this.tokens.length;
+    }
+    /**
+     * Returns the current token without advancing the position.
+     */
+    peek() {
+        return this.tokens[this.pos];
+    }
+    /**
+     * Advances past the current token and returns it, throwing if the stream is exhausted.
+     */
+    consume() {
+        const t = this.tokens[this.pos];
+        if (!t)
+            throw new Error('Unexpected end of formula');
+        this.pos++;
+        return t;
+    }
+    /**
+     * Entry point for expression parsing; delegates to the lowest-precedence level.
+     */
+    parseExpression() {
+        return this.parseComparison();
+    }
+    /**
+     * Parses comparison operators (`=`, `<>`, `<`, `<=`, `>`, `>=`).
+     */
+    parseComparison() {
+        let left = this.parseConcat();
+        while (true) {
+            const t = this.peek();
+            if (t?.kind === 'op' &&
+                (t.value === '=' ||
+                    t.value === '<>' ||
+                    t.value === '<' ||
+                    t.value === '<=' ||
+                    t.value === '>' ||
+                    t.value === '>=')) {
+                this.consume();
+                const right = this.parseConcat();
+                left = { kind: 'binary', op: t.value, left, right };
+            }
+            else {
+                break;
+            }
+        }
+        return left;
+    }
+    /**
+     * Parses the string concatenation operator (`&`).
+     */
+    parseConcat() {
+        let left = this.parseAddSub();
+        while (true) {
+            const t = this.peek();
+            if (t?.kind === 'op' && t.value === '&') {
+                this.consume();
+                const right = this.parseAddSub();
+                left = { kind: 'binary', op: '&', left, right };
+            }
+            else {
+                break;
+            }
+        }
+        return left;
+    }
+    /**
+     * Parses addition and subtraction operators (`+`, `-`).
+     */
+    parseAddSub() {
+        let left = this.parseMulDiv();
+        while (true) {
+            const t = this.peek();
+            if (t?.kind === 'op' && (t.value === '+' || t.value === '-')) {
+                this.consume();
+                const right = this.parseMulDiv();
+                left = { kind: 'binary', op: t.value, left, right };
+            }
+            else {
+                break;
+            }
+        }
+        return left;
+    }
+    /**
+     * Parses multiplication and division operators (`*`, `/`).
+     */
+    parseMulDiv() {
+        let left = this.parsePower();
+        while (true) {
+            const t = this.peek();
+            if (t?.kind === 'op' && (t.value === '*' || t.value === '/')) {
+                this.consume();
+                const right = this.parsePower();
+                left = { kind: 'binary', op: t.value, left, right };
+            }
+            else {
+                break;
+            }
+        }
+        return left;
+    }
+    /**
+     * Parses the right-associative exponentiation operator (`^`).
+     */
+    parsePower() {
+        const left = this.parsePercent();
+        const t = this.peek();
+        if (t?.kind === 'op' && t.value === '^') {
+            this.consume();
+            const right = this.parsePower(); // right-associative
+            return { kind: 'binary', op: '^', left, right };
+        }
+        return left;
+    }
+    /**
+     * Parses the postfix percent operator (`%`).
+     */
+    parsePercent() {
+        const operand = this.parseUnary();
+        const t = this.peek();
+        if (t?.kind === 'op' && t.value === '%') {
+            this.consume();
+            return { kind: 'unary', op: '%', operand };
+        }
+        return operand;
+    }
+    /**
+     * Parses unary prefix operators (`+`, `-`).
+     */
+    parseUnary() {
+        const t = this.peek();
+        if (t?.kind === 'op' && (t.value === '+' || t.value === '-')) {
+            this.consume();
+            const operand = this.parseUnary();
+            return { kind: 'unary', op: t.value === '+' ? '+' : '-', operand };
+        }
+        return this.parsePrimary();
+    }
+    /**
+     * Parses atomic values: literals, references, ranges, function calls, and parenthesised sub-expressions.
+     */
+    parsePrimary() {
+        const t = this.consume();
+        switch (t.kind) {
+            case 'number':
+                return { kind: 'number', value: Number.parseFloat(t.value) };
+            case 'string':
+                return { kind: 'string', value: t.value };
+            case 'boolean':
+                return { kind: 'boolean', value: t.value === 'TRUE' };
+            case 'error':
+                return { kind: 'errorLiteral', code: t.errorCode };
+            case 'reference': {
+                const coord = parseCellReference(t.value);
+                if (!coord) {
+                    throw new Error(`Invalid reference '${t.value}' at position ${t.position}`);
+                }
+                return { kind: 'reference', coord, text: t.value };
+            }
+            case 'range': {
+                const range = parseCellRange(t.value);
+                if (!range) {
+                    throw new Error(`Invalid range '${t.value}' at position ${t.position}`);
+                }
+                return { kind: 'range', range, text: t.value };
+            }
+            case 'identifier': {
+                // Function call: identifier followed by '('
+                const next = this.peek();
+                if (next?.kind === 'lparen') {
+                    this.consume(); // (
+                    const args = [];
+                    if (this.peek()?.kind !== 'rparen') {
+                        args.push(this.parseExpression());
+                        while (this.peek()?.kind === 'comma') {
+                            this.consume();
+                            args.push(this.parseExpression());
+                        }
+                    }
+                    const close = this.consume();
+                    if (close.kind !== 'rparen') {
+                        throw new Error(`Expected ')' at position ${close.position}`);
+                    }
+                    return { kind: 'call', name: t.value.toUpperCase(), args };
+                }
+                // Bare identifier — treat as #NAME? at evaluation time
+                return { kind: 'call', name: t.value.toUpperCase(), args: [] };
+            }
+            case 'lparen': {
+                const inner = this.parseExpression();
+                const close = this.consume();
+                if (close.kind !== 'rparen') {
+                    throw new Error(`Expected ')' at position ${close.position}`);
+                }
+                return inner;
+            }
+            default:
+                throw new Error(`Unexpected token '${t.value}' at position ${t.position}`);
+        }
+    }
+}

package/dist/references.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Cell-reference parsing and conversion utilities.
+ *
+ * @module
+ */
+import type { CellCoord, CellRange } from './types.js';
+/**
+ * Convert a column letter (`A`, `Z`, `AA`, `XFD`) to a 0-indexed column.
+ *
+ * @param letters - Column letters (case-insensitive).
+ * @returns 0-indexed column number.
+ */
+export declare function columnLettersToIndex(letters: string): number;
+/**
+ * Convert a 0-indexed column to letters (`0`→`A`, `25`→`Z`, `26`→`AA`).
+ *
+ * @param index - 0-indexed column.
+ * @returns Column letters (uppercase).
+ */
+export declare function columnIndexToLetters(index: number): string;
+/**
+ * Parse a single cell reference (e.g. `A1`, `$A$1`, `BC42`).
+ *
+ * @param ref - Reference text.
+ * @returns Parsed cell coordinate, or `null` if invalid.
+ */
+export declare function parseCellReference(ref: string): CellCoord | null;
+/**
+ * Parse a cell range (e.g. `A1:B5`). Normalizes so `start` is top-left
+ * and `end` is bottom-right regardless of input ordering.
+ *
+ * @param ref - Range text.
+ * @returns Parsed range, or `null` if invalid.
+ */
+export declare function parseCellRange(ref: string): CellRange | null;
+/**
+ * Format a cell coordinate as A1-style text (`{col:0,row:0}` → `A1`).
+ *
+ * @param coord - Cell coordinate.
+ * @returns A1-style reference text.
+ */
+export declare function formatCellReference(coord: CellCoord): string;
+/**
+ * Iterate every coordinate in a range. Yields top-to-bottom, left-to-right.
+ *
+ * @param range - Cell range.
+ * @yields {CellCoord} Each cell coordinate inside the range, inclusive of both corners.
+ */
+export declare function iterateRange(range: CellRange): Generator<CellCoord>;
+/**
+ * Encode a coordinate to a cache-friendly string key (`"col,row"`).
+ *
+ * @param coord - Cell coordinate.
+ * @returns Stable string key.
+ */
+export declare function coordKey(coord: CellCoord): string;
+//# sourceMappingURL=references.d.ts.map

package/dist/references.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"references.d.ts","sourceRoot":"","sources":["../src/references.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAEtD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAW5D;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAY1D;AAID;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAOhE;AAID;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAe5D;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAE5D;AAED;;;;;GAKG;AACH,wBAAiB,YAAY,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS,CAAC,SAAS,CAAC,CAMpE;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAEjD"}

package/dist/references.js

@@ -0,0 +1,116 @@
+/**
+ * Cell-reference parsing and conversion utilities.
+ *
+ * @module
+ */
+/**
+ * Convert a column letter (`A`, `Z`, `AA`, `XFD`) to a 0-indexed column.
+ *
+ * @param letters - Column letters (case-insensitive).
+ * @returns 0-indexed column number.
+ */
+export function columnLettersToIndex(letters) {
+    let n = 0;
+    const upper = letters.toUpperCase();
+    for (let i = 0; i < upper.length; i++) {
+        const code = upper.charCodeAt(i) - 64; // 'A' = 65
+        if (code < 1 || code > 26) {
+            throw new Error(`Invalid column letter: ${letters}`);
+        }
+        n = n * 26 + code;
+    }
+    return n - 1;
+}
+/**
+ * Convert a 0-indexed column to letters (`0`→`A`, `25`→`Z`, `26`→`AA`).
+ *
+ * @param index - 0-indexed column.
+ * @returns Column letters (uppercase).
+ */
+export function columnIndexToLetters(index) {
+    if (!Number.isInteger(index) || index < 0) {
+        throw new Error(`Invalid column index: ${index}`);
+    }
+    let n = index + 1;
+    let s = '';
+    while (n > 0) {
+        const r = (n - 1) % 26;
+        s = String.fromCharCode(65 + r) + s;
+        n = Math.floor((n - 1) / 26);
+    }
+    return s;
+}
+const REF_RE = /^\$?([A-Za-z]+)\$?(\d+)$/;
+/**
+ * Parse a single cell reference (e.g. `A1`, `$A$1`, `BC42`).
+ *
+ * @param ref - Reference text.
+ * @returns Parsed cell coordinate, or `null` if invalid.
+ */
+export function parseCellReference(ref) {
+    const m = REF_RE.exec(ref);
+    if (!m)
+        return null;
+    const col = columnLettersToIndex(m[1]);
+    const row = Number.parseInt(m[2], 10) - 1;
+    if (row < 0)
+        return null;
+    return { col, row };
+}
+const RANGE_RE = /^(\$?[A-Za-z]+\$?\d+):(\$?[A-Za-z]+\$?\d+)$/;
+/**
+ * Parse a cell range (e.g. `A1:B5`). Normalizes so `start` is top-left
+ * and `end` is bottom-right regardless of input ordering.
+ *
+ * @param ref - Range text.
+ * @returns Parsed range, or `null` if invalid.
+ */
+export function parseCellRange(ref) {
+    const m = RANGE_RE.exec(ref);
+    if (!m)
+        return null;
+    const a = parseCellReference(m[1]);
+    const b = parseCellReference(m[2]);
+    if (!a || !b)
+        return null;
+    const start = {
+        col: Math.min(a.col, b.col),
+        row: Math.min(a.row, b.row),
+    };
+    const end = {
+        col: Math.max(a.col, b.col),
+        row: Math.max(a.row, b.row),
+    };
+    return { start, end };
+}
+/**
+ * Format a cell coordinate as A1-style text (`{col:0,row:0}` → `A1`).
+ *
+ * @param coord - Cell coordinate.
+ * @returns A1-style reference text.
+ */
+export function formatCellReference(coord) {
+    return `${columnIndexToLetters(coord.col)}${coord.row + 1}`;
+}
+/**
+ * Iterate every coordinate in a range. Yields top-to-bottom, left-to-right.
+ *
+ * @param range - Cell range.
+ * @yields {CellCoord} Each cell coordinate inside the range, inclusive of both corners.
+ */
+export function* iterateRange(range) {
+    for (let r = range.start.row; r <= range.end.row; r++) {
+        for (let c = range.start.col; c <= range.end.col; c++) {
+            yield { col: c, row: r };
+        }
+    }
+}
+/**
+ * Encode a coordinate to a cache-friendly string key (`"col,row"`).
+ *
+ * @param coord - Cell coordinate.
+ * @returns Stable string key.
+ */
+export function coordKey(coord) {
+    return `${coord.col},${coord.row}`;
+}