min-heap-typed 1.49.0 → 1.49.2

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

@@ -5,11 +5,16 @@
  * @copyright Copyright (c) 2022 Tyler Zeng <zrwusa@gmail.com>
  * @license MIT License
  */
-
+import type { EntryCallback, HashMapLinkedNode, HashMapOptions, HashMapStoreItem } from '../../types';
+import { IterableEntryBase } from '../base';
 import { isWeakKey, rangeCheck } from '../../utils';
-import { EntryCallback, HashMapLinkedNode, HashMapOptions, HashMapStoreItem } from '../../types';
-import { IterableEntryBase } from "../base";
 
+/**
+ * 1. Key-Value Pair Storage: HashMap stores key-value pairs. Each key maps to a value.
+ * 2. Fast Lookup: It's used when you need to quickly find, insert, or delete elements based on a key.
+ * 3. Unique Keys: Keys are unique. If you try to insert another entry with the same key, the old entry will be replaced by the new one.
+ * 4. Unordered Collection: HashMap does not guarantee the order of elements, and the order may change over time.
+ */
 export class HashMap<K = any, V = any> extends IterableEntryBase<K, V> {
   protected _store: { [key: string]: HashMapStoreItem<K, V> } = {};
   protected _objMap: Map<object, V> = new Map();
@@ -30,7 +35,6 @@ export class HashMap<K = any, V = any> extends IterableEntryBase<K, V> {
       const { hashFn } = options;
       if (hashFn) {
         this._hashFn = hashFn;
-
       }
     }
     if (elements) {
@@ -63,8 +67,7 @@ export class HashMap<K = any, V = any> extends IterableEntryBase<K, V> {
    * @param {V} value - The value parameter represents the value that you want to associate with the
    * key in the data structure.
    */
-  set(key: K, value: V) {
-
+  set(key: K, value: V): boolean {
     if (this._isObjKey(key)) {
       if (!this._objMap.has(key)) {
         this._size++;
@@ -78,6 +81,7 @@ export class HashMap<K = any, V = any> extends IterableEntryBase<K, V> {
       }
       this._store[strKey] = { key, value };
     }
+    return true;
   }
 
   /**
@@ -85,8 +89,10 @@ export class HashMap<K = any, V = any> extends IterableEntryBase<K, V> {
    * @param elements - The `elements` parameter is an iterable containing key-value pairs. Each
    * key-value pair is represented as an array with two elements: the key and the value.
    */
-  setMany(elements: Iterable<[K, V]>) {
-    for (const [key, value] of elements) this.set(key, value);
+  setMany(elements: Iterable<[K, V]>): boolean[] {
+    const results: boolean[] = [];
+    for (const [key, value] of elements) results.push(this.set(key, value));
+    return results;
   }
 
   /**
@@ -210,6 +216,10 @@ export class HashMap<K = any, V = any> extends IterableEntryBase<K, V> {
     console.log([...this.entries()]);
   }
 
+  put(key: K, value: V): boolean {
+    return this.set(key, value);
+  }
+
   /**
    * The function returns an iterator that yields key-value pairs from both an object store and an
    * object map.
@@ -248,6 +258,11 @@ export class HashMap<K = any, V = any> extends IterableEntryBase<K, V> {
   }
 }
 
+/**
+ * 1. Maintaining the Order of Element Insertion: Unlike HashMap, LinkedHashMap maintains the order in which elements are inserted. Therefore, when you traverse it, elements will be returned in the order they were inserted into the map.
+ * 2. Based on Hash Table and Linked List: It combines the structures of a hash table and a linked list, using the hash table to ensure fast access, while maintaining the order of elements through the linked list.
+ * 3. Time Complexity: Similar to HashMap, LinkedHashMap offers constant-time performance for get and put operations in most cases.
+ */
 export class LinkedHashMap<K = any, V = any> extends IterableEntryBase<K, V> {
 
   protected _noObjMap: Record<string, HashMapLinkedNode<K, V | undefined>> = {};
@@ -276,7 +291,6 @@ export class LinkedHashMap<K = any, V = any> extends IterableEntryBase<K, V> {
         this.set(el[0], el[1]);
       }
     }
-
   }
 
   protected _size = 0;
@@ -346,7 +360,7 @@ export class LinkedHashMap<K = any, V = any> extends IterableEntryBase<K, V> {
    * value associated with the key being set in the data structure.
    * @returns the size of the data structure after the key-value pair has been set.
    */
-  set(key: K, value?: V) {
+  set(key: K, value?: V): boolean {
     let node;
     const isNewKey = !this.has(key); // Check if the key is new
 
@@ -388,7 +402,7 @@ export class LinkedHashMap<K = any, V = any> extends IterableEntryBase<K, V> {
       this._size++;
     }
 
-    return this._size;
+    return true;
   }
 
   has(key: K): boolean {
@@ -401,11 +415,13 @@ export class LinkedHashMap<K = any, V = any> extends IterableEntryBase<K, V> {
     }
   }
 
-  setMany(entries: Iterable<[K, V]>): void {
+  setMany(entries: Iterable<[K, V]>): boolean[] {
+    const results: boolean[] = [];
     for (const entry of entries) {
       const [key, value] = entry;
-      this.set(key, value);
+      results.push(this.set(key, value));
     }
+    return results;
   }
 
   /**
@@ -444,13 +460,13 @@ export class LinkedHashMap<K = any, V = any> extends IterableEntryBase<K, V> {
    * 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: number) {
+  getAt(index: number): V | undefined {
     rangeCheck(index, 0, this._size - 1);
     let node = this._head;
     while (index--) {
       node = node.next;
     }
-    return <[K, V]>[node.key, node.value];
+    return node.value;
   }
 
   /**
@@ -463,7 +479,7 @@ export class LinkedHashMap<K = any, V = any> extends IterableEntryBase<K, V> {
    * @returns a boolean value. It returns `true` if the deletion was successful, and `false` if the key
    * was not found.
    */
-  delete(key: K) {
+  delete(key: K): boolean {
     let node;
 
     if (isWeakKey(key)) {
@@ -504,14 +520,13 @@ export class LinkedHashMap<K = any, V = any> extends IterableEntryBase<K, V> {
    * deleted in the linked list.
    * @returns The size of the list after deleting the element at the specified index.
    */
-  deleteAt(index: number) {
+  deleteAt(index: number): boolean {
     rangeCheck(index, 0, this._size - 1);
     let node = this._head;
     while (index--) {
       node = node.next;
     }
-    this._deleteNode(node);
-    return this._size;
+    return this._deleteNode(node);
   }
 
   /**
@@ -522,7 +537,7 @@ export class LinkedHashMap<K = any, V = any> extends IterableEntryBase<K, V> {
    * @returns The method is returning a boolean value indicating whether the size of the object is 0 or
    * not.
    */
-  isEmpty() {
+  isEmpty(): boolean {
     return this._size === 0;
   }
 
@@ -532,7 +547,7 @@ export class LinkedHashMap<K = any, V = any> extends IterableEntryBase<K, V> {
    *
    * The `clear` function clears all the elements in a data structure and resets its properties.
    */
-  clear() {
+  clear(): void {
     this._noObjMap = {};
     this._size = 0;
     this._head = this._tail = this._sentinel.prev = this._sentinel.next = this._sentinel;
@@ -612,8 +627,8 @@ export class LinkedHashMap<K = any, V = any> extends IterableEntryBase<K, V> {
     return mappedMap;
   }
 
-  print() {
-    console.log([...this]);
+  put(key: K, value: V): boolean {
+    return this.set(key, value);
   }
 
   /**
@@ -640,7 +655,7 @@ export class LinkedHashMap<K = any, V = any> extends IterableEntryBase<K, V> {
    * represents a node in a linked list. It contains a key-value pair and references to the previous
    * and next nodes in the list.
    */
-  protected _deleteNode(node: HashMapLinkedNode<K, V | undefined>) {
+  protected _deleteNode(node: HashMapLinkedNode<K, V | undefined>): boolean {
     const { prev, next } = node;
     prev.next = next;
     next.prev = prev;
@@ -654,5 +669,6 @@ export class LinkedHashMap<K = any, V = any> extends IterableEntryBase<K, V> {
     }
 
     this._size -= 1;
+    return true;
   }
 }

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

@@ -6,7 +6,9 @@
  * @license MIT License
  */
 
-export class HashTableNode<K, V> {
+import type { HashFunction } from '../../types';
+
+export class HashTableNode<K = any, V = any> {
   key: K;
   value: V;
   next: HashTableNode<K, V> | undefined;
@@ -18,8 +20,6 @@ export class HashTableNode<K, V> {
   }
 }
 
-import { HashFunction } from '../../types';
-
 export class HashTable<K = any, V = any> {
   protected static readonly DEFAULT_CAPACITY = 16;
   protected static readonly LOAD_FACTOR = 0.75;

package/src/data-structures/heap/heap.ts

@@ -5,10 +5,21 @@
  * @license MIT License
  */
 
-import type { Comparator, DFSOrderPattern, ElementCallback } from '../../types';
-import { HeapOptions } from "../../types";
-import { IterableElementBase } from "../base";
+import type { Comparator, DFSOrderPattern, ElementCallback, HeapOptions } from '../../types';
+import { IterableElementBase } from '../base';
 
+/**
+ * 1. Complete Binary Tree: Heaps are typically complete binary trees, meaning every level is fully filled except possibly for the last level, which has nodes as far left as possible.
+ * 2. Heap Properties: Each node in a heap follows a specific order property, which varies depending on the type of heap:
+ * Max Heap: The value of each parent node is greater than or equal to the value of its children.
+ * Min Heap: The value of each parent node is less than or equal to the value of its children.
+ * 3. Root Node Access: In a heap, the largest element (in a max heap) or the smallest element (in a min heap) is always at the root of the tree.
+ * 4. Efficient Insertion and Deletion: Due to its structure, a heap allows for insertion and deletion operations in logarithmic time (O(log n)).
+ * 5. Managing Dynamic Data Sets: Heaps effectively manage dynamic data sets, especially when frequent access to the largest or smallest elements is required.
+ * 6. Non-linear Search: While a heap allows rapid access to its largest or smallest element, it is less efficient for other operations, such as searching for a specific element, as it is not designed for these tasks.
+ * 7. Efficient Sorting Algorithms: For example, heap sort. Heap sort uses the properties of a heap to sort elements.
+ * 8. Graph Algorithms: Such as Dijkstra's shortest path algorithm and Prim's minimum spanning tree algorithm, which use heaps to improve performance.
+ */
 export class Heap<E = any> extends IterableElementBase<E> {
   options: HeapOptions<E>;
 
@@ -31,7 +42,7 @@ export class Heap<E = any> extends IterableElementBase<E> {
 
     if (elements) {
       for (const el of elements) {
-        this.push(el);
+        this.add(el);
       }
       // this.fix();
     }
@@ -80,26 +91,9 @@ export class Heap<E = any> extends IterableElementBase<E> {
    * Insert an element into the heap and maintain the heap properties.
    * @param element - The element to be inserted.
    */
-  add(element: E): Heap<E> {
-    return this.push(element);
-  }
-
-  /**
-   * Time Complexity: O(log n), where n is the number of elements in the heap.
-   * Space Complexity: O(1)
-   */
-
-  /**
-   * Time Complexity: O(log n), where n is the number of elements in the heap.
-   * Space Complexity: O(1)
-   *
-   * Insert an element into the heap and maintain the heap properties.
-   * @param element - The element to be inserted.
-   */
-  push(element: E): Heap<E> {
+  add(element: E): boolean {
     this._elements.push(element);
-    this._bubbleUp(this.elements.length - 1);
-    return this;
+    return this._bubbleUp(this.elements.length - 1);
   }
 
   /**
@@ -125,22 +119,6 @@ export class Heap<E = any> extends IterableElementBase<E> {
     return value;
   }
 
-  /**
-   * Time Complexity: O(log n), where n is the number of elements in the heap.
-   * Space Complexity: O(1)
-   */
-
-  /**
-   * Time Complexity: O(log n), where n is the number of elements in the heap.
-   * Space Complexity: O(1)
-   *
-   * Remove and return the top element (smallest or largest element) from the heap.
-   * @returns The top element or undefined if the heap is empty.
-   */
-  pop(): E | undefined {
-    return this.poll();
-  }
-
   /**
    * Peek at the top element of the heap without removing it.
    * @returns The top element or undefined if the heap is empty.
@@ -153,14 +131,14 @@ export class Heap<E = any> extends IterableElementBase<E> {
    * Check if the heap is empty.
    * @returns True if the heap is empty, otherwise false.
    */
-  isEmpty() {
+  isEmpty(): boolean {
     return this.size === 0;
   }
 
   /**
    * Reset the elements of the heap. Make the elements empty.
    */
-  clear() {
+  clear(): void {
     this._elements = [];
   }
 
@@ -176,9 +154,9 @@ export class Heap<E = any> extends IterableElementBase<E> {
    * Clear and add elements of the heap
    * @param elements
    */
-  refill(elements: E[]) {
+  refill(elements: E[]): boolean[] {
     this._elements = elements;
-    this.fix();
+    return this.fix();
   }
 
   /**
@@ -214,11 +192,11 @@ export class Heap<E = any> extends IterableElementBase<E> {
    * @returns The `delete` function is returning a boolean value. It returns `true` if the element was
    * successfully deleted from the array, and `false` if the element was not found in the array.
    */
-  delete(element: E) {
+  delete(element: E): boolean {
     const index = this.elements.indexOf(element);
     if (index < 0) return false;
     if (index === 0) {
-      this.pop();
+      this.poll();
     } else if (index === this.elements.length - 1) {
       this.elements.pop();
     } else {
@@ -337,8 +315,10 @@ export class Heap<E = any> extends IterableElementBase<E> {
    *
    * Fix the entire heap to maintain heap properties.
    */
-  fix() {
-    for (let i = Math.floor(this.size / 2); i >= 0; i--) this._sinkDown(i, this.elements.length >> 1);
+  fix(): boolean[] {
+    const results: boolean[] = [];
+    for (let i = Math.floor(this.size / 2); i >= 0; i--) results.push(this._sinkDown(i, this.elements.length >> 1));
+    return results;
   }
 
   /**
@@ -367,7 +347,7 @@ export class Heap<E = any> extends IterableElementBase<E> {
     let index = 0;
     for (const current of this) {
       if (callback.call(thisArg, current, index, this)) {
-        filteredList.push(current);
+        filteredList.add(current);
       }
       index++;
     }
@@ -410,16 +390,7 @@ export class Heap<E = any> extends IterableElementBase<E> {
     return mappedHeap;
   }
 
-  /**
-   * Time Complexity: O(log n)
-   * Space Complexity: O(1)
-   */
-
-  print(): void {
-    console.log([...this]);
-  }
-
-  protected* _getIterator() {
+  protected* _getIterator(): IterableIterator<E> {
     for (const element of this.elements) {
       yield element;
     }
@@ -437,7 +408,7 @@ export class Heap<E = any> extends IterableElementBase<E> {
    * Float operation to maintain heap properties after adding an element.
    * @param index - The index of the newly added element.
    */
-  protected _bubbleUp(index: number) {
+  protected _bubbleUp(index: number): boolean {
     const element = this.elements[index];
     while (index > 0) {
       const parent = (index - 1) >> 1;
@@ -447,6 +418,7 @@ export class Heap<E = any> extends IterableElementBase<E> {
       index = parent;
     }
     this.elements[index] = element;
+    return true;
   }
 
   /**
@@ -457,7 +429,7 @@ export class Heap<E = any> extends IterableElementBase<E> {
    * @param index - The index from which to start sinking.
    * @param halfLength
    */
-  protected _sinkDown(index: number, halfLength: number) {
+  protected _sinkDown(index: number, halfLength: number): boolean {
     const element = this.elements[index];
     while (index < halfLength) {
       let left = index << 1 | 1;
@@ -475,6 +447,7 @@ export class Heap<E = any> extends IterableElementBase<E> {
       index = left;
     }
     this.elements[index] = element;
+    return true;
   }
 }
 

package/src/data-structures/heap/max-heap.ts

@@ -5,10 +5,19 @@
  * @copyright Copyright (c) 2022 Kirk Qi <qilinaus@gmail.com>
  * @license MIT License
  */
-
-import { Heap } from './heap';
 import type { HeapOptions } from '../../types';
+import { Heap } from './heap';
 
+/**
+ * 1. Complete Binary Tree: Heaps are typically complete binary trees, meaning every level is fully filled except possibly for the last level, which has nodes as far left as possible.
+ * 2. Heap Properties: The value of each parent node is greater than or equal to the value of its children.
+ * 3. Root Node Access: In a heap, the largest element (in a max heap) or the smallest element (in a min heap) is always at the root of the tree.
+ * 4. Efficient Insertion and Deletion: Due to its structure, a heap allows for insertion and deletion operations in logarithmic time (O(log n)).
+ * 5. Managing Dynamic Data Sets: Heaps effectively manage dynamic data sets, especially when frequent access to the largest or smallest elements is required.
+ * 6. Non-linear Search: While a heap allows rapid access to its largest or smallest element, it is less efficient for other operations, such as searching for a specific element, as it is not designed for these tasks.
+ * 7. Efficient Sorting Algorithms: For example, heap sort. Heap sort uses the properties of a heap to sort elements.
+ * 8. Graph Algorithms: Such as Dijkstra's shortest path algorithm and Prim's minimum spanning tree algorithm, which use heaps to improve performance.
+ */
 export class MaxHeap<E = any> extends Heap<E> {
   constructor(
     elements?: Iterable<E>,

package/src/data-structures/heap/min-heap.ts

@@ -5,10 +5,19 @@
  * @copyright Copyright (c) 2022 Kirk Qi <qilinaus@gmail.com>
  * @license MIT License
  */
-
-import { Heap } from './heap';
 import type { HeapOptions } from '../../types';
+import { Heap } from './heap';
 
+/**
+ * 1. Complete Binary Tree: Heaps are typically complete binary trees, meaning every level is fully filled except possibly for the last level, which has nodes as far left as possible.
+ * 2. Heap Properties:  The value of each parent node is less than or equal to the value of its children.
+ * 3. Root Node Access: In a heap, the largest element (in a max heap) or the smallest element (in a min heap) is always at the root of the tree.
+ * 4. Efficient Insertion and Deletion: Due to its structure, a heap allows for insertion and deletion operations in logarithmic time (O(log n)).
+ * 5. Managing Dynamic Data Sets: Heaps effectively manage dynamic data sets, especially when frequent access to the largest or smallest elements is required.
+ * 6. Non-linear Search: While a heap allows rapid access to its largest or smallest element, it is less efficient for other operations, such as searching for a specific element, as it is not designed for these tasks.
+ * 7. Efficient Sorting Algorithms: For example, heap sort. Heap sort uses the properties of a heap to sort elements.
+ * 8. Graph Algorithms: Such as Dijkstra's shortest path algorithm and Prim's minimum spanning tree algorithm, which use heaps to improve performance.
+ */
 export class MinHeap<E = any> extends Heap<E> {
   constructor(
     elements?: Iterable<E>,