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

package/browser/esm/index.mjs

@@ -1,5 +1,5 @@
 /**
-* @license @sheetxl/primitives - Primitives - Base types for SheetXL functions. - v0.8.0-beta.11
+* @license @sheetxl/primitives - Primitives - Base types for SheetXL functions. - v0.8.0-beta.12
 *
 * (C) 2026-present SheetXL Inc. & Michael T. Ford
 * License: The license can be found at https://www.sheetxl.com/license.
@@ -370,34 +370,34 @@ var v = class {
 	}
 }, y = class {
 	createRange(e, t, n) {
-		throw new S();
+		throw new C();
 	}
 	flattenAreas(e) {
-		throw new S();
+		throw new C();
 	}
 	getReference(e, t) {
-		throw new S();
+		throw new C();
 	}
 	getResizedReference(e, t, n) {
-		throw new S();
+		throw new C();
 	}
 	getNumberFormat(e, t) {
-		throw new S();
+		throw new C();
 	}
 	fromSerialDate(e, t) {
-		throw new S();
+		throw new C();
 	}
 	toSerialDate(e, t) {
-		throw new S();
+		throw new C();
 	}
 	getDateParts(e, t) {
-		throw new S();
+		throw new C();
 	}
 	getSerialDate(e, t, n, r, i, a, o) {
-		throw new S();
+		throw new C();
 	}
 	getNow() {
-		throw new S();
+		throw new C();
 	}
 	getRandom() {
 		return Math.random();
@@ -406,10 +406,10 @@ var v = class {
 		return null;
 	}
 	getEntireCoords() {
-		return C;
+		return w;
 	}
 	isValidDate(e, t) {
-		return e instanceof Date || Object.prototype.toString.call(e) === "[object Date]" ? !isNaN(e.getTime()) : !t && typeof e == "number" && !(e < 0 || e > T);
+		return e instanceof Date || Object.prototype.toString.call(e) === "[object Date]" ? !isNaN(e.getTime()) : !t && typeof e == "number" && !(e < 0 || e > E);
 	}
 	getRow() {
 		return 0;
@@ -433,6 +433,7 @@ var v = class {
 		return 1;
 	}
 	markVolatile() {}
+	defer(e, t) {}
 	formatResults(e) {}
 	filterHidden(e, t) {
 		return e;
@@ -444,22 +445,22 @@ var v = class {
 		return null;
 	}
 	getAddress(e, t) {
-		throw new S();
+		throw new C();
 	}
 	parseAsSerialDate(e, t) {
-		throw new S();
+		throw new C();
 	}
 	parseAsDate(e, t) {
-		throw new S();
+		throw new C();
 	}
 	parseAsNumber(e, t) {
-		throw new S();
+		throw new C();
 	}
 	createCriteria(e, t) {
-		throw new S();
+		throw new C();
 	}
 	createGrouping(e, t) {
-		throw new S();
+		throw new C();
 	}
 	parseAsLiteral(e) {
 		let t = e.toUpperCase();
@@ -474,10 +475,13 @@ var v = class {
 		return r === i ? e < t ? -1 : +(e > t) : r < i ? -1 : 1;
 	}
 	getRuntime() {
-		return w;
+		return T;
 	}
 	getArgs() {
-		throw new S(x);
+		throw new C(x);
+	}
+	createRichData(e, t) {
+		throw new C(S);
 	}
 }, b = (e) => {
 	if (e == null) return 0;
@@ -487,19 +491,19 @@ var v = class {
 		case "boolean": return 3;
 		default: return 4;
 	}
-}, x = "FormulaContext.getArgs() is only valid while a function body is running", S = class extends Error {
+}, x = "FormulaContext.getArgs() is only valid while a function body is running", S = "FormulaContext.createRichData() needs a workbook being calculated", C = class extends Error {
 	constructor(e = "Not implemented in StubbedFormulaContext") {
 		super(e), this.name = "NotImplementedError";
 	}
-}, C = Object.freeze({
+}, w = Object.freeze({
 	colStart: 0,
 	rowStart: 0,
 	colEnd: 2 ** 14 - 1,
 	rowEnd: 2 ** 20 - 1
-}), w = {
+}), T = {
 	isDate1904: () => !1,
-	getLocale: () => O.tag,
-	getLocaleProfile: () => O,
+	getLocale: () => k.tag,
+	getLocaleProfile: () => k,
 	isR1C1: () => !1,
 	getNow: () => 0,
 	getRandom: () => Math.random(),
@@ -508,12 +512,12 @@ var v = class {
 	getOS: () => "unknown",
 	getUser: () => "unidentified",
 	getDescription: () => "Stubbed Formula Context"
-}, T = 2958465, E = new y(), D = class {
+}, E = 2958465, D = new y(), O = class {
 	constructor() {
-		this._scope = E, this._argsFn = null;
+		this._scope = D, this._argsFn = null;
 	}
 	_setScope(e) {
-		this._scope = e ?? E;
+		this._scope = e ?? D;
 	}
 	_getScope() {
 		return this._scope;
@@ -525,7 +529,7 @@ var v = class {
 		return this._getScope().getNumberFormat(e, t);
 	}
 	getEntireCoords() {
-		return this._getScope().getEntireCoords() ?? C;
+		return this._getScope().getEntireCoords() ?? w;
 	}
 	parseAsSerialDate(e, t) {
 		return this._getScope().parseAsSerialDate(e, t);
@@ -544,7 +548,7 @@ var v = class {
 	}
 	parseAsLiteral(e) {
 		let t = this._getScope();
-		return t.parseAsLiteral ? t.parseAsLiteral(e) : E.parseAsLiteral(e);
+		return t.parseAsLiteral ? t.parseAsLiteral(e) : D.parseAsLiteral(e);
 	}
 	toText(e) {
 		return this._getScope().toText(e);
@@ -615,6 +619,9 @@ var v = class {
 	markVolatile() {
 		this._getScope().markVolatile?.();
 	}
+	defer(e, t) {
+		return this._getScope().defer?.(e, t);
+	}
 	formatResults(e) {
 		this._getScope().formatResults?.(e);
 	}
@@ -631,14 +638,18 @@ var v = class {
 		return this._getScope().getAddress(e, t);
 	}
 	compare(e, t, n) {
-		return this._getScope().compare?.(e, t, n) ?? E.compare(e, t, n);
+		return this._getScope().compare?.(e, t, n) ?? D.compare(e, t, n);
 	}
 	getRuntime() {
 		return this._getScope().getRuntime();
 	}
+	createRichData(e, t) {
+		let n = this._getScope();
+		return n.createRichData ? n.createRichData(e, t) : D.createRichData(e, t);
+	}
 	getArgs() {
 		let e = this._argsFn, t = e ? e() : null;
-		if (!t) throw new S(x);
+		if (!t) throw new C(x);
 		return t;
 	}
 	get [Symbol.toStringTag]() {
@@ -647,7 +658,7 @@ var v = class {
 	toString() {
 		return this._getScope()?.toString?.() ?? "{STUB SCOPE}";
 	}
-}, O = Object.freeze({
+}, k = Object.freeze({
 	tag: "en-US",
 	numberingSystem: "latn",
 	decimal: ".",
@@ -727,5 +738,5 @@ var v = class {
 		sensitivity: "base",
 		numeric: !0
 	})
-}), k = new D();
-export { O as DEFAULT_LOCALE_PROFILE, k as FormulaContext, i as FormulaError, t as IRange, r as IRangeStats, o as InteropScalarType, v as Observable, e as Scalar, a as ScalarType, D as ScopedFormulaContext, y as StubbedFormulaContext, s as ValueKind, u as WildCard, d as isLazyValue };
+}), A = new O();
+export { k as DEFAULT_LOCALE_PROFILE, A as FormulaContext, i as FormulaError, t as IRange, r as IRangeStats, o as InteropScalarType, v as Observable, e as Scalar, a as ScalarType, O as ScopedFormulaContext, y as StubbedFormulaContext, s as ValueKind, u as WildCard, d as isLazyValue };

package/node/esm/index.mjs

@@ -1,5 +1,5 @@
 /**
-* @license @sheetxl/primitives - Primitives - Base types for SheetXL functions. - v0.8.0-beta.11
+* @license @sheetxl/primitives - Primitives - Base types for SheetXL functions. - v0.8.0-beta.12
 *
 * (C) 2026-present SheetXL Inc. & Michael T. Ford
 * License: The license can be found at https://www.sheetxl.com/license.
@@ -225,7 +225,7 @@ var t, r, o, n, s = {
 		}
 	}
 	e.NA = g;
-	class p extends o {
+	class h extends o {
 		constructor(e, o) {
 			super(t.GettingData, r.GettingData, e, o);
 		}
@@ -233,8 +233,8 @@ var t, r, o, n, s = {
 			this.code = n.Code.GettingData;
 		}
 	}
-	e.GettingData = p;
-	class h extends o {
+	e.GettingData = h;
+	class p extends o {
 		constructor(e, o) {
 			super(t.Spill, r.Spill, e, o);
 		}
@@ -242,7 +242,7 @@ var t, r, o, n, s = {
 			this.code = n.Code.Spill;
 		}
 	}
-	e.Spill = h;
+	e.Spill = p;
 	class m extends o {
 		constructor(e, o) {
 			super(t.Connect, r.Connect, e, o);
@@ -318,13 +318,13 @@ var t, r, o, n, s = {
 }(n || (n = {}));
 var g = {};
 g[n.Code.Parse] = n.Parse, g[n.Code.Null] = n.Null, g[n.Code.Div0] = n.Div0, g[n.Code.Value] = n.Value, g[n.Code.Ref] = n.Ref, g[n.Code.Name] = n.Name, g[n.Code.Num] = n.Num, g[n.Code.NA] = n.NA, g[n.Code.GettingData] = n.GettingData, g[n.Code.Spill] = n.Spill, g[n.Code.Connect] = n.Connect, g[n.Code.Blocked] = n.Blocked, g[n.Code.Unknown] = n.Unknown, g[n.Code.Field] = n.Field, g[n.Code.Calc] = n.Calc, g[n.Code.Busy] = n.Busy, g[n.Code.Python] = n.Python, g[n.Code.Timeout] = n.Timeout;
-var p = /* @__PURE__ */ new Map(), h = /* @__PURE__ */ new Map(), m = /* @__PURE__ */ new Map(), S = /* @__PURE__ */ new Map(), C = Object.keys(g);
+var h = /* @__PURE__ */ new Map(), p = /* @__PURE__ */ new Map(), m = /* @__PURE__ */ new Map(), S = /* @__PURE__ */ new Map(), C = Object.keys(g);
 for (let e = 0; e < C.length; e++) {
 	const t = g[C[e]], r = new t();
-	m.set(r.getLabel(), t), S.set(r.getCode(), t), p.set(r.getLabel(), r), h.set(r.getCode(), r);
+	m.set(r.getLabel(), t), S.set(r.getCode(), t), h.set(r.getLabel(), r), p.set(r.getCode(), r);
 }
 (function(e) {
-	const t = e.getBuiltInByCode = (e) => h.get(e);
+	const t = e.getBuiltInByCode = (e) => p.get(e);
 	e.BuiltIn = {
 		Parse: t(n.Code.Parse),
 		Null: t(n.Code.Null),
@@ -347,7 +347,7 @@ for (let e = 0; e < C.length; e++) {
 	}, e.newTypedError = (e, t, r) => {
 		let o;
 		return o = "string" == typeof e ? m.get(e) : S.get(e), o || (o = n.Unknown), new o(t, r);
-	}, e.getBuiltInByLabel = (e) => p.get(e), e.isError = function(e, t) {
+	}, e.getBuiltInByLabel = (e) => h.get(e), e.isError = function(e, t) {
 		return !!e && !0 === e.isFormulaError && (void 0 === t || e.getCode() === t);
 	};
 })(n || (n = {}));
@@ -373,34 +373,34 @@ var w = class {
 	}
 }, f = class {
 	createRange(e, t, r) {
-		throw new b();
+		throw new D();
 	}
 	flattenAreas(e) {
-		throw new b();
+		throw new D();
 	}
 	getReference(e, t) {
-		throw new b();
+		throw new D();
 	}
 	getResizedReference(e, t, r) {
-		throw new b();
+		throw new D();
 	}
 	getNumberFormat(e, t) {
-		throw new b();
+		throw new D();
 	}
 	fromSerialDate(e, t) {
-		throw new b();
+		throw new D();
 	}
 	toSerialDate(e, t) {
-		throw new b();
+		throw new D();
 	}
 	getDateParts(e, t) {
-		throw new b();
+		throw new D();
 	}
 	getSerialDate(e, t, r, o, n, s, a) {
-		throw new b();
+		throw new D();
 	}
 	getNow() {
-		throw new b();
+		throw new D();
 	}
 	getRandom() {
 		return Math.random();
@@ -412,7 +412,7 @@ var w = class {
 		return A;
 	}
 	isValidDate(e, t) {
-		return e instanceof Date || "[object Date]" === Object.prototype.toString.call(e) ? !isNaN(e.getTime()) : !t && "number" == typeof e && !(e < 0 || e > _);
+		return e instanceof Date || "[object Date]" === Object.prototype.toString.call(e) ? !isNaN(e.getTime()) : !t && "number" == typeof e && !(e < 0 || e > R);
 	}
 	getRow() {
 		return 0;
@@ -436,6 +436,7 @@ var w = class {
 		return 1;
 	}
 	markVolatile() {}
+	defer(e, t) {}
 	formatResults(e) {}
 	filterHidden(e, t) {
 		return e;
@@ -447,22 +448,22 @@ var w = class {
 		return null;
 	}
 	getAddress(e, t) {
-		throw new b();
+		throw new D();
 	}
 	parseAsSerialDate(e, t) {
-		throw new b();
+		throw new D();
 	}
 	parseAsDate(e, t) {
-		throw new b();
+		throw new D();
 	}
 	parseAsNumber(e, t) {
-		throw new b();
+		throw new D();
 	}
 	createCriteria(e, t) {
-		throw new b();
+		throw new D();
 	}
 	createGrouping(e, t) {
-		throw new b();
+		throw new D();
 	}
 	parseAsLiteral(e) {
 		const t = e.toUpperCase();
@@ -477,10 +478,13 @@ var w = class {
 		return o !== n ? o < n ? -1 : 1 : e < t ? -1 : e > t ? 1 : 0;
 	}
 	getRuntime() {
-		return D;
+		return _;
 	}
 	getArgs() {
-		throw new b(N);
+		throw new D(N);
+	}
+	createRichData(e, t) {
+		throw new D(b);
 	}
 }, y = (e) => {
 	if (null == e) return 0;
@@ -490,7 +494,7 @@ var w = class {
 		case "boolean": return 3;
 		default: return 4;
 	}
-}, N = "FormulaContext.getArgs() is only valid while a function body is running", b = class extends Error {
+}, N = "FormulaContext.getArgs() is only valid while a function body is running", b = "FormulaContext.createRichData() needs a workbook being calculated", D = class extends Error {
 	constructor(e = "Not implemented in StubbedFormulaContext") {
 		super(e), this.name = "NotImplementedError";
 	}
@@ -499,10 +503,10 @@ var w = class {
 	rowStart: 0,
 	colEnd: Math.pow(2, 14) - 1,
 	rowEnd: Math.pow(2, 20) - 1
-}), D = {
+}), _ = {
 	isDate1904: () => !1,
-	getLocale: () => F.tag,
-	getLocaleProfile: () => F,
+	getLocale: () => T.tag,
+	getLocaleProfile: () => T,
 	isR1C1: () => !1,
 	getNow: () => 0,
 	getRandom: () => Math.random(),
@@ -511,12 +515,12 @@ var w = class {
 	getOS: () => "unknown",
 	getUser: () => "unidentified",
 	getDescription: () => "Stubbed Formula Context"
-}, _ = 2958465, R = new f(), x = class {
+}, R = 2958465, x = new f(), F = class {
 	constructor() {
-		this._scope = R, this._argsFn = null;
+		this._scope = x, this._argsFn = null;
 	}
 	_setScope(e) {
-		this._scope = e ?? R;
+		this._scope = e ?? x;
 	}
 	_getScope() {
 		return this._scope;
@@ -547,7 +551,7 @@ var w = class {
 	}
 	parseAsLiteral(e) {
 		const t = this._getScope();
-		return t.parseAsLiteral ? t.parseAsLiteral(e) : R.parseAsLiteral(e);
+		return t.parseAsLiteral ? t.parseAsLiteral(e) : x.parseAsLiteral(e);
 	}
 	toText(e) {
 		return this._getScope().toText(e);
@@ -618,6 +622,9 @@ var w = class {
 	markVolatile() {
 		this._getScope().markVolatile?.();
 	}
+	defer(e, t) {
+		return this._getScope().defer?.(e, t);
+	}
 	formatResults(e) {
 		this._getScope().formatResults?.(e);
 	}
@@ -634,14 +641,18 @@ var w = class {
 		return this._getScope().getAddress(e, t);
 	}
 	compare(e, t, r) {
-		return this._getScope().compare?.(e, t, r) ?? R.compare(e, t, r);
+		return this._getScope().compare?.(e, t, r) ?? x.compare(e, t, r);
 	}
 	getRuntime() {
 		return this._getScope().getRuntime();
 	}
+	createRichData(e, t) {
+		const r = this._getScope();
+		return r.createRichData ? r.createRichData(e, t) : x.createRichData(e, t);
+	}
 	getArgs() {
 		const e = this._argsFn, t = e ? e() : null;
-		if (!t) throw new b(N);
+		if (!t) throw new D(N);
 		return t;
 	}
 	get [Symbol.toStringTag]() {
@@ -650,7 +661,7 @@ var w = class {
 	toString() {
 		return this._getScope()?.toString?.() ?? "{STUB SCOPE}";
 	}
-}, F = Object.freeze({
+}, T = Object.freeze({
 	tag: "en-US",
 	numberingSystem: "latn",
 	decimal: ".",
@@ -730,5 +741,5 @@ var w = class {
 		sensitivity: "base",
 		numeric: !0
 	})
-}), T = new x();
-export { F as DEFAULT_LOCALE_PROFILE, T as FormulaContext, n as FormulaError, t as IRange, o as IRangeStats, a as InteropScalarType, w as Observable, e as Scalar, s as ScalarType, x as ScopedFormulaContext, f as StubbedFormulaContext, i as ValueKind, l as WildCard, d as isLazyValue };
+}), P = new F();
+export { T as DEFAULT_LOCALE_PROFILE, P as FormulaContext, n as FormulaError, t as IRange, o as IRangeStats, a as InteropScalarType, w as Observable, e as Scalar, s as ScalarType, F as ScopedFormulaContext, f as StubbedFormulaContext, i as ValueKind, l as WildCard, d as isLazyValue };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sheetxl/primitives",
   "description": "Primitives - Base types for SheetXL functions.",
-  "version": "0.8.0-beta.11",
+  "version": "0.8.0-beta.12",
   "license": "SEE LICENSE IN <LICENSE>",
   "type": "module",
   "exports": {

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 */
@@ -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/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` |
@@ -598,6 +600,64 @@ 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
+     * (`IBatchContext.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; read nothing from the formula
+     * context there. Whatever the body knows goes in the payload.
+     *
+     * @example
+     * ```typescript
+     * function fetchAll(
+     *   calls: readonly IFormulaContext.DeferredCall<string>[],
+     *   ctx: IFormulaContext.IBatchContext
+     * ): 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}
@@ -748,5 +808,66 @@ 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: IBatchContext) => 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): 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;
+    }
+    /**
+     * What an executor is given beside its calls.
+     */
+    interface IBatchContext {
+        /** 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;
+        /**
+         * 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.
+         */
+        fetch(input: string, init?: RequestInit): Promise<Response>;
+    }
 }
 //# 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,19 +298,6 @@ 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.
@@ -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,19 +747,6 @@ 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.
@@ -784,8 +755,7 @@ export declare namespace IFunction {
          * 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
          * 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}
          */

package/types/src/IRichData.d.ts

@@ -1,17 +1,24 @@
 import { Scalar } from './Scalar';
+import { IRichMeta, IRichType } from './IRichType';
 /**
  * A complex object type. This allows for more complex data types to be stored in a cell.
  */
 export interface IRichData {
     /**
-     * Reference to either a known typename or a JSON Type Definition.
-     * * {@link https://jsontypedef.com/}
+     * The value's kind: the properties it has and how they show. Every value of a kind returns the
+     * same instance.
      */
-    getType(): string;
+    getKind(): IRichType;
     /**
      * @param name The name of the property to retrieve.
      */
     getProperty(name: string): Scalar;
+    /**
+     * How the property `name` shows on this value: the value's own presentation where it differs
+     * from its kind's (a price in another currency), else the kind's ({@link IRichType.Property.meta}).
+     * `null`, or the method absent, for none.
+     */
+    getPropertyMeta?(name: string): IRichMeta | null;
     /**
      * The text shown for this value where nothing renders it: a client with no renderer for the
      * kind, a log, a placeholder. A rich text shows its text; an image a short description.
@@ -23,32 +30,48 @@ export interface IRichData {
     toString(): string;
     /**
      * The primitive this value reads as wherever one is consumed: `LEN`, `&`, `+`, comparison,
-     * `ISTEXT`, `TYPE()`, sort, filter, find. A rich text reads as its text; an image reads as
-     * nothing (`null`, or the method absent), and is `#VALUE!` wherever a primitive is needed.
+     * `ISTEXT`, `TYPE()`, sort, filter, find. A rich text reads as its text; an error that carries
+     * more than its code reads as that error; an image reads as nothing (`null`, or the method
+     * absent), and is `#VALUE!` wherever a primitive is needed.
      *
      * @remarks
-     * The ordinary rules then apply to the primitive (text-to-number coercion, collation), so a
-     * value adds no coercions of its own.
+     * The ordinary rules then apply to the primitive (text-to-number coercion, collation, error
+     * propagation), so a value adds no coercions of its own.
      */
-    toPrimitive?(): number | string | boolean | null;
+    toPrimitive?(): Exclude<Scalar, IRichData>;
     /**
      * The items this value unpacks to where a range or array is accepted (a list); `null`, or the
      * method absent, for a value that is one value.
      */
     toArray?(): Scalar[][] | null;
     /**
-     * Indicates this is an IRichData type.
+     * The value as JSON, which its kind makes it again from. A value that holds a resource (a
+     * picture's bytes) names it by the id `toResourceId` answers, and the file saves the resource;
+     * without `toResourceId` it names none.
      */
-    toJSON?(): IRichData.JSON | Promise<IRichData.JSON>;
+    toJSON?(toResourceId?: IRichData.ToResourceId): IRichData.JSON | Promise<IRichData.JSON>;
     /**
      * For runtime type checking.
      */
     get isIRichData(): true;
 }
 export declare namespace IRichData {
+    /**
+     * The id a file being saved gives a resource a value holds (an `IResource`); `null` when the
+     * file does not save it.
+     */
+    type ToResourceId = (resource: any) => number | null;
     interface JSON {
+        /** The name of the value's kind ({@link IRichType.getName}). */
         type: string;
+        /** The value's own data, as its kind reads it. */
         data?: any;
+        /**
+         * Presentation for the properties where this value differs from its kind, by property name.
+         */
+        meta?: {
+            readonly [property: string]: IRichMeta;
+        };
     }
 }
 //# sourceMappingURL=IRichData.d.ts.map

package/types/src/IRichType.d.ts

@@ -0,0 +1,139 @@
+import { Scalar } from './Scalar';
+/**
+ * The kind of a rich value: its class. A kind is a static set of typed property definitions, and
+ * every value of a kind shares the one `IRichType` its {@link IRichData.getKind} returns.
+ *
+ * @remarks
+ * For introspection: a renderer, a card, a formula editor offering `A1.` completions, or a
+ * function reading a field asks the value's kind which properties it has. What a value reads as
+ * where a primitive is consumed is the value's own answer ({@link IRichData.toPrimitive}).
+ */
+export interface IRichType {
+    /**
+     * The kind's name: what a value's JSON names as its `type`.
+     */
+    getName(): string;
+    /**
+     * The name a UI shows for the kind, such as in a list of what can be inserted. The name when the
+     * kind has no label of its own.
+     */
+    getLabel(): string;
+    /**
+     * The kind's properties, in the order the kind declares them.
+     */
+    getProperties(): readonly IRichType.Property[];
+    /**
+     * The property `name`, or `null` when the kind has none by that name.
+     */
+    getProperty(name: string): IRichType.Property | null;
+    /**
+     * The property whose value is the text a cell shows for a value of this kind, or `null` when
+     * the kind shows none (an image).
+     */
+    getDisplayProperty(): string | null;
+    /**
+     * The kind's own presentation (a card, an icon, a provider), or `null` for none.
+     */
+    getMeta(): IRichMeta | null;
+}
+export declare namespace IRichType {
+    /**
+     * What a property holds.
+     *
+     * @remarks
+     * `rich` is another rich value (a capital city, an image); `array` is an array value; `resource`
+     * is a workbook resource such as a picture's bytes.
+     */
+    type ValueType = 'number' | 'integer' | 'string' | 'boolean' | 'error' | 'rich' | 'array' | 'resource';
+    /**
+     * One property a kind declares.
+     */
+    interface Property {
+        /** The property's name. */
+        readonly name: string;
+        /** What it holds. */
+        readonly valueType: ValueType;
+        /** What it reads as on a value that holds none. Omitted, `null`. */
+        readonly defaultValue?: Scalar;
+        /** How the property shows, unless a value says otherwise. */
+        readonly meta?: IRichMeta;
+    }
+    /**
+     * A kind saved with the workbook whose values name it: one that is not registered in code, such
+     * as a kind read from a file.
+     */
+    interface JSON {
+        /** {@inheritDoc IRichType.getName} */
+        name: string;
+        /** {@inheritDoc IRichType.getLabel} */
+        label?: string;
+        /** {@inheritDoc IRichType.getProperties} */
+        properties?: readonly Property[];
+        /** {@inheritDoc IRichType.getDisplayProperty} */
+        displayProperty?: string | null;
+        /** {@inheritDoc IRichType.getMeta} */
+        meta?: IRichMeta;
+    }
+}
+/**
+ * How a rich value, or one of its properties, is presented: the number format and caption of a
+ * property, where it is offered, its sources; a kind's card, icon and provider.
+ *
+ * @remarks
+ * Presentation only, never a value. A kind gives each of its properties a default; a value gives
+ * one only for a property where it differs (a price in another currency).
+ */
+export interface IRichMeta {
+    /** The number format a number property shows in. */
+    readonly numberFormat?: string;
+    /** A short caption shown beside the property, such as its unit or the year of its data. */
+    readonly sublabel?: string;
+    /** Where the property is not offered. Each omitted entry is `false`. */
+    readonly excludeFrom?: IRichMeta.ExcludeFrom;
+    /** Where the property's data comes from and under what license. */
+    readonly attribution?: readonly IRichMeta.Attribution[];
+    /** A kind's card. */
+    readonly card?: IRichMeta.Card;
+    /** A kind's icon, by name. */
+    readonly icon?: string;
+    /** Who provides a kind's data. */
+    readonly provider?: IRichMeta.Provider;
+}
+export declare namespace IRichMeta {
+    /** Where a property is not offered. */
+    interface ExcludeFrom {
+        /** Not shown on the card. */
+        readonly cardView?: boolean;
+        /** Not offered after `A1.` in a formula. */
+        readonly dotNotation?: boolean;
+        /** Not offered by formula autocomplete. */
+        readonly autoComplete?: boolean;
+        /** A change to the property is not a change to the value. */
+        readonly calcCompare?: boolean;
+    }
+    /** One source of a property's data. */
+    interface Attribution {
+        readonly sourceText?: string;
+        readonly sourceAddress?: string;
+        readonly licenseText?: string;
+        readonly licenseAddress?: string;
+    }
+    /** A kind's card: which properties it shows, and how. */
+    interface Card {
+        /** The properties shown, in order. Omitted, the kind's order. */
+        readonly order?: readonly string[];
+        /** The property shown as the title. */
+        readonly title?: string;
+        /** The property shown under the title. */
+        readonly subTitle?: string;
+        /** The image property shown at the top. */
+        readonly mainImage?: string;
+    }
+    /** Who provides a kind's data. */
+    interface Provider {
+        readonly description?: string;
+        readonly logoSourceAddress?: string;
+        readonly logoTargetAddress?: string;
+    }
+}
+//# sourceMappingURL=IRichType.d.ts.map

package/types/src/Scalar.d.ts

@@ -46,6 +46,33 @@ export declare namespace Scalar {
      * truncation, not rounding: `1234567890.123456789` stores `…345`, never `…346`.
      */
     function truncateNumberText(text: string): string;
+    /**
+     * Encodings of `ScalarType` for persistence.
+     */
+    type JSONType = 'n' | 's' | 'b' | 'e' | 'r' | 'z';
+    /**
+     * A value encoded as a number with an associated type.
+     */
+    interface JSONTypedValue {
+        t: JSONType;
+        /**
+         * The number, string id, error code or boolean flag; for `'r'`, the rich data's own JSON
+         * (`IRichData.JSON`), which its registered kind reads back.
+         */
+        v: number | IRichData.JSON;
+    }
+    /**
+     * JSON values whose type is implied by their JavaScript type.
+     *
+     * @remarks
+     * What a string means is up to the container: a worksheet stores the id of the string in its
+     * strings collection, while an external link cache stores the string itself.
+     */
+    type JSONUnTypedValue = number | boolean | string;
+    /**
+     * For persisting a single scalar value and its type.
+     */
+    type JSON = JSONUnTypedValue | JSONTypedValue;
 }
 /**
  * Represents a cell value in JavaScript, including `Date` for convenience.

package/types/src/index.d.ts

@@ -15,6 +15,7 @@ export * from './Volatile';
 export * from './IRange';
 export * from './IReferenceRange';
 export * from './IRichData';
+export * from './IRichType';
 export * from './IFunction';
 export * from './IFormulaContext';
 export * from './IFunctionArguments';