data-structure-typed 2.5.0 → 2.5.1

package/src/data-structures/binary-tree/tree-set.ts

@@ -147,36 +147,6 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
-    * @example
- * // Check empty
- *  console.log(new TreeSet().isEmpty()); // true;
-   */
-  isEmpty(): boolean {
-    return this.size === 0;
-  }
-
-  private _validateKey(key: K): void {
-    if (!this.#isDefaultComparator) return;
-
-    if (typeof key === 'number') {
-      if (Number.isNaN(key)) throw new TypeError(ERR.invalidNaN('TreeSet'));
-      return;
-    }
-
-    if (typeof key === 'string') return;
-
-    if (key instanceof Date) {
-      if (Number.isNaN(key.getTime())) throw new TypeError(ERR.invalidDate('TreeSet'));
-      return;
-    }
-
-    // Other key types should have provided a comparator, so reaching here means misuse.
-    throw new TypeError(ERR.comparatorRequired('TreeSet'));
-  }
-
-  /**
-   * Add a key to the set (no-op if already present).
-   * @remarks Expected time O(log n)
    
    
    
@@ -223,28 +193,6 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
-    * @example
- * // Unique tags with sorted order
- *  const tags = new TreeSet<string>(['javascript', 'typescript', 'react', 'typescript', 'node']);
- *
- *     // Duplicates removed, sorted alphabetically
- *     console.log([...tags]); // ['javascript', 'node', 'react', 'typescript'];
- *     console.log(tags.size); // 4;
- *
- *     tags.add('angular');
- *     console.log(tags.first()); // 'angular';
- *     console.log(tags.last()); // 'typescript';
-   */
-  add(key: K): this {
-    this._validateKey(key);
-    // RBT.set returns boolean; Set.add returns this.
-    this.#core.set(key, undefined);
-    return this;
-  }
-
-  /**
-   * Test whether a key exists.
-   * @remarks Expected time O(log n)
    
    
    
@@ -300,20 +248,34 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
     * @example
- * // Checking membership in a sorted collection
- *  const allowed = new TreeSet<string>(['admin', 'editor', 'viewer']);
- *
- *     console.log(allowed.has('admin')); // true;
- *     console.log(allowed.has('guest')); // false;
+ * // Check empty
+ *  console.log(new TreeSet().isEmpty()); // true;
    */
-  has(key: K): boolean {
-    this._validateKey(key);
-    return this.#core.has(key);
+  isEmpty(): boolean {
+    return this.size === 0;
+  }
+
+  private _validateKey(key: K): void {
+    if (!this.#isDefaultComparator) return;
+
+    if (typeof key === 'number') {
+      if (Number.isNaN(key)) throw new TypeError(ERR.invalidNaN('TreeSet'));
+      return;
+    }
+
+    if (typeof key === 'string') return;
+
+    if (key instanceof Date) {
+      if (Number.isNaN(key.getTime())) throw new TypeError(ERR.invalidDate('TreeSet'));
+      return;
+    }
+
+    // Other key types should have provided a comparator, so reaching here means misuse.
+    throw new TypeError(ERR.comparatorRequired('TreeSet'));
   }
 
   /**
-   * Delete a key.
-   * @returns `true` if the key existed; otherwise `false`.
+   * Add a key to the set (no-op if already present).
    * @remarks Expected time O(log n)
    
    
@@ -369,22 +331,6 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
-    * @example
- * // Removing elements while maintaining order
- *  const nums = new TreeSet<number>([1, 3, 5, 7, 9]);
- *
- *     console.log(nums.delete(5)); // true;
- *     console.log(nums.delete(5)); // false; // already gone
- *     console.log([...nums]); // [1, 3, 7, 9];
-   */
-  delete(key: K): boolean {
-    this._validateKey(key);
-    const res = this.#core.delete(key);
-    return Array.isArray(res) && res.length > 0 && !!res[0]?.deleted;
-  }
-
-  /**
-   * Remove all keys.
    
    
    
@@ -428,18 +374,12 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
-    * @example
- * // Remove all
- *  const ts = new TreeSet<number>([1, 2]);
- *       ts.clear();
- *       console.log(ts.isEmpty()); // true;
-   */
-  clear(): void {
-    this.#core.clear();
-  }
-
-  /**
-   * Iterate over keys in ascending order.
+   
+   
+   
+   
+   
+   
    
    
    
@@ -484,18 +424,27 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
     * @example
- * // Get sorted keys
- *  const ts = new TreeSet<number>([30, 10, 20]);
- *       console.log([...ts.keys()]); // [10, 20, 30];
+ * // Unique tags with sorted order
+ *  const tags = new TreeSet<string>(['javascript', 'typescript', 'react', 'typescript', 'node']);
+ *
+ *     // Duplicates removed, sorted alphabetically
+ *     console.log([...tags]); // ['javascript', 'node', 'react', 'typescript'];
+ *     console.log(tags.size); // 4;
+ *
+ *     tags.add('angular');
+ *     console.log(tags.first()); // 'angular';
+ *     console.log(tags.last()); // 'typescript';
    */
-  keys(): IterableIterator<K> {
-    return this.#core.keys();
+  add(key: K): this {
+    this._validateKey(key);
+    // RBT.set returns boolean; Set.add returns this.
+    this.#core.set(key, undefined);
+    return this;
   }
 
   /**
-   * Iterate over values in ascending order.
-   *
-   * Note: for Set-like containers, `values()` is the same as `keys()`.
+   * Test whether a key exists.
+   * @remarks Expected time O(log n)
    
    
    
@@ -539,19 +488,6 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
-    * @example
- * // Get values (same as keys for Set)
- *  const ts = new TreeSet<number>([2, 1, 3]);
- *       console.log([...ts.values()]); // [1, 2, 3];
-   */
-  values(): IterableIterator<K> {
-    return this.keys();
-  }
-
-  /**
-   * Iterate over `[value, value]` pairs (native Set convention).
-   *
-   * Note: TreeSet stores only keys internally; `[k, k]` is created on-the-fly during iteration.
    
    
    
@@ -595,23 +531,6 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
-    * @example
- * // Iterate entries
- *  const ts = new TreeSet<number>([3, 1, 2]);
- *       console.log([...ts.entries()].map(([k]) => k)); // [1, 2, 3];
-   */
-  *entries(): IterableIterator<[K, K]> {
-    for (const k of this.keys()) yield [k, k];
-  }
-
-  [Symbol.iterator](): IterableIterator<K> {
-    return this.keys();
-  }
-
-  /**
-   * Visit each value in ascending order.
-   *
-   * Callback follows native Set convention: `(value, value2, set)`.
    
    
    
@@ -655,22 +574,6 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
-    * @example
- * // Execute for each
- *  const ts = new TreeSet<number>([3, 1, 2]);
- *       const keys: number[] = [];
- *       ts.forEach(k => keys.push(k));
- *       console.log(keys); // [1, 2, 3];
-   */
-  forEach(cb: (value: K, value2: K, set: TreeSet<K>) => void, thisArg?: any): void {
-    for (const k of this) cb.call(thisArg, k, k, this);
-  }
-
-  /**
-   * Create a new TreeSet by mapping each value to a new key.
-   *
-   * This mirrors `RedBlackTree.map`: mapping produces a new ordered container.
-   * @remarks Time O(n log n) expected, Space O(n)
    
    
    
@@ -696,6 +599,31 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
+    * @example
+ * // Checking membership in a sorted collection
+ *  const allowed = new TreeSet<string>(['admin', 'editor', 'viewer']);
+ *
+ *     console.log(allowed.has('admin')); // true;
+ *     console.log(allowed.has('guest')); // false;
+   */
+  has(key: K): boolean {
+    this._validateKey(key);
+    return this.#core.has(key);
+  }
+
+  /**
+   * Delete a key.
+   * @returns `true` if the key existed; otherwise `false`.
+   * @remarks Expected time O(log n)
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -714,31 +642,6 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
-    * @example
- * // Transform
- *  const ts = new TreeSet<number>([1, 2, 3]);
- *       const doubled = ts.map(k => k * 2);
- *       console.log([...doubled]); // [2, 4, 6];
-   */
-  map<MK>(
-    callbackfn: TreeSetElementCallback<K, MK, TreeSet<K>>,
-    options: Omit<TreeSetOptions<MK>, 'toElementFn'> & { comparator?: (a: MK, b: MK) => number } = {},
-    thisArg?: unknown
-  ): TreeSet<MK> {
-    const out = new TreeSet<MK>([], options as TreeSetOptions<MK>);
-    let index = 0;
-    for (const v of this) {
-      const mk = thisArg === undefined
-        ? callbackfn(v, index++, this)
-        : (callbackfn as (this: unknown, v: K, i: number, self: TreeSet<K>) => MK).call(thisArg, v, index++, this);
-      out.add(mk);
-    }
-    return out;
-  }
-
-  /**
-   * Create a new TreeSet containing only values that satisfy the predicate.
-   * @remarks Time O(n log n) expected, Space O(n)
    
    
    
@@ -782,27 +685,6 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
-    * @example
- * // Filter
- *  const ts = new TreeSet<number>([1, 2, 3, 4, 5]);
- *       const evens = ts.filter(k => k % 2 === 0);
- *       console.log([...evens]); // [2, 4];
-   */
-  filter(callbackfn: TreeSetElementCallback<K, boolean, TreeSet<K>>, thisArg?: unknown): TreeSet<K> {
-    const out = new TreeSet<K>([], { comparator: this.#userComparator });
-    let index = 0;
-    for (const v of this) {
-      const ok = thisArg === undefined
-        ? callbackfn(v, index++, this)
-        : (callbackfn as (this: unknown, v: K, i: number, self: TreeSet<K>) => boolean).call(thisArg, v, index++, this);
-      if (ok) out.add(v);
-    }
-    return out;
-  }
-
-  /**
-   * Reduce values into a single accumulator.
-   * @remarks Time O(n), Space O(1)
    
    
    
@@ -846,22 +728,6 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
-    * @example
- * // Aggregate
- *  const ts = new TreeSet<number>([1, 2, 3]);
- *       const sum = ts.reduce((acc, k) => acc + k, 0);
- *       console.log(sum); // 6;
-   */
-  reduce<A>(callbackfn: TreeSetReduceCallback<K, A, TreeSet<K>>, initialValue: A): A {
-    let acc = initialValue;
-    let index = 0;
-    for (const v of this) acc = callbackfn(acc, v, index++, this);
-    return acc;
-  }
-
-  /**
-   * Test whether all values satisfy a predicate.
-   * @remarks Time O(n), Space O(1)
    
    
    
@@ -904,24 +770,21 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
     * @example
- * // Test all
- *  const ts = new TreeSet<number>([2, 4, 6]);
- *       console.log(ts.every(k => k > 0)); // true;
+ * // Removing elements while maintaining order
+ *  const nums = new TreeSet<number>([1, 3, 5, 7, 9]);
+ *
+ *     console.log(nums.delete(5)); // true;
+ *     console.log(nums.delete(5)); // false; // already gone
+ *     console.log([...nums]); // [1, 3, 7, 9];
    */
-  every(callbackfn: TreeSetElementCallback<K, boolean, TreeSet<K>>, thisArg?: unknown): boolean {
-    let index = 0;
-    for (const v of this) {
-      const ok = thisArg === undefined
-        ? callbackfn(v, index++, this)
-        : (callbackfn as (this: unknown, v: K, i: number, self: TreeSet<K>) => boolean).call(thisArg, v, index++, this);
-      if (!ok) return false;
-    }
-    return true;
+  delete(key: K): boolean {
+    this._validateKey(key);
+    const res = this.#core.delete(key);
+    return Array.isArray(res) && res.length > 0 && !!res[0]?.deleted;
   }
 
   /**
-   * Test whether any value satisfies a predicate.
-   * @remarks Time O(n), Space O(1)
+   * Remove all keys.
    
    
    
@@ -963,25 +826,6 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
-    * @example
- * // Test any
- *  const ts = new TreeSet<number>([1, 3, 5]);
- *       console.log(ts.some(k => k === 3)); // true;
-   */
-  some(callbackfn: TreeSetElementCallback<K, boolean, TreeSet<K>>, thisArg?: unknown): boolean {
-    let index = 0;
-    for (const v of this) {
-      const ok = thisArg === undefined
-        ? callbackfn(v, index++, this)
-        : (callbackfn as (this: unknown, v: K, i: number, self: TreeSet<K>) => boolean).call(thisArg, v, index++, this);
-      if (ok) return true;
-    }
-    return false;
-  }
-
-  /**
-   * Find the first value that satisfies a predicate.
-   * @remarks Time O(n), Space O(1)
    
    
    
@@ -1023,26 +867,6 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
-    * @example
- * // Find entry
- *  const ts = new TreeSet<number>([1, 2, 3]);
- *       const found = ts.find(k => k === 2);
- *       console.log(found); // 2;
-   */
-  find(callbackfn: TreeSetElementCallback<K, boolean, TreeSet<K>>, thisArg?: unknown): K | undefined {
-    let index = 0;
-    for (const v of this) {
-      const ok = thisArg === undefined
-        ? callbackfn(v, index++, this)
-        : (callbackfn as (this: unknown, v: K, i: number, self: TreeSet<K>) => boolean).call(thisArg, v, index++, this);
-      if (ok) return v;
-    }
-    return undefined;
-  }
-
-  /**
-   * Materialize the set into an array of keys.
-   * @remarks Time O(n), Space O(n)
    
    
    
@@ -1086,18 +910,6 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
-    * @example
- * // Convert to array
- *  const ts = new TreeSet<number>([3, 1, 2]);
- *       console.log(ts.toArray()); // [1, 2, 3];
-   */
-  toArray(): K[] {
-    return [...this];
-  }
-
-  /**
-   * Print a human-friendly representation.
-   * @remarks Time O(n), Space O(n)
    
    
    
@@ -1116,6 +928,18 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
+    * @example
+ * // Remove all
+ *  const ts = new TreeSet<number>([1, 2]);
+ *       ts.clear();
+ *       console.log(ts.isEmpty()); // true;
+   */
+  clear(): void {
+    this.#core.clear();
+  }
+
+  /**
+   * Iterate over keys in ascending order.
    
    
    
@@ -1141,20 +965,6 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
-    * @example
- * // Display tree
- *  const ts = new TreeSet<number>([1, 2, 3]);
- *       expect(() => ts.print()).not.toThrow();
-   */
-  print(): void {
-    // Delegate to the underlying tree's visualization.
-    this.#core.print();
-  }
-
-  // Navigable operations
-
-  /**
-   * Smallest key in the set.
    
    
    
@@ -1167,40 +977,6 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
-    * @example
- * // Student grade ranking with custom comparator
- *  interface Student {
- *       name: string;
- *       gpa: number;
- *     }
- *
- *     const ranking = new TreeSet<Student>(
- *       [
- *         { name: 'Alice', gpa: 3.8 },
- *         { name: 'Bob', gpa: 3.5 },
- *         { name: 'Charlie', gpa: 3.9 },
- *         { name: 'Diana', gpa: 3.5 }
- *       ],
- *       { comparator: (a, b) => b.gpa - a.gpa || a.name.localeCompare(b.name) }
- *     );
- *
- *     // Sorted by GPA descending, then name ascending
- *     const names = [...ranking].map(s => s.name);
- *     console.log(names); // ['Charlie', 'Alice', 'Bob', 'Diana'];
- *
- *     // Top student
- *     console.log(ranking.first()?.name); // 'Charlie';
- *
- *     // Filter students with GPA >= 3.8
- *     const honors = ranking.filter(s => s.gpa >= 3.8);
- *     console.log(honors.toArray().map(s => s.name)); // ['Charlie', 'Alice'];
-   */
-  first(): K | undefined {
-    return this.#core.getLeftMost();
-  }
-
-  /**
-   * Largest key in the set.
    
    
    
@@ -1213,18 +989,6 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
-    * @example
- * // Get the maximum element
- *  const temps = new TreeSet<number>([18, 22, 15, 30, 25]);
- *     console.log(temps.last()); // 30;
- *     console.log(temps.first()); // 15;
-   */
-  last(): K | undefined {
-    return this.#core.getRightMost();
-  }
-
-  /**
-   * Remove and return the smallest key.
    
    
    
@@ -1237,23 +1001,6 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
-    * @example
- * // Remove and return minimum
- *  const queue = new TreeSet<number>([5, 1, 8, 3]);
- *
- *     console.log(queue.pollFirst()); // 1;
- *     console.log(queue.pollFirst()); // 3;
- *     console.log(queue.size); // 2;
-   */
-  pollFirst(): K | undefined {
-    const k = this.first();
-    if (k === undefined) return undefined;
-    this.delete(k);
-    return k;
-  }
-
-  /**
-   * Remove and return the largest key.
    
    
    
@@ -1266,22 +1013,6 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
-    * @example
- * // Remove and return maximum
- *  const stack = new TreeSet<number>([10, 20, 30]);
- *
- *     console.log(stack.pollLast()); // 30;
- *     console.log(stack.size); // 2;
-   */
-  pollLast(): K | undefined {
-    const k = this.last();
-    if (k === undefined) return undefined;
-    this.delete(k);
-    return k;
-  }
-
-  /**
-   * Smallest key that is >= the given key.
    
    
    
@@ -1324,30 +1055,6 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
-    * @example
- * // Finding nearest available time slot
- *  // Available appointment times (minutes from midnight)
- *     const slots = new TreeSet<number>([540, 600, 660, 720, 840, 900]);
- *
- *     // Customer wants something around 10:30 (630 min)
- *     const nearest = slots.ceiling(630);
- *     console.log(nearest); // 660; // 11:00 AM
- *
- *     // What's the latest slot before 2:00 PM (840)?
- *     const before2pm = slots.lower(840);
- *     console.log(before2pm); // 720; // 12:00 PM
- *
- *     // Book the 11:00 slot
- *     slots.delete(660);
- *     console.log(slots.ceiling(630)); // 720;
-   */
-  ceiling(key: K): K | undefined {
-    this._validateKey(key);
-    return this.#core.ceiling(key);
-  }
-
-  /**
-   * Largest key that is <= the given key.
    
    
    
@@ -1376,6 +1083,19 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
+    * @example
+ * // Get sorted keys
+ *  const ts = new TreeSet<number>([30, 10, 20]);
+ *       console.log([...ts.keys()]); // [10, 20, 30];
+   */
+  keys(): IterableIterator<K> {
+    return this.#core.keys();
+  }
+
+  /**
+   * Iterate over values in ascending order.
+   *
+   * Note: for Set-like containers, `values()` is the same as `keys()`.
    
    
    
@@ -1390,22 +1110,6 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
-    * @example
- * // Largest element ≤ target
- *  const breakpoints = new TreeSet<number>([320, 768, 1024, 1280, 1920]);
- *
- *     // Current width is 800 → which breakpoint applies?
- *     console.log(breakpoints.floor(800)); // 768;
- *     console.log(breakpoints.floor(1024)); // 1024; // exact match
- *     console.log(breakpoints.floor(100)); // undefined;
-   */
-  floor(key: K): K | undefined {
-    this._validateKey(key);
-    return this.#core.floor(key);
-  }
-
-  /**
-   * Smallest key that is > the given key.
    
    
    
@@ -1448,7 +1152,2323 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
-    * @example
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Get values (same as keys for Set)
+ *  const ts = new TreeSet<number>([2, 1, 3]);
+ *       console.log([...ts.values()]); // [1, 2, 3];
+   */
+  values(): IterableIterator<K> {
+    return this.keys();
+  }
+
+  /**
+   * Iterate over `[value, value]` pairs (native Set convention).
+   *
+   * Note: TreeSet stores only keys internally; `[k, k]` is created on-the-fly during iteration.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Iterate entries
+ *  const ts = new TreeSet<number>([3, 1, 2]);
+ *       console.log([...ts.entries()].map(([k]) => k)); // [1, 2, 3];
+   */
+  *entries(): IterableIterator<[K, K]> {
+    for (const k of this.keys()) yield [k, k];
+  }
+
+  [Symbol.iterator](): IterableIterator<K> {
+    return this.keys();
+  }
+
+  /**
+   * Visit each value in ascending order.
+   *
+   * Callback follows native Set convention: `(value, value2, set)`.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Execute for each
+ *  const ts = new TreeSet<number>([3, 1, 2]);
+ *       const keys: number[] = [];
+ *       ts.forEach(k => keys.push(k));
+ *       console.log(keys); // [1, 2, 3];
+   */
+  forEach(cb: (value: K, value2: K, set: TreeSet<K>) => void, thisArg?: unknown): void {
+    for (const k of this) cb.call(thisArg, k, k, this);
+  }
+
+  /**
+   * Create a new TreeSet by mapping each value to a new key.
+   *
+   * This mirrors `RedBlackTree.map`: mapping produces a new ordered container.
+   * @remarks Time O(n log n) expected, Space O(n)
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Transform
+ *  const ts = new TreeSet<number>([1, 2, 3]);
+ *       const doubled = ts.map(k => k * 2);
+ *       console.log([...doubled]); // [2, 4, 6];
+   */
+  map<MK>(
+    callbackfn: TreeSetElementCallback<K, MK, TreeSet<K>>,
+    options: Omit<TreeSetOptions<MK>, 'toElementFn'> & { comparator?: (a: MK, b: MK) => number } = {},
+    thisArg?: unknown
+  ): TreeSet<MK> {
+    const out = new TreeSet<MK>([], options as TreeSetOptions<MK>);
+    let index = 0;
+    for (const v of this) {
+      const mk = thisArg === undefined
+        ? callbackfn(v, index++, this)
+        : (callbackfn as (this: unknown, v: K, i: number, self: TreeSet<K>) => MK).call(thisArg, v, index++, this);
+      out.add(mk);
+    }
+    return out;
+  }
+
+  /**
+   * Create a new TreeSet containing only values that satisfy the predicate.
+   * @remarks Time O(n log n) expected, Space O(n)
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Filter
+ *  const ts = new TreeSet<number>([1, 2, 3, 4, 5]);
+ *       const evens = ts.filter(k => k % 2 === 0);
+ *       console.log([...evens]); // [2, 4];
+   */
+  filter(callbackfn: TreeSetElementCallback<K, boolean, TreeSet<K>>, thisArg?: unknown): TreeSet<K> {
+    const out = new TreeSet<K>([], { comparator: this.#userComparator });
+    let index = 0;
+    for (const v of this) {
+      const ok = thisArg === undefined
+        ? callbackfn(v, index++, this)
+        : (callbackfn as (this: unknown, v: K, i: number, self: TreeSet<K>) => boolean).call(thisArg, v, index++, this);
+      if (ok) out.add(v);
+    }
+    return out;
+  }
+
+  /**
+   * Reduce values into a single accumulator.
+   * @remarks Time O(n), Space O(1)
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Aggregate
+ *  const ts = new TreeSet<number>([1, 2, 3]);
+ *       const sum = ts.reduce((acc, k) => acc + k, 0);
+ *       console.log(sum); // 6;
+   */
+  reduce<A>(callbackfn: TreeSetReduceCallback<K, A, TreeSet<K>>, initialValue: A): A {
+    let acc = initialValue;
+    let index = 0;
+    for (const v of this) acc = callbackfn(acc, v, index++, this);
+    return acc;
+  }
+
+  /**
+   * Test whether all values satisfy a predicate.
+   * @remarks Time O(n), Space O(1)
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Test all
+ *  const ts = new TreeSet<number>([2, 4, 6]);
+ *       console.log(ts.every(k => k > 0)); // true;
+   */
+  every(callbackfn: TreeSetElementCallback<K, boolean, TreeSet<K>>, thisArg?: unknown): boolean {
+    let index = 0;
+    for (const v of this) {
+      const ok = thisArg === undefined
+        ? callbackfn(v, index++, this)
+        : (callbackfn as (this: unknown, v: K, i: number, self: TreeSet<K>) => boolean).call(thisArg, v, index++, this);
+      if (!ok) return false;
+    }
+    return true;
+  }
+
+  /**
+   * Test whether any value satisfies a predicate.
+   * @remarks Time O(n), Space O(1)
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Test any
+ *  const ts = new TreeSet<number>([1, 3, 5]);
+ *       console.log(ts.some(k => k === 3)); // true;
+   */
+  some(callbackfn: TreeSetElementCallback<K, boolean, TreeSet<K>>, thisArg?: unknown): boolean {
+    let index = 0;
+    for (const v of this) {
+      const ok = thisArg === undefined
+        ? callbackfn(v, index++, this)
+        : (callbackfn as (this: unknown, v: K, i: number, self: TreeSet<K>) => boolean).call(thisArg, v, index++, this);
+      if (ok) return true;
+    }
+    return false;
+  }
+
+  /**
+   * Find the first value that satisfies a predicate.
+   * @remarks Time O(n), Space O(1)
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Find entry
+ *  const ts = new TreeSet<number>([1, 2, 3]);
+ *       const found = ts.find(k => k === 2);
+ *       console.log(found); // 2;
+   */
+  find(callbackfn: TreeSetElementCallback<K, boolean, TreeSet<K>>, thisArg?: unknown): K | undefined {
+    let index = 0;
+    for (const v of this) {
+      const ok = thisArg === undefined
+        ? callbackfn(v, index++, this)
+        : (callbackfn as (this: unknown, v: K, i: number, self: TreeSet<K>) => boolean).call(thisArg, v, index++, this);
+      if (ok) return v;
+    }
+    return undefined;
+  }
+
+  /**
+   * Materialize the set into an array of keys.
+   * @remarks Time O(n), Space O(n)
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Convert to array
+ *  const ts = new TreeSet<number>([3, 1, 2]);
+ *       console.log(ts.toArray()); // [1, 2, 3];
+   */
+  toArray(): K[] {
+    return [...this];
+  }
+
+  /**
+   * Print a human-friendly representation.
+   * @remarks Time O(n), Space O(n)
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Display tree
+ *  const ts = new TreeSet<number>([1, 2, 3]);
+ *       expect(() => ts.print()).not.toThrow();
+   */
+  print(): void {
+    // Delegate to the underlying tree's visualization.
+    this.#core.print();
+  }
+
+  // Navigable operations
+
+  /**
+   * Smallest key in the set.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Student grade ranking with custom comparator
+ *  interface Student {
+ *       name: string;
+ *       gpa: number;
+ *     }
+ *
+ *     const ranking = new TreeSet<Student>(
+ *       [
+ *         { name: 'Alice', gpa: 3.8 },
+ *         { name: 'Bob', gpa: 3.5 },
+ *         { name: 'Charlie', gpa: 3.9 },
+ *         { name: 'Diana', gpa: 3.5 }
+ *       ],
+ *       { comparator: (a, b) => b.gpa - a.gpa || a.name.localeCompare(b.name) }
+ *     );
+ *
+ *     // Sorted by GPA descending, then name ascending
+ *     const names = [...ranking].map(s => s.name);
+ *     console.log(names); // ['Charlie', 'Alice', 'Bob', 'Diana'];
+ *
+ *     // Top student
+ *     console.log(ranking.first()?.name); // 'Charlie';
+ *
+ *     // Filter students with GPA >= 3.8
+ *     const honors = ranking.filter(s => s.gpa >= 3.8);
+ *     console.log(honors.toArray().map(s => s.name)); // ['Charlie', 'Alice'];
+   */
+  first(): K | undefined {
+    return this.#core.getLeftMost();
+  }
+
+  /**
+   * Largest key in the set.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Get the maximum element
+ *  const temps = new TreeSet<number>([18, 22, 15, 30, 25]);
+ *     console.log(temps.last()); // 30;
+ *     console.log(temps.first()); // 15;
+   */
+  last(): K | undefined {
+    return this.#core.getRightMost();
+  }
+
+  /**
+   * Remove and return the smallest key.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Remove and return minimum
+ *  const queue = new TreeSet<number>([5, 1, 8, 3]);
+ *
+ *     console.log(queue.pollFirst()); // 1;
+ *     console.log(queue.pollFirst()); // 3;
+ *     console.log(queue.size); // 2;
+   */
+  pollFirst(): K | undefined {
+    const k = this.first();
+    if (k === undefined) return undefined;
+    this.delete(k);
+    return k;
+  }
+
+  /**
+   * Remove and return the largest key.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Remove and return maximum
+ *  const stack = new TreeSet<number>([10, 20, 30]);
+ *
+ *     console.log(stack.pollLast()); // 30;
+ *     console.log(stack.size); // 2;
+   */
+  pollLast(): K | undefined {
+    const k = this.last();
+    if (k === undefined) return undefined;
+    this.delete(k);
+    return k;
+  }
+
+  /**
+   * Smallest key that is >= the given key.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Finding nearest available time slot
+ *  // Available appointment times (minutes from midnight)
+ *     const slots = new TreeSet<number>([540, 600, 660, 720, 840, 900]);
+ *
+ *     // Customer wants something around 10:30 (630 min)
+ *     const nearest = slots.ceiling(630);
+ *     console.log(nearest); // 660; // 11:00 AM
+ *
+ *     // What's the latest slot before 2:00 PM (840)?
+ *     const before2pm = slots.lower(840);
+ *     console.log(before2pm); // 720; // 12:00 PM
+ *
+ *     // Book the 11:00 slot
+ *     slots.delete(660);
+ *     console.log(slots.ceiling(630)); // 720;
+   */
+  ceiling(key: K): K | undefined {
+    this._validateKey(key);
+    return this.#core.ceiling(key);
+  }
+
+  /**
+   * Largest key that is <= the given key.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Largest element ≤ target
+ *  const breakpoints = new TreeSet<number>([320, 768, 1024, 1280, 1920]);
+ *
+ *     // Current width is 800 → which breakpoint applies?
+ *     console.log(breakpoints.floor(800)); // 768;
+ *     console.log(breakpoints.floor(1024)); // 1024; // exact match
+ *     console.log(breakpoints.floor(100)); // undefined;
+   */
+  floor(key: K): K | undefined {
+    this._validateKey(key);
+    return this.#core.floor(key);
+  }
+
+  /**
+   * Smallest key that is > the given key.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
  * // Smallest element strictly > target
  *  const levels = new TreeSet<number>([1, 5, 10, 25, 50, 100]);
  *
@@ -1483,6 +3503,86 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -1542,6 +3642,86 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -1628,6 +3808,106 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+