@molecule/api-formula-engine 1.0.0

package/dist/types.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Type definitions for the formula-engine.
+ *
+ * @module
+ */
+/**
+ * Spreadsheet error codes. Errors propagate through expressions: any
+ * arithmetic or function call involving a `FormulaError` returns the
+ * left-most error unchanged (Excel-compatible semantics).
+ */
+export type FormulaErrorCode = '#DIV/0!' | '#VALUE!' | '#REF!' | '#NAME?' | '#NUM!' | '#N/A' | '#CIRC!';
+/**
+ * Spreadsheet error value. Returned (never thrown) by `evaluate`/`getValue`
+ * to allow downstream cells to propagate it like Excel.
+ */
+export interface FormulaError {
+    readonly type: 'error';
+    readonly code: FormulaErrorCode;
+    readonly message?: string;
+}
+/**
+ * Possible cell values. `null` represents an empty cell; numbers, strings,
+ * booleans, and `Date`s are all valid scalar values. `FormulaError`
+ * represents a propagating error.
+ */
+export type CellValue = number | string | boolean | Date | null | FormulaError;
+/**
+ * Cell coordinate as a 0-indexed `{ col, row }`. Column 0 = "A", row 0 = 1
+ * (i.e. `A1` is `{ col: 0, row: 0 }`).
+ */
+export interface CellCoord {
+    readonly col: number;
+    readonly row: number;
+}
+/**
+ * A rectangular range of cells, half-inclusive of both corners.
+ */
+export interface CellRange {
+    readonly start: CellCoord;
+    readonly end: CellCoord;
+}
+/**
+ * AST node kinds emitted by the parser.
+ */
+export type AstNode = NumberLiteralNode | StringLiteralNode | BooleanLiteralNode | ErrorLiteralNode | ReferenceNode | RangeNode | UnaryOpNode | BinaryOpNode | FunctionCallNode;
+/** AST: numeric literal. */
+export interface NumberLiteralNode {
+    readonly kind: 'number';
+    readonly value: number;
+}
+/** AST: string literal (double-quoted). */
+export interface StringLiteralNode {
+    readonly kind: 'string';
+    readonly value: string;
+}
+/** AST: boolean literal (TRUE / FALSE). */
+export interface BooleanLiteralNode {
+    readonly kind: 'boolean';
+    readonly value: boolean;
+}
+/** AST: error literal (`#DIV/0!`, etc.). */
+export interface ErrorLiteralNode {
+    readonly kind: 'errorLiteral';
+    readonly code: FormulaErrorCode;
+}
+/** AST: cell reference (e.g. `A1`, `$A$1`). */
+export interface ReferenceNode {
+    readonly kind: 'reference';
+    readonly coord: CellCoord;
+    /** Original textual representation, preserved for diagnostics. */
+    readonly text: string;
+}
+/** AST: cell range (e.g. `A1:B5`). */
+export interface RangeNode {
+    readonly kind: 'range';
+    readonly range: CellRange;
+    readonly text: string;
+}
+/**
+ * Unary operators supported by the parser.
+ */
+export type UnaryOperator = '+' | '-' | '%';
+/** AST: unary operation (e.g. `-A1`, `A1%`). */
+export interface UnaryOpNode {
+    readonly kind: 'unary';
+    readonly op: UnaryOperator;
+    readonly operand: AstNode;
+}
+/**
+ * Binary operators. `^` = power, `&` = string concat,
+ * `=`/`<>` = equality, `<`/`<=`/`>`/`>=` = ordering.
+ */
+export type BinaryOperator = '+' | '-' | '*' | '/' | '^' | '&' | '=' | '<>' | '<' | '<=' | '>' | '>=';
+/** AST: binary operation. */
+export interface BinaryOpNode {
+    readonly kind: 'binary';
+    readonly op: BinaryOperator;
+    readonly left: AstNode;
+    readonly right: AstNode;
+}
+/** AST: function call (e.g. `SUM(A1:A10)`, `IF(A1>0, "y", "n")`). */
+export interface FunctionCallNode {
+    readonly kind: 'call';
+    readonly name: string;
+    readonly args: AstNode[];
+}
+/**
+ * Function implementation signature. Functions receive already-evaluated
+ * argument expressions: ranges are expanded into flat `CellValue[]`
+ * arrays. Functions return a `CellValue` (including `FormulaError` for
+ * domain errors).
+ */
+export type FormulaFunction = (args: ReadonlyArray<CellValue | ReadonlyArray<CellValue>>, ctx: FunctionContext) => CellValue;
+/**
+ * Context handed to function implementations. Currently exposes the
+ * `now` function so date/time helpers can be made deterministic for
+ * tests via `evaluateOptions.now`.
+ */
+export interface FunctionContext {
+    /** Returns the current date-time. */
+    readonly now: () => Date;
+}
+/**
+ * Options shared by `evaluate` and the `Sheet.recompute` family.
+ */
+export interface EvaluateOptions {
+    /** Override the clock used by `TODAY()` / `NOW()`. Defaults to `Date.now()`. */
+    readonly now?: () => Date;
+}
+/**
+ * Sheet-level configuration. `numCols` / `numRows` are advisory bounds
+ * used when validating references; out-of-bounds references produce
+ * `#REF!`.
+ */
+export interface SheetConfig {
+    /** Maximum number of columns. Default: 16384 (Excel's XFD). */
+    readonly numCols?: number;
+    /** Maximum number of rows. Default: 1048576 (Excel's row count). */
+    readonly numRows?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,6 @@
+/**
+ * Type definitions for the formula-engine.
+ *
+ * @module
+ */
+export {};

package/dist/values.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Value coercion + error helpers shared by the evaluator and built-in
+ * function implementations.
+ *
+ * @module
+ */
+import type { CellValue, FormulaError, FormulaErrorCode } from './types.js';
+/**
+ * Construct a `FormulaError` value.
+ *
+ * @param code - Error code.
+ * @param message - Optional human-readable description.
+ * @returns The error value.
+ */
+export declare function makeError(code: FormulaErrorCode, message?: string): FormulaError;
+/**
+ * Type-guard for `FormulaError`.
+ *
+ * @param value - Cell value to inspect.
+ * @returns `true` if the value is a propagating error.
+ */
+export declare function isError(value: unknown): value is FormulaError;
+/**
+ * Returns the first error encountered in a flat list, or `null` if none.
+ *
+ * @param values - Cell values to scan.
+ * @returns The first error value, or `null`.
+ */
+export declare function firstError(values: ReadonlyArray<CellValue>): FormulaError | null;
+/**
+ * Coerce a cell value to a number (Excel-compatible).
+ *
+ * - `null` → 0
+ * - boolean → 0/1
+ * - `Date` → days since 1899-12-30 (Excel's epoch)
+ * - string → parsed as number, `#VALUE!` if not parseable
+ * - error → propagated unchanged
+ *
+ * @param value - Cell value.
+ * @returns Number, or `FormulaError` on failure.
+ */
+export declare function toNumber(value: CellValue): number | FormulaError;
+/**
+ * Coerce a cell value to a string for display / `&` concatenation.
+ *
+ * @param value - Cell value.
+ * @returns String, or `FormulaError` for propagating errors.
+ */
+export declare function toStringValue(value: CellValue): string | FormulaError;
+/**
+ * Coerce a cell value to a boolean (Excel-compatible).
+ *
+ * @param value - Cell value.
+ * @returns Boolean, or `FormulaError` on failure.
+ */
+export declare function toBoolean(value: CellValue): boolean | FormulaError;
+/**
+ * Convert a `Date` to an Excel serial number (days since 1899-12-30).
+ *
+ * @param date - Date instance.
+ * @returns Excel serial date.
+ */
+export declare function dateToSerial(date: Date): number;
+/**
+ * Convert an Excel serial number to a `Date` (UTC).
+ *
+ * @param serial - Excel serial date.
+ * @returns Date instance.
+ */
+export declare function serialToDate(serial: number): Date;
+/**
+ * Compare two scalar cell values (Excel ordering: number < string,
+ * boolean compared as 0/1 within numbers).
+ *
+ * @param left - Left operand.
+ * @param right - Right operand.
+ * @returns -1, 0, 1, or `FormulaError` if uncomparable.
+ */
+export declare function compareValues(left: CellValue, right: CellValue): number | FormulaError;
+//# sourceMappingURL=values.d.ts.map

package/dist/values.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"values.d.ts","sourceRoot":"","sources":["../src/values.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAE3E;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,gBAAgB,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,YAAY,CAEhF;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,YAAY,CAI7D;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,aAAa,CAAC,SAAS,CAAC,GAAG,YAAY,GAAG,IAAI,CAKhF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,GAAG,YAAY,CAahE;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,GAAG,YAAY,CAWrE;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,GAAG,YAAY,CAYlE;AAKD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAE/C;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAEjD;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,GAAG,MAAM,GAAG,YAAY,CAoCtF"}

package/dist/values.js

@@ -0,0 +1,190 @@
+/**
+ * Value coercion + error helpers shared by the evaluator and built-in
+ * function implementations.
+ *
+ * @module
+ */
+/**
+ * Construct a `FormulaError` value.
+ *
+ * @param code - Error code.
+ * @param message - Optional human-readable description.
+ * @returns The error value.
+ */
+export function makeError(code, message) {
+    return message === undefined ? { type: 'error', code } : { type: 'error', code, message };
+}
+/**
+ * Type-guard for `FormulaError`.
+ *
+ * @param value - Cell value to inspect.
+ * @returns `true` if the value is a propagating error.
+ */
+export function isError(value) {
+    return (typeof value === 'object' && value !== null && value.type === 'error');
+}
+/**
+ * Returns the first error encountered in a flat list, or `null` if none.
+ *
+ * @param values - Cell values to scan.
+ * @returns The first error value, or `null`.
+ */
+export function firstError(values) {
+    for (const v of values) {
+        if (isError(v))
+            return v;
+    }
+    return null;
+}
+/**
+ * Coerce a cell value to a number (Excel-compatible).
+ *
+ * - `null` → 0
+ * - boolean → 0/1
+ * - `Date` → days since 1899-12-30 (Excel's epoch)
+ * - string → parsed as number, `#VALUE!` if not parseable
+ * - error → propagated unchanged
+ *
+ * @param value - Cell value.
+ * @returns Number, or `FormulaError` on failure.
+ */
+export function toNumber(value) {
+    if (isError(value))
+        return value;
+    if (value === null)
+        return 0;
+    if (typeof value === 'number')
+        return value;
+    if (typeof value === 'boolean')
+        return value ? 1 : 0;
+    if (value instanceof Date)
+        return dateToSerial(value);
+    if (typeof value === 'string') {
+        if (value.trim() === '')
+            return 0;
+        const n = Number(value);
+        if (Number.isFinite(n))
+            return n;
+        return makeError('#VALUE!', `Cannot coerce "${value}" to number`);
+    }
+    return makeError('#VALUE!');
+}
+/**
+ * Coerce a cell value to a string for display / `&` concatenation.
+ *
+ * @param value - Cell value.
+ * @returns String, or `FormulaError` for propagating errors.
+ */
+export function toStringValue(value) {
+    if (isError(value))
+        return value;
+    if (value === null)
+        return '';
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value))
+            return makeError('#NUM!');
+        return String(value);
+    }
+    if (typeof value === 'boolean')
+        return value ? 'TRUE' : 'FALSE';
+    if (value instanceof Date)
+        return value.toISOString();
+    return makeError('#VALUE!');
+}
+/**
+ * Coerce a cell value to a boolean (Excel-compatible).
+ *
+ * @param value - Cell value.
+ * @returns Boolean, or `FormulaError` on failure.
+ */
+export function toBoolean(value) {
+    if (isError(value))
+        return value;
+    if (typeof value === 'boolean')
+        return value;
+    if (value === null)
+        return false;
+    if (typeof value === 'number')
+        return value !== 0;
+    if (typeof value === 'string') {
+        const u = value.toUpperCase().trim();
+        if (u === 'TRUE')
+            return true;
+        if (u === 'FALSE')
+            return false;
+        return makeError('#VALUE!', `Cannot coerce "${value}" to boolean`);
+    }
+    return makeError('#VALUE!');
+}
+const EXCEL_EPOCH = Date.UTC(1899, 11, 30);
+const MS_PER_DAY = 86_400_000;
+/**
+ * Convert a `Date` to an Excel serial number (days since 1899-12-30).
+ *
+ * @param date - Date instance.
+ * @returns Excel serial date.
+ */
+export function dateToSerial(date) {
+    return (date.getTime() - EXCEL_EPOCH) / MS_PER_DAY;
+}
+/**
+ * Convert an Excel serial number to a `Date` (UTC).
+ *
+ * @param serial - Excel serial date.
+ * @returns Date instance.
+ */
+export function serialToDate(serial) {
+    return new Date(EXCEL_EPOCH + serial * MS_PER_DAY);
+}
+/**
+ * Compare two scalar cell values (Excel ordering: number < string,
+ * boolean compared as 0/1 within numbers).
+ *
+ * @param left - Left operand.
+ * @param right - Right operand.
+ * @returns -1, 0, 1, or `FormulaError` if uncomparable.
+ */
+export function compareValues(left, right) {
+    if (isError(left))
+        return left;
+    if (isError(right))
+        return right;
+    // null normalizes to 0 / "" depending on the other side
+    if (typeof left === 'number' || typeof left === 'boolean' || left === null) {
+        const ln = toNumber(left);
+        if (isError(ln))
+            return ln;
+        if (typeof right === 'string') {
+            // Excel: numbers always sort before strings
+            return -1;
+        }
+        const rn = toNumber(right);
+        if (isError(rn))
+            return rn;
+        return ln === rn ? 0 : ln < rn ? -1 : 1;
+    }
+    if (left instanceof Date) {
+        const ln = dateToSerial(left);
+        const rn = toNumber(right);
+        if (isError(rn))
+            return rn;
+        return ln === rn ? 0 : ln < rn ? -1 : 1;
+    }
+    if (typeof left === 'string') {
+        if (typeof right === 'number' || typeof right === 'boolean' || right === null) {
+            return 1;
+        }
+        if (right instanceof Date) {
+            return 1;
+        }
+        if (typeof right === 'string') {
+            // Case-insensitive comparison, like Excel.
+            const a = left.toUpperCase();
+            const b = right.toUpperCase();
+            return a === b ? 0 : a < b ? -1 : 1;
+        }
+    }
+    return makeError('#VALUE!');
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@molecule/api-formula-engine",
+  "version": "1.0.0",
+  "description": "Spreadsheet-style formula evaluator: parser, evaluator, dependency tracker for cell graphs with arithmetic, comparison, string ops, references, aggregations, conditionals, date/text functions, and circular-ref detection.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "molecule",
+    "formula",
+    "engine"
+  ],
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "@types/node": "26.1.2",
+    "typescript": "6.0.3",
+    "vitest": "4.1.10"
+  }
+}