data-structure-typed 2.0.0 → 2.0.1

package/dist/individuals/priority-queue/priority-queue.mjs

@@ -0,0 +1,670 @@
+// src/data-structures/base/iterable-element-base.ts
+var IterableElementBase = class {
+  /**
+   * The protected constructor initializes the options for the IterableElementBase class, including the
+   * toElementFn function.
+   * @param [options] - An optional object that contains the following properties:
+   */
+  constructor(options) {
+    if (options) {
+      const { toElementFn } = options;
+      if (typeof toElementFn === "function") this._toElementFn = toElementFn;
+      else if (toElementFn) throw new TypeError("toElementFn must be a function type");
+    }
+  }
+  _toElementFn;
+  get toElementFn() {
+    return this._toElementFn;
+  }
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(1)
+   *
+   * The function is an implementation of the Symbol.iterator method that returns an IterableIterator.
+   * @param {any[]} args - The `args` parameter in the code snippet represents a rest parameter. It
+   * allows the function to accept any number of arguments as an array. In this case, the `args`
+   * parameter is used to pass any number of arguments to the `_getIterator` method.
+   */
+  *[Symbol.iterator](...args) {
+    yield* this._getIterator(...args);
+  }
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(n)
+   *
+   * The function returns an iterator that yields all the values in the object.
+   */
+  *values() {
+    for (const item of this) {
+      yield item;
+    }
+  }
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(1)
+   *
+   * The `every` function checks if every element in the array satisfies a given predicate.
+   * @param predicate - The `predicate` parameter is a callback function that takes three arguments:
+   * the current element being processed, its index, and the array it belongs to. It should return a
+   * boolean value indicating whether the element satisfies a certain condition or not.
+   * @param {any} [thisArg] - The `thisArg` parameter is an optional argument that specifies the value
+   * to be used as `this` when executing the `predicate` function. If `thisArg` is provided, it will be
+   * passed as the `this` value to the `predicate` function. If `thisArg` is
+   * @returns The `every` method is returning a boolean value. It returns `true` if every element in
+   * the array satisfies the provided predicate function, and `false` otherwise.
+   */
+  every(predicate, thisArg) {
+    let index = 0;
+    for (const item of this) {
+      if (!predicate.call(thisArg, item, index++, this)) {
+        return false;
+      }
+    }
+    return true;
+  }
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(1)
+   *
+   * The "some" function checks if at least one element in a collection satisfies a given predicate.
+   * @param predicate - The `predicate` parameter is a callback function that takes three arguments:
+   * `value`, `index`, and `array`. It should return a boolean value indicating whether the current
+   * element satisfies the condition.
+   * @param {any} [thisArg] - The `thisArg` parameter is an optional argument that specifies the value
+   * to be used as the `this` value when executing the `predicate` function. If `thisArg` is provided,
+   * it will be passed as the `this` value to the `predicate` function. If `thisArg
+   * @returns a boolean value. It returns true if the predicate function returns true for any element
+   * in the collection, and false otherwise.
+   */
+  some(predicate, thisArg) {
+    let index = 0;
+    for (const item of this) {
+      if (predicate.call(thisArg, item, index++, this)) {
+        return true;
+      }
+    }
+    return false;
+  }
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(1)
+   *
+   * The `forEach` function iterates over each element in an array-like object and calls a callback
+   * function for each element.
+   * @param callbackfn - The callbackfn parameter is a function that will be called for each element in
+   * the array. It takes three arguments: the current element being processed, the index of the current
+   * element, and the array that forEach was called upon.
+   * @param {any} [thisArg] - The `thisArg` parameter is an optional argument that specifies the value
+   * to be used as `this` when executing the `callbackfn` function. If `thisArg` is provided, it will
+   * be passed as the `this` value to the `callbackfn` function. If `thisArg
+   */
+  forEach(callbackfn, thisArg) {
+    let index = 0;
+    for (const item of this) {
+      callbackfn.call(thisArg, item, index++, this);
+    }
+  }
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(1)
+   *
+   * The `find` function iterates over the elements of an array-like object and returns the first
+   * element that satisfies the provided callback function.
+   * @param predicate - The predicate parameter is a function that will be called for each element in
+   * the array. It takes three arguments: the current element being processed, the index of the current
+   * element, and the array itself. The function should return a boolean value indicating whether the
+   * current element matches the desired condition.
+   * @param {any} [thisArg] - The `thisArg` parameter is an optional argument that specifies the value
+   * to be used as `this` when executing the `callbackfn` function. If `thisArg` is provided, it will
+   * be passed as the `this` value to the `callbackfn` function. If `thisArg
+   * @returns The `find` method returns the first element in the array that satisfies the provided
+   * callback function. If no element satisfies the callback function, `undefined` is returned.
+   */
+  find(predicate, thisArg) {
+    let index = 0;
+    for (const item of this) {
+      if (predicate.call(thisArg, item, index++, this)) return item;
+    }
+    return;
+  }
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(1)
+   *
+   * The function checks if a given element exists in a collection.
+   * @param {E} element - The parameter "element" is of type E, which means it can be any type. It
+   * represents the element that we want to check for existence in the collection.
+   * @returns a boolean value. It returns true if the element is found in the collection, and false
+   * otherwise.
+   */
+  has(element) {
+    for (const ele of this) {
+      if (ele === element) return true;
+    }
+    return false;
+  }
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(1)
+   *
+   * The `reduce` function iterates over the elements of an array-like object and applies a callback
+   * function to reduce them into a single value.
+   * @param callbackfn - The callbackfn parameter is a function that will be called for each element in
+   * the array. It takes four arguments:
+   * @param {U} initialValue - The initialValue parameter is the initial value of the accumulator. It
+   * is the value that the accumulator starts with before the reduction operation begins.
+   * @returns The `reduce` method is returning the final value of the accumulator after iterating over
+   * all the elements in the array and applying the callback function to each element.
+   */
+  reduce(callbackfn, initialValue) {
+    let accumulator = initialValue ?? 0;
+    let index = 0;
+    for (const item of this) {
+      accumulator = callbackfn(accumulator, item, index++, this);
+    }
+    return accumulator;
+  }
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(n)
+   *
+   * The `toArray` function converts a linked list into an array.
+   * @returns The `toArray()` method is returning an array of type `E[]`.
+   */
+  toArray() {
+    return [...this];
+  }
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(n)
+   *
+   * The print function logs the elements of an array to the console.
+   */
+  toVisual() {
+    return [...this];
+  }
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(n)
+   *
+   * The print function logs the elements of an array to the console.
+   */
+  print() {
+    console.log(this.toVisual());
+  }
+};
+
+// src/data-structures/heap/heap.ts
+var Heap = class _Heap extends IterableElementBase {
+  /**
+   * The constructor initializes a heap data structure with optional elements and options.
+   * @param elements - The `elements` parameter is an iterable object that contains the initial
+   * elements to be added to the heap.
+   * It is an optional parameter, and if not provided, the heap will
+   * be initialized as empty.
+   * @param [options] - The `options` parameter is an optional object that can contain additional
+   * configuration options for the heap.
+   * In this case, it is used to specify a custom comparator
+   * function for comparing elements in the heap.
+   * The comparator function is used to determine the
+   * order of elements in the heap.
+   */
+  constructor(elements = [], options) {
+    super(options);
+    if (options) {
+      const { comparator } = options;
+      if (comparator) this._comparator = comparator;
+    }
+    this.addMany(elements);
+  }
+  _elements = [];
+  /**
+   * The function returns an array of elements.
+   * @returns The element array is being returned.
+   */
+  get elements() {
+    return this._elements;
+  }
+  /**
+   * Get the size (number of elements) of the heap.
+   */
+  get size() {
+    return this.elements.length;
+  }
+  /**
+   * Get the last element in the heap, which is not necessarily a leaf node.
+   * @returns The last element or undefined if the heap is empty.
+   */
+  get leaf() {
+    return this.elements[this.size - 1] ?? void 0;
+  }
+  /**
+   * Static method that creates a binary heap from an array of elements and a comparison function.
+   * @returns A new Heap instance.
+   * @param elements
+   * @param options
+   */
+  static heapify(elements, options) {
+    return new _Heap(elements, options);
+  }
+  /**
+   * Time Complexity: O(log n)
+   * Space Complexity: O(1)
+   *
+   * The add function pushes an element into an array and then triggers a bubble-up operation.
+   * @param {E} element - The `element` parameter represents the element that you want to add to the
+   * data structure.
+   * @returns The `add` method is returning a boolean value, which is the result of calling the
+   * `_bubbleUp` method with the index `this.elements.length - 1` as an argument.
+   */
+  add(element) {
+    this._elements.push(element);
+    return this._bubbleUp(this.elements.length - 1);
+  }
+  /**
+   * Time Complexity: O(k log n)
+   * Space Complexity: O(1)
+   *
+   * The `addMany` function iterates over elements and adds them to a collection, returning an array of
+   * boolean values indicating success or failure.
+   * @param {Iterable<E> | Iterable<R>} elements - The `elements` parameter in the `addMany` method is
+   * an iterable containing elements of type `E` or `R`. The method iterates over each element in the
+   * iterable and adds them to the data structure. If a transformation function `_toElementFn` is
+   * provided, it transforms the element
+   * @returns The `addMany` method returns an array of boolean values indicating whether each element
+   * in the input iterable was successfully added to the data structure.
+   */
+  addMany(elements) {
+    const ans = [];
+    for (const el of elements) {
+      if (this._toElementFn) {
+        ans.push(this.add(this._toElementFn(el)));
+        continue;
+      }
+      ans.push(this.add(el));
+    }
+    return ans;
+  }
+  /**
+   * Time Complexity: O(log n)
+   * Space Complexity: O(1)
+   *
+   * Remove and return the top element (the smallest or largest element) from the heap.
+   * @returns The top element or undefined if the heap is empty.
+   */
+  poll() {
+    if (this.elements.length === 0) return;
+    const value = this.elements[0];
+    const last = this.elements.pop();
+    if (this.elements.length) {
+      this.elements[0] = last;
+      this._sinkDown(0, this.elements.length >> 1);
+    }
+    return value;
+  }
+  /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   *
+   * Peek at the top element of the heap without removing it.
+   * @returns The top element or undefined if the heap is empty.
+   */
+  peek() {
+    return this.elements[0];
+  }
+  /**
+   * Check if the heap is empty.
+   * @returns True if the heap is empty, otherwise false.
+   */
+  isEmpty() {
+    return this.size === 0;
+  }
+  /**
+   * Reset the elements of the heap. Make the elements empty.
+   */
+  clear() {
+    this._elements = [];
+  }
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(n)
+   *
+   * Clear and add elements of the heap
+   * @param elements
+   */
+  refill(elements) {
+    this._elements = elements;
+    return this.fix();
+  }
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(1)
+   *
+   * Use a comparison function to check whether a binary heap contains a specific element.
+   * @param element - the element to check.
+   * @returns Returns true if the specified element is contained; otherwise, returns false.
+   */
+  has(element) {
+    return this.elements.includes(element);
+  }
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(1)
+   *
+   * The `delete` function removes an element from an array-like data structure, maintaining the order
+   * and structure of the remaining elements.
+   * @param {E} element - The `element` parameter represents the element that you want to delete from
+   * the array `this.elements`.
+   * @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) {
+    const index = this.elements.indexOf(element);
+    if (index < 0) return false;
+    if (index === 0) {
+      this.poll();
+    } else if (index === this.elements.length - 1) {
+      this.elements.pop();
+    } else {
+      this.elements.splice(index, 1, this.elements.pop());
+      this._bubbleUp(index);
+      this._sinkDown(index, this.elements.length >> 1);
+    }
+    return true;
+  }
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(log n)
+   *
+   * Depth-first search (DFS) method, different traversal orders can be selected。
+   * @param order - Traverse order parameter: 'IN' (in-order), 'PRE' (pre-order) or 'POST' (post-order).
+   * @returns An array containing elements traversed in the specified order.
+   */
+  dfs(order = "PRE") {
+    const result = [];
+    const _dfs = (index) => {
+      const left = 2 * index + 1, right = left + 1;
+      if (index < this.size) {
+        if (order === "IN") {
+          _dfs(left);
+          result.push(this.elements[index]);
+          _dfs(right);
+        } else if (order === "PRE") {
+          result.push(this.elements[index]);
+          _dfs(left);
+          _dfs(right);
+        } else if (order === "POST") {
+          _dfs(left);
+          _dfs(right);
+          result.push(this.elements[index]);
+        }
+      }
+    };
+    _dfs(0);
+    return result;
+  }
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(n)
+   *
+   * Clone the heap, creating a new heap with the same elements.
+   * @returns A new Heap instance containing the same elements.
+   */
+  clone() {
+    return new _Heap(this, { comparator: this.comparator, toElementFn: this.toElementFn });
+  }
+  /**
+   * Time Complexity: O(n log n)
+   * Space Complexity: O(n)
+   *
+   * Sort the elements in the heap and return them as an array.
+   * @returns An array containing the elements sorted in ascending order.
+   */
+  sort() {
+    const visitedNode = [];
+    const cloned = new _Heap(this, { comparator: this.comparator });
+    while (cloned.size !== 0) {
+      const top = cloned.poll();
+      if (top !== void 0) visitedNode.push(top);
+    }
+    return visitedNode;
+  }
+  /**
+   * Time Complexity: O(n log n)
+   * Space Complexity: O(n)
+   *
+   * Fix the entire heap to maintain heap properties.
+   */
+  fix() {
+    const results = [];
+    for (let i = Math.floor(this.size / 2); i >= 0; i--) results.push(this._sinkDown(i, this.elements.length >> 1));
+    return results;
+  }
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(n)
+   *
+   * The `filter` function creates a new Heap 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 `Heap` object that contains the elements that pass
+   * the filter condition specified by the `callback` function.
+   */
+  filter(callback, thisArg) {
+    const filteredList = new _Heap([], { toElementFn: this.toElementFn, comparator: this.comparator });
+    let index = 0;
+    for (const current of this) {
+      if (callback.call(thisArg, current, index, this)) {
+        filteredList.add(current);
+      }
+      index++;
+    }
+    return filteredList;
+  }
+  /**
+   * Time Complexity: O(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 `Heap` class with the mapped elements.
+   */
+  map(callback, comparator, toElementFn, thisArg) {
+    const mappedHeap = new _Heap([], { comparator, toElementFn });
+    let index = 0;
+    for (const el of this) {
+      mappedHeap.add(callback.call(thisArg, el, index, this));
+      index++;
+    }
+    return mappedHeap;
+  }
+  _DEFAULT_COMPARATOR = (a, b) => {
+    if (typeof a === "object" || typeof b === "object") {
+      throw TypeError(
+        `When comparing object types, a custom comparator must be defined in the constructor's options parameter.`
+      );
+    }
+    if (a > b) return 1;
+    if (a < b) return -1;
+    return 0;
+  };
+  _comparator = this._DEFAULT_COMPARATOR;
+  /**
+   * The function returns the value of the _comparator property.
+   * @returns The `_comparator` property is being returned.
+   */
+  get comparator() {
+    return this._comparator;
+  }
+  /**
+   * The function `_getIterator` returns an iterable iterator for the elements in the class.
+   */
+  *_getIterator() {
+    for (const element of this.elements) {
+      yield element;
+    }
+  }
+  /**
+   * Time Complexity: O(log n)
+   * Space Complexity: O(1)
+   *
+   * Float operation to maintain heap properties after adding an element.
+   * @param index - The index of the newly added element.
+   */
+  _bubbleUp(index) {
+    const element = this.elements[index];
+    while (index > 0) {
+      const parent = index - 1 >> 1;
+      const parentItem = this.elements[parent];
+      if (this.comparator(parentItem, element) <= 0) break;
+      this.elements[index] = parentItem;
+      index = parent;
+    }
+    this.elements[index] = element;
+    return true;
+  }
+  /**
+   * Time Complexity: O(log n)
+   * Space Complexity: O(1)
+   *
+   * Sinking operation to maintain heap properties after removing the top element.
+   * @param index - The index from which to start sinking.
+   * @param halfLength
+   */
+  _sinkDown(index, halfLength) {
+    const element = this.elements[index];
+    while (index < halfLength) {
+      let left = index << 1 | 1;
+      const right = left + 1;
+      let minItem = this.elements[left];
+      if (right < this.elements.length && this.comparator(minItem, this.elements[right]) > 0) {
+        left = right;
+        minItem = this.elements[right];
+      }
+      if (this.comparator(minItem, element) >= 0) break;
+      this.elements[index] = minItem;
+      index = left;
+    }
+    this.elements[index] = element;
+    return true;
+  }
+};
+
+// src/data-structures/priority-queue/priority-queue.ts
+var PriorityQueue = class _PriorityQueue extends Heap {
+  /**
+   * 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 = [], options) {
+    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.
+   */
+  clone() {
+    return new _PriorityQueue(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.
+   */
+  filter(callback, thisArg) {
+    const filteredPriorityQueue = new _PriorityQueue([], {
+      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.
+   */
+  map(callback, comparator, toElementFn, thisArg) {
+    const mappedPriorityQueue = new _PriorityQueue([], { comparator, toElementFn });
+    let index = 0;
+    for (const el of this) {
+      mappedPriorityQueue.add(callback.call(thisArg, el, index, this));
+      index++;
+    }
+    return mappedPriorityQueue;
+  }
+};
+export {
+  PriorityQueue
+};
+/**
+ * data-structure-typed
+ * @author Kirk Qi
+ * @copyright Copyright (c) 2022 Kirk Qi <qilinaus@gmail.com>
+ * @license MIT License
+ */
+/**
+ * data-structure-typed
+ *
+ * @author Kirk Qi
+ * @copyright Copyright (c) 2022 Kirk Qi <qilinaus@gmail.com>
+ * @license MIT License
+ */