tree-multimap-typed 2.2.2 → 2.2.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tree-multimap-typed",
-  "version": "2.2.2",
+  "version": "2.2.4",
   "description": "Tree Multimap",
   "browser": "dist/umd/tree-multimap-typed.min.js",
   "umd:main": "dist/umd/tree-multimap-typed.min.js",
@@ -217,6 +217,6 @@
     "typescript": "^4.9.5"
   },
   "dependencies": {
-    "data-structure-typed": "^2.2.2"
+    "data-structure-typed": "^2.2.4"
   }
 }

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

@@ -9,7 +9,6 @@
 import type {
   AVLTreeCounterOptions,
   BinaryTreeDeleteResult,
-  BinaryTreeOptions,
   BSTNOptKeyOrNode,
   EntryCallback,
   FamilyPosition,
@@ -404,7 +403,7 @@ export class AVLTreeCounter<K = any, V = any, R = any> extends AVLTree<K, V, R>
    */
   override map<MK = K, MV = V, MR = any>(
     callback: EntryCallback<K, V | undefined, [MK, MV]>,
-    options?: Partial<BinaryTreeOptions<MK, MV, MR>>,
+    options?: Partial<AVLTreeCounterOptions<MK, MV, MR>>,
     thisArg?: unknown
   ): AVLTreeCounter<MK, MV, MR> {
     const out = this._createLike<MK, MV, MR>([], options);

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

@@ -8,7 +8,6 @@
 
 import type {
   AVLTreeMultiMapOptions,
-  AVLTreeOptions,
   BTNOptKeyOrNull,
   ElemOf,
   EntryCallback,
@@ -354,7 +353,7 @@ export class AVLTreeMultiMap<K = any, V = any, R = any> extends AVLTree<K, V[],
    */
   override map<MK = K, MVArr extends unknown[] = V[], MR = any>(
     callback: EntryCallback<K, V[] | undefined, [MK, MVArr]>,
-    options?: Partial<AVLTreeOptions<MK, MVArr, MR>>,
+    options?: Partial<AVLTreeMultiMapOptions<MK, MVArr, MR>>,
     thisArg?: unknown
   ): AVLTreeMultiMap<MK, ElemOf<MVArr>, MR>;
 
@@ -371,7 +370,7 @@ export class AVLTreeMultiMap<K = any, V = any, R = any> extends AVLTree<K, V[],
    */
   override map<MK = K, MV = V[], MR = any>(
     callback: EntryCallback<K, V[] | undefined, [MK, MV]>,
-    options?: Partial<AVLTreeOptions<MK, MV, MR>>,
+    options?: Partial<AVLTreeMultiMapOptions<MK, MV, MR>>,
     thisArg?: unknown
   ): AVLTree<MK, MV, MR>;
 
@@ -388,7 +387,7 @@ export class AVLTreeMultiMap<K = any, V = any, R = any> extends AVLTree<K, V[],
    */
   override map<MK, MV, MR extends object>(
     callback: EntryCallback<K, V[] | undefined, [MK, MV]>,
-    options?: Partial<AVLTreeOptions<MK, MV, MR>>,
+    options?: Partial<AVLTreeMultiMapOptions<MK, MV, MR>>,
     thisArg?: unknown
   ): AVLTree<MK, MV, MR> {
     const out = this._createLike<MK, MV, MR>([], options);
@@ -406,10 +405,10 @@ export class AVLTreeMultiMap<K = any, V = any, R = any> extends AVLTree<K, V[],
    * @param [options] - Optional constructor options for the like-kind instance.
    * @returns An empty like-kind instance.
    */
-  protected override _createInstance<TK = K, TV = V, TR = R>(options?: Partial<AVLTreeOptions<TK, TV, TR>>): this {
+  protected override _createInstance<TK = K, TV = V, TR = R>(options?: Partial<AVLTreeMultiMapOptions<TK, TV, TR>>): this {
     const Ctor = this.constructor as unknown as new (
       iter?: Iterable<TK | AVLTreeNode<TK, TV> | [TK | null | undefined, TV | undefined] | null | undefined | TR>,
-      opts?: AVLTreeOptions<TK, TV, TR>
+      opts?: AVLTreeMultiMapOptions<TK, TV, TR>
     ) => AVLTree<TK, TV, TR>;
     return new Ctor([], { ...(this._snapshotOptions?.<TK, TV, TR>() ?? {}), ...(options ?? {}) }) as unknown as this;
   }
@@ -426,11 +425,11 @@ export class AVLTreeMultiMap<K = any, V = any, R = any> extends AVLTree<K, V[],
    */
   protected override _createLike<TK = K, TV = V, TR = R>(
     iter: Iterable<TK | AVLTreeNode<TK, TV> | [TK | null | undefined, TV | undefined] | null | undefined | TR> = [],
-    options?: Partial<AVLTreeOptions<TK, TV, TR>>
+    options?: Partial<AVLTreeMultiMapOptions<TK, TV, TR>>
   ): AVLTree<TK, TV, TR> {
     const Ctor = this.constructor as unknown as new (
       iter?: Iterable<TK | AVLTreeNode<TK, TV> | [TK | null | undefined, TV | undefined] | null | undefined | TR>,
-      opts?: AVLTreeOptions<TK, TV, TR>
+      opts?: AVLTreeMultiMapOptions<TK, TV, TR>
     ) => AVLTree<TK, TV, TR>;
     return new Ctor(iter, { ...(this._snapshotOptions?.<TK, TV, TR>() ?? {}), ...(options ?? {}) });
   }

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

@@ -17,7 +17,6 @@ import type {
   IterationType,
   RBTNColor
 } from '../../types';
-import { BSTOptions } from '../../types';
 import { IBinaryTree } from '../../interfaces';
 
 /**
@@ -198,8 +197,102 @@ export class AVLTreeNode<K = any, V = any> {
  * 7. Path Length: The path length from the root to any leaf is longer compared to an unbalanced BST, but shorter than a linear chain of nodes.
  *
  * @example
+ * // basic AVLTree creation and add operation
+ *  // Create a simple AVLTree with initial values
+ *     const tree = new AVLTree([5, 2, 8, 1, 9]);
+ *
+ *     tree.print();
+ *     //   _2___
+ *     //  /     \
+ *     //  1    _8_
+ *     //      /   \
+ *     //      5   9
+ *
+ *     // Verify the tree maintains sorted order
+ *     console.log([...tree.keys()]); // [1, 2, 5, 8, 9];
+ *
+ *     // Check size
+ *     console.log(tree.size); // 5;
+ *
+ *     // Add a new element
+ *     tree.add(3);
+ *     console.log(tree.size); // 6;
+ *     console.log([...tree.keys()]); // [1, 2, 3, 5, 8, 9];
+ * @example
+ * // AVLTree has and get operations
+ *  const tree = new AVLTree<number>([11, 3, 15, 1, 8, 13, 16, 2, 6, 9, 12, 14, 4, 7, 10, 5]);
+ *
+ *     // Check if element exists
+ *     console.log(tree.has(6)); // true;
+ *     console.log(tree.has(99)); // false;
+ *
+ *     // Get node by key
+ *     const node = tree.getNode(6);
+ *     console.log(node?.key); // 6;
+ *
+ *     // Verify tree is balanced
+ *     console.log(tree.isAVLBalanced()); // true;
+ * @example
+ * // AVLTree delete and balance verification
+ *  const tree = new AVLTree([11, 3, 15, 1, 8, 13, 16, 2, 6, 9, 12, 14, 4, 7, 10, 5]);
+ *
+ *     // Delete an element
+ *     tree.delete(10);
+ *     console.log(tree.has(10)); // false;
+ *
+ *     // Tree should remain balanced after deletion
+ *     console.log(tree.isAVLBalanced()); // true;
+ *
+ *     // Size decreased
+ *     console.log(tree.size); // 15;
+ *
+ *     // Remaining elements are still sorted
+ *     const keys = [...tree.keys()];
+ *     console.log(keys); // [1, 2, 3, 4, 5, 6, 7, 8, 9, 11, 12, 13, 14, 15, 16];
+ * @example
+ * // AVLTree for university ranking system with strict balance
+ *  interface University {
+ *       name: string;
+ *       rank: number;
+ *       students: number;
+ *     }
+ *
+ *     // AVLTree provides highest search efficiency with strict balance
+ *     // (every node's left/right subtrees differ by at most 1 in height)
+ *     const universityTree = new AVLTree<number, University>([
+ *       [1, { name: 'MIT', rank: 1, students: 1200 }],
+ *       [5, { name: 'Stanford', rank: 5, students: 1800 }],
+ *       [3, { name: 'Harvard', rank: 3, students: 2300 }],
+ *       [2, { name: 'Caltech', rank: 2, students: 400 }],
+ *       [4, { name: 'CMU', rank: 4, students: 1500 }]
+ *     ]);
+ *
+ *     // Quick lookup by rank
+ *     const mit = universityTree.get(1);
+ *     console.log(mit?.name); // 'MIT';
+ *
+ *     const cmulevel = universityTree.getHeight(4);
+ *     console.log(typeof cmulevel); // 'number';
+ *
+ *     // Tree maintains strict balance during insertions and deletions
+ *     console.log(universityTree.isAVLBalanced()); // true;
+ *
+ *     // Add more universities
+ *     universityTree.add(6, { name: 'Oxford', rank: 6, students: 2000 });
+ *     console.log(universityTree.isAVLBalanced()); // true;
+ *
+ *     // Delete and verify balance is maintained
+ *     universityTree.delete(2);
+ *     console.log(universityTree.has(2)); // false;
+ *     console.log(universityTree.isAVLBalanced()); // true;
+ *
+ *     // Get all remaining universities in rank order
+ *     const remainingRanks = [...universityTree.keys()];
+ *     console.log(remainingRanks); // [1, 3, 4, 5, 6];
+ *     console.log(universityTree.size); // 5;
+ * @example
  * // Find elements in a range
- *     // In interval queries, AVL trees, with their strictly balanced structure and lower height, offer better query efficiency, making them ideal for frequent and high-performance interval queries. In contrast, Red-Black trees, with lower update costs, are more suitable for scenarios involving frequent insertions and deletions where the requirements for interval queries are less demanding.
+ *  // In interval queries, AVL trees, with their strictly balanced structure and lower height, offer better query efficiency, making them ideal for frequent and high-performance interval queries. In contrast, Red-Black trees, with lower update costs, are more suitable for scenarios involving frequent insertions and deletions where the requirements for interval queries are less demanding.
  *     type Datum = { timestamp: Date; temperature: number };
  *     // Fixed dataset of CPU temperature readings
  *     const cpuData: Datum[] = [
@@ -260,7 +353,7 @@ export class AVLTreeNode<K = any, V = any> {
  *  //      { minute: 13, temperature: 60.2 },
  *  //      { minute: 14, temperature: 59.8 },
  *  //      { minute: 15, temperature: 58.6 }
- *  //    ]
+ *  //    ];
  */
 export class AVLTree<K = any, V = any, R = any> extends BST<K, V, R> implements IBinaryTree<K, V, R> {
   /**
@@ -418,10 +511,10 @@ export class AVLTree<K = any, V = any, R = any> extends BST<K, V, R> implements
    * @param [options] - Options for the new tree.
    * @returns A new, empty tree.
    */
-  protected override _createInstance<TK = K, TV = V, TR = R>(options?: Partial<BSTOptions<TK, TV, TR>>): this {
+  protected override _createInstance<TK = K, TV = V, TR = R>(options?: Partial<AVLTreeOptions<TK, TV, TR>>): this {
     const Ctor = this.constructor as unknown as new (
       iter?: Iterable<TK | AVLTreeNode<TK, TV> | [TK | null | undefined, TV | undefined] | null | undefined | TR>,
-      opts?: BSTOptions<TK, TV, TR>
+      opts?: AVLTreeOptions<TK, TV, TR>
     ) => this;
     return new Ctor([], { ...this._snapshotOptions<TK, TV, TR>(), ...(options ?? {}) }) as unknown as this;
   }
@@ -437,11 +530,11 @@ export class AVLTree<K = any, V = any, R = any> extends BST<K, V, R> implements
    */
   protected override _createLike<TK = K, TV = V, TR = R>(
     iter: Iterable<TK | AVLTreeNode<TK, TV> | [TK | null | undefined, TV | undefined] | null | undefined | TR> = [],
-    options?: Partial<BSTOptions<TK, TV, TR>>
+    options?: Partial<AVLTreeOptions<TK, TV, TR>>
   ): AVLTree<TK, TV, TR> {
     const Ctor = this.constructor as unknown as new (
       iter?: Iterable<TK | AVLTreeNode<TK, TV> | [TK | null | undefined, TV | undefined] | null | undefined | TR>,
-      opts?: BSTOptions<TK, TV, TR>
+      opts?: AVLTreeOptions<TK, TV, TR>
     ) => AVLTree<TK, TV, TR>;
     return new Ctor(iter, { ...this._snapshotOptions<TK, TV, TR>(), ...(options ?? {}) });
   }

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

@@ -205,8 +205,86 @@ export class BinaryTreeNode<K = any, V = any> {
  * 5. Leaf Nodes: Nodes without children are leaves.
  *
  * @example
+ * // basic BinaryTree creation and insertion
+ *  // Create a BinaryTree with entries
+ *     const entries: [number, string][] = [
+ *       [6, 'six'],
+ *       [1, 'one'],
+ *       [2, 'two'],
+ *       [7, 'seven'],
+ *       [5, 'five'],
+ *       [3, 'three'],
+ *       [4, 'four'],
+ *       [9, 'nine'],
+ *       [8, 'eight']
+ *     ];
+ *
+ *     const tree = new BinaryTree(entries);
+ *
+ *     // Verify size
+ *     console.log(tree.size); // 9;
+ *
+ *     // Add new element
+ *     tree.add(10, 'ten');
+ *     console.log(tree.size); // 10;
+ * @example
+ * // BinaryTree get and has operations
+ *  const tree = new BinaryTree(
+ *       [
+ *         [5, 'five'],
+ *         [3, 'three'],
+ *         [7, 'seven'],
+ *         [1, 'one'],
+ *         [4, 'four'],
+ *         [6, 'six'],
+ *         [8, 'eight']
+ *       ],
+ *       { isMapMode: false }
+ *     );
+ *
+ *     // Check if key exists
+ *     console.log(tree.has(5)); // true;
+ *     console.log(tree.has(10)); // false;
+ *
+ *     // Get value by key
+ *     console.log(tree.get(3)); // 'three';
+ *     console.log(tree.get(7)); // 'seven';
+ *     console.log(tree.get(100)); // undefined;
+ *
+ *     // Get node structure
+ *     const node = tree.getNode(5);
+ *     console.log(node?.key); // 5;
+ *     console.log(node?.value); // 'five';
+ * @example
+ * // BinaryTree level-order traversal
+ *  const tree = new BinaryTree([
+ *       [1, 'one'],
+ *       [2, 'two'],
+ *       [3, 'three'],
+ *       [4, 'four'],
+ *       [5, 'five'],
+ *       [6, 'six'],
+ *       [7, 'seven']
+ *     ]);
+ *
+ *     // Binary tree maintains level-order insertion
+ *     // Complete binary tree structure
+ *     console.log(tree.size); // 7;
+ *
+ *     // Verify all keys are present
+ *     console.log(tree.has(1)); // true;
+ *     console.log(tree.has(4)); // true;
+ *     console.log(tree.has(7)); // true;
+ *
+ *     // Iterate through tree
+ *     const keys: number[] = [];
+ *     for (const [key] of tree) {
+ *       keys.push(key);
+ *     }
+ *     console.log(keys.length); // 7;
+ * @example
  * // determine loan approval using a decision tree
- *     // Decision tree structure
+ *  // Decision tree structure
  *     const loanDecisionTree = new BinaryTree<string>(
  *       ['stableIncome', 'goodCredit', 'Rejected', 'Approved', 'Rejected'],
  *       { isDuplicate: true }
@@ -228,19 +306,19 @@ export class BinaryTreeNode<K = any, V = any> {
  *     }
  *
  *     // Test case 1: Stable income and good credit score
- *     console.log(determineLoanApproval(loanDecisionTree.root, { stableIncome: true, goodCredit: true })); // 'Approved'
+ *     console.log(determineLoanApproval(loanDecisionTree.root, { stableIncome: true, goodCredit: true })); // 'Approved';
  *
  *     // Test case 2: Stable income but poor credit score
- *     console.log(determineLoanApproval(loanDecisionTree.root, { stableIncome: true, goodCredit: false })); // 'Rejected'
+ *     console.log(determineLoanApproval(loanDecisionTree.root, { stableIncome: true, goodCredit: false })); // 'Rejected';
  *
  *     // Test case 3: No stable income
- *     console.log(determineLoanApproval(loanDecisionTree.root, { stableIncome: false, goodCredit: true })); // 'Rejected'
+ *     console.log(determineLoanApproval(loanDecisionTree.root, { stableIncome: false, goodCredit: true })); // 'Rejected';
  *
  *     // Test case 4: No stable income and poor credit score
- *     console.log(determineLoanApproval(loanDecisionTree.root, { stableIncome: false, goodCredit: false })); // 'Rejected'
+ *     console.log(determineLoanApproval(loanDecisionTree.root, { stableIncome: false, goodCredit: false })); // 'Rejected';
  * @example
  * // evaluate the arithmetic expression represented by the binary tree
- *     const expressionTree = new BinaryTree<number | string>(['+', 3, '*', null, null, 5, '-', null, null, 2, 8]);
+ *  const expressionTree = new BinaryTree<number | string>(['+', 3, '*', null, null, 5, '-', null, null, 2, 8]);
  *
  *     function evaluate(node?: BinaryTreeNode<number | string> | null): number {
  *       if (!node) return 0;
@@ -265,7 +343,7 @@ export class BinaryTreeNode<K = any, V = any> {
  *       }
  *     }
  *
- *     console.log(evaluate(expressionTree.root)); // -27
+ *     console.log(evaluate(expressionTree.root)); // -27;
  */
 export class BinaryTree<K = any, V = any, R = any>
   extends IterableEntryBase<K, V | undefined>
@@ -620,6 +698,21 @@ export class BinaryTree<K = any, V = any, R = any>
     return false; // Should not happen if tree is not full?
   }
 
+  /**
+   * Adds or updates a new node to the tree.
+   * @remarks Time O(log N), For BST, Red-Black Tree, and AVL Tree subclasses, the worst-case time is O(log N). This implementation adds the node at the first available position in a level-order (BFS) traversal. This is NOT a Binary Search Tree insertion. Time O(N), where N is the number of nodes. It must traverse level-by-level to find an empty slot. Space O(N) in the worst case for the BFS queue (e.g., a full last level).
+   *
+   * @param keyNodeOrEntry - The key, node, or entry to add or update.
+   * @param [value] - The value, if providing just a key.
+   * @returns True if the addition was successful, false otherwise.
+   */
+  set(
+    keyNodeOrEntry: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined,
+    value?: V
+  ): boolean {
+    return this.add(keyNodeOrEntry, value);
+  }
+
   /**
    * Adds multiple items to the tree.
    * @remarks Time O(N * M), where N is the number of items to add and M is the size of the tree at insertion (due to O(M) `add` operation). Space O(M) (from `add`) + O(N) (for the `inserted` array).
@@ -657,6 +750,23 @@ export class BinaryTree<K = any, V = any, R = any>
     return inserted;
   }
 
+  /**
+   * Adds or updates multiple items to the tree.
+   * @remarks Time O(N * M), where N is the number of items to add and M is the size of the tree at insertion (due to O(M) `add` operation). Space O(M) (from `add`) + O(N) (for the `inserted` array).
+   *
+   * @param keysNodesEntriesOrRaws - An iterable of items to add or update.
+   * @param [values] - An optional parallel iterable of values.
+   * @returns An array of booleans indicating the success of each individual `add` operation.
+   */
+  setMany(
+    keysNodesEntriesOrRaws: Iterable<
+      K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined | R
+    >,
+    values?: Iterable<V | undefined>
+  ): boolean[] {
+    return this.addMany(keysNodesEntriesOrRaws, values);
+  }
+
   /**
    * Merges another tree into this one by adding all its nodes.
    * @remarks Time O(N * M), same as `addMany`, where N is the size of `anotherTree` and M is the size of this tree. Space O(M) (from `add`).