@cj-tech-master/excelts 9.2.1 → 9.3.0

package/dist/cjs/modules/formula/syntax/parser.js

@@ -0,0 +1,440 @@
+"use strict";
+/**
+ * Formula Parser
+ *
+ * Converts a token stream into an Abstract Syntax Tree (AST).
+ * Implements a Pratt parser (top-down operator precedence) for correct
+ * handling of operator precedence and associativity.
+ *
+ * Excel operator precedence (highest to lowest):
+ *   1. Unary + / - / %
+ *   2. ^  (exponentiation, right-assoc)
+ *   3. * /
+ *   4. + -
+ *   5. &  (concatenation)
+ *   6. = <> < > <= >=  (comparison)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parse = parse;
+// ============================================================================
+// Operator Precedence
+// ============================================================================
+function prefixBindingPower(op) {
+    switch (op) {
+        case "+":
+        case "-":
+            // Must be lower than ^ (60/61) so that -2^3 parses as -(2^3), not (-2)^3.
+            // Excel: -2^2 = -4, not 4.
+            return 55;
+        default:
+            return 0;
+    }
+}
+function infixBindingPower(op) {
+    // Returns [left bp, right bp]. Higher = tighter binding.
+    // Left < Right for left-associative, Left > Right for right-associative.
+    switch (op) {
+        case "=":
+        case "<>":
+        case "<":
+        case ">":
+        case "<=":
+        case ">=":
+            return [10, 11];
+        case "&":
+            return [20, 21];
+        case "+":
+        case "-":
+            return [30, 31];
+        case "*":
+        case "/":
+            return [40, 41];
+        case "^":
+            return [61, 60]; // right-associative
+        // Intersection operator — whitespace between two refs. In Excel
+        // precedence this sits between `:` (range, already handled at the
+        // tokenizer level) and unary +/-. Left-associative, binds tighter
+        // than every arithmetic operator.
+        case " ":
+            return [80, 81];
+        default:
+            return [0, 0];
+    }
+}
+// ============================================================================
+// Parser
+// ============================================================================
+class Parser {
+    constructor(tokens) {
+        this.MAX_DEPTH = 256;
+        this.tokens = tokens;
+        this.pos = 0;
+        this.depth = 0;
+    }
+    enter() {
+        if (++this.depth > this.MAX_DEPTH) {
+            throw new Error(`Formula nested too deep (> ${this.MAX_DEPTH} levels)`);
+        }
+    }
+    leave() {
+        this.depth--;
+    }
+    peek() {
+        return this.tokens[this.pos];
+    }
+    next() {
+        return this.tokens[this.pos++];
+    }
+    expect(type) {
+        const t = this.next();
+        if (!t || t.type !== type) {
+            throw new Error(`Expected token type ${type}, got ${t?.type ?? "EOF"}`);
+        }
+        return t;
+    }
+    // Entry point
+    parse() {
+        const node = this.parseExpr(0);
+        // After parsing a complete expression, every token must have been
+        // consumed. Otherwise inputs like "A1:B2:C3" or "1+2 3" would silently
+        // produce an AST that drops the trailing tokens.
+        if (this.pos !== this.tokens.length) {
+            const t = this.tokens[this.pos];
+            throw new Error(`Unexpected trailing token at position ${this.pos} (type ${t.type})`);
+        }
+        return node;
+    }
+    parseExpr(minBp) {
+        this.enter();
+        try {
+            return this.parseExprInner(minBp);
+        }
+        finally {
+            this.leave();
+        }
+    }
+    parseExprInner(minBp) {
+        let left = this.parsePrefix();
+        while (true) {
+            const t = this.peek();
+            if (!t) {
+                break;
+            }
+            // Postfix: %
+            if (t.type === 14 /* TokenType.Percent */) {
+                this.next();
+                left = { type: 11 /* NodeType.Percent */, operand: left };
+                continue;
+            }
+            // Infix operators
+            if (t.type === 9 /* TokenType.Operator */) {
+                const [lbp, rbp] = infixBindingPower(t.value);
+                if (lbp === 0 || lbp < minBp) {
+                    break;
+                }
+                this.next();
+                const right = this.parseExpr(rbp);
+                left = { type: 7 /* NodeType.BinaryOp */, op: t.value, left, right };
+                continue;
+            }
+            // Intersection: whitespace separating two refs. Modelled as a binary
+            // operation with op=" ". The evaluator resolves both sides to refs
+            // and returns their rectangle intersection (or `#NULL!`).
+            if (t.type === 24 /* TokenType.Intersect */) {
+                const [lbp, rbp] = infixBindingPower(" ");
+                if (lbp < minBp) {
+                    break;
+                }
+                this.next();
+                const right = this.parseExpr(rbp);
+                left = { type: 7 /* NodeType.BinaryOp */, op: " ", left, right };
+                continue;
+            }
+            // Range operator `:` — binds tighter than intersection. Normally
+            // `A1:B2` is merged into a single Range token by the tokenizer,
+            // but patterns like `B11:INDIRECT("B" & ROW()-1)` where one side
+            // is a function call leave the colon as a standalone token. The
+            // evaluator then coerces both sides to references and constructs
+            // the union rectangle.
+            if (t.type === 13 /* TokenType.Colon */) {
+                // Right-biased binding power to guarantee higher precedence than
+                // every other operator in the table above.
+                const lbp = 100;
+                const rbp = 101;
+                if (lbp < minBp) {
+                    break;
+                }
+                this.next();
+                const right = this.parseExpr(rbp);
+                left = { type: 7 /* NodeType.BinaryOp */, op: ":", left, right };
+                continue;
+            }
+            break;
+        }
+        return left;
+    }
+    parsePrefix() {
+        this.enter();
+        try {
+            const result = this.parsePrefixInner();
+            // If the SheetRef consumer below set pendingSheet but the prefix that
+            // followed wasn't a ref (CellRef / Range / ColRange / RowRange), the
+            // sheet qualifier would leak into the next parse and silently attach
+            // itself to an unrelated node. Detect it here.
+            if (this.pendingSheet !== undefined) {
+                const sheet = this.pendingSheet;
+                this.pendingSheet = undefined;
+                this.pendingEndSheet = undefined;
+                throw new Error(`Sheet reference '${sheet}' not followed by a cell or range`);
+            }
+            return result;
+        }
+        finally {
+            this.leave();
+        }
+    }
+    parsePrefixInner() {
+        const t = this.peek();
+        if (!t) {
+            throw new Error("Unexpected end of formula");
+        }
+        // SheetRef: consume and set pending sheet for next cell/range
+        if (t.type === 7 /* TokenType.SheetRef */) {
+            this.next();
+            this.pendingSheet = t.sheetName;
+            this.pendingEndSheet = t.endSheetName;
+            return this.parsePrefix();
+        }
+        // Unary prefix: + -
+        if (t.type === 18 /* TokenType.UnaryPrefix */) {
+            this.next();
+            const bp = prefixBindingPower(t.value);
+            const operand = this.parseExpr(bp);
+            return { type: 8 /* NodeType.UnaryOp */, op: t.value, operand };
+        }
+        // @ implicit intersection prefix (Excel 365)
+        if (t.type === 23 /* TokenType.AtSign */) {
+            this.next();
+            const operand = this.parseExpr(55); // same precedence as unary +/-
+            return { type: 8 /* NodeType.UnaryOp */, op: "@", operand };
+        }
+        // Number literal
+        if (t.type === 1 /* TokenType.Number */) {
+            this.next();
+            const n = parseFloat(t.value);
+            // Reject non-finite literals at parse time. `1e400` would otherwise
+            // become `Infinity` and flow through arithmetic, requiring every
+            // downstream consumer to guard. Surfacing the overflow as a #NUM!
+            // error node keeps the engine's invariant that numeric values are
+            // always finite.
+            if (!Number.isFinite(n)) {
+                return { type: 4 /* NodeType.Error */, value: "#NUM!" };
+            }
+            return { type: 1 /* NodeType.Number */, value: n };
+        }
+        // String literal
+        if (t.type === 2 /* TokenType.String */) {
+            this.next();
+            return { type: 2 /* NodeType.String */, value: t.value };
+        }
+        // Boolean literal
+        if (t.type === 3 /* TokenType.Boolean */) {
+            this.next();
+            return { type: 3 /* NodeType.Boolean */, value: t.value === "TRUE" };
+        }
+        // Error literal
+        if (t.type === 4 /* TokenType.Error */) {
+            this.next();
+            return { type: 4 /* NodeType.Error */, value: t.value };
+        }
+        // Parenthesized expression
+        if (t.type === 10 /* TokenType.OpenParen */) {
+            this.next();
+            const expr = this.parseExpr(0);
+            this.expect(11 /* TokenType.CloseParen */);
+            return expr;
+        }
+        // Array constant: {1,2;3,4}
+        if (t.type === 15 /* TokenType.OpenBrace */) {
+            return this.parseArrayConstant();
+        }
+        // Function call: NAME(args)
+        if (t.type === 8 /* TokenType.Function */) {
+            return this.parseFunctionCall();
+        }
+        // Cell reference (may become range via tokenizer)
+        if (t.type === 5 /* TokenType.CellRef */) {
+            this.next();
+            const ref = this.parseCellRefFromToken(t);
+            const sheet = this.pendingSheet;
+            const endSheet = this.pendingEndSheet;
+            this.pendingSheet = undefined;
+            this.pendingEndSheet = undefined;
+            ref.sheet = sheet;
+            ref.endSheet = endSheet;
+            return ref;
+        }
+        // Range reference (already parsed by tokenizer as A1:B2)
+        if (t.type === 6 /* TokenType.Range */) {
+            this.next();
+            const sheet = this.pendingSheet;
+            const endSheet = this.pendingEndSheet;
+            this.pendingSheet = undefined;
+            this.pendingEndSheet = undefined;
+            return this.parseRangeFromToken(t, sheet, endSheet);
+        }
+        // Named range / defined name
+        if (t.type === 19 /* TokenType.Name */) {
+            this.next();
+            return { type: 12 /* NodeType.Name */, name: t.value };
+        }
+        // Whole-column range (e.g. A:B, $C:$D)
+        if (t.type === 20 /* TokenType.ColRange */) {
+            this.next();
+            const sheet = this.pendingSheet;
+            const endSheet = this.pendingEndSheet;
+            this.pendingSheet = undefined;
+            this.pendingEndSheet = undefined;
+            const parts = t.value.split(":");
+            const startCol = parts[0].replace(/\$/g, "").toUpperCase();
+            const endCol = parts[1].replace(/\$/g, "").toUpperCase();
+            return { type: 13 /* NodeType.ColRangeRef */, startCol, endCol, sheet, endSheet };
+        }
+        // Whole-row range (e.g. 1:5, $3:$7)
+        if (t.type === 21 /* TokenType.RowRange */) {
+            this.next();
+            const sheet = this.pendingSheet;
+            const endSheet = this.pendingEndSheet;
+            this.pendingSheet = undefined;
+            this.pendingEndSheet = undefined;
+            const parts = t.value.split(":");
+            const startRow = parseInt(parts[0].replace(/\$/g, ""), 10);
+            const endRow = parseInt(parts[1].replace(/\$/g, ""), 10);
+            return { type: 14 /* NodeType.RowRangeRef */, startRow, endRow, sheet, endSheet };
+        }
+        // Structured reference (e.g. Table1[Column], [@Column])
+        if (t.type === 22 /* TokenType.StructuredRef */) {
+            this.next();
+            return {
+                type: 15 /* NodeType.StructuredRef */,
+                tableName: t.tableName,
+                columns: t.columns,
+                specials: t.specials
+            };
+        }
+        throw new Error(`Unexpected token: ${t.type}`);
+    }
+    parseCellRefFromToken(t) {
+        return {
+            type: 5 /* NodeType.CellRef */,
+            col: t.col,
+            row: t.row,
+            colAbsolute: t.colAbsolute,
+            rowAbsolute: t.rowAbsolute
+        };
+    }
+    parseRangeFromToken(t, sheet, endSheet) {
+        // Token value is like "A1:B2" or "$A$1:$B$2"
+        const parts = t.value.split(":");
+        const startRef = parseCellRefStr(parts[0]);
+        const endRef = parseCellRefStr(parts[1]);
+        return {
+            type: 6 /* NodeType.RangeRef */,
+            start: { ...startRef, sheet },
+            end: { ...endRef, sheet },
+            sheet,
+            endSheet
+        };
+    }
+    parseFunctionCall() {
+        const nameToken = this.next(); // function name
+        this.expect(10 /* TokenType.OpenParen */);
+        const args = [];
+        if (this.peek()?.type !== 11 /* TokenType.CloseParen */) {
+            // First argument: might be missing if comma is next
+            if (this.peek()?.type === 12 /* TokenType.Comma */) {
+                args.push({ type: 16 /* NodeType.Missing */ });
+            }
+            else {
+                args.push(this.parseExpr(0));
+            }
+            while (this.peek()?.type === 12 /* TokenType.Comma */) {
+                this.next(); // skip comma
+                // Next argument: missing if followed by comma or close paren
+                if (this.peek()?.type === 12 /* TokenType.Comma */ || this.peek()?.type === 11 /* TokenType.CloseParen */) {
+                    args.push({ type: 16 /* NodeType.Missing */ });
+                }
+                else {
+                    args.push(this.parseExpr(0));
+                }
+            }
+        }
+        this.expect(11 /* TokenType.CloseParen */);
+        return {
+            type: 9 /* NodeType.FunctionCall */,
+            name: nameToken.name,
+            args
+        };
+    }
+    parseArrayConstant() {
+        this.next(); // skip {
+        const rows = [];
+        let currentRow = [];
+        if (this.peek()?.type !== 16 /* TokenType.CloseBrace */) {
+            currentRow.push(this.parseExpr(0));
+            while (this.peek()) {
+                const t = this.peek();
+                if (t.type === 12 /* TokenType.Comma */) {
+                    this.next();
+                    currentRow.push(this.parseExpr(0));
+                }
+                else if (t.type === 17 /* TokenType.Semicolon */) {
+                    this.next();
+                    rows.push(currentRow);
+                    currentRow = [];
+                    currentRow.push(this.parseExpr(0));
+                }
+                else {
+                    break;
+                }
+            }
+        }
+        rows.push(currentRow);
+        this.expect(16 /* TokenType.CloseBrace */);
+        return { type: 10 /* NodeType.Array */, rows };
+    }
+}
+// Helper to parse a cell reference string like "$A$1" or "B2"
+function parseCellRefStr(s) {
+    let i = 0;
+    let colAbsolute = false;
+    let rowAbsolute = false;
+    if (s[i] === "$") {
+        colAbsolute = true;
+        i++;
+    }
+    const colStart = i;
+    while (i < s.length && ((s[i] >= "A" && s[i] <= "Z") || (s[i] >= "a" && s[i] <= "z"))) {
+        i++;
+    }
+    const col = s.slice(colStart, i).toUpperCase();
+    if (i < s.length && s[i] === "$") {
+        rowAbsolute = true;
+        i++;
+    }
+    const row = s.slice(i);
+    return {
+        type: 5 /* NodeType.CellRef */,
+        col,
+        row,
+        colAbsolute,
+        rowAbsolute
+    };
+}
+// ============================================================================
+// Public API
+// ============================================================================
+function parse(tokens) {
+    const parser = new Parser(tokens);
+    return parser.parse();
+}

package/dist/cjs/modules/formula/syntax/token-types.js

@@ -0,0 +1,32 @@
+"use strict";
+/**
+ * Token Types for Formula Tokenizer
+ *
+ * Defines a proper discriminated union of all token types.
+ * Each token variant carries only the data relevant to its type.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stripFunctionPrefix = stripFunctionPrefix;
+// ============================================================================
+// Discriminated Union
+// ============================================================================
+/**
+ * Strip Excel's `_XLFN.` / `_XLFN._XLWS.` function-name prefixes.
+ *
+ * Excel emits these prefixes for functions introduced after the original
+ * XLSX schema was frozen (e.g. `_XLFN.FILTER`, `_XLFN._XLWS.SORT`). The
+ * canonical function name is recovered by stripping the prefix.
+ *
+ * The input may or may not already be uppercased — this helper does not
+ * alter case; callers that compare against an uppercase table should
+ * uppercase first (or compare case-insensitively).
+ */
+function stripFunctionPrefix(name) {
+    if (name.startsWith("_XLFN._XLWS.")) {
+        return name.slice(12);
+    }
+    if (name.startsWith("_XLFN.")) {
+        return name.slice(6);
+    }
+    return name;
+}