@sheetxl/sdk 0.8.0-beta.1 → 0.8.0-beta.2

package/types/src/protectedRange/ProtectedRangeCollection.d.ts

@@ -1,21 +1,32 @@
 import { ICellRanges } from '../cellRange';
+import { ICollection, AbstractCollection } from '../type';
+import { IListener } from '../listener';
 import { IProtectedRangeCollection } from './IProtectedRangeCollection';
 import { IProtectedRange } from './IProtectedRange';
-export declare class ProtectedRangeCollection implements IProtectedRangeCollection {
+/**
+ * Implementation for {@link IProtectedRangeCollection}.
+ *
+ * @remarks
+ * A front over the sheet's own protected-range state — the sheet keeps the store and the
+ * events, this class keeps the API. `onCollectionChange` is the sheet's
+ * `onProtectedRangesChange`, forwarded with this collection as the source.
+ */
+export declare class ProtectedRangeCollection extends AbstractCollection<IProtectedRange, IProtectedRangeCollection.GetItemsOptions> implements IProtectedRangeCollection {
     private _add;
     private _get;
     private _getByName;
     private _createItem;
-    constructor(add: (address: ICellRanges.Address | IProtectedRange, options?: IProtectedRangeCollection.AddOptions) => IProtectedRange, get: (address: ICellRanges.Address | null | undefined, ignoreHidden?: boolean, fullyContained?: boolean) => IProtectedRange[], getByName: (name: string) => IProtectedRange | null, createItem: (template?: IProtectedRange | null) => IProtectedRange);
+    private _addListeners;
+    constructor(add: (address: ICellRanges.Address | IProtectedRange, options?: IProtectedRangeCollection.AddOptions) => IProtectedRange, get: (address: ICellRanges.Address | null | undefined, ignoreHidden?: boolean, fullyContained?: boolean) => IProtectedRange[], getByName: (name: string) => IProtectedRange | null, createItem: (template?: IProtectedRange | null) => IProtectedRange, addListeners: (listeners: ICollection.IListeners, options?: IListener.Options) => IListener.Remove);
     /** {@inheritDoc IProtectedRangeCollection.add} */
     add(address: ICellRanges.Address | IProtectedRange, options?: IProtectedRangeCollection.AddOptions): IProtectedRange;
-    /** {@inheritDoc ICollection.[Symbol.iterator]} */
-    [Symbol.iterator](): IterableIterator<IProtectedRange>;
-    /** {@inheritDoc IProtectedRangeCollection.getItems} */
-    getItems(options?: IProtectedRangeCollection.GetItemsOptions): IProtectedRange[];
+    /** {@inheritDoc AbstractCollection._getItems} */
+    protected _getItems(options?: IProtectedRangeCollection.GetItemsOptions): IProtectedRange[];
     /** {@inheritDoc IProtectedRangeCollection.createItem} */
     createItem(template?: IProtectedRange | null): IProtectedRange;
-    /** {@inheritDoc IProtectedRangeCollection.getCount} */
-    getCount(): number;
+    /** {@inheritDoc ICollection.addListeners} */
+    addListeners(listeners: ICollection.IListeners, options?: IListener.Options): IListener.Remove;
+    /** {@inheritDoc IProtectedRangeCollection.isIProtectedRangeCollection} */
+    get isIProtectedRangeCollection(): true;
 }
 //# sourceMappingURL=ProtectedRangeCollection.d.ts.map

package/types/src/protection/DefaultProtection.d.ts

@@ -1,9 +1,11 @@
 import { IListener } from '../listener';
 import { IProtection } from './IProtection';
 import { ListenerEmitter } from '../listener/ListenerEmitter';
-export declare class DefaultProtection<T, P extends IProtection.Properties, J extends IProtection.JSON> implements IProtection<T, P, J> {
+export declare abstract class DefaultProtection<T, P extends IProtection.Properties, J extends IProtection.JSON> implements IProtection<T, P, J> {
     protected _emitter: ListenerEmitter<this, IProtection.IListeners>;
     protected _isPaused: boolean;
+    /** Not protected, but keeping `_properties` for the next lock. Saved as {@link _getAllowedKey}. */
+    protected _isDisabled: boolean;
     protected _password: Partial<IProtection.EncryptedPassword> | null;
     protected _identities: IProtection.IdentityProvider[] | null;
     protected _properties: Partial<P> | null;
@@ -21,6 +23,8 @@ export declare class DefaultProtection<T, P extends IProtection.Properties, J ex
     pause(password?: string): Promise<IProtection<T, P, J>>;
     /** {@inheritDoc IProtection.resume} */
     resume(): IProtection<T, P, J>;
+    /** {@inheritDoc IProtection.setProperties} */
+    setProperties(properties: Partial<P>): Promise<IProtection<T, P, J>>;
     /** {@inheritDoc IProtection.isPaused} */
     isPaused(): boolean;
     /** {@inheritDoc IProtection.isLocked} */
@@ -35,9 +39,16 @@ export declare class DefaultProtection<T, P extends IProtection.Properties, J ex
     /** {@inheritDoc IListener.ISource.addListeners} */
     addListeners(listeners: IProtection.IListeners, options?: IListener.Options): IListener.Remove;
     fromJSON(json?: J): void;
+    /**
+     * The JSON key that says the whole object stays allowed: unprotected, keeping its options. Named
+     * for the object (`sheet`, `workbook`), like the allowances beside it.
+     */
+    protected abstract _getAllowedKey(): string;
     protected _fromJSON(_json: J | null): void;
     protected _toJSON(json: Partial<J>): Partial<J>;
     /** {@inheritDoc IWorkbookProtection.toJSON} */
     toJSON(): J | null;
+    /** {@inheritDoc IProtection.isIProtection} */
+    get isIProtection(): true;
 }
 //# sourceMappingURL=DefaultProtection.d.ts.map

package/types/src/protection/IProtection.d.ts

@@ -8,13 +8,15 @@ export interface IProtection<T, P extends IProtection.Properties, J extends IPro
      * Locks the object (workbook or sheet or range) with the specified options and password.
      *
      * @param password The password required to unlock the object.
-     * @param properties The properties to allow to remain unlocked.
+     * @param properties The properties to allow to remain unlocked. Omitted, the options the object
+     * already carries are used (see {@link unlock} and {@link setProperties}).
      * @param algorithm The algorithm for encrypting the password.
      * @param spinCount The spin count for encrypting the password.
      * @returns The `IProtection` instance for method chaining.
      *
      * @remarks
      * By default all properties are locked but you can specify which properties to remain unlocked.
+     * Throws when the object is already protected, paused included.
      */
     lock(properties?: Partial<P>, password?: string, algorithm?: string, spinCount?: number): Promise<IProtection<T, P, J>>;
     /**
@@ -24,9 +26,31 @@ export interface IProtection<T, P extends IProtection.Properties, J extends IPro
      * @returns The `IProtection` instance for method chaining.
      *
      * @remarks
-     * If the correct password is provided, protection is removed from the object.
+     * If the correct password is provided, protection is removed from the object and the password is
+     * cleared. The options are kept, and saved, so a later {@link lock} with no properties protects
+     * the same way again.
      */
     unlock(password?: string): Promise<IProtection<T, P, J>>;
+    /**
+     * Replaces the options of an unprotected or paused object. On a paused object they apply when it
+     * resumes; on an unprotected one, when it is next locked.
+     *
+     * @param properties The properties to allow to remain unlocked.
+     * @returns The `IProtection` instance for method chaining.
+     *
+     * @remarks
+     * Throws while the object is locked: unprotect or {@link pause} first. Neither asks for the
+     * password here, since an unprotected object has none and a pause already asked for it.
+     */
+    setProperties(properties: Partial<P>): Promise<IProtection<T, P, J>>;
+    /**
+     * The object's options, kept while it is unlocked; `null` when it has none.
+     *
+     * @remarks
+     * A property names what stays **allowed** while locked - it is not a list of what is forbidden.
+     * Whether the options are in force is {@link isLocked}.
+     */
+    getProperties(): Partial<P> | null;
     /**
      * Temporarily disables protection with the provided password.
      *
@@ -36,6 +60,14 @@ export interface IProtection<T, P extends IProtection.Properties, J extends IPro
      * @remarks
      * This method allows temporarily pausing protection without permanently unlocking the object.
      * Use {@link resume} to restore protection.
+     *
+     * Not a shortcut for {@link unlock}, even on a lock without a password: unlocking is a document
+     * change (the file saves unprotected, and the password is gone), whereas a pause
+     * keeps the whole configuration - password, options, and any session access already granted to
+     * an {@link IProtectedRange} - and {@link resume} restores it exactly. The password is required
+     * only when one is set. Throws when the object is not locked.
+     *
+     * The paused state is session-only and is never serialized.
      */
     pause(password?: string): Promise<IProtection<T, P, J>>;
     /**
@@ -91,6 +123,8 @@ export interface IProtection<T, P extends IProtection.Properties, J extends IPro
      */
     addListeners(listeners: IProtection.IListeners, options?: IListener.Options): IListener.Remove;
     toJSON(): IProtection.JSON | null;
+    /** For runtime type checking. */
+    readonly isIProtection: true;
 }
 /**
  * {@inheritDoc IProtection}

package/types/src/reference/ReferenceUtils.d.ts

@@ -0,0 +1,80 @@
+import { IRange } from '@sheetxl/primitives';
+/**
+ * The rules a reference follows when the cells around it change.
+ *
+ * @remarks
+ * A reference is a rectangle that names cells - a formula's precedent, a range listener's
+ * subscription, a watch's location. Everything that holds one has to answer the same questions
+ * when the sheet is restructured: where is it after an insert or a delete, when does it become
+ * `#REF!`, and when does a cut carry it along. These are those answers, and they live here rather
+ * than in the calc graph so that the graph's precedents and the sheet's listeners map cannot
+ * disagree - they call the same functions.
+ *
+ * Nothing here knows about formulas, blocks or grids. A reference is two numbers per axis plus,
+ * for a formula, which of its endpoints a structural change is allowed to move.
+ *
+ * @internal
+ */
+/**
+ * Shift one axis of a reference the way a structural change shifts a formula precedent.
+ *
+ * @remarks
+ * This is the rule `shiftPrecedents` applies, per axis, to every reference it rewrites, and the
+ * rule a range listener's reference follows so that the two can never disagree. A reference is
+ * judged on the shifted axis alone - whether it overlaps the inserted or deleted band on the OTHER
+ * axis plays no part - which is why `=SUM(A1:C3)` reads `A2:C4` after one cell is inserted at A1
+ * shifting down: the whole reference moves, it does not come apart.
+ *
+ * * An insert (`shiftBy` > 0) moves every endpoint at or past `shiftStart` by `shiftBy`; an
+ *   endpoint before it stays, so a reference straddling the insert line grows.
+ * * A delete (`shiftBy` < 0) whose zone covers the whole reference makes it `#REF!` (`null`); one
+ *   that covers an end trims that end to the zone's edge; one entirely before the reference moves
+ *   it whole.
+ *
+ * An immune endpoint is left exactly as it is, and a reference with an immune endpoint is never
+ * `#REF!`: that is a relative endpoint of an unanchored block (a named formula's body), which
+ * names no cell for a structural change to move. See the note in `shiftPrecedents`.
+ *
+ * @param start The reference's absolute start on this axis.
+ * @param end The reference's absolute end on this axis.
+ * @param shiftStart The first index of the inserted or deleted band.
+ * @param shiftBy How far the band moves cells: positive for an insert, negative for a delete.
+ * @param deleteEnd The last index of the deleted band; ignored for an insert.
+ * @param immuneStart `true` if the start endpoint must not move.
+ * @param immuneEnd `true` if the end endpoint must not move.
+ * @returns The shifted `[start, end]`, or `null` when the delete removed the whole reference.
+ */
+export declare function shiftReferenceAxis(start: number, end: number, shiftStart: number, shiftBy: number, deleteEnd: number, immuneStart?: boolean, immuneEnd?: boolean): [start: number, end: number] | null;
+/**
+ * Move one axis of a reference the way a cut moves a formula precedent.
+ *
+ * @remarks
+ * A move is a rigid translation, so unlike a shift there is no zone to compare against and no
+ * `#REF!`: both endpoints travel the same distance or neither does. Whether this reference travels
+ * at all is {@link isReferenceEnclosed}'s question, asked before this one.
+ *
+ * An immune endpoint is left exactly as it is. That is a relative endpoint whose own cells are
+ * moving by the same amount - the formula and its target translate together, so the offset between
+ * them is already right - or one of an unanchored block, which names no cell to re-point.
+ *
+ * @param start The reference's start on this axis.
+ * @param end The reference's end on this axis.
+ * @param moveBy How far the cut carries the cells on this axis.
+ * @param immuneStart `true` if the start endpoint must not move.
+ * @param immuneEnd `true` if the end endpoint must not move.
+ */
+export declare function moveReferenceAxis(start: number, end: number, moveBy: number, immuneStart?: boolean, immuneEnd?: boolean): [start: number, end: number];
+/**
+ * Whether a cut of `from` carries `reference` with it.
+ *
+ * @remarks
+ * Excel's test, and the graph's: a reference moves only when the cut rectangle FULLY ENCLOSES it.
+ * Cut A1:C3 and `=SUM(A1:B2)` follows to the destination; `=SUM(A1:C5)` reaches outside the cut
+ * and so is left exactly where it is, pointing at cells that are now empty. There is no partial
+ * answer and no split - a reference that is only half carried would name two different rectangles.
+ *
+ * A formula BLOCK asks a longer version of this question, because each of its cells has a
+ * reference of its own and all of them have to be enclosed; see `movePrecedents`.
+ */
+export declare function isReferenceEnclosed(reference: Readonly<IRange.Coords>, from: Readonly<IRange.Coords>): boolean;
+//# sourceMappingURL=ReferenceUtils.d.ts.map

package/types/src/reference/index.d.ts

@@ -0,0 +1,2 @@
+export * from './ReferenceUtils';
+//# sourceMappingURL=index.d.ts.map

package/types/src/resource/IResource.d.ts

@@ -1,4 +1,4 @@
-import { JSONSerializableAsync } from '@sheetxl/utils';
+import { JSONSerializableAsync, MaybePromise } from '@sheetxl/utils';
 /**
  * A resource is an item referenced elsewhere with the application.
  * This will track when a resource is no longer being used and can be removed.
@@ -63,6 +63,26 @@ export interface IResource extends JSONSerializableAsync<IResource.JSON> {
  * {@link IResource}
  */
 export declare namespace IResource {
+    /**
+     * Writes a single resource wherever the caller wants it, and returns the {@link IResource.JSON}
+     * that should stand for it in the serialized model.
+     *
+     * @param resource The resource being written.
+     * @param id The id the serialized model references this resource by.
+     *
+     * @returns The JSON to record for the resource, or `null` to record nothing.
+     *
+     * @remarks
+     * Called once per resource that the write actually touched, never for unused ones.
+     *
+     * Returning `{ uri }` is the useful case: the bytes go wherever the writer put them and the
+     * model keeps a pointer, which reads back as an external resource with no reader changes.
+     *
+     * Ids are positions, so a `null` leaves a `{}` placeholder rather than shifting the resources
+     * after it. If every resource returns `null` no resources are recorded at all — for a writer
+     * that emits the bytes itself and only needs the ids, such as the xlsx writer.
+     */
+    type Writer = (resource: IResource, id: number) => MaybePromise<IResource.JSON | null>;
     interface IUnloadListener {
         onUnload: (ref: IResource) => void;
     }

package/types/src/resource/IResourceCollection.d.ts

@@ -3,6 +3,9 @@ import { ICollection } from '../type';
 import { IResource } from './IResource';
 /**
  * Collections of {@link IResource}.
+ *
+ * @remarks
+ * Keyed by the resource, not ordered: iteration order is unspecified.
  */
 export interface IResourceCollection extends ICollection<IResource> {
     /**
@@ -24,6 +27,8 @@ export interface IResourceCollection extends ICollection<IResource> {
      * will only save the resource that were accessed within the persist scope.
      */
     beginPersist(): IResourceCollection.IPersistScope<IResource.JSON>;
+    /** For runtime type checking. */
+    readonly isIResourceCollection: true;
 }
 /**
  * {@inheritDoc IResourceCollection}
@@ -89,8 +94,11 @@ export declare namespace IResourceCollection {
         fromJSON(json: J[]): void;
         /**
          * This can be called multiple times.
+         *
+         * @param writer Called once per resource in place of serializing it, to write it elsewhere.
+         * Returns `[]` when the writer records nothing for any of them.
          */
-        toJSONAsync(): Promise<J[]>;
+        toJSONAsync(writer?: IResource.Writer): Promise<J[]>;
     }
 }
 //# sourceMappingURL=IResourceCollection.d.ts.map

package/types/src/resource/ResourceCollection.d.ts

@@ -1,19 +1,19 @@
-import { ICollection } from '../type';
+import { ICollection, AbstractCollection } from '../type';
 import { IResource } from './IResource';
 import { IResourceCollection } from './IResourceCollection';
-export declare class ResourceCollection implements IResourceCollection {
+export declare class ResourceCollection extends AbstractCollection<IResource> implements IResourceCollection {
     private _resources;
     private _persistOpen;
     constructor();
     /** {@inheritDoc IResourceCollection.add} */
     add(res: string | IResource | IResourceCollection.AddOptions): IResource;
-    /** {@inheritDoc ICollection.[Symbol.iterator]} */
-    [Symbol.iterator](): IterableIterator<IResource>;
-    /** {@inheritDoc IResourceCollection.getItems} */
-    getItems(options?: ICollection.GetItemsOptions): IResource[];
+    /** {@inheritDoc AbstractCollection._getItems} */
+    protected _getItems(options?: ICollection.GetItemsOptions): IResource[];
     /** {@inheritDoc IResourceCollection.getCount} */
     getCount(): number;
     /** {@inheritDoc IResourceCollection.beginPersist} */
     beginPersist(): IResourceCollection.IPersistScope<IResource.JSON>;
+    /** {@inheritDoc IResourceCollection.isIResourceCollection} */
+    get isIResourceCollection(): true;
 }
 //# sourceMappingURL=ResourceCollection.d.ts.map

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

@@ -1,33 +1,48 @@
 import { IFunction, IFormulaContext } from '@sheetxl/primitives';
 import { ITransaction } from '../transaction';
 import { IListener } from '../listener';
-import { ICollection } from '../type';
-import { ListenerEmitter } from '../listener/ListenerEmitter';
+import { AbstractCollection } from '../type';
 import { IFunctionCollection } from './IFunctionCollection';
 import { FunctionMatch } from './_FunctionIndex';
 /**
  * Implementation for `IFunctionCollection`.
  */
-export declare class FunctionCollection implements IFunctionCollection {
-    protected _emitter: ListenerEmitter<this, IFunctionCollection.IListeners>;
+export declare class FunctionCollection extends AbstractCollection<IFunction, IFunctionCollection.GetItemsOptions> implements IFunctionCollection {
     private _options;
     private _readonly;
-    private _transactions;
+    /** The functions lambda-valued defined names export. See {@link _setNamedSource}. */
+    private _named;
+    protected _transactions: ITransaction.IStore;
     private _stateId;
     private _transactionsRemoveListener;
-    private _closed;
     /**
      * The descriptor index behind the metadata searches. Built on first use and dropped whenever the
      * collection's contents change — see {@link FunctionIndex}.
      */
     private _index;
     constructor(options: ConstructorOptions);
-    /** {@inheritDoc ICollection.[Symbol.iterator]} */
-    [Symbol.iterator](): IterableIterator<IFunction>;
-    /** {@inheritDoc IFunctionCollection.getItems} */
-    getItems(options?: ICollection.GetItemsOptions): IFunction[];
+    /** {@inheritDoc AbstractCollection._getItems} */
+    protected _getItems(options?: IFunctionCollection.GetItemsOptions): IFunction[];
     /** {@inheritDoc IFunctionCollection.getByName} */
     getByName(name: string, options?: IFunctionCollection.GetByNameOptions): IFunction | null;
+    /**
+     * Installs the functions lambda-valued defined names export: {@link getByName} falls back to them
+     * for a name no registered function has, and {@link getItems}, {@link search} and
+     * {@link getCategories} list them.
+     *
+     * @remarks
+     * Supplied by the calculation, which owns defined names — this layer does not know them. What it
+     * answers reports `isLambda()`, which is how the engine's own lookups tell it apart and skip it: a
+     * call to a named lambda evaluates the name, not a function.
+     */
+    _setNamedSource(source: NamedFunctionSource | null): void;
+    /**
+     * The exported named lambdas that no registered function shadows, read LIVE: a name's body and
+     * comment change without this collection hearing of it, so they never enter the cached index.
+     */
+    private _namedFunctions;
+    /** The cached index, followed by entries for {@link _namedFunctions} built fresh. */
+    private _entries;
     /** {@inheritDoc IFunctionCollection.search} */
     search(options?: IFunctionCollection.SearchOptions): Promise<IFunction[]>;
     /**
@@ -66,9 +81,24 @@ export declare class FunctionCollection implements IFunctionCollection {
     protected _initState(): void;
     /** {@inheritDoc IListener.ISource.addListeners} */
     addListeners(listeners: IFunctionCollection.IListeners, options?: IListener.Options): IListener.Remove;
-    isClosed(): boolean;
+    /**
+     * Closes the collection. Called by the owner when it closes; announces
+     * {@link ICollection.Events.onClose} once.
+     */
     close(): void;
     get isFunctionCollection(): true;
+    /** {@inheritDoc IFunctionCollection.isIFunctionCollection} */
+    get isIFunctionCollection(): true;
+}
+/**
+ * Functions a collection lists and answers without holding them — the calculation's named lambdas.
+ * See {@link FunctionCollection._setNamedSource}.
+ */
+export interface NamedFunctionSource {
+    /** The function `name` exports as seen from `sheet` (a sheet's own name shadows a global), or `null`. */
+    getByName(name: string, sheet?: string): IFunction | null;
+    /** Every exported function, one per name. */
+    getItems(): IFunction[];
 }
 export interface ConstructorOptions {
     /**

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

@@ -3,6 +3,9 @@ import { ICollection } from '../type';
 import { IListener } from '../listener';
 /**
  * Collections of {@link IFunction}.
+ *
+ * @remarks
+ * Keyed by name, not ordered: iteration order is unspecified.
  */
 export interface IFunctionCollection extends ICollection<IFunction> {
     /**
@@ -15,6 +18,19 @@ export interface IFunctionCollection extends ICollection<IFunction> {
      * are registered and the first (primary) one is returned.
      */
     add(option: string | IFunction | IFunctionCollection.AddOptions): Promise<IFunction>;
+    /**
+     * The functions in the collection, narrowed by {@link IFunctionCollection.GetItemsOptions}.
+     *
+     * @remarks
+     * Synchronous, and therefore deliberately narrower than {@link IFunctionCollection.search}: it
+     * offers only the filters that read no {@link IFunction.IDescriptor} (`name`, `type`). Anything
+     * that needs a descriptor — `text`, `category`, `includeDeprecated` — has to load them, which
+     * is why it lives on `search` and returns a promise.
+     *
+     * Unlike `search`, this does NOT resolve shadowing: a custom function sharing a built-in's name
+     * is returned alongside it rather than in place of it.
+     */
+    getItems(options?: IFunctionCollection.GetItemsOptions): IFunction[];
     /**
      * Returns functions that match the filter criteria.
      *
@@ -68,8 +84,16 @@ export interface IFunctionCollection extends ICollection<IFunction> {
      * 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.
+     *
+     * A defined name whose body is `LAMBDA(…)` answers too, when no function has the name: a function
+     * whose `isLambda()` is `true`, with the lambda's parameters and, as its summary, the name's comment
+     * (or its formula, without one).
+     * {@link getItems} and {@link search} list these under the category `Lambda`. `options.sheet` only
+     * chooses which sheet's names are visible — a named lambda cannot be bound or called outside its name.
      */
     getByName(name: string, options?: IFunctionCollection.GetByNameOptions): IFunction | null;
+    /** For runtime type checking. */
+    readonly isIFunctionCollection: true;
 }
 /**
  * {@inheritDoc IFunctionCollection}
@@ -82,6 +106,23 @@ export declare namespace IFunctionCollection {
     /**
      * Options for {@link IFunctionCollection.getByName}.
      */
+    /**
+     * Options for {@link IFunctionCollection.getItems}.
+     */
+    interface GetItemsOptions extends ICollection.GetItemsOptions {
+        /**
+         * Only the function with this name. Case insensitive.
+         */
+        name?: string;
+        /**
+         * Only functions of this type: `'formula'`, `'macro'` or `'autoRun'`.
+         *
+         * @remarks
+         * Compared against {@link IFunction.getContext}, which is what `search` filters on too, so the
+         * two agree on what a type means.
+         */
+        type?: string;
+    }
     interface GetByNameOptions {
         /**
          * A sheet name to bind the returned function to. Vends a NEW instance whose evaluation

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

@@ -1,5 +1,7 @@
 import { CompileOptions as _CompileOptions, CompileResult as _CompileResult, CompiledModule, Diagnostic as _Diagnostic } from '@sheetxl/scripting';
 import { IListener } from '../listener';
+import { ISheet } from '../sheet';
+import { IWorkbook } from '../workbook';
 import { IFunctionCollection } from './IFunctionCollection';
 /**
  * Represents a collection of functions. This is analogous to a file.
@@ -23,6 +25,21 @@ export interface IModule {
      * The language the function is written in.
      */
     getLanguage(): string;
+    /**
+     * What the module is bound to — the sheet or workbook that owns it, or `null` when it is
+     * global.
+     *
+     * @remarks
+     * Scope is a **visibility rule**, not a label: only a globally scoped module contributes
+     * functions to the workbook's formula namespace. A UDF declared in a sheet- or
+     * workbook-scoped module is unreachable from a cell formula.
+     *
+     * It is also **derived, not stored** — a module's scope is where it lives. A sheet's modules
+     * are reached through {@link ISheet.getModules}, and go away with the sheet; there is
+     * deliberately no setter, because changing a module's scope would silently promote or demote
+     * every function in it.
+     */
+    getScope(): IModule.Scope;
     /**
      * Returns the error-severity diagnostics for the module (a subset of {@link IModule.getDiagnostics}).
      */
@@ -45,6 +62,10 @@ export interface IModule {
      */
     toJSON(): IModule.JSON;
     addListeners(listeners: IModule.IListeners, options?: IListener.Options): IListener.Remove;
+    /**
+     * For runtime type checking.
+     */
+    readonly isIModule: true;
 }
 /**
  * {@inheritDoc IModule}
@@ -66,6 +87,10 @@ export declare namespace IModule {
      * Used to serialize a module.
      */
     type JSON = CompiledModule;
+    /**
+     * What a module is bound to: a sheet, the workbook, or `null` for global.
+     */
+    type Scope = ISheet | IWorkbook | null;
     /**
      * A positioned compile diagnostic (error or warning).
      */

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

@@ -3,6 +3,11 @@ import { IListener } from '../listener';
 import { IModule } from './IModule';
 /**
  * Represents a collection of functions. This is analogous to a file.
+ *
+ * @remarks
+ * Keyed by the module's id, not ordered: iteration order is unspecified. The unfiltered walk
+ * (`for…of`, `getCount()`, `toArray()`) is what `getItems()` returns with no options — the
+ * default language's modules; pass `{ language: null }` to `getItems` for every language.
  */
 export interface IModuleCollection extends ICollection<IModule> {
     /**
@@ -39,6 +44,10 @@ export interface IModuleCollection extends ICollection<IModule> {
      * Returns a JSON representation of the module collection.
      */
     toJSON(): Record<string, IModule.JSON>;
+    /**
+     * For runtime type checking.
+     */
+    readonly isIModuleCollection: true;
 }
 export declare namespace IModuleCollection {
     interface AddOptions {
@@ -59,6 +68,14 @@ export declare namespace IModuleCollection {
          * Search with the given name. This is case insensitive.
          */
         name?: string;
+        /**
+         * Only return modules written in this language. This is case insensitive.
+         *
+         * Pass `null` for every module, whatever its language.
+         *
+         * @defaultValue `'typescript'`
+         */
+        language?: string | null;
     }
     interface Events {
         /**

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

@@ -131,6 +131,8 @@ export interface IScript {
      * Returns a JSON representation of the script.
      */
     toJSON(): Record<string, IModule.JSON>;
+    /** For runtime type checking. */
+    readonly isIScript: true;
 }
 /**
  * {@inheritDoc IFunctionCollection}
@@ -140,6 +142,10 @@ export interface IScript {
  * {@link IFunctionCollection}
  */
 export declare namespace IScript {
+    /**
+     * The name a module gets when nothing named it — the one an editor opens by default.
+     */
+    const DEFAULT_MODULE: string;
     /**
      * Events for {@link ISheet}.
      */
@@ -250,6 +256,18 @@ export declare namespace IScript {
          * objects fall back to JSON.
          */
         render?: LogRenderer;
+        /**
+         * How long a finished run waits for what it logged to settle, in milliseconds. `0` waits
+         * indefinitely.
+         *
+         * @remarks
+         * `log(promise)` prints what the promise settles to, so a run is not done until its log is. A
+         * value still unsettled when this elapses prints as `[pending]`; nothing is thrown and the rest
+         * of the log is kept.
+         *
+         * @defaultValue 10 seconds
+         */
+        logTimeoutMs?: number;
     }
     /**
      * The result of {@link IScript.run}.