data-structure-typed 2.4.0 → 2.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "data-structure-typed",
-  "version": "2.4.0",
+  "version": "2.4.1",
   "description": "Standard data structure",
   "browser": "dist/umd/data-structure-typed.min.js",
   "umd:main": "dist/umd/data-structure-typed.min.js",
@@ -104,7 +104,7 @@
     "benchmark": "^2.1.4",
     "binary-tree-typed": "^1.54.3",
     "bst-typed": "^1.54.3",
-    "data-structure-typed": "^2.3.0",
+    "data-structure-typed": "^2.4.0",
     "dependency-cruiser": "^16.5.0",
     "doctoc": "^2.2.1",
     "eslint": "^9.13.0",
@@ -135,6 +135,10 @@
     "binary search tree",
     "AVL tree",
     "red black tree",
+    "tree map",
+    "tree set",
+    "tree multi map",
+    "tree multi set",
     "balanced tree",
     "binary tree",
     "BST",

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

@@ -17,31 +17,53 @@ import { RedBlackTree } from './red-black-tree';
  * - Iteration order is ascending by key.
  * - No node exposure: all APIs use keys/values only.
  */
-export class TreeMap<K = any, V = any> implements Iterable<[K, V | undefined]> {
+export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | undefined]> {
   readonly #core: RedBlackTree<K, V>;
   readonly #isDefaultComparator: boolean;
   readonly #userComparator?: Comparator<K>;
 
   /**
-   * 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> = {}
+  ) {
     this.#userComparator = options.comparator;
+    const toEntryFn = options.toEntryFn;
     const comparator = options.comparator ?? TreeMap.createDefaultComparator<K>();
     this.#isDefaultComparator = options.comparator === undefined;
 
     this.#core = new RedBlackTree<K, V>([], { comparator, isMapMode: options.isMapMode });
 
-    // Validate entries like native Map: each item must be a 2-tuple-like value.
-    for (const item of entries as unknown as Iterable<unknown>) {
-      if (!Array.isArray(item) || item.length < 2) {
-        throw new TypeError('TreeMap: each entry must be a [key, value] tuple');
+    for (const item of entries) {
+      let k: K;
+      let v: V | undefined;
+
+      if (toEntryFn) {
+        // Use toEntryFn to transform raw element
+        [k, v] = toEntryFn(item as R);
+      } else {
+        // Validate entries like native Map: each item must be a 2-tuple-like value.
+        if (!Array.isArray(item) || item.length < 2) {
+          throw new TypeError('TreeMap: each entry must be a [key, value] tuple');
+        }
+        k = item[0] as K;
+        v = item[1] as V | undefined;
       }
-      const k = item[0] as K;
-      const v = item[1] as V | undefined;
+
       this.set(k, v);
     }
   }
@@ -210,10 +232,10 @@ export class TreeMap<K = any, V = any> implements Iterable<[K, V | undefined]> {
    */
   map<MK, MV>(
     callbackfn: TreeMapEntryCallback<K, V, [MK, MV], TreeMap<K, V>>,
-    options: TreeMapOptions<MK> = {},
+    options: Omit<TreeMapOptions<MK, MV>, 'toEntryFn'> & { comparator?: (a: MK, b: MK) => number } = {},
     thisArg?: unknown
   ): TreeMap<MK, MV> {
-    const out = new TreeMap<MK, MV>([], options);
+    const out = new TreeMap<MK, MV>([], options as TreeMapOptions<MK, MV>);
     let index = 0;
     for (const [k, v] of this) {
       const [mk, mv] = thisArg === undefined

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

@@ -7,6 +7,7 @@
  */
 
 import type { Comparator, TreeMultiMapOptions } from '../../types';
+import { Range } from '../../common';
 import { RedBlackTree, RedBlackTreeNode } from './red-black-tree';
 import { TreeSet } from './tree-set';
 
@@ -200,20 +201,41 @@ export class TreeMultiMap<K = any, V = any, R = any> implements Iterable<[K, V[]
 
   /**
    * 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> = {} as any
+    options: TreeMultiMapOptions<K, V[], R> = {}
   ) {
-    const comparator = (options as any).comparator ?? TreeSet.createDefaultComparator<K>();
-    this.#isDefaultComparator = (options as any).comparator === undefined;
-    this.#core = new RedBlackTree<K, V[], R>([], { ...(options as any), comparator, isMapMode: (options as any).isMapMode });
+    const comparator = options.comparator ?? TreeSet.createDefaultComparator<K>();
+    this.#isDefaultComparator = options.comparator === undefined;
+    const toEntryFn = options.toEntryFn;
+    this.#core = new RedBlackTree<K, V[], R>([], { ...options, comparator, isMapMode: options.isMapMode });
 
-    for (const x of keysNodesEntriesOrRaws as any) {
+    for (const x of keysNodesEntriesOrRaws) {
       if (x === null || x === undefined) continue;
+
+      // If toEntryFn is provided, use it to transform raw element
+      if (toEntryFn) {
+        const [k, bucket] = toEntryFn(x as R);
+        if (k === null || k === undefined) continue;
+        if (bucket !== undefined) {
+          this.#core.set(k as K, Array.isArray(bucket) ? [...bucket] : [bucket] as V[]);
+        } else {
+          this.#core.set(k as K, [] as V[]);
+        }
+        continue;
+      }
+
       if (Array.isArray(x)) {
         const [k, bucket] = x;
         if (k === null || k === undefined) continue;
@@ -596,8 +618,8 @@ export class TreeMultiMap<K = any, V = any, R = any> implements Iterable<[K, V[]
    * Prints the internal tree structure (for debugging).
    * @remarks Time O(n), Space O(n)
    */
-  print(...args: any[]): void {
-    return (this.#core as any).print(...args);
+  print(): void {
+    this.#core.print();
   }
 
   /**
@@ -619,7 +641,7 @@ export class TreeMultiMap<K = any, V = any, R = any> implements Iterable<[K, V[]
     for (const [k, v] of this) {
       if (predicate(v, k, this)) filtered.push([k, v]);
     }
-    return new TreeMultiMap<K, V, R>(filtered, { comparator: this.comparator as any });
+    return new TreeMultiMap<K, V, R>(filtered, { comparator: this.comparator });
   }
 
   /**
@@ -633,7 +655,7 @@ export class TreeMultiMap<K = any, V = any, R = any> implements Iterable<[K, V[]
     for (const [k, v] of this) {
       mapped.push(mapper(v, k, this));
     }
-    return new TreeMultiMap<K, V2, R>(mapped, { comparator: this.comparator as any });
+    return new TreeMultiMap<K, V2, R>(mapped, { comparator: this.comparator });
   }
 
   /**
@@ -652,11 +674,11 @@ export class TreeMultiMap<K = any, V = any, R = any> implements Iterable<[K, V[]
    * 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[] {
     const results: boolean[] = [];
     for (const x of keysNodesEntriesOrRaws) {
       // Call implementation directly: entry can be K or [K, V[]] or [K, undefined]
-      results.push(this.set(x as any, undefined as any));
+      results.push(this.set(x));
     }
     return results;
   }
@@ -665,12 +687,11 @@ export class TreeMultiMap<K = any, V = any, R = any> implements Iterable<[K, V[]
    * 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
+  rangeSearch<C extends (node: RedBlackTreeNode<K, V[]>) => unknown>(
+    range: Range<K> | [K, K],
+    callback?: C
   ): ReturnType<C>[] {
-    return this.#core.rangeSearch(range, callback as any, isBalanced);
+    return this.#core.rangeSearch(range, callback as (node: RedBlackTreeNode<K, V[]>) => ReturnType<C>);
   }
 
   /**
@@ -678,7 +699,7 @@ export class TreeMultiMap<K = any, V = any, R = any> implements Iterable<[K, V[]
    * @remarks Time O(n log n), Space O(n)
    */
   clone(): TreeMultiMap<K, V, R> {
-    return new TreeMultiMap<K, V, R>(this, { comparator: this.comparator as any, isMapMode: (this.#core as any)._isMapMode });
+    return new TreeMultiMap<K, V, R>(this, { comparator: this.comparator, isMapMode: this.#core.isMapMode });
   }
 
   /**
@@ -686,6 +707,6 @@ export class TreeMultiMap<K = any, V = any, R = any> implements Iterable<[K, V[]
    * @remarks Time O(1), Space O(1)
    */
   get comparator(): Comparator<K> {
-    return (this.#core as any)._comparator;
+    return this.#core.comparator;
   }
 }

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

@@ -12,23 +12,34 @@ import type { Comparator, TreeMultiSetOptions } from '../../types';
 import { RedBlackTree } from './red-black-tree';
 import { TreeSet } from './tree-set';
 
-export class TreeMultiSet<K = any> implements Iterable<K> {
+export class TreeMultiSet<K = any, R = K> implements Iterable<K> {
   readonly #core: RedBlackTree<K, number>;
   readonly #isDefaultComparator: boolean;
   private _size = 0; // 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
-   */
-  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> = {}) {
+    const toElementFn = options.toElementFn;
     const comparator = options.comparator ?? TreeSet.createDefaultComparator<K>();
     this.#isDefaultComparator = options.comparator === undefined;
     this.#core = new RedBlackTree<K, number>([], { comparator, isMapMode: options.isMapMode });
 
-    for (const k of elements) this.add(k);
+    for (const item of elements) {
+      const k = toElementFn ? toElementFn(item as R) : (item as K);
+      this.add(k);
+    }
   }
 
   /**

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

@@ -17,26 +17,39 @@ import { RedBlackTree } from './red-black-tree';
  * - Iteration order is ascending by key.
  * - No node exposure: all APIs use keys only.
  */
-export class TreeSet<K = any> implements Iterable<K> {
+export class TreeSet<K = any, R = K> implements Iterable<K> {
   readonly #core: RedBlackTree<K, undefined>;
   readonly #isDefaultComparator: boolean;
   readonly #userComparator?: Comparator<K>;
 
   /**
-   * 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> = {}) {
     this.#userComparator = options.comparator;
+    const toElementFn = options.toElementFn;
     const comparator = options.comparator ?? TreeSet.createDefaultComparator<K>();
     this.#isDefaultComparator = options.comparator === undefined;
 
     // RedBlackTree expects an iterable of keys/entries/nodes/raws; for TreeSet we only accept keys.
     this.#core = new RedBlackTree<K, undefined>([], { comparator, isMapMode: options.isMapMode });
 
-    for (const k of elements) this.add(k);
+    for (const item of elements) {
+      const k = toElementFn ? toElementFn(item as R) : item as K;
+      this.add(k);
+    }
   }
 
   /**
@@ -194,10 +207,10 @@ export class TreeSet<K = any> implements Iterable<K> {
    */
   map<MK>(
     callbackfn: TreeSetElementCallback<K, MK, TreeSet<K>>,
-    options: TreeSetOptions<MK> = {},
+    options: Omit<TreeSetOptions<MK>, 'toElementFn'> & { comparator?: (a: MK, b: MK) => number } = {},
     thisArg?: unknown
   ): TreeSet<MK> {
-    const out = new TreeSet<MK>([], options);
+    const out = new TreeSet<MK>([], options as TreeSetOptions<MK>);
     let index = 0;
     for (const v of this) {
       const mk = thisArg === undefined

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

@@ -1,6 +1,6 @@
 import type { Comparator } from '../../common';
 
-export interface TreeMapOptions<K> {
+export interface TreeMapOptions<K, V, R = [K, V]> {
   comparator?: Comparator<K>;
 
   /**
@@ -10,6 +10,12 @@ 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 = {

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

@@ -1,6 +1,6 @@
 import type { Comparator } from '../../common';
 
-export interface TreeMultiSetOptions<K> {
+export interface TreeMultiSetOptions<K, R = K> {
   comparator?: Comparator<K>;
 
   /**
@@ -10,4 +10,10 @@ 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;
 }

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

@@ -1,6 +1,6 @@
 import type { Comparator } from '../../common';
 
-export interface TreeSetOptions<K> {
+export interface TreeSetOptions<K, R = K> {
   comparator?: Comparator<K>;
 
   /**
@@ -10,6 +10,12 @@ export interface TreeSetOptions<K> {
    * - `false`: store values on tree nodes (Node Mode).
    */
   isMapMode?: boolean;
+
+  /**
+   * Transform raw elements into keys.
+   * When provided, the constructor accepts `Iterable<R>` instead of `Iterable<K>`.
+   */
+  toElementFn?: (rawElement: R) => K;
 }
 
 export type TreeSetRangeOptions = {