@cj-tech-master/excelts 9.2.1 → 9.3.0

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

@@ -0,0 +1,385 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ERRORS = exports.BLANK = void 0;
+exports.rvNumber = rvNumber;
+exports.rvString = rvString;
+exports.rvBoolean = rvBoolean;
+exports.rvError = rvError;
+exports.rvArray = rvArray;
+exports.rvRef = rvRef;
+exports.rvCellRef = rvCellRef;
+exports.rvLambda = rvLambda;
+exports.isError = isError;
+exports.isArray = isArray;
+exports.isLambda = isLambda;
+exports.isScalar = isScalar;
+exports.toNumberRV = toNumberRV;
+exports.toStringRV = toStringRV;
+exports.toBooleanRV = toBooleanRV;
+exports.compareScalarsSameKind = compareScalarsSameKind;
+exports.scalarEquals = scalarEquals;
+exports.topLeft = topLeft;
+exports.fromSnapshotValue = fromSnapshotValue;
+// ============================================================================
+// Singleton Constants
+// ============================================================================
+/** The singleton blank value. */
+exports.BLANK = { kind: 0 /* RVKind.Blank */ };
+/** Common error values. */
+exports.ERRORS = {
+    VALUE: { kind: 4 /* RVKind.Error */, code: "#VALUE!" },
+    REF: { kind: 4 /* RVKind.Error */, code: "#REF!" },
+    NAME: { kind: 4 /* RVKind.Error */, code: "#NAME?" },
+    DIV0: { kind: 4 /* RVKind.Error */, code: "#DIV/0!" },
+    NA: { kind: 4 /* RVKind.Error */, code: "#N/A" },
+    NUM: { kind: 4 /* RVKind.Error */, code: "#NUM!" },
+    NULL: { kind: 4 /* RVKind.Error */, code: "#NULL!" },
+    SPILL: { kind: 4 /* RVKind.Error */, code: "#SPILL!" },
+    CALC: { kind: 4 /* RVKind.Error */, code: "#CALC!" }
+};
+// ============================================================================
+// Constructor Helpers
+// ============================================================================
+function rvNumber(value) {
+    return { kind: 1 /* RVKind.Number */, value };
+}
+function rvString(value) {
+    return { kind: 2 /* RVKind.String */, value };
+}
+function rvBoolean(value) {
+    return { kind: 3 /* RVKind.Boolean */, value };
+}
+function rvError(code) {
+    return { kind: 4 /* RVKind.Error */, code };
+}
+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] = exports.BLANK;
+                }
+                normalisedRows[r] = padded;
+            }
+        }
+    }
+    return originRow !== undefined
+        ? {
+            kind: 5 /* RVKind.Array */,
+            rows: normalisedRows,
+            height,
+            width,
+            originRow,
+            originCol,
+            ...(subtotalMask ? { subtotalMask } : {}),
+            ...(hiddenRowMask ? { hiddenRowMask } : {})
+        }
+        : {
+            kind: 5 /* RVKind.Array */,
+            rows: normalisedRows,
+            height,
+            width,
+            ...(subtotalMask ? { subtotalMask } : {}),
+            ...(hiddenRowMask ? { hiddenRowMask } : {})
+        };
+}
+function rvRef(sheet, top, left, bottom, right) {
+    return {
+        kind: 6 /* RVKind.Reference */,
+        areas: [{ sheet, top, left, bottom, right }]
+    };
+}
+function rvCellRef(sheet, row, col) {
+    return {
+        kind: 6 /* RVKind.Reference */,
+        areas: [{ sheet, top: row, left: col, bottom: row, right: col }],
+        singleCell: true
+    };
+}
+function rvLambda(params, body, closureBindings) {
+    return { kind: 7 /* RVKind.Lambda */, params, body, closureBindings };
+}
+// ============================================================================
+// Type Guards
+// ============================================================================
+function isError(v) {
+    return v.kind === 4 /* RVKind.Error */;
+}
+function isArray(v) {
+    return v.kind === 5 /* RVKind.Array */;
+}
+function isLambda(v) {
+    return v.kind === 7 /* RVKind.Lambda */;
+}
+function isScalar(v) {
+    return (v.kind === 0 /* RVKind.Blank */ ||
+        v.kind === 1 /* RVKind.Number */ ||
+        v.kind === 2 /* RVKind.String */ ||
+        v.kind === 3 /* RVKind.Boolean */ ||
+        v.kind === 4 /* 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 exports.ERRORS.VALUE;
+    }
+    let body = s;
+    let percentFactor = 1;
+    if (body.endsWith("%")) {
+        percentFactor = 0.01;
+        body = body.slice(0, -1).trim();
+        if (body === "") {
+            return exports.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 exports.ERRORS.VALUE;
+    }
+    const n = Number(body);
+    if (!Number.isFinite(n)) {
+        return exports.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
+ */
+function toNumberRV(v) {
+    switch (v.kind) {
+        case 1 /* RVKind.Number */:
+            return v;
+        case 0 /* RVKind.Blank */:
+            return rvNumber(0);
+        case 3 /* RVKind.Boolean */:
+            return rvNumber(v.value ? 1 : 0);
+        case 2 /* RVKind.String */: {
+            return parseNumericString(v.value);
+        }
+        case 4 /* RVKind.Error */:
+            return v;
+        default:
+            return exports.ERRORS.VALUE;
+    }
+}
+/**
+ * Coerce a runtime value to a string.
+ */
+function toStringRV(v) {
+    switch (v.kind) {
+        case 2 /* RVKind.String */:
+            return v.value;
+        case 1 /* RVKind.Number */:
+            return String(v.value);
+        case 3 /* RVKind.Boolean */:
+            return v.value ? "TRUE" : "FALSE";
+        case 0 /* RVKind.Blank */:
+            return "";
+        case 4 /* RVKind.Error */:
+            return v.code;
+        default:
+            return "";
+    }
+}
+/**
+ * Coerce a runtime value to a boolean.
+ */
+function toBooleanRV(v) {
+    switch (v.kind) {
+        case 3 /* RVKind.Boolean */:
+            return v;
+        case 1 /* RVKind.Number */:
+            return rvBoolean(v.value !== 0);
+        case 0 /* RVKind.Blank */:
+            return rvBoolean(false);
+        case 2 /* RVKind.String */: {
+            const u = v.value.toUpperCase();
+            if (u === "TRUE") {
+                return rvBoolean(true);
+            }
+            if (u === "FALSE") {
+                return rvBoolean(false);
+            }
+            return exports.ERRORS.VALUE;
+        }
+        case 4 /* RVKind.Error */:
+            return v;
+        default:
+            return exports.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.
+ */
+function compareScalarsSameKind(a, b) {
+    if (a.kind !== b.kind) {
+        return Number.NaN;
+    }
+    switch (a.kind) {
+        case 1 /* RVKind.Number */:
+            return a.value - b.value;
+        case 2 /* RVKind.String */: {
+            const al = a.value.toLowerCase();
+            const bl = b.value.toLowerCase();
+            return al < bl ? -1 : al > bl ? 1 : 0;
+        }
+        case 3 /* RVKind.Boolean */: {
+            const bv = b.value;
+            return a.value === bv ? 0 : a.value ? 1 : -1;
+        }
+        case 0 /* RVKind.Blank */:
+            return 0;
+        default:
+            return Number.NaN;
+    }
+}
+function scalarEquals(a, b) {
+    if (a.kind !== b.kind) {
+        return false;
+    }
+    switch (a.kind) {
+        case 1 /* RVKind.Number */:
+            return a.value === b.value;
+        case 2 /* RVKind.String */:
+            return a.value.toLowerCase() === b.value.toLowerCase();
+        case 3 /* RVKind.Boolean */:
+            return a.value === b.value;
+        case 0 /* RVKind.Blank */:
+            return true;
+        default:
+            return false;
+    }
+}
+/**
+ * Get the top-left scalar from any value (for implicit intersection fallback).
+ */
+function topLeft(v) {
+    if (isScalar(v)) {
+        return v;
+    }
+    if (v.kind === 5 /* RVKind.Array */) {
+        if (v.height === 0 || v.width === 0) {
+            return exports.BLANK;
+        }
+        return v.rows[0][0];
+    }
+    // Reference, Lambda → need context to resolve
+    return exports.ERRORS.VALUE;
+}
+// ============================================================================
+// Snapshot Value Conversion
+// ============================================================================
+/**
+ * Convert a SnapshotCellValue to a RuntimeValue.
+ */
+function fromSnapshotValue(v) {
+    if (v === null) {
+        return exports.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 exports.BLANK;
+}

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

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });