MIGRATION.md

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.

// 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.

// 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[]

// 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().

// 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

// 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().

// 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().

// 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()

// Deprecated
const top = heap.poll();

// Preferred
const top = heap.pop();

Heap.deleteBy() → use Heap.deleteWhere()

// Deprecated
heap.deleteBy(e => e.id === 42);

// Preferred
heap.deleteWhere(e => e.id === 42);

DoublyLinkedList.getBackward() → use findLast()

// 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:

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

// 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+)

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

// 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.

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()).

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