max-priority-queue-typed 2.4.5 → 2.5.1

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

@@ -29,83 +29,6 @@ import { ERR } from '../../common';
  * If you try to insert another entry with the same key, the new one will replace the old entry.
  * 4. Unordered Collection: HashMap does not guarantee the order of entries, and the order may change over time.
  * @example
- * // should maintain insertion order
- *  const linkedHashMap = new LinkedHashMap<number, string>();
- *     linkedHashMap.set(1, 'A');
- *     linkedHashMap.set(2, 'B');
- *     linkedHashMap.set(3, 'C');
- *
- *     const result = Array.from(linkedHashMap);
- *     console.log(result); // [
- *  //      [1, 'A'],
- *  //      [2, 'B'],
- *  //      [3, 'C']
- *  //    ];
- * @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
- * // 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 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 for user session caching O(1) performance
  *  interface UserSession {
  *       userId: number;
@@ -157,6 +80,19 @@ import { ERR } from '../../common';
  *     // Get all active sessions
  *     const activeCount = [...sessionCache.values()].length;
  *     console.log(activeCount); // 2;
+ * @example
+ * // Aggregate values
+ *  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 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> {
   /**
@@ -235,6 +171,40 @@ 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;
    */
   isEmpty(): boolean {
     return this._size === 0;
@@ -244,6 +214,41 @@ 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;
    */
   clear(): void {
     this._store = {};
@@ -256,7 +261,7 @@ export class HashMap<K = any, V = any, R = [K, V]> extends IterableEntryBase<K,
    * @remarks Time O(1), Space O(1)
    * @returns True if the value is a 2-tuple.
    */
-  isEntry(rawElement: any): rawElement is [K, V] {
+  isEntry(rawElement: unknown): rawElement is [K, V] {
     return Array.isArray(rawElement) && rawElement.length === 2;
   }
 
@@ -266,6 +271,88 @@ 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;
    */
   set(key: K, value: V): boolean {
     if (this._isObjKey(key)) {
@@ -284,6 +371,41 @@ 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;
    */
   setMany(entryOrRawElements: Iterable<R | [K, V]>): boolean[] {
     const results: boolean[] = [];
@@ -301,6 +423,59 @@ 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;
    */
   override get(key: K): V | undefined {
     if (this._isObjKey(key)) return this.objMap.get(key);
@@ -313,6 +488,44 @@ 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;
    */
   override has(key: K): boolean {
     if (this._isObjKey(key)) return this.objMap.has(key);
@@ -325,6 +538,45 @@ 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;
    */
   delete(key: K): boolean {
     if (this._isObjKey(key)) {
@@ -357,6 +609,42 @@ 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;
    */
   clone(): this {
     const opts = { hashFn: this._hashFn, toEntryFn: this._toEntryFn };
@@ -370,9 +658,48 @@ 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;
    */
-  map<VM>(callbackfn: EntryCallback<K, V, VM>, thisArg?: any): any {
-    const out = this._createLike<K, VM, [K, VM]>();
+  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>;
     let index = 0;
     for (const [key, value] of this) out.set(key, callbackfn.call(thisArg, value, key, index++, this));
     return out;
@@ -384,9 +711,66 @@ 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;
    */
 
-  filter(predicate: EntryCallback<K, V, boolean>, thisArg?: any): any {
+  filter(predicate: EntryCallback<K, V, boolean>, thisArg?: unknown): any {
     const out = this._createLike<K, V, [K, V]>();
     let index = 0;
     for (const [key, value] of this) if (predicate.call(thisArg, value, key, index++, this)) out.set(key, value);
@@ -403,8 +787,8 @@ 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?: any): any {
-    const Ctor = this.constructor as new (e?: Iterable<[TK, TV] | TR>, o?: any) => any;
+  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);
   }
 
@@ -422,7 +806,7 @@ export class HashMap<K = any, V = any, R = [K, V]> extends IterableEntryBase<K,
     for (const node of this.objMap) yield node as [K, V];
   }
 
-  protected _isObjKey(key: any): key is object | ((...args: any[]) => any) {
+  protected _isObjKey(key: unknown): key is object | ((...args: unknown[]) => unknown) {
     const keyType = typeof key;
     return (keyType === 'object' || keyType === 'function') && key !== null;
   }
@@ -744,7 +1128,7 @@ export class LinkedHashMap<K = any, V = any, R = [K, V]> extends IterableEntryBa
     return this._size === 0;
   }
 
-  isEntry(rawElement: any): rawElement is [K, V] {
+  isEntry(rawElement: unknown): rawElement is [K, V] {
     return Array.isArray(rawElement) && rawElement.length === 2;
   }
 
@@ -754,12 +1138,12 @@ export class LinkedHashMap<K = any, V = any, R = [K, V]> extends IterableEntryBa
     this._head = this._tail = this._sentinel.prev = this._sentinel.next = this._sentinel;
   }
 
-  clone(): any {
+  clone(): this {
     const opts = { hashFn: this._hashFn, objHashFn: this._objHashFn };
-    return this._createLike<[K, V], [K, V], [K, V]>(this, opts);
+    return this._createLike<K, V, [K, V]>(this, opts);
   }
 
-  filter(predicate: EntryCallback<K, V, boolean>, thisArg?: any): any {
+  filter(predicate: EntryCallback<K, V, boolean>, thisArg?: unknown): this {
     const out = this._createLike<K, V, [K, V]>();
     let index = 0;
     for (const [key, value] of this) {
@@ -778,8 +1162,8 @@ export class LinkedHashMap<K = any, V = any, R = [K, V]> extends IterableEntryBa
    * @param [thisArg] - Value for `this` inside the callback.
    * @returns A new map of the same class with transformed entries.
    */
-  map<MK, MV>(callback: EntryCallback<K, V, [MK, MV]>, thisArg?: any): any {
-    const out = this._createLike<MK, MV, [MK, MV]>();
+  map<MK, MV>(callback: EntryCallback<K, V, [MK, MV]>, thisArg?: unknown): LinkedHashMap<MK, MV> {
+    const out = this._createLike<MK, MV, [MK, MV]>() as unknown as LinkedHashMap<MK, MV>;
     let index = 0;
     for (const [key, value] of this) {
       const [newKey, newValue] = callback.call(thisArg, value, key, index, this);
@@ -819,8 +1203,8 @@ export class LinkedHashMap<K = any, V = any, R = [K, V]> extends IterableEntryBa
     return true;
   }
 
-  protected _createLike<TK = K, TV = V, TR = [TK, TV]>(entries: Iterable<[TK, TV] | TR> = [], options?: any): any {
-    const Ctor = this.constructor as new (e?: Iterable<[TK, TV] | TR>, o?: any) => any;
+  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);
   }
 }