@sheetxl/sdk 0.4.22 → 0.5.0

package/node/esm/{CB1_HpaA6RdaxTgB.mjs → uRi_w6Ccng-hSYqK.mjs}

@@ -1,5 +1,5 @@
 /**
- * @license @sheetxl/sdk - SDK - A high-performance, embeddable spreadsheet engine. - v0.4.22
+ * @license @sheetxl/sdk - SDK - A high-performance, embeddable spreadsheet engine. - v0.5.0
  *
  * (C) 2025-present SheetXL Inc. & Michael T. Ford
  * License: The license can be found at https://www.sheetxl.com/license.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sheetxl/sdk",
   "description": "SDK - A high-performance, embeddable spreadsheet engine.",
-  "version": "0.4.22",
+  "version": "0.5.0",
   "license": "SEE LICENSE IN <LICENSE>",
   "type": "module",
   "exports": {
@@ -31,9 +31,9 @@
     "automation"
   ],
   "dependencies": {
-    "@sheetxl/primitives": "^0.4.22",
-    "@sheetxl/scripting": "^0.4.22",
-    "@sheetxl/utils": "^0.4.22",
+    "@sheetxl/primitives": "^0.5.0",
+    "@sheetxl/scripting": "^0.5.0",
+    "@sheetxl/utils": "^0.5.0",
     "bahttext": "^2.3.0",
     "bessel": "^1.0.2",
     "chalk": "^5.5.0",

package/types/index.d.ts

@@ -947,6 +947,10 @@ declare interface CommitView_3 {
     listeners?: Map<number, BeforeAfterRange>;
     /** If `true` then don't do protection check. (For example load or range listeners) */
     skipProtectionCheck?: boolean;
+    /**
+     * We update values (cache, potentially styling, as a result of calculations)
+     */
+    calculationSideEffect?: boolean;
 }
 
 declare function concatModifiedRuns<T>(parts: ModifiedRuns<T>): ITypes.RunCoordValue<T>[];
@@ -6088,16 +6092,16 @@ export declare namespace IChart {
 /**
  * Interface used for all ICollections.
  */
-export declare interface ICollection {
+export declare interface ICollection<T, O = ICollection.GetItemsOptions> {
     /**
-     * Return the items at the index.
-     * @param index
+     * Returns the items in the collection.
      */
+    getItems(options?: ICollection.GetItemsOptions): T[];
     /**
      * Returns the total items available.
      *
      * @remarks
-     * Useful as a quick escape for search.
+     * Useful as a quick escape for getItems.
      */
     getCount(): number;
 }
@@ -6110,6 +6114,14 @@ export declare interface ICollection {
  * {@link ICollection}
  */
 export declare namespace ICollection {
+    /**
+     * Options for getting items from the collection.
+     *
+     * @remarks
+     * This placeholder is extended by implementations of ICollection
+     */
+    export interface GetItemsOptions {
+    }
     /**
      * Collection that can be persisted.
      */
@@ -6163,13 +6175,13 @@ export declare namespace ICollection {
         /**
          * Called when collections have changes.
          */
-        onCollectionChange?(source: ICollection): void;
+        onCollectionChange?(source: ICollection<any>): void;
         /**
          * Called when the collection has been updated due to a undo/redo and a rerender is required.
          */
-        onInvalidated?(source: ICollection): void;
+        onInvalidated?(source: ICollection<any>): void;
     }
-    export interface IListeners extends IListener.Callbacks<ICollection, ICollection.Events> {
+    export interface IListeners extends IListener.Callbacks<ICollection<any>, ICollection.Events> {
     }
 }
 
@@ -7777,7 +7789,7 @@ export declare namespace IConditionalFormat {
 /**
  * Holds a collection of {@link IConditionalFormat}s.
  */
-export declare interface IConditionalFormatCollection extends ICollection {
+export declare interface IConditionalFormatCollection extends ICollection<IConditionalFormat> {
     /**
      * Add an `IConditional` to the container.
      *
@@ -7786,21 +7798,13 @@ export declare interface IConditionalFormatCollection extends ICollection {
      */
     add(address: ICellRanges.Address, options: IConditionalFormatCollection.AddOptions): IConditionalFormat;
     /**
-     * Returns items that match the search criteria.
+     * Returns items that match the filter criteria.
      *
-     * If no search criteria is provided, all items will be returned.
+     * If no filter criteria is provided, all items will be returned.
      *
-     * @param options {@link IConditionalFormatCollection.SearchOptions}
+     * @param options {@link IConditionalFormatCollection.GetItemsOptions}
      */
-    search(options?: IConditionalFormatCollection.SearchOptions): IConditionalFormat[];
-    /**
-     * Convenience method for searching by name. This is
-     * functionally equivalent to search({ name });
-     *
-     * @param name The name to search for This is case insensitive.
-     */
-    /** {@inheritDoc ICollection.getCount} */
-    getCount(): number;
+    getItems(options?: IConditionalFormatCollection.GetItemsOptions): IConditionalFormat[];
 }
 
 /**
@@ -7819,7 +7823,7 @@ export declare namespace IConditionalFormatCollection {
     /**
      * Options for searching for {@link IConditionalFormat}s.
      */
-    export interface SearchOptions {
+    export interface GetItemsOptions extends ICollection.GetItemsOptions {
         /**
          * If provided, the search will be limited to items that intersect the range.
          */
@@ -8535,7 +8539,7 @@ declare interface IFormulaParser {
 /**
  * Collections of {@link IFunction}.
  */
-export declare interface IFunctionCollection extends ICollection {
+export declare interface IFunctionCollection extends ICollection<IFunction> {
     /**
      * Add a custom function to a collection.
      *
@@ -8543,16 +8547,16 @@ export declare interface IFunctionCollection extends ICollection {
      */
     add(options: IFunction | IFunctionCollection.AddOptions): IFunction;
     /**
-     * Returns functions that match the search criteria.
+     * Returns functions that match the filter criteria.
      *
-     * If no search criteria is provided, all items will be returned.
+     * If no filter criteria is provided, all items will be returned.
      *
-     * @param options {@link IFunctionCollection.SearchOptions}
+     * @param options {@link IFunctionCollection.GetItemsOptions}
      */
-    search(options?: IFunctionCollection.SearchOptions): IFunction[];
+    getItems(options?: IFunctionCollection.GetItemsOptions): IFunction[];
     /**
-     * Convenience method for searching by name.
-     * This is functionally equivalent to search({ name });
+     * Convenience method for filter by name.
+     * This is functionally equivalent to getItems({ name });
      *
      * @param name The name to search for This is case insensitive.
      */
@@ -8570,7 +8574,7 @@ export declare namespace IFunctionCollection {
     /**
      * Options for searching a function in the collection.
      */
-    export interface SearchOptions {
+    export interface GetItemsOptions {
         /**
          * Search with the given name. This is case insensitive.
          */
@@ -9498,7 +9502,7 @@ export declare namespace IModule {
 /**
  * Represents a collection of functions. This is analogous to a file.
  */
-declare interface IModuleCollection extends ICollection {
+declare interface IModuleCollection extends ICollection<IModule> {
     /**
      * Adds the module to the collection.
      *
@@ -9508,16 +9512,16 @@ declare interface IModuleCollection extends ICollection {
      */
     add(uid: string, module: IModule, options?: IModuleCollection.AddOptions): void;
     /**
-     * Returns functions that match the search criteria.
+     * Returns functions that match the filter criteria.
      *
-     * If no search criteria is provided, all items will be returned.
+     * If no filter criteria is provided, all items will be returned.
      *
-     * @param options {@link IModuleCollection.SearchOptions}
+     * @param options {@link IModuleCollection.GetItemsOptions}
      */
-    search(options?: IModuleCollection.SearchOptions): IModule[];
+    getItems(options?: IModuleCollection.GetItemsOptions): IModule[];
     /**
-     * Convenience method for searching by name.
-     * This is functionally equivalent to search({ name });
+     * Convenience method for filtering by name.
+     * This is functionally equivalent to getItems({ name });
      *
      * @param name The name to search for This is case insensitive.
      */
@@ -9547,9 +9551,9 @@ declare namespace IModuleCollection {
         ignoreErrors?: boolean;
     }
     /**
-     * Options for searching a function in the collection.
+     * Options for filtering a function in the collection.
      */
-    interface SearchOptions {
+    interface GetItemsOptions extends ICollection.GetItemsOptions {
         /**
          * Search with the given name. This is case insensitive.
          */
@@ -9888,7 +9892,7 @@ export declare namespace IMovable {
 /**
  * Holds a collection of IMovables.
  */
-export declare interface IMovableCollection extends ICollection, IListener.ISource<IMovableCollection> {
+export declare interface IMovableCollection extends ICollection<IMovable>, IListener.ISource<IMovableCollection> {
     /**
      * Add a resource to the movable collection.
      *
@@ -9897,15 +9901,15 @@ export declare interface IMovableCollection extends ICollection, IListener.ISour
      */
     add(options?: IMovableCollection.AddOptions): Promise<IMovable>;
     /**
-     * Returns movables that match the search criteria.
+     * Returns movables that match the filter criteria.
      *
-     * @param options {@link IMovableCollection.SearchOptions}
+     * @param options {@link IMovableCollection.GetItemsOptions}
      * @returns An Array of {@link IMovable}.
      *
      * @remarks
-     * If no search criteria is provided, all items will be returned.
+     * If no filter criteria is provided, all items will be returned.
      */
-    search(options?: IMovableCollection.SearchOptions): IMovable[];
+    getItems(options?: IMovableCollection.GetItemsOptions): IMovable[];
     /**
      * Update all of the selected movable in a single transaction
      */
@@ -9937,9 +9941,9 @@ export declare interface IMovableCollection extends ICollection, IListener.ISour
  */
 export declare namespace IMovableCollection {
     /**
-     * Options for searching a collection of movables.
+     * Options for filtering a collection of movables.
      */
-    export interface SearchOptions {
+    export interface GetItemsOptions extends ICollection.GetItemsOptions {
         /**
          * If provided, the search will be limited to items that intersect the range.
          * @remarks
@@ -10250,7 +10254,7 @@ export declare namespace INamed {
 /**
  * A collection of `INamed` items.
  */
-export declare interface INamedCollection extends ICollection {
+export declare interface INamedCollection extends ICollection<INamed> {
     /**
      * Add a named reference.
      *
@@ -10273,10 +10277,10 @@ export declare interface INamedCollection extends ICollection {
      */
     add(named: INamed): INamed;
     /**
-     * Search the named items.
+     * Return the named items.
      * These are sorted by type then by name.
      */
-    search(options?: INamedCollection.SearchOptions): INamed[];
+    getItems(options?: INamedCollection.GetItemsOptions): INamed[];
     /**
      * Lookup a named range with a given name.
      *
@@ -10288,7 +10292,7 @@ export declare interface INamedCollection extends ICollection {
      * Lookup a named range by WorkbookRangeCoords. This will only
      * return a match if all the ranges are exact matches.
      *
-     * @deprecated Use search({ address }) instead.
+     * @deprecated Use getItems({ address }) instead.
      */
     lookupByRanges(ranges: ICellRanges.Address): INamed[] | null;
     /**
@@ -10369,7 +10373,7 @@ export declare namespace INamedCollection {
     }
     export interface IListeners extends IListener.Callbacks<INamedCollection, INamedCollection.Events> {
     }
-    export interface SearchOptions {
+    export interface GetItemsOptions extends ICollection.GetItemsOptions {
         /**
          * A string indicating the type.
          */
@@ -11210,7 +11214,7 @@ export declare namespace IResource {
 /**
  * Collections of {@link IResource}.
  */
-export declare interface IResourceCollection extends ICollection {
+export declare interface IResourceCollection extends ICollection<IResource> {
     /**
      * Add a resource to a collection with an initial reference.
      * @param resource
@@ -11218,6 +11222,11 @@ export declare interface IResourceCollection extends ICollection {
      * Resources are not removed from the the collection. They are autoGCed when there are no references.
      */
     add(resource: string | IResource | IResourceCollection.AddOptions): IResource;
+    /**
+     * Returns a list of all resources in the collection.
+     * @param options
+     */
+    getItems(options?: ICollection.GetItemsOptions): IResource[];
     /**
      * Used for saving resource. Returns a visitor that will allow for a toJSON that
      * will only save the resource that were accessed within the persist scope.
@@ -11258,6 +11267,8 @@ export declare namespace IResourceCollection {
          */
         name?: string;
     }
+    export interface GetItemsOptions extends ICollection.GetItemsOptions {
+    }
     export interface IPersistScope<J extends IResource.JSON> {
         /**
          * For a resource this will return a number that can be used to reference the resource in the persisted json.
@@ -12145,27 +12156,27 @@ export declare namespace ISheet {
 /**
  * Holds a collection of {@link ISheet}s.
  */
-export declare interface ISheetCollection extends ICollection {
+export declare interface ISheetCollection extends ICollection<ISheet> {
     /**
      * Add an `ISheet` to the collection.
      */
     add(options?: ISheetCollection.AddOptions): ISheet;
     /**
-     * Returns sheets that match the search criteria.
+     * Returns sheets that match the filter criteria.
      *
-     * If no search criteria is provided, all sheets will be returned.
+     * If no filter criteria is provided, all sheets will be returned.
      *
-     * @param options {@link ISheetCollection.SearchOptions}
+     * @param options {@link ISheetCollection.GetItemsOptions}
      */
-    search(options?: ISheetCollection.SearchOptions): ISheet[];
+    getItems(options?: ISheetCollection.GetItemsOptions): ISheet[];
     /**
      * Returns the sheet at the given index.
      * @param index
      * @returns
      */
     /**
-     * Convenience method for searching by name. This is
-     * functionally equivalent to search({ name });
+     * Convenience method for filtering by name. This is
+     * functionally equivalent to getItems({ name });
      *
      * @param name The name to search for This is case insensitive.
      */
@@ -12196,7 +12207,7 @@ export declare namespace ISheetCollection {
          */
         index?: number;
     }
-    export interface SearchOptions {
+    export interface GetItemsOptions extends ICollection.GetItemsOptions {
         /**
          * Indicate if items that are in hidden headers or marked as hidden should be returned.
          * @defaultValue false
@@ -13771,7 +13782,7 @@ declare const isQuoted: (str: string) => boolean;
 /**
  * Contains a collection of interned strings.
  */
-export declare interface IStringCollection extends ICollection, ICollection.IPersistable {
+export declare interface IStringCollection extends ICollection<string>, ICollection.IPersistable {
     /**
      * Add a string to the collection.
      *
@@ -13809,6 +13820,9 @@ export declare interface IStringCollection extends ICollection, ICollection.IPer
  * {@link IStringCollection}
  */
 export declare namespace IStringCollection {
+    export interface GetItemsOptions extends ICollection.GetItemsOptions {
+        id?: number;
+    }
     /**
      * Alias for persist type of `string`.
      */
@@ -15098,7 +15112,7 @@ export declare interface ITable extends IAnchored {
 /**
  * Holds a collection of {@link ITable}s.
  */
-export declare interface ITableCollection extends ICollection {
+export declare interface ITableCollection extends ICollection<ITable> {
     /**
      * Add an `ITable` to the container.
      *
@@ -15107,18 +15121,18 @@ export declare interface ITableCollection extends ICollection {
      */
     add(address: ICellRange.Address, options?: ITableCollection.AddOptions): ITable;
     /**
-     * Returns items that match the search criteria.
+     * Returns items that match the filter criteria.
      *
-     * If no search criteria is provided, all items will be returned.
+     * If no filter criteria is provided, all items will be returned.
      *
-     * @param options {@link ITableCollection.SearchOptions}
+     * @param options {@link ITableCollection.GetItemsOptions}
      */
-    search(options?: ITableCollection.SearchOptions): ITable[];
+    getItems(options?: ITableCollection.GetItemsOptions): ITable[];
     /**
-     * Convenience method for searching by name. This is
-     * functionally equivalent to search({ name });
+     * 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 name The name to filter for This is case insensitive.
      */
     getByName(name: string): ITable | null;
 }
@@ -15163,9 +15177,9 @@ export declare namespace ITableCollection {
          */
         isLoad?: boolean;
     }
-    export interface SearchOptions {
+    export interface GetItemsOptions {
         /**
-         * If provided, the search will be limited to items that intersect the range.
+         * If provided, the filter will be limited to items that intersect the range.
          */
         address?: ICellRange.Address;
         /**
@@ -15175,13 +15189,13 @@ export declare namespace ITableCollection {
          */
         excludeHidden?: boolean;
         /**
-         * Only return items that are completely contained with the search bounds.
+         * Only return items that are completely contained with the filter bounds.
          *
          * @defaultValue false
          */
         fullyContained?: boolean;
         /**
-         * Search with the given name. This is case insensitive.
+         * Filter with the given name. This is case insensitive.
          */
         name?: string;
     }
@@ -16237,7 +16251,7 @@ export declare namespace ITheme {
 /**
  * A collection of themes.
  */
-export declare interface IThemeCollection extends ICollection {
+export declare interface IThemeCollection extends ICollection<ITheme> {
     /**
      * Add or update a theme.
      *
@@ -16259,15 +16273,15 @@ export declare interface IThemeCollection extends ICollection {
      */
     getByName(name: string): ITheme | null;
     /**
-     * Returns all themes that match the search criteria.
+     * Returns all themes that match the filter criteria.
      *
-     * @param options {@link IThemeCollection.SearchOptions}
+     * @param options {@link IThemeCollection.GetItemsOptions}
      *
      * @remarks
-     * * If no search criteria is provided, all items will be returned.
+     * * If no filter criteria is provided, all items will be returned.
      * * Generates a new array so this can be mutated without affecting the internal state.
      */
-    search(options?: IThemeCollection.SearchOptions): ITheme[];
+    getItems(options?: IThemeCollection.GetItemsOptions): ITheme[];
     /**
      * Remove a custom theme.
      *
@@ -16299,22 +16313,22 @@ export declare interface IThemeCollection extends ICollection {
  */
 export declare namespace IThemeCollection {
     export type JSON = ITheme.JSON[];
-    export interface SearchOptions {
+    export interface GetItemsOptions extends ICollection.GetItemsOptions {
         /**
-         * @defaultValue `IThemeCollection.BuiltInSearchType.All`
+         * @defaultValue `IThemeCollection.BuiltInFilterType.All`
          */
-        type?: BuiltInSearchType;
+        type?: BuiltInFilterType;
         /**
-         * Allows for the search to return a specific theme even if not in the list.
+         * Allows for the filter to return a specific theme even if not in the list.
          */
         selected?: ITheme;
     }
-    const BuiltInSearchType: {
+    const BuiltInFilterType: {
         readonly BuiltIn: "builtIn";
         readonly All: "all";
         readonly Custom: "custom";
     };
-    export type BuiltInSearchType = typeof BuiltInSearchType[keyof typeof BuiltInSearchType];
+    export type BuiltInFilterType = typeof BuiltInFilterType[keyof typeof BuiltInFilterType];
 }
 
 /**
@@ -17526,18 +17540,13 @@ declare class LM {
 declare class MergeEntry {
     private _c;
     private _tvTl;
-    private _rsTl;
-    constructor(coords: IRange.Coords, tvTl?: (coords: IRange.Coords) => Scalar | null, rsTl?: (coords: IRange.Coords) => RangeState.Intersection | null);
+    constructor(coords: IRange.Coords, tvTl?: (coords: IRange.Coords) => Scalar | null);
     /**
      * The cell value at the top left.
      * We track this because we want a quick way to access
      * the coords state during overflow scenarios.
      */
     tvTl(): Scalar | null;
-    /**
-     * The range state at the top left.
-     */
-    rsTl(): RangeState.Intersection | null;
     getCoords(): IRange.Coords;
 }
 
@@ -18086,6 +18095,7 @@ declare namespace RangeState {
         bounds?: IRange.Coords;
         includeRangeTypes: boolean | SearchTypes;
         excludeHidden?: boolean | IRange.Orientation;
+        includeMergeOverflow?: boolean;
     }
     interface Entry {
         /**
@@ -18161,6 +18171,8 @@ export declare class ResourceCollection implements IResourceCollection {
     constructor();
     /** {@inheritDoc IResourceCollection.add} */
     add(res: string | IResource | IResourceCollection.AddOptions): IResource;
+    /** {@inheritDoc IResourceCollection.getItems} */
+    getItems(options?: IResourceCollection.GetItemsOptions): IResource[];
     /** {@inheritDoc IResourceCollection.getCount} */
     getCount(): number;
     /** {@inheritDoc IResourceCollection.beginPersist} */
@@ -19675,6 +19687,8 @@ export declare class StringCollection implements IStringCollection {
     addMultiple(shared: string[], conflateDuplicates?: boolean): void;
     /** {@inheritDoc IStringCollection.add} */
     add(shared: string): number;
+    /** {@inheritDoc IStringCollection.getItems} */
+    getItems(options?: IStringCollection.GetItemsOptions): string[];
     /** {@inheritDoc IStringCollection.getById} */
     getById(id: number): string;
     /** {@inheritDoc ICollection.getCount} */
@@ -20013,7 +20027,8 @@ export declare class ThemeCollection implements IThemeCollection {
     setDefaultTheme(theme: ITheme): ITheme;
     /** {@inheritDoc IThemeCollection.getByName} */
     getByName(name: string): ITheme | null;
-    search(options?: IThemeCollection.SearchOptions): ITheme[];
+    /** {@inheritDoc IThemeCollection.getByName} */
+    getItems(options?: IThemeCollection.GetItemsOptions): ITheme[];
     /** {@inheritDoc IThemeCollection.getCount} */
     getCount(): number;
     /** {@inheritDoc IThemeCollection.setCustomTheme} */