effect 4.0.0-beta.66 → 4.0.0-beta.67

package/dist/Graph.js

@@ -1,4 +1,54 @@
 /**
+ * The `Graph` module provides immutable and scoped-mutable graph data
+ * structures for modeling relationships between indexed nodes and edges. A
+ * graph can be directed or undirected, stores user-defined data on both nodes
+ * and edges, and exposes traversal, analysis, path finding, transformation, and
+ * diagram export utilities.
+ *
+ * **Mental model**
+ *
+ * - Nodes and edges are addressed by stable numeric indices: {@link NodeIndex}
+ *   and {@link EdgeIndex}
+ * - Node data has type `N`; edge data has type `E`
+ * - {@link Graph} values are immutable snapshots; use {@link MutableGraph}
+ *   through {@link mutate}, {@link beginMutation}, or constructor callbacks to
+ *   add, remove, or update nodes and edges
+ * - Directed graphs follow edge direction for neighbors and traversals, while
+ *   undirected graphs treat each edge as connecting both endpoints
+ * - Missing lookups return `Option`, while structurally invalid operations such
+ *   as adding an edge to a missing node throw {@link GraphError}
+ *
+ * **Common tasks**
+ *
+ * - Create graphs: {@link directed}, {@link undirected}
+ * - Mutate safely: {@link mutate}, {@link addNode}, {@link addEdge},
+ *   {@link removeNode}, {@link removeEdge}
+ * - Query contents: {@link getNode}, {@link getEdge}, {@link hasNode},
+ *   {@link hasEdge}, {@link nodeCount}, {@link edgeCount}, {@link neighbors}
+ * - Transform data: {@link updateNode}, {@link updateEdge}, {@link mapNodes},
+ *   {@link mapEdges}, {@link filterNodes}, {@link filterEdges},
+ *   {@link filterMapNodes}, {@link filterMapEdges}
+ * - Traverse lazily: {@link dfs}, {@link bfs}, {@link topo},
+ *   {@link dfsPostOrder}, {@link nodes}, {@link edges}, {@link Walker}
+ * - Analyze structure: {@link isAcyclic}, {@link isBipartite},
+ *   {@link connectedComponents}, {@link stronglyConnectedComponents},
+ *   {@link externals}
+ * - Find paths: {@link dijkstra}, {@link astar}, {@link bellmanFord},
+ *   {@link floydWarshall}
+ * - Export diagrams: {@link toGraphViz}, {@link toMermaid}
+ *
+ * **Gotchas**
+ *
+ * - Only mutable graphs can be changed. Create one with {@link mutate} or by
+ *   passing a callback to {@link directed} / {@link undirected}.
+ * - Traversal APIs return lazy {@link Walker} values. Use {@link indices},
+ *   {@link values}, or {@link entries} to choose what each iteration yields.
+ * - `NodeIndex` and `EdgeIndex` values are identifiers, not array offsets. They
+ *   are not reused after removals.
+ * - Shortest-path algorithms require a cost function. {@link dijkstra} and
+ *   {@link astar} reject negative weights; use {@link bellmanFord} or
+ *   {@link floydWarshall} when negative weights are part of the model.
+ *
  * @since 4.0.0
  */
 import * as Data from "./Data.js";
@@ -13,8 +63,8 @@ const TypeId = "~effect/collections/Graph";
 /**
  * Edge data containing source, target, and user data.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export class Edge extends Data.Class {}
 // =============================================================================
@@ -91,8 +141,12 @@ const ProtoGraph = {
 // =============================================================================
 // TODO: Do we need safe variants for these?
 /**
- * @since 4.0.0
+ * Error thrown by graph operations when the requested graph structure is
+ * invalid, such as referencing a missing node or using unsupported edge
+ * weights.
+ *
  * @category errors
+ * @since 4.0.0
  */
 export class GraphError extends /*#__PURE__*/Data.TaggedError("GraphError") {}
 /** @internal */
@@ -103,14 +157,18 @@ const missingNode = node => new GraphError({
 // Constructors
 // =============================================================================
 /**
- * @since 4.0.0
+ * Returns `true` if a value has the graph runtime type identifier, narrowing
+ * it to a `Graph`.
+ *
  * @category Guards
+ * @since 4.0.0
  */
 export const isGraph = u => hasProperty(u, TypeId);
 /**
  * Creates a directed graph, optionally with initial mutations.
  *
- * @example
+ * **Example** (Creating a directed graph)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -124,8 +182,8 @@ export const isGraph = u => hasProperty(u, TypeId);
  * })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const directed = mutate => {
   const graph = Object.create(ProtoGraph);
@@ -148,7 +206,8 @@ export const directed = mutate => {
 /**
  * Creates an undirected graph, optionally with initial mutations.
  *
- * @example
+ * **Example** (Creating an undirected graph)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -162,8 +221,8 @@ export const directed = mutate => {
  * })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const undirected = mutate => {
   const graph = Object.create(ProtoGraph);
@@ -189,7 +248,8 @@ export const undirected = mutate => {
 /**
  * Creates a mutable scope for safe graph mutations by copying the data structure.
  *
- * @example
+ * **Example** (Beginning a mutation scope)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -198,8 +258,8 @@ export const undirected = mutate => {
  * // Now mutable can be safely modified without affecting original graph
  * ```
  *
- * @since 4.0.0
  * @category mutations
+ * @since 4.0.0
  */
 export const beginMutation = graph => {
   // Copy adjacency maps with deep cloned arrays
@@ -226,7 +286,8 @@ export const beginMutation = graph => {
 /**
  * Converts a mutable graph back to an immutable graph, ending the mutation scope.
  *
- * @example
+ * **Example** (Ending a mutation scope)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -236,8 +297,8 @@ export const beginMutation = graph => {
  * const newGraph = Graph.endMutation(mutable)
  * ```
  *
- * @since 4.0.0
  * @category mutations
+ * @since 4.0.0
  */
 export const endMutation = mutable => {
   const graph = Object.create(ProtoGraph);
@@ -255,19 +316,24 @@ export const endMutation = mutable => {
 /**
  * Performs scoped mutations on a graph, automatically managing the mutation lifecycle.
  *
- * @example
+ * **Example** (Applying scoped mutations)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
  * const graph = Graph.directed<string, number>()
  * const newGraph = Graph.mutate(graph, (mutable) => {
- *   // Safe mutations go here
- *   // mutable gets automatically converted back to immutable
+ *   const nodeA = Graph.addNode(mutable, "A")
+ *   const nodeB = Graph.addNode(mutable, "B")
+ *   Graph.addEdge(mutable, nodeA, nodeB, 1)
  * })
+ *
+ * console.log(Graph.nodeCount(newGraph)) // 2
+ * console.log(Graph.edgeCount(newGraph)) // 1
  * ```
  *
- * @since 4.0.0
  * @category mutations
+ * @since 4.0.0
  */
 export const mutate = /*#__PURE__*/dual(2, (graph, f) => {
   const mutable = beginMutation(graph);
@@ -280,7 +346,8 @@ export const mutate = /*#__PURE__*/dual(2, (graph, f) => {
 /**
  * Adds a new node to a mutable graph and returns its index.
  *
- * @example
+ * **Example** (Adding nodes)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -292,8 +359,8 @@ export const mutate = /*#__PURE__*/dual(2, (graph, f) => {
  * })
  * ```
  *
- * @since 4.0.0
  * @category mutations
+ * @since 4.0.0
  */
 export const addNode = (mutable, data) => {
   const nodeIndex = mutable.nextNodeIndex;
@@ -309,7 +376,8 @@ export const addNode = (mutable, data) => {
 /**
  * Gets the data associated with a node index, if it exists.
  *
- * @example
+ * **Example** (Getting node data)
+ *
  * ```ts
  * import { Graph } from "effect"
  * import * as Option from "effect/Option"
@@ -326,14 +394,15 @@ export const addNode = (mutable, data) => {
  * }
  * ```
  *
- * @since 4.0.0
  * @category getters
+ * @since 4.0.0
  */
 export const getNode = /*#__PURE__*/dual(2, (graph, nodeIndex) => graph.nodes.has(nodeIndex) ? Option.some(graph.nodes.get(nodeIndex)) : Option.none());
 /**
  * Checks if a node with the given index exists in the graph.
  *
- * @example
+ * **Example** (Checking node existence)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -350,14 +419,15 @@ export const getNode = /*#__PURE__*/dual(2, (graph, nodeIndex) => graph.nodes.ha
  * console.log(notExists) // false
  * ```
  *
- * @since 4.0.0
  * @category getters
+ * @since 4.0.0
  */
 export const hasNode = /*#__PURE__*/dual(2, (graph, nodeIndex) => graph.nodes.has(nodeIndex));
 /**
  * Returns the number of nodes in the graph.
  *
- * @example
+ * **Example** (Counting nodes)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -373,14 +443,15 @@ export const hasNode = /*#__PURE__*/dual(2, (graph, nodeIndex) => graph.nodes.ha
  * console.log(Graph.nodeCount(graphWithNodes)) // 3
  * ```
  *
- * @since 4.0.0
  * @category getters
+ * @since 4.0.0
  */
 export const nodeCount = graph => graph.nodes.size;
 /**
  * Finds the first node that matches the given predicate.
  *
- * @example
+ * **Example** (Finding the first matching node)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -397,8 +468,8 @@ export const nodeCount = graph => graph.nodes.size;
  * console.log(notFound) // Option.none()
  * ```
  *
- * @since 4.0.0
  * @category getters
+ * @since 4.0.0
  */
 export const findNode = /*#__PURE__*/dual(2, (graph, predicate) => {
   for (const [index, data] of graph.nodes) {
@@ -411,7 +482,8 @@ export const findNode = /*#__PURE__*/dual(2, (graph, predicate) => {
 /**
  * Finds all nodes that match the given predicate.
  *
- * @example
+ * **Example** (Finding matching nodes)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -428,8 +500,8 @@ export const findNode = /*#__PURE__*/dual(2, (graph, predicate) => {
  * console.log(empty) // []
  * ```
  *
- * @since 4.0.0
  * @category getters
+ * @since 4.0.0
  */
 export const findNodes = /*#__PURE__*/dual(2, (graph, predicate) => {
   const results = [];
@@ -443,7 +515,8 @@ export const findNodes = /*#__PURE__*/dual(2, (graph, predicate) => {
 /**
  * Finds the first edge that matches the given predicate.
  *
- * @example
+ * **Example** (Finding the first matching edge)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -462,8 +535,8 @@ export const findNodes = /*#__PURE__*/dual(2, (graph, predicate) => {
  * console.log(notFound) // Option.none()
  * ```
  *
- * @since 4.0.0
  * @category getters
+ * @since 4.0.0
  */
 export const findEdge = /*#__PURE__*/dual(2, (graph, predicate) => {
   for (const [edgeIndex, edgeData] of graph.edges) {
@@ -476,7 +549,8 @@ export const findEdge = /*#__PURE__*/dual(2, (graph, predicate) => {
 /**
  * Finds all edges that match the given predicate.
  *
- * @example
+ * **Example** (Finding matching edges)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -496,8 +570,8 @@ export const findEdge = /*#__PURE__*/dual(2, (graph, predicate) => {
  * console.log(empty) // []
  * ```
  *
- * @since 4.0.0
  * @category getters
+ * @since 4.0.0
  */
 export const findEdges = /*#__PURE__*/dual(2, (graph, predicate) => {
   const results = [];
@@ -511,7 +585,8 @@ export const findEdges = /*#__PURE__*/dual(2, (graph, predicate) => {
 /**
  * Updates a single node's data by applying a transformation function.
  *
- * @example
+ * **Example** (Updating node data)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -525,8 +600,8 @@ export const findEdges = /*#__PURE__*/dual(2, (graph, predicate) => {
  * console.log(nodeData) // Option.some("NODE A")
  * ```
  *
- * @since 4.0.0
  * @category transformations
+ * @since 4.0.0
  */
 export const updateNode = (mutable, index, f) => {
   if (!mutable.nodes.has(index)) {
@@ -539,7 +614,8 @@ export const updateNode = (mutable, index, f) => {
 /**
  * Updates a single edge's data by applying a transformation function.
  *
- * @example
+ * **Example** (Updating edge data)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -551,11 +627,11 @@ export const updateNode = (mutable, index, f) => {
  * })
  *
  * const edgeData = Graph.getEdge(result, 0)
- * console.log(edgeData) // new Graph.Edge({ source: 0, target: 1, data: 20 })
+ * console.log(edgeData) // Option.some(new Graph.Edge({ source: 0, target: 1, data: 20 }))
  * ```
  *
- * @since 4.0.0
  * @category mutations
+ * @since 4.0.0
  */
 export const updateEdge = (mutable, edgeIndex, f) => {
   if (!mutable.edges.has(edgeIndex)) {
@@ -569,9 +645,15 @@ export const updateEdge = (mutable, edgeIndex, f) => {
   }));
 };
 /**
- * Creates a new graph with transformed node data using the provided mapping function.
+ * Transforms every node's data in a mutable graph in place using the provided
+ * mapping function.
+ *
+ * **Details**
+ *
+ * Node indices and edges are preserved; only the stored node data is replaced.
+ *
+ * **Example** (Mapping node data)
  *
- * @example
  * ```ts
  * import { Graph } from "effect"
  *
@@ -583,11 +665,11 @@ export const updateEdge = (mutable, edgeIndex, f) => {
  * })
  *
  * const nodeData = Graph.getNode(graph, 0)
- * console.log(nodeData) // new Graph.Node("NODE A")
+ * console.log(nodeData) // Option.some("NODE A")
  * ```
  *
- * @since 4.0.0
  * @category transformations
+ * @since 4.0.0
  */
 export const mapNodes = (mutable, f) => {
   // Transform existing node data in place
@@ -599,7 +681,8 @@ export const mapNodes = (mutable, f) => {
 /**
  * Transforms all edge data in a mutable graph using the provided mapping function.
  *
- * @example
+ * **Example** (Mapping edge data)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -613,11 +696,11 @@ export const mapNodes = (mutable, f) => {
  * })
  *
  * const edgeData = Graph.getEdge(graph, 0)
- * console.log(edgeData) // new Graph.Edge({ source: 0, target: 1, data: 20 })
+ * console.log(edgeData) // Option.some(new Graph.Edge({ source: 0, target: 1, data: 20 }))
  * ```
  *
- * @since 4.0.0
  * @category transformations
+ * @since 4.0.0
  */
 export const mapEdges = (mutable, f) => {
   // Transform existing edge data in place
@@ -632,7 +715,8 @@ export const mapEdges = (mutable, f) => {
 /**
  * Reverses all edge directions in a mutable graph by swapping source and target nodes.
  *
- * @example
+ * **Example** (Reversing edge directions)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -646,11 +730,11 @@ export const mapEdges = (mutable, f) => {
  * })
  *
  * const edge0 = Graph.getEdge(graph, 0)
- * console.log(edge0) // new Graph.Edge({ source: 1, target: 0, data: 1 }) - B -> A
+ * console.log(edge0) // Option.some(new Graph.Edge({ source: 1, target: 0, data: 1 }))
  * ```
  *
- * @since 4.0.0
  * @category transformations
+ * @since 4.0.0
  */
 export const reverse = mutable => {
   // Reverse all edges by swapping source and target
@@ -682,7 +766,8 @@ export const reverse = mutable => {
  * Filters and optionally transforms nodes in a mutable graph using a predicate function.
  * Nodes that return Option.none are removed along with all their connected edges.
  *
- * @example
+ * **Example** (Filtering and mapping nodes)
+ *
  * ```ts
  * import { Graph } from "effect"
  * import * as Option from "effect/Option"
@@ -705,8 +790,8 @@ export const reverse = mutable => {
  * console.log(Graph.nodeCount(graph)) // 2 (only "active" nodes remain)
  * ```
  *
- * @since 4.0.0
  * @category transformations
+ * @since 4.0.0
  */
 export const filterMapNodes = (mutable, f) => {
   const nodesToRemove = [];
@@ -730,7 +815,8 @@ export const filterMapNodes = (mutable, f) => {
  * Filters and optionally transforms edges in a mutable graph using a predicate function.
  * Edges that return Option.none are removed from the graph.
  *
- * @example
+ * **Example** (Filtering and mapping edges)
+ *
  * ```ts
  * import { Graph } from "effect"
  * import * as Option from "effect/Option"
@@ -753,8 +839,8 @@ export const filterMapNodes = (mutable, f) => {
  * console.log(Graph.edgeCount(graph)) // 2 (edges with weight 5 removed)
  * ```
  *
- * @since 4.0.0
  * @category transformations
+ * @since 4.0.0
  */
 export const filterMapEdges = (mutable, f) => {
   const edgesToRemove = [];
@@ -781,7 +867,8 @@ export const filterMapEdges = (mutable, f) => {
  * Filters nodes by removing those that don't match the predicate.
  * This function modifies the mutable graph in place.
  *
- * @example
+ * **Example** (Filtering nodes)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -798,8 +885,8 @@ export const filterMapEdges = (mutable, f) => {
  * console.log(Graph.nodeCount(graph)) // 2 (only "active" nodes remain)
  * ```
  *
- * @since 4.0.0
  * @category transformations
+ * @since 4.0.0
  */
 export const filterNodes = (mutable, predicate) => {
   const nodesToRemove = [];
@@ -818,7 +905,8 @@ export const filterNodes = (mutable, predicate) => {
  * Filters edges by removing those that don't match the predicate.
  * This function modifies the mutable graph in place.
  *
- * @example
+ * **Example** (Filtering edges)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -838,8 +926,8 @@ export const filterNodes = (mutable, predicate) => {
  * console.log(Graph.edgeCount(graph)) // 2 (edge with weight 5 removed)
  * ```
  *
- * @since 4.0.0
  * @category transformations
+ * @since 4.0.0
  */
 export const filterEdges = (mutable, predicate) => {
   const edgesToRemove = [];
@@ -877,7 +965,8 @@ const invalidateCycleFlagOnAddition = mutable => {
 /**
  * Adds a new edge to a mutable graph and returns its index.
  *
- * @example
+ * **Example** (Adding edges)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -889,8 +978,8 @@ const invalidateCycleFlagOnAddition = mutable => {
  * })
  * ```
  *
- * @since 4.0.0
  * @category mutations
+ * @since 4.0.0
  */
 export const addEdge = (mutable, source, target, data) => {
   // Validate that both nodes exist
@@ -938,7 +1027,8 @@ export const addEdge = (mutable, source, target, data) => {
 /**
  * Removes a node and all its incident edges from a mutable graph.
  *
- * @example
+ * **Example** (Removing a node)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -952,8 +1042,8 @@ export const addEdge = (mutable, source, target, data) => {
  * })
  * ```
  *
- * @since 4.0.0
  * @category mutations
+ * @since 4.0.0
  */
 export const removeNode = (mutable, nodeIndex) => {
   // Check if node exists
@@ -991,7 +1081,8 @@ export const removeNode = (mutable, nodeIndex) => {
 /**
  * Removes an edge from a mutable graph.
  *
- * @example
+ * **Example** (Removing an edge)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -1005,8 +1096,8 @@ export const removeNode = (mutable, nodeIndex) => {
  * })
  * ```
  *
- * @since 4.0.0
  * @category mutations
+ * @since 4.0.0
  */
 export const removeEdge = (mutable, edgeIndex) => {
   const wasRemoved = removeEdgeInternal(mutable, edgeIndex);
@@ -1069,7 +1160,8 @@ const removeEdgeInternal = (mutable, edgeIndex) => {
 /**
  * Gets the edge data associated with an edge index, if it exists.
  *
- * @example
+ * **Example** (Getting edge data)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -1084,19 +1176,20 @@ const removeEdgeInternal = (mutable, edgeIndex) => {
  *
  * if (edgeData._tag === "Some") {
  *   console.log(edgeData.value.data) // 42
- *   console.log(edgeData.value.source) // NodeIndex(0)
- *   console.log(edgeData.value.target) // NodeIndex(1)
+ *   console.log(edgeData.value.source) // 0
+ *   console.log(edgeData.value.target) // 1
  * }
  * ```
  *
- * @since 4.0.0
  * @category getters
+ * @since 4.0.0
  */
 export const getEdge = /*#__PURE__*/dual(2, (graph, edgeIndex) => Option.fromUndefinedOr(graph.edges.get(edgeIndex)));
 /**
  * Checks if an edge exists between two nodes in the graph.
  *
- * @example
+ * **Example** (Checking edge existence)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -1118,8 +1211,8 @@ export const getEdge = /*#__PURE__*/dual(2, (graph, edgeIndex) => Option.fromUnd
  * console.log(hasAC) // false
  * ```
  *
- * @since 4.0.0
  * @category getters
+ * @since 4.0.0
  */
 export const hasEdge = /*#__PURE__*/dual(3, (graph, source, target) => {
   const adjacencyList = graph.adjacency.get(source);
@@ -1138,7 +1231,8 @@ export const hasEdge = /*#__PURE__*/dual(3, (graph, source, target) => {
 /**
  * Returns the number of edges in the graph.
  *
- * @example
+ * **Example** (Counting edges)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -1157,14 +1251,20 @@ export const hasEdge = /*#__PURE__*/dual(3, (graph, source, target) => {
  * console.log(Graph.edgeCount(graphWithEdges)) // 3
  * ```
  *
- * @since 4.0.0
  * @category getters
+ * @since 4.0.0
  */
 export const edgeCount = graph => graph.edges.size;
 /**
- * Returns the neighboring nodes (targets of outgoing edges) for a given node.
+ * Returns the neighboring node indices for a node.
+ *
+ * **Details**
+ *
+ * For directed graphs, neighbors are the targets of outgoing edges. For
+ * undirected graphs, neighbors are the other endpoints of incident edges.
+ *
+ * **Example** (Getting outgoing neighbors)
  *
- * @example
  * ```ts
  * import { Graph } from "effect"
  *
@@ -1181,14 +1281,14 @@ export const edgeCount = graph => graph.edges.size;
  * const nodeC = 2
  *
  * const neighborsA = Graph.neighbors(graph, nodeA)
- * console.log(neighborsA) // [NodeIndex(1), NodeIndex(2)]
+ * console.log(neighborsA) // [1, 2]
  *
  * const neighborsB = Graph.neighbors(graph, nodeB)
  * console.log(neighborsB) // []
  * ```
  *
- * @since 4.0.0
  * @category getters
+ * @since 4.0.0
  */
 export const neighbors = /*#__PURE__*/dual(2, (graph, nodeIndex) => {
   // For undirected graphs, use the specialized helper that returns the other endpoint
@@ -1211,7 +1311,8 @@ export const neighbors = /*#__PURE__*/dual(2, (graph, nodeIndex) => {
 /**
  * Get neighbors of a node in a specific direction for bidirectional traversal.
  *
- * @example
+ * **Example** (Traversing directed neighbors)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -1231,8 +1332,8 @@ export const neighbors = /*#__PURE__*/dual(2, (graph, nodeIndex) => {
  * const incoming = Graph.neighborsDirected(graph, nodeB, "incoming")
  * ```
  *
- * @since 4.0.0
  * @category queries
+ * @since 4.0.0
  */
 export const neighborsDirected = /*#__PURE__*/dual(3, (graph, nodeIndex, direction) => {
   const adjacencyMap = direction === "incoming" ? graph.reverseAdjacency : graph.adjacency;
@@ -1254,7 +1355,8 @@ export const neighborsDirected = /*#__PURE__*/dual(3, (graph, nodeIndex, directi
 /**
  * Exports a graph to GraphViz DOT format for visualization.
  *
- * @example
+ * **Example** (Exporting GraphViz DOT)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -1279,8 +1381,8 @@ export const neighborsDirected = /*#__PURE__*/dual(3, (graph, nodeIndex, directi
  * // }
  * ```
  *
- * @since 4.0.0
  * @category utils
+ * @since 4.0.0
  */
 export const toGraphViz = /*#__PURE__*/dual(args => isGraph(args[0]), (graph, options) => {
   const {
@@ -1348,7 +1450,8 @@ const formatMermaidNode = (nodeId, label, shape) => {
  * structures to valid Mermaid syntax for use in documentation, web applications,
  * and visualization tools.
  *
- * @example
+ * **Example** (Exporting a directed Mermaid diagram)
+ *
  * ```ts
  * import * as Graph from "effect/Graph"
  *
@@ -1371,7 +1474,8 @@ const formatMermaidNode = (nodeId, label, shape) => {
  * //   0 -->|"2"| 2
  * ```
  *
- * @example
+ * **Example** (Exporting an undirected Mermaid diagram)
+ *
  * ```ts
  * import * as Graph from "effect/Graph"
  *
@@ -1398,7 +1502,8 @@ const formatMermaidNode = (nodeId, label, shape) => {
  * //   1 ---|"colleagues"| 2
  * ```
  *
- * @example
+ * **Example** (Customizing Mermaid node shapes)
+ *
  * ```ts
  * import * as Graph from "effect/Graph"
  *
@@ -1449,7 +1554,8 @@ const formatMermaidNode = (nodeId, label, shape) => {
  * //   2 --> 3
  * ```
  *
- * @example
+ * **Example** (Visualizing dependency graphs)
+ *
  * ```ts
  * import * as Graph from "effect/Graph"
  *
@@ -1514,8 +1620,8 @@ const formatMermaidNode = (nodeId, label, shape) => {
  * @param options - Optional configuration for the Mermaid output
  * @returns Mermaid diagram syntax as a string
  *
- * @since 4.0.0
  * @category utils
+ * @since 4.0.0
  */
 export const toMermaid = /*#__PURE__*/dual(args => isGraph(args[0]), (graph, options) => {
   // Extract and validate options with defaults
@@ -1563,7 +1669,8 @@ export const toMermaid = /*#__PURE__*/dual(args => isGraph(args[0]), (graph, opt
  * For directed graphs, any back edge creates a cycle. For undirected graphs,
  * a back edge that doesn't go to the immediate parent creates a cycle.
  *
- * @example
+ * **Example** (Checking cycles)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -1587,8 +1694,8 @@ export const toMermaid = /*#__PURE__*/dual(args => isGraph(args[0]), (graph, opt
  * console.log(Graph.isAcyclic(cyclic)) // false
  * ```
  *
- * @since 4.0.0
  * @category algorithms
+ * @since 4.0.0
  */
 export const isAcyclic = graph => {
   // Use existing cycle flag if available
@@ -1655,7 +1762,8 @@ export const isAcyclic = graph => {
  * such that no two vertices within the same set are adjacent. Uses BFS coloring
  * to determine bipartiteness.
  *
- * @example
+ * **Example** (Checking bipartite graphs)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -1683,8 +1791,8 @@ export const isAcyclic = graph => {
  * console.log(Graph.isBipartite(triangle)) // false
  * ```
  *
- * @since 4.0.0
  * @category algorithms
+ * @since 4.0.0
  */
 export const isBipartite = graph => {
   const coloring = new Map();
@@ -1750,7 +1858,8 @@ const getUndirectedNeighbors = (graph, nodeIndex) => {
  * Find connected components in an undirected graph.
  * Each component is represented as an array of node indices.
  *
- * @example
+ * **Example** (Finding connected components)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -1767,8 +1876,8 @@ const getUndirectedNeighbors = (graph, nodeIndex) => {
  * console.log(components) // [[0, 1], [2, 3]]
  * ```
  *
- * @since 4.0.0
  * @category algorithms
+ * @since 4.0.0
  */
 export const connectedComponents = graph => {
   const visited = new Set();
@@ -1801,7 +1910,8 @@ export const connectedComponents = graph => {
  * Find strongly connected components in a directed graph using Kosaraju's algorithm.
  * Each SCC is represented as an array of node indices.
  *
- * @example
+ * **Example** (Finding strongly connected components)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -1818,8 +1928,8 @@ export const connectedComponents = graph => {
  * console.log(sccs) // [[0, 1, 2]]
  * ```
  *
- * @since 4.0.0
  * @category algorithms
+ * @since 4.0.0
  */
 export const stronglyConnectedComponents = graph => {
   const visited = new Set();
@@ -1891,12 +2001,17 @@ export const stronglyConnectedComponents = graph => {
   return sccs;
 };
 /**
- * Find the shortest path between two nodes using Dijkstra's algorithm.
+ * Finds the shortest path from the configured source node to the target node
+ * using Dijkstra's algorithm.
+ *
+ * **Details**
  *
- * Dijkstra's algorithm works with non-negative edge weights and finds the shortest
- * path from a source node to a target node in O((V + E) log V) time complexity.
+ * Edge costs must be non-negative. Returns `Option.none()` when the target is
+ * not reachable, and throws a `GraphError` when either endpoint is missing or a
+ * negative edge cost is encountered.
+ *
+ * **Example** (Finding shortest paths with Dijkstra)
  *
- * @example
  * ```ts
  * import { Graph } from "effect"
  *
@@ -1921,8 +2036,8 @@ export const stronglyConnectedComponents = graph => {
  * }
  * ```
  *
- * @since 4.0.0
  * @category algorithms
+ * @since 4.0.0
  */
 export const dijkstra = /*#__PURE__*/dual(2, (graph, config) => {
   // Validate that source and target nodes exist
@@ -2037,14 +2152,17 @@ export const dijkstra = /*#__PURE__*/dual(2, (graph, config) => {
   });
 });
 /**
- * Find shortest paths between all pairs of nodes using Floyd-Warshall algorithm.
+ * Finds shortest paths between all pairs of nodes using the Floyd-Warshall
+ * algorithm.
  *
- * Floyd-Warshall algorithm computes shortest paths between all pairs of nodes in O(V³) time.
- * It can handle negative edge weights and detect negative cycles.
+ * **Details**
  *
- * Throws if a negative cycle is detected that affects the path to target.
+ * Computes distances, reconstructed node paths, and edge-data paths for every
+ * source and target pair in O(V^3) time. Negative edge weights are allowed, but
+ * a `GraphError` is thrown if any negative cycle is detected.
+ *
+ * **Example** (Finding all-pairs shortest paths)
  *
- * @example
  * ```ts
  * import { Graph } from "effect"
  *
@@ -2062,8 +2180,8 @@ export const dijkstra = /*#__PURE__*/dual(2, (graph, config) => {
  * const pathAToC = result.paths.get(0)?.get(2) // [0, 1, 2]
  * ```
  *
- * @since 4.0.0
  * @category algorithms
+ * @since 4.0.0
  */
 export const floydWarshall = /*#__PURE__*/dual(2, (graph, cost) => {
   // Get all nodes for Floyd-Warshall algorithm (needs array for nested iteration)
@@ -2159,13 +2277,18 @@ export const floydWarshall = /*#__PURE__*/dual(2, (graph, cost) => {
   };
 });
 /**
- * Find the shortest path between two nodes using A* pathfinding algorithm.
+ * Finds the shortest path from the configured source node to the target node
+ * using the A* pathfinding algorithm.
  *
- * A* is an extension of Dijkstra's algorithm that uses a heuristic function to guide
- * the search towards the target, potentially finding paths faster than Dijkstra's.
- * The heuristic must be admissible (never overestimate the actual cost).
+ * **Details**
+ *
+ * The edge-cost function must return non-negative weights, and the heuristic
+ * should be admissible to preserve shortest-path guarantees. Returns
+ * `Option.none()` when the target is not reachable, and throws a `GraphError`
+ * when either endpoint is missing or a negative edge cost is encountered.
+ *
+ * **Example** (Finding shortest paths with A-star)
  *
- * @example
  * ```ts
  * import { Graph } from "effect"
  *
@@ -2196,8 +2319,8 @@ export const floydWarshall = /*#__PURE__*/dual(2, (graph, cost) => {
  * }
  * ```
  *
- * @since 4.0.0
  * @category algorithms
+ * @since 4.0.0
  */
 export const astar = /*#__PURE__*/dual(2, (graph, config) => {
   // Validate that source and target nodes exist
@@ -2335,13 +2458,17 @@ export const astar = /*#__PURE__*/dual(2, (graph, config) => {
   });
 });
 /**
- * Find the shortest path between two nodes using Bellman-Ford algorithm.
+ * Finds the shortest path from the configured source node to the target node
+ * using the Bellman-Ford algorithm.
+ *
+ * **Details**
  *
- * Bellman-Ford algorithm can handle negative edge weights and detects negative cycles.
- * It has O(VE) time complexity, slower than Dijkstra's but more versatile.
- * Returns Option.none() if a negative cycle is detected that affects the path.
+ * Negative edge weights are allowed. Returns `Option.none()` when the target is
+ * unreachable or when a negative cycle affects the path to the target. Throws a
+ * `GraphError` when either endpoint is missing.
+ *
+ * **Example** (Finding shortest paths with Bellman-Ford)
  *
- * @example
  * ```ts
  * import { Graph } from "effect"
  *
@@ -2366,8 +2493,8 @@ export const astar = /*#__PURE__*/dual(2, (graph, config) => {
  * }
  * ```
  *
- * @since 4.0.0
  * @category algorithms
+ * @since 4.0.0
  */
 export const bellmanFord = /*#__PURE__*/dual(2, (graph, config) => {
   // Validate that source and target nodes exist
@@ -2481,13 +2608,16 @@ export const bellmanFord = /*#__PURE__*/dual(2, (graph, config) => {
   });
 });
 /**
- * Concrete class for iterables that produce [NodeIndex, NodeData] tuples.
+ * Iterable wrapper used by graph traversal and listing APIs.
  *
- * This class provides a common abstraction for all iterables that return node data,
- * including traversal iterators (DFS, BFS, etc.) and element iterators (nodes, externals).
- * It uses a mapEntry function pattern for flexible iteration and transformation.
+ * **Details**
+ *
+ * A `Walker` yields `[index, data]` pairs lazily and can be viewed as just the
+ * indices, just the values, or mapped entries with `indices`, `values`,
+ * `entries`, and `visit`.
+ *
+ * **Example** (Working with node walkers)
  *
- * @example
  * ```ts
  * import { Graph } from "effect"
  *
@@ -2511,8 +2641,8 @@ export const bellmanFord = /*#__PURE__*/dual(2, (graph, config) => {
  * const nodeEntries = Array.from(Graph.entries(allNodes)) // [[0, "A"], [1, "B"]]
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export class Walker {
   // @ts-ignore
@@ -2524,7 +2654,8 @@ export class Walker {
    * and returns an iterable of the mapped values. Skips elements that
    * no longer exist in the graph.
    *
-   * @example
+   * **Example** (Visiting walker elements)
+   *
    * ```ts
    * import { Graph } from "effect"
    *
@@ -2547,8 +2678,8 @@ export class Walker {
    * console.log(custom) // [{ id: 0, name: "A" }, { id: 1, name: "B" }]
    * ```
    *
-   * @since 4.0.0
    * @category iterators
+   * @since 4.0.0
    */
   visit;
   constructor(
@@ -2559,7 +2690,8 @@ export class Walker {
    * and returns an iterable of the mapped values. Skips elements that
    * no longer exist in the graph.
    *
-   * @example
+   * **Example** (Visiting walker elements)
+   *
    * ```ts
    * import { Graph } from "effect"
    *
@@ -2582,8 +2714,8 @@ export class Walker {
    * console.log(custom) // [{ id: 0, name: "A" }, { id: 1, name: "B" }]
    * ```
    *
-   * @since 4.0.0
    * @category iterators
+   * @since 4.0.0
    */
   visit) {
     this.visit = visit;
@@ -2593,7 +2725,8 @@ export class Walker {
 /**
  * Returns an iterator over the indices in the walker.
  *
- * @example
+ * **Example** (Iterating walker indices)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -2608,14 +2741,15 @@ export class Walker {
  * console.log(indices) // [0, 1]
  * ```
  *
- * @since 4.0.0
  * @category utilities
+ * @since 4.0.0
  */
 export const indices = walker => walker.visit((index, _) => index);
 /**
  * Returns an iterator over the values (data) in the walker.
  *
- * @example
+ * **Example** (Iterating walker values)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -2630,14 +2764,15 @@ export const indices = walker => walker.visit((index, _) => index);
  * console.log(values) // ["A", "B"]
  * ```
  *
- * @since 4.0.0
  * @category utilities
+ * @since 4.0.0
  */
 export const values = walker => walker.visit((_, data) => data);
 /**
  * Returns an iterator over [index, data] entries in the walker.
  *
- * @example
+ * **Example** (Iterating walker entries)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -2652,17 +2787,22 @@ export const values = walker => walker.visit((_, data) => data);
  * console.log(entries) // [[0, "A"], [1, "B"]]
  * ```
  *
- * @since 4.0.0
  * @category utilities
+ * @since 4.0.0
  */
 export const entries = walker => walker.visit((index, data) => [index, data]);
 /**
- * Creates a new DFS iterator with optional configuration.
+ * Creates a lazy depth-first traversal iterator from the configured start
+ * nodes.
+ *
+ * **Details**
  *
- * The iterator maintains a stack of nodes to visit and tracks discovered nodes.
- * It provides lazy evaluation of the depth-first search.
+ * If no start nodes are supplied, the iterator is empty. The `direction` option
+ * chooses whether to follow outgoing or incoming edges. Throws a `GraphError`
+ * if any configured start node does not exist.
+ *
+ * **Example** (Traversing depth-first)
  *
- * @example
  * ```ts
  * import { Graph } from "effect"
  *
@@ -2685,8 +2825,8 @@ export const entries = walker => walker.visit((index, data) => [index, data]);
  * // Can be used programmatically
  * ```
  *
- * @since 4.0.0
  * @category iterators
+ * @since 4.0.0
  */
 export const dfs = /*#__PURE__*/dual(args => isGraph(args[0]), (graph, config = {}) => {
   const start = config.start ?? [];
@@ -2736,12 +2876,17 @@ export const dfs = /*#__PURE__*/dual(args => isGraph(args[0]), (graph, config =
   }));
 });
 /**
- * Creates a new BFS iterator with optional configuration.
+ * Creates a lazy breadth-first traversal iterator from the configured start
+ * nodes.
  *
- * The iterator maintains a queue of nodes to visit and tracks discovered nodes.
- * It provides lazy evaluation of the breadth-first search.
+ * **Details**
+ *
+ * If no start nodes are supplied, the iterator is empty. The `direction` option
+ * chooses whether to follow outgoing or incoming edges. Throws a `GraphError`
+ * if any configured start node does not exist.
+ *
+ * **Example** (Traversing breadth-first)
  *
- * @example
  * ```ts
  * import { Graph } from "effect"
  *
@@ -2764,8 +2909,8 @@ export const dfs = /*#__PURE__*/dual(args => isGraph(args[0]), (graph, config =
  * // Can be used programmatically
  * ```
  *
- * @since 4.0.0
  * @category iterators
+ * @since 4.0.0
  */
 export const bfs = /*#__PURE__*/dual(args => isGraph(args[0]), (graph, config = {}) => {
   const start = config.start ?? [];
@@ -2818,7 +2963,8 @@ export const bfs = /*#__PURE__*/dual(args => isGraph(args[0]), (graph, config =
  * The iterator uses Kahn's algorithm to lazily produce nodes in topological order.
  * Throws an error if the graph contains cycles.
  *
- * @example
+ * **Example** (Sorting topologically)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -2839,7 +2985,7 @@ export const bfs = /*#__PURE__*/dual(args => isGraph(args[0]), (graph, config =
  * // With initial nodes
  * const topo2 = Graph.topo(graph, { initials: [0] })
  *
- * // Throws error for cyclic graph
+ * // Check before sorting a cyclic graph
  * const cyclicGraph = Graph.directed<string, number>((mutable) => {
  *   const a = Graph.addNode(mutable, "A")
  *   const b = Graph.addNode(mutable, "B")
@@ -2847,15 +2993,13 @@ export const bfs = /*#__PURE__*/dual(args => isGraph(args[0]), (graph, config =
  *   Graph.addEdge(mutable, b, a, 2) // Creates cycle
  * })
  *
- * try {
- *   Graph.topo(cyclicGraph) // Throws: "Cannot perform topological sort on cyclic graph"
- * } catch (error) {
- *   console.log((error as Error).message)
+ * if (!Graph.isAcyclic(cyclicGraph)) {
+ *   console.log("cyclic graph") // cyclic graph
  * }
  * ```
  *
- * @since 4.0.0
  * @category iterators
+ * @since 4.0.0
  */
 export const topo = /*#__PURE__*/dual(args => isGraph(args[0]), (graph, config = {}) => {
   // Check if graph is acyclic first
@@ -2934,13 +3078,17 @@ export const topo = /*#__PURE__*/dual(args => isGraph(args[0]), (graph, config =
   }));
 });
 /**
- * Creates a new DFS postorder iterator with optional configuration.
+ * Creates a lazy depth-first postorder traversal iterator from the configured
+ * start nodes.
+ *
+ * **Details**
+ *
+ * Nodes are emitted after their reachable descendants have been processed. If
+ * no start nodes are supplied, the iterator is empty. The `direction` option
+ * chooses whether to follow outgoing or incoming edges.
  *
- * The iterator maintains a stack with visit state tracking and emits nodes
- * in postorder (after all descendants have been processed). Essential for
- * dependency resolution and tree destruction algorithms.
+ * **Example** (Traversing in postorder)
  *
- * @example
  * ```ts
  * import { Graph } from "effect"
  *
@@ -2959,8 +3107,8 @@ export const topo = /*#__PURE__*/dual(args => isGraph(args[0]), (graph, config =
  * }
  * ```
  *
- * @since 4.0.0
  * @category iterators
+ * @since 4.0.0
  */
 export const dfsPostOrder = /*#__PURE__*/dual(args => isGraph(args[0]), (graph, config = {}) => {
   const start = config.start ?? [];
@@ -3034,7 +3182,8 @@ export const dfsPostOrder = /*#__PURE__*/dual(args => isGraph(args[0]), (graph,
  * The iterator produces node indices in the order they were added to the graph.
  * This provides access to all nodes regardless of connectivity.
  *
- * @example
+ * **Example** (Iterating all nodes)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -3049,8 +3198,8 @@ export const dfsPostOrder = /*#__PURE__*/dual(args => isGraph(args[0]), (graph,
  * console.log(indices) // [0, 1, 2]
  * ```
  *
- * @since 4.0.0
  * @category iterators
+ * @since 4.0.0
  */
 export const nodes = graph => new Walker(f => ({
   [Symbol.iterator]() {
@@ -3080,7 +3229,8 @@ export const nodes = graph => new Walker(f => ({
  * The iterator produces edge indices in the order they were added to the graph.
  * This provides access to all edges regardless of connectivity.
  *
- * @example
+ * **Example** (Iterating all edges)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -3096,8 +3246,8 @@ export const nodes = graph => new Walker(f => ({
  * console.log(indices) // [0, 1]
  * ```
  *
- * @since 4.0.0
  * @category iterators
+ * @since 4.0.0
  */
 export const edges = graph => new Walker(f => ({
   [Symbol.iterator]() {
@@ -3128,7 +3278,8 @@ export const edges = graph => new Walker(f => ({
  * no incoming edges (direction="incoming"). These are useful for finding
  * sources, sinks, or isolated nodes.
  *
- * @example
+ * **Example** (Iterating external nodes)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -3155,8 +3306,8 @@ export const edges = graph => new Walker(f => ({
  * console.log(sources) // [0, 3]
  * ```
  *
- * @since 4.0.0
  * @category iterators
+ * @since 4.0.0
  */
 export const externals = /*#__PURE__*/dual(args => isGraph(args[0]), (graph, config = {}) => {
   const direction = config.direction ?? "outgoing";