stack-typed 1.53.6 → 1.53.8

package/src/data-structures/hash/hash-map.ts

@@ -97,6 +97,9 @@ export class HashMap<K = any, V = any, R = [K, V]> extends IterableEntryBase<K,
   }
 
   /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   *
    * The function checks if a given element is an array with exactly two elements.
    * @param {any} rawElement - The `rawElement` parameter is of type `any`, which means it can be any
    * data type.
@@ -107,6 +110,9 @@ export class HashMap<K = any, V = any, R = [K, V]> extends IterableEntryBase<K,
   }
 
   /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   *
    * The function checks if the size of an object is equal to zero and returns a boolean value.
    * @returns A boolean value indicating whether the size of the object is 0 or not.
    */
@@ -115,6 +121,9 @@ export class HashMap<K = any, V = any, R = [K, V]> extends IterableEntryBase<K,
   }
 
   /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   *
    * The clear() function resets the state of an object by clearing its internal store, object map, and
    * size.
    */
@@ -125,6 +134,9 @@ export class HashMap<K = any, V = any, R = [K, V]> extends IterableEntryBase<K,
   }
 
   /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   *
    * The `set` function adds a key-value pair to a map-like data structure, incrementing the size if
    * the key is not already present.
    * @param {K} key - The key parameter is the key used to identify the value in the data structure. It
@@ -150,6 +162,9 @@ export class HashMap<K = any, V = any, R = [K, V]> extends IterableEntryBase<K,
   }
 
   /**
+   * Time Complexity: O(k)
+   * Space Complexity: O(k)
+   *
    * The function `setMany` takes an iterable collection of objects, maps each object to a key-value
    * pair using a mapping function, and sets each key-value pair in the current object.
    * @param entryOrRawElements - The `entryOrRawElements` parameter is an iterable collection of elements of a type
@@ -175,6 +190,9 @@ export class HashMap<K = any, V = any, R = [K, V]> extends IterableEntryBase<K,
   }
 
   /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   *
    * The `get` function retrieves a value from a map based on a given key, either from an object map or
    * a string map.
    * @param {K} key - The `key` parameter is the key used to retrieve a value from the map. It can be
@@ -192,6 +210,9 @@ export class HashMap<K = any, V = any, R = [K, V]> extends IterableEntryBase<K,
   }
 
   /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   *
    * The `has` function checks if a given key exists in the `_objMap` or `_store` based on whether it
    * is an object key or not.
    * @param {K} key - The parameter "key" is of type K, which means it can be any type.
@@ -207,6 +228,9 @@ export class HashMap<K = any, V = any, R = [K, V]> extends IterableEntryBase<K,
   }
 
   /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   *
    * The `delete` function removes an element from a map-like data structure based on the provided key.
    * @param {K} key - The `key` parameter is the key of the element that you want to delete from the
    * data structure.
@@ -579,6 +603,9 @@ export class LinkedHashMap<K = any, V = any, R = [K, V]> extends IterableEntryBa
   }
 
   /**
+   * Time Complexity: O(k)
+   * Space Complexity: O(k)
+   *
    * The function `setMany` takes an iterable collection, converts each element into a key-value pair
    * using a provided function, and sets each key-value pair in the current object, returning an array
    * of booleans indicating the success of each set operation.
@@ -605,6 +632,9 @@ export class LinkedHashMap<K = any, V = any, R = [K, V]> extends IterableEntryBa
   }
 
   /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   *
    * The function checks if a given key exists in a map, using different logic depending on whether the
    * key is a weak key or not.
    * @param {K} key - The `key` parameter is the key that is being checked for existence in the map.

package/src/data-structures/heap/heap.ts

@@ -19,9 +19,9 @@ 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[] {
+ * @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()) {
@@ -29,12 +29,12 @@ import { IterableElementBase } from '../base';
  *       }
  *       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[] {
+ * @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);
@@ -42,28 +42,28 @@ import { IterableElementBase } from '../base';
  *       });
  *       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[] {
+ * @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],
@@ -72,42 +72,42 @@ import { IterableElementBase } from '../base';
  *           });
  *         }
  *       }
- * 
+ *
  *       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 {
+ * @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
@@ -119,42 +119,42 @@ import { IterableElementBase } from '../base';
  *     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[] {
+ * @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];
- * 
+ * @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()!;
@@ -162,10 +162,10 @@ import { IterableElementBase } from '../base';
  *         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],
@@ -207,12 +207,7 @@ export class Heap<E = any, R = any> extends IterableElementBase<E, R, Heap<E, R>
       if (comparator) this._comparator = comparator;
     }
 
-    if (elements) {
-      for (const el of elements) {
-        if (this.toElementFn) this.add(this.toElementFn(el as R));
-        else this.add(el as E);
-      }
-    }
+    this.addMany(elements);
   }
 
   protected _elements: E[] = [];
@@ -254,14 +249,42 @@ export class Heap<E = any, R = any> extends IterableElementBase<E, R, Heap<E, R>
    * Time Complexity: O(log n)
    * Space Complexity: O(1)
    *
-   * Insert an element into the heap and maintain the heap properties.
-   * @param element - The element to be inserted.
+   * The add function pushes an element into an array and then triggers a bubble-up operation.
+   * @param {E} element - The `element` parameter represents the element that you want to add to the
+   * data structure.
+   * @returns The `add` method is returning a boolean value, which is the result of calling the
+   * `_bubbleUp` method with the index `this.elements.length - 1` as an argument.
    */
   add(element: E): boolean {
-    this._elements.push(element);
+    this._elements.push(element as E);
     return this._bubbleUp(this.elements.length - 1);
   }
 
+  /**
+   * Time Complexity: O(k log n)
+   * Space Complexity: O(1)
+   *
+   * The `addMany` function iterates over elements and adds them to a collection, returning an array of
+   * boolean values indicating success or failure.
+   * @param {Iterable<E> | Iterable<R>} elements - The `elements` parameter in the `addMany` method is
+   * an iterable containing elements of type `E` or `R`. The method iterates over each element in the
+   * iterable and adds them to the data structure. If a transformation function `_toElementFn` is
+   * provided, it transforms the element
+   * @returns The `addMany` method returns an array of boolean values indicating whether each element
+   * in the input iterable was successfully added to the data structure.
+   */
+  addMany(elements: Iterable<E> | Iterable<R>): boolean[] {
+    const ans: boolean[] = [];
+    for (const el of elements) {
+      if (this._toElementFn) {
+        ans.push(this.add(this._toElementFn(el as R)));
+        continue;
+      }
+      ans.push(this.add(el as E));
+    }
+    return ans;
+  }
+
   /**
    * Time Complexity: O(log n)
    * Space Complexity: O(1)
@@ -473,7 +496,7 @@ export class Heap<E = any, R = any> extends IterableElementBase<E, R, Heap<E, R>
   }
 
   /**
-   * Time Complexity: O(n log n)
+   * Time Complexity: O(n)
    * Space Complexity: O(n)
    *
    * The `map` function creates a new heap by applying a callback function to each element of the