stack-typed 2.0.5 → 2.1.1

package/src/data-structures/linked-list/skip-linked-list.ts

@@ -1,10 +1,3 @@
-/**
- * data-structure-typed
- *
- * @author Pablo Zeng
- * @copyright Copyright (c) 2022 Pablo Zeng <zrwusa@gmail.com>
- * @license MIT License
- */
 import type { SkipLinkedListOptions } from '../../types';
 
 export class SkipListNode<K, V> {
@@ -19,18 +12,7 @@ export class SkipListNode<K, V> {
   }
 }
 
-/**
- *
- */
 export class SkipList<K, V> {
-  /**
-   * The constructor function initializes a SkipLinkedList object with optional options and elements.
-   * @param elements - The `elements` parameter is an iterable containing key-value pairs `[K, V]`. It
-   * is used to initialize the SkipLinkedList with the given key-value pairs. If no elements are
-   * provided, the SkipLinkedList will be empty.
-   * @param {SkipLinkedListOptions} [options] - The `options` parameter is an optional object that can
-   * contain two properties:
-   */
   constructor(elements: Iterable<[K, V]> = [], options?: SkipLinkedListOptions) {
     if (options) {
       const { maxLevel, probability } = options;
@@ -43,65 +25,35 @@ export class SkipList<K, V> {
     }
   }
 
-  protected _head: SkipListNode<K, V> = new SkipListNode<K, V>(undefined as any, undefined as any, this.maxLevel);
+  protected _head: SkipListNode<K, V> = new SkipListNode<K, V>(undefined as K, undefined as V, this.maxLevel);
 
-  /**
-   * The function returns the head node of a SkipList.
-   * @returns The method is returning a SkipListNode object with generic key type K and value type V.
-   */
   get head(): SkipListNode<K, V> {
     return this._head;
   }
 
   protected _level: number = 0;
 
-  /**
-   * The function returns the value of the protected variable _level.
-   * @returns The level property of the object.
-   */
   get level(): number {
     return this._level;
   }
 
   protected _maxLevel: number = 16;
 
-  /**
-   * The function returns the maximum level.
-   * @returns The value of the variable `_maxLevel` is being returned.
-   */
   get maxLevel(): number {
     return this._maxLevel;
   }
 
   protected _probability: number = 0.5;
 
-  /**
-   * The function returns the probability value.
-   * @returns The probability value stored in the protected variable `_probability` is being returned.
-   */
   get probability(): number {
     return this._probability;
   }
 
-  /**
-   * Time Complexity: O(1)
-   * Space Complexity: O(1)
-   *
-   * Get the value of the first element (the smallest element) in the Skip List.
-   * @returns The value of the first element, or undefined if the Skip List is empty.
-   */
   get first(): V | undefined {
     const firstNode = this.head.forward[0];
     return firstNode ? firstNode.value : undefined;
   }
 
-  /**
-   * Time Complexity: O(log n)
-   * Space Complexity: O(1)
-   *
-   * Get the value of the last element (the largest element) in the Skip List.
-   * @returns The value of the last element, or undefined if the Skip List is empty.
-   */
   get last(): V | undefined {
     let current = this.head;
     for (let i = this.level - 1; i >= 0; i--) {
@@ -112,15 +64,6 @@ export class SkipList<K, V> {
     return current.value;
   }
 
-  /**
-   * Time Complexity: O(log n)
-   * Space Complexity: O(1)
-   *
-   * The add function adds a new node with a given key and value to a Skip List data structure.
-   * @param {K} key - The key parameter represents the key of the node that needs to be added to the skip list.
-   * @param {V} value - The "value" parameter represents the value associated with the key that is being added to the Skip
-   * List.
-   */
   add(key: K, value: V): void {
     const newNode = new SkipListNode(key, value, this._randomLevel());
     const update: SkipListNode<K, V>[] = new Array(this.maxLevel).fill(this.head);
@@ -143,15 +86,6 @@ export class SkipList<K, V> {
     }
   }
 
-  /**
-   * Time Complexity: O(log n)
-   * Space Complexity: O(1)
-   *
-   * The function `get` retrieves the value associated with a given key from a skip list data structure.
-   * @param {K} key - The `key` parameter is the key of the element that we want to retrieve from the data structure.
-   * @returns The method `get(key: K)` returns the value associated with the given key if it exists in the data structure,
-   * otherwise it returns `undefined`.
-   */
   get(key: K): V | undefined {
     let current = this.head;
     for (let i = this.level - 1; i >= 0; i--) {
@@ -169,28 +103,10 @@ export class SkipList<K, V> {
     return undefined;
   }
 
-  /**
-   * Time Complexity: O(log n)
-   * Space Complexity: O(1)
-   *
-   * The function checks if a key exists in a data structure.
-   * @param {K} key - The parameter "key" is of type K, which represents the type of the key being
-   * checked.
-   * @returns a boolean value.
-   */
   has(key: K): boolean {
     return this.get(key) !== undefined;
   }
 
-  /**
-   * Time Complexity: O(log n)
-   * Space Complexity: O(1)
-   *
-   * The `delete` function removes a node with a specific key from a Skip List data structure.
-   * @param {K} key - The key parameter represents the key of the node that needs to be removed from the skip list.
-   * @returns The `delete` method returns a boolean value. It returns `true` if the key was successfully removed from the
-   * skip list, and `false` if the key was not found in the skip list.
-   */
   delete(key: K): boolean {
     const update: SkipListNode<K, V>[] = new Array(this.maxLevel).fill(this.head);
     let current = this.head;
@@ -220,14 +136,6 @@ export class SkipList<K, V> {
     return false;
   }
 
-  /**
-   * Time Complexity: O(log n)
-   * Space Complexity: O(1)
-   *
-   * Get the value of the first element in the Skip List that is greater than the given key.
-   * @param key - the given key.
-   * @returns The value of the first element greater than the given key, or undefined if there is no such element.
-   */
   higher(key: K): V | undefined {
     let current = this.head;
     for (let i = this.level - 1; i >= 0; i--) {
@@ -239,14 +147,6 @@ export class SkipList<K, V> {
     return nextNode ? nextNode.value : undefined;
   }
 
-  /**
-   * Time Complexity: O(log n)
-   * Space Complexity: O(1)
-   *
-   * Get the value of the last element in the Skip List that is less than the given key.
-   * @param key - the given key.
-   * @returns The value of the last element less than the given key, or undefined if there is no such element.
-   */
   lower(key: K): V | undefined {
     let current = this.head;
     let lastLess = undefined;
@@ -263,13 +163,6 @@ export class SkipList<K, V> {
     return lastLess ? lastLess.value : undefined;
   }
 
-  /**
-   * Time Complexity: O(maxLevel)
-   * Space Complexity: O(1)
-   *
-   * The function "_randomLevel" generates a random level based on a given probability and maximum level.
-   * @returns the level, which is a number.
-   */
   protected _randomLevel(): number {
     let level = 1;
     while (Math.random() < this.probability && level < this.maxLevel) {

package/src/data-structures/priority-queue/max-priority-queue.ts

@@ -5,22 +5,24 @@
  * @copyright Copyright (c) 2022 Kirk Qi <qilinaus@gmail.com>
  * @license MIT License
  */
-import type { Comparator, ElementCallback, PriorityQueueOptions } from '../../types';
+import type { PriorityQueueOptions } from '../../types';
 import { PriorityQueue } from './priority-queue';
 
 /**
- *
+ * Max-oriented priority queue (max-heap) built on {@link PriorityQueue}.
+ * The default comparator orders primitive values in descending order. If you store objects,
+ * you must provide a custom comparator via {@link PriorityQueueOptions}.
+ * @template E Element type stored in the queue.
+ * @template R Extra record/metadata associated with each element.
+ * @example
  */
 export class MaxPriorityQueue<E = any, R = any> extends PriorityQueue<E, R> {
   /**
-   * The constructor initializes a PriorityQueue with optional elements and options, including a
-   * comparator function.
-   * @param elements - The `elements` parameter is an iterable object that contains the initial
-   * elements to be added to the priority queue. It is optional and defaults to an empty array if not
-   * provided.
-   * @param options - The `options` parameter is an object that contains additional configuration
-   * options for the priority queue. In this case, it has a property called `comparator,` which is a
-   * function used to compare elements in the priority queue.
+   * Creates a max-priority queue.
+   * @param elements Optional initial elements to insert.
+   * @param options Optional configuration (e.g., `comparator`, `toElementFn`).
+   * @throws {TypeError} Thrown when using the default comparator with object elements (provide a custom comparator).
+   * @remarks Complexity — Time: O(n log n) when inserting n elements incrementally; Space: O(n).
    */
   constructor(elements: Iterable<E> | Iterable<R> = [], options?: PriorityQueueOptions<E, R>) {
     super(elements, {
@@ -37,81 +39,4 @@ export class MaxPriorityQueue<E = any, R = any> extends PriorityQueue<E, R> {
       ...options
     });
   }
-
-  /**
-   * The `clone` function returns a new instance of the `MaxPriorityQueue` class with the same
-   * comparator and toElementFn as the current instance.
-   * @returns The method is returning a new instance of the MaxPriorityQueue class with the same
-   * comparator and toElementFn as the current instance.
-   */
-  override clone(): MaxPriorityQueue<E, R> {
-    return new MaxPriorityQueue<E, R>(this, { comparator: this.comparator, toElementFn: this.toElementFn });
-  }
-
-  /**
-   * Time Complexity: O(n)
-   * Space Complexity: O(n)
-   *
-   * The `filter` function creates a new MaxPriorityQueue object containing elements that pass a given callback
-   * function.
-   * @param callback - The `callback` parameter is a function that will be called for each element in
-   * the heap. It takes three arguments: the current element, the index of the current element, and the
-   * heap itself. The callback function should return a boolean value indicating whether the current
-   * element should be included in the filtered list
-   * @param {any} [thisArg] - The `thisArg` parameter is an optional argument that specifies the value
-   * to be used as `this` when executing the `callback` function. If `thisArg` is provided, it will be
-   * passed as the `this` value to the `callback` function. If `thisArg` is
-   * @returns The `filter` method is returning a new `MaxPriorityQueue` object that contains the elements that pass
-   * the filter condition specified by the `callback` function.
-   */
-  override filter(callback: ElementCallback<E, R, boolean>, thisArg?: any): MaxPriorityQueue<E, R> {
-    const filteredPriorityQueue = new MaxPriorityQueue<E, R>([], {
-      toElementFn: this.toElementFn,
-      comparator: this.comparator
-    });
-    let index = 0;
-    for (const current of this) {
-      if (callback.call(thisArg, current, index, this)) {
-        filteredPriorityQueue.add(current);
-      }
-      index++;
-    }
-    return filteredPriorityQueue;
-  }
-
-  /**
-   * Time Complexity: O(n log n)
-   * Space Complexity: O(n)
-   *
-   * The `map` function creates a new heap by applying a callback function to each element of the
-   * original heap.
-   * @param callback - The `callback` parameter is a function that will be called for each element in
-   * the heap. It takes three arguments: `el` (the current element), `index` (the index of the current
-   * element), and `this` (the heap itself). The callback function should return a value of
-   * @param comparator - The `comparator` parameter is a function that defines the order of the
-   * elements in the heap. It takes two elements `a` and `b` as arguments and returns a negative number
-   * if `a` should be placed before `b`, a positive number if `a` should be placed after
-   * @param [toElementFn] - The `toElementFn` parameter is an optional function that converts the raw
-   * element `RR` to the desired type `T`. It takes a single argument `rawElement` of type `RR` and
-   * returns a value of type `T`. This function is used to transform the elements of the original
-   * @param {any} [thisArg] - The `thisArg` parameter is an optional argument that allows you to
-   * specify the value of `this` within the callback function. It is used to set the context or scope
-   * in which the callback function will be executed. If `thisArg` is provided, it will be used as the
-   * value of
-   * @returns a new instance of the `MaxPriorityQueue` class with the mapped elements.
-   */
-  override map<EM, RM>(
-    callback: ElementCallback<E, R, EM>,
-    comparator: Comparator<EM>,
-    toElementFn?: (rawElement: RM) => EM,
-    thisArg?: any
-  ): MaxPriorityQueue<EM, RM> {
-    const mappedPriorityQueue = new MaxPriorityQueue<EM, RM>([], { comparator, toElementFn });
-    let index = 0;
-    for (const el of this) {
-      mappedPriorityQueue.add(callback.call(thisArg, el, index, this));
-      index++;
-    }
-    return mappedPriorityQueue;
-  }
 }

package/src/data-structures/priority-queue/min-priority-queue.ts

@@ -5,102 +5,25 @@
  * @copyright Copyright (c) 2022 Kirk Qi <qilinaus@gmail.com>
  * @license MIT License
  */
-import type { Comparator, ElementCallback, PriorityQueueOptions } from '../../types';
+import type { PriorityQueueOptions } from '../../types';
 import { PriorityQueue } from './priority-queue';
 
 /**
- *
+ * Min-oriented priority queue (min-heap) built on {@link PriorityQueue}.
+ * The queue removes the smallest element first under the provided comparator.
+ * Provide a custom comparator if you store non-primitive objects.
+ * @template E Element type stored in the queue.
+ * @template R Extra record/metadata associated with each element.
+ * @example
  */
 export class MinPriorityQueue<E = any, R = any> extends PriorityQueue<E, R> {
   /**
-   * The constructor initializes a PriorityQueue with optional elements and options, including a
-   * comparator function.
-   * @param elements - The `elements` parameter is an iterable object that contains the initial
-   * elements to be added to the priority queue. It is optional and defaults to an empty array if not
-   * provided.
-   * @param options - The `options` parameter is an object that contains additional configuration
-   * options for the priority queue. In this case, it has a property called `comparator,` which is a
-   * function used to compare elements in the priority queue. The `comparator` function takes two
-   * parameters `a` and `b`
+   * Creates a min-priority queue.
+   * @param elements Optional initial elements to insert.
+   * @param options Optional configuration (e.g., `comparator`, `toElementFn`).
+   * @remarks Complexity — Time: O(n log n) when inserting n elements incrementally; Space: O(n).
    */
   constructor(elements: Iterable<E> | Iterable<R> = [], options?: PriorityQueueOptions<E, R>) {
     super(elements, options);
   }
-
-  /**
-   * The `clone` function returns a new instance of the `MinPriorityQueue` class with the same
-   * comparator and toElementFn as the original instance.
-   * @returns The method is returning a new instance of the `MinPriorityQueue` class with the same
-   * properties as the current instance.
-   */
-  override clone(): MinPriorityQueue<E, R> {
-    return new MinPriorityQueue<E, R>(this, { comparator: this.comparator, toElementFn: this.toElementFn });
-  }
-
-  /**
-   * Time Complexity: O(n)
-   * Space Complexity: O(n)
-   *
-   * The `filter` function creates a new MinPriorityQueue object containing elements that pass a given callback
-   * function.
-   * @param callback - The `callback` parameter is a function that will be called for each element in
-   * the heap. It takes three arguments: the current element, the index of the current element, and the
-   * heap itself. The callback function should return a boolean value indicating whether the current
-   * element should be included in the filtered list
-   * @param {any} [thisArg] - The `thisArg` parameter is an optional argument that specifies the value
-   * to be used as `this` when executing the `callback` function. If `thisArg` is provided, it will be
-   * passed as the `this` value to the `callback` function. If `thisArg` is
-   * @returns The `filter` method is returning a new `MinPriorityQueue` object that contains the elements that pass
-   * the filter condition specified by the `callback` function.
-   */
-  override filter(callback: ElementCallback<E, R, boolean>, thisArg?: any): MinPriorityQueue<E, R> {
-    const filteredPriorityQueue = new MinPriorityQueue<E, R>([], {
-      toElementFn: this.toElementFn,
-      comparator: this.comparator
-    });
-    let index = 0;
-    for (const current of this) {
-      if (callback.call(thisArg, current, index, this)) {
-        filteredPriorityQueue.add(current);
-      }
-      index++;
-    }
-    return filteredPriorityQueue;
-  }
-
-  /**
-   * Time Complexity: O(n log n)
-   * Space Complexity: O(n)
-   *
-   * The `map` function creates a new heap by applying a callback function to each element of the
-   * original heap.
-   * @param callback - The `callback` parameter is a function that will be called for each element in
-   * the heap. It takes three arguments: `el` (the current element), `index` (the index of the current
-   * element), and `this` (the heap itself). The callback function should return a value of
-   * @param comparator - The `comparator` parameter is a function that defines the order of the
-   * elements in the heap. It takes two elements `a` and `b` as arguments and returns a negative number
-   * if `a` should be placed before `b`, a positive number if `a` should be placed after
-   * @param [toElementFn] - The `toElementFn` parameter is an optional function that converts the raw
-   * element `RR` to the desired type `T`. It takes a single argument `rawElement` of type `RR` and
-   * returns a value of type `T`. This function is used to transform the elements of the original
-   * @param {any} [thisArg] - The `thisArg` parameter is an optional argument that allows you to
-   * specify the value of `this` within the callback function. It is used to set the context or scope
-   * in which the callback function will be executed. If `thisArg` is provided, it will be used as the
-   * value of
-   * @returns a new instance of the `MinPriorityQueue` class with the mapped elements.
-   */
-  override map<EM, RM>(
-    callback: ElementCallback<E, R, EM>,
-    comparator: Comparator<EM>,
-    toElementFn?: (rawElement: RM) => EM,
-    thisArg?: any
-  ): MinPriorityQueue<EM, RM> {
-    const mappedPriorityQueue: MinPriorityQueue<EM, RM> = new MinPriorityQueue<EM, RM>([], { comparator, toElementFn });
-    let index = 0;
-    for (const el of this) {
-      mappedPriorityQueue.add(callback.call(thisArg, el, index, this));
-      index++;
-    }
-    return mappedPriorityQueue;
-  }
 }

package/src/data-structures/priority-queue/priority-queue.ts

@@ -5,104 +5,15 @@
  * @copyright Copyright (c) 2022 Kirk Qi <qilinaus@gmail.com>
  * @license MIT License
  */
-import type { Comparator, ElementCallback, PriorityQueueOptions } from '../../types';
+
+import type { PriorityQueueOptions } from '../../types';
 import { Heap } from '../heap';
 
 /**
- * 1. Element Priority: In a PriorityQueue, elements are sorted according to their priority. Each dequeue (element removal) operation removes the element with the highest priority. The priority can be determined based on the natural ordering of the elements or through a provided comparator (Comparator).
- * 2. Heap-Based Implementation: PriorityQueue is typically implemented using a binary heap, allowing both insertion and removal operations to be completed in O(log n) time, where n is the number of elements in the queue.
- * 3. Task Scheduling: In systems where tasks need to be processed based on the urgency of tasks rather than the order of arrival.
- * 4. Dijkstra's Algorithm: In shortest path algorithms for graphs, used to select the next shortest edge to visit.
- * 5. Huffman Coding: Used to select the smallest node combination when constructing a Huffman tree.
- * 6. Kth Largest Element in a Data Stream: Used to maintain a min-heap of size K for quickly finding the Kth largest element in stream data
+ * @example
  */
 export class PriorityQueue<E = any, R = any> extends Heap<E, R> {
-  /**
-   * The constructor initializes a priority queue with optional elements and options.
-   * @param elements - The `elements` parameter is an iterable object that contains the initial
-   * elements to be added to the priority queue. It is an optional parameter, and if not provided, the
-   * priority queue will be initialized as empty.
-   * @param [options] - The `options` parameter is an optional object that can be used to customize the
-   * behavior of the priority queue. It can contain the following properties:
-   */
   constructor(elements: Iterable<E> | Iterable<R> = [], options?: PriorityQueueOptions<E, R>) {
     super(elements, options);
   }
-
-  /**
-   * The `clone` function returns a new instance of the `PriorityQueue` class with the same comparator
-   * and toElementFn as the original instance.
-   * @returns The method is returning a new instance of the `PriorityQueue` class with the same
-   * elements and properties as the current instance.
-   */
-  override clone(): PriorityQueue<E, R> {
-    return new PriorityQueue<E, R>(this, { comparator: this.comparator, toElementFn: this.toElementFn });
-  }
-
-  /**
-   * Time Complexity: O(n)
-   * Space Complexity: O(n)
-   *
-   * The `filter` function creates a new PriorityQueue object containing elements that pass a given callback
-   * function.
-   * @param callback - The `callback` parameter is a function that will be called for each element in
-   * the heap. It takes three arguments: the current element, the index of the current element, and the
-   * heap itself. The callback function should return a boolean value indicating whether the current
-   * element should be included in the filtered list
-   * @param {any} [thisArg] - The `thisArg` parameter is an optional argument that specifies the value
-   * to be used as `this` when executing the `callback` function. If `thisArg` is provided, it will be
-   * passed as the `this` value to the `callback` function. If `thisArg` is
-   * @returns The `filter` method is returning a new `PriorityQueue` object that contains the elements that pass
-   * the filter condition specified by the `callback` function.
-   */
-  override filter(callback: ElementCallback<E, R, boolean>, thisArg?: any): PriorityQueue<E, R> {
-    const filteredPriorityQueue = new PriorityQueue<E, R>([], {
-      toElementFn: this.toElementFn,
-      comparator: this.comparator
-    });
-    let index = 0;
-    for (const current of this) {
-      if (callback.call(thisArg, current, index, this)) {
-        filteredPriorityQueue.add(current);
-      }
-      index++;
-    }
-    return filteredPriorityQueue;
-  }
-
-  /**
-   * Time Complexity: O(n log n)
-   * Space Complexity: O(n)
-   *
-   * The `map` function creates a new heap by applying a callback function to each element of the
-   * original heap.
-   * @param callback - The `callback` parameter is a function that will be called for each element in
-   * the heap. It takes three arguments: `el` (the current element), `index` (the index of the current
-   * element), and `this` (the heap itself). The callback function should return a value of
-   * @param comparator - The `comparator` parameter is a function that defines the order of the
-   * elements in the heap. It takes two elements `a` and `b` as arguments and returns a negative number
-   * if `a` should be placed before `b`, a positive number if `a` should be placed after
-   * @param [toElementFn] - The `toElementFn` parameter is an optional function that converts the raw
-   * element `RR` to the desired type `T`. It takes a single argument `rawElement` of type `RR` and
-   * returns a value of type `T`. This function is used to transform the elements of the original
-   * @param {any} [thisArg] - The `thisArg` parameter is an optional argument that allows you to
-   * specify the value of `this` within the callback function. It is used to set the context or scope
-   * in which the callback function will be executed. If `thisArg` is provided, it will be used as the
-   * value of
-   * @returns a new instance of the `PriorityQueue` class with the mapped elements.
-   */
-  override map<EM, RM>(
-    callback: ElementCallback<E, R, EM>,
-    comparator: Comparator<EM>,
-    toElementFn?: (rawElement: RM) => EM,
-    thisArg?: any
-  ): PriorityQueue<EM, RM> {
-    const mappedPriorityQueue: PriorityQueue<EM, RM> = new PriorityQueue<EM, RM>([], { comparator, toElementFn });
-    let index = 0;
-    for (const el of this) {
-      mappedPriorityQueue.add(callback.call(thisArg, el, index, this));
-      index++;
-    }
-    return mappedPriorityQueue;
-  }
 }