data-structure-typed 2.5.3 → 2.6.1

package/src/data-structures/hash/hash-map.ts

@@ -5,7 +5,6 @@
  * @copyright Copyright (c) 2022 Pablo Zeng <zrwusa@gmail.com>
  * @license MIT License
  */
-
 import type {
   EntryCallback,
   HashMapLinkedNode,
@@ -82,19 +81,28 @@ import { ERR, raise } from '../../common';
  *     console.log(activeCount); // 2;
  * @example
  * // Aggregate values
- *  const counts = new HashMap<string, number>([['a', 5], ['b', 3], ['c', 8]]);
+ *  const counts = new HashMap<string, number>([
+ *       ['a', 5],
+ *       ['b', 3],
+ *       ['c', 8]
+ *     ]);
  *
  *     const total = counts.reduce((sum, v) => sum + (v ?? 0), 0);
  *     console.log(total); // 16;
  * @example
  * // Iterate over entries
- *  const map = new HashMap<string, number>([['x', 1], ['y', 2]]);
+ *  const map = new HashMap<string, number>([
+ *       ['x', 1],
+ *       ['y', 2]
+ *     ]);
  *     const keys: string[] = [];
  *
  *     map.forEach((v, k) => keys.push(k));
  *     console.log(keys.sort()); // ['x', 'y'];
  */
 export class HashMap<K = any, V = any, R = [K, V]> extends IterableEntryBase<K, V> {
+  protected readonly _toEntryFn?: (rawElement: R) => [K, V];
+
   /**
    * Create a HashMap and optionally bulk-insert entries.
    * @remarks Time O(N), Space O(N)
@@ -134,8 +142,6 @@ export class HashMap<K = any, V = any, R = [K, V]> extends IterableEntryBase<K,
     return this._objMap;
   }
 
-  protected readonly _toEntryFn?: (rawElement: R) => [K, V];
-
   /**
    * Get the raw→entry converter function if present.
    * @remarks Time O(1), Space O(1)
@@ -171,47 +177,10 @@ export class HashMap<K = any, V = any, R = [K, V]> extends IterableEntryBase<K,
    * Check whether the map is empty.
    * @remarks Time O(1), Space O(1)
    * @returns True if size is 0.
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Check if empty
- *  const map = new HashMap();
- *     console.log(map.isEmpty()); // true;
+   * @example
+   * // Check if empty
+   *  const map = new HashMap();
+   *     console.log(map.isEmpty()); // true;
    */
   isEmpty(): boolean {
     return this._size === 0;
@@ -221,48 +190,14 @@ export class HashMap<K = any, V = any, R = [K, V]> extends IterableEntryBase<K,
    * Remove all entries and reset counters.
    * @remarks Time O(N), Space O(1)
    * @returns void
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Remove all entries
- *  const map = new HashMap<string, number>([['a', 1], ['b', 2]]);
- *     map.clear();
- *     console.log(map.isEmpty()); // true;
+   * @example
+   * // Remove all entries
+   *  const map = new HashMap<string, number>([
+   *       ['a', 1],
+   *       ['b', 2]
+   *     ]);
+   *     map.clear();
+   *     console.log(map.isEmpty()); // true;
    */
   clear(): void {
     this._store = {};
@@ -285,102 +220,24 @@ export class HashMap<K = any, V = any, R = [K, V]> extends IterableEntryBase<K,
    * @param key - Key.
    * @param value - Value.
    * @returns True when the operation succeeds.
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // basic HashMap creation and set operation
- *  // Create a simple HashMap with key-value pairs
- *     const map = new HashMap<number, string>([
- *       [1, 'one'],
- *       [2, 'two'],
- *       [3, 'three']
- *     ]);
- *
- *     // Verify size
- *     console.log(map.size); // 3;
- *
- *     // Set a new key-value pair
- *     map.set(4, 'four');
- *     console.log(map.size); // 4;
- *
- *     // Verify entries
- *     console.log([...map.entries()]); // length: 4;
+   * @example
+   * // basic HashMap creation and set operation
+   *  // Create a simple HashMap with key-value pairs
+   *     const map = new HashMap<number, string>([
+   *       [1, 'one'],
+   *       [2, 'two'],
+   *       [3, 'three']
+   *     ]);
+   *
+   *     // Verify size
+   *     console.log(map.size); // 3;
+   *
+   *     // Set a new key-value pair
+   *     map.set(4, 'four');
+   *     console.log(map.size); // 4;
+   *
+   *     // Verify entries
+   *     console.log([...map.entries()]); // length: 4;
    */
   set(key: K, value: V): this {
     if (this._isObjKey(key)) {
@@ -399,48 +256,15 @@ export class HashMap<K = any, V = any, R = [K, V]> extends IterableEntryBase<K,
    * @remarks Time O(N), Space O(N)
    * @param entryOrRawElements - Iterable of entries or raw elements to insert.
    * @returns Array of per-entry results.
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Add multiple entries
- *  const map = new HashMap<string, number>();
- *     map.setMany([['a', 1], ['b', 2], ['c', 3]]);
- *     console.log(map.size); // 3;
+   * @example
+   * // Add multiple entries
+   *  const map = new HashMap<string, number>();
+   *     map.setMany([
+   *       ['a', 1],
+   *       ['b', 2],
+   *       ['c', 3]
+   *     ]);
+   *     console.log(map.size); // 3;
    */
   setMany(entryOrRawElements: Iterable<R | [K, V]>): boolean[] {
     const results: boolean[] = [];
@@ -462,66 +286,27 @@ export class HashMap<K = any, V = any, R = [K, V]> extends IterableEntryBase<K,
    * @remarks Time O(1), Space O(1)
    * @param key - Key to look up.
    * @returns Value or undefined.
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // HashMap get and has operations
- *  const map = new HashMap<string, number>([
- *       ['apple', 1],
- *       ['banana', 2],
- *       ['cherry', 3]
- *     ]);
- *
- *     // Check if key exists
- *     console.log(map.has('apple')); // true;
- *     console.log(map.has('date')); // false;
- *
- *     // Get value by key
- *     console.log(map.get('banana')); // 2;
- *     console.log(map.get('grape')); // undefined;
- *
- *     // Get all keys and values
- *     const keys = [...map.keys()];
- *     const values = [...map.values()];
- *     console.log(keys); // contains 'apple';
- *     console.log(values); // contains 3;
+   * @example
+   * // HashMap get and has operations
+   *  const map = new HashMap<string, number>([
+   *       ['apple', 1],
+   *       ['banana', 2],
+   *       ['cherry', 3]
+   *     ]);
+   *
+   *     // Check if key exists
+   *     console.log(map.has('apple')); // true;
+   *     console.log(map.has('date')); // false;
+   *
+   *     // Get value by key
+   *     console.log(map.get('banana')); // 2;
+   *     console.log(map.get('grape')); // undefined;
+   *
+   *     // Get all keys and values
+   *     const keys = [...map.keys()];
+   *     const values = [...map.values()];
+   *     console.log(keys); // contains 'apple';
+   *     console.log(values); // contains 3;
    */
   override get(key: K): V | undefined {
     if (this._isObjKey(key)) return this.objMap.get(key);
@@ -534,51 +319,15 @@ export class HashMap<K = any, V = any, R = [K, V]> extends IterableEntryBase<K,
    * @remarks Time O(1), Space O(1)
    * @param key - Key to test.
    * @returns True if present.
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Check key existence
- *  const map = new HashMap<string, number>([['a', 1], ['b', 2]]);
- *
- *     console.log(map.has('a')); // true;
- *     console.log(map.has('z')); // false;
+   * @example
+   * // Check key existence
+   *  const map = new HashMap<string, number>([
+   *       ['a', 1],
+   *       ['b', 2]
+   *     ]);
+   *
+   *     console.log(map.has('a')); // true;
+   *     console.log(map.has('z')); // false;
    */
   override has(key: K): boolean {
     if (this._isObjKey(key)) return this.objMap.has(key);
@@ -591,52 +340,17 @@ export class HashMap<K = any, V = any, R = [K, V]> extends IterableEntryBase<K,
    * @remarks Time O(1), Space O(1)
    * @param key - Key to delete.
    * @returns True if the key was found and removed.
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Remove entries by key
- *  const map = new HashMap<string, number>([['x', 10], ['y', 20], ['z', 30]]);
- *
- *     console.log(map.delete('y')); // true;
- *     console.log(map.has('y')); // false;
- *     console.log(map.size); // 2;
+   * @example
+   * // Remove entries by key
+   *  const map = new HashMap<string, number>([
+   *       ['x', 10],
+   *       ['y', 20],
+   *       ['z', 30]
+   *     ]);
+   *
+   *     console.log(map.delete('y')); // true;
+   *     console.log(map.has('y')); // false;
+   *     console.log(map.size); // 2;
    */
   delete(key: K): boolean {
     if (this._isObjKey(key)) {
@@ -669,49 +383,12 @@ export class HashMap<K = any, V = any, R = [K, V]> extends IterableEntryBase<K,
    * Deep clone this map, preserving hashing behavior.
    * @remarks Time O(N), Space O(N)
    * @returns A new map with the same content.
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Create independent copy
- *  const map = new HashMap<string, number>([['a', 1]]);
- *     const copy = map.clone();
- *     copy.set('a', 99);
- *     console.log(map.get('a')); // 1;
+   * @example
+   * // Create independent copy
+   *  const map = new HashMap<string, number>([['a', 1]]);
+   *     const copy = map.clone();
+   *     copy.set('a', 99);
+   *     console.log(map.get('a')); // 1;
    */
   clone(): this {
     const opts = { hashFn: this._hashFn, toEntryFn: this._toEntryFn };
@@ -725,52 +402,16 @@ export class HashMap<K = any, V = any, R = [K, V]> extends IterableEntryBase<K,
    * @param callbackfn - Mapping function (key, value, index, map) → newValue.
    * @param [thisArg] - Value for `this` inside the callback.
    * @returns A new map with transformed values.
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Transform all values
- *  const prices = new HashMap<string, number>([['apple', 1], ['banana', 2]]);
- *
- *     const doubled = prices.map(v => (v ?? 0) * 2);
- *     console.log(doubled.get('apple')); // 2;
- *     console.log(doubled.get('banana')); // 4;
+   * @example
+   * // Transform all values
+   *  const prices = new HashMap<string, number>([
+   *       ['apple', 1],
+   *       ['banana', 2]
+   *     ]);
+   *
+   *     const doubled = prices.map(v => (v ?? 0) * 2);
+   *     console.log(doubled.get('apple')); // 2;
+   *     console.log(doubled.get('banana')); // 4;
    */
   map<VM>(callbackfn: EntryCallback<K, V, VM>, thisArg?: unknown): HashMap<K, VM> {
     const out = this._createLike<K, VM, [K, VM]>() as unknown as HashMap<K, VM>;
@@ -785,72 +426,32 @@ export class HashMap<K = any, V = any, R = [K, V]> extends IterableEntryBase<K,
    * @param predicate - Predicate (key, value, index, map) → boolean.
    * @param [thisArg] - Value for `this` inside the predicate.
    * @returns A new map containing entries that satisfied the predicate.
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // HashMap iteration and filter operations
- *  const map = new HashMap<number, string>([
- *       [1, 'Alice'],
- *       [2, 'Bob'],
- *       [3, 'Charlie'],
- *       [4, 'Diana'],
- *       [5, 'Eve']
- *     ]);
- *
- *     // Iterate through entries
- *     const entries: [number, string][] = [];
- *     for (const [key, value] of map) {
- *       entries.push([key, value]);
- *     }
- *     console.log(entries); // length: 5;
- *
- *     // Filter operation (for iteration with collection methods)
- *     const filtered = [...map].filter(([key]) => key > 2);
- *     console.log(filtered.length); // 3;
- *
- *     // Map operation
- *     const values = [...map.values()].map(v => v.length);
- *     console.log(values); // contains 3; // 'Bob', 'Eve'
- *     console.log(values); // contains 7;
+   * @example
+   * // HashMap iteration and filter operations
+   *  const map = new HashMap<number, string>([
+   *       [1, 'Alice'],
+   *       [2, 'Bob'],
+   *       [3, 'Charlie'],
+   *       [4, 'Diana'],
+   *       [5, 'Eve']
+   *     ]);
+   *
+   *     // Iterate through entries
+   *     const entries: [number, string][] = [];
+   *     for (const [key, value] of map) {
+   *       entries.push([key, value]);
+   *     }
+   *     console.log(entries); // length: 5;
+   *
+   *     // Filter operation (for iteration with collection methods)
+   *     const filtered = [...map].filter(([key]) => key > 2);
+   *     console.log(filtered.length); // 3;
+   *
+   *     // Map operation
+   *     const values = [...map.values()].map(v => v.length);
+   *     console.log(values); // contains 3; // 'Bob', 'Eve'
+   *     console.log(values); // contains 7;
    */
-
   filter(predicate: EntryCallback<K, V, boolean>, thisArg?: unknown): this {
     const out = this._createLike<K, V, [K, V]>();
     let index = 0;
@@ -868,7 +469,10 @@ export class HashMap<K = any, V = any, R = [K, V]> extends IterableEntryBase<K,
    * @param [options] - Options forwarded to the constructor.
    * @returns A like-kind map instance.
    */
-  protected _createLike<TK = K, TV = V, TR = [TK, TV]>(entries: Iterable<[TK, TV] | TR> = [], options?: Record<string, unknown>): this {
+  protected _createLike<TK = K, TV = V, TR = [TK, TV]>(
+    entries: Iterable<[TK, TV] | TR> = [],
+    options?: Record<string, unknown>
+  ): this {
     const Ctor = this.constructor as new (e?: Iterable<[TK, TV] | TR>, o?: Record<string, unknown>) => this;
     return new Ctor(entries, options);
   }
@@ -894,7 +498,6 @@ export class HashMap<K = any, V = any, R = [K, V]> extends IterableEntryBase<K,
 
   protected _getNoObjKey(key: K): string {
     const keyType = typeof key;
-
     let strKey: string;
     if (keyType !== 'string' && keyType !== 'number' && keyType !== 'symbol') {
       strKey = this._hashFn(key);
@@ -931,14 +534,12 @@ export class LinkedHashMap<K = any, V = any, R = [K, V]> extends IterableEntryBa
     super();
     this._sentinel = <HashMapLinkedNode<K, V>>{};
     this._sentinel.prev = this._sentinel.next = this._head = this._tail = this._sentinel;
-
     if (options) {
       const { hashFn, objHashFn, toEntryFn } = options;
       if (hashFn) this._hashFn = hashFn;
       if (objHashFn) this._objHashFn = objHashFn;
       if (toEntryFn) this._toEntryFn = toEntryFn;
     }
-
     if (entryOrRawElements) this.setMany(entryOrRawElements);
   }
 
@@ -996,18 +597,12 @@ export class LinkedHashMap<K = any, V = any, R = [K, V]> extends IterableEntryBa
     return this._tail;
   }
 
-  protected readonly _toEntryFn?: (rawElement: R) => [K, V] = (rawElement: R) => {
-    if (this.isEntry(rawElement)) {
-      return rawElement;
-    }
-    raise(TypeError, ERR.invalidArgument('If elements do not adhere to [key, value], provide options.toEntryFn to transform raw records.', 'HashMap'));
-  };
-
   get toEntryFn() {
     return this._toEntryFn;
   }
 
   protected _size = 0;
+
   get size() {
     return this._size;
   }
@@ -1068,7 +663,6 @@ export class LinkedHashMap<K = any, V = any, R = [K, V]> extends IterableEntryBa
   set(key: K, value?: V): this {
     let node: HashMapLinkedNode<K, V | undefined> | undefined;
     const isNewKey = !this.has(key);
-
     if (isWeakKey(key)) {
       const hash = this._objHashFn(key);
       node = this.objMap.get(hash);
@@ -1087,7 +681,6 @@ export class LinkedHashMap<K = any, V = any, R = [K, V]> extends IterableEntryBa
         node.value = value;
       }
     }
-
     if (node && isNewKey) {
       if (this._size === 0) {
         this._head = node;
@@ -1100,7 +693,6 @@ export class LinkedHashMap<K = any, V = any, R = [K, V]> extends IterableEntryBa
       this._sentinel.prev = node;
       this._size++;
     }
-
     return this;
   }
 
@@ -1259,6 +851,19 @@ export class LinkedHashMap<K = any, V = any, R = [K, V]> extends IterableEntryBa
     return out;
   }
 
+  protected readonly _toEntryFn?: (rawElement: R) => [K, V] = (rawElement: R) => {
+    if (this.isEntry(rawElement)) {
+      return rawElement;
+    }
+    raise(
+      TypeError,
+      ERR.invalidArgument(
+        'If elements do not adhere to [key, value], provide options.toEntryFn to transform raw records.',
+        'HashMap'
+      )
+    );
+  };
+
   protected *_getIterator(): IterableIterator<[K, V]> {
     let node = this.head;
     while (node !== this._sentinel) {
@@ -1276,20 +881,20 @@ export class LinkedHashMap<K = any, V = any, R = [K, V]> extends IterableEntryBa
       const hash = this._hashFn(key as K);
       delete this._noObjMap[hash];
     }
-
     // Remove from linked list
     const { prev, next } = node;
     prev.next = next;
     next.prev = prev;
-
     if (node === this.head) this._head = next;
     if (node === this.tail) this._tail = prev;
-
     this._size -= 1;
     return true;
   }
 
-  protected _createLike<TK = K, TV = V, TR = [TK, TV]>(entries: Iterable<[TK, TV] | TR> = [], options?: Record<string, unknown>): this {
+  protected _createLike<TK = K, TV = V, TR = [TK, TV]>(
+    entries: Iterable<[TK, TV] | TR> = [],
+    options?: Record<string, unknown>
+  ): this {
     const Ctor = this.constructor as new (e?: Iterable<[TK, TV] | TR>, o?: Record<string, unknown>) => this;
     return new Ctor(entries, options);
   }