@sheetxl/sdk 0.7.27 → 0.7.28-beta.1

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

@@ -0,0 +1,120 @@
+import { RunCoords } from '@sheetxl/utils';
+import { IList, IListLike } from './IList';
+/**
+ * Add iteration and additional read operations to {@link IList} collections.
+ *
+ * Iterations have {@link IReadableList.IterableIterator} for entries.
+ */
+export interface IReadableList<T = any> extends IList<T> {
+    /**
+     * Creates an entries iterator that respects the provided {@link IReadableList.IteratorOptions}
+     * and allows for optional random access through the `next` method.
+     *
+     * The `next` method can be used in two ways:
+     *
+     * **Sequential Iteration:**
+     * ```typescript
+     * const iterator = list.entries(options);
+     * let result = iterator.next(); // Get the first entry
+     * while (!result.done) {
+     *   // Process result.value (the current entry)
+     *   result = iterator.next();
+     * }
+     * ```
+     *
+     * **Random Access:**
+     * ```typescript
+     * const iterator = list.entries(options);
+     * const entryAtIndex3 = iterator.next(3).value; // Get entry at index 3
+     * // Note: The iterator is now positioned at index 4 for subsequent calls
+     * ```
+     *
+     * @param options Configuration options for the iterator.
+     * @returns An iterator yielding entries in the form of `[key, value]` pairs.
+     */
+    entries(options?: IReadableList.IteratorOptions): IReadableList.EntryIterator<T>;
+    /**
+     * Returns an iterable of value for the list.
+     */
+    [Symbol.iterator](): IterableIterator<T>;
+    /**
+     * Behaves like Array slice but doesn't perform a shallow copy.
+     * @see
+     * * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/slice}
+     */
+    slice(start: number, end?: number): IReadableList<T>;
+    /**
+     * Behaves like Array concat but doesn't perform a shallow copy.
+     * @param list The IReadableList to concat.
+     * @see
+     * * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/concat}
+     */
+    concat(list: IListLike<T>): IReadableList<T>;
+    /**
+     * Return the List as an Array. This does a deep copy.
+     * @param maxLength Maximum number of elements.
+     */
+    toArray(maxLength?: number): T[];
+    /**
+     * For runtime type checking.
+     */
+    readonly isIReadableList: true;
+}
+/**
+ * {@inheritDoc IReadableList}
+ * @see
+ * ### **Interface**
+ *
+ * {@link IReadableList}
+ */
+export declare namespace IReadableList {
+    /**
+     * Allow for iterating over a subset of values in a given direction.
+     */
+    interface IteratorOptions<T = any> {
+        /**
+         * If not specified or null then all values will be iterated.
+         * @defaultValue null
+         * @remarks
+         * The min and max are always small to largest regardless of reverse flag.
+         */
+        bounds?: Partial<RunCoords>;
+        /**
+         * Iterate in reverse order.
+         *
+         * @defaultValue false
+         */
+        reverse?: boolean;
+        /**
+         * A callback function that allows customization of the iteration process by skipping specific indices.
+         * @param index The next index that would normally be processed in the iteration.
+         * @param reverse Indicates if the iteration is reversed. This defaults to the reverse option.
+         * @returns A new index 'next index' to process, or the original `index` if no skipping is desired.
+         *
+         * @remarks
+         * This callback is invoked before the iterator yields the value at the given `index`. By returning a different index, you can control the flow of the iteration and skip over certain elements.
+         */
+        processSkip?: (index: number, reverse: boolean) => number;
+        /**
+         * Provide an IteratorResult object to reuse.
+         *
+         * This is a performance optimization that will return the same iterator result and with with the values updated.
+         * This reduces the temporary objects being created but care must be take to not the iterator result instance.
+         * @defaultValue false
+         */
+        reuseResult?: IReadableList.EntryIteratorResult<T>;
+    }
+    /**
+     * Entries iterators are arrays of fixed length 2.
+     */
+    type Entry<T = any> = [number, T];
+    /**
+     * Shorthand type.
+     */
+    type EntryIteratorResult<T = any> = IteratorResult<IReadableList.Entry<T>>;
+    /**
+     * Shorthand type.
+     */
+    type EntryIterator<T = any> = Iterator<IReadableList.Entry<T>, IReadableList.Entry<T>, number>;
+}
+//# sourceMappingURL=IReadableList.d.ts.map

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

@@ -0,0 +1,171 @@
+/**
+ * A sorted key-value map.
+ *
+ * Keys are maintained in sort order, enabling efficient range queries, ordered
+ * iteration, and O(log size) lookup. Range methods (`forEach`, `forRange`) support
+ * early exit: return `{ break: R }` from the callback to stop and return `R`; otherwise
+ * they return the count of pairs visited.
+ *
+ * **Supported key types out of the box:** numbers, strings, `Date`, arrays of
+ * numbers/strings, and objects with a `valueOf()` returning any of the above.
+ * Symbols are not supported (they have no natural order). Custom types require
+ * a comparator passed to the constructor.
+ *
+ * **`forEach` argument order:** for ES6 `Map` compatibility the callback receives
+ * `(value, key)` — the reverse of most sorted-map APIs. Use `forEachPair(key, value)`
+ * if you want key first; it is also slightly faster.
+ *
+ * @example
+ * Sort by name then age with a custom comparator:
+ * ```ts
+ * const map = new SortedMap(undefined, (a, b) => {
+ *   if (a.name !== b.name) return a.name > b.name ? 1 : -1;
+ *   return a.age - b.age;
+ * });
+ * map.set({ name: "Bill", age: 17 }, "happy");
+ * map.set({ name: "Fran", age: 40 }, "busy");
+ * map.forEachPair((k, v) => console.log(k.name, k.age, v));
+ * ```
+ *
+ * @remarks
+ * Follows the collections pattern and is persistent (copy-on-write). Writes mutate the
+ * current instance; use `clone()` to capture a snapshot before mutating.
+ */
+export interface ISortedMap<K = any, V = any> {
+    /** Number of key-value pairs in the map. */
+    readonly size: number;
+    /** Returns the value associated with `key`, or `undefined` if not found. O(log size). */
+    get(key: K): V | undefined;
+    /** Returns `true` if `key` exists in the map. O(log size). */
+    has(key: K): boolean;
+    /**
+     * Iterates all pairs, calling `callback` for each. Supports early exit: if `callback`
+     * returns `{ break: R }`, iteration stops and that value is returned; otherwise returns
+     * the count of pairs visited.
+     */
+    forEach<R = number>(callback: (v: V, k: K, map: ISortedMap<K, V>) => {
+        break?: R;
+    } | void, thisArg?: any): R | number;
+    /** Returns an iterator of `[key, value]` pairs in ascending order, starting at `firstKey`. */
+    entries(firstKey?: K, reusedResults?: IteratorResult<[K, V], any>): IterableIterator<[K, V]>;
+    /**
+     * Returns an iterator of `[key, value]` pairs in descending order, starting at `highestKey`
+     * (or `maxKey()` if omitted). If `highestKey` does not exist, iteration starts at the next
+     * lower key. Pass `skipHighest: true` to exclude `highestKey` itself.
+     */
+    entriesReversed(highestKey?: K, reusedResults?: IteratorResult<[K, V], any>, skipHighest?: boolean): IterableIterator<[K, V]>;
+    /** Returns an iterator of keys in ascending order, starting at `firstKey`. */
+    keys(firstKey?: K, reusedResults?: IteratorResult<[K, V], any>): IterableIterator<K>;
+    /** Returns an iterator of values in ascending order by key, starting at `firstKey`. */
+    values(firstKey?: K, reusedResults?: IteratorResult<[K, V], any>): IterableIterator<V>;
+    /** Returns the lowest key, or `undefined` if the map is empty. O(log size). */
+    minKey(): K | undefined;
+    /** Returns the highest key, or `undefined` if the map is empty. O(1). */
+    maxKey(): K | undefined;
+    /**
+     * Returns the next key larger than `key`, or the lowest key if `key` is undefined.
+     */
+    nextHigherKey(key?: K): K | undefined;
+    /**
+     * Returns the next key smaller than `key`, or the highest key if `key` is undefined.
+     */
+    nextLowerKey(key?: K): K | undefined;
+    /** Returns the next pair whose key is larger than `key`, or the lowest pair if `key` is `undefined`. */
+    nextHigherPair(key?: K, reusedPair?: [K, V]): [K, V] | undefined;
+    /** Returns the next pair whose key is smaller than `key`, or the highest pair if `key` is `undefined`. */
+    nextLowerPair(key?: K, reusedPair?: [K, V]): [K, V] | undefined;
+    /**
+     * Returns the pair for `key` if it exists, otherwise the next higher pair.
+     * Returns `undefined` if there is no pair at or above `key`.
+     */
+    getPairOrNextHigher(key: K, reusedPair?: [K, V]): [K, V] | undefined;
+    /**
+     * Returns the pair for `key` if it exists, otherwise the next lower pair.
+     * Returns `undefined` if there is no pair at or below `key`.
+     */
+    getPairOrNextLower(key: K, reusedPair?: [K, V]): [K, V] | undefined;
+    /**
+     * Calls `onFound` for each key-value pair in the range `[low, high]`, in ascending order.
+     * Supports early exit: if `onFound` returns `{ break: R }`, iteration stops and `R` is returned.
+     *
+     * @returns The number of pairs visited, or `R` if the callback broke early.
+     */
+    forRange<R = number>(low: K, high: K, includeHigh: boolean, onFound?: ISortedMap.EditRangeCallback<K, V, R>, initialCounter?: number): R | number;
+    /**
+     * Returns an array of pairs in the range `[low, high]`, sorted by key.
+     */
+    getRange(low: K, high: K, includeHigh?: boolean, maxLength?: number): [K, V][];
+    /**
+     * Combines all pairs into a single value by calling `callback` for each pair in ascending order.
+     * `reduce((sum, [k, v]) => sum + v, 0)` sums all values.
+     */
+    reduce<R>(callback: (previous: R, currentPair: [K, V], counter: number) => R, initialValue: R): R;
+    reduce<R>(callback: (previous: R | undefined, currentPair: [K, V], counter: number) => R): R | undefined;
+    /**
+     * Adds or updates a key-value pair.
+     * @param overwrite If false and the key already exists, the call has no effect (default: true).
+     * @returns `true` if a new pair was inserted.
+     */
+    set(key: K, value: V, overwrite?: boolean | ISortedMap.SetPairCallback<K, V>): boolean;
+    /** Removes the pair with the given key. Returns `true` if a pair was found and removed. O(log size). */
+    delete(key: K): boolean;
+    /** Removes all key-value pairs from the map. */
+    clear(): void;
+    /**
+     * Inserts or updates multiple pairs.
+     * @returns The number of new pairs inserted.
+     */
+    setPairs(pairs: [K, V][], overwrite?: boolean | ISortedMap.SetPairCallback<K, V>): number;
+    /** Deletes multiple keys in one pass. Returns the number deleted. */
+    deleteKeys(keys: K[]): number;
+    /**
+     * Deletes all pairs in the range `[low, high]`.
+     * @returns The number of pairs deleted.
+     */
+    deleteRange(low: K, high: K, includeHigh: boolean): number;
+    /**
+     * Scans and potentially modifies values for a subsequence of keys.
+     * The callback may return `{ value }` to update, `{ delete: true }` to remove,
+     * `{ break: R }` to stop early, or void to leave the pair unchanged.
+     *
+     * @remarks
+     * The callback must not insert items or call `clone()` during iteration.
+     * Complexity: O(items scanned + log size).
+     */
+    editRange<R = V>(low: K, high: K, includeHigh: boolean, onFound: ISortedMap.EditRangeCallback<K, V, R>, initialCounter?: number): R | number;
+    /** Returns a shallow copy of the map (copy-on-write — O(1)). */
+    clone(): ISortedMap<K, V>;
+    /** Returns a copy of the map with pairs removed whenever `callback` returns false. */
+    filter(callback: (k: K, v: V, counter: number) => boolean, returnThisIfUnchanged?: boolean): ISortedMap<K, V>;
+    /** Returns a copy of the map with every value replaced by the result of `callback`. */
+    mapValues<R>(callback: (v: V, k: K, counter: number) => R): ISortedMap<K, R>;
+}
+/**
+ * {@inheritDoc ISortedMap}
+ * @see
+ * ### **Interface**
+ *
+ * {@link ISortedMap}
+ */
+export declare namespace ISortedMap {
+    /**
+     * Return value for {@link EditRangeCallback}. Optionally updates the value,
+     * signals early exit via `break`, or marks the pair for deletion.
+     */
+    type EditRangeResult<V, B = number> = {
+        value?: V;
+        break?: B;
+        delete?: boolean;
+    };
+    /**
+     * Callback passed to `editRange` / `forEditRange`.
+     * Return void to leave the pair unchanged, or an {@link EditRangeResult} to mutate or delete it.
+     */
+    type EditRangeCallback<K, V, R = number> = (k: K, v: V, counter: number) => EditRangeResult<V, R> | void;
+    /**
+     * Callback passed to `set` / `setPairs` when you need to compute the new value
+     * based on the previous one. Return void to keep the existing value.
+     */
+    type SetPairCallback<K, V> = (prev: V | undefined, key: K, value: V) => V | void;
+}
+//# sourceMappingURL=ISortedMap.d.ts.map

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

@@ -0,0 +1,61 @@
+import { RangeCoords } from '@sheetxl/utils';
+import { IGrid } from './IGrid';
+import { IListLike } from './IList';
+/**
+ * Extends {@link IGrid} with specialized functionality for sparse grids.
+ */
+export interface ISparseGrid<T = any> extends IGrid<T> {
+    /**
+     * Returns An iterator for iterating the runs.
+     *
+     * @remarks
+     * Sparse grids are stored as virtual tuples of [major, minor, value].
+     */
+    getRuns(options?: ISparseGrid.RunIteratorOptions): ISparseGrid.RunIterableIterator<T>;
+}
+/**
+ * {@inheritDoc ISparseGrid}
+ * @see
+ * ### **Interface**
+ *
+ * {@link ISparseGrid}
+ */
+export declare namespace ISparseGrid {
+    /**
+     * The entry for a run.
+     */
+    type RunEntry<T = any> = [major: number, minor: number, run: IListLike<T>];
+    /**
+     * Shorthand type.
+     */
+    type RunIterableIterator<T = any> = IterableIterator<RunEntry<T>>;
+    /**
+     * Shorthand type.
+     */
+    type RunIteratorResult<T = any> = IteratorResult<ISparseGrid.RunEntry<T>>;
+    /**
+     * Run Iterator extends {@link IReadableList.IteratorOptions} but removes support for
+     * processSkip and downcasts reuseResult.
+     */
+    interface RunIteratorOptions {
+        /**
+         * If not specified or `null` then all values will be iterated.
+         *
+         * @defaultValue unspecified
+         *
+         * @remarks
+         * The min and max are always small to largest regardless of reverse flag.
+         */
+        bounds?: Partial<RangeCoords>;
+        /**
+         * If `true` will return the full range even if it is outside of the iteration bounds.
+         *
+         * @defaultValue `false`
+         *
+         * @remarks
+         * This is used as a performance optimization for iterators that are reading gaps. (fillEmpty)
+         */
+        overflowRun?: boolean;
+    }
+}
+//# sourceMappingURL=ISparseGrid.d.ts.map

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

@@ -0,0 +1,103 @@
+import { RunCoords } from '@sheetxl/utils';
+import { IReadableList } from './IReadableList';
+import { IWritableList } from './IWritableList';
+/**
+ * Extends {@link IReadableList} with specialized functionality for sparse lists.
+ *
+ * A sparse list is a list where many elements are undefined or null. This interface provides methods to efficiently
+ * work with such lists, including:
+ *
+ * - Retrieving the minimum and maximum indices of populated elements.
+ *
+ * - Counting the total number of non-empty elements.
+ *
+ * - Getting the number of contiguous runs of non-empty elements.
+ */
+export interface ISparseList<T = any> extends IReadableList<T>, IWritableList<T> {
+    /**
+     * Returns the max and min for the list or null if empty.
+     */
+    getCoords(): RunCoords | null;
+    /**
+     * Represents The maximum bounds.
+     *
+     * If this is null or undefined then it is assume to be unlimited in size.
+     */
+    getMaxCoords?(): RunCoords | null;
+    /**
+     * Returns the count of elements in the list that contain values (non-empty).
+     *
+     * @remarks
+     * In a dense list, this count would be equal to the `length` property. However, since sparse lists can have gaps
+     * where elements are undefined or null, `getCount` specifically counts the elements that hold actual values.
+     */
+    getCount(): number;
+    /**
+     * Sets a list of values at the given index.
+     *
+     * @param index The offset location for the values to be placed.
+     * @param run An IReadableList containing values.
+     * @remarks
+     * For performance reasons the arrays and the values passed in are
+     * accessed directly so these should be treated as immutable.
+     */
+    setRunAt(index: number, run: IReadableList<T>): boolean;
+    /**
+     * Return an iterator for iterating the runs.
+     * @param options IteratorOptions
+     * @remarks
+     * When iterating runs with bounds any runs that intersect the bounds will be returned.
+     */
+    runs(options?: ISparseList.RunIteratorOptions): ISparseList.RunIterator<T>;
+    /**
+     * Returns the number of contiguous runs within the sparse list.
+     *
+     * A run is defined as a sequence of consecutive elements that are not undefined or null.
+     *
+     * @returns The total number of runs in the list.
+     */
+    getRunsCount(): number;
+    /**
+     * Clears all values.
+     */
+    clear(): void;
+    /**
+     * For runtime type checking.
+     */
+    readonly isISparseList: true;
+}
+/**
+ * {@inheritDoc ISparseList}
+ * @see
+ * ### **Interface**
+ *
+ * {@link ISparseList}
+ */
+export declare namespace ISparseList {
+    type RunEntry<T = any> = [RunCoords, IReadableList<T>];
+    /**
+     * Shorthand type.
+     */
+    type RunIterator<T = any> = Iterator<ISparseList.RunEntry<T>, ISparseList.RunEntry<T>, number>;
+    /**
+     * Shorthand type.
+     */
+    type RunIteratorResult<T = any> = IteratorResult<ISparseList.RunEntry<T>>;
+    /**
+     * Run Iterator extends {@link IReadableList.IteratorOptions} but removes support for
+     * processSkip and downcasts reuseResult.
+     */
+    interface RunIteratorOptions<T = any> extends Omit<IReadableList.IteratorOptions, 'reuseResult' | 'processSkip'> {
+        reuseResult?: ISparseList.RunIteratorResult<T>;
+        /**
+         * If `true` will return the full range even if it is outside of the iteration bounds.
+         *
+         * @defaultValue `false`
+         *
+         * @remarks
+         * This is used as a performance optimization for iterators that are reading gaps. (fillEmpty)
+         */
+        overflowRun?: boolean;
+    }
+}
+//# sourceMappingURL=ISparseList.d.ts.map