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

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

@@ -19,7 +19,9 @@ export interface ICalculation extends IModel {
      * @returns A promise that will be resolved when the calculation is completed.
      *
      * @remarks
-     * For async functions this will return before they are completed.
+     * For async functions this will return before they are completed. An async function is called
+     * again unless its call is still running; what it fetches is answered
+     * from the workbook's cache unless {@link ICalculation.CalculateOptions.external} is set.
      */
     calculate(options?: boolean | ICalculation.CalculateOptions): Promise<ICalculation.Status>;
     /**
@@ -38,7 +40,7 @@ export interface ICalculation extends IModel {
     /**
      * Resolves once the engine is running and idle: its calculation state is
      * {@link ICalculation.CalculationState.Done}, or {@link ICalculation.CalculationState.Pending} in
-     * manual mode.
+     * manual mode (and, under `AutomaticExceptTables`, with only data tables out of date).
      *
      * @remarks
      * * After it, every answer the engine owes has landed: a formula written before it reads as
@@ -46,14 +48,46 @@ export interface ICalculation extends IModel {
      * * Manual mode does not wait for a recalculation nobody has asked for; call {@link calculate}.
      * * Waits for what consumers derive from the results too ({@link waitUntil}): a conditional
      *   format reads as painted after it, including one a read just asked to evaluate.
-     * * A streaming or async function's result in flight is not waited for: its cell reads as the
-     *   current value until the result arrives.
+     * * An async function's result in flight is not waited for: its cell reads as what the
+     *   function returned until the result arrives.
      * * Starts the engine if it is {@link ICalculation.Status.Off}. An engine in
      *   {@link ICalculation.Status.Error} is not started; {@link start} tries again.
      *
      * @param options Pass `{ full: true }` to recalculate every grid rather than only the dirty ones.
      */
     ready(options?: ICalculation.CalculateOptions): Promise<ICalculation.Status>;
+    /**
+     * How many async function calls are waiting for an answer.
+     */
+    getPendingCount(): number;
+    /**
+     * Resolves once no async function call is pending ({@link getPendingCount} is `0`) and every
+     * answer has been calculated into the workbook — Excel's `CalculateUntilAsyncQueriesDone`.
+     *
+     * @param options `timeout` in milliseconds; 30 seconds when absent.
+     * @returns `true` when nothing is pending; `false` when the timeout came first.
+     *
+     * @remarks
+     * * An answer that makes a formula ask a new question (one call's answer is another's input)
+     *   is waited for too.
+     * * {@link ready} is the engine's own readiness and does not wait for answers.
+     */
+    whenPendingDone(options?: {
+        timeout?: number;
+    }): Promise<boolean>;
+    /**
+     * Stops waiting for async function calls — Excel's *Cancel Refresh*: each pending
+     * call the options cover is closed, and the function is told (its `onCancel`).
+     *
+     * @param options Which calls; every call when absent.
+     * @returns A promise that resolves once the cells have been recalculated.
+     *
+     * @remarks
+     * * A cell keeps what it showed — its last answer, or the value its function returned while it
+     *   waited — and is no longer pending. An answer that arrives later is dropped.
+     * * A recalculation of a cancelled cell calls its function again.
+     */
+    cancelAsync(options?: ICalculation.CancelOptions): Promise<ICalculation.Status>;
     /**
      * Counts `work` that a consumer derives from the engine's results as calculation in flight
      * until it settles: {@link ready} waits for it, and {@link getCalculationState} reads
@@ -1042,6 +1076,14 @@ export declare namespace ICalculation {
          * Use {@link ICalculation.FormulaToken.evalIndex} to discover valid indices.
          */
         evalIndex?: number;
+        /**
+         * How long to wait, in milliseconds, for the answers of async functions the formula calls:
+         * the evaluation resolves once each has answered, and
+         * answers a `#TIMEOUT!` error naming the call it waited on when the time runs out.
+         *
+         * @defaultValue `30000`
+         */
+        timeout?: number;
         /**
          * Temporary range of values to use for this evaluation.
          *
@@ -1174,6 +1216,15 @@ export declare namespace ICalculation {
          * Called when the calculation state has changed - see {@link ICalculation.getCalculationState}.
          */
         onCalculationStateChange?(source: ICalculation): void;
+        /**
+         * Called when the number of async function calls waiting for an answer may have changed — see
+         * {@link ICalculation.getPendingCount}.
+         *
+         * @remarks
+         * Called when calls are made, when answers are applied, and on a cancel or a stop: answers
+         * arriving together are one call.
+         */
+        onPendingChange?(source: ICalculation): void;
         /**
          * Called when a calculation is completed.
          */
@@ -1242,7 +1293,8 @@ export declare namespace ICalculation {
         readonly Calculating: "calculating";
         /**
          * Changes have been made that need a recalculation, and none will run until one is asked for:
-         * manual mode between an edit and {@link ICalculation.calculate}.
+         * manual mode between an edit and {@link ICalculation.calculate}, or the `TABLE` data tables an
+         * edit left out of date under `AutomaticExceptTables`.
          */
         readonly Pending: "pending";
     };
@@ -1313,14 +1365,16 @@ export declare namespace ICalculation {
          */
         readonly Stale: "stale";
         /**
-         * The value is being calculated asynchronously, typically because the function used returned a Promise.
-         * All dependent values will also be in the Pending state. If the promise returns an error or times out, the value will be an error value.
+         * The cell's own function asked for its result later (`FormulaContext.defer`) and it has not
+         * arrived: the cell shows what the function returned meanwhile, and its dependents calculate
+         * from that and read as {@link Waiting}. A failed call answers an error value.
          */
         readonly Pending: "pending";
         /**
-         * The value is up-to-date, but the underlying data source is streaming live updates.
+         * The value was calculated from a pending value — a precedent whose function has not answered —
+         * and will be calculated again when it does.
          */
-        readonly Streaming: "streaming";
+        readonly Waiting: "waiting";
     };
     type ResultStatus = typeof ResultStatus[keyof typeof ResultStatus];
     /**
@@ -1358,6 +1412,39 @@ export declare namespace ICalculation {
          * live in other sheets, and a named formula's body lives in a virtual grid of its own.
          */
         scope?: string;
+        /**
+         * If `true`, what the calculation reads from outside the workbook is read from the source
+         * again rather than from the workbook's cache — Excel's *Data › Refresh All*: what the async
+         * functions it calls fetch, and, for a calculation that is neither {@link range} nor
+         * {@link scope}, every external book (`IExternalBookCollection.refreshAll`).
+         *
+         * @remarks
+         * * Which functions are called is the calculation's own choice, as without it: pass
+         *   {@link full} for every formula. A call still running is left be.
+         * * The calculation resolves without waiting for the new answers or the external books.
+         *
+         * @example Refresh All
+         * ```ts
+         * await workbook.getCalculation().calculate({ full: true, external: true });
+         * ```
+         *
+         * @defaultValue `false`
+         */
+        external?: boolean;
+    }
+    /**
+     * Options for {@link ICalculation.cancelAsync}.
+     */
+    interface CancelOptions {
+        /**
+         * Only the calls of the formulas in this range are cancelled.
+         */
+        range?: ICellRange.Address;
+        /**
+         * Only the calls of the formulas on this sheet, by name, are cancelled. Ignored when
+         * {@link range} is set.
+         */
+        scope?: string;
     }
     interface JSON {
         /**

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

@@ -3,9 +3,9 @@ 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 { FormulaHost } from './grid';
+import { FormulaHost, ICalcGrid } from './grid';
 import { Formula, IFormulaBlockView } from './formula';
 import { ICalculation } from './ICalculation';
 import { INamedFormulasCollection } from './INamedFormulasCollection';
@@ -75,6 +75,8 @@ export declare class NamedFormulaCollection extends AbstractCollection<ICalculat
      */
     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.
@@ -157,6 +159,27 @@ export declare class NamedFormulaCollection extends AbstractCollection<ICalculat
      * 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.
      *
@@ -306,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
@@ -331,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 {
         /**
@@ -396,6 +421,12 @@ export declare namespace NamedFormulaCollection {
         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,
@@ -457,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;
     /**
@@ -465,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}. */
@@ -484,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;
@@ -528,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, lazy?: boolean);
+    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.
@@ -539,8 +630,10 @@ declare class NamedFormula extends Formula implements ICalculation.INamedFormula
      * @remarks
      * Called by the collection once the item is IN the collection, so the notification the answer
      * brings describes a set that already contains it. `getRanges()` answers once the engine has.
+     *
+     * @param loaded The body is the one the file holds: see `ICalcGrid.BodyOptions.recompile`.
      */
-    _wireNow(): void;
+    _wireNow(loaded?: boolean): 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.
@@ -560,8 +653,10 @@ declare class NamedFormula extends Formula implements ICalculation.INamedFormula
      * 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.
+     *
+     * @param loaded `false` when the text is a new definition rather than the one loaded.
      */
-    _materialize(): void;
+    _materialize(loaded?: boolean): 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.
@@ -811,10 +906,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.

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

@@ -30,16 +30,6 @@ export declare const TokenType: {
      * A function call, e.g. `SUM(...)`. `value` is the function name.
      */
     readonly Function: "function";
-    /**
-     * Function application where the callee is an EXPRESSION rather than a name — an immediately
-     * invoked lambda, `LAMBDA(a,b,a+b)(1,2)`.
-     *
-     * `inputs[0]` is the callee; `inputs[1..]` are the arguments. `value` is `null` — unlike
-     * {@link Function} there is no name to carry.
-     *
-     * A `(` binds as a call ONLY when it touches the callee's last token: `LAMBDA(x,x+1) (3)` with a
-     * space is an implicit intersection, and Excel refuses it. See DESIGN-FORMULA-APPLICATION.md.
-     */
     readonly Call: "call";
     /**
      * An error literal, e.g. `#DIV/0!` or `#REF!`.

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

@@ -1,27 +1,3 @@
-/**
- * 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).
- *
- * @remarks
- * Every request into a grid and every {@link ICalcGrid.Results} out of one passes through here.
- * With the mode `off` - always, outside a test - it is an identity call and costs nothing.
- *
- * Two things it finds, and they are different:
- *
- * - What a walk can see: a function, a class instance, a value `structuredClone` refuses or
- *   silently downgrades. Each is recorded as a {@link Violation} with the PATH it sat at, which
- *   is the point: a payload that degrades silently fails somewhere else entirely, and the path
- *   is what names the field to convert.
- * - What only running can see: a reference the two sides SHARE. A walk cannot tell a run array
- *   the sheet also holds from one minted for the message; a clone does, because the sides stop
- *   agreeing. That is what `clone` mode is for, and why `audit` alone is not the exit criterion.
- *
- * Not a boundary for READS. `getValues`, `getFormulas`, `getSnapshot` and the graph walks answer
- * synchronously out of engine objects; making them push or await is §11's list, not this one.
- * This covers what is already message-shaped.
- *
- * @internal Test-mode only. Deliberately not exported from the barrel.
- */
 export declare namespace CloneBoundary {
     /**
      * `off` is the default and the only mode outside a test.

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

@@ -1,9 +1,4 @@
 /** 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/compiler/ASTTypes.d.ts

@@ -43,20 +43,7 @@ export interface ASTNode<T extends TokenType = TokenType, V = any> {
      * @see {@link ICalculation.FormulaToken.evalIndex}
      */
     evalIndex?: number;
-    /**
-     * Compile-time: the implicit-intersection MODE this call is evaluated in — `true` VALUE mode
-     * (a multi-cell reference at a single-value slot intersects with the formula cell), `false`
-     * ARRAY mode (it reads its first cell). Set on `Function` and `Call` nodes by
-     * `CompilerUtils.annotateImplicitIntersect` (DESIGN-IMPLICIT-INTERSECTION §2).
-     */
     implicitIntersect?: boolean;
-    /**
-     * Compile-time: under a first-cell DEMAND (a block whose every cell is its own 1x1 array-entered
-     * extent — a conditional-format body), only element `[0,0]` of this node's result is ever read,
-     * so a lift or an operator here builds that one element. Set on every node reachable from the
-     * root through elementwise positions by `CompilerUtils.annotateFirstCell`
-     * (DESIGN-LIFT-AND-DEMAND §2); inert unless the block evaluating the formula demands it.
-     */
     firstCell?: boolean;
     /**
      * Compile-time: this `+`/`-` is the root of a formula body — the formula's own root or a
@@ -235,10 +222,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>;
 /**