data-structure-typed 1.50.1 → 1.50.3

package/dist/mjs/data-structures/hash/hash-map.js

@@ -7,8 +7,6 @@ import { isWeakKey, rangeCheck } from '../../utils';
  * 4. Unordered Collection: HashMap does not guarantee the order of entries, and the order may change over time.
  */
 export class HashMap extends IterableEntryBase {
-    _store = {};
-    _objMap = new Map();
     /**
      * The constructor function initializes a HashMap object with an optional initial collection and
      * options.
@@ -31,6 +29,24 @@ export class HashMap extends IterableEntryBase {
             this.setMany(rawCollection);
         }
     }
+    _store = {};
+    /**
+     * The function returns the store object, which is a dictionary of HashMapStoreItem objects.
+     * @returns The store property is being returned. It is a dictionary-like object with string keys and
+     * values of type HashMapStoreItem<K, V>.
+     */
+    get store() {
+        return this._store;
+    }
+    _objMap = new Map();
+    /**
+     * The function returns the object map.
+     * @returns The `objMap` property is being returned, which is a `Map` object with keys of type
+     * `object` and values of type `V`.
+     */
+    get objMap() {
+        return this._objMap;
+    }
     _toEntryFn = (rawElement) => {
         if (this.isEntry(rawElement)) {
             // TODO, For performance optimization, it may be necessary to only inspect the first element traversed.
@@ -40,19 +56,51 @@ export class HashMap extends IterableEntryBase {
             throw new Error("If the provided rawCollection does not adhere to the [key, value] type format, the toEntryFn in the constructor's options parameter needs to specified.");
         }
     };
+    /**
+     * The function returns the value of the _toEntryFn property.
+     * @returns The function being returned is `this._toEntryFn`.
+     */
     get toEntryFn() {
         return this._toEntryFn;
     }
     _size = 0;
+    /**
+     * The function returns the size of an object.
+     * @returns The size of the object, which is a number.
+     */
     get size() {
         return this._size;
     }
+    _hashFn = (key) => String(key);
+    /**
+     * The hasFn function is a function that takes in an item and returns a boolean
+     * indicating whether the item is contained within the hash table.
+     *
+     * @return The hash function
+     */
+    get hashFn() {
+        return this._hashFn;
+    }
+    /**
+     * The function checks if a given element is an array with exactly two elements.
+     * @param {any} rawElement - The `rawElement` parameter is of type `any`, which means it can be any
+     * data type.
+     * @returns a boolean value.
+     */
     isEntry(rawElement) {
         return Array.isArray(rawElement) && rawElement.length === 2;
     }
+    /**
+     * The function checks if the size of an object is equal to zero and returns a boolean value.
+     * @returns A boolean value indicating whether the size of the object is 0 or not.
+     */
     isEmpty() {
         return this.size === 0;
     }
+    /**
+     * The clear() function resets the state of an object by clearing its internal store, object map, and
+     * size.
+     */
     clear() {
         this._store = {};
         this._objMap.clear();
@@ -69,14 +117,14 @@ export class HashMap extends IterableEntryBase {
      */
     set(key, value) {
         if (this._isObjKey(key)) {
-            if (!this._objMap.has(key)) {
+            if (!this.objMap.has(key)) {
                 this._size++;
             }
-            this._objMap.set(key, value);
+            this.objMap.set(key, value);
         }
         else {
             const strKey = this._getNoObjKey(key);
-            if (this._store[strKey] === undefined) {
+            if (this.store[strKey] === undefined) {
                 this._size++;
             }
             this._store[strKey] = { key, value };
@@ -93,7 +141,16 @@ export class HashMap extends IterableEntryBase {
     setMany(rawCollection) {
         const results = [];
         for (const rawEle of rawCollection) {
-            const [key, value] = this.toEntryFn(rawEle);
+            let key, value;
+            if (this.isEntry(rawEle)) {
+                key = rawEle[0];
+                value = rawEle[1];
+            }
+            else {
+                const item = this.toEntryFn(rawEle);
+                key = item[0];
+                value = item[1];
+            }
             results.push(this.set(key, value));
         }
         return results;
@@ -108,7 +165,7 @@ export class HashMap extends IterableEntryBase {
      */
     get(key) {
         if (this._isObjKey(key)) {
-            return this._objMap.get(key);
+            return this.objMap.get(key);
         }
         else {
             const strKey = this._getNoObjKey(key);
@@ -123,11 +180,11 @@ export class HashMap extends IterableEntryBase {
      */
     has(key) {
         if (this._isObjKey(key)) {
-            return this._objMap.has(key);
+            return this.objMap.has(key);
         }
         else {
             const strKey = this._getNoObjKey(key);
-            return strKey in this._store;
+            return strKey in this.store;
         }
     }
     /**
@@ -139,21 +196,35 @@ export class HashMap extends IterableEntryBase {
      */
     delete(key) {
         if (this._isObjKey(key)) {
-            if (this._objMap.has(key)) {
+            if (this.objMap.has(key)) {
                 this._size--;
             }
-            return this._objMap.delete(key);
+            return this.objMap.delete(key);
         }
         else {
             const strKey = this._getNoObjKey(key);
-            if (strKey in this._store) {
-                delete this._store[strKey];
+            if (strKey in this.store) {
+                delete this.store[strKey];
                 this._size--;
                 return true;
             }
             return false;
         }
     }
+    /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(n)
+     */
+    /**
+     * The clone function creates a new HashMap with the same key-value pairs as
+     * this one. The clone function is useful for creating a copy of an existing
+     * HashMap, and then modifying that copy without affecting the original.
+     *
+     * @return A new hashmap with the same values as this one
+     */
+    clone() {
+        return new HashMap(this, { hashFn: this.hashFn, toEntryFn: this.toEntryFn });
+    }
     /**
      * Time Complexity: O(n)
      * Space Complexity: O(n)
@@ -180,10 +251,6 @@ export class HashMap extends IterableEntryBase {
         }
         return resultMap;
     }
-    /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(n)
-     */
     /**
      * Time Complexity: O(n)
      * Space Complexity: O(n)
@@ -210,6 +277,14 @@ export class HashMap extends IterableEntryBase {
         }
         return filteredMap;
     }
+    /**
+     * The put function sets a value in a data structure using a specified key.
+     * @param {K} key - The key parameter is of type K, which represents the type of the key being passed
+     * to the function.
+     * @param {V} value - The value parameter represents the value that you want to associate with the
+     * specified key in the data structure.
+     * @returns The method is returning a boolean value.
+     */
     put(key, value) {
         return this.set(key, value);
     }
@@ -218,23 +293,34 @@ export class HashMap extends IterableEntryBase {
      * object map.
      */
     *_getIterator() {
-        for (const node of Object.values(this._store)) {
+        for (const node of Object.values(this.store)) {
             yield [node.key, node.value];
         }
-        for (const node of this._objMap) {
+        for (const node of this.objMap) {
             yield node;
         }
     }
-    _hashFn = (key) => String(key);
+    /**
+     * The function checks if a given key is an object or a function.
+     * @param {any} key - The parameter "key" can be of any type.
+     * @returns a boolean value.
+     */
     _isObjKey(key) {
         const keyType = typeof key;
         return (keyType === 'object' || keyType === 'function') && key !== null;
     }
+    /**
+     * The function `_getNoObjKey` takes a key and returns a string representation of the key, handling
+     * different types of keys.
+     * @param {K} key - The `key` parameter is of type `K`, which represents the type of the key being
+     * passed to the `_getNoObjKey` function.
+     * @returns a string value.
+     */
     _getNoObjKey(key) {
         const keyType = typeof key;
         let strKey;
         if (keyType !== 'string' && keyType !== 'number' && keyType !== 'symbol') {
-            strKey = this._hashFn(key);
+            strKey = this.hashFn(key);
         }
         else {
             if (keyType === 'number') {
@@ -254,32 +340,116 @@ export class HashMap extends IterableEntryBase {
  * 3. Time Complexity: Similar to HashMap, LinkedHashMap offers constant-time performance for get and put operations in most cases.
  */
 export class LinkedHashMap extends IterableEntryBase {
-    _noObjMap = {};
-    _objMap = new WeakMap();
-    _head;
-    _tail;
     _sentinel;
-    constructor(entries, options) {
+    /**
+     * The constructor initializes a LinkedHashMap object with an optional raw collection and options.
+     * @param rawCollection - The `rawCollection` parameter is an iterable collection of elements. It is
+     * used to initialize the HashMapLinked instance with key-value pairs. Each element in the
+     * `rawCollection` is converted to a key-value pair using the `toEntryFn` function (if provided) and
+     * then added to the HashMap
+     * @param [options] - The `options` parameter is an optional object that can contain the following
+     * properties:
+     */
+    constructor(rawCollection = [], options) {
         super();
         this._sentinel = {};
         this._sentinel.prev = this._sentinel.next = this._head = this._tail = this._sentinel;
         if (options) {
-            const { hashFn, objHashFn } = options;
+            const { hashFn, objHashFn, toEntryFn } = options;
             if (hashFn)
                 this._hashFn = hashFn;
             if (objHashFn)
                 this._objHashFn = objHashFn;
+            if (toEntryFn) {
+                this._toEntryFn = toEntryFn;
+            }
         }
-        if (entries) {
-            for (const el of entries) {
-                this.set(el[0], el[1]);
+        if (rawCollection) {
+            for (const el of rawCollection) {
+                const [key, value] = this.toEntryFn(el);
+                this.set(key, value);
             }
         }
     }
+    _hashFn = (key) => String(key);
+    /**
+     * The function returns the hash function used for generating a hash value for a given key.
+     * @returns The hash function that takes a key of type K and returns a string.
+     */
+    get hashFn() {
+        return this._hashFn;
+    }
+    _objHashFn = (key) => key;
+    /**
+     * The function returns the object hash function.
+     * @returns The function `objHashFn` is being returned.
+     */
+    get objHashFn() {
+        return this._objHashFn;
+    }
+    _noObjMap = {};
+    /**
+     * The function returns a record of HashMapLinkedNode objects with string keys.
+     * @returns The method is returning a Record object, which is a TypeScript type that represents an
+     * object with string keys and values that are HashMapLinkedNode objects with keys of type K and
+     * values of type V or undefined.
+     */
+    get noObjMap() {
+        return this._noObjMap;
+    }
+    _objMap = new WeakMap();
+    /**
+     * The function returns the WeakMap object used to map objects to HashMapLinkedNode instances.
+     * @returns The `objMap` property is being returned.
+     */
+    get objMap() {
+        return this._objMap;
+    }
+    _head;
+    /**
+     * The function returns the head node of a HashMapLinkedNode.
+     * @returns The method `getHead()` is returning a `HashMapLinkedNode` object with key type `K` and
+     * value type `V | undefined`.
+     */
+    get head() {
+        return this._head;
+    }
+    _tail;
+    /**
+     * The function returns the tail node of a HashMapLinkedNode.
+     * @returns The `_tail` property of type `HashMapLinkedNode<K, V | undefined>` is being returned.
+     */
+    get tail() {
+        return this._tail;
+    }
+    _toEntryFn = (rawElement) => {
+        if (this.isEntry(rawElement)) {
+            // TODO, For performance optimization, it may be necessary to only inspect the first element traversed.
+            return rawElement;
+        }
+        else {
+            throw new Error("If the provided rawCollection does not adhere to the [key, value] type format, the toEntryFn in the constructor's options parameter needs to specified.");
+        }
+    };
+    /**
+     * The function returns the value of the _toEntryFn property.
+     * @returns The function being returned is `this._toEntryFn`.
+     */
+    get toEntryFn() {
+        return this._toEntryFn;
+    }
     _size = 0;
+    /**
+     * The function returns the size of an object.
+     * @returns The size of the object.
+     */
     get size() {
         return this._size;
     }
+    /**
+     * Time Complexity: O(1)
+     * Space Complexity: O(1)
+     */
     /**
      * Time Complexity: O(1)
      * Space Complexity: O(1)
@@ -291,8 +461,12 @@ export class LinkedHashMap extends IterableEntryBase {
     get first() {
         if (this._size === 0)
             return;
-        return [this._head.key, this._head.value];
+        return [this.head.key, this.head.value];
     }
+    /**
+     * Time Complexity: O(1)
+     * Space Complexity: O(1)
+     */
     /**
      * Time Complexity: O(1)
      * Space Complexity: O(1)
@@ -304,13 +478,13 @@ export class LinkedHashMap extends IterableEntryBase {
     get last() {
         if (this._size === 0)
             return;
-        return [this._tail.key, this._tail.value];
+        return [this.tail.key, this.tail.value];
     }
     /**
      * The `begin()` function in TypeScript iterates over a linked list and yields key-value pairs.
      */
     *begin() {
-        let node = this._head;
+        let node = this.head;
         while (node !== this._sentinel) {
             yield [node.key, node.value];
             node = node.next;
@@ -321,12 +495,16 @@ export class LinkedHashMap extends IterableEntryBase {
      * key and value.
      */
     *reverseBegin() {
-        let node = this._tail;
+        let node = this.tail;
         while (node !== this._sentinel) {
             yield [node.key, node.value];
             node = node.prev;
         }
     }
+    /**
+     * Time Complexity: O(1)
+     * Space Complexity: O(1)
+     */
     /**
      * Time Complexity: O(1)
      * Space Complexity: O(1)
@@ -343,12 +521,12 @@ export class LinkedHashMap extends IterableEntryBase {
         let node;
         const isNewKey = !this.has(key); // Check if the key is new
         if (isWeakKey(key)) {
-            const hash = this._objHashFn(key);
-            node = this._objMap.get(hash);
+            const hash = this.objHashFn(key);
+            node = this.objMap.get(hash);
             if (!node && isNewKey) {
                 // Create new node
-                node = { key: hash, value, prev: this._tail, next: this._sentinel };
-                this._objMap.set(hash, node);
+                node = { key: hash, value, prev: this.tail, next: this._sentinel };
+                this.objMap.set(hash, node);
             }
             else if (node) {
                 // Update the value of an existing node
@@ -356,10 +534,10 @@ export class LinkedHashMap extends IterableEntryBase {
             }
         }
         else {
-            const hash = this._hashFn(key);
-            node = this._noObjMap[hash];
+            const hash = this.hashFn(key);
+            node = this.noObjMap[hash];
             if (!node && isNewKey) {
-                this._noObjMap[hash] = node = { key, value, prev: this._tail, next: this._sentinel };
+                this.noObjMap[hash] = node = { key, value, prev: this.tail, next: this._sentinel };
             }
             else if (node) {
                 // Update the value of an existing node
@@ -373,8 +551,8 @@ export class LinkedHashMap extends IterableEntryBase {
                 this._sentinel.next = node;
             }
             else {
-                this._tail.next = node;
-                node.prev = this._tail; // Make sure that the prev of the new node points to the current tail node
+                this.tail.next = node;
+                node.prev = this.tail; // Make sure that the prev of the new node points to the current tail node
             }
             this._tail = node;
             this._sentinel.prev = node;
@@ -382,24 +560,42 @@ export class LinkedHashMap extends IterableEntryBase {
         }
         return true;
     }
+    /**
+     * The function `setMany` takes an iterable collection, converts each element into a key-value pair
+     * using a provided function, and sets each key-value pair in the current object, returning an array
+     * of booleans indicating the success of each set operation.
+     * @param rawCollection - The rawCollection parameter is an iterable collection of elements of type
+     * R.
+     * @returns The `setMany` function returns an array of booleans.
+     */
+    setMany(rawCollection) {
+        const results = [];
+        for (const rawEle of rawCollection) {
+            const [key, value] = this.toEntryFn(rawEle);
+            results.push(this.set(key, value));
+        }
+        return results;
+    }
+    /**
+     * The function checks if a given key exists in a map, using different logic depending on whether the
+     * key is a weak key or not.
+     * @param {K} key - The `key` parameter is the key that is being checked for existence in the map.
+     * @returns The method `has` is returning a boolean value.
+     */
     has(key) {
         if (isWeakKey(key)) {
-            const hash = this._objHashFn(key);
-            return this._objMap.has(hash);
+            const hash = this.objHashFn(key);
+            return this.objMap.has(hash);
         }
         else {
-            const hash = this._hashFn(key);
-            return hash in this._noObjMap;
+            const hash = this.hashFn(key);
+            return hash in this.noObjMap;
         }
     }
-    setMany(entries) {
-        const results = [];
-        for (const entry of entries) {
-            const [key, value] = entry;
-            results.push(this.set(key, value));
-        }
-        return results;
-    }
+    /**
+     * Time Complexity: O(1)
+     * Space Complexity: O(1)
+     */
     /**
      * Time Complexity: O(1)
      * Space Complexity: O(1)
@@ -415,36 +611,46 @@ export class LinkedHashMap extends IterableEntryBase {
      */
     get(key) {
         if (isWeakKey(key)) {
-            const hash = this._objHashFn(key);
-            const node = this._objMap.get(hash);
+            const hash = this.objHashFn(key);
+            const node = this.objMap.get(hash);
             return node ? node.value : undefined;
         }
         else {
-            const hash = this._hashFn(key);
-            const node = this._noObjMap[hash];
+            const hash = this.hashFn(key);
+            const node = this.noObjMap[hash];
             return node ? node.value : undefined;
         }
     }
     /**
-     * Time Complexity: O(n), where n is the index.
+     * Time Complexity: O(n)
+     * Space Complexity: O(1)
+     * /
+  
+     /**
+     * Time Complexity: O(n)
      * Space Complexity: O(1)
      *
-     * The function `getAt` retrieves the key-value pair at a specified index in a linked list.
+     * The function `at` retrieves the key-value pair at a specified index in a linked list.
      * @param {number} index - The index parameter is a number that represents the position of the
      * element we want to retrieve from the data structure.
-     * @returns The method `getAt(index: number)` is returning an array containing the key-value pair at
+     * @returns The method `at(index: number)` is returning an array containing the key-value pair at
      * the specified index in the data structure. The key-value pair is represented as a tuple `[K, V]`,
      * where `K` is the key and `V` is the value.
      */
-    getAt(index) {
+    at(index) {
         rangeCheck(index, 0, this._size - 1);
-        let node = this._head;
+        let node = this.head;
         while (index--) {
             node = node.next;
         }
         return node.value;
     }
     /**
+     * Time Complexity: O(1)
+     * Space Complexity: O(1)
+     * /
+  
+     /**
      * Time Complexity: O(1)
      * Space Complexity: O(1)
      *
@@ -457,31 +663,36 @@ export class LinkedHashMap extends IterableEntryBase {
     delete(key) {
         let node;
         if (isWeakKey(key)) {
-            const hash = this._objHashFn(key);
+            const hash = this.objHashFn(key);
             // Get nodes from WeakMap
-            node = this._objMap.get(hash);
+            node = this.objMap.get(hash);
             if (!node) {
                 return false; // If the node does not exist, return false
             }
             // Remove nodes from WeakMap
-            this._objMap.delete(hash);
+            this.objMap.delete(hash);
         }
         else {
-            const hash = this._hashFn(key);
+            const hash = this.hashFn(key);
             // Get nodes from noObjMap
-            node = this._noObjMap[hash];
+            node = this.noObjMap[hash];
             if (!node) {
                 return false; // If the node does not exist, return false
             }
             // Remove nodes from orgMap
-            delete this._noObjMap[hash];
+            delete this.noObjMap[hash];
         }
         // Remove node from doubly linked list
         this._deleteNode(node);
         return true;
     }
     /**
-     * Time Complexity: O(n), where n is the index.
+     * Time Complexity: O(n)
+     * Space Complexity: O(1)
+     * /
+  
+     /**
+     * Time Complexity: O(n)
      * Space Complexity: O(1)
      *
      * The `deleteAt` function deletes a node at a specified index in a linked list.
@@ -491,13 +702,18 @@ export class LinkedHashMap extends IterableEntryBase {
      */
     deleteAt(index) {
         rangeCheck(index, 0, this._size - 1);
-        let node = this._head;
+        let node = this.head;
         while (index--) {
             node = node.next;
         }
         return this._deleteNode(node);
     }
     /**
+     * Time Complexity: O(1)
+     * Space Complexity: O(1)
+     * /
+  
+     /**
      * Time Complexity: O(1)
      * Space Complexity: O(1)
      *
@@ -509,6 +725,20 @@ export class LinkedHashMap extends IterableEntryBase {
         return this._size === 0;
     }
     /**
+     * The function checks if a given element is an array with exactly two elements.
+     * @param {any} rawElement - The `rawElement` parameter is of type `any`, which means it can be any
+     * data type.
+     * @returns a boolean value.
+     */
+    isEntry(rawElement) {
+        return Array.isArray(rawElement) && rawElement.length === 2;
+    }
+    /**
+     * Time Complexity: O(1)
+     * Space Complexity: O(1)
+     * /
+  
+     /**
      * Time Complexity: O(1)
      * Space Complexity: O(1)
      *
@@ -519,8 +749,21 @@ export class LinkedHashMap extends IterableEntryBase {
         this._size = 0;
         this._head = this._tail = this._sentinel.prev = this._sentinel.next = this._sentinel;
     }
+    /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(n)
+     */
+    /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(n)
+     *
+     * The `clone` function creates a new instance of a `LinkedHashMap` with the same key-value pairs as
+     * the original.
+     * @returns The `clone()` method is returning a new instance of `LinkedHashMap<K, V>` that is a clone
+     * of the original `LinkedHashMap` object.
+     */
     clone() {
-        const cloned = new LinkedHashMap([], { hashFn: this._hashFn, objHashFn: this._objHashFn });
+        const cloned = new LinkedHashMap([], { hashFn: this.hashFn, objHashFn: this.objHashFn });
         for (const entry of this) {
             const [key, value] = entry;
             cloned.set(key, value);
@@ -528,6 +771,11 @@ export class LinkedHashMap extends IterableEntryBase {
         return cloned;
     }
     /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(n)
+     * /
+  
+     /**
      * Time Complexity: O(n)
      * Space Complexity: O(n)
      *
@@ -554,6 +802,11 @@ export class LinkedHashMap extends IterableEntryBase {
         return filteredMap;
     }
     /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(n)
+     * /
+  
+     /**
      * Time Complexity: O(n)
      * Space Complexity: O(n)
      *
@@ -581,31 +834,47 @@ export class LinkedHashMap extends IterableEntryBase {
         return mappedMap;
     }
     /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(n)
+     * Time Complexity: O(1)
+     * Space Complexity: O(1)
+     */
+    /**
+     * Time Complexity: O(1)
+     * Space Complexity: O(1)
+     *
+     * The put function sets a value in a data structure using a specified key.
+     * @param {K} key - The key parameter is of type K, which represents the type of the key being passed
+     * to the function.
+     * @param {V} value - The value parameter represents the value that you want to associate with the
+     * specified key in the data structure.
+     * @returns The method is returning a boolean value.
      */
     put(key, value) {
         return this.set(key, value);
     }
     /**
      * Time Complexity: O(n)
-     * Space Complexity: O(n)
-     */
-    _hashFn = (key) => String(key);
-    _objHashFn = (key) => key;
-    /**
-     * Time Complexity: O(n), where n is the number of entries in the LinkedHashMap.
      * Space Complexity: O(1)
+     * where n is the number of entries in the LinkedHashMap.
+     * /
+  
+     /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(1)
+     * where n is the number of entries in the LinkedHashMap.
      *
      * The above function is an iterator that yields key-value pairs from a linked list.
      */
     *_getIterator() {
-        let node = this._head;
+        let node = this.head;
         while (node !== this._sentinel) {
             yield [node.key, node.value];
             node = node.next;
         }
     }
+    /**
+     * Time Complexity: O(1)
+     * Space Complexity: O(1)
+     */
     /**
      * Time Complexity: O(1)
      * Space Complexity: O(1)
@@ -620,10 +889,10 @@ export class LinkedHashMap extends IterableEntryBase {
         const { prev, next } = node;
         prev.next = next;
         next.prev = prev;
-        if (node === this._head) {
+        if (node === this.head) {
             this._head = next;
         }
-        if (node === this._tail) {
+        if (node === this.tail) {
             this._tail = prev;
         }
         this._size -= 1;