data-structure-typed 2.5.2 → 2.6.0

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

@@ -1,15 +1,14 @@
 ---
 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]
+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)**
 
 ---
 
@@ -485,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
   }
@@ -597,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
@@ -606,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,18 +1,16 @@
 ---
-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."
+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"]
 ---
-keywords: [typescript data structures concepts, comparator, iterator protocol, generics, uniform API]
-
 # 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)**
 
 ---
-keywords: [typescript data structures concepts, comparator, iterator protocol, generics, uniform API]
 
 ## Table of Contents
 
@@ -25,7 +23,6 @@ keywords: [typescript data structures concepts, comparator, iterator protocol, g
 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
 
@@ -82,7 +79,6 @@ 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
 
@@ -108,7 +104,6 @@ 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
 
@@ -170,7 +165,6 @@ for (const item of heap) console.log(item);
 ```
 
 ---
-keywords: [typescript data structures concepts, comparator, iterator protocol, generics, uniform API]
 
 ## 🔗 Seamless Interoperability: Iterator Protocol Everywhere
 
@@ -186,7 +180,6 @@ 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
 
@@ -258,7 +251,6 @@ const stats = {
 | forEach     | ✅           | ✅    | ✅     | ✅     | ✅          |
 
 ---
-keywords: [typescript data structures concepts, comparator, iterator protocol, generics, uniform API]
 
 ## Why Not Just Use Native JavaScript?
 
@@ -341,45 +333,68 @@ const tree = new RedBlackTree(prices);
 const inRange = tree.rangeSearch([30, 70]);
 ```
 
-### Case 5: Finding the K-th Element Requires Sorting
+### Case 5: Prefix Matching is Tedious
 
-❌ Array: sort + index is O(n log n):
+❌ Array.filter is O(n*m):
 
 ```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
+const words = ['apple', 'app', 'apply', 'application'];
+const matches = words.filter(w => w.startsWith('app'));
+// For 1M words: checks 1M words ❌
 ```
 
-✅ Order-statistic tree: O(log n) getByRank/getRank with live updates:
+✅ Trie prefix matching is O(m + k):
 
 ```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)
+const trie = new Trie(words);
+const matches = trie.getWords('appl');
+// O(5 + 4) = 9 operations ✅
 ```
 
-### Case 6: Prefix Matching is Tedious
+### Case 6: Finding the K-th Element or Rank
 
-❌ Array.filter is O(n*m):
+❌ Array requires sorting O(n log n):
 
 ```javascript
-const words = ['apple', 'app', 'apply', 'application'];
-const matches = words.filter(w => w.startsWith('app'));
-// For 1M words: checks 1M words ❌
+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
 ```
 
-✅ Trie prefix matching is O(m + k):
+✅ Order-Statistic Tree gives O(log n) rank queries:
 
 ```javascript
-const trie = new Trie(words);
-const matches = trie.getWords('appl');
-// O(5 + 4) = 9 operations ✅
+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
 ```
 
 ---
-keywords: [typescript data structures concepts, comparator, iterator protocol, generics, uniform API]
 
 ## 🎯 Decision Guide: Choose the Right Data Structure
 
@@ -415,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)
@@ -423,7 +444,6 @@ Need a sorted key-value map?
 ```
 
 ---
-keywords: [typescript data structures concepts, comparator, iterator protocol, generics, uniform API]
 
 ## Next Steps
 
@@ -440,7 +460,6 @@ keywords: [typescript data structures concepts, comparator, iterator protocol, g
 → [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

@@ -1,3 +1,12 @@
+---
+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.
@@ -148,6 +157,50 @@ Yes.
 
 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

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

@@ -1,15 +1,14 @@
 ---
 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]
+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)**
 
 ---
 
@@ -148,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++) {
@@ -172,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;
 
@@ -220,7 +219,7 @@ console.log(cache.get('a')); // 'value1', 'a' is now most recent
 cache.set('d', 'value4');    // Evicts 'b' (least recent)
 ```
 
-### Example 2: Real-Time Leaderboard (Order-Statistic Tree)
+### Example 2: Real-Time Leaderboard
 
 ```typescript
 import { RedBlackTree } from 'data-structure-typed';
@@ -260,7 +259,7 @@ class Leaderboard {
     return this.scores.getRank(this.players.get(playerId)!) + 1; // 1-based
   }
 
-  // O(log n + k) — get k-th player by rank
+  // 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;