binary-tree-typed 2.4.4 → 2.5.0

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

@@ -10,12 +10,18 @@
 import type { Comparator } from '../../types';
 import type { TreeMapEntryCallback, TreeMapOptions, TreeMapRangeOptions, TreeMapReduceCallback } from '../../types';
 import { RedBlackTree } from './red-black-tree';
+import { ERR } from '../../common';
 
 /**
  * An ordered Map backed by a red-black tree.
  *
  * - Iteration order is ascending by key.
  * - No node exposure: all APIs use keys/values only.
+ * @example
+ * // Set multiple key-value pairs
+ *  const tm = new TreeMap<number, string>();
+ *     tm.setMany([[1, 'a'], [2, 'b'], [3, 'c']]);
+ *     console.log(tm.size); // 3;
  */
 export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | undefined]> {
   readonly #core: RedBlackTree<K, V>;
@@ -58,7 +64,7 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
       } else {
         // Validate entries like native Map: each item must be a 2-tuple-like value.
         if (!Array.isArray(item) || item.length < 2) {
-          throw new TypeError('TreeMap: each entry must be a [key, value] tuple');
+          throw new TypeError(ERR.invalidEntry('TreeMap'));
         }
         k = item[0] as K;
         v = item[1] as V | undefined;
@@ -81,7 +87,8 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
   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('TreeMap: NaN is not a valid key');
+        /* istanbul ignore next -- _validateKey prevents NaN from entering the tree */
+        if (Number.isNaN(a) || Number.isNaN(b)) throw new TypeError(ERR.invalidNaN('TreeMap'));
         const aa = Object.is(a, -0) ? 0 : a;
         const bb = Object.is(b, -0) ? 0 : b;
         return aa > bb ? 1 : aa < bb ? -1 : 0;
@@ -94,11 +101,12 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
       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('TreeMap: 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('TreeMap'));
         return ta > tb ? 1 : ta < tb ? -1 : 0;
       }
 
-      throw new TypeError('TreeMap: comparator is required for non-number/non-string/non-Date keys');
+      throw new TypeError(ERR.comparatorRequired('TreeMap'));
     };
   }
 
@@ -106,18 +114,18 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
     if (!this.#isDefaultComparator) return;
 
     if (typeof key === 'number') {
-      if (Number.isNaN(key)) throw new TypeError('TreeMap: NaN is not a valid key');
+      if (Number.isNaN(key)) throw new TypeError(ERR.invalidNaN('TreeMap'));
       return;
     }
 
     if (typeof key === 'string') return;
 
     if (key instanceof Date) {
-      if (Number.isNaN(key.getTime())) throw new TypeError('TreeMap: invalid Date key');
+      if (Number.isNaN(key.getTime())) throw new TypeError(ERR.invalidDate('TreeMap'));
       return;
     }
 
-    throw new TypeError('TreeMap: comparator is required for non-number/non-string/non-Date keys');
+    throw new TypeError(ERR.comparatorRequired('TreeMap'));
   }
 
   /**
@@ -129,6 +137,47 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
 
   /**
    * Whether the map is empty.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Check empty
+ *  console.log(new TreeMap().isEmpty()); // true;
    */
   isEmpty(): boolean {
     return this.size === 0;
@@ -137,6 +186,73 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
   /**
    * Set or overwrite a value for a key.
    * @remarks Expected time O(log n)
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Sorted dictionary for a contact book
+ *  const contacts = new TreeMap<string, string>([
+ *       ['Bob', '555-0102'],
+ *       ['Alice', '555-0101'],
+ *       ['Charlie', '555-0103']
+ *     ]);
+ *
+ *     // Contacts are automatically sorted by name
+ *     console.log([...contacts.keys()]); // ['Alice', 'Bob', 'Charlie'];
+ *     console.log(contacts.get('Bob')); // '555-0102';
+ *
+ *     // Find the first contact alphabetically after 'B'
+ *     console.log(contacts.ceiling('B')); // ['Bob', '555-0102'];
+ *
+ *     // Find contacts in range
+ *     console.log(contacts.rangeSearch(['Alice', 'Bob'])); // [
+ *  //      ['Alice', '555-0101'],
+ *  //      ['Bob', '555-0102']
+ *  //    ];
    */
   set(key: K, value: V | undefined): this {
     this._validateKey(key);
@@ -147,6 +263,66 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
   /**
    * Get the value under a key.
    * @remarks Expected time O(log n)
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Configuration registry with typed lookups
+ *  const config = new TreeMap<string, number>([
+ *       ['maxRetries', 3],
+ *       ['timeout', 5000],
+ *       ['poolSize', 10]
+ *     ]);
+ *
+ *     console.log(config.get('timeout')); // 5000;
+ *     console.log(config.get('missing')); // undefined;
+ *     console.log(config.size); // 3;
    */
   get(key: K): V | undefined {
     this._validateKey(key);
@@ -156,6 +332,65 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
   /**
    * Test whether a key exists.
    * @remarks Expected time O(log n)
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Feature flag checking
+ *  const flags = new TreeMap<string, boolean>([
+ *       ['darkMode', true],
+ *       ['betaFeature', false],
+ *       ['notifications', true]
+ *     ]);
+ *
+ *     console.log(flags.has('darkMode')); // true;
+ *     console.log(flags.has('unknownFlag')); // false;
    */
   has(key: K): boolean {
     this._validateKey(key);
@@ -166,6 +401,67 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    * Delete a key.
    * @returns `true` if the key existed; otherwise `false`.
    * @remarks Expected time O(log n)
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Session management with expiry
+ *  const sessions = new TreeMap<string, number>([
+ *       ['sess_abc', Date.now()],
+ *       ['sess_def', Date.now()],
+ *       ['sess_ghi', Date.now()]
+ *     ]);
+ *
+ *     console.log(sessions.size); // 3;
+ *     sessions.delete('sess_def');
+ *     console.log(sessions.has('sess_def')); // false;
+ *     console.log(sessions.size); // 2;
    */
   delete(key: K): boolean {
     this._validateKey(key);
@@ -175,6 +471,49 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
 
   /**
    * Remove all entries.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Remove all
+ *  const tm = new TreeMap<number, string>([[1, 'a']]);
+ *       tm.clear();
+ *       console.log(tm.isEmpty()); // true;
    */
   clear(): void {
     this.#core.clear();
@@ -182,6 +521,48 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
 
   /**
    * Iterate over keys in ascending order.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Get sorted keys
+ *  const tm = new TreeMap<number, string>([[3, 'c'], [1, 'a']]);
+ *       console.log([...tm.keys()]); // [1, 3];
    */
   keys(): IterableIterator<K> {
     return this.#core.keys();
@@ -197,6 +578,48 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    * Iterate over values in ascending key order.
    *
    * Note: values may be `undefined` (TreeMap allows storing `undefined`, like native `Map`).
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Get values in key order
+ *  const tm = new TreeMap<number, string>([[2, 'b'], [1, 'a']]);
+ *       console.log([...tm.values()]); // ['a', 'b'];
    */
   *values(): IterableIterator<V | undefined> {
     for (const k of this.keys()) yield this._entryFromKey(k)[1];
@@ -206,6 +629,48 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    * Iterate over `[key, value]` entries in ascending key order.
    *
    * Note: values may be `undefined`.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Iterate key-value pairs
+ *  const tm = new TreeMap<number, string>([[3, 'c'], [1, 'a'], [2, 'b']]);
+ *       console.log([...tm.entries()]); // [[1, 'a'], [2, 'b'], [3, 'c']];
    */
   *entries(): IterableIterator<[K, V | undefined]> {
     for (const k of this.keys()) yield this._entryFromKey(k);
@@ -219,6 +684,50 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    * Visit each entry in ascending key order.
    *
    * Note: callback value may be `undefined`.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Execute for each entry
+ *  const tm = new TreeMap<number, string>([[1, 'a'], [2, 'b']]);
+ *       const pairs: string[] = [];
+ *       tm.forEach((v, k) => pairs.push(`${k}:${v}`));
+ *       console.log(pairs); // ['1:a', '2:b'];
    */
   forEach(cb: (value: V | undefined, key: K, map: TreeMap<K, V>) => void, thisArg?: any): void {
     for (const [k, v] of this) cb.call(thisArg, v, k, this);
@@ -229,6 +738,49 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    *
    * This mirrors `RedBlackTree.map`: mapping produces a new ordered container.
    * @remarks Time O(n log n) expected, Space O(n)
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Transform entries
+ *  const tm = new TreeMap<number, number>([[1, 10], [2, 20]]);
+ *       const doubled = tm.map((v, k) => [k, (v ?? 0) * 2] as [number, number]);
+ *       console.log([...doubled.values()]); // [20, 40];
    */
   map<MK, MV>(
     callbackfn: TreeMapEntryCallback<K, V, [MK, MV], TreeMap<K, V>>,
@@ -249,6 +801,49 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
   /**
    * Create a new TreeMap containing only entries that satisfy the predicate.
    * @remarks Time O(n log n) expected, Space O(n)
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Filter entries
+ *  const tm = new TreeMap<number, string>([[1, 'a'], [2, 'b'], [3, 'c']]);
+ *       const filtered = tm.filter((v, k) => k > 1);
+ *       console.log([...filtered.keys()]); // [2, 3];
    */
   filter(callbackfn: TreeMapEntryCallback<K, V, boolean, TreeMap<K, V>>, thisArg?: unknown): TreeMap<K, V> {
     const out = new TreeMap<K, V>([], { comparator: this.#userComparator });
@@ -265,6 +860,48 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
   /**
    * Reduce entries into a single accumulator.
    * @remarks Time O(n), Space O(1)
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Aggregate values
+ *  const tm = new TreeMap<number, number>([[1, 10], [2, 20]]);
+ *       console.log(tm.reduce((acc, v) => acc + (v ?? 0), 0)); // 30;
    */
   reduce<A>(callbackfn: TreeMapReduceCallback<K, V, A, TreeMap<K, V>>, initialValue: A): A {
     let acc = initialValue;
@@ -276,6 +913,46 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
   /**
    * Test whether all entries satisfy a predicate.
    * @remarks Time O(n), Space O(1)
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Test all entries
+ *  const tm = new TreeMap<number, string>([[1, 'a'], [2, 'b']]);
+ *       console.log(tm.every((v, k) => k > 0)); // true;
    */
   every(callbackfn: TreeMapEntryCallback<K, V, boolean, TreeMap<K, V>>, thisArg?: unknown): boolean {
     let index = 0;
@@ -291,6 +968,46 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
   /**
    * Test whether any entry satisfies a predicate.
    * @remarks Time O(n), Space O(1)
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Test any entry
+ *  const tm = new TreeMap<number, string>([[1, 'a'], [2, 'b']]);
+ *       console.log(tm.some((v, k) => k === 2)); // true;
    */
   some(callbackfn: TreeMapEntryCallback<K, V, boolean, TreeMap<K, V>>, thisArg?: unknown): boolean {
     let index = 0;
@@ -307,6 +1024,46 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    * Find the first entry that satisfies a predicate.
    * @returns The first matching `[key, value]` tuple, or `undefined`.
    * @remarks Time O(n), Space O(1)
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Find matching entry
+ *  const tm = new TreeMap<number, string>([[1, 'a'], [2, 'b']]);
+ *       console.log(tm.find(v => v === 'b')?.[0]); // 2;
    */
   find(callbackfn: TreeMapEntryCallback<K, V, boolean, TreeMap<K, V>>, thisArg?: unknown): [K, V | undefined] | undefined {
     let index = 0;
@@ -322,6 +1079,48 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
   /**
    * Materialize the map into an array of `[key, value]` tuples.
    * @remarks Time O(n), Space O(n)
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Convert to array
+ *  const tm = new TreeMap<number, string>([[2, 'b'], [1, 'a']]);
+ *       console.log(tm.toArray()); // [[1, 'a'], [2, 'b']];
    */
   toArray(): Array<[K, V | undefined]> {
     return [...this];
@@ -330,6 +1129,48 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
   /**
    * Print a human-friendly representation.
    * @remarks Time O(n), Space O(n)
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Display tree
+ *  const tm = new TreeMap<number, string>([[1, 'a']]);
+ *       expect(() => tm.print()).not.toThrow();
    */
   print(): void {
     // Delegate to the underlying tree's visualization.
@@ -341,6 +1182,43 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
 
   /**
    * Smallest entry by key.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Leaderboard with ranked scores
+ *  // Use score as key (descending), player name as value
+ *     const leaderboard = new TreeMap<number, string>([], {
+ *       comparator: (a, b) => b - a // descending
+ *     });
+ *
+ *     leaderboard.set(1500, 'Alice');
+ *     leaderboard.set(2200, 'Bob');
+ *     leaderboard.set(1800, 'Charlie');
+ *     leaderboard.set(2500, 'Diana');
+ *
+ *     // Top 3 players (first 3 in descending order)
+ *     const top3 = [...leaderboard.entries()].slice(0, 3);
+ *     console.log(top3); // [
+ *  //      [2500, 'Diana'],
+ *  //      [2200, 'Bob'],
+ *  //      [1800, 'Charlie']
+ *  //    ];
+ *
+ *     // Highest scorer
+ *     console.log(leaderboard.first()); // [2500, 'Diana'];
+ *
+ *     // Remove lowest scorer
+ *     console.log(leaderboard.pollLast()); // [1500, 'Alice'];
+ *     console.log(leaderboard.size); // 3;
    */
   first(): [K, V | undefined] | undefined {
     const k = this.#core.getLeftMost();
@@ -349,6 +1227,27 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
 
   /**
    * Largest entry by key.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Access the maximum entry
+ *  const scores = new TreeMap<number, string>([
+ *       [85, 'Bob'],
+ *       [92, 'Alice'],
+ *       [78, 'Charlie']
+ *     ]);
+ *
+ *     console.log(scores.last()); // [92, 'Alice'];
+ *     console.log(scores.first()); // [78, 'Charlie'];
    */
   last(): [K, V | undefined] | undefined {
     const k = this.#core.getRightMost();
@@ -357,6 +1256,29 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
 
   /**
    * Remove and return the smallest entry.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Process items from lowest priority
+ *  const tasks = new TreeMap<number, string>([
+ *       [3, 'Low'],
+ *       [1, 'Critical'],
+ *       [2, 'Medium']
+ *     ]);
+ *
+ *     // Process lowest priority first
+ *     console.log(tasks.pollFirst()); // [1, 'Critical'];
+ *     console.log(tasks.pollFirst()); // [2, 'Medium'];
+ *     console.log(tasks.size); // 1;
    */
   pollFirst(): [K, V | undefined] | undefined {
     const entry = this.first();
@@ -367,6 +1289,29 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
 
   /**
    * Remove and return the largest entry.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Remove the maximum entry
+ *  const bids = new TreeMap<number, string>([
+ *       [100, 'Alice'],
+ *       [150, 'Bob'],
+ *       [120, 'Charlie']
+ *     ]);
+ *
+ *     // Remove highest bid
+ *     console.log(bids.pollLast()); // [150, 'Bob'];
+ *     console.log(bids.size); // 2;
+ *     console.log(bids.last()); // [120, 'Charlie'];
    */
   pollLast(): [K, V | undefined] | undefined {
     const entry = this.last();
@@ -377,6 +1322,75 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
 
   /**
    * Smallest entry whose key is >= the given key.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Event scheduler with time-based lookup
+ *  const events = new TreeMap<Date, string>();
+ *
+ *     const meeting = new Date('2024-01-15T10:00:00Z');
+ *     const lunch = new Date('2024-01-15T12:00:00Z');
+ *     const review = new Date('2024-01-15T15:00:00Z');
+ *     const standup = new Date('2024-01-15T09:00:00Z');
+ *
+ *     events.set(meeting, 'Team Meeting');
+ *     events.set(lunch, 'Lunch Break');
+ *     events.set(review, 'Code Review');
+ *     events.set(standup, 'Daily Standup');
+ *
+ *     // Events are sorted chronologically
+ *     console.log([...events.values()]); // [
+ *  //      'Daily Standup',
+ *  //      'Team Meeting',
+ *  //      'Lunch Break',
+ *  //      'Code Review'
+ *  //    ];
+ *
+ *     // Next event after 11:00
+ *     const after11 = new Date('2024-01-15T11:00:00Z');
+ *     console.log(events.ceiling(after11)?.[1]); // 'Lunch Break';
+ *
+ *     // Events between 9:30 and 13:00
+ *     const from = new Date('2024-01-15T09:30:00Z');
+ *     const to = new Date('2024-01-15T13:00:00Z');
+ *     const window = events.rangeSearch([from, to]);
+ *     console.log(window.map(([, v]) => v)); // ['Team Meeting', 'Lunch Break'];
    */
   ceiling(key: K): [K, V | undefined] | undefined {
     this._validateKey(key);
@@ -386,6 +1400,59 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
 
   /**
    * Largest entry whose key is <= the given key.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Find the largest key ≤ target
+ *  const versions = new TreeMap<number, string>([
+ *       [1, 'v1.0'],
+ *       [3, 'v3.0'],
+ *       [5, 'v5.0'],
+ *       [7, 'v7.0']
+ *     ]);
+ *
+ *     // Largest version ≤ 4
+ *     console.log(versions.floor(4)); // [3, 'v3.0'];
+ *     // Largest version ≤ 5 (exact match)
+ *     console.log(versions.floor(5)); // [5, 'v5.0'];
+ *     // No version ≤ 0
+ *     console.log(versions.floor(0)); // undefined;
    */
   floor(key: K): [K, V | undefined] | undefined {
     this._validateKey(key);
@@ -395,6 +1462,59 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
 
   /**
    * Smallest entry whose key is > the given key.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Find the smallest key strictly > target
+ *  const prices = new TreeMap<number, string>([
+ *       [10, 'Basic'],
+ *       [25, 'Standard'],
+ *       [50, 'Premium'],
+ *       [100, 'Enterprise']
+ *     ]);
+ *
+ *     // Next tier above $25
+ *     console.log(prices.higher(25)); // [50, 'Premium'];
+ *     // Next tier above $99
+ *     console.log(prices.higher(99)); // [100, 'Enterprise'];
+ *     // Nothing above $100
+ *     console.log(prices.higher(100)); // undefined;
    */
   higher(key: K): [K, V | undefined] | undefined {
     this._validateKey(key);
@@ -404,6 +1524,57 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
 
   /**
    * Largest entry whose key is < the given key.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Find the largest key strictly < target
+ *  const temps = new TreeMap<number, string>([
+ *       [0, 'Freezing'],
+ *       [20, 'Cool'],
+ *       [30, 'Warm'],
+ *       [40, 'Hot']
+ *     ]);
+ *
+ *     // Largest reading below 30
+ *     console.log(temps.lower(30)); // [20, 'Cool'];
+ *     // Nothing below 0
+ *     console.log(temps.lower(0)); // undefined;
    */
   lower(key: K): [K, V | undefined] | undefined {
     this._validateKey(key);
@@ -416,6 +1587,74 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    *
    * @param range `[low, high]`
    * @param options Inclusive/exclusive bounds (defaults to inclusive).
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Inventory system with price-sorted products
+ *  interface Product {
+ *       name: string;
+ *       price: number;
+ *       stock: number;
+ *     }
+ *
+ *     const inventory = new TreeMap<string, Product, Product>(
+ *       [
+ *         { name: 'Widget', price: 9.99, stock: 100 },
+ *         { name: 'Gadget', price: 24.99, stock: 50 },
+ *         { name: 'Doohickey', price: 4.99, stock: 200 }
+ *       ],
+ *       { toEntryFn: p => [p.name, p] }
+ *     );
+ *
+ *     // Sorted alphabetically by product name
+ *     console.log([...inventory.keys()]); // ['Doohickey', 'Gadget', 'Widget'];
+ *
+ *     // Filter high-stock items
+ *     const highStock = inventory.filter(p => (p?.stock ?? 0) > 75);
+ *     console.log([...highStock.keys()]); // ['Doohickey', 'Widget'];
+ *
+ *     // Calculate total inventory value
+ *     const totalValue = inventory.reduce(
+ *       (sum, p) => sum + (p ? p.price * p.stock : 0),
+ *       0
+ *     );
+ *     console.log(totalValue); // toBeCloseTo;
    */
   rangeSearch(range: [K, K], options: TreeMapRangeOptions = {}): Array<[K, V | undefined]> {
     const { lowInclusive = true, highInclusive = true } = options;
@@ -428,7 +1667,7 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
     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(this._entryFromKey(k));
@@ -440,11 +1679,51 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
   /**
    * Creates a shallow clone of this map.
    * @remarks Time O(n log n), Space O(n)
-   * @example
-   * const original = new TreeMap([['a', 1], ['b', 2]]);
-   * const copy = original.clone();
-   * copy.set('c', 3);
-   * original.has('c'); // false (original unchanged)
+  
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Deep clone
+ *  const tm = new TreeMap<number, string>([[1, 'a'], [2, 'b']]);
+ *       const copy = tm.clone();
+ *       copy.delete(1);
+ *       console.log(tm.has(1)); // true;
    */
   clone(): TreeMap<K, V> {
     return new TreeMap<K, V>(this, {