@graphty/algorithms 1.3.1 → 1.5.0

package/src/core/graph.ts

@@ -1,4 +1,4 @@
-import type {Edge, GraphConfig, Node, NodeId} from "../types/index.js";
+import type { Edge, GraphConfig, Node, NodeId } from "../types/index.js";
 
 /**
  * Core Graph data structure for the Graphty Algorithms library
@@ -13,12 +13,16 @@ export class Graph {
     private config: GraphConfig;
     private edgeCount: number;
 
+    /**
+     * Creates a new Graph instance.
+     * @param config - Configuration options for the graph
+     */
     constructor(config: Partial<GraphConfig> = {}) {
         this.config = {
             directed: false,
             allowSelfLoops: true,
             allowParallelEdges: false,
-            ... config,
+            ...config,
         };
         this.nodeMap = new Map();
         this.adjacencyList = new Map();
@@ -28,10 +32,12 @@ export class Graph {
 
     /**
      * Add a node to the graph
+     * @param id - The unique identifier for the node
+     * @param data - Optional key-value data to attach to the node
      */
     addNode(id: NodeId, data?: Record<string, unknown>): void {
         if (!this.nodeMap.has(id)) {
-            this.nodeMap.set(id, {id, data});
+            this.nodeMap.set(id, { id, data });
             this.adjacencyList.set(id, new Map());
 
             if (this.config.directed) {
@@ -42,6 +48,8 @@ export class Graph {
 
     /**
      * Remove a node from the graph
+     * @param id - The unique identifier of the node to remove
+     * @returns True if the node was removed, false if it did not exist
      */
     removeNode(id: NodeId): boolean {
         if (!this.nodeMap.has(id)) {
@@ -85,6 +93,10 @@ export class Graph {
 
     /**
      * Add an edge to the graph
+     * @param source - The source node identifier
+     * @param target - The target node identifier
+     * @param weight - The weight of the edge (defaults to 1)
+     * @param data - Optional key-value data to attach to the edge
      */
     addEdge(source: NodeId, target: NodeId, weight = 1, data?: Record<string, unknown>): void {
         // Ensure both nodes exist
@@ -101,7 +113,7 @@ export class Graph {
             throw new Error("Parallel edges are not allowed in this graph");
         }
 
-        const edge: Edge = {source, target, weight, data};
+        const edge: Edge = { source, target, weight, data };
 
         // Add to adjacency list
         const sourceAdjacency = this.adjacencyList.get(source);
@@ -120,7 +132,7 @@ export class Graph {
         } else {
             // For undirected graphs, add the reverse edge
             if (source !== target) {
-                const reverseEdge: Edge = {source: target, target: source, weight, data};
+                const reverseEdge: Edge = { source: target, target: source, weight, data };
                 const targetAdjacency = this.adjacencyList.get(target);
 
                 if (targetAdjacency) {
@@ -134,6 +146,9 @@ export class Graph {
 
     /**
      * Remove an edge from the graph
+     * @param source - The source node identifier
+     * @param target - The target node identifier
+     * @returns True if the edge was removed, false if it did not exist
      */
     removeEdge(source: NodeId, target: NodeId): boolean {
         const sourceEdges = this.adjacencyList.get(source);
@@ -162,6 +177,8 @@ export class Graph {
 
     /**
      * Check if a node exists in the graph
+     * @param id - The unique identifier of the node to check
+     * @returns True if the node exists, false otherwise
      */
     hasNode(id: NodeId): boolean {
         return this.nodeMap.has(id);
@@ -169,6 +186,9 @@ export class Graph {
 
     /**
      * Check if an edge exists in the graph
+     * @param source - The source node identifier
+     * @param target - The target node identifier
+     * @returns True if the edge exists, false otherwise
      */
     hasEdge(source: NodeId, target: NodeId): boolean {
         const sourceEdges = this.adjacencyList.get(source);
@@ -177,6 +197,8 @@ export class Graph {
 
     /**
      * Get a node by ID
+     * @param id - The unique identifier of the node to retrieve
+     * @returns The node if found, undefined otherwise
      */
     getNode(id: NodeId): Node | undefined {
         return this.nodeMap.get(id);
@@ -184,6 +206,9 @@ export class Graph {
 
     /**
      * Get an edge by source and target
+     * @param source - The source node identifier
+     * @param target - The target node identifier
+     * @returns The edge if found, undefined otherwise
      */
     getEdge(source: NodeId, target: NodeId): Edge | undefined {
         const sourceEdges = this.adjacencyList.get(source);
@@ -192,6 +217,7 @@ export class Graph {
 
     /**
      * Get the number of nodes in the graph
+     * @returns The total count of nodes
      */
     get nodeCount(): number {
         return this.nodeMap.size;
@@ -199,6 +225,7 @@ export class Graph {
 
     /**
      * Get the number of edges in the graph
+     * @returns The total count of edges
      */
     get totalEdgeCount(): number {
         return this.edgeCount;
@@ -206,6 +233,7 @@ export class Graph {
 
     /**
      * Check if the graph is directed
+     * @returns True if the graph is directed, false otherwise
      */
     get isDirected(): boolean {
         return this.config.directed;
@@ -213,6 +241,7 @@ export class Graph {
 
     /**
      * Get all nodes in the graph
+     * @returns An iterator over all nodes
      */
     nodes(): IterableIterator<Node> {
         return this.nodeMap.values();
@@ -220,6 +249,7 @@ export class Graph {
 
     /**
      * Get all edges in the graph
+     * @yields Each unique edge in the graph
      */
     *edges(): IterableIterator<Edge> {
         for (const [source, edges] of this.adjacencyList) {
@@ -236,6 +266,8 @@ export class Graph {
 
     /**
      * Get neighbors of a node (outgoing edges)
+     * @param nodeId - The node identifier to get neighbors for
+     * @returns An iterator over the neighbor node identifiers
      */
     neighbors(nodeId: NodeId): IterableIterator<NodeId> {
         const edges = this.adjacencyList.get(nodeId);
@@ -244,6 +276,8 @@ export class Graph {
 
     /**
      * Get incoming neighbors of a node (directed graphs only)
+     * @param nodeId - The node identifier to get incoming neighbors for
+     * @returns An iterator over the incoming neighbor node identifiers
      */
     inNeighbors(nodeId: NodeId): IterableIterator<NodeId> {
         if (!this.config.directed) {
@@ -256,6 +290,8 @@ export class Graph {
 
     /**
      * Get outgoing neighbors of a node
+     * @param nodeId - The node identifier to get outgoing neighbors for
+     * @returns An iterator over the outgoing neighbor node identifiers
      */
     outNeighbors(nodeId: NodeId): IterableIterator<NodeId> {
         return this.neighbors(nodeId);
@@ -263,6 +299,8 @@ export class Graph {
 
     /**
      * Get the degree of a node
+     * @param nodeId - The node identifier to get the degree for
+     * @returns The total degree of the node
      */
     degree(nodeId: NodeId): number {
         if (this.config.directed) {
@@ -275,6 +313,8 @@ export class Graph {
 
     /**
      * Get the in-degree of a node
+     * @param nodeId - The node identifier to get the in-degree for
+     * @returns The number of incoming edges to the node
      */
     inDegree(nodeId: NodeId): number {
         if (!this.config.directed) {
@@ -287,6 +327,8 @@ export class Graph {
 
     /**
      * Get the out-degree of a node
+     * @param nodeId - The node identifier to get the out-degree for
+     * @returns The number of outgoing edges from the node
      */
     outDegree(nodeId: NodeId): number {
         const edges = this.adjacencyList.get(nodeId);
@@ -295,23 +337,19 @@ export class Graph {
 
     /**
      * Create a copy of the graph
+     * @returns A new Graph instance with the same nodes and edges
      */
     clone(): Graph {
         const cloned = new Graph(this.config);
 
         // Copy nodes
         for (const node of this.nodeMap.values()) {
-            cloned.addNode(node.id, node.data ? {... node.data} : undefined);
+            cloned.addNode(node.id, node.data ? { ...node.data } : undefined);
         }
 
         // Copy edges
         for (const edge of this.edges()) {
-            cloned.addEdge(
-                edge.source,
-                edge.target,
-                edge.weight,
-                edge.data ? {... edge.data} : undefined,
-            );
+            cloned.addEdge(edge.source, edge.target, edge.weight, edge.data ? { ...edge.data } : undefined);
         }
 
         return cloned;
@@ -319,9 +357,10 @@ export class Graph {
 
     /**
      * Get graph configuration
+     * @returns A copy of the graph configuration object
      */
     getConfig(): GraphConfig {
-        return {... this.config};
+        return { ...this.config };
     }
 
     /**
@@ -337,6 +376,7 @@ export class Graph {
     /**
      * Get the number of unique edges in the graph
      * For undirected graphs, each edge is counted once
+     * @returns The count of unique edges
      */
     get uniqueEdgeCount(): number {
         if (this.config.directed) {
@@ -345,7 +385,7 @@ export class Graph {
 
         // For undirected graphs, we need to count each edge only once
         let count = 0;
-        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+         
         for (const _edge of this.edges()) {
             count++;
         }

package/src/data-structures/index.ts

@@ -2,5 +2,5 @@
  * Data structures supporting graph algorithms
  */
 
-export {PriorityQueue} from "./priority-queue.js";
-export {UnionFind} from "./union-find.js";
+export { PriorityQueue } from "./priority-queue.js";
+export { UnionFind } from "./union-find.js";

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

@@ -5,9 +5,13 @@
  * Uses a min-heap by default but supports custom comparison functions.
  */
 export class PriorityQueue<T> {
-    private heap: {item: T, priority: number}[];
+    private heap: { item: T; priority: number }[];
     private compareFn: (a: number, b: number) => number;
 
+    /**
+     * Creates a new PriorityQueue instance.
+     * @param compareFn - Custom comparison function for priorities. Returns negative if a has higher priority than b.
+     */
     constructor(compareFn?: (a: number, b: number) => number) {
         this.heap = [];
         // Default to min-heap (smaller priority values have higher priority)
@@ -16,15 +20,18 @@ export class PriorityQueue<T> {
 
     /**
      * Add an item with the given priority to the queue
+     * @param item - The item to add to the queue
+     * @param priority - The priority value for the item (lower values have higher priority in min-heap)
      */
     enqueue(item: T, priority: number): void {
-        const element = {item, priority};
+        const element = { item, priority };
         this.heap.push(element);
         this.heapifyUp(this.heap.length - 1);
     }
 
     /**
      * Remove and return the item with the highest priority
+     * @returns The item with the highest priority, or undefined if the queue is empty
      */
     dequeue(): T | undefined {
         if (this.heap.length === 0) {
@@ -52,6 +59,7 @@ export class PriorityQueue<T> {
 
     /**
      * View the item with the highest priority without removing it
+     * @returns The item with the highest priority, or undefined if the queue is empty
      */
     peek(): T | undefined {
         const first = this.heap[0];
@@ -60,6 +68,7 @@ export class PriorityQueue<T> {
 
     /**
      * Check if the queue is empty
+     * @returns True if the queue has no items, false otherwise
      */
     isEmpty(): boolean {
         return this.heap.length === 0;
@@ -67,6 +76,7 @@ export class PriorityQueue<T> {
 
     /**
      * Get the number of items in the queue
+     * @returns The number of items currently in the queue
      */
     size(): number {
         return this.heap.length;
@@ -74,7 +84,9 @@ export class PriorityQueue<T> {
 
     /**
      * Update the priority of an item if it exists in the queue
-     * Returns true if the item was found and updated
+     * @param item - The item whose priority should be updated
+     * @param newPriority - The new priority value for the item
+     * @returns True if the item was found and updated, false otherwise
      */
     updatePriority(item: T, newPriority: number): boolean {
         const index = this.heap.findIndex((element) => element.item === item);
@@ -110,13 +122,15 @@ export class PriorityQueue<T> {
 
     /**
      * Convert queue to array (for testing/debugging)
+     * @returns An array of all items with their priorities
      */
-    toArray(): {item: T, priority: number}[] {
-        return [... this.heap];
+    toArray(): { item: T; priority: number }[] {
+        return [...this.heap];
     }
 
     /**
      * Move element up the heap until heap property is satisfied
+     * @param index - The index of the element to heapify up
      */
     private heapifyUp(index: number): void {
         if (index === 0) {
@@ -136,26 +150,35 @@ export class PriorityQueue<T> {
 
     /**
      * Move element down the heap until heap property is satisfied
+     * @param index - The index of the element to heapify down
      */
     private heapifyDown(index: number): void {
-        const leftChildIndex = (2 * index) + 1;
-        const rightChildIndex = (2 * index) + 2;
+        const leftChildIndex = 2 * index + 1;
+        const rightChildIndex = 2 * index + 2;
         let targetIndex = index;
 
         // Find the child with highest priority (lowest value for min-heap)
         const leftChild = this.heap[leftChildIndex];
         const target = this.heap[targetIndex];
 
-        if (leftChildIndex < this.heap.length && leftChild && target &&
-            this.compareFn(leftChild.priority, target.priority) < 0) {
+        if (
+            leftChildIndex < this.heap.length &&
+            leftChild &&
+            target &&
+            this.compareFn(leftChild.priority, target.priority) < 0
+        ) {
             targetIndex = leftChildIndex;
         }
 
         const rightChild = this.heap[rightChildIndex];
         const newTarget = this.heap[targetIndex];
 
-        if (rightChildIndex < this.heap.length && rightChild && newTarget &&
-            this.compareFn(rightChild.priority, newTarget.priority) < 0) {
+        if (
+            rightChildIndex < this.heap.length &&
+            rightChild &&
+            newTarget &&
+            this.compareFn(rightChild.priority, newTarget.priority) < 0
+        ) {
             targetIndex = rightChildIndex;
         }
 
@@ -168,6 +191,8 @@ export class PriorityQueue<T> {
 
     /**
      * Swap two elements in the heap
+     * @param i - Index of the first element
+     * @param j - Index of the second element
      */
     private swap(i: number, j: number): void {
         const temp = this.heap[i];

package/src/data-structures/union-find.ts

@@ -1,4 +1,4 @@
-import type {NodeId} from "../types/index.js";
+import type { NodeId } from "../types/index.js";
 
 /**
  * Union-Find (Disjoint Set) data structure with path compression and union by rank
@@ -11,6 +11,10 @@ export class UnionFind {
     private rank: Map<NodeId, number>;
     private componentCount: number;
 
+    /**
+     * Creates a new UnionFind data structure with the given elements.
+     * @param elements - Array of elements to initialize the data structure with
+     */
     constructor(elements: NodeId[]) {
         this.parent = new Map();
         this.rank = new Map();
@@ -25,6 +29,8 @@ export class UnionFind {
 
     /**
      * Find the root of the set containing the element with path compression
+     * @param element - The element to find the root for
+     * @returns The root element of the set containing the given element
      */
     find(element: NodeId): NodeId {
         const parent = this.parent.get(element);
@@ -48,6 +54,8 @@ export class UnionFind {
 
     /**
      * Union two sets using union by rank
+     * @param elementA - The first element whose set should be merged
+     * @param elementB - The second element whose set should be merged
      */
     union(elementA: NodeId, elementB: NodeId): void {
         const rootA = this.find(elementA);
@@ -80,6 +88,9 @@ export class UnionFind {
 
     /**
      * Check if two elements are in the same connected component
+     * @param elementA - The first element to check
+     * @param elementB - The second element to check
+     * @returns True if both elements are in the same component, false otherwise
      */
     connected(elementA: NodeId, elementB: NodeId): boolean {
         try {
@@ -91,6 +102,7 @@ export class UnionFind {
 
     /**
      * Get the number of connected components
+     * @returns The current count of disjoint components
      */
     getComponentCount(): number {
         return this.componentCount;
@@ -98,6 +110,8 @@ export class UnionFind {
 
     /**
      * Get all elements that belong to the same component as the given element
+     * @param element - The element whose component should be retrieved
+     * @returns Array of all elements in the same component
      */
     getComponent(element: NodeId): NodeId[] {
         const root = this.find(element);
@@ -114,6 +128,7 @@ export class UnionFind {
 
     /**
      * Get all connected components as separate arrays
+     * @returns Array of arrays, where each inner array contains elements of one component
      */
     getAllComponents(): NodeId[][] {
         const componentMap = new Map<NodeId, NodeId[]>();
@@ -136,6 +151,8 @@ export class UnionFind {
 
     /**
      * Get the size of the component containing the given element
+     * @param element - The element whose component size should be retrieved
+     * @returns The number of elements in the component containing the given element
      */
     getComponentSize(element: NodeId): number {
         return this.getComponent(element).length;
@@ -143,6 +160,7 @@ export class UnionFind {
 
     /**
      * Add a new element to the data structure
+     * @param element - The element to add as a new singleton set
      */
     addElement(element: NodeId): void {
         if (this.parent.has(element)) {
@@ -156,6 +174,8 @@ export class UnionFind {
 
     /**
      * Check if an element exists in the data structure
+     * @param element - The element to check for
+     * @returns True if the element exists, false otherwise
      */
     hasElement(element: NodeId): boolean {
         return this.parent.has(element);
@@ -163,6 +183,7 @@ export class UnionFind {
 
     /**
      * Get the total number of elements
+     * @returns The total count of all elements in the data structure
      */
     size(): number {
         return this.parent.size;