@ricsam/formula-engine 0.0.1

package/dist/types/parser/ast.d.ts

@@ -0,0 +1,275 @@
+/**
+ * Abstract Syntax Tree (AST) node definitions for formula parsing
+ */
+import type { CellValue, FormulaError, SpreadsheetRange } from "../core/types";
+/**
+ * Base interface for all AST nodes
+ */
+type ASTNodeBase = {
+    position?: {
+        start: number;
+        end: number;
+    };
+};
+/**
+ * Literal value node (number, string, boolean, error)
+ */
+export type ValueNode = ASTNodeBase & {
+    type: "value";
+    value: CellValue;
+};
+/**
+ * Cell reference node (e.g., A1, Sheet1!B2)
+ */
+export type ReferenceNode = ASTNodeBase & {
+    type: "reference";
+    address: {
+        colIndex: number;
+        rowIndex: number;
+    };
+    sheetName?: string;
+    workbookName?: string;
+    isAbsolute: {
+        col: boolean;
+        row: boolean;
+    };
+};
+/**
+ * Range reference node (e.g., A1:B10)
+ */
+export type RangeNode = ASTNodeBase & {
+    type: "range";
+    sheetName?: string;
+    workbookName?: string;
+    range: SpreadsheetRange;
+    isAbsolute: {
+        start: {
+            col: boolean;
+            row: boolean;
+        };
+        end: {
+            col: boolean;
+            row: boolean;
+        };
+    };
+};
+/**
+ * Function call node (e.g., SUM(A1:A10))
+ */
+export type FunctionNode = ASTNodeBase & {
+    type: "function";
+    name: string;
+    args: ASTNode[];
+};
+/**
+ * Unary operator node (e.g., -A1, +B2)
+ */
+export type UnaryOpNode = ASTNodeBase & {
+    type: "unary-op";
+    operator: "+" | "-" | "%";
+    operand: ASTNode;
+};
+/**
+ * Binary operator node (e.g., A1+B1, C1*D1)
+ */
+export type BinaryOpNode = ASTNodeBase & {
+    type: "binary-op";
+    operator: "+" | "-" | "*" | "/" | "^" | "&" | "=" | "<>" | "<" | ">" | "<=" | ">=";
+    left: ASTNode;
+    right: ASTNode;
+};
+/**
+ * Array literal node (e.g., {1,2,3;4,5,6})
+ */
+export type ArrayNode = ASTNodeBase & {
+    type: "array";
+    elements: ASTNode[][];
+};
+/**
+ * 3D range node (e.g., Sheet1:Sheet3!A1)
+ */
+export type ThreeDRangeNode = ASTNodeBase & {
+    type: "3d-range";
+    startSheet: string;
+    endSheet: string;
+    workbookName?: string;
+    reference: ReferenceNode | RangeNode;
+};
+/**
+ * Structured reference node (e.g., Table1[Column1])
+ */
+export type StructuredReferenceNode = ASTNodeBase & {
+    type: "structured-reference";
+    tableName?: string;
+    sheetName?: string;
+    workbookName?: string;
+    cols?: {
+        startCol: string;
+        endCol: string;
+    };
+    selector?: "#All" | "#Data" | "#Headers";
+    isCurrentRow: boolean;
+};
+/**
+ * Infinity literal node
+ */
+export type InfinityNode = ASTNodeBase & {
+    type: "infinity";
+};
+export type ASTNode = ValueNode | ReferenceNode | RangeNode | FunctionNode | UnaryOpNode | BinaryOpNode | ArrayNode | NamedExpressionNode | ErrorNode | EmptyNode | ThreeDRangeNode | StructuredReferenceNode | InfinityNode;
+/**
+ * Named expression reference node
+ */
+export type NamedExpressionNode = ASTNodeBase & {
+    type: "named-expression";
+    name: string;
+    sheetName?: string;
+    workbookName?: string;
+};
+/**
+ * Error node for parsing errors
+ */
+export type ErrorNode = ASTNodeBase & {
+    type: "error";
+    error: FormulaError;
+    message: string;
+};
+export type EmptyNode = ASTNodeBase & {
+    type: "empty";
+};
+/**
+ * Helper function to create a value node
+ */
+export declare function createValueNode(value: CellValue, position?: {
+    start: number;
+    end: number;
+}): ValueNode;
+export declare function createEmptyNode(position?: {
+    start: number;
+    end: number;
+}): EmptyNode;
+/**
+ * Helper function to create a reference node
+ */
+export declare function createReferenceNode({ address, isAbsolute, position, sheetName, workbookName, }: {
+    address: {
+        colIndex: number;
+        rowIndex: number;
+    };
+    isAbsolute: {
+        col: boolean;
+        row: boolean;
+    };
+    position?: {
+        start: number;
+        end: number;
+    };
+    sheetName?: string;
+    workbookName?: string;
+}): ReferenceNode;
+/**
+ * Helper function to create a range node
+ */
+export declare function createRangeNode({ sheetName, workbookName, range, isAbsolute, position, }: {
+    sheetName?: string;
+    workbookName?: string;
+    range: SpreadsheetRange;
+    isAbsolute: RangeNode["isAbsolute"];
+    position?: {
+        start: number;
+        end: number;
+    };
+}): RangeNode;
+/**
+ * Helper function to create a function node
+ */
+export declare function createFunctionNode(name: string, args: ASTNode[], position?: {
+    start: number;
+    end: number;
+}): FunctionNode;
+/**
+ * Helper function to create a unary operator node
+ */
+export declare function createUnaryOpNode(operator: UnaryOpNode["operator"], operand: ASTNode, position?: {
+    start: number;
+    end: number;
+}): UnaryOpNode;
+/**
+ * Helper function to create a binary operator node
+ */
+export declare function createBinaryOpNode(operator: BinaryOpNode["operator"], left: ASTNode, right: ASTNode, position?: {
+    start: number;
+    end: number;
+}): BinaryOpNode;
+/**
+ * Helper function to create an array node
+ */
+export declare function createArrayNode(elements: ASTNode[][], position?: {
+    start: number;
+    end: number;
+}): ArrayNode;
+/**
+ * Helper function to create a named expression node
+ */
+export declare function createNamedExpressionNode(name: string, position?: {
+    start: number;
+    end: number;
+}, sheetName?: string, workbookName?: string): NamedExpressionNode;
+/**
+ * Helper function to create an error node
+ */
+export declare function createErrorNode(error: FormulaError, message: string, position?: {
+    start: number;
+    end: number;
+}): ErrorNode;
+/**
+ * Helper function to create a 3D range node
+ */
+export declare function createThreeDRangeNode(startSheet: string, endSheet: string, reference: ReferenceNode | RangeNode, position?: {
+    start: number;
+    end: number;
+}, workbookName?: string): ThreeDRangeNode;
+/**
+ * Helper function to create a structured reference node
+ */
+export declare function createStructuredReferenceNode({ tableName, sheetName, workbookName, cols, selector, isCurrentRow, position, }: {
+    tableName?: string;
+    sheetName?: string;
+    workbookName?: string;
+    cols?: {
+        startCol: string;
+        endCol: string;
+    };
+    selector?: "#All" | "#Data" | "#Headers";
+    isCurrentRow?: boolean;
+    position?: {
+        start: number;
+        end: number;
+    };
+}): StructuredReferenceNode;
+/**
+ * Helper function to create an infinity node
+ */
+export declare function createInfinityNode(position?: {
+    start: number;
+    end: number;
+}): InfinityNode;
+/**
+ * AST visitor interface for traversing the tree
+ */
+export interface ASTVisitor<T = void> {
+    visitValue?(node: ValueNode): T;
+    visitReference?(node: ReferenceNode): T;
+    visitRange?(node: RangeNode): T;
+    visitFunction?(node: FunctionNode): T;
+    visitUnaryOp?(node: UnaryOpNode): T;
+    visitBinaryOp?(node: BinaryOpNode): T;
+    visitArray?(node: ArrayNode): T;
+    visitNamedExpression?(node: NamedExpressionNode): T;
+    visitError?(node: ErrorNode): T;
+    visitEmpty?(node: EmptyNode): T;
+    visitThreeDRange?(node: ThreeDRangeNode): T;
+    visitStructuredReference?(node: StructuredReferenceNode): T;
+    visitInfinity?(node: InfinityNode): T;
+}
+export {};

package/dist/types/parser/formatter.d.ts

@@ -0,0 +1,6 @@
+import { type SerializedCellValue } from "../core/types";
+import type { ASTNode } from "./ast";
+export declare function astToString(ast: ASTNode): string;
+export declare function formatFormula(formula: string): string;
+export declare function normalizeSerializedCellValue(value: SerializedCellValue): SerializedCellValue;
+export declare function isSerializedCellValueEqual(a: SerializedCellValue, b: SerializedCellValue): boolean;

package/dist/types/parser/grammar.d.ts

@@ -0,0 +1,203 @@
+/**
+ * Grammar rules and operator precedence for formula parsing
+ */
+import type { BinaryOpNode } from "./ast";
+/**
+ * Operator precedence levels (higher number = higher precedence)
+ */
+export declare const OPERATOR_PRECEDENCE: Record<string, number>;
+/**
+ * Operator associativity
+ */
+type Associativity = "left" | "right";
+export declare const OPERATOR_ASSOCIATIVITY: Record<string, Associativity>;
+/**
+ * Check if a string is a valid binary operator
+ */
+export declare function isBinaryOperator(op: string): op is BinaryOpNode["operator"];
+/**
+ * Get operator precedence
+ */
+export declare function getOperatorPrecedence(op: string): number;
+/**
+ * Get operator associativity
+ */
+export declare function getOperatorAssociativity(op: string): Associativity;
+/**
+ * Compare operator precedence
+ * Returns:
+ *  - positive if op1 has higher precedence than op2
+ *  - negative if op1 has lower precedence than op2
+ *  - 0 if they have the same precedence
+ */
+export declare function compareOperatorPrecedence(op1: string, op2: string): number;
+/**
+ * Built-in function names that don't require parentheses in some contexts
+ */
+export declare const SPECIAL_FUNCTIONS: Set<string>;
+/**
+ * Special constants
+ */
+export declare const SPECIAL_CONSTANTS: Set<string>;
+/**
+ * Functions that accept variable number of arguments
+ */
+export declare const VARIADIC_FUNCTIONS: Set<string>;
+/**
+ * Functions that require at least one argument
+ */
+export declare const REQUIRED_ARG_FUNCTIONS: Set<string>;
+/**
+ * Reserved keywords that cannot be used as names
+ */
+export declare const RESERVED_KEYWORDS: Set<string>;
+/**
+ * Check if a name is a reserved keyword
+ */
+export declare function isReservedKeyword(name: string): boolean;
+/**
+ * Grammar production rules (in BNF-like notation):
+ *
+ * Formula ::= Expression
+ *
+ * Expression ::= ComparisonExpr
+ *
+ * ComparisonExpr ::= ConcatExpr (ComparisonOp ConcatExpr)*
+ * ComparisonOp ::= '=' | '<>' | '<' | '>' | '<=' | '>='
+ *
+ * ConcatExpr ::= AddExpr ('&' AddExpr)*
+ *
+ * AddExpr ::= MultExpr (AddOp MultExpr)*
+ * AddOp ::= '+' | '-'
+ *
+ * MultExpr ::= PowerExpr (MultOp PowerExpr)*
+ * MultOp ::= '*' | '/'
+ *
+ * PowerExpr ::= UnaryExpr ('^' PowerExpr)?  // Right associative
+ *
+ * UnaryExpr ::= UnaryOp UnaryExpr | PostfixExpr
+ * UnaryOp ::= '+' | '-'
+ *
+ * PostfixExpr ::= PrimaryExpr ('%')?
+ *
+ * PrimaryExpr ::= Number
+ *              | String
+ *              | Boolean
+ *              | Error
+ *              | CellReference
+ *              | RangeReference
+ *              | NamedExpression
+ *              | FunctionCall
+ *              | ArrayLiteral
+ *              | '(' Expression ')'
+ *
+ * CellReference ::= (SheetName '!')? AbsoluteIndicator? Column AbsoluteIndicator? Row
+ * RangeReference ::= CellReference ':' CellReference
+ *
+ * SheetName ::= Identifier | '\'' AnyCharsExceptQuote '\''
+ * AbsoluteIndicator ::= '$'
+ *
+ * NamedExpression ::= Identifier  // Not followed by '(' or ':'
+ *
+ * FunctionCall ::= FunctionName '(' ArgumentList? ')'
+ * ArgumentList ::= Expression (',' Expression)*
+ *
+ * ArrayLiteral ::= '{' ArrayRows '}'
+ * ArrayRows ::= ArrayRow (';' ArrayRow)*
+ * ArrayRow ::= Expression (',' Expression)*
+ *
+ * Number ::= [+-]? [0-9]+ ('.' [0-9]+)? ([eE] [+-]? [0-9]+)?
+ * String ::= '"' (AnyCharExceptQuote | '""')* '"'
+ * Boolean ::= 'TRUE' | 'FALSE'
+ * Error ::= '#DIV/0!' | '#N/A' | '#NAME?' | '#NUM!' | '#REF!' | '#VALUE!' | '#CYCLE!' | '#ERROR!'
+ * Identifier ::= [A-Za-z_][A-Za-z0-9_]*
+ * FunctionName ::= Identifier
+ */
+/**
+ * Cell reference patterns
+ */
+export declare const CELL_REFERENCE_PATTERNS: {
+    COLUMN: RegExp;
+    COLUMN_WITH_ABSOLUTE: RegExp;
+    ROW: RegExp;
+    ROW_WITH_ABSOLUTE: RegExp;
+    CELL: RegExp;
+    SHEET_QUALIFIED: RegExp;
+    SHEET_RANGE_QUALIFIED: RegExp;
+    INFINITE_COLUMN: RegExp;
+    INFINITE_ROW: RegExp;
+    OPEN_ENDED_INFINITY: RegExp;
+    OPEN_ENDED_COLUMN: RegExp;
+    OPEN_ENDED_ROW: RegExp;
+    TABLE_REFERENCE: RegExp;
+    CURRENT_ROW_REFERENCE: RegExp;
+    TABLE_SELECTOR: RegExp;
+};
+/**
+ * Validate a column reference
+ */
+export declare function isValidColumn(col: string): boolean;
+/**
+ * Validate a row reference
+ */
+export declare function isValidRow(row: string): boolean;
+/**
+ * Parse a cell reference into components
+ */
+interface ParsedCellReference {
+    sheet?: string;
+    colAbsolute: boolean;
+    col: string;
+    rowAbsolute: boolean;
+    row: string;
+}
+interface ParsedInfiniteRange {
+    sheet?: string;
+    type: "column" | "row";
+    startAbsolute: boolean;
+    start: string;
+    endAbsolute: boolean;
+    end: string;
+}
+export declare function parseCellReference(ref: string): ParsedCellReference | null;
+export declare function parseInfiniteRange(ref: string): ParsedInfiniteRange | null;
+/**
+ * Parse open-ended range patterns (A5:INFINITY, A5:D, A5:15)
+ */
+interface ParsedOpenEndedRange {
+    sheet?: string;
+    type: "infinity" | "column-bounded" | "row-bounded";
+    startCol: string;
+    startRow: string;
+    startColAbsolute: boolean;
+    startRowAbsolute: boolean;
+    endCol?: string;
+    endRow?: string;
+    endColAbsolute?: boolean;
+    endRowAbsolute?: boolean;
+}
+export declare function parseOpenEndedRange(ref: string): ParsedOpenEndedRange | null;
+/**
+ * Parse a 3D range reference (e.g., Sheet1:Sheet3!A1)
+ */
+interface Parsed3DReference {
+    startSheet: string;
+    endSheet: string;
+    reference: string;
+}
+export declare function parse3DReference(ref: string): Parsed3DReference | null;
+/**
+ * Parse a structured reference (e.g., Table1[Column1])
+ */
+interface ParsedStructuredReference {
+    tableName: string;
+    columnSpec: string;
+    isCurrentRow?: boolean;
+    selector?: string;
+    cols?: {
+        startCol: string;
+        endCol: string;
+    };
+}
+export declare function parseStructuredReference(ref: string): ParsedStructuredReference | null;
+export {};

package/dist/types/parser/lexer.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Lexer for tokenizing formula strings
+ */
+/**
+ * Token types for formula lexing
+ */
+export type TokenType = 'NUMBER' | 'STRING' | 'BOOLEAN' | 'IDENTIFIER' | 'FUNCTION' | 'OPERATOR' | 'LPAREN' | 'RPAREN' | 'LBRACE' | 'RBRACE' | 'LBRACKET' | 'RBRACKET' | 'COMMA' | 'SEMICOLON' | 'COLON' | 'DOLLAR' | 'EXCLAMATION' | 'AT' | 'HASH' | 'INFINITY' | 'ERROR' | 'EOF' | 'WHITESPACE';
+/**
+ * Token interface
+ */
+export interface Token {
+    type: TokenType;
+    value: string;
+    position: {
+        start: number;
+        end: number;
+    };
+}
+/**
+ * Lexer class for tokenizing formula strings
+ */
+export declare class Lexer {
+    private input;
+    private position;
+    private tokens;
+    constructor(input: string);
+    /**
+     * Tokenize the entire input string
+     */
+    tokenize(): Token[];
+    /**
+     * Get the next token from the input
+     */
+    private nextToken;
+    /**
+     * Read a whitespace token
+     */
+    private readWhitespace;
+    /**
+     * Read a number token
+     */
+    private readNumber;
+    /**
+     * Read a string token (enclosed in double quotes)
+     */
+    private readString;
+    /**
+     * Read a sheet name (enclosed in single quotes)
+     */
+    private readSheetName;
+    /**
+     * Read an error token (e.g., #DIV/0!)
+     */
+    private readError;
+    /**
+     * Read an identifier (cell reference, function name, boolean)
+     */
+    private readIdentifier;
+    /**
+     * Check if current position is whitespace
+     */
+    private isWhitespace;
+    /**
+     * Check if a character is whitespace
+     */
+    private isWhitespaceChar;
+    /**
+     * Check if a character is a digit
+     */
+    private isDigit;
+    /**
+     * Check if a character is alphabetic
+     */
+    private isAlpha;
+    /**
+     * Check if a character is alphanumeric
+     */
+    private isAlnum;
+    /**
+     * Check if a character can be part of an identifier
+     * This includes letters, certain symbols that are commonly used in column names
+     */
+    private isIdentifierChar;
+    /**
+     * Peek ahead to check if we have a table selector
+     */
+    private peekSelector;
+}
+/**
+ * Quick tokenization function
+ */
+export declare function tokenize(input: string): Token[];
+/**
+ * Token stream for parser consumption
+ */
+export declare class TokenStream {
+    private tokens;
+    private position;
+    constructor(tokens: Token[]);
+    /**
+     * Peek at current token without consuming
+     */
+    peek(): Token;
+    /**
+     * Peek ahead by n tokens
+     */
+    peekAhead(n: number): Token | null;
+    /**
+     * Peek at the next token without consuming
+     */
+    peekNext(): Token | null;
+    /**
+     * Consume current token and advance
+     */
+    consume(): Token;
+    /**
+     * Check if current token matches type
+     */
+    match(type: TokenType): boolean;
+    /**
+     * Check if current token matches value
+     */
+    matchValue(value: string): boolean;
+    /**
+     * Consume token if it matches type
+     */
+    consumeIf(type: TokenType): Token | null;
+    /**
+     * Check if at end of stream
+     */
+    isAtEnd(): boolean;
+    /**
+     * Get current position in stream
+     */
+    getPosition(): number;
+    /**
+     * Set position in stream
+     */
+    setPosition(position: number): void;
+    /**
+     * Get all tokens
+     */
+    getTokens(): Token[];
+}