min-heap-typed 1.40.0-rc → 1.40.0

package/src/data-structures/graph/undirected-graph.ts

@@ -0,0 +1,259 @@
+/**
+ * data-structure-typed
+ *
+ * @author Tyler Zeng
+ * @copyright Copyright (c) 2022 Tyler Zeng <zrwusa@gmail.com>
+ * @license MIT License
+ */
+import {arrayRemove} from '../../utils';
+import {AbstractEdge, AbstractGraph, AbstractVertex} from './abstract-graph';
+import type {VertexKey} from '../../types';
+import {IGraph} from '../../interfaces';
+
+export class UndirectedVertex<V = any> extends AbstractVertex<V> {
+  /**
+   * The constructor function initializes a vertex with an optional value.
+   * @param {VertexKey} key - The `key` parameter is of type `VertexKey` and represents the identifier of the vertex. It is
+   * used to uniquely identify the vertex within a graph or network.
+   * @param {V} [value] - The "value" parameter is an optional parameter of type V. It is used to initialize the value of the
+   * vertex. If no value is provided, the vertex will be initialized with a default value.
+   */
+  constructor(key: VertexKey, value?: V) {
+    super(key, value);
+  }
+}
+
+export class UndirectedEdge<E = number> extends AbstractEdge<E> {
+  vertices: [VertexKey, VertexKey];
+
+  /**
+   * The constructor function creates an instance of a class with two vertex IDs, an optional weight, and an optional
+   * value.
+   * @param {VertexKey} v1 - The first vertex ID of the edge.
+   * @param {VertexKey} v2 - The parameter `v2` is a `VertexKey`, which represents the identifier of the second vertex in a
+   * graph edge.
+   * @param {number} [weight] - The weight parameter is an optional number that represents the weight of the edge.
+   * @param {E} [value] - The "value" parameter is an optional parameter of type E. It is used to store a value associated
+   * with the edge.
+   */
+  constructor(v1: VertexKey, v2: VertexKey, weight?: number, value?: E) {
+    super(weight, value);
+    this.vertices = [v1, v2];
+  }
+}
+
+export class UndirectedGraph<
+  V = any,
+  E = any,
+  VO extends UndirectedVertex<V> = UndirectedVertex<V>,
+  EO extends UndirectedEdge<E> = UndirectedEdge<E>
+>
+  extends AbstractGraph<V, E, VO, EO>
+  implements IGraph<V, E, VO, EO> {
+  /**
+   * The constructor initializes a new Map object to store edges.
+   */
+  constructor() {
+    super();
+    this._edges = new Map<VO, EO[]>();
+  }
+
+  protected _edges: Map<VO, EO[]>;
+
+  get edges(): Map<VO, EO[]> {
+    return this._edges;
+  }
+
+  /**
+   * The function creates a new vertex with an optional value and returns it.
+   * @param {VertexKey} key - The `key` parameter is the unique identifier for the vertex. It is used to distinguish one
+   * vertex from another in the graph.
+   * @param [value] - The `value` parameter is an optional value that can be assigned to the vertex. If a value is provided,
+   * it will be used as the value of the vertex. If no value is provided, the `key` parameter will be used as the value of
+   * the vertex.
+   * @returns The method is returning a new instance of the `UndirectedVertex` class, casted as type `VO`.
+   */
+  override createVertex(key: VertexKey, value?: VO['value']): VO {
+    return new UndirectedVertex(key, value ?? key) as VO;
+  }
+
+  /**
+   * The function creates an undirected edge between two vertices with an optional weight and value.
+   * @param {VertexKey} v1 - The parameter `v1` represents the first vertex of the edge.
+   * @param {VertexKey} v2 - The parameter `v2` represents the second vertex of the edge.
+   * @param {number} [weight] - The `weight` parameter is an optional number that represents the weight of the edge. If
+   * no weight is provided, it defaults to 1.
+   * @param [value] - The `value` parameter is an optional value that can be assigned to the edge. It can be of any type and
+   * is used to store additional information or data associated with the edge.
+   * @returns a new instance of the `UndirectedEdge` class, which is casted as type `EO`.
+   */
+  override createEdge(v1: VertexKey, v2: VertexKey, weight?: number, value?: EO['value']): EO {
+    return new UndirectedEdge(v1, v2, weight ?? 1, value) as EO;
+  }
+
+  /**
+   * The function `getEdge` returns the first edge that connects two vertices, or null if no such edge exists.
+   * @param {VO | VertexKey | null} v1 - The parameter `v1` represents a vertex or vertex ID. It can be of type `VO` (vertex
+   * object), `null`, or `VertexKey` (a string or number representing the ID of a vertex).
+   * @param {VO | VertexKey | null} v2 - The parameter `v2` represents a vertex or vertex ID. It can be of type `VO` (vertex
+   * object), `null`, or `VertexKey` (vertex ID).
+   * @returns an edge (EO) or null.
+   */
+  getEdge(v1: VO | VertexKey | null, v2: VO | VertexKey | null): EO | null {
+    let edges: EO[] | undefined = [];
+
+    if (v1 !== null && v2 !== null) {
+      const vertex1: VO | null = this._getVertex(v1);
+      const vertex2: VO | null = this._getVertex(v2);
+
+      if (vertex1 && vertex2) {
+        edges = this._edges.get(vertex1)?.filter(e => e.vertices.includes(vertex2.key));
+      }
+    }
+
+    return edges ? edges[0] || null : null;
+  }
+
+  /**
+   * The function removes an edge between two vertices in a graph and returns the removed edge.
+   * @param {VO | VertexKey} v1 - The parameter `v1` represents either a vertex object (`VO`) or a vertex ID (`VertexKey`).
+   * @param {VO | VertexKey} v2 - VO | VertexKey - This parameter can be either a vertex object (VO) or a vertex ID
+   * (VertexKey). It represents the second vertex of the edge that needs to be removed.
+   * @returns the removed edge (EO) if it exists, or null if either of the vertices (VO) does not exist.
+   */
+  deleteEdgeBetween(v1: VO | VertexKey, v2: VO | VertexKey): EO | null {
+    const vertex1: VO | null = this._getVertex(v1);
+    const vertex2: VO | null = this._getVertex(v2);
+
+    if (!vertex1 || !vertex2) {
+      return null;
+    }
+
+    const v1Edges = this._edges.get(vertex1);
+    let removed: EO | null = null;
+    if (v1Edges) {
+      removed = arrayRemove<EO>(v1Edges, (e: EO) => e.vertices.includes(vertex2.key))[0] || null;
+    }
+    const v2Edges = this._edges.get(vertex2);
+    if (v2Edges) {
+      arrayRemove<EO>(v2Edges, (e: EO) => e.vertices.includes(vertex1.key));
+    }
+    return removed;
+  }
+
+  /**
+   * The deleteEdge function removes an edge between two vertices in a graph.
+   * @param {EO} edge - The parameter "edge" is of type EO, which represents an edge in a graph.
+   * @returns The method is returning either the removed edge (of type EO) or null if the edge was not found.
+   */
+  deleteEdge(edge: EO): EO | null {
+    return this.deleteEdgeBetween(edge.vertices[0], edge.vertices[1]);
+  }
+
+  /**
+   * The function `degreeOf` returns the degree of a vertex in a graph, which is the number of edges connected to that
+   * vertex.
+   * @param {VertexKey | VO} vertexOrKey - The parameter `vertexOrKey` can be either a `VertexKey` or a `VO`.
+   * @returns The function `degreeOf` returns the degree of a vertex in a graph. The degree of a vertex is the number of
+   * edges connected to that vertex.
+   */
+  degreeOf(vertexOrKey: VertexKey | VO): number {
+    const vertex = this._getVertex(vertexOrKey);
+    if (vertex) {
+      return this._edges.get(vertex)?.length || 0;
+    } else {
+      return 0;
+    }
+  }
+
+  /**
+   * The function returns the edges of a given vertex or vertex ID.
+   * @param {VertexKey | VO} vertexOrKey - The parameter `vertexOrKey` can be either a `VertexKey` or a `VO`. A `VertexKey` is a
+   * unique identifier for a vertex in a graph, while `VO` represents the type of the vertex.
+   * @returns an array of edges.
+   */
+  edgesOf(vertexOrKey: VertexKey | VO): EO[] {
+    const vertex = this._getVertex(vertexOrKey);
+    if (vertex) {
+      return this._edges.get(vertex) || [];
+    } else {
+      return [];
+    }
+  }
+
+  /**
+   * The function "edgeSet" returns an array of unique edges from a set of edges.
+   * @returns The method `edgeSet()` returns an array of type `EO[]`.
+   */
+  edgeSet(): EO[] {
+    const edgeSet: Set<EO> = new Set();
+    this._edges.forEach(edges => {
+      edges.forEach(edge => {
+        edgeSet.add(edge);
+      });
+    });
+    return [...edgeSet];
+  }
+
+  /**
+   * The function "getNeighbors" returns an array of neighboring vertices for a given vertex or vertex ID.
+   * @param {VO | VertexKey} vertexOrKey - The parameter `vertexOrKey` can be either a vertex object (`VO`) or a vertex ID
+   * (`VertexKey`).
+   * @returns an array of vertices (VO[]).
+   */
+  getNeighbors(vertexOrKey: VO | VertexKey): VO[] {
+    const neighbors: VO[] = [];
+    const vertex = this._getVertex(vertexOrKey);
+    if (vertex) {
+      const neighborEdges = this.edgesOf(vertex);
+      for (const edge of neighborEdges) {
+        const neighbor = this._getVertex(edge.vertices.filter(e => e !== vertex.key)[0]);
+        if (neighbor) {
+          neighbors.push(neighbor);
+        }
+      }
+    }
+    return neighbors;
+  }
+
+  /**
+   * The function "getEndsOfEdge" returns the vertices at the ends of an edge if the edge exists in the graph, otherwise
+   * it returns null.
+   * @param {EO} edge - The parameter "edge" is of type EO, which represents an edge in a graph.
+   * @returns The function `getEndsOfEdge` returns an array containing two vertices `[VO, VO]` if the edge exists in the
+   * graph. If the edge does not exist, it returns `null`.
+   */
+  getEndsOfEdge(edge: EO): [VO, VO] | null {
+    if (!this.hasEdge(edge.vertices[0], edge.vertices[1])) {
+      return null;
+    }
+    const v1 = this._getVertex(edge.vertices[0]);
+    const v2 = this._getVertex(edge.vertices[1]);
+    if (v1 && v2) {
+      return [v1, v2];
+    } else {
+      return null;
+    }
+  }
+
+  /**
+   * The function adds an edge to the graph by updating the adjacency list with the vertices of the edge.
+   * @param {EO} edge - The parameter "edge" is of type EO, which represents an edge in a graph.
+   * @returns a boolean value.
+   */
+  protected _addEdgeOnly(edge: EO): boolean {
+    for (const end of edge.vertices) {
+      const endVertex = this._getVertex(end);
+      if (endVertex === null) return false;
+      if (endVertex) {
+        const edges = this._edges.get(endVertex);
+        if (edges) {
+          edges.push(edge);
+        } else {
+          this._edges.set(endVertex, [edge]);
+        }
+      }
+    }
+    return true;
+  }
+}

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

@@ -0,0 +1,63 @@
+/**
+ * data-structure-typed
+ *
+ * @author Tyler Zeng
+ * @copyright Copyright (c) 2022 Tyler Zeng <zrwusa@gmail.com>
+ * @license MIT License
+ */
+export class CoordinateMap<V> extends Map<any, V> {
+  constructor(joint?: string) {
+    super();
+    if (joint !== undefined) this._joint = joint;
+  }
+
+  protected _joint = '_';
+
+  get joint(): string {
+    return this._joint;
+  }
+
+  /**
+   * The "has" function overrides the base class's "has" function and checks if a key exists in the map by joining the
+   * key array with a specified delimiter.
+   * @param {number[]} key - The parameter "key" is an array of numbers.
+   * @returns The `has` method is being overridden to return the result of calling the `has` method of the superclass
+   * (`super.has`) with the `key` array joined together using the `_joint` property.
+   */
+  override has(key: number[]) {
+    return super.has(key.join(this._joint));
+  }
+
+  /**
+   * The function overrides the set method of a Map object to convert the key from an array to a string using a specified
+   * delimiter before calling the original set method.
+   * @param {number[]} key - The key parameter is an array of numbers.
+   * @param {V} value - The value parameter is the value that you want to associate with the specified key.
+   * @returns The `set` method is returning the result of calling the `set` method of the superclass
+   * (`super.set(key.join(this._joint), value)`).
+   */
+  override set(key: number[], value: V) {
+    return super.set(key.join(this._joint), value);
+  }
+
+  /**
+   * The function overrides the get method to join the key array with a specified joint and then calls the super get
+   * method.
+   * @param {number[]} key - An array of numbers
+   * @returns The code is returning the value associated with the specified key in the map.
+   */
+  override get(key: number[]) {
+    return super.get(key.join(this._joint));
+  }
+
+  /**
+   * The function overrides the delete method and joins the key array using a specified joint character before calling
+   * the super delete method.
+   * @param {number[]} key - An array of numbers that represents the key to be deleted.
+   * @returns The `delete` method is returning the result of calling the `delete` method on the superclass, with the
+   * `key` array joined together using the `_joint` property.
+   */
+  override delete(key: number[]) {
+    return super.delete(key.join(this._joint));
+  }
+}

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

@@ -0,0 +1,52 @@
+/**
+ * data-structure-typed
+ *
+ * @author Tyler Zeng
+ * @copyright Copyright (c) 2022 Tyler Zeng <zrwusa@gmail.com>
+ * @license MIT License
+ */
+export class CoordinateSet extends Set<any> {
+  constructor(joint?: string) {
+    super();
+    if (joint !== undefined) this._joint = joint;
+  }
+
+  protected _joint = '_';
+
+  get joint(): string {
+    return this._joint;
+  }
+
+  /**
+   * The "has" function overrides the "has" method of the superclass and checks if a value exists in an array after
+   * joining its elements with a specified separator.
+   * @param {number[]} value - The parameter "value" is an array of numbers.
+   * @returns The overridden `has` method is returning the result of calling the `has` method of the superclass, passing
+   * in the joined value as an argument.
+   */
+  override has(value: number[]) {
+    return super.has(value.join(this._joint));
+  }
+
+  /**
+   * The "add" function overrides the parent class's "add" function by joining the elements of the input array with a
+   * specified delimiter before calling the parent class's "add" function.
+   * @param {number[]} value - An array of numbers
+   * @returns The overridden `add` method is returning the result of calling the `add` method of the superclass
+   * (`super.add`) with the joined string representation of the `value` array (`value.join(this._joint)`).
+   */
+  override add(value: number[]) {
+    return super.add(value.join(this._joint));
+  }
+
+  /**
+   * The function overrides the delete method and deletes an element from a Set by joining the elements of the input
+   * array with a specified joint and then calling the delete method of the parent class.
+   * @param {number[]} value - An array of numbers
+   * @returns The `delete` method is returning the result of calling the `delete` method of the superclass, with the
+   * `value` array joined together using the `_joint` property.
+   */
+  override delete(value: number[]) {
+    return super.delete(value.join(this._joint));
+  }
+}

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

@@ -0,0 +1,185 @@
+import {HashFunction} from '../../types';
+
+/**
+ * data-structure-typed
+ *
+ * @author Tyler Zeng
+ * @copyright Copyright (c) 2022 Tyler Zeng <zrwusa@gmail.com>
+ * @license MIT License
+ */
+export class HashMap<K, V> {
+  /**
+   * The constructor initializes the properties of a hash table, including the initial capacity, load factor, capacity
+   * multiplier, size, table array, and hash function.
+   * @param [initialCapacity=16] - The initial capacity is the initial size of the hash table. It determines the number of
+   * buckets or slots available for storing key-value pairs. The default value is 16.
+   * @param [loadFactor=0.75] - The load factor is a measure of how full the hash table can be before it is resized. It is
+   * a value between 0 and 1, where 1 means the hash table is completely full and 0 means it is completely empty. When the
+   * load factor is reached, the hash table will
+   * @param [hashFn] - The `hashFn` parameter is an optional parameter that represents the hash function used to calculate
+   * the index of a key in the hash table. If a custom hash function is not provided, a default hash function is used. The
+   * default hash function converts the key to a string, calculates the sum of the
+   */
+  constructor(initialCapacity = 16, loadFactor = 0.75, hashFn?: HashFunction<K>) {
+    this._initialCapacity = initialCapacity;
+    this._loadFactor = loadFactor;
+    this._capacityMultiplier = 2;
+    this._size = 0;
+    this._table = new Array(initialCapacity);
+    this._hashFn =
+      hashFn ||
+      ((key: K) => {
+        const strKey = String(key);
+        let hash = 0;
+        for (let i = 0; i < strKey.length; i++) {
+          hash += strKey.charCodeAt(i);
+        }
+        return hash % this.table.length;
+      });
+  }
+
+  protected _initialCapacity: number;
+
+  get initialCapacity(): number {
+    return this._initialCapacity;
+  }
+
+  protected _loadFactor: number;
+
+  get loadFactor(): number {
+    return this._loadFactor;
+  }
+
+  protected _capacityMultiplier: number;
+
+  get capacityMultiplier(): number {
+    return this._capacityMultiplier;
+  }
+
+  protected _size: number;
+
+  get size(): number {
+    return this._size;
+  }
+
+  protected _table: Array<Array<[K, V]>>;
+
+  get table(): Array<Array<[K, V]>> {
+    return this._table;
+  }
+
+  protected _hashFn: HashFunction<K>;
+
+  get hashFn(): HashFunction<K> {
+    return this._hashFn;
+  }
+
+  set(key: K, value: V): void {
+    const loadFactor = this.size / this.table.length;
+    if (loadFactor >= this.loadFactor) {
+      this.resizeTable(this.table.length * this.capacityMultiplier);
+    }
+
+    const index = this._hash(key);
+    if (!this.table[index]) {
+      this.table[index] = [];
+    }
+
+    // Check if the key already exists in the bucket
+    for (let i = 0; i < this.table[index].length; i++) {
+      if (this.table[index][i][0] === key) {
+        this.table[index][i][1] = value;
+        return;
+      }
+    }
+
+    this.table[index].push([key, value]);
+    this._size++;
+  }
+
+  get(key: K): V | undefined {
+    const index = this._hash(key);
+    if (!this.table[index]) {
+      return undefined;
+    }
+
+    for (const [k, v] of this.table[index]) {
+      if (k === key) {
+        return v;
+      }
+    }
+
+    return undefined;
+  }
+
+  delete(key: K): void {
+    const index = this._hash(key);
+    if (!this.table[index]) {
+      return;
+    }
+
+    for (let i = 0; i < this.table[index].length; i++) {
+      if (this.table[index][i][0] === key) {
+        this.table[index].splice(i, 1);
+        this._size--;
+
+        // Check if the table needs to be resized down
+        const loadFactor = this.size / this.table.length;
+        if (loadFactor < this.loadFactor / this.capacityMultiplier) {
+          this.resizeTable(this.table.length / this.capacityMultiplier);
+        }
+        return;
+      }
+    }
+  }
+
+  * entries(): IterableIterator<[K, V]> {
+    for (const bucket of this.table) {
+      if (bucket) {
+        for (const [key, value] of bucket) {
+          yield [key, value];
+        }
+      }
+    }
+  }
+
+  [Symbol.iterator](): IterableIterator<[K, V]> {
+    return this.entries();
+  }
+
+  clear(): void {
+    this._size = 0;
+    this._table = new Array(this.initialCapacity);
+  }
+
+  isEmpty(): boolean {
+    return this.size === 0;
+  }
+
+  protected _hash(key: K): number {
+    return this._hashFn(key);
+  }
+
+  /**
+   * The `resizeTable` function resizes the table used in a hash map by creating a new table with a specified capacity and
+   * rehashing the key-value pairs from the old table into the new table.
+   * @param {number} newCapacity - The newCapacity parameter is the desired capacity for the resized table. It represents
+   * the number of buckets that the new table should have.
+   */
+  protected resizeTable(newCapacity: number): void {
+    const newTable = new Array(newCapacity);
+    for (const bucket of this._table) {
+      // Note that this is this._table
+      if (bucket) {
+        for (const [key, value] of bucket) {
+          const newIndex = this._hash(key) % newCapacity;
+          if (!newTable[newIndex]) {
+            newTable[newIndex] = [];
+          }
+          newTable[newIndex].push([key, value]);
+        }
+      }
+    }
+    this._table = newTable; // Again, here is this._table
+  }
+}