data-structure-typed 1.35.0 → 1.36.0

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

@@ -1,212 +1,254 @@
 /**
  * data-structure-typed
  *
- * @author Tyler Zeng
- * @copyright Copyright (c) 2022 Tyler Zeng <zrwusa@gmail.com>
+ * @author Kirk Qi
+ * @copyright Copyright (c) 2022 Kirk Qi <qilinaus@gmail.com>
  * @license MIT License
  */
-import {PriorityQueue} from '../priority-queue';
-import type {HeapOptions} from '../../types';
 
-export class HeapItem<V = any> {
-  /**
-   * The constructor function initializes an instance of a class with a priority and a value.
-   * @param {number} priority - The `priority` parameter is a number that represents the priority of the value. It is
-   * optional and has a default value of `NaN`.
-   * @param {V | null} [val=null] - The `val` parameter is of type `V | null`, which means it can accept a value of type
-   * `V` or `null`.
-   */
-  constructor(priority: number = Number.MAX_SAFE_INTEGER, val: V | null = null) {
-    this._val = val;
-    this._priority = priority;
-  }
+import type {CompareFunction} from '../../types';
 
-  private _priority: number;
+export class Heap<T> {
+  private nodes: T[] = [];
+  private readonly comparator: CompareFunction<T>;
 
-  get priority(): number {
-    return this._priority;
+  constructor(comparator: CompareFunction<T>) {
+    this.comparator = comparator;
   }
 
-  set priority(value: number) {
-    this._priority = value;
+  /**
+   * Insert an element into the heap and maintain the heap properties.
+   * @param value - The element to be inserted.
+   */
+  add(value: T): Heap<T> {
+    this.nodes.push(value);
+    this.bubbleUp(this.nodes.length - 1);
+    return this;
   }
 
-  private _val: V | null;
+  /**
+   * Remove and return the top element (smallest or largest element) from the heap.
+   * @returns The top element or null if the heap is empty.
+   */
+  poll(): T | null {
+    if (this.nodes.length === 0) {
+      return null;
+    }
+    if (this.nodes.length === 1) {
+      return this.nodes.pop() as T;
+    }
 
-  get val(): V | null {
-    return this._val;
+    const topValue = this.nodes[0];
+    this.nodes[0] = this.nodes.pop() as T;
+    this.sinkDown(0);
+    return topValue;
   }
 
-  set val(value: V | null) {
-    this._val = value;
-  }
-}
-
-export abstract class Heap<V = any> {
   /**
-   * The function is a constructor for a class that initializes a priority callback function based on the
-   * options provided.
-   * @param [options] - An optional object that contains configuration options for the Heap.
+   * Float operation to maintain heap properties after adding an element.
+   * @param index - The index of the newly added element.
    */
-  protected constructor(options?: HeapOptions<V>) {
-    if (options) {
-      const {priorityExtractor} = options;
-      if (priorityExtractor !== undefined && typeof priorityExtractor !== 'function') {
-        throw new Error('.constructor expects a valid priority function');
+  protected bubbleUp(index: number): void {
+    const element = this.nodes[index];
+    while (index > 0) {
+      const parentIndex = Math.floor((index - 1) / 2);
+      const parent = this.nodes[parentIndex];
+      if (this.comparator(element, parent) < 0) {
+        this.nodes[index] = parent;
+        this.nodes[parentIndex] = element;
+        index = parentIndex;
+      } else {
+        break;
       }
-      this._priorityExtractor = priorityExtractor || (el => +el);
-    } else {
-      this._priorityExtractor = el => +el;
     }
   }
 
-  protected abstract _pq: PriorityQueue<HeapItem<V>>;
+  /**
+   * Sinking operation to maintain heap properties after removing the top element.
+   * @param index - The index from which to start sinking.
+   */
+  protected sinkDown(index: number): void {
+    const leftChildIndex = 2 * index + 1;
+    const rightChildIndex = 2 * index + 2;
+    const length = this.nodes.length;
+    let targetIndex = index;
+
+    if (leftChildIndex < length && this.comparator(this.nodes[leftChildIndex], this.nodes[targetIndex]) < 0) {
+      targetIndex = leftChildIndex;
+    }
+    if (rightChildIndex < length && this.comparator(this.nodes[rightChildIndex], this.nodes[targetIndex]) < 0) {
+      targetIndex = rightChildIndex;
+    }
 
-  get pq() {
-    return this._pq;
+    if (targetIndex !== index) {
+      const temp = this.nodes[index];
+      this.nodes[index] = this.nodes[targetIndex];
+      this.nodes[targetIndex] = temp;
+      this.sinkDown(targetIndex);
+    }
   }
 
-  protected _priorityExtractor: (val: V) => number;
-  get priorityExtractor() {
-    return this._priorityExtractor;
+  /**
+   * Fix the entire heap to maintain heap properties.
+   */
+  protected fix() {
+    for (let i = Math.floor(this.size / 2); i >= 0; i--) this.sinkDown(i);
   }
 
   /**
-   * The function returns the size of a priority queue.
-   * @returns The size of the priority queue.
+   * Peek at the top element of the heap without removing it.
+   * @returns The top element or null if the heap is empty.
    */
-  get size(): number {
-    return this._pq.size;
+  peek(): T | null {
+    if (this.nodes.length === 0) {
+      return null;
+    }
+    return this.nodes[0];
   }
 
   /**
-   * The function checks if a priority queue is empty.
-   * @returns {boolean} A boolean value indicating whether the size of the priority queue is less than 1.
+   * Get the size (number of elements) of the heap.
    */
-  isEmpty(): boolean {
-    return this._pq.size < 1;
+  get size(): number {
+    return this.nodes.length;
   }
 
-  peek(isItem?: undefined): V | undefined;
-  peek(isItem: false): V | undefined;
-  peek(isItem: true): HeapItem<V> | null;
+  /**
+   * Get the last element in the heap, which is not necessarily a leaf node.
+   * @returns The last element or null if the heap is empty.
+   */
+  leaf(): T | null {
+    return this.nodes[this.size - 1] ?? null;
+  }
 
   /**
-   * The `peek` function returns the top item in the priority queue without removing it.
-   * @returns The `peek()` method is returning either a `HeapItem<V>` object or `null`.Returns an val with the highest priority in the queue
+   * Check if the heap is empty.
+   * @returns True if the heap is empty, otherwise false.
    */
-  peek(isItem?: boolean): HeapItem<V> | null | V | undefined {
-    isItem = isItem ?? false;
-    const peeked = this._pq.peek();
+  isEmpty() {
+    return this.size === 0;
+  }
 
-    return isItem ? peeked : peeked?.val;
+  clear() {
+    this.nodes = [];
   }
 
-  peekLast(isItem?: undefined): V | undefined;
-  peekLast(isItem: false): V | undefined;
-  peekLast(isItem: true): HeapItem<V> | null;
+  refill(nodes: T[]) {
+    this.nodes = nodes;
+    this.fix();
+  }
 
   /**
-   * The `peekLast` function returns the last item in the heap.
-   * @returns The method `peekLast()` returns either a `HeapItem<V>` object or `null`.Returns an val with the lowest priority in the queue
+   * Use a comparison function to check whether a binary heap contains a specific element.
+   * @param value - the element to check.
+   * @returns Returns true if the specified element is contained; otherwise, returns false.
    */
-  peekLast(isItem?: boolean): HeapItem<V> | null | V | undefined {
-    isItem = isItem ?? false;
-    const leafItem = this._pq.leaf();
-
-    return isItem ? leafItem : leafItem?.val;
+  has(value: T): boolean {
+    return this.nodes.includes(value);
   }
 
   /**
-   * The `add` function adds an val to a priority queue with an optional priority value.
-   * @param {V} val - The `val` parameter represents the value that you want to add to the heap. It can be of any
-   * type.
-   * @param {number} [priority] - The `priority` parameter is an optional number that represents the priority of the
-   * val being added to the heap. If the `val` parameter is a number, then the `priority` parameter is set to
-   * the value of `val`. If the `val` parameter is not a number, then the
-   * @returns The `add` method returns the instance of the `Heap` class.
-   * @throws {Error} if priority is not a valid number
+   * Use a comparison function to find the index of an element in the heap.
+   * @param value - the element to find.
+   * @param index - the index currently being searched.
+   * @returns The index of the element, or -1 if not found.
    */
-  add(priority: number, val?: V): Heap<V> {
-    val = val === undefined ? (priority as unknown as V) : val;
-    this._pq.add(new HeapItem<V>(priority, val));
+  private findIndex(value: T, index: number): number {
+    if (index >= this.size) {
+      return -1;
+    }
 
-    return this;
-  }
+    const compareResult = this.comparator(value, this.nodes[index]);
 
-  poll(isItem?: undefined): V | undefined;
-  poll(isItem: false): V | undefined;
-  poll(isItem: true): HeapItem<V> | null;
+    if (compareResult === 0) {
+      return index; // Element found
+    } else if (compareResult < 0) {
+      // The element should be in the left subtree
+      return this.findIndex(value, 2 * index + 1);
+    } else {
+      // The element should be in the right subtree
+      return this.findIndex(value, 2 * index + 2);
+    }
+  }
 
   /**
-   * The `poll` function returns the top item from a priority queue or null if the queue is empty.Removes and returns an val with the highest priority in the queue
-   * @returns either a HeapItem<V> object or null.
+   * Depth-first search (DFS) method, different traversal orders can be selected。
+   * @param order - Traversal order parameter: 'in' (in-order), 'pre' (pre-order) or 'post' (post-order).
+   * @returns An array containing elements traversed in the specified order.
    */
-  poll(isItem?: boolean): HeapItem<V> | null | V | undefined {
-    isItem = isItem ?? false;
-    const top = this._pq.poll();
-    if (!top) {
-      return null;
-    }
+  dfs(order: 'in' | 'pre' | 'post'): T[] {
+    const result: T[] = [];
+
+    // Auxiliary recursive function, traverses the binary heap according to the traversal order
+    const dfsHelper = (index: number) => {
+      if (index < this.size) {
+        if (order === 'in') {
+          dfsHelper(2 * index + 1);
+          result.push(this.nodes[index]);
+          dfsHelper(2 * index + 2);
+        } else if (order === 'pre') {
+          result.push(this.nodes[index]);
+          dfsHelper(2 * index + 1);
+          dfsHelper(2 * index + 2);
+        } else if (order === 'post') {
+          dfsHelper(2 * index + 1);
+          dfsHelper(2 * index + 2);
+          result.push(this.nodes[index]);
+        }
+      }
+    };
+
+    dfsHelper(0); // Traverse starting from the root node
 
-    return isItem ? top : top.val;
+    return result;
   }
 
   /**
-   * The function checks if a given node or value exists in the priority queue.
-   * @param {V | HeapItem<V>} node - The parameter `node` can be of type `V` or `HeapItem<V>`.
-   * @returns a boolean value.
+   * Convert the heap to an array.
+   * @returns An array containing the elements of the heap.
    */
-  has(node: V | HeapItem<V>): boolean {
-    if (node instanceof HeapItem) {
-      return this.pq.getNodes().includes(node);
-    } else {
-      return (
-        this.pq.getNodes().findIndex(item => {
-          return item.val === node;
-        }) !== -1
-      );
-    }
+  toArray(): T[] {
+    return [...this.nodes];
   }
 
-  toArray(isItem?: undefined): (V | undefined)[];
-  toArray(isItem: false): (V | undefined)[];
-  toArray(isItem: true): (HeapItem<V> | null)[];
+  getNodes(): T[] {
+    return this.nodes;
+  }
 
   /**
-   * The `toArray` function returns an array of `HeapItem<V>` objects.
-   * @returns An array of HeapItem<V> objects.Returns a sorted list of vals
+   * Clone the heap, creating a new heap with the same elements.
+   * @returns A new Heap instance containing the same elements.
    */
-  toArray(isItem?: boolean): (HeapItem<V> | null | V | undefined)[] {
-    isItem = isItem ?? false;
-    const itemArray = this._pq.toArray();
-
-    return isItem ? itemArray : itemArray.map(item => item.val);
+  clone(): Heap<T> {
+    const clonedHeap = new Heap<T>(this.comparator);
+    clonedHeap.nodes = [...this.nodes];
+    return clonedHeap;
   }
 
-  sort(isItem?: undefined): (V | undefined)[];
-  sort(isItem: false): (V | undefined)[];
-  sort(isItem: true): (HeapItem<V> | null)[];
-
   /**
-   * The function sorts the elements in the priority queue and returns either the sorted items or their values depending
-   * on the value of the isItem parameter.
-   * @param {boolean} [isItem] - The `isItem` parameter is a boolean flag that indicates whether the sorted result should
-   * be an array of `HeapItem<V>` objects or an array of the values (`V`) of those objects. If `isItem` is `true`, the
-   * sorted result will be an array of `HeapItem
-   * @returns an array of either `HeapItem<V>`, `null`, `V`, or `undefined` values.
+   * Sort the elements in the heap and return them as an array.
+   * @returns An array containing the elements sorted in ascending order.
    */
-  sort(isItem?: boolean): (HeapItem<V> | null | V | undefined)[] {
-    isItem = isItem ?? false;
-    const sorted = this._pq.sort();
-
-    return isItem ? sorted : sorted.map(item => item.val);
+  sort(): T[] {
+    const visitedNode: T[] = [];
+    const cloned = this.clone();
+    while (cloned.size !== 0) {
+      const top = cloned.poll();
+      if (top) visitedNode.push(top);
+    }
+    return visitedNode;
   }
 
   /**
-   * The clear function clears the priority queue.
+   * Static method that creates a binary heap from an array of nodes and a comparison function.
+   * @param nodes
+   * @param comparator - Comparison function.
+   * @returns A new Heap instance.
    */
-  clear(): void {
-    this._pq.clear();
+  static heapify<T>(nodes: T[], comparator: CompareFunction<T>): Heap<T> {
+    const binaryHeap = new Heap<T>(comparator);
+    binaryHeap.nodes = [...nodes];
+    binaryHeap.fix(); // Fix heap properties
+    return binaryHeap;
   }
 }

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

@@ -1,31 +1,24 @@
 /**
  * data-structure-typed
  *
- * @author Tyler Zeng
- * @copyright Copyright (c) 2022 Tyler Zeng <zrwusa@gmail.com>
+ * @author Kirk Qi
+ * @copyright Copyright (c) 2022 Kirk Qi <qilinaus@gmail.com>
  * @license MIT License
  */
 
-import {Heap, HeapItem} from './heap';
-import {PriorityQueue} from '../priority-queue';
-import type {HeapOptions} from '../../types';
+import {Heap} from './heap';
+import type {CompareFunction} from '../../types';
 
-/**
- * @class MaxHeap
- * @extends Heap
- */
-export class MaxHeap<V = any> extends Heap<V> {
-  protected _pq: PriorityQueue<HeapItem<V>>;
-
-  /**
-   * The constructor initializes a PriorityQueue with a custom comparator function.
-   * @param [options] - The `options` parameter is an optional object that can be passed to the constructor. It is of
-   * type `HeapOptions<V>`, which is a generic type that represents the options for the heap.
-   */
-  constructor(options?: HeapOptions<V>) {
-    super(options);
-    this._pq = new PriorityQueue<HeapItem<V>>({
-      comparator: (a, b) => b.priority - a.priority
-    });
+export class MaxHeap<T = any> extends Heap<T> {
+  constructor(
+    comparator: CompareFunction<T> = (a: T, b: T) => {
+      if (!(typeof a === 'number' && typeof b === 'number')) {
+        throw new Error('The a, b params of compare function must be number');
+      } else {
+        return b - a;
+      }
+    }
+  ) {
+    super(comparator);
   }
 }

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

@@ -1,32 +1,24 @@
 /**
  * data-structure-typed
  *
- * @author Tyler Zeng
- * @copyright Copyright (c) 2022 Tyler Zeng <zrwusa@gmail.com>
+ * @author Kirk Qi
+ * @copyright Copyright (c) 2022 Kirk Qi <qilinaus@gmail.com>
  * @license MIT License
  */
 
-import {Heap, HeapItem} from './heap';
-import {PriorityQueue} from '../priority-queue';
-import type {HeapOptions} from '../../types';
+import {Heap} from './heap';
+import type {CompareFunction} from '../../types';
 
-/**
- * @class MinHeap
- * @extends Heap
- */
-export class MinHeap<V = any> extends Heap<V> {
-  protected _pq: PriorityQueue<HeapItem<V>>;
-
-  /**
-   * The constructor initializes a PriorityQueue with a comparator function that compares the priority of two HeapItem
-   * objects.
-   * @param [options] - The `options` parameter is an optional object that can be passed to the constructor. It is of
-   * type `HeapOptions<V>`, which is a generic type that represents the options for the heap.
-   */
-  constructor(options?: HeapOptions<V>) {
-    super(options);
-    this._pq = new PriorityQueue<HeapItem<V>>({
-      comparator: (a, b) => a.priority - b.priority
-    });
+export class MinHeap<T = any> extends Heap<T> {
+  constructor(
+    comparator: CompareFunction<T> = (a: T, b: T) => {
+      if (!(typeof a === 'number' && typeof b === 'number')) {
+        throw new Error('The a, b params of compare function must be number');
+      } else {
+        return a - b;
+      }
+    }
+  ) {
+    super(comparator);
   }
 }

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

@@ -1,56 +1,23 @@
 /**
  * data-structure-typed
  *
- * @author Tyler Zeng
- * @copyright Copyright (c) 2022 Tyler Zeng <zrwusa@gmail.com>
+ * @author Kirk Qi
+ * @copyright Copyright (c) 2022 Kirk Qi <qilinaus@gmail.com>
  * @license MIT License
  */
 import {PriorityQueue} from './priority-queue';
-import type {PriorityQueueOptions, SpecifyOptional} from '../../types';
+import type {CompareFunction} from '../../types';
 
-export class MaxPriorityQueue<E = any> extends PriorityQueue<E> {
-  constructor(options?: Omit<PriorityQueueOptions<number>, 'comparator'>);
-  constructor(options: PriorityQueueOptions<E>);
-
-  /**
-   * The constructor initializes a priority queue with an optional comparator function.
-   * @param [options] - The `options` parameter is an optional object that can contain various properties to configure
-   * the priority queue.
-   */
-  constructor(options?: SpecifyOptional<PriorityQueueOptions<E>, 'comparator'>) {
-    super({
-      ...options,
-      comparator: options?.comparator
-        ? options.comparator
-        : (a: E, b: E) => {
-            const aKey = a as unknown as number,
-              bKey = b as unknown as number;
-            return bKey - aKey;
-          }
-    });
-  }
-
-  static override heapify<E extends number>(options?: Omit<PriorityQueueOptions<E>, 'comparator'>): MaxPriorityQueue<E>;
-  static override heapify<E>(options: PriorityQueueOptions<E>): MaxPriorityQueue<E>;
-
-  /**
-   * The function `heapify` creates a max priority queue from the given options and returns it.
-   * @param options - The `options` parameter is an object that contains configuration options for creating a priority
-   * queue. It can have the following properties:
-   * @returns a MaxPriorityQueue object.
-   */
-  static override heapify<E>(options: PriorityQueueOptions<E>): MaxPriorityQueue<E> {
-    const maxPQ = new MaxPriorityQueue<E>({
-      ...options,
-      comparator: options?.comparator
-        ? options.comparator
-        : (a: E, b: E) => {
-            const aKey = a as unknown as number,
-              bKey = b as unknown as number;
-            return bKey - aKey;
-          }
-    });
-    maxPQ._fix();
-    return maxPQ;
+export class MaxPriorityQueue<T = any> extends PriorityQueue<T> {
+  constructor(
+    compare: CompareFunction<T> = (a: T, b: T) => {
+      if (!(typeof a === 'number' && typeof b === 'number')) {
+        throw new Error('The a, b params of compare function must be number');
+      } else {
+        return b - a;
+      }
+    }
+  ) {
+    super(compare);
   }
 }

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

@@ -1,57 +1,23 @@
 /**
  * data-structure-typed
  *
- * @author Tyler Zeng
- * @copyright Copyright (c) 2022 Tyler Zeng <zrwusa@gmail.com>
+ * @author Kirk Qi
+ * @copyright Copyright (c) 2022 Kirk Qi <qilinaus@gmail.com>
  * @license MIT License
  */
 import {PriorityQueue} from './priority-queue';
-import type {PriorityQueueOptions, SpecifyOptional} from '../../types';
+import type {CompareFunction} from '../../types';
 
-export class MinPriorityQueue<E = any> extends PriorityQueue<E> {
-  constructor(options?: Omit<PriorityQueueOptions<number>, 'comparator'>);
-  constructor(options: PriorityQueueOptions<E>);
-
-  /**
-   * The constructor initializes a priority queue with an optional comparator function.
-   * @param [options] - The `options` parameter is an optional object that can contain various configuration options for
-   * the `PriorityQueue` constructor.
-   */
-  constructor(options?: SpecifyOptional<PriorityQueueOptions<E>, 'comparator'>) {
-    super({
-      ...options,
-      comparator: options?.comparator
-        ? options.comparator
-        : (a: E, b: E) => {
-            const aKey = a as unknown as number,
-              bKey = b as unknown as number;
-            return aKey - bKey;
-          }
-    });
-  }
-
-  static override heapify<E extends number>(options?: Omit<PriorityQueueOptions<E>, 'comparator'>): MinPriorityQueue<E>;
-  static override heapify<E>(options: PriorityQueueOptions<E>): MinPriorityQueue<E>;
-
-  /**
-   * The function `heapify` creates a new MinPriorityQueue instance and sets the comparator function based on the options
-   * provided, and then fixes the heap structure of the queue.
-   * @param options - The `options` parameter is an object that contains configuration options for creating a priority
-   * queue. It can have the following properties:
-   * @returns a MinPriorityQueue object.
-   */
-  static override heapify<E>(options: PriorityQueueOptions<E>): MinPriorityQueue<E> {
-    const minPQ = new MinPriorityQueue<E>({
-      ...options,
-      comparator: options?.comparator
-        ? options.comparator
-        : (a: E, b: E) => {
-            const aKey = a as unknown as number,
-              bKey = b as unknown as number;
-            return aKey - bKey;
-          }
-    });
-    minPQ._fix();
-    return minPQ;
+export class MinPriorityQueue<T = any> extends PriorityQueue<T> {
+  constructor(
+    compare: CompareFunction<T> = (a: T, b: T) => {
+      if (!(typeof a === 'number' && typeof b === 'number')) {
+        throw new Error('The a, b params of compare function must be number');
+      } else {
+        return a - b;
+      }
+    }
+  ) {
+    super(compare);
   }
 }