@sheetxl/sdk 0.7.28-beta.4 → 0.8.0-beta.10

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/FunctionArguments.d.ts

@@ -0,0 +1,22 @@
+import { IFunction, IFunctionArguments } from '@sheetxl/primitives';
+/**
+ * A bound view, as the marshaller holds it.
+ *
+ * @internal The public half is {@link IFunctionArguments}; this adds the two things only `_exec`
+ * may do — point the view at the argument array its broadcast loop rewrites per output cell, and
+ * take it off the engine's shared dispatch buffer when the body is about to re-enter dispatch.
+ */
+export interface IArgumentsFrame extends IFunctionArguments {
+    /** @see FunctionArguments._setLiftValues */
+    _setLiftValues(values: any[] | null): void;
+    /** @see FunctionArguments._setPrivateArgs */
+    _setPrivateArgs(args: any[]): void;
+}
+/**
+ * Binds the view for a call about to dispatch, and returns it so the lift can point it at its
+ * per-cell arguments. Pairs with {@link popArguments} in a `finally`.
+ */
+export declare const pushArguments: (params: IFunction.ParameterTypeJSON[] | null | undefined, variadic: number, suffix: number, args: any[], argsLength: number) => IArgumentsFrame;
+/** Ends the call {@link pushArguments} began. */
+export declare const popArguments: () => void;
+//# sourceMappingURL=FunctionArguments.d.ts.map

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

@@ -1,33 +1,52 @@
 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;
+    /** The read-only and own functions, by name. Dropped with {@link _index}. */
+    private _sorted;
     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.getCount} */
+    getCount(options?: IFunctionCollection.GetItemsOptions): number;
     /** {@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[]>;
     /**
@@ -35,14 +54,12 @@ export declare class FunctionCollection implements IFunctionCollection {
      *
      * @remarks
      * Not part of {@link IFunctionCollection}: it exists so a caller merging SEVERAL collections
-     * ({@link IScript.searchFunctions} — built-ins plus every module) can rank the union on one
-     * scale instead of concatenating separately-ranked lists.
+     * ({@link IScript.searchFunctions} — every loaded module) can rank the union on one scale instead
+     * of concatenating separately-ranked lists.
      */
     searchScored(options?: IFunctionCollection.SearchOptions): Promise<FunctionMatch[]>;
     /** {@inheritDoc IFunctionCollection.getCategories} */
     getCategories(options?: IFunctionCollection.GetCategoryOptions): Promise<IFunctionCollection.Category[]>;
-    /** {@inheritDoc ICollection.getCount} */
-    getCount(): number;
     /** {@inheritDoc IFunctionCollection.validateName} */
     validateName(named: string): void;
     _validateName(name: string, ignoreExisting?: boolean): void;
@@ -60,15 +77,32 @@ export declare class FunctionCollection implements IFunctionCollection {
     private _addFunction;
     /** {@inheritDoc ITransaction.ITransactional.beginCommit} */
     beginCommit(options?: string | ITransaction.OperationOptions): ITransaction;
+    /** Drops everything derived from the collection's contents. */
+    private _invalidate;
     private _getState;
     private _beginCommit;
     private _updateState;
     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> {
     /**
@@ -16,27 +19,41 @@ export interface IFunctionCollection extends ICollection<IFunction> {
      */
     add(option: string | IFunction | IFunctionCollection.AddOptions): Promise<IFunction>;
     /**
-     * Returns functions that match the filter criteria.
+     * The functions in the collection, ordered by canonical name.
+     *
+     * @param options {@link IFunctionCollection.GetItemsOptions}
      *
-     * If no filter criteria is provided, all items will be returned.
+     * @remarks
+     * Leaves out hidden functions ({@link IFunction.IDeclaration.isHidden}) unless
+     * {@link GetItemsOptions.includeHidden} is set.
+     */
+    getItems(options?: IFunctionCollection.GetItemsOptions): IFunction[];
+    /**
+     * How many functions {@link getItems} returns for the same options.
+     *
+     * @param options {@link IFunctionCollection.GetItemsOptions}
+     */
+    getCount(options?: IFunctionCollection.GetItemsOptions): number;
+    /**
+     * {@link getItems}, with the filters that read a function's {@link IFunction.IDescriptor}.
      *
      * @param options {@link IFunctionCollection.SearchOptions}
      *
      * @remarks
+     * Without {@link SearchOptions.text} or {@link SearchOptions.category}, returns exactly what
+     * `getItems` returns for the same options.
+     *
      * ### 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.
+     * By relevance when there is `text`, by canonical name otherwise.
      *
      * 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.
+     * `text` and `category` read each function's descriptor, 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[]>;
     /**
@@ -56,8 +73,7 @@ export interface IFunctionCollection extends ICollection<IFunction> {
      */
     getCategories(options?: IFunctionCollection.GetCategoryOptions): Promise<IFunctionCollection.Category[]>;
     /**
-     * Convenience method for filter by name.
-     * This is functionally equivalent to getItems({ name });
+     * The function with this name, hidden or not.
      *
      * @param name The name to search for This is case insensitive.
      * @param options {@link IFunctionCollection.GetByNameOptions}
@@ -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,29 @@ 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;
+        /**
+         * Include hidden functions ({@link IFunction.IDeclaration.isHidden}).
+         *
+         * @defaultValue `false`
+         */
+        includeHidden?: boolean;
+    }
     interface GetByNameOptions {
         /**
          * A sheet name to bind the returned function to. Vends a NEW instance whose evaluation
@@ -94,11 +141,7 @@ export declare namespace IFunctionCollection {
     /**
      * Options for searching a function in the collection.
      */
-    interface SearchOptions {
-        /**
-         * Search with the given name. This is case insensitive.
-         */
-        name?: string;
+    interface SearchOptions extends GetItemsOptions {
         /**
          * Search all function descriptors for the given text. This is case insensitive.
          *
@@ -107,22 +150,9 @@ export declare namespace IFunctionCollection {
          */
         text?: string;
         /**
-         * Search with the given name. This is case insensitive.
+         * Only functions in this category ({@link IFunction.IDescriptor.getCategory}). 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.
          *
@@ -144,11 +174,11 @@ export declare namespace IFunctionCollection {
          */
         type?: string;
         /**
-         * Count functions their descriptor marks deprecated (or hidden).
+         * Count hidden functions ({@link IFunction.IDeclaration.isHidden}).
          *
          * @defaultValue `false`
          */
-        includeDeprecated?: boolean;
+        includeHidden?: boolean;
     }
     /**
      * One category and its population, as returned by {@link IFunctionCollection.getCategories}.

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 {
         /**