@graphty/algorithms 1.3.1 → 1.4.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphty/algorithms",
-  "version": "1.3.1",
+  "version": "1.4.2",
   "description": "Graph algorithms library for browser environments implemented in TypeScript",
   "author": "Adam Powers <apowers@ato.ms>",
   "main": "dist/algorithms.js",
@@ -21,44 +21,10 @@
   "directories": {
     "example": "examples"
   },
-  "scripts": {
-    "test": "vitest",
-    "test:ui": "vitest --ui",
-    "test:run": "vitest run --project=default",
-    "test:coverage": "vitest run --coverage",
-    "test:browser": "vitest --project=browser",
-    "test:all": "vitest run --project=default --project=browser",
-    "test:performance": "tsx test/helpers/run-performance-regression.ts",
-    "test:performance:update": "tsx test/helpers/run-performance-regression.ts --update-baselines",
-    "benchmark": "tsx src/benchmark-all-algorithms.ts",
-    "benchmark:quick": "tsx src/benchmark-all-algorithms.ts --quick",
-    "benchmark:report": "tsx scripts/generate-performance-report.ts",
-    "benchmark:validation": "tsx src/optimized/benchmark-validation.ts",
-    "benchmark:comprehensive": "tsx src/optimized/benchmark-comprehensive.ts",
-    "memory:profile": "tsx test/helpers/memory-profiler.ts",
-    "lint": "eslint && tsc --noEmit",
-    "lint:fix": "eslint --fix",
-    "lint:pkg": "knip",
-    "lint:all": "npm run lint && npm run lint:pkg",
-    "typecheck": "tsc --noEmit",
-    "prepare": "husky",
-    "build": "tsc",
-    "build:bundle": "node scripts/build-bundle.js",
-    "build:all": "npm run build && npm run build:bundle",
-    "build:gh-pages": "npm run build:bundle && node scripts/build-gh-pages.js",
-    "build:watch": "tsc --watch",
-    "dev": "tsc --watch",
-    "examples": "node examples/run-all-examples.js",
-    "examples:run": "node examples/run-all-examples.js",
-    "examples:html": "npm run build:bundle && vite",
-    "serve": "npm run build:bundle && vite",
-    "commit": "cz",
-    "ready:commit": "npm run build && npm run lint && npm run test:all",
-    "watch": "tsc --watch"
-  },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/graphty-org/algorithms.git"
+    "url": "git+https://github.com/graphty-org/graphty-monorepo.git",
+    "directory": "algorithms"
   },
   "keywords": [
     "graph",
@@ -78,9 +44,9 @@
     "provenance": true
   },
   "bugs": {
-    "url": "https://github.com/graphty-org/algorithms/issues"
+    "url": "https://github.com/graphty-org/graphty-monorepo/issues"
   },
-  "homepage": "https://github.com/graphty-org/algorithms#readme",
+  "homepage": "https://github.com/graphty-org/graphty-monorepo/tree/master/algorithms#readme",
   "engines": {
     "node": ">=18.19.0"
   },
@@ -90,25 +56,20 @@
     }
   },
   "devDependencies": {
-    "@commitlint/cli": "^19.8.1",
-    "@commitlint/config-conventional": "^19.8.1",
     "@eslint/js": "^9.29.0",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
-    "@stylistic/eslint-plugin": "^4.4.1",
     "@types/benchmark": "^2.1.5",
     "@types/node": "^20.19.9",
     "@vitest/browser": "^3.2.4",
     "@vitest/coverage-v8": "^3.2.4",
     "@vitest/ui": "^3.2.4",
     "benchmark": "^2.1.4",
-    "cz-conventional-changelog": "^3.3.0",
     "eslint": "^9.29.0",
     "eslint-plugin-simple-import-sort": "^12.1.1",
     "gh-pages": "^6.3.0",
     "globals": "^15.12.0",
     "happy-dom": "^18.0.1",
-    "husky": "^9.1.7",
     "knip": "^5.61.3",
     "playwright": "^1.53.0",
     "semantic-release": "^25.0.2",
@@ -122,5 +83,48 @@
   "dependencies": {
     "pupt": "^1.3.2",
     "typedfastbitset": "^0.6.1"
+  },
+  "scripts": {
+    "test": "vitest",
+    "test:ui": "vitest --ui",
+    "test:run": "vitest run --project=default",
+    "test:coverage": "vitest run --coverage",
+    "coverage": "npm run coverage:shards && npm run coverage:merge",
+    "coverage:merge": "./scripts/coverage-merge.sh",
+    "coverage:shards": "npm run coverage:shards:clean && npm run coverage:shards:run",
+    "coverage:shards:clean": "rm -rf .coverage-parts",
+    "coverage:shards:run": "npm run coverage:shard:default && npm run coverage:shard:browser",
+    "coverage:shard:default": "COVERAGE_DIR=.coverage-parts/default vitest run --project=default --coverage",
+    "coverage:shard:browser": "COVERAGE_DIR=.coverage-parts/browser vitest run --project=browser --coverage",
+    "coverage:fast": "vitest run --project=default --coverage",
+    "coverage:preview": "npx serve coverage -p 9051",
+    "test:browser": "vitest --project=browser",
+    "test:all": "vitest run --project=default --project=browser",
+    "test:performance": "tsx test/helpers/run-performance-regression.ts",
+    "test:performance:update": "tsx test/helpers/run-performance-regression.ts --update-baselines",
+    "benchmark": "tsx src/benchmark-all-algorithms.ts",
+    "benchmark:quick": "tsx src/benchmark-all-algorithms.ts --quick",
+    "benchmark:report": "tsx scripts/generate-performance-report.ts",
+    "benchmark:validation": "tsx src/optimized/benchmark-validation.ts",
+    "benchmark:comprehensive": "tsx src/optimized/benchmark-comprehensive.ts",
+    "memory:profile": "tsx test/helpers/memory-profiler.ts",
+    "lint": "eslint && tsc --noEmit",
+    "lint:fix": "eslint --fix",
+    "lint:pkg": "knip",
+    "lint:all": "npm run lint && npm run lint:pkg",
+    "typecheck": "tsc --noEmit",
+    "build": "tsc",
+    "build:bundle": "node scripts/build-bundle.js",
+    "build:all": "npm run build && npm run build:bundle",
+    "build:gh-pages": "npm run build:bundle && node scripts/build-gh-pages.js",
+    "build:watch": "tsc --watch",
+    "dev": "tsc --watch",
+    "examples": "node examples/run-all-examples.js",
+    "examples:run": "node examples/run-all-examples.js",
+    "examples:html": "npm run build:bundle && vite",
+    "serve": "npm run build:bundle && vite",
+    "commit": "cz",
+    "ready:commit": "npm run build && npm run lint && npm run test:all",
+    "watch": "tsc --watch"
   }
-}
+}

package/src/algorithms/centrality/betweenness.ts

@@ -1,6 +1,6 @@
-import type {Graph} from "../../core/graph.js";
-import type {NodeId} from "../../types/index.js";
-import {bfsWithPathCounting} from "../traversal/bfs-variants.js";
+import type { Graph } from "../../core/graph.js";
+import type { NodeId } from "../../types/index.js";
+import { bfsWithPathCounting } from "../traversal/bfs-variants.js";
 
 /**
  * Betweenness centrality implementation using Brandes' algorithm
@@ -39,9 +39,13 @@ interface BrandesResult {
 
 /**
  * Run single-source shortest path computation using BFS
+ * @param graph - The input graph to analyze
+ * @param source - The source node for shortest path computation
+ * @param optimized - Whether to use optimized BFS implementation
+ * @returns The BFS result containing stack, predecessors, sigma, and distances
  */
 function brandesSingleSource(graph: Graph, source: NodeId, optimized?: boolean): BrandesResult {
-    const result = bfsWithPathCounting(graph, source, optimized !== undefined ? {optimized} : {});
+    const result = bfsWithPathCounting(graph, source, optimized !== undefined ? { optimized } : {});
 
     return {
         stack: result.stack,
@@ -53,6 +57,10 @@ function brandesSingleSource(graph: Graph, source: NodeId, optimized?: boolean):
 
 /**
  * Accumulate betweenness contributions from a single source
+ * @param result - The BFS result from brandesSingleSource
+ * @param source - The source node used in BFS
+ * @param centrality - The centrality map to update
+ * @param options - Algorithm configuration options
  */
 function accumulateBetweenness(
     result: BrandesResult,
@@ -60,7 +68,7 @@ function accumulateBetweenness(
     centrality: Record<string, number>,
     options: BetweennessCentralityOptions,
 ): void {
-    const {stack, predecessors, sigma} = result;
+    const { stack, predecessors, sigma } = result;
     const delta = new Map<NodeId, number>();
 
     // Initialize delta
@@ -109,6 +117,10 @@ function accumulateBetweenness(
 
 /**
  * Accumulate edge betweenness contributions from a single source
+ * @param result - The BFS result from brandesSingleSource
+ * @param source - The source node used in BFS
+ * @param edgeCentrality - The edge centrality map to update
+ * @param options - Algorithm configuration options
  */
 function accumulateEdgeBetweenness(
     result: BrandesResult,
@@ -116,7 +128,7 @@ function accumulateEdgeBetweenness(
     edgeCentrality: Map<string, number>,
     options: BetweennessCentralityOptions,
 ): void {
-    const {stack, predecessors, sigma} = result;
+    const { stack, predecessors, sigma } = result;
     const delta = new Map<NodeId, number>();
 
     // Initialize delta
@@ -165,16 +177,13 @@ function accumulateEdgeBetweenness(
 
 /**
  * Apply normalization to centrality values
+ * @param centrality - The centrality map to normalize in place
+ * @param nodeCount - Total number of nodes in the graph
+ * @param isDirected - Whether the graph is directed
  */
-function normalizeCentrality(
-    centrality: Record<string, number>,
-    nodeCount: number,
-    isDirected: boolean,
-): void {
+function normalizeCentrality(centrality: Record<string, number>, nodeCount: number, isDirected: boolean): void {
     const n = nodeCount;
-    const normalizationFactor = isDirected ?
-        (n - 1) * (n - 2) :
-        ((n - 1) * (n - 2)) / 2;
+    const normalizationFactor = isDirected ? (n - 1) * (n - 2) : ((n - 1) * (n - 2)) / 2;
 
     if (normalizationFactor > 0) {
         for (const key in centrality) {
@@ -188,6 +197,9 @@ function normalizeCentrality(
 
 /**
  * Calculate betweenness centrality for all nodes using Brandes' algorithm
+ * @param graph - The input graph to analyze
+ * @param options - Algorithm configuration options
+ * @returns Centrality scores for each node keyed by node ID
  */
 export function betweennessCentrality(
     graph: Graph,
@@ -228,6 +240,10 @@ export function betweennessCentrality(
 
 /**
  * Calculate betweenness centrality for a specific node
+ * @param graph - The input graph to analyze
+ * @param targetNode - The node to calculate centrality for
+ * @param options - Algorithm configuration options
+ * @returns The betweenness centrality score for the target node
  */
 export function nodeBetweennessCentrality(
     graph: Graph,
@@ -244,6 +260,9 @@ export function nodeBetweennessCentrality(
 
 /**
  * Calculate edge betweenness centrality
+ * @param graph - The input graph to analyze
+ * @param options - Algorithm configuration options
+ * @returns Edge centrality scores keyed by edge string representation
  */
 export function edgeBetweennessCentrality(
     graph: Graph,
@@ -274,9 +293,7 @@ export function edgeBetweennessCentrality(
     // Normalization for edges
     if (options.normalized) {
         const n = nodes.length;
-        const normalizationFactor = graph.isDirected ?
-            (n - 1) * (n - 2) :
-            ((n - 1) * (n - 2)) / 2;
+        const normalizationFactor = graph.isDirected ? (n - 1) * (n - 2) : ((n - 1) * (n - 2)) / 2;
 
         if (normalizationFactor > 0) {
             for (const [edgeKey, centrality] of Array.from(edgeCentrality)) {

package/src/algorithms/centrality/closeness.ts

@@ -1,6 +1,6 @@
-import type {Graph} from "../../core/graph.js";
-import type {NodeId} from "../../types/index.js";
-import {bfsDistancesOnly, bfsWeightedDistances} from "../traversal/bfs-variants.js";
+import type { Graph } from "../../core/graph.js";
+import type { NodeId } from "../../types/index.js";
+import { bfsDistancesOnly, bfsWeightedDistances } from "../traversal/bfs-variants.js";
 
 /**
  * Closeness centrality implementation
@@ -34,6 +34,11 @@ export interface ClosenessCentralityOptions {
 
 /**
  * Calculate closeness centrality from distances
+ * @param distances - Map of node IDs to their distances from source
+ * @param sourceNode - The source node for distance calculations
+ * @param totalNodes - Total number of nodes in the graph
+ * @param options - Algorithm configuration options
+ * @returns The closeness centrality score for the source node
  */
 function calculateClosenessFromDistances(
     distances: Map<NodeId, number>,
@@ -76,7 +81,7 @@ function calculateClosenessFromDistances(
 
             // Wasserman and Faust normalization for disconnected graphs
             if (options.normalized && totalNodes > 1) {
-                centrality = centrality * reachableNodes / (totalNodes - 1);
+                centrality = (centrality * reachableNodes) / (totalNodes - 1);
             }
         }
     }
@@ -90,11 +95,9 @@ function calculateClosenessFromDistances(
  * Closeness centrality measures how close a node is to all other nodes
  * in the graph. It is the reciprocal of the sum of the shortest path
  * distances to all other reachable nodes.
- *
  * @param graph - The input graph
  * @param options - Algorithm options
  * @returns Centrality scores for each node
- *
  * @example
  * ```typescript
  * const graph = new Graph();
@@ -108,10 +111,7 @@ function calculateClosenessFromDistances(
  * Time Complexity: O(V * (V + E)) for unweighted graphs
  * Space Complexity: O(V)
  */
-export function closenessCentrality(
-    graph: Graph,
-    options: ClosenessCentralityOptions = {},
-): Record<string, number> {
+export function closenessCentrality(graph: Graph, options: ClosenessCentralityOptions = {}): Record<string, number> {
     const nodes = Array.from(graph.nodes()).map((node) => node.id);
     const centrality: Record<string, number> = {};
 
@@ -124,18 +124,23 @@ export function closenessCentrality(
 
 /**
  * Calculate closeness centrality for a specific node
+ * @param graph - The input graph to analyze
+ * @param node - The node to calculate centrality for
+ * @param options - Algorithm configuration options
+ * @returns The closeness centrality score for the node
  */
-export function nodeClosenessCentrality(
-    graph: Graph,
-    node: NodeId,
-    options: ClosenessCentralityOptions = {},
-): number {
+export function nodeClosenessCentrality(graph: Graph, node: NodeId, options: ClosenessCentralityOptions = {}): number {
     if (!graph.hasNode(node)) {
         throw new Error(`Node ${String(node)} not found in graph`);
     }
 
     // Use optimized BFS variant for unweighted graphs
-    const distances = bfsDistancesOnly(graph, node, options.cutoff, options.optimized !== undefined ? {optimized: options.optimized} : {});
+    const distances = bfsDistancesOnly(
+        graph,
+        node,
+        options.cutoff,
+        options.optimized !== undefined ? { optimized: options.optimized } : {},
+    );
     const totalNodes = graph.nodeCount;
 
     return calculateClosenessFromDistances(distances, node, totalNodes, options);
@@ -143,6 +148,9 @@ export function nodeClosenessCentrality(
 
 /**
  * Calculate weighted closeness centrality using Dijkstra's algorithm
+ * @param graph - The input graph to analyze
+ * @param options - Algorithm configuration options
+ * @returns Centrality scores for each node keyed by node ID
  */
 export function weightedClosenessCentrality(
     graph: Graph,
@@ -160,6 +168,10 @@ export function weightedClosenessCentrality(
 
 /**
  * Calculate weighted closeness centrality for a specific node using Dijkstra
+ * @param graph - The input graph to analyze
+ * @param node - The node to calculate centrality for
+ * @param options - Algorithm configuration options
+ * @returns The weighted closeness centrality score for the node
  */
 export function nodeWeightedClosenessCentrality(
     graph: Graph,
@@ -171,7 +183,12 @@ export function nodeWeightedClosenessCentrality(
     }
 
     // Use optimized weighted BFS variant (simplified Dijkstra)
-    const distances = bfsWeightedDistances(graph, node, options.cutoff, options.optimized !== undefined ? {optimized: options.optimized} : {});
+    const distances = bfsWeightedDistances(
+        graph,
+        node,
+        options.cutoff,
+        options.optimized !== undefined ? { optimized: options.optimized } : {},
+    );
     const totalNodes = graph.nodeCount;
 
     return calculateClosenessFromDistances(distances, node, totalNodes, options);

package/src/algorithms/centrality/degree.ts

@@ -1,5 +1,5 @@
-import type {Graph} from "../../core/graph.js";
-import type {CentralityOptions, CentralityResult} from "../../types/index.js";
+import type { Graph } from "../../core/graph.js";
+import type { CentralityOptions, CentralityResult } from "../../types/index.js";
 
 /**
  * Degree centrality implementation
@@ -10,13 +10,13 @@ import type {CentralityOptions, CentralityResult} from "../../types/index.js";
 
 /**
  * Calculate degree centrality for all nodes in the graph
+ * @param graph - The input graph to analyze
+ * @param options - Algorithm configuration options
+ * @returns Centrality scores for each node keyed by node ID
  */
-export function degreeCentrality(
-    graph: Graph,
-    options: CentralityOptions = {},
-): CentralityResult {
+export function degreeCentrality(graph: Graph, options: CentralityOptions = {}): CentralityResult {
     const centrality: CentralityResult = {};
-    const {nodeCount} = graph;
+    const { nodeCount } = graph;
 
     // Calculate normalization factor (same for both directed and undirected graphs)
     const maxPossibleDegree = nodeCount - 1;
@@ -49,9 +49,7 @@ export function degreeCentrality(
         }
 
         // Apply normalization if requested
-        const normalizedDegree = options.normalized && maxPossibleDegree > 0 ?
-            degree / maxPossibleDegree :
-            degree;
+        const normalizedDegree = options.normalized && maxPossibleDegree > 0 ? degree / maxPossibleDegree : degree;
 
         centrality[node.id.toString()] = normalizedDegree;
     }
@@ -61,17 +59,17 @@ export function degreeCentrality(
 
 /**
  * Calculate degree centrality for a specific node
+ * @param graph - The input graph to analyze
+ * @param nodeId - The node to calculate centrality for
+ * @param options - Algorithm configuration options
+ * @returns The degree centrality score for the node
  */
-export function nodeDegreeCentrality(
-    graph: Graph,
-    nodeId: string | number,
-    options: CentralityOptions = {},
-): number {
+export function nodeDegreeCentrality(graph: Graph, nodeId: string | number, options: CentralityOptions = {}): number {
     if (!graph.hasNode(nodeId)) {
         throw new Error(`Node ${String(nodeId)} not found in graph`);
     }
 
-    const {nodeCount} = graph;
+    const { nodeCount } = graph;
     let degree: number;
 
     if (graph.isDirected && options.mode) {
@@ -99,7 +97,5 @@ export function nodeDegreeCentrality(
     // Apply normalization if requested
     const maxPossibleDegree = nodeCount - 1;
 
-    return options.normalized && maxPossibleDegree > 0 ?
-        degree / maxPossibleDegree :
-        degree;
+    return options.normalized && maxPossibleDegree > 0 ? degree / maxPossibleDegree : degree;
 }

package/src/algorithms/centrality/delta-pagerank-simple.ts

@@ -1,5 +1,5 @@
-import type {Graph} from "../../core/graph.js";
-import type {NodeId} from "../../types/index.js";
+import type { Graph } from "../../core/graph.js";
+import type { NodeId } from "../../types/index.js";
 
 /**
  * Simplified Delta-based PageRank that matches the standard algorithm
@@ -13,6 +13,10 @@ export class SimpleDeltaPageRank {
     private nodeCount: number;
     private previousScores: Map<NodeId, number> | null = null;
 
+    /**
+     * Creates a new SimpleDeltaPageRank instance for the given graph.
+     * @param graph - The directed graph to compute PageRank on
+     */
     constructor(graph: Graph) {
         if (!graph.isDirected) {
             throw new Error("PageRank requires a directed graph");
@@ -22,20 +26,26 @@ export class SimpleDeltaPageRank {
         this.nodeCount = graph.nodeCount;
     }
 
-    public compute(options: {
-        dampingFactor?: number;
-        tolerance?: number;
-        maxIterations?: number;
-        personalization?: Map<NodeId, number>;
-        weight?: string;
-    } = {}): Map<NodeId, number> {
-        const {
-            dampingFactor = 0.85,
-            tolerance = 1e-6,
-            maxIterations = 100,
-            personalization,
-            weight,
-        } = options;
+    /**
+     * 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
+     */
+    public compute(
+        options: {
+            dampingFactor?: number;
+            tolerance?: number;
+            maxIterations?: number;
+            personalization?: Map<NodeId, number>;
+            weight?: string;
+        } = {},
+    ): Map<NodeId, number> {
+        const { dampingFactor = 0.85, tolerance = 1e-6, maxIterations = 100, personalization, weight } = options;
 
         if (this.nodeCount === 0) {
             return new Map();
@@ -97,7 +107,7 @@ export class SimpleDeltaPageRank {
             }
 
             if (danglingSum > 0) {
-                const danglingContribution = dampingFactor * danglingSum / this.nodeCount;
+                const danglingContribution = (dampingFactor * danglingSum) / this.nodeCount;
                 for (const nodeId of scores.keys()) {
                     const current = newScores.get(nodeId) ?? 0;
                     if (personalVector) {
@@ -175,9 +185,13 @@ export 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
      */
     public update(
@@ -195,13 +209,7 @@ export class SimpleDeltaPageRank {
             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;
 
         // Initialize scores from previous computation
         const scores = new Map(this.previousScores);
@@ -275,7 +283,7 @@ export class SimpleDeltaPageRank {
             }
 
             if (danglingSum > 0) {
-                const danglingContribution = dampingFactor * danglingSum / this.nodeCount;
+                const danglingContribution = (dampingFactor * danglingSum) / this.nodeCount;
                 for (const nodeId of scores.keys()) {
                     const current = newScores.get(nodeId) ?? 0;
                     if (personalVector) {

package/src/algorithms/centrality/delta-pagerank.ts

@@ -1,6 +1,6 @@
-import type {Graph} from "../../core/graph.js";
-import {PriorityQueue} from "../../data-structures/priority-queue.js";
-import type {NodeId} from "../../types/index.js";
+import type { Graph } from "../../core/graph.js";
+import { PriorityQueue } from "../../data-structures/priority-queue.js";
+import type { NodeId } from "../../types/index.js";
 
 /**
  * Delta-based PageRank implementation for faster convergence
@@ -45,6 +45,10 @@ export interface DeltaPageRankOptions {
     weight?: string;
 }
 
+/**
+ * Delta-based PageRank class that tracks changes between iterations
+ * and only processes nodes with significant changes for improved performance.
+ */
 export class DeltaPageRank {
     private graph: Graph;
     private scores: Map<NodeId, number>;
@@ -55,6 +59,10 @@ export class DeltaPageRank {
     private danglingNodes: Set<NodeId>;
     private nodeCount: number;
 
+    /**
+     * Creates a new DeltaPageRank instance for the given graph.
+     * @param graph - The directed graph to compute PageRank on
+     */
     constructor(graph: Graph) {
         if (!graph.isDirected) {
             throw new Error("DeltaPageRank requires a directed graph");
@@ -101,6 +109,11 @@ export 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
+     */
     public compute(options: DeltaPageRankOptions = {}): Map<NodeId, number> {
         const {
             dampingFactor = 0.85,
@@ -149,7 +162,7 @@ export class DeltaPageRank {
             }
 
             if (danglingSum > 0) {
-                const danglingContribution = dampingFactor * danglingSum / this.nodeCount;
+                const danglingContribution = (dampingFactor * danglingSum) / this.nodeCount;
                 for (const node of this.graph.nodes()) {
                     const nodeId = node.id;
                     const currentDelta = nextDeltas.get(nodeId) ?? 0;
@@ -197,7 +210,7 @@ export class DeltaPageRank {
                 const nodeId = node.id;
                 const currentDelta = nextDeltas.get(nodeId) ?? 0;
                 if (personalVector) {
-                    nextDeltas.set(nodeId, currentDelta + ((1 - dampingFactor) * (personalVector.get(nodeId) ?? 0)));
+                    nextDeltas.set(nodeId, currentDelta + (1 - dampingFactor) * (personalVector.get(nodeId) ?? 0));
                 } else {
                     nextDeltas.set(nodeId, currentDelta + randomJump);
                 }
@@ -231,13 +244,13 @@ export class DeltaPageRank {
     }
 
     /**
-     * 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
      */
-    public update(
-        modifiedNodes: Set<NodeId>,
-        options: DeltaPageRankOptions = {},
-    ): Map<NodeId, number> {
+    public update(modifiedNodes: Set<NodeId>, options: DeltaPageRankOptions = {}): Map<NodeId, number> {
         // Mark modified nodes and their neighbors as active
         this.activeNodes.clear();
 
@@ -286,6 +299,10 @@ export class PriorityDeltaPageRank {
     private danglingNodes: Set<NodeId>;
     private nodeCount: number;
 
+    /**
+     * Creates a new PriorityDeltaPageRank instance for the given graph.
+     * @param graph - The directed graph to compute PageRank on
+     */
     constructor(graph: Graph) {
         if (!graph.isDirected) {
             throw new Error("PriorityDeltaPageRank requires a directed graph");
@@ -332,6 +349,12 @@ export 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
+     */
     public computeWithPriority(options: DeltaPageRankOptions = {}): Map<NodeId, number> {
         const {
             dampingFactor = 0.85,