@cj-tech-master/excelts 9.2.1 → 9.3.0

package/dist/browser/modules/formula/materialize/types.js

@@ -0,0 +1,29 @@
+/**
+ * Structural interfaces the formula engine consumes.
+ *
+ * The engine talks to these interfaces only — never to the concrete
+ * `Workbook` / `Worksheet` / `Cell` classes from the `excel` module. Any
+ * host that wants to drive the engine (including the Node/browser
+ * Workbook in `@excel/*`) must implement these shapes.
+ *
+ * This is what keeps the Layer 3 ↔ Layer 4 dependency one-way: the
+ * `excel` module imports from `formula`, never the reverse.
+ */
+// ============================================================================
+// ValueType — numeric mirror of `@excel/enums` ValueType
+// ============================================================================
+/**
+ * Numeric cell-type tag exposed by host cells. The engine only compares
+ * against `Null` and `Formula`; any other value is treated as a scalar
+ * literal.
+ *
+ * Kept as inline numeric literals (not an enum) so this file stays free
+ * of runtime dependencies. The `const` object and `type` alias share a
+ * name via TypeScript's declaration merging — the value form
+ * (`CellValueTypeLike.Null`, `CellValueTypeLike.Formula`) is used at
+ * comparison sites, the type form annotates `CellLike.type`.
+ */
+export const CellValueTypeLike = {
+    Null: 0,
+    Formula: 6
+};

package/dist/browser/modules/formula/materialize/writeback-plan.d.ts

@@ -0,0 +1,167 @@
+/**
+ * Writeback Plan — Declarative description of formula calculation results.
+ *
+ * The engine never directly mutates workbook cells. Instead, it produces a
+ * `WritebackPlan` — a list of write operations that describe what values
+ * should be written where. A thin adapter layer then applies the plan to
+ * the live workbook.
+ *
+ * ## Design Principles
+ *
+ * 1. **Declarative** — the plan describes *what* to write, not *how*.
+ * 2. **Deterministic** — #SPILL! conflicts are detected during plan
+ *    construction, not during application.
+ * 3. **Ordered** — operations are applied in the order they appear.
+ * 4. **Independent** — each operation stands alone; the adapter does not
+ *    need engine internals to apply the plan.
+ *
+ * ## Operation Types
+ *
+ * - `ScalarWrite` — write a single value to a formula cell's result.
+ * - `CSEWrite` — distribute an array across a CSE formula's target range.
+ * - `SpillWrite` — write a dynamic array result to adjacent cells (spill).
+ * - `SpillErrorWrite` — write #SPILL! to the source cell (conflict detected).
+ * - `CleanupWrite` — clear stale ghost cells from a previous spill.
+ * - `PreserveWrite` — keep the cell's existing cached result (unsupported fn).
+ */
+import type { SnapshotCellValue } from "../integration/workbook-snapshot.js";
+import type { SpillRegion } from "./types.js";
+/**
+ * Write a scalar value to a formula cell's result.
+ */
+export interface ScalarWrite {
+    readonly type: "scalar";
+    readonly sheetName: string;
+    readonly row: number;
+    readonly col: number;
+    /** The computed result value. */
+    readonly value: SnapshotCellValue;
+}
+/**
+ * Distribute an array result across a CSE (Ctrl+Shift+Enter) formula's
+ * target range. Each cell in the range gets the corresponding element.
+ * If the result is smaller than the target range, excess cells receive
+ * the scalar value (or `null` for missing elements).
+ */
+export interface CSEWrite {
+    readonly type: "cse";
+    readonly sheetName: string;
+    /** Top-left corner of the target range. */
+    readonly top: number;
+    readonly left: number;
+    /** Bottom-right corner of the target range. */
+    readonly bottom: number;
+    readonly right: number;
+    /**
+     * The result array. `results[r][c]` is the value for row `top + r`,
+     * col `left + c`. May be smaller than the target range.
+     */
+    readonly results: readonly (readonly SnapshotCellValue[])[];
+    /**
+     * For scalar CSE results: the single value to fill the entire range.
+     * When set, `results` is ignored.
+     */
+    readonly scalarFill?: SnapshotCellValue;
+}
+/**
+ * Write a dynamic array result to the source cell and adjacent ghost cells.
+ * The spill region starts at (row, col) and extends downward/rightward.
+ */
+export interface SpillWrite {
+    readonly type: "spill";
+    readonly sheetName: string;
+    readonly sheetId: number;
+    /** Source formula cell position. */
+    readonly row: number;
+    readonly col: number;
+    /**
+     * The result array. `results[r][c]` is the value for row `row + r`,
+     * col `col + c`. The source cell gets `results[0][0]`.
+     */
+    readonly results: readonly (readonly SnapshotCellValue[])[];
+}
+/**
+ * Write #SPILL! to the source cell because the target range is occupied.
+ */
+export interface SpillErrorWrite {
+    readonly type: "spill-error";
+    readonly sheetName: string;
+    readonly sheetId: number;
+    readonly row: number;
+    readonly col: number;
+}
+/**
+ * Clear ghost cells from a previous spill that is no longer valid.
+ * Each entry in `cells` is a (row, col) pair to clear.
+ */
+export interface CleanupWrite {
+    readonly type: "cleanup";
+    readonly sheetName: string;
+    readonly sheetId: number;
+    /**
+     * Cells to clear. Each is `{ row, col }`.
+     * Only cells that haven't been modified by the user should be cleared —
+     * the plan builder checks this against the snapshot.
+     */
+    readonly cells: readonly {
+        readonly row: number;
+        readonly col: number;
+    }[];
+}
+/**
+ * Keep the cell's existing cached result.
+ * Used when the engine returns #NAME? (unsupported function) but the cell
+ * has a usable cached result from the XLSX file.
+ */
+export interface PreserveWrite {
+    readonly type: "preserve";
+    readonly sheetName: string;
+    readonly row: number;
+    readonly col: number;
+}
+/**
+ * A single write operation in the plan.
+ */
+export type WriteOperation = ScalarWrite | CSEWrite | SpillWrite | SpillErrorWrite | CleanupWrite | PreserveWrite;
+/**
+ * The complete writeback plan produced by the engine.
+ *
+ * Operations are ordered: cleanups first, then writes, to ensure stale
+ * data is removed before new data is written.
+ */
+export interface WritebackPlan {
+    /**
+     * All write operations in application order.
+     * The adapter should apply them sequentially.
+     */
+    readonly operations: readonly WriteOperation[];
+    /**
+     * Spill persistent state changes — spill regions and ghost cell snapshots
+     * that the adapter must update in the persistent tracking maps.
+     */
+    readonly spillState: SpillStateDelta;
+}
+/**
+ * Describes changes to the persistent spill tracking state.
+ * The adapter updates the persistent maps accordingly.
+ */
+export interface SpillStateDelta {
+    /**
+     * New or updated spill region metadata.
+     * Key: `"ws:<id>!row:col"` of the source formula cell.
+     * Value: the spill region dimensions.
+     */
+    readonly spillRegions: ReadonlyMap<string, SpillRegion>;
+    /**
+     * Ghost cell value snapshots for modification detection.
+     * Key: ghost cell key `"ws:<id>!row:col"`.
+     * Value: the raw value written to that ghost cell.
+     */
+    readonly ghostSnapshots: ReadonlyMap<string, SnapshotCellValue>;
+    /**
+     * Spill region entries to remove from the persistent map.
+     * These are source cell keys whose formulas no longer exist or whose
+     * spill was replaced.
+     */
+    readonly removedSpillKeys: readonly string[];
+}

package/dist/browser/modules/formula/materialize/writeback-plan.js

@@ -0,0 +1,27 @@
+/**
+ * Writeback Plan — Declarative description of formula calculation results.
+ *
+ * The engine never directly mutates workbook cells. Instead, it produces a
+ * `WritebackPlan` — a list of write operations that describe what values
+ * should be written where. A thin adapter layer then applies the plan to
+ * the live workbook.
+ *
+ * ## Design Principles
+ *
+ * 1. **Declarative** — the plan describes *what* to write, not *how*.
+ * 2. **Deterministic** — #SPILL! conflicts are detected during plan
+ *    construction, not during application.
+ * 3. **Ordered** — operations are applied in the order they appear.
+ * 4. **Independent** — each operation stands alone; the adapter does not
+ *    need engine internals to apply the plan.
+ *
+ * ## Operation Types
+ *
+ * - `ScalarWrite` — write a single value to a formula cell's result.
+ * - `CSEWrite` — distribute an array across a CSE formula's target range.
+ * - `SpillWrite` — write a dynamic array result to adjacent cells (spill).
+ * - `SpillErrorWrite` — write #SPILL! to the source cell (conflict detected).
+ * - `CleanupWrite` — clear stale ghost cells from a previous spill.
+ * - `PreserveWrite` — keep the cell's existing cached result (unsupported fn).
+ */
+export {};

package/dist/browser/modules/formula/runtime/evaluator.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Evaluator — Execute BoundExpr using the RuntimeValue system.
+ *
+ * The evaluator operates on BoundExpr (from the compile phase),
+ * WorkbookSnapshot (from the snapshot phase), and RuntimeValue
+ * (the value system).
+ */
+import type { BoundExpr } from "../compile/bound-ast.js";
+import type { CompiledFormula } from "../compile/compiled-formula.js";
+import type { WorkbookSnapshot } from "../integration/workbook-snapshot.js";
+import type { RuntimeValue } from "./values.js";
+/**
+ * Cached formula evaluation result with both scalar and raw forms.
+ * The scalar form is used by dependent formulas (implicit intersection applied).
+ * The raw form preserves the full array for dynamic array / CSE materialization.
+ */
+interface CachedResult {
+    /** Scalar (implicit-intersected, dereferenced) result. */
+    readonly scalar: RuntimeValue;
+    /** Raw (full array) result. Only differs from scalar for array formulas. */
+    readonly raw: RuntimeValue;
+}
+/**
+ * Per-calculation mutable state.
+ */
+export declare class EvalSession {
+    /** Cells currently on the evaluation call stack (circular-ref detection). */
+    readonly evaluating: Set<string>;
+    /**
+     * Unified formula result cache.
+     * Each entry holds both the scalar form (for dependents) and the raw form
+     * (for materialize). This replaces the previous separate cache/rawCache
+     * pattern with a single, self-documenting structure.
+     */
+    readonly resultCache: Map<string, CachedResult>;
+    /** Cache for runtime name resolution (defined names that need parsing). */
+    readonly nameCache: Map<string, RuntimeValue>;
+    /** Fallback values for circular references during iterative calculation. */
+    readonly circularFallback: Map<string, RuntimeValue>;
+    /**
+     * Live spill map: cell key → (masterKey, row-offset, col-offset).
+     *
+     * Populated as soon as a dynamic-array formula is evaluated and yields
+     * an array result. Downstream formulas that read a cell inside the
+     * spill region look the master's cached array up via this map and
+     * return the correct element — even before materialize has written
+     * the ghost cells to the snapshot.
+     *
+     * This is the fix for "first-pass `=SUM(A1:A5)` over a `=SEQUENCE(5)`
+     * spill" — without the live map, `getCellValue("S", 2, 1)` returned
+     * BLANK and SUM only counted the master cell.
+     */
+    readonly liveSpills: Map<string, {
+        masterKey: string;
+        rowOffset: number;
+        colOffset: number;
+    }>;
+    /**
+     * Runtime dependency recorder — tracks cell accesses made during evaluation.
+     *
+     * When a formula with `hasDynamicRefs` (INDIRECT/OFFSET) is being evaluated,
+     * every `getCellValue` / `buildRangeArray` call records the accessed cell/range
+     * key here. After evaluation, these dynamic edges can be merged with the
+     * compiled static dependency set to produce a complete dependency graph.
+     *
+     * Key: formula cell key being evaluated → Set of accessed cell keys.
+     * Only populated for formulas that have `hasDynamicRefs === true`.
+     */
+    readonly dynamicDeps: Map<string, Set<string>>;
+    /**
+     * The formula cell key currently being recorded (null if recording is off).
+     * Set before evaluating a formula with dynamic refs, cleared after.
+     */
+    recordingKey: string | null;
+    /**
+     * Current LAMBDA invocation depth. Guards against unbounded recursion
+     * (e.g. `LAMBDA(x, x(x))(LAMBDA(x, x(x)))`) that would otherwise overflow
+     * the JS call stack. Excel documents a recursion limit of ~256.
+     */
+    lambdaDepth: number;
+    /**
+     * AST cache for INDIRECT re-parsing. INDIRECT receives a runtime string
+     * describing a reference; re-parsing it per invocation would be wasted
+     * work, so we memoise the `bound` expression keyed on the reference
+     * text. This belongs to the session (per-calculation lifetime) rather
+     * than the snapshot because the bindings depend on the evaluation
+     * context.
+     */
+    readonly indirectAstCache: Map<string, BoundExpr>;
+    makeKey(sheet: string, row: number, col: number): string;
+    /**
+     * Record a cell access for the currently-recording formula.
+     */
+    recordAccess(sheet: string, row: number, col: number): void;
+}
+/**
+ * The evaluation context. Carries the snapshot and compiled formula map
+ * for the evaluator to access cell values and resolve names at runtime.
+ * Short-lived per-calculation state (caches, iteration flags, etc.) lives
+ * on `EvalSession` instead.
+ */
+export interface EvalContext {
+    /** The workbook snapshot. */
+    readonly snapshot: WorkbookSnapshot;
+    /** Map from formula cell key to CompiledFormula. */
+    readonly compiledFormulas: ReadonlyMap<string, CompiledFormula>;
+    /** The current sheet name (for relative references). */
+    currentSheet: string;
+    /** Current cell address being evaluated. */
+    currentAddress?: {
+        sheet: string;
+        row: number;
+        col: number;
+    };
+    /** Local variable bindings from LET expressions. */
+    localBindings?: Map<string, RuntimeValue>;
+}
+/**
+ * Evaluate a BoundExpr to produce a RuntimeValue.
+ */
+export declare function evaluate(expr: BoundExpr, ctx: EvalContext, session: EvalSession): RuntimeValue;
+/**
+ * Evaluate a compiled formula and return its **scalar** result.
+ *
+ * This is the standard evaluation path for regular (non-array) formulas.
+ * The result is:
+ * 1. Evaluated from the bound expression tree
+ * 2. Implicit-intersected to a single value/reference
+ * 3. Dereferenced if it's a reference
+ * 4. Cached for subsequent lookups by dependent formulas
+ *
+ * Use `evaluateFormulaRaw` instead when the full array result is needed
+ * (dynamic array formulas, CSE formulas).
+ */
+export declare function evaluateFormula(compiled: CompiledFormula, ctx: EvalContext, session: EvalSession): RuntimeValue;
+/**
+ * Evaluate a compiled formula and return the **raw** (possibly array) result.
+ *
+ * This is the evaluation path for dynamic array and CSE formulas where
+ * the full array shape must be preserved for spill/distribution.
+ *
+ * Semantics:
+ * - Both scalar and raw forms are stored in `session.resultCache` as a
+ *   `CachedResult{scalar, raw}`. Dependent scalar formulas see the scalar
+ *   form; the materialize layer retrieves the raw form.
+ * - The return value is the full dereferenced result — may be an ArrayValue
+ *   with height > 1 or width > 1.
+ */
+export declare function evaluateFormulaRaw(compiled: CompiledFormula, ctx: EvalContext, session: EvalSession): RuntimeValue;
+export declare function implicitIntersect(val: RuntimeValue, ctx: EvalContext): RuntimeValue;
+export {};