data-structure-typed 2.4.0 → 2.4.2

package/CHANGELOG.md

@@ -8,7 +8,7 @@ All notable changes to this project will be documented in this file.
 - [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
 - [`auto-changelog`](https://github.com/CookPete/auto-changelog)
 
-## [v2.4.0](https://github.com/zrwusa/data-structure-typed/compare/v2.2.3...main) (upcoming)
+## [v2.4.2](https://github.com/zrwusa/data-structure-typed/compare/v2.2.3...main) (upcoming)
 
 ## [v2.2.3](https://github.com/zrwusa/data-structure-typed/compare/v2.2.2...v2.2.3) (6 January 2026)
 

package/README.md

@@ -6,7 +6,6 @@ A comprehensive TypeScript data structures library with production-ready impleme
 
 ![npm](https://img.shields.io/npm/dm/data-structure-typed)
 ![GitHub contributors](https://img.shields.io/github/contributors/zrwusa/data-structure-typed)
-![GitHub top language](https://img.shields.io/github/languages/top/zrwusa/data-structure-typed)
 ![GITHUB Star](https://img.shields.io/github/stars/zrwusa/data-structure-typed)
 [![codecov](https://img.shields.io/codecov/c/github/zrwusa/data-structure-typed)](https://codecov.io/gh/zrwusa/data-structure-typed)
 ![eslint](https://aleen42.github.io/badges/src/eslint.svg)
@@ -93,7 +92,7 @@ for (let i = 0; i < 100000; i++) {
 
 - **Tree-shakable** ESM / CJS / legacy builds
 
-📊 [Full benchmarks →](./docs/PERFORMANCE.md)
+📊 [Full benchmarks →](./docs/benchmark.html)
 
 ---
 
@@ -469,7 +468,7 @@ class MessageQueue {
 ✅ **50+ code examples** (real-world patterns)  
 ✅ **Full TypeScript support** (strict typing)  
 ✅ **Performance benchmarks** (484x speedups)  
-✅ **Framework integrations** (React, Express, Nest.js)
+✅ **Framework integrations** (React, Express, Nest.js)  
 ✅ **6 core documentation files** (2500+ lines)
 
 ---

package/README_CN.md

@@ -6,7 +6,6 @@
 
 ![npm](https://img.shields.io/npm/dm/data-structure-typed)
 ![GitHub contributors](https://img.shields.io/github/contributors/zrwusa/data-structure-typed)
-![GitHub top language](https://img.shields.io/github/languages/top/zrwusa/data-structure-typed)
 ![GITHUB Star](https://img.shields.io/github/stars/zrwusa/data-structure-typed)
 [![codecov](https://img.shields.io/codecov/c/github/zrwusa/data-structure-typed)](https://codecov.io/gh/zrwusa/data-structure-typed)
 ![eslint](https://aleen42.github.io/badges/src/eslint.svg)

package/dist/cjs/index.cjs

@@ -11860,17 +11860,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.
@@ -12181,16 +12194,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;
@@ -12526,8 +12557,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.
@@ -12578,7 +12609,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;
   }
@@ -12586,22 +12617,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;
   }
 };
 
@@ -12614,22 +12645,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);
     }
   }
@@ -12955,15 +13002,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.
@@ -14301,20 +14359,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/cjs-legacy/index.cjs

@@ -11847,10 +11847,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);
@@ -11858,10 +11867,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.
@@ -12173,9 +12186,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);
@@ -12183,9 +12203,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;
@@ -12521,8 +12552,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.
@@ -12573,7 +12604,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;
   }
@@ -12581,22 +12612,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();
@@ -12608,10 +12639,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);
@@ -12619,15 +12659,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);
     }
   }
@@ -12954,19 +13001,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.
@@ -14305,20 +14363,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) {