data-structure-typed 2.5.0 → 2.5.2

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

@@ -0,0 +1,104 @@
+---
+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
+
+## Leaderboard (Ranked Collections)
+
+```typescript
+import { RedBlackTree } from 'data-structure-typed';
+
+// Descending comparator — highest scores first
+const leaderboard = new RedBlackTree<number, string>([
+  [100, 'Alice'],
+  [85, 'Bob'],
+  [92, 'Charlie']
+], { comparator: (a, b) => b - a });
+
+// Top-2 via lazy iterator — O(2 log n), no full traversal
+const iter = leaderboard.entries();
+for (let i = 0; i < 2; i++) {
+  const { value: [score, player] } = iter.next();
+  console.log(`${score}: ${player}`);
+}
+// Output: 100: Alice → 92: Charlie
+
+// Update score — O(log n)
+leaderboard.delete(85);
+leaderboard.set(95, 'Bob');
+
+// Range query — players scoring 90~100, O(log n + k)
+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
+import { MinPriorityQueue } from 'data-structure-typed';
+
+const tasks = new MinPriorityQueue<{ task: string; priority: number }>(
+  [], { comparator: (a, b) => a.priority - b.priority }
+);
+
+tasks.add({ task: 'Send email', priority: 3 });
+tasks.add({ task: 'Fix critical bug', priority: 1 });
+tasks.add({ task: 'Update docs', priority: 2 });
+
+// Process in priority order
+while (!tasks.isEmpty()) {
+  const next = tasks.poll();
+  console.log(next?.task);
+}
+// Fix critical bug → Update docs → Send email
+```
+
+## Fast Autocomplete (Trie)
+
+```typescript
+import { Trie } from 'data-structure-typed';
+
+const trie = new Trie();
+trie.addMany(['apple', 'application', 'app', 'apex']);
+
+console.log(trie.getWords('app')); // ['app', 'apple', 'application']
+console.log(trie.hasPrefix('ap')); // true
+```
+
+## Next Steps
+
+- 📖 [Core Concepts](/guide/concepts) — understand the Big Three
+- 📋 [API Reference](/api/) — full method signatures and examples
+- 💡 [Real-World Examples](/guide/guides) — patterns for production
+- ⚡ [Performance](/guide/performance) — benchmarks and comparisons

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

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

package/docs-site-docusaurus/docs/guide/use-cases/array-sort-alternative.md

@@ -0,0 +1,158 @@
+---
+title: When Array + Sort Becomes Too Slow
+description: Stop re-sorting arrays after every insert. Use TreeMap, TreeSet, or Heap for O(log n) ordered operations in JavaScript and TypeScript.
+keywords: [javascript sorted insert, array sort performance, sorted array alternative, binary search insert javascript, ordered collection typescript]
+sidebar_label: Array + Sort Alternatives
+---
+
+# When Array + Sort Becomes Too Slow
+
+A common pattern in JavaScript:
+
+```typescript
+const items: number[] = [];
+
+function addSorted(value: number) {
+  items.push(value);
+  items.sort((a, b) => a - b); // O(n log n) every time!
+}
+```
+
+This works fine for 100 elements. At 10,000, it's noticeably slow. At 100,000, it's a bottleneck.
+
+## Why This Is Slow
+
+| Elements | Array push + sort | Tree insert |
+|----------|------------------|-------------|
+| 100 | ~0.01ms | ~0.01ms |
+| 10,000 | ~5ms | ~0.1ms |
+| 100,000 | ~80ms | ~0.2ms |
+| 1,000,000 | ~1200ms | ~0.5ms |
+
+Array.sort is O(n log n). Tree insert is O(log n). The gap grows with data size.
+
+## Choose the Right Alternative
+
+### Need sorted key-value pairs → TreeMap
+
+```typescript
+import { TreeMap } from 'data-structure-typed';
+
+const prices = new TreeMap<string, number>();
+prices.set('apple', 1.2);
+prices.set('banana', 0.5);
+prices.set('cherry', 2.5);
+
+// Always sorted by key
+for (const [fruit, price] of prices) {
+  console.log(fruit, price);
+}
+// apple 1.2, banana 0.5, cherry 2.5
+
+// Find nearest
+prices.floor('blueberry'); // ['banana', 0.5]
+```
+
+### Need sorted unique values → TreeSet
+
+```typescript
+import { TreeSet } from 'data-structure-typed';
+
+const uniqueScores = new TreeSet<number>();
+uniqueScores.add(85);
+uniqueScores.add(92);
+uniqueScores.add(78);
+uniqueScores.add(85); // duplicate ignored
+
+[...uniqueScores]; // [78, 85, 92] — sorted, unique
+```
+
+### Only need min or max → Heap
+
+```typescript
+import { MinHeap } from 'data-structure-typed';
+
+const heap = new MinHeap<number>();
+heap.add(5);
+heap.add(2);
+heap.add(8);
+
+heap.peek(); // 2 — O(1)
+heap.poll(); // 2 — O(log n), removes and returns min
+```
+
+Heap is lighter than TreeMap when you only need the top element.
+
+## Decision Guide
+
+```
+Do you need...
+├── Only the min or max? → Heap / MinHeap / MaxHeap
+├── Sorted iteration of all elements?
+│   ├── Key-value pairs? → TreeMap
+│   └── Values only? → TreeSet
+├── Floor / ceiling / range queries? → TreeMap / TreeSet
+├── Rank queries (kth element)? → TreeMap/TreeSet with enableOrderStatistic
+└── Just fast lookup by key? → HashMap (or native Map)
+```
+
+## Before and After
+
+### Task queue (before)
+```typescript
+// ❌ O(n log n) per insert
+const tasks: { priority: number; name: string }[] = [];
+tasks.push({ priority: 3, name: 'email' });
+tasks.push({ priority: 1, name: 'bugfix' });
+tasks.sort((a, b) => a.priority - b.priority);
+const next = tasks.shift(); // O(n) shift
+```
+
+### Task queue (after)
+```typescript
+// ✅ O(log n) per insert, O(log n) per poll
+import { MinPriorityQueue } from 'data-structure-typed';
+
+const tasks = new MinPriorityQueue<{ priority: number; name: string }>({
+  comparator: (a, b) => a.priority - b.priority
+});
+tasks.add({ priority: 3, name: 'email' });
+tasks.add({ priority: 1, name: 'bugfix' });
+const next = tasks.poll(); // { priority: 1, name: 'bugfix' }
+```
+
+### Leaderboard (before)
+```typescript
+// ❌ Re-sort after every score update
+const scores: [string, number][] = [];
+scores.push(['Alice', 100]);
+scores.push(['Bob', 250]);
+scores.sort((a, b) => b[1] - a[1]);
+const top3 = scores.slice(0, 3); // O(n log n) + O(k)
+```
+
+### Leaderboard (after)
+```typescript
+// ✅ O(log n) insert, O(log n + k) for top-k
+import { TreeMap } from 'data-structure-typed';
+
+const board = new TreeMap<number, string>(
+  [[100, 'Alice'], [250, 'Bob']],
+  { comparator: (a, b) => b - a, enableOrderStatistic: true }
+);
+board.rangeByRank(0, 2); // Top 3 in O(log n + k)
+```
+
+## Complexity Cheat Sheet
+
+| Operation | Array + sort | TreeMap/TreeSet | Heap |
+|-----------|-------------|----------------|------|
+| Insert (maintain order) | O(n log n) | O(log n) | O(log n) |
+| Get min/max | O(1) | O(log n) | O(1) |
+| Delete min/max | O(n) | O(log n) | O(log n) |
+| Find by key | O(log n) | O(log n) | O(n) |
+| Floor/Ceiling | O(log n) | O(log n) | ❌ |
+| Range query | O(log n + k) | O(log n + k) | ❌ |
+| Sorted iteration | O(1)* | O(n) | O(n log n) |
+
+*Array is already sorted, so iteration is free — but maintaining that sort is expensive.

package/docs-site-docusaurus/docs/guide/use-cases/heap-vs-sorting.md

@@ -0,0 +1,92 @@
+---
+title: Heap vs Sorting an Array — When to Use Which
+description: Compare Heap and Array.sort for priority queues, top-k, and streaming data in JavaScript/TypeScript. Performance analysis and code examples.
+keywords: [heap vs sort, array sort performance, priority queue vs sort, top k javascript, heap javascript, when to use heap]
+sidebar_label: Heap vs Sorting
+---
+
+# Heap vs Sorting an Array
+
+Both can give you ordered data. But they're optimized for different access patterns.
+
+## Quick Answer
+
+- **Need all elements sorted** → sort the array once
+- **Need only the min/max repeatedly** → use a Heap
+- **Streaming data (elements arrive over time)** → use a Heap
+- **Static data, one-time sort** → use Array.sort
+
+## Performance Comparison
+
+| Operation | Array.sort | Heap |
+|-----------|-----------|------|
+| Sort all elements | O(n log n) | O(n log n) |
+| Insert 1 element (keep sorted) | O(n log n) or O(n)* | O(log n) |
+| Get min/max | O(1) | O(1) |
+| Remove min/max | O(n) | O(log n) |
+| Get top-k from n elements | O(n log n) | O(n log k) |
+
+*O(n) if you binary-search + splice; O(n log n) if you push + re-sort.
+
+## Example: Top-K Scores
+
+### Array approach
+```typescript
+// ❌ Sort everything, take first k
+function topK_array(scores: number[], k: number): number[] {
+  return scores.sort((a, b) => b - a).slice(0, k);
+  // O(n log n) — sorts ALL elements even if k is small
+}
+```
+
+### Heap approach
+```typescript
+import { MinHeap } from 'data-structure-typed';
+
+// ✅ Only maintain k elements in the heap
+function topK_heap(scores: number[], k: number): number[] {
+  const heap = new MinHeap<number>();
+  for (const score of scores) {
+    heap.add(score);
+    if (heap.size > k) heap.poll();
+  }
+  return heap.toArray().sort((a, b) => b - a);
+  // O(n log k) — much faster when k << n
+}
+```
+
+For 1,000,000 elements with k=10: array sorts all 1M elements. Heap only maintains 10.
+
+## Example: Streaming Data
+
+```typescript
+import { MinHeap } from 'data-structure-typed';
+
+// New scores arrive continuously
+const liveScores = new MinHeap<number>();
+
+// Each insert: O(log n)
+liveScores.add(85);
+liveScores.add(92);
+liveScores.add(78);
+
+// Current lowest: O(1)
+liveScores.peek(); // 78
+
+// Process lowest: O(log n)
+liveScores.poll(); // 78
+```
+
+With an array, you'd re-sort after every insert — O(n log n) each time.
+
+## When to Use Each
+
+| Scenario | Use Array.sort | Use Heap |
+|----------|---------------|----------|
+| One-time sort of static data | ✅ | ❌ |
+| Repeated insert + get min/max | ❌ | ✅ |
+| Top-k from large dataset | ❌ (k << n) | ✅ |
+| Streaming / real-time data | ❌ | ✅ |
+| Need sorted iteration of ALL elements | ✅ | ❌ |
+| Dijkstra / A* algorithm | ❌ | ✅ |
+| Simple, small dataset (< 100) | ✅ | Either |

package/docs-site-docusaurus/docs/guide/use-cases/map-vs-treemap.md

@@ -0,0 +1,151 @@
+---
+title: Map vs TreeMap — When Native Map Isn't Enough
+description: Compare JavaScript's native Map with TreeMap for sorted collections, range queries, and ordered iteration. Code examples and performance analysis.
+keywords: [map vs treemap, javascript map alternative, sorted map javascript, ordered map typescript, treemap performance, when to use treemap]
+sidebar_label: Map vs TreeMap
+---
+
+# Map vs TreeMap
+
+JavaScript's `Map` is excellent for key-value lookup. But it has no concept of order, range, or proximity. When you need those, use `TreeMap`.
+
+## Feature Comparison
+
+| Feature | Map | TreeMap |
+|---------|-----|---------|
+| Key-value lookup | O(1) avg | O(log n) |
+| Insert / delete | O(1) avg | O(log n) |
+| Sorted iteration | ❌ | ✅ |
+| Floor (largest key ≤ x) | ❌ | O(log n) |
+| Ceiling (smallest key ≥ x) | ❌ | O(log n) |
+| Range query | ❌ | O(log n + k) |
+| getRank / getByRank | ❌ | O(log n) |
+| First / last key | ❌ | O(log n) |
+| Memory | Lower | Higher |
+
+## When Map Is the Right Choice
+
+```typescript
+// User lookup by ID — order doesn't matter
+const users = new Map<string, User>();
+users.set('abc123', { name: 'Alice' });
+users.get('abc123'); // O(1)
+```
+
+Use `Map` when:
+- You only need get/set/delete by exact key
+- Order doesn't matter
+- Performance on individual lookups is critical (O(1) vs O(log n))
+
+## When TreeMap Is the Right Choice
+
+### Sorted iteration
+```typescript
+import { TreeMap } from 'data-structure-typed';
+
+const config = new TreeMap<string, string>();
+config.set('database.host', 'localhost');
+config.set('app.name', 'MyApp');
+config.set('database.port', '5432');
+
+for (const [key, value] of config) {
+  console.log(key, value);
+}
+// app.name MyApp
+// database.host localhost
+// database.port 5432
+```
+
+### Finding nearest keys
+```typescript
+const prices = new TreeMap<number, string>();
+prices.set(10, 'cheap');
+prices.set(50, 'medium');
+prices.set(100, 'expensive');
+
+// "What's the price tier for $35?"
+prices.floor(35);   // [10, 'cheap'] — largest key ≤ 35
+prices.ceiling(35); // [50, 'medium'] — smallest key ≥ 35
+```
+
+### Range queries
+```typescript
+const events = new TreeMap<number, string>();
+events.set(1000, 'login');
+events.set(2000, 'click');
+events.set(3000, 'purchase');
+events.set(4000, 'logout');
+
+// Events between t=1500 and t=3500
+events.rangeSearch([1500, 3500]); // [[2000, 'click'], [3000, 'purchase']]
+```
+
+### Rank queries
+```typescript
+const leaderboard = new TreeMap<number, string>(
+  [[100, 'Alice'], [250, 'Bob'], [180, 'Charlie']],
+  { enableOrderStatistic: true }
+);
+
+leaderboard.getRank(180);  // 1 — Charlie is at position 1
+leaderboard.getByRank(0);  // [100, 'Alice'] — first in tree order
+```
+
+## Performance: When Does TreeMap Win?
+
+For pure get/set, Map is faster (O(1) vs O(log n)). TreeMap wins when you need **ordered operations**:
+
+| 10,000 entries | Map | TreeMap |
+|----------------|-----|---------|
+| set() | ~0.5μs | ~2μs |
+| get() | ~0.3μs | ~1.5μs |
+| floor() | N/A (manual O(n)) | ~1.5μs |
+| rangeSearch() | N/A (manual O(n log n)) | ~5μs + O(k) |
+| Sorted iteration | O(n log n) sort first | O(n) |
+
+If you're calling `.floor()` or `.rangeSearch()` frequently, TreeMap is orders of magnitude faster than manually sorting Map keys every time.
+
+## Set vs TreeSet — Same Story
+
+| Feature | Set | TreeSet |
+|---------|-----|---------|
+| Membership check | O(1) avg | O(log n) |
+| Sorted iteration | ❌ | ✅ |
+| Floor / ceiling | ❌ | O(log n) |
+| Range queries | ❌ | O(log n + k) |
+| First / last | ❌ | O(log n) |
+
+```typescript
+import { TreeSet } from 'data-structure-typed';
+
+const timestamps = new TreeSet<number>([1000, 3000, 2000, 5000]);
+[...timestamps]; // [1000, 2000, 3000, 5000]
+timestamps.floor(2500); // 2000
+timestamps.ceiling(2500); // 3000
+```
+
+## Migration Guide: Map → TreeMap
+
+TreeMap implements the same interface patterns as Map:
+
+```typescript
+// Map
+const map = new Map<string, number>();
+map.set('a', 1);
+map.get('a');
+map.has('a');
+map.delete('a');
+map.size;
+for (const [k, v] of map) { ... }
+
+// TreeMap — same API, plus ordered operations
+const tree = new TreeMap<string, number>();
+tree.set('a', 1);
+tree.get('a');
+tree.has('a');
+tree.delete('a');
+tree.size;
+for (const [k, v] of tree) { ... } // sorted!
+tree.floor('b');     // bonus
+tree.rangeSearch(['a', 'z']); // bonus
+```

package/docs-site-docusaurus/docs/guide/use-cases/priority-queue-typescript.md

@@ -0,0 +1,113 @@
+---
+title: Priority Queue in TypeScript — Complete Guide
+description: How to implement a priority queue in TypeScript using Heap, MinHeap, and MaxHeap. Covers task scheduling, top-k problems, and Dijkstra's algorithm.
+keywords: [priority queue typescript, heap typescript, min heap javascript, max heap javascript, task scheduler, top-k]
+sidebar_label: Priority Queue
+---
+
+# Priority Queue in TypeScript
+
+A **priority queue** processes elements by priority, not insertion order. In TypeScript, there is no built-in priority queue — but you can use a **Heap** to get O(log n) insert and O(1) access to the highest-priority element.
+
+## The Problem
+
+You have tasks with different priorities. Using a sorted array:
+
+```typescript
+// ❌ Array approach — O(n) insert to maintain sorted order
+const tasks: [number, string][] = [];
+
+function addTask(priority: number, name: string) {
+  tasks.push([priority, name]);
+  tasks.sort((a, b) => a[0] - b[0]); // O(n log n) every time!
+}
+```
+
+With 10,000 tasks, this gets slow fast.
+
+## The Solution
+
+```typescript
+import { MinPriorityQueue } from 'data-structure-typed';
+
+// O(log n) insert, O(1) peek, O(log n) poll
+const tasks = new MinPriorityQueue<[number, string]>({
+  comparator: (a, b) => a[0] - b[0]
+});
+
+tasks.add([3, 'Send email']);
+tasks.add([1, 'Fix critical bug']);
+tasks.add([2, 'Review PR']);
+
+tasks.poll(); // [1, 'Fix critical bug'] — highest priority first
+tasks.poll(); // [2, 'Review PR']
+tasks.poll(); // [3, 'Send email']
+```
+
+## When to Use a Priority Queue
+
+| Scenario | Why Heap? |
+|----------|-----------|
+| Task scheduling | Process highest-priority task first |
+| Top-k elements | Find k largest/smallest in O(n log k) |
+| Dijkstra's algorithm | Always expand the nearest unvisited node |
+| Event simulation | Process next event by timestamp |
+| Median finding | Two heaps (min + max) for O(log n) median |
+
+## MinHeap vs MaxHeap vs Custom
+
+```typescript
+import { MinHeap, MaxHeap, Heap } from 'data-structure-typed';
+
+// Numbers — built-in comparison
+const minHeap = new MinHeap<number>([5, 3, 8, 1]);
+minHeap.peek(); // 1
+
+const maxHeap = new MaxHeap<number>([5, 3, 8, 1]);
+maxHeap.peek(); // 8
+
+// Objects — custom comparator
+const taskHeap = new Heap<{ priority: number; name: string }>({
+  comparator: (a, b) => a.priority - b.priority
+});
+taskHeap.add({ priority: 2, name: 'Review PR' });
+taskHeap.add({ priority: 1, name: 'Fix bug' });
+taskHeap.peek(); // { priority: 1, name: 'Fix bug' }
+```
+
+## Top-K Problem
+
+Find the 3 highest scores from a stream:
+
+```typescript
+import { MinHeap } from 'data-structure-typed';
+
+function topK(stream: number[], k: number): number[] {
+  const heap = new MinHeap<number>();
+  for (const val of stream) {
+    heap.add(val);
+    if (heap.size > k) heap.poll(); // remove smallest
+  }
+  return heap.toArray().sort((a, b) => b - a);
+}
+
+topK([3, 1, 4, 1, 5, 9, 2, 6, 5], 3); // [9, 6, 5]
+```
+
+Time: O(n log k) — much better than sorting the entire array.
+
+## Complexity
+
+| Operation | Array (sorted) | Heap |
+|-----------|---------------|------|
+| Insert | O(n) | O(log n) |
+| Get min/max | O(1) | O(1) |
+| Remove min/max | O(1) | O(log n) |
+| Search | O(log n) | O(n) |
+
+## When NOT to Use a Heap
+
+- You need to search for arbitrary elements → use a Tree or HashMap
+- You need sorted iteration of all elements → use TreeMap/TreeSet
+- Your data is small (< 100 elements) → array sort is fine
+- You need both min and max → use two heaps or a TreeMap