data-structure-typed 1.51.8 → 1.51.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "data-structure-typed",
-  "version": "1.51.8",
+  "version": "1.51.9",
   "description": "Javascript Data Structure. Heap, Binary Tree, Red Black Tree, Linked List, Deque, Trie, HashMap, Directed Graph, Undirected Graph, Binary Search Tree(BST), AVL Tree, Priority Queue, Graph, Queue, Tree Multiset, Singly Linked List, Doubly Linked List, Max Heap, Max Priority Queue, Min Heap, Min Priority Queue, Stack. Benchmark compared with C++ STL. API aligned with ES6 and Java.util. Usability is comparable to Python",
   "main": "dist/cjs/index.js",
   "module": "dist/mjs/index.js",
@@ -66,11 +66,11 @@
     "@typescript-eslint/eslint-plugin": "^6.7.4",
     "@typescript-eslint/parser": "^6.7.4",
     "auto-changelog": "^2.4.0",
-    "avl-tree-typed": "^1.51.7",
+    "avl-tree-typed": "^1.51.8",
     "benchmark": "^2.1.4",
-    "binary-tree-typed": "^1.51.7",
-    "bst-typed": "^1.51.7",
-    "data-structure-typed": "^1.51.7",
+    "binary-tree-typed": "^1.51.8",
+    "bst-typed": "^1.51.8",
+    "data-structure-typed": "^1.51.8",
     "dependency-cruiser": "^14.1.0",
     "doctoc": "^2.2.1",
     "eslint": "^8.50.0",
@@ -79,7 +79,7 @@
     "eslint-import-resolver-typescript": "^3.6.1",
     "eslint-plugin-import": "^2.28.1",
     "fast-glob": "^3.3.1",
-    "heap-typed": "^1.51.7",
+    "heap-typed": "^1.51.8",
     "istanbul-badges-readme": "^1.8.5",
     "jest": "^29.7.0",
     "js-sdsl": "^4.4.2",

package/src/data-structures/binary-tree/avl-tree-multi-map.ts

@@ -16,6 +16,7 @@ import type {
   IterationType,
   KeyOrNodeOrEntry
 } from '../../types';
+import { BTNEntry } from '../../types';
 import { IBinaryTree } from '../../interfaces';
 import { AVLTree, AVLTreeNode } from './avl-tree';
 
@@ -65,19 +66,36 @@ export class AVLTreeMultiMapNode<
 export class AVLTreeMultiMap<
   K extends Comparable,
   V = any,
+  R = BTNEntry<K, V>,
   NODE extends AVLTreeMultiMapNode<K, V, NODE> = AVLTreeMultiMapNode<K, V, AVLTreeMultiMapNodeNested<K, V>>,
-  TREE extends AVLTreeMultiMap<K, V, NODE, TREE> = AVLTreeMultiMap<K, V, NODE, AVLTreeMultiMapNested<K, V, NODE>>
+  TREE extends AVLTreeMultiMap<K, V, R, NODE, TREE> = AVLTreeMultiMap<
+    K,
+    V,
+    R,
+    NODE,
+    AVLTreeMultiMapNested<K, V, R, NODE>
+  >
 >
-  extends AVLTree<K, V, NODE, TREE>
-  implements IBinaryTree<K, V, NODE, TREE> {
-  constructor(keysOrNodesOrEntries: Iterable<KeyOrNodeOrEntry<K, V, NODE>> = [], options?: AVLTreeMultiMapOptions<K>) {
+  extends AVLTree<K, V, R, NODE, TREE>
+  implements IBinaryTree<K, V, R, NODE, TREE> {
+  /**
+   * The constructor initializes a new AVLTreeMultiMap object with optional initial elements.
+   * @param keysOrNodesOrEntriesOrRawElements - The `keysOrNodesOrEntriesOrRawElements` parameter is an
+   * iterable object that can contain either keys, nodes, entries, or raw elements.
+   * @param [options] - The `options` parameter is an optional object that can be used to customize the
+   * behavior of the AVLTreeMultiMap. It can include properties such as `compareKeys` and
+   * `compareValues` functions to define custom comparison logic for keys and values, respectively.
+   */
+  constructor(
+    keysOrNodesOrEntriesOrRawElements: Iterable<R | KeyOrNodeOrEntry<K, V, NODE>> = [],
+    options?: AVLTreeMultiMapOptions<K, V, R>
+  ) {
     super([], options);
-    if (keysOrNodesOrEntries) this.addMany(keysOrNodesOrEntries);
+    if (keysOrNodesOrEntriesOrRawElements) this.addMany(keysOrNodesOrEntriesOrRawElements);
   }
 
   protected _count = 0;
 
-  // TODO the _count is not accurate after nodes count modified
   /**
    * The function calculates the sum of the count property of all nodes in a tree using depth-first
    * search.
@@ -107,20 +125,29 @@ export class AVLTreeMultiMap<
   }
 
   /**
-   * The function creates a new BSTNode with the given key, value, and count.
-   * @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 {NODE} 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).
+   * The function creates a new AVLTreeMultiMapNode with the specified key, value, and count.
+   * @param {K} key - The key parameter represents the key of the node being created. It is of type K,
+   * which is a generic type that can be replaced with any specific type when using the function.
+   * @param {V} [value] - The `value` parameter is an optional parameter that represents the value
+   * associated with the key in the node. It is of type `V`, which can be any data type.
+   * @param {number} [count] - The `count` parameter represents the number of occurrences of a
+   * key-value pair in the AVLTreeMultiMapNode. It is an optional parameter, so it can be omitted when
+   * calling the `createNode` method. If provided, it specifies the initial count for the node.
+   * @returns a new instance of the AVLTreeMultiMapNode class, casted as NODE.
    */
   override createNode(key: K, value?: V, count?: number): NODE {
     return new AVLTreeMultiMapNode(key, value, count) as NODE;
   }
 
-  override createTree(options?: AVLTreeMultiMapOptions<K>): TREE {
-    return new AVLTreeMultiMap<K, V, NODE, TREE>([], {
+  /**
+   * The function creates a new AVLTreeMultiMap object with the specified options and returns it.
+   * @param [options] - The `options` parameter is an optional object that contains additional
+   * configuration options for creating the AVLTreeMultiMap. It can have the following properties:
+   * @returns a new instance of the AVLTreeMultiMap class, with the specified options, as a TREE
+   * object.
+   */
+  override createTree(options?: AVLTreeMultiMapOptions<K, V, R>): TREE {
+    return new AVLTreeMultiMap<K, V, R, NODE, TREE>([], {
       iterationType: this.iterationType,
       comparator: this.comparator,
       ...options
@@ -128,49 +155,52 @@ export class AVLTreeMultiMap<
   }
 
   /**
-   * The function `keyValueOrEntryToNode` converts an keyOrNodeOrEntry object into a node object.
-   * @param keyOrNodeOrEntry - The `keyOrNodeOrEntry` parameter is of type `KeyOrNodeOrEntry<K, V, NODE>`, 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`.
+   * The function checks if the input is an instance of AVLTreeMultiMapNode.
+   * @param {R | KeyOrNodeOrEntry<K, V, NODE>} keyOrNodeOrEntryOrRawElement - The parameter
+   * `keyOrNodeOrEntryOrRawElement` can be of type `R` or `KeyOrNodeOrEntry<K, V, NODE>`.
+   * @returns a boolean value indicating whether the input parameter `keyOrNodeOrEntryOrRawElement` is
+   * an instance of the `AVLTreeMultiMapNode` class.
+   */
+  override isNode(
+    keyOrNodeOrEntryOrRawElement: R | KeyOrNodeOrEntry<K, V, NODE>
+  ): keyOrNodeOrEntryOrRawElement is NODE {
+    return keyOrNodeOrEntryOrRawElement instanceof AVLTreeMultiMapNode;
+  }
+
+  /**
+   * The function `keyValueOrEntryOrRawElementToNode` converts a key, value, entry, or raw element into
+   * a node object.
+   * @param {R | KeyOrNodeOrEntry<K, V, NODE>} keyOrNodeOrEntryOrRawElement - The
+   * `keyOrNodeOrEntryOrRawElement` parameter can be of type `R` or `KeyOrNodeOrEntry<K, V, NODE>`.
+   * @param {V} [value] - The `value` parameter is an optional value that can be passed to the
+   * `override` function. It represents the value associated with the key in the data structure. If no
+   * value is provided, it will default to `undefined`.
    * @param [count=1] - The `count` parameter is an optional parameter that specifies the number of
-   * times the value should be added to the node. If not provided, it defaults to 1.
-   * @returns a node of type `NODE` or `undefined`.
+   * times the key-value pair should be added to the data structure. If not provided, it defaults to 1.
+   * @returns either a NODE object or undefined.
    */
-  override keyValueOrEntryToNode(
-    keyOrNodeOrEntry: KeyOrNodeOrEntry<K, V, NODE>,
+  override keyValueOrEntryOrRawElementToNode(
+    keyOrNodeOrEntryOrRawElement: R | KeyOrNodeOrEntry<K, V, NODE>,
     value?: V,
     count = 1
   ): NODE | undefined {
-    let node: NODE | undefined;
-    if (keyOrNodeOrEntry === undefined || keyOrNodeOrEntry === null) {
-      return;
-    } else if (this.isNode(keyOrNodeOrEntry)) {
-      node = keyOrNodeOrEntry;
-    } else if (this.isEntry(keyOrNodeOrEntry)) {
-      const [key, value] = keyOrNodeOrEntry;
-      if (key === undefined || key === null) {
-        return;
-      } else {
-        node = this.createNode(key, value, count);
-      }
-    } else if (!this.isNode(keyOrNodeOrEntry)) {
-      node = this.createNode(keyOrNodeOrEntry, value, count);
-    } else {
-      return;
+    if (keyOrNodeOrEntryOrRawElement === undefined || keyOrNodeOrEntryOrRawElement === null) return;
+    if (this.isNode(keyOrNodeOrEntryOrRawElement)) return keyOrNodeOrEntryOrRawElement;
+
+    if (this.toEntryFn) {
+      const [key, entryValue] = this.toEntryFn(keyOrNodeOrEntryOrRawElement as R);
+      if (key) return this.createNode(key, entryValue ?? value, count);
     }
-    return node;
-  }
 
-  /**
-   * The function checks if an keyOrNodeOrEntry is an instance of the AVLTreeMultiMapNode class.
-   * @param keyOrNodeOrEntry - The `keyOrNodeOrEntry` parameter is of type `KeyOrNodeOrEntry<K, V, NODE>`.
-   * @returns a boolean value indicating whether the keyOrNodeOrEntry is an instance of the AVLTreeMultiMapNode
-   * class.
-   */
-  override isNode(keyOrNodeOrEntry: KeyOrNodeOrEntry<K, V, NODE>): keyOrNodeOrEntry is NODE {
-    return keyOrNodeOrEntry instanceof AVLTreeMultiMapNode;
+    if (this.isEntry(keyOrNodeOrEntryOrRawElement)) {
+      const [key, value] = keyOrNodeOrEntryOrRawElement;
+      if (key === undefined || key === null) return;
+      else return this.createNode(key, value, count);
+    }
+
+    if (this.isKey(keyOrNodeOrEntryOrRawElement)) return this.createNode(keyOrNodeOrEntryOrRawElement, value, count);
+
+    return;
   }
 
   /**
@@ -182,20 +212,21 @@ export class AVLTreeMultiMap<
    * Time Complexity: O(log n)
    * Space Complexity: O(1)
    *
-   * 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.
+   * The function overrides the add method of a TypeScript class to add a new node to a data structure
+   * and update the count.
+   * @param {R | KeyOrNodeOrEntry<K, V, NODE>} keyOrNodeOrEntryOrRawElement - The
+   * `keyOrNodeOrEntryOrRawElement` parameter can accept a value of type `R`, which can be any type. It
+   * can also accept a value of type `KeyOrNodeOrEntry<K, V, NODE>`, which represents a key, node,
+   * entry, or raw element
    * @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.
+   * data structure. It is an optional parameter, so it can be omitted if not needed.
    * @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.
+   * be added to the data structure. 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 a boolean value.
    */
-  override add(keyOrNodeOrEntry: KeyOrNodeOrEntry<K, V, NODE>, value?: V, count = 1): boolean {
-    const newNode = this.keyValueOrEntryToNode(keyOrNodeOrEntry, value, count);
+  override add(keyOrNodeOrEntryOrRawElement: R | KeyOrNodeOrEntry<K, V, NODE>, value?: V, count = 1): boolean {
+    const newNode = this.keyValueOrEntryOrRawElementToNode(keyOrNodeOrEntryOrRawElement, value, count);
     if (newNode === undefined) return false;
 
     const orgNodeCount = newNode?.count || 0;
@@ -215,19 +246,19 @@ export class AVLTreeMultiMap<
    * Time Complexity: O(log n)
    * Space Complexity: O(1)
    *
-   * The `delete` function in TypeScript is used to remove a node from a binary tree, taking into
-   * account the count of the node and balancing the tree if necessary.
-   * @param identifier - The identifier is the value or key that is used to identify the node that
-   * needs to be deleted from the binary tree. It can be of any type that is returned by the callback
+   * The `delete` function in a binary tree data structure deletes a node based on its identifier and
+   * returns the deleted node along with the parent node that needs to be balanced.
+   * @param identifier - The identifier parameter is the value used to identify the node that needs to
+   * be deleted from the binary tree. It can be of any type and is the return type of the callback
    * function.
-   * @param {C} callback - The `callback` parameter is a function that is used to determine if a node
-   * should be deleted. It is optional and defaults to a default callback function. The `callback`
-   * function takes one parameter, which is the identifier of the node, and returns a value that is
-   * used to identify the node to
+   * @param {C} callback - The `callback` parameter is a function that is used to determine the
+   * equality of nodes in the binary tree. It is optional and has a default value of
+   * `this._DEFAULT_CALLBACK`. The `callback` function takes a single argument, which is the identifier
+   * of a node, and returns a value that
    * @param [ignoreCount=false] - A boolean flag indicating whether to ignore the count of the node
    * being deleted. If set to true, the count of the node will not be considered and the node will be
-   * deleted regardless of its count. If set to false (default), the count of the node will be
-   * decremented by 1 and
+   * deleted regardless of its count. If set to false (default), the count of the node will be taken
+   * into account and the node
    * @returns an array of `BinaryTreeDeleteResult<NODE>`.
    */
   override delete<C extends BTNCallback<NODE>>(
@@ -300,7 +331,8 @@ export class AVLTreeMultiMap<
    * Time Complexity: O(1)
    * Space Complexity: O(1)
    *
-   * The clear() function clears the contents of a data structure and sets the count to zero.
+   * The "clear" function overrides the parent class's "clear" function and also resets the count to
+   * zero.
    */
   override clear() {
     super.clear();
@@ -315,13 +347,14 @@ export class AVLTreeMultiMap<
   /**
    * Time Complexity: O(n log n)
    * Space Complexity: O(log n)
-   *
    * The `perfectlyBalance` function takes a sorted array of nodes and builds a balanced binary search
    * tree using either a recursive or iterative approach.
-   * @param iterationType - The `iterationType` parameter is an optional parameter that specifies the
-   * type of iteration to use when building the balanced binary search tree. It can have two possible
-   * values:
-   * @returns a boolean value.
+   * @param {IterationType} iterationType - The `iterationType` parameter is an optional parameter that
+   * specifies the type of iteration to use when building the balanced binary search tree. It has a
+   * default value of `this.iterationType`, which means it will use the iteration type currently set in
+   * the object.
+   * @returns The function `perfectlyBalance` returns a boolean value. It returns `true` if the
+   * balancing operation is successful, and `false` if there are no nodes to balance.
    */
   override perfectlyBalance(iterationType: IterationType = this.iterationType): boolean {
     const sorted = this.dfs(node => node, 'IN'),
@@ -370,7 +403,7 @@ export class AVLTreeMultiMap<
    * Time complexity: O(n)
    * Space complexity: O(n)
    *
-   * The `clone` function creates a deep copy of a tree object.
+   * The function overrides the clone method to create a deep copy of a tree object.
    * @returns The `clone()` method is returning a cloned instance of the `TREE` object.
    */
   override clone(): TREE {
@@ -380,17 +413,26 @@ export class AVLTreeMultiMap<
   }
 
   /**
-   * The `_swapProperties` function swaps the key, value, count, and height properties between two nodes.
-   * @param {K | NODE | undefined} srcNode - The `srcNode` parameter represents the source node from
-   * which the values will be swapped. It can be of type `K`, `NODE`, or `undefined`.
-   * @param {K | NODE | 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.
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   */
+
+  /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   *
+   * The `_swapProperties` function swaps the properties (key, value, count, height) between two nodes
+   * in a binary search tree.
+   * @param {R | BSTNKeyOrNode<K, NODE>} srcNode - The `srcNode` parameter represents the source node
+   * that will be swapped with the `destNode`.
+   * @param {R | BSTNKeyOrNode<K, NODE>} destNode - The `destNode` parameter represents the destination
+   * node where the properties will be swapped with the source node.
+   * @returns The method is returning the `destNode` after swapping its properties with the `srcNode`.
+   * If either `srcNode` or `destNode` is undefined, it returns `undefined`.
    */
   protected override _swapProperties(
-    srcNode: BSTNKeyOrNode<K, NODE>,
-    destNode: BSTNKeyOrNode<K, NODE>
+    srcNode: R | BSTNKeyOrNode<K, NODE>,
+    destNode: R | BSTNKeyOrNode<K, NODE>
   ): NODE | undefined {
     srcNode = this.ensureNode(srcNode);
     destNode = this.ensureNode(destNode);
@@ -417,12 +459,20 @@ export class AVLTreeMultiMap<
   }
 
   /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   */
+
+  /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   *
    * The function replaces an old node with a new node and updates the count property of the new node.
-   * @param {NODE} oldNode - The `oldNode` parameter is of type `NODE` and represents the node that
-   * needs to be replaced in a data structure.
-   * @param {NODE} newNode - The `newNode` parameter is an object of type `NODE`.
+   * @param {NODE} oldNode - The oldNode parameter represents the node that needs to be replaced in the
+   * data structure. It is of type NODE.
+   * @param {NODE} newNode - The `newNode` parameter is an instance of the `NODE` class.
    * @returns The method is returning the result of calling the `_replaceNode` method from the
-   * superclass, after updating the `count` property of the `newNode` object.
+   * superclass, which is of type `NODE`.
    */
   protected override _replaceNode(oldNode: NODE, newNode: NODE): NODE {
     newNode.count = oldNode.count + newNode.count;

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

@@ -16,6 +16,7 @@ import type {
   Comparable,
   KeyOrNodeOrEntry
 } from '../../types';
+import { BTNEntry } from '../../types';
 import { IBinaryTree } from '../../interfaces';
 
 export class AVLTreeNode<
@@ -68,33 +69,39 @@ export class AVLTreeNode<
 export class AVLTree<
   K extends Comparable,
   V = any,
+  R = BTNEntry<K, V>,
   NODE extends AVLTreeNode<K, V, NODE> = AVLTreeNode<K, V, AVLTreeNodeNested<K, V>>,
-  TREE extends AVLTree<K, V, NODE, TREE> = AVLTree<K, V, NODE, AVLTreeNested<K, V, NODE>>
+  TREE extends AVLTree<K, V, R, NODE, TREE> = AVLTree<K, V, R, NODE, AVLTreeNested<K, V, R, NODE>>
 >
-  extends BST<K, V, NODE, TREE>
-  implements IBinaryTree<K, V, NODE, TREE> {
+  extends BST<K, V, R, NODE, TREE>
+  implements IBinaryTree<K, V, R, NODE, TREE> {
   /**
-   * The constructor function initializes an AVLTree object with optional keysOrNodesOrEntries and options.
-   * @param [keysOrNodesOrEntries] - The `keysOrNodesOrEntries` parameter is an optional iterable of `KeyOrNodeOrEntry<K, V, NODE>`
-   * objects. It represents a collection of nodes that will be added to the AVL tree during
-   * initialization.
-   * @param [options] - The `options` parameter is an optional object that allows you to customize the
-   * behavior of the AVL tree. It is of type `Partial<AVLTreeOptions>`, which means that you can
-   * provide only a subset of the properties defined in the `AVLTreeOptions` interface.
+   * This is a constructor function for an AVLTree class that initializes the tree with keys, nodes,
+   * entries, or raw elements.
+   * @param keysOrNodesOrEntriesOrRawElements - The `keysOrNodesOrEntriesOrRawElements` parameter is an
+   * iterable object that can contain either keys, nodes, entries, or raw elements. These elements will
+   * be used to initialize the AVLTree.
+   * @param [options] - The `options` parameter is an optional object that can be used to customize the
+   * behavior of the AVLTree. It can include properties such as `compareFn` (a function used to compare
+   * keys), `allowDuplicates` (a boolean indicating whether duplicate keys are allowed), and
+   * `nodeBuilder` (
    */
-  constructor(keysOrNodesOrEntries: Iterable<KeyOrNodeOrEntry<K, V, NODE>> = [], options?: AVLTreeOptions<K>) {
+  constructor(
+    keysOrNodesOrEntriesOrRawElements: Iterable<R | KeyOrNodeOrEntry<K, V, NODE>> = [],
+    options?: AVLTreeOptions<K, V, R>
+  ) {
     super([], options);
-    if (keysOrNodesOrEntries) super.addMany(keysOrNodesOrEntries);
+    if (keysOrNodesOrEntriesOrRawElements) super.addMany(keysOrNodesOrEntriesOrRawElements);
   }
 
   /**
-   * The function creates a new AVL tree node with the specified key and value.
-   * @param {K} key - The key parameter is the key value that will be associated with
-   * the new node. It is used to determine the position of the node in the binary search tree.
-   * @param [value] - The parameter `value` is an optional value that can be assigned to the node. It is of
-   * type `V`, which means it can be any value that is assignable to the `value` property of the
-   * node type `NODE`.
-   * @returns a new AVLTreeNode object with the specified key and value.
+   * The function creates a new AVL tree node with the given key and value.
+   * @param {K} key - The key parameter is of type K, which represents the key of the node being
+   * created.
+   * @param {V} [value] - The "value" parameter is an optional parameter of type V. It represents the
+   * value associated with the key in the node being created.
+   * @returns The method is returning a new instance of the AVLTreeNode class, casted as the generic
+   * type NODE.
    */
   override createNode(key: K, value?: V): NODE {
     return new AVLTreeNode<K, V, NODE>(key, value) as NODE;
@@ -107,8 +114,8 @@ export class AVLTree<
    * being created.
    * @returns a new AVLTree object.
    */
-  override createTree(options?: AVLTreeOptions<K>): TREE {
-    return new AVLTree<K, V, NODE, TREE>([], {
+  override createTree(options?: AVLTreeOptions<K, V, R>): TREE {
+    return new AVLTree<K, V, R, NODE, TREE>([], {
       iterationType: this.iterationType,
       comparator: this.comparator,
       ...options
@@ -116,12 +123,16 @@ export class AVLTree<
   }
 
   /**
-   * The function checks if an keyOrNodeOrEntry is an instance of AVLTreeNode.
-   * @param keyOrNodeOrEntry - The `keyOrNodeOrEntry` parameter is of type `KeyOrNodeOrEntry<K, V, NODE>`.
-   * @returns a boolean value indicating whether the keyOrNodeOrEntry is an instance of the AVLTreeNode class.
+   * The function checks if the input is an instance of AVLTreeNode.
+   * @param {R | KeyOrNodeOrEntry<K, V, NODE>} keyOrNodeOrEntryOrRawElement - The parameter
+   * `keyOrNodeOrEntryOrRawElement` can be of type `R` or `KeyOrNodeOrEntry<K, V, NODE>`.
+   * @returns a boolean value indicating whether the input parameter `keyOrNodeOrEntryOrRawElement` is
+   * an instance of the `AVLTreeNode` class.
    */
-  override isNode(keyOrNodeOrEntry: KeyOrNodeOrEntry<K, V, NODE>): keyOrNodeOrEntry is NODE {
-    return keyOrNodeOrEntry instanceof AVLTreeNode;
+  override isNode(
+    keyOrNodeOrEntryOrRawElement: R | KeyOrNodeOrEntry<K, V, NODE>
+  ): keyOrNodeOrEntryOrRawElement is NODE {
+    return keyOrNodeOrEntryOrRawElement instanceof AVLTreeNode;
   }
 
   /**
@@ -134,18 +145,19 @@ export class AVLTree<
    * Time Complexity: O(log n)
    * Space Complexity: O(1)
    *
-   * The function overrides the add method of a binary tree node and balances the tree after inserting
-   * a new node.
-   * @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 tree.
-   * @returns The method is returning either the inserted node or undefined.
+   * The function overrides the add method of a class and inserts a key-value pair into a data
+   * structure, then balances the path.
+   * @param {R | KeyOrNodeOrEntry<K, V, NODE>} keyOrNodeOrEntryOrRawElement - The parameter
+   * `keyOrNodeOrEntryOrRawElement` can accept values of type `R`, `KeyOrNodeOrEntry<K, V, NODE>`, or
+   * `RawElement`.
+   * @param {V} [value] - The `value` parameter is an optional value that you want to associate with
+   * the key or node being added to the data structure.
+   * @returns The method is returning a boolean value.
    */
-  override add(keyOrNodeOrEntry: KeyOrNodeOrEntry<K, V, NODE>, value?: V): boolean {
-    if (keyOrNodeOrEntry === null) return false;
-    const inserted = super.add(keyOrNodeOrEntry, value);
-    if (inserted) this._balancePath(keyOrNodeOrEntry);
+  override add(keyOrNodeOrEntryOrRawElement: R | KeyOrNodeOrEntry<K, V, NODE>, value?: V): boolean {
+    if (keyOrNodeOrEntryOrRawElement === null) return false;
+    const inserted = super.add(keyOrNodeOrEntryOrRawElement, value);
+    if (inserted) this._balancePath(keyOrNodeOrEntryOrRawElement);
     return inserted;
   }
 
@@ -158,16 +170,14 @@ export class AVLTree<
    * Time Complexity: O(log n)
    * Space Complexity: O(1)
    *
-   * The function overrides the delete method of a binary tree, performs the deletion, and then
-   * balances the tree if necessary.
+   * The function overrides the delete method of a binary tree class and performs additional operations
+   * to balance the tree after deletion.
    * @param identifier - The `identifier` parameter is the value or condition used to identify the
-   * node(s) to be deleted from the binary tree. It can be of any type and is the return type of the
-   * `callback` function.
-   * @param {C} callback - The `callback` parameter is a function that will be called for each node
-   * that is deleted from the binary tree. It is an optional parameter and if not provided, it will
-   * default to the `_DEFAULT_CALLBACK` function. The `callback` function should have a single
-   * parameter of type `NODE
-   * @returns The method is returning an array of `BinaryTreeDeleteResult<NODE>`.
+   * node(s) to be deleted from the binary tree. It can be of any type that is compatible with the
+   * binary tree's node type.
+   * @param {C} callback - The `callback` parameter is a function that will be used to determine if a
+   * node should be deleted or not. It is optional and has a default value of `this._DEFAULT_CALLBACK`.
+   * @returns The method is returning an array of BinaryTreeDeleteResult<NODE> objects.
    */
   override delete<C extends BTNCallback<NODE>>(
     identifier: ReturnType<C>,
@@ -183,18 +193,26 @@ export class AVLTree<
   }
 
   /**
-   * The `_swapProperties` function swaps the key, value, and height properties between two nodes in a binary
-   * tree.
-   * @param {K | NODE | undefined} srcNode - The `srcNode` parameter represents the source node that
-   * needs to be swapped with the destination node. It can be of type `K`, `NODE`, or `undefined`.
-   * @param {K | NODE  | 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.
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   */
+
+  /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   *
+   * The `_swapProperties` function swaps the key, value, and height properties between two nodes in a
+   * binary search tree.
+   * @param {R | BSTNKeyOrNode<K, NODE>} srcNode - The `srcNode` parameter represents either a node
+   * object (`NODE`) or a key-value pair (`R`) that is being swapped with another node.
+   * @param {R | BSTNKeyOrNode<K, NODE>} destNode - The `destNode` parameter is either an instance of
+   * `R` or an instance of `BSTNKeyOrNode<K, NODE>`.
+   * @returns The method is returning the `destNodeEnsured` object if both `srcNodeEnsured` and
+   * `destNodeEnsured` are truthy. Otherwise, it returns `undefined`.
    */
   protected override _swapProperties(
-    srcNode: BSTNKeyOrNode<K, NODE>,
-    destNode: BSTNKeyOrNode<K, NODE>
+    srcNode: R | BSTNKeyOrNode<K, NODE>,
+    destNode: R | BSTNKeyOrNode<K, NODE>
   ): NODE | undefined {
     const srcNodeEnsured = this.ensureNode(srcNode);
     const destNodeEnsured = this.ensureNode(destNode);
@@ -230,7 +248,8 @@ export class AVLTree<
    * Space Complexity: O(1)
    *
    * The function calculates the balance factor of a node in a binary tree.
-   * @param {NODE} node - The parameter "node" represents a node in a binary tree data structure.
+   * @param {NODE} node - The parameter "node" is of type "NODE", which likely represents a node in a
+   * binary tree data structure.
    * @returns the balance factor of a given node. The balance factor is calculated by subtracting the
    * height of the left subtree from the height of the right subtree.
    */
@@ -275,7 +294,7 @@ export class AVLTree<
    * Time Complexity: O(1)
    * Space Complexity: O(1)
    *
-   * The function `_balanceLL` performs a left-left rotation to balance a binary tree.
+   * The `_balanceLL` function performs a left-left rotation to balance a binary search tree.
    * @param {NODE} A - A is a node in a binary tree.
    */
   protected _balanceLL(A: NODE): void {
@@ -470,10 +489,10 @@ export class AVLTree<
    *
    * The `_balancePath` function is used to update the heights of nodes and perform rotation operations
    * to restore balance in an AVL tree after inserting a node.
-   * @param {NODE} node - The `node` parameter in the `_balancePath` function represents the node in the
-   * AVL tree that needs to be balanced.
+   * @param {R | KeyOrNodeOrEntry<K, V, NODE>} node - The `node` parameter can be of type `R` or
+   * `KeyOrNodeOrEntry<K, V, NODE>`.
    */
-  protected _balancePath(node: KeyOrNodeOrEntry<K, V, NODE>): void {
+  protected _balancePath(node: R | KeyOrNodeOrEntry<K, V, NODE>): void {
     node = this.ensureNode(node);
     const path = this.getPathToRoot(node, false); // first O(log n) + O(log n)
     for (let i = 0; i < path.length; i++) {
@@ -514,13 +533,22 @@ export class AVLTree<
   }
 
   /**
-   * The function replaces an old node with a new node while preserving the height of the old node.
-   * @param {NODE} oldNode - The `oldNode` parameter is the node that you want to replace with the
-   * `newNode`.
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   */
+
+  /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   *
+   * The function replaces an old node with a new node and sets the height of the new node to be the
+   * same as the old node.
+   * @param {NODE} oldNode - The `oldNode` parameter represents the node that needs to be replaced in
+   * the data structure.
    * @param {NODE} newNode - The `newNode` parameter is the new node that will replace the `oldNode` in
    * the data structure.
-   * @returns the result of calling the `_replaceNode` method on the superclass, passing in the
-   * `oldNode` and `newNode` as arguments.
+   * @returns The method is returning the result of calling the `_replaceNode` method from the
+   * superclass, with the `oldNode` and `newNode` as arguments.
    */
   protected override _replaceNode(oldNode: NODE, newNode: NODE): NODE {
     newNode.height = oldNode.height;