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

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

@@ -10,8 +10,13 @@ import { ICalculation } from './ICalculation';
  * 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
@@ -47,9 +52,16 @@ export declare namespace FormulaText {
         /** 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.
+     * 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
@@ -58,7 +70,7 @@ export declare namespace FormulaText {
     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.
+     * when the transform changed nothing, or when the parser is not loaded.
      *
      * @see {@link ICalculation.FormulaTransform}
      */
@@ -69,6 +81,7 @@ export declare namespace FormulaText {
      * @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. */
@@ -76,6 +89,9 @@ export declare namespace FormulaText {
     /**
      * 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;
 }

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

@@ -44,6 +44,8 @@ export interface ICalculation extends IModel {
      * * After it, every answer the engine owes has landed: a formula written before it reads as
      *   compiled, and its value is current (in automatic mode).
      * * Manual mode does not wait for a recalculation nobody has asked for; call {@link calculate}.
+     * * Waits for what consumers derive from the results too ({@link waitUntil}): a conditional
+     *   format reads as painted after it, including one a read just asked to evaluate.
      * * A streaming or async function's result in flight is not waited for: its cell reads as the
      *   current value until the result arrives.
      * * Starts the engine if it is {@link ICalculation.Status.Off}. An engine in
@@ -52,6 +54,21 @@ export interface ICalculation extends IModel {
      * @param options Pass `{ full: true }` to recalculate every grid rather than only the dirty ones.
      */
     ready(options?: ICalculation.CalculateOptions): Promise<ICalculation.Status>;
+    /**
+     * Counts `work` that a consumer derives from the engine's results as calculation in flight
+     * until it settles: {@link ready} waits for it, and {@link getCalculationState} reads
+     * `Calculating` meanwhile.
+     *
+     * @remarks
+     * For anything whose answer follows from a pass and lands after it - a conditional format
+     * re-judging its cells once the pass delivers its formula's values - so that a reader who
+     * waited for `ready()` reads the answer rather than the one before it. Not counted in manual
+     * mode, where the pass such work waits for runs only when asked.
+     *
+     * @param work The derived work. Its failure is the consumer's: it settles the wait either way.
+     * @returns `work`.
+     */
+    waitUntil<T>(work: Promise<T>): Promise<T>;
     /**
      * Returns the current status of the calculation engine: whether it is running at all.
      */
@@ -457,8 +474,13 @@ export declare namespace ICalculation {
          * @remarks
          * - Volatile formulas are re-evaluated on every calculation cycle regardless
          *   of whether their inputs have changed.
-         * - This is a runtime property tracked by the calculation engine — it cannot
-         *   be derived from static AST analysis alone.
+         * - A property of the formula text first, closed over the names it mentions, so an arm no
+         *   branch selects still counts (`=IF(TRUE,1,RAND())`) and the answer stands with nothing
+         *   calculated — a named formula is never evaluated by a pass. A cell is also volatile when
+         *   its last evaluation read cells its text does not name (`OFFSET`, `INDIRECT`, an `INDEX`
+         *   on a computed index, a `SUMIF` sum range extended to its criteria range): its inputs can
+         *   move with its values. And when the engine registered it as it evaluated: a member of an
+         *   iterated cycle, or a function that marks itself at run time.
          * - Named formulas where `isVolatile()` is true should not be used as
          *   navigation targets even if `isReferenceOnly()` returns true, since their
          *   resolved range may differ by context.
@@ -553,6 +575,14 @@ export declare namespace ICalculation {
          * The comment, or `null` if none has been set.
          */
         getComment(): string | null;
+        /**
+         * What the file said about this name beyond its value — macro bindings, Excel 4.0 and publishing
+         * flags — or `null` when it said nothing.
+         *
+         * @remarks
+         * Read-only: carried and written back as read. None of it changes how the name evaluates.
+         */
+        getFileAttributes(): Readonly<INamed.FileAttributes> | null;
         /**
          * If `true` the name is not shown in the UI. This does not affect resolution in formulas.
          */
@@ -1206,8 +1236,8 @@ export declare namespace ICalculation {
          */
         readonly Done: "done";
         /**
-         * Work is in hand: a pass running or owed, or answers the engine owes the model that have not
-         * landed.
+         * Work is in hand: a pass running or owed, answers the engine owes the model that have not
+         * landed, or work a consumer derives from the results ({@link ICalculation.waitUntil}).
          */
         readonly Calculating: "calculating";
         /**
@@ -1369,12 +1399,10 @@ export declare namespace ICalculation {
          */
         concurrentCalc?: boolean;
         /**
-         * Specifies whether concurrent calculations are allowed in manual calculation mode.
-         *
-         * @remarks
-         * If `true`, manual calculations can utilize multiple threads.
+         * How many threads concurrent calculation uses, when the count was set by hand rather than
+         * left to the number of processors. Kept from the file.
          */
-        concurrentManualCount?: boolean;
+        concurrentManualCount?: number;
         /**
          * Specifies whether the workbook forces a full recalculation of all formulas.
          *

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

@@ -92,6 +92,10 @@ export declare namespace INamedFormulasCollection {
          * @defaultValue false
          */
         hidden?: boolean;
+        /**
+         * Kept from a file and written back. See {@link INamed.FileAttributes}.
+         */
+        fileAttributes?: INamed.FileAttributes;
         /**
          * If `true`, redefine an existing name in the same scope instead of throwing.
          *

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

@@ -1,11 +1,10 @@
-import { IRange, Scalar, IFormulaContext } from '@sheetxl/primitives';
+import { IRange, Scalar } from '@sheetxl/primitives';
 import { ITransaction } from '../transaction';
 import { IListener } from '../listener';
 import { ICellRange, ICellRanges } from '../cellRange';
 import { NamedNodeInfo, ReferenceCoords } from './Types';
 import { INamed } from '../named';
 import { ITypes, AbstractCollection } from '../type';
-import { IContextContainer } from './state';
 import { FormulaHost } from './grid';
 import { Formula, IFormulaBlockView } from './formula';
 import { ICalculation } from './ICalculation';
@@ -38,9 +37,8 @@ export declare class NamedFormulaCollection extends AbstractCollection<ICalculat
      * exactly as they were read.
      */
     private _pendingJSON;
-    protected _container: IContextContainer | null;
+    protected _engine: NamedFormulaCollection.Engine | null;
     protected _bindSheet: ((scope: string) => string | null) | null;
-    protected _context: IFormulaContext | null;
     protected _ready: (() => Promise<ICalculation.Status>) | null;
     protected _getActiveCell: () => IRange.CellCoords | null;
     protected _createHost: ((gridId: string) => FormulaHost) | null;
@@ -63,6 +61,19 @@ export declare class NamedFormulaCollection extends AbstractCollection<ICalculat
      * store, never open, so nothing waits for the operation to land.
      */
     private _namesEmitter;
+    /**
+     * The items by their upper-cased name: what {@link getByName} and {@link _findSameIdentity}
+     * read instead of scanning the set.
+     *
+     * @remarks
+     * A derived cache, not state - the set stays keyed by id (see `State`). It answers for one
+     * store position: the commit, the operation open on it, and the set's own map. Anything that
+     * moves one of those without passing through {@link _indexItem} (a restore, a rollback, a
+     * commit closing) rebuilds it on the next read, once over the set; a write made here keeps it
+     * current in place, so a load of thousands of names costs each one a map lookup rather than a
+     * scan - which, over the names a legacy file carries, was the larger part of opening it.
+     */
+    private _nameIndex;
     constructor(options?: NamedFormulaCollection.ConstructorOptions);
     /**
      * Hydrates from `IWorkbook.JSON.names`. A malformed entry is warned and skipped rather than
@@ -75,10 +86,20 @@ export declare class NamedFormulaCollection extends AbstractCollection<ICalculat
      * be listed, and still evaluate to `#NAME?`.
      *
      * Not on `INamedFormulasCollection`: hydration belongs to whoever constructs the engine.
+     *
+     * A loaded name BINDS now and COMPILES on first use (see {@link NamedFormula._materialize}). A
+     * legacy file carries thousands of names nothing reads, and compiling one costs a grid of its own
+     * in the model's store, which every later commit copies. Until a reader binds the name, or the
+     * item is asked something only a compiled body answers, it answers from its state - and a loaded
+     * expression is already the file's sheet-qualified form, so the text is what a save writes back
+     * either way. A lambda-valued name is the exception: it is reached as a FUNCTION, by name, not
+     * through a symbol bind, so nothing would compile it ahead of the call.
      */
     hydrate(json: INamed.JSON[] | undefined): void;
     /** Set while {@link hydrate} runs, so the read-only refusal in {@link add} stands down. */
     private _hydrating;
+    /** The set's map as the running {@link hydrate} made it - see `add`. */
+    private _hydratingItems;
     /**
      * Serializes to `IWorkbook.JSON.names` form, sorted by scope+name so output is stable across
      * saves.
@@ -104,6 +125,52 @@ export declare class NamedFormulaCollection extends AbstractCollection<ICalculat
     toJSON(): INamed.JSON[] | null;
     /** {@inheritDoc INamedFormulasCollection.add} */
     add(options: INamedFormulasCollection.AddOptions): ICalculation.INamedFormula;
+    /**
+     * {@link add}, with the choice of WHEN the name compiles.
+     *
+     * @param lazy `true` for a loaded name: the item is recorded, indexed and announced, and its body
+     * compiles on first use (see {@link hydrate}). A name authored through the API compiles at once -
+     * the author expects `getRanges()` after `ready()`, and the wire is what qualifies a bare reference.
+     */
+    protected _add(options: INamedFormulasCollection.AddOptions, lazy: boolean): ICalculation.INamedFormula;
+    /**
+     * Compiles every loaded name whose text mentions the sheet, and has not compiled yet.
+     *
+     * @internal
+     *
+     * @remarks
+     * A compiled body follows the sheets it reads: a shift of their cells moves its references, and
+     * a rename re-images it from the sheet's id. Text follows nothing. So before a change of that kind
+     * lands, every name still answering from its text that could be reading the sheet is compiled,
+     * and the change reaches a body. A name that mentions no sheet at all - an error, an array
+     * constant, a number - is left as it is. The test is a spelling in the text, which is wider than
+     * a reference (a sheet called `A` is mentioned by nearly everything): a wide net compiles more
+     * than it needs to, a narrow one would leave a name pointing at the wrong cells.
+     */
+    _materializeMentioning(sheetName: string): void;
+    /**
+     * {@inheritDoc NamedCollection.Source.prepareRanges}
+     *
+     * @remarks
+     * Compiles, as one batch, the loaded names among `items` whose `getRanges()` would otherwise
+     * compile them one at a time: a name whose text is a literal or a plain address answers from its
+     * text and is left alone. Items of another source are not this collection's and are skipped.
+     */
+    prepareRanges(items: readonly INamed[]): void;
+    /**
+     * Compiles the loaded names among `items` that have not compiled, as ONE operation.
+     *
+     * @remarks
+     * Compiled one by one outside an operation, each name opens a commit of its own on the model
+     * store, so its grid lands under its own engine commit - and every engine commit copies the
+     * engine's registries, which hold an entry per sheet and per compiled name. A loop over the names
+     * of a legacy file (ten thousand of them) is then quadratic, in time and in memory held until the
+     * loop yields. Under one operation the names share one landing, one engine commit and one clone
+     * key, and the engine collects the grids they make into one write ({@link Engine.collectGrids}).
+     *
+     * @internal
+     */
+    _materializeMany(items: readonly NamedFormula[]): void;
     /**
      * A name has just been bound to the region it designates.
      *
@@ -204,6 +271,14 @@ export declare class NamedFormulaCollection extends AbstractCollection<ICalculat
      * Backs both the duplicate check in {@link add} and the collision check on rename.
      */
     protected _findSameIdentity(name: string, scopeId: string | null): NamedFormula | null;
+    /** The items named `upper` (already upper-cased), through {@link _nameIndex}. */
+    protected _itemsNamed(upper: string, state: State): readonly NamedFormula[];
+    /**
+     * A write made here - an item added, renamed or removed - keeps {@link _nameIndex} current
+     * rather than costing the next read a rebuild. The set's map is read again, as the write has
+     * just replaced it.
+     */
+    protected _indexItem(item: NamedFormula, removed: boolean): void;
     /**
      * Resolves a caller's `scope` input to the sheet's stableId.
      *
@@ -269,8 +344,8 @@ export declare namespace NamedFormulaCollection {
          */
         json?: INamed.JSON[];
         transactions?: ITransaction.IStore;
-        container?: IContextContainer;
-        context?: IFormulaContext;
+        /** What a name tells the engine it compiles into, and reads back from it. */
+        engine?: NamedFormulaCollection.Engine;
         ready?: () => Promise<ICalculation.Status>;
         getRange: (address: ICellRange.Address) => ICellRange;
         /** Resolves an address to ranges. Backs {@link ICalculation.INamedFormula.getReferences}. */
@@ -286,7 +361,7 @@ export declare namespace NamedFormulaCollection {
         resolveSheetScope?: (stableId: string) => string | null;
         /**
          * A sheet's name or stable id to its stable id, as the model holds its sheets now - not as the
-         * engine's replica has been told. Falls back to the container's symbols when absent.
+         * engine's replica has been told. Without it, a scope binds to nothing.
          */
         bindSheet?: (scope: string) => string | null;
         /** Backs {@link INamed.isReadOnly} on each item. Defaults to not read-only. */
@@ -310,12 +385,34 @@ export declare namespace NamedFormulaCollection {
          */
         isEngineReady?: () => boolean;
     }
+    /**
+     * What a name asks of the engine it compiles into. Held from before the engine starts: each call
+     * reaches the engine once there is one, and waits for it until then.
+     */
+    interface Engine {
+        /** The name's resolution moved: the formulas that read it are out of date. */
+        invalidateNamed(nameId: string): void;
+        /** The name's body changed or went: the formulas that read it compile again. */
+        recompileNamed(nameId: string): void;
+        /** The root of the name's compiled body, or `null` while it has none. */
+        getBodyNode(nameId: string): ICalculation.FormulaNode | null;
+        /**
+         * Runs `batch` with the grids it makes collected into one write of the engine's registry, under
+         * one clone key - see `CalcBackend._collectingGrids`. Without it each grid is its own write,
+         * each copying the registry: a burst of a thousand compiles costs a thousand copies of a
+         * thousand entries, all of them reachable until the burst yields.
+         */
+        collectGrids?<R>(batch: () => R): R;
+    }
 }
 interface NamedFormulaWireOptions {
-    container: IContextContainer;
-    context: IFormulaContext;
-    /** Holds the body. `null` for a name that has no grid (no proxy id was bound for it). */
-    host: FormulaHost | null;
+    engine: NamedFormulaCollection.Engine;
+    /**
+     * Makes the host that holds the body - the same one again for the same name, see
+     * `NamedFormulaCollection.ConstructorOptions.createHost`. `null` for a name that has no grid (no
+     * proxy id was bound for it).
+     */
+    createHost: (() => FormulaHost) | null;
     ready: () => Promise<ICalculation.Status>;
     /** Returns the scope's sheet gridId (for reference resolution). Resolved after ready(). */
     getScopeGridId: () => string | null;
@@ -402,8 +499,15 @@ declare class NamedFormula extends Formula implements ICalculation.INamedFormula
     private _seenBlock;
     private _seenDeleted;
     private _seenExpression;
-    /** Holds the body; `null` for a name without a grid. See {@link _block}. */
-    private readonly _host;
+    /**
+     * Holds the body; `null` for a name without a grid, and for a loaded name nothing has read yet.
+     * See {@link _block} and {@link _materialize}.
+     */
+    private _host;
+    /** A loaded name, compiled on first use - see `NamedFormulaCollection.hydrate`. */
+    private readonly _lazy;
+    /** A {@link _materializeLater} is queued and has not run. */
+    private _materializeQueued;
     /**
      * The compiled body, read LIVE from this name's host on every access.
      *
@@ -425,7 +529,7 @@ declare class NamedFormula extends Formula implements ICalculation.INamedFormula
      * accessor below already has a fallback for.
      */
     protected get _block(): IFormulaBlockView;
-    constructor(coords: IRange.CellCoords | null, options: INamedFormulasCollection.AddOptions, deleteFromCollection: () => void, wire: NamedFormulaWireOptions | null, gridId?: string | null, checkRename?: (nextName: string) => void, transactions?: ITransaction.IStore, isReadOnly?: (() => boolean) | null, resolveSheetScope?: (stableId: string) => string | null, notifyCollection?: () => void, notifyNameWritten?: () => void);
+    constructor(coords: IRange.CellCoords | null, options: INamedFormulasCollection.AddOptions, deleteFromCollection: () => void, wire: NamedFormulaWireOptions | null, gridId?: string | null, checkRename?: (nextName: string) => void, transactions?: ITransaction.IStore, isReadOnly?: (() => boolean) | null, resolveSheetScope?: (stableId: string) => string | null, notifyCollection?: () => void, notifyNameWritten?: () => void, lazy?: boolean);
     /**
      * Writes this name's body, which binds it to the region its expression designates once the
      * engine answers.
@@ -437,6 +541,66 @@ declare class NamedFormula extends Formula implements ICalculation.INamedFormula
      * brings describes a set that already contains it. `getRanges()` answers once the engine has.
      */
     _wireNow(): void;
+    /**
+     * A loaded name that answers from its text: no host, or one whose grid a restore has left
+     * without state (see `CalcGrid._revive`), so no compiled body.
+     * @internal
+     */
+    _isUnmaterialized(): boolean;
+    /**
+     * Gives a loaded name what a name authored through the API has from the start: a host, and the
+     * body compiled into it. The first use of the name calls this - a reader binding it, or an ask
+     * only the compiled body answers (`getRanges`, the graph, `evaluate`, a redefinition). Nothing
+     * more than bookkeeping for a name that has it already.
+     *
+     * @internal
+     *
+     * @remarks
+     * Folded into the current commit: the host writes as `FormulaHost._amendCurrent` does. So an undo
+     * past the edit whose reader compiled the name leaves the item without a body in its grid - the
+     * unmaterialized state again, with the host object still held - and the next use writes the body
+     * once more rather than assuming it is there.
+     */
+    _materialize(): void;
+    /**
+     * {@link _materialize} at the next safe point: for a caller inside the engine's own work (the
+     * compile of a formula that mentions this name), where a body cannot be written.
+     * @internal
+     */
+    _materializeLater(): void;
+    /**
+     * For a loaded name that has not compiled: its text as a list of sheet-qualified addresses
+     * (`Sheet1!$A$1:$B$2`, `'Q1'!$A:$A,'Q2'!$A:$A`), or `null` when the text is anything else.
+     *
+     * @remarks
+     * Read with the address grammar the API's `getRanges(address)` reads - a cell, a range, an entire
+     * row or column, a comma list of those - and nothing wider. A text that is a function, a name, an
+     * error, an array constant, an intersection or a bare reference does not parse, and only the
+     * compiler can say what it designates; the caller compiles then. What does parse is what the
+     * compiler would have called reference-only and resolved to these same cells, so the name can
+     * answer {@link getRanges} without a grid of its own - the Name Box asks every name what it
+     * designates, and a file's thousands of names must not all compile for the question.
+     */
+    private _parseAddressText;
+    /**
+     * For a loaded name that has not compiled: whether its text is a literal - a number, a string, a
+     * boolean, an error or an array constant - and so designates no cells whatever the compiler would
+     * make of it.
+     *
+     * @remarks
+     * The names a decades-old model carries by the thousand are exactly these (macro-sheet
+     * constants, dead `#REF!`s), and a report that asks every name what it covers must not compile
+     * them for an answer that is `null` by the shape of the text. Strict on purpose: `#REF!$A$1` or
+     * `{1,2}+A1` is not matched and compiles, where the compiler's answer is the only correct one.
+     */
+    private _isLiteralText;
+    /**
+     * Whether `getRanges()` on this name would compile it: a loaded name that has not compiled and
+     * whose text is neither a literal nor a plain address list. What a batch compiles ahead of a loop
+     * that asks each name in turn ({@link NamedFormulaCollection.prepareRanges}).
+     * @internal
+     */
+    _compilesForRanges(): boolean;
     /** Records what the readers have been reconciled with — see `_seenBlock`. */
     private _recordSeen;
     /**
@@ -523,6 +687,8 @@ declare class NamedFormula extends Formula implements ICalculation.INamedFormula
     setExpression(expression: string, options?: ITransaction.OperationOptions): this;
     /** {@inheritDoc INamed.getComment} */
     getComment(): string | null;
+    /** {@inheritDoc ICalculation.INamedFormula.getFileAttributes} */
+    getFileAttributes(): Readonly<INamed.FileAttributes> | null;
     /** {@inheritDoc INamed.setComment} */
     setComment(comment: string | null, options?: ITransaction.OperationOptions): this;
     /** {@inheritDoc INamed.isHidden} */
@@ -615,8 +781,14 @@ declare class NamedFormula extends Formula implements ICalculation.INamedFormula
      *    Consumers requery once the engine has started.
      * 3. **Wiring bailed.** `_doWireCore` returns early when the scope sheet cannot be resolved,
      *    which leaves the item permanently unwired rather than transiently.
+     *
+     * A loaded name that has not compiled answers from its text when the text is a plain address
+     * list (see {@link _parseAddressText}) or a literal (see {@link _isLiteralText}, case 1 without
+     * the compile); any other text compiles it, and the answer is case 2.
      */
     getRanges(): ICellRanges | null;
+    /** {@inheritDoc ICalculation.IFormula.getReferences} */
+    getReferences(): ICellRanges | null;
     /** {@inheritDoc ICalculation.INamedFormula.getDirectDependents} */
     getDirectDependents(): Promise<ICellRanges | null>;
     /** {@inheritDoc ICalculation.INamedFormula.getDependents} */
@@ -678,7 +850,10 @@ declare class NamedFormula extends Formula implements ICalculation.INamedFormula
     _getBodyNode(): ICalculation.FormulaNode | null;
     /** Pre-wire fallback: return empty array before block is compiled. */
     getTokens(evalIndex?: number): readonly ICalculation.FormulaToken[];
-    /** Pre-wire fallback: return false before block is compiled. */
+    /**
+     * Pre-wire fallback: return false before block is compiled. A loaded name that has not compiled
+     * answers as {@link getRanges} does, from its text.
+     */
     isReferenceOnly(): boolean;
     /**
      * Anchored at the virtual grid's origin. `this._coords` is the *defining* cell (the active cell

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

@@ -0,0 +1,9 @@
+/** The formula toolkit's code (`./toolkit`). */
+export type FormulaToolkitModule = typeof import('./toolkit');
+/**
+ * The one loader of the formula toolkit, shared by `FormulaText`, `parseFormulaLiteral` and
+ * `FunctionDeclarations`: each answers from {@link FormulaToolkit.peek} and gives the answer it
+ * gives for text it cannot read until the toolkit is loaded (DESIGN-CALC-SERVICE §13.25).
+ */
+export declare const FormulaToolkit: import('@sheetxl/utils').LazyModule<typeof import("./toolkit")>;
+//# sourceMappingURL=_FormulaToolkit.d.ts.map

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

@@ -0,0 +1,60 @@
+import { FormulaError, IRange } from '@sheetxl/primitives';
+import { ITable } from '../table';
+import { ASTNode } from './compiler/ASTTypes';
+import { StructuredReference } from './Types';
+/**
+ * What a structured reference resolves against: a live table, or a snapshot of one taken before it
+ * was removed ({@link snapshotTableExtent}).
+ */
+export interface TableExtent {
+    getRange(): {
+        getCoords(): IRange.Coords;
+    };
+    getDataRange(): {
+        getCoords(): IRange.Coords;
+    };
+    getHeaderRowRange(): {
+        getCoords(): IRange.Coords;
+    };
+    getTotalRowRange(): {
+        getCoords(): IRange.Coords;
+    };
+    isShowHeaders(): boolean;
+    isShowTotals(): boolean;
+    getColumnById(id: string): {
+        getIndex(): number;
+    } | null;
+    getWorksheet(): {
+        getId(): string;
+    } | null | undefined;
+}
+/**
+ * The column a structured reference's column id (`_<tableStableId>:<rawColumnId>`) names in `table`,
+ * or `null` when the table no longer has it.
+ */
+export declare function tableColumnOf(table: TableExtent, columnId: string): {
+    getIndex(): number;
+} | null;
+/**
+ * Whether a column `structuredReference` names is gone from `table`. Excel then writes `#REF!` in
+ * place of the whole reference, for an endpoint of a column range as much as for a lone column; a
+ * column deleted strictly between the endpoints leaves the reference as it was.
+ */
+export declare function namesDeadColumn(structuredReference: StructuredReference, table: TableExtent): boolean;
+/**
+ * The cells `structuredReference` designates in `table`, for a formula in `row`.
+ */
+export declare function structuredReferenceCoords(structuredReference: StructuredReference, row: number, table: TableExtent): IRange.FixableCoords | FormulaError.Known;
+/**
+ * `table`'s extent as plain data, so its references can still be resolved after it is removed.
+ */
+export declare function snapshotTableExtent(table: ITable): TableExtent;
+/**
+ * The absolute address a structured reference designates, as a reference node: `Sheet1!$A$2:$C$4`.
+ *
+ * @remarks
+ * A this-row reference keeps its row relative (`Sheet1!$A2`), so every cell of a block still reads
+ * its own row.
+ */
+export declare function structuredReferenceAddress(reference: StructuredReference, extent: TableExtent): ASTNode;
+//# sourceMappingURL=_TableExtent.d.ts.map

package/types/src/calculation/compiler/CompilerUtils.d.ts

@@ -154,6 +154,23 @@ export declare function annotateImplicitIntersect(root: ASTNode, getFunction: ((
  * carries it harmlessly: nothing reads it unless the block evaluating the formula demands it.
  */
 export declare function annotateFirstCell(root: ASTNode, getFunction: ((name: string) => IFunction | null) | null | undefined): void;
+/**
+ * The formula with every POSITION TEST replaced by `TRUE` and by `FALSE`, in every combination:
+ * what a block's blank-region representative is re-evaluated as to show its answer does not
+ * depend on which cell is asking (`IFormulaBlock.getPositionVariants`).
+ *
+ * @remarks
+ * A position test is a maximal subtree that reads the position (`ROW()`, `COLUMN()`) and is
+ * BOOLEAN at every cell, never an error: a comparison of position arithmetic with a literal
+ * (`ROW()>1`, `MOD(ROW(),2)=0`), `ISODD`/`ISEVEN` of it, and `NOT`/`AND`/`OR`/`XOR` of tests. Its
+ * value at any cell is `TRUE` or `FALSE`, so when the formula answers alike for every combination,
+ * the position cannot change the answer.
+ *
+ * `null` — nothing to vary — when the formula has no position test, more than
+ * {@link MAX_POSITION_TESTS}, a lazy argument (an `IF` arm a variant takes could read what the
+ * formula itself never did), or a `LET`/`LAMBDA` binding.
+ */
+export declare function positionVariants(root: ASTNode, getFunction: ((name: string) => IFunction | null) | null | undefined): ASTNode[] | null;
 export declare function compileAST(runtime: IRuntime, symbols: ISymbolRegistry | undefined, original: ASTNode, preserveExpression?: boolean, error?: ParseError | null, getFunction?: ((name: string) => IFunction | null) | null): CompiledFormula;
 /**
  * Convert a chevrotain error into a {@link FormulaError.Parse}.

package/types/src/calculation/compiler/ParserUtils.d.ts

@@ -50,6 +50,12 @@ export declare function createTableReference(value: string, inputs: any[]): ASTN
  * word → canonical. Display re-imaging (`tokensToString`) re-localizes for a localized target.
  */
 export declare function createTableSpecifier(image: string, locale?: CompilerLocale): ASTNode;
+/** The canonical specifier words a structured reference accepts — the text inside `[#…]`, minus the `#`. */
+export declare const CANONICAL_SPECIFIER_WORDS: readonly string[];
+/**
+ * The section (`StructuredReference.spec`) a structured reference's specifiers designate.
+ */
+export declare function structuredReferenceSpec(all: boolean, headers: boolean, data: boolean, totals: boolean): number;
 /**
  * A column name as a structured reference spells it: a `'` before each `[`, `]`, `#` and `'`,
  * which is Excel's escape inside a column specifier. Without it a name holding a bracket cannot be
@@ -65,6 +71,16 @@ export declare function escapeColumnName(name: string): string;
  * column (`[Q#1]` and `[Q'#1]` are both `Q#1`).
  */
 export declare function unescapeColumnName(image: string): string;
+/**
+ * The table reference starting at `startOffset` — `Table1[Col]`, `[1]!Table1[Col]` — as a one-element
+ * match, or `null`. The formula lexer's matcher for the token, and the address parser's.
+ */
+export declare function matchTableReference(text: string, startOffset: number): [string] | null;
+/**
+ * The outermost bracketed string starting at `startOffset` — `[Workbook]`, an unqualified `[Col]` —
+ * as a one-element match, or `null`.
+ */
+export declare function matchBracketedString(text: string, startOffset: number): [string] | null;
 export declare function createTableColumn(image: string): ASTNode;
 export declare function createInfix(operator: string, left: ASTNode, right: ASTNode, isReference?: boolean): ASTNode;
 export declare function createPostfix(operator: string, input: ASTNode | null | undefined, isReference?: boolean): ASTNode;

package/types/src/calculation/compiler/Types.d.ts

@@ -288,7 +288,7 @@ export interface CompiledFormula {
      * expression callee, or a function the registry does not know. `TODAY()` and `NOW()` are
      * accepted: volatile, but one value per pass. So are `RAND()` and every function taking a
      * reference (`ROW()`, `OFFSET`, `FORMULATEXT`, the `SUMIF` family): whether the body reads a
-     * position (or draws) is a per-cell READ (`CalcScope.perCellRead`) that the pass sees when it
+     * position (or draws) is a per-cell READ (`CalcScope.perCellRead`, `positionRead`) that the pass sees when it
      * evaluates the representative, not a property of the text. The block adds its own gates (a
      * precedent template, not array-entered) and the pass its run-time ones (no dynamic read, no
      * per-cell read, a scalar result); this is only the half that can be known from the text.