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

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.

package/types/src/calculation/engine/CalcBackend.d.ts

@@ -2,6 +2,7 @@ import { IRange, IFormulaContext, IRuntime, Scalar } from '@sheetxl/primitives';
 import { FunctionProvider } from '@sheetxl/scripting';
 import { AbstractModel, IModel } from '../../model';
 import { ITransaction } from '../../transaction';
+import { IRichDataKind } from '../../richData/IRichDataKind';
 import { ISpatialMap, ISpatialQuery, ISpatialMap3D, ISparseGrid } from '../../collections';
 import { IExternalBookCollection } from '../../externalBook';
 import { ICalculation } from '../ICalculation';
@@ -11,9 +12,12 @@ import { IFormulaCompiler } from '../compiler';
 import { FormulaBlockResolvers, IFormulaBlock, FormulaImager } from '../formula';
 import { CalculationContext } from '../state/CalculationContext';
 import { IContextContainer, CalcNode, CalcScope } from '../state';
+import { DeferredCalls, DeferredCall } from '../state/DeferredCalls';
+import { AsyncValue } from '../../primitives/AsyncValue';
 import { PrecedentSpatialValue, PrecedentKind } from '../spatial';
 import { FormulaSpatialValue } from '../spatial/FormulaSpatialValue';
 import { CalcExecutor } from '../executor/CalcExecutor';
+import { WhatIfTable } from '../executor/_WhatIf';
 import { CalcGridBackend } from '../grid/CalcGridBackend';
 import { ICalcGrid, FormulaHost } from '../grid';
 import { CalcRequest, CalcResponse, CalcGridSpec, TableSymbols, NameSymbols } from '../grid/_CalcRequest';
@@ -34,6 +38,7 @@ import { ISymbolRegistry } from '../symbol';
 export declare class CalcBackend extends AbstractModel<CalcBackend.State> implements IContextContainer {
     protected _callbacks: CalcBackend.Callbacks;
     protected _runtime: IRuntime;
+    protected _richData: IRichDataKind.Context;
     protected _symbols: ISymbolRegistry;
     protected _resolvers: FormulaBlockResolvers;
     protected _getSheetIndex: ((sheetName?: string) => number) | null;
@@ -52,6 +57,7 @@ export declare class CalcBackend extends AbstractModel<CalcBackend.State> implem
     protected _epochSeenPrecedents: ISpatialMap3D<PrecedentSpatialValue> | null;
     protected _epochSeenDynamics: Map<FormulaSpatialValue, ISpatialMap.Entry<PrecedentSpatialValue>[]> | null;
     protected _volatiles: Set<CalcNode>;
+    protected _deferred: DeferredCalls;
     protected _calculatedCommitId: string | null;
     protected _calculatedEngineId: string | null;
     /** The engine holds grids: from a start's boot until a stop. */
@@ -94,8 +100,47 @@ export declare class CalcBackend extends AbstractModel<CalcBackend.State> implem
     getContext(): CalculationContext & IFormulaContext;
     /** {@inheritDoc IContextContainer.getRuntime} */
     getRuntime(): IRuntime;
+    /** {@inheritDoc IContextContainer.getRichDataContext} */
+    getRichDataContext(): IRichDataKind.Context;
     /** {@inheritDoc IContextContainer.getScope} */
     getScope(): CalcScope;
+    /** {@inheritDoc IContextContainer.getDeferred} */
+    getDeferred(): DeferredCalls;
+    /**
+     * The settle pass (DESIGN-ASYNC §4.5): a change with no write, for every call whose latest
+     * moved since the last one.
+     *
+     * @remarks
+     * A cell whose formula is its one call reads the latest through its holder: the model is told
+     * the cell's value as it reads now, its pending status clears, and its dependents are marked
+     * dirty — never the cell itself. A cell whose formula is more than its call is marked dirty
+     * itself, and its next evaluation serves each site its call. One settle pass follows, seeded from
+     * what was marked and nothing else, and vends the repaints with its results.
+     *
+     * A call whose owner's cell no longer names it — the cell was edited, or its version is not the
+     * current one — settles into that version's holder and nothing here.
+     */
+    protected _settle(): void;
+    /**
+     * Cancels every call `cover` covers (`ICalculation.cancelAsync`, DESIGN-ASYNC §4.6): each is
+     * closed and its `onCancel` runs. Each owner whose cell still names its call re-evaluates in a
+     * settle pass: served the closed call, it shows what it did and is no longer pending.
+     *
+     * @returns The settle pass, or `null` when nothing was cancelled.
+     */
+    cancelAsync(cover: true | string | IRange.Coords): Promise<ICalculation.Status> | null;
+    /**
+     * A call's result as a cell can hold it (`DeferredCalls.Normalize`): an array becomes a range
+     * as a body's array return does, a one-cell range its scalar, a jagged array `#VALUE!`.
+     */
+    protected _normalizeResult(value: unknown): unknown;
+    /**
+     * The holder at a cell: the engine grid's value there, else the entry of the spill anchored
+     * there (an anchor cell holds its first element; the spill's entry carries the holder). `null`
+     * for a cell with neither.
+     */
+    protected _holderAt(gridId: string, row: number, column: number): AsyncValue<DeferredCall> | null;
+    protected _settleNow(): void;
     /** {@inheritDoc IContextContainer.createFormulaBlock} */
     createFormulaBlock(gridId: string, context: IFormulaContext, expression: string, rowIndex: number, colIndex: number, editing?: ICalculation.FormulaTarget, legacyIntersect?: boolean): IFormulaBlock;
     /** {@inheritDoc IContextContainer.getSymbols} */
@@ -129,6 +174,8 @@ export declare class CalcBackend extends AbstractModel<CalcBackend.State> implem
     setDynamics(map: Map<FormulaSpatialValue, ISpatialMap.Entry<PrecedentSpatialValue>[]>): void;
     /** {@inheritDoc IContextContainer.addDynamicPrecedent} */
     addDynamicPrecedent(node: CalcNode, range: IRange.Coords | undefined, kind: PrecedentKind): void;
+    /** {@inheritDoc IContextContainer.evaluateWhatIf} */
+    evaluateWhatIf(table: WhatIfTable): Scalar[][];
     /** {@inheritDoc IContextContainer.getVolatiles} */
     getVolatiles(): Set<CalcNode>;
     /** {@inheritDoc IContextContainer.isLegacyIntersect} */
@@ -234,6 +281,33 @@ export declare class CalcBackend extends AbstractModel<CalcBackend.State> implem
      * second hop) and the diamond guard both.
      */
     getNamedDependentNames(nameId: string): ReadonlySet<string>;
+    /**
+     * What a `nameGraph` request answers: a defined name's precedents or dependents, cells scoped by
+     * grid and names as nodes - ONE answer, as a cell's is.
+     *
+     * @remarks
+     * The PRECEDENTS: the cell half is the ordinary precedent graph of the name's grid - a body is a
+     * real formula there, and its references registered precedent ranges like any cell's. The name
+     * half is the body's `getNamedIds`: apply-at-eval means a name the body reads has no precedent
+     * edge, so the symbol list is the only carrier - one hop for `direct`, the downward closure
+     * (cycle-guarded) for the deep form, each member contributing its own grid's cell walk. The deep
+     * form does not take the symbol hop from UPSTREAM CELLS (`X = A1*2`, `A1 = SomeName`: `A1` is
+     * listed and `SomeName`'s inputs are not) - that hop is `A1`'s, one step of a tree walk. A name
+     * with no grid (it has not compiled) has nothing to walk.
+     *
+     * The DEPENDENTS: two graphs meet, and the walk changes vehicles between them. The symbol edge -
+     * which formulas mention this name - is not in the precedent spatial at all; it is the symbol
+     * index ({@link getNamedDependents}), keyed by the name's id, so the name's own grid is never
+     * read: a name that has not compiled is answered as one that has. The cell edge is the precedent
+     * graph, which carries everything downstream of those blocks: `direct` is one hop of the first;
+     * the deep form takes it, then hands each landing block to its grid. A block on a watch's grid
+     * (a conditional format, a validation, a chart) is the cells it is attached to, on the sheet the
+     * watch shadows. A block on any other grid that is no sheet is another NAME reading this one: a
+     * node, and the deep walk passes THROUGH it on the symbol closure (`getNamedDependentNames`), or
+     * `Base`'s dependents would stop at `Plus1`. This name is listed only when a true cycle leads
+     * back to it.
+     */
+    protected _nameGraphNow(nameId: string, kind: 'precedents' | 'dependents', direct: boolean): ICalcGrid.GraphNeighbors;
     /** A grid of the backend's, registered. */
     createBackendGrid(options?: CalcGridBackend.ConstructorOptions): CalcGridBackend;
     /**
@@ -267,7 +341,7 @@ export declare class CalcBackend extends AbstractModel<CalcBackend.State> implem
     getExternalNameByScope(name: string, scopeId: string): ExternalNamedItem | null;
     /**
      * Applies one request from the channel: the service's own (`sheets`, `tables`, `names`,
-     * `rollback`, `create`) here, a grid's on its grid. A request for a grid the engine does not hold
+     * `nameGraph`, `rollback`, `create`) here, a grid's on its grid. A request for a grid the engine does not hold
      * is answered with nothing.
      *
      * @param held The request was held while the engine came up: it lands under the engine's
@@ -649,9 +723,6 @@ export declare class CalcBackend extends AbstractModel<CalcBackend.State> implem
     get [Symbol.toStringTag](): string;
     toString(): string;
 }
-/**
- * Interfaces for creating a {@link CalcBackend}.
- */
 export declare namespace CalcBackend {
     /**
      * What the backend asks of the calculation that made it: the in-process half of the backend's
@@ -672,14 +743,19 @@ export declare namespace CalcBackend {
         onRestored(): void;
         /** Something was marked out of date: the calculation state may have changed. */
         onDirty(): void;
+        /** The count of async calls pending may have changed. */
+        onPendingChange(): void;
         /** A replica of tables or names changed: what its symbols resolve to now is reconciled. */
         onSymbolsChanged(kind: 'tables' | 'names'): void;
         /** Runs an action at the calculation's next safe point; a `priority` one ahead of the rest. */
         whenSafe(action: () => Promise<unknown>, priority: boolean): void;
         /** Whether the calculation is loading: draining, or starting. */
         isLoading(): boolean;
-        /** Runs a pass: explicit without `gridId`, reactive for it with one. */
-        calculate(options?: ICalculation.CalculateOptions, gridId?: string): Promise<ICalculation.Status>;
+        /**
+         * Runs a pass: explicit without `gridId`, reactive for it with one; a settle pass with
+         * `settle`, seeded from what the settle marked only (DESIGN-ASYNC §4.5).
+         */
+        calculate(options?: ICalculation.CalculateOptions, gridId?: string, settle?: boolean): Promise<ICalculation.Status>;
         /** Owes a reactive pass for `gridId`, run once the current flush is over. */
         owePass(gridId: string): void;
         /** Whether a grid id is a defined name's: its virtual grid's id is the name's. */
@@ -733,6 +809,8 @@ export declare namespace CalcBackend {
         gridId: string;
         /** Evaluates `block` - this one, or a repair of it - at the formula's cell. */
         evaluate(block: IFormulaBlock, evalIndex: number | undefined, alwaysReturnRange: boolean): Scalar | IRange;
+        /** The calls the last evaluation made or was served; none when it did not defer. */
+        getCalls(): readonly DeferredCall[];
     }
     /** The three replicas, as a start seeds them. */
     interface Replica {
@@ -750,6 +828,17 @@ export declare namespace CalcBackend {
         calcCoords?: IRange.Coords;
         /** The grid whose reactive pass this is; absent for an explicit one. */
         gridId?: string;
+        /**
+         * The settle pass (DESIGN-ASYNC §4.5, §4.8): seeded from the regions the settle marked only.
+         * Volatiles are not collected and the dirty set is left for the pass that owes it, so a
+         * landing result neither re-rolls `RAND` nor runs the recalculation manual mode withholds.
+         */
+        settle?: boolean;
+        /**
+         * `ICalculation.CalculateOptions.external`: the calls the pass makes fetch past the workbook's
+         * cache, to the source.
+         */
+        external?: boolean;
         /** Iterative calculation's limits, or `null` when it is off. */
         iterate: {
             maxIteration: number;
@@ -757,6 +846,11 @@ export declare namespace CalcBackend {
         } | null;
         /** The model operation open now: what the pass's results are realized under. */
         openOperationId: string | null;
+        /**
+         * A reactive pass under `AutomaticExceptTables`: the what-if data tables (`TABLE` nodes) are
+         * skipped and stay out of date (DESIGN-DATA-TABLES §4.4). Ignored by a full pass.
+         */
+        exceptTables?: boolean;
     }
     interface ConstructorOptions {
         callbacks: Callbacks;
@@ -778,6 +872,10 @@ export declare namespace CalcBackend {
         calculation: ICalculation;
         /** The external books the bindings mirror. */
         books: IExternalBookCollection;
+        /** What rich values a formula makes are made for; omitted, made outside any workbook. */
+        richData?: IRichDataKind.Context;
+        /** What async functions fetch through (`IBatchContext.fetch`); omitted, the global `fetch`. */
+        fetch?: (input: string, init?: RequestInit) => Promise<Response>;
         /** The replicas as the owner holds them when the start was asked for. */
         replica?: Replica;
         /** The model's current commit, mirrored first. */

package/types/src/calculation/executor/CalcExecutor.d.ts

@@ -1,4 +1,4 @@
-import { IRange, IFormulaContext } from '@sheetxl/primitives';
+import { IRange, Scalar, IFormulaContext } from '@sheetxl/primitives';
 import { FixedPackedArray } from '../../primitives/PrimitiveUtils';
 import { PendingOverlayGrid } from '../state/_PendingOverlayGrid';
 import { ISpatialMap, ISpatialMap3D } from '../../collections';
@@ -6,21 +6,20 @@ import { FormulaSpatialValue, PrecedentSpatialValue, PrecedentKind } from '../sp
 import { ICalcGrid, CalcGridBackend } from '../grid';
 import { IContextContainer, CalcNode } from '../state';
 import { ReadHook } from '../state/_ReadObservedGrid';
+import { DeferredCall } from '../state/DeferredCalls';
+import { AsyncValue } from '../../primitives/AsyncValue';
+import { WhatIfTable } from './_WhatIf';
+import { WhatIfLayer } from '../state/_WhatIfLayer';
 import { CircularReference, CycleHost } from './CircularReference';
 /**
  * Executes a calculation cycle: collect → mark-and-plan → evaluate.
  *
- * Owns cycle counters, the async-recalc pending queue, and all transient
- * per-pass state. `Calculation` is the controller that owns persistent spatial
- * state; CalcExecutor receives snapshots and returns results.
+ * Owns cycle counters and all transient per-pass state. `Calculation` is the controller that
+ * owns persistent spatial state; CalcExecutor receives snapshots and returns results.
  */
 export declare class CalcExecutor {
     protected _container: IContextContainer;
     protected _context: IFormulaContext;
-    private readonly _requestCalculate;
-    protected _pendingCalcs: Map<CalcNode, number>;
-    /** Debounced drain of {@link _pendingCalcs} into the volatile set; one instance for the executor's lifetime. */
-    private readonly _flushPendingCalcs;
     /**
      * The last pass's circular roster: every node it evaluated by demand (a `doMarkAndPlan` that
      * could not order, or the iteration guard's hand-over) plus every node whose dynamic read
@@ -91,6 +90,13 @@ export declare class CalcExecutor {
     protected _deferredLength: number;
     /** The pass the hook answers for; inert otherwise. Set by `doMarkAndPlan`, released with `_gridUpdates`. */
     protected _passActive: boolean;
+    /** The pass in progress is a settle pass (`ExecuteOptions.settle`): its seeds are the settles' alone. */
+    protected _settlePass: boolean;
+    /**
+     * The holder {@link _takeDeferred} made for an evaluation whose value is a range: the value keeps
+     * its shape for the spill layout, which puts the holder on the spill's entry. Taken at once.
+     */
+    protected _spillHolder: AsyncValue<DeferredCall> | null;
     protected _passCycleId: number;
     protected _passMarkId: number;
     /**
@@ -105,6 +111,19 @@ export declare class CalcExecutor {
      * while a pass evaluates. Released with {@link _flush}.
      */
     _overlays: Map<string, PendingOverlayGrid> | null;
+    /**
+     * The what-if layers of the data table being evaluated, per grid id (DESIGN-DATA-TABLES §4.3):
+     * what `getGridValues` hands every read while a `TABLE` node runs its substitutions. `null`
+     * otherwise.
+     */
+    _whatIf: Map<string, WhatIfLayer> | null;
+    /**
+     * A reactive pass under `AutomaticExceptTables`: a `TABLE` node is not evaluated, and is left
+     * dirty ({@link _skippedTables}). Set for the length of `execute`.
+     */
+    protected _exceptTables: boolean;
+    /** The `TABLE` nodes the pass in progress skipped, for `ExecuteResult.skippedTables`. */
+    protected _skippedTables: Set<CalcNode>;
     /**
      * The blank regions of the blocks whose representative could not stand for them this plan
      * (PLAN-WATCHES-BLANK-AWARE §4), and the cells of the regions that WERE shared whose value the
@@ -193,20 +212,9 @@ export declare class CalcExecutor {
     protected _planMemos: [CalcExecutor.PlanMemo, CalcExecutor.PlanMemo];
     /** The memos' LRU clock. Its own counter, NOT `PlanStats.passes`: a stats reset must not reorder the slots. */
     protected _planMemoClock: number;
-    /**
-     * Nodes with an async promise in flight. Per executor, NOT module scope — module scope would
-     * cross-pollute workbook instances (undo to 0 formulas needs to clear these; TODO - revisit
-     * how we manage promises).
-     */
-    protected _pendingPromises: Set<CalcNode>;
     _gridUpdates: Map<string, ICalcGrid.IncrementalUpdates> | null;
     _addDynamicPrecedent: ((node: CalcNode, range: IRange.Coords | undefined, kind: PrecedentKind) => void) | null;
-    constructor(container: IContextContainer, context: IFormulaContext, requestCalculate: () => void);
-    /**
-     * Called when an async formula promise resolves. Adds the node to the pending
-     * queue and debounces a new calculation cycle via `requestCalculate`.
-     */
-    scheduleRecalculation: (cycleId: number, calcNode?: CalcNode) => void;
+    constructor(container: IContextContainer, context: IFormulaContext);
     /**
      * Runs a full calculation pass.
      *
@@ -216,6 +224,14 @@ export declare class CalcExecutor {
      *          nothing was dirty.
      */
     execute(cycleId: number, options: CalcExecutor.ExecuteOptions, state: CalcExecutor.ExecuteState): CalcExecutor.ExecuteResult | null;
+    /**
+     * Takes the calls an evaluation of `node` deferred (DESIGN-ASYNC §4.4): the cell's value is an
+     * `AsyncValue` over them and what the formula calculated from their initials, and the node is
+     * pending with it while any is open.
+     */
+    protected _takeDeferred(node: CalcNode, value: any): any;
+    /** The cells of the `TABLE` nodes the pass skipped, scoped; `undefined` for none. */
+    private _takeSkippedTables;
     /**
      * The read hook of a pass (DESIGN-CIRCULAR-CALC.md §4.3, §5), shared by both paths: armed for
      * every reference while a node is evaluated by demand, and for dynamic-branch references
@@ -332,6 +348,24 @@ export declare class CalcExecutor {
      * `flush` of the `doEvaluate` that made it, and only that one.
      */
     private _overlayFor;
+    /**
+     * The results of a what-if data table, for the `TABLE` node being evaluated
+     * (DESIGN-DATA-TABLES §4.3): the affected nodes re-evaluated under each substitution of §2.2,
+     * through layers over what the grids read as now, the pass's uncommitted results included.
+     *
+     * @remarks
+     * The read hooks and the dynamic-edge accumulator are set aside while it runs: every member
+     * read is a plain read through the layers and registers no edge. The table's own reads of its
+     * edge, which order it and register its edges, are made before (`_DataTableFunction`). The calc
+     * scope is the table's again on return.
+     */
+    evaluateWhatIf(table: WhatIfTable): Scalar[][];
+    /**
+     * One node evaluated where it sits, under the what-if layers (DESIGN-DATA-TABLES §4.3): its
+     * input slots are cleared so every read falls through to the funnel, as a demand evaluation's
+     * do. An async result stands as the cell's last value; so does a read that raised a signal.
+     */
+    private _evaluateWhatIf;
     /**
      * A finalized result fitted to its cell when the block makes every cell its own 1x1
      * array-entered extent (`FormulaSpatialValue.arrayFirstCell`): element `[0,0]` of a range, so the
@@ -520,7 +554,7 @@ export declare class CalcExecutor {
      * A `CalcNode` is a plain graph object reachable by identity long after the grid has replaced or
      * dropped its block — the same hazard `doCollectVolatileCalcs` guards against with `isLiveBlock`.
      */
-    protected isLiveNode(node: CalcNode): boolean;
+    isLiveNode(node: CalcNode): boolean;
     /**
      * @internal
      * A copy of the last pass's circular roster — see {@link _circularNodesLength} — each node
@@ -587,7 +621,7 @@ export declare class CalcExecutor {
      * one if there is one, else the least recently used.
      */
     private _rememberPlan;
-    doEvaluate(cycleId: number, getUpdates: (scope: string) => ICalcGrid.IncrementalUpdates, scheduleRecalculation: (cycleId: number, calcNode?: CalcNode) => void, commit: (calcNodes: CalcNode[], calcNodesLength: number) => void, forceFull: boolean, plan: FixedPackedArray<CalcNode>): ISpatialMap | undefined;
+    doEvaluate(cycleId: number, getUpdates: (scope: string) => ICalcGrid.IncrementalUpdates, commit: (calcNodes: CalcNode[], calcNodesLength: number) => void, forceFull: boolean, plan: FixedPackedArray<CalcNode>): ISpatialMap | undefined;
 }
 export declare namespace CalcExecutor {
     /** Per-pass options derived from ICalculation.CalculateOptions */
@@ -603,10 +637,25 @@ export declare namespace CalcExecutor {
          * The grid to seed the pass FROM — `ICalculation.CalculateOptions.scope`, i.e. "Calculate Sheet".
          */
         scopeGridId?: string;
+        /**
+         * The settle pass (DESIGN-ASYNC §4.5): seeded from what the settles marked only; the volatiles
+         * and the dirty set are left for the pass that owes them.
+         */
+        settle?: boolean;
+        /**
+         * `ICalculation.CalculateOptions.external`: the calls the pass makes fetch past the workbook's
+         * cache, to the source.
+         */
+        external?: boolean;
         /**
          * Iterative calculation (design §6.3) for the pass; `null`/absent with it off.
          */
         iterate?: IterateOptions | null;
+        /**
+         * A reactive pass under `AutomaticExceptTables`: `TABLE` nodes are skipped and left dirty
+         * (DESIGN-DATA-TABLES §4.4); they come back in {@link ExecuteResult.skippedTables}.
+         */
+        exceptTables?: boolean;
     }
     /** The two limits of `ICalculation.IterativeCalculation`. */
     interface IterateOptions {
@@ -708,6 +757,8 @@ export declare namespace CalcExecutor {
         precedentSpatial: ISpatialMap3D<PrecedentSpatialValue>;
         dynamicByBlock: Map<FormulaSpatialValue, ISpatialMap.Entry<PrecedentSpatialValue>[]>;
         lastUpdates: Map<string, ICalcGrid.IncrementalUpdates>;
+        /** The cells of the `TABLE` nodes an `exceptTables` pass skipped, scoped: still out of date. */
+        skippedTables?: IRange.Coords[];
     }
 }
 //# sourceMappingURL=CalcExecutor.d.ts.map

package/types/src/calculation/executor/CalcExecutorUtils.d.ts

@@ -1,5 +1,5 @@
 import { IRange, Scalar } from '@sheetxl/primitives';
-import { Tuple, ISpatialMap } from '../../collections';
+import { Tuple, ISpatialMap, ISpatialQuery } from '../../collections';
 import { CalcSignal } from '../../primitives/CalcSignal';
 import { CalcNode } from '../state';
 import { PrecedentSpatialValue, FormulaSpatialValue } from '../spatial';
@@ -62,6 +62,22 @@ export declare function fitToExtent(value: Scalar | IRange, rowCount: number, co
  * to. `null` when every fitted cell is blank.
  */
 export declare function fitToTuples(value: Scalar | IRange, coords: IRange.Coords, isColumn: boolean): Tuple.Region<Scalar> | null;
+/**
+ * Visits, for every precedent entry that reads into `region`, the window of its block whose cells
+ * can see the region - the discovery step of a dirty walk (`CalcExecutor.doCollectDirtyCalcs`)
+ * and of a data table's affected set (`_WhatIf`).
+ *
+ * @remarks
+ * An entry spans the REFERENCED region, which may be larger than the block (a relative reference
+ * is widened per block cell), so the region is mapped back through that overflow to the block's
+ * own coordinates. An anchored endpoint sits at the same coordinate for every cell of the block,
+ * so it stops bounding which cells saw the change - that side opens to the whole block. The END
+ * endpoint bounds the near side, the START endpoint the far side (see `PrecedentSpatialValue`).
+ * A dynamic entry (`index < 0`) has no extent to map: it is reported whole.
+ *
+ * @param scratch An array the search fills; the caller's, reused across calls.
+ */
+export declare function visitReaderWindows(precedentSpatial: ISpatialQuery<PrecedentSpatialValue>, region: IRange.Coords, scratch: ISpatialMap.Entry<PrecedentSpatialValue>[], visitWindow: (block: FormulaSpatialValue, rowFrom: number, rowTo: number, colFrom: number, colTo: number) => void, visitDynamic: (entry: ISpatialMap.Entry<PrecedentSpatialValue>, block: FormulaSpatialValue) => void): void;
 /**
  * TODO - document and/or rationalize with visitPrecedentBlock
  */

package/types/src/calculation/executor/_WhatIf.d.ts

@@ -0,0 +1,50 @@
+import { IRange, Scalar } from '@sheetxl/primitives';
+import { CalcNode, IContextContainer } from '../state';
+import { WhatIfLayer } from '../state/_WhatIfLayer';
+/**
+ * A what-if data table as its `TABLE` formula states it (DESIGN-DATA-TABLES §1): the results'
+ * top-left cell and size, and the input cells, all on one grid.
+ */
+export interface WhatIfTable {
+    gridId: string;
+    /** The top-left result cell: where the `TABLE` formula sits. */
+    row: number;
+    col: number;
+    rows: number;
+    cols: number;
+    /** The cell the row axis values go into; `null` for a one-input table down a column. */
+    rowInput: IRange.CellCoords | null;
+    /** The cell the column axis values go into; `null` for a one-input table along a row. */
+    colInput: IRange.CellCoords | null;
+}
+/** What the what-if evaluation asks of the executor it runs inside. */
+export interface WhatIfHost {
+    readonly container: IContextContainer;
+    /**
+     * Evaluates `node` where it sits, every read answered through the installed what-if layers: the
+     * cell's finalized value, a range for a spill.
+     */
+    evaluate(node: CalcNode): Scalar | IRange;
+    /** The layer of a grid, made on first use over what the grid reads as now. */
+    layerFor(gridId: string): WhatIfLayer;
+}
+/** The rectangles of a table's edge: the formula cells, then the axes. All on the table's grid. */
+export declare function whatIfEdge(table: WhatIfTable): IRange.Coords[];
+/**
+ * The affected set S of a table (DESIGN-DATA-TABLES §4.3): every node downstream of an input
+ * that is upstream of a formula cell or an axis cell, in an order that evaluates a node after
+ * the nodes it reads. Widened to the whole downstream closure when a member reads through a
+ * dynamic reference, whose edges the index cannot bound.
+ *
+ * A `TABLE` node is never a member, this table's own included: another table's results are read as
+ * they stand, not re-run under this table's substitutions, as Excel reads them (design §2.2 T6).
+ * That also keeps the walk from passing through a table's own edges, which would reach the table.
+ */
+export declare function whatIfAffectedSet(container: IContextContainer, table: WhatIfTable): CalcNode[];
+/**
+ * A table's results under the what-if protocol of DESIGN-DATA-TABLES §2.2, evaluating `affected`
+ * (from {@link whatIfAffectedSet}) under each substitution. The layers are the host's; nothing is
+ * restored, the caller drops them.
+ */
+export declare function runWhatIf(host: WhatIfHost, table: WhatIfTable, affected: readonly CalcNode[]): Scalar[][];
+//# sourceMappingURL=_WhatIf.d.ts.map

package/types/src/calculation/formula/FormulaBlock.d.ts

@@ -80,6 +80,8 @@ export declare class FormulaBlock implements IFormulaBlock {
     getReferencedSymbolIds(): string[];
     /** @inheritdoc IFormulaBlock.hasTotals */
     hasTotals(): boolean;
+    /** @inheritdoc IFormulaBlock.hasDataTable */
+    hasDataTable(): boolean;
     /** @inheritdoc IFormulaBlock.hasVolatile */
     hasVolatile(): boolean;
     /** @inheritdoc IFormulaBlock.isBlankCacheable */
@@ -274,10 +276,9 @@ export declare class FormulaBlock implements IFormulaBlock {
     protected _evaluateSubtree(node: ASTNode, regs: any[], frame: ReadonlyMap<number, any> | null, row: number, column: number): any;
     /**
      * Runs an execution list — the eager `executions` or a deferred root's list — writing each
-     * node's result into its register. Answers the promise chain when a node is async, in which
-     * case the rest of the list is queued behind it.
+     * node's result into its register.
      */
-    protected _runList(list: ASTNode[], regs: any[], row: number, column: number, frame: ReadonlyMap<number, any> | null): Promise<any> | undefined;
+    protected _runList(list: ASTNode[], regs: any[], row: number, column: number, frame: ReadonlyMap<number, any> | null): void;
     /**
      * The execution list of a subtree that is NOT a deferred root — a partial evaluation (the
      * editor's tooltip) pointing inside a lazy argument. The enclosing root's list restricted to

package/types/src/calculation/formula/IFormulaBlock.d.ts

@@ -346,6 +346,11 @@ export interface IFormulaBlock extends IFormulaBlockView {
      * either all of them call a total function or none do.
      */
     hasTotals(): boolean;
+    /**
+     * Whether the formula calls `TABLE`, the what-if data table, anywhere in its tree. Read off the
+     * compiled cache (`CompiledFormula.hasDataTable`).
+     */
+    hasDataTable(): boolean;
     /**
      * Whether the formula names a volatile function anywhere in its tree.
      *

package/types/src/calculation/functions/_DataTableFunction.d.ts

@@ -0,0 +1,14 @@
+import { IFormulaContext } from '@sheetxl/primitives';
+import { FunctionDeclarationModule, Implementations, DescriptorModule } from '@sheetxl/scripting';
+/**
+ * The category `TABLE` is listed under: ours, not Excel's. Excel has no `TABLE` a user may type, so
+ * the writer treats it as a function Excel does not have wherever it cannot write Excel's tag.
+ */
+export declare const DataTableCategory = "SheetXL";
+/** `TABLE`'s declarations, as the declaration table and the function registry read them. */
+export declare const DataTableDeclarations: FunctionDeclarationModule;
+/** `TABLE`'s descriptors, loaded on demand like the built-ins'. */
+export declare const DataTableDescriptors: () => Promise<DescriptorModule>;
+/** The implementation the registry binds `TABLE`'s declaration to. */
+export declare const createDataTableImplementations: (getContext: () => IFormulaContext) => Implementations;
+//# sourceMappingURL=_DataTableFunction.d.ts.map

package/types/src/calculation/grid/CalcGrid.d.ts

@@ -135,7 +135,7 @@ export declare class CalcGrid implements ICalcGrid {
     /** {@inheritDoc ICalcGrid.getSpills} */
     getSpills(transaction?: ITransaction | null): ISpatialMap<SpillEntry>;
     /** {@inheritDoc ICalcGrid.getPending} */
-    getPending(transaction?: ITransaction | null): ISpatialMap<boolean>;
+    getCalcStatus(transaction?: ITransaction | null): ISpatialMap<ICalcGrid.CalcStatus>;
     /** {@inheritDoc ICalcGrid.getCalcErrors} */
     getCalcErrors(transaction?: ITransaction | null): ISpatialMap<string>;
     /** {@inheritDoc ICalcGrid.getCirculars} */
@@ -233,8 +233,6 @@ export declare class CalcGrid implements ICalcGrid {
     _demand(rects: readonly IRange.Coords[]): void;
     /** {@inheritDoc ICalcGrid.getGraphNeighborsAt} */
     getGraphNeighborsAt(coords: IRange.Coords, kind: 'precedents' | 'dependents', direct: boolean): Promise<ICalcGrid.GraphNeighbors>;
-    /** {@inheritDoc ICalcGrid.Backend.getNameGraph} @internal */
-    _getNameGraph(kind: 'precedents' | 'dependents', direct: boolean): Promise<ICalcGrid.GraphNeighbors>;
     /** {@inheritDoc ICalcGrid.evaluateAt} */
     evaluateAt(row: number, column: number, options?: number | ICalculation.EvaluateOptions): Promise<Scalar | IRange>;
     /** `true` once closed: its state is gone. @internal */
@@ -396,12 +394,12 @@ export declare namespace CalcGrid {
          */
         volatile: IRange.Address[] | null;
         /** Cells the engine has not answered for yet. */
-        pendingSpatial: ISpatialMap<boolean>;
+        calcStatusSpatial: ISpatialMap<ICalcGrid.CalcStatus>;
         /** Engine FAILURES by cell, as a message. Not error values - those are in the values. */
         calcErrorsSpatial: ISpatialMap<string>;
         /**
          * Cells in a reference cycle or downstream of one, by cycle (DESIGN-CIRCULAR-CALC.md §7.2).
-         * Maintained from the executor's deltas, like {@link pendingSpatial}.
+         * Maintained from the executor's deltas, like {@link calcStatusSpatial}.
          */
         circularSpatial: ISpatialMap<CircularEntry>;
         /**
@@ -437,7 +435,7 @@ export declare namespace CalcGrid {
         values: ISparseGrid<Scalar>;
         contentful: ISpatialMap<ContentfulSpatialValue>;
         spills: ISpatialMap<SpillEntry>;
-        pending: ISpatialMap<boolean>;
+        calcStatus: ISpatialMap<ICalcGrid.CalcStatus>;
         calcErrors: ISpatialMap<string>;
         circulars: ISpatialMap<CircularEntry>;
         errorValues: ISpatialMap<boolean>;