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

package/types/src/FormulaContext.d.ts

@@ -6,6 +6,7 @@ import { IFunction } from './IFunction';
 import { IFunctionArguments } from './IFunctionArguments';
 import { IFormulaContext } from './IFormulaContext';
 import { IRuntime } from './IRuntime';
+import { IRichData } from './IRichData';
 import { LocaleProfile } from './LocaleProfile';
 /**
  * Default implementation of the IFormulaContext interface.
@@ -63,6 +64,8 @@ export declare class StubbedFormulaContext implements IFormulaContext {
     getSheetCount(): number | null;
     /** @inheritdoc IFormulaContext.markVolatile */
     markVolatile(): void;
+    /** @inheritdoc IFormulaContext.defer */
+    defer(_executor: IFormulaContext.DeferExecutor, _payload?: unknown): unknown;
     /** @inheritdoc IFormulaContext.formatResults */
     formatResults(numFmt: string): void;
     /** @inheritdoc IFormulaContext.filterHidden */
@@ -94,7 +97,7 @@ export declare class StubbedFormulaContext implements IFormulaContext {
      * Unimplemented. See {@link IFormulaContext.createGrouping}.
      *
      * @remarks
-     * Grouping needs Excel's key equality, which this stub does not have.
+     * Grouping needs the engine's key equality, which this stub does not have.
      */
     createGrouping(keys: IRange, options?: IFormulaContext.GroupingOptions): IFormulaContext.Grouping;
     /**
@@ -112,15 +115,15 @@ export declare class StubbedFormulaContext implements IFormulaContext {
      * Renders a scalar as text. See {@link IFormulaContext.toText}.
      *
      * @remarks
-     * A BASIC rendering, deliberately NOT Excel's. Excel's rule -- coercion General (15
+     * A BASIC rendering, deliberately NOT the engine's. The engine's rule -- coercion General (15
      * significant digits, plain decimal while the rendering fits 20 characters, else
      * scientific) written with the workbook LOCALE's decimal separator -- is
      * `formatNumberGeneral` in `@sheetxl/sdk`, and every evaluation path reaches it through
      * the calculation context rather than through this stub. Numbers here get the plain JS
-     * rendering, which diverges from Excel on both precision and separator.
+     * rendering, which diverges from the engine on both precision and separator.
      *
      * This exists so authoring, type defs and other non-runtime access get usable text
-     * instead of throwing. Anything that needs Excel parity is running in the engine, and
+     * instead of throwing. Anything that needs the full rule is running in the engine, and
      * the engine never lands here.
      */
     toText(value: Scalar | undefined): string;
@@ -128,14 +131,14 @@ export declare class StubbedFormulaContext implements IFormulaContext {
      * Orders two scalars. See {@link IFormulaContext.compare}.
      *
      * @remarks
-     * A BASIC total order, deliberately NOT Excel's. Excel's rule -- locale collation, the word
+     * A BASIC total order, deliberately NOT the engine's. The engine's rule -- locale collation, the word
      * sort, a blank taking the other operand's type, 11-decimal numeric normalization -- is
      * `ScalarCollation` in `@sheetxl/sdk`, and every evaluation path reaches it through the
      * calculation context rather than through this stub. `options` is ignored: strength is a
      * collation concept and nothing here collates.
      *
      * This exists so authoring, type defs and other non-runtime access get a usable ordering
-     * instead of throwing. Anything that needs Excel parity is running in the engine, and the
+     * instead of throwing. Anything that needs the full rule is running in the engine, and the
      * engine never lands here.
      */
     compare(a: Scalar, b: Scalar, options?: Intl.CollatorOptions): number;
@@ -143,6 +146,8 @@ export declare class StubbedFormulaContext implements IFormulaContext {
     getRuntime(): IRuntime;
     /** @inheritdoc IFormulaContext.getArgs */
     getArgs(): IFunctionArguments;
+    /** @inheritdoc IFormulaContext.createRichData */
+    createRichData(_type: string, _data?: any): IRichData;
 }
 /**
  * The single, shared {@link IFormulaContext} that formula implementations use (via
@@ -231,6 +236,8 @@ export declare class ScopedFormulaContext implements IFormulaContext {
     getSheetCount(): number | null;
     /** @inheritdoc IFormulaContext.markVolatile */
     markVolatile(): void;
+    /** @inheritdoc IFormulaContext.defer */
+    defer(executor: IFormulaContext.DeferExecutor, payload?: unknown): unknown;
     /** @inheritdoc IFormulaContext.formatResults */
     formatResults(numFmt: string): void;
     /** @inheritdoc IFormulaContext.filterHidden */
@@ -245,6 +252,8 @@ export declare class ScopedFormulaContext implements IFormulaContext {
     compare(a: Scalar, b: Scalar, options?: Intl.CollatorOptions): number;
     /** @inheritdoc IFormulaContext.getRuntime */
     getRuntime(): IRuntime;
+    /** @inheritdoc IFormulaContext.createRichData */
+    createRichData(type: string, data?: any): IRichData;
     /** @inheritdoc IFormulaContext.getArgs */
     getArgs(): IFunctionArguments;
     get [Symbol.toStringTag](): string;

package/types/src/FormulaError.d.ts

@@ -20,7 +20,7 @@ import { IReferenceRange } from './IReferenceRange';
  *
  *  SpillErrorScalarSubType | "Unknown" | "Collision" | "IndeterminateSize" | "WorksheetEdge" | "OutOfMemoryWhileCalc" | "Table" | "MergedCell"
  * # Office 2023
- * 10. #CONNECT! This occurs when a data type is used that is not currently supported in this version of Excel.
+ * 10. #CONNECT! This occurs when a data type is used that is not currently supported.
  * 11. #BLOCKED! Indicates that an action or feature is blocked, possibly due to security settings, protected view, or other restrictions. Often related to online features, external links, or macros.
  * 12. #UNKNOWN! May be returned in the case of a protected workbook.
  * 13. #FIELD! Invalid field name for a data type.

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.
  *
@@ -29,6 +30,7 @@ import { IRuntime } from './IRuntime';
  * | Category | Key methods |
  * |---|---|
  * | Evaluation lifecycle | `markVolatile`, `getRow`, `getColumn`, `getEntireCoords`, `getRandom` |
+ * | Answering later | `defer` |
  * | Argument reflection | `getArgs` |
  * | Output hints | `formatResults` |
  * | Range construction | `createRange`, `flattenAreas`, `filterHidden` |
@@ -65,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
@@ -115,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.
      *
@@ -154,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.
@@ -558,12 +560,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.
@@ -571,8 +572,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;
     /**
@@ -588,8 +589,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
@@ -598,6 +599,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}
@@ -623,7 +683,7 @@ export declare namespace IFormulaContext {
          * then `range` is returned as it is, hidden rows included.
          *
          * @remarks
-         * This is `SUBTOTAL` 1-11 (Excel: they "include manually hidden rows", which is what an
+         * 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
@@ -748,5 +808,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`, `markVolatile`,
+         * `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

package/types/src/IFunction.d.ts

@@ -284,11 +284,9 @@ export declare namespace IFunction {
         getMembers(): readonly IFunction.IEnumMember[];
     }
     /**
-     * Describes the runtime return behavior of a function, including modifiers like
-     * async resolution, streaming data, or volatility.
+     * Describes the runtime return behavior of a function, including modifiers like volatility.
      *
      * @remarks
-     * All return type modifiers are mutually exclusive.
      * If none are specified, The value will be returned with no special behavior.
      */
     interface IReturnType extends IValueType {
@@ -300,26 +298,13 @@ export declare namespace IFunction {
          * @see {@link ReturnTypeJSON.kind}
          */
         getKind(): ValueKind | null;
-        /**
-         * Indicates the return value is a Promise or Promise-like (i.e., async).
-         * The system will mark the result as pending and re-trigger evaluation once resolved.
-         *
-         * Can be combined with any scalar, array, or range return type.
-         */
-        isAsync(): boolean;
-        /**
-         * Indicates whether the function produces a continuous stream of output (e.g., real-time data).
-         *
-         * @defaultValue `false`
-         */
-        isStreaming(): boolean;
         /**
          * True when the result can change with nothing dirty, so a cell naming this function
          * recalculates on every pass — the `Volatile<T>` marker.
          *
          * @remarks
          * STATIC, and read from the formula text at compile time: it is true of the call whether or
-         * not the call runs, which is what a lazy argument (and Excel) requires.
+         * not the call runs, which is what a lazy argument requires.
          *
          * @see {@link ReturnTypeJSON.volatile}
          */
@@ -358,7 +343,7 @@ export declare namespace IFunction {
          * @remarks
          * Only meaningful for a VARIADIC function; a fixed parameter list is already its own maximum.
          * The number is the whole CALL's argument count, prefix and optional suffix included, and it
-         * is refused where Excel refuses it — at entry, before evaluation.
+         * is refused at entry, before evaluation.
          *
          * @see {@link Repeating}
          */
@@ -660,8 +645,8 @@ export declare namespace IFunction {
          * Generated from the `NoLift<T>` marker.
          *
          * @remarks
-         * Per parameter, because Excel is: `NETWORKDAYS.INTL` refuses a reference at its date slots
-         * and lifts one at `weekend`. An ARRAY at the slot still lifts, a one-cell reference is an
+         * Per parameter, because Excel's built-ins differ by slot: `NETWORKDAYS.INTL` refuses a
+         * reference at its date slots and lifts one at `weekend`. An ARRAY at the slot still lifts, a one-cell reference is an
          * ordinary argument, and a repeating slot absorbs a container as members, so the marker only
          * ever applies to a non-repeating scalar parameter.
          */
@@ -701,7 +686,7 @@ export declare namespace IFunction {
          * union is the range arm, handed over whole. The slot never lifts.
          *
          * @remarks
-         * Excel reads a one-cell argument at some array slots as THE ARGUMENT rather than as a
+         * Some array slots read a one-cell argument as THE ARGUMENT rather than as a
          * one-cell container: `SORT(<#N/A cell>,1,1,<#DIV/0! cell>)` is `#N/A` where
          * `TAKE(<#N/A cell>,<#DIV/0! cell>)` is `#DIV/0!`. The engine's default
          * for a range slot is TAKE's; this flag is SORT's. {@link scalar} and {@link range} each carry
@@ -738,8 +723,7 @@ export declare namespace IFunction {
         members: [name: string, value: number | string, deprecated?: string | true][];
     }
     /**
-     * Describes the runtime return behavior of a function, including modifiers like
-     * async resolution, streaming data, or volatility.
+     * Describes the runtime return behavior of a function, including modifiers like volatility.
      *
      * @remarks
      * If none are specified, The value will be returned with no special behavior.
@@ -763,29 +747,15 @@ export declare namespace IFunction {
          * is a scalar is its member value downstream.
          */
         kind?: ValueKind;
-        /**
-         * Indicates the return value is a Promise or Promise-like (i.e., async).
-         * The system will mark the result as pending and re-trigger evaluation once resolved.
-         *
-         * Can be combined with any scalar, array, or range return type.
-         */
-        async?: boolean;
-        /**
-         * Indicates whether the function produces a continuous stream of output (e.g., real-time data).
-         *
-         * @defaultValue `false`
-         */
-        stream?: boolean;
         /**
          * The result can change with nothing dirty — a cell naming this function recalculates on
          * every pass. Generated from the `Volatile<T>` marker.
          *
          * @remarks
          * Collected at COMPILE time from the formula text (`CompiledFormula.hasVolatile`), because
-         * that is where Excel decides it: `=IF(TRUE,1,RAND())` recalculates on every idle pass though
+         * that is where volatility is decided: `=IF(TRUE,1,RAND())` recalculates on every idle pass though
          * no branch selects the arm, and with lazy arguments the call never happens for the engine to
-         * observe. Sits beside {@link async} and {@link stream} because all three are about WHEN a
-         * result arrives rather than what it is.
+         * observe.
          *
          * @see {@link Volatile}
          */
@@ -806,11 +776,10 @@ export declare namespace IFunction {
          * parameter. Omitted at the default of 255.
          *
          * @remarks
-         * Excel keeps one such number per NAME and compares it against the whole call's argument
-         * count in its front end, so a call past it is refused AT ENTRY rather than answered — which
-         * is why the cap lives on the declaration and not in a body. It is not derivable from the
-         * shape: `STDEV` takes 255 arguments and `STDEV.S`, the same function under its dotted name,
-         * takes 254.
+         * The cap is one number per NAME, compared against the whole call's argument count, so a call
+         * past it is refused AT ENTRY rather than answered — which is why the cap lives on the
+         * declaration and not in a body. It is not derivable from the shape: in Excel `STDEV` takes 255
+         * arguments and `STDEV.S`, the same function under its dotted name, takes 254.
          *
          * @defaultValue 255
          */

package/types/src/IFunctionArguments.d.ts

@@ -15,9 +15,8 @@ import { IFunction } from './IFunction';
  * - What was the value BEFORE the parameter's type coerced it?
  * - Was that empty slot an omission, or a blank cell the caller pointed at?
  *
- * Excel has behaviors that turn on exactly those questions, and they cluster at the
- * parameters Excel declares `any` — where there is nothing to express as a type, because Excel
- * declined to express one. `CUMIPMT` refuses a boolean at every slot while `FV` coerces one at
+ * Some functions have behaviors that turn on exactly those questions, and they cluster at
+ * parameters declared `any` — where there is nothing to express as a type. `CUMIPMT` refuses a boolean at every slot while `FV` coerces one at
  * every slot; the difference is not the values, it is that `CUMIPMT`'s slots are `any` and its
  * body decides.
  *
@@ -142,7 +141,7 @@ export interface IFunctionArguments {
      */
     getKindAt(index: number): ValueKind;
     /**
-     * True when the argument at `index` is DIRECT — Excel's "typed into the list of arguments":
+     * True when the argument at `index` is DIRECT — typed into the list of arguments:
      * the evaluated value IS a value, not a container or a callable.
      *
      * @param index The PARAMETER index — the position in the body's own signature.

package/types/src/IRange.d.ts

@@ -255,7 +255,7 @@ export interface IRange<T extends Scalar = Scalar> {
      * @remarks
      * Errors INSIDE a range are the body's to judge: the engine hands a valid range over whole and
      * never looks inside, so a function whose answer depends on every member says so with this
-     * line, placed before its own validation where Excel's error outranks it. A reshaper or a
+     * line, placed before its own validation where the member's error outranks it. A reshaper or a
      * lookup, whose members pass through or are never read, needs no line at all.
      */
     firstError(): FormulaError.Known | null;
@@ -268,7 +268,7 @@ export interface IRange<T extends Scalar = Scalar> {
      * @remarks
      * `options.axis` is the TRAVERSAL order feeding the ordinal, not the orientation of the result:
      * the result is always Nx1, and a row is `flatten().transpose()`. The default is row-major,
-     * which is the order Excel pairs two range operands in.
+     * which is the order two range operands pair in.
      *
      * `options.type` carries a read type onto the result, so a member the type filters out becomes
      * a HOLE at its ordinal rather than compacting the column. That is what lets two operands be
@@ -916,7 +916,7 @@ export declare namespace IRange {
          *
          * - By default, `broadcast()` follows strict alignment rules like NumPy and will
          *   throw an error if the input ranges cannot be broadcasted together.
-         * - When `misalignValue` is provided, `broadcast()` will instead mimic Excel behavior:
+         * - When `misalignValue` is provided, `broadcast()` will instead follow Excel's behavior:
          *   - It finds the **largest valid intersection** of the ranges.
          *   - It expands the result to the **union of both range sizes**.
          *   - Any cells that do not have valid corresponding values from the inputs
@@ -974,7 +974,7 @@ export declare namespace IRange {
          *
          * @remarks
          * Off, a dimension of 1 is a short dimension like any other and pads `misalignValue` past
-         * its one position: Excel's `MAP` rule, where a 1-row array is not stretched.
+         * its one position: the `MAP` rule, where a 1-row array is not stretched.
          */
         tile?: boolean;
         /**

package/types/src/IRangeStats.d.ts

@@ -71,7 +71,7 @@ export interface IRangeStats {
      */
     getAggregates(options?: IRange.IteratorOptions): Readonly<IRangeStats.Aggregates>;
     /**
-     * Returns the sum as Excel's `SUM` reports it — {@link getAggregates}'s `sum` with Excel's
+     * Returns the sum as `SUM` reports it — {@link getAggregates}'s `sum` with Excel's
      * cancellation-to-zero rule applied.
      *
      * @param total A total the caller accumulated across SEVERAL stats instances. Omit for a
@@ -82,7 +82,7 @@ export interface IRangeStats {
      * @remarks
      * Collapses a total to exactly zero when it lands at least 50 binary exponents below the
      * operands that produced it, so `SUM(0.1,0.2,-0.3)` is `0` rather than `5.55111512312578E-17`.
-     * Use this wherever you mean "the number Excel's SUM would show" — a status bar, a report
+     * Use this wherever you mean "the number SUM shows" — a status bar, a report
      * total, a formula. Use `getAggregates().sum` where you mean the true total of the data.
      *
      * The two genuinely differ, and neither is a rounding of the other:
@@ -92,12 +92,12 @@ export interface IRangeStats {
      *   and `PERCENTOF`, and to NOTHING else — `SUMIF`, `SUMPRODUCT`, `SERIESSUM`, `DSUM`, the
      *   `SUMX2MY2` family and every binary operator all keep the residue over the same values.
      *   That is why this is a method you call and not a change to `getAggregates`.
-     * - `AVERAGE` divides THIS, not the raw sum: snapping the mean instead is measurably wrong.
+     * - `AVERAGE` divides THIS, not the raw sum: snapping the mean instead is wrong.
      *
      * It is also cheap when it does not fire: a bound derived from `min`/`max` rejects any
      * ordinary total without re-reading the range.
      *
-     * **Multiple ranges.** Excel evaluates the rule on the *final* accumulation step, so a total
+     * **Multiple ranges.** The rule applies on the *final* accumulation step, so a total
      * spanning several ranges must be judged against the range holding the LAST value — pass the
      * running total as `total` and call this on that range. (Snapping each range separately gets
      * `SUM(A1:A3,0)` and `SUM(A1:A1,A2:A2,A3:A3)` wrong in opposite directions.) A composite
@@ -245,7 +245,7 @@ export declare namespace IRangeStats {
      * Sorting requires materializing the full numeric population (O(n log n), one allocation).
      * Unlike `Aggregates`, sorted views are **not composable across sub-ranges**.
      *
-     * Covers the following Excel functions (all share one sort per coords per calc cycle):
+     * Covers the following functions (all share one sort per coords per calc cycle):
      * - `LARGE`, `SMALL`
      * - `MEDIAN`, `PERCENTILE`, `PERCENTILE.INC`, `PERCENTILE.EXC`
      * - `QUARTILE`, `QUARTILE.INC`, `QUARTILE.EXC`  (q1 = k=0.25, q3 = k=0.75)
@@ -310,7 +310,7 @@ export declare namespace IRangeStats {
          * one outside the population is not found.
          * @param exclusive If true, uses exclusive formula (0 and 1 are excluded).
          * @param significance Number of DECIMAL PLACES to TRUNCATE the result to — despite what
-         * Excel's own help calls the argument, it is not significant digits and it does not round.
+         * Excel's help calls the argument, it is not significant digits and it does not round.
          * Truncated toward zero first (1.9 places means 1), and must be at least 1. Omit it for the
          * exact untruncated rank, which is also the only form that cannot fail.
          * @returns The percent rank of x; `null` if x is not found or there are no numbers in range.