data-structure-typed 2.4.5 → 2.5.1

package/dist/types/data-structures/linked-list/skip-linked-list.d.ts

@@ -1,27 +1,790 @@
-import type { SkipLinkedListOptions } from '../../types';
+/**
+ * data-structure-typed
+ *
+ * @author Pablo Zeng
+ * @copyright Copyright (c) 2022 Pablo Zeng <zrwusa@gmail.com>
+ * @license MIT License
+ */
+import type { Comparator, EntryCallback } from '../../types';
+import { IterableEntryBase } from '../base';
 export declare class SkipListNode<K, V> {
     key: K;
     value: V;
-    forward: SkipListNode<K, V>[];
+    forward: (SkipListNode<K, V> | undefined)[];
     constructor(key: K, value: V, level: number);
 }
-export declare class SkipList<K, V> {
-    constructor(elements?: Iterable<[K, V]>, options?: SkipLinkedListOptions);
+export type SkipListOptions<K, V, R = [K, V]> = {
+    comparator?: Comparator<K>;
+    toEntryFn?: (rawElement: R) => [K, V];
+    maxLevel?: number;
+    probability?: number;
+};
+export type SkipListRangeOptions = {
+    lowInclusive?: boolean;
+    highInclusive?: boolean;
+};
+/**
+ * SkipList — a probabilistic sorted key-value container.
+ *
+ * API mirrors TreeMap: users can swap `TreeMap` ↔ `SkipList` with zero code changes.
+ * Reference: Java ConcurrentSkipListMap (NavigableMap interface).
+ *
+ * @example
+ * // Display skip list
+ *  const sl = new SkipList<number, string>([[1, 'a']]);
+ *     expect(() => sl.print()).not.toThrow();
+ */
+export declare class SkipList<K = any, V = any, R = [K, V]> extends IterableEntryBase<K, V | undefined> {
+    #private;
+    constructor(entries?: Iterable<R> | Iterable<[K, V | undefined]>, options?: SkipListOptions<K, V, R>);
+    /**
+     * Creates a default comparator supporting number, string, Date, and bigint.
+     */
+    static createDefaultComparator<K>(): Comparator<K>;
     protected _head: SkipListNode<K, V>;
-    get head(): SkipListNode<K, V>;
     protected _level: number;
-    get level(): number;
+    protected _size: number;
     protected _maxLevel: number;
-    get maxLevel(): number;
     protected _probability: number;
+    get size(): number;
+    get maxLevel(): number;
     get probability(): number;
-    get first(): V | undefined;
-    get last(): V | undefined;
-    add(key: K, value: V): void;
+    get comparator(): Comparator<K>;
+    /**
+   * Check if empty
+  
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Check if empty
+ *  const sl = new SkipList<number, string>();
+ *     console.log(sl.isEmpty()); // true;
+   */
+    isEmpty(): boolean;
+    /**
+   * Remove all entries
+  
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Remove all entries
+ *  const sl = new SkipList<number, string>([[1, 'a'], [2, 'b']]);
+ *     sl.clear();
+ *     console.log(sl.isEmpty()); // true;
+   */
+    clear(): void;
+    /**
+   * Create independent copy
+  
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Create independent copy
+ *  const sl = new SkipList<number, string>([[1, 'a'], [2, 'b']]);
+ *     const copy = sl.clone();
+ *     copy.delete(1);
+ *     console.log(sl.has(1)); // true;
+   */
+    clone(): this;
+    /**
+     * Insert or update a key-value pair. Returns `this` for chaining.
+     * Unique keys only — if key exists, value is updated in place.
+    
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // In-memory sorted key-value store
+   *  const store = new SkipList<number, string>();
+   *
+   *     store.set(3, 'three');
+   *     store.set(1, 'one');
+   *     store.set(5, 'five');
+   *     store.set(2, 'two');
+   *
+   *     console.log(store.get(3)); // 'three';
+   *     console.log(store.get(1)); // 'one';
+   *     console.log(store.get(5)); // 'five';
+   *
+   *     // Update existing key
+   *     store.set(3, 'THREE');
+   *     console.log(store.get(3)); // 'THREE';
+     */
+    set(key: K, value: V): this;
+    /**
+     * Get the value for a key, or `undefined` if not found.
+     * Overrides base O(n) with O(log n) skip-list search.
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Building a sorted index
+   *  type Product = { id: number; name: string; price: number };
+   *     const products: Product[] = [
+   *       { id: 1, name: 'Widget', price: 25 },
+   *       { id: 2, name: 'Gadget', price: 50 },
+   *       { id: 3, name: 'Doohickey', price: 15 }
+   *     ];
+   *
+   *     const index = new SkipList<number, Product, Product>(products, {
+   *       toEntryFn: (p: Product) => [p.price, p]
+   *     });
+   *
+   *     // Iterate in sorted order by price
+   *     const names = [...index.values()].map(p => p!.name);
+   *     console.log(names); // ['Doohickey', 'Widget', 'Gadget'];
+   *
+   *     // Range search: products between $20 and $60
+   *     const range = index.rangeSearch([20, 60]);
+   *     console.log(range.map(([, p]) => p!.name)); // ['Widget', 'Gadget'];
+     */
     get(key: K): V | undefined;
+    /**
+     * Check if a key exists.
+     * Overrides base O(n) with O(log n) skip-list search.
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Check key existence
+   *  const sl = new SkipList<number, string>([[1, 'a'], [3, 'c'], [5, 'e']]);
+   *     console.log(sl.has(3)); // true;
+   *     console.log(sl.has(4)); // false;
+     */
     has(key: K): boolean;
+    /**
+     * Delete a key. Returns `true` if the key was found and removed.
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Fast lookup with deletion
+   *  const cache = new SkipList<string, number>();
+   *
+   *     cache.set('alpha', 1);
+   *     cache.set('beta', 2);
+   *     cache.set('gamma', 3);
+   *
+   *     console.log(cache.has('beta')); // true;
+   *     cache.delete('beta');
+   *     console.log(cache.has('beta')); // false;
+   *     console.log(cache.size); // 2;
+     */
     delete(key: K): boolean;
-    higher(key: K): V | undefined;
-    lower(key: K): V | undefined;
+    /**
+     * Returns the first (smallest key) entry, or `undefined` if empty.
+    
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Access the minimum entry
+   *  const sl = new SkipList<number, string>([[5, 'e'], [1, 'a'], [3, 'c']]);
+   *     console.log(sl.first()); // [1, 'a'];
+     */
+    first(): [K, V | undefined] | undefined;
+    /**
+     * Returns the last (largest key) entry, or `undefined` if empty.
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Access the maximum entry
+   *  const sl = new SkipList<number, string>([[5, 'e'], [1, 'a'], [3, 'c']]);
+   *     console.log(sl.last()); // [5, 'e'];
+     */
+    last(): [K, V | undefined] | undefined;
+    /**
+     * Remove and return the first (smallest key) entry.
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Remove and return smallest
+   *  const sl = new SkipList<number, string>([[1, 'a'], [2, 'b'], [3, 'c']]);
+   *     console.log(sl.pollFirst()); // [1, 'a'];
+   *     console.log(sl.size); // 2;
+     */
+    pollFirst(): [K, V | undefined] | undefined;
+    /**
+     * Remove and return the last (largest key) entry.
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Remove and return largest
+   *  const sl = new SkipList<number, string>([[1, 'a'], [2, 'b'], [3, 'c']]);
+   *     console.log(sl.pollLast()); // [3, 'c'];
+   *     console.log(sl.size); // 2;
+     */
+    pollLast(): [K, V | undefined] | undefined;
+    /**
+     * Least entry ≥ key, or `undefined`.
+    
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Least entry ≥ key
+   *  const sl = new SkipList<number, string>([[10, 'a'], [20, 'b'], [30, 'c']]);
+   *     console.log(sl.ceiling(15)); // [20, 'b'];
+   *     console.log(sl.ceiling(20)); // [20, 'b'];
+     */
+    ceiling(key: K): [K, V | undefined] | undefined;
+    /**
+     * Greatest entry ≤ key, or `undefined`.
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Greatest entry ≤ key
+   *  const sl = new SkipList<number, string>([[10, 'a'], [20, 'b'], [30, 'c']]);
+   *     console.log(sl.floor(25)); // [20, 'b'];
+   *     console.log(sl.floor(5)); // undefined;
+     */
+    floor(key: K): [K, V | undefined] | undefined;
+    /**
+     * Least entry strictly > key, or `undefined`.
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Strictly greater entry
+   *  const sl = new SkipList<number, string>([[10, 'a'], [20, 'b'], [30, 'c']]);
+   *     console.log(sl.higher(15)); // [20, 'b'];
+   *     console.log(sl.higher(30)); // undefined;
+     */
+    higher(key: K): [K, V | undefined] | undefined;
+    /**
+     * Greatest entry strictly < key, or `undefined`.
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Strictly less entry
+   *  const sl = new SkipList<number, string>([[10, 'a'], [20, 'b'], [30, 'c']]);
+   *     console.log(sl.lower(25)); // [20, 'b'];
+   *     console.log(sl.lower(10)); // undefined;
+     */
+    lower(key: K): [K, V | undefined] | undefined;
+    /**
+     * Returns entries within the given key range.
+    
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Find entries in a range
+   *  const sl = new SkipList<number, string>([[1, 'a'], [2, 'b'], [3, 'c'], [4, 'd'], [5, 'e']]);
+   *     const result = sl.rangeSearch([2, 4]);
+   *     console.log(result); // [[2, 'b'], [3, 'c'], [4, 'd']];
+     */
+    rangeSearch(range: [K, K], options?: SkipListRangeOptions): Array<[K, V | undefined]>;
+    /**
+     * Creates a new SkipList with entries transformed by callback.
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Transform entries
+   *  const sl = new SkipList<number, string>([[1, 'a'], [2, 'b']]);
+   *     const mapped = sl.map((v, k) => [k, v?.toUpperCase()] as [number, string]);
+   *     console.log([...mapped.values()]); // ['A', 'B'];
+     */
+    map<MK, MV>(callback: EntryCallback<K, V | undefined, [MK, MV]>, options?: SkipListOptions<MK, MV>): SkipList<MK, MV>;
+    /**
+     * Creates a new SkipList with entries that pass the predicate.
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Filter entries
+   *  const sl = new SkipList<number, string>([[1, 'a'], [2, 'b'], [3, 'c']]);
+   *     const result = sl.filter((v, k) => k > 1);
+   *     console.log(result.size); // 2;
+     */
+    filter(callbackfn: EntryCallback<K, V | undefined, boolean>, thisArg?: unknown): this;
+    protected _getIterator(): IterableIterator<[K, V | undefined]>;
+    /**
+     * Finds the update array (predecessors at each level) for a given key.
+     */
+    protected _findUpdate(key: K): SkipListNode<K, V>[];
+    /**
+     * Finds the node for a given key, or undefined.
+     */
+    protected _findNode(key: K): SkipListNode<K, V> | undefined;
     protected _randomLevel(): number;
 }