@sheetxl/sdk 0.8.0-beta.1 → 0.8.0-beta.11

package/types/src/calculation/ExternalBookBindings.d.ts

@@ -0,0 +1,118 @@
+import { Scalar } from '@sheetxl/primitives';
+import { ICell } from '../cell';
+import { Tuple } from '../collections';
+import { IExternalBookCollection } from '../externalBook';
+import { CalcGridBackend, FormulaHost } from './grid';
+/**
+ * A cached defined name of an external book, as the named-formula symbol provider sees it.
+ *
+ * @remarks
+ * The minimal `INamed.INamedValue` shape plus the duck-typed `getScope` the provider keys on.
+ * {@link getId} is the fake id the provider minted for the pair, which is also the virtual grid the
+ * body compiles into — the same arrangement a workbook's own name has, so a `[1]!Name` node
+ * evaluates through `getNamedFormulaBlock` unchanged.
+ */
+export interface ExternalNamedItem {
+    getId(): string;
+    getName(): string;
+    /** The `ext:` id the name is scoped to — the book, or one of its sheets. */
+    getScope(): string;
+    /** The cached body as written; replaced in place when a refresh changes it. */
+    refersTo: string;
+}
+/**
+ * What an external book's cache is to the engine: one read-only grid per sheet, and one virtual
+ * grid per cached defined name — reconciled against the collection on every change.
+ *
+ * @remarks
+ * DESIGN-EXTERNAL-LINKS §5 steps 15 and 16. The measured rule (§6 items 1 and 2) is that an
+ * external cell the cache does not hold is a BLANK CELL, so a sheet's grid is simply the sparse
+ * cache loaded at its real coordinates with the ordinary sheet extent: every cell it does not hold
+ * is already empty, and a whole-column citation walks the cache's used cells like any sheet's.
+ * A sheet with no cache at all gets an empty grid for the same reason — Excel answers blank there
+ * too, and the alternative (`#REF!`) is the value damage this phase exists to remove.
+ *
+ * Grids are keyed by the `ext:` stable id the sheet symbol binds to, so `container.getGrid(scope)`
+ * finds them with no change to the executor. A book's removal unregisters its grids WITHOUT the
+ * `delete()` a dropped sheet gets: a citation keeps the slot's id and computes `#REF!`, and an undo,
+ * which restores the slot with its id, rebuilds the grids and heals it (see
+ * `IExternalBook.delete`).
+ *
+ * A cached name's body is compiled INSIDE the book (`SheetCtx.book`), so `'Alpha'!$A$1` names the
+ * book's sheet; a bare reference anchors to the scoping sheet, else the book's first. A name is
+ * found under exactly the scope it was cached with — Excel flattens a sheet-scoped source name
+ * into the book's namespace on caching and then answers `#NAME?` to the sheet-qualified citation
+ * of it (measured 2026-09-11, `externalLinksNames.xlsx` + `probe-external-names-recalc.ps1`:
+ * `'Data Sheet'!Local` is cached with no `sheetId`, and `'[1]Data Sheet'!Local` rebuilds to
+ * `#NAME?` with the source absent), so there is no sheet-to-book fallback here.
+ */
+export declare class ExternalBookBindings {
+    private readonly _options;
+    /** Every registered name, by the provider's key: `<scopeId>::<lowercase name>`. */
+    private readonly _namesByKey;
+    private readonly _namesById;
+    /** The virtual grids the names above compile into, by fake id. */
+    private readonly _hostsById;
+    /** The cache tuples each sheet grid was loaded from, by grid id — a refresh swaps them. */
+    private readonly _loadedData;
+    constructor(options: ExternalBookBindings.ConstructorOptions);
+    /**
+     * Brings the grids and names into step with the collection: a book or sheet that arrived gets
+     * its grid, one that left loses it, and the same for names. Cheap when nothing changed.
+     *
+     * @param initial The sync at construction, before any formula has compiled. A name registered
+     * here needs no recompile of its citations: they do not exist yet, and every one that compiles
+     * later binds to the id minted here. A recompile would rewrite each citing formula and mark it
+     * dirty, which is what turned a loaded cell's cached value into the name's recomputed one on the
+     * first pass after open — where Excel keeps the loaded value until a full recalculation.
+     * @returns The ids of the books whose grids or names changed — the caller dirties their citations.
+     */
+    sync(initial?: boolean): ReadonlySet<string>;
+    /**
+     * The name `name` cached under exactly `scopeId` — a book, or one of its sheets — or `null`.
+     * The named symbol provider's lookup for an external scope.
+     */
+    getNameByScope(name: string, scopeId: string): ExternalNamedItem | null;
+    /** The name holding a fake id, or `null`. */
+    getNameById(id: string): ExternalNamedItem | null;
+    /** Every registered sheet grid's id — read off the container, which is the state that undoes. */
+    private _registeredSheetGrids;
+    private _registerSheet;
+    private _registerName;
+    /** Writes a name's body into its virtual grid at the engine's next safe point. */
+    private _queueBody;
+}
+/**
+ * A sheet's cache — `IExternalBook.SheetData.data`, row-major as the part stores it — as the
+ * column-major scalar tuples a `CalcGridBackend` loads.
+ *
+ * @remarks
+ * `ICell.JSON`'s untyped arm is a bare primitive, and the cache's strings are LITERAL (never a
+ * string-table index — the part inlines them, design doc §1). The typed arm carries an error by
+ * code. `null` when the cache holds nothing.
+ */
+export declare function cacheToGridTuples(data: Tuple.GridTuple<ICell.JSON> | null | undefined): Tuple.GridTuple<Scalar> | null;
+export declare namespace ExternalBookBindings {
+    interface ConstructorOptions {
+        /** The collection to mirror — read fresh on every {@link ExternalBookBindings.sync}. */
+        books: IExternalBookCollection;
+        /** Creates AND registers a grid under `id` — `Calculation._createCalcGrid`. */
+        createGrid: (id: string) => CalcGridBackend;
+        /** Takes a sheet grid out of the graph, its citations left as written — `CalcGridBackend._detach`. */
+        unregisterGrid: (id: string) => void;
+        getGrid: (id: string) => CalcGridBackend | null;
+        /** Every registered grid's id, so a removal can be found without a second record of it. */
+        gridIds: () => Iterable<string>;
+        /** Whether the engine holds grids now; the sheet grids wait for it. `true` when absent. */
+        holdsGrids?: () => boolean;
+        /** A name's virtual grid, as a handle — `Calculation._createFormulaHost` with the named options. */
+        createHost: (id: string) => FormulaHost;
+        /** The named symbol provider's `bind(name, { scope, own: true })` — the pair's fake id. */
+        bindNameId: (name: string, scopeId: string) => string;
+        /** Runs an action at the engine's next safe point, with priority — `Calculation._whenSafe`. */
+        queue: (action: () => Promise<unknown>) => void;
+        /** `IContextContainer.recompileNamed` — the dependents of a freshly written body. */
+        recompileNamed: (id: string) => void;
+    }
+}
+//# sourceMappingURL=ExternalBookBindings.d.ts.map

package/types/src/calculation/FormulaLiterals.d.ts

@@ -5,7 +5,8 @@ import { Scalar } from '@sheetxl/primitives';
  *
  * @param text The formula text, without a leading `=`.
  * @returns The literal's value, or `undefined` when the text is anything else — a reference, a
- * function call, an expression, or text that does not lex at all.
+ * function call, an expression, or text that does not lex at all — or when the parser is not
+ * loaded (see `FormulaText.load`).
  *
  * @remarks
  * Backed by the calculation compiler's own lexer and literal actions (canonical locale: `.`

package/types/src/calculation/FormulaText.d.ts

@@ -0,0 +1,98 @@
+import { IRange } from '@sheetxl/primitives';
+import { ICalculation } from './ICalculation';
+/**
+ * Formula text as a tree, and back, with no calculation involved.
+ *
+ * @remarks
+ * A file format reads and writes formulas as text and needs to see their structure to spell them:
+ * which function a name is, which argument a range sits in, where an operator was implied. This is
+ * the parser and the printer the compiler uses, offered on text alone. Nothing here resolves a
+ * symbol or evaluates anything: a sheet name is text, a function name is text, a cell is an
+ * offset from the anchor.
+ *
+ * The parser is loaded on demand. Await {@link load} first: until it resolves, {@link parse}
+ * answers `null` and {@link transform} returns the tree it was given, which is what each answers
+ * for text it cannot read. A calculation's start loads it too.
+ *
+ * @example
+ * ```ts
+ * await FormulaText.load();
+ * const root = FormulaText.parse('SUM(A1:A5)', { anchor: { rowIndex: 9, colIndex: 1 } });
+ * const spelled = FormulaText.transform(root!, (node) =>
+ *   node.type === 'function' && node.value === 'SUM' ? { ...node, value: '_xlfn.SUM' } : undefined
+ * );
+ * FormulaText.image(spelled, { at: { rowIndex: 9, colIndex: 1 } });   // '_xlfn.SUM(A1:A5)'
+ * FormulaText.image(spelled, { at: { rowIndex: 10, colIndex: 1 } });  // '_xlfn.SUM(A2:A6)'
+ * ```
+ */
+export declare namespace FormulaText {
+    interface ParseOptions {
+        /**
+         * The cell the text is written at. A relative reference is stored as its offset from here, so
+         * the same tree images at another cell as the formula would read there. Defaults to `A1`.
+         */
+        anchor?: IRange.CellCoords;
+        /**
+         * Normalize the tree as the compiler does before it links symbols: a `LET` or `LAMBDA`
+         * parameter is a bound name, an unknown function is a call of a name, a structured reference
+         * is normalized and `[#This Row]` reads as `@`. What a writer wants, since that is the shape
+         * the model's canonical text has. A reader wants the text as written, which is the default:
+         * a spelling it has yet to unwrap is still a function to it.
+         */
+        normalize?: boolean;
+    }
+    interface ImageOptions {
+        /**
+         * The cell to image the text at. Image at the anchor the text was parsed at to reproduce it;
+         * image at another cell to re-anchor it. Defaults to `A1`.
+         */
+        at?: IRange.CellCoords;
+        /** The sheet's extent, for whole-row and whole-column references. Defaults to the maximum. */
+        entireCoords?: IRange.Coords;
+        /** Image in R1C1 rather than A1. */
+        r1c1?: boolean;
+    }
+    /**
+     * Loads the parser and the printer. Resolves once {@link parse}, {@link transform}, {@link image},
+     * `parseFormulaLiteral` and `FunctionDeclarations` can answer; at once if they already can.
+     */
+    function load(): Promise<void>;
+    /** Whether {@link load} has resolved, so that every function here answers. */
+    function isLoaded(): boolean;
+    /**
+     * Parses canonical formula text (English function names, `,` separators, no leading `=`) into
+     * its tree, or `null` when the text does not parse or the parser is not loaded.
+     *
+     * @remarks
+     * A sheet, table or name is the text that names it; nothing is resolved. See
+     * {@link ParseOptions.normalize} for the shape of the tree.
+     */
+    function parse(text: string, options?: ParseOptions): ICalculation.FormulaNode | null;
+    /**
+     * Applies a transform to a tree, post-order, and returns the transformed tree: the same object
+     * when the transform changed nothing, or when the parser is not loaded.
+     *
+     * @see {@link ICalculation.FormulaTransform}
+     */
+    function transform(root: ICalculation.FormulaNode, transform: ICalculation.FormulaTransform): ICalculation.FormulaNode;
+    /**
+     * Spells a structured reference to one column of a table, as a formula does: `Sales[Region]`.
+     *
+     * @remarks
+     * A `[`, `]`, `#` or `'` in the column name is escaped with `'`, which is how a formula names
+     * such a column. What a reader uses to name a column it knows only by table and column name.
+     * Needs no {@link load}.
+     */
+    function structuredReference(tableName: string, columnName: string): string;
+    /** Images a tree as text at a cell. */
+    function image(root: ICalculation.FormulaNode, options?: ImageOptions): string;
+    /**
+     * Prepares a tree for imaging at many cells: the tree is rebuilt once, and each call images it
+     * at one cell. What a writer uses for the members of a block that share one formula.
+     *
+     * @throws When the printer is not loaded: a tree comes from {@link parse}, so {@link load} has
+     * resolved before there is one to image.
+     */
+    function imager(root: ICalculation.FormulaNode, options?: Omit<ImageOptions, 'at'>): (at?: IRange.CellCoords) => string;
+}
+//# sourceMappingURL=FormulaText.d.ts.map