data-structure-typed 1.33.9 → 1.33.10

package/src/data-structures/hash/hash-table.ts

@@ -0,0 +1,277 @@
+/**
+ * data-structure-typed
+ *
+ * @author Tyler Zeng
+ * @copyright Copyright (c) 2022 Tyler Zeng <zrwusa@gmail.com>
+ * @license MIT License
+ */
+
+export class HashTableNode<K, V> {
+  key: K;
+  val: V;
+  next: HashTableNode<K, V> | null;
+
+  constructor(key: K, val: V) {
+    this.key = key;
+    this.val = val;
+    this.next = null;
+  }
+}
+
+import {HashFunction} from '../../types';
+
+export class HashTable<K, V> {
+  get hashFn(): HashFunction<K> {
+    return this._hashFn;
+  }
+
+  set hashFn(value: HashFunction<K>) {
+    this._hashFn = value;
+  }
+
+  get buckets(): Array<HashTableNode<K, V> | null> {
+    return this._buckets;
+  }
+
+  set buckets(value: Array<HashTableNode<K, V> | null>) {
+    this._buckets = value;
+  }
+
+  get capacity(): number {
+    return this._capacity;
+  }
+
+  set capacity(value: number) {
+    this._capacity = value;
+  }
+
+  private static readonly DEFAULT_CAPACITY = 16;
+  private static readonly LOAD_FACTOR = 0.75;
+
+  private _capacity: number;
+  private _size: number;
+  private _buckets: Array<HashTableNode<K, V> | null>;
+  private _hashFn: HashFunction<K>;
+
+  constructor(capacity: number = HashTable.DEFAULT_CAPACITY, hashFn?: HashFunction<K>) {
+    this._hashFn = hashFn || this._defaultHashFn;
+    this._capacity = Math.max(capacity, HashTable.DEFAULT_CAPACITY);
+    this._size = 0;
+    this._buckets = new Array<HashTableNode<K, V> | null>(this._capacity).fill(null);
+  }
+
+  /**
+   * The function `_defaultHashFn` calculates the hash value of a given key and returns the remainder when divided by the
+   * capacity of the data structure.
+   * @param {K} key - The `key` parameter is the input value that needs to be hashed. It can be of any type, but in this
+   * code snippet, it is checked whether the key is a string or an object. If it is a string, the `_murmurStringHashFn`
+   * function is used to
+   * @returns the hash value of the key modulo the capacity of the data structure.
+   */
+  protected _defaultHashFn(key: K): number {
+    // Can be replaced with other hash functions as needed
+    const hashValue = typeof key === 'string' ? this._murmurStringHashFn(key) : this._objectHash(key);
+    return hashValue % this._capacity;
+  }
+
+  /**
+   * The `_multiplicativeStringHashFn` function calculates a hash value for a given string key using the multiplicative
+   * string hash function.
+   * @param {K} key - The `key` parameter is the input value for which we want to calculate the hash. It can be of any
+   * type, as it is generic (`K`). The function converts the `key` to a string using the `String()` function.
+   * @returns a number, which is the result of the multiplicative string hash function applied to the input key.
+   */
+  protected _multiplicativeStringHashFn<K>(key: K): number {
+    const keyString = String(key);
+    let hash = 0;
+    for (let i = 0; i < keyString.length; i++) {
+      const charCode = keyString.charCodeAt(i);
+      // Some constants for adjusting the hash function
+      const A = 0.618033988749895;
+      const M = 1 << 30; // 2^30
+      hash = (hash * A + charCode) % M;
+    }
+    return Math.abs(hash); // Take absolute value to ensure non-negative numbers
+  }
+
+  /**
+   * The function `_murmurStringHashFn` calculates a hash value for a given string key using the MurmurHash algorithm.
+   * @param {K} key - The `key` parameter is the input value for which you want to calculate the hash. It can be of any
+   * type, but it will be converted to a string using the `String()` function before calculating the hash.
+   * @returns a number, which is the hash value calculated for the given key.
+   */
+  protected _murmurStringHashFn<K>(key: K): number {
+    const keyString = String(key);
+    const seed = 0;
+    let hash = seed;
+
+    for (let i = 0; i < keyString.length; i++) {
+      const char = keyString.charCodeAt(i);
+      hash = (hash ^ char) * 0x5bd1e995;
+      hash = (hash ^ (hash >>> 15)) * 0x27d4eb2d;
+      hash = hash ^ (hash >>> 15);
+    }
+
+    return Math.abs(hash);
+  }
+
+  /**
+   * The _hash function takes a key and returns a number.
+   * @param {K} key - The parameter "key" is of type K, which represents the type of the key that will be hashed.
+   * @returns The hash function is returning a number.
+   */
+  protected _hash(key: K): number {
+    return this.hashFn(key);
+  }
+
+  /**
+   * The function calculates a hash value for a given string using the djb2 algorithm.
+   * @param {string} key - The `key` parameter in the `stringHash` function is a string value that represents the input for
+   * which we want to calculate the hash value.
+   * @returns a number, which is the hash value of the input string.
+   */
+  protected _stringHash(key: string): number {
+    let hash = 0;
+    for (let i = 0; i < key.length; i++) {
+      hash = (hash * 31 + key.charCodeAt(i)) & 0xffffffff;
+    }
+    return hash;
+  }
+
+  /**
+   * The function `_objectHash` takes a key and returns a hash value, using a custom hash function for objects.
+   * @param {K} key - The parameter "key" is of type "K", which means it can be any type. It could be a string, number,
+   * boolean, object, or any other type of value. The purpose of the objectHash function is to generate a hash value for
+   * the key, which can be used for
+   * @returns a number, which is the hash value of the key.
+   */
+  protected _objectHash(key: K): number {
+    // If the key is an object, you can write a custom hash function
+    // For example, convert the object's properties to a string and use string hashing
+    // This is just an example; you should write a specific object hash function as needed
+    return this._stringHash(JSON.stringify(key));
+  }
+
+  /**
+   * The set function adds a key-value pair to the hash table, handling collisions and resizing if necessary.
+   * @param {K} key - The key parameter represents the key of the key-value pair that you want to insert into the hash
+   * table. It is of type K, which is a generic type representing the key's data type.
+   * @param {V} val - The parameter `val` represents the value that you want to associate with the given key in the hash
+   * table.
+   * @returns Nothing is being returned. The return type of the `put` method is `void`, which means it does not return any
+   * value.
+   */
+  set(key: K, val: V): void {
+    const index = this._hash(key);
+    const newNode = new HashTableNode<K, V>(key, val);
+
+    if (!this._buckets[index]) {
+      this._buckets[index] = newNode;
+    } else {
+      // Handle collisions, consider using open addressing, etc.
+      let currentNode = this._buckets[index]!;
+      while (currentNode) {
+        if (currentNode.key === key) {
+          // If the key already exists, update the value
+          currentNode.val = val;
+          return;
+        }
+        if (!currentNode.next) {
+          break;
+        }
+        currentNode = currentNode.next;
+      }
+      // Add to the end of the linked list
+      currentNode.next = newNode;
+    }
+    this._size++;
+
+    // If the load factor is too high, resize the hash table
+    if (this._size / this._capacity >= HashTable.LOAD_FACTOR) {
+      this._expand();
+    }
+  }
+
+  /**
+   * The `get` function retrieves the value associated with a given key from a hash table.
+   * @param {K} key - The `key` parameter represents the key of the element that we want to retrieve from the data
+   * structure.
+   * @returns The method is returning the value associated with the given key if it exists in the hash table. If the key is
+   * not found, it returns `undefined`.
+   */
+  get(key: K): V | undefined {
+    const index = this._hash(key);
+    let currentNode = this._buckets[index];
+
+    while (currentNode) {
+      if (currentNode.key === key) {
+        return currentNode.val;
+      }
+      currentNode = currentNode.next;
+    }
+    return undefined; // Key not found
+  }
+
+  /**
+   * The remove function removes a key-value pair from a hash table.
+   * @param {K} key - The `key` parameter represents the key of the key-value pair that needs to be removed from the hash
+   * table.
+   * @returns Nothing is being returned. The `remove` method has a return type of `void`, which means it does not return
+   * any value.
+   */
+  remove(key: K): void {
+    const index = this._hash(key);
+    let currentNode = this._buckets[index];
+    let prevNode: HashTableNode<K, V> | null = null;
+
+    while (currentNode) {
+      if (currentNode.key === key) {
+        if (prevNode) {
+          prevNode.next = currentNode.next;
+        } else {
+          this._buckets[index] = currentNode.next;
+        }
+        this._size--;
+        currentNode.next = null; // Release memory
+        return;
+      }
+      prevNode = currentNode;
+      currentNode = currentNode.next;
+    }
+  }
+
+  /**
+   * The `expand` function increases the capacity of a hash table by creating a new array of buckets with double the
+   * capacity and rehashing all the existing key-value pairs into the new buckets.
+   */
+  protected _expand(): void {
+    const newCapacity = this._capacity * 2;
+    const newBuckets = new Array<HashTableNode<K, V> | null>(newCapacity).fill(null);
+
+    for (const bucket of this._buckets) {
+      let currentNode = bucket;
+      while (currentNode) {
+        const newIndex = this._hash(currentNode.key);
+        const newNode = new HashTableNode<K, V>(currentNode.key, currentNode.val);
+
+        if (!newBuckets[newIndex]) {
+          newBuckets[newIndex] = newNode;
+        } else {
+          let currentNewNode = newBuckets[newIndex]!;
+          while (currentNewNode.next) {
+            currentNewNode = currentNewNode.next;
+          }
+          currentNewNode.next = newNode;
+        }
+        currentNode = currentNode.next;
+      }
+    }
+
+    this._buckets = newBuckets;
+    this._capacity = newCapacity;
+  }
+
+  get size(): number {
+    return this._size;
+  }
+}

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

@@ -0,0 +1,7 @@
+export * from './hash-table';
+export * from './coordinate-map';
+export * from './coordinate-set';
+export * from './pair';
+export * from './tree-map';
+export * from './tree-set';
+export * from './hash-map';

package/src/data-structures/hash/pair.ts

@@ -0,0 +1 @@
+export class Pair {}

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

@@ -0,0 +1 @@
+export class TreeMap {}

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

@@ -0,0 +1 @@
+export class TreeSet {}

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

@@ -0,0 +1,212 @@
+/**
+ * data-structure-typed
+ *
+ * @author Tyler Zeng
+ * @copyright Copyright (c) 2022 Tyler Zeng <zrwusa@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;
+  }
+
+  private _priority: number;
+
+  get priority(): number {
+    return this._priority;
+  }
+
+  set priority(value: number) {
+    this._priority = value;
+  }
+
+  private _val: V | null;
+
+  get val(): V | null {
+    return this._val;
+  }
+
+  set val(value: V | null) {
+    this._val = value;
+  }
+}
+
+export abstract class Heap<V = number> {
+  /**
+   * 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.
+   */
+  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');
+      }
+      this._priorityExtractor = priorityExtractor || (el => +el);
+    } else {
+      this._priorityExtractor = el => +el;
+    }
+  }
+
+  protected abstract _pq: PriorityQueue<HeapItem<V>>;
+
+  get pq() {
+    return this._pq;
+  }
+
+  protected _priorityExtractor: (val: V) => number;
+  get priorityExtractor() {
+    return this._priorityExtractor;
+  }
+
+  /**
+   * The function returns the size of a priority queue.
+   * @returns The size of the priority queue.
+   */
+  get size(): number {
+    return this._pq.size;
+  }
+
+  /**
+   * 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.
+   */
+  isEmpty(): boolean {
+    return this._pq.size < 1;
+  }
+
+  peek(isItem?: undefined): V | undefined;
+  peek(isItem: false): V | undefined;
+  peek(isItem: true): HeapItem<V> | 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
+   */
+  peek(isItem?: boolean): HeapItem<V> | null | V | undefined {
+    isItem = isItem ?? false;
+    const peeked = this._pq.peek();
+
+    return isItem ? peeked : peeked?.val;
+  }
+
+  peekLast(isItem?: undefined): V | undefined;
+  peekLast(isItem: false): V | undefined;
+  peekLast(isItem: true): HeapItem<V> | null;
+
+  /**
+   * 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
+   */
+  peekLast(isItem?: boolean): HeapItem<V> | null | V | undefined {
+    isItem = isItem ?? false;
+    const leafItem = this._pq.leaf();
+
+    return isItem ? leafItem : leafItem?.val;
+  }
+
+  /**
+   * 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
+   */
+  add(priority: number, val?: V): Heap<V> {
+    val = val === undefined ? (priority as unknown as V) : val;
+    this._pq.add(new HeapItem<V>(priority, val));
+
+    return this;
+  }
+
+  poll(isItem?: undefined): V | undefined;
+  poll(isItem: false): V | undefined;
+  poll(isItem: true): HeapItem<V> | null;
+
+  /**
+   * 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.
+   */
+  poll(isItem?: boolean): HeapItem<V> | null | V | undefined {
+    isItem = isItem ?? false;
+    const top = this._pq.poll();
+    if (!top) {
+      return null;
+    }
+
+    return isItem ? top : top.val;
+  }
+
+  /**
+   * 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.
+   */
+  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(isItem?: undefined): (V | undefined)[];
+  toArray(isItem: false): (V | undefined)[];
+  toArray(isItem: true): (HeapItem<V> | null)[];
+
+  /**
+   * The `toArray` function returns an array of `HeapItem<V>` objects.
+   * @returns An array of HeapItem<V> objects.Returns a sorted list of vals
+   */
+  toArray(isItem?: boolean): (HeapItem<V> | null | V | undefined)[] {
+    isItem = isItem ?? false;
+    const itemArray = this._pq.toArray();
+
+    return isItem ? itemArray : itemArray.map(item => item.val);
+  }
+
+  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(isItem?: boolean): (HeapItem<V> | null | V | undefined)[] {
+    isItem = isItem ?? false;
+    const sorted = this._pq.sort();
+
+    return isItem ? sorted : sorted.map(item => item.val);
+  }
+
+  /**
+   * The clear function clears the priority queue.
+   */
+  clear(): void {
+    this._pq.clear();
+  }
+}

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

@@ -0,0 +1,3 @@
+export * from './max-heap';
+export * from './min-heap';
+export * from './heap';

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

@@ -0,0 +1,31 @@
+/**
+ * data-structure-typed
+ *
+ * @author Tyler Zeng
+ * @copyright Copyright (c) 2022 Tyler Zeng <zrwusa@gmail.com>
+ * @license MIT License
+ */
+
+import {Heap, HeapItem} from './heap';
+import {PriorityQueue} from '../priority-queue';
+import type {HeapOptions} 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
+    });
+  }
+}

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

@@ -0,0 +1,32 @@
+/**
+ * data-structure-typed
+ *
+ * @author Tyler Zeng
+ * @copyright Copyright (c) 2022 Tyler Zeng <zrwusa@gmail.com>
+ * @license MIT License
+ */
+
+import {Heap, HeapItem} from './heap';
+import {PriorityQueue} from '../priority-queue';
+import type {HeapOptions} 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
+    });
+  }
+}

package/src/data-structures/index.ts

@@ -0,0 +1,11 @@
+export * from './hash';
+export * from './linked-list';
+export * from './stack';
+export * from './queue';
+export * from './graph';
+export * from './binary-tree';
+export * from './tree';
+export * from './heap';
+export * from './priority-queue';
+export * from './matrix';
+export * from './trie';