@sheetxl/sdk 0.7.21 → 0.7.23-beta.2

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

@@ -0,0 +1,208 @@
+import { IFunction } from '@sheetxl/primitives';
+import { ICollection } from '../type';
+import { IListener } from '../listener';
+/**
+ * Collections of {@link IFunction}.
+ */
+export interface IFunctionCollection extends ICollection<IFunction> {
+    /**
+     * Add a custom function to the collection.
+     *
+     * @param option Either TypeScript source, a pre-built {@link IFunction},
+     * or {@link IFunctionCollection.AddOptions}.
+     *
+     * @returns The registered function. When source is supplied and defines multiple functions, all
+     * are registered and the first (primary) one is returned.
+     */
+    add(option: string | IFunction | IFunctionCollection.AddOptions): Promise<IFunction>;
+    /**
+     * Returns functions that match the filter criteria.
+     *
+     * If no filter criteria is provided, all items will be returned.
+     *
+     * @param options {@link IFunctionCollection.SearchOptions}
+     *
+     * @remarks
+     * ### Ordering
+     * A search that reads DESCRIPTORS ({@link SearchOptions.text} / {@link SearchOptions.category},
+     * see below) returns results ordered — by relevance when there is `text`, alphabetically by
+     * canonical name otherwise. Every other search returns them in registration order.
+     *
+     * With `text`, relevance is: an exact name, then a name prefix, then a name substring, then the
+     * same three for the LOCALIZED name (each one tier behind its canonical counterpart), and finally
+     * a summary substring. Matching is case-insensitive "contains" — never fuzzy.
+     *
+     * ### Cost
+     * `name`- and `type`-only searches are a cheap scan. `text`, `category` and an explicit
+     * {@link SearchOptions.includeDeprecated} read each function's {@link IFunction.IDescriptor},
+     * which loads (once, lazily, per language) the descriptor chunk of every module — pennies for a
+     * search box, but not something to put on a hot path.
+     */
+    search(options?: IFunctionCollection.SearchOptions): Promise<IFunction[]>;
+    /**
+     * The categories the collection's functions declare, each with how many functions carry it.
+     *
+     * @param options {@link IFunctionCollection.GetCategoryOptions}
+     *
+     * @returns The categories, ordered by name. Never contains an empty category — a category exists
+     * because a function is in it.
+     *
+     * @remarks
+     * The category is a display string owned by the descriptor (`Math & Trig`, `Date & Time`, …), so
+     * this is a descriptor-reading call with the same lazy cost as a `text` search — and, being
+     * per-language, it re-derives when the language changes. It exists so a function picker can build
+     * its category list from what is actually registered (custom functions included) rather than from
+     * a hard-coded table that silently drifts.
+     */
+    getCategories(options?: IFunctionCollection.GetCategoryOptions): Promise<IFunctionCollection.Category[]>;
+    /**
+     * Convenience method for filter by name.
+     * This is functionally equivalent to getItems({ name });
+     *
+     * @param name The name to search for This is case insensitive.
+     * @param options {@link IFunctionCollection.GetByNameOptions}
+     *
+     * @remarks
+     * With `options.sheet`, returns a NEW instance bound to that sheet, for calling the function
+     * as a regular API outside the calculation graph — reference arguments and address strings
+     * resolve against the bound sheet with no evaluation current, and the instance is safe to
+     * hold across awaits. Without options, the shared registry instance is returned (the one the
+     * engine evaluates with); its reference resolution requires an active evaluation.
+     */
+    getByName(name: string, options?: IFunctionCollection.GetByNameOptions): IFunction | null;
+}
+/**
+ * {@inheritDoc IFunctionCollection}
+ * @see
+ * ### **Interface**
+ *
+ * {@link IFunctionCollection}
+ */
+export declare namespace IFunctionCollection {
+    /**
+     * Options for {@link IFunctionCollection.getByName}.
+     */
+    interface GetByNameOptions {
+        /**
+         * A sheet name to bind the returned function to. Vends a NEW instance whose evaluation
+         * context resolves references against this sheet even when no calculation is running —
+         * the public-API calling convention. Throws for an unknown sheet or a function that
+         * cannot be scoped (macros).
+         */
+        sheet?: string;
+    }
+    /**
+     * Options for searching a function in the collection.
+     */
+    interface SearchOptions {
+        /**
+         * Search with the given name. This is case insensitive.
+         */
+        name?: string;
+        /**
+         * Search all function descriptors for the given text. This is case insensitive.
+         *
+         * @remarks
+         * If this is specified this will also search the name.
+         */
+        text?: string;
+        /**
+         * Search with the given name. This is case insensitive.
+         */
+        category?: string;
+        type?: string;
+        /**
+         * Include functions their descriptor marks deprecated (or hidden).
+         *
+         * @defaultValue `false` — but only where it can be read; see the remarks.
+         *
+         * @remarks
+         * Deprecation lives in the descriptor ({@link IFunction.IDescriptor.isDeprecated}), so honoring
+         * this means loading descriptors. To keep a `name`/`type` lookup free, the filter applies only
+         * when the search is already reading them — with {@link text} or {@link category}, or when this
+         * option is passed EXPLICITLY (either value forces the read).
+         */
+        includeDeprecated?: boolean;
+        /**
+         * Return at most this many functions.
+         *
+         * @remarks
+         * Applied AFTER ordering, so a limited search is the top N by relevance — not an arbitrary N.
+         * A search box wanting "the best 50 of 400" should use this rather than slicing the result, so
+         * the caller never pays to materialize the rest.
+         */
+        limit?: number;
+    }
+    /**
+     * Options for {@link IFunctionCollection.getCategories}.
+     */
+    interface GetCategoryOptions {
+        /**
+         * Count only functions of this type (`'formula'`, `'macro'`, `'autoRun'`).
+         *
+         * @defaultValue every type.
+         */
+        type?: string;
+        /**
+         * Count functions their descriptor marks deprecated (or hidden).
+         *
+         * @defaultValue `false`
+         */
+        includeDeprecated?: boolean;
+    }
+    /**
+     * One category and its population, as returned by {@link IFunctionCollection.getCategories}.
+     */
+    interface Category {
+        /**
+         * The category as the descriptor spells it — `Math & Trig`, `Date & Time`, `Text`, …
+         *
+         * @remarks
+         * This is the IDENTITY (what {@link SearchOptions.category} matches, case-insensitively) and
+         * today it is also the display string. Localizing the label is a presentation concern: a picker
+         * maps the categories it knows to its own translated label + icon and falls back to this text
+         * for one it does not (a custom function's category, most likely).
+         */
+        name: string;
+        /** How many functions are in it, after {@link GetCategoryOptions} filtering. */
+        count: number;
+    }
+    interface Events {
+        /**
+         * Called when the collection changes.
+         *
+         * @remarks
+         * This is not used to capture individual item changes.
+         */
+        onCollectionChange?(source: IFunctionCollection): void;
+        /**
+         * Transaction items have a close event.
+         */
+        onClose?(source: IFunctionCollection): void;
+    }
+    interface IListeners extends IListener.Callbacks<IFunctionCollection, IFunctionCollection.Events> {
+    }
+    /**
+     * Add a custom function.
+     */
+    interface AddOptions {
+        /**
+         * Required.
+         *
+         * @param args
+         * @returns the value of the function.
+         */
+        execute: (args: any[]) => any;
+        /**
+         * Required.
+         */
+        declaration: IFunction.DeclarationJSON;
+        /**
+         * Configuration for UI descriptor.
+         * @param locale
+         * @returns
+         */
+        descriptor?: IFunction.DescriptorJSON | ((locale?: string) => Promise<IFunction.DescriptorJSON>);
+    }
+}
+//# sourceMappingURL=IFunctionCollection.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"IFunctionCollection.d.ts","sourceRoot":"","sources":["../../../../src/scripting/IFunctionCollection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAErD,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAE3C,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C;;GAEG;AACH,MAAM,WAAW,mBAAoB,SAAQ,WAAW,CAAC,SAAS,CAAC;IACjE;;;;;;;;OAQG;IACH,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,mBAAmB,CAAC,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IACrF;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,MAAM,CAAC,OAAO,CAAC,EAAE,mBAAmB,CAAC,aAAa,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;IAC1E;;;;;;;;;;;;;;OAcG;IACH,aAAa,CAAC,OAAO,CAAC,EAAE,mBAAmB,CAAC,kBAAkB,GAAG,OAAO,CAAC,mBAAmB,CAAC,QAAQ,EAAE,CAAC,CAAC;IACzG;;;;;;;;;;;;;OAaG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB,CAAC,gBAAgB,GAAG,SAAS,GAAG,IAAI,CAAC;CAC3F;AAED;;;;;;GAMG;AACH,yBAAiB,mBAAmB,CAAC;IAEnC;;OAEG;IACH,UAAiB,gBAAgB;QAC/B;;;;;WAKG;QACH,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB;IAED;;OAEG;IACH,UAAiB,aAAa;QAC5B;;WAEG;QACH,IAAI,CAAC,EAAE,MAAM,CAAC;QACd;;;;;WAKG;QACH,IAAI,CAAC,EAAE,MAAM,CAAC;QACd;;WAEG;QACH,QAAQ,CAAC,EAAE,MAAM,CAAC;QAGlB,IAAI,CAAC,EAAE,MAAM,CAAC;QAId;;;;;;;;;;WAUG;QACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;QAC5B;;;;;;;WAOG;QACH,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB;IAED;;OAEG;IACH,UAAiB,kBAAkB;QACjC;;;;WAIG;QACH,IAAI,CAAC,EAAE,MAAM,CAAC;QACd;;;;WAIG;QACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;KAC7B;IAED;;OAEG;IACH,UAAiB,QAAQ;QACvB;;;;;;;;WAQG;QACH,IAAI,EAAE,MAAM,CAAC;QACb,gFAAgF;QAChF,KAAK,EAAE,MAAM,CAAC;KACf;IAED,UAAiB,MAAM;QACrB;;;;;WAKG;QACH,kBAAkB,CAAC,CAAC,MAAM,EAAE,mBAAmB,GAAG,IAAI,CAAC;QACvD;;WAEG;QACH,OAAO,CAAC,CAAC,MAAM,EAAE,mBAAmB,GAAG,IAAI,CAAC;KAC7C;IAED,UAAiB,UAAW,SAAQ,SAAS,CAAC,SAAS,CAAC,mBAAmB,EAAE,mBAAmB,CAAC,MAAM,CAAC;KAAG;IAE3G;;OAEG;IAGH,UAAiB,UAAU;QACzB;;;;;WAKG;QACH,OAAO,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC;QAC9B;;WAEG;QACH,WAAW,EAAE,SAAS,CAAC,eAAe,CAAC;QACvC;;;;WAIG;QACH,UAAU,CAAC,EAAE,SAAS,CAAC,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,cAAc,CAAC,CAAC,CAAC;KAClG;CACF"}

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

@@ -0,0 +1,82 @@
+import { CompileOptions as _CompileOptions, CompileResult as _CompileResult, CompiledModule, Diagnostic as _Diagnostic } from '@sheetxl/scripting';
+import { IListener } from '../listener';
+import { IFunctionCollection } from './IFunctionCollection';
+/**
+ * Represents a collection of functions. This is analogous to a file.
+ */
+export interface IModule {
+    /**
+     * Returns the functions in the module.
+     *
+     * @remarks
+     * This maybe be empty even if there is source. It is possible that a script might contain only comments or other non-executable code.
+     */
+    getFunctions(): IFunctionCollection;
+    /**
+     * The human-readable source code of the script.
+     *
+     * @remarks
+     * If this property is null, the module may still have compiled functions.
+     */
+    getSource(): string | null;
+    /**
+     * The language the function is written in.
+     */
+    getLanguage(): string;
+    /**
+     * Returns the error-severity diagnostics for the module (a subset of {@link IModule.getDiagnostics}).
+     */
+    getErrors(): any[];
+    /**
+     * Returns all positioned diagnostics (errors + warnings) produced when the module was compiled.
+     */
+    getDiagnostics(): _Diagnostic[];
+    getId?(): string;
+    /**
+     * The name of the module.
+     */
+    getName(): string;
+    /**
+     * Remove the module from the collection.
+     */
+    delete(): void;
+    /**
+     * Returns a JSON representation of the module.
+     */
+    toJSON(): IModule.JSON;
+    addListeners(listeners: IModule.IListeners, options?: IListener.Options): IListener.Remove;
+}
+/**
+ * {@inheritDoc IModule}
+ * @see
+ * ### **Interface**
+ *
+ * {@link IModule}
+ */
+export declare namespace IModule {
+    /**
+     * Results for compiling a module.
+     */
+    type CompileResult = _CompileResult;
+    /**
+     * Options for compiling a module.
+     */
+    type CompileOptions = _CompileOptions;
+    /**
+     * Used to serialize a module.
+     */
+    type JSON = CompiledModule;
+    /**
+     * A positioned compile diagnostic (error or warning).
+     */
+    type Diagnostic = _Diagnostic;
+    interface Events {
+        /**
+         * When delete is called
+         */
+        onDelete?(source: IModule): void;
+    }
+    interface IListeners extends IListener.Callbacks<IModule, IModule.Events> {
+    }
+}
+//# sourceMappingURL=IModule.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"IModule.d.ts","sourceRoot":"","sources":["../../../../src/scripting/IModule.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,cAAc,IAAI,eAAe,EACtC,KAAK,aAAa,IAAI,cAAc,EACpC,KAAK,cAAc,EAAE,KAAK,UAAU,IAAI,WAAW,EACpD,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,KAAK,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAEjE;;GAEG;AACH,MAAM,WAAW,OAAO;IACtB;;;;;OAKG;IACH,YAAY,IAAI,mBAAmB,CAAC;IACpC;;;;;OAKG;IACH,SAAS,IAAI,MAAM,GAAG,IAAI,CAAC;IAC3B;;OAEG;IACH,WAAW,IAAI,MAAM,CAAC;IAEtB;;OAEG;IACH,SAAS,IAAI,GAAG,EAAE,CAAC;IAEnB;;OAEG;IACH,cAAc,IAAI,WAAW,EAAE,CAAC;IAEhC,KAAK,CAAC,IAAI,MAAM,CAAC;IACjB;;OAEG;IACH,OAAO,IAAI,MAAM,CAAC;IAElB;;OAEG;IACH,MAAM,IAAI,IAAI,CAAC;IAEf;;OAEG;IACH,MAAM,IAAK,OAAO,CAAC,IAAI,CAAC;IAExB,YAAY,CAAC,SAAS,EAAE,OAAO,CAAC,UAAU,EAAE,OAAO,CAAC,EAAE,SAAS,CAAC,OAAO,GAAG,SAAS,CAAC,MAAM,CAAC;CAK5F;AAED;;;;;;GAMG;AACH,yBAAiB,OAAO,CAAC;IAEvB;;OAEG;IACH,KAAY,aAAa,GAAG,cAAc,CAAC;IAE3C;;OAEG;IACH,KAAY,cAAc,GAAG,eAAe,CAAC;IAE7C;;OAEG;IACH,KAAY,IAAI,GAAG,cAAc,CAAC;IAElC;;OAEG;IACH,KAAY,UAAU,GAAG,WAAW,CAAC;IAErC,UAAiB,MAAM;QACrB;;WAEG;QACH,QAAQ,CAAC,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;KAClC;IAED,UAAiB,UAAW,SAAQ,SAAS,CAAC,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC;KAAG;CACpF"}

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

@@ -0,0 +1,79 @@
+import { ICollection } from '../type';
+import { IListener } from '../listener';
+import { IModule } from './IModule';
+/**
+ * Represents a collection of functions. This is analogous to a file.
+ */
+export interface IModuleCollection extends ICollection<IModule> {
+    /**
+     * Adds the module to the collection.
+     *
+     * @param uid A unique identifier for the module. This can be either a name, a fully qualified path, or a url (e.g., a file name, a Git url with commit ID).
+     * @param module The module to add. This will generally come from IScript.createModule.
+     * @param options The options for adding the module.
+     */
+    add(uid: string, module: IModule, options?: IModuleCollection.AddOptions): void;
+    /**
+     * Returns functions that match the filter criteria.
+     *
+     * If no filter criteria is provided, all items will be returned.
+     *
+     * @param options {@link IModuleCollection.GetItemsOptions}
+     */
+    getItems(options?: IModuleCollection.GetItemsOptions): IModule[];
+    /**
+     * Convenience method for filtering by name.
+     * This is functionally equivalent to getItems({ name });
+     *
+     * @param name The name to search for This is case insensitive.
+     */
+    getByName(name: string): IModule | null;
+    /**
+     * Add Listeners.
+     *
+     * @see
+     * {@link IListener.ISource.addListeners}
+     */
+    addListeners(listeners: IModuleCollection.IListeners, options?: IListener.Options): IListener.Remove;
+    /**
+     * Returns a JSON representation of the module collection.
+     */
+    toJSON(): Record<string, IModule.JSON>;
+}
+export declare namespace IModuleCollection {
+    interface AddOptions {
+        /**
+         * If true, the module will be added to the collection even if it already exists.
+         */
+        replace?: boolean;
+        /**
+         * If true, the module will be added to the collection even if it has errors.
+         */
+        ignoreErrors?: boolean;
+    }
+    /**
+   * Options for filtering a function in the collection.
+   */
+    interface GetItemsOptions extends ICollection.GetItemsOptions {
+        /**
+         * Search with the given name. This is case insensitive.
+         */
+        name?: string;
+    }
+    interface Events {
+        /**
+         * Called when the collection changes.
+         *
+         * @remarks
+         * This is not used to capture individual item changes.
+         */
+        onCollectionChange?(source: IModuleCollection): void;
+        /**
+         * Transaction items have a close event.
+         */
+        onClose?(source: IModuleCollection): void;
+    }
+    interface IListeners extends IListener.Callbacks<IModuleCollection, IModuleCollection.Events> {
+    }
+}
+//# sourceMappingURL=IModuleCollection.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"IModuleCollection.d.ts","sourceRoot":"","sources":["../../../../src/scripting/IModuleCollection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAC3C,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC;;GAEG;AACH,MAAM,WAAW,iBAAkB,SAAQ,WAAW,CAAC,OAAO,CAAC;IAC7D;;;;;;OAMG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,iBAAiB,CAAC,UAAU,GAAG,IAAI,CAAC;IAChF;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,iBAAiB,CAAC,eAAe,GAAG,OAAO,EAAE,CAAC;IACjE;;;;;OAKG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;IACxC;;;;;OAKG;IACH,YAAY,CAAC,SAAS,EAAE,iBAAiB,CAAC,UAAU,EAAE,OAAO,CAAC,EAAE,SAAS,CAAC,OAAO,GAAG,SAAS,CAAC,MAAM,CAAC;IAErG;;OAEG;IACH,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC;AAED,yBAAiB,iBAAiB,CAAC;IACjC,UAAiB,UAAU;QACzB;;WAEG;QAEH,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB;;WAEG;QACH,YAAY,CAAC,EAAE,OAAO,CAAC;KACxB;IAEC;;KAEC;IACH,UAAiB,eAAgB,SAAQ,WAAW,CAAC,eAAe;QAClE;;WAEG;QACH,IAAI,CAAC,EAAE,MAAM,CAAC;KAGf;IAED,UAAiB,MAAM;QACrB;;;;;WAKG;QACH,kBAAkB,CAAC,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAAC;QACrD;;WAEG;QACH,OAAO,CAAC,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAAC;KAC3C;IAED,UAAiB,UAAW,SAAQ,SAAS,CAAC,SAAS,CAAC,iBAAiB,EAAE,iBAAiB,CAAC,MAAM,CAAC;KAAG;CACxG"}

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

@@ -0,0 +1,289 @@
+import { IFunction } from '@sheetxl/primitives';
+import { ILogger, LogRenderer } from '@sheetxl/utils';
+import { IListener } from '../listener';
+import { IWorkbook } from '../workbook';
+import { ITransaction } from '../transaction';
+import { IFunctionCollection } from './IFunctionCollection';
+import { IModule } from './IModule';
+import { IModuleCollection } from './IModuleCollection';
+/**
+ * Contains interfaces for working with scripts.
+ *
+ * @remarks
+ * Scripts are collections of modules that contain functions.
+ *
+ * Modules are analogous to files, and functions are the executable code within those modules.
+ */
+export interface IScript {
+    /**
+     * Returns a collection of modules.
+     */
+    getModules(): IModuleCollection;
+    /**
+     * Creates a module from the source code.
+     *
+     * @param options
+     */
+    createModule(options?: IModule.CompileOptions): Promise<IModule | null>;
+    /**
+     * Adds a module to the script.
+     * @param uid
+     * @param module
+     * @param options
+     */
+    addModule(uid: string, module: IModule, options?: IModuleCollection.AddOptions): void;
+    /**
+     * Registers a **pre-compiled** module from its {@link IModule.JSON} (the execute-half of
+     * {@link createModule}, with NO TypeScript compiler loaded).
+     *
+     * @remarks
+     * Builds the module via the compiler-free `data:` URL path (same as {@link run} with a `IModule.JSON`) and adds it
+     * to the collection. This is how a CSP-restricted host (the VS Code webview, which cannot compile)
+     * persists an edited macro into the live workbook: the editor compiles on Node and ships the
+     * compiled module here to register.
+     *
+     * @param uid Stable id the module is stored/serialized under.
+     * @param json A compiled module ({@link IModule.JSON}) — the `module` of a `CompileResult`.
+     * @param options {@link IModuleCollection.AddOptions}
+     */
+    addModuleFromJSON(uid: string, json: IModule.JSON, options?: IModuleCollection.AddOptions): Promise<IModule>;
+    /**
+     * Executes a macro function - the **user-invoked** entry point.
+     *
+     * @remarks
+     * The macro's target comes from the selection (the sheet, the ranges, the range - whichever its
+     * first parameter declares), and so does where its result goes: a returned value is written into
+     * the selection ({@link IScript.RunOptions.applyResult}, on by default here and only here). To run
+     * a script for its *answer* rather than its effect, use {@link run}.
+     *
+     * @param functionName The name of the function to execute.
+     * @param moduleId The ID of the module containing the function.
+     * @param options {@link IScript.RunOptions}
+     */
+    executeMacro(functionName: string, moduleId?: string, options?: IScript.RunOptions): Promise<IScript.MacroResults>;
+    /**
+     * Runs a script's entry once against the workbook - the "make a change" primitive.
+     *
+     * @remarks
+     * Unlike {@link IFunctionCollection.add} (which registers a reusable function), this is a one-shot:
+     * the entry runs inside a single transaction and nothing is registered. That transaction becomes
+     * an undo entry only if the entry actually wrote something - a run that only reads elides, so
+     * there is no commit id, no event and nothing on the undo stack. The entry's return value is the
+     * caller's *result*: it is reported back, never written into the workbook (contrast
+     * {@link executeMacro}, the user-invoked path, which puts it at the selection). The entry
+     * is the default export, authored as `export default function (ctx: IScript.ScriptContext) { ... }`
+     * — one parameter, with the workbook as `ctx.wb`. A macro that wants "the selected" sheet/range
+     * instead takes that target first and the context second (`(sheet: ISheet, ctx)`).
+     * Changes are made via the workbook API in the body; observation is via `ctx.log`.
+     *
+     * Accepts either form of the same script:
+     * - **source** (`string`) — TypeScript, compiled here (needs the TS compiler).
+     * - **compiled** ({@link IModule.JSON}) — an already-compiled module, run with NO compiler. This is
+     *   the CSP-safe path for hosts that compile elsewhere: the VS Code webview's CSP blocks the
+     *   CDN-loaded compiler, so the MCP server compiles on Node and ships the compiled module here for
+     *   execution via a `data:` URL. (The compiler filters error-severity diagnostics before shipping,
+     *   so a compiled module passed here is expected to be runnable.)
+     *
+     * @param script TypeScript source, or a compiled {@link IModule.JSON} (the `module` of a `CompileResult`).
+     * @param options {@link IScript.RunOptions}
+     */
+    run(script: string | IModule.JSON, options?: IScript.RunOptions): Promise<IScript.RunResults>;
+    /**
+     * Will start scripting engine and autoRun scripts.
+     */
+    start(): Promise<void>;
+    /**
+     * Returns if the script is readonly.
+     */
+    isReadOnly(): boolean;
+    /**
+     * Convenience method for creating a module from a file.
+     *
+     * @remarks
+     * equivalent to `getModules().search( { type: 'macro', name } )`
+     *
+     * Searches every loaded module and — with {@link IScript.SearchOptions.includeBuiltIn} — the
+     * built-in functions, as ONE list: {@link IScript.SearchOptions.limit} and the relevance ordering
+     * of {@link IFunctionCollection.search} apply to the union, not to each source separately.
+     */
+    searchFunctions(options?: IScript.SearchOptions): Promise<IFunction[]>;
+    /**
+     * The categories the searchable functions declare, each with how many functions carry it.
+     *
+     * @param options {@link IScript.GetCategoryOptions}
+     *
+     * @returns The categories, ordered by name; counts are summed across every source searched.
+     *
+     * @remarks
+     * The workbook-level {@link IFunctionCollection.getCategories} — a function picker builds its
+     * category list from this, so a module's custom functions show up in it (in their own category, or
+     * swelling the count of a built-in one they declare).
+     */
+    getFunctionCategories(options?: IScript.GetCategoryOptions): Promise<IFunctionCollection.Category[]>;
+    /**
+     * Add Listeners.
+     *
+     * @see
+     * {@link IListener.ISource.addListeners}
+     */
+    addListeners(listeners: IScript.IListeners, options?: IListener.Options): IListener.Remove;
+    /**
+     * Returns a JSON representation of the script.
+     */
+    toJSON(): Record<string, IModule.JSON>;
+}
+/**
+ * {@inheritDoc IFunctionCollection}
+ * @see
+ * ### **Interface**
+ *
+ * {@link IFunctionCollection}
+ */
+export declare namespace IScript {
+    /**
+     * Events for {@link ISheet}.
+     */
+    interface Events {
+        /**
+         * Called before search.
+         */
+        onBeforeSearch?(source: IScript): Promise<void> | void;
+        /**
+         * Called after load.
+         */
+        onChange?(source: IScript): void;
+        /**
+         * Called before load. If any exception is thrown this
+         * exception will be returned to the client and delete will be aborted.
+         */
+        onBeforeSave?(source: IScript): Promise<void> | void;
+        /**
+         * Called after save.
+         */
+        onSave?(source: IScript): void;
+    }
+    interface IListeners extends IListener.Callbacks<IScript, IScript.Events> {
+    }
+    /**
+     * The results from a macro script
+     */
+    interface MacroResults {
+        params: any[];
+        results: any;
+        /**
+         * The id of the transaction this macro committed - use with
+         * {@link ITransaction.IStore.revert}/`restore` to undo or reapply.
+         */
+        commitId?: string;
+    }
+    /**
+     * The execution context passed as the second argument to a script entry
+     * (`export default function (workbook, ctx)`).
+     *
+     * @remarks
+     * These five members are the run context on every transport — and the implicit
+     * globals of an inline snippet: `wb`, `log`, `warn`, `error`, `args`.
+     */
+    interface ScriptContext {
+        /** The workbook the script is running against. */
+        wb: IWorkbook;
+        /**
+         * The reporting channel - findings and results.
+         *
+         * @remarks
+         * Variadic and value-taking, like `console.log`: `log('rows:', n)` and `log(range.getStats())`
+         * both work. An SDK object (workbook, sheet, range, cell, stats, regions, style) renders as its
+         * markdown report - the same report returning it would produce.
+         */
+        log(...args: any[]): void;
+        /** Diagnostics: something surprising but survivable. Travels separately from {@link log}. */
+        warn(...args: any[]): void;
+        /** Diagnostics: something wrong. Travels separately from {@link log}. */
+        error(...args: any[]): void;
+        /** Optional caller-supplied arguments (CLI: everything after `--`; MCP: the `args` object). */
+        args?: Record<string, any>;
+    }
+    /**
+     * Options for {@link IScript.run}.
+     *
+     * @remarks
+     * Extends {@link ITransaction.OperationOptions}, so a caller can name the resulting transaction
+     * (`description`) - this is the label the UI shows for undo/redo - and control `autoSelect`. When
+     * `description` is omitted the label falls to the entry's JSDoc summary, then to
+     * {@link defaultDescription}, then to the entry's name.
+     */
+    interface RunOptions extends ITransaction.OperationOptions {
+        /**
+         * The label to use when neither the caller nor the code names the change — a FLOOR, not an
+         * override.
+         *
+         * @remarks
+         * `description` outranks the entry's JSDoc summary, which is right for a caller naming a specific
+         * change and wrong for a host supplying a generic default: passing "Agent Update" as the
+         * `description` throws away the summary of every documented script it runs. Hence two options and
+         * one order — `description`, then the summary, then this, then the entry's name.
+         */
+        defaultDescription?: string;
+        /** Output channel; defaults to a console logger. A host may pass a `BufferLogger` to capture. */
+        logger?: ILogger;
+        /** Arguments exposed to the script via `ctx.args`. */
+        args?: Record<string, any>;
+        /**
+         * Writes the entry's return value into the current selection.
+         *
+         * @defaultValue false
+         *
+         * @remarks
+         * The user-invoked macro affordance: a macro run from the UI that returns a value (or an
+         * {@link ICell}/{@link ICellRange}) puts it where the user is. {@link IScript.executeMacro} sets
+         * it; {@link IScript.run} does not, because a programmatic caller's return value is its
+         * *answer* - `run("wb.getRange('A1:B2').getValues()")` is a read, and pasting its result at the
+         * selection would make every read an edit.
+         */
+        applyResult?: boolean;
+        /**
+         * Renders an SDK object logged by the script as its markdown report.
+         *
+         * @remarks
+         * Injected because the renderer registry lives in `@sheetxl/query`, which depends on this
+         * package. Hosts pass a closure over `renderMarkdown` and its workbook; without it, logged
+         * objects fall back to JSON.
+         */
+        render?: LogRenderer;
+    }
+    /**
+     * The result of {@link IScript.run}.
+     */
+    interface RunResults {
+        /** True if the script ran without throwing. */
+        ok: boolean;
+        /** The script entry's return value, if any. */
+        result?: any;
+        /** The committed transaction id (for revert/restore), if a change was made. */
+        commitId?: string;
+        /** The error, if `ok` is false. */
+        error?: any;
+        /**
+         * Positioned compile diagnostics, if the script failed to compile.
+         *
+         * @remarks
+         * Present when `ok` is false due to compile errors. Lets callers render `line:col` + code rather
+         * than only the flattened {@link RunResults.error} message.
+         */
+        diagnostics?: IModule.Diagnostic[];
+    }
+    interface SearchOptions extends IFunctionCollection.SearchOptions {
+        moduleName?: string;
+        includeBuiltIn?: boolean;
+    }
+    /**
+     * Options for {@link IScript.getFunctionCategories}.
+     */
+    interface GetCategoryOptions extends IFunctionCollection.GetCategoryOptions {
+        /** Restrict to one module's functions. */
+        moduleName?: string;
+        /** Include the categories of the built-in functions. */
+        includeBuiltIn?: boolean;
+    }
+}
+//# sourceMappingURL=IScript.d.ts.map

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

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