@graphty/algorithms 1.3.1 → 1.5.0

package/dist/algorithms.js

@@ -1,4 +1,8 @@
 class Graph {
+  /**
+   * Creates a new Graph instance.
+   * @param config - Configuration options for the graph
+   */
   constructor(config = {}) {
     this.config = {
       directed: false,
@@ -13,6 +17,8 @@ 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, data) {
     if (!this.nodeMap.has(id)) {
@@ -25,6 +31,8 @@ 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) {
     if (!this.nodeMap.has(id)) {
@@ -59,6 +67,10 @@ 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, target, weight = 1, data) {
     this.addNode(source);
@@ -92,6 +104,9 @@ 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, target) {
     const sourceEdges = this.adjacencyList.get(source);
@@ -115,12 +130,17 @@ 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) {
     return this.nodeMap.has(id);
   }
   /**
    * 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, target) {
     const sourceEdges = this.adjacencyList.get(source);
@@ -128,12 +148,17 @@ 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) {
     return this.nodeMap.get(id);
   }
   /**
    * 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, target) {
     const sourceEdges = this.adjacencyList.get(source);
@@ -141,30 +166,35 @@ class Graph {
   }
   /**
    * Get the number of nodes in the graph
+   * @returns The total count of nodes
    */
   get nodeCount() {
     return this.nodeMap.size;
   }
   /**
    * Get the number of edges in the graph
+   * @returns The total count of edges
    */
   get totalEdgeCount() {
     return this.edgeCount;
   }
   /**
    * Check if the graph is directed
+   * @returns True if the graph is directed, false otherwise
    */
   get isDirected() {
     return this.config.directed;
   }
   /**
    * Get all nodes in the graph
+   * @returns An iterator over all nodes
    */
   nodes() {
     return this.nodeMap.values();
   }
   /**
    * Get all edges in the graph
+   * @yields Each unique edge in the graph
    */
   *edges() {
     for (const [source, edges] of this.adjacencyList) {
@@ -178,6 +208,8 @@ 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) {
     const edges = this.adjacencyList.get(nodeId);
@@ -185,6 +217,8 @@ 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) {
     if (!this.config.directed) {
@@ -195,12 +229,16 @@ 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) {
     return this.neighbors(nodeId);
   }
   /**
    * 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) {
     if (this.config.directed) {
@@ -211,6 +249,8 @@ 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) {
     if (!this.config.directed) {
@@ -221,6 +261,8 @@ 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) {
     const edges = this.adjacencyList.get(nodeId);
@@ -228,6 +270,7 @@ class Graph {
   }
   /**
    * Create a copy of the graph
+   * @returns A new Graph instance with the same nodes and edges
    */
   clone() {
     const cloned = new Graph(this.config);
@@ -235,17 +278,13 @@ class Graph {
       cloned.addNode(node.id, node.data ? { ...node.data } : void 0);
     }
     for (const edge of this.edges()) {
-      cloned.addEdge(
-        edge.source,
-        edge.target,
-        edge.weight,
-        edge.data ? { ...edge.data } : void 0
-      );
+      cloned.addEdge(edge.source, edge.target, edge.weight, edge.data ? { ...edge.data } : void 0);
     }
     return cloned;
   }
   /**
    * Get graph configuration
+   * @returns A copy of the graph configuration object
    */
   getConfig() {
     return { ...this.config };
@@ -262,6 +301,7 @@ 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() {
     if (this.config.directed) {
@@ -339,7 +379,7 @@ function requireSparseTypedFastBitSet() {
   }
   var SparseTypedFastBitSet$1 = (
     /** @class */
-    function() {
+    (function() {
       function SparseTypedFastBitSet2(iterable, data) {
         var e_1, _a;
         if (data === void 0) {
@@ -1520,7 +1560,7 @@ function requireSparseTypedFastBitSet() {
         }
       };
       return SparseTypedFastBitSet2;
-    }()
+    })()
   );
   SparseTypedFastBitSet.SparseTypedFastBitSet = SparseTypedFastBitSet$1;
   return SparseTypedFastBitSet;
@@ -1552,7 +1592,7 @@ function requireTypedFastBitSet() {
   }
   var TypedFastBitSet$1 = (
     /** @class */
-    function() {
+    (function() {
       function TypedFastBitSet2(iterable, words) {
         var e_1, _a;
         if (words === void 0) {
@@ -2044,7 +2084,7 @@ function requireTypedFastBitSet() {
         return answer;
       };
       return TypedFastBitSet2;
-    }()
+    })()
   );
   TypedFastBitSet.TypedFastBitSet = TypedFastBitSet$1;
   return TypedFastBitSet;
@@ -2053,8 +2093,8 @@ var hasRequiredLib;
 function requireLib() {
   if (hasRequiredLib) return lib;
   hasRequiredLib = 1;
-  (function(exports) {
-    var __createBinding = lib && lib.__createBinding || (Object.create ? function(o, m, k, k2) {
+  (function(exports$1) {
+    var __createBinding = lib && lib.__createBinding || (Object.create ? (function(o, m, k, k2) {
       if (k2 === void 0) k2 = k;
       var desc = Object.getOwnPropertyDescriptor(m, k);
       if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
@@ -2063,21 +2103,25 @@ function requireLib() {
         } };
       }
       Object.defineProperty(o, k2, desc);
-    } : function(o, m, k, k2) {
+    }) : (function(o, m, k, k2) {
       if (k2 === void 0) k2 = k;
       o[k2] = m[k];
-    });
-    var __exportStar = lib && lib.__exportStar || function(m, exports2) {
-      for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports2, p)) __createBinding(exports2, m, p);
+    }));
+    var __exportStar = lib && lib.__exportStar || function(m, exports$12) {
+      for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports$12, p)) __createBinding(exports$12, m, p);
     };
-    Object.defineProperty(exports, "__esModule", { value: true });
-    __exportStar(requireSparseTypedFastBitSet(), exports);
-    __exportStar(requireTypedFastBitSet(), exports);
+    Object.defineProperty(exports$1, "__esModule", { value: true });
+    __exportStar(requireSparseTypedFastBitSet(), exports$1);
+    __exportStar(requireTypedFastBitSet(), exports$1);
   })(lib);
   return lib;
 }
 var libExports = requireLib();
 class GraphBitSet {
+  /**
+   * Creates a new GraphBitSet with optional pre-allocated capacity.
+   * @param capacity - The initial capacity to pre-allocate for the bitset
+   */
   constructor(capacity) {
     this._cardinality = 0;
     this.bitset = new libExports.TypedFastBitSet();
@@ -2086,8 +2130,9 @@ class GraphBitSet {
     }
   }
   /**
-  * Add a single element
-  */
+   * Add a single element to the set.
+   * @param index - The element index to add
+   */
   add(index) {
     if (!this.bitset.has(index)) {
       this.bitset.add(index);
@@ -2095,8 +2140,9 @@ class GraphBitSet {
     }
   }
   /**
-  * Remove a single element
-  */
+   * Remove a single element from the set.
+   * @param index - The element index to remove
+   */
   remove(index) {
     if (this.bitset.has(index)) {
       this.bitset.remove(index);
@@ -2104,27 +2150,32 @@ class GraphBitSet {
     }
   }
   /**
-  * Check if element exists
-  */
+   * Check if an element exists in the set.
+   * @param index - The element index to check
+   * @returns True if the element exists, false otherwise
+   */
   has(index) {
     return this.bitset.has(index);
   }
   /**
-  * Clear all elements
-  */
+   * Clear all elements
+   */
   clear() {
     this.bitset.clear();
     this._cardinality = 0;
   }
   /**
-  * Check if empty
-  */
+   * Check if the set is empty.
+   * @returns True if the set contains no elements, false otherwise
+   */
   isEmpty() {
     return this._cardinality === 0;
   }
   /**
-  * Optimized for graph algorithms - add range of indices
-  */
+   * Optimized for graph algorithms - add a range of indices.
+   * @param start - The starting index (inclusive)
+   * @param end - The ending index (exclusive)
+   */
   addRange(start, end) {
     for (let i = start; i < end; i++) {
       if (!this.bitset.has(i)) {
@@ -2134,39 +2185,51 @@ class GraphBitSet {
     }
   }
   /**
-  * Fast cardinality tracking
-  */
+   * Fast cardinality tracking - get the number of elements in the set.
+   * @returns The number of elements in the set
+   */
   size() {
     return this._cardinality;
   }
   /**
-  * Batch operations for frontier management - swap contents
-  */
+   * Batch operations for frontier management - swap contents with another GraphBitSet.
+   * @param other - The GraphBitSet to swap contents with
+   */
   swap(other) {
     [this.bitset, other.bitset] = [other.bitset, this.bitset];
     [this._cardinality, other._cardinality] = [other._cardinality, this._cardinality];
   }
   /**
-  * Efficient iteration
-  */
+   * Efficient iteration over all elements in the set.
+   * @yields The indices of elements in the set
+   */
   *[Symbol.iterator]() {
     yield* this.bitset;
   }
   /**
-  * Set operations with cardinality tracking
-  */
+   * Perform union operation with another GraphBitSet, updating this set in place.
+   * @param other - The GraphBitSet to union with
+   */
   union(other) {
     const result = this.bitset.union(other.bitset);
     this.bitset = result;
     const size = this.bitset.size();
     this._cardinality = size;
   }
+  /**
+   * Perform intersection operation with another GraphBitSet, updating this set in place.
+   * @param other - The GraphBitSet to intersect with
+   */
   intersection(other) {
     const result = this.bitset.intersection(other.bitset);
     this.bitset = result;
     const size = this.bitset.size();
     this._cardinality = size;
   }
+  /**
+   * Perform difference operation with another GraphBitSet, updating this set in place.
+   * @param other - The GraphBitSet to subtract from this set
+   */
   difference(other) {
     const result = this.bitset.difference(other.bitset);
     this.bitset = result;
@@ -2174,8 +2237,9 @@ class GraphBitSet {
     this._cardinality = size;
   }
   /**
-  * Clone the bitset
-  */
+   * Clone the bitset.
+   * @returns A new GraphBitSet with the same elements
+   */
   clone() {
     const cloned = new GraphBitSet();
     cloned.bitset = this.bitset.clone();
@@ -2184,14 +2248,19 @@ class GraphBitSet {
   }
 }
 class VisitedBitArray {
+  /**
+   * Creates a new VisitedBitArray with the specified size.
+   * @param size - The number of bits to allocate
+   */
   constructor(size) {
     this._size = size;
     this.wordCount = Math.ceil(size / 32);
     this.words = new Uint32Array(this.wordCount);
   }
   /**
-  * Set bit at index
-  */
+   * Set bit at the specified index.
+   * @param index - The bit index to set
+   */
   set(index) {
     if (index < 0 || index >= this._size) {
       throw new Error(`Index ${String(index)} out of bounds [0, ${String(this._size)})`);
@@ -2204,8 +2273,10 @@ class VisitedBitArray {
     }
   }
   /**
-  * Get bit at index
-  */
+   * Get bit value at the specified index.
+   * @param index - The bit index to get
+   * @returns True if the bit is set, false otherwise
+   */
   get(index) {
     if (index < 0 || index >= this._size) {
       return false;
@@ -2216,14 +2287,15 @@ class VisitedBitArray {
     return word !== void 0 && (word & 1 << bitIndex) !== 0;
   }
   /**
-  * Clear all bits
-  */
+   * Clear all bits
+   */
   clear() {
     this.words.fill(0);
   }
   /**
-  * Toggle bit at index
-  */
+   * Toggle bit at the specified index.
+   * @param index - The bit index to toggle
+   */
   toggle(index) {
     if (index < 0 || index >= this._size) {
       throw new Error(`Index ${String(index)} out of bounds [0, ${String(this._size)})`);
@@ -2236,8 +2308,9 @@ class VisitedBitArray {
     }
   }
   /**
-  * Population count for statistics
-  */
+   * Population count for statistics - count the number of set bits.
+   * @returns The number of bits set to 1
+   */
   popcount() {
     let count = 0;
     for (let i = 0; i < this.wordCount; i++) {
@@ -2249,9 +2322,11 @@ class VisitedBitArray {
     return count;
   }
   /**
-  * Efficient population count for a single word
-  * Uses bit manipulation tricks for fast counting
-  */
+   * Efficient population count for a single word.
+   * Uses bit manipulation tricks for fast counting.
+   * @param n - The 32-bit word to count
+   * @returns The number of bits set to 1 in the word
+   */
   popcountWord(n) {
     let x = n;
     x = x - (x >>> 1 & 1431655765);
@@ -2259,14 +2334,16 @@ class VisitedBitArray {
     return (x + (x >>> 4) & 252645135) * 16843009 >>> 24;
   }
   /**
-  * Get size of the bit array
-  */
+   * Get size of the bit array.
+   * @returns The total number of bits in the array
+   */
   size() {
     return this._size;
   }
   /**
-  * Check if all bits are zero
-  */
+   * Check if all bits are zero.
+   * @returns True if no bits are set, false otherwise
+   */
   isEmpty() {
     for (let i = 0; i < this.wordCount; i++) {
       if (this.words[i] !== 0) {
@@ -2276,16 +2353,18 @@ class VisitedBitArray {
     return true;
   }
   /**
-  * Set multiple bits from array
-  */
+   * Set multiple bits from an array of indices.
+   * @param indices - Array of bit indices to set
+   */
   setMultiple(indices) {
     for (const index of indices) {
       this.set(index);
     }
   }
   /**
-  * Get indices of all set bits
-  */
+   * Get indices of all set bits.
+   * @returns Array containing the indices of all bits that are set to 1
+   */
   getSetIndices() {
     const indices = [];
     for (let wordIndex = 0; wordIndex < this.wordCount; wordIndex++) {
@@ -2306,14 +2385,20 @@ class VisitedBitArray {
   }
 }
 const _CompactDistanceArray = class _CompactDistanceArray {
+  /**
+   * Creates a new CompactDistanceArray with the specified size.
+   * @param size - The number of distance values to store
+   */
   constructor(size) {
     this._size = size;
     this.data = new Uint16Array(size);
     this.data.fill(_CompactDistanceArray.INFINITY);
   }
   /**
-  * Set distance at index
-  */
+   * Set distance at the specified index.
+   * @param index - The node index to set the distance for
+   * @param distance - The distance value to set
+   */
   set(index, distance) {
     if (distance >= _CompactDistanceArray.INFINITY) {
       throw new Error(`Distance exceeds maximum value (${String(_CompactDistanceArray.INFINITY - 1)})`);
@@ -2321,27 +2406,32 @@ const _CompactDistanceArray = class _CompactDistanceArray {
     this.data[index] = distance;
   }
   /**
-  * Get distance at index
-  */
+   * Get distance at the specified index.
+   * @param index - The node index to get the distance for
+   * @returns The distance value, or INFINITY if not set
+   */
   get(index) {
     const value = this.data[index];
     return value ?? _CompactDistanceArray.INFINITY;
   }
   /**
-  * Check if node has been visited
-  */
+   * Check if a node has been visited (has a valid distance).
+   * @param index - The node index to check
+   * @returns True if the node has been visited, false otherwise
+   */
   isVisited(index) {
     return this.data[index] !== _CompactDistanceArray.INFINITY;
   }
   /**
-  * Reset all distances
-  */
+   * Reset all distances to unvisited state.
+   */
   clear() {
     this.data.fill(_CompactDistanceArray.INFINITY);
   }
   /**
-  * Get size
-  */
+   * Get the size of the distance array.
+   * @returns The number of elements in the array
+   */
   size() {
     return this._size;
   }
@@ -2349,6 +2439,11 @@ const _CompactDistanceArray = class _CompactDistanceArray {
 _CompactDistanceArray.INFINITY = 65535;
 let CompactDistanceArray = _CompactDistanceArray;
 class DirectionOptimizedBFS {
+  /**
+   * Creates a new DirectionOptimizedBFS instance.
+   * @param graph - The CSR graph to perform BFS on
+   * @param options - Optional configuration for switching thresholds
+   */
   constructor(graph, options) {
     this.graph = graph;
     this.alpha = options?.alpha ?? 15;
@@ -2360,8 +2455,10 @@ class DirectionOptimizedBFS {
     this.distances = new CompactDistanceArray(nodeCount);
   }
   /**
-  * Perform BFS from a single source
-  */
+   * Perform BFS from a single source node.
+   * @param source - The source node ID to start the BFS from
+   * @returns The BFS result containing distances and parent pointers
+   */
   search(source) {
     const sourceIndex = this.graph.nodeToIndex(source);
     this.parent[sourceIndex] = -2;
@@ -2396,8 +2493,9 @@ class DirectionOptimizedBFS {
     return this.buildResult();
   }
   /**
-  * Top-down BFS step - explore from frontier
-  */
+   * Top-down BFS step - explore from frontier.
+   * @returns The scout count (total degree of newly discovered nodes)
+   */
   topDownStep() {
     let scoutCount = 0;
     for (const node of this.frontier) {
@@ -2414,8 +2512,9 @@ class DirectionOptimizedBFS {
     return scoutCount;
   }
   /**
-  * Bottom-up BFS step - check unvisited nodes
-  */
+   * Bottom-up BFS step - check unvisited nodes for frontier neighbors.
+   * @returns The number of newly discovered nodes
+   */
   bottomUpStep() {
     const nodeCount = this.graph.nodeCount();
     let awakeCount = 0;
@@ -2436,8 +2535,9 @@ class DirectionOptimizedBFS {
     return awakeCount;
   }
   /**
-  * Calculate edges to check for switching heuristic
-  */
+   * Calculate edges to check for switching heuristic.
+   * @returns The total number of outgoing edges from frontier nodes
+   */
   calculateEdgesToCheck() {
     let count = 0;
     for (const node of this.frontier) {
@@ -2446,8 +2546,9 @@ class DirectionOptimizedBFS {
     return count;
   }
   /**
-  * Build result map from internal data structures
-  */
+   * Build result map from internal data structures.
+   * @returns The BFS result containing distances and parent pointers
+   */
   buildResult() {
     const distances = /* @__PURE__ */ new Map();
     const parents = /* @__PURE__ */ new Map();
@@ -2470,8 +2571,10 @@ class DirectionOptimizedBFS {
     return { distances, parents, visitedCount };
   }
   /**
-  * Perform multi-source BFS
-  */
+   * Perform multi-source BFS from multiple source nodes.
+   * @param sources - Array of source node IDs to start the BFS from
+   * @returns The BFS result containing distances and parent pointers
+   */
   searchMultiple(sources) {
     for (const source of sources) {
       const sourceIndex = this.graph.nodeToIndex(source);
@@ -2513,8 +2616,8 @@ class DirectionOptimizedBFS {
     return this.buildResult();
   }
   /**
-  * Reset internal state for reuse
-  */
+   * Reset internal state for reuse
+   */
   reset() {
     this.parent.fill(-1);
     this.frontier.clear();
@@ -2523,12 +2626,22 @@ class DirectionOptimizedBFS {
   }
 }
 class CSRGraph {
+  /**
+   * Creates a new CSRGraph from an adjacency list representation.
+   * @param adjacencyList - Map of node IDs to arrays of neighbor node IDs
+   * @param weights - Optional map of edge weights keyed by "source-target" strings
+   * @param buildReverse - Whether to build reverse edges for bottom-up BFS (default true)
+   */
   constructor(adjacencyList, weights, buildReverse = true) {
     this.data = this.buildCSR(adjacencyList, weights, buildReverse);
   }
   /**
-  * Build CSR structure from adjacency list
-  */
+   * Build CSR structure from adjacency list.
+   * @param adjacencyList - Map of node IDs to arrays of neighbor node IDs
+   * @param weights - Optional map of edge weights keyed by "source-target" strings
+   * @param buildReverse - Whether to build reverse edges for bottom-up BFS
+   * @returns The constructed CSR graph data structure
+   */
   buildCSR(adjacencyList, weights, buildReverse = true) {
     const allNodes = /* @__PURE__ */ new Set();
     for (const [source, neighbors] of adjacencyList) {
@@ -2631,15 +2744,34 @@ class CSRGraph {
     return result;
   }
   // Core API methods
+  /**
+   * Get the total number of nodes in the graph.
+   * @returns The number of nodes
+   */
   nodeCount() {
     return this.data.indexToNodeId.length;
   }
+  /**
+   * Get the total number of edges in the graph.
+   * @returns The number of edges
+   */
   edgeCount() {
     return this.data.columnIndices.length;
   }
+  /**
+   * Check if a node exists in the graph.
+   * @param nodeId - The node ID to check
+   * @returns True if the node exists, false otherwise
+   */
   hasNode(nodeId) {
     return this.data.nodeIdToIndex.has(nodeId);
   }
+  /**
+   * Check if an edge exists between two nodes.
+   * @param source - The source node ID
+   * @param target - The target node ID
+   * @returns True if the edge exists, false otherwise
+   */
   hasEdge(source, target) {
     const sourceIndex = this.data.nodeIdToIndex.get(source);
     const targetIndex = this.data.nodeIdToIndex.get(target);
@@ -2654,8 +2786,10 @@ class CSRGraph {
     return this.binarySearch(this.data.columnIndices, targetIndex, start, end) !== -1;
   }
   /**
-  * Get neighbors as node IDs
-  */
+   * Get neighbors of a node as node IDs.
+   * @param nodeId - The node ID to get neighbors for
+   * @returns An iterator over neighbor node IDs
+   */
   neighbors(nodeId) {
     const nodeIndex = this.data.nodeIdToIndex.get(nodeId);
     if (nodeIndex === void 0) {
@@ -2680,14 +2814,17 @@ class CSRGraph {
     return generateNeighbors();
   }
   /**
-  * Get all nodes
-  */
+   * Get all nodes in the graph.
+   * @returns An iterator over all node IDs
+   */
   nodes() {
     return this.data.indexToNodeId.values();
   }
   /**
-  * Get neighbors as indices (internal use)
-  */
+   * Get neighbors as indices (internal use).
+   * @param nodeIndex - The internal index of the node
+   * @returns Array of neighbor indices
+   */
   getNeighborIndices(nodeIndex) {
     if (nodeIndex < 0 || nodeIndex >= this.data.indexToNodeId.length) {
       return [];
@@ -2699,6 +2836,11 @@ class CSRGraph {
     }
     return Array.from(this.data.columnIndices.subarray(start, end));
   }
+  /**
+   * Get the out-degree (number of outgoing edges) of a node.
+   * @param nodeId - The node ID to get the out-degree for
+   * @returns The number of outgoing edges from the node
+   */
   outDegree(nodeId) {
     const nodeIndex = this.data.nodeIdToIndex.get(nodeId);
     if (nodeIndex === void 0) {
@@ -2707,8 +2849,10 @@ class CSRGraph {
     return this.outDegreeByIndex(nodeIndex);
   }
   /**
-  * Get out-degree by index (internal use)
-  */
+   * Get out-degree by index (internal use).
+   * @param nodeIndex - The internal index of the node
+   * @returns The number of outgoing edges from the node
+   */
   outDegreeByIndex(nodeIndex) {
     const start = this.data.rowPointers[nodeIndex];
     const end = this.data.rowPointers[nodeIndex + 1];
@@ -2718,8 +2862,10 @@ class CSRGraph {
     return 0;
   }
   /**
-  * Iterator support for neighbor indices
-  */
+   * Iterator support for neighbor indices.
+   * @param nodeIndex - The internal index of the node
+   * @yields The indices of neighboring nodes
+   */
   *iterateNeighborIndices(nodeIndex) {
     const start = this.data.rowPointers[nodeIndex];
     const end = this.data.rowPointers[nodeIndex + 1];
@@ -2733,8 +2879,10 @@ class CSRGraph {
     }
   }
   /**
-  * Iterator support for incoming neighbor indices (for bottom-up BFS)
-  */
+   * Iterator support for incoming neighbor indices (for bottom-up BFS).
+   * @param nodeIndex - The internal index of the node
+   * @yields The indices of nodes with edges pointing to this node
+   */
   *iterateIncomingNeighborIndices(nodeIndex) {
     if (!this.data.reverseRowPointers || !this.data.reverseColumnIndices) {
       return;
@@ -2751,8 +2899,10 @@ class CSRGraph {
     }
   }
   /**
-  * Convert node ID to index
-  */
+   * Convert node ID to internal index.
+   * @param nodeId - The node ID to convert
+   * @returns The internal index for the node
+   */
   nodeToIndex(nodeId) {
     const index = this.data.nodeIdToIndex.get(nodeId);
     if (index === void 0) {
@@ -2761,8 +2911,10 @@ class CSRGraph {
     return index;
   }
   /**
-  * Convert index to node ID
-  */
+   * Convert internal index to node ID.
+   * @param index - The internal index to convert
+   * @returns The node ID for the given index
+   */
   indexToNodeId(index) {
     const nodeId = this.data.indexToNodeId[index];
     if (nodeId === void 0) {
@@ -2771,8 +2923,11 @@ class CSRGraph {
     return nodeId;
   }
   /**
-  * Get edge weight
-  */
+   * Get edge weight between two nodes.
+   * @param source - The source node ID
+   * @param target - The target node ID
+   * @returns The edge weight, or undefined if the edge doesn't exist or has no weight
+   */
   getEdgeWeight(source, target) {
     if (!this.data.edgeWeights) {
       return void 0;
@@ -2794,8 +2949,13 @@ class CSRGraph {
     return this.data.edgeWeights[edgeIndex];
   }
   /**
-  * Binary search for target in sorted array
-  */
+   * Binary search for target in sorted array.
+   * @param arr - The typed array to search in
+   * @param target - The value to search for
+   * @param start - The starting index (inclusive)
+   * @param end - The ending index (exclusive)
+   * @returns The index of the target, or -1 if not found
+   */
   binarySearch(arr, target, start, end) {
     let left = start;
     let right = end - 1;
@@ -2817,8 +2977,14 @@ class CSRGraph {
     return -1;
   }
   /**
-  * Create CSR graph from standard Graph
-  */
+   * Create CSR graph from standard Graph interface.
+   * @param graph - The graph object to convert, must implement nodes, neighbors, hasNode, and optionally getEdge
+   * @param graph.nodes - Function that returns an iterator over node objects with id property
+   * @param graph.neighbors - Function that returns an iterator over neighbor node IDs
+   * @param graph.hasNode - Function that checks if a node exists in the graph
+   * @param graph.getEdge - Optional function that returns edge data including weight
+   * @returns A new CSRGraph instance
+   */
   static fromGraph(graph) {
     const adjacencyList = /* @__PURE__ */ new Map();
     const weights = /* @__PURE__ */ new Map();
@@ -2839,6 +3005,10 @@ class CSRGraph {
   }
 }
 class GraphAdapter {
+  /**
+   * Creates a new GraphAdapter that wraps or converts a graph to CSR format.
+   * @param graph - The graph to adapt (either standard Graph or ReadonlyGraph)
+   */
   constructor(graph) {
     if (graph instanceof CSRGraph) {
       this.csrGraph = graph;
@@ -2847,8 +3017,10 @@ class GraphAdapter {
     }
   }
   /**
-  * Convert standard graph to CSR format
-  */
+   * Convert standard graph to CSR format.
+   * @param graph - The graph to convert
+   * @returns A new CSRGraph instance
+   */
   convertToCSR(graph) {
     const adjacencyList = /* @__PURE__ */ new Map();
     const weights = /* @__PURE__ */ new Map();
@@ -2888,30 +3060,64 @@ class GraphAdapter {
     return new CSRGraph(adjacencyList, weights.size > 0 ? weights : void 0);
   }
   // Delegate all methods to CSR implementation
+  /**
+   * Get the total number of nodes in the graph.
+   * @returns The number of nodes
+   */
   nodeCount() {
     return this.csrGraph.nodeCount();
   }
+  /**
+   * Get the total number of edges in the graph.
+   * @returns The number of edges
+   */
   edgeCount() {
     return this.csrGraph.edgeCount();
   }
+  /**
+   * Check if a node exists in the graph.
+   * @param nodeId - The node ID to check
+   * @returns True if the node exists, false otherwise
+   */
   hasNode(nodeId) {
     return this.csrGraph.hasNode(nodeId);
   }
+  /**
+   * Check if an edge exists between two nodes.
+   * @param source - The source node ID
+   * @param target - The target node ID
+   * @returns True if the edge exists, false otherwise
+   */
   hasEdge(source, target) {
     return this.csrGraph.hasEdge(source, target);
   }
+  /**
+   * Get neighbors of a node as node IDs.
+   * @param nodeId - The node ID to get neighbors for
+   * @returns An iterator over neighbor node IDs
+   */
   neighbors(nodeId) {
     return this.csrGraph.neighbors(nodeId);
   }
+  /**
+   * Get the out-degree (number of outgoing edges) of a node.
+   * @param nodeId - The node ID to get the out-degree for
+   * @returns The number of outgoing edges from the node
+   */
   outDegree(nodeId) {
     return this.csrGraph.outDegree(nodeId);
   }
+  /**
+   * Get all nodes in the graph.
+   * @returns An iterator over all node IDs
+   */
   nodes() {
     return this.csrGraph.nodes();
   }
   /**
-  * Get the underlying CSR graph
-  */
+   * Get the underlying CSR graph.
+   * @returns The CSRGraph instance used internally
+   */
   getCSRGraph() {
     return this.csrGraph;
   }
@@ -2962,12 +3168,8 @@ function reconstructPath(target, predecessor) {
   return path;
 }
 function getCommonNeighbors(graph, source, target, directed = false) {
-  const sourceNeighbors = new Set(
-    directed ? graph.outNeighbors(source) : graph.neighbors(source)
-  );
-  const targetNeighbors = new Set(
-    directed ? graph.outNeighbors(target) : graph.neighbors(target)
-  );
+  const sourceNeighbors = new Set(directed ? graph.outNeighbors(source) : graph.neighbors(source));
+  const targetNeighbors = new Set(directed ? graph.outNeighbors(target) : graph.neighbors(target));
   const common = /* @__PURE__ */ new Set();
   for (const neighbor of sourceNeighbors) {
     if (targetNeighbors.has(neighbor)) {
@@ -3528,12 +3730,18 @@ function hasNegativeCycle(graph) {
   return false;
 }
 class PriorityQueue {
+  /**
+   * Creates a new PriorityQueue instance.
+   * @param compareFn - Custom comparison function for priorities. Returns negative if a has higher priority than b.
+   */
   constructor(compareFn) {
     this.heap = [];
     this.compareFn = compareFn ?? ((a, b) => a - b);
   }
   /**
    * 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, priority) {
     const element = { item, priority };
@@ -3542,6 +3750,7 @@ class PriorityQueue {
   }
   /**
    * Remove and return the item with the highest priority
+   * @returns The item with the highest priority, or undefined if the queue is empty
    */
   dequeue() {
     if (this.heap.length === 0) {
@@ -3563,6 +3772,7 @@ class PriorityQueue {
   }
   /**
    * 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() {
     const first = this.heap[0];
@@ -3570,19 +3780,23 @@ class PriorityQueue {
   }
   /**
    * Check if the queue is empty
+   * @returns True if the queue has no items, false otherwise
    */
   isEmpty() {
     return this.heap.length === 0;
   }
   /**
    * Get the number of items in the queue
+   * @returns The number of items currently in the queue
    */
   size() {
     return this.heap.length;
   }
   /**
    * 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, newPriority) {
     const index = this.heap.findIndex((element2) => element2.item === item);
@@ -3610,12 +3824,14 @@ class PriorityQueue {
   }
   /**
    * Convert queue to array (for testing/debugging)
+   * @returns An array of all items with their priorities
    */
   toArray() {
     return [...this.heap];
   }
   /**
    * Move element up the heap until heap property is satisfied
+   * @param index - The index of the element to heapify up
    */
   heapifyUp(index) {
     if (index === 0) {
@@ -3631,6 +3847,7 @@ class PriorityQueue {
   }
   /**
    * Move element down the heap until heap property is satisfied
+   * @param index - The index of the element to heapify down
    */
   heapifyDown(index) {
     const leftChildIndex = 2 * index + 1;
@@ -3653,6 +3870,8 @@ class PriorityQueue {
   }
   /**
    * Swap two elements in the heap
+   * @param i - Index of the first element
+   * @param j - Index of the second element
    */
   swap(i, j) {
     const temp = this.heap[i];
@@ -3664,6 +3883,10 @@ class PriorityQueue {
   }
 }
 class BidirectionalDijkstra {
+  /**
+   * Creates a new BidirectionalDijkstra instance
+   * @param graph - The graph to search for shortest paths
+   */
   constructor(graph) {
     this.meetingNode = null;
     this.shortestDistance = Infinity;
@@ -3680,8 +3903,11 @@ class BidirectionalDijkstra {
     };
   }
   /**
-  * Find shortest path between source and target nodes
-  */
+   * Find shortest path between source and target nodes
+   * @param source - The starting node for the path
+   * @param target - The destination node for the path
+   * @returns The shortest path result or null if no path exists
+   */
   findShortestPath(source, target) {
     this.reset();
     if (!this.graph.hasNode(source)) {
@@ -3773,7 +3999,7 @@ class BidirectionalDijkstra {
     }
     return false;
   }
-  getMinDistance(frontier) {
+  _getMinDistance(frontier) {
     if (frontier.isEmpty()) {
       return Infinity;
     }
@@ -3806,8 +4032,8 @@ class BidirectionalDijkstra {
     return path;
   }
   /**
-  * Reset the search state for reuse
-  */
+   * Reset the search state for reuse
+   */
   reset() {
     this.forwardSearch = this.initSearchState();
     this.backwardSearch = this.initSearchState();
@@ -4583,7 +4809,12 @@ function nodeClosenessCentrality(graph, node, options = {}) {
   if (!graph.hasNode(node)) {
     throw new Error(`Node ${String(node)} not found in graph`);
   }
-  const distances = bfsDistancesOnly(graph, node, options.cutoff, options.optimized !== void 0 ? { optimized: options.optimized } : {});
+  const distances = bfsDistancesOnly(
+    graph,
+    node,
+    options.cutoff,
+    options.optimized !== void 0 ? { optimized: options.optimized } : {}
+  );
   const totalNodes = graph.nodeCount;
   return calculateClosenessFromDistances(distances, node, totalNodes, options);
 }
@@ -4599,7 +4830,12 @@ function nodeWeightedClosenessCentrality(graph, node, options = {}) {
   if (!graph.hasNode(node)) {
     throw new Error(`Node ${String(node)} not found in graph`);
   }
-  const distances = bfsWeightedDistances(graph, node, options.cutoff, options.optimized !== void 0 ? { optimized: options.optimized } : {});
+  const distances = bfsWeightedDistances(
+    graph,
+    node,
+    options.cutoff,
+    options.optimized !== void 0 ? { optimized: options.optimized } : {}
+  );
   const totalNodes = graph.nodeCount;
   return calculateClosenessFromDistances(distances, node, totalNodes, options);
 }
@@ -4666,6 +4902,10 @@ function nodeDegreeCentrality(graph, nodeId, options = {}) {
   return options.normalized && maxPossibleDegree > 0 ? degree / maxPossibleDegree : degree;
 }
 class DeltaPageRank {
+  /**
+   * Creates a new DeltaPageRank instance for the given graph.
+   * @param graph - The directed graph to compute PageRank on
+   */
   constructor(graph) {
     if (!graph.isDirected) {
       throw new Error("DeltaPageRank requires a directed graph");
@@ -4701,6 +4941,11 @@ class DeltaPageRank {
       }
     }
   }
+  /**
+   * Computes PageRank scores using delta-based iteration for faster convergence.
+   * @param options - Configuration options for PageRank computation
+   * @returns Map of node IDs to their PageRank scores
+   */
   compute(options = {}) {
     const {
       dampingFactor = 0.85,
@@ -4796,8 +5041,11 @@ class DeltaPageRank {
     return new Map(this.scores);
   }
   /**
-   * Update PageRank scores after graph modification
-   * This is where delta-based approach really shines
+   * Update PageRank scores after graph modification.
+   * This is where delta-based approach really shines.
+   * @param modifiedNodes - Set of nodes that were modified (edges added/removed)
+   * @param options - Configuration options for PageRank computation
+   * @returns Updated PageRank scores
    */
   update(modifiedNodes, options = {}) {
     this.activeNodes.clear();
@@ -4825,6 +5073,10 @@ class DeltaPageRank {
   }
 }
 class PriorityDeltaPageRank {
+  /**
+   * Creates a new PriorityDeltaPageRank instance for the given graph.
+   * @param graph - The directed graph to compute PageRank on
+   */
   constructor(graph) {
     if (!graph.isDirected) {
       throw new Error("PriorityDeltaPageRank requires a directed graph");
@@ -4858,6 +5110,12 @@ class PriorityDeltaPageRank {
       }
     }
   }
+  /**
+   * Computes PageRank scores using priority queue-based delta iteration.
+   * Processes nodes in order of their delta magnitude for optimal convergence.
+   * @param options - Configuration options for PageRank computation
+   * @returns Map of node IDs to their PageRank scores
+   */
   computeWithPriority(options = {}) {
     const {
       dampingFactor = 0.85,
@@ -4935,12 +5193,7 @@ class PriorityDeltaPageRank {
   }
 }
 function eigenvectorCentrality(graph, options = {}) {
-  const {
-    maxIterations = 100,
-    tolerance = 1e-6,
-    normalized = true,
-    startVector
-  } = options;
+  const { maxIterations = 100, tolerance = 1e-6, normalized = true, startVector } = options;
   const centrality = {};
   const nodes = Array.from(graph.nodes());
   const nodeIds = nodes.map((node) => node.id);
@@ -5031,11 +5284,7 @@ function nodeEigenvectorCentrality(graph, nodeId, options = {}) {
   return centrality[nodeId.toString()] ?? 0;
 }
 function hits(graph, options = {}) {
-  const {
-    maxIterations = 100,
-    tolerance = 1e-6,
-    normalized = true
-  } = options;
+  const { maxIterations = 100, tolerance = 1e-6, normalized = true } = options;
   const hubs = {};
   const authorities = {};
   const nodes = Array.from(graph.nodes());
@@ -5159,13 +5408,7 @@ function nodeHITS(graph, nodeId, options = {}) {
   };
 }
 function katzCentrality(graph, options = {}) {
-  const {
-    alpha = 0.1,
-    beta = 1,
-    maxIterations = 100,
-    tolerance = 1e-6,
-    normalized = true
-  } = options;
+  const { alpha = 0.1, beta = 1, maxIterations = 100, tolerance = 1e-6, normalized = true } = options;
   const centrality = {};
   const nodes = Array.from(graph.nodes());
   const nodeIds = nodes.map((node) => node.id);
@@ -5229,6 +5472,10 @@ function nodeKatzCentrality(graph, nodeId, options = {}) {
   return centrality[nodeId.toString()] ?? 0;
 }
 class SimpleDeltaPageRank {
+  /**
+   * Creates a new SimpleDeltaPageRank instance for the given graph.
+   * @param graph - The directed graph to compute PageRank on
+   */
   constructor(graph) {
     this.previousScores = null;
     if (!graph.isDirected) {
@@ -5237,14 +5484,18 @@ class SimpleDeltaPageRank {
     this.graph = graph;
     this.nodeCount = graph.nodeCount;
   }
+  /**
+   * Computes PageRank scores for all nodes in the graph using power iteration.
+   * @param options - Configuration options for PageRank computation
+   * @param options.dampingFactor - Probability of following a link (default: 0.85)
+   * @param options.tolerance - Convergence tolerance threshold (default: 1e-6)
+   * @param options.maxIterations - Maximum number of iterations (default: 100)
+   * @param options.personalization - Personalization vector for Personalized PageRank
+   * @param options.weight - Edge attribute name for weighted PageRank
+   * @returns Map of node IDs to their PageRank scores
+   */
   compute(options = {}) {
-    const {
-      dampingFactor = 0.85,
-      tolerance = 1e-6,
-      maxIterations = 100,
-      personalization,
-      weight
-    } = options;
+    const { dampingFactor = 0.85, tolerance = 1e-6, maxIterations = 100, personalization, weight } = options;
     if (this.nodeCount === 0) {
       return /* @__PURE__ */ new Map();
     }
@@ -5348,22 +5599,20 @@ class SimpleDeltaPageRank {
   /**
    * Perform incremental update after graph modification.
    * This is where delta-based approach provides significant speedup.
-   *
-   * @param modifiedNodes Set of nodes that were modified (edges added/removed)
-   * @param options Computation options
+   * @param modifiedNodes - Set of nodes that were modified (edges added/removed)
+   * @param options - Computation options
+   * @param options.dampingFactor - Probability of following a link (default: 0.85)
+   * @param options.tolerance - Convergence tolerance threshold (default: 1e-6)
+   * @param options.maxIterations - Maximum number of iterations (default: 100)
+   * @param options.personalization - Personalization vector for Personalized PageRank
+   * @param options.weight - Edge attribute name for weighted PageRank
    * @returns Updated PageRank scores
    */
   update(modifiedNodes, options = {}) {
     if (!this.previousScores) {
       return this.compute(options);
     }
-    const {
-      dampingFactor = 0.85,
-      tolerance = 1e-6,
-      maxIterations = 100,
-      personalization,
-      weight
-    } = options;
+    const { dampingFactor = 0.85, tolerance = 1e-6, maxIterations = 100, personalization, weight } = options;
     const scores = new Map(this.previousScores);
     const newScores = /* @__PURE__ */ new Map();
     for (const node of this.graph.nodes()) {
@@ -5679,6 +5928,10 @@ function normalizeRanks(ranks) {
   }
 }
 class UnionFind {
+  /**
+   * Creates a new UnionFind data structure with the given elements.
+   * @param elements - Array of elements to initialize the data structure with
+   */
   constructor(elements) {
     this.parent = /* @__PURE__ */ new Map();
     this.rank = /* @__PURE__ */ new Map();
@@ -5690,6 +5943,8 @@ 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) {
     const parent = this.parent.get(element);
@@ -5707,6 +5962,8 @@ 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, elementB) {
     const rootA = this.find(elementA);
@@ -5731,6 +5988,9 @@ 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, elementB) {
     try {
@@ -5741,12 +6001,15 @@ class UnionFind {
   }
   /**
    * Get the number of connected components
+   * @returns The current count of disjoint components
    */
   getComponentCount() {
     return this.componentCount;
   }
   /**
    * 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) {
     const root = this.find(element);
@@ -5760,6 +6023,7 @@ class UnionFind {
   }
   /**
    * Get all connected components as separate arrays
+   * @returns Array of arrays, where each inner array contains elements of one component
    */
   getAllComponents() {
     const componentMap = /* @__PURE__ */ new Map();
@@ -5777,12 +6041,15 @@ 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) {
     return this.getComponent(element).length;
   }
   /**
    * Add a new element to the data structure
+   * @param element - The element to add as a new singleton set
    */
   addElement(element) {
     if (this.parent.has(element)) {
@@ -5794,12 +6061,15 @@ 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) {
     return this.parent.has(element);
   }
   /**
    * Get the total number of elements
+   * @returns The total count of all elements in the data structure
    */
   size() {
     return this.parent.size;
@@ -5807,7 +6077,9 @@ class UnionFind {
 }
 function connectedComponents(graph) {
   if (graph.isDirected) {
-    throw new Error("Connected components algorithm requires an undirected graph. Use stronglyConnectedComponents for directed graphs.");
+    throw new Error(
+      "Connected components algorithm requires an undirected graph. Use stronglyConnectedComponents for directed graphs."
+    );
   }
   const nodes = Array.from(graph.nodes()).map((node) => node.id);
   if (nodes.length === 0) {
@@ -5854,9 +6126,7 @@ function largestConnectedComponent(graph) {
   if (components.length === 0) {
     return [];
   }
-  return components.reduce(
-    (largest, current) => current.length > largest.length ? current : largest
-  );
+  return components.reduce((largest, current) => current.length > largest.length ? current : largest);
 }
 function getConnectedComponent(graph, nodeId) {
   if (!graph.hasNode(nodeId)) {
@@ -5932,7 +6202,9 @@ function isStronglyConnected(graph) {
 }
 function weaklyConnectedComponents(graph) {
   if (!graph.isDirected) {
-    throw new Error("Weakly connected components are for directed graphs. Use connectedComponents for undirected graphs.");
+    throw new Error(
+      "Weakly connected components are for directed graphs. Use connectedComponents for undirected graphs."
+    );
   }
   const nodes = Array.from(graph.nodes()).map((node) => node.id);
   if (nodes.length === 0) {
@@ -6116,9 +6388,7 @@ function girvanNewman(graph, options = {}) {
       workingGraph.removeEdge(source, target);
     }
     components = getConnectedComponentsResult(workingGraph);
-    const validCommunities = components.components.filter(
-      (community) => community.length >= minCommunitySize
-    );
+    const validCommunities = components.components.filter((community) => community.length >= minCommunitySize);
     const modularity = calculateModularity$3(graph, components.componentMap);
     dendrogram.push({
       communities: validCommunities,
@@ -6324,6 +6594,10 @@ function graphToMap(graph) {
   return map;
 }
 class SeededRandom {
+  /**
+   * Creates a new SeededRandom instance with the given seed.
+   * @param seed - The seed value for reproducible random number generation
+   */
   constructor(seed) {
     this.m = 2147483648;
     this.a = 1103515245;
@@ -6332,6 +6606,7 @@ class SeededRandom {
   }
   /**
    * Generate next random number between 0 and 1
+   * @returns A pseudo-random number in the range [0, 1]
    */
   next() {
     this.seed = (this.a * this.seed + this.c) % this.m;
@@ -6339,6 +6614,8 @@ class SeededRandom {
   }
   /**
    * Create a generator function for backward compatibility
+   * @param seed - The seed value for reproducible random number generation
+   * @returns A function that returns the next random number when called
    */
   static createGenerator(seed) {
     const rng = new SeededRandom(seed);
@@ -6373,10 +6650,7 @@ function euclideanDistance(a, b) {
   return Math.sqrt(sum);
 }
 function labelPropagationImpl(graph, options = {}) {
-  const {
-    maxIterations = 100,
-    randomSeed = 42
-  } = options;
+  const { maxIterations = 100, randomSeed = 42 } = options;
   if (graph.size === 0) {
     return {
       communities: /* @__PURE__ */ new Map(),
@@ -6459,9 +6733,7 @@ function labelPropagationImpl(graph, options = {}) {
   };
 }
 function labelPropagationAsyncImpl(graph, options = {}) {
-  const {
-    maxIterations = 100
-  } = options;
+  const { maxIterations = 100 } = options;
   if (graph.size === 0) {
     return {
       communities: /* @__PURE__ */ new Map(),
@@ -6535,10 +6807,7 @@ function labelPropagationAsyncImpl(graph, options = {}) {
   };
 }
 function labelPropagationSemiSupervisedImpl(graph, seedLabels, options = {}) {
-  const {
-    maxIterations = 100,
-    randomSeed = 42
-  } = options;
+  const { maxIterations = 100, randomSeed = 42 } = options;
   const random = SeededRandom.createGenerator(randomSeed);
   const labels = /* @__PURE__ */ new Map();
   const nodes = Array.from(graph.keys());
@@ -6620,12 +6889,7 @@ function labelPropagationSemiSupervised(graph, seedLabels, options = {}) {
   return labelPropagationSemiSupervisedImpl(graphMap, seedLabels, options);
 }
 function leidenImpl(inputGraph, options = {}) {
-  const {
-    resolution = 1,
-    randomSeed = 42,
-    maxIterations = 100,
-    threshold = 1e-7
-  } = options;
+  const { resolution = 1, randomSeed = 42, maxIterations = 100, threshold = 1e-7 } = options;
   if (inputGraph.size === 0) {
     return {
       communities: /* @__PURE__ */ new Map(),
@@ -6691,10 +6955,7 @@ function leidenImpl(inputGraph, options = {}) {
       }
     }
     createAggregateNetwork(currentGraph, communities);
-    const subsetPartition = refinePartition(
-      currentGraph,
-      communities
-    );
+    const subsetPartition = refinePartition(currentGraph, communities);
     for (const [node, newCommunity] of subsetPartition) {
       communities.set(node, newCommunity);
     }
@@ -6976,6 +7237,10 @@ function leiden(graph, options = {}) {
   return leidenImpl(graphMap, options);
 }
 class OptimizedLouvain {
+  /**
+   * Create an optimized Louvain detector for the given graph
+   * @param graph - The input graph to detect communities in
+   */
   constructor(graph) {
     this.graph = graph;
     this.communities = /* @__PURE__ */ new Map();
@@ -6991,6 +7256,8 @@ class OptimizedLouvain {
   }
   /**
    * Run optimized Louvain algorithm
+   * @param options - Algorithm configuration options
+   * @returns Community detection result with communities, modularity, and iterations
    */
   detectCommunities(options = {}) {
     const {
@@ -7074,6 +7341,7 @@ class OptimizedLouvain {
   }
   /**
    * Get nodes ordered by importance (degree * log(weight))
+   * @returns Array of node IDs sorted by descending importance
    */
   getNodesInImportanceOrder() {
     const nodeImportance = /* @__PURE__ */ new Map();
@@ -7086,6 +7354,12 @@ class OptimizedLouvain {
   }
   /**
    * Perform local moving phase with optimizations
+   * @param nodes - Array of node IDs to process
+   * @param options - Local moving options
+   * @param options.pruneLeaves - Whether to skip leaf nodes
+   * @param options.threshold - Minimum gain threshold for moves
+   * @param options.resolution - Resolution parameter for modularity
+   * @returns True if any improvement was made, false otherwise
    */
   performLocalMoving(nodes, options) {
     const { pruneLeaves, threshold, resolution } = options;
@@ -7129,6 +7403,8 @@ class OptimizedLouvain {
   }
   /**
    * Check if node is a leaf (degree 1)
+   * @param nodeId - The node ID to check
+   * @returns True if the node has degree 1, false otherwise
    */
   isLeafNode(nodeId) {
     const degree = this.nodeDegrees.get(nodeId) ?? 0;
@@ -7136,12 +7412,19 @@ class OptimizedLouvain {
   }
   /**
    * Get adaptive threshold that decreases with iterations
+   * @param iteration - Current iteration number
+   * @param baseThreshold - Base threshold value to scale
+   * @returns Adaptive threshold value that decays over iterations
    */
   getAdaptiveThreshold(iteration, baseThreshold) {
     return baseThreshold * Math.pow(0.5, iteration / 10);
   }
   /**
    * Calculate modularity gain from moving a node to a community
+   * @param nodeId - The node ID to move
+   * @param targetCommunity - The target community ID
+   * @param resolution - Resolution parameter for modularity calculation
+   * @returns The modularity gain from moving the node
    */
   calculateModularityGain(nodeId, targetCommunity, resolution) {
     const nodeWeight = this.nodeWeights.get(nodeId) ?? 0;
@@ -7166,6 +7449,8 @@ class OptimizedLouvain {
   }
   /**
    * Remove node from community (for gain calculation)
+   * @param nodeId - The node ID to remove
+   * @param community - The community ID to remove from
    */
   removeNodeFromCommunity(nodeId, community) {
     const nodeWeight = this.nodeWeights.get(nodeId) ?? 0;
@@ -7174,6 +7459,8 @@ class OptimizedLouvain {
   }
   /**
    * Add node to community
+   * @param nodeId - The node ID to add
+   * @param community - The community ID to add to
    */
   addNodeToCommunity(nodeId, community) {
     const nodeWeight = this.nodeWeights.get(nodeId) ?? 0;
@@ -7182,6 +7469,8 @@ class OptimizedLouvain {
   }
   /**
    * Get neighboring communities of a node
+   * @param nodeId - The node ID to find neighbor communities for
+   * @returns Set of community IDs that neighbors belong to
    */
   getNeighborCommunities(nodeId) {
     const communities = /* @__PURE__ */ new Set();
@@ -7203,6 +7492,8 @@ class OptimizedLouvain {
   }
   /**
    * Calculate total modularity
+   * @param resolution - Resolution parameter for modularity calculation
+   * @returns The modularity score of the current partition
    */
   calculateModularity(resolution) {
     if (this.totalWeight === 0) {
@@ -7233,6 +7524,7 @@ class OptimizedLouvain {
   }
   /**
    * Get pruning statistics
+   * @returns Statistics about nodes pruned during optimization
    */
   getPruningStats() {
     return { ...this.pruningStats };
@@ -7433,6 +7725,10 @@ function extractCommunities(communities) {
   return Array.from(communityMap.values());
 }
 class MinPriorityQueue {
+  /**
+   * Creates a new MinPriorityQueue instance.
+   * @param compareFunction - Custom comparison function. Returns negative if a has higher priority than b.
+   */
   constructor(compareFunction) {
     this.heap = [];
     this.compare = compareFunction ?? ((a, b) => this.defaultCompare(a, b));
@@ -7498,10 +7794,18 @@ class MinPriorityQueue {
       }
     }
   }
+  /**
+   * Insert a value into the priority queue.
+   * @param value - The value to insert
+   */
   insert(value) {
     this.heap.push(value);
     this.heapifyUp(this.heap.length - 1);
   }
+  /**
+   * Remove and return the minimum value from the priority queue.
+   * @returns The minimum value, or undefined if the queue is empty
+   */
   extractMin() {
     if (this.heap.length === 0) {
       return void 0;
@@ -7517,20 +7821,35 @@ class MinPriorityQueue {
     }
     return min;
   }
+  /**
+   * View the minimum value without removing it.
+   * @returns The minimum value, or undefined if the queue is empty
+   */
   peek() {
     return this.heap[0];
   }
+  /**
+   * Check if the priority queue is empty.
+   * @returns True if the queue has no items, false otherwise
+   */
   isEmpty() {
     return this.heap.length === 0;
   }
+  /**
+   * Get the number of items in the priority queue.
+   * @returns The number of items currently in the queue
+   */
   size() {
     return this.heap.length;
   }
 }
 const pathfindingUtils = {
   /**
-  * Reconstructs a path from start to goal using the cameFrom map
-  */
+   * Reconstructs a path from start to goal using the cameFrom map
+   * @param cameFrom - Map of each node to its predecessor on the path
+   * @param goal - The goal node to reconstruct the path to
+   * @returns An array of nodes representing the path from start to goal
+   */
   reconstructPath(cameFrom, goal) {
     const path = [goal];
     let current = goal;
@@ -7545,8 +7864,12 @@ const pathfindingUtils = {
     return path;
   },
   /**
-  * Creates a grid graph for testing pathfinding algorithms
-  */
+   * Creates a grid graph for testing pathfinding algorithms
+   * @param width - The width of the grid
+   * @param height - The height of the grid
+   * @param obstacles - Set of obstacle coordinates as "x,y" strings
+   * @returns A grid graph with 4-directional movement
+   */
   createGridGraph(width, height, obstacles = /* @__PURE__ */ new Set()) {
     const graph = /* @__PURE__ */ new Map();
     for (let x = 0; x < width; x++) {
@@ -7581,8 +7904,10 @@ const pathfindingUtils = {
     return graph;
   },
   /**
-  * Parses a grid coordinate string
-  */
+   * Parses a grid coordinate string
+   * @param coord - The coordinate string in "x,y" format
+   * @returns A tuple of [x, y] coordinates
+   */
   parseGridCoordinate(coord) {
     const parts = coord.split(",").map(Number);
     const x = parts[0];
@@ -7722,27 +8047,38 @@ function astarWithDetails(graph, start, goal, heuristic) {
 }
 const heuristics = {
   /**
-  * Manhattan distance heuristic for grid-based graphs
-  */
+   * Manhattan distance heuristic for grid-based graphs
+   * @param a - First coordinate as [x, y] tuple
+   * @param b - Second coordinate as [x, y] tuple
+   * @returns The Manhattan distance between the two points
+   */
   manhattan: (a, b) => {
     return Math.abs(a[0] - b[0]) + Math.abs(a[1] - b[1]);
   },
   /**
-  * Euclidean distance heuristic
-  */
+   * Euclidean distance heuristic
+   * @param a - First coordinate as [x, y] tuple
+   * @param b - Second coordinate as [x, y] tuple
+   * @returns The Euclidean distance between the two points
+   */
   euclidean: (a, b) => {
     return Math.sqrt(Math.pow(a[0] - b[0], 2) + Math.pow(a[1] - b[1], 2));
   },
   /**
-  * Chebyshev distance heuristic (diagonal movement allowed)
-  */
+   * Chebyshev distance heuristic (diagonal movement allowed)
+   * @param a - First coordinate as [x, y] tuple
+   * @param b - Second coordinate as [x, y] tuple
+   * @returns The Chebyshev distance between the two points
+   */
   chebyshev: (a, b) => {
     return Math.max(Math.abs(a[0] - b[0]), Math.abs(a[1] - b[1]));
   },
   /**
-  * Zero heuristic (makes A* behave like Dijkstra)
-  */
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+   * Zero heuristic (makes A* behave like Dijkstra)
+   * @param _a - First node (unused)
+   * @param _b - Second node (unused)
+   * @returns Always returns 0
+   */
   zero: (_a, _b) => 0
 };
 function createResidualGraph(graph) {
@@ -8900,10 +9236,12 @@ function extractClusters(matrix, nodeIds) {
       }
     }
     if (clusterNodes.length > 0) {
-      communities.push(clusterNodes.map((idx) => {
-        const nodeId = nodeIds[idx];
-        return nodeId;
-      }).filter((node) => node !== void 0));
+      communities.push(
+        clusterNodes.map((idx) => {
+          const nodeId = nodeIds[idx];
+          return nodeId;
+        }).filter((node) => node !== void 0)
+      );
       clusterIndex++;
     }
   }
@@ -8943,12 +9281,7 @@ function calculateMCLModularity(graph, communities) {
   return modularity / (2 * m);
 }
 function spectralClustering(graph, options) {
-  const {
-    k,
-    laplacianType = "normalized",
-    maxIterations = 100,
-    tolerance = 1e-4
-  } = options;
+  const { k, laplacianType = "normalized", maxIterations = 100, tolerance = 1e-4 } = options;
   if (k < 1 || !Number.isInteger(k)) {
     throw new Error("k must be a positive integer");
   }
@@ -9738,10 +10071,7 @@ function adamicAdarScore(graph, source, target, options = {}) {
   const commonNeighborsSet = directed ? getIntermediateNodes(graph, source, target) : getCommonNeighbors(graph, source, target, false);
   let score = 0;
   for (const neighbor of commonNeighborsSet) {
-    const degree = directed ? graph.outDegree(neighbor) : (
-      // Use out-degree for directed graphs
-      graph.degree(neighbor)
-    );
+    const degree = directed ? graph.outDegree(neighbor) : graph.degree(neighbor);
     if (degree > 1) {
       score += 1 / Math.log(degree);
     } else if (degree === 1) {
@@ -9751,11 +10081,7 @@ function adamicAdarScore(graph, source, target, options = {}) {
   return score;
 }
 function adamicAdarPrediction(graph, options = {}) {
-  const {
-    directed = false,
-    includeExisting = false,
-    topK
-  } = options;
+  const { directed = false, includeExisting = false, topK } = options;
   const scores = [];
   const nodes = Array.from(graph.nodes()).map((n) => n.id);
   for (let i = 0; i < nodes.length; i++) {
@@ -9794,12 +10120,7 @@ function getTopAdamicAdarCandidatesForNode(graph, node, options = {}) {
   if (!graph.hasNode(node)) {
     return [];
   }
-  const {
-    directed = false,
-    includeExisting = false,
-    topK = 10,
-    candidates
-  } = options;
+  const { directed = false, includeExisting = false, topK = 10, candidates } = options;
   const scores = [];
   const targetNodes = candidates ?? Array.from(graph.nodes()).map((n) => n.id);
   for (const target of targetNodes) {
@@ -9938,11 +10259,7 @@ function commonNeighborsScore(graph, source, target, options = {}) {
   return commonNeighborsSet.size;
 }
 function commonNeighborsPrediction(graph, options = {}) {
-  const {
-    directed = false,
-    includeExisting = false,
-    topK
-  } = options;
+  const { directed = false, includeExisting = false, topK } = options;
   const scores = [];
   const nodes = Array.from(graph.nodes()).map((n) => n.id);
   for (let i = 0; i < nodes.length; i++) {
@@ -9981,12 +10298,7 @@ function getTopCandidatesForNode(graph, node, options = {}) {
   if (!graph.hasNode(node)) {
     return [];
   }
-  const {
-    directed = false,
-    includeExisting = false,
-    topK = 10,
-    candidates
-  } = options;
+  const { directed = false, includeExisting = false, topK = 10, candidates } = options;
   const scores = [];
   const targetNodes = candidates ?? Array.from(graph.nodes()).map((n) => n.id);
   for (const target of targetNodes) {
@@ -10056,14 +10368,7 @@ function evaluateCommonNeighbors(trainingGraph, testEdges, nonEdges, options = {
   };
 }
 function syncClustering(graph, config) {
-  const {
-    numClusters,
-    maxIterations = 100,
-    tolerance = 1e-6,
-    seed = 42,
-    learningRate = 0.01,
-    lambda = 0.1
-  } = config;
+  const { numClusters, maxIterations = 100, tolerance = 1e-6, seed = 42, learningRate = 0.01, lambda = 0.1 } = config;
   const originalRandom = Math.random;
   const rng = SeededRandom.createGenerator(seed);
   Math.random = rng;
@@ -10079,7 +10384,9 @@ function syncClustering(graph, config) {
     };
   }
   if (numClusters <= 0 || numClusters > nodeCount) {
-    throw new Error(`Invalid number of clusters: ${String(numClusters)}. Must be between 1 and ${String(nodeCount)}`);
+    throw new Error(
+      `Invalid number of clusters: ${String(numClusters)}. Must be between 1 and ${String(nodeCount)}`
+    );
   }
   const embeddingDim = Math.min(64, nodeCount);
   const embeddings = /* @__PURE__ */ new Map();
@@ -10197,7 +10504,7 @@ function initializeClusterCenters(embeddings, numClusters) {
   }
   return centers;
 }
-function updateEmbeddings(graph, embeddings, clusters, learningRate, lambda) {
+function updateEmbeddings(graph, embeddings, _clusters, learningRate, lambda) {
   const gradients = /* @__PURE__ */ new Map();
   for (const [nodeId, embedding] of embeddings) {
     gradients.set(nodeId, new Array(embedding.length).fill(0));
@@ -10344,7 +10651,9 @@ function teraHAC(graph, config = {}) {
     throw new Error("Cannot cluster empty graph");
   }
   if (nodeCount > maxNodes) {
-    onWarning(`Graph has ${String(nodeCount)} nodes, which exceeds maxNodes (${String(maxNodes)}). Performance may be degraded.`);
+    onWarning(
+      `Graph has ${String(nodeCount)} nodes, which exceeds maxNodes (${String(maxNodes)}). Performance may be degraded.`
+    );
   }
   const clusters = /* @__PURE__ */ new Map();
   let nextClusterId = nodeCount;
@@ -10680,13 +10989,7 @@ function grsbm(graph, config = {}) {
     if (currentCluster.depth >= maxDepth || currentCluster.members.size < minClusterSize * 2) {
       continue;
     }
-    const bisectionResult = spectralBisection(
-      graph,
-      currentCluster,
-      numEigenvectors,
-      tolerance,
-      maxIterations
-    );
+    const bisectionResult = spectralBisection(graph, currentCluster, numEigenvectors, tolerance, maxIterations);
     if (!bisectionResult) {
       continue;
     }
@@ -10759,7 +11062,7 @@ function grsbm(graph, config = {}) {
     explanation: explanations
   };
 }
-function spectralBisection(graph, cluster, numEigenvectors, tolerance, maxIterations) {
+function spectralBisection(graph, cluster, _numEigenvectors, tolerance, maxIterations) {
   const members = Array.from(cluster.members);
   const n = members.length;
   if (n < 4) {