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

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,29 +12,21 @@ 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';
 import { ExternalBookBindings, ExternalNamedItem } from '../ExternalBookBindings';
 import { ISymbolRegistry } from '../symbol';
-/**
- * The calculation backend: the engine's store and everything kept in it, and the container its
- * grids, formulas and executor work against (DESIGN-CALC-SERVICE §5).
- *
- * @remarks
- * Made by the first `start()` from the loaded engine module, and kept across a stop and a restart.
- * Its history is its own (§13.13): every model commit has a mirror here, a request lands under the
- * model's operation or savepoint it was made in, and a revert names a model commit. The model's ids
- * are known to it through one map, landing to engine commit.
- *
- * What it asks of the calculation that made it is {@link CalcBackend.Callbacks}, and nothing else.
- */
 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;
@@ -41,6 +34,8 @@ export declare class CalcBackend extends AbstractModel<CalcBackend.State> implem
     protected _gridOptions: Partial<CalcGridBackend.ConstructorOptions>;
     protected _calculation: ICalculation;
     protected _context: CalculationContext & IFormulaContext;
+    /** {@link _context} with no cell, for executors (`IDeferContext.getFormulaContext`); made on first ask. */
+    protected _cellFreeContext: (CalculationContext & IFormulaContext) | null;
     protected _calcExecutor: CalcExecutor;
     /** The cache as grids and the cached names as virtual grids — see {@link ExternalBookBindings}. */
     protected _externalBindings: ExternalBookBindings;
@@ -52,6 +47,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. */
@@ -86,6 +82,8 @@ export declare class CalcBackend extends AbstractModel<CalcBackend.State> implem
      * a load wires every name it holds in one batch.
      */
     private _recompileNamedPending;
+    /** {@link _recompileNamedPending} for a name whose definition has not changed. */
+    private _recompileLoadedPending;
     private _invalidateNamedPending;
     constructor(options: CalcBackend.ConstructorOptions);
     /** Initializes the context: the function registry the backend calls through. */
@@ -94,8 +92,26 @@ 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;
+    protected _settle(): void;
+    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, options?: IFormulaContext.DeferredCall.ResolveOptions): 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 +145,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} */
@@ -209,7 +227,7 @@ export declare class CalcBackend extends AbstractModel<CalcBackend.State> implem
     /** {@inheritDoc IContextContainer.isLoading} */
     isLoading(): boolean;
     /** {@inheritDoc IContextContainer.recompileNamed} */
-    recompileNamed(nameId: string): void;
+    recompileNamed(nameId: string, loaded?: boolean): void;
     /** {@inheritDoc IContextContainer.invalidateNamed} */
     invalidateNamed(nameId: string): void;
     /** {@inheritDoc IContextContainer.getNamedNodeInfo} */
@@ -234,6 +252,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 +312,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
@@ -275,28 +320,6 @@ export declare class CalcBackend extends AbstractModel<CalcBackend.State> implem
      * @throws What the grid throws applying it.
      */
     apply(gridId: string, landingId: string | undefined, request: CalcRequest, held?: boolean): CalcResponse | PromiseLike<CalcResponse>;
-    /**
-     * Applies what the channel held while the engine came up (DESIGN-CALC-SERVICE §6.3): every
-     * grid made first, then a defined name's body, in its own order (`ICalcGrid.BodyOptions.priority`),
-     * then the rest in send order. A name must be bound before any formula that mentions it is
-     * examined, and each is held behind the create of its own grid.
-     *
-     * @remarks
-     * Every sheet a held `sheets` message adds enters the replica at its end first, under the name it
-     * was first listed by: a defined name's body is applied ahead of the seeds and may name a sheet
-     * listed while starting. Every table a held `tables` message adds enters the same way, under the
-     * name and columns it was first told by: a seed sent ahead of a later sheet's tables compiles a
-     * reference to one, and a reference to a table the replica does not hold is refused. The messages
-     * themselves still apply in send order, so a seed sent before a rename binds the name it was sent
-     * under.
-     *
-     * A request whose snapshot the model has undone since (`dead`) is answered and not applied,
-     * except a grid's `create`.
-     *
-     * @param wroteWhileOff Something was written while the engine was `Off`: a seed asking for a
-     * full pass keeps it. Otherwise its values are the engine's own, or a file's.
-     * @returns What each request answered, in the order they were applied.
-     */
     applyHeld(batch: readonly CalcBackend.Held[], wroteWhileOff: boolean): CalcBackend.Applied[];
     /** {@inheritDoc IContextContainer.getHeldCloneKey} */
     getHeldCloneKey(): string | null;
@@ -407,51 +430,12 @@ export declare class CalcBackend extends AbstractModel<CalcBackend.State> implem
      * {@link _namedTargets} expansion: a name whose body cites the symbol reaches its own readers.
      *
      * Run at a safe point only — it writes inputs.
-     */
-    recompileReferencing(changedIds: ReadonlySet<string>): void;
-    /**
-     * A table's body has changed rows: re-fit the A1 references that spanned it.
-     *
-     * @remarks
-     * Excel treats a reference whose ROWS are exactly a table's body - or run from its header to the
-     * body's end - as naming the body, whatever columns of the table it covers, and keeps it on the
-     * body however the body's rows change (probed, `probe-table-refit.ps1`): `SUM(B2:B5)` over body
-     * rows 2-5 reads `SUM(B2:B6)` after a row is appended, and `SUM(B2:B3)` after a resize gives two
-     * up. Relative, absolute or mixed alike, from any sheet, and in anything that holds a reference -
-     * a defined name, a table's held totals formula and a condition's formula are blocks too. A
-     * reference that only starts or only ends with the body is an ordinary one, and a change of
-     * COLUMNS re-fits nothing. A name's relative rows are read from its body's origin, A1, as Excel
-     * reads them (`probe-table-refit-relative.ps1`); a shift never moves them, so a row at the top
-     * leaves such a name alone.
-     *
-     * An insert or delete inside the body already leaves such a reference right, so this is asked
-     * only for what a shift gets wrong: rows taken or given up at the body's end, and a row inserted
-     * at its first row (which pushes the whole reference down).
      *
-     * One search of the precedent index over the rows that match - an entry per (block, reference)
-     * that reads them - so the cost is the readers of the body, on a change of a table's rows. The
-     * text a cell shows catches up with the engine the way it does after any shift.
-     *
-     * A block is re-fitted cell by cell: only the cells whose reference spans the body are rewritten,
-     * which splits them out of the block. An array-entered block is one formula, read at its top-left,
-     * and is never split.
-     *
-     * **A DELIBERATE DIVERGENCE lives here** (Michael, 2026-09-22). Excel asks how the cell was
-     * authored, not what it reads: a fully relative reference is left where it is when the cell
-     * belongs to a shared-formula group, and re-fitted when it stands alone - so `SUM(B2:B5)` follows
-     * the body when it was typed and does not when the same three formulas were filled, and the file
-     * carries the difference as `<f t="shared">` (`probe-table-refit-fillhandle.ps1`,
-     * `probe-table-refit-roundtrip.ps1`). Here a run is a data-model fact, not an authoring one -
-     * cells holding the same formula are conflated whatever made them - so honoring that rule would
-     * make a formula follow the body or not depending on what a NEIGHBOR happens to hold, which a
-     * user cannot see. Every reference that spans the body is re-fitted, however it was written.
-     *
-     * @param sheet The sheet the table is on, by id or name.
-     * @param columns The table's columns. A reference reaching outside them is an ordinary one.
-     * @param match The rows a reference has to span to be one of the body's, as they read NOW.
-     * @param headerRow The header's row when a reference from it to `match.rowEnd` also counts.
-     * @param to The body's rows now.
+     * @param loaded The definitions have not changed (see {@link recompileNamed}). What was loaded
+     * with them, and the bodies of other names, only re-derive their precedents: opening a file
+     * evaluates what the file marks dirty, and mentioning a name is not a mark.
      */
+    recompileReferencing(changedIds: ReadonlySet<string>, loaded?: boolean): void;
     refitTableRows(sheet: string, columns: {
         colStart: number;
         colEnd: number;
@@ -475,38 +459,6 @@ export declare class CalcBackend extends AbstractModel<CalcBackend.State> implem
     protected _writeBlockText(fsv: FormulaSpatialValue, text: string, coords?: IRange.Coords): void;
     /** Whether any cell is out of date. */
     hasDirty(): boolean;
-    /**
-     * Runs one pass over the dirty set (or all of it, or a range of it), and writes what it found
-     * into the state.
-     *
-     * @remarks
-     * One recalculation per COMMIT, not per notification of one.
-     *
-     * `gridId` marks the engine's own reactive pass — `ICalcGrid.calculate()`, which is what an
-     * edit schedules (`Sheet.onAfterStateChange`) and what `ready()` runs per dirty grid. An
-     * explicit `calculate()` from the API (F9, Shift+F9, a resolved async result) has no `gridId`
-     * and is always honored.
-     *
-     * The reactive pass is skipped only when BOTH halves say there is nothing to do:
-     *
-     * - the current commit has already had its recalculation. Commits notify their listeners on
-     *   `setTimeout(0)`, so a script that writes N cells without awaiting queues N dispatchers,
-     *   none of which run until it yields. By then the store is at the LAST commit and every one
-     *   of those dispatchers asks for a pass over the same final state — N-1 of them describing
-     *   work another pass has already done.
-     * - nothing is dirty. The dirty set is cumulative and whichever pass runs first consumes all
-     *   of it, but a seed (`CalcGridBackend._seedNow`) marks dirty without producing a commit of its
-     *   own, so the commit id alone would strand it.
-     *
-     * Neither half alone is enough, and the second is emphatically not sufficient: an edit that
-     * marks nothing dirty is still a recalculation in Excel, and it is the only thing that re-rolls
-     * `RAND`/`NOW` — see the "unrelated edit" case in `graph/volatile.test.ts`.
-     *
-     * Together they were the whole cost of the round-trip workbook build (`functions-to-xlsx.ts`):
-     * 2,594 redundant passes, each re-evaluating every volatile in the workbook and everything
-     * downstream of it, for 49,289 of 52,917 total evaluations — 93% of the engine's work, still
-     * running six seconds after `ready()` had resolved. See DESIGN-CALC-PASS-GATING.md.
-     */
     runPass(options: ICalculation.CalculateOptions | undefined, pass: CalcBackend.PassOptions): void;
     /** Each grid with cells out of date runs its pass - every grid, when `full`. */
     calculateGrids(full: boolean): Promise<void>;
@@ -649,9 +601,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 +621,15 @@ 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>;
+        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 +683,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 +702,14 @@ export declare namespace CalcBackend {
         calcCoords?: IRange.Coords;
         /** The grid whose reactive pass this is; absent for an explicit one. */
         gridId?: string;
+        settle?: boolean;
+        /**
+         * `ICalculation.CalculateOptions.external`: the calls the pass makes fetch past the workbook's
+         * cache, to the source.
+         */
+        external?: boolean;
+        /** The pass a load owes: see `CalcExecutor.ExecuteOptions.load`. */
+        load?: boolean;
         /** Iterative calculation's limits, or `null` when it is off. */
         iterate: {
             maxIteration: number;
@@ -757,6 +717,7 @@ export declare namespace CalcBackend {
         } | null;
         /** The model operation open now: what the pass's results are realized under. */
         openOperationId: string | null;
+        exceptTables?: boolean;
     }
     interface ConstructorOptions {
         callbacks: Callbacks;
@@ -778,6 +739,12 @@ 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 (`IDeferContext.fetch`); omitted, the global `fetch`. */
+        fetch?: (input: string, init?: RequestInit) => Promise<Response>;
+        /** How async functions read delimited text (`IDeferContext.parseText`); omitted, it rejects. */
+        parseText?: (text: string, options?: IFormulaContext.IDeferContext.ParseTextOptions) => Promise<Scalar[][]>;
         /** The replicas as the owner holds them when the start was asked for. */
         replica?: Replica;
         /** The model's current commit, mirrored first. */
@@ -822,23 +789,12 @@ export declare namespace CalcBackend {
          * All registered grids.
          */
         gridsAll: Map<string, CalcGridBackend>;
-        /**
-         * The engine's replica of the model's sheet list (DESIGN-CALC-SERVICE §8): grid id to name, in
-         * tab order. What every symbol lookup, span and sheet-position function reads. Fed by the
-         * `sheets` message and by grid registration; versioned here so a revert restores it with the
-         * formulas that bound through it.
-         */
         sheets: ReadonlyMap<string, string | null>;
         /**
          * The sheets in {@link sheets} that have no grid: chart, macro and dialog sheets. They count in
          * tab order (`SHEETS`, `SHEET`, a span's members) and hold no cells.
          */
         gridless: ReadonlySet<string>;
-        /**
-         * The engine's replica of the model's tables (DESIGN-CALC-SERVICE §8): table id to its name and
-         * its columns' ids and names. What a structured reference binds and images through. Fed by the
-         * `tables` message, seeded at a start, versioned here as {@link sheets} is.
-         */
         tables: ReadonlyMap<string, TableSymbols>;
         /**
          * The engine's replica of the defined names: name id to its spelling and the sheet it is scoped

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

@@ -1,10 +1,2 @@
-/**
- * The calculation backend's code: what a started engine builds and runs.
- *
- * @remarks
- * `Calculation` reaches every value here through this one module and nothing else, so the facade a
- * workbook constructs carries none of it (DESIGN-CALC-SERVICE §5, §13.25). Types are imported
- * directly; only values belong on this list.
- */
 export { CalcBackend } from './CalcBackend';
 //# sourceMappingURL=index.d.ts.map