data-structure-typed 2.5.1 → 2.5.2

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

@@ -1,6 +1,8 @@
 ---
 sidebar_label: "ARCHITECTURE"
 description: "Internal architecture: inheritance hierarchy, iterator protocol, memory layout, and algorithmic guarantees."
+title: "Architecture — Inheritance, Iterators, Memory Layout"
+keywords: [data structure library architecture, typescript inheritance, iterator protocol, memory layout, algorithmic guarantees]
 ---
 
 # ARCHITECTURE

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

@@ -1,7 +1,9 @@
 ---
+keywords: [typescript data structures concepts, comparator, iterator protocol, generics, uniform API]
 sidebar_label: "CONCEPTS"
 description: "Core concepts behind data-structure-typed: uniform API, iterators, generics, comparators, and the 5 design traits."
 ---
+keywords: [typescript data structures concepts, comparator, iterator protocol, generics, uniform API]
 
 # CONCEPTS
 
@@ -10,6 +12,7 @@ This guide explains the foundational concepts behind data structures through pla
 **👈 [Back to README](/.md) • [API Docs](https://data-structure-typed-docs.vercel.app/) • [Real-World Guides](/guide/guides.md)**
 
 ---
+keywords: [typescript data structures concepts, comparator, iterator protocol, generics, uniform API]
 
 ## Table of Contents
 
@@ -22,6 +25,7 @@ This guide explains the foundational concepts behind data structures through pla
 7. [Decision Guide](#-decision-guide-choose-the-right-data-structure)
 
 ---
+keywords: [typescript data structures concepts, comparator, iterator protocol, generics, uniform API]
 
 ## The Big Three Concepts
 
@@ -78,6 +82,7 @@ A complete binary tree where parent always has priority over children.
 **Perfect for**: Priority queues, heap sort
 
 ---
+keywords: [typescript data structures concepts, comparator, iterator protocol, generics, uniform API]
 
 ## 🌍 Plain Language Explanations
 
@@ -103,6 +108,7 @@ For those who love understanding concepts through metaphors:
 | **Matrix**             | A 2D grid of numbers supporting standard linear algebra operations.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | 2D grid transformations, linear algebra                                        |
 
 ---
+keywords: [typescript data structures concepts, comparator, iterator protocol, generics, uniform API]
 
 ## Iterator Protocol Design
 
@@ -164,6 +170,7 @@ for (const item of heap) console.log(item);
 ```
 
 ---
+keywords: [typescript data structures concepts, comparator, iterator protocol, generics, uniform API]
 
 ## 🔗 Seamless Interoperability: Iterator Protocol Everywhere
 
@@ -179,6 +186,7 @@ Instead of forcing conversions between data structures, we made every structure
 This is **zero friction** because you use the same mental model.
 
 ---
+keywords: [typescript data structures concepts, comparator, iterator protocol, generics, uniform API]
 
 ## 🎁 All Array Methods Work Everywhere
 
@@ -250,6 +258,7 @@ const stats = {
 | forEach     | ✅           | ✅    | ✅     | ✅     | ✅          |
 
 ---
+keywords: [typescript data structures concepts, comparator, iterator protocol, generics, uniform API]
 
 ## Why Not Just Use Native JavaScript?
 
@@ -332,7 +341,26 @@ const tree = new RedBlackTree(prices);
 const inRange = tree.rangeSearch([30, 70]);
 ```
 
-### Case 5: Prefix Matching is Tedious
+### Case 5: Finding the K-th Element Requires Sorting
+
+❌ Array: sort + index is O(n log n):
+
+```javascript
+const scores = [85, 92, 78, 95, 88, 100, 73];
+scores.sort((a, b) => a - b);
+const median = scores[Math.floor(scores.length / 2)]; // re-sort on every update
+```
+
+✅ Order-statistic tree: O(log n) getByRank/getRank with live updates:
+
+```javascript
+const tree = new RedBlackTree(scores, { enableOrderStatistic: true });
+const median = tree.getByRank(Math.floor(tree.size / 2)); // O(log n)
+const rank = tree.getRank(92); // "how many scores below 92?" — O(log n)
+const top3 = tree.rangeByRank(tree.size - 3, tree.size - 1); // O(log n + 3)
+```
+
+### Case 6: Prefix Matching is Tedious
 
 ❌ Array.filter is O(n*m):
 
@@ -351,6 +379,7 @@ const matches = trie.getWords('appl');
 ```
 
 ---
+keywords: [typescript data structures concepts, comparator, iterator protocol, generics, uniform API]
 
 ## 🎯 Decision Guide: Choose the Right Data Structure
 
@@ -394,6 +423,7 @@ Need a sorted key-value map?
 ```
 
 ---
+keywords: [typescript data structures concepts, comparator, iterator protocol, generics, uniform API]
 
 ## Next Steps
 
@@ -410,6 +440,7 @@ Need a sorted key-value map?
 → [See architecture details](/guide/architecture.md)
 
 ---
+keywords: [typescript data structures concepts, comparator, iterator protocol, generics, uniform API]
 
 **Related:**
 

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

@@ -0,0 +1,180 @@
+---
+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.
+
+## 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,6 +1,8 @@
 ---
 sidebar_label: "GUIDES"
 description: "Real-world examples: leaderboards with RedBlackTree, task scheduling with PriorityQueue, autocomplete with Trie, and more."
+title: "Guides — Leaderboards, Scheduling, Autocomplete"
+keywords: [typescript leaderboard, task scheduler priority queue, autocomplete trie, rank query, range query, real world examples]
 ---
 
 # GUIDES
@@ -218,11 +220,11 @@ console.log(cache.get('a')); // 'value1', 'a' is now most recent
 cache.set('d', 'value4');    // Evicts 'b' (least recent)
 ```
 
-### Example 2: Real-Time Leaderboard
+### Example 2: Real-Time Leaderboard (Order-Statistic Tree)
 
 ```typescript
 import { RedBlackTree } from 'data-structure-typed';
-// TODO
+
 interface Player {
   id: string;
   name: string;
@@ -230,76 +232,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 + k) — 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 +293,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

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

@@ -1,6 +1,8 @@
 ---
 sidebar_label: "INTEGRATIONS"
 description: "Integrate data-structure-typed with React, Express, NestJS, and other frameworks. Production-ready patterns."
+title: "Framework Integrations — React, Express, NestJS"
+keywords: [data-structure-typed react, typescript data structures express, nestjs data structures, production patterns]
 ---
 
 # INTEGRATIONS

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

@@ -1,6 +1,8 @@
 ---
 sidebar_label: "OVERVIEW"
 description: "Complete overview of all 20+ data structures: trees, heaps, graphs, queues, linked lists, hash maps, and more."
+title: "Data Structures Overview — Trees, Heaps, Graphs, Queues"
+keywords: [typescript data structures overview, red black tree, heap, priority queue, trie, graph, deque, treemap, treeset]
 ---
 
 # OVERVIEW
@@ -147,6 +149,11 @@ rbTree.print()
 //  /   \
 //  1    4
 
+// Order-Statistic mode — O(log n) rank queries
+const ost = new RedBlackTree<number, string>([[1, 'A'], [2, 'B'], [3, 'C']], { enableOrderStatistic: true });
+ost.getByRank(0);         // 1 (smallest key)
+ost.getRank(2);           // 1 (one element before key 2)
+ost.rangeByRank(0, 1); // [1, 2] (first two elements)
 ```
 
 #### AVL Tree

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

@@ -1,6 +1,8 @@
 ---
 sidebar_label: "PERFORMANCE"
 description: "Benchmarks comparing data-structure-typed vs native Arrays, Maps, and C++ implementations. Includes methodology."
+title: "Performance Benchmarks"
+keywords: [typescript data structures performance, red black tree benchmark, heap benchmark, priority queue performance, javascript vs cpp]
 ---
 
 # PERFORMANCE

package/docs-site-docusaurus/docs/guide/quick-start.md

@@ -1,5 +1,7 @@
 ---
 description: "Get started with data-structure-typed in 30 seconds. Create trees, queues, and maps with a familiar JavaScript API."
+title: "Quick Start — Get Running in 30 Seconds"
+sidebar_label: "QUICK START"keywords: [data-structure-typed tutorial, typescript data structures getting started, treemap example, heap example]
 ---
 
 # Quick Start
@@ -32,6 +34,35 @@ leaderboard.set(95, 'Bob');
 const scores90to100 = leaderboard.rangeSearch([90, 100]);
 ```
 
+## Order-Statistic Tree (Rank Queries)
+
+```typescript
+import { RedBlackTree } from 'data-structure-typed';
+
+// Enable order-statistic for O(log n) rank operations
+const tree = new RedBlackTree<number, string>([
+  [100, 'Alice'],
+  [85, 'Bob'],
+  [92, 'Charlie'],
+  [78, 'Diana'],
+  [95, 'Eve']
+], { comparator: (a, b) => b - a, enableOrderStatistic: true });
+
+// select(k) — find k-th element (0-indexed)
+console.log(tree.getByRank(0));  // 100 (1st in tree order)
+console.log(tree.getByRank(2));  // 92  (3rd in tree order)
+
+// rank(key) — how many elements before this key?
+console.log(tree.getRank(92));   // 2 (2 elements before 92 in tree order)
+
+// rangeByRank(start, end) — pagination
+console.log(tree.rangeByRank(0, 2)); // [100, 95, 92] — top 3
+
+// Inverse property: getByRank(getRank(key)) === key
+const k = tree.getRank(85);
+console.log(tree.getByRank(k));  // 85
+```
+
 ## Task Queue (Scheduling)
 
 ```typescript

package/docs-site-docusaurus/docs/guide/use-cases/_category_.json

@@ -0,0 +1,6 @@
+{
+  "label": "Use Cases",
+  "position": 8,
+  "collapsible": true,
+  "collapsed": false
+}