data-structure-typed 2.5.1 → 2.5.3

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

@@ -1,13 +1,14 @@
 ---
 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
 
 How to use data-structure-typed with React, Express, Nest.js, and other frameworks.
 
-**[Back to README](/.md) • [Code Examples](/guide/guides.md) • [Performance](/guide/performance.md)**
+**[Back to README](/docs/guide/quick-start) • [Code Examples](/guide/guides.md) • [Performance](/guide/performance.md)**
 
 ---
 
@@ -289,6 +290,8 @@ app.get('/api/data', (req, res) => {
 
 ### Use Case: Product Price Index Service
 
+> Full working demo: [StackBlitz NestJS Playground](https://stackblitz.com/github/zrwusa/dst-playgrounds/tree/main/apps/nestjs?file=src%2Fproduct%2Fservices%2Fproduct-price-index.service.ts&title=data-structure-typed%20%E2%80%94%20NestJS%20Product%20API)
+
 ```typescript
 import {
   BadRequestException,
@@ -307,7 +310,6 @@ export interface Product {
   lastUpdated?: Date;
 }
 
-/** KEY INSIGHT: Use compound keys to solve the problem of "multiple products at the same price" */
 interface CompositeKey {
   price: number;
   productId: string;
@@ -326,13 +328,8 @@ export type TierName = 'budget' | 'mid-range' | 'premium';
  * Point Lookup       | O(1)                  | O(1)      | O(1)
  * Insert/Update      | O(log n)              | O(n)      | O(log n)
  * Sort by Price      | O(n)                  | O(n log n)| O(n log n)
- * Multiple at Price  | ✓ Supported           | ✓         | Complex
- *
- * Advantages:
- * - O(1) idToKeyMap lookup + O(log n) tree operations
- * - Automatic ordering without post-sort
- * - Efficient range queries for pricing tiers
- * - Low memory footprint vs duplicate maps
+ * Pagination         | O(log n + k)          | O(n log n)| O(n log n)
+ * Rank/Percentile    | O(log n)              | O(n)      | O(n log n)
  */
 @Injectable()
 export class ProductPriceIndexService {
@@ -346,228 +343,130 @@ export class ProductPriceIndexService {
         if (priceCmp !== 0) return priceCmp;
         return a.productId.localeCompare(b.productId);
       },
+      enableOrderStatistic: true, // Enables getRank/getByRank/rangeByRank
     });
     this.idToKeyMap = new Map();
   }
 
-  /** Time Complexity: O(log n) */
+  /** O(log n) */
   addProduct(product: Product): Product {
     if (this.idToKeyMap.has(product.id))
       throw new BadRequestException(`Product ${product.id} already exists`);
 
     product.lastUpdated = new Date();
-
-    const key: CompositeKey = {
-      price: product.price,
-      productId: product.id,
-    };
-
-    this.priceIndex.add(key, product);
+    const key: CompositeKey = { price: product.price, productId: product.id };
+    this.priceIndex.set(key, product);
     this.idToKeyMap.set(product.id, key);
-
     return product;
   }
 
-  /** Time Complexity: O(log n) */
-  updateProduct(productId: string, updates: Partial<Product>): Product {
-    const oldKey = this.idToKeyMap.get(productId);
-    if (oldKey === undefined)
-      throw new NotFoundException(`Product ${productId} not found`);
-
-    const existing = this.priceIndex.get(oldKey);
-    if (!existing)
-      throw new NotFoundException(`Product ${productId} not found`);
-
-    const updated: Product = {
-      ...existing,
-      ...updates,
-      id: existing.id,
-      lastUpdated: new Date(),
-    };
-
-    const newPrice = updates.price ?? existing.price;
-
-    this.priceIndex.delete(oldKey);
-    const currentKey: CompositeKey = {
-      price: newPrice,
-      productId,
-    };
-    this.priceIndex.set(currentKey, updated);
-    this.idToKeyMap.set(productId, currentKey);
-
-    return updated;
-  }
-
-  /** Time Complexity: O(1) */
+  /** O(1) — HashMap lookup */
   getProductById(productId: string): Product {
     const key = this.idToKeyMap.get(productId);
-
     if (key === undefined)
       throw new NotFoundException(`Product ${productId} not found`);
-
     return this.priceIndex.get(key)!;
   }
 
-  /** Time Complexity: O(log n + k) */
+  /** O(log n + k) — directly returns values, no secondary lookup */
   getProductsByPriceRange(minPrice: number, maxPrice: number): Product[] {
     const range = new Range(
       { price: minPrice, productId: '' },
       { price: maxPrice, productId: '\uffff' },
-      true, // includeLow
-      true, // includeHigh
+      true,
+      true,
     );
-
-    const keys = this.priceIndex.rangeSearch(range, (n) => n.key);
-    return keys.map((key) => this.priceIndex.get(key)!);
+    return this.priceIndex.rangeSearch(range, (n) => n.value!);
   }
 
-  /** Time Complexity: O(log n) */
+  /** O(log n) — NavigableMap floor() */
   getHighestPricedProductWithinBudget(maxBudget: number): Product | null {
-    const key: CompositeKey = {
-      price: maxBudget,
-      productId: '\uffff',
-    };
+    const key: CompositeKey = { price: maxBudget, productId: '\uffff' };
     const floorKey = this.priceIndex.floor(key);
     return floorKey ? this.priceIndex.get(floorKey)! : null;
   }
 
-  /** Time O(log n) */
-  getCheapestProductAbovePrice(minPrice: number): Product | null {
-    const key: CompositeKey = {
-      price: minPrice,
-      productId: '\uffff',
-    };
-    const higherKey = this.priceIndex.higher(key);
-    return higherKey ? this.priceIndex.get(higherKey)! : null;
-  }
-
-  /** Time Complexity: O(log n + k) */
-  getProductsByTier(tierName: TierName): Product[] {
-    const tiers = {
-      budget: [0, 50],
-      'mid-range': [50, 200],
-      premium: [200, Infinity],
-    };
-
-    const [min, max] = tiers[tierName];
-    return this.getProductsByPriceRange(min, max);
-  }
-
-  /** Time Complexity: O(log n + k + m) */
-  getProductsByPriceAndCategory(
-    minPrice: number,
-    maxPrice: number,
-    category: string,
-  ): Product[] {
-    const priceRangeProducts = this.getProductsByPriceRange(minPrice, maxPrice);
-    return priceRangeProducts.filter(
-      (p) => p.category.toLowerCase() === category.toLowerCase(),
-    );
-  }
-
-  /** Time Complexity: O((log n + k) * log n) */
-  applyDiscountToRange(
-    minPrice: number,
-    maxPrice: number,
-    discountPercent: number,
-  ): Product[] {
-    const products = this.getProductsByPriceRange(minPrice, maxPrice);
-    const updated: Product[] = [];
-
-    for (const product of products) {
-      const newPrice = product.price * (1 - discountPercent / 100);
-      const updatedProduct = this.updateProduct(product.id, {
-        price: newPrice,
-      });
-      updated.push(updatedProduct);
-    }
-
-    return updated;
+  /** O(n) — iterator protocol, one-liner */
+  getAllProductsSortedByPrice(): Product[] {
+    return [...this.priceIndex.values()];
   }
 
-  /** Time Complexity: O(log n) */
-  deleteProduct(productId: string): void {
-    const key = this.idToKeyMap.get(productId);
-
-    if (key === undefined)
-      throw new NotFoundException(`Product ${productId} not found`);
-
-    this.priceIndex.delete(key);
-    this.idToKeyMap.delete(productId);
-  }
+  /**
+   * O(n) for totalValue, O(log n) for min/max
+   * min/max use getLeftMost/getRightMost instead of full traversal
+   */
+  getStatistics() {
+    if (this.idToKeyMap.size === 0)
+      return { totalProducts: 0, priceRange: { min: 0, max: 0 }, averagePrice: 0, totalValue: 0 };
 
-  /** Time Complexity: O(n) */
-  getStatistics(): {
-    totalProducts: number;
-    priceRange: { min: number; max: number };
-    averagePrice: number;
-    totalValue: number;
-  } {
-    if (this.idToKeyMap.size === 0) {
-      return {
-        totalProducts: 0,
-        priceRange: { min: 0, max: 0 },
-        averagePrice: 0,
-        totalValue: 0,
-      };
-    }
+    const minKey = this.priceIndex.getLeftMost();
+    const maxKey = this.priceIndex.getRightMost();
 
-    let minPrice = Infinity;
-    let maxPrice = -Infinity;
     let totalValue = 0;
     let totalProducts = 0;
-
-    let entry = this.priceIndex.getLeftMost((node) => node);
-
-    while (entry) {
-      const product = this.priceIndex.get(entry.key);
-      if (product) {
-        minPrice = Math.min(minPrice, product.price);
-        maxPrice = Math.max(maxPrice, product.price);
-        totalValue += product.price * product.quantity;
-        totalProducts += product.quantity;
-      }
-
-      entry = this.priceIndex.higher(entry.key, (node) => node);
+    for (const [, product] of this.priceIndex) {
+      totalValue += product.price * product.quantity;
+      totalProducts += product.quantity;
     }
 
     return {
-      totalProducts: totalProducts,
-      priceRange: { min: minPrice, max: maxPrice },
+      totalProducts,
+      priceRange: { min: minKey?.price ?? 0, max: maxKey?.price ?? 0 },
       averagePrice: totalValue / totalProducts,
       totalValue,
     };
   }
 
-  /** Time Complexity: O(n) */
-  getAllProductsSortedByPrice(): Product[] {
-    const products: Product[] = [];
-    let curNode = this.priceIndex.getLeftMost((node) => node);
+  // ── Order-Statistic API (rank-based queries) ──────────────────────
 
-    while (curNode) {
-      if (curNode.key) products.push(this.priceIndex.get(curNode.key)!);
-      curNode = this.priceIndex.higher(curNode.key, (node) => node);
-    }
+  /** O(log n + pageSize) — rank-based pagination */
+  getProductsByPage(page: number, pageSize: number): Product[] {
+    const start = page * pageSize;
+    const end = Math.min(start + pageSize - 1, this.priceIndex.size - 1);
+    if (start >= this.priceIndex.size) return [];
+    const keys = this.priceIndex.rangeByRank(start, end);
+    return keys.map((key) => this.priceIndex.get(key)!);
+  }
 
-    return products;
+  /** O(log n) — what % of products are cheaper */
+  getPricePercentile(productId: string): number {
+    const key = this.idToKeyMap.get(productId);
+    if (!key) throw new NotFoundException(`Product ${productId} not found`);
+    return (this.priceIndex.getRank(key) / this.priceIndex.size) * 100;
   }
 
-  /** O(1) */
-  getProductCount(): number {
-    return this.idToKeyMap.size;
+  /** O(log n) — median product */
+  getMedianProduct(): Product | null {
+    if (this.priceIndex.size === 0) return null;
+    const key = this.priceIndex.getByRank(Math.floor((this.priceIndex.size - 1) / 2));
+    return key ? this.priceIndex.get(key)! : null;
   }
 
-  /** O(1) */
-  hasProduct(productId: string): boolean {
-    return this.idToKeyMap.has(productId);
+  /** O(log n + k) — top N cheapest */
+  getTopNCheapest(n: number): Product[] {
+    const end = Math.min(n - 1, this.priceIndex.size - 1);
+    if (end < 0) return [];
+    return this.priceIndex.rangeByRank(0, end).map((key) => this.priceIndex.get(key)!);
   }
 
-  /** O(n) */
-  getAllProductIds(): string[] {
-    return [...this.idToKeyMap.keys()];
+  /** O(log n + k) — top N most expensive */
+  getTopNExpensive(n: number): Product[] {
+    const size = this.priceIndex.size;
+    if (size === 0) return [];
+    const start = Math.max(size - n, 0);
+    return this.priceIndex.rangeByRank(start, size - 1)
+      .map((key) => this.priceIndex.get(key)!)
+      .reverse();
   }
-}
 
+  /** O(log n) — dynamic tier by percentile, no hardcoded price ranges */
+  getTierByPercentile(productId: string): TierName {
+    const pct = this.getPricePercentile(productId);
+    if (pct < 33) return 'budget';
+    if (pct < 66) return 'mid-range';
+    return 'premium';
+  }
+}
 ```
 
 ### Use Case: Task Queue Controller

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

@@ -1,13 +1,14 @@
 ---
 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
 
 A quick-reference guide to all structures, common operations, and usage patterns. For complete API details with method signatures and examples, see the **[Full API Docs](https://data-structure-typed-docs.vercel.app/)**.
 
-**[Back to README](/.md) • [API Docs](https://data-structure-typed-docs.vercel.app/) • [Real-World Examples](/guide/guides.md) • [Performance](/guide/performance.md)**
+**[Back to README](/docs/guide/quick-start) • [API Docs](https://data-structure-typed-docs.vercel.app/) • [Real-World Examples](/guide/guides.md) • [Performance](/guide/performance.md)**
 
 ---
 
@@ -55,7 +56,7 @@ A quick-reference guide to all structures, common operations, and usage patterns
 import { Stack } from 'data-structure-typed';
 
 const stack = new Stack<number>([1, 2]);
-stack.push(3);                // add to bottom
+stack.push(3);                // add to top
 const top = stack.pop();      // Remove from top - O(1)
 const peek = stack.peek();    // View top
 stack.print();                // [1, 2]
@@ -166,6 +167,97 @@ avl.print()
 //      4      9 
 ```
 
+#### TreeMap (Ordered Map)
+
+```typescript
+import { TreeMap } from 'data-structure-typed';
+
+const tm = new TreeMap<number, string>([[3, 'c'], [1, 'a'], [2, 'b']]);
+tm.set(4, 'd');                    // Set key-value - O(log n)
+tm.get(2);                         // 'b' - O(log n)
+tm.has(3);                         // true
+tm.delete(1);                      // Remove - O(log n)
+
+// Navigation — Java NavigableMap-style
+tm.first();                        // [2, 'b'] — smallest entry
+tm.last();                         // [4, 'd'] — largest entry
+tm.ceiling(3);                     // [3, 'c'] — smallest >= 3
+tm.floor(2);                       // [2, 'b'] — largest <= 2
+tm.higher(2);                      // [3, 'c'] — strictly > 2
+tm.lower(3);                       // [2, 'b'] — strictly < 3
+
+// Iteration (sorted order)
+console.log([...tm.keys()]);       // [2, 3, 4]
+console.log([...tm.values()]);     // ['b', 'c', 'd']
+
+// Bulk operations
+tm.setMany([[5, 'e'], [6, 'f']]);  // Set multiple at once
+
+// Functional
+const filtered = tm.filter((v, k) => k > 2);
+const mapped = tm.map((v, k) => [k * 10, v!.toUpperCase()] as [number, string]);
+```
+
+#### TreeSet (Ordered Set)
+
+```typescript
+import { TreeSet } from 'data-structure-typed';
+
+const ts = new TreeSet<number>([5, 3, 8, 1]);
+ts.add(4);                         // Add - O(log n)
+ts.has(3);                         // true
+ts.delete(5);                      // Remove - O(log n)
+
+// Navigation
+ts.first();                        // 1
+ts.last();                         // 8
+ts.ceiling(4);                     // 4 — smallest >= 4
+ts.floor(6);                       // 4 — largest <= 6
+ts.higher(3);                      // 4 — strictly > 3
+ts.lower(4);                       // 3 — strictly < 4
+
+// Iteration (sorted order)
+console.log([...ts.keys()]);       // [1, 3, 4, 8]
+
+// Bulk operations
+ts.addMany([10, 20, 30]);          // Add multiple at once
+```
+
+#### Order-Statistic Tree (Rank Queries)
+
+Enable `enableOrderStatistic: true` on any tree-based structure to get O(log n) rank operations:
+
+```typescript
+import { RedBlackTree, TreeMap, TreeSet } from 'data-structure-typed';
+
+// Works with RedBlackTree, TreeMap, TreeSet, TreeMultiMap, TreeMultiSet
+const tree = new RedBlackTree<number, string>(
+  [[100, 'Alice'], [85, 'Bob'], [92, 'Charlie'], [78, 'Diana']],
+  { comparator: (a, b) => b - a, enableOrderStatistic: true }
+);
+
+// getByRank(k) — element at position k in tree order, O(log n)
+tree.getByRank(0);                 // 100 (1st in tree order)
+tree.getByRank(2);                 // 92  (3rd in tree order)
+
+// getRank(key) — count of elements before key in tree order, O(log n)
+tree.getRank(92);                  // 2
+
+// rangeByRank(start, end) — elements between positions, O(log n + k)
+tree.rangeByRank(0, 2);           // [100, 92, 85] — positions 0..2
+
+// Also works with wrapper classes
+const tm = new TreeMap<number, string>([], { enableOrderStatistic: true });
+tm.set(10, 'a'); tm.set(20, 'b'); tm.set(30, 'c');
+tm.getByRank(1);                   // [20, 'b']
+tm.getRank(20);                    // 1
+
+const ts = new TreeSet<number>([], { enableOrderStatistic: true });
+ts.addMany([10, 20, 30]);
+ts.getByRank(0);                   // 10
+ts.getRank(30);                    // 2
+```
+
 ### Heap & Priority Queue
 
 #### Heap
@@ -184,7 +276,9 @@ const peek = minHeap.peek();  // View minimum - O(1)
 ```typescript
 import { MaxPriorityQueue } from 'data-structure-typed';
 
-const pq = new MaxPriorityQueue<Task>();
+const pq = new MaxPriorityQueue<Task>([], {
+  comparator: (a, b) => b.priority - a.priority
+});
 pq.add({ id: 1, priority: 5 });  // Add - O(log n)
 const task = pq.poll();          // Remove highest - O(log n)
 const size = pq.size;            // Current size
@@ -266,7 +360,7 @@ heap.peek();               // Highest priority element
 heap.size;                 // Current size
 
 // Trie
-trie.getWords('hello');      // true
+trie.has('hello');            // true
 trie.hasPrefix('hel');    // true
 
 // Graph
@@ -296,6 +390,12 @@ graph.deleteVertex('A');      // Remove vertex
 // All structures support:
 structure.clear();             // Remove all elements
 structure.delete(key);         // Remove specific
+
+// Conditional delete (BST-family and Deque)
+tree.deleteWhere(node => node.key < 10);           // Delete all matching
+tree.deleteWhere(node => node.key < 10, true);     // Delete first match only
+tree.deleteWhere(new Range(5, 15));                 // Delete by range
+deque.deleteWhere((val, idx) => val > 100);        // Deque predicate delete
 ```
 
 ---
@@ -328,12 +428,33 @@ structure.size;                // Element count
 structure.isEmpty();           // Check empty
 ```
 
+### Raw Data Mapping
+
+Pass raw objects directly — no `.map()` pre-processing needed:
+
+```typescript
+// toElementFn — extract a field, store only that (Heap, Queue, Stack, LinkedList, Trie)
+const heap = new MinHeap<number, User>(users, {
+  toElementFn: u => u.age
+});
+
+// toEntryFn — split into key-value pairs (TreeMap, HashMap, SkipList)
+const map = new TreeMap<number, User, User>(users, {
+  toEntryFn: u => [u.id, u]
+});
+
+// comparator — store full objects, sort by a field (all sorted structures)
+const set = new TreeSet<User>(users, {
+  comparator: (a, b) => a.id - b.id
+});
+```
+
 ### Structure-Specific Methods
 
 #### Trees
 
 ```typescript
-tree.height;                   // Tree height
+tree.height;                   // Tree height (getter)
 tree.isAVLBalanced();         // Balance check
 tree.getNode(key);            // Get node object
 tree.getHeight(key);          // Node height
@@ -344,10 +465,10 @@ tree.getRightMost();          // Rightmost node
 #### Deque
 
 ```typescript
-deque.peekFirst();            // View front
-deque.peekLast();             // View back
-deque.pollFirst();            // Remove front - O(1)
-deque.pollLast();             // Remove back - O(1)
+deque.first;                  // View front (getter)
+deque.last;                   // View back (getter)
+deque.shift();                // Remove front - O(1)
+deque.pop();                  // Remove back - O(1)
 ```
 
 #### Graph
@@ -463,7 +584,7 @@ const sorted = [...new RedBlackTree(data).keys()]; // Instant sort!
 
 ---
 
-## SkipList & SkipListSet
+## SkipList
 
 Probabilistic sorted containers. Interchangeable with `TreeMap`/`TreeSet`.
 

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
+}