@cj-tech-master/excelts 9.2.1 → 9.3.0

package/dist/esm/modules/formula/host-registry.js

@@ -0,0 +1,69 @@
+/**
+ * Formula Engine Registry
+ *
+ * A tiny indirection layer that lets `Workbook.calculateFormulas()` and
+ * the PDF bridge invoke a full formula engine **only if the host
+ * application has opted in** by calling `installFormulaEngine()` from
+ * `@cj-tech-master/excelts/formula`.
+ *
+ * ## Why a registry
+ *
+ * The formula engine ships 433 Excel functions, a tokenizer, a parser,
+ * a compiler, an evaluator, a dependency graph and a spill materialiser.
+ * Minified this is ~200 KB. Most Workbook users only need to read /
+ * write XLSX files and let Excel recalculate on open; pulling the
+ * engine into their bundle unconditionally would be a large, invisible
+ * cost.
+ *
+ * This file is the single point of indirection. Importing `Workbook`
+ * pulls it in (~2.5 KB) but does NOT pull in the engine; the engine's
+ * implementation only arrives once someone calls `installFormulaEngine()`,
+ * which bundlers can then resolve to the subpath import graph.
+ *
+ * If `calculateFormulas()` is called without `installFormulaEngine()`
+ * having run, a clear error is thrown telling the developer how to fix it.
+ */
+let installed = null;
+/**
+ * Install a formula engine implementation. Called from
+ * `installFormulaEngine()` in the `@cj-tech-master/excelts/formula`
+ * subpath.
+ *
+ * Re-installing is allowed — the last registration wins. This keeps
+ * hot-reload tooling and tests simple. Passing `null` uninstalls the
+ * engine, which is useful for tests that exercise the
+ * "no engine" error path.
+ */
+export function registerFormulaEngine(engine) {
+    installed = engine;
+}
+/** Returns true when a formula engine has been installed. */
+export function hasFormulaEngine() {
+    return installed !== null;
+}
+/**
+ * Invoke the registered engine on `workbook`. Throws a descriptive error
+ * if no engine has been installed.
+ */
+export function invokeFormulaEngine(workbook) {
+    if (!installed) {
+        throw new Error("No formula engine is installed. " +
+            "Call `installFormulaEngine()` from `@cj-tech-master/excelts/formula` " +
+            "once at startup to enable `Workbook.calculateFormulas()` and " +
+            "automatic recalculation during `excelToPdf()`.");
+    }
+    installed(workbook);
+}
+/**
+ * Like {@link invokeFormulaEngine} but returns silently when no engine is
+ * installed. Used by `excelToPdf()` so that PDF export still works for
+ * workbooks whose cached formula results are already up to date (the
+ * common case when the XLSX was saved by Excel itself).
+ */
+export function tryInvokeFormulaEngine(workbook) {
+    if (!installed) {
+        return false;
+    }
+    installed(workbook);
+    return true;
+}

package/dist/esm/modules/formula/index.js

@@ -0,0 +1,49 @@
+/**
+ * Public entry for the excelts formula engine.
+ *
+ * Two complementary usage styles are supported:
+ *
+ * 1. **Functional, zero-side-effect**:
+ *    ```ts
+ *    import { calculateFormulas } from "@cj-tech-master/excelts/formula";
+ *    calculateFormulas(workbook);
+ *    ```
+ *    Perfect tree-shaking: unused exports are dropped, no module
+ *    initialisation runs. Bundles that import only `tokenize` or
+ *    `parse` never pull the evaluator or function registry in.
+ *
+ * 2. **Engine installation**, to enable `Workbook.calculateFormulas()`
+ *    and automatic recalculation in `excelToPdf()`:
+ *    ```ts
+ *    import { installFormulaEngine } from "@cj-tech-master/excelts/formula";
+ *    installFormulaEngine();                // once, at startup
+ *    workbook.calculateFormulas();          // now works
+ *    ```
+ *
+ * The engine is **never installed implicitly** — consumers pay for what
+ * they ask for. This keeps the root `package.json` `sideEffects: false`
+ * contract intact, so bundles that only use the functional API include
+ * exactly the code paths reachable from the exports they reference.
+ *
+ * Note: `installFormulaEngine` lives in a separate module
+ * (`./install.ts`) so that its host-registry import and the
+ * evaluator pipeline it carries don't get pulled in by consumers who
+ * only need the tokenizer, parser, or the functional `calculateFormulas`
+ * API. See `scripts/treeshake-verify.ts` for the bundler contracts.
+ */
+// Functional API — same capability exposed as a callable rather than
+// going through `Workbook.calculateFormulas()`. Useful for server-side
+// recalculation of cached XLSX files loaded via the excel module.
+export { calculateFormulas } from "./integration/calculate-formulas.js";
+// Low-level syntax surface — for tooling, static analysers and callers
+// that want to pre-validate formulas without evaluating them.
+export { tokenize } from "./syntax/tokenizer.js";
+export { parse } from "./syntax/parser.js";
+// Engine installer — isolated module so its imports don't leak into
+// functional-only consumers. `createFormulaSyntaxProbe` is exported for
+// callers that want a standalone probe (e.g. for per-Workbook injection
+// via `new Workbook({ formulaSyntaxProbe })`) without touching
+// process-global state. `uninstallFormulaEngine` is exported for
+// symmetry and for test suites that exercise the cold-start
+// classification path.
+export { createFormulaSyntaxProbe, installFormulaEngine, uninstallFormulaEngine } from "./install.js";

package/dist/esm/modules/formula/install.js

@@ -0,0 +1,88 @@
+/**
+ * Opt-in engine installer.
+ *
+ * This file carries the imports that wire a concrete formula engine and
+ * a tokenizer+parser probe into the excel host. Keep these imports
+ * isolated in a separate module so callers who import only the
+ * tokenizer, parser, or the functional `calculateFormulas` API from
+ * `./index` never trigger this module — and its evaluator + function
+ * registry — at bundle time.
+ *
+ * Two process-wide slots are populated:
+ *
+ * 1. The formula-engine slot (`@formula/host-registry`) — enables
+ *    `Workbook.calculateFormulas()` and the PDF bridge's automatic
+ *    recalculation.
+ *
+ * 2. The default syntax-probe slot (`@excel/default-syntax-probe`) —
+ *    enables strict classification of defined-name text (formula vs.
+ *    opaque) during XLSX load. Without this, `DefinedNames` preserves
+ *    unrecognised text verbatim as opaque, which is correct for
+ *    round-trip but cannot evaluate.
+ *
+ * Both slots accept `null` to uninstall. See `createFormulaSyntaxProbe`
+ * for constructing a probe without touching the process-global slot
+ * (useful for tests and for per-Workbook injection via
+ * `new Workbook({ formulaSyntaxProbe })`).
+ */
+import { setDefaultSyntaxProbe } from "./default-syntax-probe.js";
+import { registerFormulaEngine } from "./host-registry.js";
+import { calculateFormulas } from "./integration/calculate-formulas.js";
+import { parse } from "./syntax/parser.js";
+import { tokenize } from "./syntax/tokenizer.js";
+/**
+ * Build a standalone formula-syntax probe backed by the real
+ * tokenizer+parser. The returned function reports whether its argument
+ * parses as a formula expression.
+ *
+ * Unlike {@link installFormulaEngine}, calling this does **not** touch
+ * any process-global state. Inject the returned probe explicitly via
+ * `new Workbook({ formulaSyntaxProbe })` or `new DefinedNames(probe)`
+ * for deterministic, instance-scoped behaviour.
+ */
+export function createFormulaSyntaxProbe() {
+    return (text) => {
+        try {
+            const tokens = tokenize(text);
+            if (tokens.length === 0) {
+                return false;
+            }
+            parse(tokens);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+}
+/**
+ * Install the formula engine and the default syntax probe into the
+ * excel host.
+ *
+ * After calling this once, `Workbook.calculateFormulas()` and the PDF
+ * bridge's automatic recalculation run the full 433-function engine
+ * instead of throwing / using stale cached values, and every
+ * subsequently-loaded workbook's defined-name classification uses the
+ * real tokenizer+parser instead of the conservative "opaque" fallback.
+ *
+ * Safe to call more than once — the registry accepts the last
+ * registration.
+ */
+export function installFormulaEngine() {
+    registerFormulaEngine(wb => {
+        calculateFormulas(wb);
+    });
+    setDefaultSyntaxProbe(createFormulaSyntaxProbe());
+}
+/**
+ * Uninstall both slots, restoring the cold-start state.
+ *
+ * Mainly useful for tests that need to exercise the "no engine" /
+ * "no probe" classification path. In production, calling this is
+ * rarely necessary — subsequent `installFormulaEngine()` calls simply
+ * overwrite the previous registration.
+ */
+export function uninstallFormulaEngine() {
+    registerFormulaEngine(null);
+    setDefaultSyntaxProbe(null);
+}

package/dist/esm/modules/formula/integration/apply-writeback-plan.js

@@ -0,0 +1,210 @@
+/**
+ * Apply Writeback Plan — Write formula results back to the live workbook.
+ *
+ * This is the **only** file that mutates live workbook/cell objects in the
+ * new engine pipeline. It reads a `WritebackPlan` and applies each operation
+ * to the workbook.
+ *
+ * ## Responsibilities
+ *
+ * 1. Apply `ScalarWrite` → set `cell.result`.
+ * 2. Apply `CSEWrite` → distribute array across CSE range, update session cache.
+ * 3. Apply `SpillWrite` → write source + ghost cells, update persistent maps.
+ * 4. Apply `SpillErrorWrite` → set #SPILL! on source cell.
+ * 5. Apply `CleanupWrite` → clear stale ghost cells.
+ * 6. Apply `PreserveWrite` → no-op (cell keeps existing result).
+ * 7. Update persistent spill maps and ghost snapshot maps.
+ */
+import { getGhostSnapshots, getPersistentSpillMap } from "../materialize/spill-engine.js";
+import { CellValueTypeLike } from "../materialize/types.js";
+// ============================================================================
+// Apply Writeback Plan
+// ============================================================================
+/**
+ * Apply a `WritebackPlan` to a live workbook.
+ *
+ * This mutates the workbook in-place. Operations are applied in order.
+ * After all operations, persistent spill metadata is updated.
+ */
+export function applyWritebackPlan(workbook, plan) {
+    // Apply each operation
+    for (const op of plan.operations) {
+        applyOperation(workbook, op);
+    }
+    // Update persistent spill metadata
+    const persistentSpills = getPersistentSpillMap(workbook);
+    const ghostSnapshots = getGhostSnapshots(workbook);
+    // Remove stale spill entries
+    for (const key of plan.spillState.removedSpillKeys) {
+        persistentSpills.delete(key);
+    }
+    // Update spill regions
+    for (const [key, region] of plan.spillState.spillRegions) {
+        persistentSpills.set(key, region);
+    }
+    // Update ghost value snapshots
+    for (const [key, value] of plan.spillState.ghostSnapshots) {
+        ghostSnapshots.set(key, snapshotValueToRaw(value));
+    }
+}
+// ============================================================================
+// Apply Individual Operations
+// ============================================================================
+function applyOperation(workbook, op) {
+    switch (op.type) {
+        case "scalar":
+            applyScalarWrite(workbook, op);
+            break;
+        case "cse":
+            applyCSEWrite(workbook, op);
+            break;
+        case "spill":
+            applySpillWrite(workbook, op);
+            break;
+        case "spill-error":
+            applySpillErrorWrite(workbook, op);
+            break;
+        case "cleanup":
+            applyCleanupWrite(workbook, op);
+            break;
+        case "preserve":
+            // No-op: keep existing cached result
+            break;
+    }
+}
+function applyScalarWrite(workbook, op) {
+    const ws = workbook.getWorksheet(op.sheetName);
+    if (!ws) {
+        return;
+    }
+    const cell = ws.findCell(op.row, op.col);
+    if (!cell) {
+        return;
+    }
+    cell.result = snapshotValueToResult(op.value);
+}
+function applyCSEWrite(workbook, op) {
+    const ws = workbook.getWorksheet(op.sheetName);
+    if (!ws) {
+        return;
+    }
+    const numRows = op.bottom - op.top + 1;
+    const numCols = op.right - op.left + 1;
+    for (let r = 0; r < numRows; r++) {
+        for (let c = 0; c < numCols; c++) {
+            const targetRow = op.top + r;
+            const targetCol = op.left + c;
+            // Use `findCell` (non-creating) rather than `getCell`. Only cells
+            // that are already CSE array slaves — i.e., existing formula cells
+            // sharing the master's array `ref` — receive results. Calling
+            // `getCell` would lazily materialise every blank position in the
+            // target range, which for a 1000×1000 CSE region would bloat the
+            // workbook with a million empty cells (and force every subsequent
+            // row iterator to walk them). The type check on the next line
+            // already implied this intent; we now match it with a matching
+            // lookup that has no side effects.
+            const targetCell = ws.findCell(targetRow, targetCol);
+            if (targetCell && targetCell.type === CellValueTypeLike.Formula) {
+                if (op.scalarFill !== undefined) {
+                    targetCell.result = snapshotValueToResult(op.scalarFill);
+                }
+                else {
+                    const val = op.results[r]?.[c] ?? null;
+                    targetCell.result = snapshotValueToResult(val);
+                }
+            }
+        }
+    }
+}
+function applySpillWrite(workbook, op) {
+    const ws = workbook.getWorksheet(op.sheetName);
+    if (!ws) {
+        return;
+    }
+    const numRows = op.results.length;
+    const numCols = op.results[0]?.length ?? 0;
+    for (let r = 0; r < numRows; r++) {
+        for (let c = 0; c < numCols; c++) {
+            const targetRow = op.row + r;
+            const targetCol = op.col + c;
+            const val = op.results[r]?.[c] ?? null;
+            if (r === 0 && c === 0) {
+                // Source cell: set result
+                const sourceCell = ws.findCell(targetRow, targetCol);
+                if (sourceCell) {
+                    sourceCell.result = snapshotValueToResult(val);
+                }
+            }
+            else {
+                // Ghost cell: set value (not result)
+                const targetCell = ws.getCell(targetRow, targetCol);
+                targetCell.value = snapshotValueToRaw(val);
+            }
+        }
+    }
+}
+function applySpillErrorWrite(workbook, op) {
+    const ws = workbook.getWorksheet(op.sheetName);
+    if (!ws) {
+        return;
+    }
+    const cell = ws.findCell(op.row, op.col);
+    if (cell) {
+        cell.result = { error: "#SPILL!" };
+    }
+}
+function applyCleanupWrite(workbook, op) {
+    const ws = workbook.getWorksheet(op.sheetName);
+    if (!ws) {
+        return;
+    }
+    for (const { row, col } of op.cells) {
+        const cell = ws.findCell(row, col);
+        if (cell) {
+            cell.value = null;
+        }
+    }
+}
+// ============================================================================
+// Value Conversion (Snapshot → Live)
+// ============================================================================
+/**
+ * Convert a snapshot cell value to a `FormulaResult` suitable for `cell.result`.
+ *
+ * `null` represents a BLANK — the formula produced no value (e.g.
+ * `=IF(FALSE, 1, )` or an empty reference). Returning literal `0` for
+ * that case conflates "formula returned 0" with "formula returned
+ * nothing", which breaks downstream consumers that distinguish the two
+ * (for instance, `ISBLANK(A1)` on a cell that holds `=B1` where B1 is
+ * empty should stay TRUE, not flip to FALSE because we injected 0).
+ */
+function snapshotValueToResult(val) {
+    if (val === null) {
+        return undefined;
+    }
+    if (typeof val === "number" || typeof val === "string" || typeof val === "boolean") {
+        return val;
+    }
+    if (isSnapshotError(val)) {
+        return val;
+    }
+    return undefined;
+}
+/**
+ * Convert a snapshot cell value to a raw value suitable for `cell.value`.
+ */
+function snapshotValueToRaw(val) {
+    if (val === null) {
+        return null;
+    }
+    if (typeof val === "number" || typeof val === "string" || typeof val === "boolean") {
+        return val;
+    }
+    if (isSnapshotError(val)) {
+        return val;
+    }
+    return null;
+}
+function isSnapshotError(val) {
+    return val !== null && typeof val === "object" && "error" in val;
+}