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

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

@@ -1,5 +1,4 @@
 import { Scalar } from '@sheetxl/primitives';
-import { ICell } from '../cell';
 import { Tuple } from '../collections';
 import { IExternalBookCollection } from '../externalBook';
 import { CalcGridBackend, FormulaHost } from './grid';
@@ -87,11 +86,11 @@ export declare class ExternalBookBindings {
  * column-major scalar tuples a `CalcGridBackend` loads.
  *
  * @remarks
- * `ICell.JSON`'s untyped arm is a bare primitive, and the cache's strings are LITERAL (never a
+ * `Scalar.JSON`'s untyped arm is a bare primitive, and the cache's strings are LITERAL (never a
  * string-table index — the part inlines them, design doc §1). The typed arm carries an error by
  * code. `null` when the cache holds nothing.
  */
-export declare function cacheToGridTuples(data: Tuple.GridTuple<ICell.JSON> | null | undefined): Tuple.GridTuple<Scalar> | null;
+export declare function cacheToGridTuples(data: Tuple.GridTuple<Scalar.JSON> | null | undefined): Tuple.GridTuple<Scalar> | null;
 export declare namespace ExternalBookBindings {
     interface ConstructorOptions {
         /** The collection to mirror — read fresh on every {@link ExternalBookBindings.sync}. */

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

@@ -5,7 +5,8 @@ import { Scalar } from '@sheetxl/primitives';
  *
  * @param text The formula text, without a leading `=`.
  * @returns The literal's value, or `undefined` when the text is anything else — a reference, a
- * function call, an expression, or text that does not lex at all.
+ * function call, an expression, or text that does not lex at all — or when the parser is not
+ * loaded (see `FormulaText.load`).
  *
  * @remarks
  * Backed by the calculation compiler's own lexer and literal actions (canonical locale: `.`

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

@@ -10,8 +10,13 @@ import { ICalculation } from './ICalculation';
  * symbol or evaluates anything: a sheet name is text, a function name is text, a cell is an
  * offset from the anchor.
  *
+ * The parser is loaded on demand. Await {@link load} first: until it resolves, {@link parse}
+ * answers `null` and {@link transform} returns the tree it was given, which is what each answers
+ * for text it cannot read. A calculation's start loads it too.
+ *
  * @example
  * ```ts
+ * await FormulaText.load();
  * const root = FormulaText.parse('SUM(A1:A5)', { anchor: { rowIndex: 9, colIndex: 1 } });
  * const spelled = FormulaText.transform(root!, (node) =>
  *   node.type === 'function' && node.value === 'SUM' ? { ...node, value: '_xlfn.SUM' } : undefined
@@ -47,9 +52,16 @@ export declare namespace FormulaText {
         /** Image in R1C1 rather than A1. */
         r1c1?: boolean;
     }
+    /**
+     * Loads the parser and the printer. Resolves once {@link parse}, {@link transform}, {@link image},
+     * `parseFormulaLiteral` and `FunctionDeclarations` can answer; at once if they already can.
+     */
+    function load(): Promise<void>;
+    /** Whether {@link load} has resolved, so that every function here answers. */
+    function isLoaded(): boolean;
     /**
      * Parses canonical formula text (English function names, `,` separators, no leading `=`) into
-     * its tree, or `null` when the text does not parse.
+     * its tree, or `null` when the text does not parse or the parser is not loaded.
      *
      * @remarks
      * A sheet, table or name is the text that names it; nothing is resolved. See
@@ -58,7 +70,7 @@ export declare namespace FormulaText {
     function parse(text: string, options?: ParseOptions): ICalculation.FormulaNode | null;
     /**
      * Applies a transform to a tree, post-order, and returns the transformed tree: the same object
-     * when the transform changed nothing.
+     * when the transform changed nothing, or when the parser is not loaded.
      *
      * @see {@link ICalculation.FormulaTransform}
      */
@@ -69,6 +81,7 @@ export declare namespace FormulaText {
      * @remarks
      * A `[`, `]`, `#` or `'` in the column name is escaped with `'`, which is how a formula names
      * such a column. What a reader uses to name a column it knows only by table and column name.
+     * Needs no {@link load}.
      */
     function structuredReference(tableName: string, columnName: string): string;
     /** Images a tree as text at a cell. */
@@ -76,6 +89,9 @@ export declare namespace FormulaText {
     /**
      * Prepares a tree for imaging at many cells: the tree is rebuilt once, and each call images it
      * at one cell. What a writer uses for the members of a block that share one formula.
+     *
+     * @throws When the printer is not loaded: a tree comes from {@link parse}, so {@link load} has
+     * resolved before there is one to image.
      */
     function imager(root: ICalculation.FormulaNode, options?: Omit<ImageOptions, 'at'>): (at?: IRange.CellCoords) => string;
 }

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

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

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

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