data-structure-typed 1.53.8 → 1.54.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "data-structure-typed",
-  "version": "1.53.8",
+  "version": "1.54.0",
   "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",
@@ -70,11 +70,11 @@
     "@typescript-eslint/eslint-plugin": "^8.12.1",
     "@typescript-eslint/parser": "^8.12.1",
     "auto-changelog": "^2.5.0",
-    "avl-tree-typed": "^1.53.7",
+    "avl-tree-typed": "^1.53.9",
     "benchmark": "^2.1.4",
-    "binary-tree-typed": "^1.53.7",
-    "bst-typed": "^1.53.7",
-    "data-structure-typed": "^1.53.7",
+    "binary-tree-typed": "^1.53.8",
+    "bst-typed": "^1.53.9",
+    "data-structure-typed": "^1.53.9",
     "dependency-cruiser": "^16.5.0",
     "doctoc": "^2.2.1",
     "eslint": "^9.13.0",
@@ -83,7 +83,7 @@
     "eslint-import-resolver-typescript": "^3.6.3",
     "eslint-plugin-import": "^2.31.0",
     "fast-glob": "^3.3.2",
-    "heap-typed": "^1.53.7",
+    "heap-typed": "^1.53.9",
     "istanbul-badges-readme": "^1.9.0",
     "jest": "^29.7.0",
     "js-sdsl": "^4.4.2",

package/src/data-structures/base/iterable-entry-base.ts

@@ -70,7 +70,7 @@ export abstract class IterableEntryBase<K = any, V = any> {
   every(predicate: EntryCallback<K, V, boolean>, thisArg?: any): boolean {
     let index = 0;
     for (const item of this) {
-      if (!predicate.call(thisArg, item[1], item[0], index++, this)) {
+      if (!predicate.call(thisArg, item[0], item[1], index++, this)) {
         return false;
       }
     }
@@ -95,7 +95,7 @@ export abstract class IterableEntryBase<K = any, V = any> {
   some(predicate: EntryCallback<K, V, boolean>, thisArg?: any): boolean {
     let index = 0;
     for (const item of this) {
-      if (predicate.call(thisArg, item[1], item[0], index++, this)) {
+      if (predicate.call(thisArg, item[0], item[1], index++, this)) {
         return true;
       }
     }
@@ -119,7 +119,7 @@ export abstract class IterableEntryBase<K = any, V = any> {
     let index = 0;
     for (const item of this) {
       const [key, value] = item;
-      callbackfn.call(thisArg, value, key, index++, this);
+      callbackfn.call(thisArg, key, value, index++, this);
     }
   }
 
@@ -144,7 +144,7 @@ export abstract class IterableEntryBase<K = any, V = any> {
     let index = 0;
     for (const item of this) {
       const [key, value] = item;
-      if (callbackfn.call(thisArg, value, key, index++, this)) return item;
+      if (callbackfn.call(thisArg, key, value, index++, this)) return item;
     }
     return;
   }

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

@@ -12,6 +12,7 @@ import type {
   BinaryTreeDeleteResult,
   BSTNOptKeyOrNode,
   BTNRep,
+  EntryCallback,
   IterationType
 } from '../../types';
 import { IBinaryTree } from '../../interfaces';
@@ -36,25 +37,6 @@ export class AVLTreeMultiMapNode<
     super(key, value);
     this.count = count;
   }
-
-  protected _count: number = 1;
-
-  /**
-   * The function returns the value of the protected variable _count.
-   * @returns The count property of the object, which is of type number.
-   */
-  get count(): number {
-    return this._count;
-  }
-
-  /**
-   * The above function sets the value of the count property.
-   * @param {number} value - The value parameter is of type number, which means it can accept any
-   * numeric value.
-   */
-  set count(value: number) {
-    this._count = value;
-  }
 }
 
 /**
@@ -64,17 +46,23 @@ export class AVLTreeMultiMap<
     K = any,
     V = any,
     R = object,
+    MK = any,
+    MV = any,
+    MR = object,
     NODE extends AVLTreeMultiMapNode<K, V, NODE> = AVLTreeMultiMapNode<K, V, AVLTreeMultiMapNodeNested<K, V>>,
-    TREE extends AVLTreeMultiMap<K, V, R, NODE, TREE> = AVLTreeMultiMap<
+    TREE extends AVLTreeMultiMap<K, V, R, MK, MV, MR, NODE, TREE> = AVLTreeMultiMap<
       K,
       V,
       R,
+      MK,
+      MV,
+      MR,
       NODE,
-      AVLTreeMultiMapNested<K, V, R, NODE>
+      AVLTreeMultiMapNested<K, V, R, MK, MV, MR, NODE>
     >
   >
-  extends AVLTree<K, V, R, NODE, TREE>
-  implements IBinaryTree<K, V, R, NODE, TREE>
+  extends AVLTree<K, V, R, MK, MV, MR, NODE, TREE>
+  implements IBinaryTree<K, V, R, MK, MV, MR, NODE, TREE>
 {
   /**
    * The constructor initializes a new AVLTreeMultiMap object with optional initial elements.
@@ -140,10 +128,10 @@ export class AVLTreeMultiMap<
    * object.
    */
   override createTree(options?: AVLTreeMultiMapOptions<K, V, R>): TREE {
-    return new AVLTreeMultiMap<K, V, R, NODE, TREE>([], {
+    return new AVLTreeMultiMap<K, V, R, MK, MV, MR, NODE, TREE>([], {
       iterationType: this.iterationType,
       isMapMode: this._isMapMode,
-      extractComparable: this._extractComparable,
+      specifyComparable: this._specifyComparable,
       toEntryFn: this._toEntryFn,
       isReverse: this._isReverse,
       ...options
@@ -161,44 +149,6 @@ export class AVLTreeMultiMap<
     return keyNodeEntryOrRaw instanceof AVLTreeMultiMapNode;
   }
 
-  /**
-   * The function `keyValueNodeEntryRawToNodeAndValue` converts a key, value, entry, or raw element into
-   * a node object.
-   * @param {BTNRep<K, V, NODE> | R} keyNodeEntryOrRaw - The
-   * `keyNodeEntryOrRaw` parameter can be of type `R` or `BTNRep<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 key-value pair should be added to the data structure. If not provided, it defaults to 1.
-   * @returns either a NODE object or undefined.
-   */
-  protected override _keyValueNodeEntryRawToNodeAndValue(
-    keyNodeEntryOrRaw: BTNRep<K, V, NODE> | R,
-    value?: V,
-    count = 1
-  ): [NODE | undefined, V | undefined] {
-    if (keyNodeEntryOrRaw === undefined || keyNodeEntryOrRaw === null) return [undefined, undefined];
-    if (this.isNode(keyNodeEntryOrRaw)) return [keyNodeEntryOrRaw, value];
-
-    if (this.isEntry(keyNodeEntryOrRaw)) {
-      const [key, entryValue] = keyNodeEntryOrRaw;
-      if (key === undefined || key === null) return [undefined, undefined];
-      const finalValue = value ?? entryValue;
-      return [this.createNode(key, finalValue, count), finalValue];
-    }
-
-    if (this.isRaw(keyNodeEntryOrRaw)) {
-      const [key, entryValue] = this._toEntryFn!(keyNodeEntryOrRaw);
-      const finalValue = value ?? entryValue;
-      if (this.isKey(key)) return [this.createNode(key, finalValue, count), finalValue];
-    }
-
-    if (this.isKey(keyNodeEntryOrRaw)) return [this.createNode(keyNodeEntryOrRaw, value, count), value];
-
-    return [undefined, undefined];
-  }
-
   /**
    * Time Complexity: O(log n)
    * Space Complexity: O(1)
@@ -264,7 +214,7 @@ export class AVLTreeMultiMap<
     } else {
       if (!curr.left) {
         if (!parent) {
-          if (curr.right !== undefined) this._setRoot(curr.right);
+          if (curr.right !== undefined && curr.right !== null) this._setRoot(curr.right);
         } else {
           const { familyPosition: fp } = curr;
           if (fp === 'LEFT' || fp === 'ROOT_LEFT') {
@@ -382,6 +332,75 @@ export class AVLTreeMultiMap<
     return cloned;
   }
 
+  /**
+   * The `map` function in TypeScript overrides the default behavior to create a new AVLTreeMultiMap
+   * with modified entries based on a provided callback.
+   * @param callback - The `callback` parameter is a function that will be called for each entry in the
+   * AVLTreeMultiMap. It takes four arguments:
+   * @param [options] - The `options` parameter in the `override map` function is of type
+   * `AVLTreeMultiMapOptions<MK, MV, MR>`. This parameter allows you to provide additional
+   * configuration options when creating a new `AVLTreeMultiMap` instance within the `map` function.
+   * These options
+   * @param {any} [thisArg] - The `thisArg` parameter in the `override map` function is used to specify
+   * the value of `this` when executing the `callback` function. It allows you to set the context
+   * (value of `this`) for the callback function. This can be useful when you want to access properties
+   * or
+   * @returns The `map` method is returning a new `AVLTreeMultiMap` instance with the entries
+   * transformed by the provided `callback` function. Each entry in the original tree is passed to the
+   * `callback` function along with the index and the original tree itself. The transformed entries are
+   * then added to the new `AVLTreeMultiMap` instance, which is returned at the end.
+   */
+  override map<MK, MV, MR>(
+    callback: EntryCallback<K, V | undefined, [MK, MV]>,
+    options?: AVLTreeMultiMapOptions<MK, MV, MR>,
+    thisArg?: any
+  ): AVLTreeMultiMap<MK, MV, MR> {
+    const newTree = new AVLTreeMultiMap<MK, MV, MR>([], options);
+    let index = 0;
+    for (const [key, value] of this) {
+      newTree.add(callback.call(thisArg, key, value, index++, this));
+    }
+    return newTree;
+  }
+
+  /**
+   * The function `keyValueNodeEntryRawToNodeAndValue` converts a key, value, entry, or raw element into
+   * a node object.
+   * @param {BTNRep<K, V, NODE> | R} keyNodeEntryOrRaw - The
+   * `keyNodeEntryOrRaw` parameter can be of type `R` or `BTNRep<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 key-value pair should be added to the data structure. If not provided, it defaults to 1.
+   * @returns either a NODE object or undefined.
+   */
+  protected override _keyValueNodeEntryRawToNodeAndValue(
+    keyNodeEntryOrRaw: BTNRep<K, V, NODE> | R,
+    value?: V,
+    count = 1
+  ): [NODE | undefined, V | undefined] {
+    if (keyNodeEntryOrRaw === undefined || keyNodeEntryOrRaw === null) return [undefined, undefined];
+    if (this.isNode(keyNodeEntryOrRaw)) return [keyNodeEntryOrRaw, value];
+
+    if (this.isEntry(keyNodeEntryOrRaw)) {
+      const [key, entryValue] = keyNodeEntryOrRaw;
+      if (key === undefined || key === null) return [undefined, undefined];
+      const finalValue = value ?? entryValue;
+      return [this.createNode(key, finalValue, count), finalValue];
+    }
+
+    if (this.isRaw(keyNodeEntryOrRaw)) {
+      const [key, entryValue] = this._toEntryFn!(keyNodeEntryOrRaw);
+      const finalValue = value ?? entryValue;
+      if (this.isKey(key)) return [this.createNode(key, finalValue, count), finalValue];
+    }
+
+    if (this.isKey(keyNodeEntryOrRaw)) return [this.createNode(keyNodeEntryOrRaw, value, count), value];
+
+    return [undefined, undefined];
+  }
+
   /**
    * Time Complexity: O(1)
    * Space Complexity: O(1)

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

@@ -12,7 +12,8 @@ import type {
   AVLTreeOptions,
   BinaryTreeDeleteResult,
   BSTNOptKeyOrNode,
-  BTNRep
+  BTNRep,
+  EntryCallback
 } from '../../types';
 import { IBinaryTree } from '../../interfaces';
 
@@ -31,26 +32,6 @@ export class AVLTreeNode<
    */
   constructor(key: K, value?: V) {
     super(key, value);
-    this._height = 0;
-  }
-
-  protected _height: number;
-
-  /**
-   * The function returns the value of the height property.
-   * @returns The height of the object.
-   */
-  get height(): number {
-    return this._height;
-  }
-
-  /**
-   * The above function sets the value of the height property.
-   * @param {number} value - The value parameter is a number that represents the new height value to be
-   * set.
-   */
-  set height(value: number) {
-    this._height = value;
   }
 }
 
@@ -67,11 +48,23 @@ export class AVLTree<
     K = any,
     V = any,
     R = object,
+    MK = any,
+    MV = any,
+    MR = object,
     NODE extends AVLTreeNode<K, V, NODE> = AVLTreeNode<K, V, AVLTreeNodeNested<K, V>>,
-    TREE extends AVLTree<K, V, R, NODE, TREE> = AVLTree<K, V, R, NODE, AVLTreeNested<K, V, R, NODE>>
+    TREE extends AVLTree<K, V, R, MK, MV, MR, NODE, TREE> = AVLTree<
+      K,
+      V,
+      R,
+      MK,
+      MV,
+      MR,
+      NODE,
+      AVLTreeNested<K, V, R, MK, MV, MR, NODE>
+    >
   >
-  extends BST<K, V, R, NODE, TREE>
-  implements IBinaryTree<K, V, R, NODE, TREE>
+  extends BST<K, V, R, MK, MV, MR, NODE, TREE>
+  implements IBinaryTree<K, V, R, MK, MV, MR, NODE, TREE>
 {
   /**
    * This is a constructor function for an AVLTree class that initializes the tree with keys, nodes,
@@ -110,10 +103,10 @@ export class AVLTree<
    * @returns a new AVLTree object.
    */
   override createTree(options?: AVLTreeOptions<K, V, R>): TREE {
-    return new AVLTree<K, V, R, NODE, TREE>([], {
+    return new AVLTree<K, V, R, MK, MV, MR, NODE, TREE>([], {
       iterationType: this.iterationType,
       isMapMode: this._isMapMode,
-      extractComparable: this._extractComparable,
+      specifyComparable: this._specifyComparable,
       toEntryFn: this._toEntryFn,
       isReverse: this._isReverse,
       ...options
@@ -174,6 +167,19 @@ export class AVLTree<
     return deletedResults;
   }
 
+  override map(
+    callback: EntryCallback<K, V | undefined, [MK, MV]>,
+    options?: AVLTreeOptions<MK, MV, MR>,
+    thisArg?: any
+  ): AVLTree<MK, MV, MR> {
+    const newTree = new AVLTree<MK, MV, MR>([], options);
+    let index = 0;
+    for (const [key, value] of this) {
+      newTree.add(callback.call(thisArg, key, value, index++, this));
+    }
+    return newTree;
+  }
+
   /**
    * Time Complexity: O(1)
    * Space Complexity: O(1)
@@ -262,7 +268,7 @@ export class AVLTree<
   protected _balanceLL(A: NODE): void {
     const parentOfA = A.parent;
     const B = A.left;
-    A.parent = B;
+    if (B !== null) A.parent = B;
     if (B && B.right) {
       B.right.parent = A;
     }
@@ -299,12 +305,12 @@ export class AVLTree<
     if (B) {
       C = B.right;
     }
-    if (A) A.parent = C;
-    if (B) B.parent = C;
+    if (A && C !== null) A.parent = C;
+    if (B && C !== null) B.parent = C;
 
     if (C) {
       if (C.left) {
-        C.left.parent = B;
+        if (B !== null) C.left.parent = B;
       }
       if (C.right) {
         C.right.parent = A;
@@ -346,7 +352,7 @@ export class AVLTree<
   protected _balanceRR(A: NODE): void {
     const parentOfA = A.parent;
     const B = A.right;
-    A.parent = B;
+    if (B !== null) A.parent = B;
     if (B) {
       if (B.left) {
         B.left.parent = A;
@@ -389,15 +395,15 @@ export class AVLTree<
       C = B.left;
     }
 
-    A.parent = C;
-    if (B) B.parent = C;
+    if (C !== null) A.parent = C;
+    if (B && C !== null) B.parent = C;
 
     if (C) {
       if (C.left) {
         C.left.parent = A;
       }
       if (C.right) {
-        C.right.parent = B;
+        if (B !== null) C.right.parent = B;
       }
       C.parent = parentOfA;
     }

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

@@ -23,6 +23,7 @@ import {
   NodeDisplayLayout,
   NodePredicate,
   OptNodeOrNull,
+  type RBTNColor,
   ToEntryFn
 } from '../../types';
 import { IBinaryTree } from '../../interfaces';
@@ -52,7 +53,7 @@ export class BinaryTreeNode<
     this.value = value;
   }
 
-  protected _left?: OptNodeOrNull<NODE>;
+  _left?: OptNodeOrNull<NODE>;
 
   get left(): OptNodeOrNull<NODE> {
     return this._left;
@@ -65,7 +66,7 @@ export class BinaryTreeNode<
     this._left = v;
   }
 
-  protected _right?: OptNodeOrNull<NODE>;
+  _right?: OptNodeOrNull<NODE>;
 
   get right(): OptNodeOrNull<NODE> {
     return this._right;
@@ -78,6 +79,36 @@ export class BinaryTreeNode<
     this._right = v;
   }
 
+  _height: number = 0;
+
+  get height(): number {
+    return this._height;
+  }
+
+  set height(value: number) {
+    this._height = value;
+  }
+
+  _color: RBTNColor = 'BLACK';
+
+  get color(): RBTNColor {
+    return this._color;
+  }
+
+  set color(value: RBTNColor) {
+    this._color = value;
+  }
+
+  _count: number = 1;
+
+  get count(): number {
+    return this._count;
+  }
+
+  set count(value: number) {
+    this._count = value;
+  }
+
   get familyPosition(): FamilyPosition {
     const that = this as unknown as NODE;
     if (!this.parent) {
@@ -105,11 +136,23 @@ export class BinaryTree<
     K = any,
     V = any,
     R = object,
+    MK = any,
+    MV = any,
+    MR = object,
     NODE extends BinaryTreeNode<K, V, NODE> = BinaryTreeNode<K, V, BinaryTreeNodeNested<K, V>>,
-    TREE extends BinaryTree<K, V, R, NODE, TREE> = BinaryTree<K, V, R, NODE, BinaryTreeNested<K, V, R, NODE>>
+    TREE extends BinaryTree<K, V, R, MK, MV, MR, NODE, TREE> = BinaryTree<
+      K,
+      V,
+      R,
+      MK,
+      MV,
+      MR,
+      NODE,
+      BinaryTreeNested<K, V, R, MK, MV, MR, NODE>
+    >
   >
   extends IterableEntryBase<K, V | undefined>
-  implements IBinaryTree<K, V, R, NODE, TREE>
+  implements IBinaryTree<K, V, R, MK, MV, MR, NODE, TREE>
 {
   iterationType: IterationType = 'ITERATIVE';
 
@@ -172,6 +215,9 @@ export class BinaryTree<
   }
 
   /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   *
    * The function creates a new binary tree node with a specified key and optional value.
    * @param {K} key - The `key` parameter is the key of the node being created in the binary tree.
    * @param {V} [value] - The `value` parameter in the `createNode` function is optional, meaning it is
@@ -193,7 +239,7 @@ export class BinaryTree<
    * @returns A new instance of a binary tree with the specified options is being returned.
    */
   createTree(options?: BinaryTreeOptions<K, V, R>): TREE {
-    return new BinaryTree<K, V, R, NODE, TREE>([], {
+    return new BinaryTree<K, V, R, MK, MV, MR, NODE, TREE>([], {
       iterationType: this.iterationType,
       isMapMode: this._isMapMode,
       toEntryFn: this._toEntryFn,
@@ -1673,7 +1719,7 @@ export class BinaryTree<
     const newTree = this.createTree();
     let index = 0;
     for (const [key, value] of this) {
-      if (predicate.call(thisArg, value, key, index++, this)) {
+      if (predicate.call(thisArg, key, value, index++, this)) {
         newTree.add([key, value]);
       }
     }
@@ -1684,36 +1730,34 @@ export class BinaryTree<
    * Time Complexity: O(n)
    * Space Complexity: O(n)
    *
-   * The `map` function iterates over key-value pairs in a tree data structure, applies a callback
-   * function to each value, and returns a new tree with the updated values.
-   * @param callback - The `callback` parameter in the `map` method is a function that will be called
-   * on each entry in the tree. It takes four arguments:
-   * @param {any} [thisArg] - The `thisArg` parameter in the `map` function is an optional parameter
-   * that specifies the value to be passed as `this` when executing the callback function. If provided,
-   * the `thisArg` value will be used as the `this` value within the callback function. If `thisArg
-   * @returns The `map` method is returning a new tree with the entries modified by the provided
-   * callback function. Each entry in the original tree is passed to the callback function, and the
-   * result of the callback function is added to the new tree.
+   * The `map` function in TypeScript creates a new BinaryTree by applying a callback function to each
+   * entry in the original BinaryTree.
+   * @param callback - A function that will be called for each entry in the current binary tree. It
+   * takes the key, value (which can be undefined), and an array containing the mapped key and value as
+   * arguments.
+   * @param [options] - The `options` parameter in the `map` method is of type `BinaryTreeOptions<MK,
+   * MV, MR>`. It is an optional parameter that allows you to specify additional options for the binary
+   * tree being created during the mapping process. These options could include things like custom
+   * comparators, initial
+   * @param {any} [thisArg] - The `thisArg` parameter in the `map` method is used to specify the value
+   * of `this` when executing the `callback` function. It allows you to set the context (value of
+   * `this`) within the callback function. If `thisArg` is provided, it will be passed
+   * @returns The `map` function is returning a new `BinaryTree` instance filled with entries that are
+   * the result of applying the provided `callback` function to each entry in the original tree.
    */
-  map(callback: EntryCallback<K, V | undefined, V>, thisArg?: any) {
-    const newTree = this.createTree();
+  map(
+    callback: EntryCallback<K, V | undefined, [MK, MV]>,
+    options?: BinaryTreeOptions<MK, MV, MR>,
+    thisArg?: any
+  ): BinaryTree<MK, MV, MR> {
+    const newTree = new BinaryTree<MK, MV, MR>([], options);
     let index = 0;
     for (const [key, value] of this) {
-      newTree.add([key, callback.call(thisArg, value, key, index++, this)]);
+      newTree.add(callback.call(thisArg, key, value, index++, this));
     }
     return newTree;
   }
 
-  // // TODO Type error, need to return a TREE<NV> that is a value type only for callback function.
-  // // map<NV>(callback: (entry: [K, V | undefined], tree: this) => NV) {
-  // //   const newTree = this.createTree();
-  // //   for (const [key, value] of this) {
-  // //     newTree.add(key, callback([key, value], this));
-  // //   }
-  // //   return newTree;
-  // // }
-  //
-
   /**
    * Time Complexity: O(n)
    * Space Complexity: O(n)
@@ -1743,7 +1787,7 @@ export class BinaryTree<
     if (opts.isShowRedBlackNIL) output += `S for Sentinel Node(NIL)\n`;
 
     const display = (root: OptNodeOrNull<NODE>): void => {
-      const [lines, , ,] = this._displayAux(root, opts);
+      const [lines, ,] = this._displayAux(root, opts);
       let paragraph = '';
       for (const line of lines) {
         paragraph += line + '\n';