@graphty/algorithms 1.7.2 → 1.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphty/algorithms",
-  "version": "1.7.2",
+  "version": "1.8.0",
   "description": "Graph algorithms library for browser environments implemented in TypeScript",
   "author": "Adam Powers <apowers@ato.ms>",
   "main": "dist/algorithms.js",
@@ -88,7 +88,11 @@
     "vitest": "^3.2.4"
   },
   "dependencies": {
-    "typedfastbitset": "^0.6.1"
+    "typedfastbitset": "^0.6.1",
+    "@graphty/graph-format": "^1.0.1"
+  },
+  "peerDependencies": {
+    "@graphty/graph-format": "^1.0.0"
   },
   "scripts": {
     "test": "vitest",
@@ -114,7 +118,7 @@
     "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": "eslint && tsc --noEmit && tsc -p tsconfig.typecheck.json",
     "lint:fix": "eslint --fix",
     "lint:knip": "cd .. && pnpm run lint:knip -- --workspace algorithms",
     "typecheck": "tsc --noEmit",

package/src/algorithms/centrality/betweenness.ts

@@ -10,21 +10,43 @@ import { bfsWithPathCounting } from "../traversal/bfs-variants.js";
  */
 
 /**
- * Betweenness centrality options
+ * Betweenness centrality options.
+ *
+ * Every member is `readonly` and carries `| undefined`: the GPU package compiles this declaration
+ * a second time under `exactOptionalPropertyTypes`, where `sources?: readonly number[]` and
+ * `sources?: readonly number[] | undefined` are different types (plan decision PD-6).
  */
 export interface BetweennessCentralityOptions {
+    /** Whether to normalize the centrality values (default: false) */
+    readonly normalized?: boolean | undefined;
+    /** Whether to use endpoints in path counting (default: false) */
+    readonly endpoints?: boolean | undefined;
+    /** Whether to use optimized BFS implementation for large graphs */
+    readonly optimized?: boolean | undefined;
     /**
-     * Whether to normalize the centrality values (default: false)
-     */
-    normalized?: boolean;
-    /**
-     * Whether to use endpoints in path counting (default: false)
+     * Sampled betweenness: the source NODE INDICES to run from. Indices are meaningful only against
+     * a `GraphSnapshot`, so the legacy `Graph`-taking entry points below THROW when this is set.
      */
-    endpoints?: boolean;
-    /**
-     * Whether to use optimized BFS implementation for large graphs
-     */
-    optimized?: boolean;
+    readonly sources?: readonly number[] | undefined;
+    /** Sampled betweenness: how many sources to draw when `sources` is not given. */
+    readonly k?: number | undefined;
+}
+
+/**
+ * Refuse the index-space options on a path that has no index space.
+ *
+ * Ignoring them would be the expensive silence: a caller asking for a 128-source sample would get
+ * an exact all-sources run, correct and a thousand times too slow, with no signal at all.
+ * @param options - The caller's options
+ * @param fn - The entry point's name, for the message
+ */
+function rejectIndexOptions(options: BetweennessCentralityOptions, fn: string): void {
+    if (options.sources !== undefined || options.k !== undefined) {
+        throw new Error(
+            `${fn}: 'sources' and 'k' are node INDICES and are meaningful only against a GraphSnapshot; ` +
+                "call accelerated(accelerator).betweennessCentrality(snapshot, options) instead",
+        );
+    }
 }
 
 /**
@@ -205,6 +227,7 @@ export function betweennessCentrality(
     graph: Graph,
     options: BetweennessCentralityOptions = {},
 ): Record<string, number> {
+    rejectIndexOptions(options, "betweennessCentrality");
     const nodes = Array.from(graph.nodes()).map((node) => node.id);
     const centrality: Record<string, number> = {};
 
@@ -250,6 +273,7 @@ export function nodeBetweennessCentrality(
     targetNode: NodeId,
     options: BetweennessCentralityOptions = {},
 ): number {
+    rejectIndexOptions(options, "nodeBetweennessCentrality");
     if (!graph.hasNode(targetNode)) {
         throw new Error(`Node ${String(targetNode)} not found in graph`);
     }
@@ -268,6 +292,7 @@ export function edgeBetweennessCentrality(
     graph: Graph,
     options: BetweennessCentralityOptions = {},
 ): Map<string, number> {
+    rejectIndexOptions(options, "edgeBetweennessCentrality");
     const nodes = Array.from(graph.nodes()).map((node) => node.id);
     const edgeCentrality = new Map<string, number>();
 

package/src/core/graph.ts

@@ -1,5 +1,16 @@
 import type { Edge, GraphConfig, Node, NodeId } from "../types/index.js";
 
+/**
+ * True when an undirected edge seen from `source` is the mirror of one already yielded from
+ * `target`: ids of one type compare by value, ids of different types by their type name.
+ * @param source - The node the edge is read from
+ * @param target - The node the edge points to
+ * @returns True when this side of the edge is the duplicate
+ */
+function isMirror(source: NodeId, target: NodeId): boolean {
+    return typeof source === typeof target ? source > target : typeof source > typeof target;
+}
+
 /**
  * Core Graph data structure for the Graphty Algorithms library
  *
@@ -12,6 +23,7 @@ export class Graph {
     private incomingEdges: Map<NodeId, Map<NodeId, Edge>>; // For directed graphs
     private config: GraphConfig;
     private edgeCount: number;
+    private mutations: number;
 
     /**
      * Creates a new Graph instance.
@@ -28,6 +40,7 @@ export class Graph {
         this.adjacencyList = new Map();
         this.incomingEdges = new Map();
         this.edgeCount = 0;
+        this.mutations = 0;
     }
 
     /**
@@ -43,6 +56,8 @@ export class Graph {
             if (this.config.directed) {
                 this.incomingEdges.set(id, new Map());
             }
+
+            this.mutations++;
         }
     }
 
@@ -88,6 +103,7 @@ export class Graph {
             this.incomingEdges.delete(id);
         }
 
+        this.mutations++;
         return true;
     }
 
@@ -142,6 +158,7 @@ export class Graph {
         }
 
         this.edgeCount++;
+        this.mutations++;
     }
 
     /**
@@ -172,6 +189,7 @@ export class Graph {
         }
 
         this.edgeCount--;
+        this.mutations++;
         return true;
     }
 
@@ -223,6 +241,18 @@ export class Graph {
         return this.nodeMap.size;
     }
 
+    /**
+     * A counter that increases on every topology change (`addNode` of a new id, `removeNode`,
+     * `addEdge`, `removeEdge`, `clear`) and never on a read. Callers memoise derived structures on
+     * `(graph, mutationCount)`; graph-format design 14.1 rule 4 names this counter, and `toSnapshot`
+     * is its first consumer. It is monotone and is NOT reset by `clear()`: a reset could hand a
+     * stale cache entry a matching key.
+     * @returns The number of topology changes made to this graph
+     */
+    get mutationCount(): number {
+        return this.mutations;
+    }
+
     /**
      * Get the number of edges in the graph
      * @returns The total count of edges
@@ -254,8 +284,10 @@ export class Graph {
     *edges(): IterableIterator<Edge> {
         for (const [source, edges] of this.adjacencyList) {
             for (const edge of edges.values()) {
-                // For undirected graphs, only yield each edge once
-                if (!this.config.directed && source > edge.target) {
+                // For undirected graphs, only yield each edge once. A string never compares
+                // greater than a number (both `<` and `>` are false), so mixed-type ids are
+                // ordered by their type name first; the mirror is then skipped on exactly one side.
+                if (!this.config.directed && isMirror(source, edge.target)) {
                     continue;
                 }
 
@@ -371,6 +403,7 @@ export class Graph {
         this.adjacencyList.clear();
         this.incomingEdges.clear();
         this.edgeCount = 0;
+        this.mutations++;
     }
 
     /**

package/src/index.ts

@@ -25,6 +25,12 @@ export type {
     MSTResult,
     Node,
     NodeId,
+    // NOTE: this explicit re-export SHADOWS the `PageRankOptions` that `export * from
+    // "./algorithms/index.js"` below re-exports from centrality/pagerank.ts, which is the one
+    // pageRank() actually takes. The two differ (`alpha` here, `dampingFactor` there), so
+    // `const o: PageRankOptions = { alpha: 0.9 }` compiles and is silently ignored. Neither is
+    // changed during the dual-API window (graph-format design 14.1 rule 1); this one is removed at
+    // 2.0. See design/decisions/2026-09-19-pagerank-options-shadowing.md.
     PageRankOptions,
     ShortestPathResult,
     TraversalOptions,
@@ -43,5 +49,45 @@ export * from "./data-structures/index.js";
 // Optimized algorithm exports
 export * from "./optimized/index.js";
 
+// Index-based implementations over @graphty/graph-format snapshots (graph-format design 14.1 rule 2).
+// A NAMESPACE, not a flat re-export: indexed.pageRank, indexed.dijkstra, indexed.breadthFirstSearch,
+// indexed.connectedComponents and indexed.kruskalMST all collide by name with the legacy functions above.
+export * as indexed from "./indexed/index.js";
+
+// The graph-format bridge (graph-format design 14.6 row A1).
+export { toSnapshot } from "./indexed/to-snapshot.js";
+
+// The accelerator seam (design/webgpu/webgpu-acceleration-plan.md section 9.2). Flat, NOT through the
+// namespace: the GPU package writes `import type { AlgorithmAccelerator } from "@graphty/algorithms"`.
+export type {
+    AcceleratedAlgorithms,
+    AlgorithmAccelerator,
+    ApspResultLike,
+    BellmanFordResultLike,
+    BetweennessAcceleratorOptions,
+    BfsResultLike,
+    CommunityResultLike,
+    CorenessResultLike,
+    EdgeScoresResultLike,
+    HitsOptionsLike,
+    HitsResultLike,
+    LabelResultLike,
+    MstResultLike,
+    PageRankResultLike,
+    ScoresResultLike,
+    SsspResultLike,
+} from "./indexed/accelerator.js";
+export { accelerated } from "./indexed/accelerator.js";
+export type { BfsOptions, BfsResult } from "./indexed/bfs.js";
+export type { CommonNeighborsOptions } from "./indexed/common-neighbors.js";
+export type { LabelResult } from "./indexed/components.js";
+export type { SsspOptions, SsspResult } from "./indexed/dijkstra.js";
+export type { MstOptions, MstResult } from "./indexed/mst.js";
+// Aliased: the flat names are taken twice over (types/index.ts:96 and centrality/pagerank.ts:15).
+export type {
+    PageRankOptions as IndexedPageRankOptions,
+    PageRankResult as IndexedPageRankResult,
+} from "./indexed/pagerank.js";
+
 // Note: Configuration exports have been removed.
 // The library now automatically optimizes based on graph size.

package/src/indexed/accelerator.ts

@@ -0,0 +1,225 @@
+/**
+ * The accelerator seam of `@graphty/algorithms` (WebGPU design section 9.2). It contains NO
+ * WebGPU types: an accelerator is anything that satisfies `AlgorithmAccelerator` structurally,
+ * and this package never imports the GPU package (design section 9.1, the dependency direction).
+ *
+ * `accelerated(acc)` is the ONE dispatcher object (design section 9.2, the dispatcher rule); the
+ * spelling is `accelerated(acc).pageRank(s, options)`, never
+ * `runAlgorithm(snapshot, { accelerator })`. There is no try/catch anywhere below: an accelerator
+ * method that throws propagates its throw unchanged, because a silent CPU fallback would hide a
+ * broken device behind a slow answer.
+ * @module
+ */
+
+import type { F32, F64, GraphSnapshot, NumericVector, U32 } from "@graphty/graph-format";
+
+import type { BfsOptions } from "./bfs.js";
+import { type SsspOptions, type SsspResult, walkPredArcs, walkPredEdges } from "./dijkstra.js";
+import * as indexed from "./index.js";
+import type { MstOptions } from "./mst.js";
+import type { PageRankOptions } from "./pagerank.js";
+
+// ============================================================ result shapes (design 9.2 lines 2909-2922)
+// Scores may be f32 (an accelerator) or f64 (the CPU ports), so every score field is NumericVector.
+
+/** A score vector with its convergence report. @public */
+export interface ScoresResultLike {
+    readonly scores: NumericVector;
+    readonly iterations: number;
+    readonly converged: boolean;
+}
+/** ScoresResultLike plus the mass held by dangling nodes. @public */
+export interface PageRankResultLike extends ScoresResultLike {
+    readonly danglingMass?: number | undefined;
+}
+/** The two HITS vectors with their convergence report. @public */
+export interface HitsResultLike {
+    readonly hubs: NumericVector;
+    readonly authorities: NumericVector;
+    readonly iterations: number;
+    readonly converged: boolean;
+}
+/** A partition: dense labels, a count, and the grouped node indices. @public */
+export interface LabelResultLike {
+    readonly labels: U32;
+    readonly count: number;
+    groups(): U32[];
+}
+/** A breadth-first traversal. @public */
+export interface BfsResultLike {
+    readonly depth: U32;
+    readonly parent: U32;
+    readonly order: U32;
+    readonly visitedCount: number;
+}
+/** Single-source distances plus the relaxing arc per node. @public */
+export interface SsspResultLike {
+    readonly dist: NumericVector;
+    readonly predArc: U32;
+}
+/** SsspResultLike plus the negative-cycle flag. @public */
+export interface BellmanFordResultLike extends SsspResultLike {
+    readonly hasNegativeCycle: boolean;
+}
+/** A per-logical-edge score vector. @public */
+export interface EdgeScoresResultLike {
+    readonly scores: NumericVector;
+}
+/** An all-pairs distance matrix, row-major, n by n. @public */
+export interface ApspResultLike {
+    readonly dist: NumericVector;
+    readonly n: number;
+}
+/** Per-node coreness. @public */
+export interface CorenessResultLike {
+    readonly coreness: U32;
+}
+/** A spanning forest as logical edge indices. @public */
+export interface MstResultLike {
+    readonly edges: U32;
+    readonly totalWeight: number;
+}
+/** A partition with its modularity. @public */
+export interface CommunityResultLike extends LabelResultLike {
+    readonly modularity: number;
+}
+
+// ============================================================ the injected object (design 9.2 lines 2925-2948)
+
+/**
+ * The structural contract an injected accelerator satisfies. EVERY member except `kind` is
+ * optional: an accelerator declares only what it implements, and the dispatcher runs the CPU port
+ * for everything else. The list is the design's, in full, so that an accelerator written against
+ * it needs no change as the ports land.
+ * @public
+ */
+export interface AlgorithmAccelerator {
+    readonly kind: string;
+    pageRank?(s: GraphSnapshot, options?: PageRankOptions): Promise<PageRankResultLike>;
+    personalizedPageRank?(
+        s: GraphSnapshot,
+        personalization: F32 | F64,
+        options?: PageRankOptions,
+    ): Promise<PageRankResultLike>;
+    hits?(s: GraphSnapshot, options?: HitsOptionsLike): Promise<HitsResultLike>;
+    eigenvectorCentrality?(s: GraphSnapshot, options?: HitsOptionsLike): Promise<ScoresResultLike>;
+    katzCentrality?(s: GraphSnapshot, options?: HitsOptionsLike): Promise<ScoresResultLike>;
+    connectedComponents?(s: GraphSnapshot): Promise<LabelResultLike>;
+    weaklyConnectedComponents?(s: GraphSnapshot): Promise<LabelResultLike>;
+    breadthFirstSearch?(s: GraphSnapshot, source: number, options?: BfsOptions): Promise<BfsResultLike>;
+    sssp?(s: GraphSnapshot, source: number, options?: SsspOptions): Promise<SsspResultLike>;
+    bellmanFord?(s: GraphSnapshot, source: number, options?: SsspOptions): Promise<BellmanFordResultLike>;
+    closenessCentrality?(s: GraphSnapshot, options?: HitsOptionsLike): Promise<ScoresResultLike>;
+    betweennessCentrality?(s: GraphSnapshot, options?: BetweennessAcceleratorOptions): Promise<ScoresResultLike>;
+    edgeBetweennessCentrality?(
+        s: GraphSnapshot,
+        options?: BetweennessAcceleratorOptions,
+    ): Promise<EdgeScoresResultLike>;
+    allPairsShortestPath?(s: GraphSnapshot, options?: SsspOptions): Promise<ApspResultLike>;
+    kCoreDecomposition?(s: GraphSnapshot): Promise<CorenessResultLike>;
+    triangleCount?(s: GraphSnapshot): Promise<{ readonly perNode: U32; readonly total: number }>;
+    labelPropagation?(s: GraphSnapshot, options?: HitsOptionsLike): Promise<LabelResultLike>;
+    minimumSpanningTree?(s: GraphSnapshot, options?: MstOptions): Promise<MstResultLike>;
+    louvain?(s: GraphSnapshot, options?: HitsOptionsLike): Promise<CommunityResultLike>;
+    release?(s: GraphSnapshot): void;
+    dispose?(): void;
+}
+
+/**
+ * The option shape of the power-iteration family until each one's `indexed.*` port lands and
+ * brings its real option type (plan decision PD-2's "NOT TOUCHED" rows). It is DELIBERATELY not
+ * `Record<string, unknown>`: these three are the members every one of those algorithms takes, so
+ * an accelerator can honour them today and the type narrows rather than widens as ports arrive.
+ * @public
+ */
+export interface HitsOptionsLike {
+    readonly maxIterations?: number | undefined;
+    readonly tolerance?: number | undefined;
+    readonly weighted?: boolean | undefined;
+}
+
+/**
+ * Betweenness options as the accelerator sees them: node INDICES, which is the only form that
+ * means anything on a snapshot (plan decision PD-5).
+ * @public
+ */
+export interface BetweennessAcceleratorOptions {
+    readonly normalized?: boolean | undefined;
+    readonly endpoints?: boolean | undefined;
+    readonly sources?: readonly number[] | undefined;
+    readonly k?: number | undefined;
+}
+
+// ============================================================ the dispatcher (design 9.2 lines 2950-2957)
+
+/**
+ * The async dispatcher: one method per accelerable `indexed.*` function. Each delegates to the
+ * accelerator when it has the method and runs the CPU port otherwise, wrapped in `Promise.resolve`
+ * so both paths are async and graphty-element's `async run()` adapters treat them alike.
+ *
+ * The list GROWS with the A2 ports -- each port PR adds its method. Today it carries the six whose
+ * ports exist (plan departure DEP-8A-E).
+ * @public
+ */
+export interface AcceleratedAlgorithms {
+    readonly accelerator: AlgorithmAccelerator | null;
+    pageRank(s: GraphSnapshot, options?: PageRankOptions): Promise<PageRankResultLike>;
+    sssp(s: GraphSnapshot, source: number, options?: SsspOptions): Promise<SsspResult>;
+    breadthFirstSearch(s: GraphSnapshot, source: number, options?: BfsOptions): Promise<BfsResultLike>;
+    connectedComponents(s: GraphSnapshot): Promise<LabelResultLike>;
+    weaklyConnectedComponents(s: GraphSnapshot): Promise<LabelResultLike>;
+    minimumSpanningTree(s: GraphSnapshot, options?: MstOptions): Promise<MstResultLike>;
+}
+
+/**
+ * Attach `pathTo` / `pathEdges` to an accelerator's bare `{ dist, predArc }`, so both paths return
+ * the design's `SsspResult` and the element keeps ONE result-writing loop. The GPU package cannot
+ * attach them itself: it must not depend on the CPU package at runtime (design 9.2 line 2971, D3).
+ * @param s - The snapshot the search ran on
+ * @param source - The search's source node index
+ * @param like - The accelerator's result
+ * @returns The decorated result
+ */
+function decorateSssp(s: GraphSnapshot, source: number, like: SsspResultLike): SsspResult {
+    const { predArc } = like;
+    return {
+        dist: like.dist,
+        predArc,
+        pathTo: (target: number): U32 => walkPredArcs(s, predArc, source, target),
+        pathEdges: (target: number): U32 => walkPredEdges(s, predArc, source, target),
+    };
+}
+
+/**
+ * Build the dispatcher for an accelerator, or for none.
+ * @param acc - The injected accelerator, or `null` / `undefined` for the CPU path
+ * @returns A dispatcher whose methods delegate where they can and run the CPU port otherwise
+ * @public
+ */
+export function accelerated(acc: AlgorithmAccelerator | null | undefined): AcceleratedAlgorithms {
+    return {
+        accelerator: acc ?? null,
+        pageRank: (s, options) =>
+            acc?.pageRank !== undefined ? acc.pageRank(s, options) : Promise.resolve(indexed.pageRank(s, options)),
+        sssp: (s, source, options) =>
+            acc?.sssp !== undefined
+                ? acc.sssp(s, source, options).then((like) => decorateSssp(s, source, like))
+                : Promise.resolve(indexed.dijkstra(s, source, options)),
+        breadthFirstSearch: (s, source, options) =>
+            acc?.breadthFirstSearch !== undefined
+                ? acc.breadthFirstSearch(s, source, options)
+                : Promise.resolve(indexed.breadthFirstSearch(s, source, options)),
+        connectedComponents: (s) =>
+            acc?.connectedComponents !== undefined
+                ? acc.connectedComponents(s)
+                : Promise.resolve(indexed.connectedComponents(s)),
+        weaklyConnectedComponents: (s) =>
+            acc?.weaklyConnectedComponents !== undefined
+                ? acc.weaklyConnectedComponents(s)
+                : Promise.resolve(indexed.weaklyConnectedComponents(s)),
+        minimumSpanningTree: (s, options) =>
+            acc?.minimumSpanningTree !== undefined
+                ? acc.minimumSpanningTree(s, options)
+                : Promise.resolve(indexed.kruskalMST(s, options)),
+    };
+}

package/src/indexed/bfs.ts

@@ -0,0 +1,57 @@
+import { type AdjacencyView, INVALID_INDEX, type U32 } from "@graphty/graph-format";
+
+/** Result of the index-based BFS (graph-format design 14.2 Port 1). @public */
+export interface BfsResult {
+    /** Visit order, one entry per visited node; a subarray of length `visitedCount`. */
+    readonly order: U32;
+    /** Parent of every node, INVALID_INDEX for the start node and for unvisited nodes. */
+    readonly parent: U32;
+    /** Hop depth of every node, INVALID_INDEX for unvisited nodes. */
+    readonly depth: U32;
+    /** How many nodes were visited. */
+    readonly visitedCount: number;
+}
+
+/** Options of the index-based BFS. @public */
+export interface BfsOptions {
+    /** Stop expanding at this depth; unbounded when omitted. */
+    readonly maxDepth?: number | undefined;
+}
+
+/**
+ * Breadth-first search over out-neighbours. Takes any `AdjacencyView`, so `s.reverse()` gives an
+ * in-neighbour BFS with no extra code.
+ * @param g - The adjacency to traverse
+ * @param start - The node index to start from
+ * @param options - Traversal options
+ * @returns The visit order, the parent array, the depth array and the visited count
+ * @public
+ */
+export function breadthFirstSearch(g: AdjacencyView, start: number, options: BfsOptions = {}): BfsResult {
+    const { nodeCount, rowPtr, colIdx } = g;
+    const parent = new Uint32Array(nodeCount).fill(INVALID_INDEX);
+    const depth = new Uint32Array(nodeCount).fill(INVALID_INDEX);
+    const order = new Uint32Array(nodeCount);
+    const maxDepth = options.maxDepth ?? INVALID_INDEX;
+    let head = 0;
+    let tail = 0;
+    order[tail++] = start;
+    depth[start] = 0;
+    while (head < tail) {
+        const u = order[head++];
+        const d = depth[u];
+        if (d >= maxDepth) {
+            continue;
+        }
+        const end = rowPtr[u + 1];
+        for (let a = rowPtr[u]; a < end; a++) {
+            const v = colIdx[a];
+            if (depth[v] === INVALID_INDEX) {
+                depth[v] = d + 1;
+                parent[v] = u;
+                order[tail++] = v;
+            }
+        }
+    }
+    return { order: order.subarray(0, tail), parent, depth, visitedCount: tail };
+}

package/src/indexed/common-neighbors.ts

@@ -0,0 +1,46 @@
+import type { AdjacencyView, GraphSnapshot } from "@graphty/graph-format";
+
+/** Options of the index-based common-neighbour score. @public */
+export interface CommonNeighborsOptions {
+    /** Intersect out(u) with in(v) instead of the two undirected rows. */
+    readonly directed?: boolean | undefined;
+}
+
+/**
+ * The number of distinct common neighbours of two nodes, by a merge of their sorted rows.
+ * @param s - The snapshot
+ * @param u - A node index
+ * @param v - A node index
+ * @param o - Options
+ * @returns The count of distinct common neighbours
+ * @public
+ */
+export function commonNeighborsScore(s: GraphSnapshot, u: number, v: number, o: CommonNeighborsOptions = {}): number {
+    const fwd: AdjacencyView = s;
+    const bwd: AdjacencyView = o.directed === true ? s.reverse() : s;
+    let i = fwd.rowPtr[u];
+    const iEnd = fwd.rowPtr[u + 1];
+    let j = bwd.rowPtr[v];
+    const jEnd = bwd.rowPtr[v + 1];
+    let count = 0;
+    while (i < iEnd && j < jEnd) {
+        const a = fwd.colIdx[i];
+        const b = bwd.colIdx[j];
+        if (a === b) {
+            count++;
+            i++;
+            j++;
+            while (i < iEnd && fwd.colIdx[i] === a) {
+                i++;
+            }
+            while (j < jEnd && bwd.colIdx[j] === b) {
+                j++;
+            }
+        } else if (a < b) {
+            i++;
+        } else {
+            j++;
+        }
+    }
+    return count;
+}

package/src/indexed/components.ts

@@ -0,0 +1,78 @@
+import { type GraphSnapshot, type U32 } from "@graphty/graph-format";
+
+import { IntUnionFind } from "./structures/union-find.js";
+
+/** A partition of the node set (graph-format design 14.2's result table, line 3738). @public */
+export interface LabelResult {
+    /** Dense label per node index, in first-seen order. */
+    readonly labels: U32;
+    /** Number of distinct labels. */
+    readonly count: number;
+    /**
+     * Node indices grouped by label, computed once and cached.
+     * @returns One array per label
+     */
+    groups(): U32[];
+}
+
+function withGroups(labels: U32, count: number): LabelResult {
+    let cached: U32[] | null = null;
+    return {
+        labels,
+        count,
+        groups(): U32[] {
+            if (cached === null) {
+                const sizes = new Uint32Array(count);
+                for (let i = 0; i < labels.length; i++) {
+                    sizes[labels[i]]++;
+                }
+                const out: U32[] = [];
+                for (let c = 0; c < count; c++) {
+                    out.push(new Uint32Array(sizes[c]));
+                }
+                const fill = new Uint32Array(count);
+                for (let i = 0; i < labels.length; i++) {
+                    const c = labels[i];
+                    out[c][fill[c]++] = i;
+                }
+                cached = out;
+            }
+            return cached;
+        },
+    };
+}
+
+function unionEdges(s: GraphSnapshot): LabelResult {
+    const uf = new IntUnionFind(s.nodeCount);
+    const el = s.edgeList();
+    for (let e = 0; e < s.edgeCount; e++) {
+        uf.union(el.src[e], el.dst[e]);
+    }
+    const { labels, count } = uf.toLabels();
+    return withGroups(labels, count);
+}
+
+/**
+ * Connected components of an UNDIRECTED snapshot.
+ * @param s - An undirected snapshot
+ * @returns The partition
+ * @public
+ */
+export function connectedComponents(s: GraphSnapshot): LabelResult {
+    if (s.directed) {
+        throw new Error(
+            "Connected components requires an undirected graph. Use weaklyConnectedComponents, or pass s.toUndirected().snapshot.",
+        );
+    }
+    return unionEdges(s);
+}
+
+/**
+ * Weakly connected components: the same union-find pass with the direction check dropped.
+ * @param s - Any snapshot
+ * @returns The partition
+ * @public
+ */
+export function weaklyConnectedComponents(s: GraphSnapshot): LabelResult {
+    return unionEdges(s);
+}