@graphty/algorithms 1.6.0 → 1.7.1

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "@graphty/algorithms",
-  "version": "1.6.0",
+  "version": "1.7.1",
   "description": "Graph algorithms library for browser environments implemented in TypeScript",
   "author": "Adam Powers <apowers@ato.ms>",
   "main": "dist/algorithms.js",
   "type": "module",
   "exports": {
     ".": {
+      "types": "./dist/algorithms.d.ts",
       "import": "./dist/algorithms.js",
-      "types": "./dist/algorithms.d.ts"
+      "default": "./dist/algorithms.js"
     }
   },
   "types": "dist/algorithms.d.ts",
@@ -56,10 +57,35 @@
     }
   },
   "devDependencies": {
+    "@chromatic-com/storybook": "^4.0.0",
+    "@eslint/js": "^9.29.0",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "@storybook/addon-docs": "^9.0.11",
+    "@storybook/html-vite": "^9.0.11",
+    "@storybook/test": "^8.6.14",
     "@types/benchmark": "^2.1.5",
     "benchmark": "^2.1.4",
+    "chromatic": "^11.0.0",
+    "eslint": "^9.29.0",
+    "eslint-plugin-simple-import-sort": "^12.1.1",
     "gh-pages": "^6.3.0",
-    "ts-node": "^10.9.2"
+    "globals": "^15.12.0",
+    "happy-dom": "^18.0.1",
+    "knip": "^5.61.3",
+    "playwright": "^1.53.0",
+    "semantic-release": "^25.0.2",
+    "storybook": "^9.0.11",
+    "ts-node": "^10.9.2",
+    "tsx": "^4.20.3",
+    "typedoc": "^0.28.15",
+    "typedoc-plugin-markdown": "^4.9.0",
+    "typedoc-vitepress-theme": "^1.1.2",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.34.1",
+    "vite": "^7.0.5",
+    "vitepress": "^1.6.3",
+    "vitest": "^3.2.4"
   },
   "dependencies": {
     "pupt": "^1.3.2",
@@ -112,6 +138,8 @@
     "docs:dev": "vitepress dev docs",
     "docs:watch": "npm run docs:api && (npm run docs:api:watch & npm run docs:dev & wait)",
     "docs:build": "npm run docs:api && vitepress build docs",
-    "docs:preview": "vitepress preview docs"
+    "docs:preview": "vitepress preview docs",
+    "storybook": ". ../.env 2>/dev/null; storybook dev -p ${PORT:-6006} --host ${HOST:-localhost} ${HTTPS_CERT_PATH:+--https --ssl-cert $HTTPS_CERT_PATH --ssl-key $HTTPS_KEY_PATH} --no-open",
+    "build-storybook": "storybook build"
   }
 }

package/src/algorithms/community/girvan-newman.ts

@@ -39,7 +39,7 @@ export function girvanNewman(graph: Graph, options: GirvanNewmanOptions = {}): C
     while (Array.from(workingGraph.edges()).length > 0 && iterations < maxIterations) {
         iterations++;
         // Calculate edge betweenness centrality
-        const edgeBetweenness = calculateEdgeBetweenness(workingGraph);
+        const { betweenness: edgeBetweenness, edgeEndpoints } = calculateEdgeBetweenness(workingGraph);
 
         if (edgeBetweenness.size === 0) {
             break;
@@ -51,9 +51,10 @@ export function girvanNewman(graph: Graph, options: GirvanNewmanOptions = {}): C
 
         for (const [edgeKey, centrality] of edgeBetweenness) {
             if (Math.abs(centrality - maxBetweenness) < 1e-10) {
-                const [source, target] = edgeKey.split("|");
-                if (source && target) {
-                    edgesToRemove.push({ source, target });
+                // Use original edge endpoints to preserve node ID types (number vs string)
+                const endpoints = edgeEndpoints.get(edgeKey);
+                if (endpoints) {
+                    edgesToRemove.push(endpoints);
                 }
             }
         }
@@ -91,21 +92,31 @@ export function girvanNewman(graph: Graph, options: GirvanNewmanOptions = {}): C
     return dendrogram;
 }
 
+/**
+ * Edge betweenness result containing centrality values and original edge endpoints
+ */
+interface EdgeBetweennessResult {
+    betweenness: Map<string, number>;
+    edgeEndpoints: Map<string, { source: NodeId; target: NodeId }>;
+}
+
 /**
  * Calculate edge betweenness centrality for all edges in the graph
  *
  * Edge betweenness is the fraction of shortest paths that pass through the edge.
  * We adapt node betweenness centrality calculation to work with edges.
  * @param graph - The input graph to analyze
- * @returns Map of edge keys to their betweenness centrality values
+ * @returns Object with betweenness map and edge endpoints map (preserving original ID types)
  */
-function calculateEdgeBetweenness(graph: Graph): Map<string, number> {
+function calculateEdgeBetweenness(graph: Graph): EdgeBetweennessResult {
     const edgeBetweenness = new Map<string, number>();
+    const edgeEndpoints = new Map<string, { source: NodeId; target: NodeId }>();
 
-    // Initialize all edges with 0 betweenness
+    // Initialize all edges with 0 betweenness and store original endpoints
     for (const edge of graph.edges()) {
         const edgeKey = getEdgeKey(edge.source, edge.target);
         edgeBetweenness.set(edgeKey, 0);
+        edgeEndpoints.set(edgeKey, { source: edge.source, target: edge.target });
     }
 
     // For each node as source, calculate shortest paths and accumulate edge betweenness
@@ -182,7 +193,7 @@ function calculateEdgeBetweenness(graph: Graph): Map<string, number> {
         }
     }
 
-    return edgeBetweenness;
+    return { betweenness: edgeBetweenness, edgeEndpoints };
 }
 
 /**

package/src/clustering/mcl.ts

@@ -111,7 +111,7 @@ function buildTransitionMatrix(graph: Graph, nodeIds: NodeId[], selfLoops: boole
     // Fill adjacency values
     for (let i = 0; i < n; i++) {
         const nodeId = nodeIds[i];
-        if (!nodeId) {
+        if (nodeId === undefined) {
             continue;
         }
 
@@ -398,11 +398,16 @@ function extractClusters(
         }
     }
 
-    // Assign nodes to clusters based on columns
-    let clusterIndex = 0;
+    // Assign nodes (columns) to clusters based on which attractor (row) they flow to
+    // After MCL convergence, matrix[i][j] > 0 means node j belongs to attractor i's cluster
+    const attractorToCommunity = new Map<number, number[]>();
+
     for (let j = 0; j < n; j++) {
-        // Find nodes that belong to this cluster (column)
-        const clusterNodes: number[] = [];
+        // Find the attractor for this column (node j)
+        // Look for the row with the highest non-zero value in column j
+        let maxVal = 0;
+        let attractorRow = -1;
+
         for (let i = 0; i < n; i++) {
             const matrixRow = matrix[i];
             if (!matrixRow) {
@@ -410,34 +415,43 @@ function extractClusters(
             }
 
             const val = matrixRow[j];
-            if (val !== undefined && val > 0 && !nodeToCluster.has(i)) {
-                clusterNodes.push(i);
-                nodeToCluster.set(i, clusterIndex);
+            if (val !== undefined && val > maxVal) {
+                maxVal = val;
+                attractorRow = i;
             }
         }
 
-        if (clusterNodes.length > 0) {
-            communities.push(
-                clusterNodes
-                    .map((idx) => {
-                        const nodeId = nodeIds[idx];
-                        return nodeId;
-                    })
-                    .filter((node): node is NodeId => node !== undefined),
-            );
-            clusterIndex++;
+        if (attractorRow >= 0) {
+            // Node j belongs to the cluster of attractor at row attractorRow
+            let community = attractorToCommunity.get(attractorRow);
+            if (!community) {
+                community = [];
+                attractorToCommunity.set(attractorRow, community);
+            }
+            community.push(j);
+            nodeToCluster.set(j, attractorRow);
         }
     }
 
-    // Handle isolated nodes
-    for (let i = 0; i < n; i++) {
-        if (!nodeToCluster.has(i)) {
-            const nodeId = nodeIds[i];
+    // Convert attractor communities to node ID arrays
+    for (const [, memberIndices] of attractorToCommunity) {
+        communities.push(
+            memberIndices
+                .map((idx) => {
+                    const nodeId = nodeIds[idx];
+                    return nodeId;
+                })
+                .filter((node): node is NodeId => node !== undefined),
+        );
+    }
+
+    // Handle isolated nodes (nodes with all-zero columns)
+    for (let j = 0; j < n; j++) {
+        if (!nodeToCluster.has(j)) {
+            const nodeId = nodeIds[j];
             if (nodeId !== undefined) {
                 communities.push([nodeId]);
             }
-
-            nodeToCluster.set(i, clusterIndex++);
         }
     }
 

package/src/clustering/spectral.ts

@@ -1,6 +1,6 @@
 import type { Graph } from "../core/graph.js";
 import type { NodeId } from "../types/index.js";
-import { euclideanDistance } from "../utils/math-utilities.js";
+import { euclideanDistance, SeededRandom } from "../utils/math-utilities.js";
 
 /**
  * Spectral Clustering implementation
@@ -17,6 +17,7 @@ export interface SpectralClusteringOptions {
     laplacianType?: "unnormalized" | "normalized" | "randomWalk"; // Type of Laplacian
     maxIterations?: number; // Max iterations for k-means (default: 100)
     tolerance?: number; // Convergence tolerance (default: 1e-4)
+    seed?: number; // Random seed for reproducible results
 }
 
 export interface SpectralClusteringResult {
@@ -41,7 +42,10 @@ export interface SpectralClusteringResult {
  * @returns Spectral clustering result with communities and cluster assignments
  */
 export function spectralClustering(graph: Graph, options: SpectralClusteringOptions): SpectralClusteringResult {
-    const { k, laplacianType = "normalized", maxIterations = 100, tolerance = 1e-4 } = options;
+    const { k, laplacianType = "normalized", maxIterations = 100, tolerance = 1e-4, seed } = options;
+
+    // Create random function - use seeded PRNG if seed provided, otherwise Math.random
+    const random = seed !== undefined ? SeededRandom.createGenerator(seed) : Math.random;
 
     // Input validation
     if (k < 1 || !Number.isInteger(k)) {
@@ -67,7 +71,7 @@ export function spectralClustering(graph: Graph, options: SpectralClusteringOpti
     const laplacianMatrix = buildLaplacianMatrix(adjacencyMatrix, laplacianType);
 
     // Find k smallest eigenvectors
-    const eigenResult = findSmallestEigenvectors(laplacianMatrix, k);
+    const eigenResult = findSmallestEigenvectors(laplacianMatrix, k, random);
 
     // Perform k-means clustering on the eigenvectors
     // For spectral clustering, we need to transpose the eigenvector matrix
@@ -89,7 +93,7 @@ export function spectralClustering(graph: Graph, options: SpectralClusteringOpti
         normalizeRows(dataPoints);
     }
 
-    const kmeans = kMeansClustering(dataPoints, k, maxIterations, tolerance);
+    const kmeans = kMeansClustering(dataPoints, k, maxIterations, tolerance, random);
 
     // Build communities
     const communities: NodeId[][] = Array.from({ length: k }, () => []);
@@ -293,11 +297,13 @@ function buildLaplacianMatrix(adjacency: number[][], type: string): number[][] {
  * This is a simplified implementation - in practice, you'd use LAPACK or similar
  * @param matrix - The Laplacian matrix for eigendecomposition
  * @param k - Number of smallest eigenvectors to find
+ * @param random - Random number generator function
  * @returns Object containing eigenvalues and corresponding eigenvectors
  */
 function findSmallestEigenvectors(
     matrix: number[][],
     k: number,
+    random: () => number,
 ): {
     eigenvalues: number[];
     eigenvectors: number[][];
@@ -318,7 +324,7 @@ function findSmallestEigenvectors(
     // For spectral clustering, we need proper eigenvectors
     // Special handling for small k values which are common in clustering
     if (k <= 3 && n > k) {
-        return computeSmallestEigenvectorsSimple(matrix, k, n);
+        return computeSmallestEigenvectorsSimple(matrix, k, n, random);
     }
 
     // For larger k, use power iteration
@@ -330,7 +336,7 @@ function findSmallestEigenvectors(
         // Initialize random vector
         let vector = Array(n)
             .fill(0)
-            .map(() => Math.random() - 0.5);
+            .map(() => random() - 0.5);
 
         // Normalize initial vector
         const initNorm = Math.sqrt(vector.reduce((sum, val) => sum + val * val, 0));
@@ -447,6 +453,7 @@ function normalizeRows(matrix: number[][]): void {
  * @param k - Number of clusters to form
  * @param maxIterations - Maximum number of iterations
  * @param tolerance - Convergence tolerance for centroid movement
+ * @param random - Random number generator function
  * @returns Object containing cluster assignments and final centroids
  */
 function kMeansClustering(
@@ -454,6 +461,7 @@ function kMeansClustering(
     k: number,
     maxIterations: number,
     tolerance = 1e-4,
+    random: () => number = Math.random,
 ): { assignments: number[]; centroids: number[][] } {
     const n = data.length;
     const d = data[0]?.length ?? 0;
@@ -476,7 +484,7 @@ function kMeansClustering(
     const selectedIndices = new Set<number>();
 
     while (centroids.length < k && selectedIndices.size < n) {
-        const idx = Math.floor(Math.random() * n);
+        const idx = Math.floor(random() * n);
         if (!selectedIndices.has(idx) && data[idx]) {
             selectedIndices.add(idx);
             centroids.push([...data[idx]]);
@@ -487,7 +495,7 @@ function kMeansClustering(
     while (centroids.length < k) {
         const centroid = Array(d).fill(0) as number[];
         for (let j = 0; j < d; j++) {
-            centroid[j] = Math.random() - 0.5;
+            centroid[j] = random() - 0.5;
         }
         centroids.push(centroid);
     }
@@ -611,12 +619,14 @@ function kMeansClustering(
  * @param matrix - The Laplacian matrix
  * @param k - Number of eigenvectors to compute (1-3)
  * @param n - Size of the matrix
+ * @param random - Random number generator function
  * @returns Object containing eigenvalues and eigenvectors
  */
 function computeSmallestEigenvectorsSimple(
     matrix: number[][],
     k: number,
     n: number,
+    random: () => number,
 ): {
     eigenvalues: number[];
     eigenvectors: number[][];
@@ -635,7 +645,7 @@ function computeSmallestEigenvectorsSimple(
         const maxEig = 2; // For normalized Laplacian, max eigenvalue <= 2
         let vector = Array(n)
             .fill(0)
-            .map(() => Math.random() - 0.5);
+            .map(() => random() - 0.5);
 
         // Make orthogonal to first eigenvector
         const dot1 = vector.reduce((sum, val) => sum + val / Math.sqrt(n), 0);
@@ -681,7 +691,7 @@ function computeSmallestEigenvectorsSimple(
     if (k >= 3) {
         let vector = Array(n)
             .fill(0)
-            .map(() => Math.random() - 0.5);
+            .map(() => random() - 0.5);
 
         // Orthogonalize against previous eigenvectors
         for (const prev of eigenvectors) {