min-heap-typed 1.40.0-rc → 1.40.0

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

@@ -0,0 +1,209 @@
+/**
+ * @license MIT
+ * @copyright Tyler Zeng <zrwusa@gmail.com>
+ * @class
+ */
+import {SinglyLinkedList} from '../linked-list';
+
+export class LinkedListQueue<E = any> extends SinglyLinkedList<E> {
+  /**
+   * The enqueue function adds a value to the end of an array.
+   * @param {E} value - The value parameter represents the value that you want to add to the queue.
+   */
+  enqueue(value: E) {
+    this.push(value);
+  }
+
+  /**
+   * The `dequeue` function removes and returns the first element from a queue, or returns null if the queue is empty.
+   * @returns The method is returning the element at the front of the queue, or null if the queue is empty.
+   */
+  dequeue(): E | undefined {
+    return this.shift();
+  }
+
+  /**
+   * The `getFirst` function returns the value of the head node in a linked list, or `undefined` if the list is empty.
+   * @returns The `getFirst()` method is returning the value of the `head` node if it exists, otherwise it returns `undefined`.
+   */
+  getFirst(): E | undefined {
+    return this.head?.value;
+  }
+
+  /**
+   * The `peek` function returns the value of the head node in a linked list, or `undefined` if the list is empty.
+   * @returns The `peek()` method is returning the value of the `head` node if it exists, otherwise it returns `undefined`.
+   */
+  peek(): E | undefined {
+    return this.getFirst();
+  }
+}
+
+export class Queue<E = any> {
+  /**
+   * The constructor initializes an instance of a class with an optional array of elements and sets the offset to 0.
+   * @param {E[]} [elements] - The `elements` parameter is an optional array of elements of type `E`. If provided, it
+   * will be used to initialize the `_nodes` property of the class. If not provided, the `_nodes` property will be
+   * initialized as an empty array.
+   */
+  constructor(elements?: E[]) {
+    this._nodes = elements || [];
+    this._offset = 0;
+  }
+
+  protected _nodes: E[];
+
+  get nodes(): E[] {
+    return this._nodes;
+  }
+
+  protected _offset: number;
+
+  get offset(): number {
+    return this._offset;
+  }
+
+  /**
+   * The size function returns the number of elements in an array.
+   * @returns {number} The size of the array, which is the difference between the length of the array and the offset.
+   */
+  get size(): number {
+    return this.nodes.length - this.offset;
+  }
+
+  /**
+   * The function "fromArray" creates a new Queue object from an array of elements.Creates a queue from an existing array.
+   * @public
+   * @static
+   * @param {E[]} elements - The "elements" parameter is an array of elements of type E.
+   * @returns The method is returning a new instance of the Queue class, initialized with the elements from the input
+   * array.
+   */
+  static fromArray<E>(elements: E[]): Queue<E> {
+    return new Queue(elements);
+  }
+
+  /**
+   * The push function adds an element to the end of the queue and returns the updated queue.Adds an element at the back of the queue.
+   * @param {E} element - The `element` parameter represents the element that you want to add to the queue.
+   * @returns The `add` method is returning a `Queue<E>` object.
+   */
+  push(element: E): Queue<E> {
+    this.nodes.push(element);
+    return this;
+  }
+
+  /**
+   * The `shift` function removes and returns the first element in the queue, and adjusts the internal data structure if
+   * necessary to optimize performance.
+   * @returns The function `shift()` returns either the first element in the queue or `null` if the queue is empty.
+   */
+  shift(): E | undefined {
+    if (this.size === 0) return undefined;
+
+    const first = this.getFirst();
+    this._offset += 1;
+
+    if (this.offset * 2 < this.nodes.length) return first;
+
+    // only delete dequeued elements when reaching half size
+    // to decrease latency of shifting elements.
+    this._nodes = this.nodes.slice(this.offset);
+    this._offset = 0;
+    return first;
+  }
+
+  /**
+   * The `getFirst` function returns the first element of the array `_nodes` if it exists, otherwise it returns `null`.
+   * @returns The `getFirst()` method returns the first element of the data structure, represented by the `_nodes` array at
+   * the `_offset` index. If the data structure is empty (size is 0), it returns `null`.
+   */
+  getFirst(): E | undefined {
+    return this.size > 0 ? this.nodes[this.offset] : undefined;
+  }
+
+  /**
+   * The `peek` function returns the first element of the array `_nodes` if it exists, otherwise it returns `null`.
+   * @returns The `peek()` method returns the first element of the data structure, represented by the `_nodes` array at
+   * the `_offset` index. If the data structure is empty (size is 0), it returns `null`.
+   */
+  peek(): E | undefined {
+    return this.getFirst();
+  }
+
+  /**
+   * The `getLast` function returns the last element in an array-like data structure, or null if the structure is empty.
+   * @returns The method `getLast()` returns the last element of the `_nodes` array if the array is not empty. If the
+   * array is empty, it returns `null`.
+   */
+  getLast(): E | undefined {
+    return this.size > 0 ? this.nodes[this.nodes.length - 1] : undefined;
+  }
+
+  /**
+   * The `peekLast` function returns the last element in an array-like data structure, or null if the structure is empty.
+   * @returns The method `peekLast()` returns the last element of the `_nodes` array if the array is not empty. If the
+   * array is empty, it returns `null`.
+   */
+  peekLast(): E | undefined {
+    return this.getLast();
+  }
+
+  /**
+   * The enqueue function adds a value to the end of a queue.
+   * @param {E} value - The value parameter represents the value that you want to add to the queue.
+   */
+  enqueue(value: E) {
+    this.push(value);
+  }
+
+  /**
+   * The `dequeue` function removes and returns the first element from a queue, or returns null if the queue is empty.
+   * @returns The method is returning a value of type E or null.
+   */
+  dequeue(): E | undefined {
+    return this.shift();
+  }
+
+  getAt(index: number): E | undefined {
+    return this.nodes[index];
+  }
+
+  /**
+   * The function checks if a data structure is empty by comparing its size to zero.
+   * @returns {boolean} A boolean value indicating whether the size of the object is 0 or not.
+   */
+  isEmpty(): boolean {
+    return this.size === 0;
+  }
+
+  /**
+   * The toArray() function returns an array of elements from the current offset to the end of the _nodes array.
+   * @returns An array of type E is being returned.
+   */
+  toArray(): E[] {
+    return this.nodes.slice(this.offset);
+  }
+
+  /**
+   * The clear function resets the nodes array and offset to their initial values.
+   */
+  clear(): void {
+    this._nodes = [];
+    this._offset = 0;
+  }
+
+  /**
+   * The `clone()` function returns a new Queue object with the same elements as the original Queue.
+   * @returns The `clone()` method is returning a new instance of the `Queue` class.
+   */
+  clone(): Queue<E> {
+    return new Queue(this.nodes.slice(this.offset));
+  }
+
+  * [Symbol.iterator]() {
+    for (const item of this.nodes) {
+      yield item;
+    }
+  }
+}

package/src/data-structures/stack/index.ts

@@ -0,0 +1 @@
+export * from './stack';

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

@@ -0,0 +1,102 @@
+/**
+ * @license MIT
+ * @copyright Tyler Zeng <zrwusa@gmail.com>
+ * @class
+ */
+export class Stack<E = any> {
+  /**
+   * The constructor initializes an array of elements, which can be provided as an optional parameter.
+   * @param {E[]} [elements] - The `elements` parameter is an optional parameter of type `E[]`, which represents an array
+   * of elements of type `E`. It is used to initialize the `_elements` property of the class. If the `elements` parameter
+   * is provided and is an array, it is assigned to the `_elements
+   */
+  constructor(elements?: E[]) {
+    this._elements = Array.isArray(elements) ? elements : [];
+  }
+
+  protected _elements: E[];
+
+  get elements(): E[] {
+    return this._elements;
+  }
+
+  /**
+   * The function "fromArray" creates a new Stack object from an array of elements.
+   * @param {E[]} elements - The `elements` parameter is an array of elements of type `E`.
+   * @returns {Stack} The method is returning a new instance of the Stack class, initialized with the elements from the input
+   * array.
+   */
+  static fromArray<E>(elements: E[]): Stack<E> {
+    return new Stack(elements);
+  }
+
+  /**
+   * The function checks if an array is empty and returns a boolean value.
+   * @returns A boolean value indicating whether the `_elements` array is empty or not.
+   */
+  isEmpty(): boolean {
+    return this.elements.length === 0;
+  }
+
+  /**
+   * The size() function returns the number of elements in an array.
+   * @returns The size of the elements array.
+   */
+  size(): number {
+    return this.elements.length;
+  }
+
+  /**
+   * The `peek` function returns the last element of an array, or null if the array is empty.
+   * @returns The `peek()` function returns the last element of the `_elements` array, or `null` if the array is empty.
+   */
+  peek(): E | null {
+    if (this.isEmpty()) return null;
+
+    return this.elements[this.elements.length - 1];
+  }
+
+  /**
+   * The push function adds an element to the stack and returns the updated stack.
+   * @param {E} element - The parameter "element" is of type E, which means it can be any data type.
+   * @returns The `push` method is returning the updated `Stack<E>` object.
+   */
+  push(element: E): Stack<E> {
+    this.elements.push(element);
+    return this;
+  }
+
+  /**
+   * The `pop` function removes and returns the last element from an array, or returns null if the array is empty.
+   * @returns The `pop()` method is returning the last element of the array `_elements` if the array is not empty. If the
+   * array is empty, it returns `null`.
+   */
+  pop(): E | null {
+    if (this.isEmpty()) return null;
+
+    return this.elements.pop() || null;
+  }
+
+  /**
+   * The toArray function returns a copy of the elements in an array.
+   * @returns An array of type E.
+   */
+  toArray(): E[] {
+    return this.elements.slice();
+  }
+
+  /**
+   * The clear function clears the elements array.
+   */
+  clear(): void {
+    this._elements = [];
+  }
+
+  /**
+   * The `clone()` function returns a new `Stack` object with the same elements as the original stack.
+   * @returns The `clone()` method is returning a new `Stack` object with a copy of the `_elements` array.
+   */
+  clone(): Stack<E> {
+    return new Stack(this.elements.slice());
+  }
+}

package/src/data-structures/tree/index.ts

@@ -0,0 +1 @@
+export * from './tree';

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

@@ -0,0 +1,41 @@
+export class TreeNode<V = any> {
+  key: string;
+  value?: V | undefined;
+  children?: TreeNode<V>[] | undefined;
+
+  constructor(key: string, value?: V, children?: TreeNode<V>[]) {
+    this.key = key;
+    this.value = value || undefined;
+    this.children = children || [];
+  }
+
+  addChildren(children: TreeNode<V> | TreeNode<V>[]) {
+    if (!this.children) {
+      this.children = [];
+    }
+    if (children instanceof TreeNode) {
+      this.children.push(children);
+    } else {
+      this.children = this.children.concat(children);
+    }
+  }
+
+  getHeight() {
+    let maxDepth = 0;
+    if (this) {
+      const bfs = (node: TreeNode<V>, level: number) => {
+        if (level > maxDepth) {
+          maxDepth = level;
+        }
+        const {children} = node;
+        if (children) {
+          for (let i = 0, len = children.length; i < len; i++) {
+            bfs(children[i], level + 1);
+          }
+        }
+      };
+      bfs(this, 0);
+    }
+    return maxDepth;
+  }
+}

package/src/data-structures/trie/index.ts

@@ -0,0 +1 @@
+export * from './trie';

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

@@ -0,0 +1,262 @@
+/**
+ * data-structure-typed
+ *
+ * @author Tyler Zeng
+ * @copyright Copyright (c) 2022 Tyler Zeng <zrwusa@gmail.com>
+ * @license MIT License
+ */
+
+/**
+ * TrieNode represents a node in the Trie data structure. It holds a character key, a map of children nodes,
+ * and a flag indicating whether it's the end of a word.
+ */
+export class TrieNode {
+  key: string;
+  children: Map<string, TrieNode>;
+  isEnd: boolean;
+
+  constructor(key: string) {
+    this.key = key;
+    this.isEnd = false;
+    this.children = new Map<string, TrieNode>();
+  }
+}
+
+/**
+ * Trie represents a Trie data structure. It provides basic Trie operations and additional methods.
+ */
+export class Trie {
+  constructor(words?: string[], caseSensitive = true) {
+    this._root = new TrieNode('');
+    this._caseSensitive = caseSensitive;
+    if (words) {
+      for (const i of words) {
+        this.add(i);
+      }
+    }
+  }
+
+  protected _caseSensitive: boolean;
+
+  get caseSensitive(): boolean {
+    return this._caseSensitive;
+  }
+
+  protected _root: TrieNode;
+
+  get root() {
+    return this._root;
+  }
+
+  /**
+   * Add a word to the Trie structure.
+   * @param {string} word - The word to add.
+   * @returns {boolean} True if the word was successfully added.
+   */
+  add(word: string): boolean {
+    word = this._caseProcess(word);
+    let cur = this.root;
+    for (const c of word) {
+      let nodeC = cur.children.get(c);
+      if (!nodeC) {
+        nodeC = new TrieNode(c);
+        cur.children.set(c, nodeC);
+      }
+      cur = nodeC;
+    }
+    cur.isEnd = true;
+    return true;
+  }
+
+  /**
+   * Check if the Trie contains a given word.
+   * @param {string} word - The word to check for.
+   * @returns {boolean} True if the word is present in the Trie.
+   */
+  has(word: string): boolean {
+    word = this._caseProcess(word);
+    let cur = this.root;
+    for (const c of word) {
+      const nodeC = cur.children.get(c);
+      if (!nodeC) return false;
+      cur = nodeC;
+    }
+    return cur.isEnd;
+  }
+
+  /**
+   * Remove a word from the Trie structure.
+   * @param{string} word - The word to delete.
+   * @returns {boolean} True if the word was successfully removed.
+   */
+  delete(word: string) {
+    word = this._caseProcess(word);
+    let isDeleted = false;
+    const dfs = (cur: TrieNode, i: number): boolean => {
+      const char = word[i];
+      const child = cur.children.get(char);
+      if (child) {
+        if (i === word.length - 1) {
+          if (child.isEnd) {
+            if (child.children.size > 0) {
+              child.isEnd = false;
+            } else {
+              cur.children.delete(char);
+            }
+            isDeleted = true;
+            return true;
+          }
+          return false;
+        }
+        const res = dfs(child, i + 1);
+        if (res && !cur.isEnd && child.children.size === 0) {
+          cur.children.delete(char);
+          return true;
+        }
+        return false;
+      }
+      return false;
+    };
+
+    dfs(this.root, 0);
+    return isDeleted;
+  }
+
+  getHeight() {
+    const beginRoot = this.root;
+    let maxDepth = 0;
+    if (beginRoot) {
+      const bfs = (node: TrieNode, level: number) => {
+        if (level > maxDepth) {
+          maxDepth = level;
+        }
+        const {children} = node;
+        if (children) {
+          for (const child of children.entries()) {
+            bfs(child[1], level + 1);
+          }
+        }
+      };
+      bfs(beginRoot, 0);
+    }
+    return maxDepth;
+  }
+
+  // --- start additional methods ---
+  /**
+   * Check if a given input string has an absolute prefix in the Trie, meaning it's not a complete word.
+   * @param {string} input - The input string to check.
+   * @returns {boolean} True if it's an absolute prefix in the Trie.
+   */
+  hasPurePrefix(input: string): boolean {
+    input = this._caseProcess(input);
+    let cur = this.root;
+    for (const c of input) {
+      const nodeC = cur.children.get(c);
+      if (!nodeC) return false;
+      cur = nodeC;
+    }
+    return !cur.isEnd;
+  }
+
+  /**
+   * Check if a given input string is a prefix of any existing word in the Trie, whether as an absolute prefix or a complete word.
+   * @param {string} input - The input string representing the prefix to check.
+   * @returns {boolean} True if it's a prefix in the Trie.
+   */
+  hasPrefix(input: string): boolean {
+    input = this._caseProcess(input);
+    let cur = this.root;
+    for (const c of input) {
+      const nodeC = cur.children.get(c);
+      if (!nodeC) return false;
+      cur = nodeC;
+    }
+    return true;
+  }
+
+  /**
+   * Check if the input string is a common prefix in the Trie, meaning it's a prefix shared by all words in the Trie.
+   * @param {string} input - The input string representing the common prefix to check for.
+   * @returns {boolean} True if it's a common prefix in the Trie.
+   */
+  hasCommonPrefix(input: string): boolean {
+    input = this._caseProcess(input);
+    let commonPre = '';
+    const dfs = (cur: TrieNode) => {
+      commonPre += cur.key;
+      if (commonPre === input) return;
+      if (cur.isEnd) return;
+      if (cur && cur.children && cur.children.size === 1) dfs(Array.from(cur.children.values())[0]);
+      else return;
+    };
+    dfs(this.root);
+    return commonPre === input;
+  }
+
+  /**
+   * Get the longest common prefix among all the words stored in the Trie.
+   * @returns {string} The longest common prefix found in the Trie.
+   */
+  getLongestCommonPrefix(): string {
+    let commonPre = '';
+    const dfs = (cur: TrieNode) => {
+      commonPre += cur.key;
+      if (cur.isEnd) return;
+      if (cur && cur.children && cur.children.size === 1) dfs(Array.from(cur.children.values())[0]);
+      else return;
+    };
+    dfs(this.root);
+    return commonPre;
+  }
+
+  /**
+   * The `getAll` function returns an array of all words in a Trie data structure that start with a given prefix.
+   * @param {string} prefix - The `prefix` parameter is a string that represents the prefix that we want to search for in the
+   * trie. It is an optional parameter, so if no prefix is provided, it will default to an empty string.
+   * @param {number} max - The max count of words will be found
+   * @param isAllWhenEmptyPrefix - If true, when the prefix provided as '', returns all the words in the trie.
+   * @returns {string[]} an array of strings.
+   */
+  getWords(prefix = '', max = Number.MAX_SAFE_INTEGER, isAllWhenEmptyPrefix = false): string[] {
+    prefix = this._caseProcess(prefix);
+    const words: string[] = [];
+    let found = 0;
+
+    function dfs(node: TrieNode, word: string) {
+      for (const char of node.children.keys()) {
+        const charNode = node.children.get(char);
+        if (charNode !== undefined) {
+          dfs(charNode, word.concat(char));
+        }
+      }
+      if (node.isEnd) {
+        if (found > max - 1) return;
+        words.push(word);
+        found++;
+      }
+    }
+
+    let startNode = this.root;
+
+    if (prefix) {
+      for (const c of prefix) {
+        const nodeC = startNode.children.get(c);
+        if (nodeC) startNode = nodeC;
+      }
+    }
+
+    if (isAllWhenEmptyPrefix || startNode !== this.root) dfs(startNode, prefix);
+
+    return words;
+  }
+
+  protected _caseProcess(str: string) {
+    if (!this._caseSensitive) {
+      str = str.toLowerCase(); // Convert str to lowercase if case-insensitive
+    }
+    return str;
+  }
+
+  // --- end additional methods ---
+}

package/src/index.ts

@@ -5,4 +5,7 @@
  * @copyright Copyright (c) 2022 Tyler Zeng <zrwusa@gmail.com>
  * @license MIT License
  */
-export { MinHeap, HeapItem } from 'data-structure-typed';
+// export { MinHeap } from 'data-structure-typed';
+export * from './data-structures/heap/min-heap';
+export * from './types/data-structures/heap/min-heap';
+export * from './types/helpers';

package/src/interfaces/binary-tree.ts

@@ -0,0 +1,10 @@
+import {BinaryTreeNode} from '../data-structures';
+import {BinaryTreeDeletedResult, BinaryTreeNodeNested, BTNCallback, BTNKey} from '../types';
+
+export interface IBinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNodeNested<V>> {
+  createNode(key: BTNKey, value?: N['value']): N;
+
+  add(keyOrNode: BTNKey | N | null, value?: N['value']): N | null | undefined;
+
+  delete<C extends BTNCallback<N>>(identifier: ReturnType<C> | null, callback: C): BinaryTreeDeletedResult<N>[];
+}

package/src/interfaces/doubly-linked-list.ts

@@ -0,0 +1 @@
+export {};

package/src/interfaces/graph.ts

@@ -0,0 +1,7 @@
+import {VertexKey} from '../types';
+
+export interface IGraph<V, E, VO, EO> {
+  createVertex(key: VertexKey, value?: V): VO;
+
+  createEdge(srcOrV1: VertexKey, destOrV2: VertexKey, weight?: number, value?: E): EO;
+}

package/src/interfaces/heap.ts

@@ -0,0 +1 @@
+export {};

package/src/interfaces/index.ts

@@ -0,0 +1,8 @@
+export * from './graph';
+export * from './binary-tree';
+export * from './doubly-linked-list';
+export * from './heap';
+export * from './navigator';
+export * from './priority-queue';
+export * from './segment-tree';
+export * from './singly-linked-list';

package/src/interfaces/navigator.ts

@@ -0,0 +1 @@
+export {};

package/src/interfaces/priority-queue.ts

@@ -0,0 +1 @@
+export {};

package/src/interfaces/segment-tree.ts

@@ -0,0 +1 @@
+export {};

package/src/interfaces/singly-linked-list.ts

@@ -0,0 +1 @@
+export {};

package/src/types/data-structures/binary-tree/avl-tree.ts

@@ -0,0 +1,5 @@
+import {AVLTreeNode} from '../../../data-structures';
+import {BSTOptions} from './bst';
+
+export type AVLTreeNodeNested<T> = AVLTreeNode<T, AVLTreeNode<T, AVLTreeNode<T, AVLTreeNode<T, AVLTreeNode<T, AVLTreeNode<T, AVLTreeNode<T, AVLTreeNode<T, AVLTreeNode<T, AVLTreeNode<T, AVLTreeNode<T, AVLTreeNode<T, AVLTreeNode<T, AVLTreeNode<T, AVLTreeNode<T, AVLTreeNode<T, AVLTreeNode<T, AVLTreeNode<T, AVLTreeNode<T, AVLTreeNode<T, AVLTreeNode<T, AVLTreeNode<T, AVLTreeNode<T, AVLTreeNode<T, AVLTreeNode<T, AVLTreeNode<T, AVLTreeNode<T, AVLTreeNode<T, AVLTreeNode<T, AVLTreeNode<T, AVLTreeNode<T, AVLTreeNode<T, AVLTreeNode<T, AVLTreeNode<T, AVLTreeNode<T, AVLTreeNode<T, AVLTreeNode<T, AVLTreeNode<T, AVLTreeNode<T, AVLTreeNode<T, AVLTreeNode<T, AVLTreeNode<T, AVLTreeNode<T, AVLTreeNode<T, AVLTreeNode<T, AVLTreeNode<T, AVLTreeNode<T, AVLTreeNode<T, AVLTreeNode<T, AVLTreeNode<T, any>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+export type AVLTreeOptions = BSTOptions & {};

package/src/types/data-structures/binary-tree/binary-indexed-tree.ts

@@ -0,0 +1 @@
+export {};