data-structure-typed 2.5.2 → 2.5.3

package/CHANGELOG.md

@@ -8,7 +8,9 @@ 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.2](https://github.com/zrwusa/data-structure-typed/compare/v2.5.1...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)
 

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

@@ -83,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)
 
 ---
 
@@ -216,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
@@ -225,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?
@@ -238,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:**
 
@@ -246,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
 
 ---
 
@@ -314,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)
@@ -701,6 +746,15 @@ Yes. 2600+ tests, 99%+ code coverage, zero dependencies, and used in production.
 
 `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.