graphwise 1.7.0 → 1.8.0

package/README.md

@@ -14,6 +14,7 @@ Low-dependency TypeScript graph algorithms for citation network analysis: novel
 - **Seed selection**: GRASP, Stratified
 - **Subgraph extraction**: ego-network, k-core, k-truss, motif, induced, filter
 - **Optional WebGPU acceleration**
+- **Async support**: Generator coroutine protocol, sync/async runners, all algorithms available as `*Async` variants
 
 ## Installation
 
@@ -37,7 +38,7 @@ const ranked = parse(graph, result.paths, { mi: jaccard });
 
 ### Expansion: BASE Framework
 
-**Boundary-free Adaptive Seeded Expansion** (BASE) is a parameter-free graph expansion algorithm. Given a graph $G = (V, E)$ and seed nodes $S \subseteq V$, BASE produces the subgraph induced by all vertices visited during priority-ordered expansion until frontier exhaustion:
+**Boundary-free Adaptive Seeded Expansion** (BASE) discovers the neighbourhood around seed nodes without any configuration. You provide seeds and a priority function; BASE expands outward, visiting the most interesting nodes first and recording paths when search frontiers from different seeds collide. It stops naturally when there is nothing left to explore — no depth limits, no size thresholds, no parameters to tune.
 
 $$G_S = (V_S, E_S) \quad \text{where} \quad V_S = \bigcup_{v \in S} \text{Expand}(v, \pi)$$
 
@@ -51,7 +52,7 @@ Three key properties:
 
 #### DOME: Degree-Ordered Multi-seed Expansion
 
-The default priority function uses degree-based hub deferral:
+Explores low-connectivity nodes before hubs. In a social network, DOME visits niche specialists before reaching the well-connected influencers, discovering the quiet corners of the graph before the busy crossroads.
 
 $$\pi(v) = \frac{\deg^{+}(v) + \deg^{-}(v)}{w_V(v) + \varepsilon}$$
 
@@ -81,99 +82,117 @@ where $\deg^{+}(v)$ is weighted out-degree, $\deg^{-}(v)$ is weighted in-degree,
 
 #### EDGE: Entropy-Driven Graph Expansion
 
+Finds nodes that sit at the boundary between different kinds of things. If a person's friends include scientists, artists, and engineers (high type diversity), EDGE visits them early — they are likely bridges between communities.
+
 $$\pi_{\text{EDGE}}(v) = \frac{1}{H_{\text{local}}(v) + \varepsilon} \times \log(\deg(v) + 1)$$
 
-where $H_{\text{local}}(v) = -\sum_{\tau} p(\tau) \log p(\tau)$ is the Shannon entropy of the neighbour type distribution. Nodes bridging heterogeneous structural regimes (high entropy) are explored first.
+where $H_{\text{local}}(v) = -\sum_{\tau} p(\tau) \log p(\tau)$ is the Shannon entropy of the neighbour type distribution.
 
 ---
 
 #### PIPE: Path-potential Informed Priority Expansion
 
+Rushes towards nodes that are about to connect two search frontiers. When expanding from multiple seeds, PIPE detects that a node's neighbours have already been reached by another seed's frontier — meaning a connecting path is one step away.
+
 $$\pi_{\text{PIPE}}(v) = \frac{\deg(v)}{1 + \mathrm{pathPotential}(v)}$$
 
-where $\mathrm{pathPotential}(v) = \lvert N(v) \cap \bigcup_{j \neq i} V_j \rvert$ counts neighbours already visited by other seed frontiers. High path potential indicates imminent path completion.
+where $\mathrm{pathPotential}(v) = \lvert N(v) \cap \bigcup_{j \neq i} V_j \rvert$ counts neighbours already visited by other seed frontiers.
 
 ---
 
 #### SAGE: Salience-Accumulation Guided Expansion
 
+Learns from its own discoveries. Phase 1 explores by degree (like DOME). Once the first path is found, SAGE switches to Phase 2: nodes that appear in many discovered paths get top priority, guiding expansion towards structurally rich regions.
+
 $$
 \pi_{\text{SAGE}}(v) = \begin{cases} \log(\deg(v) + 1) & \text{Phase 1 (before first path)} \\ -(\text{salience}(v) \times 1000 - \deg(v)) & \text{Phase 2 (after first path)} \end{cases}
 $$
 
-where $\text{salience}(v)$ counts discovered paths containing $v$. Salience dominates in Phase 2; degree serves as tiebreaker.
+where $\text{salience}(v)$ counts discovered paths containing $v$.
 
 ---
 
 #### REACH: Retrospective Expansion with Adaptive Convergence
 
+Uses the quality of already-discovered paths to steer future exploration. Phase 1 explores by degree. Once paths are found, REACH asks "which unexplored nodes look structurally similar to the endpoints of my best paths?" and prioritises those — seeking more of what already worked.
+
 $$
 \pi_{\text{REACH}}(v) = \begin{cases} \log(\deg(v) + 1) & \text{Phase 1} \\ \log(\deg(v) + 1) \times (1 - \widehat{\text{MI}}(v)) & \text{Phase 2} \end{cases}
 $$
 
-where $\widehat{\text{MI}}(v)$ estimates MI via Jaccard similarity to discovered path endpoints:
-
-$$
-\widehat{\text{MI}}(v) = \frac{1}{\lvert \mathcal{P}\_{\text{top}} \rvert} \sum\_{p} J(N(v), N(p\_{\text{endpoint}}))
-$$
+where $\widehat{\text{MI}}(v) = \frac{1}{\lvert \mathcal{P}\_{\text{top}} \rvert} \sum\_{p} J(N(v), N(p\_{\text{endpoint}}))$ estimates MI via Jaccard similarity to discovered path endpoints.
 
 ---
 
 #### MAZE: Multi-frontier Adaptive Zone Expansion
 
+Combines the best of PIPE and SAGE across three phases. First, it races to find initial paths using path potential (like PIPE). Then it refines exploration using salience feedback (like SAGE). Finally, it decides when to stop based on whether it's still discovering diverse, high-quality paths.
+
 $$
 \pi^{(1)}(v) = \frac{\deg(v)}{1 + \mathrm{pathPotential}(v)} \qquad \pi^{(2)}(v) = \pi^{(1)}(v) \times \frac{1}{1 + \lambda \cdot \text{salience}(v)}
 $$
 
-Phase 1 uses PIPE's path potential until $M$ paths found. Phase 2 incorporates SAGE's salience feedback. Phase 3 evaluates diversity, path count, and salience plateau for termination.
+Phase 1 uses path potential until $M$ paths found. Phase 2 adds salience feedback. Phase 3 evaluates diversity, path count, and salience plateau for termination.
 
 ---
 
 #### TIDE: Total Interconnected Degree Expansion
 
+Avoids dense clusters by looking at total neighbourhood connectivity. A node surrounded by other well-connected nodes gets deferred; a node in a quiet corner of the graph gets explored first.
+
 $$\pi_{\text{TIDE}}(v) = \deg(v) + \sum_{w \in N(v)} \deg(w)$$
 
-Nodes in sparse regions (low aggregate neighbourhood degree) are explored first. Related to EDGE but uses raw degree sums rather than entropy.
+Related to EDGE but uses raw degree sums rather than entropy.
 
 ---
 
 #### LACE: Local Affinity-Computed Expansion
 
+Explores towards nodes that are most similar to what the frontier has already seen. If a candidate node shares many neighbours with the explored region, it gets priority — building outward from a coherent core.
+
 $$\pi_{\text{LACE}}(v) = 1 - \overline{\text{MI}}(v, \text{frontier})$$
 
-Prioritises nodes by average MI to already-visited frontier nodes. Related to HAE but uses MI to visited nodes rather than type entropy.
+Related to HAE but uses MI to visited nodes rather than type entropy.
 
 ---
 
 #### WARP: Weighted Adjacent Reachability Priority
 
+Aggressively prioritises nodes that look like they will connect two search frontiers, regardless of their degree. If a node's neighbours have been visited by another seed's search, it gets top priority.
+
 $$\pi_{\text{WARP}}(v) = \frac{1}{1 + \text{bridge}(v)}$$
 
-Pure cross-frontier bridge score without degree normalisation. Related to PIPE but omits the degree numerator.
+Related to PIPE but omits the degree numerator, making it more aggressive at prioritising bridge nodes.
 
 ---
 
 #### FUSE: Fused Utility-Salience Expansion
 
+Balances two signals simultaneously: how connected a node is (degree) and how strongly it relates to the explored region (MI). The weight $w$ controls the trade-off — at $w=0$ it behaves like DOME, at $w=1$ it behaves like LACE.
+
 $$\pi_{\text{FUSE}}(v) = (1 - w) \cdot \deg(v) + w \cdot (1 - \overline{\text{MI}})$$
 
-Single-phase weighted blend of degree and MI. Related to SAGE but uses continuous blending rather than two-phase transition.
+Related to SAGE but uses continuous blending rather than two-phase transition.
 
 ---
 
 #### SIFT: Salience-Informed Frontier Threshold
 
+Acts as a gate: nodes with MI above a threshold get MI-based priority (explore the promising ones); nodes below the threshold get deferred with a large degree-based penalty (ignore the unpromising ones). A binary version of REACH's continuous approach.
+
 $$
 \pi_{\text{SIFT}}(v) = \begin{cases} 1 - \overline{\text{MI}} & \text{if } \overline{\text{MI}} \geq \tau \\ \deg(v) + 100 & \text{otherwise} \end{cases}
 $$
 
-MI-threshold-based priority with degree fallback. Related to REACH but uses a hard threshold instead of continuous MI-weighted priority.
+Related to REACH but uses a hard threshold instead of continuous MI-weighted priority.
 
 ---
 
 #### FLUX: Flexible Local Utility Crossover
 
-Density-adaptive strategy switching. Selects between DOME, EDGE, and PIPE modes per-node based on local graph density and cross-frontier bridge score. Related to MAZE but adapts spatially (per-node) rather than temporally (per-phase).
+Adapts its strategy to the local topology of each node. In dense regions it uses low-degree-first exploration (like EDGE); near frontier boundaries it uses bridge detection (like PIPE); in sparse regions it falls back to degree ordering (like DOME). Different parts of the graph are explored with different strategies simultaneously.
+
+Related to MAZE but adapts spatially (per-node) rather than temporally (per-phase).
 
 ---
 
@@ -192,73 +211,83 @@ Density-adaptive strategy switching. Selects between DOME, EDGE, and PIPE modes
 
 ### Path Ranking: PARSE
 
-**Path Aggregation Ranked by Salience Estimation** (PARSE) scores paths by the geometric mean of per-edge mutual information, eliminating length bias:
+**Path Aggregation Ranked by Salience Estimation** (PARSE) ranks discovered paths by asking "how consistently strong is every edge along this path?" It uses the geometric mean of per-edge MI scores, which means one weak link drags down the entire path — unlike arithmetic mean where a strong edge can compensate for a weak one. A 10-hop path with consistently good edges scores the same as a 2-hop path with equally good edges.
 
 $$M(P) = \exp\left( \frac{1}{k} \sum_{i=1}^{k} \log I(u_i, v_i) \right)$$
 
-where $k$ is path length (number of edges) and $I(u_i, v_i)$ is the per-edge MI score from any variant below. The geometric mean ensures a 10-hop path with consistently high-MI edges scores equally to a 2-hop path with the same average MI.
+where $k$ is path length (number of edges) and $I(u_i, v_i)$ is the per-edge MI score from any variant below.
 
 ---
 
 ### MI Variants
 
-Seven MI variants serve as per-edge estimators within PARSE. All build on Jaccard neighbourhood overlap, then weight by domain-specific structural properties.
+MI variants answer the question "how strongly are two connected nodes related?" Each measures the overlap between their neighbourhoods, then optionally weights by structural properties like density, degree rarity, clustering, or entity type. PARSE uses these as per-edge scores in its geometric mean.
 
 ---
 
 #### Jaccard (baseline)
 
-$$I_{\text{Jac}}(u, v) = \frac{|N(u) \cap N(v)|}{|N(u) \cup N(v)|}$$
+What fraction of combined neighbours do two nodes share? If Alice and Bob know 3 of the same people out of 10 total acquaintances between them, their Jaccard score is 0.3.
 
-Standard neighbourhood overlap. Default MI estimator.
+$$I_{\text{Jac}}(u, v) = \frac{|N(u) \cap N(v)|}{|N(u) \cup N(v)|}$$
 
 ---
 
 #### Adamic-Adar
 
-$$I_{\text{AA}}(u, v) = \sum_{w \in N(u) \cap N(v)} \frac{1}{\log(\deg(w) + 1)}$$
+Counts shared neighbours, but recognises that sharing a rare connection is more meaningful than sharing a popular one. If two researchers both cite a niche paper, that says more about their relationship than both citing a famous textbook.
 
-Downweights common neighbours with high degree. Shared hub neighbours are less informative than shared rare neighbours.
+$$I_{\text{AA}}(u, v) = \sum_{w \in N(u) \cap N(v)} \frac{1}{\log(\deg(w) + 1)}$$
 
 ---
 
 #### SCALE: Structural Correction via Adjusted Local Estimation
 
+Adjusts for graph density. In a dense network where everyone knows everyone, sharing neighbours is expected and less meaningful. In a sparse network, the same overlap is rare and significant. SCALE divides Jaccard by density to make scores comparable across differently-dense regions.
+
 $$I_{\text{SCALE}}(u, v) = \frac{J(N(u), N(v))}{\rho(G)}$$
 
-where $\rho(G) = \frac{2|E|}{|V|(|V|-1)}$ is graph density. Normalises Jaccard by density so that overlap in dense subgraphs is not artificially inflated.
+where $\rho(G) = \frac{2|E|}{|V|(|V|-1)}$ is graph density.
 
 ---
 
 #### SKEW: Sparse-weighted Knowledge Emphasis Weighting
 
+Rewards edges between rare (low-degree) nodes and penalises edges involving hubs. Like TF-IDF in search engines: a connection between two niche nodes is more informative than a connection between two mega-hubs that connect to everything.
+
 $$I_{\text{SKEW}}(u, v) = J(N(u), N(v)) \cdot \log\!\left(\frac{N}{\deg(u) + 1}\right) \cdot \log\!\left(\frac{N}{\deg(v) + 1}\right)$$
 
-where $N = |V|$. IDF-style rarity weighting on both endpoints. Paths through low-degree (rare) nodes score higher; paths through hubs score lower.
+where $N = |V|$.
 
 ---
 
 #### SPAN: Spanning-community Penalty for Adjacent Nodes
 
+Rewards edges that bridge separate communities and penalises edges within tight-knit groups. If both endpoints sit in dense clusters where everyone knows everyone (high clustering coefficient), the edge is probably redundant. If at least one endpoint is a bridge between groups, the edge is structurally interesting.
+
 $$I_{\text{SPAN}}(u, v) = J(N(u), N(v)) \cdot \bigl(1 - \max(C(u), C(v))\bigr)$$
 
-where $C(v)$ is the local clustering coefficient. Penalises edges within tight clusters; rewards edges bridging communities (structural holes).
+where $C(v)$ is the local clustering coefficient.
 
 ---
 
 #### ETCH: Edge Type Contrast Heuristic
 
+Boosts edges of rare types. If a graph has 1000 "knows" edges but only 5 "mentors" edges, a mentoring relationship is worth more than an acquaintanceship. ETCH multiplies Jaccard by the log-rarity of the edge type.
+
 $$I_{\text{ETCH}}(u, v) = J(N(u), N(v)) \cdot \log\!\left(\frac{|E|}{\text{count}(\text{edges with type}(u,v))}\right)$$
 
-Weights Jaccard by edge-type rarity. Paths traversing rare edge types receive higher scores. Requires edge-type annotations; falls back to Jaccard when unavailable.
+Requires edge-type annotations; falls back to Jaccard when unavailable.
 
 ---
 
 #### NOTCH: Node Type Contrast Heuristic
 
+Boosts edges connecting rare node types. In a graph with 500 people but only 10 organisations, an edge involving an organisation is more distinctive. NOTCH multiplies Jaccard by the log-rarity of both endpoint types.
+
 $$I_{\text{NOTCH}}(u, v) = J(N(u), N(v)) \cdot \log\!\left(\frac{|V|}{c(\tau_u)}\right) \cdot \log\!\left(\frac{|V|}{c(\tau_v)}\right)$$
 
-where $c(\tau_u)$ is the count of nodes with the same type as $u$. Weights Jaccard by node-type rarity for both endpoints.
+where $c(\tau_u)$ is the count of nodes with the same type as $u$.
 
 ---
 
@@ -296,7 +325,7 @@ where $c(\tau_u)$ is the count of nodes with the same type as $u$. Weights Jacca
 
 ### Seed Selection: GRASP
 
-**Graph-agnostic Representative seed pAir Sampling**: selects structurally representative seed pairs from an unknown graph using reservoir sampling and structural feature clustering. Operates blind: no full graph loading, no ground-truth labels, no human-defined strata.
+**Graph-agnostic Representative seed pAir Sampling** picks starting points for expansion algorithms. Given a graph you have never seen before, GRASP streams through its edges, samples a representative set of nodes, clusters them by structural role (hubs, bridges, peripherals), and returns seed pairs that cover the full range of structural diversity — without loading the entire graph into memory.
 
 Three phases:
 
@@ -323,6 +352,28 @@ import { ... } from 'graphwise/extraction'; // Subgraph extraction
 import { ... } from 'graphwise/utils';      // Utilities
 import { ... } from 'graphwise/gpu';        // WebGPU acceleration
 import { ... } from 'graphwise/schemas';    // Zod schemas
+import { ... } from 'graphwise/async';      // Async runners & protocol
+```
+
+### Async Usage
+
+All algorithms are available as `*Async` variants for use with remote or lazy graph data sources:
+
+```typescript
+import { domeAsync, parseAsync, jaccardAsync } from "graphwise";
+import type { AsyncReadableGraph } from "graphwise/graph";
+
+// Your async graph implementation
+const remoteGraph: AsyncReadableGraph = createRemoteGraph();
+
+const result = await domeAsync(remoteGraph, seeds, {
+    signal: controller.signal,
+    onProgress: (stats) => console.log(stats),
+});
+
+const ranked = await parseAsync(remoteGraph, result.paths, {
+    mi: jaccardAsync,
+});
 ```
 
 ## Commands

package/dist/async/index.cjs

@@ -0,0 +1,243 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#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" };
+	}
+}
+/**
+* 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;
+}
+function* opGetNode(id) {
+	const response = yield {
+		tag: "getNode",
+		id
+	};
+	if (response.tag !== "getNode") throw new TypeError(`Expected getNode response, got ${response.tag}`);
+	return response.value;
+}
+function* opGetEdge(source, target) {
+	const response = yield {
+		tag: "getEdge",
+		source,
+		target
+	};
+	if (response.tag !== "getEdge") throw new TypeError(`Expected getEdge response, got ${response.tag}`);
+	return response.value;
+}
+function* opHasNode(id) {
+	const response = yield {
+		tag: "hasNode",
+		id
+	};
+	if (response.tag !== "hasNode") throw new TypeError(`Expected hasNode response, got ${response.tag}`);
+	return response.value;
+}
+function* opYield() {
+	yield { tag: "yield" };
+}
+function* opProgress(stats) {
+	yield {
+		tag: "progress",
+		stats
+	};
+}
+//#endregion
+exports.collectAsyncIterable = collectAsyncIterable;
+exports.defaultYieldStrategy = defaultYieldStrategy;
+exports.opDegree = opDegree;
+exports.opGetEdge = opGetEdge;
+exports.opGetNode = opGetNode;
+exports.opHasNode = opHasNode;
+exports.opNeighbours = opNeighbours;
+exports.opProgress = opProgress;
+exports.opYield = opYield;
+exports.resolveAsyncOp = resolveAsyncOp;
+exports.resolveSyncOp = resolveSyncOp;
+exports.runAsync = runAsync;
+exports.runSync = runSync;
+
+//# sourceMappingURL=index.cjs.map

package/dist/async/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":[],"sources":["../../src/async/utils.ts","../../src/async/runners.ts","../../src/async/ops.ts"],"sourcesContent":["/**\n * Async utility functions.\n *\n * @module async/utils\n */\n\n/** Collect an AsyncIterable into a readonly array. */\nexport async function collectAsyncIterable<T>(\n\titer: AsyncIterable<T>,\n): Promise<readonly T[]> {\n\tconst result: T[] = [];\n\tfor await (const item of iter) result.push(item);\n\treturn result;\n}\n\n/** Default yield strategy: setTimeout(0) to yield to the event loop. */\nexport function defaultYieldStrategy(): Promise<void> {\n\treturn new Promise((r) => {\n\t\tsetTimeout(r, 0);\n\t});\n}\n","/**\n * Sync and async runners for generator-based graph algorithms.\n *\n * The runner drives a generator that yields GraphOp objects, resolves each op\n * against the graph, and feeds the result back via gen.next(response). This\n * allows algorithm logic to be written once as a generator and executed\n * synchronously or asynchronously depending on the graph backing.\n *\n * @module async/runners\n */\n\nimport type { NodeData, EdgeData, ReadableGraph } from \"../graph\";\nimport type { AsyncReadableGraph } from \"../graph/async-interfaces\";\nimport type { GraphOp, GraphOpResponse } from \"./protocol\";\nimport type { AsyncRunnerOptions } from \"./types\";\nimport { collectAsyncIterable, defaultYieldStrategy } from \"./utils\";\n\n// ---------------------------------------------------------------------------\n// Sync runner\n// ---------------------------------------------------------------------------\n\n/**\n * Resolve a single GraphOp against a synchronous ReadableGraph.\n *\n * Returns a tagged GraphOpResponse so the receiving generator can narrow\n * the result type without type assertions.\n *\n * @param graph - The synchronous graph to query\n * @param op - The operation to resolve\n * @returns The tagged response\n */\nexport function resolveSyncOp<N extends NodeData, E extends EdgeData>(\n\tgraph: ReadableGraph<N, E>,\n\top: GraphOp,\n): GraphOpResponse<N, E> {\n\tswitch (op.tag) {\n\t\tcase \"neighbours\":\n\t\t\treturn {\n\t\t\t\ttag: \"neighbours\",\n\t\t\t\tvalue: Array.from(graph.neighbours(op.id, op.direction)),\n\t\t\t};\n\t\tcase \"degree\":\n\t\t\treturn { tag: \"degree\", value: graph.degree(op.id, op.direction) };\n\t\tcase \"getNode\":\n\t\t\treturn { tag: \"getNode\", value: graph.getNode(op.id) };\n\t\tcase \"getEdge\":\n\t\t\treturn { tag: \"getEdge\", value: graph.getEdge(op.source, op.target) };\n\t\tcase \"hasNode\":\n\t\t\treturn { tag: \"hasNode\", value: graph.hasNode(op.id) };\n\t\tcase \"yield\":\n\t\t\treturn { tag: \"yield\" };\n\t\tcase \"progress\":\n\t\t\treturn { tag: \"progress\" };\n\t}\n}\n\n/**\n * Drive a generator to completion using a synchronous graph.\n *\n * The generator yields GraphOp requests; each is resolved immediately\n * against the graph and the tagged response is fed back via gen.next().\n *\n * @param gen - The generator to drive\n * @param graph - The graph to resolve ops against\n * @returns The generator's return value\n */\nexport function runSync<N extends NodeData, E extends EdgeData, R>(\n\tgen: Generator<GraphOp, R, GraphOpResponse<N, E>>,\n\tgraph: ReadableGraph<N, E>,\n): R {\n\tlet step = gen.next();\n\twhile (step.done !== true) {\n\t\tconst response = resolveSyncOp(graph, step.value);\n\t\tstep = gen.next(response);\n\t}\n\treturn step.value;\n}\n\n// ---------------------------------------------------------------------------\n// Async runner\n// ---------------------------------------------------------------------------\n\n/**\n * Resolve a single GraphOp against an async ReadableGraph.\n *\n * AsyncIterables (neighbours) are collected into readonly arrays so the\n * generator receives the same value type as in sync mode. Returns a tagged\n * GraphOpResponse for type-safe narrowing without assertions.\n *\n * @param graph - The async graph to query\n * @param op - The operation to resolve\n * @returns A promise resolving to the tagged response\n */\nexport async function resolveAsyncOp<N extends NodeData, E extends EdgeData>(\n\tgraph: AsyncReadableGraph<N, E>,\n\top: GraphOp,\n): Promise<GraphOpResponse<N, E>> {\n\tswitch (op.tag) {\n\t\tcase \"neighbours\":\n\t\t\treturn {\n\t\t\t\ttag: \"neighbours\",\n\t\t\t\tvalue: await collectAsyncIterable(\n\t\t\t\t\tgraph.neighbours(op.id, op.direction),\n\t\t\t\t),\n\t\t\t};\n\t\tcase \"degree\":\n\t\t\treturn { tag: \"degree\", value: await graph.degree(op.id, op.direction) };\n\t\tcase \"getNode\":\n\t\t\treturn { tag: \"getNode\", value: await graph.getNode(op.id) };\n\t\tcase \"getEdge\":\n\t\t\treturn {\n\t\t\t\ttag: \"getEdge\",\n\t\t\t\tvalue: await graph.getEdge(op.source, op.target),\n\t\t\t};\n\t\tcase \"hasNode\":\n\t\t\treturn { tag: \"hasNode\", value: await graph.hasNode(op.id) };\n\t\tcase \"yield\":\n\t\t\treturn { tag: \"yield\" };\n\t\tcase \"progress\":\n\t\t\treturn { tag: \"progress\" };\n\t}\n}\n\n/**\n * Drive a generator to completion using an async graph.\n *\n * Extends sync semantics with:\n * - Cancellation via AbortSignal (throws DOMException \"AbortError\")\n * - Cooperative yielding at `yield` ops (calls yieldStrategy)\n * - Progress callbacks at `progress` ops (may be async for backpressure)\n * - Error propagation: graph errors are forwarded via gen.throw(); if the\n *   generator does not handle them, they propagate to the caller\n *\n * @param gen - The generator to drive\n * @param graph - The async graph to resolve ops against\n * @param options - Runner configuration\n * @returns A promise resolving to the generator's return value\n */\nexport async function runAsync<N extends NodeData, E extends EdgeData, R>(\n\tgen: Generator<GraphOp, R, GraphOpResponse<N, E>>,\n\tgraph: AsyncReadableGraph<N, E>,\n\toptions?: AsyncRunnerOptions,\n): Promise<R> {\n\tconst signal = options?.signal;\n\tconst onProgress = options?.onProgress;\n\tconst yieldStrategy = options?.yieldStrategy ?? defaultYieldStrategy;\n\n\tlet step = gen.next();\n\n\twhile (step.done !== true) {\n\t\t// Check for cancellation before processing each op. Throw the error\n\t\t// into the generator so that any finally blocks in the algorithm run\n\t\t// before the error propagates to the caller.\n\t\tif (signal?.aborted === true) {\n\t\t\tconst abortError = new DOMException(\"Aborted\", \"AbortError\");\n\t\t\ttry {\n\t\t\t\tgen.throw(abortError);\n\t\t\t} catch {\n\t\t\t\t// Generator did not handle the error — propagate it\n\t\t\t\tthrow abortError;\n\t\t\t}\n\t\t\t// Generator handled the error but we still honour cancellation\n\t\t\tthrow abortError;\n\t\t}\n\n\t\tconst op = step.value;\n\n\t\t// Handle cooperative yield ops without hitting the graph\n\t\tif (op.tag === \"yield\") {\n\t\t\tawait yieldStrategy();\n\t\t\tstep = gen.next({ tag: \"yield\" });\n\t\t\tcontinue;\n\t\t}\n\n\t\t// Handle progress ops: call the callback (awaiting if async)\n\t\tif (op.tag === \"progress\") {\n\t\t\tif (onProgress !== undefined) {\n\t\t\t\tconst maybePromise = onProgress(op.stats);\n\t\t\t\tif (maybePromise instanceof Promise) {\n\t\t\t\t\tawait maybePromise;\n\t\t\t\t}\n\t\t\t}\n\t\t\tstep = gen.next({ tag: \"progress\" });\n\t\t\tcontinue;\n\t\t}\n\n\t\t// Resolve graph ops, forwarding any errors into the generator\n\t\tlet response: GraphOpResponse<N, E>;\n\t\ttry {\n\t\t\tresponse = await resolveAsyncOp(graph, op);\n\t\t} catch (error) {\n\t\t\t// Forward the error into the generator; if unhandled, it propagates\n\t\t\tstep = gen.throw(error);\n\t\t\tcontinue;\n\t\t}\n\n\t\tstep = gen.next(response);\n\t}\n\n\treturn step.value;\n}\n","/**\n * Type-safe yield helpers for graph operations.\n *\n * Each function is a sub-generator that yields one GraphOp and returns\n * the correctly-typed result. Narrowing is done via the tagged discriminated\n * union in GraphOpResponse — no type assertions needed.\n *\n * Use with `yield*` inside algorithm generators.\n *\n * @module async/ops\n */\n\nimport type { NodeId, NodeData, EdgeData, Direction } from \"../graph\";\nimport type { GraphOp, GraphOpResponse, ProgressStats } from \"./protocol\";\n\nexport function* opNeighbours<\n\tN extends NodeData = NodeData,\n\tE extends EdgeData = EdgeData,\n>(\n\tid: NodeId,\n\tdirection?: Direction,\n): Generator<GraphOp, readonly NodeId[], GraphOpResponse<N, E>> {\n\tconst op: GraphOp =\n\t\tdirection !== undefined\n\t\t\t? { tag: \"neighbours\", id, direction }\n\t\t\t: { tag: \"neighbours\", id };\n\tconst response: GraphOpResponse<N, E> = yield op;\n\tif (response.tag !== \"neighbours\") {\n\t\tthrow new TypeError(`Expected neighbours response, got ${response.tag}`);\n\t}\n\treturn response.value;\n}\n\nexport function* opDegree<\n\tN extends NodeData = NodeData,\n\tE extends EdgeData = EdgeData,\n>(\n\tid: NodeId,\n\tdirection?: Direction,\n): Generator<GraphOp, number, GraphOpResponse<N, E>> {\n\tconst op: GraphOp =\n\t\tdirection !== undefined\n\t\t\t? { tag: \"degree\", id, direction }\n\t\t\t: { tag: \"degree\", id };\n\tconst response: GraphOpResponse<N, E> = yield op;\n\tif (response.tag !== \"degree\") {\n\t\tthrow new TypeError(`Expected degree response, got ${response.tag}`);\n\t}\n\treturn response.value;\n}\n\nexport function* opGetNode<\n\tN extends NodeData = NodeData,\n\tE extends EdgeData = EdgeData,\n>(id: NodeId): Generator<GraphOp, N | undefined, GraphOpResponse<N, E>> {\n\tconst response: GraphOpResponse<N, E> = yield { tag: \"getNode\", id };\n\tif (response.tag !== \"getNode\") {\n\t\tthrow new TypeError(`Expected getNode response, got ${response.tag}`);\n\t}\n\treturn response.value;\n}\n\nexport function* opGetEdge<\n\tN extends NodeData = NodeData,\n\tE extends EdgeData = EdgeData,\n>(\n\tsource: NodeId,\n\ttarget: NodeId,\n): Generator<GraphOp, E | undefined, GraphOpResponse<N, E>> {\n\tconst response: GraphOpResponse<N, E> = yield {\n\t\ttag: \"getEdge\",\n\t\tsource,\n\t\ttarget,\n\t};\n\tif (response.tag !== \"getEdge\") {\n\t\tthrow new TypeError(`Expected getEdge response, got ${response.tag}`);\n\t}\n\treturn response.value;\n}\n\nexport function* opHasNode<\n\tN extends NodeData = NodeData,\n\tE extends EdgeData = EdgeData,\n>(id: NodeId): Generator<GraphOp, boolean, GraphOpResponse<N, E>> {\n\tconst response: GraphOpResponse<N, E> = yield { tag: \"hasNode\", id };\n\tif (response.tag !== \"hasNode\") {\n\t\tthrow new TypeError(`Expected hasNode response, got ${response.tag}`);\n\t}\n\treturn response.value;\n}\n\nexport function* opYield<\n\tN extends NodeData = NodeData,\n\tE extends EdgeData = EdgeData,\n>(): Generator<GraphOp, void, GraphOpResponse<N, E>> {\n\tyield { tag: \"yield\" };\n}\n\nexport function* opProgress<\n\tN extends NodeData = NodeData,\n\tE extends EdgeData = EdgeData,\n>(stats: ProgressStats): Generator<GraphOp, void, GraphOpResponse<N, E>> {\n\tyield { tag: \"progress\", stats };\n}\n"],"mappings":";;;;;;;;AAOA,eAAsB,qBACrB,MACwB;CACxB,MAAM,SAAc,EAAE;AACtB,YAAW,MAAM,QAAQ,KAAM,QAAO,KAAK,KAAK;AAChD,QAAO;;;AAIR,SAAgB,uBAAsC;AACrD,QAAO,IAAI,SAAS,MAAM;AACzB,aAAW,GAAG,EAAE;GACf;;;;;;;;;;;;;;ACYH,SAAgB,cACf,OACA,IACwB;AACxB,SAAQ,GAAG,KAAX;EACC,KAAK,aACJ,QAAO;GACN,KAAK;GACL,OAAO,MAAM,KAAK,MAAM,WAAW,GAAG,IAAI,GAAG,UAAU,CAAC;GACxD;EACF,KAAK,SACJ,QAAO;GAAE,KAAK;GAAU,OAAO,MAAM,OAAO,GAAG,IAAI,GAAG,UAAU;GAAE;EACnE,KAAK,UACJ,QAAO;GAAE,KAAK;GAAW,OAAO,MAAM,QAAQ,GAAG,GAAG;GAAE;EACvD,KAAK,UACJ,QAAO;GAAE,KAAK;GAAW,OAAO,MAAM,QAAQ,GAAG,QAAQ,GAAG,OAAO;GAAE;EACtE,KAAK,UACJ,QAAO;GAAE,KAAK;GAAW,OAAO,MAAM,QAAQ,GAAG,GAAG;GAAE;EACvD,KAAK,QACJ,QAAO,EAAE,KAAK,SAAS;EACxB,KAAK,WACJ,QAAO,EAAE,KAAK,YAAY;;;;;;;;;;;;;AAc7B,SAAgB,QACf,KACA,OACI;CACJ,IAAI,OAAO,IAAI,MAAM;AACrB,QAAO,KAAK,SAAS,MAAM;EAC1B,MAAM,WAAW,cAAc,OAAO,KAAK,MAAM;AACjD,SAAO,IAAI,KAAK,SAAS;;AAE1B,QAAO,KAAK;;;;;;;;;;;;;AAkBb,eAAsB,eACrB,OACA,IACiC;AACjC,SAAQ,GAAG,KAAX;EACC,KAAK,aACJ,QAAO;GACN,KAAK;GACL,OAAO,MAAM,qBACZ,MAAM,WAAW,GAAG,IAAI,GAAG,UAAU,CACrC;GACD;EACF,KAAK,SACJ,QAAO;GAAE,KAAK;GAAU,OAAO,MAAM,MAAM,OAAO,GAAG,IAAI,GAAG,UAAU;GAAE;EACzE,KAAK,UACJ,QAAO;GAAE,KAAK;GAAW,OAAO,MAAM,MAAM,QAAQ,GAAG,GAAG;GAAE;EAC7D,KAAK,UACJ,QAAO;GACN,KAAK;GACL,OAAO,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,OAAO;GAChD;EACF,KAAK,UACJ,QAAO;GAAE,KAAK;GAAW,OAAO,MAAM,MAAM,QAAQ,GAAG,GAAG;GAAE;EAC7D,KAAK,QACJ,QAAO,EAAE,KAAK,SAAS;EACxB,KAAK,WACJ,QAAO,EAAE,KAAK,YAAY;;;;;;;;;;;;;;;;;;AAmB7B,eAAsB,SACrB,KACA,OACA,SACa;CACb,MAAM,SAAS,SAAS;CACxB,MAAM,aAAa,SAAS;CAC5B,MAAM,gBAAgB,SAAS,iBAAiB;CAEhD,IAAI,OAAO,IAAI,MAAM;AAErB,QAAO,KAAK,SAAS,MAAM;AAI1B,MAAI,QAAQ,YAAY,MAAM;GAC7B,MAAM,aAAa,IAAI,aAAa,WAAW,aAAa;AAC5D,OAAI;AACH,QAAI,MAAM,WAAW;WACd;AAEP,UAAM;;AAGP,SAAM;;EAGP,MAAM,KAAK,KAAK;AAGhB,MAAI,GAAG,QAAQ,SAAS;AACvB,SAAM,eAAe;AACrB,UAAO,IAAI,KAAK,EAAE,KAAK,SAAS,CAAC;AACjC;;AAID,MAAI,GAAG,QAAQ,YAAY;AAC1B,OAAI,eAAe,KAAA,GAAW;IAC7B,MAAM,eAAe,WAAW,GAAG,MAAM;AACzC,QAAI,wBAAwB,QAC3B,OAAM;;AAGR,UAAO,IAAI,KAAK,EAAE,KAAK,YAAY,CAAC;AACpC;;EAID,IAAI;AACJ,MAAI;AACH,cAAW,MAAM,eAAe,OAAO,GAAG;WAClC,OAAO;AAEf,UAAO,IAAI,MAAM,MAAM;AACvB;;AAGD,SAAO,IAAI,KAAK,SAAS;;AAG1B,QAAO,KAAK;;;;ACxLb,UAAiB,aAIhB,IACA,WAC+D;CAK/D,MAAM,WAAkC,MAHvC,cAAc,KAAA,IACX;EAAE,KAAK;EAAc;EAAI;EAAW,GACpC;EAAE,KAAK;EAAc;EAAI;AAE7B,KAAI,SAAS,QAAQ,aACpB,OAAM,IAAI,UAAU,qCAAqC,SAAS,MAAM;AAEzE,QAAO,SAAS;;AAGjB,UAAiB,SAIhB,IACA,WACoD;CAKpD,MAAM,WAAkC,MAHvC,cAAc,KAAA,IACX;EAAE,KAAK;EAAU;EAAI;EAAW,GAChC;EAAE,KAAK;EAAU;EAAI;AAEzB,KAAI,SAAS,QAAQ,SACpB,OAAM,IAAI,UAAU,iCAAiC,SAAS,MAAM;AAErE,QAAO,SAAS;;AAGjB,UAAiB,UAGf,IAAsE;CACvE,MAAM,WAAkC,MAAM;EAAE,KAAK;EAAW;EAAI;AACpE,KAAI,SAAS,QAAQ,UACpB,OAAM,IAAI,UAAU,kCAAkC,SAAS,MAAM;AAEtE,QAAO,SAAS;;AAGjB,UAAiB,UAIhB,QACA,QAC2D;CAC3D,MAAM,WAAkC,MAAM;EAC7C,KAAK;EACL;EACA;EACA;AACD,KAAI,SAAS,QAAQ,UACpB,OAAM,IAAI,UAAU,kCAAkC,SAAS,MAAM;AAEtE,QAAO,SAAS;;AAGjB,UAAiB,UAGf,IAAgE;CACjE,MAAM,WAAkC,MAAM;EAAE,KAAK;EAAW;EAAI;AACpE,KAAI,SAAS,QAAQ,UACpB,OAAM,IAAI,UAAU,kCAAkC,SAAS,MAAM;AAEtE,QAAO,SAAS;;AAGjB,UAAiB,UAGoC;AACpD,OAAM,EAAE,KAAK,SAAS;;AAGvB,UAAiB,WAGf,OAAuE;AACxE,OAAM;EAAE,KAAK;EAAY;EAAO"}