directed-graph-typed 1.48.0 → 1.49.0

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

@@ -10,8 +10,8 @@ import {
   BiTreeDeleteResult,
   BSTNodeKeyOrNode,
   BTNCallback,
-  BTNKey,
   BTNodeExemplar,
+  BTNodeKeyOrNode,
   IterationType,
   RBTNColor,
   RBTreeOptions,
@@ -22,13 +22,13 @@ import { BST, BSTNode } from './bst';
 import { IBinaryTree } from '../../interfaces';
 import { BinaryTreeNode } from './binary-tree';
 
-export class RedBlackTreeNode<V = any, N extends RedBlackTreeNode<V, N> = RedBlackTreeNodeNested<V>> extends BSTNode<
-  V,
+export class RedBlackTreeNode<K = any, V = any, N extends RedBlackTreeNode<K, V, N> = RedBlackTreeNodeNested<K, V>> extends BSTNode<
+  K, V,
   N
 > {
   color: RBTNColor;
 
-  constructor(key: BTNKey, value?: V, color: RBTNColor = RBTNColor.BLACK) {
+  constructor(key: K, value?: V, color: RBTNColor = RBTNColor.BLACK) {
     super(key, value);
     this.color = color;
   }
@@ -41,15 +41,15 @@ export class RedBlackTreeNode<V = any, N extends RedBlackTreeNode<V, N> = RedBla
  * 4. Red nodes must have black children.
  * 5. Black balance: Every path from any node to each of its leaf nodes contains the same number of black nodes.
  */
-export class RedBlackTree<V = any, N extends RedBlackTreeNode<V, N> = RedBlackTreeNode<V, RedBlackTreeNodeNested<V>>, TREE extends RedBlackTree<V, N, TREE> = RedBlackTree<V, N, RedBlackTreeNested<V, N>>>
-  extends BST<V, N, TREE>
-  implements IBinaryTree<V, N, TREE> {
-  Sentinel: N = new RedBlackTreeNode<V>(NaN) as unknown as N;
+export class RedBlackTree<K = any, V = any, N extends RedBlackTreeNode<K, V, N> = RedBlackTreeNode<K, V, RedBlackTreeNodeNested<K, V>>, TREE extends RedBlackTree<K, V, N, TREE> = RedBlackTree<K, V, N, RedBlackTreeNested<K, V, N>>>
+  extends BST<K, V, N, TREE>
+  implements IBinaryTree<K, V, N, TREE> {
+  Sentinel: N = new RedBlackTreeNode<K, V>(NaN as K) as unknown as N;
 
   /**
    * This is the constructor function for a Red-Black Tree data structure in TypeScript, which
    * initializes the tree with optional elements and options.
-   * @param [elements] - The `elements` parameter is an optional iterable of `BTNodeExemplar<V, N>`
+   * @param [elements] - The `elements` parameter is an optional iterable of `BTNodeExemplar<K, V, N>`
    * objects. It represents the initial elements that will be added to the RBTree during its
    * construction. If this parameter is provided, the `addMany` method is called to add all the
    * elements to the
@@ -57,7 +57,7 @@ export class RedBlackTree<V = any, N extends RedBlackTreeNode<V, N> = RedBlackTr
    * behavior of the RBTree. It is of type `Partial<RBTreeOptions>`, which means that you can provide
    * only a subset of the properties defined in the `RBTreeOptions` interface.
    */
-  constructor(elements?: Iterable<BTNodeExemplar<V, N>>, options?: Partial<RBTreeOptions>) {
+  constructor(elements?: Iterable<BTNodeExemplar<K, V, N>>, options?: Partial<RBTreeOptions<K>>) {
     super([], options);
 
     this._root = this.Sentinel;
@@ -78,7 +78,7 @@ export class RedBlackTree<V = any, N extends RedBlackTreeNode<V, N> = RedBlackTr
 
   /**
    * The function creates a new Red-Black Tree node with the specified key, value, and color.
-   * @param {BTNKey} key - The key parameter is the key value associated with the node. It is used to
+   * @param {K} key - The key parameter is the key value associated with the node. It is used to
    * identify and compare nodes in the Red-Black Tree.
    * @param {V} [value] - The `value` parameter is an optional parameter that represents the value
    * associated with the node. It is of type `V`, which is a generic type that can be replaced with any
@@ -88,8 +88,8 @@ export class RedBlackTree<V = any, N extends RedBlackTreeNode<V, N> = RedBlackTr
    * @returns The method is returning a new instance of a RedBlackTreeNode with the specified key,
    * value, and color.
    */
-  override createNode(key: BTNKey, value?: V, color: RBTNColor = RBTNColor.BLACK): N {
-    return new RedBlackTreeNode<V, N>(key, value, color) as N;
+  override createNode(key: K, value?: V, color: RBTNColor = RBTNColor.BLACK): N {
+    return new RedBlackTreeNode<K, V, N>(key, value, color) as N;
   }
 
   /**
@@ -99,32 +99,42 @@ export class RedBlackTree<V = any, N extends RedBlackTreeNode<V, N> = RedBlackTr
    * class.
    * @returns a new instance of a RedBlackTree object.
    */
-  override createTree(options?: RBTreeOptions): TREE {
-    return new RedBlackTree<V, N, TREE>([], {
+  override createTree(options?: RBTreeOptions<K>): TREE {
+    return new RedBlackTree<K, V, N, TREE>([], {
       iterationType: this.iterationType,
-      comparator: this.comparator, ...options
+      variant: this.variant, ...options
     }) as TREE;
   }
 
   /**
    * The function checks if an exemplar is an instance of the RedBlackTreeNode class.
-   * @param exemplar - The `exemplar` parameter is of type `BTNodeExemplar<V, N>`.
+   * @param exemplar - The `exemplar` parameter is of type `BTNodeExemplar<K, V, N>`.
    * @returns a boolean value indicating whether the exemplar is an instance of the RedBlackTreeNode
    * class.
    */
-  override isNode(exemplar: BTNodeExemplar<V, N>): exemplar is N {
+  override isNode(exemplar: BTNodeExemplar<K, V, N>): exemplar is N {
     return exemplar instanceof RedBlackTreeNode;
   }
 
   /**
-   * The function `exemplarToNode` takes an exemplar and returns a node if the exemplar is valid,
-   * otherwise it returns undefined.
-   * @param exemplar - BTNodeExemplar<V, N> - A generic type representing an exemplar of a binary tree
-   * node. It can be either a node itself, an entry (key-value pair), a node key, or any other value
-   * that is not a valid exemplar.
-   * @returns a variable `node` which is of type `N | undefined`.
+   * 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 exemplarToNode(exemplar: BTNodeExemplar<V, N>): N | undefined {
+  override isNotNodeInstance(potentialKey: BTNodeKeyOrNode<K, N>): potentialKey is K {
+    return !(potentialKey instanceof RedBlackTreeNode)
+  }
+
+  /**
+   * The function `exemplarToNode` takes an exemplar and converts it into a node object if possible.
+   * @param exemplar - The `exemplar` parameter is of type `BTNodeExemplar<K, V, N>`, where:
+   * @param {V} [value] - The `value` parameter is an optional value that can be passed to the
+   * `exemplarToNode` function. It represents the value associated with the exemplar node. If a value
+   * is provided, it will be used when creating the new node. If no value is provided, the new node
+   * @returns a node of type N or undefined.
+   */
+  override exemplarToNode(exemplar: BTNodeExemplar<K, V, N>, value?: V): N | undefined {
     let node: N | undefined;
 
     if (exemplar === null || exemplar === undefined) {
@@ -138,8 +148,8 @@ export class RedBlackTree<V = any, N extends RedBlackTreeNode<V, N> = RedBlackTr
       } else {
         node = this.createNode(key, value, RBTNColor.RED);
       }
-    } else if (this.isNodeKey(exemplar)) {
-      node = this.createNode(exemplar, undefined, RBTNColor.RED);
+    } else if (this.isNotNodeInstance(exemplar)) {
+      node = this.createNode(exemplar, value, RBTNColor.RED);
     } else {
       return;
     }
@@ -152,13 +162,19 @@ export class RedBlackTree<V = any, N extends RedBlackTreeNode<V, N> = RedBlackTr
    */
 
   /**
-   * The function adds a node to a Red-Black Tree data structure.
-   * @param keyOrNodeOrEntry - The `keyOrNodeOrEntry` parameter can be one of the following:
-   * @returns The method `add` returns either an instance of `N` (the node that was added) or
-   * `undefined`.
+   * Time Complexity: O(log n) on average (where n is the number of nodes in the tree)
+   * Space Complexity: O(1)
+   *
+   * The `add` function adds a new node to a binary search tree and performs necessary rotations and
+   * color changes to maintain the red-black tree properties.
+   * @param keyOrNodeOrEntry - The `keyOrNodeOrEntry` parameter can be either a key, a node, or an
+   * entry.
+   * @param {V} [value] - The `value` parameter represents the value associated with the key that is
+   * being added to the binary search tree.
+   * @returns The method `add` returns either the newly added node (`N`) or `undefined`.
    */
-  override add(keyOrNodeOrEntry: BTNodeExemplar<V, N>): N | undefined {
-    const newNode = this.exemplarToNode(keyOrNodeOrEntry);
+  override add(keyOrNodeOrEntry: BTNodeExemplar<K, V, N>, value?: V): N | undefined {
+    const newNode = this.exemplarToNode(keyOrNodeOrEntry, value);
     if (newNode === undefined) return;
 
     newNode.left = this.Sentinel;
@@ -295,11 +311,12 @@ export class RedBlackTree<V = any, N extends RedBlackTreeNode<V, N> = RedBlackTr
    */
 
   override isRealNode(node: N | undefined): node is N {
-    return node !== this.Sentinel && node !== undefined;
+    if (node === this.Sentinel || node === undefined) return false;
+    return node instanceof RedBlackTreeNode;
   }
 
-  getNode<C extends BTNCallback<N, BTNKey>>(
-    identifier: BTNKey,
+  getNode<C extends BTNCallback<N, K>>(
+    identifier: K,
     callback?: C,
     beginRoot?: N | undefined,
     iterationType?: IterationType
@@ -337,7 +354,7 @@ export class RedBlackTree<V = any, N extends RedBlackTreeNode<V, N> = RedBlackTr
    * @param {C} callback - The `callback` parameter is a function that will be called for each node in
    * the binary tree. It is used to determine if a node matches the given identifier. The `callback`
    * function should take a single parameter of type `N` (the type of the nodes in the binary tree) and
-   * @param {BTNKey | N | undefined} beginRoot - The `beginRoot` parameter is the starting point for
+   * @param {K | N | undefined} beginRoot - The `beginRoot` parameter is the starting point for
    * searching for a node in a binary tree. It can be either a key value or a node object. If it is not
    * provided, the search will start from the root of the binary tree.
    * @param iterationType - The `iterationType` parameter is a variable that determines the type of
@@ -348,7 +365,7 @@ export class RedBlackTree<V = any, N extends RedBlackTreeNode<V, N> = RedBlackTr
   getNode<C extends BTNCallback<N>>(
     identifier: ReturnType<C> | undefined,
     callback: C = this._defaultOneParamCallback as C,
-    beginRoot: BSTNodeKeyOrNode<N> = this.root,
+    beginRoot: BSTNodeKeyOrNode<K, N> = this.root,
     iterationType = this.iterationType
   ): N | null | undefined {
     if ((identifier as any) instanceof BinaryTreeNode) callback = (node => node) as C;
@@ -357,38 +374,12 @@ export class RedBlackTree<V = any, N extends RedBlackTreeNode<V, N> = RedBlackTr
   }
 
   /**
-   * Time Complexity: O(log n) on average (where n is the number of nodes in the tree)
+   * Time Complexity: O(log n)
    * Space Complexity: O(1)
    */
 
   /**
-   * Time Complexity: O(log n) on average (where n is the number of nodes in the tree)
-   * Space Complexity: O(1)
-   *
-   * The function returns the successor of a given node in a red-black tree.
-   * @param {RedBlackTreeNode} x - RedBlackTreeNode - The node for which we want to find the successor.
-   * @returns the successor of the given RedBlackTreeNode.
-   */
-  override getSuccessor(x: N): N | undefined {
-    if (x.right !== this.Sentinel) {
-      return this.getLeftMost(x.right) ?? undefined;
-    }
-
-    let y: N | undefined = x.parent;
-    while (y !== this.Sentinel && y !== undefined && x === y.right) {
-      x = y;
-      y = y.parent;
-    }
-    return y;
-  }
-
-  /**
-   * Time Complexity: O(log n) on average (where n is the number of nodes in the tree)
-   * Space Complexity: O(1)
-   */
-
-  /**
-   * Time Complexity: O(log n) on average (where n is the number of nodes in the tree)
+   * Time Complexity: O(log n)
    * Space Complexity: O(1)
    *
    * The function returns the predecessor of a given node in a red-black tree.
@@ -397,12 +388,12 @@ export class RedBlackTree<V = any, N extends RedBlackTreeNode<V, N> = RedBlackTr
    * @returns the predecessor of the given RedBlackTreeNode 'x'.
    */
   override getPredecessor(x: N): N {
-    if (x.left !== this.Sentinel) {
-      return this.getRightMost(x.left!)!;
+    if (this.isRealNode(x.left)) {
+      return this.getRightMost(x.left)!;
     }
 
     let y: N | undefined = x.parent;
-    while (y !== this.Sentinel && x === y!.left) {
+    while (this.isRealNode(y) && x === y.left) {
       x = y!;
       y = y!.parent;
     }

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

@@ -5,26 +5,28 @@
  * @copyright Copyright (c) 2022 Tyler Zeng <zrwusa@gmail.com>
  * @license MIT License
  */
-import type {
-  BSTNodeKeyOrNode,
-  BTNKey,
-  BTNodeExemplar,
-  TreeMultimapNodeNested,
-  TreeMultimapOptions
+import type { BSTNodeKeyOrNode, BTNodeExemplar, TreeMultimapNodeNested, TreeMultimapOptions } from '../../types';
+import {
+  BiTreeDeleteResult,
+  BTNCallback,
+  BTNodeKeyOrNode,
+  FamilyPosition,
+  IterationType,
+  TreeMultimapNested
 } from '../../types';
-import { BiTreeDeleteResult, BTNCallback, FamilyPosition, IterationType, TreeMultimapNested } from '../../types';
 import { IBinaryTree } from '../../interfaces';
 import { AVLTree, AVLTreeNode } from './avl-tree';
 
 export class TreeMultimapNode<
+  K = any,
   V = any,
-  N extends TreeMultimapNode<V, N> = TreeMultimapNodeNested<V>
-> extends AVLTreeNode<V, N> {
+  N extends TreeMultimapNode<K, V, N> = TreeMultimapNodeNested<K, V>
+> extends AVLTreeNode<K, V, N> {
   count: number;
 
   /**
    * The constructor function initializes a BinaryTreeNode object with a key, value, and count.
-   * @param {BTNKey} key - The `key` parameter is of type `BTNKey` and represents the unique identifier
+   * @param {K} key - The `key` parameter is of type `K` and represents the unique identifier
    * of the binary tree node.
    * @param {V} [value] - The `value` parameter is an optional parameter of type `V`. It represents the value of the binary
    * tree node. If no value is provided, it will be `undefined`.
@@ -32,7 +34,7 @@ export class TreeMultimapNode<
    * occurs in a binary tree node. It has a default value of 1, which means that if no value is provided for the `count`
    * parameter when creating a new instance of the `BinaryTreeNode` class.
    */
-  constructor(key: BTNKey, value?: V, count = 1) {
+  constructor(key: K, value?: V, count = 1) {
     super(key, value);
     this.count = count;
   }
@@ -41,12 +43,12 @@ export class TreeMultimapNode<
 /**
  * The only distinction between a TreeMultimap and a AVLTree lies in the ability of the former to store duplicate nodes through the utilization of counters.
  */
-export class TreeMultimap<V = any, N extends TreeMultimapNode<V, N> = TreeMultimapNode<V, TreeMultimapNodeNested<V>>,
-  TREE extends TreeMultimap<V, N, TREE> = TreeMultimap<V, N, TreeMultimapNested<V, N>>>
-  extends AVLTree<V, N, TREE>
-  implements IBinaryTree<V, N, TREE> {
+export class TreeMultimap<K = any, V = any, N extends TreeMultimapNode<K, V, N> = TreeMultimapNode<K, V, TreeMultimapNodeNested<K, V>>,
+  TREE extends TreeMultimap<K, V, N, TREE> = TreeMultimap<K, V, N, TreeMultimapNested<K, V, N>>>
+  extends AVLTree<K, V, N, TREE>
+  implements IBinaryTree<K, V, N, TREE> {
 
-  constructor(elements?: Iterable<BTNodeExemplar<V, N>>, options?: Partial<TreeMultimapOptions>) {
+  constructor(elements?: Iterable<BTNodeExemplar<K, V, N>>, options?: Partial<TreeMultimapOptions<K>>) {
     super([], options);
     if (elements) this.addMany(elements);
   }
@@ -62,43 +64,56 @@ export class TreeMultimap<V = any, N extends TreeMultimapNode<V, N> = TreeMultim
 
   /**
    * The function creates a new BSTNode with the given key, value, and count.
-   * @param {BTNKey} key - The key parameter is the unique identifier for the binary tree node. It is used to
+   * @param {K} key - The key parameter is the unique identifier for the binary tree node. It is used to
    * distinguish one node from another in the tree.
    * @param {N} value - The `value` parameter represents the value that will be stored in the binary search tree node.
    * @param {number} [count] - The "count" parameter is an optional parameter of type number. It represents the number of
    * occurrences of the value in the binary search tree node. If not provided, the count will default to 1.
    * @returns A new instance of the BSTNode class with the specified key, value, and count (if provided).
    */
-  override createNode(key: BTNKey, value?: V, count?: number): N {
+  override createNode(key: K, value?: V, count?: number): N {
     return new TreeMultimapNode(key, value, count) as N;
   }
 
-  override createTree(options?: TreeMultimapOptions): TREE {
-    return new TreeMultimap<V, N, TREE>([], {
+  override createTree(options?: TreeMultimapOptions<K>): TREE {
+    return new TreeMultimap<K, V, N, TREE>([], {
       iterationType: this.iterationType,
-      comparator: this.comparator, ...options
+      variant: this.variant, ...options
     }) as TREE;
   }
 
   /**
    * The function checks if an exemplar is an instance of the TreeMultimapNode class.
-   * @param exemplar - The `exemplar` parameter is of type `BTNodeExemplar<V, N>`.
+   * @param exemplar - The `exemplar` parameter is of type `BTNodeExemplar<K, V, N>`.
    * @returns a boolean value indicating whether the exemplar is an instance of the TreeMultimapNode
    * class.
    */
-  override isNode(exemplar: BTNodeExemplar<V, N>): exemplar is N {
+  override isNode(exemplar: BTNodeExemplar<K, V, N>): exemplar is N {
     return exemplar 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: BTNodeKeyOrNode<K, N>): potentialKey is K {
+    return !(potentialKey instanceof TreeMultimapNode)
+  }
+
   /**
    * The function `exemplarToNode` converts an exemplar object into a node object.
-   * @param exemplar - The `exemplar` parameter is of type `BTNodeExemplar<V, N>`, where `V` represents
-   * the value type and `N` represents the node type.
+   * @param exemplar - The `exemplar` parameter is of type `BTNodeExemplar<K, V, N>`, which means it
+   * can be one of the following:
+   * @param {V} [value] - The `value` parameter is an optional argument that represents the value
+   * associated with the node. It is of type `V`, which can be any data type. If no value is provided,
+   * it defaults to `undefined`.
    * @param [count=1] - The `count` parameter is an optional parameter that specifies the number of
-   * times the node should be created. If not provided, it defaults to 1.
-   * @returns a value of type `N` (the generic type parameter) or `undefined`.
+   * times the value should be added to the node. If not provided, it defaults to 1.
+   * @returns a node of type `N` or `undefined`.
    */
-  override exemplarToNode(exemplar: BTNodeExemplar<V, N>, count = 1): N | undefined {
+  override exemplarToNode(exemplar: BTNodeExemplar<K, V, N>, value?: V, count = 1): N | undefined {
     let node: N | undefined;
     if (exemplar === undefined || exemplar === null) {
       return;
@@ -111,8 +126,8 @@ export class TreeMultimap<V = any, N extends TreeMultimapNode<V, N> = TreeMultim
       } else {
         node = this.createNode(key, value, count);
       }
-    } else if (this.isNodeKey(exemplar)) {
-      node = this.createNode(exemplar, undefined, count);
+    } else if (this.isNotNodeInstance(exemplar)) {
+      node = this.createNode(exemplar, value, count);
     } else {
       return;
     }
@@ -128,16 +143,20 @@ export class TreeMultimap<V = any, N extends TreeMultimapNode<V, N> = TreeMultim
    * Time Complexity: O(log n) - logarithmic time, where "n" is the number of nodes in the tree. The add method of the superclass (AVLTree) has logarithmic time complexity.
    * Space Complexity: O(1) - constant space, as it doesn't use additional data structures that scale with input size.
    *
-   * The `add` function overrides the base class `add` function to add a new node to the tree multimap
-   * and update the count.
-   * @param keyOrNodeOrEntry - The `keyOrNodeOrEntry` parameter can be one of the following:
-   * @param [count=1] - The `count` parameter is an optional parameter that specifies the number of
-   * times the key or node or entry should be added to the multimap. If not provided, the default value
-   * is 1.
-   * @returns either a node (`N`) or `undefined`.
+   * The function overrides the add method of a binary tree node and adds a new node to the tree.
+   * @param keyOrNodeOrEntry - The `keyOrNodeOrEntry` parameter can be either a key, a node, or an
+   * entry. It represents the key, node, or entry that you want to add to the binary tree.
+   * @param {V} [value] - The `value` parameter represents the value associated with the key in the
+   * binary tree node. It is an optional parameter, meaning it can be omitted when calling the `add`
+   * method.
+   * @param [count=1] - The `count` parameter represents the number of times the key-value pair should
+   * be added to the binary tree. By default, it is set to 1, meaning that the key-value pair will be
+   * added once. However, you can specify a different value for `count` if you want to add
+   * @returns The method is returning either the newly inserted node or `undefined` if the insertion
+   * was not successful.
    */
-  override add(keyOrNodeOrEntry: BTNodeExemplar<V, N>, count = 1): N | undefined {
-    const newNode = this.exemplarToNode(keyOrNodeOrEntry, count);
+  override add(keyOrNodeOrEntry: BTNodeExemplar<K, V, N>, value?: V, count = 1): N | undefined {
+    const newNode = this.exemplarToNode(keyOrNodeOrEntry, value, count);
     if (newNode === undefined) return;
 
     const orgNodeCount = newNode?.count || 0;
@@ -163,7 +182,7 @@ export class TreeMultimap<V = any, N extends TreeMultimapNode<V, N> = TreeMultim
    * either keys, nodes, or entries.
    * @returns The method is returning an array of type `N | undefined`.
    */
-  override addMany(keysOrNodesOrEntries: Iterable<BTNodeExemplar<V, N>>): (N | undefined)[] {
+  override addMany(keysOrNodesOrEntries: Iterable<BTNodeExemplar<K, V, N>>): (N | undefined)[] {
     return super.addMany(keysOrNodesOrEntries);
   }
 
@@ -195,7 +214,7 @@ export class TreeMultimap<V = any, N extends TreeMultimapNode<V, N> = TreeMultim
         if (l > r) return;
         const m = l + Math.floor((r - l) / 2);
         const midNode = sorted[m];
-        this.add([midNode.key, midNode.value], midNode.count);
+        this.add(midNode.key, midNode.value, midNode.count);
         buildBalanceBST(l, m - 1);
         buildBalanceBST(m + 1, r);
       };
@@ -211,7 +230,7 @@ export class TreeMultimap<V = any, N extends TreeMultimapNode<V, N> = TreeMultim
           if (l <= r) {
             const m = l + Math.floor((r - l) / 2);
             const midNode = sorted[m];
-            this.add([midNode.key, midNode.value], midNode.count);
+            this.add(midNode.key, midNode.value, midNode.count);
             stack.push([m + 1, r]);
             stack.push([l, m - 1]);
           }
@@ -318,6 +337,24 @@ export class TreeMultimap<V = any, N extends TreeMultimapNode<V, N> = TreeMultim
     this._count = 0;
   }
 
+  /**
+   * Time complexity: O(n)
+   * Space complexity: O(n)
+   */
+
+  /**
+   * Time complexity: O(n)
+   * Space complexity: O(n)
+   *
+   * The `clone` function creates a deep copy of a tree object.
+   * @returns The `clone()` method is returning a cloned instance of the `TREE` object.
+   */
+  override clone(): TREE {
+    const cloned = this.createTree();
+    this.bfs(node => cloned.add(node.key, node.value, node.count));
+    return cloned;
+  }
+
   /**
    * Time Complexity: O(1) - constant time, as it performs basic pointer assignments.
    * Space Complexity: O(1) - constant space, as it only uses a constant amount of memory.
@@ -327,13 +364,13 @@ export class TreeMultimap<V = any, N extends TreeMultimapNode<V, N> = TreeMultim
    * @param {N | undefined} newNode - The `newNode` parameter represents the node that needs to be
    * added to the binary tree. It can be of type `N` (which represents a node in the binary tree) or
    * `undefined` if there is no node to add.
-   * @param {BTNKey | N | undefined} parent - The `parent` parameter represents the parent node to
+   * @param {K | N | undefined} parent - The `parent` parameter represents the parent node to
    * which the new node will be added as a child. It can be either a node object (`N`) or a key value
-   * (`BTNKey`).
+   * (`K`).
    * @returns The method `_addTo` returns either the `parent.left` or `parent.right` node that was
    * added, or `undefined` if no node was added.
    */
-  protected override _addTo(newNode: N | undefined, parent: BSTNodeKeyOrNode<N>): N | undefined {
+  protected override _addTo(newNode: N | undefined, parent: BSTNodeKeyOrNode<K, N>): N | undefined {
     parent = this.ensureNode(parent);
     if (parent) {
       if (parent.left === undefined) {
@@ -361,14 +398,14 @@ export class TreeMultimap<V = any, N extends TreeMultimapNode<V, N> = TreeMultim
 
   /**
    * The `_swapProperties` function swaps the key, value, count, and height properties between two nodes.
-   * @param {BTNKey | N | undefined} srcNode - The `srcNode` parameter represents the source node from
-   * which the values will be swapped. It can be of type `BTNKey`, `N`, or `undefined`.
-   * @param {BTNKey | N | undefined} destNode - The `destNode` parameter represents the destination
+   * @param {K | N | undefined} srcNode - The `srcNode` parameter represents the source node from
+   * which the values will be swapped. It can be of type `K`, `N`, or `undefined`.
+   * @param {K | N | undefined} destNode - The `destNode` parameter represents the destination
    * node where the values from the source node will be swapped to.
    * @returns either the `destNode` object if both `srcNode` and `destNode` are defined, or `undefined`
    * if either `srcNode` or `destNode` is undefined.
    */
-  protected override _swapProperties(srcNode: BSTNodeKeyOrNode<N>, destNode: BSTNodeKeyOrNode<N>): N | undefined {
+  protected override _swapProperties(srcNode: BSTNodeKeyOrNode<K, N>, destNode: BSTNodeKeyOrNode<K, N>): N | undefined {
     srcNode = this.ensureNode(srcNode);
     destNode = this.ensureNode(destNode);
     if (srcNode && destNode) {