stack-typed 1.48.8 → 1.49.0

package/dist/data-structures/queue/deque.js

@@ -7,7 +7,7 @@
  * @license MIT License
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ObjectDeque = exports.Deque = void 0;
+exports.Deque = void 0;
 const utils_1 = require("../../utils");
 const base_1 = require("../base");
 /**
@@ -792,174 +792,3 @@ class Deque extends base_1.IterableElementBase {
     }
 }
 exports.Deque = Deque;
-// O(1) time complexity of obtaining the element
-// O(n) time complexity of adding at the beginning and the end
-// todo tested slowest one
-class ObjectDeque {
-    constructor(capacity) {
-        this._nodes = {};
-        this._capacity = Number.MAX_SAFE_INTEGER;
-        this._first = -1;
-        this._last = -1;
-        this._size = 0;
-        if (capacity !== undefined)
-            this._capacity = capacity;
-    }
-    get nodes() {
-        return this._nodes;
-    }
-    get capacity() {
-        return this._capacity;
-    }
-    get first() {
-        return this._first;
-    }
-    get last() {
-        return this._last;
-    }
-    get size() {
-        return this._size;
-    }
-    /**
-     * Time Complexity: O(1)
-     * Space Complexity: O(1)
-     */
-    /**
-     * Time Complexity: O(1)
-     * Space Complexity: O(1)
-     *
-     * The "addFirst" function adds an element to the beginning of an array-like data structure.
-     * @param {E} element - The `element` parameter represents the element that you want to add to the beginning of the data
-     * structure.
-     */
-    addFirst(element) {
-        if (this.size === 0) {
-            const mid = Math.floor(this.capacity / 2);
-            this._first = mid;
-            this._last = mid;
-        }
-        else {
-            this._first--;
-        }
-        this.nodes[this.first] = element;
-        this._size++;
-    }
-    /**
-     * Time Complexity: O(1)
-     * Space Complexity: O(1)
-     */
-    /**
-     * Time Complexity: O(1)
-     * Space Complexity: O(1)
-     *
-     * The addLast function adds an element to the end of an array-like data structure.
-     * @param {E} element - The `element` parameter represents the element that you want to add to the end of the data structure.
-     */
-    addLast(element) {
-        if (this.size === 0) {
-            const mid = Math.floor(this.capacity / 2);
-            this._first = mid;
-            this._last = mid;
-        }
-        else {
-            this._last++;
-        }
-        this.nodes[this.last] = element;
-        this._size++;
-    }
-    /**
-     * Time Complexity: O(1)
-     * Space Complexity: O(1)
-     */
-    /**
-     * Time Complexity: O(1)
-     * Space Complexity: O(1)
-     *
-     * The function `pollFirst()` removes and returns the first element in a data structure.
-     * @returns The element of the first element in the data structure.
-     */
-    pollFirst() {
-        if (!this.size)
-            return;
-        const element = this.getFirst();
-        delete this.nodes[this.first];
-        this._first++;
-        this._size--;
-        return element;
-    }
-    /**
-     * Time Complexity: O(1)
-     * Space Complexity: O(1)
-     */
-    /**
-     * Time Complexity: O(1)
-     * Space Complexity: O(1)
-     *
-     * The `getFirst` function returns the first element in an array-like data structure if it exists.
-     * @returns The element at the first position of the `_nodes` array.
-     */
-    getFirst() {
-        if (this.size)
-            return this.nodes[this.first];
-    }
-    /**
-     * Time Complexity: O(1)
-     * Space Complexity: O(1)
-     */
-    /**
-     * Time Complexity: O(1)
-     * Space Complexity: O(1)
-     *
-     * The `pollLast()` function removes and returns the last element in a data structure.
-     * @returns The element that was removed from the data structure.
-     */
-    pollLast() {
-        if (!this.size)
-            return;
-        const element = this.getLast();
-        delete this.nodes[this.last];
-        this._last--;
-        this._size--;
-        return element;
-    }
-    /**
-     * Time Complexity: O(1)
-     * Space Complexity: O(1)
-     */
-    /**
-     * Time Complexity: O(1)
-     * Space Complexity: O(1)
-     *
-     * The `getLast()` function returns the last element in an array-like data structure.
-     * @returns The last element in the array "_nodes" is being returned.
-     */
-    getLast() {
-        if (this.size)
-            return this.nodes[this.last];
-    }
-    /**
-     * Time Complexity: O(1)
-     * Space Complexity: O(1)
-     */
-    /**
-     * Time Complexity: O(1)
-     * Space Complexity: O(1)
-     *
-     * The get function returns the element at the specified index in an array-like data structure.
-     * @param {number} index - The index parameter is a number that represents the position of the element you want to
-     * retrieve from the array.
-     * @returns The element at the specified index in the `_nodes` array is being returned. If there is no element at that
-     * index, `undefined` is returned.
-     */
-    get(index) {
-        return this.nodes[this.first + index] || undefined;
-    }
-    /**
-     * The function checks if the size of a data structure is less than or equal to zero.
-     * @returns The method is returning a boolean element indicating whether the size of the object is less than or equal to 0.
-     */
-    isEmpty() {
-        return this.size <= 0;
-    }
-}
-exports.ObjectDeque = ObjectDeque;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stack-typed",
-  "version": "1.48.8",
+  "version": "1.49.0",
   "description": "Stack. Javascript & Typescript Data Structure.",
   "main": "dist/index.js",
   "scripts": {
@@ -65,6 +65,6 @@
     "typescript": "^4.9.5"
   },
   "dependencies": {
-    "data-structure-typed": "^1.48.8"
+    "data-structure-typed": "^1.48.9"
   }
 }

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

@@ -14,7 +14,7 @@ import type {
   BSTNodeKeyOrNode,
   BTNodeExemplar
 } from '../../types';
-import { BTNCallback } from '../../types';
+import { BTNCallback, BTNodeKeyOrNode } from '../../types';
 import { IBinaryTree } from '../../interfaces';
 
 export class AVLTreeNode<K = any, V = any, N extends AVLTreeNode<K, V, N> = AVLTreeNodeNested<K, V>> extends BSTNode<K, V, N> {
@@ -90,6 +90,16 @@ export class AVLTree<K = any, V = any, N extends AVLTreeNode<K, V, N> = AVLTreeN
     return exemplar instanceof AVLTreeNode;
   }
 
+  /**
+   * 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 AVLTreeNode)
+  }
+
   /**
    * Time Complexity: O(log n) - logarithmic time, where "n" is the number of nodes in the tree. The add method of the superclass (BST) has logarithmic time complexity.
    * Space Complexity: O(1) - constant space, as it doesn't use additional data structures that scale with input size.

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

@@ -98,10 +98,6 @@ export class BinaryTreeNode<K = any, V = any, N extends BinaryTreeNode<K, V, N>
  * 3. Depth and Height: Depth is the number of edges from the root to a node; height is the maximum depth in the tree.
  * 4. Subtrees: Each child of a node forms the root of a subtree.
  * 5. Leaf Nodes: Nodes without children are leaves.
- * 6. Internal Nodes: Nodes with at least one child are internal.
- * 7. Balanced Trees: The heights of the left and right subtrees of any node differ by no more than one.
- * 8. Full Trees: Every node has either 0 or 2 children.
- * 9. Complete Trees: All levels are fully filled except possibly the last, filled from left to right.
  */
 
 export class BinaryTree<K = any, V = any, N extends BinaryTreeNode<K, V, N> = BinaryTreeNode<K, V, BinaryTreeNodeNested<K, V>>, TREE extends BinaryTree<K, V, N, TREE> = BinaryTree<K, V, N, BinaryTreeNested<K, V, N>>> extends IterableEntryBase<K, V | undefined>
@@ -231,7 +227,6 @@ export class BinaryTree<K = any, V = any, N extends BinaryTreeNode<K, V, N> = Bi
    * Space Complexity O(1)
    */
 
-
   /**
    * Time Complexity O(log n) - O(n)
    * Space Complexity O(1)
@@ -243,50 +238,65 @@ export class BinaryTree<K = any, V = any, N extends BinaryTreeNode<K, V, N> = Bi
    * @returns The function `add` returns either a node (`N`), `null`, or `undefined`.
    */
   add(keyOrNodeOrEntry: BTNodeExemplar<K, V, N>, value?: V): N | null | undefined {
-
-    let inserted: N | null | undefined;
     const newNode = this.exemplarToNode(keyOrNodeOrEntry, value);
     if (newNode === undefined) return;
 
-    // TODO There are still some problems with the way duplicate nodes are handled
-    if (newNode !== null && this.has(newNode.key)) return undefined;
+    // If the tree is empty, directly set the new node as the root node
+    if (!this.root) {
+      this._root = newNode;
+      this._size = 1;
+      return newNode;
+    }
 
-    const _bfs = (root: N, newNode: N | null): N | undefined | null => {
-      const queue = new Queue<N>([root]);
-      while (queue.size > 0) {
-        const cur = queue.shift()!;
-        if (newNode && cur.key === newNode.key) {
-          this._replaceNode(cur, newNode);
-          return newNode;
-        }
-        const inserted = this._addTo(newNode, cur);
-        if (inserted !== undefined) return inserted;
-        if (cur.left) queue.push(cur.left);
-        if (cur.right) queue.push(cur.right);
+    const queue = new Queue<N>([this.root]);
+    let potentialParent: N | undefined; // Record the parent node of the potential insertion location
+
+    while (queue.size > 0) {
+      const cur = queue.shift();
+
+      if (!cur) continue;
+
+      // Check for duplicate keys when newNode is not null
+      if (newNode !== null && cur.key === newNode.key) {
+        this._replaceNode(cur, newNode);
+        return newNode; // If duplicate keys are found, no insertion is performed
       }
-    };
 
-    if (this.root) {
-      inserted = _bfs(this.root, newNode);
-    } else {
-      this._setRoot(newNode);
-      if (newNode) {
-        this._size = 1;
-      } else {
-        this._size = 0;
+      // Record the first possible insertion location found
+      if (potentialParent === undefined && (cur.left === undefined || cur.right === undefined)) {
+        potentialParent = cur;
+      }
+
+      // Continue traversing the left and right subtrees
+      if (cur.left !== null) {
+        cur.left && queue.push(cur.left);
+      }
+      if (cur.right !== null) {
+        cur.right && queue.push(cur.right);
       }
-      inserted = this.root;
     }
-    return inserted;
+
+    // At the end of the traversal, if the insertion position is found, insert
+    if (potentialParent) {
+      if (potentialParent.left === undefined) {
+        potentialParent.left = newNode;
+      } else if (potentialParent.right === undefined) {
+        potentialParent.right = newNode;
+      }
+      this._size++;
+      return newNode;
+    }
+
+    return undefined; // If the insertion position cannot be found, return undefined
   }
 
+
   /**
    * Time Complexity: O(k log n) - O(k * n)
    * Space Complexity: O(1)
    * Comments: The time complexity for adding a node depends on the depth of the tree. In the best case (when the tree is empty), it's O(1). In the worst case (when the tree is a degenerate tree), it's O(n). The space complexity is constant.
    */
 
-
   /**
    * Time Complexity: O(k log n) - O(k * n)
    * Space Complexity: O(1)
@@ -1226,8 +1236,8 @@ export class BinaryTree<K = any, V = any, N extends BinaryTreeNode<K, V, N> = Bi
    * @param {any} node - The parameter `node` is of type `any`, which means it can be any data type.
    * @returns a boolean value.
    */
-  isRealNode(node: any): node is N {
-    return node instanceof BinaryTreeNode && node.key.toString() !== 'NaN';
+  isRealNode(node: BTNodeExemplar<K, V, N>): node is N {
+    return node instanceof BinaryTreeNode && String(node.key) !== 'NaN';
   }
 
   /**
@@ -1235,8 +1245,8 @@ export class BinaryTree<K = any, V = any, N extends BinaryTreeNode<K, V, N> = Bi
    * @param {any} node - The parameter `node` is of type `any`, which means it can be any data type.
    * @returns a boolean value.
    */
-  isNIL(node: any) {
-    return node instanceof BinaryTreeNode && node.key.toString() === 'NaN';
+  isNIL(node: BTNodeExemplar<K, V, N>) {
+    return node instanceof BinaryTreeNode && String(node.key) === 'NaN';
   }
 
   /**
@@ -1244,12 +1254,12 @@ export class BinaryTree<K = any, V = any, N extends BinaryTreeNode<K, V, N> = Bi
    * @param {any} node - The parameter `node` is of type `any`, which means it can be any data type.
    * @returns a boolean value.
    */
-  isNodeOrNull(node: any): node is N | null {
+  isNodeOrNull(node: BTNodeExemplar<K, V, N>): node is N | null {
     return this.isRealNode(node) || node === null;
   }
 
   /**
-   * The function "isNotNodeInstance" checks if a potential key is a number.
+   * 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.
@@ -1596,26 +1606,24 @@ export class BinaryTree<K = any, V = any, N extends BinaryTreeNode<K, V, N> = Bi
   }
 
   /**
-   * Time complexity: O(n)
-   * Space complexity: O(n)
+   * Time Complexity: O(log n)
+   * Space Complexity: O(1)
    */
 
-  getPredecessor(node: N): N;
-
   /**
-   * The function `getPredecessor` returns the predecessor node of a given node in a binary tree.
-   * @param {K | N | null | undefined} node - The `node` parameter can be of type `K`, `N`,
-   * `null`, or `undefined`.
-   * @returns The function `getPredecessor` returns a value of type `N | undefined`.
+   * Time Complexity: O(log n)
+   * Space Complexity: O(1)
+   *
+   * The function returns the predecessor of a given node in a tree.
+   * @param {N} node - The parameter `node` is of type `RedBlackTreeNode`, which represents a node in a
+   * tree.
+   * @returns the predecessor of the given 'node'.
    */
-  getPredecessor(node: BTNodeKeyOrNode<K, N>): N | undefined {
-    node = this.ensureNode(node);
-    if (!this.isRealNode(node)) return undefined;
-
-    if (node.left) {
+  getPredecessor(node: N): N {
+    if (this.isRealNode(node.left)) {
       let predecessor: N | null | undefined = node.left;
       while (!this.isRealNode(predecessor) || (this.isRealNode(predecessor.right) && predecessor.right !== node)) {
-        if (predecessor) {
+        if (this.isRealNode(predecessor)) {
           predecessor = predecessor.right;
         }
       }
@@ -1632,15 +1640,16 @@ export class BinaryTree<K = any, V = any, N extends BinaryTreeNode<K, V, N> = Bi
    * after the given node in the inorder traversal of the binary tree.
    */
   getSuccessor(x?: K | N | null): N | null | undefined {
+
     x = this.ensureNode(x);
-    if (!x) return undefined;
+    if (!this.isRealNode(x)) return undefined;
 
-    if (x.right) {
+    if (this.isRealNode(x.right)) {
       return this.getLeftMost(x.right);
     }
 
     let y: N | null | undefined = x.parent;
-    while (y && y && x === y.right) {
+    while (this.isRealNode(y) && x === y.right) {
       x = y;
       y = y.parent;
     }

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

@@ -14,7 +14,7 @@ import type {
   BTNodeExemplar,
   BTNodePureExemplar
 } from '../../types';
-import { BSTVariant, CP, IterationType } from '../../types';
+import { BSTVariant, BTNodeKeyOrNode, CP, IterationType } from '../../types';
 import { BinaryTree, BinaryTreeNode } from './binary-tree';
 import { IBinaryTree } from '../../interfaces';
 import { Queue } from '../queue';
@@ -442,6 +442,16 @@ export class BST<K = any, V = any, N extends BSTNode<K, V, N> = BSTNode<K, V, BS
     }
   }
 
+  /**
+   * 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 BSTNode)
+  }
+
   /**
    * Time Complexity: O(log n) - Average case for a balanced tree.
    * Space Complexity: O(log n) - Space for the recursive call stack in the worst case.

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

@@ -11,6 +11,7 @@ import {
   BSTNodeKeyOrNode,
   BTNCallback,
   BTNodeExemplar,
+  BTNodeKeyOrNode,
   IterationType,
   RBTNColor,
   RBTreeOptions,
@@ -115,6 +116,16 @@ export class RedBlackTree<K = any, V = any, N extends RedBlackTreeNode<K, V, N>
     return exemplar 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: 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:
@@ -300,7 +311,8 @@ export class RedBlackTree<K = any, V = any, N extends RedBlackTreeNode<K, V, N>
    */
 
   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, K>>(
@@ -362,38 +374,12 @@ export class RedBlackTree<K = any, V = any, N extends RedBlackTreeNode<K, V, N>
   }
 
   /**
-   * 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)
-   * 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)
+   * 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)
+   * Time Complexity: O(log n)
    * Space Complexity: O(1)
    *
    * The function returns the predecessor of a given node in a red-black tree.
@@ -402,12 +388,12 @@ export class RedBlackTree<K = any, V = any, N extends RedBlackTreeNode<K, V, N>
    * @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

@@ -6,7 +6,14 @@
  * @license MIT License
  */
 import type { BSTNodeKeyOrNode, BTNodeExemplar, TreeMultimapNodeNested, TreeMultimapOptions } from '../../types';
-import { BiTreeDeleteResult, BTNCallback, FamilyPosition, IterationType, TreeMultimapNested } from '../../types';
+import {
+  BiTreeDeleteResult,
+  BTNCallback,
+  BTNodeKeyOrNode,
+  FamilyPosition,
+  IterationType,
+  TreeMultimapNested
+} from '../../types';
 import { IBinaryTree } from '../../interfaces';
 import { AVLTree, AVLTreeNode } from './avl-tree';
 
@@ -85,6 +92,15 @@ export class TreeMultimap<K = any, V = any, N extends TreeMultimapNode<K, V, 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.