data-structure-typed 2.5.2 → 2.6.0

package/.husky/pre-commit

@@ -0,0 +1,3 @@
+#!/bin/sh
+echo "🔍 Pre-commit: check + lint + integration tests..."
+npm run check && npm run lint && npx jest --config jest.integration.config.js

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.6.0](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,217 @@
+# 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);
+```
+
+#### `DoublyLinkedList.getBackward()` → use `findLast()`
+
+```typescript
+// Deprecated
+list.getBackward(node => node.value > 5);
+
+// Preferred (aligns with ES2023 Array.findLast)
+list.findLast(node => node.value > 5);
+```
+
+---
+
+### New Features
+
+#### Array-Compatible APIs (v2.5.4+)
+
+All `IterableElementBase` containers (Queue, Deque, Stack, LinkedList, Heap, Trie) now support:
+
+```typescript
+structure.includes(element);    // alias for has()
+[...structure.entries()];       // [[0, val0], [1, val1], ...]
+[...structure.keys()];          // [0, 1, 2, ...]
+structure.toReversed();         // new instance, reversed (linear containers)
+```
+
+#### Back-to-Front Search (v2.5.4+)
+
+```typescript
+// Deque + DoublyLinkedList
+deque.findLast(v => v > 10);       // last matching value
+deque.findLastIndex(v => v > 10);  // last matching index, or -1
+```
+
+#### TreeSet ES2025 Set Operations (v2.5.4+)
+
+```typescript
+const a = new TreeSet([1, 2, 3, 4, 5]);
+const b = new TreeSet([3, 4, 5, 6, 7]);
+
+a.union(b);               // TreeSet [1,2,3,4,5,6,7]
+a.intersection(b);        // TreeSet [3,4,5]
+a.difference(b);          // TreeSet [1,2]
+a.symmetricDifference(b); // TreeSet [1,2,6,7]
+a.isSubsetOf(b);          // false
+a.isSupersetOf(b);        // false
+a.isDisjointFrom(b);      // false
+
+// Works with any Iterable
+a.union([10, 11]);
+a.intersection(new Set([2, 4]));
+```
+
+#### `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 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`).
+A production-ready TypeScript data structures library featuring **Heap, Linked List, Deque, Trie, Graph, Red-Black Tree, TreeMap, TreeSet, SkipList, Segment Tree**, and more — with APIs that align with JavaScript's native **Array, Map, and Set**. Zero dependencies. Type-safe. ES2025 Set operations. O(log n) rank & range queries.
 
-> **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.
+> **Looking for a TreeMap, TreeSet, or PriorityQueue in TypeScript/JavaScript?** Familiar API, set operations, rank queries, sorted access — no more repeated `Array.sort()`.
 
 ![npm](https://img.shields.io/npm/dm/data-structure-typed)
 ![GitHub contributors](https://img.shields.io/github/contributors/zrwusa/data-structure-typed)
@@ -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,25 @@ 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' }
+```
+
+### Set Operations (ES2025)
+
+```typescript
+import { TreeSet } from 'data-structure-typed';
+
+const a = new TreeSet([1, 2, 3, 4, 5]);
+const b = new TreeSet([3, 4, 5, 6, 7]);
+
+[...a.union(b)];               // [1,2,3,4,5,6,7]
+[...a.intersection(b)];        // [3,4,5]
+[...a.difference(b)];          // [1,2]
+[...a.symmetricDifference(b)]; // [1,2,6,7]
+a.isSubsetOf(b);               // false
+
+// Works with any Iterable — native Set, arrays, generators
+a.intersection(new Set([2, 4, 6]));  // TreeSet [2, 4]
 ```
 
 ### Fast Queue (FIFO)
@@ -701,6 +764,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.