@cj-tech-master/excelts 9.2.1 → 9.3.0

package/dist/types/modules/formula/functions/text.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Text Functions — Native RuntimeValue implementations.
+ */
+import type { RuntimeValue } from "../runtime/values.js";
+/** Type alias for a native text function. */
+type NativeFn = (args: RuntimeValue[]) => RuntimeValue;
+export declare const fnCONCATENATE: NativeFn;
+export declare const fnCONCAT: NativeFn;
+export declare const fnTEXTJOIN: NativeFn;
+export declare const fnLEFT: NativeFn;
+export declare const fnRIGHT: NativeFn;
+export declare const fnMID: NativeFn;
+export declare const fnLEN: NativeFn;
+export declare const fnTRIM: NativeFn;
+export declare const fnLOWER: NativeFn;
+export declare const fnUPPER: NativeFn;
+export declare const fnPROPER: NativeFn;
+export declare const fnSUBSTITUTE: NativeFn;
+export declare const fnREPLACE: NativeFn;
+export declare const fnFIND: NativeFn;
+export declare const fnSEARCH: NativeFn;
+export declare const fnREPT: NativeFn;
+export declare const fnTEXT: NativeFn;
+export declare const fnVALUE: NativeFn;
+export declare const fnEXACT: NativeFn;
+export declare const fnCODE: NativeFn;
+export declare const fnCHAR: NativeFn;
+export declare const fnCLEAN: NativeFn;
+export declare const fnT: NativeFn;
+export declare const fnUNICHAR: NativeFn;
+export declare const fnUNICODE: NativeFn;
+export declare const fnBAHTTEXT: NativeFn;
+export declare const fnDOLLAR: NativeFn;
+export declare const fnFIXED: NativeFn;
+export declare const fnASC: NativeFn;
+export declare const fnDBCS: NativeFn;
+export declare const fnJIS: NativeFn;
+export declare const fnPHONETIC: NativeFn;
+export declare const fnNUMBERVALUE: NativeFn;
+export declare const fnTEXTBEFORE: NativeFn;
+export declare const fnTEXTAFTER: NativeFn;
+export declare const fnTEXTSPLIT: NativeFn;
+/**
+ * REGEXTEST(text, pattern, [case_sensitivity]) — returns TRUE iff the
+ * regex matches any substring of `text`.
+ */
+export declare const fnREGEXTEST: NativeFn;
+/**
+ * REGEXEXTRACT(text, pattern, [return_mode], [case_sensitivity]) —
+ *   return_mode = 0 (default) → first match as a string
+ *   return_mode = 1 → all matches as a 1-column array
+ *   return_mode = 2 → capture groups of the first match as a 1-row array
+ */
+export declare const fnREGEXEXTRACT: NativeFn;
+/**
+ * REGEXREPLACE(text, pattern, replacement, [occurrence], [case_sensitivity]) —
+ *   occurrence = 0 (default) → replace all
+ *   occurrence = n (positive) → replace only the n-th match
+ *   occurrence = n (negative) → replace only the n-th-last match
+ */
+export declare const fnREGEXREPLACE: NativeFn;
+/**
+ * VALUETOTEXT(value, [format]) — format a scalar or 1×1 array as text.
+ * For multi-cell arrays, this applies implicit intersection at the
+ * evaluator layer — so by the time we see args[0] it is already scalar.
+ */
+export declare const fnVALUETOTEXT: NativeFn;
+/**
+ * ARRAYTOTEXT(array, [format]) — flatten an array to a delimited text
+ * representation.
+ *
+ * Format 0 (concise, default): row-major join with ", ".
+ * Format 1 (strict): wraps output in `{…}`, rows separated by `;`,
+ *   cells by `,`; strings inside quoted.
+ */
+export declare const fnARRAYTOTEXT: NativeFn;
+/**
+ * ENCODEURL(text) — percent-encode a string for URL use.
+ *
+ * Excel follows RFC 3986's "unreserved" character rule: A-Z, a-z, 0-9,
+ * and `- _ . ~` are kept verbatim; everything else is encoded as
+ * `%HH` using the UTF-8 byte sequence. This is exactly what JavaScript's
+ * `encodeURIComponent` does, so we delegate to it.
+ */
+export declare const fnENCODEURL: NativeFn;
+export {};

package/dist/types/modules/formula/host-registry.d.ts

@@ -0,0 +1,53 @@
+/**
+ * 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.
+ */
+import type { WorkbookLike } from "./materialize/types.js";
+/** The function shape {@link installFormulaEngine} registers here. */
+export type FormulaEngine = (workbook: WorkbookLike) => void;
+/**
+ * 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 declare function registerFormulaEngine(engine: FormulaEngine | null): void;
+/** Returns true when a formula engine has been installed. */
+export declare function hasFormulaEngine(): boolean;
+/**
+ * Invoke the registered engine on `workbook`. Throws a descriptive error
+ * if no engine has been installed.
+ */
+export declare function invokeFormulaEngine(workbook: WorkbookLike): void;
+/**
+ * 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 declare function tryInvokeFormulaEngine(workbook: WorkbookLike): boolean;

package/dist/types/modules/formula/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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.
+ */
+export { calculateFormulas } from "./integration/calculate-formulas.js";
+export { tokenize } from "./syntax/tokenizer.js";
+export { parse } from "./syntax/parser.js";
+export { createFormulaSyntaxProbe, installFormulaEngine, uninstallFormulaEngine } from "./install.js";
+export type { SyntaxProbe } from "./default-syntax-probe.js";
+export type { CellErrorValueLike, CellLike, DefinedNameEntry, DefinedNamesLike, DimensionsLike, FormulaResultLike, RowLike, SpillRegion, WorkbookLike, WorksheetLike } from "./materialize/types.js";

package/dist/types/modules/formula/install.d.ts

@@ -0,0 +1,62 @@
+/**
+ * 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 { type SyntaxProbe } from "./default-syntax-probe.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 declare function createFormulaSyntaxProbe(): SyntaxProbe;
+/**
+ * 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 declare function installFormulaEngine(): void;
+/**
+ * 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 declare function uninstallFormulaEngine(): void;

package/dist/types/modules/formula/integration/apply-writeback-plan.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 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 type { WorkbookLike } from "../materialize/types.js";
+import type { WritebackPlan } from "../materialize/writeback-plan.js";
+/**
+ * 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 declare function applyWritebackPlan(workbook: WorkbookLike, plan: WritebackPlan): void;

package/dist/types/modules/formula/integration/calculate-formulas-impl.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Formula Calculation Implementation
+ *
+ * The pipeline that implements the snapshot → compile → evaluate →
+ * materialize → apply architecture.
+ *
+ * ## Pipeline Steps
+ *
+ * 1. **Snapshot** — `buildWorkbookSnapshot()` creates an immutable snapshot
+ *    of the entire workbook.
+ * 2. **Normalize** — `collectFormulaInstances()` extracts all formula cells
+ *    into uniform `FormulaInstance` objects.
+ * 3. **Parse** — Each formula's source text is tokenized and parsed into an AST.
+ * 4. **Compile** — The binder transforms each AST into a `BoundExpr` tree,
+ *    resolving names, structured references, and sheet references.
+ * 5. **Dependency Analysis** — Static dependencies are extracted from bound
+ *    expressions and a topological evaluation order is computed.
+ * 6. **Evaluate** — Formulas are evaluated in dependency order using the
+ *    evaluator which operates on `BoundExpr` and produces `RuntimeValue`.
+ * 7. **Materialize** — Evaluation results are converted into a `WritebackPlan`.
+ * 8. **Apply** — The plan is applied to the live workbook.
+ */
+import type { WorkbookLike } from "../materialize/types.js";
+/**
+ * Recalculate all formula cells using the new pipeline.
+ *
+ * This implements the full snapshot → compile → evaluate → materialize → apply
+ * architecture. The workbook is mutated only at the final apply step.
+ */
+export declare function calculateFormulasImpl(workbook: WorkbookLike): void;

package/dist/types/modules/formula/integration/calculate-formulas.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Formula Calculation Engine
+ *
+ * Provides `calculateFormulas()` as the primary function-style entry
+ * point. The same work runs when a host calls
+ * `Workbook.calculateFormulas()` — both paths dispatch through the
+ * engine registered via `installFormulaEngine()`.
+ *
+ * ## Architecture
+ *
+ * 1. **Snapshot** — immutable capture of all workbook state
+ * 2. **Normalize** — uniform FormulaInstance objects
+ * 3. **Parse** — tokenize → AST
+ * 4. **Compile** — bind AST → BoundExpr (resolve names, structured refs, sheets)
+ * 5. **Dependency Analysis** — topological sort
+ * 6. **Evaluate** — execute BoundExpr with RuntimeValue system
+ * 7. **Materialize** — build declarative WritebackPlan
+ * 8. **Apply** — write plan to live workbook
+ */
+import type { WorkbookLike } from "../materialize/types.js";
+export type { DefinedNamesLike, WorkbookLike } from "../materialize/types.js";
+/**
+ * Recalculate all formula cells in a workbook.
+ *
+ * Evaluates every formula cell using the built-in calculation engine
+ * and updates each cell's `result` value. Formulas are evaluated lazily
+ * with recursive dependency resolution, memoization, and circular
+ * reference detection.
+ *
+ * All evaluation state is scoped to this invocation — concurrent calls
+ * for different workbooks are safe.
+ *
+ * **Supported formula features:**
+ * - Cell references: `A1`, `$B$2`, `Sheet1!A1`, `'Sheet Name'!A1:B10`
+ * - Operators: `+ - * / ^`, `& (concat)`, `= <> < > <= >=`, `%`
+ * - 433 built-in functions across math, text, logical, date, lookup,
+ *   statistical, financial, dynamic-array, database and engineering
+ *   categories.
+ * - Shared formulas, array constants, nested expressions
+ * - Dynamic array spill: FILTER, SORT, UNIQUE, SORTBY results are
+ *   written to adjacent cells. #SPILL! error if target cells are occupied.
+ * - CSE array formulas: `{=formula}` with a ref range distribute results
+ *   across the designated range.
+ * - Array arithmetic broadcasting: `{1,2,3} + {4;5;6}` produces a 3x3 matrix.
+ * - Implicit intersection: range references in scalar context pick the
+ *   value from the formula cell's row or column.
+ *
+ * **Unsupported formula behavior:**
+ * - If a formula uses a function the engine does not implement, the engine
+ *   returns `#NAME?`. However, if the cell already has a cached result
+ *   (e.g., pre-computed by Excel when the XLSX was saved), that cached
+ *   result is **preserved** — the engine will not overwrite usable data.
+ * - If no cached result exists, the cell's result becomes `#NAME?`.
+ *
+ * **Volatile functions:**
+ * - `RAND`, `RANDBETWEEN`, `NOW`, `TODAY` are re-evaluated on every call.
+ *   This is intentional — these functions are expected to produce fresh values.
+ *
+ * **Side effects:**
+ * - This function **mutates** the workbook by updating formula cells' `result`
+ *   property in-place. For dynamic array formulas, adjacent cells are also
+ *   written with spill results. If you need the original cached results
+ *   preserved, clone the workbook before calling this function.
+ *
+ * @param workbook - The workbook whose formulas should be recalculated
+ */
+export declare function calculateFormulas(workbook: WorkbookLike): void;

package/dist/types/modules/formula/integration/formula-instance.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Formula Instance — Unified model for all formula cell variants.
+ *
+ * The normalizer converts the heterogeneous formula representations found
+ * in the snapshot (normal, shared-master, shared-slave, CSE, dynamic-array)
+ * into a uniform `FormulaInstance` structure. After normalization, the
+ * compile and runtime layers do not need to know how a formula originated.
+ *
+ * ## Invariants
+ *
+ * - Every `FormulaInstance` has a non-empty `sourceText` (the formula to parse).
+ * - Shared-slave formulas have already been translated (offset applied) by
+ *   the snapshot builder, so `sourceText` is the final formula text.
+ * - `kind` is preserved so the materialize layer can determine the correct
+ *   writeback strategy (scalar vs. CSE vs. spill).
+ */
+import type { FormulaCellKind, WorkbookSnapshot } from "./workbook-snapshot.js";
+/**
+ * A normalized, engine-internal representation of a formula cell.
+ * This is the unit of work that enters the compile → evaluate pipeline.
+ */
+export interface FormulaInstance {
+    /** The worksheet name this formula belongs to. */
+    readonly sheetName: string;
+    /** The worksheet id (stable across renames). */
+    readonly sheetId: number;
+    /** 1-based row number. */
+    readonly row: number;
+    /** 1-based column number. */
+    readonly col: number;
+    /** The final formula text to parse and evaluate. */
+    readonly sourceText: string;
+    /**
+     * The formula classification.
+     * - `"normal"` — standard scalar formula
+     * - `"shared-master"` — master of a shared formula group (treated as normal for eval)
+     * - `"shared-slave"` — slave with translated formula (treated as normal for eval)
+     * - `"cse"` — legacy CSE array formula; result distributed across `targetRef`
+     * - `"dynamic-array"` — dynamic array formula; result spills to adjacent cells
+     */
+    readonly kind: FormulaCellKind;
+    /**
+     * For CSE formulas: the target range in "A1:B2" format.
+     * For dynamic-array formulas: `undefined` (spill range is computed at runtime).
+     * For all other kinds: `undefined`.
+     */
+    readonly targetRef?: string;
+    /**
+     * Whether this formula was explicitly flagged as a dynamic array formula
+     * (from the XLSX `isDynamicArray` attribute).
+     */
+    readonly isDynamicArray: boolean;
+}
+/**
+ * Collect all formula instances from a workbook snapshot.
+ *
+ * Iterates every cell in every worksheet, selects cells with formulas,
+ * and normalizes them into `FormulaInstance` objects. The result is a
+ * flat list ordered by worksheet order then cell position.
+ *
+ * This replaces the old `collectFormulaCells()` function but operates
+ * entirely on snapshot data — no live workbook objects are touched.
+ */
+export declare function collectFormulaInstances(snapshot: WorkbookSnapshot): FormulaInstance[];

package/dist/types/modules/formula/integration/workbook-adapter.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Workbook Adapter — Bridge between a host workbook (implementing the
+ * `WorkbookLike` / `WorksheetLike` / `CellLike` interfaces) and the
+ * engine's snapshot representation.
+ *
+ * This is the only file in the engine pipeline that walks a live host
+ * workbook; the rest of the pipeline consumes the immutable
+ * `WorkbookSnapshot` this file produces.
+ *
+ * ## Responsibilities
+ *
+ * 1. `buildWorkbookSnapshot()` — walk the host workbook and produce an
+ *    immutable `WorkbookSnapshot`.
+ * 2. Cell value conversion — Date → serial number, rich text → string,
+ *    shared formula translation, etc.
+ */
+import type { WorkbookLike } from "../materialize/types.js";
+import type { WorkbookSnapshot } from "./workbook-snapshot.js";
+/**
+ * Build a complete `WorkbookSnapshot` from a live workbook.
+ *
+ * This traverses all worksheets and cells once, converting everything to
+ * engine-internal snapshot types. The result is a fully self-contained,
+ * read-only data structure.
+ */
+export declare function buildWorkbookSnapshot(workbook: WorkbookLike): WorkbookSnapshot;