binary-tree-typed 2.4.5 → 2.5.1

package/src/data-structures/linked-list/skip-linked-list.ts

@@ -1,171 +1,1148 @@
-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 { ERR } from '../../common';
+import { IterableEntryBase } from '../base';
 
 export class SkipListNode<K, V> {
   key: K;
   value: V;
-  forward: SkipListNode<K, V>[];
+  forward: (SkipListNode<K, V> | undefined)[];
 
   constructor(key: K, value: V, level: number) {
     this.key = key;
     this.value = value;
-    this.forward = new Array(level);
+    this.forward = new Array(level).fill(undefined);
   }
 }
 
-export class SkipList<K, V> {
-  constructor(elements: Iterable<[K, V]> = [], options?: SkipLinkedListOptions) {
-    if (options) {
-      const { maxLevel, probability } = options;
-      if (typeof maxLevel === 'number') this._maxLevel = maxLevel;
-      if (typeof probability === 'number') this._probability = probability;
-    }
+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 class SkipList<K = any, V = any, R = [K, V]> extends IterableEntryBase<K, V | undefined> {
+  readonly #comparator: Comparator<K>;
+  readonly #isDefaultComparator: boolean;
+
+  constructor(
+    entries: Iterable<R> | Iterable<[K, V | undefined]> = [],
+    options: SkipListOptions<K, V, R> = {}
+  ) {
+    super();
+    const { comparator, toEntryFn, maxLevel, probability } = options;
 
-    if (elements) {
-      for (const [key, value] of elements) this.add(key, value);
+    if (typeof maxLevel === 'number' && maxLevel > 0) this._maxLevel = maxLevel;
+    if (typeof probability === 'number' && probability > 0 && probability < 1) this._probability = probability;
+
+    this.#isDefaultComparator = comparator === undefined;
+    this.#comparator = comparator ?? SkipList.createDefaultComparator<K>();
+
+    this._head = new SkipListNode<K, V>(undefined as K, undefined as V, this._maxLevel);
+
+    for (const item of entries) {
+      let k: K;
+      let v: V | undefined;
+      if (toEntryFn) {
+        [k, v] = toEntryFn(item as R);
+      } else {
+        if (!Array.isArray(item) || item.length < 2) {
+          throw new TypeError(ERR.invalidEntry('SkipList'));
+        }
+        [k, v] = item as [K, V];
+      }
+      this.set(k, v as V);
     }
   }
 
-  protected _head: SkipListNode<K, V> = new SkipListNode<K, V>(undefined as K, undefined as V, this.maxLevel);
-
-  get head(): SkipListNode<K, V> {
-    return this._head;
+  /**
+   * Creates a default comparator supporting number, string, Date, and bigint.
+   */
+  static createDefaultComparator<K>(): Comparator<K> {
+    return (a: K, b: K): number => {
+      if (typeof a === 'number' && typeof b === 'number') {
+        if (Number.isNaN(a) || Number.isNaN(b)) throw new TypeError(ERR.invalidNaN('SkipList'));
+        return a - b;
+      }
+      if (typeof a === 'string' && typeof b === 'string') {
+        return a < b ? -1 : a > b ? 1 : 0;
+      }
+      if (a instanceof Date && b instanceof Date) {
+        const ta = a.getTime(),
+          tb = b.getTime();
+        if (Number.isNaN(ta) || Number.isNaN(tb)) throw new TypeError(ERR.invalidDate('SkipList'));
+        return ta - tb;
+      }
+      if (typeof a === 'bigint' && typeof b === 'bigint') {
+        return a < b ? -1 : a > b ? 1 : 0;
+      }
+      throw new TypeError(ERR.comparatorRequired('SkipList'));
+    };
   }
 
+  // ─── Internal state ──────────────────────────────────────────
+
+  protected _head: SkipListNode<K, V>;
+
   protected _level: number = 0;
 
-  get level(): number {
-    return this._level;
-  }
+  protected _size: number = 0;
 
   protected _maxLevel: number = 16;
 
+  protected _probability: number = 0.5;
+
+  // ─── Size & lifecycle ────────────────────────────────────────
+
+  get size(): number {
+    return this._size;
+  }
+
   get maxLevel(): number {
     return this._maxLevel;
   }
 
-  protected _probability: number = 0.5;
-
   get probability(): number {
     return this._probability;
   }
 
-  get first(): V | undefined {
-    const firstNode = this.head.forward[0];
-    return firstNode ? firstNode.value : undefined;
+  get comparator(): Comparator<K> {
+    return this.#comparator;
   }
 
-  get last(): V | undefined {
-    let current = this.head;
-    for (let i = this.level - 1; i >= 0; i--) {
-      while (current.forward[i]) {
-        current = current.forward[i];
-      }
-    }
-    return current.value;
+    /**
+   * Check if empty
+  
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Check if empty
+ *  const sl = new SkipList<number, string>();
+ *     console.log(sl.isEmpty()); // true;
+   */
+  isEmpty(): boolean {
+    return this._size === 0;
   }
 
-  add(key: K, value: V): void {
-    const newNode = new SkipListNode(key, value, this._randomLevel());
-    const update: SkipListNode<K, V>[] = new Array(this.maxLevel).fill(this.head);
-    let current = this.head;
+    /**
+   * 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 {
+    this._head = new SkipListNode<K, V>(undefined as K, undefined as V, this._maxLevel);
+    this._level = 0;
+    this._size = 0;
+  }
+
+    /**
+   * 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 {
+    return new SkipList<K, V, R>(this as Iterable<[K, V | undefined]>, {
+      comparator: this.#isDefaultComparator ? undefined : this.#comparator,
+      maxLevel: this._maxLevel,
+      probability: this._probability
+    }) as this;
+  }
 
-    for (let i = this.level - 1; i >= 0; i--) {
-      while (current.forward[i] && current.forward[i].key < key) {
-        current = current.forward[i];
+  // ─── Core CRUD ───────────────────────────────────────────────
+
+  /**
+   * 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 {
+    const cmp = this.#comparator;
+    const update = this._findUpdate(key);
+
+    // If key already exists, update value in place
+    const existing = update[0].forward[0];
+    if (existing && cmp(existing.key, key) === 0) {
+      existing.value = value;
+      return this;
+    }
+
+    const newLevel = this._randomLevel();
+    const newNode = new SkipListNode(key, value, newLevel);
+
+    if (newLevel > this._level) {
+      for (let i = this._level; i < newLevel; i++) {
+        update[i] = this._head;
       }
-      update[i] = current;
+      this._level = newLevel;
     }
 
-    for (let i = 0; i < newNode.forward.length; i++) {
+    for (let i = 0; i < newLevel; i++) {
       newNode.forward[i] = update[i].forward[i];
       update[i].forward[i] = newNode;
     }
 
-    if (!newNode.forward[0]) {
-      this._level = Math.max(this.level, newNode.forward.length);
+    this._size++;
+    return 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'];
+   */
+  override get(key: K): V | undefined {
+    const node = this._findNode(key);
+    return node ? node.value : 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;
+   */
+  override has(key: K): boolean {
+    return this._findNode(key) !== undefined;
+  }
+
+  /**
+   * 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 {
+    const cmp = this.#comparator;
+    const update = this._findUpdate(key);
+
+    const target = update[0].forward[0];
+    if (!target || cmp(target.key, key) !== 0) return false;
+
+    for (let i = 0; i < this._level; i++) {
+      if (update[i].forward[i] !== target) break;
+      update[i].forward[i] = target.forward[i];
+    }
+
+    while (this._level > 0 && !this._head.forward[this._level - 1]) {
+      this._level--;
     }
+
+    this._size--;
+    return true;
+  }
+
+  // ─── Navigation ──────────────────────────────────────────────
+
+  /**
+   * 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 {
+    const node = this._head.forward[0];
+    return node ? [node.key, node.value] : undefined;
   }
 
-  get(key: K): V | undefined {
-    let current = this.head;
-    for (let i = this.level - 1; i >= 0; i--) {
-      while (current.forward[i] && current.forward[i].key < key) {
-        current = current.forward[i];
+  /**
+   * 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 {
+    let current = this._head;
+    for (let i = this._level - 1; i >= 0; i--) {
+      while (current.forward[i]) {
+        current = current.forward[i]!;
       }
     }
+    return current === this._head ? undefined : [current.key, current.value];
+  }
 
-    current = current.forward[0];
+  /**
+   * 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 {
+    const entry = this.first();
+    if (!entry) return undefined;
+    this.delete(entry[0]);
+    return entry;
+  }
+
+  /**
+   * 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 {
+    const entry = this.last();
+    if (!entry) return undefined;
+    this.delete(entry[0]);
+    return entry;
+  }
 
-    if (current && current.key === key) {
-      return current.value;
+  /**
+   * 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 {
+    const cmp = this.#comparator;
+    let current = this._head;
+    for (let i = this._level - 1; i >= 0; i--) {
+      while (current.forward[i] && cmp(current.forward[i]!.key, key) < 0) {
+        current = current.forward[i]!;
+      }
+    }
+    const node = current.forward[0];
+    return node ? [node.key, node.value] : 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 {
+    const cmp = this.#comparator;
+    let current = this._head;
+    for (let i = this._level - 1; i >= 0; i--) {
+      while (current.forward[i] && cmp(current.forward[i]!.key, key) <= 0) {
+        current = current.forward[i]!;
+      }
     }
+    const result = current === this._head ? undefined : current;
 
+    // Check if we're exactly at or before key
+    if (result && cmp(result.key, key) <= 0) return [result.key, result.value];
     return undefined;
   }
 
-  has(key: K): boolean {
-    return this.get(key) !== 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 {
+    const cmp = this.#comparator;
+    let current = this._head;
+    for (let i = this._level - 1; i >= 0; i--) {
+      while (current.forward[i] && cmp(current.forward[i]!.key, key) <= 0) {
+        current = current.forward[i]!;
+      }
+    }
+    const node = current.forward[0];
+    return node ? [node.key, node.value] : undefined;
   }
 
-  delete(key: K): boolean {
-    const update: SkipListNode<K, V>[] = new Array(this.maxLevel).fill(this.head);
-    let current = this.head;
-
-    for (let i = this.level - 1; i >= 0; i--) {
-      while (current.forward[i] && current.forward[i].key < key) {
-        current = current.forward[i];
+  /**
+   * 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 {
+    const cmp = this.#comparator;
+    let current = this._head;
+    let result: SkipListNode<K, V> | undefined;
+    for (let i = this._level - 1; i >= 0; i--) {
+      while (current.forward[i] && cmp(current.forward[i]!.key, key) < 0) {
+        current = current.forward[i]!;
+      }
+      if (current !== this._head && cmp(current.key, key) < 0) {
+        result = current;
       }
-      update[i] = current;
     }
+    return result ? [result.key, result.value] : undefined;
+  }
 
-    current = current.forward[0];
+  /**
+   * 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]> {
+    const { lowInclusive = true, highInclusive = true } = options;
+    const [low, high] = range;
+    const cmp = this.#comparator;
+    const out: Array<[K, V | undefined]> = [];
 
-    if (current && current.key === key) {
-      for (let i = 0; i < this.level; i++) {
-        if (update[i].forward[i] !== current) {
-          break;
-        }
-        update[i].forward[i] = current.forward[i];
+    // Start from the first node >= low
+    let current = this._head;
+    for (let i = this._level - 1; i >= 0; i--) {
+      while (current.forward[i] && cmp(current.forward[i]!.key, low) < 0) {
+        current = current.forward[i]!;
       }
-      while (this.level > 0 && !this.head.forward[this.level - 1]) {
-        this._level--;
+    }
+    current = current.forward[0]!;
+
+    while (current) {
+      const cmpHigh = cmp(current.key, high);
+      if (cmpHigh > 0) break;
+      if (cmpHigh === 0 && !highInclusive) break;
+
+      const cmpLow = cmp(current.key, low);
+      if (cmpLow > 0 || (cmpLow === 0 && lowInclusive)) {
+        out.push([current.key, current.value]);
       }
-      return true;
+
+      current = current.forward[0]!;
     }
 
-    return false;
+    return out;
   }
 
-  higher(key: K): V | undefined {
-    let current = this.head;
-    for (let i = this.level - 1; i >= 0; i--) {
-      while (current.forward[i] && current.forward[i].key <= key) {
-        current = current.forward[i];
-      }
+  // ─── Functional (overrides) ──────────────────────────────────
+
+  /**
+   * 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> {
+    const out = new SkipList<MK, MV>([], options ?? {});
+    let i = 0;
+    for (const [k, v] of this) {
+      const [nk, nv] = callback(v, k, i++, this);
+      out.set(nk, nv);
+    }
+    return out;
+  }
+
+  /**
+   * 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 {
+    const out = new SkipList<K, V, R>([], {
+      comparator: this.#isDefaultComparator ? undefined : this.#comparator,
+      maxLevel: this._maxLevel,
+      probability: this._probability
+    });
+    let i = 0;
+    for (const [k, v] of this) {
+      const ok = callbackfn.call(thisArg, v, k, i++, this);
+      if (ok) out.set(k, v as V);
     }
-    const nextNode = current.forward[0];
-    return nextNode ? nextNode.value : undefined;
+    return out as this;
   }
 
-  lower(key: K): V | undefined {
-    let current = this.head;
-    let lastLess = undefined;
+  // ─── Iterator (required by IterableEntryBase) ────────────────
 
-    for (let i = this.level - 1; i >= 0; i--) {
-      while (current.forward[i] && current.forward[i].key < key) {
-        current = current.forward[i];
+  protected _getIterator(): IterableIterator<[K, V | undefined]> {
+    const head = this._head;
+    return (function* () {
+      let node = head.forward[0];
+      while (node) {
+        yield [node.key, node.value] as [K, V | undefined];
+        node = node.forward[0];
       }
-      if (current.key < key) {
-        lastLess = current;
+    })();
+  }
+
+  // ─── Internal helpers ────────────────────────────────────────
+
+  /**
+   * Finds the update array (predecessors at each level) for a given key.
+   */
+  protected _findUpdate(key: K): SkipListNode<K, V>[] {
+    const cmp = this.#comparator;
+    const update: SkipListNode<K, V>[] = new Array(this._maxLevel).fill(this._head);
+    let current = this._head;
+
+    for (let i = this._level - 1; i >= 0; i--) {
+      while (current.forward[i] && cmp(current.forward[i]!.key, key) < 0) {
+        current = current.forward[i]!;
       }
+      update[i] = current;
     }
 
-    return lastLess ? lastLess.value : undefined;
+    return update;
+  }
+
+  /**
+   * Finds the node for a given key, or undefined.
+   */
+  protected _findNode(key: K): SkipListNode<K, V> | undefined {
+    const cmp = this.#comparator;
+    let current = this._head;
+
+    for (let i = this._level - 1; i >= 0; i--) {
+      while (current.forward[i] && cmp(current.forward[i]!.key, key) < 0) {
+        current = current.forward[i]!;
+      }
+    }
+
+    const candidate = current.forward[0];
+    if (candidate && cmp(candidate.key, key) === 0) return candidate;
+    return undefined;
   }
 
   protected _randomLevel(): number {
     let level = 1;
-    while (Math.random() < this.probability && level < this.maxLevel) {
+    while (Math.random() < this._probability && level < this._maxLevel) {
       level++;
     }
     return level;