@cj-tech-master/excelts 9.2.1 → 9.3.0

package/dist/esm/modules/formula/compile/address-utils.js

@@ -0,0 +1,83 @@
+/**
+ * Formula Address Utilities — Shared helpers for address parsing and conversion.
+ *
+ * These pure functions are used across the compile, runtime, and materialize
+ * layers. Centralizing them here eliminates duplication and ensures consistent
+ * behavior.
+ *
+ * ## Design Constraint
+ *
+ * This module must NOT import from `@excel/utils/col-cache` or any live
+ * workbook type. All functions are self-contained.
+ */
+// ============================================================================
+// Column Letter ↔ Number
+// ============================================================================
+/**
+ * Convert a column letter string (e.g. "A", "AA", "XFD") to a 1-based number.
+ *
+ * - `"A"` → 1
+ * - `"Z"` → 26
+ * - `"AA"` → 27
+ * - `"XFD"` → 16384
+ */
+export function colLetterToNumber(col) {
+    let result = 0;
+    for (let i = 0; i < col.length; i++) {
+        result = result * 26 + (col.charCodeAt(i) - 64); // 'A' = 65
+    }
+    return result;
+}
+const DEFINED_NAME_RANGE_RE = /^(?:'([^']*(?:''[^']*)*)'|([^!]+))!\$([A-Z]+)\$(\d+)(?::\$([A-Z]+)\$(\d+))?$/;
+/**
+ * Parse a defined-name range string like `"Sheet1!$A$1:$B$2"` or `"'Sheet Name'!$C$3"`
+ * into a `ParsedNameRange`. Returns `null` if the format is unrecognized.
+ */
+export function parseDefinedNameRange(rangeStr) {
+    const m = DEFINED_NAME_RANGE_RE.exec(rangeStr);
+    if (!m) {
+        return null;
+    }
+    // Sheet name: quoted (group 1, with '' unescaping) or unquoted (group 2)
+    const sheet = m[1] !== undefined ? m[1].replace(/''/g, "'") : m[2];
+    const startCol = colLetterToNumber(m[3]);
+    const startRow = parseInt(m[4], 10);
+    const endCol = m[5] ? colLetterToNumber(m[5]) : startCol;
+    const endRow = m[6] ? parseInt(m[6], 10) : startRow;
+    return { sheet, startRow, startCol, endRow, endCol };
+}
+/**
+ * Parse a simple cell address like `"A1"`, `"$B$2"`, or `"AA100"`.
+ * Dollar signs are stripped. Returns `null` on parse failure.
+ */
+export function parseSimpleAddress(addr) {
+    const m = /^([A-Z]+)(\d+)$/.exec(addr.replace(/\$/g, ""));
+    if (!m) {
+        return null;
+    }
+    return {
+        row: parseInt(m[2], 10),
+        col: colLetterToNumber(m[1])
+    };
+}
+/**
+ * Parse a cell range string like `"A1:B2"` into a `ParsedRefRange`.
+ * Returns `null` if the format is unrecognized.
+ */
+export function parseRefRange(ref) {
+    const parts = ref.split(":");
+    if (parts.length !== 2) {
+        return null;
+    }
+    const tl = parseSimpleAddress(parts[0]);
+    const br = parseSimpleAddress(parts[1]);
+    if (!tl || !br) {
+        return null;
+    }
+    return {
+        top: Math.min(tl.row, br.row),
+        left: Math.min(tl.col, br.col),
+        bottom: Math.max(tl.row, br.row),
+        right: Math.max(tl.col, br.col)
+    };
+}

package/dist/esm/modules/formula/compile/binder.js

@@ -0,0 +1,487 @@
+/**
+ * Binder — Transform raw AST into BoundExpr.
+ *
+ * The binder performs static symbol resolution:
+ * - Cell/range references → BoundCellRef / BoundAreaRef with resolved sheet
+ * - Defined names → BoundCellRef / BoundAreaRef (if resolvable) or BoundNameExpr
+ * - Structured references → BoundCellRef / BoundAreaRef
+ * - Function calls → BoundCall or BoundSpecialCall
+ * - 3D references → BoundRef3D
+ *
+ * The binder operates on snapshot data only — no live workbook objects.
+ */
+import { resolveDefinedName as resolveDefinedNameFromSnapshot } from "../integration/workbook-snapshot.js";
+import { NodeType } from "../syntax/ast.js";
+import { stripFunctionPrefix } from "../syntax/token-types.js";
+import { colLetterToNumber, parseDefinedNameRange } from "./address-utils.js";
+import { BoundExprKind, boundAreaRef, boundCall, boundCellRef, boundErrorLiteral, boundLiteral, boundNameExpr, boundSpecialCall } from "./bound-ast.js";
+import { resolveStructuredRefRows, buildTableGeometry, resolveStructuredRefColumns } from "./structured-ref-utils.js";
+// ============================================================================
+// Special Form Registry
+// ============================================================================
+const SPECIAL_FORMS = new Set([
+    "IF",
+    "IFERROR",
+    "IFNA",
+    "IFS",
+    "SWITCH",
+    "CHOOSE",
+    "LET",
+    "LAMBDA",
+    "INDIRECT",
+    "OFFSET",
+    "MAP",
+    "REDUCE",
+    "SCAN",
+    "MAKEARRAY",
+    "BYROW",
+    "BYCOL"
+]);
+/**
+ * Map prefixed names to their canonical special form name.
+ */
+function canonicalSpecialForm(name) {
+    const canonical = stripFunctionPrefix(name);
+    if (SPECIAL_FORMS.has(canonical)) {
+        return canonical;
+    }
+    return undefined;
+}
+// ============================================================================
+// Main Bind Function
+// ============================================================================
+/**
+ * Bind a raw AST node to produce a BoundExpr.
+ *
+ * This is the main entry point for the compilation phase. It recursively
+ * walks the AST and resolves all symbols against the snapshot.
+ */
+export function bind(node, ctx) {
+    switch (node.type) {
+        case NodeType.Number:
+            return boundLiteral(node.value);
+        case NodeType.String:
+            return boundLiteral(node.value);
+        case NodeType.Boolean:
+            return boundLiteral(node.value);
+        case NodeType.Error:
+            return boundErrorLiteral(node.value);
+        case NodeType.Missing:
+            return boundLiteral(null);
+        case NodeType.CellRef:
+            return bindCellRef(node, ctx);
+        case NodeType.RangeRef:
+            return bindRangeRef(node, ctx);
+        case NodeType.ColRangeRef:
+            return bindColRangeRef(node, ctx);
+        case NodeType.RowRangeRef:
+            return bindRowRangeRef(node, ctx);
+        case NodeType.BinaryOp:
+            return {
+                kind: BoundExprKind.BinaryOp,
+                op: node.op,
+                left: bind(node.left, ctx),
+                right: bind(node.right, ctx)
+            };
+        case NodeType.UnaryOp:
+            return {
+                kind: BoundExprKind.UnaryOp,
+                op: node.op,
+                operand: bind(node.operand, ctx)
+            };
+        case NodeType.Percent:
+            return {
+                kind: BoundExprKind.Percent,
+                operand: bind(node.operand, ctx)
+            };
+        case NodeType.FunctionCall:
+            return bindFunctionCall(node.name, node.args, ctx);
+        case NodeType.Array:
+            return {
+                kind: BoundExprKind.Array,
+                rows: node.rows.map(row => row.map(elem => bind(elem, ctx)))
+            };
+        case NodeType.Name:
+            return bindName(node.name, ctx);
+        case NodeType.StructuredRef:
+            return bindStructuredRef(node.tableName, node.columns, node.specials, ctx);
+        default:
+            return assertNever(node);
+    }
+}
+/**
+ * Exhaustiveness helper: triggers a compile-time error if `bind` misses a
+ * discriminated-union variant. At runtime, this path is unreachable.
+ */
+function assertNever(x) {
+    throw new Error(`unexpected AST node: ${JSON.stringify(x)}`);
+}
+// ============================================================================
+// Cell Reference Binding
+// ============================================================================
+function bindCellRef(node, ctx) {
+    const sheet = node.sheet ?? ctx.currentSheet;
+    const row = parseInt(node.row, 10);
+    const col = colLetterToNumber(node.col);
+    // Excel's cell coordinate range is 1..1048576 for rows, 1..16384 for
+    // columns. The tokenizer enforces these when recognising cell refs,
+    // but we re-check here because the same binder runs on defined-name
+    // range strings that bypass the tokenizer and could carry arbitrary
+    // large values.
+    if (row < 1 || row > 1048576 || col < 1 || col > 16384) {
+        return boundErrorLiteral("#REF!");
+    }
+    // 3D cell reference: Sheet1:Sheet3!A1
+    if (node.endSheet) {
+        const sheets = getSheetsInRange(ctx.snapshot, sheet, node.endSheet);
+        if (!sheets) {
+            return boundErrorLiteral("#REF!");
+        }
+        const inner = boundCellRef(sheets[0], row, col);
+        return {
+            kind: BoundExprKind.Ref3D,
+            sheets,
+            inner
+        };
+    }
+    // Validate sheet exists
+    if (!ctx.snapshot.worksheetsByName.has(sheet.toLowerCase())) {
+        return boundErrorLiteral("#REF!");
+    }
+    return boundCellRef(sheet, row, col);
+}
+function bindRangeRef(node, ctx) {
+    const sheet = node.sheet ?? ctx.currentSheet;
+    const startRow = parseInt(node.start.row, 10);
+    const startCol = colLetterToNumber(node.start.col);
+    const endRow = parseInt(node.end.row, 10);
+    const endCol = colLetterToNumber(node.end.col);
+    const top = Math.min(startRow, endRow);
+    const bottom = Math.max(startRow, endRow);
+    const left = Math.min(startCol, endCol);
+    const right = Math.max(startCol, endCol);
+    // 3D range reference: Sheet1:Sheet3!A1:B2
+    if (node.endSheet) {
+        const sheets = getSheetsInRange(ctx.snapshot, sheet, node.endSheet);
+        if (!sheets) {
+            return boundErrorLiteral("#REF!");
+        }
+        const inner = boundAreaRef(sheets[0], top, left, bottom, right);
+        return {
+            kind: BoundExprKind.Ref3D,
+            sheets,
+            inner
+        };
+    }
+    return boundAreaRef(sheet, top, left, bottom, right);
+}
+function bindColRangeRef(node, ctx) {
+    const sheet = node.sheet ?? ctx.currentSheet;
+    const startCol = colLetterToNumber(node.startCol);
+    const endCol = colLetterToNumber(node.endCol);
+    const leftCol = Math.min(startCol, endCol);
+    const rightCol = Math.max(startCol, endCol);
+    // Validate sheet exists
+    if (!ctx.snapshot.worksheetsByName.has(sheet.toLowerCase())) {
+        return boundErrorLiteral("#REF!");
+    }
+    // 3D col range: Sheet1:Sheet3!A:B
+    if (node.endSheet) {
+        const sheets = getSheetsInRange(ctx.snapshot, sheet, node.endSheet);
+        if (!sheets) {
+            return boundErrorLiteral("#REF!");
+        }
+        // Return Ref3D wrapping an area for the full column range
+        const inner = boundAreaRef(sheets[0], 1, leftCol, 1048576, rightCol);
+        return {
+            kind: BoundExprKind.Ref3D,
+            sheets,
+            inner
+        };
+    }
+    return {
+        kind: BoundExprKind.ColRangeRef,
+        sheet,
+        leftCol,
+        rightCol
+    };
+}
+function bindRowRangeRef(node, ctx) {
+    const sheet = node.sheet ?? ctx.currentSheet;
+    const topRow = Math.min(node.startRow, node.endRow);
+    const bottomRow = Math.max(node.startRow, node.endRow);
+    // Validate sheet exists
+    if (!ctx.snapshot.worksheetsByName.has(sheet.toLowerCase())) {
+        return boundErrorLiteral("#REF!");
+    }
+    // 3D row range: Sheet1:Sheet3!1:5
+    if (node.endSheet) {
+        const sheets = getSheetsInRange(ctx.snapshot, sheet, node.endSheet);
+        if (!sheets) {
+            return boundErrorLiteral("#REF!");
+        }
+        const inner = boundAreaRef(sheets[0], topRow, 1, bottomRow, 16384);
+        return {
+            kind: BoundExprKind.Ref3D,
+            sheets,
+            inner
+        };
+    }
+    return {
+        kind: BoundExprKind.RowRangeRef,
+        sheet,
+        topRow,
+        bottomRow
+    };
+}
+// ============================================================================
+// Name Binding
+// ============================================================================
+function bindName(name, ctx) {
+    // A lambda parameter (or other compile-time local) shadows any
+    // workbook-level defined name. Without this short-circuit,
+    // `LAMBDA(x, x*2)(10)` would pick up a defined name called `x` that
+    // resolves to a cell reference, computing the cell's value × 2
+    // instead of the lambda argument × 2.
+    if (ctx.localNames && ctx.localNames.has(name.toUpperCase())) {
+        return boundNameExpr(name);
+    }
+    // Try to resolve as a defined name that maps to a cell/range.
+    // Respects scope precedence: sheet-local > workbook-global.
+    const dn = resolveDefinedNameFromSnapshot(ctx.snapshot.definedNames, name, ctx.currentSheet);
+    if (dn) {
+        return resolveDefinedName(dn, ctx);
+    }
+    // Unresolved — could be a LET-bound local variable, a formula-based name,
+    // or a truly unknown name. Return BoundNameExpr for runtime resolution.
+    return boundNameExpr(name);
+}
+function resolveDefinedName(dn, ctx) {
+    if (dn.ranges.length === 0) {
+        return boundErrorLiteral("#NAME?");
+    }
+    // Multi-area names are not supported
+    if (dn.ranges.length > 1) {
+        return boundErrorLiteral("#VALUE!");
+    }
+    const rangeStr = dn.ranges[0];
+    // Try to parse as a cell/range reference
+    const parsed = parseDefinedNameRange(rangeStr);
+    if (parsed) {
+        // Single cell
+        if (parsed.startRow === parsed.endRow && parsed.startCol === parsed.endCol) {
+            return boundCellRef(parsed.sheet, parsed.startRow, parsed.startCol);
+        }
+        // Range
+        return boundAreaRef(parsed.sheet, Math.min(parsed.startRow, parsed.endRow), Math.min(parsed.startCol, parsed.endCol), Math.max(parsed.startRow, parsed.endRow), Math.max(parsed.startCol, parsed.endCol));
+    }
+    // The range string is a formula expression (e.g. "LAMBDA(x,y,x+y)").
+    // This must be resolved at runtime since it may produce a lambda or
+    // depend on the evaluation context. Return a BoundNameExpr.
+    return boundNameExpr(dn.name);
+}
+// ============================================================================
+// Structured Reference Binding
+// ============================================================================
+function bindStructuredRef(tableName, columns, specials, ctx) {
+    // If the table name is empty (implicit @) or specials include #This Row,
+    // we need runtime context (current cell position) to resolve.
+    // Defer to the evaluator.
+    const needsRuntime = tableName === "" || specials.includes("#This Row");
+    // Find the table in the snapshot
+    const table = findTable(ctx.snapshot, tableName);
+    if (!table) {
+        if (needsRuntime) {
+            // Defer to runtime — return BoundStructuredRef
+            return {
+                kind: BoundExprKind.StructuredRef,
+                tableName,
+                columns: [...columns],
+                specials: [...specials]
+            };
+        }
+        return boundErrorLiteral("#REF!");
+    }
+    // If #This Row is present, defer to runtime even if table is found
+    if (needsRuntime) {
+        return {
+            kind: BoundExprKind.StructuredRef,
+            tableName: table.table.name,
+            columns: [...columns],
+            specials: [...specials]
+        };
+    }
+    const resolved = resolveStructuredRefBounds(table, columns, specials);
+    if (!resolved) {
+        return boundErrorLiteral("#REF!");
+    }
+    if (resolved.top === resolved.bottom && resolved.left === resolved.right) {
+        return boundCellRef(resolved.sheet, resolved.top, resolved.left);
+    }
+    return boundAreaRef(resolved.sheet, resolved.top, resolved.left, resolved.bottom, resolved.right);
+}
+function findTable(snapshot, tableName) {
+    if (!tableName) {
+        return null;
+    }
+    // Use the pre-built tablesByName index for O(1) lookup
+    const resolved = snapshot.tablesByName.get(tableName.toLowerCase());
+    if (resolved) {
+        return { table: resolved.table, sheetName: resolved.sheetName };
+    }
+    return null;
+}
+function resolveStructuredRefBounds(tw, columns, specials) {
+    const t = tw.table;
+    const geo = buildTableGeometry(t);
+    const colRange = resolveStructuredRefColumns(columns, t, "strict");
+    if (colRange === "error") {
+        return null;
+    }
+    const rowRange = resolveStructuredRefRows(specials, geo);
+    let rowTop;
+    let rowBottom;
+    if (rowRange === "error") {
+        return null;
+    }
+    else if (rowRange === "thisRow") {
+        // #This Row requires runtime context — use data range as static fallback
+        rowTop = geo.dataRowStart;
+        rowBottom = geo.dataRowEnd;
+    }
+    else {
+        rowTop = rowRange.rowTop;
+        rowBottom = rowRange.rowBottom;
+    }
+    return {
+        sheet: tw.sheetName,
+        top: rowTop,
+        left: colRange.colLeft,
+        bottom: rowBottom,
+        right: colRange.colRight
+    };
+}
+// ============================================================================
+// Function Call Binding
+// ============================================================================
+function bindFunctionCall(name, args, ctx) {
+    const upperName = name.toUpperCase();
+    // Check for special forms (lazy evaluation)
+    const specialName = canonicalSpecialForm(upperName);
+    if (specialName) {
+        // LAMBDA is special: bind it into a BoundLambda if possible
+        if (specialName === "LAMBDA" && args.length >= 1) {
+            return bindLambda(args, ctx);
+        }
+        // LET has the shape LET(name, value, name, value, …, body). The
+        // `name` slots must be treated as pure locals, not resolved against
+        // workbook defined names, or e.g. a defined-name `X` pointing at
+        // `$A$1` would hijack `LET(X, 5, X+1)` and route the final body to
+        // `A1+1` instead of `5+1`. We extend `localNames` to cover every
+        // name slot before recursively binding the rest.
+        if (specialName === "LET" && args.length >= 3) {
+            return bindLet(args, ctx);
+        }
+        // All other special forms: bind args recursively but wrap as BoundSpecialCall
+        const boundArgs = args.map(arg => bind(arg, ctx));
+        return boundSpecialCall(specialName, boundArgs);
+    }
+    // Reference functions that need AST-level access (ROW, COLUMN, ROWS, COLUMNS)
+    // are bound as regular calls — the evaluator handles the AST → BoundExpr
+    // mapping for these since they work the same way with BoundExpr.
+    // Standard eager function call
+    const boundArgs = args.map(arg => bind(arg, ctx));
+    return boundCall(upperName, boundArgs);
+}
+/**
+ * Bind `LET(name1, value1, …, nameN, valueN, body)` with lexical scoping.
+ *
+ * Even-indexed slots (0, 2, 4, …) are Name AST nodes that introduce new
+ * locals. We add each such name to `localNames` progressively — Excel
+ * allows later `value_i` expressions to reference earlier LET-bound
+ * variables, but NOT the variable being defined on the same slot. The
+ * `body` (last arg) sees every local.
+ */
+function bindLet(args, ctx) {
+    // args = [name1, value1, name2, value2, …, body]; length must be odd.
+    if (args.length < 3 || args.length % 2 === 0) {
+        return boundErrorLiteral("#VALUE!");
+    }
+    const locals = ctx.localNames ? new Set(ctx.localNames) : new Set();
+    const boundArgs = [];
+    for (let i = 0; i + 1 < args.length; i += 2) {
+        const nameNode = args[i];
+        if (nameNode.type !== NodeType.Name) {
+            // Not a Name-shaped slot: preserve whatever the user wrote so the
+            // evaluator's own LET implementation can report the error with
+            // better context.
+            boundArgs.push(bind(nameNode, ctx));
+        }
+        else {
+            // Bind the name slot as a runtime-resolved NameExpr rather than
+            // letting `bindName` eagerly pick up a workbook-level defined name.
+            boundArgs.push(boundNameExpr(nameNode.name));
+        }
+        // Bind the value expression with locals-so-far in scope.
+        const valueCtx = { ...ctx, localNames: new Set(locals) };
+        boundArgs.push(bind(args[i + 1], valueCtx));
+        // The just-bound name is now available to subsequent value slots
+        // and to the body.
+        if (nameNode.type === NodeType.Name) {
+            locals.add(nameNode.name.toUpperCase());
+        }
+    }
+    const bodyCtx = { ...ctx, localNames: locals };
+    boundArgs.push(bind(args[args.length - 1], bodyCtx));
+    return boundSpecialCall("LET", boundArgs);
+}
+function bindLambda(args, ctx) {
+    if (args.length < 1) {
+        return boundErrorLiteral("#VALUE!");
+    }
+    const paramNodes = args.slice(0, -1);
+    const bodyNode = args[args.length - 1];
+    const params = [];
+    // Detect duplicate parameter names up front. Excel rejects
+    // `LAMBDA(x, x, x*2)` with #VALUE! rather than silently letting the
+    // second occurrence shadow the first.
+    const seen = new Set();
+    for (const pNode of paramNodes) {
+        if (pNode.type !== NodeType.Name) {
+            return boundErrorLiteral("#VALUE!");
+        }
+        const upper = pNode.name.toUpperCase();
+        if (seen.has(upper)) {
+            return boundErrorLiteral("#VALUE!");
+        }
+        seen.add(upper);
+        params.push(upper);
+    }
+    // Extend the local-name scope with the lambda's parameters so nested
+    // name lookups inside the body bind to runtime locals rather than
+    // same-named workbook defined names.
+    const mergedLocals = ctx.localNames ? new Set(ctx.localNames) : new Set();
+    for (const p of params) {
+        mergedLocals.add(p);
+    }
+    const bodyCtx = { ...ctx, localNames: mergedLocals };
+    return {
+        kind: BoundExprKind.Lambda,
+        params,
+        body: bind(bodyNode, bodyCtx)
+    };
+}
+// ============================================================================
+// 3D Reference Helpers
+// ============================================================================
+function getSheetsInRange(snapshot, startSheet, endSheet) {
+    const allSheets = snapshot.worksheets;
+    const startIdx = allSheets.findIndex(s => s.name.toLowerCase() === startSheet.toLowerCase());
+    const endIdx = allSheets.findIndex(s => s.name.toLowerCase() === endSheet.toLowerCase());
+    if (startIdx === -1 || endIdx === -1) {
+        return null;
+    }
+    const lo = Math.min(startIdx, endIdx);
+    const hi = Math.max(startIdx, endIdx);
+    return allSheets.slice(lo, hi + 1).map(s => s.name);
+}

package/dist/esm/modules/formula/compile/bound-ast.js

@@ -0,0 +1,80 @@
+/**
+ * Bound Expression AST — The output of the compilation (binding) phase.
+ *
+ * After parsing produces a raw AST, the binder resolves all static symbols:
+ * - Defined names → resolved cell/range references or formula expressions
+ * - Structured references → resolved cell/range references
+ * - Sheet names → validated against the snapshot
+ * - Function names → validated against the registry
+ *
+ * The result is a `BoundExpr` tree where every reference is resolved and
+ * every function call is validated. The runtime evaluator only executes
+ * `BoundExpr` nodes — it never needs to perform symbol resolution.
+ *
+ * ## Node Types (compile output)
+ *
+ * After binding, only these node types exist:
+ *
+ * - `BoundLiteral` — number, string, boolean, error, null (missing)
+ * - `BoundCellRef` — resolved cell reference (sheet + row + col)
+ * - `BoundAreaRef` — resolved rectangular range (sheet + bounds)
+ * - `BoundColRangeRef` — resolved whole-column range
+ * - `BoundRowRangeRef` — resolved whole-row range
+ * - `BoundRef3D` — resolved 3D reference (multiple sheets)
+ * - `BoundBinaryOp` — binary operation
+ * - `BoundUnaryOp` — unary operation (including @)
+ * - `BoundPercent` — postfix %
+ * - `BoundCall` — function call (eagerly evaluated args)
+ * - `BoundSpecialCall` — special form (IF, LET, LAMBDA, etc.) with lazy args
+ * - `BoundArray` — array constant {1,2;3,4}
+ * - `BoundNameExpr` — UNRESOLVED name (only for names that must be resolved at runtime,
+ *   e.g. formula-based defined names that produce lambdas, or truly unknown names)
+ * - `BoundLambda` — LAMBDA expression (params + body)
+ */
+// ============================================================================
+// Bound Expression Tag Enum
+// ============================================================================
+export var BoundExprKind;
+(function (BoundExprKind) {
+    BoundExprKind[BoundExprKind["Literal"] = 1] = "Literal";
+    BoundExprKind[BoundExprKind["CellRef"] = 2] = "CellRef";
+    BoundExprKind[BoundExprKind["AreaRef"] = 3] = "AreaRef";
+    BoundExprKind[BoundExprKind["ColRangeRef"] = 4] = "ColRangeRef";
+    BoundExprKind[BoundExprKind["RowRangeRef"] = 5] = "RowRangeRef";
+    BoundExprKind[BoundExprKind["Ref3D"] = 6] = "Ref3D";
+    BoundExprKind[BoundExprKind["BinaryOp"] = 7] = "BinaryOp";
+    BoundExprKind[BoundExprKind["UnaryOp"] = 8] = "UnaryOp";
+    BoundExprKind[BoundExprKind["Percent"] = 9] = "Percent";
+    BoundExprKind[BoundExprKind["Call"] = 10] = "Call";
+    BoundExprKind[BoundExprKind["SpecialCall"] = 11] = "SpecialCall";
+    BoundExprKind[BoundExprKind["Array"] = 12] = "Array";
+    BoundExprKind[BoundExprKind["NameExpr"] = 13] = "NameExpr";
+    BoundExprKind[BoundExprKind["Lambda"] = 14] = "Lambda";
+    BoundExprKind[BoundExprKind["StructuredRef"] = 15] = "StructuredRef";
+})(BoundExprKind || (BoundExprKind = {}));
+// ============================================================================
+// Constructor Helpers
+// ============================================================================
+export function boundLiteral(value, errorCode) {
+    return errorCode !== undefined
+        ? { kind: BoundExprKind.Literal, value, errorCode }
+        : { kind: BoundExprKind.Literal, value };
+}
+export function boundCellRef(sheet, row, col) {
+    return { kind: BoundExprKind.CellRef, sheet, row, col };
+}
+export function boundAreaRef(sheet, top, left, bottom, right) {
+    return { kind: BoundExprKind.AreaRef, sheet, top, left, bottom, right };
+}
+export function boundCall(name, args) {
+    return { kind: BoundExprKind.Call, name, args };
+}
+export function boundSpecialCall(name, args) {
+    return { kind: BoundExprKind.SpecialCall, name, args };
+}
+export function boundNameExpr(name) {
+    return { kind: BoundExprKind.NameExpr, name, upperName: name.toUpperCase() };
+}
+export function boundErrorLiteral(errorCode) {
+    return { kind: BoundExprKind.Literal, value: null, errorCode };
+}