data-structure-typed 2.5.1 → 2.5.3

package/docs-site-docusaurus/docs/guide/architecture.md

@@ -1,13 +1,14 @@
 ---
 sidebar_label: "ARCHITECTURE"
-description: "Internal architecture: inheritance hierarchy, iterator protocol, memory layout, and algorithmic guarantees."
+description: "Design philosophy, V8 JIT optimizations, self-balancing strategies, and internal architecture of data-structure-typed."
+title: "Architecture — Design & Implementation Details"
+keywords: ["data structures architecture", "red black tree implementation", "v8 optimization", "typescript library design"]
 ---
-
 # ARCHITECTURE
 
 Understand why this library is designed the way it is, and how it works internally.
 
-**[Back to README](/.md) • [See Performance](/guide/performance.md) • [Real Examples](/guide/guides.md)**
+**[Back to README](/docs/guide/quick-start) • [See Performance](/guide/performance.md) • [Real Examples](/guide/guides.md)**
 
 ---
 
@@ -483,7 +484,7 @@ class TreeStructure<K, V> {
     return this;  // Chain continues!
   }
 
-  reduce(reducer: (acc: any, v: V, k: K) => any, init: any) {
+  reduce<A>(reducer: (acc: A, v: V, k: K) => A, init: A): A {
     // ... reduce logic ...
     return result;  // Terminal operation
   }
@@ -595,6 +596,74 @@ const objectTree = new RedBlackTree<CustomObject>([], {
 
 ---
 
+## Order-Statistic Tree Architecture
+
+### How `enableOrderStatistic` Works
+
+When enabled, every node maintains a `_count` field — the number of nodes in its subtree (including itself).
+
+```
+        8 (count=5)
+       / \
+      3   10 (count=1)
+    (count=3)
+     / \
+    1   6 (count=1)
+  (count=1)
+```
+
+### Count Maintenance
+
+Counts are updated in every mutation path:
+
+- **Insert** (`set`/`add`): `_updateCountAlongPath` increments counts from new node to root
+- **Delete**: `_updateCountAlongPath` decrements counts from deleted position to root
+- **Rotations** (AVL: `_balanceLL/LR/RR/RL`, RBT: `_leftRotate/_rightRotate`): `_updateCount` recalculates after structural changes
+- **Balanced rebuild** (`setMany`, `perfectlyBalance`): counts rebuilt during tree construction
+
+### Rank Operations
+
+All O(log n) by walking down the tree using counts:
+
+- **`getByRank(k)`**: Start at root. If left subtree count > k, go left. If equal, return current. Otherwise subtract and go right.
+- **`getRank(key)`**: Walk to key, accumulating left subtree counts. Returns count of elements preceding key in tree order.
+- **`rangeByRank(start, end)`**: Combine `getByRank` to find boundaries, then in-order collect.
+
+### Opt-in Design
+
+Order-statistic is **opt-in** (`enableOrderStatistic: true`) because:
+- Extra count maintenance on every mutation adds O(log n) overhead
+- Most users don't need rank queries
+- `_snapshotOptions` preserves the flag through `clone()` and `map()`
+
+---
+
+## Error Handling: `raise()`
+
+### Unified Error Strategy
+
+All error throwing goes through `raise(ErrorType, message)` in `src/common/error.ts`:
+
+```typescript
+raise(TypeError, ERR.comparatorRequired('TreeMap'));
+raise(RangeError, ERR.indexOutOfBounds(index, length));
+```
+
+### Why `raise()` Instead of Direct `throw`
+
+1. **Single chokepoint** — all errors flow through one function for consistent behavior
+2. **Error message templates** — `ERR` object provides standardized, reusable messages
+3. **Future extensibility** — can add logging, telemetry, or error transformation without touching call sites
+
+### Error Categories
+
+| Error Type | When | Example |
+|------------|------|---------|
+| `TypeError` | Invalid input type | NaN key, missing comparator, non-function callback |
+| `RangeError` | Out of bounds | Index beyond array length, invalid rank |
+
+---
+
 ## Summary: Design Checklist
 
 - ✅ Unified API across all structures
@@ -604,7 +673,8 @@ const objectTree = new RedBlackTree<CustomObject>([], {
 - ✅ V8 JIT-friendly code
 - ✅ Memory-efficient algorithms
 - ✅ Full TypeScript support
-- ✅ Production-ready error handling
+- ✅ Order-statistic tree with opt-in `enableOrderStatistic`
+- ✅ Unified error handling via `raise()` + `ERR` templates
 
 ---
 

package/docs-site-docusaurus/docs/guide/concepts.md

@@ -1,13 +1,14 @@
 ---
 sidebar_label: "CONCEPTS"
-description: "Core concepts behind data-structure-typed: uniform API, iterators, generics, comparators, and the 5 design traits."
+description: "Core fundamentals and theory behind data-structure-typed. BST, balanced trees, heap, iterator protocol, and decision guide."
+title: "Concepts — Core Fundamentals & Theory"
+keywords: ["data structures concepts", "binary search tree", "balanced tree", "heap theory", "typescript data structures"]
 ---
-
 # CONCEPTS
 
 This guide explains the foundational concepts behind data structures through plain language and practical understanding.
 
-**👈 [Back to README](/.md) • [API Docs](https://data-structure-typed-docs.vercel.app/) • [Real-World Guides](/guide/guides.md)**
+**👈 [Back to README](/docs/guide/quick-start) • [API Docs](https://data-structure-typed-docs.vercel.app/) • [Real-World Guides](/guide/guides.md)**
 
 ---
 
@@ -350,6 +351,49 @@ const matches = trie.getWords('appl');
 // O(5 + 4) = 9 operations ✅
 ```
 
+### Case 6: Finding the K-th Element or Rank
+
+❌ Array requires sorting O(n log n):
+
+```javascript
+const scores = [85, 92, 78, 95, 88, 73, 99];
+scores.sort((a, b) => b - a);
+const thirdPlace = scores[2];  // Must re-sort after every insert
+```
+
+✅ Order-Statistic Tree gives O(log n) rank queries:
+
+```javascript
+const tree = new RedBlackTree(scores.map(s => [s, null]), {
+  comparator: (a, b) => b - a,
+  enableOrderStatistic: true
+});
+tree.getByRank(2);     // 3rd place — O(log n)
+tree.getRank(92);      // How many scores are higher? — O(log n)
+tree.rangeByRank(0, 2); // Top 3 scores — O(log n + k)
+// Insert new score — O(log n), no re-sorting needed
+tree.set(91, null);
+```
+
+### Case 7: Pass Raw Objects Without Pre-Processing
+
+❌ Array.map just to reshape data:
+
+```javascript
+const users = [{ id: 3, name: 'Charlie' }, { id: 1, name: 'Alice' }];
+const entries = users.map(u => [u.id, u]);  // Extra step
+const map = new Map(entries);
+```
+
+✅ Pass raw objects directly with `toEntryFn`:
+
+```javascript
+const map = new TreeMap(users, {
+  toEntryFn: u => [u.id, u]
+});
+// No .map() needed — sorted by id automatically
+```
+
 ---
 
 ## 🎯 Decision Guide: Choose the Right Data Structure
@@ -386,6 +430,12 @@ Need range queries on an indexed sequence?
     Only need prefix sums? → BinaryIndexedTree (simpler, less memory)
   No  → Continue
 
+Need k-th element or rank queries?
+  ↓
+  Yes → RedBlackTree / TreeMap / TreeSet with { enableOrderStatistic: true }
+    getByRank(k), getRank(key), rangeByRank(start, end) — all O(log n)
+  No  → Continue
+
 Need a sorted key-value map?
   ↓
   Yes → TreeMap (guaranteed O(log n) via Red-Black Tree)

package/docs-site-docusaurus/docs/guide/faq.md

@@ -0,0 +1,233 @@
+---
+sidebar_label: "FAQ"
+sidebar_position: 7
+description: "Frequently asked questions about data-structure-typed."
+title: "FAQ — Frequently Asked Questions"
+keywords: ["data-structure-typed faq", "typescript data structures questions"]
+---
+# FAQ
+
+---
+title: FAQ — Frequently Asked Questions
+sidebar_label: "FAQ"description: Common questions about data-structure-typed — TreeMap in JavaScript, priority queues, rank queries, bundle size, and more.
+keywords: [typescript data structures, treemap javascript, priority queue typescript, sorted set javascript, rank query, faq]
+sidebar_position: 7
+---
+
+# FAQ
+
+## Does JavaScript have a TreeMap or TreeSet?
+
+Not natively. JavaScript's `Map` and `Set` are hash-based and unordered. This library provides `TreeMap` and `TreeSet` backed by Red-Black Trees — offering sorted iteration, `floor`/`ceiling`/`higher`/`lower` lookups, and `getRank`/`getByRank`/`rangeByRank` queries.
+
+```typescript
+import { TreeMap } from 'data-structure-typed';
+
+const map = new TreeMap<number, string>();
+map.set(3, 'c');
+map.set(1, 'a');
+map.set(2, 'b');
+
+// Sorted iteration (by key)
+for (const [key, value] of map) {
+  console.log(key, value); // 1 'a', 2 'b', 3 'c'
+}
+
+// NavigableMap operations
+map.floor(2.5);   // [2, 'b'] — largest key ≤ 2.5
+map.ceiling(1.5); // [2, 'b'] — smallest key ≥ 1.5
+```
+
+## When should I use a Heap instead of sorting an array?
+
+When you need to repeatedly access the smallest or largest element. Sorting an array is O(n log n) every time you add an element. A Heap gives you O(log n) insert and O(1) access to the top element.
+
+**Use Heap when:**
+- Building a priority queue or task scheduler
+- Finding top-k elements from a stream
+- Implementing Dijkstra's algorithm
+- Any scenario where you repeatedly need the min/max
+
+```typescript
+import { MinHeap } from 'data-structure-typed';
+
+const tasks = new MinHeap<number>([5, 1, 3, 7, 2]);
+tasks.poll(); // 1 (O(log n), not O(n log n))
+tasks.add(0);
+tasks.peek(); // 0
+```
+
+## Does this library support rank and range queries?
+
+Yes. Enable with `{ enableOrderStatistic: true }` on any tree-based structure:
+
+```typescript
+import { RedBlackTree } from 'data-structure-typed';
+
+const tree = new RedBlackTree<number>([10, 20, 30, 40, 50], {
+  enableOrderStatistic: true
+});
+
+tree.getRank(30);          // 2 — two elements precede 30 in tree order
+tree.getByRank(0);         // 10 — first element in tree order
+tree.rangeByRank(1, 3);    // [20, 30, 40] — positions 1 through 3
+```
+
+Works with `TreeMap`, `TreeSet`, `TreeMultiMap`, and `TreeMultiSet` too.
+
+## Is it faster than native arrays for ordered operations?
+
+For ordered insert + lookup: **yes, significantly**.
+
+| Operation | Sorted Array | Red-Black Tree |
+|-----------|-------------|----------------|
+| Insert (maintain order) | O(n) | O(log n) |
+| Find by key | O(log n) | O(log n) |
+| Find min/max | O(1) | O(log n) |
+| Delete by key | O(n) | O(log n) |
+| Get kth element | O(1) | O(log n) |
+
+For 10,000+ elements, the O(n) insert cost of arrays becomes a bottleneck. Trees maintain O(log n) regardless of size.
+
+See [PERFORMANCE.md](https://github.com/zrwusa/data-structure-typed/blob/main/docs/PERFORMANCE.md) for benchmark results.
+
+## Can I use this in React / Node.js / browser?
+
+Yes. The library ships ESM, CJS, and UMD builds. It works in:
+
+- **Node.js** (any version supporting ES2015+)
+- **Browsers** (via bundler or UMD script tag)
+- **React / Next.js / Vue / Angular** (import normally)
+- **Deno / Bun** (ESM compatible)
+
+Zero dependencies means no compatibility concerns.
+
+## What data structures are included?
+
+| Category | Structures |
+|----------|-----------|
+| Trees | RedBlackTree, AVLTree, BST, TreeMap, TreeSet, TreeMultiMap, TreeMultiSet |
+| Heaps | Heap, MinHeap, MaxHeap, MinPriorityQueue, MaxPriorityQueue |
+| Queues | Queue, Deque |
+| Lists | SinglyLinkedList, DoublyLinkedList, SkipList |
+| Hashing | HashMap |
+| Graphs | DirectedGraph, UndirectedGraph |
+| Strings | Trie |
+| Arrays | SegmentTree, BinaryIndexedTree (Fenwick Tree), Matrix |
+| Basic | Stack |
+
+## Is this library production-ready?
+
+Yes.
+
+- **2600+ tests**, 99%+ code coverage
+- **Zero dependencies**
+- **Type-safe** — full TypeScript generics
+- **Actively maintained** — regular releases
+- Every release passes typecheck, lint, and full test suite via CI
+
+## How does this compare to js-sdsl?
+
+| Feature | data-structure-typed | js-sdsl |
+|---------|---------------------|---------|
+| Data structures | 20+ | ~6 |
+| API style | Unified Array-like | Mixed |
+| Order-statistic (getRank/getByRank) | ✅ | ❌ |
+| Tree-shaking subpaths | ✅ | ❌ |
+| Maintenance | Active (2026) | Inactive |
+| Bundle (full) | ~143KB min | ~45KB min |
+
+`data-structure-typed` is broader and more actively maintained. js-sdsl is smaller if you only need a few structures.
+
+## What is the bundle size?
+
+| Import | Size (ESM) |
+|--------|-----------|
+| Full bundle | 598KB |
+| `data-structure-typed/binary-tree` | 315KB |
+| `data-structure-typed/graph` | 127KB |
+| `data-structure-typed/linked-list` | 93KB |
+| `data-structure-typed/queue` | 91KB |
+| `data-structure-typed/heap` | 36KB |
+| `data-structure-typed/priority-queue` | 30KB |
+| `data-structure-typed/hash` | 29KB |
+| `data-structure-typed/matrix` | 28KB |
+| `data-structure-typed/trie` | 27KB |
+| `data-structure-typed/stack` | 18KB |
+
+UMD bundle: ~143KB minified. `sideEffects: false` enables full tree-shaking with modern bundlers.
+
+## Can I pass raw data without converting it first?
+
+Yes. Three patterns depending on what you want to store:
+
+```typescript
+interface User {
+  id: number;
+  name: string;
+}
+
+const users: User[] = [
+  { id: 3, name: 'Charlie' },
+  { id: 1, name: 'Alice' },
+  { id: 2, name: 'Bob' }
+];
+
+// 1. Extract a field — only that field is stored
+const ids = new TreeSet<number, User>(
+  users,
+  { toElementFn: u => u.id }
+);
+// [1, 2, 3]
+
+// 2. Store full objects — sort by a field (raw data preserved!)
+const fullSet = new TreeSet<User>(
+  users,
+  { comparator: (a, b) => a.id - b.id }
+);
+// [{ id: 1, name: 'Alice' }, { id: 2, ... }, { id: 3, ... }]
+
+// 3. Split into key-value — key for lookup, full object as value
+const map = new TreeMap<number, User, User>(
+  users,
+  { toEntryFn: u => [u.id, u] }
+);
+// map.get(1) → { id: 1, name: 'Alice' }
+```
+
+| I want to... | Use |
+|---|---|
+| Store only IDs/scores/prices | `toElementFn` |
+| Store full objects, sorted by a field | `comparator` |
+| Look up full objects by a key | `toEntryFn` |
+
+## How do I build a leaderboard with this library?
+
+```typescript
+import { TreeMap } from 'data-structure-typed';
+
+const leaderboard = new TreeMap<number, string>(
+  [[100, 'Alice'], [250, 'Bob'], [180, 'Charlie']],
+  { comparator: (a, b) => b - a, enableOrderStatistic: true }
+);
+
+// Top 3 players (descending score order)
+leaderboard.rangeByRank(0, 2);
+// → [[250, 'Bob'], [180, 'Charlie'], [100, 'Alice']]
+
+// What rank is score 180?
+leaderboard.getRank(180); // 1 (0-indexed, second position)
+```
+
+## How do I build autocomplete with a Trie?
+
+```typescript
+import { Trie } from 'data-structure-typed';
+
+const trie = new Trie(['apple', 'app', 'application', 'banana', 'band']);
+
+trie.getWords('app');  // ['app', 'apple', 'application']
+trie.getWords('ban');  // ['banana', 'band']
+trie.hasPrefix('app'); // true
+trie.has('apple');     // true
+```

package/docs-site-docusaurus/docs/guide/guides.md

@@ -1,13 +1,14 @@
 ---
 sidebar_label: "GUIDES"
-description: "Real-world examples: leaderboards with RedBlackTree, task scheduling with PriorityQueue, autocomplete with Trie, and more."
+description: "Real-world examples and production patterns for data-structure-typed."
+title: "Guides — Real-World Examples & Production Patterns"
+keywords: ["data-structure-typed examples", "typescript data structures patterns", "production code examples"]
 ---
-
 # GUIDES
 
 Production-ready code examples for common use cases. Learn by doing.
 
-**[Back to README](/.md) • [API Docs](https://data-structure-typed-docs.vercel.app/) • [See INTEGRATIONS](/guide/integrations.md)**
+**[Back to README](/docs/guide/quick-start) • [API Docs](https://data-structure-typed-docs.vercel.app/) • [See INTEGRATIONS](/guide/integrations.md)**
 
 ---
 
@@ -146,7 +147,7 @@ If you insert keys in sorted or nearly-sorted order (timestamps, auto-increment
 import { RedBlackTree } from 'data-structure-typed';
 import type { RedBlackTreeNode } from 'data-structure-typed';
 
-const tree = new RedBlackTree<number, number>([], { isMapMode: true });
+const tree = new RedBlackTree<number, number>();
 
 let hint: RedBlackTreeNode<number, number> | undefined;
 for (let i = 0; i < 1_000_000; i++) {
@@ -170,7 +171,7 @@ Notes:
 import { DoublyLinkedList } from 'data-structure-typed';
 
 class LRUCache<K, V> {
-  private cache = new Map<K, { value: V; node: any }>();
+  private cache = new Map<K, { value: V; node: DoublyLinkedList<K> }>();
   private order = new DoublyLinkedList<K>();
   private readonly capacity: number;
 
@@ -222,7 +223,7 @@ cache.set('d', 'value4');    // Evicts 'b' (least recent)
 
 ```typescript
 import { RedBlackTree } from 'data-structure-typed';
-// TODO
+
 interface Player {
   id: string;
   name: string;
@@ -230,76 +231,58 @@ interface Player {
 }
 
 class Leaderboard {
+  // enableOrderStatistic gives O(log n) getByRank/getRank/rangeByRank
   private scores = new RedBlackTree<number, Player>(
-    (a, b) => b - a  // Descending order
+    [],
+    { comparator: (a, b) => b - a, enableOrderStatistic: true }
   );
   private players = new Map<string, number>(); // playerId → currentScore
 
   updateScore(player: Player): void {
-    // Remove old score if exists
     if (this.players.has(player.id)) {
-      const oldScore = this.players.get(player.id)!;
-      this.scores.delete(oldScore);
+      this.scores.delete(this.players.get(player.id)!);
     }
-
-    // Add new score
     this.scores.set(player.score, player);
     this.players.set(player.id, player.score);
   }
 
-  // O(k log n) — walk from highest score, no array copy
+  // O(k) — select by rank, no array copy
   getTopN(n: number): Player[] {
-    const result: Player[] = [];
-    let key = this.scores.getLeftMost(); // highest in desc tree
-    while (key !== undefined && result.length < n) {
-      const player = this.scores.get(key);
-      if (player) result.push(player);
-      key = this.scores.higher(key);     // next in tree order
-    }
-    return result;
+    return this.scores.rangeByRank(0, n - 1)
+      .map(key => key !== undefined ? this.scores.get(key) : undefined)
+      .filter((p): p is Player => p !== undefined);
   }
 
-  // O(log n + k) — count entries above the target score
+  // O(log n) — direct rank lookup
   getRank(playerId: string): number {
     if (!this.players.has(playerId)) return -1;
-    const score = this.players.get(playerId)!;
-    let rank = 1;
-    let key = this.scores.getLeftMost();
-    while (key !== undefined && key > score) {
-      rank++;
-      key = this.scores.higher(key);
-    }
-    return rank;
+    return this.scores.getRank(this.players.get(playerId)!) + 1; // 1-based
+  }
+
+  // O(log n) — get k-th player by rank
+  getPlayerAt(rank: number): Player | undefined {
+    const key = this.scores.getByRank(rank - 1); // 0-indexed internally
+    return key !== undefined ? this.scores.get(key) : undefined;
   }
 
-  // O(log n + k) — navigate to target player, then walk ±range
+  // O(log n + k) — players around a given player
   getAroundMe(playerId: string, range: number): Player[] {
     if (!this.players.has(playerId)) return [];
-    const myScore = this.players.get(playerId)!;
-    const result: Player[] = [];
-
-    // Collect `range` players above me
-    const above: Player[] = [];
-    let key = this.scores.lower(myScore);
-    for (let i = 0; i < range && key !== undefined; i++) {
-      const p = this.scores.get(key);
-      if (p) above.unshift(p);
-      key = this.scores.lower(key);
-    }
-
-    // Me + `range` players below me
-    result.push(...above);
-    const me = this.scores.get(myScore);
-    if (me) result.push(me);
-
-    key = this.scores.higher(myScore);
-    for (let i = 0; i < range && key !== undefined; i++) {
-      const p = this.scores.get(key);
-      if (p) result.push(p);
-      key = this.scores.higher(key);
-    }
+    const myRank = this.scores.getRank(this.players.get(playerId)!);
+    const start = Math.max(0, myRank - range);
+    const end = Math.min(this.scores.size - 1, myRank + range);
+    return this.scores.rangeByRank(start, end)
+      .map(key => key !== undefined ? this.scores.get(key) : undefined)
+      .filter((p): p is Player => p !== undefined);
+  }
 
-    return result;
+  // Pagination: show page N of the leaderboard
+  getPage(page: number, pageSize: number): Player[] {
+    const start = (page - 1) * pageSize;
+    const end = start + pageSize - 1;
+    return this.scores.rangeByRank(start, end)
+      .map(key => key !== undefined ? this.scores.get(key) : undefined)
+      .filter((p): p is Player => p !== undefined);
   }
 }
 
@@ -309,9 +292,11 @@ lb.updateScore({ id: '1', name: 'Alice', score: 1000 });
 lb.updateScore({ id: '2', name: 'Bob', score: 900 });
 lb.updateScore({ id: '3', name: 'Charlie', score: 950 });
 
-console.log(lb.getTopN(2));        // Top 2 players
-console.log(lb.getRank('2'));      // Bob's rank
-console.log(lb.getAroundMe('2', 1)); // Players around Bob
+console.log(lb.getTopN(2));          // Alice, Charlie
+console.log(lb.getRank('2'));        // 3 (Bob is 3rd)
+console.log(lb.getPlayerAt(1));      // Alice (1st place)
+console.log(lb.getAroundMe('3', 1)); // [Alice, Charlie, Bob]
+console.log(lb.getPage(1, 2));       // [Alice, Charlie] (page 1, 2 per page)
 ```
 
 ### Example 3: Message Queue with Priorities

package/docs-site-docusaurus/docs/guide/installation.md

@@ -1,5 +1,7 @@
 ---
 description: "Install data-structure-typed via npm, yarn, or pnpm. Supports tree-shaking with subpath imports for minimal bundle size."
+title: "Installation — npm, yarn, pnpm"
+sidebar_label: "INSTALLATION"keywords: [data-structure-typed install, npm data structures, typescript library install, tree shaking, subpath imports]
 ---
 
 # Installation