data-structure-typed 2.5.0 → 2.5.2

package/docs-site-docusaurus/docs/api/classes/TreeMap.md

@@ -0,0 +1,1389 @@
+[**data-structure-typed**](../README.md)
+
+***
+
+[data-structure-typed](../README.md) / TreeMap
+
+# Class: TreeMap\<K, V, R\>
+
+Defined in: [data-structures/binary-tree/tree-map.ts:26](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/binary-tree/tree-map.ts#L26)
+
+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
+
+```ts
+// Set multiple key-value pairs
+ const tm = new TreeMap<number, string>();
+    tm.setMany([[1, 'a'], [2, 'b'], [3, 'c']]);
+    console.log(tm.size); // 3;
+```
+
+## Type Parameters
+
+### K
+
+`K` = `any`
+
+### V
+
+`V` = `any`
+
+### R
+
+`R` = \[`K`, `V`\]
+
+## Implements
+
+- `Iterable`\<\[`K`, `V` \| `undefined`\]\>
+
+## Constructors
+
+### Constructor
+
+```ts
+new TreeMap<K, V, R>(entries?, options?): TreeMap<K, V, R>;
+```
+
+Defined in: [data-structures/binary-tree/tree-map.ts:46](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/binary-tree/tree-map.ts#L46)
+
+Create a TreeMap from an iterable of `[key, value]` entries or raw elements.
+
+#### Parameters
+
+##### entries?
+
+  \| `Iterable`\<\[`K`, `V` \| `undefined`\], `any`, `any`\>
+  \| `Iterable`\<`R`, `any`, `any`\>
+
+Iterable of `[key, value]` tuples, or raw elements if `toEntryFn` is provided.
+
+##### options?
+
+`TreeMapOptions`\<`K`, `V`, `R`\> = `{}`
+
+Configuration options including optional `toEntryFn` to transform raw elements.
+
+#### Returns
+
+`TreeMap`\<`K`, `V`, `R`\>
+
+#### Throws
+
+If any entry is not a 2-tuple-like value (when no toEntryFn), or when using
+the default comparator and encountering unsupported/invalid keys (e.g. `NaN`, invalid `Date`).
+
+#### Example
+
+```ts
+// Standard usage with entries
+const map = new TreeMap([['a', 1], ['b', 2]]);
+
+// Using toEntryFn to transform raw objects
+const users = [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }];
+const map = new TreeMap<number, User, User>(users, { toEntryFn: u => [u.id, u] });
+```
+
+## Accessors
+
+### size
+
+#### Get Signature
+
+```ts
+get size(): number;
+```
+
+Defined in: [data-structures/binary-tree/tree-map.ts:134](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/binary-tree/tree-map.ts#L134)
+
+Number of entries in the map.
+
+##### Returns
+
+`number`
+
+## Methods
+
+### ceiling()
+
+```ts
+ceiling(key): [K, V | undefined] | undefined;
+```
+
+Defined in: [data-structures/binary-tree/tree-map.ts:3747](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/binary-tree/tree-map.ts#L3747)
+
+Smallest entry whose key is >= the given key.
+
+ *
+
+#### Parameters
+
+##### key
+
+`K`
+
+#### Returns
+
+\[`K`, `V` \| `undefined`\] \| `undefined`
+
+#### Example
+
+```ts
+// 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'];
+```
+
+***
+
+### clear()
+
+```ts
+clear(): void;
+```
+
+Defined in: [data-structures/binary-tree/tree-map.ts:1238](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/binary-tree/tree-map.ts#L1238)
+
+Remove all entries.
+
+ *
+
+#### Returns
+
+`void`
+
+#### Example
+
+```ts
+// Remove all
+ const tm = new TreeMap<number, string>([[1, 'a']]);
+      tm.clear();
+      console.log(tm.isEmpty()); // true;
+```
+
+***
+
+### clone()
+
+```ts
+clone(): TreeMap<K, V>;
+```
+
+Defined in: [data-structures/binary-tree/tree-map.ts:4652](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/binary-tree/tree-map.ts#L4652)
+
+Creates a shallow clone of this map.
+
+#### Returns
+
+`TreeMap`\<`K`, `V`\>
+
+#### Remarks
+
+Time O(n log n), Space O(n)
+
+ *
+
+#### Example
+
+```ts
+// 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;
+```
+
+***
+
+### delete()
+
+```ts
+delete(key): boolean;
+```
+
+Defined in: [data-structures/binary-tree/tree-map.ts:1066](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/binary-tree/tree-map.ts#L1066)
+
+Delete a key.
+
+#### Parameters
+
+##### key
+
+`K`
+
+#### Returns
+
+`boolean`
+
+`true` if the key existed; otherwise `false`.
+
+#### Remarks
+
+Expected time O(log n)
+
+ *
+
+#### Example
+
+```ts
+// 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;
+```
+
+***
+
+### entries()
+
+```ts
+entries(): IterableIterator<[K, V | undefined]>;
+```
+
+Defined in: [data-structures/binary-tree/tree-map.ts:1755](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/binary-tree/tree-map.ts#L1755)
+
+Iterate over `[key, value]` entries in ascending key order.
+
+Note: values may be `undefined`.
+
+ *
+
+#### Returns
+
+`IterableIterator`\<\[`K`, `V` \| `undefined`\]\>
+
+#### Example
+
+```ts
+// 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']];
+```
+
+***
+
+### every()
+
+```ts
+every(callbackfn, thisArg?): boolean;
+```
+
+Defined in: [data-structures/binary-tree/tree-map.ts:2637](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/binary-tree/tree-map.ts#L2637)
+
+Test whether all entries satisfy a predicate.
+
+#### Parameters
+
+##### callbackfn
+
+`TreeMapEntryCallback`\<`K`, `V`, `boolean`, `TreeMap`\<`K`, `V`, \[`K`, `V`\]\>\>
+
+##### thisArg?
+
+`unknown`
+
+#### Returns
+
+`boolean`
+
+#### Remarks
+
+Time O(n), Space O(1)
+
+ *
+
+#### Example
+
+```ts
+// Test all entries
+ const tm = new TreeMap<number, string>([[1, 'a'], [2, 'b']]);
+      console.log(tm.every((v, k) => k > 0)); // true;
+```
+
+***
+
+### filter()
+
+```ts
+filter(callbackfn, thisArg?): TreeMap<K, V>;
+```
+
+Defined in: [data-structures/binary-tree/tree-map.ts:2288](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/binary-tree/tree-map.ts#L2288)
+
+Create a new TreeMap containing only entries that satisfy the predicate.
+
+#### Parameters
+
+##### callbackfn
+
+`TreeMapEntryCallback`\<`K`, `V`, `boolean`, `TreeMap`\<`K`, `V`, \[`K`, `V`\]\>\>
+
+##### thisArg?
+
+`unknown`
+
+#### Returns
+
+`TreeMap`\<`K`, `V`\>
+
+#### Remarks
+
+Time O(n log n) expected, Space O(n)
+
+ *
+
+#### Example
+
+```ts
+// 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];
+```
+
+***
+
+### find()
+
+```ts
+find(callbackfn, thisArg?): [K, V | undefined] | undefined;
+```
+
+Defined in: [data-structures/binary-tree/tree-map.ts:2988](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/binary-tree/tree-map.ts#L2988)
+
+Find the first entry that satisfies a predicate.
+
+#### Parameters
+
+##### callbackfn
+
+`TreeMapEntryCallback`\<`K`, `V`, `boolean`, `TreeMap`\<`K`, `V`, \[`K`, `V`\]\>\>
+
+##### thisArg?
+
+`unknown`
+
+#### Returns
+
+\[`K`, `V` \| `undefined`\] \| `undefined`
+
+The first matching `[key, value]` tuple, or `undefined`.
+
+#### Remarks
+
+Time O(n), Space O(1)
+
+ *
+
+#### Example
+
+```ts
+// Find matching entry
+ const tm = new TreeMap<number, string>([[1, 'a'], [2, 'b']]);
+      console.log(tm.find(v => v === 'b')?.[0]); // 2;
+```
+
+***
+
+### first()
+
+```ts
+first(): [K, V | undefined] | undefined;
+```
+
+Defined in: [data-structures/binary-tree/tree-map.ts:3407](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/binary-tree/tree-map.ts#L3407)
+
+Smallest entry by key.
+
+ *
+
+#### Returns
+
+\[`K`, `V` \| `undefined`\] \| `undefined`
+
+#### Example
+
+```ts
+// 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;
+```
+
+***
+
+### floor()
+
+```ts
+floor(key): [K, V | undefined] | undefined;
+```
+
+Defined in: [data-structures/binary-tree/tree-map.ts:3905](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/binary-tree/tree-map.ts#L3905)
+
+Largest entry whose key is <= the given key.
+
+ *
+
+#### Parameters
+
+##### key
+
+`K`
+
+#### Returns
+
+\[`K`, `V` \| `undefined`\] \| `undefined`
+
+#### Example
+
+```ts
+// 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;
+```
+
+***
+
+### forEach()
+
+```ts
+forEach(cb, thisArg?): void;
+```
+
+Defined in: [data-structures/binary-tree/tree-map.ts:1932](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/binary-tree/tree-map.ts#L1932)
+
+Visit each entry in ascending key order.
+
+Note: callback value may be `undefined`.
+
+ *
+
+#### Parameters
+
+##### cb
+
+(`value`, `key`, `map`) => `void`
+
+##### thisArg?
+
+`unknown`
+
+#### Returns
+
+`void`
+
+#### Example
+
+```ts
+// 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'];
+```
+
+***
+
+### get()
+
+```ts
+get(key): V | undefined;
+```
+
+Defined in: [data-structures/binary-tree/tree-map.ts:687](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/binary-tree/tree-map.ts#L687)
+
+Get the value under a key.
+
+#### Parameters
+
+##### key
+
+`K`
+
+#### Returns
+
+`V` \| `undefined`
+
+#### Remarks
+
+Expected time O(log n)
+
+ *
+
+#### Example
+
+```ts
+// 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;
+```
+
+***
+
+### getByRank()
+
+```ts
+getByRank(k): [K, V | undefined] | undefined;
+```
+
+Defined in: [data-structures/binary-tree/tree-map.ts:4433](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/binary-tree/tree-map.ts#L4433)
+
+Returns the entry at the k-th position in tree order (0-indexed).
+
+#### Parameters
+
+##### k
+
+`number`
+
+#### Returns
+
+\[`K`, `V` \| `undefined`\] \| `undefined`
+
+#### Remarks
+
+Time O(log n). Requires `enableOrderStatistic: true`.
+
+ *
+
+#### Example
+
+```ts
+// Find k-th entry in a TreeMap
+ const map = new TreeMap<string, number>(
+        [['alice', 95], ['bob', 87], ['charlie', 92]],
+        { enableOrderStatistic: true }
+      );
+      console.log(map.getByRank(0)); // 'alice';
+      console.log(map.getByRank(1)); // 'bob';
+      console.log(map.getByRank(2)); // 'charlie';
+```
+
+***
+
+### getRank()
+
+```ts
+getRank(key): number;
+```
+
+Defined in: [data-structures/binary-tree/tree-map.ts:4453](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/binary-tree/tree-map.ts#L4453)
+
+Returns the 0-based rank of a key (number of elements that precede it in tree order).
+
+#### Parameters
+
+##### key
+
+`K`
+
+#### Returns
+
+`number`
+
+#### Remarks
+
+Time O(log n). Requires `enableOrderStatistic: true`.
+ *
+
+#### Example
+
+```ts
+// Get the rank of a key in sorted order
+ const tree = new TreeMap<number>(
+        [10, 20, 30, 40, 50],
+        { enableOrderStatistic: true }
+      );
+      console.log(tree.getRank(10)); // 0;  // smallest → rank 0
+      console.log(tree.getRank(30)); // 2;  // 2 elements before 30 in tree order
+      console.log(tree.getRank(50)); // 4;  // largest → rank 4
+      console.log(tree.getRank(25)); // 2;
+```
+
+***
+
+### has()
+
+```ts
+has(key): boolean;
+```
+
+Defined in: [data-structures/binary-tree/tree-map.ts:875](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/binary-tree/tree-map.ts#L875)
+
+Test whether a key exists.
+
+#### Parameters
+
+##### key
+
+`K`
+
+#### Returns
+
+`boolean`
+
+#### Remarks
+
+Expected time O(log n)
+
+ *
+
+#### Example
+
+```ts
+// 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;
+```
+
+***
+
+### higher()
+
+```ts
+higher(key): [K, V | undefined] | undefined;
+```
+
+Defined in: [data-structures/binary-tree/tree-map.ts:4063](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/binary-tree/tree-map.ts#L4063)
+
+Smallest entry whose key is > the given key.
+
+ *
+
+#### Parameters
+
+##### key
+
+`K`
+
+#### Returns
+
+\[`K`, `V` \| `undefined`\] \| `undefined`
+
+#### Example
+
+```ts
+// 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;
+```
+
+***
+
+### isEmpty()
+
+```ts
+isEmpty(): boolean;
+```
+
+Defined in: [data-structures/binary-tree/tree-map.ts:302](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/binary-tree/tree-map.ts#L302)
+
+Whether the map is empty.
+
+ *
+
+#### Returns
+
+`boolean`
+
+#### Example
+
+```ts
+// Check empty
+ console.log(new TreeMap().isEmpty()); // true;
+```
+
+***
+
+### keys()
+
+```ts
+keys(): IterableIterator<K>;
+```
+
+Defined in: [data-structures/binary-tree/tree-map.ts:1407](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/binary-tree/tree-map.ts#L1407)
+
+Iterate over keys in ascending order.
+
+ *
+
+#### Returns
+
+`IterableIterator`\<`K`\>
+
+#### Example
+
+```ts
+// Get sorted keys
+ const tm = new TreeMap<number, string>([[3, 'c'], [1, 'a']]);
+      console.log([...tm.keys()]); // [1, 3];
+```
+
+***
+
+### last()
+
+```ts
+last(): [K, V | undefined] | undefined;
+```
+
+Defined in: [data-structures/binary-tree/tree-map.ts:3460](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/binary-tree/tree-map.ts#L3460)
+
+Largest entry by key.
+
+ *
+
+#### Returns
+
+\[`K`, `V` \| `undefined`\] \| `undefined`
+
+#### Example
+
+```ts
+// 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'];
+```
+
+***
+
+### lower()
+
+```ts
+lower(key): [K, V | undefined] | undefined;
+```
+
+Defined in: [data-structures/binary-tree/tree-map.ts:4219](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/binary-tree/tree-map.ts#L4219)
+
+Largest entry whose key is < the given key.
+
+ *
+
+#### Parameters
+
+##### key
+
+`K`
+
+#### Returns
+
+\[`K`, `V` \| `undefined`\] \| `undefined`
+
+#### Example
+
+```ts
+// 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;
+```
+
+***
+
+### map()
+
+```ts
+map<MK, MV>(
+   callbackfn, 
+   options?, 
+thisArg?): TreeMap<MK, MV>;
+```
+
+Defined in: [data-structures/binary-tree/tree-map.ts:2105](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/binary-tree/tree-map.ts#L2105)
+
+Create a new TreeMap by mapping each entry to a new `[key, value]` entry.
+
+This mirrors `RedBlackTree.map`: mapping produces a new ordered container.
+
+#### Type Parameters
+
+##### MK
+
+`MK`
+
+##### MV
+
+`MV`
+
+#### Parameters
+
+##### callbackfn
+
+`TreeMapEntryCallback`\<`K`, `V`, \[`MK`, `MV`\], `TreeMap`\<`K`, `V`, \[`K`, `V`\]\>\>
+
+##### options?
+
+`Omit`\<`TreeMapOptions`\<`MK`, `MV`, \[`MK`, `MV`\]\>, `"toEntryFn"`\> & `object` = `{}`
+
+##### thisArg?
+
+`unknown`
+
+#### Returns
+
+`TreeMap`\<`MK`, `MV`\>
+
+#### Remarks
+
+Time O(n log n) expected, Space O(n)
+
+ *
+
+#### Example
+
+```ts
+// 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];
+```
+
+***
+
+### pollFirst()
+
+```ts
+pollFirst(): [K, V | undefined] | undefined;
+```
+
+Defined in: [data-structures/binary-tree/tree-map.ts:3515](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/binary-tree/tree-map.ts#L3515)
+
+Remove and return the smallest entry.
+
+ *
+
+#### Returns
+
+\[`K`, `V` \| `undefined`\] \| `undefined`
+
+#### Example
+
+```ts
+// 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;
+```
+
+***
+
+### pollLast()
+
+```ts
+pollLast(): [K, V | undefined] | undefined;
+```
+
+Defined in: [data-structures/binary-tree/tree-map.ts:3572](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/binary-tree/tree-map.ts#L3572)
+
+Remove and return the largest entry.
+
+ *
+
+#### Returns
+
+\[`K`, `V` \| `undefined`\] \| `undefined`
+
+#### Example
+
+```ts
+// 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'];
+```
+
+***
+
+### print()
+
+```ts
+print(): void;
+```
+
+Defined in: [data-structures/binary-tree/tree-map.ts:3335](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/binary-tree/tree-map.ts#L3335)
+
+Print a human-friendly representation.
+
+#### Returns
+
+`void`
+
+#### Remarks
+
+Time O(n), Space O(n)
+
+ *
+
+#### Example
+
+```ts
+// Display tree
+ const tm = new TreeMap<number, string>([[1, 'a']]);
+      expect(() => tm.print()).not.toThrow();
+```
+
+***
+
+### rangeByRank()
+
+```ts
+rangeByRank(start, end): [K, V | undefined][];
+```
+
+Defined in: [data-structures/binary-tree/tree-map.ts:4476](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/binary-tree/tree-map.ts#L4476)
+
+Returns keys by rank range (0-indexed, inclusive on both ends).
+
+#### Parameters
+
+##### start
+
+`number`
+
+##### end
+
+`number`
+
+#### Returns
+
+\[`K`, `V` \| `undefined`\][]
+
+#### Remarks
+
+Time O(log n + k). Requires `enableOrderStatistic: true`.
+
+ *
+
+#### Example
+
+```ts
+// Pagination with rangeByRank
+ const tree = new TreeMap<number>(
+        [10, 20, 30, 40, 50, 60, 70, 80, 90],
+        { enableOrderStatistic: true }
+      );
+      const pageSize = 3;
+
+      // Page 1
+      console.log(tree.rangeByRank(0, pageSize - 1)); // [10, 20, 30];
+      // Page 2
+      console.log(tree.rangeByRank(pageSize, 2 * pageSize - 1)); // [40, 50, 60];
+      // Page 3
+      console.log(tree.rangeByRank(2 * pageSize, 3 * pageSize - 1)); // [70, 80, 90];
+```
+
+***
+
+### rangeSearch()
+
+```ts
+rangeSearch(range, options?): [K, V | undefined][];
+```
+
+Defined in: [data-structures/binary-tree/tree-map.ts:4395](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/binary-tree/tree-map.ts#L4395)
+
+Return all entries in a given key range.
+
+#### Parameters
+
+##### range
+
+\[`K`, `K`\]
+
+`[low, high]`
+
+##### options?
+
+`TreeMapRangeOptions` = `{}`
+
+Inclusive/exclusive bounds (defaults to inclusive).
+
+ *
+
+#### Returns
+
+\[`K`, `V` \| `undefined`\][]
+
+#### Example
+
+```ts
+// 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;
+```
+
+***
+
+### reduce()
+
+```ts
+reduce<A>(callbackfn, initialValue): A;
+```
+
+Defined in: [data-structures/binary-tree/tree-map.ts:2466](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/binary-tree/tree-map.ts#L2466)
+
+Reduce entries into a single accumulator.
+
+#### Type Parameters
+
+##### A
+
+`A`
+
+#### Parameters
+
+##### callbackfn
+
+`TreeMapReduceCallback`\<`K`, `V`, `A`, `TreeMap`\<`K`, `V`, \[`K`, `V`\]\>\>
+
+##### initialValue
+
+`A`
+
+#### Returns
+
+`A`
+
+#### Remarks
+
+Time O(n), Space O(1)
+
+ *
+
+#### Example
+
+```ts
+// Aggregate values
+ const tm = new TreeMap<number, number>([[1, 10], [2, 20]]);
+      console.log(tm.reduce((acc, v) => acc + (v ?? 0), 0)); // 30;
+```
+
+***
+
+### set()
+
+```ts
+set(key, value): this;
+```
+
+Defined in: [data-structures/binary-tree/tree-map.ts:497](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/binary-tree/tree-map.ts#L497)
+
+Set or overwrite a value for a key.
+
+#### Parameters
+
+##### key
+
+`K`
+
+##### value
+
+`V` \| `undefined`
+
+#### Returns
+
+`this`
+
+#### Remarks
+
+Expected time O(log n)
+
+ *
+
+#### Example
+
+```ts
+// 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']
+ //    ];
+```
+
+***
+
+### some()
+
+```ts
+some(callbackfn, thisArg?): boolean;
+```
+
+Defined in: [data-structures/binary-tree/tree-map.ts:2812](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/binary-tree/tree-map.ts#L2812)
+
+Test whether any entry satisfies a predicate.
+
+#### Parameters
+
+##### callbackfn
+
+`TreeMapEntryCallback`\<`K`, `V`, `boolean`, `TreeMap`\<`K`, `V`, \[`K`, `V`\]\>\>
+
+##### thisArg?
+
+`unknown`
+
+#### Returns
+
+`boolean`
+
+#### Remarks
+
+Time O(n), Space O(1)
+
+ *
+
+#### Example
+
+```ts
+// Test any entry
+ const tm = new TreeMap<number, string>([[1, 'a'], [2, 'b']]);
+      console.log(tm.some((v, k) => k === 2)); // true;
+```
+
+***
+
+### toArray()
+
+```ts
+toArray(): [K, V | undefined][];
+```
+
+Defined in: [data-structures/binary-tree/tree-map.ts:3165](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/binary-tree/tree-map.ts#L3165)
+
+Materialize the map into an array of `[key, value]` tuples.
+
+#### Returns
+
+\[`K`, `V` \| `undefined`\][]
+
+#### Remarks
+
+Time O(n), Space O(n)
+
+ *
+
+#### Example
+
+```ts
+// Convert to array
+ const tm = new TreeMap<number, string>([[2, 'b'], [1, 'a']]);
+      console.log(tm.toArray()); // [[1, 'a'], [2, 'b']];
+```
+
+***
+
+### values()
+
+```ts
+values(): IterableIterator<V | undefined>;
+```
+
+Defined in: [data-structures/binary-tree/tree-map.ts:1584](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/binary-tree/tree-map.ts#L1584)
+
+Iterate over values in ascending key order.
+
+Note: values may be `undefined` (TreeMap allows storing `undefined`, like native `Map`).
+
+ *
+
+#### Returns
+
+`IterableIterator`\<`V` \| `undefined`\>
+
+#### Example
+
+```ts
+// Get values in key order
+ const tm = new TreeMap<number, string>([[2, 'b'], [1, 'a']]);
+      console.log([...tm.values()]); // ['a', 'b'];
+```
+
+***
+
+### createDefaultComparator()
+
+```ts
+static createDefaultComparator<K>(): Comparator<K>;
+```
+
+Defined in: [data-structures/binary-tree/tree-map.ts:87](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/binary-tree/tree-map.ts#L87)
+
+Create the strict default comparator.
+
+Supports:
+- `number` (rejects `NaN`; treats `-0` and `0` as equal)
+- `string`
+- `Date` (orders by `getTime()`, rejects invalid dates)
+
+For other key types, a custom comparator must be provided.
+
+#### Type Parameters
+
+##### K
+
+`K`
+
+#### Returns
+
+`Comparator`\<`K`\>