@sheetxl/primitives 0.8.0-beta.2 → 0.8.0-beta.20

package/types/src/IFormulaContext.d.ts

@@ -5,6 +5,7 @@ import { IReferenceRange } from './IReferenceRange';
 import { IFunction } from './IFunction';
 import { IFunctionArguments } from './IFunctionArguments';
 import { IRuntime } from './IRuntime';
+import { IRichData } from './IRichData';
 /**
  * Everything a formula function is allowed to know about the world outside its arguments.
  *
@@ -28,7 +29,8 @@ import { IRuntime } from './IRuntime';
  *
  * | Category | Key methods |
  * |---|---|
- * | Evaluation lifecycle | `markVolatile`, `getRow`, `getColumn`, `getEntireCoords`, `getRandom` |
+ * | Evaluation lifecycle | `getRow`, `getColumn`, `getEntireCoords`, `getRandom` |
+ * | Answering later | `defer` |
  * | Argument reflection | `getArgs` |
  * | Output hints | `formatResults` |
  * | Range construction | `createRange`, `flattenAreas`, `filterHidden` |
@@ -37,6 +39,7 @@ import { IRuntime } from './IRuntime';
  * | Dates | `getNow`, `toSerialDate`, `fromSerialDate`, `getDateParts`, `getSerialDate`, `parseAsDate`, `parseAsSerialDate`, `isValidDate` |
  * | Coercion | `parseAsNumber`, `parseAsLiteral`, `toText`, `compare` |
  * | Criteria | `createCriteria` |
+ * | Grouping | `createPivot`, `getPivotAt` |
  * | Sheet introspection | `getSheetCount`, `getSheetIndex`, `getAddress`, `getNumberFormat` |
  *
  * ### Implementors
@@ -64,8 +67,8 @@ export interface IFormulaContext {
      * A union `(A1:A5,B1:B2)` reaches a {@link IFunction.ParameterTypeJSON.reportType} slot as one
      * `IRange` per area. Functions that answer over it do so because they walk MEMBERS and a union
      * simply has more of them — `LARGE((DA1:DA5,DK1:DK2),2)` is the second largest of all seven
-     * cells. This is that walk, and it is a helper rather than a marshalling step on purpose: Excel
-     * flattens in exactly the same place, a shared reducer its bodies opt into, which is why the
+     * cells. This is that walk, and it is a helper rather than a marshalling step on purpose:
+     * flattening is a shared reducer the bodies opt into, which is why the
      * same union is flattened by `LARGE`, refused by `SUMPRODUCT` and answered `#REF!` by `ROWS`.
      *
      * The result is a single column in area order, row-major within each area. SHAPE IS NOT
@@ -114,7 +117,7 @@ export interface IFormulaContext {
      */
     getColumn(): number;
     /**
-     * Whether the call being evaluated is in Excel's VALUE mode, where a multi-cell reference at a
+     * Whether the call being evaluated is in VALUE mode, where a multi-cell reference at a
      * slot that reads ONE value is implicitly intersected with the formula's cell (the `@` rule);
      * `false` is ARRAY mode, where such a slot reads the reference's first cell.
      *
@@ -153,7 +156,7 @@ export interface IFormulaContext {
      * A few arguments honor only their top-left corner and are re-sized to the shape of the range
      * that drives them — `SUMIF`'s `sum_range`, `LOOKUP`'s `result_vector`. The window can therefore
      * run off the bottom or right of the grid: `SUMIF(A1:A5,">0",A1048574)` asks for five rows
-     * starting three from the end. Excel reads the part that fits and treats the rest as blank, which
+     * starting three from the end. The part that fits is read and the rest is blank, which
      * is what this returns; positions past the clamp read as `undefined` from `getValueAt`.
      *
      * @param anchor The coords of the argument as written; only its top-left corner is honored.
@@ -219,16 +222,30 @@ export interface IFormulaContext {
      */
     getSheetIndex(sheet?: string | IReferenceRange): number;
     /**
-     * Returns a copy of a range with hidden rows or columns removed.
+     * Returns a range as it reads without its hidden rows or columns.
      *
      * @param range The range to filter.
-     * @param axes Which axis to filter on. Default is `IRange.AxisSelection.Row`.
-     * @returns A new range without the hidden rows or columns.
+     * @param options See {@link IFormulaContext.FilterHiddenOptions}.
+     * @returns `range` itself when nothing in it is hidden; otherwise the same range reading with
+     * the hidden rows or columns skipped ({@link IRange.IteratorOptions.processRowSkip}).
      *
      * @remarks
      * Use this for functions that ignore hidden data, such as `SUBTOTAL`.
+     *
+     * Nothing is copied. The shape of `range` is kept, and a reference stays a reference: a hidden
+     * cell is not visited and reads as empty, so every position still means the cell it meant, and
+     * an aggregate that ignores blanks ignores it. A computed array has no rows or columns to hide
+     * and is returned as it is.
+     *
+     * A hidden row is a hidden row, whoever hid it: a filter and the user leave the same mark, and
+     * nothing here tells them apart. What a filter adds is a state of the range's SHEET, which
+     * {@link IFormulaContext.FilterHiddenOptions.onlyWhileFiltered} reads.
+     *
+     * A formula that calls `SUBTOTAL` or `AGGREGATE` is recalculated when a row or column is hidden
+     * or shown, and when a filter is set or cleared. One that reaches this only through a custom
+     * function is not: it reads the state when it is next calculated.
      */
-    filterHidden(range: IRange, axes?: IRange.AxisSelection): IRange;
+    filterHidden(range: IRange, options?: IFormulaContext.FilterHiddenOptions): IRange;
     /**
      * Returns a copy of a range with any cell whose formula is a nested total removed.
      *
@@ -260,14 +277,6 @@ export interface IFormulaContext {
      * chosen one. When a range is returned every cell takes the same format.
      */
     formatResults(numFmt: string): void;
-    /**
-     * Marks this function as volatile, so it re-evaluates on every calculation.
-     *
-     * @remarks
-     * Call this when the result depends on something outside the arguments, such as the clock.
-     * A function can also be declared volatile in its registration instead.
-     */
-    markVolatile(): void;
     /**
      * Coerces a value to a serial date.
      *
@@ -333,6 +342,51 @@ export interface IFormulaContext {
      * ```
      */
     createCriteria(criteria: Scalar, options?: IFormulaContext.CriteriaOptions): IFormulaContext.CriteriaEvaluator;
+    /**
+     * Groups the records of a range two ways at once — by row keys and by column keys — at every
+     * key level of each, and crosses every row group with every column group.
+     *
+     * @param rows The row key columns, or `null` for none: every record is then in the one row group.
+     * @param columns The column key columns, or `null` for none.
+     * @param options Which records take part. See {@link IFormulaContext.PivotOptions}.
+     * @returns The two axes of groups and what their crossings hold.
+     * @throws `#VALUE!` for more than 32 key columns on one axis, or more groups and crossings than
+     * the pivot can number.
+     *
+     * @remarks
+     * Every row is a record, blank rows included. Two keys are equal by the rule `UNIQUE` uses: text
+     * ignores case, and types never mix, so `1`, `"1"` and `TRUE` are three groups. A blank key is a
+     * key of its own, distinct from `""`, and an error is a key like any other value.
+     *
+     * Each axis is a tree: its root is every kept record, the root's children are the groups of the
+     * first key column, theirs add the second, and so on, each in the order its first record appears.
+     * A subtotal is then one group, never a union of its children.
+     *
+     * One pivot answers what a grouping per key level, and another per pair of levels, would — in
+     * one pass, which is what `PIVOTBY` and a pivot table need.
+     *
+     * @example
+     * ```typescript
+     * const pivot = FormulaContext.createPivot(regions, years);
+     * for (const region of pivot.getRows().getRoot().getChildren()) {
+     *   const total = pivot.getMembers(sales, region); // every year
+     *   const [name] = region.getKeys();
+     * }
+     * ```
+     */
+    createPivot(rows: IRange | null, columns: IRange | null, options?: IFormulaContext.PivotOptions): IFormulaContext.Pivot;
+    /**
+     * The pivot table a reference touches, as the values it shows.
+     *
+     * @param reference Any cell or range of the table, its page fields included.
+     * @returns The view, or `null` when the reference touches no pivot table, or the table's values
+     * are not computed (it is not modeled, or its view has not loaded yet).
+     *
+     * @remarks
+     * What `GETPIVOTDATA` reads. The view answers for the values the table shows; matching a request
+     * to its fields and items by name is the caller's.
+     */
+    getPivotAt(reference: IReferenceRange): IFormulaContext.PivotView | null;
     /**
      * Reads a typed literal in the workbook's language — the parse side of {@link toText}.
      *
@@ -406,15 +460,14 @@ export interface IFormulaContext {
      * @remarks
      * Always read the clock through this, never `Date.now()`. The time is fixed for the whole
      * calculation pass, so every cell in one pass agrees, collaborators evaluating the same
-     * workbook agree, and tests can pin it. Pair it with {@link markVolatile} so the function
+     * workbook agree, and tests can pin it. Pair it with `Volatile<T>` so the function
      * picks up a fresh time on the next pass.
      *
      * This is a calendar clock, not a stopwatch — use `performance.now()` to measure elapsed time.
      *
      * @example
      * ```typescript
-     * export function NOW(): number {
-     *   FormulaContext.markVolatile();
+     * export function NOW(): Volatile<number> {
      *   return FormulaContext.getNow();
      * }
      * ```
@@ -516,12 +569,11 @@ export interface IFormulaContext {
      *   want the raw carry above — `DATEDIF("2020-01-31","2020-03-01","md")` is `-1`
      *   because Jan 31 rolls into March. `EDATE`/`EOMONTH` want the opposite and CLAMP to
      *   the target month's length, so they pre-clamp before calling here. One conversion,
-     *   two opposite rules, both matching Excel. Baking either one in breaks the other.
+     *   two opposite rules. Baking either one in breaks the other.
      * * **Results may legitimately leave the calendar.** `YEARFRAC` basis 1 anchors a year
      *   length on January 1 of `laterYear + 1`, which at the top of the calendar is
-     *   `10000-01-01`; Excel answers `1.9972602739726026` for
-     *   `YEARFRAC(DATE(9998,1,1),DATE(9999,12,31),1)` rather than `#NUM!`. A range check
-     *   here would break it.
+     *   `10000-01-01`; `YEARFRAC(DATE(9998,1,1),DATE(9999,12,31),1)` is
+     *   `1.9972602739726026`, not `#NUM!`. A range check here would break it.
      * * **The 16-bit argument limits are per-function.** `DATE`'s month errors outside
      *   `[-32767, 32766]` while its day saturates to `32767`, and `TIME` errors outside
      *   `[0, 32767]` on every argument — same magic number, three different rules.
@@ -529,8 +581,8 @@ export interface IFormulaContext {
      * Note the asymmetry with {@link getDateParts}, which DOES throw `#NUM!` outside the
      * calendar because it answers a user-facing question. An internal intermediate that
      * steps one day past the end must therefore not be round-tripped through it; compute
-     * on the fields instead. That mistake made `YEARFRAC(DATE(9999,1,1),DATE(9999,12,31),0)`
-     * `#NUM!` where Excel says `1`.
+     * on the fields instead, or `YEARFRAC(DATE(9999,1,1),DATE(9999,12,31),0)` becomes `#NUM!`
+     * rather than `1`.
      */
     getSerialDate(year: number, month: number, day: number, hour?: number, minute?: number, second?: number, millis?: number): number;
     /**
@@ -546,8 +598,8 @@ export interface IFormulaContext {
      *
      * @remarks
      * Argument REFLECTION, for the one thing a declaration cannot say: what happened at *this* call.
-     * It exists to serve Excel's declared `any`, which means "no contract, the body decides" — every
-     * other Excel type maps onto a type we already have and the marshaller handles it.
+     * It exists to serve a declared `any`, which means "no contract, the body decides" — every
+     * other declared type maps onto a type we already have and the marshaller handles it.
      *
      * The returned view is valid ONLY while the body that asked for it is running. Views are pooled
      * by dispatch depth, so retaining one across an `await`, a callback, or a nested evaluation hands
@@ -556,6 +608,65 @@ export interface IFormulaContext {
      * @throws If called outside a function dispatch — there are no arguments to reflect on.
      */
     getArgs(): IFunctionArguments;
+    /**
+     * Answers this call later: hands `executor` a call to settle, and leaves the cell showing what
+     * the function returns now.
+     *
+     * @param executor Runs once at the end of the recalculation with every call made against it.
+     * Pass a module-level function by name: calls join one batch when they name the same function.
+     * @param payload Everything the executor needs to answer this call, and how a later evaluation
+     * recognizes it: while the call is still waiting, a recalculation with
+     * an equal payload leaves it be rather than asking again. Once it has stopped, a recalculation
+     * calls the function again; what it fetched is answered from the workbook's cache
+     * (`IDeferContext.fetch`).
+     * @returns The last answer this call gave for the same question, when the function is being
+     * called again (a recalculation); `undefined` on a first call or a changed question. Return it
+     * to keep showing it until the new answer arrives, or return something else to show that the
+     * cell is waiting.
+     *
+     * @remarks
+     * The function still returns a value: what this call answers until its result arrives (nothing
+     * returned reads as blank), and it is what every formula over the cell calculates
+     * from meanwhile: return `#BUSY!` when they should wait as an error, or text such as
+     * `'Fetching…'` when that is what they should show.
+     *
+     * The executor runs after the recalculation, outside any cell, so the ambient `FormulaContext`
+     * is not its own: it reads the workbook through `ctx.getFormulaContext()`. Whatever the body
+     * knows about its cell goes in the payload.
+     *
+     * @example
+     * ```typescript
+     * function fetchAll(
+     *   calls: readonly IFormulaContext.DeferredCall<string>[],
+     *   ctx: IFormulaContext.IDeferContext
+     * ): void {
+     *   for (const call of calls) {
+     *     ctx.fetch(call.payload as string)
+     *       .then((response) => response.text())
+     *       .then((text) => call.resolve(text), (error) => call.reject(error));
+     *   }
+     * }
+     *
+     * export function FETCHTEXT(url: string): string {
+     *   FormulaContext.defer(fetchAll, url);
+     *   return 'Fetching…';
+     * }
+     * ```
+     */
+    defer(executor: IFormulaContext.DeferExecutor, payload?: unknown): unknown;
+    /**
+     * A rich value of a registered type, made from its data as the type's JSON holds it, for the
+     * workbook being calculated.
+     *
+     * @param type The name of the value's kind (`'hyperlink'`): what its `getKind().getName()`
+     * will answer.
+     * @param data The value's data, as its JSON's `data`.
+     *
+     * @remarks
+     * A type nobody has registered still makes a value: one that carries the data and reads as
+     * nothing.
+     */
+    createRichData(type: string, data?: any): IRichData;
 }
 /**
  * {@inheritDoc IFormulaContext}
@@ -566,6 +677,28 @@ export interface IFormulaContext {
  * {@link IFormulaContext}
  */
 export declare namespace IFormulaContext {
+    /**
+     * Options for {@link IFormulaContext.filterHidden}.
+     */
+    interface FilterHiddenOptions {
+        /**
+         * Which axis to filter on.
+         * @defaultValue `IRange.AxisSelection.Row`
+         */
+        axes?: IRange.AxisSelection;
+        /**
+         * Skip the hidden rows or columns only while the range's sheet is filtered: while some
+         * AutoFilter or table on that sheet holds a condition, whether or not it hides a row. Until
+         * then `range` is returned as it is, hidden rows included.
+         *
+         * @remarks
+         * This is `SUBTOTAL` 1-11 (they include manually hidden rows, which is what an
+         * unfiltered sheet reads as). `SUBTOTAL` 101-111 and `AGGREGATE` leave it off and skip
+         * always.
+         * @defaultValue false
+         */
+        onlyWhileFiltered?: boolean;
+    }
     /**
      * Options for {@link IFormulaContext.parseAsNumber}.
      */
@@ -599,6 +732,160 @@ export declare namespace IFormulaContext {
          */
         anchor?: 'whole' | 'start';
     }
+    /**
+     * Options for {@link IFormulaContext.createPivot}.
+     */
+    interface PivotOptions {
+        /**
+         * One column, as tall as the keys, selecting the records that take part. A record is kept
+         * when its member is `TRUE` or a nonzero number, and left out otherwise.
+         */
+        filter?: IRange;
+    }
+    /**
+     * The records of a range grouped by rows and by columns — see {@link IFormulaContext.createPivot}.
+     */
+    interface Pivot {
+        /**
+         * The number of records kept by the filter.
+         */
+        getRecordCount(): number;
+        /**
+         * The row groups.
+         */
+        getRows(): PivotAxis;
+        /**
+         * The column groups.
+         */
+        getColumns(): PivotAxis;
+        /**
+         * The members of `values` in both a row group and a column group, as one column in record order.
+         *
+         * @param values One column, as tall as the keys.
+         * @param row A group of this pivot's rows; omit it, or pass the root, for every row.
+         * @param column A group of this pivot's columns; omit it, or pass the root, for every column.
+         * @returns An array, never a reference, or `null` when no kept record is in both groups.
+         */
+        getMembers(values: IRange, row?: PivotGroup, column?: PivotGroup): IRange | null;
+        /**
+         * What `fn` returns over the members {@link getMembers} would give, computed without them.
+         *
+         * @returns `null` when no kept record is in both groups, `undefined` when the pivot does not
+         * compute `fn` this way: call `fn` over {@link getMembers} instead.
+         *
+         * @remarks
+         * Optional. Where it is present it answers for the built-in aggregates it knows (`SUM`,
+         * `COUNT`, `AVERAGE`, ...) with exactly the value the call would return, the first error
+         * member included.
+         */
+        getAggregate?(values: IRange, fn: IFunction, row?: PivotGroup, column?: PivotGroup): Scalar | null | undefined;
+    }
+    /**
+     * A pivot table as the values it shows — see {@link IFormulaContext.getPivotAt}.
+     */
+    interface PivotView {
+        /**
+         * The table's values, in its order.
+         */
+        getDataFields(): readonly PivotViewDataField[];
+        /**
+         * The fields on the table's rows, columns and pages, in that order.
+         */
+        getFields(): readonly PivotViewField[];
+        /**
+         * A value the table shows.
+         *
+         * @param dataField The value, by index into {@link getDataFields}.
+         * @param items Per field, by index into {@link getFields}, the item by index into its
+         * {@link PivotViewField.items}. A field left out is totaled over.
+         * @returns The value, or `undefined` when the table does not show it: a line it does not show
+         * (a hidden or collapsed item, a subtotal or grand total turned off), an item not on its page,
+         * or a crossing with no records.
+         */
+        getValue(dataField: number, items: ReadonlyMap<number, number>): Scalar | undefined;
+        /**
+         * Whether the table's values are known here.
+         *
+         * @returns `false` for a table that is there but whose values the host does not compute: its
+         * fields and values are empty, and a caller that answered from it before keeps that answer, as
+         * the table only changes on a refresh. Absent means `true`.
+         */
+        isComputed?(): boolean;
+    }
+    /**
+     * A value of a {@link PivotView}.
+     */
+    interface PivotViewDataField {
+        /** As the table shows it (`Sum of Sales`). */
+        readonly name: string;
+        /** The name of the source field it summarizes (`Sales`). */
+        readonly sourceName: string;
+    }
+    /**
+     * A field of a {@link PivotView}.
+     */
+    interface PivotViewField {
+        /** As the table shows it: its caption, or the source field's name. */
+        readonly name: string;
+        readonly items: readonly PivotViewItem[];
+    }
+    /**
+     * An item of a {@link PivotViewField}.
+     */
+    interface PivotViewItem {
+        /** The item's value; `null` for the blank item. */
+        readonly value: Scalar;
+        /** The value as the table shows it, in the field's number format; `(blank)` for the blank item. */
+        readonly text: string;
+        /** The caption the item was renamed to, if it was. */
+        readonly name?: string;
+    }
+    /**
+     * One axis of a {@link Pivot}: its groups at every key level, as a tree under one root.
+     */
+    interface PivotAxis {
+        /**
+         * The group of every kept record, at level `0`.
+         */
+        getRoot(): PivotGroup;
+        /**
+         * The number of groups, the root included.
+         */
+        getGroupCount(): number;
+    }
+    /**
+     * One group of a {@link PivotAxis}. The axis answers the same object for a group every time, so a
+     * group can key a map.
+     */
+    interface PivotGroup {
+        /**
+         * The number of key columns the group is keyed by: `0` for the root, `1` for the groups of the
+         * first key column, and so on.
+         */
+        getLevel(): number;
+        /**
+         * The group one level up, or `null` for the root.
+         */
+        getParent(): PivotGroup | null;
+        /**
+         * The groups one level down, in the order their first records appear.
+         */
+        getChildren(): readonly PivotGroup[];
+        /**
+         * The keys, one per level down to this group's own. Each level's key is spelled by the first
+         * record of the group at that level, so a group's keys begin with its parent's. A blank key is
+         * `null`.
+         */
+        getKeys(): readonly Scalar[];
+        /**
+         * The number of kept records in the group.
+         */
+        getSize(): number;
+        /**
+         * The row of the group's first record within the keys.
+         */
+        getFirstRecord(): number;
+    }
     /**
      * A serial date split into fields — see {@link IFormulaContext.getDateParts}.
      *
@@ -630,5 +917,150 @@ export declare namespace IFormulaContext {
          */
         readonly dow: number;
     }
+    /**
+     * Answers the calls made by {@link IFormulaContext.defer} against it. Invoked once at the end of
+     * a recalculation with every such call; how many requests that becomes is the executor's choice.
+     */
+    type DeferExecutor<T = any> = (calls: readonly DeferredCall<T>[], ctx: IDeferContext) => void | Promise<void>;
+    /**
+     * One call made by {@link IFormulaContext.defer}, as its executor receives it.
+     *
+     * @remarks
+     * Settle each call itself, never by its position in a response. An executor that returns a
+     * promise which rejects fails every call it has not settled.
+     */
+    interface DeferredCall<T = any> {
+        /** What the function passed to `defer`. */
+        readonly payload: unknown;
+        /** Settles the call with its result. */
+        resolve(value: T, options?: DeferredCall.ResolveOptions): void;
+        /** Settles the call with an error: a `FormulaError` as itself, anything else as `#VALUE!`. */
+        reject(error: unknown): void;
+        /** Runs `fn` when the result is no longer wanted. */
+        onCancel(fn: () => void): void;
+        /**
+         * Whether the result is no longer wanted. Only an executor that holds calls to settle later
+         * needs it; a result for a cancelled call is dropped.
+         */
+        readonly cancelled: boolean;
+    }
+    namespace DeferredCall {
+        /**
+         * Options for {@link DeferredCall.resolve}.
+         */
+        interface ResolveOptions {
+            /**
+             * Whether the blanks of an array result stay blank when it spills. Omitted, they read as
+             * `0`, as any spilled array's blanks do.
+             *
+             * @remarks
+             * For data whose empty fields mean "nothing here", such as an imported file. The result
+             * keeps them while a formula passes it on as it is (`IF(c, result, …)`). A function that
+             * answers element by element builds a new array, whose blanks read as `0`
+             * (`IFERROR(result, …)`, `result & ""`).
+             * @defaultValue false
+             */
+            keepBlanks?: boolean;
+        }
+    }
+    /**
+     * What an executor is given beside its calls.
+     */
+    interface IDeferContext {
+        /** A random number in `[0, 1)` from the calculation's source, which a test can seed. */
+        getRandom(): number;
+        /**
+         * State kept for this executor across recalculations, made by `init` on first ask. Keep data
+         * here (maps, numbers, strings, buffers), not connections or sockets.
+         */
+        getState<S>(init: () => S): S;
+        /**
+         * Groups `calls` by payload and runs `answer` once per distinct payload with every call that
+         * asked it: one request per question, however many cells asked.
+         *
+         * @param calls The calls to group, usually every call the executor was handed.
+         * @param answer Settles one group. When it throws, or the promise it returns rejects, the
+         * group's calls it has not settled fail with that error; the other groups are not affected.
+         * @returns Resolves once every group has been answered. It never rejects.
+         *
+         * @remarks
+         * Payloads are equal as `defer` compares them: the same primitive, or plain objects or arrays
+         * whose own values are the same one level deep. Groups are answered concurrently, in the
+         * order their first call appears.
+         *
+         * @example
+         * ```typescript
+         * async function fetchQuotes(
+         *   calls: readonly IFormulaContext.DeferredCall<number>[],
+         *   ctx: IFormulaContext.IDeferContext
+         * ): Promise<void> {
+         *   await ctx.byPayload(calls, async (ticker: string, group) => {
+         *     const response = await ctx.fetch(`https://api.example.com/quote/${ticker}`);
+         *     const price: number = (await response.json()).price;
+         *     for (const call of group) call.resolve(price);
+         *   });
+         * }
+         * ```
+         */
+        byPayload<T = any, P = unknown>(calls: readonly DeferredCall<T>[], answer: (payload: P, group: readonly DeferredCall<T>[]) => void | Promise<void>): Promise<void>;
+        /**
+         * A rich value of a registered type, for the workbook being calculated: what
+         * {@link IFormulaContext.createRichData} makes inside a cell, made here for a call's result.
+         */
+        createRichData(type: string, data?: any): IRichData;
+        /**
+         * Adds bytes to the workbook being calculated as a resource (an `IResource`), for a rich value
+         * to hold: pass it in {@link createRichData}'s data. The workbook saves it while a value holds
+         * it. With `fetchedFrom` it is the workbook's copy of that URL: {@link fetch} answers the URL
+         * from it, and adding the same URL again answers the resource already added.
+         */
+        addResource(buffer: ArrayBuffer, options?: {
+            fetchedFrom?: string;
+        }): object;
+        /**
+         * Fetches through the workbook being calculated: the standard `fetch`, answered by the
+         * fetchers the host registered for the URL's scheme, with the host's authentication. An
+         * answer the workbook already has for the URL (a picture it keeps, or anything fetched while
+         * it is open) answers from the workbook, and two calls for one URL share one request. In an
+         * external calculation (*Refresh All*) it goes to the source.
+         *
+         * Rejects when the URL cannot be reached, with a `FormulaError.Blocked` when the site responded
+         * but the browser would not let the page read it.
+         */
+        fetch(input: string, init?: RequestInit): Promise<Response>;
+        /**
+         * The formula context of the workbook being calculated, with no cell: its parsing, text,
+         * comparison and dates, read with the workbook's locale and date system.
+         *
+         * @remarks
+         * Valid for as long as the executor runs, across every `await`. The ambient `FormulaContext`
+         * is not: it belongs to the cell being evaluated, and an executor runs after that evaluation
+         * ends. What needs a cell (`getRow`, `getReference`, `getValueAt`, `defer`,
+         * `formatResults`, `getRandom`) throws here; {@link getRandom} is the executor's own.
+         */
+        getFormulaContext(): IFormulaContext;
+        /**
+         * Reads delimited text (CSV, TSV) into rows of values, each field read the way the workbook
+         * reads typed entry: numbers, dates, booleans and error labels become values, anything else
+         * stays text, and an empty field is blank.
+         *
+         * @param text The delimited text.
+         * @param options How the text is split.
+         * @returns The rows, padded with blanks to the widest row.
+         */
+        parseText(text: string, options?: IDeferContext.ParseTextOptions): Promise<Scalar[][]>;
+    }
+    namespace IDeferContext {
+        /**
+         * Options for {@link IDeferContext.parseText}.
+         */
+        interface ParseTextOptions {
+            /**
+             * The character between fields.
+             * @defaultValue `','`
+             */
+            delimiter?: string;
+        }
+    }
 }
 //# sourceMappingURL=IFormulaContext.d.ts.map