linked-list-typed 2.0.4 → 2.1.0

package/dist/data-structures/linked-list/skip-linked-list.d.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 declare class SkipListNode<K, V> {
     key: K;
@@ -12,123 +5,23 @@ export declare class SkipListNode<K, V> {
     forward: SkipListNode<K, V>[];
     constructor(key: K, value: V, level: number);
 }
-/**
- *
- */
 export declare 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);
     protected _head: SkipListNode<K, V>;
-    /**
-     * 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>;
     protected _level: number;
-    /**
-     * The function returns the value of the protected variable _level.
-     * @returns The level property of the object.
-     */
     get level(): number;
     protected _maxLevel: number;
-    /**
-     * The function returns the maximum level.
-     * @returns The value of the variable `_maxLevel` is being returned.
-     */
     get maxLevel(): number;
     protected _probability: number;
-    /**
-     * The function returns the probability value.
-     * @returns The probability value stored in the protected variable `_probability` is being returned.
-     */
     get probability(): number;
-    /**
-     * 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;
-    /**
-     * 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;
-    /**
-     * 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;
-    /**
-     * 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;
-    /**
-     * 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;
-    /**
-     * 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;
-    /**
-     * 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;
-    /**
-     * 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;
-    /**
-     * 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;
 }

package/dist/data-structures/linked-list/skip-linked-list.js

@@ -9,18 +9,7 @@ class SkipListNode {
     }
 }
 exports.SkipListNode = SkipListNode;
-/**
- *
- */
 class SkipList {
-    /**
-     * 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 = [], options) {
         this._head = new SkipListNode(undefined, undefined, this.maxLevel);
         this._level = 0;
@@ -38,52 +27,22 @@ class SkipList {
                 this.add(key, value);
         }
     }
-    /**
-     * 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() {
         return this._head;
     }
-    /**
-     * The function returns the value of the protected variable _level.
-     * @returns The level property of the object.
-     */
     get level() {
         return this._level;
     }
-    /**
-     * The function returns the maximum level.
-     * @returns The value of the variable `_maxLevel` is being returned.
-     */
     get maxLevel() {
         return this._maxLevel;
     }
-    /**
-     * The function returns the probability value.
-     * @returns The probability value stored in the protected variable `_probability` is being returned.
-     */
     get probability() {
         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() {
         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() {
         let current = this.head;
         for (let i = this.level - 1; i >= 0; i--) {
@@ -93,15 +52,6 @@ class SkipList {
         }
         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, value) {
         const newNode = new SkipListNode(key, value, this._randomLevel());
         const update = new Array(this.maxLevel).fill(this.head);
@@ -120,15 +70,6 @@ class SkipList {
             this._level = Math.max(this.level, newNode.forward.length);
         }
     }
-    /**
-     * 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) {
         let current = this.head;
         for (let i = this.level - 1; i >= 0; i--) {
@@ -142,27 +83,9 @@ class SkipList {
         }
         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) {
         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) {
         const update = new Array(this.maxLevel).fill(this.head);
         let current = this.head;
@@ -187,14 +110,6 @@ class SkipList {
         }
         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) {
         let current = this.head;
         for (let i = this.level - 1; i >= 0; i--) {
@@ -205,14 +120,6 @@ class SkipList {
         const nextNode = current.forward[0];
         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) {
         let current = this.head;
         let lastLess = undefined;
@@ -226,13 +133,6 @@ class SkipList {
         }
         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.
-     */
     _randomLevel() {
         let level = 1;
         while (Math.random() < this.probability && level < this.maxLevel) {

package/dist/data-structures/priority-queue/max-priority-queue.d.ts

@@ -5,67 +5,23 @@
  * @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 declare 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>);
-    /**
-     * 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.
-     */
-    clone(): MaxPriorityQueue<E, R>;
-    /**
-     * 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.
-     */
-    filter(callback: ElementCallback<E, R, boolean>, thisArg?: any): MaxPriorityQueue<E, R>;
-    /**
-     * 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.
-     */
-    map<EM, RM>(callback: ElementCallback<E, R, EM>, comparator: Comparator<EM>, toElementFn?: (rawElement: RM) => EM, thisArg?: any): MaxPriorityQueue<EM, RM>;
 }

package/dist/data-structures/priority-queue/max-priority-queue.js

@@ -3,18 +3,20 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.MaxPriorityQueue = void 0;
 const priority_queue_1 = require("./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
  */
 class MaxPriorityQueue extends priority_queue_1.PriorityQueue {
     /**
-     * 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 = [], options) {
         super(elements, Object.assign({ comparator: (a, b) => {
@@ -28,74 +30,5 @@ class MaxPriorityQueue extends priority_queue_1.PriorityQueue {
                 return 0;
             } }, 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.
-     */
-    clone() {
-        return new MaxPriorityQueue(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.
-     */
-    filter(callback, thisArg) {
-        const filteredPriorityQueue = new MaxPriorityQueue([], {
-            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.
-     */
-    map(callback, comparator, toElementFn, thisArg) {
-        const mappedPriorityQueue = new MaxPriorityQueue([], { comparator, toElementFn });
-        let index = 0;
-        for (const el of this) {
-            mappedPriorityQueue.add(callback.call(thisArg, el, index, this));
-            index++;
-        }
-        return mappedPriorityQueue;
-    }
 }
 exports.MaxPriorityQueue = MaxPriorityQueue;

package/dist/data-structures/priority-queue/min-priority-queue.d.ts

@@ -5,68 +5,22 @@
  * @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 declare 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>);
-    /**
-     * 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.
-     */
-    clone(): MinPriorityQueue<E, R>;
-    /**
-     * 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.
-     */
-    filter(callback: ElementCallback<E, R, boolean>, thisArg?: any): MinPriorityQueue<E, R>;
-    /**
-     * 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.
-     */
-    map<EM, RM>(callback: ElementCallback<E, R, EM>, comparator: Comparator<EM>, toElementFn?: (rawElement: RM) => EM, thisArg?: any): MinPriorityQueue<EM, RM>;
 }