heap-typed 1.53.2 → 1.53.4

package/README.md

@@ -39,61 +39,163 @@ Max Heap
 
 ### snippet
 
-#### TS
+#### heap sort TS
 
 ```typescript
-    import {MinHeap, MaxHeap} from 'data-structure-typed';
-    // /* or if you prefer */ import {MinHeap, MaxHeap} from 'heap-typed';
-
-    const minNumHeap = new MinHeap<number>([1, 6, 2, 0, 5]);
-    minNumHeap.add(9);
-    minNumHeap.has(1)        //  true
-    minNumHeap.has(2)        //  true
-    minNumHeap.poll()        //  0
-    minNumHeap.poll()        //  1
-    minNumHeap.peek()        //  2
-    minNumHeap.has(1);       // false
-    minNumHeap.has(2);       // true
-
-    const arrFromHeap = minNumHeap.toArray();
-    arrFromHeap.length       //  4
-    arrFromHeap[0]           //  2
-    arrFromHeap[1]           //  5
-    arrFromHeap[2]           //  9
-    arrFromHeap[3]           //  6
-    minNumHeap.sort()        //  [2, 5, 6, 9]
-
-    const maxHeap = new MaxHeap<{ keyA: string }>([], {comparator: (a, b) => b.keyA - a.keyA});
-    const obj1 = {keyA: 'a1'}, obj6 = {keyA: 'a6'}, obj5 = {keyA: 'a5'}, obj2 = {keyA: 'a2'},
-        obj0 = {keyA: 'a0'}, obj9 = {keyA: 'a9'};
-    
-    maxHeap.add(obj1);
-    maxHeap.has(obj1)                       // true
-    maxHeap.has(obj9)                       // false
-    maxHeap.add(obj6);
-    maxHeap.has(obj6)                       // true
-    maxHeap.add(obj5);
-    maxHeap.add(obj2);
-    maxHeap.add(obj0);
-    maxHeap.add(obj9);
-    maxHeap.has(obj9)                       // true
-    
-    const peek9 = maxHeap.peek();
-    console.log(peek9.keyA)                 // 'a9'
-    
-    const heapToArr = maxHeap.toArray();
-    console.log(heapToArr.map(ele => ele?.keyA));  // ['a9', 'a2', 'a6', 'a1', 'a0', 'a5']
-    
-    const values = ['a9', 'a6', 'a5', 'a2', 'a1', 'a0'];
-    let i = 0;
-    while (maxHeap.size > 0) {
-        const polled = maxHeap.poll();
-        console.log(polled.keyA)           // values[i]
-        i++;
+    import {Heap, MaxHeap, MinHeap} from 'data-structure-typed';
+
+// /* or if you prefer */ import {MinHeap, MaxHeap} from 'heap-typed';
+
+// Use Heap to sort an array
+function heapSort(arr: number[]): number[] {
+    const heap = new Heap<number>(arr, {comparator: (a, b) => a - b});
+    const sorted: number[] = [];
+    while (!heap.isEmpty()) {
+        sorted.push(heap.poll()!); // Poll minimum element
+    }
+    return sorted;
+}
+
+console.log('Heap sorted:', heapSort([5, 3, 8, 4, 1, 2]));  // [1, 2, 3, 4, 5, 8];
+
+```
+
+
+#### top K problem TS
+
+```typescript
+// Use Heap to resolve top K problem
+function topKElements(arr: number[], k: number): number[] {
+    const heap = new Heap<number>([], {comparator: (a, b) => b - a}); // Max heap
+    arr.forEach((num) => {
+        heap.add(num);
+        if (heap.size > k) heap.poll(); // Keep the heap size at K
+    });
+    return heap.toArray();
+}
+
+const numbers = [10, 30, 20, 5, 15, 25];
+console.log('Top K:', topKElements(numbers, 3)); // [15, 10, 5]
+```
+
+#### real-time median TS
+
+```typescript
+// Use Heap to maintain median value for real-time retrieval
+class MedianFinder {
+    private low: MaxHeap<number>; // Max heap, stores the smaller half
+    private high: MinHeap<number>; // Min heap, stores the larger half
+
+    constructor() {
+        this.low = new MaxHeap<number>([]);
+        this.high = new MinHeap<number>([]);
+    }
+
+    addNum(num: number): void {
+        if (this.low.isEmpty() || num <= this.low.peek()!) this.low.add(num);
+        else this.high.add(num);
+
+        // Balance heaps
+        if (this.low.size > this.high.size + 1) this.high.add(this.low.poll()!);
+        else if (this.high.size > this.low.size) this.low.add(this.high.poll()!);
     }
+
+    findMedian(): number {
+        return this.low.peek()!;
+    }
+}
+
+const medianFinder = new MedianFinder();
+medianFinder.addNum(10);
+console.log('realtime median: ', medianFinder.findMedian()) // 10
+medianFinder.addNum(20);
+console.log('realtime median: ', medianFinder.findMedian()) // 10
+medianFinder.addNum(30);
+console.log('realtime median: ', medianFinder.findMedian()) // 20
+medianFinder.addNum(40);
+console.log('realtime median: ', medianFinder.findMedian()) // 20
+medianFinder.addNum(50);
+console.log('realtime median: ', medianFinder.findMedian()) // 30
+```
+
+#### load balance TS
+
+```typescript
+// Use Heap for load balancing
+function loadBalance(requests: number[], servers: number): number[] {
+    const serverHeap = new Heap<{ id: number; load: number }>([], { comparator: (a, b) => a.load - b.load }); // min heap
+    const serverLoads = new Array(servers).fill(0);
+
+    for (let i = 0; i < servers; i++) {
+        serverHeap.add({ id: i, load: 0 });
+    }
+
+    requests.forEach(req => {
+        const server = serverHeap.poll()!;
+        serverLoads[server.id] += req;
+        server.load += req;
+        serverHeap.add(server); // The server after updating the load is re-entered into the heap
+    });
+
+    return serverLoads;
+}
+
+const requests = [5, 2, 8, 3, 7];
+const serversLoads = loadBalance(requests, 3);
+console.log('server loads: ', serversLoads);  // [12, 8, 5]
+```
+#### conventional operation TS
+
+```typescript
+const minNumHeap = new MinHeap<number>([1, 6, 2, 0, 5]);
+minNumHeap.add(9);
+minNumHeap.has(1)        //  true
+minNumHeap.has(2)        //  true
+minNumHeap.poll()        //  0
+minNumHeap.poll()        //  1
+minNumHeap.peek()        //  2
+minNumHeap.has(1);       // false
+minNumHeap.has(2);       // true
+
+const arrFromHeap = minNumHeap.toArray();
+arrFromHeap.length       //  4
+arrFromHeap[0]           //  2
+arrFromHeap[1]           //  5
+arrFromHeap[2]           //  9
+arrFromHeap[3]           //  6
+minNumHeap.sort()        //  [2, 5, 6, 9]
+
+const maxHeap = new MaxHeap<{ keyA: string }>([], {comparator: (a, b) => b.keyA - a.keyA});
+const obj1 = {keyA: 'a1'}, obj6 = {keyA: 'a6'}, obj5 = {keyA: 'a5'}, obj2 = {keyA: 'a2'},
+    obj0 = {keyA: 'a0'}, obj9 = {keyA: 'a9'};
+
+maxHeap.add(obj1);
+maxHeap.has(obj1)                       // true
+maxHeap.has(obj9)                       // false
+maxHeap.add(obj6);
+maxHeap.has(obj6)                       // true
+maxHeap.add(obj5);
+maxHeap.add(obj2);
+maxHeap.add(obj0);
+maxHeap.add(obj9);
+maxHeap.has(obj9)                       // true
+
+const peek9 = maxHeap.peek();
+console.log(peek9.keyA)                 // 'a9'
+
+const heapToArr = maxHeap.toArray();
+console.log(heapToArr.map(ele => ele?.keyA));  // ['a9', 'a2', 'a6', 'a1', 'a0', 'a5']
+
+const values = ['a9', 'a6', 'a5', 'a2', 'a1', 'a0'];
+let i = 0;
+while (maxHeap.size > 0) {
+    const polled = maxHeap.poll();
+    console.log(polled.keyA)           // values[i]
+    i++;
+}
 ```
 
-#### JS
+#### conventional operation JS
 
 ```javascript
 const {MinHeap, MaxHeap} = require('data-structure-typed');

package/dist/data-structures/heap/heap.d.ts

@@ -17,6 +17,171 @@ import { IterableElementBase } from '../base';
  * 6. Non-linear Search: While a heap allows rapid access to its largest or smallest element, it is less efficient for other operations, such as searching for a specific element, as it is not designed for these tasks.
  * 7. Efficient Sorting Algorithms: For example, heap sort. Heap sort uses the properties of a heap to sort elements.
  * 8. Graph Algorithms: Such as Dijkstra's shortest path algorithm and Prime's minimum-spanning tree algorithm, which use heaps to improve performance.
+ * @example
+ * // Use Heap to sort an array
+ * function heapSort(arr: number[]): number[] {
+ *       const heap = new Heap<number>(arr, { comparator: (a, b) => a - b });
+ *       const sorted: number[] = [];
+ *       while (!heap.isEmpty()) {
+ *         sorted.push(heap.poll()!); // Poll minimum element
+ *       }
+ *       return sorted;
+ *     }
+ *
+ *     const array = [5, 3, 8, 4, 1, 2];
+ *     console.log(heapSort(array)); // [1, 2, 3, 4, 5, 8]
+ * @example
+ * // Use Heap to solve top k problems
+ * function topKElements(arr: number[], k: number): number[] {
+ *       const heap = new Heap<number>([], { comparator: (a, b) => b - a }); // Max heap
+ *       arr.forEach(num => {
+ *         heap.add(num);
+ *         if (heap.size > k) heap.poll(); // Keep the heap size at K
+ *       });
+ *       return heap.toArray();
+ *     }
+ *
+ *     const numbers = [10, 30, 20, 5, 15, 25];
+ *     console.log(topKElements(numbers, 3)); // [15, 10, 5]
+ * @example
+ * // Use Heap to merge sorted sequences
+ * function mergeSortedSequences(sequences: number[][]): number[] {
+ *       const heap = new Heap<{ value: number; seqIndex: number; itemIndex: number }>([], {
+ *         comparator: (a, b) => a.value - b.value // Min heap
+ *       });
+ *
+ *       // Initialize heap
+ *       sequences.forEach((seq, seqIndex) => {
+ *         if (seq.length) {
+ *           heap.add({ value: seq[0], seqIndex, itemIndex: 0 });
+ *         }
+ *       });
+ *
+ *       const merged: number[] = [];
+ *       while (!heap.isEmpty()) {
+ *         const { value, seqIndex, itemIndex } = heap.poll()!;
+ *         merged.push(value);
+ *
+ *         if (itemIndex + 1 < sequences[seqIndex].length) {
+ *           heap.add({
+ *             value: sequences[seqIndex][itemIndex + 1],
+ *             seqIndex,
+ *             itemIndex: itemIndex + 1
+ *           });
+ *         }
+ *       }
+ *
+ *       return merged;
+ *     }
+ *
+ *     const sequences = [
+ *       [1, 4, 7],
+ *       [2, 5, 8],
+ *       [3, 6, 9]
+ *     ];
+ *     console.log(mergeSortedSequences(sequences)); // [1, 2, 3, 4, 5, 6, 7, 8, 9]
+ * @example
+ * // Use Heap to dynamically maintain the median
+ * class MedianFinder {
+ *       private low: MaxHeap<number>; // Max heap, stores the smaller half
+ *       private high: MinHeap<number>; // Min heap, stores the larger half
+ *
+ *       constructor() {
+ *         this.low = new MaxHeap<number>([]);
+ *         this.high = new MinHeap<number>([]);
+ *       }
+ *
+ *       addNum(num: number): void {
+ *         if (this.low.isEmpty() || num <= this.low.peek()!) this.low.add(num);
+ *         else this.high.add(num);
+ *
+ *         // Balance heaps
+ *         if (this.low.size > this.high.size + 1) this.high.add(this.low.poll()!);
+ *         else if (this.high.size > this.low.size) this.low.add(this.high.poll()!);
+ *       }
+ *
+ *       findMedian(): number {
+ *         if (this.low.size === this.high.size) return (this.low.peek()! + this.high.peek()!) / 2;
+ *         return this.low.peek()!;
+ *       }
+ *     }
+ *
+ *     const medianFinder = new MedianFinder();
+ *     medianFinder.addNum(10);
+ *     console.log(medianFinder.findMedian()); // 10
+ *     medianFinder.addNum(20);
+ *     console.log(medianFinder.findMedian()); // 15
+ *     medianFinder.addNum(30);
+ *     console.log(medianFinder.findMedian()); // 20
+ *     medianFinder.addNum(40);
+ *     console.log(medianFinder.findMedian()); // 25
+ *     medianFinder.addNum(50);
+ *     console.log(medianFinder.findMedian()); // 30
+ * @example
+ * // Use Heap for load balancing
+ * function loadBalance(requests: number[], servers: number): number[] {
+ *       const serverHeap = new Heap<{ id: number; load: number }>([], { comparator: (a, b) => a.load - b.load }); // min heap
+ *       const serverLoads = new Array(servers).fill(0);
+ *
+ *       for (let i = 0; i < servers; i++) {
+ *         serverHeap.add({ id: i, load: 0 });
+ *       }
+ *
+ *       requests.forEach(req => {
+ *         const server = serverHeap.poll()!;
+ *         serverLoads[server.id] += req;
+ *         server.load += req;
+ *         serverHeap.add(server); // The server after updating the load is re-entered into the heap
+ *       });
+ *
+ *       return serverLoads;
+ *     }
+ *
+ *     const requests = [5, 2, 8, 3, 7];
+ *     console.log(loadBalance(requests, 3)); // [12, 8, 5]
+ * @example
+ * // Use Heap to schedule tasks
+ * type Task = [string, number];
+ *
+ *     function scheduleTasks(tasks: Task[], machines: number): Map<number, Task[]> {
+ *       const machineHeap = new Heap<{ id: number; load: number }>([], { comparator: (a, b) => a.load - b.load }); // Min heap
+ *       const allocation = new Map<number, Task[]>();
+ *
+ *       // Initialize the load on each machine
+ *       for (let i = 0; i < machines; i++) {
+ *         machineHeap.add({ id: i, load: 0 });
+ *         allocation.set(i, []);
+ *       }
+ *
+ *       // Assign tasks
+ *       tasks.forEach(([task, load]) => {
+ *         const machine = machineHeap.poll()!;
+ *         allocation.get(machine.id)!.push([task, load]);
+ *         machine.load += load;
+ *         machineHeap.add(machine); // The machine after updating the load is re-entered into the heap
+ *       });
+ *
+ *       return allocation;
+ *     }
+ *
+ *     const tasks: Task[] = [
+ *       ['Task1', 3],
+ *       ['Task2', 1],
+ *       ['Task3', 2],
+ *       ['Task4', 5],
+ *       ['Task5', 4]
+ *     ];
+ *     const expectedMap = new Map<number, Task[]>();
+ *     expectedMap.set(0, [
+ *       ['Task1', 3],
+ *       ['Task4', 5]
+ *     ]);
+ *     expectedMap.set(1, [
+ *       ['Task2', 1],
+ *       ['Task3', 2],
+ *       ['Task5', 4]
+ *     ]);
+ *     console.log(scheduleTasks(tasks, 2)); // expectedMap
  */
 export declare class Heap<E = any, R = any> extends IterableElementBase<E, R, Heap<E, R>> {
     /**

package/dist/data-structures/heap/heap.js

@@ -19,6 +19,171 @@ const base_1 = require("../base");
  * 6. Non-linear Search: While a heap allows rapid access to its largest or smallest element, it is less efficient for other operations, such as searching for a specific element, as it is not designed for these tasks.
  * 7. Efficient Sorting Algorithms: For example, heap sort. Heap sort uses the properties of a heap to sort elements.
  * 8. Graph Algorithms: Such as Dijkstra's shortest path algorithm and Prime's minimum-spanning tree algorithm, which use heaps to improve performance.
+ * @example
+ * // Use Heap to sort an array
+ * function heapSort(arr: number[]): number[] {
+ *       const heap = new Heap<number>(arr, { comparator: (a, b) => a - b });
+ *       const sorted: number[] = [];
+ *       while (!heap.isEmpty()) {
+ *         sorted.push(heap.poll()!); // Poll minimum element
+ *       }
+ *       return sorted;
+ *     }
+ *
+ *     const array = [5, 3, 8, 4, 1, 2];
+ *     console.log(heapSort(array)); // [1, 2, 3, 4, 5, 8]
+ * @example
+ * // Use Heap to solve top k problems
+ * function topKElements(arr: number[], k: number): number[] {
+ *       const heap = new Heap<number>([], { comparator: (a, b) => b - a }); // Max heap
+ *       arr.forEach(num => {
+ *         heap.add(num);
+ *         if (heap.size > k) heap.poll(); // Keep the heap size at K
+ *       });
+ *       return heap.toArray();
+ *     }
+ *
+ *     const numbers = [10, 30, 20, 5, 15, 25];
+ *     console.log(topKElements(numbers, 3)); // [15, 10, 5]
+ * @example
+ * // Use Heap to merge sorted sequences
+ * function mergeSortedSequences(sequences: number[][]): number[] {
+ *       const heap = new Heap<{ value: number; seqIndex: number; itemIndex: number }>([], {
+ *         comparator: (a, b) => a.value - b.value // Min heap
+ *       });
+ *
+ *       // Initialize heap
+ *       sequences.forEach((seq, seqIndex) => {
+ *         if (seq.length) {
+ *           heap.add({ value: seq[0], seqIndex, itemIndex: 0 });
+ *         }
+ *       });
+ *
+ *       const merged: number[] = [];
+ *       while (!heap.isEmpty()) {
+ *         const { value, seqIndex, itemIndex } = heap.poll()!;
+ *         merged.push(value);
+ *
+ *         if (itemIndex + 1 < sequences[seqIndex].length) {
+ *           heap.add({
+ *             value: sequences[seqIndex][itemIndex + 1],
+ *             seqIndex,
+ *             itemIndex: itemIndex + 1
+ *           });
+ *         }
+ *       }
+ *
+ *       return merged;
+ *     }
+ *
+ *     const sequences = [
+ *       [1, 4, 7],
+ *       [2, 5, 8],
+ *       [3, 6, 9]
+ *     ];
+ *     console.log(mergeSortedSequences(sequences)); // [1, 2, 3, 4, 5, 6, 7, 8, 9]
+ * @example
+ * // Use Heap to dynamically maintain the median
+ * class MedianFinder {
+ *       private low: MaxHeap<number>; // Max heap, stores the smaller half
+ *       private high: MinHeap<number>; // Min heap, stores the larger half
+ *
+ *       constructor() {
+ *         this.low = new MaxHeap<number>([]);
+ *         this.high = new MinHeap<number>([]);
+ *       }
+ *
+ *       addNum(num: number): void {
+ *         if (this.low.isEmpty() || num <= this.low.peek()!) this.low.add(num);
+ *         else this.high.add(num);
+ *
+ *         // Balance heaps
+ *         if (this.low.size > this.high.size + 1) this.high.add(this.low.poll()!);
+ *         else if (this.high.size > this.low.size) this.low.add(this.high.poll()!);
+ *       }
+ *
+ *       findMedian(): number {
+ *         if (this.low.size === this.high.size) return (this.low.peek()! + this.high.peek()!) / 2;
+ *         return this.low.peek()!;
+ *       }
+ *     }
+ *
+ *     const medianFinder = new MedianFinder();
+ *     medianFinder.addNum(10);
+ *     console.log(medianFinder.findMedian()); // 10
+ *     medianFinder.addNum(20);
+ *     console.log(medianFinder.findMedian()); // 15
+ *     medianFinder.addNum(30);
+ *     console.log(medianFinder.findMedian()); // 20
+ *     medianFinder.addNum(40);
+ *     console.log(medianFinder.findMedian()); // 25
+ *     medianFinder.addNum(50);
+ *     console.log(medianFinder.findMedian()); // 30
+ * @example
+ * // Use Heap for load balancing
+ * function loadBalance(requests: number[], servers: number): number[] {
+ *       const serverHeap = new Heap<{ id: number; load: number }>([], { comparator: (a, b) => a.load - b.load }); // min heap
+ *       const serverLoads = new Array(servers).fill(0);
+ *
+ *       for (let i = 0; i < servers; i++) {
+ *         serverHeap.add({ id: i, load: 0 });
+ *       }
+ *
+ *       requests.forEach(req => {
+ *         const server = serverHeap.poll()!;
+ *         serverLoads[server.id] += req;
+ *         server.load += req;
+ *         serverHeap.add(server); // The server after updating the load is re-entered into the heap
+ *       });
+ *
+ *       return serverLoads;
+ *     }
+ *
+ *     const requests = [5, 2, 8, 3, 7];
+ *     console.log(loadBalance(requests, 3)); // [12, 8, 5]
+ * @example
+ * // Use Heap to schedule tasks
+ * type Task = [string, number];
+ *
+ *     function scheduleTasks(tasks: Task[], machines: number): Map<number, Task[]> {
+ *       const machineHeap = new Heap<{ id: number; load: number }>([], { comparator: (a, b) => a.load - b.load }); // Min heap
+ *       const allocation = new Map<number, Task[]>();
+ *
+ *       // Initialize the load on each machine
+ *       for (let i = 0; i < machines; i++) {
+ *         machineHeap.add({ id: i, load: 0 });
+ *         allocation.set(i, []);
+ *       }
+ *
+ *       // Assign tasks
+ *       tasks.forEach(([task, load]) => {
+ *         const machine = machineHeap.poll()!;
+ *         allocation.get(machine.id)!.push([task, load]);
+ *         machine.load += load;
+ *         machineHeap.add(machine); // The machine after updating the load is re-entered into the heap
+ *       });
+ *
+ *       return allocation;
+ *     }
+ *
+ *     const tasks: Task[] = [
+ *       ['Task1', 3],
+ *       ['Task2', 1],
+ *       ['Task3', 2],
+ *       ['Task4', 5],
+ *       ['Task5', 4]
+ *     ];
+ *     const expectedMap = new Map<number, Task[]>();
+ *     expectedMap.set(0, [
+ *       ['Task1', 3],
+ *       ['Task4', 5]
+ *     ]);
+ *     expectedMap.set(1, [
+ *       ['Task2', 1],
+ *       ['Task3', 2],
+ *       ['Task5', 4]
+ *     ]);
+ *     console.log(scheduleTasks(tasks, 2)); // expectedMap
  */
 class Heap extends base_1.IterableElementBase {
     /**