binary-tree-typed 2.5.0 → 2.5.1

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

@@ -175,17 +175,6 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
-    * @example
- * // Check empty
- *  console.log(new TreeMap().isEmpty()); // true;
-   */
-  isEmpty(): boolean {
-    return this.size === 0;
-  }
-
-  /**
-   * Set or overwrite a value for a key.
-   * @remarks Expected time O(log n)
    
    
    
@@ -233,36 +222,15 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
-    * @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);
-    this.#core.set(key, value as V);
-    return this;
-  }
-
-  /**
-   * Get the value under a key.
-   * @remarks Expected time O(log n)
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -313,24 +281,15 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
     * @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;
+ * // Check empty
+ *  console.log(new TreeMap().isEmpty()); // true;
    */
-  get(key: K): V | undefined {
-    this._validateKey(key);
-    return this.#core.get(key);
+  isEmpty(): boolean {
+    return this.size === 0;
   }
 
   /**
-   * Test whether a key exists.
+   * Set or overwrite a value for a key.
    * @remarks Expected time O(log n)
    
    
@@ -381,26 +340,6 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
-    * @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);
-    return this.#core.has(key);
-  }
-
-  /**
-   * Delete a key.
-   * @returns `true` if the key existed; otherwise `false`.
-   * @remarks Expected time O(log n)
    
    
    
@@ -450,27 +389,22 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
-    * @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);
-    const res = this.#core.delete(key);
-    return Array.isArray(res) && res.length > 0 && !!res[0]?.deleted;
-  }
-
-  /**
-   * Remove all entries.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -510,17 +444,37 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
     * @example
- * // Remove all
- *  const tm = new TreeMap<number, string>([[1, 'a']]);
- *       tm.clear();
- *       console.log(tm.isEmpty()); // true;
+ * // 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']
+ *  //    ];
    */
-  clear(): void {
-    this.#core.clear();
+  set(key: K, value: V | undefined): this {
+    this._validateKey(key);
+    this.#core.set(key, value as V);
+    return this;
   }
 
   /**
-   * Iterate over keys in ascending order.
+   * Get the value under a key.
+   * @remarks Expected time O(log n)
+   
+   
    
    
    
@@ -559,25 +513,6 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
-    * @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();
-  }
-
-  private _entryFromKey(k: K): [K, V | undefined] {
-    // Keys come from `keys()` which only yields existing keys.
-    // We allow `undefined` as a stored value (native Map behavior), so entries are typed as `[K, V | undefined]`.
-    return [k, this.#core.get(k)];
-  }
-
-  /**
-   * Iterate over values in ascending key order.
-   *
-   * Note: values may be `undefined` (TreeMap allows storing `undefined`, like native `Map`).
    
    
    
@@ -616,19 +551,6 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
-    * @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];
-  }
-
-  /**
-   * Iterate over `[key, value]` entries in ascending key order.
-   *
-   * Note: values may be `undefined`.
    
    
    
@@ -667,23 +589,6 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
-    * @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);
-  }
-
-  [Symbol.iterator](): IterableIterator<[K, V | undefined]> {
-    return this.entries();
-  }
-
-  /**
-   * Visit each entry in ascending key order.
-   *
-   * Note: callback value may be `undefined`.
    
    
    
@@ -723,21 +628,29 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
     * @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'];
+ * // 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;
    */
-  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);
+  get(key: K): V | undefined {
+    this._validateKey(key);
+    return this.#core.get(key);
   }
 
   /**
-   * Create a new TreeMap by mapping each entry to a new `[key, value]` entry.
-   *
-   * This mirrors `RedBlackTree.map`: mapping produces a new ordered container.
-   * @remarks Time O(n log n) expected, Space O(n)
+   * Test whether a key exists.
+   * @remarks Expected time O(log n)
+   
+   
+   
+   
    
    
    
@@ -776,31 +689,6 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
-    * @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>>,
-    options: Omit<TreeMapOptions<MK, MV>, 'toEntryFn'> & { comparator?: (a: MK, b: MK) => number } = {},
-    thisArg?: unknown
-  ): TreeMap<MK, MV> {
-    const out = new TreeMap<MK, MV>([], options as TreeMapOptions<MK, MV>);
-    let index = 0;
-    for (const [k, v] of this) {
-      const [mk, mv] = thisArg === undefined
-        ? callbackfn(v, k, index++, this)
-        : (callbackfn as (this: unknown, v: V | undefined, k: K, i: number, self: TreeMap<K, V>) => [MK, MV]).call(thisArg, v, k, index++, this);
-      out.set(mk, mv);
-    }
-    return out;
-  }
-
-  /**
-   * Create a new TreeMap containing only entries that satisfy the predicate.
-   * @remarks Time O(n log n) expected, Space O(n)
    
    
    
@@ -839,27 +727,6 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
-    * @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 });
-    let index = 0;
-    for (const [k, v] of this) {
-      const ok = thisArg === undefined
-        ? callbackfn(v, k, index++, this)
-        : (callbackfn as (this: unknown, v: V | undefined, k: K, i: number, self: TreeMap<K, V>) => boolean).call(thisArg, v, k, index++, this);
-      if (ok) out.set(k, v);
-    }
-    return out;
-  }
-
-  /**
-   * Reduce entries into a single accumulator.
-   * @remarks Time O(n), Space O(1)
    
    
    
@@ -898,21 +765,6 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
-    * @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;
-    let index = 0;
-    for (const [k, v] of this) acc = callbackfn(acc, v, k, index++, this);
-    return acc;
-  }
-
-  /**
-   * Test whether all entries satisfy a predicate.
-   * @remarks Time O(n), Space O(1)
    
    
    
@@ -950,24 +802,31 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
     * @example
- * // Test all entries
- *  const tm = new TreeMap<number, string>([[1, 'a'], [2, 'b']]);
- *       console.log(tm.every((v, k) => k > 0)); // true;
+ * // 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;
    */
-  every(callbackfn: TreeMapEntryCallback<K, V, boolean, TreeMap<K, V>>, thisArg?: unknown): boolean {
-    let index = 0;
-    for (const [k, v] of this) {
-      const ok = thisArg === undefined
-        ? callbackfn(v, k, index++, this)
-        : (callbackfn as (this: unknown, v: V | undefined, k: K, i: number, self: TreeMap<K, V>) => boolean).call(thisArg, v, k, index++, this);
-      if (!ok) return false;
-    }
-    return true;
+  has(key: K): boolean {
+    this._validateKey(key);
+    return this.#core.has(key);
   }
 
   /**
-   * Test whether any entry satisfies a predicate.
-   * @remarks Time O(n), Space O(1)
+   * Delete a key.
+   * @returns `true` if the key existed; otherwise `false`.
+   * @remarks Expected time O(log n)
+   
+   
+   
+   
+   
+   
    
    
    
@@ -1004,26 +863,6 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
-    * @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;
-    for (const [k, v] of this) {
-      const ok = thisArg === undefined
-        ? callbackfn(v, k, index++, this)
-        : (callbackfn as (this: unknown, v: V | undefined, k: K, i: number, self: TreeMap<K, V>) => boolean).call(thisArg, v, k, index++, this);
-      if (ok) return true;
-    }
-    return false;
-  }
-
-  /**
-   * Find the first entry that satisfies a predicate.
-   * @returns The first matching `[key, value]` tuple, or `undefined`.
-   * @remarks Time O(n), Space O(1)
    
    
    
@@ -1060,25 +899,6 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
-    * @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;
-    for (const [k, v] of this) {
-      const ok = thisArg === undefined
-        ? callbackfn(v, k, index++, this)
-        : (callbackfn as (this: unknown, v: V | undefined, k: K, i: number, self: TreeMap<K, V>) => boolean).call(thisArg, v, k, index++, this);
-      if (ok) return [k, v];
-    }
-    return undefined;
-  }
-
-  /**
-   * Materialize the map into an array of `[key, value]` tuples.
-   * @remarks Time O(n), Space O(n)
    
    
    
@@ -1117,18 +937,6 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
-    * @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];
-  }
-
-  /**
-   * Print a human-friendly representation.
-   * @remarks Time O(n), Space O(n)
    
    
    
@@ -1168,20 +976,26 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
     * @example
- * // Display tree
- *  const tm = new TreeMap<number, string>([[1, 'a']]);
- *       expect(() => tm.print()).not.toThrow();
+ * // 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;
    */
-  print(): void {
-    // Delegate to the underlying tree's visualization.
-    this.#core.print();
+  delete(key: K): boolean {
+    this._validateKey(key);
+    const res = this.#core.delete(key);
+    return Array.isArray(res) && res.length > 0 && !!res[0]?.deleted;
   }
 
-  // Navigable operations (return entry tuples)
-  // Note: returned tuple values may be `undefined`.
-
   /**
-   * Smallest entry by key.
+   * Remove all entries.
    
    
    
@@ -1193,40 +1007,6 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
-    * @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();
-    return k === undefined ? undefined : this._entryFromKey(k);
-  }
-
-  /**
-   * Largest entry by key.
    
    
    
@@ -1238,24 +1018,6 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
-    * @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();
-    return k === undefined ? undefined : this._entryFromKey(k);
-  }
-
-  /**
-   * Remove and return the smallest entry.
    
    
    
@@ -1267,28 +1029,6 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
-    * @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();
-    if (!entry) return undefined;
-    this.delete(entry[0]);
-    return entry;
-  }
-
-  /**
-   * Remove and return the largest entry.
    
    
    
@@ -1300,28 +1040,6 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
-    * @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();
-    if (!entry) return undefined;
-    this.delete(entry[0]);
-    return entry;
-  }
-
-  /**
-   * Smallest entry whose key is >= the given key.
    
    
    
@@ -1360,11 +1078,2351 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
-    * @example
- * // Event scheduler with time-based lookup
- *  const events = new TreeMap<Date, string>();
- *
- *     const meeting = new Date('2024-01-15T10:00:00Z');
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Remove all
+ *  const tm = new TreeMap<number, string>([[1, 'a']]);
+ *       tm.clear();
+ *       console.log(tm.isEmpty()); // true;
+   */
+  clear(): void {
+    this.#core.clear();
+  }
+
+  /**
+   * 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();
+  }
+
+  private _entryFromKey(k: K): [K, V | undefined] {
+    // Keys come from `keys()` which only yields existing keys.
+    // We allow `undefined` as a stored value (native Map behavior), so entries are typed as `[K, V | undefined]`.
+    return [k, this.#core.get(k)];
+  }
+
+  /**
+   * 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];
+  }
+
+  /**
+   * 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);
+  }
+
+  [Symbol.iterator](): IterableIterator<[K, V | undefined]> {
+    return this.entries();
+  }
+
+  /**
+   * 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?: unknown): void {
+    for (const [k, v] of this) cb.call(thisArg, v, k, this);
+  }
+
+  /**
+   * Create a new TreeMap by mapping each entry to a new `[key, value]` entry.
+   *
+   * 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>>,
+    options: Omit<TreeMapOptions<MK, MV>, 'toEntryFn'> & { comparator?: (a: MK, b: MK) => number } = {},
+    thisArg?: unknown
+  ): TreeMap<MK, MV> {
+    const out = new TreeMap<MK, MV>([], options as TreeMapOptions<MK, MV>);
+    let index = 0;
+    for (const [k, v] of this) {
+      const [mk, mv] = thisArg === undefined
+        ? callbackfn(v, k, index++, this)
+        : (callbackfn as (this: unknown, v: V | undefined, k: K, i: number, self: TreeMap<K, V>) => [MK, MV]).call(thisArg, v, k, index++, this);
+      out.set(mk, mv);
+    }
+    return out;
+  }
+
+  /**
+   * 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 });
+    let index = 0;
+    for (const [k, v] of this) {
+      const ok = thisArg === undefined
+        ? callbackfn(v, k, index++, this)
+        : (callbackfn as (this: unknown, v: V | undefined, k: K, i: number, self: TreeMap<K, V>) => boolean).call(thisArg, v, k, index++, this);
+      if (ok) out.set(k, v);
+    }
+    return out;
+  }
+
+  /**
+   * 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;
+    let index = 0;
+    for (const [k, v] of this) acc = callbackfn(acc, v, k, index++, this);
+    return acc;
+  }
+
+  /**
+   * 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;
+    for (const [k, v] of this) {
+      const ok = thisArg === undefined
+        ? callbackfn(v, k, index++, this)
+        : (callbackfn as (this: unknown, v: V | undefined, k: K, i: number, self: TreeMap<K, V>) => boolean).call(thisArg, v, k, index++, this);
+      if (!ok) return false;
+    }
+    return true;
+  }
+
+  /**
+   * 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;
+    for (const [k, v] of this) {
+      const ok = thisArg === undefined
+        ? callbackfn(v, k, index++, this)
+        : (callbackfn as (this: unknown, v: V | undefined, k: K, i: number, self: TreeMap<K, V>) => boolean).call(thisArg, v, k, index++, this);
+      if (ok) return true;
+    }
+    return false;
+  }
+
+  /**
+   * 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;
+    for (const [k, v] of this) {
+      const ok = thisArg === undefined
+        ? callbackfn(v, k, index++, this)
+        : (callbackfn as (this: unknown, v: V | undefined, k: K, i: number, self: TreeMap<K, V>) => boolean).call(thisArg, v, k, index++, this);
+      if (ok) return [k, v];
+    }
+    return undefined;
+  }
+
+  /**
+   * 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];
+  }
+
+  /**
+   * 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.
+    this.#core.print();
+  }
+
+  // Navigable operations (return entry tuples)
+  // Note: returned tuple values may be `undefined`.
+
+  /**
+   * 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();
+    return k === undefined ? undefined : this._entryFromKey(k);
+  }
+
+  /**
+   * 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();
+    return k === undefined ? undefined : this._entryFromKey(k);
+  }
+
+  /**
+   * 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();
+    if (!entry) return undefined;
+    this.delete(entry[0]);
+    return entry;
+  }
+
+  /**
+   * 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();
+    if (!entry) return undefined;
+    this.delete(entry[0]);
+    return entry;
+  }
+
+  /**
+   * 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');
@@ -1382,24 +3440,324 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
  *  //      'Code Review'
  *  //    ];
  *
- *     // Next event after 11:00
- *     const after11 = new Date('2024-01-15T11:00:00Z');
- *     console.log(events.ceiling(after11)?.[1]); // 'Lunch Break';
+ *     // 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);
+    const k = this.#core.ceiling(key);
+    return k === undefined ? undefined : this._entryFromKey(k);
+  }
+
+  /**
+   * 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);
+    const k = this.#core.floor(key);
+    return k === undefined ? undefined : this._entryFromKey(k);
+  }
+
+  /**
+   * 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']
+ *     ]);
  *
- *     // 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'];
+ *     // 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;
    */
-  ceiling(key: K): [K, V | undefined] | undefined {
+  higher(key: K): [K, V | undefined] | undefined {
     this._validateKey(key);
-    const k = this.#core.ceiling(key);
+    const k = this.#core.higher(key);
     return k === undefined ? undefined : this._entryFromKey(k);
   }
 
   /**
-   * Largest entry whose key is <= the given key.
+   * Largest entry whose key is < the given key.
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -1438,30 +3796,6 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
-    * @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);
-    const k = this.#core.floor(key);
-    return k === undefined ? undefined : this._entryFromKey(k);
-  }
-
-  /**
-   * Smallest entry whose key is > the given key.
    
    
    
@@ -1500,30 +3834,6 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
-    * @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);
-    const k = this.#core.higher(key);
-    return k === undefined ? undefined : this._entryFromKey(k);
-  }
-
-  /**
-   * Largest entry whose key is < the given key.
    
    
    
@@ -1604,6 +3914,90 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -1697,6 +4091,111 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+