@graphty/algorithms 1.5.0 → 1.7.0

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "@graphty/algorithms",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "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++);
         }
     }