min-heap-typed 1.49.8 → 1.50.0

package/src/data-structures/binary-tree/bst.ts

@@ -13,7 +13,7 @@ import type {
   BTNodePureExemplar,
   KeyOrNodeOrEntry
 } from '../../types';
-import { BSTVariant, CP, IterationType } from '../../types';
+import { BSTVariant, CP, DFSOrderPattern, IterationType } from '../../types';
 import { BinaryTree, BinaryTreeNode } from './binary-tree';
 import { IBinaryTree } from '../../interfaces';
 import { Queue } from '../queue';
@@ -171,7 +171,7 @@ export class BST<
       } else {
         node = this.createNode(key, value);
       }
-    } else if (this.isNotNodeInstance(keyOrNodeOrEntry)) {
+    } else if (!this.isNode(keyOrNodeOrEntry)) {
       node = this.createNode(keyOrNodeOrEntry, value);
     } else {
       return;
@@ -212,16 +212,6 @@ export class BST<
     return res;
   }
 
-  /**
-   * The function "isNotNodeInstance" checks if a potential key is a K.
-   * @param {any} potentialKey - The potentialKey parameter is of type any, which means it can be any
-   * data type.
-   * @returns a boolean value indicating whether the potentialKey is of type number or not.
-   */
-  override isNotNodeInstance(potentialKey: KeyOrNodeOrEntry<K, V, N>): potentialKey is K {
-    return !(potentialKey instanceof BSTNode);
-  }
-
   /**
    * The function checks if an keyOrNodeOrEntry is an instance of BSTNode.
    * @param keyOrNodeOrEntry - The `keyOrNodeOrEntry` parameter is a variable of type `KeyOrNodeOrEntry<K, V, N>`.
@@ -407,43 +397,6 @@ export class BST<
     return inserted;
   }
 
-  /**
-   * Time Complexity: O(n log n)
-   * Space Complexity: O(n)
-   * Adding each element individually in a balanced tree. Additional space is required for the sorted array.
-   */
-
-  /**
-   * Time Complexity: O(n log n)
-   * Space Complexity: O(n)
-   *
-   * The `lastKey` function returns the key of the rightmost node in a binary tree, or the key of the
-   * leftmost node if the comparison result is greater than.
-   * @param {K | N | undefined} beginRoot - The `beginRoot` parameter is optional and can be of
-   * type `K`, `N`, or `undefined`. It represents the starting point for finding the last key in
-   * the binary tree. If not provided, it defaults to the root of the binary tree (`this.root`).
-   * @returns the key of the rightmost node in the binary tree if the comparison result is less than,
-   * the key of the leftmost node if the comparison result is greater than, and the key of the
-   * rightmost node otherwise. If no node is found, it returns 0.
-   */
-  lastKey(beginRoot: KeyOrNodeOrEntry<K, V, N> = this.root): K | undefined {
-    let current = this.ensureNode(beginRoot);
-    if (!current) return undefined;
-
-    if (this._variant === BSTVariant.STANDARD) {
-      // For BSTVariant.MIN, find the rightmost node
-      while (current.right !== undefined) {
-        current = current.right;
-      }
-    } else {
-      // For BSTVariant.MAX, find the leftmost node
-      while (current.left !== undefined) {
-        current = current.left;
-      }
-    }
-    return current.key;
-  }
-
   /**
    * Time Complexity: O(log n)
    * Space Complexity: O(1)
@@ -573,6 +526,157 @@ export class BST<
     return ans;
   }
 
+  // /**
+  //  * The function overrides the subTreeTraverse method and returns the result of calling the super
+  //  * method with the provided arguments.
+  //  * @param {C} callback - The `callback` parameter is a function that will be called for each node in
+  //  * the subtree traversal. It should accept a single parameter of type `N`, which represents a node in
+  //  * the tree. The return type of the callback function can be any type.
+  //  * @param beginRoot - The `beginRoot` parameter is the starting point for traversing the subtree. It
+  //  * can be either a key, a node, or an entry.
+  //  * @param iterationType - The `iterationType` parameter is used to specify the type of iteration to
+  //  * be performed during the traversal of the subtree. It can have one of the following values:
+  //  * @returns The method is returning an array of the return type of the callback function.
+  //  */
+  // override subTreeTraverse<C extends BTNCallback<N>>(
+  //   callback: C = this._defaultOneParamCallback as C,
+  //   beginRoot: KeyOrNodeOrEntry<K, V, N> = this.root,
+  //   iterationType = this.iterationType
+  // ): ReturnType<C>[] {
+  //   return super.subTreeTraverse(callback, beginRoot, iterationType, false);
+  // }
+
+  /**
+   * Time complexity: O(n)
+   * Space complexity: O(n)
+   */
+
+  /**
+   * Time complexity: O(n)
+   * Space complexity: O(n)
+   *
+   * The function overrides the depth-first search method and returns an array of the return types of
+   * the callback function.
+   * @param {C} callback - The `callback` parameter is a function that will be called for each node
+   * during the depth-first search traversal. It is an optional parameter and if not provided, a
+   * default callback function will be used.
+   * @param {DFSOrderPattern} [pattern=in] - The `pattern` parameter specifies the order in which the
+   * nodes are visited during the depth-first search. It can have one of the following values:
+   * @param beginRoot - The `beginRoot` parameter is used to specify the starting point for the
+   * Depth-First Search (DFS) traversal. It can be either a key, a node, or an entry in the tree. If no
+   * value is provided, the DFS traversal will start from the root of the tree.
+   * @param {IterationType} iterationType - The `iterationType` parameter specifies the type of
+   * iteration to be used during the Depth-First Search (DFS) traversal. It can have one of the
+   * following values:
+   * @returns The method is returning an array of the return type of the callback function.
+   */
+  override dfs<C extends BTNCallback<N>>(
+    callback: C = this._defaultOneParamCallback as C,
+    pattern: DFSOrderPattern = 'in',
+    beginRoot: KeyOrNodeOrEntry<K, V, N> = this.root,
+    iterationType: IterationType = IterationType.ITERATIVE
+  ): ReturnType<C>[] {
+    return super.dfs(callback, pattern, beginRoot, iterationType, false);
+  }
+
+  /**
+   * Time complexity: O(n)
+   * Space complexity: O(n)
+   */
+
+  /**
+   * Time complexity: O(n)
+   * Space complexity: O(n)
+   *
+   * The function overrides the breadth-first search method and returns an array of the return types of
+   * the callback function.
+   * @param {C} callback - The `callback` parameter is a function that will be called for each node
+   * visited during the breadth-first search traversal. It is an optional parameter and if not
+   * provided, a default callback function will be used.
+   * @param beginRoot - The `beginRoot` parameter is the starting point for the breadth-first search
+   * traversal. It can be either a key, a node, or an entry in the tree. If not specified, the root of
+   * the tree is used as the starting point.
+   * @param iterationType - The `iterationType` parameter is used to specify the type of iteration to
+   * be performed during the breadth-first search (BFS) traversal. It determines the order in which the
+   * nodes are visited.
+   * @returns The method is returning an array of the return type of the callback function.
+   */
+  override bfs<C extends BTNCallback<N>>(
+    callback: C = this._defaultOneParamCallback as C,
+    beginRoot: KeyOrNodeOrEntry<K, V, N> = this.root,
+    iterationType = this.iterationType
+  ): ReturnType<C>[] {
+    return super.bfs(callback, beginRoot, iterationType, false);
+  }
+
+  /**
+   * Time complexity: O(n)
+   * Space complexity: O(n)
+   */
+
+  /**
+   * Time complexity: O(n)
+   * Space complexity: O(n)
+   *
+   * The function overrides the listLevels method and returns an array of arrays containing the return
+   * type of the callback function for each level of the tree.
+   * @param {C} callback - The `callback` parameter is a generic type `C` that extends
+   * `BTNCallback<N>`. It represents a callback function that will be called for each node in the tree
+   * during the level listing process.
+   * @param beginRoot - The `beginRoot` parameter is used to specify the starting point for listing the
+   * levels of a binary tree. It can be either a key, a node, or an entry in the binary tree. If not
+   * provided, the root of the binary tree is used as the starting point.
+   * @param iterationType - The `iterationType` parameter is used to specify the type of iteration to
+   * be performed on the tree. It determines the order in which the nodes are visited during the
+   * iteration.
+   * @returns The method is returning a two-dimensional array of the return type of the callback
+   * function.
+   */
+  override listLevels<C extends BTNCallback<N>>(
+    callback: C = this._defaultOneParamCallback as C,
+    beginRoot: KeyOrNodeOrEntry<K, V, N> = this.root,
+    iterationType = this.iterationType
+  ): ReturnType<C>[][] {
+    return super.listLevels(callback, beginRoot, iterationType, false);
+  }
+
+  /**
+   * Time Complexity: O(n log n)
+   * Space Complexity: O(n)
+   * Adding each element individually in a balanced tree. Additional space is required for the sorted array.
+   */
+
+  /**
+   * Time Complexity: O(n log n)
+   * Space Complexity: O(n)
+   *
+   * The `lastKey` function returns the key of the rightmost node in a binary tree, or the key of the
+   * leftmost node if the comparison result is greater than.
+   * @param {K | N | undefined} beginRoot - The `beginRoot` parameter is optional and can be of
+   * type `K`, `N`, or `undefined`. It represents the starting point for finding the last key in
+   * the binary tree. If not provided, it defaults to the root of the binary tree (`this.root`).
+   * @returns the key of the rightmost node in the binary tree if the comparison result is less than,
+   * the key of the leftmost node if the comparison result is greater than, and the key of the
+   * rightmost node otherwise. If no node is found, it returns 0.
+   */
+  lastKey(beginRoot: KeyOrNodeOrEntry<K, V, N> = this.root): K | undefined {
+    let current = this.ensureNode(beginRoot);
+    if (!current) return undefined;
+
+    if (this._variant === BSTVariant.STANDARD) {
+      // For BSTVariant.MIN, find the rightmost node
+      while (current.right !== undefined) {
+        current = current.right;
+      }
+    } else {
+      // For BSTVariant.MAX, find the leftmost node
+      while (current.left !== undefined) {
+        current = current.left;
+      }
+    }
+    return current.key;
+  }
+
   /**
    * Time Complexity: O(log n)
    * Space Complexity: O(log n)

package/src/data-structures/binary-tree/rb-tree.ts

@@ -132,7 +132,7 @@ export class RedBlackTree<
       } else {
         node = this.createNode(key, value, RBTNColor.RED);
       }
-    } else if (this.isNotNodeInstance(keyOrNodeOrEntry)) {
+    } else if (!this.isNode(keyOrNodeOrEntry)) {
       node = this.createNode(keyOrNodeOrEntry, value, RBTNColor.RED);
     } else {
       return;
@@ -160,16 +160,6 @@ export class RedBlackTree<
     return node instanceof RedBlackTreeNode;
   }
 
-  /**
-   * The function "isNotNodeInstance" checks if a potential key is a K.
-   * @param {any} potentialKey - The potentialKey parameter is of type any, which means it can be any
-   * data type.
-   * @returns a boolean value indicating whether the potentialKey is of type number or not.
-   */
-  override isNotNodeInstance(potentialKey: KeyOrNodeOrEntry<K, V, N>): potentialKey is K {
-    return !(potentialKey instanceof RedBlackTreeNode);
-  }
-
   /**
    * Time Complexity: O(log n)
    * Space Complexity: O(1)

package/src/data-structures/binary-tree/tree-multimap.ts

@@ -62,7 +62,7 @@ export class TreeMultimap<
   // TODO the _count is not accurate after nodes count modified
   get count(): number {
     let sum = 0;
-    this.subTreeTraverse(node => (sum += node.count));
+    this.dfs(node => (sum += node.count));
     return sum;
   }
 
@@ -111,7 +111,7 @@ export class TreeMultimap<
       } else {
         node = this.createNode(key, value, count);
       }
-    } else if (this.isNotNodeInstance(keyOrNodeOrEntry)) {
+    } else if (!this.isNode(keyOrNodeOrEntry)) {
       node = this.createNode(keyOrNodeOrEntry, value, count);
     } else {
       return;
@@ -129,16 +129,6 @@ export class TreeMultimap<
     return keyOrNodeOrEntry instanceof TreeMultimapNode;
   }
 
-  /**
-   * The function "isNotNodeInstance" checks if a potential key is a K.
-   * @param {any} potentialKey - The potentialKey parameter is of type any, which means it can be any
-   * data type.
-   * @returns a boolean value indicating whether the potentialKey is of type number or not.
-   */
-  override isNotNodeInstance(potentialKey: KeyOrNodeOrEntry<K, V, N>): potentialKey is K {
-    return !(potentialKey instanceof TreeMultimapNode);
-  }
-
   /**
    * Time Complexity: O(log n)
    * Space Complexity: O(1)

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

@@ -21,29 +21,46 @@ import { isWeakKey, rangeCheck } from '../../utils';
  * 3. Unique Keys: Keys are unique. If you try to insert another entry with the same key, the old entry will be replaced by the new one.
  * 4. Unordered Collection: HashMap does not guarantee the order of entries, and the order may change over time.
  */
-export class HashMap<K = any, V = any> extends IterableEntryBase<K, V> {
+export class HashMap<K = any, V = any, R = [K, V]> extends IterableEntryBase<K, V> {
   protected _store: { [key: string]: HashMapStoreItem<K, V> } = {};
   protected _objMap: Map<object, V> = new Map();
 
   /**
-   * The constructor function initializes a new instance of a class with optional entries and options.
-   * @param entries - The `entries` parameter is an iterable containing key-value pairs `[K, V]`. It
-   * is optional and defaults to an empty array `[]`. This parameter is used to initialize the map with
-   * key-value pairs.
-   * @param [options] - The `options` parameter is an optional object that can contain additional
-   * configuration options for the constructor. In this case, it has one property:
+   * The constructor function initializes a HashMap object with an optional initial collection and
+   * options.
+   * @param rawCollection - The `rawCollection` parameter is an iterable collection of elements of type
+   * `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(entries: Iterable<[K, V]> = [], options?: HashMapOptions<K>) {
+  constructor(rawCollection: Iterable<R> = [], options?: HashMapOptions<K, V, R>) {
     super();
     if (options) {
-      const { hashFn } = options;
+      const { hashFn, toEntryFn } = options;
       if (hashFn) {
         this._hashFn = hashFn;
       }
+      if (toEntryFn) {
+        this._toEntryFn = toEntryFn;
+      }
     }
-    if (entries) {
-      this.setMany(entries);
+    if (rawCollection) {
+      this.setMany(rawCollection);
+    }
+  }
+
+  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."
+      );
     }
+  };
+
+  get toEntryFn() {
+    return this._toEntryFn;
   }
 
   protected _size = 0;
@@ -52,6 +69,10 @@ export class HashMap<K = any, V = any> extends IterableEntryBase<K, V> {
     return this._size;
   }
 
+  isEntry(rawElement: any): rawElement is [K, V] {
+    return Array.isArray(rawElement) && rawElement.length === 2;
+  }
+
   isEmpty(): boolean {
     return this.size === 0;
   }
@@ -88,13 +109,18 @@ export class HashMap<K = any, V = any> extends IterableEntryBase<K, V> {
   }
 
   /**
-   * The function "setMany" sets multiple key-value pairs in a map.
-   * @param entries - The `entries` parameter is an iterable containing key-value pairs. Each
-   * key-value pair is represented as an array with two entries: the key and the value.
+   * 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 rawCollection - The `rawCollection` parameter is an iterable collection of elements of type
+   * `T`.
+   * @returns The `setMany` function is returning an array of booleans.
    */
-  setMany(entries: Iterable<[K, V]>): boolean[] {
+  setMany(rawCollection: Iterable<R>): boolean[] {
     const results: boolean[] = [];
-    for (const [key, value] of entries) results.push(this.set(key, value));
+    for (const rawEle of rawCollection) {
+      const [key, value] = this.toEntryFn(rawEle);
+      results.push(this.set(key, value));
+    }
     return results;
   }
 

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

@@ -10,8 +10,9 @@ export type LinkedHashMapOptions<K> = {
   objHashFn?: (key: K) => object;
 };
 
-export type HashMapOptions<K> = {
+export type HashMapOptions<K, V, T> = {
   hashFn?: (key: K) => string;
+  toEntryFn?: (rawElement: T) => [K, V];
 };
 
 export type HashMapStoreItem<K, V> = { key: K; value: V };