data-structure-typed 2.4.0 → 2.4.2

package/dist/esm/index.mjs

@@ -11858,17 +11858,30 @@ var TreeSet = class _TreeSet {
   #isDefaultComparator;
   #userComparator;
   /**
-   * Create a TreeSet from an iterable of keys.
+   * Create a TreeSet from an iterable of keys or raw elements.
    *
+   * @param elements - Iterable of keys, or raw elements if `toElementFn` is provided.
+   * @param options - Configuration options including optional `toElementFn` to transform raw elements.
    * @throws {TypeError} When using the default comparator and encountering unsupported key types,
    * or invalid keys (e.g. `NaN`, invalid `Date`).
+   * @example
+   * // Standard usage with keys
+   * const set = new TreeSet([3, 1, 2]);
+   *
+   * // Using toElementFn to transform raw objects
+   * const users = [{ id: 3, name: 'Alice' }, { id: 1, name: 'Bob' }];
+   * const set = new TreeSet<number, User>(users, { toElementFn: u => u.id });
    */
   constructor(elements = [], options = {}) {
     this.#userComparator = options.comparator;
+    const toElementFn = options.toElementFn;
     const comparator = options.comparator ?? _TreeSet.createDefaultComparator();
     this.#isDefaultComparator = options.comparator === void 0;
     this.#core = new RedBlackTree([], { comparator, isMapMode: options.isMapMode });
-    for (const k of elements) this.add(k);
+    for (const item of elements) {
+      const k = toElementFn ? toElementFn(item) : item;
+      this.add(k);
+    }
   }
   /**
    * Create the strict default comparator.
@@ -12179,16 +12192,34 @@ var TreeMultiMap = class _TreeMultiMap {
   #isDefaultComparator;
   /**
    * Creates a new TreeMultiMap.
-   * @param keysNodesEntriesOrRaws - Initial entries
-   * @param options - Configuration options
+   * @param keysNodesEntriesOrRaws - Initial entries, or raw elements if `toEntryFn` is provided.
+   * @param options - Configuration options including optional `toEntryFn` to transform raw elements.
    * @remarks Time O(m log m), Space O(m) where m is the number of initial entries
+   * @example
+   * // Standard usage with entries
+   * const mmap = new TreeMultiMap([['a', ['x', 'y']], ['b', ['z']]]);
+   *
+   * // Using toEntryFn to transform raw objects
+   * const players = [{ score: 100, items: ['sword'] }, { score: 200, items: ['shield', 'bow'] }];
+   * const mmap = new TreeMultiMap(players, { toEntryFn: p => [p.score, p.items] });
    */
   constructor(keysNodesEntriesOrRaws = [], options = {}) {
     const comparator = options.comparator ?? TreeSet.createDefaultComparator();
     this.#isDefaultComparator = options.comparator === void 0;
+    const toEntryFn = options.toEntryFn;
     this.#core = new RedBlackTree([], { ...options, comparator, isMapMode: options.isMapMode });
     for (const x of keysNodesEntriesOrRaws) {
       if (x === null || x === void 0) continue;
+      if (toEntryFn) {
+        const [k, bucket] = toEntryFn(x);
+        if (k === null || k === void 0) continue;
+        if (bucket !== void 0) {
+          this.#core.set(k, Array.isArray(bucket) ? [...bucket] : [bucket]);
+        } else {
+          this.#core.set(k, []);
+        }
+        continue;
+      }
       if (Array.isArray(x)) {
         const [k, bucket] = x;
         if (k === null || k === void 0) continue;
@@ -12524,8 +12555,8 @@ var TreeMultiMap = class _TreeMultiMap {
    * Prints the internal tree structure (for debugging).
    * @remarks Time O(n), Space O(n)
    */
-  print(...args) {
-    return this.#core.print(...args);
+  print() {
+    this.#core.print();
   }
   /**
    * Executes a callback for each entry.
@@ -12576,7 +12607,7 @@ var TreeMultiMap = class _TreeMultiMap {
   setMany(keysNodesEntriesOrRaws) {
     const results = [];
     for (const x of keysNodesEntriesOrRaws) {
-      results.push(this.set(x, void 0));
+      results.push(this.set(x));
     }
     return results;
   }
@@ -12584,22 +12615,22 @@ var TreeMultiMap = class _TreeMultiMap {
    * Searches for entries within a key range.
    * @remarks Time O(log n + k), Space O(k) where k is result size
    */
-  rangeSearch(range, callback, isBalanced) {
-    return this.#core.rangeSearch(range, callback, isBalanced);
+  rangeSearch(range, callback) {
+    return this.#core.rangeSearch(range, callback);
   }
   /**
    * Creates a shallow clone of this map.
    * @remarks Time O(n log n), Space O(n)
    */
   clone() {
-    return new _TreeMultiMap(this, { comparator: this.comparator, isMapMode: this.#core._isMapMode });
+    return new _TreeMultiMap(this, { comparator: this.comparator, isMapMode: this.#core.isMapMode });
   }
   /**
    * Expose comparator for advanced usage/testing (read-only).
    * @remarks Time O(1), Space O(1)
    */
   get comparator() {
-    return this.#core._comparator;
+    return this.#core.comparator;
   }
 };
 
@@ -12612,22 +12643,38 @@ var TreeMap = class _TreeMap {
   #isDefaultComparator;
   #userComparator;
   /**
-   * Create a TreeMap from an iterable of `[key, value]` entries.
+   * Create a TreeMap from an iterable of `[key, value]` entries or raw elements.
+   *
+   * @param entries - Iterable of `[key, value]` tuples, or raw elements if `toEntryFn` is provided.
+   * @param options - Configuration options including optional `toEntryFn` to transform raw elements.
+   * @throws {TypeError} If any entry is not a 2-tuple-like value (when no toEntryFn), or when using
+   * the default comparator and encountering unsupported/invalid keys (e.g. `NaN`, invalid `Date`).
+   * @example
+   * // Standard usage with entries
+   * const map = new TreeMap([['a', 1], ['b', 2]]);
    *
-   * @throws {TypeError} If any entry is not a 2-tuple-like value, or when using the default comparator
-   * and encountering unsupported/invalid keys (e.g. `NaN`, invalid `Date`).
+   * // Using toEntryFn to transform raw objects
+   * const users = [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }];
+   * const map = new TreeMap<number, User, User>(users, { toEntryFn: u => [u.id, u] });
    */
   constructor(entries = [], options = {}) {
     this.#userComparator = options.comparator;
+    const toEntryFn = options.toEntryFn;
     const comparator = options.comparator ?? _TreeMap.createDefaultComparator();
     this.#isDefaultComparator = options.comparator === void 0;
     this.#core = new RedBlackTree([], { comparator, isMapMode: options.isMapMode });
     for (const item of entries) {
-      if (!Array.isArray(item) || item.length < 2) {
-        throw new TypeError("TreeMap: each entry must be a [key, value] tuple");
+      let k;
+      let v;
+      if (toEntryFn) {
+        [k, v] = toEntryFn(item);
+      } else {
+        if (!Array.isArray(item) || item.length < 2) {
+          throw new TypeError("TreeMap: each entry must be a [key, value] tuple");
+        }
+        k = item[0];
+        v = item[1];
       }
-      const k = item[0];
-      const v = item[1];
       this.set(k, v);
     }
   }
@@ -12953,15 +13000,26 @@ var TreeMultiSet = class _TreeMultiSet {
   // total occurrences (sumCounts)
   /**
    * Creates a new TreeMultiSet.
-   * @param elements - Initial elements to add
-   * @param options - Configuration options
+   * @param elements - Initial elements to add, or raw elements if `toElementFn` is provided.
+   * @param options - Configuration options including optional `toElementFn` to transform raw elements.
    * @remarks Time O(m log m), Space O(m) where m is the number of initial elements
+   * @example
+   * // Standard usage with elements
+   * const mset = new TreeMultiSet([1, 2, 2, 3]);
+   *
+   * // Using toElementFn to transform raw objects
+   * const items = [{ score: 100 }, { score: 200 }, { score: 100 }];
+   * const mset = new TreeMultiSet<number, Item>(items, { toElementFn: item => item.score });
    */
   constructor(elements = [], options = {}) {
+    const toElementFn = options.toElementFn;
     const comparator = options.comparator ?? TreeSet.createDefaultComparator();
     this.#isDefaultComparator = options.comparator === void 0;
     this.#core = new RedBlackTree([], { comparator, isMapMode: options.isMapMode });
-    for (const k of elements) this.add(k);
+    for (const item of elements) {
+      const k = toElementFn ? toElementFn(item) : item;
+      this.add(k);
+    }
   }
   /**
    * Validates the key against the default comparator rules.
@@ -14299,20 +14357,17 @@ var Trie = class extends IterableElementBase {
     prefix = this._caseProcess(prefix);
     const words = [];
     let found = 0;
-    function dfs(node, word) {
-      for (const char of node.children.keys()) {
-        const charNode = node.children.get(char);
-        if (charNode !== void 0) {
-          dfs(charNode, word.concat(char));
-        }
+    const dfs = /* @__PURE__ */ __name((node, word) => {
+      for (const [char, childNode] of node.children) {
+        if (found >= max) return;
+        dfs(childNode, word + char);
       }
       if (node.isEnd) {
-        if (found > max - 1) return;
+        if (found >= max) return;
         words.push(word);
         found++;
       }
-    }
-    __name(dfs, "dfs");
+    }, "dfs");
     let startNode = this.root;
     if (prefix) {
       for (const c of prefix) {

package/dist/esm-legacy/index.mjs

@@ -11845,10 +11845,19 @@ var RedBlackTree = _RedBlackTree;
 var _core, _isDefaultComparator, _userComparator;
 var _TreeSet = class _TreeSet {
   /**
-   * Create a TreeSet from an iterable of keys.
+   * Create a TreeSet from an iterable of keys or raw elements.
    *
+   * @param elements - Iterable of keys, or raw elements if `toElementFn` is provided.
+   * @param options - Configuration options including optional `toElementFn` to transform raw elements.
    * @throws {TypeError} When using the default comparator and encountering unsupported key types,
    * or invalid keys (e.g. `NaN`, invalid `Date`).
+   * @example
+   * // Standard usage with keys
+   * const set = new TreeSet([3, 1, 2]);
+   *
+   * // Using toElementFn to transform raw objects
+   * const users = [{ id: 3, name: 'Alice' }, { id: 1, name: 'Bob' }];
+   * const set = new TreeSet<number, User>(users, { toElementFn: u => u.id });
    */
   constructor(elements = [], options = {}) {
     __privateAdd(this, _core);
@@ -11856,10 +11865,14 @@ var _TreeSet = class _TreeSet {
     __privateAdd(this, _userComparator);
     var _a;
     __privateSet(this, _userComparator, options.comparator);
+    const toElementFn = options.toElementFn;
     const comparator = (_a = options.comparator) != null ? _a : _TreeSet.createDefaultComparator();
     __privateSet(this, _isDefaultComparator, options.comparator === void 0);
     __privateSet(this, _core, new RedBlackTree([], { comparator, isMapMode: options.isMapMode }));
-    for (const k of elements) this.add(k);
+    for (const item of elements) {
+      const k = toElementFn ? toElementFn(item) : item;
+      this.add(k);
+    }
   }
   /**
    * Create the strict default comparator.
@@ -12171,9 +12184,16 @@ var _core2, _isDefaultComparator2;
 var _TreeMultiMap = class _TreeMultiMap {
   /**
    * Creates a new TreeMultiMap.
-   * @param keysNodesEntriesOrRaws - Initial entries
-   * @param options - Configuration options
+   * @param keysNodesEntriesOrRaws - Initial entries, or raw elements if `toEntryFn` is provided.
+   * @param options - Configuration options including optional `toEntryFn` to transform raw elements.
    * @remarks Time O(m log m), Space O(m) where m is the number of initial entries
+   * @example
+   * // Standard usage with entries
+   * const mmap = new TreeMultiMap([['a', ['x', 'y']], ['b', ['z']]]);
+   *
+   * // Using toEntryFn to transform raw objects
+   * const players = [{ score: 100, items: ['sword'] }, { score: 200, items: ['shield', 'bow'] }];
+   * const mmap = new TreeMultiMap(players, { toEntryFn: p => [p.score, p.items] });
    */
   constructor(keysNodesEntriesOrRaws = [], options = {}) {
     __privateAdd(this, _core2);
@@ -12181,9 +12201,20 @@ var _TreeMultiMap = class _TreeMultiMap {
     var _a;
     const comparator = (_a = options.comparator) != null ? _a : TreeSet.createDefaultComparator();
     __privateSet(this, _isDefaultComparator2, options.comparator === void 0);
+    const toEntryFn = options.toEntryFn;
     __privateSet(this, _core2, new RedBlackTree([], { ...options, comparator, isMapMode: options.isMapMode }));
     for (const x of keysNodesEntriesOrRaws) {
       if (x === null || x === void 0) continue;
+      if (toEntryFn) {
+        const [k, bucket] = toEntryFn(x);
+        if (k === null || k === void 0) continue;
+        if (bucket !== void 0) {
+          __privateGet(this, _core2).set(k, Array.isArray(bucket) ? [...bucket] : [bucket]);
+        } else {
+          __privateGet(this, _core2).set(k, []);
+        }
+        continue;
+      }
       if (Array.isArray(x)) {
         const [k, bucket] = x;
         if (k === null || k === void 0) continue;
@@ -12519,8 +12550,8 @@ var _TreeMultiMap = class _TreeMultiMap {
    * Prints the internal tree structure (for debugging).
    * @remarks Time O(n), Space O(n)
    */
-  print(...args) {
-    return __privateGet(this, _core2).print(...args);
+  print() {
+    __privateGet(this, _core2).print();
   }
   /**
    * Executes a callback for each entry.
@@ -12571,7 +12602,7 @@ var _TreeMultiMap = class _TreeMultiMap {
   setMany(keysNodesEntriesOrRaws) {
     const results = [];
     for (const x of keysNodesEntriesOrRaws) {
-      results.push(this.set(x, void 0));
+      results.push(this.set(x));
     }
     return results;
   }
@@ -12579,22 +12610,22 @@ var _TreeMultiMap = class _TreeMultiMap {
    * Searches for entries within a key range.
    * @remarks Time O(log n + k), Space O(k) where k is result size
    */
-  rangeSearch(range, callback, isBalanced) {
-    return __privateGet(this, _core2).rangeSearch(range, callback, isBalanced);
+  rangeSearch(range, callback) {
+    return __privateGet(this, _core2).rangeSearch(range, callback);
   }
   /**
    * Creates a shallow clone of this map.
    * @remarks Time O(n log n), Space O(n)
    */
   clone() {
-    return new _TreeMultiMap(this, { comparator: this.comparator, isMapMode: __privateGet(this, _core2)._isMapMode });
+    return new _TreeMultiMap(this, { comparator: this.comparator, isMapMode: __privateGet(this, _core2).isMapMode });
   }
   /**
    * Expose comparator for advanced usage/testing (read-only).
    * @remarks Time O(1), Space O(1)
    */
   get comparator() {
-    return __privateGet(this, _core2)._comparator;
+    return __privateGet(this, _core2).comparator;
   }
 };
 _core2 = new WeakMap();
@@ -12606,10 +12637,19 @@ var TreeMultiMap = _TreeMultiMap;
 var _core3, _isDefaultComparator3, _userComparator2;
 var _TreeMap = class _TreeMap {
   /**
-   * Create a TreeMap from an iterable of `[key, value]` entries.
+   * Create a TreeMap from an iterable of `[key, value]` entries or raw elements.
+   *
+   * @param entries - Iterable of `[key, value]` tuples, or raw elements if `toEntryFn` is provided.
+   * @param options - Configuration options including optional `toEntryFn` to transform raw elements.
+   * @throws {TypeError} If any entry is not a 2-tuple-like value (when no toEntryFn), or when using
+   * the default comparator and encountering unsupported/invalid keys (e.g. `NaN`, invalid `Date`).
+   * @example
+   * // Standard usage with entries
+   * const map = new TreeMap([['a', 1], ['b', 2]]);
    *
-   * @throws {TypeError} If any entry is not a 2-tuple-like value, or when using the default comparator
-   * and encountering unsupported/invalid keys (e.g. `NaN`, invalid `Date`).
+   * // Using toEntryFn to transform raw objects
+   * const users = [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }];
+   * const map = new TreeMap<number, User, User>(users, { toEntryFn: u => [u.id, u] });
    */
   constructor(entries = [], options = {}) {
     __privateAdd(this, _core3);
@@ -12617,15 +12657,22 @@ var _TreeMap = class _TreeMap {
     __privateAdd(this, _userComparator2);
     var _a;
     __privateSet(this, _userComparator2, options.comparator);
+    const toEntryFn = options.toEntryFn;
     const comparator = (_a = options.comparator) != null ? _a : _TreeMap.createDefaultComparator();
     __privateSet(this, _isDefaultComparator3, options.comparator === void 0);
     __privateSet(this, _core3, new RedBlackTree([], { comparator, isMapMode: options.isMapMode }));
     for (const item of entries) {
-      if (!Array.isArray(item) || item.length < 2) {
-        throw new TypeError("TreeMap: each entry must be a [key, value] tuple");
+      let k;
+      let v;
+      if (toEntryFn) {
+        [k, v] = toEntryFn(item);
+      } else {
+        if (!Array.isArray(item) || item.length < 2) {
+          throw new TypeError("TreeMap: each entry must be a [key, value] tuple");
+        }
+        k = item[0];
+        v = item[1];
       }
-      const k = item[0];
-      const v = item[1];
       this.set(k, v);
     }
   }
@@ -12952,19 +12999,30 @@ var _TreeMultiSet = class _TreeMultiSet {
   // total occurrences (sumCounts)
   /**
    * Creates a new TreeMultiSet.
-   * @param elements - Initial elements to add
-   * @param options - Configuration options
+   * @param elements - Initial elements to add, or raw elements if `toElementFn` is provided.
+   * @param options - Configuration options including optional `toElementFn` to transform raw elements.
    * @remarks Time O(m log m), Space O(m) where m is the number of initial elements
+   * @example
+   * // Standard usage with elements
+   * const mset = new TreeMultiSet([1, 2, 2, 3]);
+   *
+   * // Using toElementFn to transform raw objects
+   * const items = [{ score: 100 }, { score: 200 }, { score: 100 }];
+   * const mset = new TreeMultiSet<number, Item>(items, { toElementFn: item => item.score });
    */
   constructor(elements = [], options = {}) {
     __privateAdd(this, _core4);
     __privateAdd(this, _isDefaultComparator4);
     __publicField(this, "_size", 0);
     var _a;
+    const toElementFn = options.toElementFn;
     const comparator = (_a = options.comparator) != null ? _a : TreeSet.createDefaultComparator();
     __privateSet(this, _isDefaultComparator4, options.comparator === void 0);
     __privateSet(this, _core4, new RedBlackTree([], { comparator, isMapMode: options.isMapMode }));
-    for (const k of elements) this.add(k);
+    for (const item of elements) {
+      const k = toElementFn ? toElementFn(item) : item;
+      this.add(k);
+    }
   }
   /**
    * Validates the key against the default comparator rules.
@@ -14303,20 +14361,17 @@ var _Trie = class _Trie extends IterableElementBase {
     prefix = this._caseProcess(prefix);
     const words = [];
     let found = 0;
-    function dfs(node, word) {
-      for (const char of node.children.keys()) {
-        const charNode = node.children.get(char);
-        if (charNode !== void 0) {
-          dfs(charNode, word.concat(char));
-        }
+    const dfs = /* @__PURE__ */ __name((node, word) => {
+      for (const [char, childNode] of node.children) {
+        if (found >= max) return;
+        dfs(childNode, word + char);
       }
       if (node.isEnd) {
-        if (found > max - 1) return;
+        if (found >= max) return;
         words.push(word);
         found++;
       }
-    }
-    __name(dfs, "dfs");
+    }, "dfs");
     let startNode = this.root;
     if (prefix) {
       for (const c of prefix) {

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

@@ -14,15 +14,24 @@ import type { TreeMapEntryCallback, TreeMapOptions, TreeMapRangeOptions, TreeMap
  * - Iteration order is ascending by key.
  * - No node exposure: all APIs use keys/values only.
  */
-export declare class TreeMap<K = any, V = any> implements Iterable<[K, V | undefined]> {
+export declare class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | undefined]> {
     #private;
     /**
-     * Create a TreeMap from an iterable of `[key, value]` entries.
+     * Create a TreeMap from an iterable of `[key, value]` entries or raw elements.
      *
-     * @throws {TypeError} If any entry is not a 2-tuple-like value, or when using the default comparator
-     * and encountering unsupported/invalid keys (e.g. `NaN`, invalid `Date`).
+     * @param entries - Iterable of `[key, value]` tuples, or raw elements if `toEntryFn` is provided.
+     * @param options - Configuration options including optional `toEntryFn` to transform raw elements.
+     * @throws {TypeError} If any entry is not a 2-tuple-like value (when no toEntryFn), or when using
+     * the default comparator and encountering unsupported/invalid keys (e.g. `NaN`, invalid `Date`).
+     * @example
+     * // Standard usage with entries
+     * const map = new TreeMap([['a', 1], ['b', 2]]);
+     *
+     * // Using toEntryFn to transform raw objects
+     * const users = [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }];
+     * const map = new TreeMap<number, User, User>(users, { toEntryFn: u => [u.id, u] });
      */
-    constructor(entries?: Iterable<[K, V | undefined]>, options?: TreeMapOptions<K>);
+    constructor(entries?: Iterable<R> | Iterable<[K, V | undefined]>, options?: TreeMapOptions<K, V, R>);
     /**
      * Create the strict default comparator.
      *
@@ -98,7 +107,9 @@ export declare class TreeMap<K = any, V = any> implements Iterable<[K, V | undef
      * This mirrors `RedBlackTree.map`: mapping produces a new ordered container.
      * @remarks Time O(n log n) expected, Space O(n)
      */
-    map<MK, MV>(callbackfn: TreeMapEntryCallback<K, V, [MK, MV], TreeMap<K, V>>, options?: TreeMapOptions<MK>, thisArg?: unknown): TreeMap<MK, MV>;
+    map<MK, MV>(callbackfn: TreeMapEntryCallback<K, V, [MK, MV], TreeMap<K, V>>, options?: Omit<TreeMapOptions<MK, MV>, 'toEntryFn'> & {
+        comparator?: (a: MK, b: MK) => number;
+    }, thisArg?: unknown): TreeMap<MK, MV>;
     /**
      * Create a new TreeMap containing only entries that satisfy the predicate.
      * @remarks Time O(n log n) expected, Space O(n)

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

@@ -6,6 +6,7 @@
  * @license MIT License
  */
 import type { Comparator, TreeMultiMapOptions } from '../../types';
+import { Range } from '../../common';
 import { RedBlackTreeNode } from './red-black-tree';
 /**
  * Node type used by TreeMultiMap (alias to RedBlackTreeNode for backward compatibility).
@@ -192,9 +193,16 @@ export declare class TreeMultiMap<K = any, V = any, R = any> implements Iterable
     #private;
     /**
      * Creates a new TreeMultiMap.
-     * @param keysNodesEntriesOrRaws - Initial entries
-     * @param options - Configuration options
+     * @param keysNodesEntriesOrRaws - Initial entries, or raw elements if `toEntryFn` is provided.
+     * @param options - Configuration options including optional `toEntryFn` to transform raw elements.
      * @remarks Time O(m log m), Space O(m) where m is the number of initial entries
+     * @example
+     * // Standard usage with entries
+     * const mmap = new TreeMultiMap([['a', ['x', 'y']], ['b', ['z']]]);
+     *
+     * // Using toEntryFn to transform raw objects
+     * const players = [{ score: 100, items: ['sword'] }, { score: 200, items: ['shield', 'bow'] }];
+     * const mmap = new TreeMultiMap(players, { toEntryFn: p => [p.score, p.items] });
      */
     constructor(keysNodesEntriesOrRaws?: Iterable<K | [K | null | undefined, V[] | undefined] | null | undefined | R>, options?: TreeMultiMapOptions<K, V[], R>);
     /**
@@ -372,7 +380,7 @@ export declare class TreeMultiMap<K = any, V = any, R = any> implements Iterable
      * Prints the internal tree structure (for debugging).
      * @remarks Time O(n), Space O(n)
      */
-    print(...args: any[]): void;
+    print(): void;
     /**
      * Executes a callback for each entry.
      * @remarks Time O(n), Space O(1)
@@ -397,12 +405,12 @@ export declare class TreeMultiMap<K = any, V = any, R = any> implements Iterable
      * Sets multiple entries at once.
      * @remarks Time O(m log n), Space O(m) where m is input size
      */
-    setMany(keysNodesEntriesOrRaws: Iterable<any>): boolean[];
+    setMany(keysNodesEntriesOrRaws: Iterable<K | [K | null | undefined, V[] | undefined]>): boolean[];
     /**
      * Searches for entries within a key range.
      * @remarks Time O(log n + k), Space O(k) where k is result size
      */
-    rangeSearch<C extends (node: RedBlackTreeNode<K, V[]>) => any>(range: any, callback?: C, isBalanced?: any): ReturnType<C>[];
+    rangeSearch<C extends (node: RedBlackTreeNode<K, V[]>) => unknown>(range: Range<K> | [K, K], callback?: C): ReturnType<C>[];
     /**
      * Creates a shallow clone of this map.
      * @remarks Time O(n log n), Space O(n)

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

@@ -8,16 +8,23 @@
  * - `delete(x)` removes one occurrence by default
  */
 import type { Comparator, TreeMultiSetOptions } from '../../types';
-export declare class TreeMultiSet<K = any> implements Iterable<K> {
+export declare class TreeMultiSet<K = any, R = K> implements Iterable<K> {
     #private;
     private _size;
     /**
      * Creates a new TreeMultiSet.
-     * @param elements - Initial elements to add
-     * @param options - Configuration options
+     * @param elements - Initial elements to add, or raw elements if `toElementFn` is provided.
+     * @param options - Configuration options including optional `toElementFn` to transform raw elements.
      * @remarks Time O(m log m), Space O(m) where m is the number of initial elements
-     */
-    constructor(elements?: Iterable<K>, options?: TreeMultiSetOptions<K>);
+     * @example
+     * // Standard usage with elements
+     * const mset = new TreeMultiSet([1, 2, 2, 3]);
+     *
+     * // Using toElementFn to transform raw objects
+     * const items = [{ score: 100 }, { score: 200 }, { score: 100 }];
+     * const mset = new TreeMultiSet<number, Item>(items, { toElementFn: item => item.score });
+     */
+    constructor(elements?: Iterable<R> | Iterable<K>, options?: TreeMultiSetOptions<K, R>);
     /**
      * Validates the key against the default comparator rules.
      * @remarks Time O(1), Space O(1)

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

@@ -14,15 +14,24 @@ import type { TreeSetElementCallback, TreeSetOptions, TreeSetRangeOptions, TreeS
  * - Iteration order is ascending by key.
  * - No node exposure: all APIs use keys only.
  */
-export declare class TreeSet<K = any> implements Iterable<K> {
+export declare class TreeSet<K = any, R = K> implements Iterable<K> {
     #private;
     /**
-     * Create a TreeSet from an iterable of keys.
+     * Create a TreeSet from an iterable of keys or raw elements.
      *
+     * @param elements - Iterable of keys, or raw elements if `toElementFn` is provided.
+     * @param options - Configuration options including optional `toElementFn` to transform raw elements.
      * @throws {TypeError} When using the default comparator and encountering unsupported key types,
      * or invalid keys (e.g. `NaN`, invalid `Date`).
+     * @example
+     * // Standard usage with keys
+     * const set = new TreeSet([3, 1, 2]);
+     *
+     * // Using toElementFn to transform raw objects
+     * const users = [{ id: 3, name: 'Alice' }, { id: 1, name: 'Bob' }];
+     * const set = new TreeSet<number, User>(users, { toElementFn: u => u.id });
      */
-    constructor(elements?: Iterable<K>, options?: TreeSetOptions<K>);
+    constructor(elements?: Iterable<R> | Iterable<K>, options?: TreeSetOptions<K, R>);
     /**
      * Create the strict default comparator.
      *
@@ -92,7 +101,9 @@ export declare class TreeSet<K = any> implements Iterable<K> {
      * This mirrors `RedBlackTree.map`: mapping produces a new ordered container.
      * @remarks Time O(n log n) expected, Space O(n)
      */
-    map<MK>(callbackfn: TreeSetElementCallback<K, MK, TreeSet<K>>, options?: TreeSetOptions<MK>, thisArg?: unknown): TreeSet<MK>;
+    map<MK>(callbackfn: TreeSetElementCallback<K, MK, TreeSet<K>>, options?: Omit<TreeSetOptions<MK>, 'toElementFn'> & {
+        comparator?: (a: MK, b: MK) => number;
+    }, thisArg?: unknown): TreeSet<MK>;
     /**
      * Create a new TreeSet containing only values that satisfy the predicate.
      * @remarks Time O(n log n) expected, Space O(n)

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

@@ -1,5 +1,5 @@
 import type { Comparator } from '../../common';
-export interface TreeMapOptions<K> {
+export interface TreeMapOptions<K, V, R = [K, V]> {
     comparator?: Comparator<K>;
     /**
      * Pass-through to the underlying RedBlackTree/BST `isMapMode` option.
@@ -8,6 +8,11 @@ export interface TreeMapOptions<K> {
      * - `false`: store values on tree nodes (Node Mode).
      */
     isMapMode?: boolean;
+    /**
+     * Transform raw elements into `[key, value]` entries.
+     * When provided, the constructor accepts `Iterable<R>` instead of `Iterable<[K, V]>`.
+     */
+    toEntryFn?: (rawElement: R) => [K, V];
 }
 export type TreeMapRangeOptions = {
     lowInclusive?: boolean;

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

@@ -1,5 +1,5 @@
 import type { Comparator } from '../../common';
-export interface TreeMultiSetOptions<K> {
+export interface TreeMultiSetOptions<K, R = K> {
     comparator?: Comparator<K>;
     /**
      * Pass-through to the underlying RedBlackTree/BST `isMapMode` option.
@@ -8,4 +8,9 @@ export interface TreeMultiSetOptions<K> {
      * - `false`: Node Mode.
      */
     isMapMode?: boolean;
+    /**
+     * Transform raw elements into keys.
+     * When provided, the constructor accepts `Iterable<R>` instead of `Iterable<K>`.
+     */
+    toElementFn?: (rawElement: R) => K;
 }