@sheetxl/sdk 0.7.21 → 0.7.23-beta.2

package/types/src/collections/ISpatialMap.d.ts

@@ -0,0 +1,515 @@
+import { Direction, CoordUtils, RangeCoords, RangeAxis } from '@sheetxl/utils';
+/**
+ * Data structure that allows for querying 2d rectangles.
+ */
+export interface ISpatialMap<T = any> extends ISpatialQuery<T> {
+    /**
+     * Returns `true` if there are any items within the range.
+     *
+     * @param range The range to search
+     */
+    has(range: Readonly<RangeCoords>): boolean;
+    /**
+     * Returns the smallest range that includes all ranges.
+     */
+    getBoundingRange(): RangeCoords;
+    /**
+     * A quick search for all.
+     */
+    size(): number;
+    /**
+     * Returns all entries in the map.
+     *
+     * @param results Optional array to store the results.
+     *
+     * @remarks
+     * Like {@link ISpatialQuery#search}, if the results are length 0 and the results parameter is not provided an readonly single array is returned.
+     */
+    all(results?: ISpatialMap.Entry<T>[]): ISpatialMap.Entry<T>[];
+    /**
+     * Visit all items within a range.
+     *
+     * @param range The range to visit.
+     * @param visitor The visitor function to call for each item.
+     * @param sort If provided, the ranges will be sorted in either row or column order. Default value is no sort.
+     */
+    visitRanges(range: Readonly<RangeCoords>, visitor: ISpatialMap.Visitor<T>, sort?: Direction): void;
+    /**
+     * Insert a an entry.
+     *
+     * @param entry The item to insert
+     * @remarks
+     * * This does not prevent duplicates. A remove is required.
+     * *
+     */
+    insert(entry: ISpatialMap.Entry): this;
+    /**
+     * Inserts a item but splits and merges all intersections to ensure no overlaps.
+     *
+     * @param entry The entry to add.
+     * @param options Options for adding non overlapping options.
+     *
+     * @remarks
+     * * This is much slower than a regular load so if the ranges are known to be non-overlapping
+     *   then the `load` method should be used.
+     */
+    insertNonOverlapping(entry: ISpatialMap.Entry<T>, options?: ISpatialMap.InsertNonOverlappingOptions<T>): this;
+    /**
+     * TODO - remove this.
+     *
+     * @param entries the entries to manage together
+     * @param uuid A unique identifier for the group.
+     *
+     * @deprecated Use AnchorMap instead
+     */
+    insertGroup(entries: ISpatialMap.Entry[], uuid: string): this;
+    /**
+     * Returns a set of non overlapping inserts and removes that would represent a copy.
+     *
+     * @param from The range to copy from.
+     * @param to The range to copy to
+     *
+     * @remarks
+     * This doesn't actually make the copy but returns the entries that would reflect a copy.
+     */
+    createCopiedEntries(from: RangeCoords, to: RangeCoords, options?: ISpatialMap.CopyOptions, reuseInsert?: ISpatialMap.Entry<T>[], reuseRemove?: ISpatialMap.Entry[]): ISpatialMap.Updates<T>;
+    /**
+     * Optimized bulk insert. This should be used when possible.
+     * @param entries A readonly list of RangeCoordValues
+     */
+    load(entries: ReadonlyArray<ISpatialMap.Entry>): this;
+    /**
+     * Shifts all ranges in a given direction.
+     *
+     * @param options The options for the shift.
+     */
+    shift(options: ISpatialMap.ShiftOptions<T>): this;
+    /**
+     * Remove item.
+     *
+     * @param entry The item to remove.
+     * @param equals A custom equal check to determine if the item should be returned.
+     */
+    remove(entry: ISpatialMap.Entry, equals?: (a: ISpatialMap.Entry, b: ISpatialMap.Entry) => boolean): this;
+    /**
+     * Removes multiple entries in a single tree traversal.
+     *
+     * @param entries The items to remove.
+     * @param equals A custom equal check to determine if the item should be returned.
+     */
+    removeAll(entries: ISpatialMap.Entry<T>[], equals?: (a: ISpatialMap.Entry<T>, b: ISpatialMap.Entry<T>) => boolean): this;
+    /**
+     * Clear the tree.
+     */
+    clear(): this;
+    /**
+     * Delete all values within a range.
+     *
+     * @param coords The range to delete.
+     */
+    delete(coords: RangeCoords | null): this;
+    /**
+     * Returns a copy on write clone.
+     *
+     * @param cloneKey A performance optimization that will avoid cloning if the same key is used.
+     *
+     * @remarks
+     * If the same clone key is used then the same instance will be returned.
+     */
+    clone(cloneKey?: any): this;
+}
+/**
+ * {@inheritDoc ISpatialMap}
+ * @see
+ * ### **Interface**
+ *
+ * {@link ISpatialMap}
+ */
+export declare namespace ISpatialMap {
+    /**
+     * A visitor function that is called for each item in a range.
+     */
+    type Visitor<T = any> = (entry: ISpatialMap.Entry<T>) => ISpatialMap.VisitorResults<T>;
+    /**
+     * Allows for the visitor to update the results.
+     */
+    type VisitorResults<T = any> = {
+        update?: ISpatialMap.Entry<T>;
+        delete?: boolean;
+        break?: boolean;
+    } | void;
+    interface Entry<T = any> extends RangeCoords {
+        value?: T;
+        uuid?: string;
+        /**
+         * If the entry is the results of a split or a merge.
+         */
+        lastId?: string;
+    }
+    /**
+     * Optional interface for spatial map values that need custom behavior
+     * during split, merge, shift, and copy operations.
+     *
+     * Values that do not implement this are reused as-is (immutable) during spatial operations.
+     * Values that do implement use the methods callbacks for each spatial operation.
+     */
+    interface IUpdatableValue<T = any> {
+        /**
+         * Splits the range into multiple sub-ranges based on specified coordinates and axis.
+         *
+         * @param destination The destination coordinates for the split.
+         * @param axis The axis (horizontal/vertical) of the split.
+         * @returns An array of the split ranges.
+         * @throws Will throw an error if the split cannot be performed.
+         *
+         * @remarks
+         * This method allows for dividing the range into smaller segments. If splitting
+         * is not supported, an error will be thrown.
+         */
+        getSplit?(destination: readonly [RangeCoords, RangeCoords], axis: RangeAxis, offset: number): [T, T] | undefined;
+        /**
+         * Attempts to merge this range with another range, based on specified coordinates
+         * and axis. Returns a new merged range or `undefined` if merging is not possible.
+         *
+         * @param other The other range to merge with.
+         * @param coords The coordinates of the merged range.
+         * @param axis The axis (horizontal/vertical) for merging.
+         * @returns A new merged range if successful, or `undefined` if merging is not possible.
+         *
+         * @remarks
+         * This method always returns a merged range that is aligned to the left/top.
+         */
+        getMerged?(other: T, coords: RangeCoords, axis: RangeAxis): T | undefined;
+        /**
+         * Called when the range is shifted.
+         *
+         * @param options The details of the shift operation.
+         * @returns The new shifted range entry, `null` if the entry was deleted by the shift, or
+         * `undefined` if shifting is not possible.
+         *
+         * @remarks
+         * * Always happens in a direction. If not implemented, a shift will still occur.
+         * * An insert will attempt to resize, then split, then error.
+         * * A delete will attempt to resize, then split, then error.
+         */
+        getShifted?(options: ISpatialMap.ShiftDetails<T>): ISpatialMap.Entry<T> | [ISpatialMap.Entry<T>, ISpatialMap.Entry<T>] | null | undefined;
+        /**
+         * Called when the node is being removed.
+         *
+         * @param coords The coordinates of the range being removed.
+         *
+         * @remarks
+         * TODO - This is not reliably called.
+         */
+        onRemove?(entry: ISpatialMap.Entry<T>): void;
+        /**
+         * Copies the range to a specified destination.
+         *
+         * @param destination The destination coordinates.
+         * @param options Optional parameters for the copy operation.
+         * @returns The copied range.
+         *
+         * @remarks
+         * The destination is guaranteed to be a multiple of the RangeCoords.
+         * Will tile if `canTile` returns `true`; otherwise, the size will always be the same.
+         */
+        copyTo?(destination: RangeCoords, options?: ISpatialMap.CopyOptions): ISpatialMap.Entry<T> | undefined;
+        /**
+         * Returns a flag indicating whether the range can be tiled.
+         *
+         * @param destination The destination coordinates.
+         * @param options Optional parameters for the tiling operation.
+         * @returns `true` if the range can be tiled; otherwise, `false`.
+         *
+         * @remarks
+         * If missing or not implemented, it is assumed that the range cannot be tiled.
+         */
+        canTile?(destination: RangeCoords, options?: ISpatialMap.CopyOptions): boolean | RangeAxis;
+    }
+    /**
+     * External callbacks for customizing how values are split, merged,
+     * shifted, and copied during spatial map mutations.
+     */
+    interface UpdateOptions<T = any> {
+        /**
+         * This will be recursively called to break ranges into smaller parts to ensure there is no
+         * overlap.
+         *
+         * @param from The entry that is being split
+         * @param destination The default splits
+         * @param axis The axis.
+         * @param offset The offset. 0 is far left.
+         * @throws - Error if the split cannot be performed.
+         * @returns An array of 2 values that represent the values for the split.
+         */
+        getSplit?(from: ISpatialMap.Entry<T>, destination: [ISpatialMap.Entry<T>, ISpatialMap.Entry<T>], axis: RangeAxis, offset: number): [ISpatialMap.Entry<T>, ISpatialMap.Entry<T>] | null;
+        /**
+         * Attempts to merge two entries in an axis. Returns a new merged entry or `undefined` if merging is not possible.
+         *
+         * @param from The other range to merge with.
+         * @param destination The coordinates of the merged range.
+         * @param axis The axis (horizontal/vertical) for merging.
+         * @returns A new merged range if successful, or `undefined` if merging is not possible.
+         *
+         * @remarks
+         * This method always returns a merged range that is aligned to the left/top.
+         */
+        getMerged?(from: [ISpatialMap.Entry<T>, ISpatialMap.Entry<T>], destination: ISpatialMap.Entry<T>, axis: RangeAxis): ISpatialMap.Entry<T> | null | undefined;
+        /**
+         * Return a shifted range.
+         *
+         * @param options The details of the shift operation.
+         * @returns The new shifted range entry, or `undefined` if shifting is not possible.
+         *
+         * @remarks
+         * * Always happens in a direction. If not implemented, a shift will still occur.
+         * * An insert will attempt to resize, then split, then error.
+         * * A delete will attempt to resize, then split, then error.
+         */
+        getShifted?(from: ISpatialMap.Entry<T>, destination: ISpatialMap.Entry<T>, options: ISpatialMap.ShiftDetails<T>): ISpatialMap.Entry<T> | undefined;
+        /**
+         * Called after all splitting for any ranges that intersect.
+         *
+         * @param orig A node with the original value.
+         * @param adj A node with the adjusted value.
+         * @returns The value for the intersected ranges.
+         *
+         * @remarks
+         * * This can be called multiple times on a single inset with different bounds and values to due splits.
+         */
+        getIntersect?(orig: ISpatialMap.Entry<T>, adj: ISpatialMap.Entry<T>): ISpatialMap.Entry<T> | null;
+        /**
+         * Copies the entry to a specified destination.
+         *
+         * @param destination The destination coordinates.
+         * @param options Optional parameters for the copy operation.
+         * @returns A new entry.
+         *
+         * @remarks
+         * The destination is guaranteed to be a multiple of the RangeCoords.
+         * Will tile if `canTile` returns `true`; otherwise, the size will always be the same.
+         */
+        copyTo?(from: ISpatialMap.Entry<T>, destination: RangeCoords, options?: ISpatialMap.CopyOptions): ISpatialMap.Entry<T>;
+        /**
+         * Returns a flag indicating whether the range can be tiled.
+         *
+         * @param destination The destination coordinates.
+         * @param options Optional parameters for the tiling operation.
+         * @returns `true` if the range can be tiled; otherwise, `false`.
+         *
+         * @remarks
+         * If missing or not implemented, it is assumed that the range cannot be tiled.
+         */
+        canTile?(orig: ISpatialMap.Entry<T>, destination: RangeCoords, options?: ISpatialMap.CopyOptions): boolean | RangeAxis;
+        /**
+         * Called on all nodes that have been modified by either a split or an insert but not a shift.
+         *
+         * @param adj The adjust node.
+         *
+         * @remarks
+         * * Provides a hook to track all changes.
+         * * If `null` is return then this will be culled.
+         */
+        getUpdate?(adj: ISpatialMap.Entry<T>): ISpatialMap.Entry<T> | null | void;
+        /**
+         * Called for all nodes that are being shifted.
+         */
+        onShifted?(shifted: ISpatialMap.Entry<T>[]): void;
+        /**
+         * called when a range is removed. This can be due to
+         * either a remove of the entry of a shift.
+         *
+         * @param removes
+         */
+        onRemoved?(removes: ISpatialMap.Entry<T>[]): void;
+        /**
+         * Called when a value is inserted or updated.
+        */
+        onUpdated?(updates: ISpatialMap.Entry<T>[]): void;
+        /**
+         * Called when a group of ranges are merged together.
+         */
+        onMerged?(onMerges: ISpatialMap.Entry<T>[]): void;
+        /**
+         * Called when a group is updated.
+         *
+         * @param entries All entries in the group.
+         * @param uuid Any params argument passed a modification option.
+         */
+        onGroupUpdate?(entries: ISpatialMap.Entry<T>[], uuid?: string): void;
+        /**
+         * Called after structure has been updated with for any reason with all
+         * inserts and removes.
+         *
+         * @param insert All new entries.
+         * @param remove All removed entries.
+         */
+        onUpdates?(inserts: ISpatialMap.Entry<T>[], removes: ISpatialMap.Entry<T>[], spatial: ISpatialMap): void;
+        /**
+         * Indicates whether shifting should occur when an insert is made on the trailing row or column.
+         *
+         * @defaultValue `false`
+         *
+         * @remarks
+         * Useful for ranges that shift the value immediately before on an insert (e.g., styles).
+         */
+        isTrailingEdge?: boolean;
+        /**
+         * Indicates if the entries should split when the range is expanding.
+         *
+         * @defaultValue `false`
+         *
+         * @remarks
+         * Examples include formula, comments, and conditional formatting
+         */
+        isSplitOnExpand?: boolean;
+        /**
+         * If `true` then after shift any shift entries will attempt to be merged to their nearest neighbors.
+         *
+         * @defaultValue `false`
+         *
+         * @remarks
+         * This will cause merge to fail it there are any overlapping ranges.
+         * Examples include styles.
+         */
+        isMergeOnShift?: boolean;
+        /**
+         * Default for merge
+         */
+        noMerge?: boolean;
+    }
+    /**
+     * Options for the shift method on the Index.
+     */
+    interface ShiftOptions<T> {
+        /**
+         * The range to shift.
+         */
+        range: RangeCoords;
+        /**
+         * The direction to shift.
+         */
+        direction: Direction;
+        /**
+         * Allows for a a validation of the range after the shift amount is determined
+         * but before this shift is performed.
+         *
+         * @remarks
+         * * Useful when performing inserts that may fall outside of the bounds.
+         */
+        coordValidator?: CoordUtils.CoordValidator;
+        /**
+         * If `true` the this will return a clone index if there are any modifications.
+         *
+         * @defaultValue false
+         *
+         * @remarks
+         * This allows for a 0-1 clone on write.
+         */
+        cloneIfUpdate?: boolean;
+        /**
+         * If provided this will be called to update to ensure the location if valid.
+         */
+        onShift?: (options: ISpatialMap.ShiftDetails<T>) => void;
+        /**
+         * Callback for all inserts and removes
+         */
+        onUpdates?(inserts: ISpatialMap.Entry<T>[], removes: ISpatialMap.Entry<T>[], spatial: ISpatialMap): void;
+    }
+    /**
+     * Options for {@link ISpatialMap.insertNonOverlappingOptions}
+     */
+    interface InsertNonOverlappingOptions<T> {
+        /**
+         * Callback function that will be be called on insert.
+         *
+         * @remarks
+         * If see this will be called for each new entry creation with the original entry.
+         */
+        onIntersect?: (orig: ISpatialMap.Entry<T>, adj: ISpatialMap.Entry<T>) => ISpatialMap.Entry<T>;
+        onUpdates?(inserts: ISpatialMap.Entry<T>[], removes: ISpatialMap.Entry<T>[], spatial: ISpatialMap): void;
+        /**
+         * If `true` then insert will not attempt to merge fragmented entries.
+         *
+         * @remarks
+         * Useful when you want to merge all entries at the end.
+         */
+        noMerge?: boolean;
+    }
+    /**
+     * Pair of spatial updates when doing batch updates.
+     */
+    interface Updates<T = any> {
+        inserts: ISpatialMap.Entry<T>[];
+        removes: ISpatialMap.Entry[];
+    }
+    /**
+     * Details about the shift operation.
+     */
+    interface ShiftDetails<T = any> {
+        before: ISpatialMap.Entry<T>;
+        after: ISpatialMap.Entry<T> | null;
+        intersect: RangeCoords;
+        isSplit: boolean;
+        axis: RangeAxis;
+        amount: number;
+    }
+    /** Options */
+    interface ConstructorOptions<T = any> {
+        /**
+         * Options for managing updates,splits, and merges.
+         */
+        updateEntryOptions?: ISpatialMap.UpdateOptions<T>;
+        /**
+         * @param maxEntries An optional argument to RTree defines the maximum number of entries in a tree node. Higher
+         *                   value means faster insertion and slower search, and vice versa.
+         * @defaultValue 9.
+         */
+        maxNodeEntries?: number;
+    }
+    interface CopyOptions {
+        transpose?: boolean;
+    }
+    /**
+     * Interface for creating entries using a similar approach
+     * to tuple builder.
+     */
+    interface IConflatingEntries<T = any> {
+        /**
+         * Append a major minor value with an optional value. The value can be left empty if the value is not needed or can be derived from the major and minor.
+         */
+        append: (major: number, minor: number, value?: T) => void;
+        /**
+         * Returns the conflated entries. If `merge` is `true` then adjacent entries will be merged into a single entry with a range that covers both entries. If `false` then each entry will be returned as-is.
+         */
+        done: (merge?: boolean) => ISpatialMap.Entry<T>[];
+    }
+}
+export interface ISpatialQuery<T = any> {
+    /**
+     * Returns all items within the search range.
+     *
+     * @param range The range to search
+     * @param fullyContained Only search for ranges that are completely contained with the search range. DefaultValue `false`.
+     * @param sort Will use the sort of the spatial
+     * @param results Optional array to store the results.
+     *
+     * @remarks
+     * If the results are length 0 and the results parameter is not provided an readonly single array is returned.
+     *
+     * The returned array is **borrowed and read-only** — implementations may hand back an array they
+     * own and reuse (`SpatialMap._lastSingleResult`, `AnchoredMap._cacheSearchResults`). Sorting,
+     * splicing or otherwise mutating it in place corrupts the implementation's cache, so copy first
+     * (or pass `results` and let the entries be appended to an array you own).
+     */
+    search(range: Readonly<RangeCoords>, fullyContained?: boolean, sort?: boolean, results?: ISpatialMap.Entry<T>[]): ISpatialMap.Entry<T>[];
+    /**
+     * Returns the bounding range for the content
+     */
+    getBoundingRange(): RangeCoords;
+    /**
+     * Just like `size === 0` but even quicker.
+     */
+    isEmpty(): boolean;
+}
+//# sourceMappingURL=ISpatialMap.d.ts.map

package/types/src/collections/ISpatialMap.d.ts.map

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

package/types/src/collections/ISpatialMap3D.d.ts

@@ -0,0 +1,116 @@
+import { RangeCoords } from '@sheetxl/utils';
+import { ISpatialMap, ISpatialQuery } from './ISpatialMap';
+/**
+ * A 3D spatial map: a collection of per-scope 2D spatial maps keyed by a scope string.
+ *
+ * This is deliberately NOT an {@link ISpatialMap}. Every operation routes to the owning
+ * 2D map via `scope` on the coords, so the whole-map operations of a 2D map (`all`,
+ * `clear`, `size`, `visitRanges`, ...) do not apply; use {@link ISpatialMap3D.getSpatialAt}
+ * to operate on a single scope, or {@link ISpatialMap3D.all3D} to enumerate across scopes.
+ *
+ * Entries stored inside each per-scope 2D map always carry `scope` equal to the map's key
+ * (stamped on insert if missing). Within a single 2D map, `scope` never participates in
+ * coordinate comparisons.
+ *
+ * * This allows for lazy cloning.
+ * * Load and remove will delegate to the 2D map for the scope.
+ */
+export interface ISpatialMap3D<T = any> extends ISpatialQuery<T> {
+    /**
+     * Returns `true` if there are any items within the range.
+     *
+     * @param range The range to search. Must have a `scope`.
+     */
+    has(range: Readonly<RangeCoords>): boolean;
+    /**
+     * Insert an entry into the 2D map for its `scope`.
+     *
+     * @param entry The item to insert. Must have a `scope`.
+     * @remarks
+     * * This does not prevent duplicates. A remove is required.
+     */
+    insert(entry: ISpatialMap.Entry<T>): this;
+    /**
+     * Inserts an item but splits and merges all intersections to ensure no overlaps,
+     * within the 2D map for its `scope`.
+     *
+     * @param entry The entry to add. Must have a `scope`.
+     * @param options Options for adding non overlapping options.
+     */
+    insertNonOverlapping(entry: ISpatialMap.Entry<T>, options?: ISpatialMap.InsertNonOverlappingOptions<T>): this;
+    /**
+     * Optimized bulk insert. Entries are grouped by `scope` and batch-loaded per 2D map.
+     *
+     * @param entries A readonly list of entries. Each must have a `scope`.
+     */
+    load(entries: ReadonlyArray<ISpatialMap.Entry<T>>): this;
+    /**
+     * Shifts all ranges of the scoped 2D map in a given direction.
+     *
+     * @param options The options for the shift. `options.range` must have a `scope`.
+     */
+    shift(options: ISpatialMap.ShiftOptions<T>): this;
+    /**
+     * Remove item from the 2D map for its `scope`.
+     *
+     * @param entry The item to remove. Must have a `scope`.
+     * @param equals A custom equal check to determine if the item should be removed.
+     */
+    remove(entry: ISpatialMap.Entry<T>, equals?: (a: ISpatialMap.Entry<T>, b: ISpatialMap.Entry<T>) => boolean): this;
+    /**
+     * Removes multiple entries, grouped by `scope`, in a single traversal per 2D map.
+     *
+     * @param entries The items to remove. Each must have a `scope`.
+     * @param equals A custom equal check to determine if the item should be removed.
+     */
+    removeAll(entries: ISpatialMap.Entry<T>[], equals?: (a: ISpatialMap.Entry<T>, b: ISpatialMap.Entry<T>) => boolean): this;
+    /**
+     * Delete all values within a range of the scoped 2D map.
+     *
+     * @param coords The range to delete. Must have a `scope`.
+     */
+    delete(coords: RangeCoords | null): this;
+    /**
+     * Returns a copy on write clone.
+     *
+     * @param cloneKey A performance optimization that will avoid cloning if the same key is used.
+     */
+    clone(cloneKey?: any): this;
+    /**
+     * Returns a set of non overlapping inserts and removes that would represent a copy,
+     * within the 2D map for `from.scope`. Returned entries are stamped with the scope.
+     *
+     * @param from The range to copy from. Must have a `scope`.
+     * @param to The range to copy to.
+     */
+    createCopiedEntries(from: RangeCoords, to: RangeCoords, options?: ISpatialMap.CopyOptions, reuseInsert?: ISpatialMap.Entry<T>[], reuseRemove?: ISpatialMap.Entry[]): ISpatialMap.Updates<T>;
+    /**
+     * Get all scopes in the 3D spatial map.
+     */
+    getScopeEntries(): MapIterator<[string, ISpatialMap<T>]>;
+    /**
+     * Get all scope keys in the 3D spatial map.
+     */
+    getScopeKeys(): MapIterator<string>;
+    /**
+     * Get all scope values in the 3D spatial map.
+     */
+    getScopeValues(): MapIterator<ISpatialMap<T>>;
+    /**
+     * Returns the 2D spatial map for a given scope, or undefined if it doesn't exist.
+     */
+    getSpatialAt(scope?: string): ISpatialMap<T>;
+    /**
+     * Returns all entries in the 3D map.
+     *
+     * @param results Optional array to store the results.
+     *
+     * @remarks
+     * This will return every entry and include a scope.
+     * * This is not very efficient, so use with caution.
+     * If you just need the entries for a specific scope, it's better to get the 2D map
+     * for that scope and call all() on it.
+     */
+    all3D(results?: ISpatialMap.Entry<T>[]): ISpatialMap.Entry<T>[];
+}
+//# sourceMappingURL=ISpatialMap3D.d.ts.map

package/types/src/collections/ISpatialMap3D.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ISpatialMap3D.d.ts","sourceRoot":"","sources":["../../../../src/collections/ISpatialMap3D.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAElD,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,aAAa,EAAE,MAAM,eAAe,CAAC;AAErE;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC,GAAC,GAAG,CAAE,SAAQ,aAAa,CAAC,CAAC,CAAC;IAE5D;;;;OAIG;IACH,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAC,WAAW,CAAC,GAAG,OAAO,CAAC;IAE3C;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAE1C;;;;;;OAMG;IACH,oBAAoB,CAAC,KAAK,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,WAAW,CAAC,2BAA2B,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAE9G;;;;OAIG;IACH,IAAI,CAAC,OAAO,EAAE,aAAa,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAEzD;;;;OAIG;IACH,KAAK,CAAC,OAAO,EAAE,WAAW,CAAC,YAAY,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAElD;;;;;OAKG;IACH,MAAM,CACJ,KAAK,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,EAC3B,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,OAAO,GACrE,IAAI,CAAC;IAER;;;;;OAKG;IACH,SAAS,CACP,OAAO,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAC/B,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,OAAO,GACrE,IAAI,CAAC;IAER;;;;OAIG;IACH,MAAM,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,GAAG,IAAI,CAAC;IAEzC;;;;OAIG;IACH,KAAK,CAAC,QAAQ,CAAC,EAAE,GAAG,GAAG,IAAI,CAAC;IAE5B;;;;;;OAMG;IACH,mBAAmB,CACjB,IAAI,EAAE,WAAW,EACjB,EAAE,EAAE,WAAW,EACf,OAAO,CAAC,EAAE,WAAW,CAAC,WAAW,EACjC,WAAW,CAAC,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EACpC,WAAW,CAAC,EAAE,WAAW,CAAC,KAAK,EAAE,GAChC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAE1B;;OAEG;IACH,eAAe,IAAI,WAAW,CAAC,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAEzD;;OAEG;IACH,YAAY,IAAI,WAAW,CAAC,MAAM,CAAC,CAAC;IAEpC;;OAEG;IACH,cAAc,IAAI,WAAW,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;IAE9C;;OAEG;IACH,YAAY,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC;IAE7C;;;;;;;;;;OAUG;IACH,KAAK,CAAC,OAAO,CAAC,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;CACjE"}