tree-multimap-typed 2.2.2 → 2.2.4

package/dist/types/data-structures/trie/trie.d.ts

@@ -77,53 +77,99 @@ export declare class TrieNode {
  * 10. IP Routing: Used in certain types of IP routing algorithms.
  * 11. Text Word Frequency Count: Counting and storing the frequency of words in a large amount of text data.
  * @example
- * // Autocomplete: Prefix validation and checking
- *     const autocomplete = new Trie<string>(['gmail.com', 'gmail.co.nz', 'gmail.co.jp', 'yahoo.com', 'outlook.com']);
+ * // basic Trie creation and add words
+ *  // Create a simple Trie with initial words
+ *     const trie = new Trie(['apple', 'app', 'apply']);
  *
- *     // Get all completions for a prefix
- *     const gmailCompletions = autocomplete.getWords('gmail');
- *     console.log(gmailCompletions); // ['gmail.com', 'gmail.co.nz', 'gmail.co.jp']
+ *     // Verify size
+ *     console.log(trie.size); // 3;
+ *
+ *     // Check if words exist
+ *     console.log(trie.has('apple')); // true;
+ *     console.log(trie.has('app')); // true;
+ *
+ *     // Add a new word
+ *     trie.add('application');
+ *     console.log(trie.size); // 4;
  * @example
- * // File System Path Operations
- *     const fileSystem = new Trie<string>([
- *       '/home/user/documents/file1.txt',
- *       '/home/user/documents/file2.txt',
- *       '/home/user/pictures/photo.jpg',
- *       '/home/user/pictures/vacation/',
- *       '/home/user/downloads'
- *     ]);
+ * // Trie getWords and prefix search
+ *  const trie = new Trie(['apple', 'app', 'apply', 'application', 'apricot']);
  *
- *     // Find common directory prefix
- *     console.log(fileSystem.getLongestCommonPrefix()); // '/home/user/'
+ *     // Get all words with prefix 'app'
+ *     const appWords = trie.getWords('app');
+ *     console.log(appWords); // contains 'app';
+ *     console.log(appWords); // contains 'apple';
+ *     console.log(appWords); // contains 'apply';
+ *     console.log(appWords); // contains 'application';
+ *     expect(appWords).not.toContain('apricot');
+ * @example
+ * // Trie isPrefix and isAbsolutePrefix checks
+ *  const trie = new Trie(['tree', 'trial', 'trick', 'trip', 'trie']);
  *
- *     // List all files in a directory
- *     const documentsFiles = fileSystem.getWords('/home/user/documents/');
- *     console.log(documentsFiles); // ['/home/user/documents/file1.txt', '/home/user/documents/file2.txt']
+ *     // Check if string is a prefix of any word
+ *     console.log(trie.hasPrefix('tri')); // true;
+ *     console.log(trie.hasPrefix('tr')); // true;
+ *     console.log(trie.hasPrefix('xyz')); // false;
+ *
+ *     // Check if string is an absolute prefix (not a complete word)
+ *     console.log(trie.hasPurePrefix('tri')); // true;
+ *     console.log(trie.hasPurePrefix('tree')); // false; // 'tree' is a complete word
+ *
+ *     // Verify size
+ *     console.log(trie.size); // 5;
  * @example
- * // Autocomplete: Basic word suggestions
- *     // Create a trie for autocomplete
- *     const autocomplete = new Trie<string>([
- *       'function',
- *       'functional',
- *       'functions',
- *       'class',
- *       'classes',
- *       'classical',
- *       'closure',
- *       'const',
- *       'constructor'
- *     ]);
+ * // Trie delete and iteration
+ *  const trie = new Trie(['car', 'card', 'care', 'careful', 'can', 'cat']);
+ *
+ *     // Delete a word
+ *     trie.delete('card');
+ *     console.log(trie.has('card')); // false;
+ *
+ *     // Word with same prefix still exists
+ *     console.log(trie.has('care')); // true;
  *
- *     // Test autocomplete with different prefixes
- *     console.log(autocomplete.getWords('fun')); // ['functional', 'functions', 'function']
- *     console.log(autocomplete.getWords('cla')); // ['classes', 'classical', 'class']
- *     console.log(autocomplete.getWords('con')); // ['constructor', 'const']
+ *     // Size decreased
+ *     console.log(trie.size); // 5;
  *
- *     // Test with non-matching prefix
- *     console.log(autocomplete.getWords('xyz')); // []
+ *     // Iterate through all words
+ *     const allWords = [...trie];
+ *     console.log(allWords.length); // 5;
+ * @example
+ * // Trie for autocomplete search index
+ *  // Trie is perfect for autocomplete: O(m + k) where m is prefix length, k is results
+ *     const searchIndex = new Trie(['typescript', 'javascript', 'python', 'java', 'rust', 'ruby', 'golang', 'kotlin']);
+ *
+ *     // User types 'j' - get all suggestions
+ *     const jResults = searchIndex.getWords('j');
+ *     console.log(jResults); // contains 'javascript';
+ *     console.log(jResults); // contains 'java';
+ *     console.log(jResults.length); // 2;
+ *
+ *     // User types 'ja' - get more specific suggestions
+ *     const jaResults = searchIndex.getWords('ja');
+ *     console.log(jaResults); // contains 'javascript';
+ *     console.log(jaResults); // contains 'java';
+ *     console.log(jaResults.length); // 2;
+ *
+ *     // User types 'jav' - even more specific
+ *     const javResults = searchIndex.getWords('jav');
+ *     console.log(javResults); // contains 'javascript';
+ *     console.log(javResults); // contains 'java';
+ *     console.log(javResults.length); // 2;
+ *
+ *     // Check for common prefix
+ *
+ *     console.log(searchIndex.hasCommonPrefix('ja')); // false; // Not all words start with 'ja'
+ *
+ *     // Total words in index
+ *     console.log(searchIndex.size); // 8;
+ *
+ *     // Get height (depth of tree)
+ *     const height = searchIndex.getHeight();
+ *     console.log(typeof height); // 'number';
  * @example
  * // Dictionary: Case-insensitive word lookup
- *     // Create a case-insensitive dictionary
+ *  // Create a case-insensitive dictionary
  *     const dictionary = new Trie<string>([], { caseSensitive: false });
  *
  *     // Add words with mixed casing
@@ -132,14 +178,30 @@ export declare class TrieNode {
  *     dictionary.add('JavaScript');
  *
  *     // Test lookups with different casings
- *     console.log(dictionary.has('hello')); // true
- *     console.log(dictionary.has('HELLO')); // true
- *     console.log(dictionary.has('Hello')); // true
- *     console.log(dictionary.has('javascript')); // true
- *     console.log(dictionary.has('JAVASCRIPT')); // true
+ *     console.log(dictionary.has('hello')); // true;
+ *     console.log(dictionary.has('HELLO')); // true;
+ *     console.log(dictionary.has('Hello')); // true;
+ *     console.log(dictionary.has('javascript')); // true;
+ *     console.log(dictionary.has('JAVASCRIPT')); // true;
+ * @example
+ * // File System Path Operations
+ *  const fileSystem = new Trie<string>([
+ *       '/home/user/documents/file1.txt',
+ *       '/home/user/documents/file2.txt',
+ *       '/home/user/pictures/photo.jpg',
+ *       '/home/user/pictures/vacation/',
+ *       '/home/user/downloads'
+ *     ]);
+ *
+ *     // Find common directory prefix
+ *     console.log(fileSystem.getLongestCommonPrefix()); // '/home/user/';
+ *
+ *     // List all files in a directory
+ *     const documentsFiles = fileSystem.getWords('/home/user/documents/');
+ *     console.log(documentsFiles); // ['/home/user/documents/file1.txt', '/home/user/documents/file2.txt'];
  * @example
  * // IP Address Routing Table
- *     // Add IP address prefixes and their corresponding routes
+ *  // Add IP address prefixes and their corresponding routes
  *     const routes = {
  *       '192.168.1': 'LAN_SUBNET_1',
  *       '192.168.2': 'LAN_SUBNET_2',
@@ -150,13 +212,13 @@ export declare class TrieNode {
  *     const ipRoutingTable = new Trie<string>(Object.keys(routes));
  *
  *     // Check IP address prefix matching
- *     console.log(ipRoutingTable.hasPrefix('192.168.1')); // true
- *     console.log(ipRoutingTable.hasPrefix('192.168.2')); // true
+ *     console.log(ipRoutingTable.hasPrefix('192.168.1')); // true;
+ *     console.log(ipRoutingTable.hasPrefix('192.168.2')); // true;
  *
  *     // Validate IP address belongs to subnet
  *     const ip = '192.168.1.100';
  *     const subnet = ip.split('.').slice(0, 3).join('.');
- *     console.log(ipRoutingTable.hasPrefix(subnet)); // true
+ *     console.log(ipRoutingTable.hasPrefix(subnet)); // true;
  */
 export declare class Trie<R = any> extends IterableElementBase<string, R> {
     /**

package/dist/types/interfaces/binary-tree.d.ts

@@ -17,6 +17,7 @@ export interface IBinaryTree<K = any, V = any, R = any> {
     createNode(key: K, value?: BinaryTreeNode<K, V>['value']): BinaryTreeNode<K, V>;
     createTree(options?: Partial<BinaryTreeOptions<K, V, R>>): IBinaryTree<K, V, R>;
     add(keyOrNodeOrEntryOrRawElement: BTNRep<K, V, BinaryTreeNode<K, V>>, value?: V, count?: number): boolean;
+    set(keyOrNodeOrEntryOrRawElement: BTNRep<K, V, BinaryTreeNode<K, V>>, value?: V, count?: number): boolean;
     addMany(keysNodesEntriesOrRaws: Iterable<K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined | R>, values?: Iterable<V | undefined>): boolean[];
     delete(keyNodeEntryRawOrPredicate: R | BTNRep<K, V, BinaryTreeNode<K, V>> | NodePredicate<BinaryTreeNode<K, V> | null>): BinaryTreeDeleteResult<BinaryTreeNode<K, V>>[];
     clear(): void;

package/dist/types/types/data-structures/binary-tree/bst.d.ts

@@ -1,12 +1,12 @@
 import type { BinaryTreeOptions } from './binary-tree';
-import { Comparable } from '../../utils';
-import { OptValue } from '../../common';
-export type BSTOptions<K, V, R> = Omit<BinaryTreeOptions<K, V, R>, 'isDuplicate'> & {
-    specifyComparable?: (key: K) => Comparable;
-    isReverse?: boolean;
+import type { Comparator, OptValue } from '../../common';
+type BSTBaseOptions<K, V, R> = Omit<BinaryTreeOptions<K, V, R>, 'isDuplicate'>;
+export type BSTOptions<K, V, R> = BSTBaseOptions<K, V, R> & {
+    comparator?: Comparator<K>;
 };
 export type BSTNOptKey<K> = K | undefined;
 export type OptNode<NODE> = NODE | undefined;
 export type BSTNEntry<K, V> = [BSTNOptKey<K>, OptValue<V>];
 export type BSTNOptKeyOrNode<K, NODE> = BSTNOptKey<K> | NODE;
 export type BSTNRep<K, V, NODE> = BSTNEntry<K, V> | BSTNOptKeyOrNode<K, NODE>;
+export {};

package/dist/umd/tree-multimap-typed.js

@@ -1479,6 +1479,17 @@ var treeMultimapTyped = (() => {
       }
       return false;
     }
+    /**
+     * 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, value) {
+      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).
@@ -1506,6 +1517,17 @@ var treeMultimapTyped = (() => {
       }
       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, values) {
+      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`).
@@ -2818,36 +2840,20 @@ var treeMultimapTyped = (() => {
     constructor(keysNodesEntriesOrRaws = [], options) {
       super([], options);
       __publicField(this, "_root");
-      __publicField(this, "_isReverse", false);
       /**
-       * The default comparator function.
-       * @remarks Time O(1) (or O(C) if `specifyComparable` is used, C is complexity of that function).
-       */
-      __publicField(this, "_comparator", (a, b) => {
-        if (isComparable(a) && isComparable(b)) {
-          if (a > b) return 1;
-          if (a < b) return -1;
-          return 0;
-        }
-        if (this._specifyComparable) {
-          const va = this._specifyComparable(a);
-          const vb = this._specifyComparable(b);
-          if (va > vb) return 1;
-          if (va < vb) return -1;
-          return 0;
-        }
-        if (typeof a === "object" || typeof b === "object") {
-          throw TypeError(
-            `When comparing object types, a custom specifyComparable must be defined in the constructor's options.`
-          );
-        }
-        return 0;
-      });
-      __publicField(this, "_specifyComparable");
+         * The comparator function used to determine the order of keys in the tree.
+      
+         * @remarks Time O(1) Space O(1)
+         */
+      __publicField(this, "_comparator");
       if (options) {
-        const { specifyComparable, isReverse } = options;
-        if (typeof specifyComparable === "function") this._specifyComparable = specifyComparable;
-        if (isReverse !== void 0) this._isReverse = isReverse;
+        if ("comparator" in options && options.comparator !== void 0) {
+          this._comparator = options.comparator;
+        } else {
+          this._comparator = this._createDefaultComparator();
+        }
+      } else {
+        this._comparator = this._createDefaultComparator();
       }
       if (keysNodesEntriesOrRaws) this.addMany(keysNodesEntriesOrRaws);
     }
@@ -2861,13 +2867,25 @@ var treeMultimapTyped = (() => {
       return this._root;
     }
     /**
-     * Gets whether the tree's comparison logic is reversed.
-     * @remarks Time O(1)
-     *
-     * @returns True if the tree is reversed (e.g., a max-heap logic).
+     * (Protected) Creates the default comparator function for keys that don't have a custom comparator.
+     * @remarks Time O(1) Space O(1)
+     * @returns The default comparator function.
      */
-    get isReverse() {
-      return this._isReverse;
+    _createDefaultComparator() {
+      return (a, b) => {
+        debugger;
+        if (isComparable(a) && isComparable(b)) {
+          if (a > b) return 1;
+          if (a < b) return -1;
+          return 0;
+        }
+        if (typeof a === "object" || typeof b === "object") {
+          throw TypeError(
+            `When comparing object type keys, a custom comparator must be provided in the constructor's options!`
+          );
+        }
+        return 0;
+      };
     }
     /**
      * Gets the comparator function used by the tree.
@@ -2878,15 +2896,6 @@ var treeMultimapTyped = (() => {
     get comparator() {
       return this._comparator;
     }
-    /**
-     * Gets the function used to extract a comparable value from a complex key.
-     * @remarks Time O(1)
-     *
-     * @returns The key-to-comparable conversion function.
-     */
-    get specifyComparable() {
-      return this._specifyComparable;
-    }
     /**
      * (Protected) Creates a new BST node.
      * @remarks Time O(1), Space O(1)
@@ -2928,7 +2937,7 @@ var treeMultimapTyped = (() => {
      * @returns True if the key is valid, false otherwise.
      */
     isValidKey(key) {
-      return isComparable(key, this._specifyComparable !== void 0);
+      return isComparable(key);
     }
     /**
      * Performs a Depth-First Search (DFS) traversal.
@@ -3018,8 +3027,8 @@ var treeMultimapTyped = (() => {
         if (!this.isRealNode(cur.left)) return false;
         if (isRange) {
           const range = keyNodeEntryOrPredicate;
-          const leftS = this.isReverse ? range.high : range.low;
-          const leftI = this.isReverse ? range.includeHigh : range.includeLow;
+          const leftS = range.low;
+          const leftI = range.includeLow;
           return leftI && this._compare(cur.key, leftS) >= 0 || !leftI && this._compare(cur.key, leftS) > 0;
         }
         if (!isRange && !this._isPredicate(keyNodeEntryOrPredicate)) {
@@ -3033,8 +3042,8 @@ var treeMultimapTyped = (() => {
         if (!this.isRealNode(cur.right)) return false;
         if (isRange) {
           const range = keyNodeEntryOrPredicate;
-          const rightS = this.isReverse ? range.low : range.high;
-          const rightI = this.isReverse ? range.includeLow : range.includeHigh;
+          const rightS = range.high;
+          const rightI = range.includeHigh;
           return rightI && this._compare(cur.key, rightS) <= 0 || !rightI && this._compare(cur.key, rightS) < 0;
         }
         if (!isRange && !this._isPredicate(keyNodeEntryOrPredicate)) {
@@ -3195,6 +3204,32 @@ var treeMultimapTyped = (() => {
       else _iterate();
       return inserted;
     }
+    /**
+     * Returns the first node with a key greater than or equal to the given key.
+     * This is equivalent to C++ std::lower_bound on a BST.
+     * Supports RECURSIVE and ITERATIVE implementations.
+     * Time Complexity: O(log n) on average, O(h) where h is tree height.
+     * Space Complexity: O(h) for recursion, O(1) for iteration.
+     * @param keyNodeEntryOrPredicate - The key, node, entry, or predicate function to search for.
+     * @param iterationType The iteration type (RECURSIVE or ITERATIVE). Defaults to this.iterationType.
+     * @returns The first node with key >= given key, or undefined if no such node exists.
+     */
+    lowerBound(keyNodeEntryOrPredicate, iterationType = this.iterationType) {
+      return this._bound(keyNodeEntryOrPredicate, true, iterationType);
+    }
+    /**
+     * Returns the first node with a key strictly greater than the given key.
+     * This is equivalent to C++ std::upper_bound on a BST.
+     * Supports RECURSIVE and ITERATIVE implementations.
+     * Time Complexity: O(log n) on average, O(h) where h is tree height.
+     * Space Complexity: O(h) for recursion, O(1) for iteration.
+     * @param keyNodeEntryOrPredicate - The key, node, entry, or predicate function to search for.
+     * @param iterationType The iteration type (RECURSIVE or ITERATIVE). Defaults to this.iterationType.
+     * @returns The first node with key > given key, or undefined if no such node exists.
+     */
+    upperBound(keyNodeEntryOrPredicate, iterationType = this.iterationType) {
+      return this._bound(keyNodeEntryOrPredicate, false, iterationType);
+    }
     /**
      * Traverses the tree and returns nodes that are lesser or greater than a target node.
      * @remarks Time O(N), as it performs a full traversal. Space O(log N) or O(N).
@@ -3329,31 +3364,171 @@ var treeMultimapTyped = (() => {
       return out;
     }
     /**
-     * Deletes the first node found that satisfies the predicate.
-     * @remarks Performs an in-order traversal. Time O(N) worst-case (O(log N) to find + O(log N) to delete). Space O(log N) for stack.
+     * Deletes nodes that match a key, node, entry, predicate, or range.
      *
-     * @param predicate - A function to test each [key, value] pair.
-     * @returns True if a node was deleted, false otherwise.
+     * @remarks
+     * Time Complexity: O(N) for search + O(M log N) for M deletions, where N is tree size.
+     * Space Complexity: O(M) for storing matched nodes and result map.
+     *
+     * @template K - The key type.
+     * @template V - The value type.
+     *
+     * @param keyNodeEntryOrPredicate - The search criteria. Can be one of:
+     *   - A key (type K): searches for exact key match using the comparator.
+     *   - A BSTNode: searches for the matching node in the tree.
+     *   - An entry tuple: searches for the key-value pair.
+     *   - A NodePredicate function: tests each node and returns true for matches.
+     *   - A Range object: searches for nodes whose keys fall within the specified range (inclusive/exclusive based on range settings).
+     *   - null or undefined: treated as no match, returns empty results.
+     *
+     * @param onlyOne - If true, stops the search after finding the first match and only deletes that one node.
+     *   If false (default), searches for and deletes all matching nodes.
+     *
+     * @param startNode - The node to start the search from. Can be:
+     *   - A key, node, or entry: the method resolves it to a node and searches from that subtree.
+     *   - null or undefined: defaults to the root, searching the entire tree.
+     *   - Default value: this._root (the tree's root).
+     *
+     * @param iterationType - Controls the internal traversal implementation:
+     *   - 'RECURSIVE': uses recursive function calls for traversal.
+     *   - 'ITERATIVE': uses explicit stack-based iteration.
+     *   - Default: this.iterationType (the tree's default iteration mode).
+     *
+     * @returns A Map<K, boolean> containing the deletion results:
+     *   - Key: the matched node's key.
+     *   - Value: true if the deletion succeeded, false if it failed (e.g., key not found during deletion phase).
+     *   - If no nodes match the search criteria, the returned map is empty.
+     */
+    deleteWhere(keyNodeEntryOrPredicate, onlyOne = false, startNode = this._root, iterationType = this.iterationType) {
+      const toDelete = this.search(
+        keyNodeEntryOrPredicate,
+        onlyOne,
+        (node) => node,
+        startNode,
+        iterationType
+      );
+      let results = [];
+      for (const node of toDelete) {
+        const deleteInfo = this.delete(node);
+        results = results.concat(deleteInfo);
+      }
+      return results;
+    }
+    /**
+     * (Protected) Core bound search implementation supporting all parameter types.
+     * Unified logic for both lowerBound and upperBound.
+     * Resolves various input types (Key, Node, Entry, Predicate) using parent class utilities.
+     * @param keyNodeEntryOrPredicate - The key, node, entry, or predicate function to search for.
+     * @param isLower - True for lowerBound (>=), false for upperBound (>).
+     * @param iterationType - The iteration type (RECURSIVE or ITERATIVE).
+     * @returns The first matching node, or undefined if no such node exists.
      */
-    deleteWhere(predicate) {
-      const stack = [];
-      let cur = this._root;
-      let index = 0;
-      while (stack.length > 0 || cur !== void 0) {
-        while (cur !== void 0 && cur !== null) {
-          stack.push(cur);
-          cur = cur.left;
+    _bound(keyNodeEntryOrPredicate, isLower, iterationType) {
+      if (keyNodeEntryOrPredicate === null || keyNodeEntryOrPredicate === void 0) {
+        return void 0;
+      }
+      if (this._isPredicate(keyNodeEntryOrPredicate)) {
+        return this._boundByPredicate(keyNodeEntryOrPredicate, iterationType);
+      }
+      let targetKey;
+      if (this.isNode(keyNodeEntryOrPredicate)) {
+        targetKey = keyNodeEntryOrPredicate.key;
+      } else if (this.isEntry(keyNodeEntryOrPredicate)) {
+        const key = keyNodeEntryOrPredicate[0];
+        if (key === null || key === void 0) {
+          return void 0;
         }
-        const node = stack.pop();
-        if (!node) break;
-        const key = node.key;
-        const val = node.value;
-        if (predicate(key, val, index++, this)) {
-          return this._deleteByKey(key);
+        targetKey = key;
+      } else {
+        targetKey = keyNodeEntryOrPredicate;
+      }
+      if (targetKey !== void 0) {
+        return this._boundByKey(targetKey, isLower, iterationType);
+      }
+      return void 0;
+    }
+    /**
+     * (Protected) Binary search for bound by key with pruning optimization.
+     * Performs standard BST binary search, choosing left or right subtree based on comparator result.
+     * For lowerBound: finds first node where key >= target.
+     * For upperBound: finds first node where key > target.
+     * @param key - The target key to search for.
+     * @param isLower - True for lowerBound (>=), false for upperBound (>).
+     * @param iterationType - The iteration type (RECURSIVE or ITERATIVE).
+     * @returns The first node matching the bound condition, or undefined if none exists.
+     */
+    _boundByKey(key, isLower, iterationType) {
+      var _a, _b;
+      if (iterationType === "RECURSIVE") {
+        const dfs = (cur) => {
+          if (!this.isRealNode(cur)) return void 0;
+          const cmp = this.comparator(cur.key, key);
+          const condition = isLower ? cmp >= 0 : cmp > 0;
+          if (condition) {
+            const leftResult = dfs(cur.left);
+            return leftResult != null ? leftResult : cur;
+          } else {
+            return dfs(cur.right);
+          }
+        };
+        return dfs(this.root);
+      } else {
+        let current = this.root;
+        let result = void 0;
+        while (this.isRealNode(current)) {
+          const cmp = this.comparator(current.key, key);
+          const condition = isLower ? cmp >= 0 : cmp > 0;
+          if (condition) {
+            result = current;
+            current = (_a = current.left) != null ? _a : void 0;
+          } else {
+            current = (_b = current.right) != null ? _b : void 0;
+          }
         }
-        cur = node.right;
+        return result;
+      }
+    }
+    /**
+     * (Protected) In-order traversal search by predicate.
+     * Falls back to linear in-order traversal when predicate-based search is required.
+     * Returns the first node that satisfies the predicate function.
+     * Note: Predicate-based search cannot leverage BST's binary search optimization.
+     * Time Complexity: O(n) since it may visit every node.
+     * @param predicate - The predicate function to test nodes.
+     * @param iterationType - The iteration type (RECURSIVE or ITERATIVE).
+     * @returns The first node satisfying predicate, or undefined if none found.
+     */
+    _boundByPredicate(predicate, iterationType) {
+      if (iterationType === "RECURSIVE") {
+        let result = void 0;
+        const dfs = (cur) => {
+          if (result || !this.isRealNode(cur)) return;
+          if (this.isRealNode(cur.left)) dfs(cur.left);
+          if (!result && predicate(cur)) {
+            result = cur;
+          }
+          if (!result && this.isRealNode(cur.right)) dfs(cur.right);
+        };
+        dfs(this.root);
+        return result;
+      } else {
+        const stack = [];
+        let current = this.root;
+        while (stack.length > 0 || this.isRealNode(current)) {
+          if (this.isRealNode(current)) {
+            stack.push(current);
+            current = current.left;
+          } else {
+            const node = stack.pop();
+            if (!this.isRealNode(node)) break;
+            if (predicate(node)) {
+              return node;
+            }
+            current = node.right;
+          }
+        }
+        return void 0;
       }
-      return false;
     }
     /**
      * (Protected) Creates a new, empty instance of the same BST constructor.
@@ -3390,8 +3565,7 @@ var treeMultimapTyped = (() => {
     _snapshotOptions() {
       return {
         ...super._snapshotOptions(),
-        specifyComparable: this.specifyComparable,
-        isReverse: this.isReverse
+        comparator: this._comparator
       };
     }
     /**
@@ -3419,14 +3593,14 @@ var treeMultimapTyped = (() => {
     }
     /**
      * (Protected) Compares two keys using the tree's comparator and reverse setting.
-     * @remarks Time O(1) (or O(C) if `specifyComparable` is used).
+     * @remarks Time O(1) Space O(1)
      *
      * @param a - The first key.
      * @param b - The second key.
      * @returns A number (1, -1, or 0) representing the comparison.
      */
     _compare(a, b) {
-      return this._isReverse ? -this._comparator(a, b) : this._comparator(a, b);
+      return this._comparator(a, b);
     }
     /**
      * (Private) Deletes a node by its key.