min-heap-typed 1.50.0 → 1.50.2

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

@@ -32,7 +32,7 @@ export class HashMap<K = any, V = any, R = [K, V]> extends IterableEntryBase<K,
    * `T`. It is an optional parameter and its default value is an empty array `[]`.
    * @param [options] - The `options` parameter is an optional object that can contain two properties:
    */
-  constructor(rawCollection: Iterable<R> = [], options?: HashMapOptions<K, V, R>) {
+  constructor(rawCollection: Iterable<R | [K, V]> = [], options?: HashMapOptions<K, V, R>) {
     super();
     if (options) {
       const { hashFn, toEntryFn } = options;
@@ -59,24 +59,56 @@ export class HashMap<K = any, V = any, R = [K, V]> extends IterableEntryBase<K,
     }
   };
 
+  /**
+   * The function returns the value of the _toEntryFn property.
+   * @returns The function being returned is `this._toEntryFn`.
+   */
   get toEntryFn() {
     return this._toEntryFn;
   }
 
+  /**
+   * The hasFn function is a function that takes in an item and returns a boolean
+   * indicating whether the item is contained within the hash table.
+   *
+   * @return The hash function
+   */
+  get hasFn() {
+    return this._hashFn;
+  }
+
   protected _size = 0;
 
+  /**
+   * The function returns the size of an object.
+   * @returns The size of the object, which is a number.
+   */
   get size(): number {
     return this._size;
   }
 
+  /**
+   * 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.
+   * @returns a boolean value.
+   */
   isEntry(rawElement: any): rawElement is [K, V] {
     return Array.isArray(rawElement) && rawElement.length === 2;
   }
 
+  /**
+   * 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.
+   */
   isEmpty(): boolean {
     return this.size === 0;
   }
 
+  /**
+   * The clear() function resets the state of an object by clearing its internal store, object map, and
+   * size.
+   */
   clear() {
     this._store = {};
     this._objMap.clear();
@@ -115,10 +147,18 @@ export class HashMap<K = any, V = any, R = [K, V]> extends IterableEntryBase<K,
    * `T`.
    * @returns The `setMany` function is returning an array of booleans.
    */
-  setMany(rawCollection: Iterable<R>): boolean[] {
+  setMany(rawCollection: Iterable<R | [K, V]>): boolean[] {
     const results: boolean[] = [];
     for (const rawEle of rawCollection) {
-      const [key, value] = this.toEntryFn(rawEle);
+      let key, value;
+      if (this.isEntry(rawEle)) {
+        key = rawEle[0];
+        value = rawEle[1];
+      } else {
+        const item = this.toEntryFn(rawEle);
+        key = item[0];
+        value = item[1];
+      }
       results.push(this.set(key, value));
     }
     return results;
@@ -132,7 +172,7 @@ export class HashMap<K = any, V = any, R = [K, V]> extends IterableEntryBase<K,
    * @returns The method `get(key: K)` returns a value of type `V` if the key exists in the `_objMap`
    * or `_store`, otherwise it returns `undefined`.
    */
-  get(key: K): V | undefined {
+  override get(key: K): V | undefined {
     if (this._isObjKey(key)) {
       return this._objMap.get(key);
     } else {
@@ -147,7 +187,7 @@ export class HashMap<K = any, V = any, R = [K, V]> extends IterableEntryBase<K,
    * @param {K} key - The parameter "key" is of type K, which means it can be any type.
    * @returns The `has` method is returning a boolean value.
    */
-  has(key: K): boolean {
+  override has(key: K): boolean {
     if (this._isObjKey(key)) {
       return this._objMap.has(key);
     } else {
@@ -181,6 +221,17 @@ export class HashMap<K = any, V = any, R = [K, V]> extends IterableEntryBase<K,
     }
   }
 
+  /**
+   * The clone function creates a new HashMap with the same key-value pairs as
+   * this one. The clone function is useful for creating a copy of an existing
+   * HashMap, and then modifying that copy without affecting the original.
+   *
+   * @return A new hashmap with the same values as this one
+   */
+  clone(): HashMap<K, V, R> {
+    return new HashMap<K, V, R>(this, { hashFn: this._hashFn, toEntryFn: this.toEntryFn });
+  }
+
   /**
    * Time Complexity: O(n)
    * Space Complexity: O(n)
@@ -241,6 +292,14 @@ export class HashMap<K = any, V = any, R = [K, V]> extends IterableEntryBase<K,
     return filteredMap;
   }
 
+  /**
+   * The put function sets a value in a data structure using a specified key.
+   * @param {K} key - The key parameter is of type K, which represents the type of the key being passed
+   * to the function.
+   * @param {V} value - The value parameter represents the value that you want to associate with the
+   * specified key in the data structure.
+   * @returns The method is returning a boolean value.
+   */
   put(key: K, value: V): boolean {
     return this.set(key, value);
   }
@@ -288,33 +347,70 @@ export class HashMap<K = any, V = any, R = [K, V]> extends IterableEntryBase<K,
  * 2. Based on Hash Table and Linked List: It combines the structures of a hash table and a linked list, using the hash table to ensure fast access, while maintaining the order of entries through the linked list.
  * 3. Time Complexity: Similar to HashMap, LinkedHashMap offers constant-time performance for get and put operations in most cases.
  */
-export class LinkedHashMap<K = any, V = any> extends IterableEntryBase<K, V> {
+export class LinkedHashMap<K = any, V = any, R = [K, V]> extends IterableEntryBase<K, V> {
   protected _noObjMap: Record<string, HashMapLinkedNode<K, V | undefined>> = {};
   protected _objMap = new WeakMap<object, HashMapLinkedNode<K, V | undefined>>();
   protected _head: HashMapLinkedNode<K, V | undefined>;
   protected _tail: HashMapLinkedNode<K, V | undefined>;
   protected readonly _sentinel: HashMapLinkedNode<K, V | undefined>;
 
-  constructor(entries?: Iterable<[K, V]>, options?: LinkedHashMapOptions<K>) {
+  /**
+   * The constructor initializes a LinkedHashMap object with an optional raw collection and options.
+   * @param rawCollection - The `rawCollection` parameter is an iterable collection of elements. It is
+   * used to initialize the HashMapLinked instance with key-value pairs. Each element in the
+   * `rawCollection` is converted to a key-value pair using the `toEntryFn` function (if provided) and
+   * then added to the HashMap
+   * @param [options] - The `options` parameter is an optional object that can contain the following
+   * properties:
+   */
+  constructor(rawCollection: Iterable<R> = [], options?: LinkedHashMapOptions<K, V, R>) {
     super();
     this._sentinel = <HashMapLinkedNode<K, V>>{};
     this._sentinel.prev = this._sentinel.next = this._head = this._tail = this._sentinel;
 
     if (options) {
-      const { hashFn, objHashFn } = options;
+      const { hashFn, objHashFn, toEntryFn } = options;
       if (hashFn) this._hashFn = hashFn;
       if (objHashFn) this._objHashFn = objHashFn;
+
+      if (toEntryFn) {
+        this._toEntryFn = toEntryFn;
+      }
     }
 
-    if (entries) {
-      for (const el of entries) {
-        this.set(el[0], el[1]);
+    if (rawCollection) {
+      for (const el of rawCollection) {
+        const [key, value] = this.toEntryFn(el);
+        this.set(key, value);
       }
     }
   }
 
+  protected _toEntryFn: (rawElement: R) => [K, V] = (rawElement: R) => {
+    if (this.isEntry(rawElement)) {
+      // TODO, For performance optimization, it may be necessary to only inspect the first element traversed.
+      return rawElement;
+    } else {
+      throw new Error(
+        "If the provided rawCollection does not adhere to the [key, value] type format, the toEntryFn in the constructor's options parameter needs to specified."
+      );
+    }
+  };
+
+  /**
+   * The function returns the value of the _toEntryFn property.
+   * @returns The function being returned is `this._toEntryFn`.
+   */
+  get toEntryFn() {
+    return this._toEntryFn;
+  }
+
   protected _size = 0;
 
+  /**
+   * The function returns the size of an object.
+   * @returns The size of the object.
+   */
   get size() {
     return this._size;
   }
@@ -425,7 +521,30 @@ export class LinkedHashMap<K = any, V = any> extends IterableEntryBase<K, V> {
     return true;
   }
 
-  has(key: K): boolean {
+  /**
+   * 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.
+   * @param rawCollection - The rawCollection parameter is an iterable collection of elements of type
+   * R.
+   * @returns The `setMany` function returns an array of booleans.
+   */
+  setMany(rawCollection: Iterable<R>): boolean[] {
+    const results: boolean[] = [];
+    for (const rawEle of rawCollection) {
+      const [key, value] = this.toEntryFn(rawEle);
+      results.push(this.set(key, value));
+    }
+    return results;
+  }
+
+  /**
+   * 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.
+   * @returns The method `has` is returning a boolean value.
+   */
+  override has(key: K): boolean {
     if (isWeakKey(key)) {
       const hash = this._objHashFn(key);
       return this._objMap.has(hash);
@@ -435,15 +554,6 @@ export class LinkedHashMap<K = any, V = any> extends IterableEntryBase<K, V> {
     }
   }
 
-  setMany(entries: Iterable<[K, V]>): boolean[] {
-    const results: boolean[] = [];
-    for (const entry of entries) {
-      const [key, value] = entry;
-      results.push(this.set(key, value));
-    }
-    return results;
-  }
-
   /**
    * Time Complexity: O(1)
    * Space Complexity: O(1)
@@ -457,7 +567,7 @@ export class LinkedHashMap<K = any, V = any> extends IterableEntryBase<K, V> {
    * property of the key. If the key is a string key, the value is retrieved from the `_noObjMap` object
    * using the key itself. If the key is not found, `undefined` is
    */
-  get(key: K): V | undefined {
+  override get(key: K): V | undefined {
     if (isWeakKey(key)) {
       const hash = this._objHashFn(key);
       const node = this._objMap.get(hash);
@@ -473,14 +583,14 @@ export class LinkedHashMap<K = any, V = any> extends IterableEntryBase<K, V> {
    * Time Complexity: O(n), where n is the index.
    * Space Complexity: O(1)
    *
-   * The function `getAt` retrieves the key-value pair at a specified index in a linked list.
+   * The function `at` retrieves the key-value pair at a specified index in a linked list.
    * @param {number} index - The index parameter is a number that represents the position of the
    * element we want to retrieve from the data structure.
-   * @returns The method `getAt(index: number)` is returning an array containing the key-value pair at
+   * @returns The method `at(index: number)` is returning an array containing the key-value pair at
    * the specified index in the data structure. The key-value pair is represented as a tuple `[K, V]`,
    * where `K` is the key and `V` is the value.
    */
-  getAt(index: number): V | undefined {
+  at(index: number): V | undefined {
     rangeCheck(index, 0, this._size - 1);
     let node = this._head;
     while (index--) {
@@ -532,7 +642,7 @@ export class LinkedHashMap<K = any, V = any> extends IterableEntryBase<K, V> {
   }
 
   /**
-   * Time Complexity: O(n), where n is the index.
+   * Time Complexity: O(n)
    * Space Complexity: O(1)
    *
    * The `deleteAt` function deletes a node at a specified index in a linked list.
@@ -561,6 +671,16 @@ export class LinkedHashMap<K = any, V = any> extends IterableEntryBase<K, V> {
     return this._size === 0;
   }
 
+  /**
+   * 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.
+   * @returns a boolean value.
+   */
+  isEntry(rawElement: any): rawElement is [K, V] {
+    return Array.isArray(rawElement) && rawElement.length === 2;
+  }
+
   /**
    * Time Complexity: O(1)
    * Space Complexity: O(1)
@@ -573,6 +693,20 @@ export class LinkedHashMap<K = any, V = any> extends IterableEntryBase<K, V> {
     this._head = this._tail = this._sentinel.prev = this._sentinel.next = this._sentinel;
   }
 
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(n)
+   */
+
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(n)
+   *
+   * The `clone` function creates a new instance of a `LinkedHashMap` with the same key-value pairs as
+   * the original.
+   * @returns The `clone()` method is returning a new instance of `LinkedHashMap<K, V>` that is a clone
+   * of the original `LinkedHashMap` object.
+   */
   clone(): LinkedHashMap<K, V> {
     const cloned = new LinkedHashMap<K, V>([], { hashFn: this._hashFn, objHashFn: this._objHashFn });
     for (const entry of this) {
@@ -638,26 +772,33 @@ export class LinkedHashMap<K = any, V = any> extends IterableEntryBase<K, V> {
   }
 
   /**
-   * Time Complexity: O(n)
-   * Space Complexity: O(n)
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
    */
 
+  /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   *
+   * The put function sets a value in a data structure using a specified key.
+   * @param {K} key - The key parameter is of type K, which represents the type of the key being passed
+   * to the function.
+   * @param {V} value - The value parameter represents the value that you want to associate with the
+   * specified key in the data structure.
+   * @returns The method is returning a boolean value.
+   */
   put(key: K, value: V): boolean {
     return this.set(key, value);
   }
 
-  /**
-   * Time Complexity: O(n)
-   * Space Complexity: O(n)
-   */
-
   protected _hashFn: (key: K) => string = (key: K) => String(key);
 
   protected _objHashFn: (key: K) => object = (key: K) => <object>key;
 
   /**
-   * Time Complexity: O(n), where n is the number of entries in the LinkedHashMap.
+   * Time Complexity: O(n)
    * Space Complexity: O(1)
+   * where n is the number of entries in the LinkedHashMap.
    *
    * The above function is an iterator that yields key-value pairs from a linked list.
    */

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

@@ -21,6 +21,16 @@ import { IterableElementBase } from '../base';
  * 8. Graph Algorithms: Such as Dijkstra's shortest path algorithm and Prim's minimum spanning tree algorithm, which use heaps to improve performance.
  */
 export class Heap<E = any> extends IterableElementBase<E> {
+  /**
+   * The constructor initializes a heap data structure with optional elements and options.
+   * @param elements - The `elements` parameter is an iterable object that contains the initial
+   * elements to be added to the heap. It is an optional parameter and if not provided, the heap will
+   * be initialized as empty.
+   * @param [options] - The `options` parameter is an optional object that can contain additional
+   * configuration options for the heap. In this case, it is used to specify a custom comparator
+   * function for comparing elements in the heap. The comparator function is used to determine the
+   * order of elements in the heap.
+   */
   constructor(elements: Iterable<E> = [], options?: HeapOptions<E>) {
     super();
 
@@ -45,12 +55,20 @@ export class Heap<E = any> extends IterableElementBase<E> {
     }
   };
 
+  /**
+   * The function returns the value of the _comparator property.
+   * @returns The `_comparator` property is being returned.
+   */
   get comparator() {
     return this._comparator;
   }
 
   protected _elements: E[] = [];
 
+  /**
+   * The function returns an array of elements.
+   * @returns The elements array is being returned.
+   */
   get elements(): E[] {
     return this._elements;
   }
@@ -81,12 +99,13 @@ export class Heap<E = any> extends IterableElementBase<E> {
   }
 
   /**
-   * Time Complexity: O(log n), where n is the number of elements in the heap.
+   * Time Complexity: O(log n)
    * Space Complexity: O(1)
+   * where n is the number of elements in the heap.
    */
 
   /**
-   * Time Complexity: O(log n), where n is the number of elements in the heap.
+   * Time Complexity: O(log n)
    * Space Complexity: O(1)
    *
    * Insert an element into the heap and maintain the heap properties.
@@ -98,12 +117,13 @@ export class Heap<E = any> extends IterableElementBase<E> {
   }
 
   /**
-   * Time Complexity: O(log n), where n is the number of elements in the heap.
+   * Time Complexity: O(log n)
    * Space Complexity: O(1)
+   * where n is the number of elements in the heap.
    */
 
   /**
-   * Time Complexity: O(log n), where n is the number of elements in the heap.
+   * Time Complexity: O(log n)
    * Space Complexity: O(1)
    *
    * Remove and return the top element (smallest or largest element) from the heap.
@@ -121,6 +141,9 @@ export class Heap<E = any> extends IterableElementBase<E> {
   }
 
   /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   *
    * Peek at the top element of the heap without removing it.
    * @returns The top element or undefined if the heap is empty.
    */
@@ -391,6 +414,9 @@ export class Heap<E = any> extends IterableElementBase<E> {
     return mappedHeap;
   }
 
+  /**
+   * The function `_getIterator` returns an iterable iterator for the elements in the class.
+   */
   protected* _getIterator(): IterableIterator<E> {
     for (const element of this.elements) {
       yield element;
@@ -458,6 +484,16 @@ export class FibonacciHeapNode<E> {
   parent?: FibonacciHeapNode<E>;
   marked: boolean;
 
+  /**
+   * The constructor function initializes an object with an element and a degree, and sets the marked
+   * property to false.
+   * @param {E} element - The "element" parameter represents the value or data that will be stored in
+   * the node of a data structure. It can be any type of data, such as a number, string, object, or
+   * even another data structure.
+   * @param [degree=0] - The degree parameter represents the degree of the element in a data structure
+   * called a Fibonacci heap. The degree of a node is the number of children it has. By default, the
+   * degree is set to 0 when a new node is created.
+   */
   constructor(element: E, degree = 0) {
     this.element = element;
     this.degree = degree;
@@ -466,6 +502,13 @@ export class FibonacciHeapNode<E> {
 }
 
 export class FibonacciHeap<E> {
+  /**
+   * The constructor function initializes a FibonacciHeap object with an optional comparator function.
+   * @param [comparator] - The `comparator` parameter is an optional argument that represents a
+   * function used to compare elements in the FibonacciHeap. If a comparator function is provided, it
+   * will be used to determine the order of elements in the heap. If no comparator function is
+   * provided, a default comparator function will be used.
+   */
   constructor(comparator?: Comparator<E>) {
     this.clear();
     this._comparator = comparator || this._defaultComparator;
@@ -477,24 +520,41 @@ export class FibonacciHeap<E> {
 
   protected _root?: FibonacciHeapNode<E>;
 
+  /**
+   * The function returns the root node of a Fibonacci heap.
+   * @returns The method is returning either a FibonacciHeapNode object or undefined.
+   */
   get root(): FibonacciHeapNode<E> | undefined {
     return this._root;
   }
 
   protected _size = 0;
 
+  /**
+   * The function returns the size of an object.
+   * @returns The size of the object, which is a number.
+   */
   get size(): number {
     return this._size;
   }
 
   protected _min?: FibonacciHeapNode<E>;
 
+  /**
+   * The function returns the minimum node in a Fibonacci heap.
+   * @returns The method is returning the minimum node of the Fibonacci heap, which is of type
+   * `FibonacciHeapNode<E>`. If there is no minimum node, it will return `undefined`.
+   */
   get min(): FibonacciHeapNode<E> | undefined {
     return this._min;
   }
 
   protected _comparator: Comparator<E>;
 
+  /**
+   * The function returns the comparator used for comparing elements.
+   * @returns The `_comparator` property of the object.
+   */
   get comparator(): Comparator<E> {
     return this._comparator;
   }
@@ -808,12 +868,12 @@ export class FibonacciHeap<E> {
   }
 
   /**
-   * Time Complexity: O(n log n), where n is the number of elements in the heap.
+   * Time Complexity: O(n log n)
    * Space Complexity: O(n)
    */
 
   /**
-   * Time Complexity: O(n log n), where n is the number of elements in the heap.
+   * Time Complexity: O(n log n)
    * Space Complexity: O(n)
    *
    * Remove and return the top element (smallest or largest element) from the heap.