@zengrid/shared 1.0.0 → 1.0.1

package/dist/src/data-structures/skip-list/index.d.ts

@@ -0,0 +1,4 @@
+export { SkipList } from './skip-list';
+export type { ISkipList, SkipListNode, SkipListOptions, RangeResult, SkipListStats, } from './skip-list.interface';
+export { defaultComparator, SkipListUtils } from './skip-list.interface';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/data-structures/skip-list/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../packages/shared/src/data-structures/skip-list/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,YAAY,EACV,SAAS,EACT,YAAY,EACZ,eAAe,EACf,WAAW,EACX,aAAa,GACd,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/src/data-structures/skip-list/skip-list.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Skip List implementation
+ * Probabilistic sorted data structure
+ */
+import type { ISkipList, SkipListOptions, RangeResult, SkipListStats } from './skip-list.interface';
+/**
+ * Skip List - Probabilistic sorted data structure
+ *
+ * Implementation:
+ * - Multiple levels of linked lists
+ * - Each level is a subset of the level below
+ * - Levels are determined probabilistically
+ * - Search starts at highest level and descends
+ *
+ * @example
+ * ```typescript
+ * const skipList = new SkipList<number, string>();
+ * skipList.set(10, 'ten');
+ * skipList.set(5, 'five');
+ * skipList.set(20, 'twenty');
+ *
+ * skipList.get(10); // 'ten'
+ * skipList.range(5, 15); // [{key: 5, value: 'five'}, {key: 10, value: 'ten'}]
+ * skipList.keys(); // [5, 10, 20]
+ * ```
+ */
+export declare class SkipList<K, V> implements ISkipList<K, V> {
+    private head;
+    private maxLevel;
+    private probability;
+    private compare;
+    private currentLevel;
+    private count;
+    constructor(options?: SkipListOptions<K>);
+    /**
+     * Create a new node with random level
+     */
+    private createNode;
+    /**
+     * Generate random level for new node
+     */
+    private randomLevel;
+    /**
+     * Find the position where key should be or is located
+     * Returns update array with predecessors at each level
+     */
+    private findUpdatePath;
+    /**
+     * Insert or update a key-value pair
+     */
+    set(key: K, value: V): V | undefined;
+    /**
+     * Get value by key
+     */
+    get(key: K): V | undefined;
+    /**
+     * Check if key exists
+     */
+    has(key: K): boolean;
+    /**
+     * Delete a key
+     */
+    delete(key: K): boolean;
+    /**
+     * Get all entries in sorted order
+     */
+    entries(): Array<[K, V]>;
+    /**
+     * Get all keys in sorted order
+     */
+    keys(): K[];
+    /**
+     * Get all values in sorted order by key
+     */
+    values(): V[];
+    /**
+     * Get range of entries
+     */
+    range(startKey: K, endKey: K): RangeResult<K, V>[];
+    /**
+     * Get minimum entry
+     */
+    min(): RangeResult<K, V> | undefined;
+    /**
+     * Get maximum entry
+     */
+    max(): RangeResult<K, V> | undefined;
+    /**
+     * Get kth smallest entry (0-indexed)
+     */
+    getKth(k: number): RangeResult<K, V> | undefined;
+    /**
+     * Count entries in range
+     */
+    countRange(startKey: K, endKey: K): number;
+    /**
+     * Find floor (largest key <= given key)
+     */
+    floor(key: K): RangeResult<K, V> | undefined;
+    /**
+     * Find ceiling (smallest key >= given key)
+     */
+    ceiling(key: K): RangeResult<K, V> | undefined;
+    /**
+     * Iterate over all entries
+     */
+    forEach(callback: (value: V, key: K) => void): void;
+    /**
+     * Clear all entries
+     */
+    clear(): void;
+    /**
+     * Get statistics
+     */
+    getStats(): SkipListStats;
+    /**
+     * Get size
+     */
+    get size(): number;
+    /**
+     * Check if empty
+     */
+    get isEmpty(): boolean;
+    /**
+     * Create skip list from entries
+     */
+    static from<K, V>(entries: Array<[K, V]>, options?: SkipListOptions<K>): SkipList<K, V>;
+    /**
+     * Debug: Print structure
+     */
+    toString(): string;
+    /**
+     * Debug: Validate structure
+     */
+    validate(): boolean;
+}
+//# sourceMappingURL=skip-list.d.ts.map

package/dist/src/data-structures/skip-list/skip-list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skip-list.d.ts","sourceRoot":"","sources":["../../../../../../packages/shared/src/data-structures/skip-list/skip-list.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACV,SAAS,EAET,eAAe,EACf,WAAW,EACX,aAAa,EACd,MAAM,uBAAuB,CAAC;AAI/B;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAE,YAAW,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC;IACpD,OAAO,CAAC,IAAI,CAAqB;IACjC,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,OAAO,CAAgB;IAC/B,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,KAAK,CAAS;gBAEV,OAAO,GAAE,eAAe,CAAC,CAAC,CAAM;IAW5C;;OAEG;IACH,OAAO,CAAC,UAAU;IAQlB;;OAEG;IACH,OAAO,CAAC,WAAW;IAQnB;;;OAGG;IACH,OAAO,CAAC,cAAc;IAkBtB;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS;IAmCpC;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS;IAuB1B;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,OAAO;IAIpB;;OAEG;IACH,MAAM,CAAC,GAAG,EAAE,CAAC,GAAG,OAAO;IA6BvB;;OAEG;IACH,OAAO,IAAI,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAYxB;;OAEG;IACH,IAAI,IAAI,CAAC,EAAE;IAYX;;OAEG;IACH,MAAM,IAAI,CAAC,EAAE;IAYb;;OAEG;IACH,KAAK,CAAC,QAAQ,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE;IA0BlD;;OAEG;IACH,GAAG,IAAI,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,SAAS;IAQpC;;OAEG;IACH,GAAG,IAAI,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,SAAS;IAsBpC;;OAEG;IACH,MAAM,CAAC,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,SAAS;IAoBhD;;OAEG;IACH,UAAU,CAAC,QAAQ,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,MAAM;IAI1C;;OAEG;IACH,KAAK,CAAC,GAAG,EAAE,CAAC,GAAG,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,SAAS;IAqB5C;;OAEG;IACH,OAAO,CAAC,GAAG,EAAE,CAAC,GAAG,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,SAAS;IAqB9C;;OAEG;IACH,OAAO,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,KAAK,IAAI,GAAG,IAAI;IASnD;;OAEG;IACH,KAAK,IAAI,IAAI;IAMb;;OAEG;IACH,QAAQ,IAAI,aAAa;IA0BzB;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;OAEG;IACH,IAAI,OAAO,IAAI,OAAO,CAErB;IAED;;OAEG;IACH,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,EACd,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EACtB,OAAO,CAAC,EAAE,eAAe,CAAC,CAAC,CAAC,GAC3B,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC;IAQjB;;OAEG;IACH,QAAQ,IAAI,MAAM;IAIlB;;OAEG;IACH,QAAQ,IAAI,OAAO;CAyBpB"}

package/dist/src/data-structures/skip-list/skip-list.interface.d.ts

@@ -0,0 +1,223 @@
+/**
+ * Skip List interfaces for ZenGrid
+ * Probabilistic data structure for efficient sorted data management
+ */
+import type { Comparator } from '../../types';
+/**
+ * Skip List Node representing a key-value pair at a specific level
+ */
+export interface SkipListNode<K, V> {
+    key: K;
+    value: V;
+    forward: Array<SkipListNode<K, V> | null>;
+}
+/**
+ * Range query result
+ */
+export interface RangeResult<K, V> {
+    key: K;
+    value: V;
+}
+/**
+ * Skip List statistics
+ */
+export interface SkipListStats {
+    /** Total number of entries */
+    size: number;
+    /** Current maximum level */
+    level: number;
+    /** Maximum allowed levels */
+    maxLevel: number;
+    /** Average level of nodes */
+    averageLevel: number;
+    /** Memory usage estimate in bytes */
+    memoryBytes: number;
+}
+/**
+ * Skip List interface
+ *
+ * A probabilistic alternative to balanced trees that maintains sorted data.
+ * Uses multiple levels of linked lists with exponentially decreasing probability.
+ *
+ * Use cases:
+ * - Sorted column data in grids
+ * - Maintaining sorted indices
+ * - Range queries on sorted data
+ * - Finding kth smallest/largest element
+ * - Ordered iteration
+ * - Implementing sorted maps/sets
+ *
+ * Performance:
+ * - Search: O(log n) average, O(n) worst case
+ * - Insert: O(log n) average, O(n) worst case
+ * - Delete: O(log n) average, O(n) worst case
+ * - Range query: O(log n + k) where k = results
+ * - Space: O(n log n) average
+ *
+ * Advantages over balanced trees:
+ * - Simpler implementation (no rotations)
+ * - Better cache locality
+ * - Lock-free concurrent implementation possible
+ * - Predictable performance (no worst-case rebalancing)
+ */
+export interface ISkipList<K, V> {
+    /**
+     * Insert or update a key-value pair
+     * @param key - The key to insert
+     * @param value - The value to associate with the key
+     * @returns The previous value if key existed, undefined otherwise
+     * @complexity O(log n) average
+     */
+    set(key: K, value: V): V | undefined;
+    /**
+     * Get the value associated with a key
+     * @param key - The key to search for
+     * @returns The value if found, undefined otherwise
+     * @complexity O(log n) average
+     */
+    get(key: K): V | undefined;
+    /**
+     * Check if a key exists in the skip list
+     * @param key - The key to check
+     * @complexity O(log n) average
+     */
+    has(key: K): boolean;
+    /**
+     * Delete a key-value pair
+     * @param key - The key to delete
+     * @returns true if the key was found and deleted
+     * @complexity O(log n) average
+     */
+    delete(key: K): boolean;
+    /**
+     * Get all entries in sorted order
+     * @returns Array of [key, value] tuples
+     * @complexity O(n)
+     */
+    entries(): Array<[K, V]>;
+    /**
+     * Get all keys in sorted order
+     * @returns Array of keys
+     * @complexity O(n)
+     */
+    keys(): K[];
+    /**
+     * Get all values in sorted order by key
+     * @returns Array of values
+     * @complexity O(n)
+     */
+    values(): V[];
+    /**
+     * Get range of entries between two keys (inclusive)
+     * @param startKey - Start of range (inclusive)
+     * @param endKey - End of range (inclusive)
+     * @returns Array of entries in range
+     * @complexity O(log n + k) where k = results
+     */
+    range(startKey: K, endKey: K): RangeResult<K, V>[];
+    /**
+     * Get the minimum (first) entry
+     * @returns The minimum entry or undefined if empty
+     * @complexity O(1)
+     */
+    min(): RangeResult<K, V> | undefined;
+    /**
+     * Get the maximum (last) entry
+     * @returns The maximum entry or undefined if empty
+     * @complexity O(log n)
+     */
+    max(): RangeResult<K, V> | undefined;
+    /**
+     * Get the kth smallest entry (0-indexed)
+     * @param k - Index (0 = smallest)
+     * @returns The kth entry or undefined if k >= size
+     * @complexity O(k) - could be improved to O(log n) with span tracking
+     */
+    getKth(k: number): RangeResult<K, V> | undefined;
+    /**
+     * Count entries in a range
+     * @param startKey - Start of range (inclusive)
+     * @param endKey - End of range (inclusive)
+     * @complexity O(log n + k) where k = count
+     */
+    countRange(startKey: K, endKey: K): number;
+    /**
+     * Find the closest key less than or equal to the given key
+     * @param key - The key to search for
+     * @returns The floor entry or undefined if no such key exists
+     * @complexity O(log n)
+     */
+    floor(key: K): RangeResult<K, V> | undefined;
+    /**
+     * Find the closest key greater than or equal to the given key
+     * @param key - The key to search for
+     * @returns The ceiling entry or undefined if no such key exists
+     * @complexity O(log n)
+     */
+    ceiling(key: K): RangeResult<K, V> | undefined;
+    /**
+     * Iterate over all entries in sorted order
+     * @param callback - Function to call for each entry
+     * @complexity O(n)
+     */
+    forEach(callback: (value: V, key: K) => void): void;
+    /**
+     * Clear all entries
+     * @complexity O(1)
+     */
+    clear(): void;
+    /**
+     * Get statistics about the skip list
+     */
+    getStats(): SkipListStats;
+    /**
+     * Number of entries in the skip list
+     */
+    readonly size: number;
+    /**
+     * Whether the skip list is empty
+     */
+    readonly isEmpty: boolean;
+}
+/**
+ * Options for creating a Skip List
+ */
+export interface SkipListOptions<K> {
+    /**
+     * Custom comparator function
+     * Defaults to natural ordering for numbers/strings
+     */
+    comparator?: Comparator<K>;
+    /**
+     * Maximum number of levels
+     * @default 32 (supports ~4 billion elements efficiently)
+     */
+    maxLevel?: number;
+    /**
+     * Probability for level increase
+     * @default 0.5 (standard Skip List probability)
+     */
+    probability?: number;
+}
+/**
+ * Default comparator for common types
+ */
+export declare function defaultComparator<K>(a: K, b: K): number;
+/**
+ * Utility functions for Skip List
+ */
+export declare const SkipListUtils: {
+    /**
+     * Calculate expected maximum level for n elements
+     */
+    expectedMaxLevel(n: number, probability?: number): number;
+    /**
+     * Calculate expected number of nodes at level i
+     */
+    expectedNodesAtLevel(n: number, level: number, probability?: number): number;
+    /**
+     * Calculate expected memory usage
+     */
+    estimateMemory(n: number, _maxLevel: number, probability?: number): number;
+};
+//# sourceMappingURL=skip-list.interface.d.ts.map

package/dist/src/data-structures/skip-list/skip-list.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skip-list.interface.d.ts","sourceRoot":"","sources":["../../../../../../packages/shared/src/data-structures/skip-list/skip-list.interface.ts"],"names":[],"mappings":"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"}

package/dist/src/data-structures/sparse-matrix/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Sparse Matrix - Memory-efficient 2D grid storage
+ */
+export { SparseMatrix } from './sparse-matrix';
+export type { ReadonlySparseMatrix, SparseMatrix as ISparseMatrix, SparseMatrixOptions, } from './sparse-matrix.interface';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/data-structures/sparse-matrix/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../packages/shared/src/data-structures/sparse-matrix/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,YAAY,EACV,oBAAoB,EACpB,YAAY,IAAI,aAAa,EAC7B,mBAAmB,GACpB,MAAM,2BAA2B,CAAC"}

package/dist/src/data-structures/sparse-matrix/sparse-matrix.d.ts

@@ -0,0 +1,44 @@
+import type { SparseMatrix as ISparseMatrix, SparseMatrixOptions } from './sparse-matrix.interface';
+/**
+ * SparseMatrix implementation using Map of Maps
+ *
+ * Memory-efficient storage for large grids where most cells are empty.
+ * Uses nested Maps with numeric keys for optimal performance.
+ *
+ * Structure: Map<row, Map<col, value>>
+ * - Row operations are O(1) - direct map lookup
+ * - Column operations are O(r) where r = rows with data (not total cells)
+ * - Memory efficient: only allocates maps for rows that have data
+ *
+ * @example
+ * ```typescript
+ * const matrix = new SparseMatrix<string>();
+ * matrix.set(0, 0, 'A1');
+ * matrix.set(1000, 1000, 'B1000');
+ * console.log(matrix.get(0, 0)); // 'A1'
+ * console.log(matrix.size); // 2 (only stores non-empty cells)
+ * ```
+ */
+export declare class SparseMatrix<T> implements ISparseMatrix<T> {
+    private rows;
+    private cellCount;
+    constructor(_options?: SparseMatrixOptions);
+    get(row: number, col: number): T | undefined;
+    has(row: number, col: number): boolean;
+    set(row: number, col: number, value: T): void;
+    delete(row: number, col: number): boolean;
+    clear(): void;
+    getRow(row: number): ReadonlyMap<number, T>;
+    getColumn(col: number): ReadonlyMap<number, T>;
+    setRow(row: number, values: Map<number, T>): void;
+    deleteRow(row: number): number;
+    deleteColumn(col: number): number;
+    get size(): number;
+    [Symbol.iterator](): IterableIterator<[number, number, T]>;
+    /**
+     * Convert to dense 2D array (for debugging/testing)
+     * WARNING: Can be memory-intensive for large sparse matrices
+     */
+    toDenseArray(maxRow: number, maxCol: number, defaultValue: T): T[][];
+}
+//# sourceMappingURL=sparse-matrix.d.ts.map

package/dist/src/data-structures/sparse-matrix/sparse-matrix.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sparse-matrix.d.ts","sourceRoot":"","sources":["../../../../../../packages/shared/src/data-structures/sparse-matrix/sparse-matrix.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,IAAI,aAAa,EAC7B,mBAAmB,EACpB,MAAM,2BAA2B,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,YAAY,CAAC,CAAC,CAAE,YAAW,aAAa,CAAC,CAAC,CAAC;IACtD,OAAO,CAAC,IAAI,CAA8B;IAC1C,OAAO,CAAC,SAAS,CAAS;gBAEd,QAAQ,GAAE,mBAAwB;IAO9C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAK5C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO;IAKtC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI;IAuB7C,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO;IAmBzC,KAAK,IAAI,IAAI;IAKb,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,CAAC,MAAM,EAAE,CAAC,CAAC;IAM3C,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,CAAC,MAAM,EAAE,CAAC,CAAC;IAc9C,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,IAAI;IAMjD,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAc9B,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAyBjC,IAAI,IAAI,IAAI,MAAM,CAEjB;IAEA,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,gBAAgB,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;IAQ3D;;;OAGG;IACH,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,GAAG,CAAC,EAAE,EAAE;CAarE"}

package/dist/src/data-structures/sparse-matrix/sparse-matrix.interface.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Sparse Matrix interfaces for ZenGrid
+ */
+/**
+ * Read-only view of a sparse matrix
+ */
+export interface ReadonlySparseMatrix<T> {
+    /**
+     * Get value at position (row, col)
+     * @param row - Row index
+     * @param col - Column index
+     * @returns Value at position or undefined if not set
+     * @complexity O(1)
+     */
+    get(row: number, col: number): T | undefined;
+    /**
+     * Check if a value exists at position (row, col)
+     * @param row - Row index
+     * @param col - Column index
+     * @returns true if value exists
+     * @complexity O(1)
+     */
+    has(row: number, col: number): boolean;
+    /**
+     * Get all values in a row
+     * @param row - Row index
+     * @returns Map of column index to value
+     * @complexity O(1) - direct map lookup
+     */
+    getRow(row: number): ReadonlyMap<number, T>;
+    /**
+     * Get all values in a column
+     * @param col - Column index
+     * @returns Map of row index to value
+     * @complexity O(r) where r = number of rows with data (not total cells)
+     */
+    getColumn(col: number): ReadonlyMap<number, T>;
+    /**
+     * Number of non-empty cells
+     */
+    readonly size: number;
+    /**
+     * Iterate over all (row, col, value) tuples
+     */
+    [Symbol.iterator](): IterableIterator<[number, number, T]>;
+}
+/**
+ * Mutable sparse matrix interface
+ */
+export interface SparseMatrix<T> extends ReadonlySparseMatrix<T> {
+    /**
+     * Set value at position (row, col)
+     * @param row - Row index
+     * @param col - Column index
+     * @param value - Value to set
+     * @complexity O(1)
+     */
+    set(row: number, col: number, value: T): void;
+    /**
+     * Delete value at position (row, col)
+     * @param row - Row index
+     * @param col - Column index
+     * @returns true if value was deleted
+     * @complexity O(1)
+     */
+    delete(row: number, col: number): boolean;
+    /**
+     * Clear all values
+     * @complexity O(1)
+     */
+    clear(): void;
+    /**
+     * Set multiple values in a row
+     * @param row - Row index
+     * @param values - Map of column index to value
+     * @complexity O(k) where k = values.size
+     */
+    setRow(row: number, values: Map<number, T>): void;
+    /**
+     * Delete entire row
+     * @param row - Row index
+     * @returns Number of cells deleted
+     * @complexity O(1) - direct map deletion
+     */
+    deleteRow(row: number): number;
+    /**
+     * Delete entire column
+     * @param col - Column index
+     * @returns Number of cells deleted
+     * @complexity O(r) where r = number of rows with data
+     */
+    deleteColumn(col: number): number;
+}
+/**
+ * Options for creating a sparse matrix
+ */
+export interface SparseMatrixOptions {
+    /**
+     * Initial capacity (number of expected rows with data)
+     * Hint for Map pre-allocation to reduce resizing
+     * @default 16
+     */
+    initialCapacity?: number;
+}
+//# sourceMappingURL=sparse-matrix.interface.d.ts.map

package/dist/src/data-structures/sparse-matrix/sparse-matrix.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sparse-matrix.interface.d.ts","sourceRoot":"","sources":["../../../../../../packages/shared/src/data-structures/sparse-matrix/sparse-matrix.interface.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,MAAM,WAAW,oBAAoB,CAAC,CAAC;IACrC;;;;;;OAMG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAAC;IAE7C;;;;;;OAMG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAEvC;;;;;OAKG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IAE5C;;;;;OAKG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IAE/C;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,gBAAgB,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC;CAC5D;AAED;;GAEG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC,CAAE,SAAQ,oBAAoB,CAAC,CAAC,CAAC;IAC9D;;;;;;OAMG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;IAE9C;;;;;;OAMG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAE1C;;;OAGG;IACH,KAAK,IAAI,IAAI,CAAC;IAEd;;;;;OAKG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC;IAElD;;;;;OAKG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IAE/B;;;;;OAKG;IACH,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B"}

package/dist/src/data-structures/suffix-array/index.d.ts

@@ -0,0 +1,3 @@
+export { SuffixArray } from './suffix-array';
+export type { ISuffixArray, SuffixArrayOptions, SuffixSearchResult, SuffixArrayStats, } from './suffix-array.interface';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/data-structures/suffix-array/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../packages/shared/src/data-structures/suffix-array/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,YAAY,EACV,YAAY,EACZ,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,0BAA0B,CAAC"}

package/dist/src/data-structures/suffix-array/suffix-array.d.ts

@@ -0,0 +1,102 @@
+import type { ISuffixArray, SuffixArrayOptions, SuffixSearchResult, SuffixArrayStats } from './suffix-array.interface';
+/**
+ * Suffix Array - Efficient substring search data structure
+ *
+ * A suffix array is a sorted array of all suffixes of a string.
+ * It enables fast substring search in O(m log n) time.
+ *
+ * **Time Complexity:**
+ * - Construction: O(n log² n) where n = text length
+ * - Search: O(m log n) where m = pattern length
+ * - Count: O(m log n)
+ * - Contains: O(m log n)
+ *
+ * **Space Complexity:** O(n)
+ *
+ * **Use Cases in Grid:**
+ * - Substring search: Find cells containing "phone" (matches "iPhone")
+ * - Filter by contains: Show rows where column contains pattern
+ * - Autocomplete: Find all values containing typed text
+ * - Fuzzy search: Find similar values
+ *
+ * @example Basic Usage
+ * ```typescript
+ * const sa = new SuffixArray("banana");
+ *
+ * // Search for pattern
+ * const positions = sa.search("ana");
+ * console.log(positions); // [1, 3] - "banana" has "ana" at positions 1 and 3
+ *
+ * // Check if contains
+ * console.log(sa.contains("nan")); // true
+ * console.log(sa.contains("xyz")); // false
+ *
+ * // Count occurrences
+ * console.log(sa.count("ana")); // 2
+ * ```
+ *
+ * @example Grid Integration
+ * ```typescript
+ * // Index a column for substring search
+ * const columnData = grid.getColumn(0); // ["Apple iPhone", "Samsung Galaxy", ...]
+ * const combinedText = columnData.join("\0"); // Use null separator
+ * const sa = new SuffixArray(combinedText);
+ *
+ * // Find all cells containing "phone"
+ * const positions = sa.search("phone");
+ * // Convert positions back to row indices
+ * ```
+ */
+export declare class SuffixArray implements ISuffixArray {
+    private text;
+    private suffixArray;
+    private lcp;
+    private options;
+    constructor(text: string, options?: SuffixArrayOptions);
+    /**
+     * Search for a pattern in the text
+     */
+    search(pattern: string): number[];
+    /**
+     * Search with context
+     */
+    searchWithContext(pattern: string, contextLength?: number): SuffixSearchResult[];
+    /**
+     * Count occurrences of a pattern
+     */
+    count(pattern: string): number;
+    /**
+     * Check if pattern exists
+     */
+    contains(pattern: string): boolean;
+    /**
+     * Find the longest repeated substring using LCP array
+     */
+    longestRepeatedSubstring(): string;
+    /**
+     * Get all unique substrings of a given length
+     */
+    uniqueSubstrings(length: number): string[];
+    /**
+     * Get statistics
+     */
+    getStats(): SuffixArrayStats;
+    /**
+     * Clear the suffix array
+     */
+    clear(): void;
+    /**
+     * Build suffix array using simple O(n log² n) algorithm
+     */
+    private buildSuffixArray;
+    /**
+     * Build LCP (Longest Common Prefix) array using Kasai's algorithm
+     * Time: O(n)
+     */
+    private buildLCPArray;
+    /**
+     * Binary search to find range of suffixes that start with pattern
+     */
+    private findRange;
+}
+//# sourceMappingURL=suffix-array.d.ts.map

package/dist/src/data-structures/suffix-array/suffix-array.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"suffix-array.d.ts","sourceRoot":"","sources":["../../../../../../packages/shared/src/data-structures/suffix-array/suffix-array.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,EACjB,MAAM,0BAA0B,CAAC;AAElC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,qBAAa,WAAY,YAAW,YAAY;IAC9C,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,WAAW,CAAW;IAC9B,OAAO,CAAC,GAAG,CAAyB;IACpC,OAAO,CAAC,OAAO,CAA+B;gBAElC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB;IAkB1D;;OAEG;IACH,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE;IAgBjC;;OAEG;IACH,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,aAAa,GAAE,MAAW,GAAG,kBAAkB,EAAE;IAmBpF;;OAEG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAW9B;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAOlC;;OAEG;IACH,wBAAwB,IAAI,MAAM;IAkBlC;;OAEG;IACH,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE;IAY1C;;OAEG;IACH,QAAQ,IAAI,gBAAgB;IAa5B;;OAEG;IACH,KAAK,IAAI,IAAI;IAQb;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAiBxB;;;OAGG;IACH,OAAO,CAAC,aAAa;IA6BrB;;OAEG;IACH,OAAO,CAAC,SAAS;CA0ClB"}