data-structure-typed 2.5.0 → 2.5.2

package/docs-site-docusaurus/docs/api/classes/PriorityQueue.md

@@ -0,0 +1,1839 @@
+[**data-structure-typed**](../README.md)
+
+***
+
+[data-structure-typed](../README.md) / PriorityQueue
+
+# Class: PriorityQueue\<E, R\>
+
+Defined in: [data-structures/priority-queue/priority-queue.ts:75](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/priority-queue/priority-queue.ts#L75)
+
+## Examples
+
+```ts
+// Hospital emergency room triage
+ interface Patient {
+      name: string;
+      severity: number; // 1 = critical, 5 = minor
+    }
+
+    const er = new PriorityQueue<Patient>([], {
+      comparator: (a, b) => a.severity - b.severity
+    });
+
+    er.add({ name: 'Flu symptoms', severity: 4 });
+    er.add({ name: 'Heart attack', severity: 1 });
+    er.add({ name: 'Broken arm', severity: 3 });
+    er.add({ name: 'Stroke', severity: 1 });
+
+    // Most critical patients first
+    console.log(er.poll()?.severity); // 1;
+    console.log(er.poll()?.severity); // 1;
+    console.log(er.poll()?.severity); // 3;
+    console.log(er.poll()?.severity); // 4;
+```
+
+```ts
+// Task scheduler with deadlines
+ interface Task {
+      name: string;
+      deadline: number; // hours until due
+    }
+
+    const scheduler = new PriorityQueue<Task>([], {
+      comparator: (a, b) => a.deadline - b.deadline
+    });
+
+    scheduler.add({ name: 'Report', deadline: 24 });
+    scheduler.add({ name: 'Email', deadline: 2 });
+    scheduler.add({ name: 'Meeting prep', deadline: 4 });
+    scheduler.add({ name: 'Code review', deadline: 8 });
+
+    // Process most urgent first
+    console.log(scheduler.peek()?.name); // 'Email';
+    console.log(scheduler.size); // 4;
+
+    const order = [];
+    while (scheduler.size > 0) {
+      order.push(scheduler.poll()!.name);
+    }
+    console.log(order); // ['Email', 'Meeting prep', 'Code review', 'Report'];
+```
+
+```ts
+// Bandwidth allocation with priorities
+ const bandwidth = new PriorityQueue<[number, string]>([], {
+      comparator: (a, b) => a[0] - b[0]
+    });
+
+    bandwidth.add([1, 'Video call']);     // highest priority
+    bandwidth.add([3, 'File download']);
+    bandwidth.add([2, 'Web browsing']);
+    bandwidth.add([1, 'Voice call']);
+
+    // Allocate bandwidth to highest priority first
+    console.log(bandwidth.poll()?.[1]); // 'Video call';
+    console.log(bandwidth.poll()?.[1]); // 'Voice call';
+    console.log(bandwidth.size); // 2;
+```
+
+## Extends
+
+- [`Heap`](Heap.md)\<`E`, `R`\>
+
+## Extended by
+
+- [`MinPriorityQueue`](MinPriorityQueue.md)
+- [`MaxPriorityQueue`](MaxPriorityQueue.md)
+
+## Type Parameters
+
+### E
+
+`E` = `any`
+
+### R
+
+`R` = `any`
+
+## Properties
+
+### comparator
+
+#### Get Signature
+
+```ts
+get comparator(): Comparator<E>;
+```
+
+Defined in: [data-structures/heap/heap.ts:1184](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/heap/heap.ts#L1184)
+
+Get the comparator used to order elements.
+
+##### Remarks
+
+Time O(1), Space O(1)
+
+##### Returns
+
+`Comparator`\<`E`\>
+
+Comparator function.
+
+#### Inherited from
+
+[`Heap`](Heap.md).[`comparator`](Heap.md#comparator)
+
+***
+
+### elements
+
+#### Get Signature
+
+```ts
+get elements(): E[];
+```
+
+Defined in: [data-structures/heap/heap.ts:180](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/heap/heap.ts#L180)
+
+Get the backing array of the heap.
+
+##### Remarks
+
+Time O(1), Space O(1)
+
+##### Returns
+
+`E`[]
+
+Internal elements array.
+
+#### Inherited from
+
+[`Heap`](Heap.md).[`elements`](Heap.md#elements)
+
+***
+
+### leaf
+
+#### Get Signature
+
+```ts
+get leaf(): E | undefined;
+```
+
+Defined in: [data-structures/heap/heap.ts:244](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/heap/heap.ts#L244)
+
+Get the last leaf element.
+
+##### Remarks
+
+Time O(1), Space O(1)
+
+##### Returns
+
+`E` \| `undefined`
+
+Last element or undefined.
+
+#### Inherited from
+
+[`Heap`](Heap.md).[`leaf`](Heap.md#leaf)
+
+***
+
+### size
+
+#### Get Signature
+
+```ts
+get size(): number;
+```
+
+Defined in: [data-structures/heap/heap.ts:234](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/heap/heap.ts#L234)
+
+Get the number of elements.
+
+##### Remarks
+
+Time O(1), Space O(1)
+
+##### Example
+
+```ts
+// Track heap capacity
+ const heap = new Heap<number>();
+    console.log(heap.size); // 0;
+    heap.add(10);
+    heap.add(20);
+    console.log(heap.size); // 2;
+    heap.poll();
+    console.log(heap.size); // 1;
+```
+
+##### Returns
+
+`number`
+
+Heap size.
+
+ *
+
+#### Inherited from
+
+[`Heap`](Heap.md).[`size`](Heap.md#size)
+
+***
+
+### toElementFn
+
+#### Get Signature
+
+```ts
+get toElementFn(): ((rawElement) => E) | undefined;
+```
+
+Defined in: [data-structures/base/iterable-element-base.ts:48](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/base/iterable-element-base.ts#L48)
+
+Exposes the current `toElementFn`, if configured.
+
+##### Remarks
+
+Time O(1), Space O(1).
+
+##### Returns
+
+((`rawElement`) => `E`) \| `undefined`
+
+The converter function or `undefined` when not set.
+
+#### Inherited from
+
+[`Heap`](Heap.md).[`toElementFn`](Heap.md#toelementfn)
+
+## Methods
+
+### \[iterator\]()
+
+```ts
+iterator: IterableIterator<E>;
+```
+
+Defined in: [data-structures/base/iterable-element-base.ts:61](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/base/iterable-element-base.ts#L61)
+
+Returns an iterator over the structure's elements.
+
+#### Parameters
+
+##### args
+
+...`unknown`[]
+
+Optional iterator arguments forwarded to the internal iterator.
+
+#### Returns
+
+`IterableIterator`\<`E`\>
+
+An `IterableIterator<E>` that yields the elements in traversal order.
+
+#### Remarks
+
+Producing the iterator is O(1); consuming the entire iterator is Time O(n) with O(1) extra space.
+
+#### Inherited from
+
+[`Heap`](Heap.md).[`[iterator]`](Heap.md#iterator)
+
+***
+
+### add()
+
+```ts
+add(element): boolean;
+```
+
+Defined in: [data-structures/heap/heap.ts:338](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/heap/heap.ts#L338)
+
+Insert an element.
+
+#### Parameters
+
+##### element
+
+`E`
+
+Element to insert.
+
+#### Returns
+
+`boolean`
+
+True.
+
+ *
+
+#### Remarks
+
+Time O(1) amortized, Space O(1)
+
+#### Example
+
+```ts
+// basic Heap creation and add operation
+ // Create a min heap (default)
+    const minHeap = new Heap([5, 3, 7, 1, 9, 2]);
+
+    // Verify size
+    console.log(minHeap.size); // 6;
+
+    // Add new element
+    minHeap.add(4);
+    console.log(minHeap.size); // 7;
+
+    // Min heap property: smallest element at root
+    const min = minHeap.peek();
+    console.log(min); // 1;
+```
+
+#### Inherited from
+
+[`Heap`](Heap.md).[`add`](Heap.md#add)
+
+***
+
+### addMany()
+
+```ts
+addMany(elements): boolean[];
+```
+
+Defined in: [data-structures/heap/heap.ts:388](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/heap/heap.ts#L388)
+
+Insert many elements from an iterable.
+
+#### Parameters
+
+##### elements
+
+`Iterable`\<`E` \| `R`\>
+
+Iterable of elements or raw values.
+
+#### Returns
+
+`boolean`[]
+
+Array of per-element success flags.
+
+ *
+
+#### Remarks
+
+Time O(N log N), Space O(1)
+
+#### Example
+
+```ts
+// Add multiple elements
+ const heap = new Heap<number>([], { comparator: (a, b) => a - b });
+    heap.addMany([5, 3, 7, 1]);
+    console.log(heap.peek()); // 1;
+    console.log(heap.size); // 4;
+```
+
+#### Inherited from
+
+[`Heap`](Heap.md).[`addMany`](Heap.md#addmany)
+
+***
+
+### clear()
+
+```ts
+clear(): void;
+```
+
+Defined in: [data-structures/heap/heap.ts:676](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/heap/heap.ts#L676)
+
+Remove all elements.
+
+#### Returns
+
+`void`
+
+void
+
+ *
+
+#### Remarks
+
+Time O(1), Space O(1)
+
+#### Example
+
+```ts
+// Remove all elements
+ const heap = new Heap<number>([1, 2, 3], { comparator: (a, b) => a - b });
+    heap.clear();
+    console.log(heap.isEmpty()); // true;
+```
+
+#### Inherited from
+
+[`Heap`](Heap.md).[`clear`](Heap.md#clear)
+
+***
+
+### clone()
+
+```ts
+clone(): this;
+```
+
+Defined in: [data-structures/heap/heap.ts:1020](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/heap/heap.ts#L1020)
+
+Deep clone this heap.
+
+#### Returns
+
+`this`
+
+A new heap with the same elements.
+
+ *
+
+#### Remarks
+
+Time O(N), Space O(N)
+
+#### Example
+
+```ts
+// Create independent copy
+ const heap = new Heap<number>([3, 1, 4], { comparator: (a, b) => a - b });
+    const copy = heap.clone();
+    copy.poll();
+    console.log(heap.size); // 3;
+    console.log(copy.size); // 2;
+```
+
+#### Inherited from
+
+[`Heap`](Heap.md).[`clone`](Heap.md#clone)
+
+***
+
+### delete()
+
+```ts
+delete(element): boolean;
+```
+
+Defined in: [data-structures/heap/heap.ts:779](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/heap/heap.ts#L779)
+
+Delete one occurrence of an element.
+
+#### Parameters
+
+##### element
+
+`E`
+
+Element to delete.
+
+#### Returns
+
+`boolean`
+
+True if an element was removed.
+
+ *
+
+#### Remarks
+
+Time O(N), Space O(1)
+
+#### Example
+
+```ts
+// Remove specific element
+ const heap = new Heap<number>([3, 1, 4, 1, 5], { comparator: (a, b) => a - b });
+    heap.delete(4);
+    console.log(heap.toArray().includes(4)); // false;
+```
+
+#### Inherited from
+
+[`Heap`](Heap.md).[`delete`](Heap.md#delete)
+
+***
+
+### deleteBy()
+
+```ts
+deleteBy(predicate): boolean;
+```
+
+Defined in: [data-structures/heap/heap.ts:807](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/heap/heap.ts#L807)
+
+Delete the first element that matches a predicate.
+
+#### Parameters
+
+##### predicate
+
+(`element`, `index`, `heap`) => `boolean`
+
+Function (element, index, heap) → boolean.
+
+#### Returns
+
+`boolean`
+
+True if an element was removed.
+
+#### Remarks
+
+Time O(N), Space O(1)
+
+#### Inherited from
+
+[`Heap`](Heap.md).[`deleteBy`](Heap.md#deleteby)
+
+***
+
+### dfs()
+
+```ts
+dfs(order?): E[];
+```
+
+Defined in: [data-structures/heap/heap.ts:878](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/heap/heap.ts#L878)
+
+Traverse the binary heap as a complete binary tree and collect elements.
+
+#### Parameters
+
+##### order?
+
+`DFSOrderPattern` = `'PRE'`
+
+Traversal order: 'PRE' | 'IN' | 'POST'.
+
+#### Returns
+
+`E`[]
+
+Array of visited elements.
+
+ *
+
+#### Remarks
+
+Time O(N), Space O(H)
+
+#### Example
+
+```ts
+// Depth-first traversal
+ const heap = new Heap<number>([3, 1, 2], { comparator: (a, b) => a - b });
+    const result = heap.dfs('IN');
+    console.log(result.length); // 3;
+```
+
+#### Inherited from
+
+[`Heap`](Heap.md).[`dfs`](Heap.md#dfs)
+
+***
+
+### every()
+
+```ts
+every(predicate, thisArg?): boolean;
+```
+
+Defined in: [data-structures/base/iterable-element-base.ts:87](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/base/iterable-element-base.ts#L87)
+
+Tests whether all elements satisfy the predicate.
+
+#### Parameters
+
+##### predicate
+
+`ElementCallback`\<`E`, `R`, `boolean`\>
+
+Function invoked for each element with signature `(value, index, self)`.
+
+##### thisArg?
+
+`unknown`
+
+Optional `this` binding for the predicate.
+
+#### Returns
+
+`boolean`
+
+`true` if every element passes; otherwise `false`.
+
+#### Remarks
+
+Time O(n) in the worst case; may exit early when the first failure is found. Space O(1).
+
+#### Inherited from
+
+[`Heap`](Heap.md).[`every`](Heap.md#every)
+
+***
+
+### filter()
+
+```ts
+filter(callback, thisArg?): this;
+```
+
+Defined in: [data-structures/heap/heap.ts:1072](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/heap/heap.ts#L1072)
+
+Filter elements into a new heap of the same class.
+
+#### Parameters
+
+##### callback
+
+`ElementCallback`\<`E`, `R`, `boolean`\>
+
+Predicate (element, index, heap) → boolean to keep element.
+
+##### thisArg?
+
+`unknown`
+
+Value for `this` inside the callback.
+
+#### Returns
+
+`this`
+
+A new heap with the kept elements.
+
+ *
+
+#### Remarks
+
+Time O(N log N), Space O(N)
+
+#### Example
+
+```ts
+// Filter elements
+ const heap = new Heap<number>([1, 2, 3, 4, 5], { comparator: (a, b) => a - b });
+    const evens = heap.filter(x => x % 2 === 0);
+    console.log(evens.size); // 2;
+```
+
+#### Inherited from
+
+[`Heap`](Heap.md).[`filter`](Heap.md#filter)
+
+***
+
+### find()
+
+#### Call Signature
+
+```ts
+find<S>(predicate, thisArg?): S | undefined;
+```
+
+Defined in: [data-structures/base/iterable-element-base.ts:163](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/base/iterable-element-base.ts#L163)
+
+Finds the first element that satisfies the predicate and returns it.
+
+Finds the first element of type `S` (a subtype of `E`) that satisfies the predicate and returns it.
+
+##### Type Parameters
+
+###### S
+
+`S`
+
+##### Parameters
+
+###### predicate
+
+`ElementCallback`\<`E`, `R`, `S`\>
+
+Type-guard predicate: `(value, index, self) => value is S`.
+
+###### thisArg?
+
+`unknown`
+
+Optional `this` binding for the predicate.
+
+##### Returns
+
+`S` \| `undefined`
+
+The matched element typed as `S`, or `undefined` if not found.
+
+##### Remarks
+
+Time O(n) in the worst case; may exit early on the first match. Space O(1).
+
+##### Inherited from
+
+[`Heap`](Heap.md).[`find`](Heap.md#find)
+
+#### Call Signature
+
+```ts
+find(predicate, thisArg?): E | undefined;
+```
+
+Defined in: [data-structures/base/iterable-element-base.ts:164](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/base/iterable-element-base.ts#L164)
+
+Finds the first element that satisfies the predicate and returns it.
+
+Finds the first element of type `S` (a subtype of `E`) that satisfies the predicate and returns it.
+
+##### Parameters
+
+###### predicate
+
+`ElementCallback`\<`E`, `R`, `unknown`\>
+
+Type-guard predicate: `(value, index, self) => value is S`.
+
+###### thisArg?
+
+`unknown`
+
+Optional `this` binding for the predicate.
+
+##### Returns
+
+`E` \| `undefined`
+
+The matched element typed as `S`, or `undefined` if not found.
+
+##### Remarks
+
+Time O(n) in the worst case; may exit early on the first match. Space O(1).
+
+##### Inherited from
+
+[`Heap`](Heap.md).[`find`](Heap.md#find)
+
+***
+
+### fix()
+
+```ts
+fix(): boolean[];
+```
+
+Defined in: [data-structures/heap/heap.ts:909](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/heap/heap.ts#L909)
+
+Restore heap order bottom-up (heapify in-place).
+
+#### Returns
+
+`boolean`[]
+
+Array of per-node results from fixing steps.
+
+#### Remarks
+
+Time O(N), Space O(1)
+
+#### Inherited from
+
+[`Heap`](Heap.md).[`fix`](Heap.md#fix)
+
+***
+
+### forEach()
+
+```ts
+forEach(callbackfn, thisArg?): void;
+```
+
+Defined in: [data-structures/base/iterable-element-base.ts:133](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/base/iterable-element-base.ts#L133)
+
+Invokes a callback for each element in iteration order.
+
+#### Parameters
+
+##### callbackfn
+
+`ElementCallback`\<`E`, `R`, `void`\>
+
+Function invoked per element with signature `(value, index, self)`.
+
+##### thisArg?
+
+`unknown`
+
+Optional `this` binding for the callback.
+
+#### Returns
+
+`void`
+
+`void`.
+
+#### Remarks
+
+Time O(n), Space O(1).
+
+#### Inherited from
+
+[`Heap`](Heap.md).[`forEach`](Heap.md#foreach)
+
+***
+
+### has()
+
+```ts
+has(element): boolean;
+```
+
+Defined in: [data-structures/heap/heap.ts:730](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/heap/heap.ts#L730)
+
+Check if an equal element exists in the heap.
+
+#### Parameters
+
+##### element
+
+`E`
+
+Element to search for.
+
+#### Returns
+
+`boolean`
+
+True if found.
+
+ *
+
+#### Remarks
+
+Time O(N), Space O(1)
+
+#### Example
+
+```ts
+// Check element existence
+ const heap = new Heap<number>([3, 1, 2], { comparator: (a, b) => a - b });
+    console.log(heap.has(1)); // true;
+    console.log(heap.has(99)); // false;
+```
+
+#### Inherited from
+
+[`Heap`](Heap.md).[`has`](Heap.md#has)
+
+***
+
+### isEmpty()
+
+```ts
+isEmpty(): boolean;
+```
+
+Defined in: [data-structures/heap/heap.ts:628](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/heap/heap.ts#L628)
+
+Check whether the heap is empty.
+
+#### Returns
+
+`boolean`
+
+True if size is 0.
+
+ *
+
+#### Remarks
+
+Time O(1), Space O(1)
+
+#### Example
+
+```ts
+// Check if heap is empty
+ const heap = new Heap<number>([], { comparator: (a, b) => a - b });
+    console.log(heap.isEmpty()); // true;
+    heap.add(1);
+    console.log(heap.isEmpty()); // false;
+```
+
+#### Inherited from
+
+[`Heap`](Heap.md).[`isEmpty`](Heap.md#isempty)
+
+***
+
+### map()
+
+```ts
+map<EM, RM>(
+   callback, 
+   options, 
+thisArg?): Heap<EM, RM>;
+```
+
+Defined in: [data-structures/heap/heap.ts:1133](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/heap/heap.ts#L1133)
+
+Map elements into a new heap of possibly different element type.
+
+#### Type Parameters
+
+##### EM
+
+`EM`
+
+##### RM
+
+`RM`
+
+#### Parameters
+
+##### callback
+
+`ElementCallback`\<`E`, `R`, `EM`\>
+
+Mapping function (element, index, heap) → newElement.
+
+##### options
+
+`IterableElementBaseOptions`\<`EM`, `RM`\> & `object` & `object`
+
+Options for the output heap, including comparator for EM.
+
+##### thisArg?
+
+`unknown`
+
+Value for `this` inside the callback.
+
+#### Returns
+
+[`Heap`](Heap.md)\<`EM`, `RM`\>
+
+A new heap with mapped elements.
+
+ *
+
+#### Remarks
+
+Time O(N log N), Space O(N)
+
+#### Example
+
+```ts
+// Transform elements
+ const heap = new Heap<number>([1, 2, 3], { comparator: (a, b) => a - b });
+    const doubled = heap.map(x => x * 2, { comparator: (a, b) => a - b });
+    console.log(doubled.peek()); // 2;
+```
+
+#### Inherited from
+
+[`Heap`](Heap.md).[`map`](Heap.md#map)
+
+***
+
+### mapSame()
+
+```ts
+mapSame(callback, thisArg?): this;
+```
+
+Defined in: [data-structures/heap/heap.ts:1157](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/heap/heap.ts#L1157)
+
+Map elements into a new heap of the same element type.
+
+#### Parameters
+
+##### callback
+
+`ElementCallback`\<`E`, `R`, `E`\>
+
+Mapping function (element, index, heap) → element.
+
+##### thisArg?
+
+`unknown`
+
+Value for `this` inside the callback.
+
+#### Returns
+
+`this`
+
+A new heap with mapped elements.
+
+#### Remarks
+
+Time O(N log N), Space O(N)
+
+#### Inherited from
+
+[`Heap`](Heap.md).[`mapSame`](Heap.md#mapsame)
+
+***
+
+### peek()
+
+```ts
+peek(): E | undefined;
+```
+
+Defined in: [data-structures/heap/heap.ts:579](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/heap/heap.ts#L579)
+
+Get the current top element without removing it.
+
+#### Returns
+
+`E` \| `undefined`
+
+Top element or undefined.
+
+ *
+
+#### Remarks
+
+Time O(1), Space O(1)
+
+#### Example
+
+```ts
+// Heap for event processing with priority
+ interface Event {
+      id: number;
+      type: 'critical' | 'warning' | 'info';
+      timestamp: number;
+      message: string;
+    }
+
+    // Custom priority: critical > warning > info
+    const priorityMap = { critical: 3, warning: 2, info: 1 };
+
+    const eventHeap = new Heap<Event>([], {
+      comparator: (a: Event, b: Event) => {
+        const priorityA = priorityMap[a.type];
+        const priorityB = priorityMap[b.type];
+        return priorityB - priorityA; // Higher priority first
+      }
+    });
+
+    // Add events in random order
+    eventHeap.add({ id: 1, type: 'info', timestamp: 100, message: 'User logged in' });
+    eventHeap.add({ id: 2, type: 'critical', timestamp: 101, message: 'Server down' });
+    eventHeap.add({ id: 3, type: 'warning', timestamp: 102, message: 'High memory' });
+    eventHeap.add({ id: 4, type: 'info', timestamp: 103, message: 'Cache cleared' });
+    eventHeap.add({ id: 5, type: 'critical', timestamp: 104, message: 'Database error' });
+
+    console.log(eventHeap.size); // 5;
+
+    // Process events by priority (critical first)
+    const processedOrder: Event[] = [];
+    while (eventHeap.size > 0) {
+      const event = eventHeap.poll();
+      if (event) {
+        processedOrder.push(event);
+      }
+    }
+
+    // Verify critical events came first
+    console.log(processedOrder[0].type); // 'critical';
+    console.log(processedOrder[1].type); // 'critical';
+    console.log(processedOrder[2].type); // 'warning';
+    console.log(processedOrder[3].type); // 'info';
+    console.log(processedOrder[4].type); // 'info';
+
+    // Verify O(log n) operations
+    const newHeap = new Heap<number>([5, 3, 7, 1]);
+
+    // Add - O(log n)
+    newHeap.add(2);
+    console.log(newHeap.size); // 5;
+
+    // Poll - O(log n)
+    const removed = newHeap.poll();
+    console.log(removed); // 1;
+
+    // Peek - O(1)
+    const top = newHeap.peek();
+    console.log(top); // 2;
+```
+
+#### Inherited from
+
+[`Heap`](Heap.md).[`peek`](Heap.md#peek)
+
+***
+
+### poll()
+
+```ts
+poll(): E | undefined;
+```
+
+Defined in: [data-structures/heap/heap.ts:468](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/heap/heap.ts#L468)
+
+Remove and return the top element.
+
+#### Returns
+
+`E` \| `undefined`
+
+Top element or undefined.
+
+ *
+
+#### Remarks
+
+Time O(log N), Space O(1)
+
+#### Example
+
+```ts
+// Heap with custom comparator (MaxHeap behavior)
+ interface Task {
+      id: number;
+      priority: number;
+      name: string;
+    }
+
+    // Custom comparator for max heap behavior (higher priority first)
+    const tasks: Task[] = [
+      { id: 1, priority: 5, name: 'Email' },
+      { id: 2, priority: 3, name: 'Chat' },
+      { id: 3, priority: 8, name: 'Alert' }
+    ];
+
+    const maxHeap = new Heap(tasks, {
+      comparator: (a: Task, b: Task) => b.priority - a.priority
+    });
+
+    console.log(maxHeap.size); // 3;
+
+    // Peek returns highest priority task
+    const topTask = maxHeap.peek();
+    console.log(topTask?.priority); // 8;
+    console.log(topTask?.name); // 'Alert';
+```
+
+#### Inherited from
+
+[`Heap`](Heap.md).[`poll`](Heap.md#poll)
+
+***
+
+### print()
+
+```ts
+print(): void;
+```
+
+Defined in: [data-structures/base/iterable-element-base.ts:269](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/base/iterable-element-base.ts#L269)
+
+Prints `toVisual()` to the console. Intended for quick debugging.
+
+#### Returns
+
+`void`
+
+`void`.
+
+#### Remarks
+
+Time O(n) due to materialization, Space O(n) for the intermediate representation.
+
+#### Inherited from
+
+[`Heap`](Heap.md).[`print`](Heap.md#print)
+
+***
+
+### reduce()
+
+Reduces all elements to a single accumulated value.
+
+#### Param
+
+Reducer of signature `(acc, value, index, self) => nextAcc`. The first element is used as the initial accumulator.
+
+#### Param
+
+Reducer of signature `(acc, value, index, self) => nextAcc`.
+
+#### Param
+
+The initial accumulator value of type `E`.
+
+#### Template
+
+The accumulator type when it differs from `E`.
+
+#### Param
+
+Reducer of signature `(acc: U, value, index, self) => U`.
+
+#### Param
+
+The initial accumulator value of type `U`.
+
+#### Remarks
+
+Time O(n), Space O(1). Throws if called on an empty structure without `initialValue`.
+
+#### Call Signature
+
+```ts
+reduce(callbackfn): E;
+```
+
+Defined in: [data-structures/base/iterable-element-base.ts:194](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/base/iterable-element-base.ts#L194)
+
+##### Parameters
+
+###### callbackfn
+
+`ReduceElementCallback`\<`E`, `R`\>
+
+##### Returns
+
+`E`
+
+##### Inherited from
+
+[`Heap`](Heap.md).[`reduce`](Heap.md#reduce)
+
+#### Call Signature
+
+```ts
+reduce(callbackfn, initialValue): E;
+```
+
+Defined in: [data-structures/base/iterable-element-base.ts:195](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/base/iterable-element-base.ts#L195)
+
+##### Parameters
+
+###### callbackfn
+
+`ReduceElementCallback`\<`E`, `R`\>
+
+###### initialValue
+
+`E`
+
+##### Returns
+
+`E`
+
+##### Inherited from
+
+[`Heap`](Heap.md).[`reduce`](Heap.md#reduce)
+
+#### Call Signature
+
+```ts
+reduce<U>(callbackfn, initialValue): U;
+```
+
+Defined in: [data-structures/base/iterable-element-base.ts:196](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/base/iterable-element-base.ts#L196)
+
+##### Type Parameters
+
+###### U
+
+`U`
+
+##### Parameters
+
+###### callbackfn
+
+`ReduceElementCallback`\<`E`, `R`, `U`\>
+
+###### initialValue
+
+`U`
+
+##### Returns
+
+`U`
+
+##### Inherited from
+
+[`Heap`](Heap.md).[`reduce`](Heap.md#reduce)
+
+***
+
+### refill()
+
+```ts
+refill(elements): boolean[];
+```
+
+Defined in: [data-structures/heap/heap.ts:687](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/heap/heap.ts#L687)
+
+Replace the backing array and rebuild the heap.
+
+#### Parameters
+
+##### elements
+
+`Iterable`\<`E`\>
+
+Iterable used to refill the heap.
+
+#### Returns
+
+`boolean`[]
+
+Array of per-node results from fixing steps.
+
+#### Remarks
+
+Time O(N), Space O(N)
+
+#### Inherited from
+
+[`Heap`](Heap.md).[`refill`](Heap.md#refill)
+
+***
+
+### setEquality()
+
+```ts
+setEquality(equals): this;
+```
+
+Defined in: [data-structures/heap/heap.ts:835](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/heap/heap.ts#L835)
+
+Set the equality comparator used by has/delete operations.
+
+#### Parameters
+
+##### equals
+
+(`a`, `b`) => `boolean`
+
+Equality predicate (a, b) → boolean.
+
+#### Returns
+
+`this`
+
+This heap.
+
+#### Remarks
+
+Time O(1), Space O(1)
+
+#### Inherited from
+
+[`Heap`](Heap.md).[`setEquality`](Heap.md#setequality)
+
+***
+
+### some()
+
+```ts
+some(predicate, thisArg?): boolean;
+```
+
+Defined in: [data-structures/base/iterable-element-base.ts:110](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/base/iterable-element-base.ts#L110)
+
+Tests whether at least one element satisfies the predicate.
+
+#### Parameters
+
+##### predicate
+
+`ElementCallback`\<`E`, `R`, `boolean`\>
+
+Function invoked for each element with signature `(value, index, self)`.
+
+##### thisArg?
+
+`unknown`
+
+Optional `this` binding for the predicate.
+
+#### Returns
+
+`boolean`
+
+`true` if any element passes; otherwise `false`.
+
+#### Remarks
+
+Time O(n) in the worst case; may exit early on first success. Space O(1).
+
+#### Inherited from
+
+[`Heap`](Heap.md).[`some`](Heap.md#some)
+
+***
+
+### sort()
+
+```ts
+sort(): E[];
+```
+
+Defined in: [data-structures/heap/heap.ts:963](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/heap/heap.ts#L963)
+
+Return all elements in ascending order by repeatedly polling.
+
+#### Returns
+
+`E`[]
+
+Sorted array of elements.
+
+ *
+
+#### Remarks
+
+Time O(N log N), Space O(N)
+
+#### Example
+
+```ts
+// Sort elements using heap
+ const heap = new Heap<number>([5, 1, 3, 2, 4]);
+    const sorted = heap.sort();
+    console.log(sorted); // [1, 2, 3, 4, 5];
+```
+
+#### Inherited from
+
+[`Heap`](Heap.md).[`sort`](Heap.md#sort)
+
+***
+
+### toArray()
+
+```ts
+toArray(): E[];
+```
+
+Defined in: [data-structures/base/iterable-element-base.ts:246](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/base/iterable-element-base.ts#L246)
+
+Materializes the elements into a new array.
+
+#### Returns
+
+`E`[]
+
+A shallow array copy of the iteration order.
+
+#### Remarks
+
+Time O(n), Space O(n).
+
+#### Inherited from
+
+[`Heap`](Heap.md).[`toArray`](Heap.md#toarray)
+
+***
+
+### toVisual()
+
+```ts
+toVisual(): E[];
+```
+
+Defined in: [data-structures/base/iterable-element-base.ts:258](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/base/iterable-element-base.ts#L258)
+
+Returns a representation of the structure suitable for quick visualization.
+Defaults to an array of elements; subclasses may override to provide richer visuals.
+
+#### Returns
+
+`E`[]
+
+A visual representation (array by default).
+
+#### Remarks
+
+Time O(n), Space O(n).
+
+#### Inherited from
+
+[`Heap`](Heap.md).[`toVisual`](Heap.md#tovisual)
+
+***
+
+### values()
+
+```ts
+values(): IterableIterator<E>;
+```
+
+Defined in: [data-structures/base/iterable-element-base.ts:72](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/base/iterable-element-base.ts#L72)
+
+Returns an iterator over the values (alias of the default iterator).
+
+#### Returns
+
+`IterableIterator`\<`E`\>
+
+An `IterableIterator<E>` over all elements.
+
+#### Remarks
+
+Creating the iterator is O(1); full iteration is Time O(n), Space O(1).
+
+#### Inherited from
+
+[`Heap`](Heap.md).[`values`](Heap.md#values)
+
+***
+
+### from()
+
+```ts
+static from<T, R, S>(
+   this, 
+   elements?, 
+   options?): S;
+```
+
+Defined in: [data-structures/heap/heap.ts:259](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/heap/heap.ts#L259)
+
+Create a heap of the same class from an iterable.
+
+#### Type Parameters
+
+##### T
+
+`T`
+
+##### R
+
+`R` = `any`
+
+##### S
+
+`S` *extends* [`Heap`](Heap.md)\<`T`, `R`\> = [`Heap`](Heap.md)\<`T`, `R`\>
+
+#### Parameters
+
+##### this
+
+`Object`
+
+##### elements?
+
+`Iterable`\<`T` \| `R`, `any`, `any`\>
+
+Iterable of elements or raw records.
+
+##### options?
+
+`HeapOptions`\<`T`, `R`\>
+
+Heap options including comparator.
+
+#### Returns
+
+`S`
+
+A new heap instance of this class.
+
+#### Remarks
+
+Time O(N), Space O(N)
+
+#### Inherited from
+
+[`Heap`](Heap.md).[`from`](Heap.md#from)
+
+***
+
+### heapify()
+
+```ts
+static heapify<EE, RR>(elements, options): Heap<EE, RR>;
+```
+
+Defined in: [data-structures/heap/heap.ts:277](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/heap/heap.ts#L277)
+
+Build a Heap from an iterable in linear time given a comparator.
+
+#### Type Parameters
+
+##### EE
+
+`EE` = `any`
+
+##### RR
+
+`RR` = `any`
+
+#### Parameters
+
+##### elements
+
+`Iterable`\<`EE`\>
+
+Iterable of elements.
+
+##### options
+
+`HeapOptions`\<`EE`, `RR`\>
+
+Heap options including comparator.
+
+#### Returns
+
+[`Heap`](Heap.md)\<`EE`, `RR`\>
+
+A new Heap built from elements.
+
+#### Remarks
+
+Time O(N), Space O(N)
+
+#### Inherited from
+
+[`Heap`](Heap.md).[`heapify`](Heap.md#heapify)
+
+
+---
+
+## Protected Members
+
+### \_toElementFn?
+
+```ts
+protected optional _toElementFn?: (rawElement) => E;
+```
+
+Defined in: [data-structures/base/iterable-element-base.ts:39](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/base/iterable-element-base.ts#L39)
+
+The converter used to transform a raw element (`R`) into a public element (`E`).
+
+#### Parameters
+
+##### rawElement
+
+`R`
+
+#### Returns
+
+`E`
+
+#### Remarks
+
+Time O(1), Space O(1).
+
+#### Inherited from
+
+[`Heap`](Heap.md).[`_toElementFn`](Heap.md#_toelementfn)
+
+## Accessors
+
+### \_createInstance()
+
+```ts
+protected _createInstance(options?): this;
+```
+
+Defined in: [data-structures/heap/heap.ts:1230](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/heap/heap.ts#L1230)
+
+(Protected) Create an empty instance of the same concrete class.
+
+#### Parameters
+
+##### options?
+
+`HeapOptions`\<`E`, `R`\>
+
+Options to override comparator or toElementFn.
+
+#### Returns
+
+`this`
+
+A like-kind empty heap instance.
+
+#### Remarks
+
+Time O(1), Space O(1)
+
+#### Inherited from
+
+[`Heap`](Heap.md).[`_createInstance`](Heap.md#_createinstance)
+
+***
+
+### \_createLike()
+
+```ts
+protected _createLike<EM, RM>(elements?, options?): Heap<EM, RM>;
+```
+
+Defined in: [data-structures/heap/heap.ts:1248](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/heap/heap.ts#L1248)
+
+(Protected) Create a like-kind instance seeded by elements.
+
+#### Type Parameters
+
+##### EM
+
+`EM`
+
+##### RM
+
+`RM`
+
+#### Parameters
+
+##### elements?
+
+`Iterable`\<`EM`, `any`, `any`\> \| `Iterable`\<`RM`, `any`, `any`\>
+
+Iterable of elements or raw values to seed.
+
+##### options?
+
+`HeapOptions`\<`EM`, `RM`\>
+
+Options forwarded to the constructor.
+
+#### Returns
+
+[`Heap`](Heap.md)\<`EM`, `RM`\>
+
+A like-kind heap instance.
+
+#### Remarks
+
+Time O(N log N), Space O(N)
+
+#### Inherited from
+
+[`Heap`](Heap.md).[`_createLike`](Heap.md#_createlike)
+
+***
+
+### \_getIterator()
+
+```ts
+protected _getIterator(): IterableIterator<E>;
+```
+
+Defined in: [data-structures/heap/heap.ts:1188](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/heap/heap.ts#L1188)
+
+Internal iterator factory used by the default iterator.
+
+#### Returns
+
+`IterableIterator`\<`E`\>
+
+An iterator over elements.
+
+#### Remarks
+
+Implementations should yield in O(1) per element with O(1) extra space when possible.
+
+#### Inherited from
+
+[`Heap`](Heap.md).[`_getIterator`](Heap.md#_getiterator)
+
+***
+
+### \_spawnLike()
+
+```ts
+protected _spawnLike<EM, RM>(options?): Heap<EM, RM>;
+```
+
+Defined in: [data-structures/heap/heap.ts:1268](https://github.com/zrwusa/data-structure-typed/blob/8292cb978daf85ebe846186c7c7572aece04fb7b/src/data-structures/heap/heap.ts#L1268)
+
+(Protected) Spawn an empty like-kind heap instance.
+
+#### Type Parameters
+
+##### EM
+
+`EM`
+
+##### RM
+
+`RM`
+
+#### Parameters
+
+##### options?
+
+`HeapOptions`\<`EM`, `RM`\>
+
+Options forwarded to the constructor.
+
+#### Returns
+
+[`Heap`](Heap.md)\<`EM`, `RM`\>
+
+An empty like-kind heap instance.
+
+#### Remarks
+
+Time O(1), Space O(1)
+
+#### Inherited from
+
+[`Heap`](Heap.md).[`_spawnLike`](Heap.md#_spawnlike)
+
+***