@cj-tech-master/excelts 9.2.1 → 9.3.0

package/dist/browser/modules/formula/integration/workbook-snapshot.d.ts

@@ -0,0 +1,267 @@
+/**
+ * Workbook Snapshot — Immutable data layer for the formula engine.
+ *
+ * The snapshot captures all workbook state needed for formula compilation
+ * and evaluation as plain, read-only data structures. Runtime/compile code
+ * must depend only on these types — never on live Workbook/Worksheet/Cell
+ * objects.
+ *
+ * ## Design Principles
+ *
+ * 1. **Immutable** — all interfaces use `readonly` modifiers. The engine
+ *    must never mutate snapshot data.
+ * 2. **Self-contained** — every piece of information the engine needs
+ *    (cell values, formula text, table metadata, defined names, calc
+ *    properties) is captured up front.
+ * 3. **No @excel/ imports** — this file defines pure data types. The
+ *    concrete builder that populates these structures lives in
+ *    `workbook-adapter.ts` and is the only file that touches live objects.
+ */
+/**
+ * Error codes recognized by the formula engine.
+ * This is an engine-internal type that avoids importing from `@excel/types`.
+ */
+export type ErrorCode = "#N/A" | "#REF!" | "#NAME?" | "#DIV/0!" | "#NULL!" | "#VALUE!" | "#NUM!" | "#SPILL!" | "#CALC!";
+export interface SnapshotErrorValue {
+    readonly error: ErrorCode;
+}
+/**
+ * A cell's raw value as captured in the snapshot.
+ *
+ * - `Date` is NOT included — dates are stored as their Excel serial number.
+ *   The snapshot builder converts Date objects to serial numbers at capture
+ *   time so the engine never needs to reason about Date objects.
+ * - Rich text is flattened to a plain string.
+ */
+export type SnapshotCellValue = number | string | boolean | SnapshotErrorValue | null;
+/**
+ * The kind of formula a cell contains.
+ *
+ * - `"none"` — not a formula cell (literal value)
+ * - `"normal"` — ordinary formula
+ * - `"shared-master"` — master cell of a shared formula group
+ * - `"shared-slave"` — slave cell that inherits from a shared master
+ * - `"cse"` — legacy CSE (Ctrl+Shift+Enter) array formula
+ * - `"dynamic-array"` — Excel 365 dynamic array formula
+ */
+export type FormulaCellKind = "none" | "normal" | "shared-master" | "shared-slave" | "cse" | "dynamic-array";
+/**
+ * Snapshot of a single cell.
+ *
+ * Only cells that contain data or formulas are captured — truly empty
+ * positions are represented by the absence of a CellSnapshot in the
+ * worksheet's cell map.
+ */
+export interface CellSnapshot {
+    /** 1-based row number. */
+    readonly row: number;
+    /** 1-based column number. */
+    readonly col: number;
+    /** The cell's raw value (for non-formula cells) or cached result (for formula cells). */
+    readonly value: SnapshotCellValue;
+    /** The formula classification. */
+    readonly formulaKind: FormulaCellKind;
+    /**
+     * The formula source text.
+     * - For normal / shared-master / CSE / dynamic-array: the actual formula.
+     * - For shared-slave: the *translated* formula (already offset from master).
+     * - For non-formula cells: `undefined`.
+     */
+    readonly formula?: string;
+    /**
+     * For CSE and shared-master formulas: the target range in "A1:B2" format.
+     * Used by the materialize layer to determine where results are written.
+     */
+    readonly ref?: string;
+    /**
+     * Whether this is a dynamic array formula (explicit `isDynamicArray` flag
+     * from the XLSX model, or inferred from the top-level function name).
+     */
+    readonly isDynamicArray?: boolean;
+    /**
+     * The cached result from the XLSX file (before engine evaluation).
+     * Used by `shouldPreserveCachedResult` to avoid overwriting usable data
+     * when the engine returns #NAME? for an unsupported function.
+     */
+    readonly cachedResult?: SnapshotCellValue;
+}
+/**
+ * Snapshot of a single worksheet.
+ */
+export interface WorksheetSnapshot {
+    /** Stable worksheet identifier (survives renames). */
+    readonly id: number;
+    /** Worksheet name (used as the key for cross-sheet references). */
+    readonly name: string;
+    /**
+     * The used range of the worksheet. `null` if the sheet has no data.
+     * All values are 1-based.
+     */
+    readonly dimensions: {
+        readonly top: number;
+        readonly left: number;
+        readonly bottom: number;
+        readonly right: number;
+    } | null;
+    /**
+     * All cells with data, keyed by `"row:col"` (e.g. `"1:1"` for A1).
+     * Only non-empty cells are present.
+     */
+    readonly cells: ReadonlyMap<string, CellSnapshot>;
+    /**
+     * Rows that are hidden. Used by SUBTOTAL's 1xx-variant codes
+     * (101-111) and AGGREGATE option 5/7 to skip hidden rows during
+     * aggregation. Excel distinguishes filter-hidden vs manually hidden,
+     * but our worksheet model carries a single `row.hidden` boolean for
+     * either case — SUBTOTAL 1xx/AGGREGATE treat them identically anyway,
+     * and SUBTOTAL 9 (plain) always skips filter-hidden rows (not
+     * distinguishable here, so we conservatively treat them as visible).
+     * 1-based row numbers.
+     */
+    readonly hiddenRows: ReadonlySet<number>;
+    /** Tables defined in this worksheet. */
+    readonly tables: readonly TableSnapshot[];
+}
+/**
+ * Column definition within a table.
+ */
+export interface TableColumnSnapshot {
+    readonly name: string;
+}
+/**
+ * Snapshot of a table (ListObject) within a worksheet.
+ */
+export interface TableSnapshot {
+    /** The table name (used in structured references). */
+    readonly name: string;
+    /** Column definitions — order matches physical column order. */
+    readonly columns: readonly TableColumnSnapshot[];
+    /** Top-left corner of the table (1-based). */
+    readonly topLeft: {
+        readonly row: number;
+        readonly col: number;
+    };
+    /** Number of data rows (excludes header and totals). */
+    readonly dataRowCount: number;
+    /** Whether the table has a header row (default true). */
+    readonly hasHeaderRow: boolean;
+    /** Whether the table has a totals row. */
+    readonly hasTotalsRow: boolean;
+}
+/**
+ * A single defined name in the workbook.
+ *
+ * Defined names can reference:
+ * - A cell or range: `"Sheet1!$A$1:$B$2"`
+ * - A formula expression: `"LAMBDA(x,y,x+y)"`
+ * - Multiple areas (currently unsupported by the engine)
+ */
+export interface DefinedNameSnapshot {
+    /** The defined name (case-insensitive). */
+    readonly name: string;
+    /**
+     * The range strings associated with this name.
+     * Usually a single entry. Multi-area names (length > 1) are not supported
+     * by the engine and will produce #VALUE!.
+     */
+    readonly ranges: readonly string[];
+    /**
+     * The scope of this defined name.
+     * - `undefined` or empty string means workbook-scoped (global).
+     * - A sheet name means this name is local to that worksheet.
+     *
+     * Excel allows the same name to exist both as a workbook-scoped name
+     * and as a sheet-scoped name on specific worksheets. When a formula on
+     * Sheet1 references the name "Total", the engine first looks for a
+     * sheet-scoped name on Sheet1, then falls back to the workbook-scoped name.
+     */
+    readonly scope?: string;
+}
+/**
+ * Calculation settings from the workbook.
+ */
+export interface CalcPropertiesSnapshot {
+    /** Whether to perform a full calculation on load. */
+    readonly fullCalcOnLoad?: boolean;
+    /** Whether iterative calculation is enabled (for circular references). */
+    readonly iterate?: boolean;
+    /** Maximum number of iterations (default 100). */
+    readonly iterateCount?: number;
+    /** Maximum change threshold for convergence (default 0.001). */
+    readonly iterateDelta?: number;
+}
+/**
+ * Global workbook properties relevant to the formula engine.
+ */
+export interface WorkbookPropertiesSnapshot {
+    /** Whether the workbook uses the 1904 date system. */
+    readonly date1904?: boolean;
+}
+/**
+ * A table resolved with its containing worksheet name.
+ * Used by the `tablesByName` index for O(1) table lookup.
+ */
+export interface ResolvedTable {
+    readonly table: TableSnapshot;
+    readonly sheetName: string;
+}
+/**
+ * Complete, immutable snapshot of all workbook state needed by the formula
+ * engine. This is the sole input to the compile → evaluate → materialize
+ * pipeline.
+ */
+export interface WorkbookSnapshot {
+    /** All worksheets in workbook order. */
+    readonly worksheets: readonly WorksheetSnapshot[];
+    /** Quick lookup: worksheet name (lowercase) → WorksheetSnapshot. */
+    readonly worksheetsByName: ReadonlyMap<string, WorksheetSnapshot>;
+    /** Quick lookup: worksheet id → WorksheetSnapshot. */
+    readonly worksheetsById: ReadonlyMap<number, WorksheetSnapshot>;
+    /** All defined names in the workbook. Keyed by uppercase name for global
+     *  names, or `"SHEETNAME\0NAME"` for sheet-scoped names. Use the
+     *  `resolveDefinedNameKey()` helper to find the correct entry. */
+    readonly definedNames: ReadonlyMap<string, DefinedNameSnapshot>;
+    /**
+     * Quick lookup: table name (lowercase) → table + sheet info.
+     * Built at snapshot creation time to avoid O(sheets × tables) scans
+     * in the binder and evaluator.
+     */
+    readonly tablesByName: ReadonlyMap<string, ResolvedTable>;
+    /** Calculation properties (iterative calc settings, etc.). */
+    readonly calcProperties: CalcPropertiesSnapshot;
+    /** Global workbook properties. */
+    readonly properties: WorkbookPropertiesSnapshot;
+}
+/**
+ * Build a snapshot cell key from row and column.
+ * This key format is used for the `WorksheetSnapshot.cells` map.
+ */
+export declare function snapshotCellKey(row: number, col: number): string;
+/**
+ * Build a formula cell key that includes the sheet name.
+ * Used by the dependency graph and eval session cache.
+ */
+export declare function formulaCellKey(sheet: string, row: number, col: number): string;
+/**
+ * Build a spill cell key using the worksheet id (stable across renames).
+ * Used by the spill engine for persistent tracking.
+ */
+export declare function spillCellKeyFromId(worksheetId: number, row: number, col: number): string;
+/**
+ * Build the key used to store a sheet-scoped defined name.
+ * Format: `"SHEETNAME\0NAME"` (null character separator ensures no collisions).
+ */
+export declare function scopedNameKey(sheetName: string, name: string): string;
+/**
+ * Resolve a defined name considering scope precedence.
+ *
+ * Excel name resolution order:
+ * 1. Sheet-scoped name on `currentSheet` (if any)
+ * 2. Workbook-scoped (global) name
+ *
+ * @param definedNames - The defined names map from the snapshot
+ * @param name - The name to resolve (case-insensitive)
+ * @param currentSheet - The sheet where the formula is located
+ * @returns The matching DefinedNameSnapshot, or undefined
+ */
+export declare function resolveDefinedName(definedNames: ReadonlyMap<string, DefinedNameSnapshot>, name: string, currentSheet?: string): DefinedNameSnapshot | undefined;

package/dist/browser/modules/formula/integration/workbook-snapshot.js

@@ -0,0 +1,77 @@
+/**
+ * Workbook Snapshot — Immutable data layer for the formula engine.
+ *
+ * The snapshot captures all workbook state needed for formula compilation
+ * and evaluation as plain, read-only data structures. Runtime/compile code
+ * must depend only on these types — never on live Workbook/Worksheet/Cell
+ * objects.
+ *
+ * ## Design Principles
+ *
+ * 1. **Immutable** — all interfaces use `readonly` modifiers. The engine
+ *    must never mutate snapshot data.
+ * 2. **Self-contained** — every piece of information the engine needs
+ *    (cell values, formula text, table metadata, defined names, calc
+ *    properties) is captured up front.
+ * 3. **No @excel/ imports** — this file defines pure data types. The
+ *    concrete builder that populates these structures lives in
+ *    `workbook-adapter.ts` and is the only file that touches live objects.
+ */
+// ============================================================================
+// Cell Key Helpers
+// ============================================================================
+/**
+ * Build a snapshot cell key from row and column.
+ * This key format is used for the `WorksheetSnapshot.cells` map.
+ */
+export function snapshotCellKey(row, col) {
+    return `${row}:${col}`;
+}
+/**
+ * Build a formula cell key that includes the sheet name.
+ * Used by the dependency graph and eval session cache.
+ */
+export function formulaCellKey(sheet, row, col) {
+    return `${sheet}!${row}:${col}`;
+}
+/**
+ * Build a spill cell key using the worksheet id (stable across renames).
+ * Used by the spill engine for persistent tracking.
+ */
+export function spillCellKeyFromId(worksheetId, row, col) {
+    return `ws:${worksheetId}!${row}:${col}`;
+}
+// ============================================================================
+// Defined Name Resolution
+// ============================================================================
+/**
+ * Build the key used to store a sheet-scoped defined name.
+ * Format: `"SHEETNAME\0NAME"` (null character separator ensures no collisions).
+ */
+export function scopedNameKey(sheetName, name) {
+    return `${sheetName.toUpperCase()}\0${name.toUpperCase()}`;
+}
+/**
+ * Resolve a defined name considering scope precedence.
+ *
+ * Excel name resolution order:
+ * 1. Sheet-scoped name on `currentSheet` (if any)
+ * 2. Workbook-scoped (global) name
+ *
+ * @param definedNames - The defined names map from the snapshot
+ * @param name - The name to resolve (case-insensitive)
+ * @param currentSheet - The sheet where the formula is located
+ * @returns The matching DefinedNameSnapshot, or undefined
+ */
+export function resolveDefinedName(definedNames, name, currentSheet) {
+    // 1. Try sheet-scoped name first
+    if (currentSheet) {
+        const scopedKey = scopedNameKey(currentSheet, name);
+        const scoped = definedNames.get(scopedKey);
+        if (scoped) {
+            return scoped;
+        }
+    }
+    // 2. Fall back to global name
+    return definedNames.get(name.toUpperCase());
+}

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

@@ -0,0 +1,34 @@
+/**
+ * Build Writeback Plan — Convert evaluation results into a WritebackPlan.
+ *
+ * This module takes the evaluation results from the evaluator and
+ * produces a declarative `WritebackPlan` that describes all cell mutations.
+ * The plan is then applied by `apply-writeback-plan.ts`.
+ *
+ * ## Responsibilities
+ *
+ * 1. Classify each formula's result as scalar, CSE, or dynamic-array.
+ * 2. Check spill availability and detect #SPILL! conflicts.
+ * 3. Generate cleanup operations for stale ghost cells.
+ * 4. Track spill regions and ghost snapshots for persistence.
+ *
+ * ## Key Principle
+ *
+ * This module does NOT touch any live workbook objects. It reads only
+ * from the `WorkbookSnapshot` and the evaluation results.
+ */
+import type { CompiledFormula } from "../compile/compiled-formula.js";
+import type { WorkbookSnapshot } from "../integration/workbook-snapshot.js";
+import type { RuntimeValue } from "../runtime/values.js";
+import type { SpillRegion } from "./types.js";
+import type { WritebackPlan } from "./writeback-plan.js";
+/**
+ * Build a complete `WritebackPlan` from evaluation results.
+ *
+ * @param snapshot - The workbook snapshot
+ * @param compiled - All compiled formulas in evaluation order
+ * @param results - Raw evaluation results, keyed by formula cell key
+ * @param previousSpills - Persistent spill regions from previous calculation
+ * @param previousGhosts - Persistent ghost snapshots from previous calculation
+ */
+export declare function buildWritebackPlan(snapshot: WorkbookSnapshot, compiled: readonly CompiledFormula[], results: ReadonlyMap<string, RuntimeValue>, previousSpills: ReadonlyMap<string, SpillRegion>, previousGhosts: ReadonlyMap<string, unknown>): WritebackPlan;