data-structure-typed 2.5.1 → 2.5.3

package/CHANGELOG.md

@@ -8,7 +8,11 @@ All notable changes to this project will be documented in this file.
 - [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
 - [`auto-changelog`](https://github.com/CookPete/auto-changelog)
 
-## [v2.5.1](https://github.com/zrwusa/data-structure-typed/compare/v2.5.0...main) (upcoming)
+## [v2.5.3](https://github.com/zrwusa/data-structure-typed/compare/v2.5.3...main) (upcoming)
+
+## [v2.5.3](https://github.com/zrwusa/data-structure-typed/compare/v2.5.1...v2.5.3) (31 March 2026)
+
+## [v2.5.1](https://github.com/zrwusa/data-structure-typed/compare/v2.5.0...v2.5.1) (28 March 2026)
 
 ## [v2.5.0](https://github.com/zrwusa/data-structure-typed/compare/v2.4.3...v2.5.0) (27 March 2026)
 

package/MIGRATION.md

@@ -0,0 +1,169 @@
+# Migration Guide
+
+## Upgrading to v2.5.3
+
+### Breaking Changes
+
+#### 1. `HashMap/LinkedHashMap.set()` returns `this` instead of `boolean`
+
+Aligns with the native JS `Map.set()` spec. Enables chaining.
+
+```typescript
+// Before
+const success: boolean = map.set('key', 'value');
+
+// After
+map.set('key', 'value');                          // returns this
+const chain = map.set('a', 1).set('b', 2);       // chaining works
+```
+
+#### 2. `BinaryTree/BST/AVL/RedBlackTree.delete()` returns `boolean` instead of `BinaryTreeDeleteResult[]`
+
+Simplified to match standard container semantics.
+
+```typescript
+// Before
+const results: BinaryTreeDeleteResult[] = tree.delete(key);
+const success = results.length > 0 && results[0].deleted !== undefined;
+
+// After
+const success: boolean = tree.delete(key);        // true if found and removed
+```
+
+#### 3. `BST.deleteWhere()` returns `boolean` instead of `BinaryTreeDeleteResult[]`
+
+```typescript
+// Before
+const results: BinaryTreeDeleteResult[] = bst.deleteWhere(pred);
+
+// After
+const deleted: boolean = bst.deleteWhere(pred);   // true if any match removed
+```
+
+#### 4. `Stack.deleteAt()` returns `E | undefined` instead of `boolean`
+
+Consistent with `LinkedList.deleteAt()`, `Queue.deleteAt()`, `Deque.deleteAt()`.
+
+```typescript
+// Before
+const success: boolean = stack.deleteAt(2);
+
+// After
+const removed: E | undefined = stack.deleteAt(2); // returns removed element
+if (removed !== undefined) { /* success */ }
+```
+
+#### 5. `LinkedHashMap.deleteAt()` returns `[K, V] | undefined` instead of `boolean`
+
+```typescript
+// Before
+const success: boolean = lhm.deleteAt(0);
+
+// After
+const entry: [K, V] | undefined = lhm.deleteAt(0);
+if (entry) {
+  const [key, value] = entry;
+}
+```
+
+#### 6. `FibonacciHeap.push()` returns `boolean` instead of `this`
+
+Consistent with `Heap.add()`.
+
+```typescript
+// Before
+const heap: FibonacciHeap = fh.push(42);         // returned this
+
+// After
+const success: boolean = fh.push(42);            // returns true
+```
+
+#### 7. `refill()` removed from `BinaryTree` and `Heap`
+
+Replace with `clear()` + `addMany()`/`setMany()`.
+
+```typescript
+// Before (Heap)
+heap.refill([5, 3, 1, 4]);
+
+// After (Heap)
+heap.clear();
+heap.addMany([5, 3, 1, 4]);
+
+// Before (BinaryTree)
+tree.refill(entries);
+
+// After (BinaryTree)
+tree.clear();
+tree.setMany(entries);
+```
+
+---
+
+### Deprecations
+
+These still work but will be removed in a future major version.
+
+#### `Heap.poll()` → use `Heap.pop()`
+
+```typescript
+// Deprecated
+const top = heap.poll();
+
+// Preferred
+const top = heap.pop();
+```
+
+#### `Heap.deleteBy()` → use `Heap.deleteWhere()`
+
+```typescript
+// Deprecated
+heap.deleteBy(e => e.id === 42);
+
+// Preferred
+heap.deleteWhere(e => e.id === 42);
+```
+
+---
+
+### New Features
+
+#### `deleteWhere()` — conditional deletion
+
+Available on: `TreeMap`, `TreeSet`, `TreeMultiMap`, `TreeMultiSet`, `DoublyLinkedList`, `Queue`, `Heap`
+
+```typescript
+// Delete first even number from queue
+queue.deleteWhere((value, index) => value % 2 === 0);
+
+// Delete entries where value > 100 from TreeMap
+treeMap.deleteWhere((key, value) => value > 100);
+
+// Delete keys > 50 from TreeSet
+treeSet.deleteWhere((key) => key > 50);
+```
+
+#### `Queue.peek()` / `Deque.peek()`
+
+Alias for the `first` getter. Familiar API for users coming from other languages.
+
+```typescript
+const queue = new Queue([10, 20, 30]);
+queue.peek();   // 10 (same as queue.first)
+queue.first;    // 10
+
+const deque = new Deque([10, 20, 30]);
+deque.peek();   // 10 (same as deque.first)
+```
+
+#### `Heap.pop()` — primary top-removal method
+
+Consistent naming across all containers (`Stack.pop()`, `Deque.pop()`, `Heap.pop()`).
+
+```typescript
+const heap = new Heap([3, 1, 4], { comparator: (a, b) => a - b });
+heap.pop();     // 1 (min element)
+heap.pop();     // 3
+heap.pop();     // 4
+heap.pop();     // undefined
+```

package/README.md

@@ -2,9 +2,9 @@
 
 English | [简体中文](./README_CN.md)
 
-A comprehensive TypeScript data structures library with production-ready implementations.
+A production-ready TypeScript data structures library featuring **Heap, Priority Queue, Deque, Trie, Graph, Red-Black Tree, TreeMap, TreeSet, SkipList, Segment Tree**, and more — with an API that feels as intuitive as JavaScript's native `Array`. Zero dependencies. Type-safe. Supports rank queries (`getRank`), positional access (`getByRank`), and range queries (`rangeByRank`).
 
-**We TypeScript/JavaScript devs want something like C++'s `STL`, Java's `java.util` Collections, or Python's `collections` — but with an API that feels as intuitive and ergonomic as JavaScript's native `Array`.** If that's what you're looking for, you're in the right place. This is a zero-dependency library, and you can also install individual data structure packages separately if you prefer a more modular setup.
+> **Looking for a TreeMap or TreeSet in JavaScript?** Need a priority queue, an ordered set, or efficient rank/range queries? Tired of repeatedly sorting arrays after every insert? This library provides all of that with a unified, Array-like API.
 
 ![npm](https://img.shields.io/npm/dm/data-structure-typed)
 ![GitHub contributors](https://img.shields.io/github/contributors/zrwusa/data-structure-typed)
@@ -14,7 +14,7 @@ A comprehensive TypeScript data structures library with production-ready impleme
 ![NPM](https://img.shields.io/npm/l/data-structure-typed)
 ![npm](https://img.shields.io/npm/v/data-structure-typed)
 
-**📦 [Installation](#-installation) • 🎮 [Playground](#-playground) • ⚡ [Quick Start](#-quick-start-30-seconds) • 📖 [Docs](#-documentation) • 📋 [API](https://data-structure-typed-docs.vercel.app/) • 💡 [Examples](./docs/GUIDES.md)**
+**📦 [Installation](#-installation) • 🎮 [Playground](#-playground) • ⚡ [Quick Start](#-quick-start-30-seconds) • 📖 [Docs](#-documentation) • 📋 [API](https://data-structure-typed-docs.vercel.app/) • 💡 [Examples](./docs/GUIDES.md) • ❓ [FAQ](#-faq)**
 
 ---
 
@@ -28,6 +28,7 @@ A comprehensive TypeScript data structures library with production-ready impleme
 6. [Key Features](#-key-features)
 7. [Data Structures](#-data-structures-available)
 8. [Documentation](#-documentation)
+9. [FAQ](#-faq)
 
 ---
 
@@ -82,10 +83,10 @@ npm i avl-tree-typed bst-typed heap-typed
 
 Try it instantly:
 
-- [Node.js TypeScript](https://stackblitz.com/edit/stackblitz-starters-e1vdy3zw?file=src%2Findex.ts)
-- [Node.js JavaScript](https://stackblitz.com/edit/stackblitz-starters-oczhrfzn?file=src%2Findex.js)
-- [React TypeScript](https://stackblitz.com/edit/vitejs-vite-7bva1zhd?file=src%2FApp.tsx)
-- [NestJS](https://stackblitz.com/edit/nestjs-typescript-starter-q9n7okgc?file=src%2Fproduct%2Fservices%2Fproduct-price-index.service.ts)
+- [Node.js TypeScript](https://stackblitz.com/github/zrwusa/dst-playgrounds/tree/main/apps/nodejs-ts?file=src%2Findex.ts&title=data-structure-typed%20%E2%80%94%20Node.js%20TypeScript)
+- [Node.js JavaScript](https://stackblitz.com/github/zrwusa/dst-playgrounds/tree/main/apps/nodejs-js?file=src%2Findex.js&title=data-structure-typed%20%E2%80%94%20Node.js%20JavaScript)
+- [React TypeScript](https://stackblitz.com/github/zrwusa/dst-playgrounds/tree/main/apps/reactjs?file=src%2FApp.tsx&title=data-structure-typed%20%E2%80%94%20React%20Playground)
+- [NestJS](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)
 
 ---
 
@@ -215,7 +216,7 @@ const value = tree.get(1);  // Type: string | undefined
 
 ### ✨ Zero Friction
 
-Works everywhere. Spread it `[...]`, loop it `for..of`, convert it instantly.
+Works everywhere. Spread it `[...]`, loop it `for..of`, convert it instantly. Pass raw data with `toEntryFn`/`toElementFn` — no pre-processing needed.
 
 ```javascript
 // All data structures work with iterator protocol
@@ -224,8 +225,51 @@ const sorted = [...tree];              // Spread operator
 for (const item of tree) {
 }           // for...of loop
 const set = new Set(tree);             // Set constructor
+
+// Pass raw data directly
+const map = new TreeMap(users, { toEntryFn: u => [u.id, u.name] });
 ```
 
+### 🔄 Working with Raw Data
+
+Got raw objects? Three ways to use them — pick based 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 — store only that field
+const ids = new TreeSet<number, User>(
+  users,
+  { toElementFn: u => u.id }
+);
+// [1, 2, 3] — numbers only, original objects not kept
+
+// 2. Store full objects — sort by a field
+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 — field as key, anything as value
+const map = new TreeMap<number, User, User>(
+  users,
+  { toEntryFn: u => [u.id, u] }
+);
+// map.get(1) → { id: 1, name: 'Alice' }
+```
+
+Works across all data structures — `toElementFn` for single-value types (Heap, Queue, Stack, LinkedList, Trie), `toEntryFn` for key-value types (TreeMap, HashMap, SkipList), and `comparator` for any sorted structure.
+
 ---
 
 ## 💡 When Should I Consider This Library?
@@ -237,6 +281,7 @@ const set = new Set(tree);             // Set constructor
 - Priority queues with fast position-based access
 - Time-series data with range queries
 - Red-Black Tree / Heap performance without learning new APIs
+- **Pass raw objects directly** — no `.map()` pre-processing needed (unique to this library in JS/TS)
 
 ✅ **When your current code has:**
 
@@ -245,6 +290,7 @@ const set = new Set(tree);             // Set constructor
 - `Array.shift()` on large lists (queues)
 - Custom sorting logic you repeat across files
 - Map that needs to be ordered
+- `.map()` calls just to reshape data before putting it in a collection
 
 ---
 
@@ -262,29 +308,43 @@ const leaderboard = new RedBlackTree<number, string>([
   [92, 'Charlie']
 ], { comparator: (a, b) => b - a });
 
-// Top-2 via lazy iterator — O(2 log n), no full traversal
+// Top-2 via lazy iterator — O(k log n), no array copy
 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
+const { value: [topScore, topPlayer] } = iter.next();
+console.log(`${topScore}: ${topPlayer}`); // 100: Alice
 
 // Update score — O(log n)
 leaderboard.delete(85);
 leaderboard.set(95, 'Bob');
 
-// Top-k — O(k log n), no array copy needed
-const top3: [number, string][] = [];
-let score = leaderboard.getLeftMost();        // highest score
-while (score !== undefined && top3.length < 3) {
-  top3.push([score, leaderboard.get(score)!]);
-  score = leaderboard.higher(score);          // next in tree order
-}
-
 // Range query — players scoring 90~100, O(log n + k)
 const scores90to100 = leaderboard.rangeSearch([90, 100]);
 // [100, 95, 92] — automatically respects tree order
+
+// For O(log n) top-k, rank, and pagination → see Order-Statistic Tree below
+```
+
+### Order-Statistic Tree (Rank Queries)
+
+```typescript
+import { RedBlackTree } from 'data-structure-typed';
+
+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, O(log n)
+tree.getByRank(0);              // 100 (1st in tree order)
+tree.getByRank(2);              // 92  (3rd in tree order)
+
+// rank(key) — count elements preceding key in tree order, O(log n)
+tree.getRank(92);               // 2 (2 elements before 92 in tree order)
+
+// rangeByRank — pagination, O(log n + k)
+tree.rangeByRank(0, 2);      // [100, 95, 92] — top 3
+
+// Also works with TreeMap, TreeSet, TreeMultiMap, TreeMultiSet
 ```
 
 ### Task Queue (Scheduling)
@@ -299,7 +359,7 @@ const taskQueue = new MaxPriorityQueue<{priority: number; task: string}>([], {
 taskQueue.add({ priority: 5, task: 'Email' });
 taskQueue.add({ priority: 9, task: 'Alert' });  // Instant priority handling
 
-const nextTask = taskQueue.poll();  // { priority: 9, task: 'Alert' }
+const nextTask = taskQueue.pop();  // { priority: 9, task: 'Alert' }
 ```
 
 ### Fast Queue (FIFO)
@@ -646,3 +706,55 @@ docs/
 ---
 
 **Ready to supercharge your TypeScript data structures? [Get started now →](#-quick-start-30-seconds)**
+
+---
+
+## ❓ FAQ
+
+### Does JavaScript have a TreeMap or TreeSet?
+
+Not natively. JavaScript's `Map` and `Set` are hash-based (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.
+
+### 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; a Heap gives you O(log n) insert and O(1) access to the top element. Use `Heap`, `MinHeap`, or `MaxHeap` for priority queues, top-k problems, and scheduling.
+
+### Does this library support rank and range queries?
+
+Yes. Enable with `{ enableOrderStatistic: true }` on any tree-based structure (RedBlackTree, TreeMap, TreeSet, etc.):
+- `getRank(key)` — how many elements precede this key in tree order
+- `getByRank(k)` — get the element at position k
+- `rangeByRank(start, end)` — get all elements between two positions
+
+### Is it faster than native arrays for ordered operations?
+
+For ordered insert + lookup: yes. Array insert into sorted position is O(n) (shift elements). Red-Black Tree insert is O(log n). For 10,000+ elements, the difference is significant. See [PERFORMANCE.md](./docs/PERFORMANCE.md) for benchmarks.
+
+### Can I use this in React / Node.js / browser?
+
+Yes. The library ships ESM, CJS, and UMD builds. It works in Node.js, browsers, React, Vue, Angular, Next.js, and any JavaScript runtime. Zero dependencies means no compatibility concerns.
+
+### What data structures are included?
+
+Heap, MinHeap, MaxHeap, Priority Queue, Deque, Queue, Stack, Linked List (Singly / Doubly), Red-Black Tree, AVL Tree, BST, TreeMap, TreeSet, TreeMultiMap, TreeMultiSet, SkipList, Trie, HashMap, Graph (Directed / Undirected), Segment Tree, Binary Indexed Tree (Fenwick Tree), Matrix. See [full list](#-data-structures-available).
+
+### Is this library production-ready?
+
+Yes. 2600+ tests, 99%+ code coverage, zero dependencies, and used in production. Every release passes typecheck, lint, and full test suite.
+
+### How does this compare to js-sdsl or other libraries?
+
+`data-structure-typed` offers more data structures (20+), a unified Array-like API across all structures, tree-shakeable subpath exports, and active maintenance. See [PERFORMANCE.md](./docs/PERFORMANCE.md) for benchmark comparisons.
+
+### Can I pass raw data without converting it first?
+
+Yes. Three patterns:
+- **`toElementFn`** — extract a field, store only that (TreeSet, Heap, Queue, Stack, LinkedList, Trie)
+- **`comparator`** — store full objects, sort by a field (all sorted structures)
+- **`toEntryFn`** — split into key-value pairs (TreeMap, HashMap, SkipList)
+
+See the [Raw Data section](#-working-with-raw-data) for examples.
+
+### What is the bundle size?
+
+UMD bundle: ~143KB minified. With subpath imports (e.g., `data-structure-typed/heap`), you only load what you use — as small as 18KB for Stack, 30KB for Heap. `sideEffects: false` enables full tree-shaking.