@cj-tech-master/excelts 9.2.1 → 9.3.0

package/dist/esm/modules/formula/runtime/values.js

@@ -0,0 +1,385 @@
+/**
+ * Runtime Value System — The engine's canonical value representation.
+ *
+ * Every value that flows through the formula evaluator is a `RuntimeValue`.
+ * This is a properly tagged discriminated union that all function
+ * implementations operate on directly — no adapter layer.
+ *
+ * ## Design Principles
+ *
+ * 1. **No Date objects** — dates are represented as their Excel serial
+ *    number (a plain `number`). Date formatting is an output concern.
+ * 2. **No monkey-patched arrays** — `ArrayValue` is a proper type with
+ *    explicit `height`, `width`, and optional origin metadata.
+ * 3. **Reference is a first-class value** — `ReferenceValue` can flow
+ *    through the evaluator and be passed to functions.
+ * 4. **Error codes are strict** — `ErrorValue` uses a typed code enum.
+ * 5. **Lambda is a value** — `LambdaValue` is part of the value union.
+ */
+// ============================================================================
+// Value Tag Enum
+// ============================================================================
+export var RVKind;
+(function (RVKind) {
+    /** Empty cell / blank. Numeric value 0, string value "". */
+    RVKind[RVKind["Blank"] = 0] = "Blank";
+    /** A number (includes dates as serial numbers). */
+    RVKind[RVKind["Number"] = 1] = "Number";
+    /** A string. */
+    RVKind[RVKind["String"] = 2] = "String";
+    /** A boolean (TRUE / FALSE). */
+    RVKind[RVKind["Boolean"] = 3] = "Boolean";
+    /** An error value (#N/A, #VALUE!, etc.). */
+    RVKind[RVKind["Error"] = 4] = "Error";
+    /** A 2D array of scalar values. */
+    RVKind[RVKind["Array"] = 5] = "Array";
+    /** A cell or area reference (lazy — not yet resolved to values). */
+    RVKind[RVKind["Reference"] = 6] = "Reference";
+    /** A lambda (closure). */
+    RVKind[RVKind["Lambda"] = 7] = "Lambda";
+})(RVKind || (RVKind = {}));
+// ============================================================================
+// Singleton Constants
+// ============================================================================
+/** The singleton blank value. */
+export const BLANK = { kind: RVKind.Blank };
+/** Common error values. */
+export const ERRORS = {
+    VALUE: { kind: RVKind.Error, code: "#VALUE!" },
+    REF: { kind: RVKind.Error, code: "#REF!" },
+    NAME: { kind: RVKind.Error, code: "#NAME?" },
+    DIV0: { kind: RVKind.Error, code: "#DIV/0!" },
+    NA: { kind: RVKind.Error, code: "#N/A" },
+    NUM: { kind: RVKind.Error, code: "#NUM!" },
+    NULL: { kind: RVKind.Error, code: "#NULL!" },
+    SPILL: { kind: RVKind.Error, code: "#SPILL!" },
+    CALC: { kind: RVKind.Error, code: "#CALC!" }
+};
+// ============================================================================
+// Constructor Helpers
+// ============================================================================
+export function rvNumber(value) {
+    return { kind: RVKind.Number, value };
+}
+export function rvString(value) {
+    return { kind: RVKind.String, value };
+}
+export function rvBoolean(value) {
+    return { kind: RVKind.Boolean, value };
+}
+export function rvError(code) {
+    return { kind: RVKind.Error, code };
+}
+export function rvArray(rows, originRow, originCol, subtotalMask, hiddenRowMask) {
+    const height = rows.length;
+    // Determine max width across all rows for rectangular normalisation.
+    let width = 0;
+    for (const row of rows) {
+        if (row.length > width) {
+            width = row.length;
+        }
+    }
+    // Pad short rows with BLANK so the resulting ArrayValue is rectangular.
+    // The old implementation did `row.push(BLANK)` directly — mutating the
+    // caller's arrays. Callers that shared row references across multiple
+    // `rvArray` calls could observe surprise modifications; we now copy any
+    // row that needs padding and leave the caller's arrays untouched.
+    let normalisedRows = rows;
+    if (height > 0 && width > 0) {
+        let anyNeedPadding = false;
+        for (const row of rows) {
+            if (row.length < width) {
+                anyNeedPadding = true;
+                break;
+            }
+        }
+        if (anyNeedPadding) {
+            normalisedRows = new Array(height);
+            for (let r = 0; r < height; r++) {
+                const row = rows[r];
+                if (row.length === width) {
+                    normalisedRows[r] = row;
+                    continue;
+                }
+                const padded = new Array(width);
+                for (let c = 0; c < row.length; c++) {
+                    padded[c] = row[c];
+                }
+                for (let c = row.length; c < width; c++) {
+                    padded[c] = BLANK;
+                }
+                normalisedRows[r] = padded;
+            }
+        }
+    }
+    return originRow !== undefined
+        ? {
+            kind: RVKind.Array,
+            rows: normalisedRows,
+            height,
+            width,
+            originRow,
+            originCol,
+            ...(subtotalMask ? { subtotalMask } : {}),
+            ...(hiddenRowMask ? { hiddenRowMask } : {})
+        }
+        : {
+            kind: RVKind.Array,
+            rows: normalisedRows,
+            height,
+            width,
+            ...(subtotalMask ? { subtotalMask } : {}),
+            ...(hiddenRowMask ? { hiddenRowMask } : {})
+        };
+}
+export function rvRef(sheet, top, left, bottom, right) {
+    return {
+        kind: RVKind.Reference,
+        areas: [{ sheet, top, left, bottom, right }]
+    };
+}
+export function rvCellRef(sheet, row, col) {
+    return {
+        kind: RVKind.Reference,
+        areas: [{ sheet, top: row, left: col, bottom: row, right: col }],
+        singleCell: true
+    };
+}
+export function rvLambda(params, body, closureBindings) {
+    return { kind: RVKind.Lambda, params, body, closureBindings };
+}
+// ============================================================================
+// Type Guards
+// ============================================================================
+export function isError(v) {
+    return v.kind === RVKind.Error;
+}
+export function isArray(v) {
+    return v.kind === RVKind.Array;
+}
+export function isLambda(v) {
+    return v.kind === RVKind.Lambda;
+}
+export function isScalar(v) {
+    return (v.kind === RVKind.Blank ||
+        v.kind === RVKind.Number ||
+        v.kind === RVKind.String ||
+        v.kind === RVKind.Boolean ||
+        v.kind === RVKind.Error);
+}
+// ============================================================================
+// Coercion Helpers
+// ============================================================================
+/**
+ * Parse a user-facing numeric string the way Excel does.
+ *
+ * Accepts:
+ *   - plain decimals: `"1"`, `"-1.5"`, `"+.25"`
+ *   - scientific notation: `"1.2e3"`, `"2E-4"`
+ *   - percentage suffix: `"50%"` → 0.5
+ *   - leading/trailing whitespace around the above
+ *
+ * Rejects (unlike JavaScript's `Number()`):
+ *   - empty strings and whitespace-only (`" "` would become 0)
+ *   - `"Infinity"`, `"-Infinity"`, `"NaN"` (Excel treats as text)
+ *   - hexadecimal (`"0x10"`), octal, binary literals
+ *   - currency symbols, thousands separators, locale-specific formats
+ *     (these are out of scope for the engine; callers should strip before
+ *     calling)
+ *
+ * Returns `#VALUE!` on any rejection so the error bubbles naturally
+ * through formula evaluation.
+ */
+function parseNumericString(raw) {
+    const s = raw.trim();
+    if (s === "") {
+        return ERRORS.VALUE;
+    }
+    let body = s;
+    let percentFactor = 1;
+    if (body.endsWith("%")) {
+        percentFactor = 0.01;
+        body = body.slice(0, -1).trim();
+        if (body === "") {
+            return ERRORS.VALUE;
+        }
+    }
+    // Require at least one digit somewhere; this shuts the door on
+    // "Infinity", "NaN", "0x10", "1e" (Excel's own lexer refuses these).
+    // The strict decimal grammar below also rejects "1_000" etc.
+    if (!/^[+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?$/.test(body)) {
+        return ERRORS.VALUE;
+    }
+    const n = Number(body);
+    if (!Number.isFinite(n)) {
+        return ERRORS.VALUE;
+    }
+    return rvNumber(n * percentFactor);
+}
+/**
+ * Coerce a runtime value to a number.
+ * - Blank → 0
+ * - Number → itself
+ * - Boolean → 1 / 0
+ * - String → parse or #VALUE!
+ * - Error → propagate
+ */
+export function toNumberRV(v) {
+    switch (v.kind) {
+        case RVKind.Number:
+            return v;
+        case RVKind.Blank:
+            return rvNumber(0);
+        case RVKind.Boolean:
+            return rvNumber(v.value ? 1 : 0);
+        case RVKind.String: {
+            return parseNumericString(v.value);
+        }
+        case RVKind.Error:
+            return v;
+        default:
+            return ERRORS.VALUE;
+    }
+}
+/**
+ * Coerce a runtime value to a string.
+ */
+export function toStringRV(v) {
+    switch (v.kind) {
+        case RVKind.String:
+            return v.value;
+        case RVKind.Number:
+            return String(v.value);
+        case RVKind.Boolean:
+            return v.value ? "TRUE" : "FALSE";
+        case RVKind.Blank:
+            return "";
+        case RVKind.Error:
+            return v.code;
+        default:
+            return "";
+    }
+}
+/**
+ * Coerce a runtime value to a boolean.
+ */
+export function toBooleanRV(v) {
+    switch (v.kind) {
+        case RVKind.Boolean:
+            return v;
+        case RVKind.Number:
+            return rvBoolean(v.value !== 0);
+        case RVKind.Blank:
+            return rvBoolean(false);
+        case RVKind.String: {
+            const u = v.value.toUpperCase();
+            if (u === "TRUE") {
+                return rvBoolean(true);
+            }
+            if (u === "FALSE") {
+                return rvBoolean(false);
+            }
+            return ERRORS.VALUE;
+        }
+        case RVKind.Error:
+            return v;
+        default:
+            return ERRORS.VALUE;
+    }
+}
+/**
+ * Structural equality of scalar values.
+ *
+ * - Different kinds → false
+ * - Number / Boolean / Blank → strict value equality (Blank always equal)
+ * - String → case-insensitive comparison (Excel semantics)
+ * - Error → not equal (errors do not compare equal to each other)
+ */
+/**
+ * Three-way compare two scalars that share a kind.
+ *
+ * Returns a negative number if `a < b`, zero if equal, positive if `a > b`.
+ * Returns `NaN` when the kinds differ or cannot be ordered (e.g. errors);
+ * callers decide how to surface the incomparability — sort helpers usually
+ * skip NaN pairs, while comparison operators route to a kind-priority
+ * tiebreak. Strings are compared case-insensitively to match Excel.
+ */
+export function compareScalarsSameKind(a, b) {
+    if (a.kind !== b.kind) {
+        return Number.NaN;
+    }
+    switch (a.kind) {
+        case RVKind.Number:
+            return a.value - b.value;
+        case RVKind.String: {
+            const al = a.value.toLowerCase();
+            const bl = b.value.toLowerCase();
+            return al < bl ? -1 : al > bl ? 1 : 0;
+        }
+        case RVKind.Boolean: {
+            const bv = b.value;
+            return a.value === bv ? 0 : a.value ? 1 : -1;
+        }
+        case RVKind.Blank:
+            return 0;
+        default:
+            return Number.NaN;
+    }
+}
+export function scalarEquals(a, b) {
+    if (a.kind !== b.kind) {
+        return false;
+    }
+    switch (a.kind) {
+        case RVKind.Number:
+            return a.value === b.value;
+        case RVKind.String:
+            return a.value.toLowerCase() === b.value.toLowerCase();
+        case RVKind.Boolean:
+            return a.value === b.value;
+        case RVKind.Blank:
+            return true;
+        default:
+            return false;
+    }
+}
+/**
+ * Get the top-left scalar from any value (for implicit intersection fallback).
+ */
+export function topLeft(v) {
+    if (isScalar(v)) {
+        return v;
+    }
+    if (v.kind === RVKind.Array) {
+        if (v.height === 0 || v.width === 0) {
+            return BLANK;
+        }
+        return v.rows[0][0];
+    }
+    // Reference, Lambda → need context to resolve
+    return ERRORS.VALUE;
+}
+// ============================================================================
+// Snapshot Value Conversion
+// ============================================================================
+/**
+ * Convert a SnapshotCellValue to a RuntimeValue.
+ */
+export function fromSnapshotValue(v) {
+    if (v === null) {
+        return BLANK;
+    }
+    if (typeof v === "number") {
+        return rvNumber(v);
+    }
+    if (typeof v === "string") {
+        return rvString(v);
+    }
+    if (typeof v === "boolean") {
+        return rvBoolean(v);
+    }
+    if (typeof v === "object" && "error" in v) {
+        return rvError(v.error);
+    }
+    return BLANK;
+}

package/dist/esm/modules/formula/syntax/ast.js

@@ -0,0 +1,28 @@
+/**
+ * AST Node Types for Formula Parser
+ *
+ * Defines the Abstract Syntax Tree node types as a proper discriminated union.
+ * Each node variant carries only the data relevant to its type.
+ */
+// ============================================================================
+// Node Type Enum
+// ============================================================================
+export var NodeType;
+(function (NodeType) {
+    NodeType[NodeType["Number"] = 1] = "Number";
+    NodeType[NodeType["String"] = 2] = "String";
+    NodeType[NodeType["Boolean"] = 3] = "Boolean";
+    NodeType[NodeType["Error"] = 4] = "Error";
+    NodeType[NodeType["CellRef"] = 5] = "CellRef";
+    NodeType[NodeType["RangeRef"] = 6] = "RangeRef";
+    NodeType[NodeType["BinaryOp"] = 7] = "BinaryOp";
+    NodeType[NodeType["UnaryOp"] = 8] = "UnaryOp";
+    NodeType[NodeType["FunctionCall"] = 9] = "FunctionCall";
+    NodeType[NodeType["Array"] = 10] = "Array";
+    NodeType[NodeType["Percent"] = 11] = "Percent";
+    NodeType[NodeType["Name"] = 12] = "Name";
+    NodeType[NodeType["ColRangeRef"] = 13] = "ColRangeRef";
+    NodeType[NodeType["RowRangeRef"] = 14] = "RowRangeRef";
+    NodeType[NodeType["StructuredRef"] = 15] = "StructuredRef";
+    NodeType[NodeType["Missing"] = 16] = "Missing";
+})(NodeType || (NodeType = {}));