@devmm/puredocs-excel-formula 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,455 @@
+declare const enum FormulaError {
+    None = 0,
+    Null = 1,
+    Div0 = 2,
+    Value = 3,
+    Ref = 4,
+    Name = 5,
+    Num = 6,
+    NA = 7,
+    Calc = 8,
+    Spill = 9
+}
+type FormulaValueKind = 'blank' | 'number' | 'text' | 'boolean' | 'error' | 'array';
+declare class FormulaValue {
+    #private;
+    readonly kind: FormulaValueKind;
+    readonly errorCode: FormulaError;
+    private constructor();
+    static readonly blank: FormulaValue;
+    static readonly zero: FormulaValue;
+    static readonly one: FormulaValue;
+    static readonly true_: FormulaValue;
+    static readonly false_: FormulaValue;
+    static readonly emptyString: FormulaValue;
+    static readonly errorDiv0: FormulaValue;
+    static readonly errorValue: FormulaValue;
+    static readonly errorRef: FormulaValue;
+    static readonly errorName: FormulaValue;
+    static readonly errorNA: FormulaValue;
+    static readonly errorNum: FormulaValue;
+    static readonly errorNull: FormulaValue;
+    static number(v: number): FormulaValue;
+    static text(v: string): FormulaValue;
+    static boolean(v: boolean): FormulaValue;
+    static error(e: FormulaError): FormulaValue;
+    static array(a: ArrayValue): FormulaValue;
+    get isBlank(): boolean;
+    get isNumber(): boolean;
+    get isText(): boolean;
+    get isBoolean(): boolean;
+    get isError(): boolean;
+    get isArray(): boolean;
+    get isNumeric(): boolean;
+    get numberValue(): number;
+    get textValue(): string;
+    get booleanValue(): boolean;
+    get arrayVal(): ArrayValue;
+    coerceToNumber(): FormulaValue;
+    tryAsDouble(): {
+        ok: true;
+        value: number;
+    } | {
+        ok: false;
+    };
+    coerceToBool(): FormulaValue;
+    asText(): string;
+    static areEqual(a: FormulaValue, b: FormulaValue): boolean;
+    /** Excel-compatible sort order: Number/Blank < Text < Boolean. */
+    static compare(a: FormulaValue, b: FormulaValue): number;
+    static errorToString(e: FormulaError): string;
+    static errorFromString(s: string): FormulaError;
+    static fromObjectSync(value: unknown): FormulaValue;
+    toObject(): unknown;
+    toString(): string;
+}
+/**
+ * 2D array value for formula results and range data.
+ * Port of TVE.PureDocs.Excel.Formulas.ArrayValue (C#)
+ */
+declare class ArrayValue {
+    #private;
+    static readonly empty: ArrayValue;
+    readonly rows: number;
+    readonly columns: number;
+    constructor(rows: number, columns: number);
+    get length(): number;
+    get(row: number, col: number): FormulaValue;
+    set(row: number, col: number, value: FormulaValue): void;
+    getFlat(index: number): FormulaValue;
+    setFlat(index: number, value: FormulaValue): void;
+    /** Iterate all values in row-major order. */
+    values(): Iterable<FormulaValue>;
+    toObjectArray(): unknown[];
+    /** Create from a flat array (single column). */
+    static fromFlat(values: FormulaValue[]): ArrayValue;
+    /** Create a 1×1 array wrapping a scalar value (for broadcasting). */
+    static fromScalar(value: FormulaValue): ArrayValue;
+    /** Element-wise broadcasting operation (mirrors ArrayValue.Broadcast in C#). */
+    static broadcast(a: ArrayValue, b: ArrayValue, op: (av: FormulaValue, bv: FormulaValue) => FormulaValue): ArrayValue;
+    /** Implicit intersection: reduce array to scalar based on formula position. */
+    implicitIntersect(formulaRow: number, formulaCol: number, rangeStartRow: number, rangeStartCol: number): FormulaValue;
+    transpose(): ArrayValue;
+}
+
+/**
+ * Tokens produced by the formula lexer.
+ * Port of TVE.PureDocs.Excel.Formulas.FormulaToken + FormulaTokenType (C#)
+ */
+declare const enum TokenType {
+    Number = 0,
+    String = 1,
+    Boolean = 2,
+    CellReference = 3,
+    Colon = 4,
+    Function = 5,
+    LeftParen = 6,
+    RightParen = 7,
+    Comma = 8,
+    Plus = 9,
+    Minus = 10,
+    Multiply = 11,
+    Divide = 12,
+    Power = 13,
+    Percent = 14,
+    Ampersand = 15,
+    Equal = 16,
+    NotEqual = 17,
+    LessThan = 18,
+    LessThanOrEqual = 19,
+    GreaterThan = 20,
+    GreaterThanOrEqual = 21,
+    SheetReference = 22,
+    NamedRange = 23,
+    Exclamation = 24,
+    AtSign = 25,
+    ErrorLiteral = 26,
+    EOF = 27
+}
+interface Token {
+    readonly type: TokenType;
+    readonly value: string;
+    readonly position: number;
+}
+
+/**
+ * Tokenises an Excel formula string into a sequence of tokens.
+ * Full port of TVE.PureDocs.Excel.Formulas.FormulaLexer (C#)
+ *
+ * Supports:
+ *   - String literals ("hello")
+ *   - Error literals (#N/A, #REF!, #VALUE!, etc.)
+ *   - Quoted sheet references ('My Sheet'!A1)
+ *   - Unquoted sheet references (Sheet1!A1)
+ *   - _xlfn. prefix stripping
+ *   - Cell references ($A$1, A1, AA123)
+ *   - Named ranges
+ *   - @ implicit intersection operator
+ *   - All standard operators
+ */
+
+declare class FormulaException extends Error {
+    constructor(message: string);
+}
+declare class FormulaLexer {
+    #private;
+    constructor(formula: string);
+    tokenize(): Token[];
+}
+
+/**
+ * Central registry of all supported Excel functions.
+ * Port of TVE.PureDocs.Excel.Formulas.FunctionRegistry (C#)
+ */
+
+type FormulaFunction = (args: FormulaNode[], ctx: FormulaContext) => FormulaValue;
+interface FunctionDef {
+    readonly name: string;
+    readonly minArgs: number;
+    readonly maxArgs: number;
+    readonly isVolatile: boolean;
+    readonly handler: FormulaFunction;
+}
+declare class FunctionRegistry {
+    #private;
+    /** Lazily-created default registry with all built-in functions registered. */
+    static get default(): FunctionRegistry;
+    /** Registers a function. Name is normalised to UPPERCASE. */
+    register(name: string, handler: FormulaFunction, minArgs?: number, maxArgs?: number, isVolatile?: boolean): void;
+    /** Executes a function by name with argument validation. */
+    execute(name: string, args: FormulaNode[], ctx: FormulaContext): FormulaValue;
+    /** Returns true if the named function is volatile (NOW, RAND, etc.). */
+    isVolatile(name: string): boolean;
+    /** Returns true if the function is registered. */
+    has(name: string): boolean;
+}
+declare namespace FormulaHelper {
+    /** Evaluates a node and coerces to number, propagating errors. */
+    function evalDouble(node: FormulaNode, ctx: FormulaContext): {
+        ok: true;
+        value: number;
+    } | {
+        ok: false;
+        error: FormulaValue;
+    };
+    /** Evaluates a node and coerces to string, propagating errors. */
+    function evalString(node: FormulaNode, ctx: FormulaContext): {
+        ok: true;
+        value: string;
+    } | {
+        ok: false;
+        error: FormulaValue;
+    };
+    /**
+     * Collects numbers from all args (expanding arrays, skipping blanks/text).
+     * Returns false + error value if any arg is an error.
+     */
+    function collectNumbers(args: FormulaNode[], ctx: FormulaContext): {
+        ok: true;
+        values: number[];
+    } | {
+        ok: false;
+        error: FormulaValue;
+    };
+    /** Flattens all args into FormulaValue array (expanding arrays). */
+    function flattenArgs(args: FormulaNode[], ctx: FormulaContext): FormulaValue[];
+    /** Matches a criteria string (e.g. ">5", "=hello", "*partial*") against a value. */
+    function matchesCriteria(value: FormulaValue, criteria: string): boolean;
+}
+
+interface WorksheetLike {
+    getCellValue(reference: string): unknown;
+    name: string;
+}
+interface WorkbookLike {
+    worksheets: readonly WorksheetLike[];
+    getWorksheet(name: string): WorksheetLike;
+}
+declare class FormulaContext {
+    #private;
+    /** Row of the formula cell (for @ implicit intersection). */
+    formulaRow: number;
+    /** Column of the formula cell (for @ implicit intersection). */
+    formulaCol: number;
+    /** Optional workbook reference for cross-sheet references. */
+    workbook?: WorkbookLike;
+    constructor(sheet: WorksheetLike, formulaRow?: number, formulaCol?: number, evaluating?: Set<string>, registry?: FunctionRegistry);
+    get worksheet(): WorksheetLike;
+    getCellValue(cellReference: string): FormulaValue;
+    getRangeValues(startRef: string, endRef: string): FormulaValue;
+    getSheetCellValue(sheetName: string, cellReference: string): FormulaValue;
+    getSheetRangeValues(sheetName: string, startRef: string, endRef: string): FormulaValue;
+    resolveNamedRange(_name: string): FormulaValue;
+    getRangeBounds(startRef: string, endRef: string): {
+        startRow: number;
+        startCol: number;
+        endRow: number;
+        endCol: number;
+    };
+    evaluateFunction(name: string, args: FormulaNode[]): FormulaValue;
+}
+
+/**
+ * AST node types for formula expressions.
+ * Port of TVE.PureDocs.Excel.Formulas.FormulaNode (C#)
+ */
+
+declare abstract class FormulaNode {
+    abstract evaluate(ctx: FormulaContext): FormulaValue;
+}
+declare class NumberNode extends FormulaNode {
+    readonly value: number;
+    constructor(value: number);
+    evaluate(): FormulaValue;
+}
+declare class StringNode extends FormulaNode {
+    readonly value: string;
+    constructor(value: string);
+    evaluate(): FormulaValue;
+}
+declare class BooleanNode extends FormulaNode {
+    readonly value: boolean;
+    constructor(value: boolean);
+    evaluate(): FormulaValue;
+}
+declare class ErrorNode extends FormulaNode {
+    readonly errorValue: FormulaValue;
+    constructor(errorValue: FormulaValue);
+    evaluate(): FormulaValue;
+}
+/** Represents an empty/omitted argument in a function call (e.g. IF(A1,,0)). */
+declare class BlankNode extends FormulaNode {
+    evaluate(): FormulaValue;
+}
+declare class CellReferenceNode extends FormulaNode {
+    readonly reference: string;
+    constructor(reference: string);
+    evaluate(ctx: FormulaContext): FormulaValue;
+}
+declare class RangeReferenceNode extends FormulaNode {
+    readonly startRef: string;
+    readonly endRef: string;
+    constructor(startRef: string, endRef: string);
+    evaluate(ctx: FormulaContext): FormulaValue;
+}
+declare class SheetCellReferenceNode extends FormulaNode {
+    readonly sheetName: string;
+    readonly cellReference: string;
+    constructor(sheetName: string, cellReference: string);
+    evaluate(ctx: FormulaContext): FormulaValue;
+}
+declare class SheetRangeReferenceNode extends FormulaNode {
+    readonly sheetName: string;
+    readonly startRef: string;
+    readonly endRef: string;
+    constructor(sheetName: string, startRef: string, endRef: string);
+    evaluate(ctx: FormulaContext): FormulaValue;
+}
+declare class NamedRangeNode extends FormulaNode {
+    readonly name: string;
+    constructor(name: string);
+    evaluate(ctx: FormulaContext): FormulaValue;
+}
+declare const enum BinaryOperator {
+    Add = 0,
+    Subtract = 1,
+    Multiply = 2,
+    Divide = 3,
+    Power = 4,
+    Concatenate = 5,
+    Equal = 6,
+    NotEqual = 7,
+    LessThan = 8,
+    LessThanOrEqual = 9,
+    GreaterThan = 10,
+    GreaterThanOrEqual = 11
+}
+declare const enum UnaryOperator {
+    Negate = 0,
+    Plus = 1,
+    Percent = 2
+}
+declare class BinaryOpNode extends FormulaNode {
+    #private;
+    readonly left: FormulaNode;
+    readonly op: BinaryOperator;
+    readonly right: FormulaNode;
+    constructor(left: FormulaNode, op: BinaryOperator, right: FormulaNode);
+    evaluate(ctx: FormulaContext): FormulaValue;
+}
+declare class UnaryOpNode extends FormulaNode {
+    readonly op: UnaryOperator;
+    readonly operand: FormulaNode;
+    constructor(op: UnaryOperator, operand: FormulaNode);
+    evaluate(ctx: FormulaContext): FormulaValue;
+}
+/** @ implicit intersection operator (Excel 365). */
+declare class ImplicitIntersectionNode extends FormulaNode {
+    readonly inner: FormulaNode;
+    constructor(inner: FormulaNode);
+    evaluate(ctx: FormulaContext): FormulaValue;
+}
+declare class FunctionCallNode extends FormulaNode {
+    readonly functionName: string;
+    readonly args: FormulaNode[];
+    constructor(functionName: string, args: FormulaNode[]);
+    evaluate(ctx: FormulaContext): FormulaValue;
+}
+
+/**
+ * Recursive descent parser converting formula tokens into an AST.
+ * Port of TVE.PureDocs.Excel.Formulas.FormulaParser (C#)
+ *
+ * Operator precedence (low → high):
+ *   Comparison: =, <>, <, <=, >, >=
+ *   Concatenation: &
+ *   Addition/Subtraction: +, -
+ *   Multiplication/Division: *, /
+ *   Unary: +, -, @ (prefix)
+ *   Power: ^ (right-associative)
+ *   Percent: % (postfix)
+ *   Primary: literals, refs, functions, parentheses
+ */
+
+declare class FormulaParser {
+    #private;
+    constructor(tokens: Token[]);
+    parse(): FormulaNode;
+}
+
+/**
+ * Parses a formula string to an AST, with LRU caching.
+ */
+declare function parseFormula(formula: string): FormulaNode;
+/**
+ * Evaluates a formula string against a worksheet.
+ * Mirrors FormulaEvaluator.Evaluate() in C#.
+ */
+declare function evaluateFormula(formula: string, sheet: WorksheetLike, options?: {
+    workbook?: WorkbookLike;
+    formulaRow?: number;
+    formulaCol?: number;
+}): FormulaValue;
+declare function clearAstCache(): void;
+declare function getAstCacheStats(): {
+    size: number;
+    hits: number;
+    misses: number;
+    hitRate: number;
+};
+declare function setAstCacheCapacity(capacity: number): void;
+
+/**
+ * Least-Recently-Used cache using JavaScript Map insertion-order semantics.
+ * Port of TVE.PureDocs.Excel.Formulas.LruCache<TKey, TValue> (C#)
+ *
+ * JS Map maintains insertion order, so LRU eviction is simply:
+ *   delete oldest key = map.keys().next().value
+ *   move to end = delete + re-insert
+ *
+ * This is simpler and faster than the C# LinkedList + Dictionary approach.
+ */
+declare class LruCache<K, V> {
+    #private;
+    constructor(capacity: number);
+    get capacity(): number;
+    get size(): number;
+    get hits(): number;
+    get misses(): number;
+    get evictions(): number;
+    get hitRate(): number;
+    /**
+     * Returns the value for key, or undefined if not present.
+     * Moves the accessed key to the "most recently used" end.
+     */
+    get(key: K): V | undefined;
+    /**
+     * Inserts or updates a key-value pair.
+     * Evicts the least-recently-used entry if over capacity.
+     */
+    set(key: K, value: V): void;
+    /** Removes a key from the cache. Returns true if it existed. */
+    delete(key: K): boolean;
+    /** Returns true if the key is present (does NOT update LRU order). */
+    has(key: K): boolean;
+    /** Removes all entries and resets statistics. */
+    clear(): void;
+    /** Resizes the cache, evicting oldest entries if necessary. */
+    resize(newCapacity: number): void;
+}
+
+declare function registerMath(r: FunctionRegistry): void;
+
+declare function registerText(r: FunctionRegistry): void;
+
+declare function registerLogical(r: FunctionRegistry): void;
+
+declare function registerDate(r: FunctionRegistry): void;
+
+declare function registerLookup(r: FunctionRegistry): void;
+
+declare function registerStatistical(r: FunctionRegistry): void;
+
+declare function registerInfo(r: FunctionRegistry): void;
+
+export { ArrayValue, BinaryOpNode, BinaryOperator, BlankNode, BooleanNode, CellReferenceNode, ErrorNode, FormulaContext, FormulaError, FormulaException, type FormulaFunction, FormulaHelper, FormulaLexer, FormulaNode, FormulaParser, FormulaValue, type FormulaValueKind, FunctionCallNode, type FunctionDef, FunctionRegistry, ImplicitIntersectionNode, LruCache, NamedRangeNode, NumberNode, RangeReferenceNode, SheetCellReferenceNode, SheetRangeReferenceNode, StringNode, type Token, TokenType, UnaryOpNode, UnaryOperator, type WorkbookLike, type WorksheetLike, clearAstCache, evaluateFormula, getAstCacheStats, parseFormula, registerDate, registerInfo, registerLogical, registerLookup, registerMath, registerStatistical, registerText, setAstCacheCapacity };