@sheetxl/sdk 0.7.21 → 0.7.23-beta.2

package/types/src/scripting/ITypedFunction.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Provides interfaces for defining and working with functions at runtime, including metadata for
+ * function declarations and execution scripts.
+ */
+export declare namespace ITypedFunction {
+    /**
+     * Describes the execution context required by the function.
+     */
+    const Context: {
+        /**
+         * The selected workbook.
+         *
+         * @remarks
+         * `IWorkbook` will be passed as the first argument to `execute`.
+         */
+        readonly Workbook: "workbook";
+        /**
+         * The selected sheet.
+         *
+         * @remarks
+         * `ISheet` will be passed as the first argument to `execute`.
+         */
+        readonly Sheet: "sheet";
+        /**
+         * The selected ranges.
+         *
+         * @remarks
+         * `ICellRanges` will be passed as the first argument to `execute`.
+         */
+        readonly Ranges: "ranges";
+        /**
+         * The selected ranges.
+         *
+         * @remarks
+         * `ICellRange` will be passed as the first argument to `execute`.
+         */
+        readonly Range: "range";
+        /**
+         * The script context alone - no target argument.
+         *
+         * @remarks
+         * `IScript.ScriptContext` will be passed as the ONLY argument to `execute`, so the entry reads
+         * `export default function main(ctx: IScript.ScriptContext)`. The workbook is still reachable
+         * (`ctx.wb`), which is what makes this signature portable: the same one-parameter entry runs as
+         * a macro here and as a runner script on the CLI.
+         *
+         * The other contexts pass their target first and the script context after it; this one is the
+         * degenerate case where the target *is* the context.
+         */
+        readonly Script: "script";
+        /**
+         * The calculation context.
+         *
+         * @remarks
+         * `ICalculation.IContext` will be passed as the first argument to `execute`.
+         */
+        readonly Calculation: "calculation";
+    };
+    type Context = typeof Context[keyof typeof Context];
+}
+//# sourceMappingURL=ITypedFunction.d.ts.map

package/types/src/scripting/ITypedFunction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ITypedFunction.d.ts","sourceRoot":"","sources":["../../../../src/scripting/ITypedFunction.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,yBAAiB,cAAc,CAAC;IAE9B;;OAEG;IACI,MAAM,OAAO;QAClB;;;;;WAKG;;QAEH;;;;;WAKG;;QAEH;;;;;WAKG;;QAEH;;;;;WAKG;;QAEH;;;;;;;;;;;WAWG;;QAEH;;;;;WAKG;;KAEK,CAAC;IACX,KAAY,OAAO,GAAG,OAAO,OAAO,CAAC,MAAM,OAAO,OAAO,CAAC,CAAC;CAE5D"}

package/types/src/scripting/MacroFunction.d.ts

@@ -0,0 +1,15 @@
+import { IFunction, IFormulaContext } from '@sheetxl/primitives';
+import { TypedFunction } from './TypedFunction';
+export declare class MacroFunction extends TypedFunction {
+    /**
+     * When set, the compiled body is loaded lazily on first {@link execute} instead of at construction —
+     * so opening a workbook doesn't import or run the JS of macros the user hasn't invoked. Resolved once.
+     */
+    private _fnLoader?;
+    constructor(json: IFunction.DeclarationJSON, fn: (...args: any) => any, getContext: () => IFormulaContext | null | undefined, desc?: IFunction.DescriptorJSON | ((locale?: string) => Promise<IFunction.DescriptorJSON>) | null, builtIn?: boolean, fnLoader?: () => Promise<(...args: any) => any>);
+    /** Resolves the deferred compiled body (if any) and binds it as `_fn`. Safe to call repeatedly. */
+    private _ensureLoaded;
+    /** @inheritdoc IFunction.execute */
+    execute<T = any>(...args: any[]): T;
+}
+//# sourceMappingURL=MacroFunction.d.ts.map

package/types/src/scripting/MacroFunction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MacroFunction.d.ts","sourceRoot":"","sources":["../../../../src/scripting/MacroFunction.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAa3E,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAiBhD,qBAAa,aAAc,SAAQ,aAAa;IAE9C;;;OAGG;IACH,OAAO,CAAC,SAAS,CAAC,CAAuC;gBAGvD,IAAI,EAAE,SAAS,CAAC,eAAe,EAC/B,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,KAAK,GAAG,EACzB,UAAU,EAAE,MAAM,eAAe,GAAG,IAAI,GAAG,SAAS,EACpD,IAAI,GAAE,SAAS,CAAC,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,cAAc,CAAC,CAAC,GAAG,IAAW,EACvG,OAAO,GAAE,OAAa,EACtB,QAAQ,CAAC,EAAE,MAAM,OAAO,CAAC,CAAC,GAAG,IAAI,EAAE,GAAG,KAAK,GAAG,CAAC;IAYjD,mGAAmG;YACrF,aAAa;IAO3B,oCAAoC;IACpC,OAAO,CAAC,CAAC,GAAC,GAAG,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,CAAC;CA8MlC"}

package/types/src/scripting/Module.d.ts

@@ -0,0 +1,39 @@
+import { IFunction } from '@sheetxl/primitives';
+import { Diagnostic } from '@sheetxl/scripting';
+import { IListener } from '../listener/';
+import { ListenerEmitter } from '../listener/ListenerEmitter';
+import { IModule } from './IModule';
+import { IFunctionCollection } from './IFunctionCollection';
+export declare class Module implements IModule {
+    protected _json: IModule.JSON;
+    protected _functions: IFunctionCollection;
+    /** Diagnostics are NOT part of the persisted JSON artifact; they are supplied by the compile. */
+    protected _diagnostics: Diagnostic[];
+    protected _emitter: ListenerEmitter<IModule, IModule.IListeners>;
+    protected _name: string;
+    constructor(options: {
+        json: IModule.JSON;
+        readonlyFunctions: Map<string, IFunction>;
+        name: string;
+        diagnostics?: Diagnostic[];
+    });
+    /** {@inheritDoc IModule.getName} */
+    getName(): string;
+    /** {@inheritDoc IModule.getFunctions} */
+    getFunctions(): IFunctionCollection;
+    /** {@inheritDoc IModule.getSource} */
+    getSource(): string | null;
+    /** {@inheritDoc IModule.getLanguage} */
+    getLanguage(): string;
+    /** {@inheritDoc IModule.getErrors} */
+    getErrors(): any[];
+    /** {@inheritDoc IModule.getDiagnostics} */
+    getDiagnostics(): Diagnostic[];
+    /** {@inheritDoc IModule.delete} */
+    delete(): void;
+    /** {@inheritDoc IModule.addListeners} */
+    addListeners(listeners: IModule.IListeners, options?: IListener.Options): IListener.Remove;
+    /** {@inheritDoc IModule.toJSON} */
+    toJSON(): IModule.JSON;
+}
+//# sourceMappingURL=Module.d.ts.map

package/types/src/scripting/Module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Module.d.ts","sourceRoot":"","sources":["../../../../src/scripting/Module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAErD,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAE,KAAK,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAIjE,qBAAa,MAAO,YAAW,OAAO;IACpC,SAAS,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC;IAC9B,SAAS,CAAC,UAAU,EAAE,mBAAmB,CAAC;IAC1C,iGAAiG;IACjG,SAAS,CAAC,YAAY,EAAE,UAAU,EAAE,CAAC;IAErC,SAAS,CAAC,QAAQ,EAAE,eAAe,CAAC,OAAO,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;IACjE,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC;gBAEZ,OAAO,EAAE;QAAE,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC;QAAC,iBAAiB,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,UAAU,EAAE,CAAA;KAAE;IAgBhI,oCAAoC;IACpC,OAAO,IAAI,MAAM;IAIjB,yCAAyC;IACzC,YAAY,IAAI,mBAAmB;IAInC,sCAAsC;IACtC,SAAS,IAAI,MAAM,GAAG,IAAI;IAI1B,wCAAwC;IACxC,WAAW,IAAI,MAAM;IAIrB,sCAAsC;IACtC,SAAS,IAAI,GAAG,EAAE;IAIlB,2CAA2C;IAC3C,cAAc,IAAI,UAAU,EAAE;IAI9B,mCAAmC;IACnC,MAAM,IAAI,IAAI;IAId,yCAAyC;IACzC,YAAY,CAAC,SAAS,EAAE,OAAO,CAAC,UAAU,EAAE,OAAO,CAAC,EAAE,SAAS,CAAC,OAAO,GAAG,SAAS,CAAC,MAAM;IAI1F,mCAAmC;IACnC,MAAM,IAAI,OAAO,CAAC,IAAI;CAGvB"}

package/types/src/scripting/ModuleCollection.d.ts

@@ -0,0 +1,56 @@
+import { ITransaction } from '../transaction';
+import { IListener } from '../listener';
+import { ListenerEmitter } from '../listener/ListenerEmitter';
+import { IModule } from './IModule';
+import { IModuleCollection } from './IModuleCollection';
+/**
+ * Implementation for `IModuleCollection`.
+ */
+export declare class ModuleCollection implements IModuleCollection {
+    protected _emitter: ListenerEmitter<this, IModuleCollection.IListeners>;
+    private _options;
+    private _transactions;
+    private _stateId;
+    private _transactionsRemoveListener;
+    private _closed;
+    constructor(options: ModuleCollection.ConstructorOptions);
+    /** {@inheritDoc IModuleCollection.add} */
+    add(uid: string, module: IModule, options?: IModuleCollection.AddOptions): void;
+    /** {@inheritDoc ICollection.[Symbol.iterator]} */
+    [Symbol.iterator](): IterableIterator<IModule>;
+    /** {@inheritDoc IModuleCollection.getItems} */
+    getItems(options?: IModuleCollection.GetItemsOptions): IModule[];
+    /** {@inheritDoc IModuleCollection.getByName} */
+    getByName(name: string): IModule | null;
+    /** {@inheritDoc ICollection.getCount} */
+    getCount(): number;
+    /** {@inheritDoc ITransaction.ITransactional.beginCommit} */
+    beginCommit(options?: string | ITransaction.OperationOptions): ITransaction;
+    private _getState;
+    private _beginCommit;
+    private _updateState;
+    protected _initState(initial?: Record<string, IModule>): void;
+    /** {@inheritDoc IListener.ISource.addListeners} */
+    addListeners(listeners: IModuleCollection.IListeners, options?: IListener.Options): IListener.Remove;
+    /** {@inheritDoc IModuleCollection.toJSON} */
+    toJSON(): Record<string, IModule.JSON>;
+    isClosed(): boolean;
+    close(): void;
+    get isFunctionCollection(): true;
+}
+export declare namespace ModuleCollection {
+    interface ConstructorOptions {
+        /**
+         * A transaction store that can be used to undo/redo changes to the names.
+         */
+        transactions?: ITransaction.IStore;
+        /**
+         * The initial modules.
+         */
+        initial?: Record<string, IModule>;
+        /** `module` is `null` when the removal came from saving empty content. */
+        onRemove?: (moduleId: string, module: IModule | null) => void;
+        onAdd?: (moduleId: string, module: IModule) => void;
+    }
+}
+//# sourceMappingURL=ModuleCollection.d.ts.map

package/types/src/scripting/ModuleCollection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ModuleCollection.d.ts","sourceRoot":"","sources":["../../../../src/scripting/ModuleCollection.ts"],"names":[],"mappings":"AAEA,OAAO,EAAoB,KAAK,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACrE,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,aAAa,CAAC;AAI7C,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAI9D,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAE,KAAK,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAW7D;;GAEG;AAEH,qBAAa,gBAAiB,YAAW,iBAAiB;IAExD,SAAS,CAAC,QAAQ,EAAE,eAAe,CAAC,IAAI,EAAE,iBAAiB,CAAC,UAAU,CAAC,CAAC;IAExE,OAAO,CAAC,QAAQ,CAAsC;IAEtD,OAAO,CAAC,aAAa,CAAsB;IAC3C,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,2BAA2B,CAAmB;IAEtD,OAAO,CAAC,OAAO,CAAkB;gBAErB,OAAO,EAAE,gBAAgB,CAAC,kBAAkB;IAoBxD,0CAA0C;IAC1C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,iBAAiB,CAAC,UAAU,GAAG,IAAI;IA0C/E,kDAAkD;IACjD,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,gBAAgB,CAAC,OAAO,CAAC;IAI/C,+CAA+C;IAC/C,QAAQ,CAAC,OAAO,CAAC,EAAE,iBAAiB,CAAC,eAAe,GAAG,OAAO,EAAE;IAwBhE,gDAAgD;IAChD,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI;IAgBvC,yCAAyC;IACzC,QAAQ,IAAI,MAAM;IAMlB,4DAA4D;IAC5D,WAAW,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,YAAY,CAAC,gBAAgB,GAAG,YAAY;IAI3E,OAAO,CAAC,SAAS;IAMjB,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,YAAY;IAmBpB,SAAS,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAiB7D,mDAAmD;IACnD,YAAY,CAAC,SAAS,EAAE,iBAAiB,CAAC,UAAU,EAAE,OAAO,CAAC,EAAE,SAAS,CAAC,OAAO,GAAG,SAAS,CAAC,MAAM;IAIpG,6CAA6C;IAC7C,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC;IAetC,QAAQ,IAAI,OAAO;IAInB,KAAK;IASL,IAAI,oBAAoB,IAAI,IAAI,CAE/B;CACF;AAED,yBAAiB,gBAAgB,CAAC;IAChC,UAAiB,kBAAkB;QACjC;;WAEG;QACH,YAAY,CAAC,EAAE,YAAY,CAAC,MAAM,CAAC;QACnC;;WAEG;QACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAElC,0EAA0E;QAC1E,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI,KAAK,IAAI,CAAC;QAE9D,KAAK,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;KACrD;CACF"}

package/types/src/scripting/Runtime.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The global variable name the generated ambient `declare global { namespace SheetXL }` surface
+ * (`scripting.d.ts`) is authored against. At execution we install a matching runtime value here so
+ * that `SheetXL.IColor.Named.Red` / `SheetXL.ISheet.Visibility.Visible` resolve to the SAME literal
+ * the author (or AI) saw at authoring time.
+ */
+export declare const GLOBAL_SCRIPT_VARIABLE = "SheetXL";
+/**
+ * Resolve (once) the frozen runtime value of the `SheetXL` global. Async because the manifest is a
+ * runtime asset; memoized so repeated macro runs share a single load. On failure the cache is
+ * cleared so a later run can retry.
+ */
+export declare function getRuntime(): Promise<any>;
+export declare function setGlobalRuntime(): Promise<void>;
+export declare function clearGlobalRuntime(): void;
+//# sourceMappingURL=Runtime.d.ts.map

package/types/src/scripting/Runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Runtime.d.ts","sourceRoot":"","sources":["../../../../src/scripting/Runtime.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,YAAY,CAAC;AAwBhD;;;;GAIG;AACH,wBAAgB,UAAU,IAAI,OAAO,CAAC,GAAG,CAAC,CAOzC;AAGD,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAItD;AAED,wBAAgB,kBAAkB,IAAI,IAAI,CAOzC"}

package/types/src/scripting/Scripts.d.ts

@@ -0,0 +1,79 @@
+import { IFunction } from '@sheetxl/primitives';
+import { IListener } from '../listener';
+import { ListenerEmitter } from '../listener/ListenerEmitter';
+import { ITransaction } from '../transaction';
+import { IWorkbook } from '../workbook';
+import { IModule } from './IModule';
+import { IModuleCollection } from './IModuleCollection';
+import { IScript } from './IScript';
+import { IFunctionCollection } from './IFunctionCollection';
+export declare class Scripts implements IScript {
+    private _options;
+    private _modules;
+    /** In-flight {@link start} run, so concurrent callers share one attempt (and one error). */
+    private _startPromise?;
+    protected _emitter: ListenerEmitter<IScript, IScript.IListeners>;
+    constructor(options: Scripts.ConstructorOptions);
+    protected _initState(): void;
+    /** {@inheritDoc IScript.getModules} */
+    getModules(): IModuleCollection;
+    /**
+     * The names a calculation function may not take, read from the workbook's own registry.
+     *
+     * @remarks
+     * The live registry rather than the static build list: a host may bind its own functions, and
+     * only the registry knows what this workbook actually has. Custom functions are excluded - they
+     * are replaceable (re-saving a module recompiles its own functions), only built-ins are owned.
+     * An empty list simply leaves the rule off, which is what a registry that has not started yet
+     * honestly reports.
+     */
+    private _builtInNames;
+    /** {@inheritDoc IScript.createModule} */
+    createModule(options?: IModule.CompileOptions): Promise<IModule | null>;
+    /** {@inheritDoc IScript.createModule} */
+    addModule(uid: string, module: IModule, options?: IModuleCollection.AddOptions): void;
+    /** {@inheritDoc IScript.addModuleFromJSON} */
+    addModuleFromJSON(uid: string, json: IModule.JSON, options?: IModuleCollection.AddOptions): Promise<IModule>;
+    /** {@inheritDoc IScript.search} */
+    executeMacro(functionName: string, moduleId?: string, options?: IScript.RunOptions): Promise<IScript.MacroResults>;
+    /** {@inheritDoc IScript.run} */
+    run(script: string | IModule.JSON, options?: IScript.RunOptions): Promise<IScript.RunResults>;
+    /**
+     * Shared post-build half of {@link run}: surfaces compile diagnostics, finds the runnable entry, and
+     * executes it once against the workbook. `source` is used only to format diagnostic positions.
+     */
+    private _runModule;
+    /**
+     * The collections {@link searchFunctions} and {@link getFunctionCategories} span: the built-ins
+     * (when asked for) followed by each loaded module's — built-ins first, so a name they share
+     * resolves to the built-in, the way `getByName` does.
+     */
+    private _searchable;
+    /** {@inheritDoc IScript.searchFunctions} */
+    searchFunctions(options?: IScript.SearchOptions): Promise<IFunction[]>;
+    /** {@inheritDoc IScript.getFunctionCategories} */
+    getFunctionCategories(options?: IScript.GetCategoryOptions): Promise<IFunctionCollection.Category[]>;
+    /** {@inheritDoc IScript.start} */
+    start(): Promise<void>;
+    private _doStart;
+    /** {@inheritDoc IListener.ISource.addListeners} */
+    addListeners(listeners: IScript.IListeners, options?: IListener.Options): IListener.Remove;
+    /** {@inheritDoc IScript.isReadOnly} */
+    isReadOnly(): boolean;
+    /** {@inheritDoc IScript.toJSON} */
+    toJSON(): Record<string, IModule.JSON>;
+}
+export declare namespace Scripts {
+    interface ConstructorOptions {
+        /**
+         * A transaction store that can be used to undo/redo changes to the names.
+         */
+        transactions?: ITransaction.IStore;
+        json?: Record<string, IModule.JSON>;
+        workbook: IWorkbook;
+        onRemove?: (moduleId: string, module: IModule) => void;
+        onAdd?: (moduleId: string, module: IModule) => void;
+        getBuiltInFunctions?(): IFunctionCollection;
+    }
+}
+//# sourceMappingURL=Scripts.d.ts.map

package/types/src/scripting/Scripts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Scripts.d.ts","sourceRoot":"","sources":["../../../../src/scripting/Scripts.ts"],"names":[],"mappings":"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"}

package/types/src/scripting/TypedFunction.d.ts

@@ -0,0 +1,161 @@
+import { ScalarType, IRange, IFunction, IFormulaContext } from '@sheetxl/primitives';
+/**
+ * The per-call shape of a declaration that carries a repeating group, resolved from the ARGUMENT
+ * COUNT alone (`Repeating<T>`; DESIGN-ENUM §5). Excel is measured never to disambiguate by type —
+ * `SORTBY(array, by1, by2, o2)` is refused where a type-directed parse would have read argument 2
+ * as `by_array2` — so the arithmetic is the whole rule.
+ */
+interface RepeatPlan {
+    /**
+     * The parameter list the coercion loop runs against.
+     *
+     * Period 2+ expands to one entry per ARGUMENT — prefix, the slots cycled `n` times, then suffix
+     * — because each slot has its own type and each argument must bind to exactly one.
+     *
+     * Period 1 does NOT expand. It ends at a single slot marked `rest`, so the marshaller's rest
+     * branch consumes the tail exactly as `...p: T[]` always did. That is not an optimization: a
+     * reference union in a range-typed slot contributes one entry PER AREA, so the coerced count is
+     * argument count plus extra areas and no 1:1 expansion can describe it. Marshalling it as a
+     * single reference instead answers `#REF!` (PrimitiveUtils `isMultiAreaValue`), which is how
+     * `SUMPRODUCT(A1:A3,(A1:A3,C1:C3))` briefly started failing.
+     */
+    params: IFunction.ParameterTypeJSON[];
+    /** Number of parameters before the group. */
+    prefix: number;
+    /** Group period (the slot count). */
+    period: number;
+    /** Repetitions. */
+    n: number;
+    /**
+     * The last repetition dropped the group's trailing optional slot — the one short form, legal
+     * only at `n === 1` (SORTBY: arities 2 and 1+2n, nothing else).
+     */
+    short: boolean;
+    /** Period 1 hands the body `T[]`; period 2+ hands it tuples. */
+    tuples: boolean;
+}
+export declare class TypedFunction implements IFunction {
+    protected _n: string;
+    protected _d: IFunction.IDeclaration;
+    protected _p: readonly IFunction.IParameterType[];
+    protected _ct: string;
+    protected _cf: () => IFormulaContext | null | undefined;
+    protected _fn: (...args: any) => any;
+    protected _descFn: (locale?: string) => Promise<IFunction.DescriptorJSON>;
+    protected _desc: IFunction.IDescriptor | undefined;
+    /** The language the cached {@link _desc} was derived for (descriptors carry localized copy). */
+    protected _descLanguage: string | undefined;
+    protected _builtIn: boolean;
+    protected _cfp: {
+        argsValues: any[] | null;
+        argsLength: number;
+    };
+    protected _lc: boolean;
+    protected _rlc: boolean;
+    /**
+     * The declared return scalar type, normalized (`'*'`/null → null).
+     *
+     * Needed by the single-argument lift: `Range.map` clones the SOURCE range's read options, so a
+     * function whose return type differs from its parameter type would have its results read back
+     * through the parameter's coercion.
+     */
+    protected _rs: ScalarType | null;
+    protected _json: IFunction.DeclarationJSON;
+    protected _pj: IFunction.ParameterTypeJSON[] | null | undefined;
+    /** Index of the repeating-group parameter, or `-1`. */
+    protected _gi: number;
+    /** Resolved {@link RepeatPlan} per argument count (`null` = an arity the declaration refuses). */
+    protected _gc: Map<number, RepeatPlan | null> | null;
+    constructor(json: IFunction.DeclarationJSON, fn: (...args: any) => any, getContext: () => IFormulaContext | null | undefined, desc?: IFunction.DescriptorJSON | ((locale?: string) => Promise<IFunction.DescriptorJSON>) | null, builtIn?: boolean);
+    /** @inheritdoc IFunction.execute */
+    execute<R = any>(...args: any[]): R;
+    /**
+     * Resolves this call's {@link RepeatPlan} from the argument count, or `null` when the count is
+     * one the declaration refuses.
+     *
+     * `n = (argc − prefix − suffix) / period` and a non-zero remainder is an error, with ONE
+     * exception: a group whose last slot is optional also accepts `period − 1` variable arguments,
+     * which is `n = 1` with that slot omitted. Those two rules produce SORTBY's measured arities
+     * exactly — 2 and 1+2n, with 4 refused (probe rows H7/H10).
+     *
+     * A trailing suffix may be OPTIONAL, so `suffix` is solved for alongside `n` rather than fixed.
+     * SWITCH is the case: `prefix 1, period 2, one optional suffix` yields argument parity as the
+     * whole rule — odd is pairs alone, even is pairs plus a default — and refuses argc 2, because
+     * dropping the suffix still leaves the group owing its one repetition. That matches Excel row
+     * for row (probe-switch-arity.ps1: 3/4/5/6 legal, 1 and 2 refused). The group's minimum stays
+     * 1 regardless of the suffix; nothing here ever resolves `n = 0`.
+     *
+     * Period 1 ends at one rest-marked slot instead — see {@link RepeatPlan.params}.
+     *
+     * Must stay in step with `CompilerUtils.resolveRepeat`, its COMPILE-TIME twin. That one decides
+     * `#PARSE!` and the per-argument binding, so a rule added only here is simply never reached: the
+     * formula is refused before it ever executes.
+     */
+    protected _plan(argsLength: number): RepeatPlan | null;
+    /**
+     * Folds the flat, per-argument-position values back into the shape the BODY declares: the group
+     * becomes one array argument, of tuples when the period is 2+ and of bare values when it is 1
+     * (`Repeating<IRange>` hands the body `IRange[]`, the same shape a rest parameter would).
+     */
+    protected _regroup(values: any[], length: number, plan: RepeatPlan): any[];
+    /**
+     * The body of {@link execute} after argument-source resolution. Split out so the reference
+     * lift (`_refLift`) can invoke the function once per element with a substituted argument list,
+     * without re-reading the engine's fast-path slot. Safe to re-enter: the shared `_reuseCoerced`
+     * buffer is reset on entry, and the ref-lift recursion happens BEFORE this call's own coercion
+     * writes anything into it.
+     */
+    protected _exec<R = any>(argsEval: any[], argsLength: number): R;
+    /**
+     * The consumer half of the lift (CALC-ISSUES item 22 change 2). Each `refLifts` entry is a
+     * reference-only (r:'p') argument holding a producer lift's preserved per-element results.
+     * The function runs once per output cell through {@link _exec} — a full re-invocation, so
+     * every other argument re-coerces and the body re-runs per element (measured:
+     * `SUBTOTAL(9,OFFSET(A1,{0;1},0,1,1),B1:B2)` = 31|32 — the plain range is consumed WHOLE in
+     * each call). Shape rules are the scalar lift's: output dims = max over entries, dim-1 tiles,
+     * a shorter dim pads `#N/A` (probe-lift-member-coercion.ps1: 2×1 beside 1×2 → 2×2).
+     *
+     * An element that is not a reference (a plain value in a reference-only position) is not
+     * special-cased: the per-element coercion answers exactly as it would for the unlifted call
+     * (item 23b's `#PARSE!`), which becomes that member of the output.
+     */
+    protected _refLift<R>(context: IFormulaContext, argsEval: any[], argsLength: number, refLifts: RefLiftEntry[]): R;
+    /**
+     * @hidden
+     * Vends a NEW instance whose evaluation context comes from `getContext` — the public-API
+     * scope vend behind `IFunctionCollection.getByName(name, { sheet })` (CALC-ISSUES item 35).
+     * The registry instance is what the ENGINE holds and its evaluation path stays
+     * allocation-free; a vended instance additionally owns a private fast-path slot the engine
+     * never loads, so callers may hold it across awaits (or re-enter it) without racing the
+     * engine's synchronous argument hand-off.
+     */
+    _withContext(getContext: () => IFormulaContext | null | undefined): TypedFunction;
+    /** @inheritdoc IFunction.getName */
+    getName(): string;
+    /** @inheritdoc IFunction.getDeclaration */
+    getDeclaration(): IFunction.IDeclaration;
+    /** @inheritdoc IFunction.getDescriptor */
+    getDescriptor(locale?: string): Promise<IFunction.IDescriptor>;
+    /** @inheritdoc IFunction.isBuiltIn */
+    isBuiltIn(): boolean;
+    /** @inheritdoc IFunction.getContext() */
+    getContext(): string | null;
+    get [Symbol.toStringTag](): string;
+    toString(): string;
+    /** @inheritdoc IFunction.isIFunction */
+    get isIFunction(): true;
+    /** @inheritdoc ITypedFunction.isITypedFunction */
+    get isITypedFunction(): true;
+}
+type LiftedFnResults = {
+    elements: any[];
+    rows: number;
+    cols: number;
+};
+/** A reference-only argument holding preserved lift elements, found by `_exec`'s pre-pass. */
+type RefLiftEntry = LiftedFnResults & {
+    argIndex: number;
+    collapsed: IRange;
+};
+export {};
+//# sourceMappingURL=TypedFunction.d.ts.map

package/types/src/scripting/TypedFunction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TypedFunction.d.ts","sourceRoot":"","sources":["../../../../src/scripting/TypedFunction.ts"],"names":[],"mappings":"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"}

package/types/src/scripting/_FunctionIndex.d.ts

@@ -0,0 +1,111 @@
+import { IFunction } from '@sheetxl/primitives';
+/**
+ * The descriptor-derived metadata for ONE function, upper-cased once at build time so a
+ * search-as-you-type box compares against pre-folded strings rather than re-casing 400+
+ * summaries per keystroke.
+ *
+ * @remarks
+ * Everything here comes from {@link IFunction.IDescriptor}, which is **per language** — hence
+ * {@link FunctionIndex}'s per-language cache. The canonical {@link name} is the identity;
+ * {@link nameLocal} is the active pack's display name (`SUMME` for `SUM`) and equals `name`
+ * when the language does not translate it.
+ */
+export interface FunctionIndexEntry {
+    /** The function this entry describes. */
+    fn: IFunction;
+    /** The canonical name, UPPER-cased (the identity — matches the collection's map key). */
+    name: string;
+    /** The active language's display name, UPPER-cased; equals {@link name} when untranslated. */
+    nameLocal: string;
+    /** The summary, UPPER-cased. Empty when the function ships no descriptor. */
+    summary: string;
+    /** The category as the descriptor spells it — the DISPLAY form, kept verbatim. */
+    category: string;
+    /** {@link category}, UPPER-cased (category matching is case-insensitive). */
+    categoryUpper: string;
+    /** Whether the descriptor marks this deprecated/hidden (the string form is a label, still truthy). */
+    deprecated: boolean;
+}
+/** One search hit: the function, its relevance {@link scoreEntry} and the key results order by. */
+export interface FunctionMatch {
+    fn: IFunction;
+    /** LOWER is better; `0` when the search carried no text. */
+    score: number;
+    /** The canonical UPPER name — the tie-breaker, so equal scores read alphabetically. */
+    name: string;
+}
+/**
+ * The "did not match" score. Positive infinity rather than `-1` so every comparison stays a plain
+ * `<` (a lower score is a better match) and a non-match can never sort ahead of a real one.
+ */
+export declare const NO_MATCH: number;
+/**
+ * Relevance of `textUpper` against a function NAME — the ranking that needs no descriptor, so it
+ * also serves {@link rankByName} when results from several collections merge.
+ *
+ * Tiers: exact (0) → prefix (2) → substring (4). The gaps leave room for the localized name to
+ * rank one step behind its canonical counterpart in {@link scoreEntry} (exact-local 1,
+ * prefix-local 3, …) — an English `SUM` beats a German `SUMME` on the query `SUM`, but both beat
+ * a mere summary hit.
+ */
+export declare const scoreName: (nameUpper: string, textUpper: string) => number;
+/**
+ * Relevance of `textUpper` against a whole entry: the canonical name, the localized name, then the
+ * summary — {@link NO_MATCH} when none of the three contains it.
+ *
+ * @remarks
+ * Excel's Insert-Function search is a plain "contains" over name + description; the ranking is what
+ * makes typing `SUM` put `SUM` above `SUMIF` above `DSUM` above the 30-odd functions that merely
+ * mention summing. No fuzzy matching — a typo finding nothing is easier to understand than a typo
+ * finding something surprising.
+ */
+export declare const scoreEntry: (entry: FunctionIndexEntry, textUpper: string) => number;
+/** Orders matches: best score first, then alphabetically by canonical name. */
+export declare const compareMatches: (a: FunctionMatch, b: FunctionMatch) => number;
+/**
+ * Re-ranks an ALREADY-merged list (built-ins + each module's functions) by canonical name relevance.
+ *
+ * @remarks
+ * Used where the merge crosses collections and no shared index exists. Name-only by design: it must
+ * not force every collection's descriptors to load just to interleave two lists. The sort is stable,
+ * so entries with no NAME match (localized-name and summary hits) keep the order their own
+ * collection ranked them in and land after the name hits.
+ *
+ * Sorts `functions` IN PLACE (and returns it) — callers pass the freshly merged array.
+ */
+export declare const rankByName: (functions: IFunction[], textUpper: string) => IFunction[];
+/**
+ * The LAZY, per-language descriptor index behind {@link IFunctionCollection.search} and
+ * {@link IFunctionCollection.getCategories}.
+ *
+ * @remarks
+ * Descriptors are the expensive half of a function: each built-in module's copy is a separate
+ * dynamically-imported chunk, and the active language pack overlays it per field. Resolving all of
+ * them costs one import per module — worth paying for a search box, wasteful for the
+ * `getByName`/`search({ name })` lookups that dominate everything else. So this builds on FIRST
+ * descriptor-dependent search and never before:
+ *
+ * - a `name`- or `type`-only search never touches it;
+ * - the build is memoized per language, and a language switch re-derives (each function's own
+ *   `getDescriptor` cache is also per language, so re-deriving is cheap after the first time);
+ * - {@link invalidate} drops it when the collection's contents change.
+ *
+ * A function whose descriptor fails to resolve still gets an entry (name only, `Uncategorized`) —
+ * a broken descriptor must not make a function un-findable.
+ */
+export declare class FunctionIndex {
+    /** Enumerates what to index; called afresh on every build so it always sees current contents. */
+    private _source;
+    private _entries;
+    /** The language {@link _entries} was built for (and the one {@link _building} is building for). */
+    private _language;
+    /** The in-flight build, so concurrent searches share one pass rather than each starting their own. */
+    private _building;
+    constructor(source: () => Iterable<IFunction>);
+    /** Drop the cache — the collection changed. The next search rebuilds. */
+    invalidate(): void;
+    /** The indexed entries for the ACTIVE language, building (once) if needed. */
+    entries(): Promise<readonly FunctionIndexEntry[]>;
+    private _build;
+}
+//# sourceMappingURL=_FunctionIndex.d.ts.map

package/types/src/scripting/_FunctionIndex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_FunctionIndex.d.ts","sourceRoot":"","sources":["../../../../src/scripting/_FunctionIndex.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAGrD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,kBAAkB;IACjC,yCAAyC;IACzC,EAAE,EAAE,SAAS,CAAC;IACd,yFAAyF;IACzF,IAAI,EAAE,MAAM,CAAC;IACb,8FAA8F;IAC9F,SAAS,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAC;IAChB,kFAAkF;IAClF,QAAQ,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,aAAa,EAAE,MAAM,CAAC;IACtB,sGAAsG;IACtG,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,mGAAmG;AACnG,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,SAAS,CAAC;IACd,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAC;IACd,uFAAuF;IACvF,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;GAGG;AACH,eAAO,MAAM,QAAQ,QAA2B,CAAC;AAEjD;;;;;;;;GAQG;AACH,eAAO,MAAM,SAAS,GAAI,WAAW,MAAM,EAAE,WAAW,MAAM,KAAG,MAKhE,CAAC;AAKF;;;;;;;;;GASG;AACH,eAAO,MAAM,UAAU,GAAI,OAAO,kBAAkB,EAAE,WAAW,MAAM,KAAG,MAQzE,CAAC;AAEF,+EAA+E;AAC/E,eAAO,MAAM,cAAc,GAAI,GAAG,aAAa,EAAE,GAAG,aAAa,KAAG,MAGnE,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,UAAU,GAAI,WAAW,SAAS,EAAE,EAAE,WAAW,MAAM,KAAG,SAAS,EAgB/E,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,aAAa;IACxB,iGAAiG;IACjG,OAAO,CAAC,OAAO,CAA4B;IAC3C,OAAO,CAAC,QAAQ,CAA8C;IAC9D,mGAAmG;IACnG,OAAO,CAAC,SAAS,CAAuB;IACxC,sGAAsG;IACtG,OAAO,CAAC,SAAS,CAAuD;gBAE5D,MAAM,EAAE,MAAM,QAAQ,CAAC,SAAS,CAAC;IAI7C,yEAAyE;IACzE,UAAU,IAAI,IAAI;IAKlB,8EAA8E;IAC9E,OAAO,IAAI,OAAO,CAAC,SAAS,kBAAkB,EAAE,CAAC;YAoBnC,MAAM;CAgCrB"}

package/types/src/scripting/_FunctionMessages.d.ts

@@ -0,0 +1,6 @@
+export declare const ERROR_FUNCTION_REQUIRED = "Item must be specified.";
+export declare const ERROR_NO_FUNCTION_SCOPE = "No function scope.";
+export declare const ERROR_NO_SCOPED_CONTEXT = "This collection cannot vend sheet-scoped functions (no scoped-context factory).";
+export declare const ERROR_NOT_SCOPEABLE = "This function cannot be sheet-scoped.";
+export declare const ERROR_UNKNOWN_SCOPE_SHEET = "Unknown sheet for function scope.";
+//# sourceMappingURL=_FunctionMessages.d.ts.map

package/types/src/scripting/_FunctionMessages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_FunctionMessages.d.ts","sourceRoot":"","sources":["../../../../src/scripting/_FunctionMessages.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,uBAAuB,4BAA4B,CAAC;AAGjE,eAAO,MAAM,uBAAuB,uBAAuB,CAAC;AAG5D,eAAO,MAAM,uBAAuB,oFAAoF,CAAC;AAGzH,eAAO,MAAM,mBAAmB,0CAA0C,CAAC;AAG3E,eAAO,MAAM,yBAAyB,sCAAsC,CAAC"}

package/types/src/scripting/_ModuleUtils.d.ts

@@ -0,0 +1,5 @@
+import { Diagnostic } from '@sheetxl/scripting';
+import { IModule } from './IModule';
+export declare function jsonToModule(name: string, json: IModule.JSON, declarationsOnly?: boolean, diagnostics?: Diagnostic[]): Promise<IModule>;
+export declare function runAsyncGenerator<T>(generator: AsyncGenerator<any, T, any>): Promise<T>;
+//# sourceMappingURL=_ModuleUtils.d.ts.map

package/types/src/scripting/_ModuleUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_ModuleUtils.d.ts","sourceRoot":"","sources":["../../../../src/scripting/_ModuleUtils.ts"],"names":[],"mappings":"AAEA,OAAO,EAAa,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAEhE,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,WAAW,CAAC;AAmDzC,wBAAsB,YAAY,CAChC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,CAAC,IAAI,EAClB,gBAAgB,GAAE,OAAa,EAC/B,WAAW,GAAE,UAAU,EAAK,GAC3B,OAAO,CAAC,OAAO,CAAC,CAwClB;AAgBD,wBAAsB,iBAAiB,CAAC,CAAC,EAAE,SAAS,EAAE,cAAc,CAAC,GAAG,EAAE,CAAC,EAAE,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAY7F"}

package/types/src/scripting/_ScriptUtils.d.ts

@@ -0,0 +1,18 @@
+import { IRange, FormulaError, Observable, IFormulaContext } from '@sheetxl/primitives';
+export declare const _ReuseGlobalContext: {
+    FormulaContext: IFormulaContext | undefined;
+    ScalarType: {
+        readonly Number: "number";
+        readonly String: "string";
+        readonly Boolean: "boolean";
+        readonly Error: "error";
+        readonly RichData: "richData";
+        readonly Null: "null";
+    };
+    IRange: typeof IRange;
+    FormulaError: typeof FormulaError;
+    Observable: typeof Observable;
+};
+export declare function setGlobalScope(scope: Partial<IFormulaContext> | null | undefined): void;
+export declare function clearGlobalScope(): void;
+//# sourceMappingURL=_ScriptUtils.d.ts.map

package/types/src/scripting/_ScriptUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_ScriptUtils.d.ts","sourceRoot":"","sources":["../../../../src/scripting/_ScriptUtils.ts"],"names":[],"mappings":"AAAA,OAAO,EACO,MAAM,EAAE,YAAY,EAAE,UAAU,EAAE,KAAK,eAAe,EACnE,MAAM,qBAAqB,CAAC;AAQ7B,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;CAM/B,CAAC;AAUF,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,CAWvF;AAED,wBAAgB,gBAAgB,IAAI,IAAI,CAkBvC"}