graphwise 1.5.2 → 1.7.0

package/dist/index/index.cjs

@@ -6,22 +6,326 @@ const require_kmeans = require("../kmeans-BIgSyGKu.cjs");
 const require_utils = require("../utils/index.cjs");
 const require_seeds = require("../seeds/index.cjs");
 const require_gpu = require("../gpu/index.cjs");
-//#region src/expansion/base.ts
+//#region src/async/utils.ts
+/**
+* Async utility functions.
+*
+* @module async/utils
+*/
+/** Collect an AsyncIterable into a readonly array. */
+async function collectAsyncIterable(iter) {
+	const result = [];
+	for await (const item of iter) result.push(item);
+	return result;
+}
+/** Default yield strategy: setTimeout(0) to yield to the event loop. */
+function defaultYieldStrategy() {
+	return new Promise((r) => {
+		setTimeout(r, 0);
+	});
+}
+//#endregion
+//#region src/async/runners.ts
+/**
+* Resolve a single GraphOp against a synchronous ReadableGraph.
+*
+* Returns a tagged GraphOpResponse so the receiving generator can narrow
+* the result type without type assertions.
+*
+* @param graph - The synchronous graph to query
+* @param op - The operation to resolve
+* @returns The tagged response
+*/
+function resolveSyncOp(graph, op) {
+	switch (op.tag) {
+		case "neighbours": return {
+			tag: "neighbours",
+			value: Array.from(graph.neighbours(op.id, op.direction))
+		};
+		case "degree": return {
+			tag: "degree",
+			value: graph.degree(op.id, op.direction)
+		};
+		case "getNode": return {
+			tag: "getNode",
+			value: graph.getNode(op.id)
+		};
+		case "getEdge": return {
+			tag: "getEdge",
+			value: graph.getEdge(op.source, op.target)
+		};
+		case "hasNode": return {
+			tag: "hasNode",
+			value: graph.hasNode(op.id)
+		};
+		case "yield": return { tag: "yield" };
+		case "progress": return { tag: "progress" };
+	}
+}
 /**
-* Default priority function - degree-ordered (DOME).
+* Drive a generator to completion using a synchronous graph.
+*
+* The generator yields GraphOp requests; each is resolved immediately
+* against the graph and the tagged response is fed back via gen.next().
+*
+* @param gen - The generator to drive
+* @param graph - The graph to resolve ops against
+* @returns The generator's return value
+*/
+function runSync(gen, graph) {
+	let step = gen.next();
+	while (step.done !== true) {
+		const response = resolveSyncOp(graph, step.value);
+		step = gen.next(response);
+	}
+	return step.value;
+}
+/**
+* Resolve a single GraphOp against an async ReadableGraph.
+*
+* AsyncIterables (neighbours) are collected into readonly arrays so the
+* generator receives the same value type as in sync mode. Returns a tagged
+* GraphOpResponse for type-safe narrowing without assertions.
+*
+* @param graph - The async graph to query
+* @param op - The operation to resolve
+* @returns A promise resolving to the tagged response
+*/
+async function resolveAsyncOp(graph, op) {
+	switch (op.tag) {
+		case "neighbours": return {
+			tag: "neighbours",
+			value: await collectAsyncIterable(graph.neighbours(op.id, op.direction))
+		};
+		case "degree": return {
+			tag: "degree",
+			value: await graph.degree(op.id, op.direction)
+		};
+		case "getNode": return {
+			tag: "getNode",
+			value: await graph.getNode(op.id)
+		};
+		case "getEdge": return {
+			tag: "getEdge",
+			value: await graph.getEdge(op.source, op.target)
+		};
+		case "hasNode": return {
+			tag: "hasNode",
+			value: await graph.hasNode(op.id)
+		};
+		case "yield": return { tag: "yield" };
+		case "progress": return { tag: "progress" };
+	}
+}
+/**
+* Drive a generator to completion using an async graph.
+*
+* Extends sync semantics with:
+* - Cancellation via AbortSignal (throws DOMException "AbortError")
+* - Cooperative yielding at `yield` ops (calls yieldStrategy)
+* - Progress callbacks at `progress` ops (may be async for backpressure)
+* - Error propagation: graph errors are forwarded via gen.throw(); if the
+*   generator does not handle them, they propagate to the caller
+*
+* @param gen - The generator to drive
+* @param graph - The async graph to resolve ops against
+* @param options - Runner configuration
+* @returns A promise resolving to the generator's return value
+*/
+async function runAsync(gen, graph, options) {
+	const signal = options?.signal;
+	const onProgress = options?.onProgress;
+	const yieldStrategy = options?.yieldStrategy ?? defaultYieldStrategy;
+	let step = gen.next();
+	while (step.done !== true) {
+		if (signal?.aborted === true) {
+			const abortError = new DOMException("Aborted", "AbortError");
+			try {
+				gen.throw(abortError);
+			} catch {
+				throw abortError;
+			}
+			throw abortError;
+		}
+		const op = step.value;
+		if (op.tag === "yield") {
+			await yieldStrategy();
+			step = gen.next({ tag: "yield" });
+			continue;
+		}
+		if (op.tag === "progress") {
+			if (onProgress !== void 0) {
+				const maybePromise = onProgress(op.stats);
+				if (maybePromise instanceof Promise) await maybePromise;
+			}
+			step = gen.next({ tag: "progress" });
+			continue;
+		}
+		let response;
+		try {
+			response = await resolveAsyncOp(graph, op);
+		} catch (error) {
+			step = gen.throw(error);
+			continue;
+		}
+		step = gen.next(response);
+	}
+	return step.value;
+}
+//#endregion
+//#region src/async/ops.ts
+function* opNeighbours(id, direction) {
+	const response = yield direction !== void 0 ? {
+		tag: "neighbours",
+		id,
+		direction
+	} : {
+		tag: "neighbours",
+		id
+	};
+	if (response.tag !== "neighbours") throw new TypeError(`Expected neighbours response, got ${response.tag}`);
+	return response.value;
+}
+function* opDegree(id, direction) {
+	const response = yield direction !== void 0 ? {
+		tag: "degree",
+		id,
+		direction
+	} : {
+		tag: "degree",
+		id
+	};
+	if (response.tag !== "degree") throw new TypeError(`Expected degree response, got ${response.tag}`);
+	return response.value;
+}
+//#endregion
+//#region src/expansion/base-helpers.ts
+/**
+* Check whether expansion should continue given current progress.
+*
+* Returns shouldContinue=false as soon as any configured limit is reached,
+* along with the appropriate termination reason.
+*
+* @param iterations - Number of iterations completed so far
+* @param nodesVisited - Number of distinct nodes visited so far
+* @param pathsFound - Number of paths discovered so far
+* @param limits - Configured expansion limits (0 = unlimited)
+* @returns Whether to continue and the termination reason if stopping
+*/
+function continueExpansion(iterations, nodesVisited, pathsFound, limits) {
+	if (limits.maxIterations > 0 && iterations >= limits.maxIterations) return {
+		shouldContinue: false,
+		termination: "limit"
+	};
+	if (limits.maxNodes > 0 && nodesVisited >= limits.maxNodes) return {
+		shouldContinue: false,
+		termination: "limit"
+	};
+	if (limits.maxPaths > 0 && pathsFound >= limits.maxPaths) return {
+		shouldContinue: false,
+		termination: "limit"
+	};
+	return {
+		shouldContinue: true,
+		termination: "exhausted"
+	};
+}
+/**
+* Reconstruct path from collision point.
+*
+* Traces backwards through the predecessor maps of both frontiers from the
+* collision node, then concatenates the two halves to form the full path.
+*
+* @param collisionNode - The node where the two frontiers met
+* @param frontierA - Index of the first frontier
+* @param frontierB - Index of the second frontier
+* @param predecessors - Predecessor maps, one per frontier
+* @param seeds - Seed nodes, one per frontier
+* @returns The reconstructed path, or null if seeds are missing
+*/
+function reconstructPath$1(collisionNode, frontierA, frontierB, predecessors, seeds) {
+	const pathA = [collisionNode];
+	const predA = predecessors[frontierA];
+	if (predA !== void 0) {
+		let node = collisionNode;
+		let next = predA.get(node);
+		while (next !== null && next !== void 0) {
+			node = next;
+			pathA.unshift(node);
+			next = predA.get(node);
+		}
+	}
+	const pathB = [];
+	const predB = predecessors[frontierB];
+	if (predB !== void 0) {
+		let node = collisionNode;
+		let next = predB.get(node);
+		while (next !== null && next !== void 0) {
+			node = next;
+			pathB.push(node);
+			next = predB.get(node);
+		}
+	}
+	const fullPath = [...pathA, ...pathB];
+	const seedA = seeds[frontierA];
+	const seedB = seeds[frontierB];
+	if (seedA === void 0 || seedB === void 0) return null;
+	return {
+		fromSeed: seedA,
+		toSeed: seedB,
+		nodes: fullPath
+	};
+}
+/**
+* Create an empty expansion result for early termination (e.g. no seeds given).
+*
+* @param algorithm - Name of the algorithm producing this result
+* @param startTime - performance.now() timestamp taken before the algorithm began
+* @returns An ExpansionResult with zero paths and zero stats
+*/
+function emptyResult$2(algorithm, startTime) {
+	return {
+		paths: [],
+		sampledNodes: /* @__PURE__ */ new Set(),
+		sampledEdges: /* @__PURE__ */ new Set(),
+		visitedPerFrontier: [],
+		stats: {
+			iterations: 0,
+			nodesVisited: 0,
+			edgesTraversed: 0,
+			pathsFound: 0,
+			durationMs: performance.now() - startTime,
+			algorithm,
+			termination: "exhausted"
+		}
+	};
+}
+//#endregion
+//#region src/expansion/base-core.ts
+/**
+* Default priority function — degree-ordered (DOME).
+*
+* Lower degree = higher priority, so sparse nodes are explored before hubs.
 */
 function degreePriority(_nodeId, context) {
 	return context.degree;
 }
 /**
-* Run BASE expansion algorithm.
+* Generator core of the BASE expansion algorithm.
 *
-* @param graph - Source graph
+* Yields GraphOp objects to request graph data, allowing the caller to
+* provide a sync or async runner. The optional `graphRef` parameter is
+* required when the priority function accesses `context.graph` — it is
+* populated in sync mode by `base()`. In async mode (Phase 4+), a proxy
+* graph may be supplied instead.
+*
+* @param graphMeta - Immutable graph metadata (directed, nodeCount, edgeCount)
 * @param seeds - Seed nodes for expansion
-* @param config - Expansion configuration
-* @returns Expansion result with discovered paths
+* @param config - Expansion configuration (priority, limits, debug)
+* @param graphRef - Optional real graph reference for context.graph in priority functions
+* @returns An ExpansionResult with all discovered paths and statistics
 */
-function base(graph, seeds, config) {
+function* baseCore(graphMeta, seeds, config, graphRef) {
 	const startTime = performance.now();
 	const { maxNodes = 0, maxIterations = 0, maxPaths = 0, priority = degreePriority, debug = false } = config ?? {};
 	if (seeds.length === 0) return emptyResult$2("base", startTime);
@@ -41,7 +345,8 @@ function base(graph, seeds, config) {
 		predecessors[i]?.set(seedNode, null);
 		combinedVisited.set(seedNode, i);
 		allVisited.add(seedNode);
-		const seedPriority = priority(seedNode, createPriorityContext(graph, seedNode, i, combinedVisited, allVisited, [], 0));
+		const seedDegree = yield* opDegree(seedNode);
+		const seedPriority = priority(seedNode, buildPriorityContext(seedNode, i, combinedVisited, allVisited, [], 0, seedDegree, graphRef));
 		queues[i]?.push({
 			nodeId: seedNode,
 			frontierIndex: i,
@@ -53,22 +358,17 @@ function base(graph, seeds, config) {
 	let iterations = 0;
 	let edgesTraversed = 0;
 	let termination = "exhausted";
-	const continueExpansion = () => {
-		if (maxIterations > 0 && iterations >= maxIterations) {
-			termination = "limit";
-			return false;
-		}
-		if (maxNodes > 0 && allVisited.size >= maxNodes) {
-			termination = "limit";
-			return false;
-		}
-		if (maxPaths > 0 && discoveredPaths.length >= maxPaths) {
-			termination = "limit";
-			return false;
-		}
-		return true;
+	const limits = {
+		maxIterations,
+		maxNodes,
+		maxPaths
 	};
-	while (continueExpansion()) {
+	for (;;) {
+		const check = continueExpansion(iterations, allVisited.size, discoveredPaths.length, limits);
+		if (!check.shouldContinue) {
+			termination = check.termination;
+			break;
+		}
 		let lowestPriority = Number.POSITIVE_INFINITY;
 		let activeFrontier = -1;
 		for (let i = 0; i < numFrontiers; i++) {
@@ -112,7 +412,7 @@ function base(graph, seeds, config) {
 				}
 			}
 		}
-		const neighbours = graph.neighbours(nodeId);
+		const neighbours = yield* opNeighbours(nodeId);
 		for (const neighbour of neighbours) {
 			edgesTraversed++;
 			const [s, t] = nodeId < neighbour ? [nodeId, neighbour] : [neighbour, nodeId];
@@ -122,9 +422,10 @@ function base(graph, seeds, config) {
 				sampledEdgeMap.set(s, targets);
 			}
 			targets.add(t);
-			const frontierVisited = visitedByFrontier[activeFrontier];
-			if (frontierVisited === void 0 || frontierVisited.has(neighbour)) continue;
-			const neighbourPriority = priority(neighbour, createPriorityContext(graph, neighbour, activeFrontier, combinedVisited, allVisited, discoveredPaths, iterations + 1));
+			const fv = visitedByFrontier[activeFrontier];
+			if (fv === void 0 || fv.has(neighbour)) continue;
+			const neighbourDegree = yield* opDegree(neighbour);
+			const neighbourPriority = priority(neighbour, buildPriorityContext(neighbour, activeFrontier, combinedVisited, allVisited, discoveredPaths, iterations + 1, neighbourDegree, graphRef));
 			queue.push({
 				nodeId: neighbour,
 				frontierIndex: activeFrontier,
@@ -154,12 +455,50 @@ function base(graph, seeds, config) {
 	};
 }
 /**
-* Create priority context for a node.
+* Create a sentinel ReadableGraph that throws if any member is accessed.
+*
+* Used in async mode when no graphRef is provided. Gives a clear error
+* message rather than silently returning incorrect results if a priority
+* function attempts to access `context.graph` before Phase 4b introduces
+* a real async proxy.
 */
-function createPriorityContext(graph, nodeId, frontierIndex, combinedVisited, allVisited, discoveredPaths, iteration) {
+function makeNoGraphSentinel() {
+	const msg = "Priority function accessed context.graph in async mode without a graph proxy. Pass a graphRef or use a priority function that does not access context.graph.";
+	const fail = () => {
+		throw new Error(msg);
+	};
 	return {
-		graph,
-		degree: graph.degree(nodeId),
+		get directed() {
+			return fail();
+		},
+		get nodeCount() {
+			return fail();
+		},
+		get edgeCount() {
+			return fail();
+		},
+		hasNode: fail,
+		getNode: fail,
+		nodeIds: fail,
+		neighbours: fail,
+		degree: fail,
+		getEdge: fail,
+		edges: fail
+	};
+}
+/**
+* Build a PriorityContext for a node using a pre-fetched degree.
+*
+* When `graphRef` is provided (sync mode), it is used as `context.graph` so
+* priority functions can access the graph directly. When it is absent (async
+* mode), a Proxy is used in its place that throws a clear error if any
+* property is accessed — this prevents silent failures until Phase 4b
+* introduces a real async proxy graph.
+*/
+function buildPriorityContext(_nodeId, frontierIndex, combinedVisited, allVisited, discoveredPaths, iteration, degree, graphRef) {
+	return {
+		graph: graphRef ?? makeNoGraphSentinel(),
+		degree,
 		frontierIndex,
 		visitedByFrontier: combinedVisited,
 		allVisited,
@@ -167,61 +506,55 @@ function createPriorityContext(graph, nodeId, frontierIndex, combinedVisited, al
 		iteration
 	};
 }
+//#endregion
+//#region src/expansion/base.ts
 /**
-* Reconstruct path from collision point.
+* Run BASE expansion synchronously.
+*
+* Delegates to baseCore + runSync. Behaviour is identical to the previous
+* direct implementation — all existing callers are unaffected.
+*
+* @param graph - Source graph
+* @param seeds - Seed nodes for expansion
+* @param config - Expansion configuration
+* @returns Expansion result with discovered paths
 */
-function reconstructPath$1(collisionNode, frontierA, frontierB, predecessors, seeds) {
-	const pathA = [collisionNode];
-	const predA = predecessors[frontierA];
-	if (predA !== void 0) {
-		let node = collisionNode;
-		let next = predA.get(node);
-		while (next !== null && next !== void 0) {
-			node = next;
-			pathA.unshift(node);
-			next = predA.get(node);
-		}
-	}
-	const pathB = [];
-	const predB = predecessors[frontierB];
-	if (predB !== void 0) {
-		let node = collisionNode;
-		let next = predB.get(node);
-		while (next !== null && next !== void 0) {
-			node = next;
-			pathB.push(node);
-			next = predB.get(node);
-		}
-	}
-	const fullPath = [...pathA, ...pathB];
-	const seedA = seeds[frontierA];
-	const seedB = seeds[frontierB];
-	if (seedA === void 0 || seedB === void 0) return null;
-	return {
-		fromSeed: seedA,
-		toSeed: seedB,
-		nodes: fullPath
-	};
+function base(graph, seeds, config) {
+	return runSync(baseCore({
+		directed: graph.directed,
+		nodeCount: graph.nodeCount,
+		edgeCount: graph.edgeCount
+	}, seeds, config, graph), graph);
 }
 /**
-* Create an empty result for early termination.
-*/
-function emptyResult$2(algorithm, startTime) {
-	return {
-		paths: [],
-		sampledNodes: /* @__PURE__ */ new Set(),
-		sampledEdges: /* @__PURE__ */ new Set(),
-		visitedPerFrontier: [],
-		stats: {
-			iterations: 0,
-			nodesVisited: 0,
-			edgesTraversed: 0,
-			pathsFound: 0,
-			durationMs: performance.now() - startTime,
-			algorithm,
-			termination: "exhausted"
-		}
-	};
+* Run BASE expansion asynchronously.
+*
+* Delegates to baseCore + runAsync. Supports:
+* - Cancellation via AbortSignal (config.signal)
+* - Progress callbacks (config.onProgress)
+* - Custom cooperative yield strategies (config.yieldStrategy)
+*
+* Note: priority functions that access `context.graph` are not supported in
+* async mode without a graph proxy (Phase 4b). The default degree-based
+* priority (DOME) does not access context.graph and works correctly.
+*
+* @param graph - Async source graph
+* @param seeds - Seed nodes for expansion
+* @param config - Expansion and async runner configuration
+* @returns Promise resolving to the expansion result
+*/
+async function baseAsync(graph, seeds, config) {
+	const [nodeCount, edgeCount] = await Promise.all([graph.nodeCount, graph.edgeCount]);
+	const gen = baseCore({
+		directed: graph.directed,
+		nodeCount,
+		edgeCount
+	}, seeds, config);
+	const runnerOptions = {};
+	if (config?.signal !== void 0) runnerOptions.signal = config.signal;
+	if (config?.onProgress !== void 0) runnerOptions.onProgress = config.onProgress;
+	if (config?.yieldStrategy !== void 0) runnerOptions.yieldStrategy = config.yieldStrategy;
+	return runAsync(gen, graph, runnerOptions);
 }
 //#endregion
 //#region src/expansion/dome.ts
@@ -3011,6 +3344,7 @@ exports.adaptive = adaptive;
 exports.approximateClusteringCoefficient = require_utils.approximateClusteringCoefficient;
 exports.assertWebGPUAvailable = require_gpu.assertWebGPUAvailable;
 exports.base = base;
+exports.baseAsync = baseAsync;
 exports.batchClusteringCoefficients = require_utils.batchClusteringCoefficients;
 exports.betweenness = betweenness;
 exports.bfs = require_traversal.bfs;