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

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

@@ -1,12 +1,11 @@
-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 { INamed, INamedCollection } from '../named';
 import { ITypes, AbstractCollection } from '../type';
-import { IContextContainer } from './state';
-import { FormulaHost } from './grid';
+import { FormulaHost, ICalcGrid } from './grid';
 import { Formula, IFormulaBlockView } from './formula';
 import { ICalculation } from './ICalculation';
 import { INamedFormulasCollection } from './INamedFormulasCollection';
@@ -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,7 +61,22 @@ 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);
+    /** Loaded names some write has given a state of their own - see {@link NamedFormula._writeNamedState}. */
+    private _written;
     /**
      * Hydrates from `IWorkbook.JSON.names`. A malformed entry is warned and skipped rather than
      * failing the whole load — one bad name must not cost the workbook every other name.
@@ -75,10 +88,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 +127,73 @@ 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;
+    /**
+     * {@inheritDoc NamedCollection.Source.removeUnused}
+     *
+     * @remarks
+     * A name that has not compiled has no compiled reader - a formula that reads a name binds it - so
+     * only the compiled ones are asked of the engine. What the engine cannot see is a reader that has
+     * not compiled either: a kept name whose definition spells a candidate keeps it, and whatever that
+     * one spells in turn. By spelling, so lenient - a name wrongly kept costs nothing, one wrongly
+     * removed breaks the name that read it.
+     *
+     * A LAMBDA is called, not bound, so it is never removed; nor is a built-in name (`_xlnm.`),
+     * which the sheet reads rather than any formula.
+     */
+    removeUnused(options: INamedCollection.RemoveUnusedOptions & {
+        scope?: string;
+    }): Promise<number>;
+    /**
+     * Deletes `items` as ONE operation: each item's own writes, then a single rewrite of the set.
+     * Deleted one at a time, each removal copies the set, and a legacy file's names are thousands.
+     */
+    protected _removeMany(items: readonly NamedFormula[]): 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 +294,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.
      *
@@ -231,6 +329,8 @@ export declare class NamedFormulaCollection extends AbstractCollection<ICalculat
      */
     _addNamesWrittenListener(listeners: IListener.Callbacks<NamedFormulaCollection, NamedFormulaCollection.NamesWrittenEvents>): IListener.Remove;
     protected _notifyNamesWritten(item: NamedFormula, removed: boolean): void;
+    /** {@link _notifyNamesWritten} for a batch, told as one. */
+    protected _notifyManyWritten(items: readonly NamedFormula[], removed: boolean): void;
     /**
      * Every name as {@link _addNamesWrittenListener} tells one: what a listener starts from.
      * @internal
@@ -256,7 +356,7 @@ export declare namespace NamedFormulaCollection {
     }
     /** See {@link NamedFormulaCollection._addNamesWrittenListener}. */
     interface NamesWrittenEvents {
-        onNamesWritten?(source: NamedFormulaCollection, written: NamesWritten): void;
+        onNamesWritten?(source: NamedFormulaCollection, written: readonly NamesWritten[]): void;
     }
     interface ConstructorOptions {
         /**
@@ -269,8 +369,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 +386,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 +410,40 @@ 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;
+        /**
+         * The name's precedents or dependents, cells in calc currency and names, as the engine walks
+         * them - asked by the name's id, so a name that has not compiled is asked without compiling it.
+         * Nothing while the engine is `Off`.
+         */
+        getNameGraph(nameId: string, kind: 'precedents' | 'dependents', direct: boolean): Promise<ICalcGrid.GraphNeighbors>;
+        /**
+         * 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;
@@ -360,7 +488,10 @@ interface NamedFormulaWireOptions {
  * supplied is implemented here against the transaction store the item already holds.
  */
 declare class NamedFormula extends Formula implements ICalculation.INamedFormula, INamed<string> {
-    /** Transactional state — see the field docs on `_transactions`. */
+    /**
+     * Transactional state — see the field docs on `_transactions`. A loaded name nothing has written
+     * reads what the file said, as does one an undo took back past its first write.
+     */
     private _getNamedState;
     private readonly _id;
     /**
@@ -368,7 +499,19 @@ declare class NamedFormula extends Formula implements ICalculation.INamedFormula
      * mutation is undoable.
      */
     private readonly _transactions;
-    private readonly _stateId;
+    /**
+     * `null` for a loaded name until its first write: every commit copies the store's snapshot, and a
+     * legacy file's tens of thousands of names were nearly all of it. See {@link _writeNamedState}.
+     */
+    private _stateId;
+    /** What a loaded name's file said: its state until written, and again when undone past that write. */
+    private readonly _loaded;
+    /** Tells the collection a loaded name has a state now, so it hears an undo that removes it. */
+    private readonly _noteWritten;
+    /** Whether the collection lists this item now — a loaded name's deletion when it has no state. */
+    private readonly _isListed;
+    /** {@link _loaded}, deleted. */
+    private _loadedDeleted;
     private readonly _deleteFromCollection;
     private readonly _wire;
     /** Refuses a rename that would collide with a sibling — see {@link setName}. */
@@ -387,6 +530,11 @@ declare class NamedFormula extends Formula implements ICalculation.INamedFormula
     private readonly _notifyCollection;
     /** The collection's {@link NamedFormulaCollection._addNamesWrittenListener}, for a rename. */
     private readonly _notifyNameWritten;
+    /**
+     * Made on the first `addListeners`. Every emitter on the shared store is told of every commit, and
+     * a legacy file's tens of thousands of names nothing listens to made each commit pay for all of
+     * them. Until it exists there is nobody to notify.
+     */
     private _emitter;
     private _transactionsRemoveListener;
     private _closed;
@@ -402,8 +550,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.
      *
@@ -424,8 +579,48 @@ declare class NamedFormula extends Formula implements ICalculation.INamedFormula
      * `undefined` (no grid, or nothing compiled at its origin) is the pre-wire state, which every
      * accessor below already has a fallback for.
      */
+    /** Hears this name's own state: made with the item, or by a loaded name's first write. */
+    private _listenToState;
+    /**
+     * Whether an undo has taken this loaded name back past its first write: it has a state id, and
+     * the snapshot the store is at does not hold it.
+     * @internal
+     */
+    _isStateAbsent(): boolean;
+    /**
+     * An undo/redo repointed the store.
+     * @internal
+     */
+    _onRestoreOrRevert(): void;
+    /**
+     * {@link delete}'s own writes, inside an operation the collection holds — its removal from the
+     * set is the caller's, made once for many.
+     *
+     * @remarks
+     * A loaded name nothing has written writes no state: not being listed is its deletion (see
+     * {@link _getNamedState}), so deleting a legacy file's thousands of names adds nothing to every
+     * later commit's snapshot.
+     * @internal
+     */
+    _deleteWithin(trans: ITransaction): void;
+    /**
+     * Adds every identifier this name's definition spells, lowercased, to `into` — nothing for a
+     * literal, which reads no name.
+     * @internal
+     */
+    _addSpelledNames(into: Set<string>): void;
+    /**
+     * Writes this item's state in `trans`.
+     *
+     * @remarks
+     * A loaded name has no state until this runs: it is made here, inside the write, so the commit
+     * before the write has none and an undo past it reads {@link _loaded} again. Whenever the
+     * snapshot holds no state - the first write, or one after such an undo - the write carries the
+     * whole of it, since an update merges onto what the store holds.
+     */
+    private _writeNamedState;
     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, noteWritten?: () => void, isListed?: () => boolean);
     /**
      * Writes this name's body, which binds it to the region its expression designates once the
      * engine answers.
@@ -437,6 +632,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 +778,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 +872,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} */
@@ -639,10 +902,15 @@ declare class NamedFormula extends Formula implements ICalculation.INamedFormula
     getPrecedents(): Promise<ICellRanges | null>;
     /**
      * The precedents or dependents of this NAME — cells and names, ONE answer — as the engine walks
-     * them over its body's grid (see `CalcGridBackend._nameGraphNow` for the walk: the symbol edges
-     * names ride on, and the cell graph between them).
+     * them (see `CalcBackend._nameGraphNow` for the walk: the symbol edges names ride on, and the
+     * cell graph between them).
      *
      * @remarks
+     * Only the precedents read the body, so only they compile it, and a literal has none. The
+     * dependents are asked by id and never compile: a formula that reads this name bound it when it
+     * compiled, so a name still waiting for its first use has no compiled reader to find — and a
+     * report asking every name of a legacy file must not compile thousands of them to learn that.
+     *
      * What is left here is the translation out of calc currency: a cell on no addressable sheet
      * drops, and the rest are reduced to regions, not a list of blocks - two formulas naming this
      * name in adjacent cells are one range, and the deep walk can reach one block down two paths.
@@ -678,7 +946,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/_CloneBoundary.d.ts

@@ -1,6 +1,6 @@
 /**
  * The clone boundary: a test mode that treats the model/engine crossing as if it were a wire
- * (DESIGN-CALC-SERVICE §11, goal G1, plan step 6).
+ * (DESIGN-CALC-SERVICE §11, goal G1).
  *
  * @remarks
  * Every request into a grid and every {@link ICalcGrid.Results} out of one passes through here.

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/ASTTypes.d.ts

@@ -235,10 +235,14 @@ export interface NamedNode extends ASTNode<typeof TokenType.Named, NamedReferenc
 }
 export interface FunctionNode extends ASTNode<typeof TokenType.Function, any> {
     /**
-     * Re use this as a cache for built-in static functions.
-     *
+     * The function this call resolved to.
      */
     cacheFn?: IFunction;
+    /**
+     * The registry stamp `cacheFn` resolved under, for a custom function; `undefined` for a built-in,
+     * which never changes.
+     */
+    cacheFnStamp?: number;
 }
 export type ParenNode = ASTNode<typeof TokenType.Paren>;
 /**

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

@@ -260,6 +260,14 @@ export interface CompiledFormula {
      * `_xlfn.`-prefixed one both answer correctly.
      */
     hasTotals: boolean;
+    /**
+     * Whether the formula calls `TABLE`, the what-if data table, anywhere in its tree.
+     *
+     * @remarks
+     * What a reactive pass under `AutomaticExceptTables` skips (DESIGN-DATA-TABLES §4.4). Resolved
+     * through `getFunction`, like {@link hasTotals}.
+     */
+    hasDataTable: boolean;
     /**
      * Whether the formula names a VOLATILE function anywhere in its tree — the cell recalculates on
      * every pass, whether or not that call is ever reached.
@@ -288,7 +296,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.