data-structure-typed 1.18.0 → 1.18.5

package/backup/recursive-type/src/data-structures/graph/undirected-graph.ts

@@ -0,0 +1,293 @@
+/**
+ * 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 {VertexId} from '../types';
+
+export class UndirectedVertex<T = number> extends AbstractVertex<T> {
+    /**
+     * The constructor function initializes a vertex with an optional value.
+     * @param {VertexId} id - The `id` parameter is the identifier for the vertex. It is of type `VertexId`, which is
+     * typically a unique identifier for each vertex in a graph.
+     * @param {T} [val] - The "val" parameter is an optional parameter of type T. 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(id: VertexId, val?: T) {
+        super(id, val);
+    }
+
+    // _createVertex(id: VertexId, val?: T): T {
+    //     return new T(id, val);
+    // }
+}
+
+export class UndirectedEdge<T = number> extends AbstractEdge<T> {
+    /**
+     * The constructor function initializes an instance of a class with two vertex IDs, an optional weight, and an optional
+     * value.
+     * @param {VertexId} v1 - The parameter `v1` is of type `VertexId` and represents the first vertex in the edge.
+     * @param {VertexId} v2 - The parameter `v2` is a `VertexId`, 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 {T} [val] - The "val" parameter is an optional parameter of type T. It represents the value associated with
+     * the edge.
+     */
+    constructor(v1: VertexId, v2: VertexId, weight?: number, val?: T) {
+        super(weight, val);
+        this._vertices = [v1, v2];
+    }
+
+    private _vertices: [VertexId, VertexId];
+
+    get vertices() {
+        return this._vertices;
+    }
+
+    set vertices(v: [VertexId, VertexId]) {
+        this._vertices = v;
+    }
+
+    // _createEdge(src: VertexId, dest: VertexId, weight?: number, val?: T): T {
+    //     if (weight === undefined || weight === null) weight = 1;
+    //     return new UndirectedEdge(src, dest, weight, val);
+    // }
+}
+
+export class UndirectedGraph<V extends UndirectedVertex<any>, E extends UndirectedEdge<any>> extends AbstractGraph<V, E> {
+
+    private readonly _vertexConstructor: new (id: VertexId, val?: V['val']) => V;
+    private readonly _edgeConstructor: new (src: VertexId, dest: VertexId, weight?: number, val?: E['val']) => E;
+
+    constructor(vertexConstructor: new (id: VertexId, val?: V['val']) => V, edgeConstructor: new (src: VertexId, dest: VertexId, weight?: number, val?: E['val']) => E) {
+        super();
+        this._vertexConstructor = vertexConstructor;
+        this._edgeConstructor = edgeConstructor;
+        this._edges = new Map<V, E[]>();
+    }
+
+    protected _edges: Map<V, E[]>;
+
+    get edges(): Map<V, E[]> {
+        return this._edges;
+    }
+
+    /**
+     * In TypeScript, a subclass inherits the interface implementation of its parent class, without needing to implement the same interface again in the subclass. This behavior differs from Java's approach. In Java, if a parent class implements an interface, the subclass needs to explicitly implement the same interface, even if the parent class has already implemented it.
+     * This means that using abstract methods in the parent class cannot constrain the grandchild classes. Defining methods within an interface also cannot constrain the descendant classes. When inheriting from this class, developers need to be aware that this method needs to be overridden.
+     * @param id
+     * @param val
+     */
+    _createVertex(id: VertexId, val?: V['val']): V {
+        return new this._vertexConstructor(id, val);
+    }
+
+    /**
+     * In TypeScript, a subclass inherits the interface implementation of its parent class, without needing to implement the same interface again in the subclass. This behavior differs from Java's approach. In Java, if a parent class implements an interface, the subclass needs to explicitly implement the same interface, even if the parent class has already implemented it.
+     * This means that using abstract methods in the parent class cannot constrain the grandchild classes. Defining methods within an interface also cannot constrain the descendant classes. When inheriting from this class, developers need to be aware that this method needs to be overridden.
+     * @param src
+     * @param dest
+     * @param weight
+     * @param val
+     */
+    _createEdge(src: VertexId, dest: VertexId, weight?: number, val?: E['val']): E {
+        if (weight === undefined || weight === null) weight = 1;
+        return new this._edgeConstructor(src, dest, weight, val);
+    }
+
+    /**
+     * The function `getEdge` returns the first undirected edge that connects two given vertices, or null if no such edge
+     * exists.
+     * @param {V | null | VertexId} v1 - The parameter `v1` represents either an `V`
+     * object, `null`, or a `VertexId`. It is used to specify one of the vertices of the edge.
+     * @param {V | null | VertexId} v2 - The parameter `v2` represents either an `UndirectedVertex`
+     * object or a `VertexId` (identifier) of an undirected vertex.
+     * @returns an instance of `E` or `null`.
+     */
+    getEdge(v1: V | null | VertexId, v2: V | null | VertexId): E | null {
+        let edges: E[] | undefined = [];
+
+        if (v1 !== null && v2 !== null) {
+            const vertex1: V | null = this._getVertex(v1);
+            const vertex2: V | null = this._getVertex(v2);
+
+            if (vertex1 && vertex2) {
+                edges = this._edges.get(vertex1)?.filter(e => e.vertices.includes(vertex2.id));
+            }
+        }
+
+        return edges ? edges[0] || null : null;
+    }
+
+    /**
+     * The function adds an undirected edge to a graph by updating the adjacency list.
+     * @param edge - An object representing an undirected edge in a graph. It has a property called "vertices" which is an
+     * array of two vertices connected by the edge.
+     * @returns a boolean value.
+     */
+    addEdge(edge: E): 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;
+    }
+
+    /**
+     * The function removes an edge between two vertices in an undirected graph.
+     * @param {V | VertexId} v1 - The parameter `v1` represents either an `V` object or
+     * a `VertexId`. It is used to specify one of the vertices of the edge that needs to be removed.
+     * @param {V | VertexId} v2 - The parameter `v2` represents either an instance of the
+     * `UndirectedVertex` class or a `VertexId`. It is used to identify the second vertex of the edge that needs to be
+     * removed.
+     * @returns The function `removeEdgeBetween` returns an `E` object if an edge is successfully removed
+     * between the two vertices `v1` and `v2`. If either `v1` or `v2` is not found in the graph, or if there is no edge
+     * between them, the function returns `null`.
+     */
+    removeEdgeBetween(v1: V | VertexId, v2: V | VertexId): E | null {
+
+        const vertex1: V | null = this._getVertex(v1);
+        const vertex2: V | null = this._getVertex(v2);
+
+        if (!vertex1 || !vertex2) {
+            return null;
+        }
+
+        const v1Edges = this._edges.get(vertex1);
+        let removed: E | null = null;
+        if (v1Edges) {
+            removed = arrayRemove<E>(v1Edges, (e: E) => e.vertices.includes(vertex2.id))[0] || null;
+        }
+        const v2Edges = this._edges.get(vertex2);
+        if (v2Edges) {
+            arrayRemove<E>(v2Edges, (e: E) => e.vertices.includes(vertex1.id));
+        }
+        return removed;
+    }
+
+    /**
+     * The removeEdge function removes an edge between two vertices in an undirected graph.
+     * @param edge - An object representing an undirected edge. It has a property called "vertices" which is an array
+     * containing the two vertices connected by the edge.
+     * @returns The method is returning an UndirectedEdge object or null.
+     */
+    removeEdge(edge: E): E | null {
+        return this.removeEdgeBetween(edge.vertices[0], edge.vertices[1]);
+    }
+
+    /**
+     * The function "degreeOf" returns the degree of a given vertex in an undirected graph.
+     * @param {VertexId | V} vertexOrId - The parameter `vertexOrId` can be either a `VertexId` or an
+     * `V`.
+     * @returns the degree of the vertex.
+     */
+    degreeOf(vertexOrId: VertexId | V): number {
+        const vertex = this._getVertex(vertexOrId);
+        if (vertex) {
+            return this._edges.get(vertex)?.length || 0;
+        } else {
+            return 0;
+        }
+    }
+
+    /**
+     * The function "edgesOf" returns an array of undirected edges connected to a given vertex or vertex ID.
+     * @param {VertexId | V} vertexOrId - The parameter `vertexOrId` can be either a `VertexId` or an
+     * `V`.
+     * @returns an array of UndirectedEdge objects.
+     */
+    edgesOf(vertexOrId: VertexId | V): E[] {
+        const vertex = this._getVertex(vertexOrId);
+        if (vertex) {
+            return this._edges.get(vertex) || [];
+        } else {
+            return [];
+        }
+    }
+
+    /**
+     * The function "edgeSet" returns an array of unique undirected edges from a set of edges.
+     * @returns The method `edgeSet()` returns an array of `E` objects.
+     */
+    edgeSet(): E[] {
+        const edgeSet: Set<E> = new Set();
+        this._edges.forEach(edges => {
+            edges.forEach(edge => {
+                edgeSet.add(edge);
+            });
+        });
+        return [...edgeSet];
+    }
+
+    /**
+     * The function "getEdgesOf" returns an array of undirected edges connected to a given vertex or vertex ID.
+     * @param {V | VertexId} vertexOrId - The parameter `vertexOrId` can be either an
+     * `V` object or a `VertexId`.
+     * @returns The function `getEdgesOf` returns an array of `E` objects.
+     */
+    getEdgesOf(vertexOrId: V | VertexId): E[] {
+        const vertex = this._getVertex(vertexOrId);
+        if (!vertex) {
+            return [];
+        }
+        return this._edges.get(vertex) || [];
+    }
+
+    /**
+     * The function `getNeighbors` returns an array of neighboring vertices of a given vertex in an undirected graph.
+     * @param {V | VertexId} vertexOrId - The `vertexOrId` parameter can be either an
+     * `V` object or a `VertexId`. It represents the vertex for which we want to find the neighbors.
+     * @returns an array of UndirectedVertex objects.
+     */
+    getNeighbors(vertexOrId: V | VertexId): V[] {
+        const neighbors: V[] = [];
+        const vertex = this._getVertex(vertexOrId);
+        if (vertex) {
+            const neighborEdges = this.getEdgesOf(vertex);
+            for (const edge of neighborEdges) {
+                const neighbor = this._getVertex(edge.vertices.filter(e => e !== vertex.id)[0]);
+                if (neighbor) {
+                    neighbors.push(neighbor);
+                }
+            }
+        }
+        return neighbors;
+    }
+
+    /**
+     * The function "getEndsOfEdge" returns the two vertices that form the ends of a given undirected edge, or null if the
+     * edge does not exist in the graph.
+     * @param edge - An object representing an undirected edge in a graph. It has a property called "vertices" which is an
+     * array containing two vertices that the edge connects.
+     * @returns The function `getEndsOfEdge` returns an array containing the two ends of the given `edge` if the edge
+     * exists in the graph. If the edge does not exist, it returns `null`.
+     */
+    getEndsOfEdge(edge: E): [V, V] | 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;
+        }
+    }
+
+    protected _setEdges(v: Map<V, E[]>) {
+        this._edges = v;
+    }
+}

package/backup/recursive-type/src/data-structures/hash/coordinate-map.ts

@@ -0,0 +1,67 @@
+/**
+ * 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: string = '_';
+
+    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));
+    }
+
+    protected _setJoint(v: string) {
+        this._joint = v;
+    }
+}

package/backup/recursive-type/src/data-structures/hash/coordinate-set.ts

@@ -0,0 +1,56 @@
+/**
+ * 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: string = '_';
+
+    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));
+    }
+
+    protected _setJoint(v: string) {
+        this._joint = v;
+    }
+}

package/backup/recursive-type/src/data-structures/hash/hash-table.ts

@@ -0,0 +1,3 @@
+export class HashTable {
+
+}

package/backup/recursive-type/src/data-structures/hash/index.ts

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

package/backup/recursive-type/src/data-structures/hash/pair.ts

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

package/backup/recursive-type/src/data-structures/hash/tree-map.ts

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

package/backup/recursive-type/src/data-structures/hash/tree-set.ts

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

package/backup/recursive-type/src/data-structures/heap/heap.ts

@@ -0,0 +1,176 @@
+/**
+ * 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<T = number> {
+
+    constructor(priority: number = NaN, val: T | 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: T | null;
+
+    get val(): T | null {
+        return this._val;
+    }
+
+    set val(value: T | null) {
+        this._val = value;
+    }
+}
+
+export abstract class Heap<T = 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<T>) {
+        if (options) {
+            const {priority} = options;
+            if (priority !== undefined && typeof priority !== 'function') {
+                throw new Error('.constructor expects a valid priority function');
+            }
+            this._priorityCb = priority || ((el) => +el);
+        } else {
+            this._priorityCb = (el) => +el;
+        }
+    }
+
+    protected abstract _pq: PriorityQueue<HeapItem<T>>;
+
+    get pq() {
+        return this._pq;
+    }
+
+    protected _priorityCb: (val: T) => number;
+    get priorityCb() {
+        return this._priorityCb;
+    }
+
+    /**
+     * 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;
+    }
+
+    /**
+     * The `peek` function returns the top item in the priority queue without removing it.
+     * @returns The `peek()` method is returning either a `HeapItem<T>` object or `null`.Returns an val with the highest priority in the queue
+     */
+    peek(): HeapItem<T> | null {
+        return this._pq.peek();
+    }
+
+    /**
+     * The `peekLast` function returns the last item in the heap.
+     * @returns The method `peekLast()` returns either a `HeapItem<T>` object or `null`.Returns an val with the lowest priority in the queue
+     */
+    peekLast(): HeapItem<T> | null {
+        return this._pq.leaf();
+    }
+
+    /**
+     * The `add` function adds an val to a priority queue with an optional priority value.
+     * @param {T} 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(val: T, priority?: number): Heap<T> {
+        if (typeof val === 'number') {
+            priority = val;
+        } else {
+            if (priority === undefined) {
+                throw new Error('.add expects a numeric priority');
+            }
+        }
+
+        if (priority && Number.isNaN(+priority)) {
+            throw new Error('.add expects a numeric priority');
+        }
+
+        if (Number.isNaN(+priority) && Number.isNaN(this._priorityCb(val))) {
+            throw new Error(
+                '.add expects a numeric priority '
+                + 'or a constructor callback that returns a number'
+            );
+        }
+
+        const _priority = !Number.isNaN(+priority) ? priority : this._priorityCb(val);
+        this._pq.add(new HeapItem<T>(_priority, val));
+        return this;
+    }
+
+    /**
+     * 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<T> object or null.
+     */
+    poll(): HeapItem<T> | null {
+        const top = this._pq.poll();
+        if (!top) {
+            return null;
+        }
+        return top;
+    }
+
+    /**
+     * The function checks if a given node or value exists in the priority queue.
+     * @param {T | HeapItem<T>} node - The parameter `node` can be of type `T` or `HeapItem<T>`.
+     * @returns a boolean value.
+     */
+    has(node: T | HeapItem<T>): boolean {
+        if (node instanceof HeapItem) {
+            return this.pq.getNodes().includes(node);
+        } else {
+            return this.pq.getNodes().findIndex(item => {
+                return item.val === node;
+            }) !== -1;
+        }
+    }
+
+    /**
+     * The `toArray` function returns an array of `HeapItem<T>` objects.
+     * @returns An array of HeapItem<T> objects.Returns a sorted list of vals
+     */
+    toArray(): HeapItem<T>[] {
+        return this._pq.toArray();
+    }
+
+    /**
+     * The clear function clears the priority queue.
+     */
+    clear(): void {
+        this._pq.clear();
+    }
+}

package/backup/recursive-type/src/data-structures/heap/index.ts

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

package/backup/recursive-type/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<T = number> extends Heap<T> {
+    protected _pq: PriorityQueue<HeapItem<T>>;
+
+    /**
+     * 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<T>`, which is a generic type that represents the options for the heap.
+     */
+    constructor(options?: HeapOptions<T>) {
+        super(options);
+        this._pq = new PriorityQueue<HeapItem<T>>({
+            comparator: (a, b) => b.priority - a.priority
+        });
+    }
+}