@sheetxl/sdk 0.7.26 → 0.7.28-beta.1

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

@@ -0,0 +1,72 @@
+import { Direction, RangeAxis, CellCoords, RangeCoords } from '@sheetxl/utils';
+import { Tuple } from './Tuple';
+import { IGrid } from './IGrid';
+/**
+ * PLACEHOLDER
+ *
+ * Uses 2d arrays to implement an IGrid.
+ *
+ * @remarks
+ * This is not finished or even tested. We may remove it. The original goal was to allow this
+ * in leu of SparseGrid for a reference implementation but SparseGrid ended up being more performant
+ * than expected and the use-case for this in no longer clear.
+ */
+export declare class ArraysGrid<T = any> implements IGrid<T> {
+    private _options;
+    private _isColumn;
+    private _maxCoords;
+    private _values;
+    constructor(options?: ArraysGrid.ConstructorOptions);
+    /** {@inheritDoc IGrid.entries} */
+    entries(options?: IGrid.IteratorOptions): IterableIterator<IGrid.Entry<T>, IGrid.Entry<T>, CellCoords>;
+    /** {@inheritDoc IGrid.getCoords} */
+    getCoords(): RangeCoords | null;
+    /** {@inheritDoc IGrid.setValues} */
+    setValues(_values: Tuple.GridTuple): this;
+    getValues(coords?: RangeCoords): Tuple.BoundedTuples<T> | null;
+    /** {@inheritDoc IGrid.getAxis} */
+    getAxis(): RangeAxis;
+    /** {@inheritDoc IGrid.delete} */
+    delete(_range: RangeCoords): boolean;
+    /** {@inheritDoc IGrid.copyTo} */
+    copyTo(destination: IGrid, topLeft: CellCoords, from: RangeCoords): void;
+    /** {@inheritDoc IGrid.shift} */
+    shift(_range: RangeCoords, _direction: Direction): boolean;
+    /** {@inheritDoc IGrid.getValueAt} */
+    getValueAt(row: number, column: number): T;
+    /** {@inheritDoc IGrid.setValueAt} */
+    setValueAt(row: number, column: number, value: T): void;
+    /** {@inheritDoc IGrid.clone} */
+    clone(cloneKey?: any): this;
+    /** {@inheritDoc IGrid.getMaxCoords} */
+    getMaxCoords(): RangeCoords | null;
+    /** {@inheritDoc IGrid.clear} */
+    clear(): void;
+    /** {@inheritDoc IGrid.getCount} */
+    getCount(): number;
+}
+/**
+ * {@inheritDoc ArraysGrid}
+ * @see
+ * ### **Interface**
+ *
+ * {@link ArraysGrid}
+ */
+export declare namespace ArraysGrid {
+    /**
+     * For constructing an ArraysGrid.
+     */
+    interface ConstructorOptions {
+        /**
+         * If not specified then unlimited bounds.
+         * @defaultValue undefined
+         */
+        maxCoords?: RangeCoords;
+        /**
+         * Determines the axis that cells are visited.
+         * @defaultValue RangeAxis.Column
+         */
+        axis?: RangeAxis;
+    }
+}
+//# sourceMappingURL=ArraysGrid.d.ts.map

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

@@ -0,0 +1,67 @@
+import { IListLike } from './IList';
+/**
+ * Compact, immutable, list for storing boolean flags.
+ *
+ * @remarks
+ * `BooleanList` stores `length` boolean values using a `Uint8Array`
+ * with 8 flags per byte. It implements {@link IListLike} so it can be
+ * used anywhere a simple array-like list is expected, without exposing
+ * the full {@link IReadableList} surface.
+ *
+ * This type is intended for metadata overlays such as:
+ *
+ * - Data validation masks (valid / invalid flags per row)
+ * - Per-row or per-cell boolean annotations
+ *
+ * The list is logically immutable:
+ *
+ * - Construction packs bits once (either from a length or from a boolean array).
+ * - Methods like {@link slice} and {@link concat} always return new instances.
+ */
+export declare class BooleanList implements IListLike<boolean> {
+    /**
+     * Backing storage, 8 bits per byte.
+     */
+    private _bytes;
+    /**
+     * Number of logical bits (not number of bytes).
+     */
+    protected _length: number;
+    /**
+     * Create an empty BooleanList of the given length (all bits false).
+     *
+     * Public, but logically immutable: callers can't mutate bits directly.
+     * Construction + factories are the only "write" sites.
+     */
+    constructor(arr: readonly boolean[]);
+    /** {@inheritDoc IListLike.length} */
+    get length(): number;
+    /**
+     * IListLike.fromArray implementation.
+     * Allows this type to participate in your generic IListLike machinery.
+     */
+    fromArray(arr: boolean[]): IListLike<boolean>;
+    /** {@inheritDoc IListLike.at} */
+    at(index: number): boolean | undefined;
+    /** {@inheritDoc IListLike.toArray} */
+    toArray(): boolean[];
+    /**
+     * Create a new BooleanList representing [start, end) in bit-space.
+     *
+     * Semantics match Array.prototype.slice:
+     *  - negative indices are relative to the end,
+     *  - end is exclusive,
+     *  - result is always a new instance (no shared view).
+     *
+     * Implementation is simple bit-by-bit copy.
+     */
+    slice(start: number, end?: number): BooleanList;
+    /**
+     * Concatenate this BooleanList with another, returning a new instance.
+     * Bits from `other` are appended after this list.
+     *
+     * Implementation is bit-by-bit copy for simplicity.
+     */
+    concat(other: BooleanList): BooleanList;
+}
+//# sourceMappingURL=BooleanList.d.ts.map

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

@@ -0,0 +1,47 @@
+import { CellCoords } from '@sheetxl/utils';
+import { IGrid } from './IGrid';
+/**
+ * Wraps an {@link IGrid} as a standard Map.
+ */
+export declare class GridMap<V> implements Map<CellCoords, V> {
+    private _grid;
+    private _options;
+    private _isColumn;
+    private _optionsValues;
+    constructor(grid: IGrid, options?: IGrid.IteratorOptions);
+    clear(): void;
+    /**
+     * Returns true if an element in the Map existed and has been removed, or false if the element does not exist.
+     */
+    delete(key: CellCoords): boolean;
+    /**
+     * Executes a provided function once per each key/value pair in the Map, in insertion order.
+     */
+    forEach(callback: (value: V, key: CellCoords, map: Map<CellCoords, V>) => void, _thisArg?: any): void;
+    /**
+     * Returns a specified element from the Map object. If the value that is associated to the provided key is an object, then you will get a reference to that object and any change made to that object will effectively modify it inside the Map.
+     * @returns Returns the element associated with the specified key. If no element is associated with the specified key, undefined is returned.
+     */
+    get(key: CellCoords): V | undefined;
+    /**
+     * Returns boolean indicating whether an element with the specified key exists or not.
+     */
+    has(key: CellCoords): boolean;
+    /**
+     * Adds a new element with a specified key and value to the Map. If an element with the same key already exists, the element will be updated.
+     */
+    set(key: CellCoords, value: V): this;
+    /**
+     * Returns the number of elements in the Map.
+     */
+    get size(): number;
+    entries(): MapIterator<IGrid.Entry<V>>;
+    /** Returns an iterable of entries in the map. */
+    [Symbol.iterator](): MapIterator<IGrid.Entry<V>>;
+    test(): MapIterator<[CellCoords, V]>;
+    [Symbol.dispose](): void;
+    keys(): MapIterator<CellCoords>;
+    values(): MapIterator<V>;
+    get [Symbol.toStringTag](): string;
+}
+//# sourceMappingURL=GridMap.d.ts.map

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

@@ -0,0 +1,15 @@
+import { IMap } from './IMap';
+/**
+ * A basic implementation of IMap using JavaScript's native Map.
+ */
+export declare class HashMap<K, V> implements IMap<K, V> {
+    private _map;
+    private _isDirty;
+    constructor(source?: Map<K, V>);
+    get(key: K): V | undefined;
+    set(key: K, value: V): void;
+    delete(key: K): this;
+    has(key: K): boolean;
+    clone(): IMap<K, V>;
+}
+//# sourceMappingURL=HashMap.d.ts.map

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

@@ -0,0 +1,278 @@
+import { Direction, RangeAxis, CellCoords, RangeCoords } from '@sheetxl/utils';
+import { Tuple } from './Tuple';
+/**
+ * Primary interface for retrieving and setting values in a 2D space.
+ *
+ * To support infinite values IGrid uses an iterator to retrieve values.
+ *
+ * For read-only the minimum implementation required are:
+ *
+ * {@link entries} - Iterator of key/value.
+ *
+ * {@link getCoords} - The size and location of the data.
+ *
+ * For read-write the minimum addition is
+ *
+ * {@link setValues} - Set an IGrid.Tuple2D.
+ *
+ * @see `ArraysGrid` - Implementation using a 2D array. ({@link https://www.sheetxl.com | source}).
+ * @see `GridMap` - Provides a `Map<CellCoords, T>` interface for an IGrid.
+ */
+export interface IGrid<T = any> {
+    /**
+     * Sets values at specific coordinates within the grid using an array of `Tuple2D`.
+     *
+     * @param values GridTuples to update.
+     * @throws `Error` If the Tuple.GridTuple are invalid see {@link Tuple.GridTuple} or if any the provided
+     * tuples extend beyond the 'maxCoords'.
+     *
+     * @remarks
+     * * Clear values - Setting values to `undefined` or `null` are not treated special and will become
+     *   managed values. To clear use delete.
+     * * Immutability - For performance reasons all arrays and values passed in are
+     *   accessed directly (zero-copy) so these should be treated as immutable.
+     */
+    setValues(values: Tuple.GridTuple<T>): this;
+    /**
+     * Returns bounded tuples for a given range of coordinates.
+     *
+     * @param coords The range of coordinates to retrieve values from.
+     *
+     * @remarks
+     * * Results `null` if there are no values
+     * * If `coords` is not provided then all values will be retrieved.
+     */
+    getValues(coords?: RangeCoords): Tuple.BoundedTuples<T> | null;
+    /**
+     * Returns an iterator for traversing entries in the IGrid.
+     *
+     * The entries must support all IteratorOptions.
+     *
+     * @remarks
+     * Unlike map this is does not need to be an IterableIterator.
+     */
+    entries(options?: IGrid.IteratorOptions): IGrid.EntryIterator<T>;
+    /**
+     * Delete all values within a range.
+     *
+     * @param coords The range to delete.
+     *
+     * @remarks
+     * If not implemented and setRange is then setRange will called with null values.
+     */
+    delete?(coords: RangeCoords | null): boolean;
+    /**
+     * Clears all values.
+     */
+    clear?(): void;
+    /**
+     * Shift values in a given direction.
+     *
+     * @param coords The range that will shift.
+     * @param direction The direction to shift.
+     * @returns `true` if data was shifted.
+     *
+     * @remarks
+     * If this is not implemented shifting ranges will be attempted using
+     * delete and setAt (if implemented).
+     */
+    shift?(coords: RangeCoords, direction: Direction): boolean;
+    /**
+     * Copy values from another grid.
+     *
+     * @param destination The grid to copy to.
+     * @param topLeft The coordinates of the destination grid.
+     * @param from The bounds coordinates to copy from.
+     */
+    copyTo(destination: IGrid, topLeft: CellCoords, from: RangeCoords): void;
+    /**
+     * Creates a logical copy of the current values.
+     *
+     * Undo and branching works by creating 'copies' and then rolling back or commit these later.
+     *
+     * @remarks
+     * If this is not available then undo does not work for values.
+     */
+    clone?(cloneKey?: any): this;
+    /**
+     * Create a new grid but with no data.
+     *
+     * @remarks
+     * * Returns an empty grid with the same configuration as the original grid.
+     * * This is the same as clone(); clear() but more efficient.
+     */
+    cloneEmpty?(cloneKey?: any): this;
+    /**
+     * Iterate keys.
+     *
+     * @remarks
+     * This is not required unless retrieving keys is significantly less expensive than
+     * entries. There are few internal use cases that use only keys.
+     *
+     * @see
+     * {@link IGrid.entries}
+     */
+    keys?(options?: IGrid.IteratorOptions): IGrid.KeyIterator;
+    /**
+     * Iterate values.
+     *
+     * @remarks
+     * This is not required unless retrieving values is significantly less expensive than
+     * entries. there are few internal uses cases that use only values.
+     *
+     * @see
+     * {@link IGrid.entries}
+     * @param options {@link IGrid.IteratorOptions}
+     */
+    values?(options?: IGrid.IteratorOptions): IGrid.ValueIterator;
+    /**
+     * Returns the value at a specific row and column or `undefined` if not found.
+     *
+     * @param row
+     * @param column
+     *
+     * @remarks
+     * This ignores hiddens rows and columns.
+     */
+    getValueAt(row: number, column: number): T;
+    /**
+     * Sets a single value on the grid.
+     *
+     * @param row
+     * @param column
+     *
+     * @remarks
+     * Consider using a TupleBuilder. This is always less efficient than setValues.
+     */
+    setValueAt(row: number, column: number, value: T): void;
+    /**
+     * Determine major axis for storing values.
+     *
+     * This is used to indicate which axis the 2D array for values will be
+     * interpreted as well as the default axis for getValues.
+     *
+     * @remarks
+     * This value is only read once and should never change.
+     *
+     * If not implemented the client should default to `RangeAxis.Row`.
+     */
+    getAxis?(): RangeAxis;
+    /**
+     * Returns the number of values.
+     *
+     * @remarks
+     * If this is not implemented an approximation using getCoords will be assumed.
+     */
+    getCount?(): number;
+    /**
+     * Returns the bounds for all of the entries or empty if null.
+     */
+    getCoords(): RangeCoords | null;
+    /**
+     * Represents a max range or a max number.
+     *
+     * If this is `null` or `undefined` then it is assume to be unlimited in size.
+     *
+     * @remarks
+     * Coords must always be positive even if no bounds are set
+     */
+    getMaxCoords?(): RangeCoords | null;
+}
+/**
+ * {@inheritDoc IGrid}
+ * @see
+ * ### **Interface**
+ *
+ * {@link IGrid}
+ */
+export declare namespace IGrid {
+    /**
+     * Allow for iterating over a subset of values in a given direction.
+     */
+    interface IteratorOptions<T = any> {
+        /**
+         * If `null' or `undefined` then all cells will be visited.
+         *
+         * @defaultValue undefined
+         */
+        bounds?: Partial<RangeCoords>;
+        /**
+         * Determines the axis that cells are visited.
+         *
+         * @defaultValue The ICoordsMap axis.
+         */
+        axis?: RangeAxis;
+        /**
+         * Iterate in reverse order.
+         * @defaultValue false
+         */
+        reverse?: boolean;
+        /**
+         * A callback function that allows customization of the iteration process by skipping specific rows.
+         * This is a row orientated implementation of {@link IReadableList.IteratorOptions.processSkip}.
+         *
+         * @see
+         * {@link IReadableList.IteratorOptions.processSkip}
+         * {@link IGrid.IteratorOptions.processColumnSkip}
+         */
+        processRowSkip?: (index: number, reverse?: boolean) => number;
+        /**
+         * A callback function that allows customization of the iteration process by skipping specific columns.
+         * This is a row orientated implementation of {@link IReadableList.IteratorOptions.processSkip}.
+         *
+         * @see
+         * {@link IReadableList.IteratorOptions.processSkip}
+         * {@link IGrid.IteratorOptions.processRowSkip}
+         */
+        processColumnSkip?: (index: number, reverse?: boolean) => number;
+        /**
+         * This is a performance optimization.
+         * To avoid a large amount of object creation a reusable Iterator result can be provided.
+         * If set to true a global instance will be used.
+         * If multiple iterators are being used simultaneously then the client can provide
+         * their own reusable result.
+         *
+         * Additionally if the reuseResults has a CellCoords defined this will also get reused.
+         * The `globalReuseResults` is as follows
+         *
+         * `-1` is use as placeholder to ensure monomorphic types.
+         * If a simple javascript type is used for the value a typed placeholder value should be
+         * used for it as well.
+         * ```ts
+    {
+      done: false,
+      value: [
+        {
+          colIndex: -1,
+          rowIndex: -1
+        },
+        null
+      ]
+    }
+         * ```
+         * @defaultValue false
+         */
+        reuseResult?: boolean | IteratorResult<T>;
+    }
+    /**
+     * Entries iterators are arrays of fixed length 2.
+     */
+    type Entry<T = any> = [CellCoords, T];
+    /**
+     * Shorthand type.
+     */
+    type EntryIteratorResult<T = any> = IteratorResult<IGrid.Entry<T>>;
+    /**
+     * Shorthand type.
+     */
+    type EntryIterator<T = any> = IterableIterator<IGrid.Entry<T>, IGrid.Entry<T>, CellCoords>;
+    /**
+     * Shorthand type.
+     */
+    type ValueIterator<T = any> = IterableIterator<T, T, CellCoords>;
+    /**
+     * Shorthand type.
+     */
+    type KeyIterator = IterableIterator<CellCoords, CellCoords, CellCoords>;
+}
+//# sourceMappingURL=IGrid.d.ts.map

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

@@ -0,0 +1,89 @@
+/**
+ * IListLike objects are orders collections of values.
+ *
+ * While similar to an {@link Array} they have different implementations
+ * to allow for more efficient of large sets of data.
+ */
+export interface IListLike<T = any> {
+    /**
+     * Return the max element index within the list.
+     */
+    readonly length: number;
+    /**
+     * Returns the value at a given index.
+     *
+     * @param index The index to retrieve.
+     * @returns The value
+     */
+    at(index: number): T | undefined;
+    /**
+     * Optimization.
+     *
+     * If this is implemented then lists may attempt to 'compact' when the list is
+     * below a certain size.
+     *
+     * If not implemented, callers should fall back to a generic adapter.
+     */
+    fromArray?(arr: T[]): IListLike<T>;
+}
+export interface IList<T = any> extends IListLike<T> {
+    /**
+     * Returns `true` if the object implements IList.
+     *
+     * @remarks
+     * Required to differentiate from Arrays and strings.
+     */
+    readonly isIList: true;
+}
+/**
+ * {@inheritDoc IList}
+ * @see
+ * ### **Interface**
+ *
+ * {@link IList}
+ */
+export declare namespace IList {
+    /**
+     * Returns true if the object is {@link IList}.
+     * @param arg Object to check.
+     */
+    function isList(arg: any): boolean;
+    /**
+     * Returns true if the object is {@link IListLike}.
+     *
+     * @param arg Object to check.
+     *
+     * @remarks
+     * Similar to {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/isArray | Array.isArray}.
+     * Returns `true` for `string` and `Array`
+     */
+    function isListLike(arg: any): boolean;
+    /**
+     * Helper method that wraps a native Array into a IListLike.
+     *
+     * @param arr The array to wrap.
+     * @param getAt Optional function to allow for altering the value before returning.
+     *
+     * @remarks
+     * Useful for callbacks
+     */
+    function fromArray<T, R = any>(arr: any[], getAt?: (value: R | undefined, index: number) => T | undefined, setAt?: (value: T | undefined, index: number) => R | undefined, internal?: any[]): IList<T>;
+    /**
+     * Wraps a native Array into a IList.
+     */
+    class ArrayList<T = any> implements IList<T> {
+        private a;
+        private g;
+        private s;
+        constructor(a: any[], getAt?: (value: any | undefined, index: number) => T | undefined, setAt?: (value: T | undefined, index: number) => any | undefined, internal?: any[]);
+        /** {@inheritDoc IListLike.at} */
+        at(index: number): T | undefined;
+        /** {@inheritDoc IListLike.fromArray} */
+        fromArray?(arr: T[]): IListLike<T>;
+        /** {@inheritDoc IListLike.length} */
+        get length(): number;
+        /** {@inheritDoc IList.isIList} */
+        get isIList(): true;
+    }
+}
+//# sourceMappingURL=IList.d.ts.map

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

@@ -0,0 +1,45 @@
+/**
+ * A persistent (structurally-shared) map optimized for a clone-on-write collections model.
+ *
+ * @remarks
+ * Collections use **persistent data structures** to support fast undo/redo, versioned snapshots,
+ * and (future) collaboration without copying large collections on every update.
+ *
+ * `IMap` behaves like a familiar key/value map for reads and writes, while providing an explicit
+ * snapshot boundary via {@link clone}. Implementations are expected to use **structural sharing**
+ * (e.g., trie / tree based) so that cloning and incremental updates are efficient even for large maps.
+ *
+ * Typical use cases include:
+ * - Maintaining large indexes (e.g., uniqueness/count maps) where copying a native `Map` would be too costly.
+ * - Capturing point-in-time snapshots for undo/redo by cloning collection roots.
+ * - Enabling future branching/versioning semantics by treating each clone as a stable revision root.
+ *
+ * ### Clone-on-write semantics
+ * Mutations apply to the current instance. {@link clone} returns a new instance that represents a
+ * stable snapshot of the map’s contents at the time `clone()` was called.
+ *
+ * Callers can assume that:
+ * - `clone()` is cheap (structural sharing; no full copy).
+ * - A clone is logically separate: later mutations to the original do not affect the clone’s observable contents.
+ * - Clones share internal structure where possible to keep memory and runtime costs low.
+ *
+ * @template K - Key type. Prefer stable, canonical keys for large indexes.
+ * @template V - Value type.
+ */
+export interface IMap<K, V> {
+    /**
+     * Retrieves the value associated with the given key.
+     */
+    get(key: K): V | undefined;
+    /**
+     * Sets the value for the given key and returns the updated map.
+     */
+    set(key: K, value: V): void;
+    delete(key: K): this;
+    has(key: K): boolean;
+    /**
+     * Returns a new map that can be written to.
+     */
+    clone(): IMap<K, V>;
+}
+//# sourceMappingURL=IMap.d.ts.map