data-structure-typed 2.4.4 → 2.5.0

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

@@ -9,6 +9,7 @@
 
 import type { Comparator } from '../../types';
 import type { TreeSetElementCallback, TreeSetOptions, TreeSetRangeOptions, TreeSetReduceCallback } from '../../types';
+import { ERR } from '../../common';
 import { RedBlackTree } from './red-black-tree';
 
 /**
@@ -16,6 +17,11 @@ import { RedBlackTree } from './red-black-tree';
  *
  * - Iteration order is ascending by key.
  * - No node exposure: all APIs use keys only.
+ * @example
+ * // Set multiple key-value pairs
+ *  const ts = new TreeSet<number, string>();
+ *     ts.setMany([[1, 'a'], [2, 'b'], [3, 'c']]);
+ *     console.log(ts.size); // 3;
  */
 export class TreeSet<K = any, R = K> implements Iterable<K> {
   readonly #core: RedBlackTree<K, undefined>;
@@ -66,27 +72,26 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
     return (a: K, b: K): number => {
       // numbers
       if (typeof a === 'number' && typeof b === 'number') {
-        if (Number.isNaN(a) || Number.isNaN(b)) throw new TypeError('TreeSet: NaN is not a valid key');
-        // treat -0 and 0 as equal
+        /* istanbul ignore next -- _validateKey prevents NaN from entering the tree */
+        if (Number.isNaN(a) || Number.isNaN(b)) throw new TypeError(ERR.invalidNaN('TreeSet'));
         const aa = Object.is(a, -0) ? 0 : a;
         const bb = Object.is(b, -0) ? 0 : b;
         return aa > bb ? 1 : aa < bb ? -1 : 0;
       }
 
-      // strings
       if (typeof a === 'string' && typeof b === 'string') {
         return a > b ? 1 : a < b ? -1 : 0;
       }
 
-      // Date
       if (a instanceof Date && b instanceof Date) {
         const ta = a.getTime();
         const tb = b.getTime();
-        if (Number.isNaN(ta) || Number.isNaN(tb)) throw new TypeError('TreeSet: invalid Date key');
+        /* istanbul ignore next -- _validateKey prevents invalid Date from entering the tree */
+        if (Number.isNaN(ta) || Number.isNaN(tb)) throw new TypeError(ERR.invalidDate('TreeSet'));
         return ta > tb ? 1 : ta < tb ? -1 : 0;
       }
 
-      throw new TypeError('TreeSet: comparator is required for non-number/non-string/non-Date keys');
+      throw new TypeError(ERR.comparatorRequired('TreeSet'));
     };
   }
 
@@ -99,6 +104,52 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
 
   /**
    * Whether the set is empty.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Check empty
+ *  console.log(new TreeSet().isEmpty()); // true;
    */
   isEmpty(): boolean {
     return this.size === 0;
@@ -108,24 +159,81 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
     if (!this.#isDefaultComparator) return;
 
     if (typeof key === 'number') {
-      if (Number.isNaN(key)) throw new TypeError('TreeSet: NaN is not a valid key');
+      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('TreeSet: invalid Date key');
+      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('TreeSet: comparator is required for non-number/non-string/non-Date keys');
+    throw new TypeError(ERR.comparatorRequired('TreeSet'));
   }
 
   /**
    * Add a key to the set (no-op if already present).
    * @remarks Expected time O(log n)
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @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);
@@ -137,6 +245,66 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
   /**
    * Test whether a key exists.
    * @remarks Expected time O(log n)
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @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);
@@ -147,6 +315,67 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    * Delete a key.
    * @returns `true` if the key existed; otherwise `false`.
    * @remarks Expected time O(log n)
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @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);
@@ -156,6 +385,54 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
 
   /**
    * Remove all keys.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Remove all
+ *  const ts = new TreeSet<number>([1, 2]);
+ *       ts.clear();
+ *       console.log(ts.isEmpty()); // true;
    */
   clear(): void {
     this.#core.clear();
@@ -163,6 +440,53 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
 
   /**
    * Iterate over keys in ascending order.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @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();
@@ -172,6 +496,53 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    * Iterate over values in ascending order.
    *
    * Note: for Set-like containers, `values()` is the same as `keys()`.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @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();
@@ -181,6 +552,53 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    * 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];
@@ -194,6 +612,55 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    * 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?: any): void {
     for (const k of this) cb.call(thisArg, k, k, this);
@@ -204,6 +671,54 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    *
    * 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>>,
@@ -224,6 +739,54 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
   /**
    * 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 });
@@ -240,6 +803,54 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
   /**
    * 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;
@@ -251,6 +862,51 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
   /**
    * 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;
@@ -266,6 +922,51 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
   /**
    * 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;
@@ -281,6 +982,52 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
   /**
    * 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;
@@ -296,6 +1043,53 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
   /**
    * 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];
@@ -304,6 +1098,53 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
   /**
    * 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.
@@ -314,6 +1155,45 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
 
   /**
    * 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();
@@ -321,6 +1201,23 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
 
   /**
    * 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();
@@ -328,6 +1225,25 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
 
   /**
    * 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();
@@ -338,6 +1254,24 @@ export class TreeSet<K = any, R = K> implements Iterable<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();
@@ -348,6 +1282,64 @@ export class TreeSet<K = any, R = K> implements Iterable<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);
@@ -356,6 +1348,56 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
 
   /**
    * 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);
@@ -364,6 +1406,54 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
 
   /**
    * Smallest key that is > the given key.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Smallest element strictly > target
+ *  const levels = new TreeSet<number>([1, 5, 10, 25, 50, 100]);
+ *
+ *     console.log(levels.higher(10)); // 25;
+ *     console.log(levels.higher(100)); // undefined;
    */
   higher(key: K): K | undefined {
     this._validateKey(key);
@@ -372,6 +1462,54 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
 
   /**
    * Largest key that is < the given key.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Largest element strictly < target
+ *  const tiers = new TreeSet<number>([100, 200, 500, 1000]);
+ *
+ *     console.log(tiers.lower(500)); // 200;
+ *     console.log(tiers.lower(100)); // undefined;
    */
   lower(key: K): K | undefined {
     this._validateKey(key);
@@ -383,6 +1521,65 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    *
    * @param range `[low, high]`
    * @param options Inclusive/exclusive bounds (defaults to inclusive).
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // IP address blocklist with range checking
+ *  // Simplified: use numeric IP representation
+ *     const blocklist = new TreeSet<number>([
+ *       167772160, // 10.0.0.0
+ *       167772416, // 10.0.1.0
+ *       167772672, // 10.0.2.0
+ *       167773184  // 10.0.4.0
+ *     ]);
+ *
+ *     // Check if any blocked IP is in range 10.0.1.0 - 10.0.3.0
+ *     const inRange = blocklist.rangeSearch([167772416, 167772928]);
+ *     console.log(inRange); // [167772416, 167772672];
+ *
+ *     // Quick membership check
+ *     console.log(blocklist.has(167772416)); // true;
+ *     console.log(blocklist.has(167772800)); // false;
    */
   rangeSearch(range: [K, K], options: TreeSetRangeOptions = {}): K[] {
     const { lowInclusive = true, highInclusive = true } = options;
@@ -396,7 +1593,7 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
     const cmp = this.#core.comparator;
 
     for (const k of keys) {
-      if (k === undefined) continue;
+      /* istanbul ignore next -- defensive: tree keys are never undefined */ if (k === undefined) continue;
       if (!lowInclusive && cmp(k, low) === 0) continue;
       if (!highInclusive && cmp(k, high) === 0) continue;
       out.push(k);
@@ -408,11 +1605,56 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
   /**
    * Creates a shallow clone of this set.
    * @remarks Time O(n log n), Space O(n)
-   * @example
-   * const original = new TreeSet([1, 2, 3]);
-   * const copy = original.clone();
-   * copy.add(4);
-   * original.has(4); // false (original unchanged)
+  
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Deep clone
+ *  const ts = new TreeSet<number>([1, 2, 3]);
+ *       const copy = ts.clone();
+ *       copy.delete(1);
+ *       console.log(ts.has(1)); // true;
    */
   clone(): TreeSet<K> {
     return new TreeSet<K>(this, {