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

package/dist/Graph.d.ts

@@ -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.ts";
@@ -10,22 +60,22 @@ declare const TypeId = "~effect/collections/Graph";
 /**
  * Node index for node identification using plain numbers.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export type NodeIndex = number;
 /**
  * Edge index for edge identification using plain numbers.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export type EdgeIndex = number;
 /**
  * Edge data containing source, target, and user data.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export declare class Edge<E> extends Data.Class<{
     readonly source: NodeIndex;
@@ -36,15 +86,20 @@ export declare class Edge<E> extends Data.Class<{
 /**
  * Graph type for distinguishing directed and undirected graphs.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export type Kind = "directed" | "undirected";
 /**
- * Graph prototype interface.
+ * Common structural interface shared by immutable and mutable graphs.
+ *
+ * **Details**
+ *
+ * Contains the node and edge maps, adjacency indexes, allocation counters, and
+ * shared protocols used by both `Graph` and `MutableGraph`.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface Proto<out N, out E> extends Iterable<readonly [NodeIndex, N]>, Equal.Equal, Pipeable, Inspectable {
     readonly [TypeId]: typeof TypeId;
@@ -59,8 +114,8 @@ export interface Proto<out N, out E> extends Iterable<readonly [NodeIndex, N]>,
 /**
  * Immutable graph interface.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface Graph<out N, out E, T extends Kind = "directed"> extends Proto<N, E> {
     readonly type: T;
@@ -69,8 +124,8 @@ export interface Graph<out N, out E, T extends Kind = "directed"> extends Proto<
 /**
  * Mutable graph interface.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface MutableGraph<out N, out E, T extends Kind = "directed"> extends Proto<N, E> {
     readonly type: T;
@@ -79,51 +134,59 @@ export interface MutableGraph<out N, out E, T extends Kind = "directed"> extends
 /**
  * Directed graph type alias.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export type DirectedGraph<N, E> = Graph<N, E, "directed">;
 /**
  * Undirected graph type alias.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export type UndirectedGraph<N, E> = Graph<N, E, "undirected">;
 /**
  * Mutable directed graph type alias.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export type MutableDirectedGraph<N, E> = MutableGraph<N, E, "directed">;
 /**
  * Mutable undirected graph type alias.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export type MutableUndirectedGraph<N, E> = MutableGraph<N, E, "undirected">;
 declare const GraphError_base: new <A extends Record<string, any> = {}>(args: import("./Types.ts").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("./Cause.ts").YieldableError & {
     readonly _tag: "GraphError";
 } & Readonly<A>;
 /**
- * @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 declare class GraphError extends GraphError_base<{
     readonly message: string;
 }> {
 }
 /**
- * @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 declare const isGraph: (u: unknown) => u is Graph<unknown, unknown>;
 /**
  * Creates a directed graph, optionally with initial mutations.
  *
- * @example
+ * **Example** (Creating a directed graph)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -137,14 +200,15 @@ export declare const isGraph: (u: unknown) => u is Graph<unknown, unknown>;
  * })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const directed: <N, E>(mutate?: (mutable: MutableDirectedGraph<N, E>) => void) => DirectedGraph<N, E>;
 /**
  * Creates an undirected graph, optionally with initial mutations.
  *
- * @example
+ * **Example** (Creating an undirected graph)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -158,14 +222,15 @@ export declare const directed: <N, E>(mutate?: (mutable: MutableDirectedGraph<N,
  * })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const undirected: <N, E>(mutate?: (mutable: MutableUndirectedGraph<N, E>) => void) => UndirectedGraph<N, E>;
 /**
  * Creates a mutable scope for safe graph mutations by copying the data structure.
  *
- * @example
+ * **Example** (Beginning a mutation scope)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -174,14 +239,15 @@ export declare const undirected: <N, E>(mutate?: (mutable: MutableUndirectedGrap
  * // Now mutable can be safely modified without affecting original graph
  * ```
  *
- * @since 4.0.0
  * @category mutations
+ * @since 4.0.0
  */
 export declare const beginMutation: <N, E, T extends Kind = "directed">(graph: Graph<N, E, T>) => MutableGraph<N, E, T>;
 /**
  * Converts a mutable graph back to an immutable graph, ending the mutation scope.
  *
- * @example
+ * **Example** (Ending a mutation scope)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -191,69 +257,85 @@ export declare const beginMutation: <N, E, T extends Kind = "directed">(graph: G
  * const newGraph = Graph.endMutation(mutable)
  * ```
  *
- * @since 4.0.0
  * @category mutations
+ * @since 4.0.0
  */
 export declare const endMutation: <N, E, T extends Kind = "directed">(mutable: MutableGraph<N, E, T>) => Graph<N, E, T>;
 /**
  * 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 declare const mutate: {
     /**
      * 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
      */
     <N, E, T extends Kind = "directed">(f: (mutable: MutableGraph<N, E, T>) => void): (graph: Graph<N, E, T>) => Graph<N, E, T>;
     /**
      * 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
      */
     <N, E, T extends Kind = "directed">(graph: Graph<N, E, T>, f: (mutable: MutableGraph<N, E, T>) => void): Graph<N, E, T>;
 };
 /**
  * Adds a new node to a mutable graph and returns its index.
  *
- * @example
+ * **Example** (Adding nodes)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -265,14 +347,15 @@ export declare const mutate: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category mutations
+ * @since 4.0.0
  */
 export declare const addNode: <N, E, T extends Kind = "directed">(mutable: MutableGraph<N, E, T>, data: N) => NodeIndex;
 /**
  * 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"
@@ -289,14 +372,15 @@ export declare const addNode: <N, E, T extends Kind = "directed">(mutable: Mutab
  * }
  * ```
  *
- * @since 4.0.0
  * @category getters
+ * @since 4.0.0
  */
 export declare const getNode: {
     /**
      * 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"
@@ -313,14 +397,15 @@ export declare const getNode: {
      * }
      * ```
      *
-     * @since 4.0.0
      * @category getters
+     * @since 4.0.0
      */
     <N, E, T extends Kind = "directed">(nodeIndex: NodeIndex): (graph: Graph<N, E, T> | MutableGraph<N, E, T>) => Option.Option<N>;
     /**
      * 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"
@@ -337,15 +422,16 @@ export declare const getNode: {
      * }
      * ```
      *
-     * @since 4.0.0
      * @category getters
+     * @since 4.0.0
      */
     <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>, nodeIndex: NodeIndex): Option.Option<N>;
 };
 /**
  * Checks if a node with the given index exists in the graph.
  *
- * @example
+ * **Example** (Checking node existence)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -362,14 +448,15 @@ export declare const getNode: {
  * console.log(notExists) // false
  * ```
  *
- * @since 4.0.0
  * @category getters
+ * @since 4.0.0
  */
 export declare const hasNode: {
     /**
      * Checks if a node with the given index exists in the graph.
      *
-     * @example
+     * **Example** (Checking node existence)
+     *
      * ```ts
      * import { Graph } from "effect"
      *
@@ -386,14 +473,15 @@ export declare const hasNode: {
      * console.log(notExists) // false
      * ```
      *
-     * @since 4.0.0
      * @category getters
+     * @since 4.0.0
      */
     (nodeIndex: NodeIndex): <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => boolean;
     /**
      * Checks if a node with the given index exists in the graph.
      *
-     * @example
+     * **Example** (Checking node existence)
+     *
      * ```ts
      * import { Graph } from "effect"
      *
@@ -410,15 +498,16 @@ export declare const hasNode: {
      * console.log(notExists) // false
      * ```
      *
-     * @since 4.0.0
      * @category getters
+     * @since 4.0.0
      */
     <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>, nodeIndex: NodeIndex): boolean;
 };
 /**
  * Returns the number of nodes in the graph.
  *
- * @example
+ * **Example** (Counting nodes)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -434,14 +523,15 @@ export declare const hasNode: {
  * console.log(Graph.nodeCount(graphWithNodes)) // 3
  * ```
  *
- * @since 4.0.0
  * @category getters
+ * @since 4.0.0
  */
 export declare const nodeCount: <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => number;
 /**
  * Finds the first node that matches the given predicate.
  *
- * @example
+ * **Example** (Finding the first matching node)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -458,14 +548,15 @@ export declare const nodeCount: <N, E, T extends Kind = "directed">(graph: Graph
  * console.log(notFound) // Option.none()
  * ```
  *
- * @since 4.0.0
  * @category getters
+ * @since 4.0.0
  */
 export declare const findNode: {
     /**
      * Finds the first node that matches the given predicate.
      *
-     * @example
+     * **Example** (Finding the first matching node)
+     *
      * ```ts
      * import { Graph } from "effect"
      *
@@ -482,14 +573,15 @@ export declare const findNode: {
      * console.log(notFound) // Option.none()
      * ```
      *
-     * @since 4.0.0
      * @category getters
+     * @since 4.0.0
      */
     <N>(predicate: (data: N) => boolean): <E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => Option.Option<NodeIndex>;
     /**
      * Finds the first node that matches the given predicate.
      *
-     * @example
+     * **Example** (Finding the first matching node)
+     *
      * ```ts
      * import { Graph } from "effect"
      *
@@ -506,15 +598,16 @@ export declare const findNode: {
      * console.log(notFound) // Option.none()
      * ```
      *
-     * @since 4.0.0
      * @category getters
+     * @since 4.0.0
      */
     <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>, predicate: (data: N) => boolean): Option.Option<NodeIndex>;
 };
 /**
  * Finds all nodes that match the given predicate.
  *
- * @example
+ * **Example** (Finding matching nodes)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -531,14 +624,15 @@ export declare const findNode: {
  * console.log(empty) // []
  * ```
  *
- * @since 4.0.0
  * @category getters
+ * @since 4.0.0
  */
 export declare const findNodes: {
     /**
      * Finds all nodes that match the given predicate.
      *
-     * @example
+     * **Example** (Finding matching nodes)
+     *
      * ```ts
      * import { Graph } from "effect"
      *
@@ -555,14 +649,15 @@ export declare const findNodes: {
      * console.log(empty) // []
      * ```
      *
-     * @since 4.0.0
      * @category getters
+     * @since 4.0.0
      */
     <N>(predicate: (data: N) => boolean): <E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => Array<NodeIndex>;
     /**
      * Finds all nodes that match the given predicate.
      *
-     * @example
+     * **Example** (Finding matching nodes)
+     *
      * ```ts
      * import { Graph } from "effect"
      *
@@ -579,15 +674,16 @@ export declare const findNodes: {
      * console.log(empty) // []
      * ```
      *
-     * @since 4.0.0
      * @category getters
+     * @since 4.0.0
      */
     <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>, predicate: (data: N) => boolean): Array<NodeIndex>;
 };
 /**
  * Finds the first edge that matches the given predicate.
  *
- * @example
+ * **Example** (Finding the first matching edge)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -606,14 +702,15 @@ export declare const findNodes: {
  * console.log(notFound) // Option.none()
  * ```
  *
- * @since 4.0.0
  * @category getters
+ * @since 4.0.0
  */
 export declare const findEdge: {
     /**
      * Finds the first edge that matches the given predicate.
      *
-     * @example
+     * **Example** (Finding the first matching edge)
+     *
      * ```ts
      * import { Graph } from "effect"
      *
@@ -632,14 +729,15 @@ export declare const findEdge: {
      * console.log(notFound) // Option.none()
      * ```
      *
-     * @since 4.0.0
      * @category getters
+     * @since 4.0.0
      */
     <E>(predicate: (data: E, source: NodeIndex, target: NodeIndex) => boolean): <N, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => Option.Option<EdgeIndex>;
     /**
      * Finds the first edge that matches the given predicate.
      *
-     * @example
+     * **Example** (Finding the first matching edge)
+     *
      * ```ts
      * import { Graph } from "effect"
      *
@@ -658,15 +756,16 @@ export declare const findEdge: {
      * console.log(notFound) // Option.none()
      * ```
      *
-     * @since 4.0.0
      * @category getters
+     * @since 4.0.0
      */
     <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>, predicate: (data: E, source: NodeIndex, target: NodeIndex) => boolean): Option.Option<EdgeIndex>;
 };
 /**
  * Finds all edges that match the given predicate.
  *
- * @example
+ * **Example** (Finding matching edges)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -686,14 +785,15 @@ export declare const findEdge: {
  * console.log(empty) // []
  * ```
  *
- * @since 4.0.0
  * @category getters
+ * @since 4.0.0
  */
 export declare const findEdges: {
     /**
      * Finds all edges that match the given predicate.
      *
-     * @example
+     * **Example** (Finding matching edges)
+     *
      * ```ts
      * import { Graph } from "effect"
      *
@@ -713,14 +813,15 @@ export declare const findEdges: {
      * console.log(empty) // []
      * ```
      *
-     * @since 4.0.0
      * @category getters
+     * @since 4.0.0
      */
     <E>(predicate: (data: E, source: NodeIndex, target: NodeIndex) => boolean): <N, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => Array<EdgeIndex>;
     /**
      * Finds all edges that match the given predicate.
      *
-     * @example
+     * **Example** (Finding matching edges)
+     *
      * ```ts
      * import { Graph } from "effect"
      *
@@ -740,15 +841,16 @@ export declare const findEdges: {
      * console.log(empty) // []
      * ```
      *
-     * @since 4.0.0
      * @category getters
+     * @since 4.0.0
      */
     <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>, predicate: (data: E, source: NodeIndex, target: NodeIndex) => boolean): Array<EdgeIndex>;
 };
 /**
  * Updates a single node's data by applying a transformation function.
  *
- * @example
+ * **Example** (Updating node data)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -762,14 +864,15 @@ export declare const findEdges: {
  * console.log(nodeData) // Option.some("NODE A")
  * ```
  *
- * @since 4.0.0
  * @category transformations
+ * @since 4.0.0
  */
 export declare const updateNode: <N, E, T extends Kind = "directed">(mutable: MutableGraph<N, E, T>, index: NodeIndex, f: (data: N) => N) => void;
 /**
  * Updates a single edge's data by applying a transformation function.
  *
- * @example
+ * **Example** (Updating edge data)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -781,17 +884,23 @@ export declare const updateNode: <N, E, T extends Kind = "directed">(mutable: Mu
  * })
  *
  * 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 declare const updateEdge: <N, E, T extends Kind = "directed">(mutable: MutableGraph<N, E, T>, edgeIndex: EdgeIndex, f: (data: E) => E) => void;
 /**
- * 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"
  *
@@ -803,17 +912,18 @@ export declare const updateEdge: <N, E, T extends Kind = "directed">(mutable: Mu
  * })
  *
  * 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 declare const mapNodes: <N, E, T extends Kind = "directed">(mutable: MutableGraph<N, E, T>, f: (data: N) => N) => void;
 /**
  * Transforms all edge data in a mutable graph using the provided mapping function.
  *
- * @example
+ * **Example** (Mapping edge data)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -827,17 +937,18 @@ export declare const mapNodes: <N, E, T extends Kind = "directed">(mutable: Muta
  * })
  *
  * 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 declare const mapEdges: <N, E, T extends Kind = "directed">(mutable: MutableGraph<N, E, T>, f: (data: E) => E) => void;
 /**
  * Reverses all edge directions in a mutable graph by swapping source and target nodes.
  *
- * @example
+ * **Example** (Reversing edge directions)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -851,18 +962,19 @@ export declare const mapEdges: <N, E, T extends Kind = "directed">(mutable: Muta
  * })
  *
  * 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 declare const reverse: <N, E, T extends Kind = "directed">(mutable: MutableGraph<N, E, T>) => void;
 /**
  * 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"
@@ -885,15 +997,16 @@ export declare const reverse: <N, E, T extends Kind = "directed">(mutable: Mutab
  * console.log(Graph.nodeCount(graph)) // 2 (only "active" nodes remain)
  * ```
  *
- * @since 4.0.0
  * @category transformations
+ * @since 4.0.0
  */
 export declare const filterMapNodes: <N, E, T extends Kind = "directed">(mutable: MutableGraph<N, E, T>, f: (data: N) => Option.Option<N>) => void;
 /**
  * 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"
@@ -916,15 +1029,16 @@ export declare const filterMapNodes: <N, E, T extends Kind = "directed">(mutable
  * console.log(Graph.edgeCount(graph)) // 2 (edges with weight 5 removed)
  * ```
  *
- * @since 4.0.0
  * @category transformations
+ * @since 4.0.0
  */
 export declare const filterMapEdges: <N, E, T extends Kind = "directed">(mutable: MutableGraph<N, E, T>, f: (data: E) => Option.Option<E>) => void;
 /**
  * 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"
  *
@@ -941,15 +1055,16 @@ export declare const filterMapEdges: <N, E, T extends Kind = "directed">(mutable
  * console.log(Graph.nodeCount(graph)) // 2 (only "active" nodes remain)
  * ```
  *
- * @since 4.0.0
  * @category transformations
+ * @since 4.0.0
  */
 export declare const filterNodes: <N, E, T extends Kind = "directed">(mutable: MutableGraph<N, E, T>, predicate: (data: N) => boolean) => void;
 /**
  * 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"
  *
@@ -969,14 +1084,15 @@ export declare const filterNodes: <N, E, T extends Kind = "directed">(mutable: M
  * console.log(Graph.edgeCount(graph)) // 2 (edge with weight 5 removed)
  * ```
  *
- * @since 4.0.0
  * @category transformations
+ * @since 4.0.0
  */
 export declare const filterEdges: <N, E, T extends Kind = "directed">(mutable: MutableGraph<N, E, T>, predicate: (data: E) => boolean) => void;
 /**
  * Adds a new edge to a mutable graph and returns its index.
  *
- * @example
+ * **Example** (Adding edges)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -988,14 +1104,15 @@ export declare const filterEdges: <N, E, T extends Kind = "directed">(mutable: M
  * })
  * ```
  *
- * @since 4.0.0
  * @category mutations
+ * @since 4.0.0
  */
 export declare const addEdge: <N, E, T extends Kind = "directed">(mutable: MutableGraph<N, E, T>, source: NodeIndex, target: NodeIndex, data: E) => EdgeIndex;
 /**
  * Removes a node and all its incident edges from a mutable graph.
  *
- * @example
+ * **Example** (Removing a node)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -1009,14 +1126,15 @@ export declare const addEdge: <N, E, T extends Kind = "directed">(mutable: Mutab
  * })
  * ```
  *
- * @since 4.0.0
  * @category mutations
+ * @since 4.0.0
  */
 export declare const removeNode: <N, E, T extends Kind = "directed">(mutable: MutableGraph<N, E, T>, nodeIndex: NodeIndex) => void;
 /**
  * Removes an edge from a mutable graph.
  *
- * @example
+ * **Example** (Removing an edge)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -1030,14 +1148,15 @@ export declare const removeNode: <N, E, T extends Kind = "directed">(mutable: Mu
  * })
  * ```
  *
- * @since 4.0.0
  * @category mutations
+ * @since 4.0.0
  */
 export declare const removeEdge: <N, E, T extends Kind = "directed">(mutable: MutableGraph<N, E, T>, edgeIndex: EdgeIndex) => void;
 /**
  * Gets the edge data associated with an edge index, if it exists.
  *
- * @example
+ * **Example** (Getting edge data)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -1052,19 +1171,20 @@ export declare const removeEdge: <N, E, T extends Kind = "directed">(mutable: Mu
  *
  * 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 declare const getEdge: {
     /**
      * Gets the edge data associated with an edge index, if it exists.
      *
-     * @example
+     * **Example** (Getting edge data)
+     *
      * ```ts
      * import { Graph } from "effect"
      *
@@ -1079,19 +1199,20 @@ export declare const getEdge: {
      *
      * 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
      */
     <E>(edgeIndex: EdgeIndex): <N, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => Option.Option<Edge<E>>;
     /**
      * Gets the edge data associated with an edge index, if it exists.
      *
-     * @example
+     * **Example** (Getting edge data)
+     *
      * ```ts
      * import { Graph } from "effect"
      *
@@ -1106,20 +1227,21 @@ export declare const getEdge: {
      *
      * 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
      */
     <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>, edgeIndex: EdgeIndex): Option.Option<Edge<E>>;
 };
 /**
  * Checks if an edge exists between two nodes in the graph.
  *
- * @example
+ * **Example** (Checking edge existence)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -1141,14 +1263,15 @@ export declare const getEdge: {
  * console.log(hasAC) // false
  * ```
  *
- * @since 4.0.0
  * @category getters
+ * @since 4.0.0
  */
 export declare const hasEdge: {
     /**
      * Checks if an edge exists between two nodes in the graph.
      *
-     * @example
+     * **Example** (Checking edge existence)
+     *
      * ```ts
      * import { Graph } from "effect"
      *
@@ -1170,14 +1293,15 @@ export declare const hasEdge: {
      * console.log(hasAC) // false
      * ```
      *
-     * @since 4.0.0
      * @category getters
+     * @since 4.0.0
      */
     (source: NodeIndex, target: NodeIndex): <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => boolean;
     /**
      * Checks if an edge exists between two nodes in the graph.
      *
-     * @example
+     * **Example** (Checking edge existence)
+     *
      * ```ts
      * import { Graph } from "effect"
      *
@@ -1199,15 +1323,16 @@ export declare const hasEdge: {
      * console.log(hasAC) // false
      * ```
      *
-     * @since 4.0.0
      * @category getters
+     * @since 4.0.0
      */
     <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>, source: NodeIndex, target: NodeIndex): boolean;
 };
 /**
  * Returns the number of edges in the graph.
  *
- * @example
+ * **Example** (Counting edges)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -1226,14 +1351,20 @@ export declare const hasEdge: {
  * console.log(Graph.edgeCount(graphWithEdges)) // 3
  * ```
  *
- * @since 4.0.0
  * @category getters
+ * @since 4.0.0
  */
 export declare const edgeCount: <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => number;
 /**
- * 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"
  *
@@ -1250,20 +1381,26 @@ export declare const edgeCount: <N, E, T extends Kind = "directed">(graph: Graph
  * 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 declare const neighbors: {
     /**
-     * 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"
      *
@@ -1280,20 +1417,26 @@ export declare const neighbors: {
      * 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
      */
     (nodeIndex: NodeIndex): <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => Array<NodeIndex>;
     /**
-     * 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"
      *
@@ -1310,21 +1453,22 @@ export declare const neighbors: {
      * 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
      */
     <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>, nodeIndex: NodeIndex): Array<NodeIndex>;
 };
 /**
  * Get neighbors of a node in a specific direction for bidirectional traversal.
  *
- * @example
+ * **Example** (Traversing directed neighbors)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -1344,14 +1488,15 @@ export declare const neighbors: {
  * const incoming = Graph.neighborsDirected(graph, nodeB, "incoming")
  * ```
  *
- * @since 4.0.0
  * @category queries
+ * @since 4.0.0
  */
 export declare const neighborsDirected: {
     /**
      * Get neighbors of a node in a specific direction for bidirectional traversal.
      *
-     * @example
+     * **Example** (Traversing directed neighbors)
+     *
      * ```ts
      * import { Graph } from "effect"
      *
@@ -1371,14 +1516,15 @@ export declare const neighborsDirected: {
      * const incoming = Graph.neighborsDirected(graph, nodeB, "incoming")
      * ```
      *
-     * @since 4.0.0
      * @category queries
+     * @since 4.0.0
      */
     (nodeIndex: NodeIndex, direction: Direction): <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => Array<NodeIndex>;
     /**
      * Get neighbors of a node in a specific direction for bidirectional traversal.
      *
-     * @example
+     * **Example** (Traversing directed neighbors)
+     *
      * ```ts
      * import { Graph } from "effect"
      *
@@ -1398,8 +1544,8 @@ export declare const neighborsDirected: {
      * const incoming = Graph.neighborsDirected(graph, nodeB, "incoming")
      * ```
      *
-     * @since 4.0.0
      * @category queries
+     * @since 4.0.0
      */
     <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>, nodeIndex: NodeIndex, direction: Direction): Array<NodeIndex>;
 };
@@ -1409,7 +1555,8 @@ export declare const neighborsDirected: {
  * Provides customization for node labels, edge labels, and graph naming
  * in DOT format compatible with GraphViz tools.
  *
- * @example
+ * **Example** (Configuring GraphViz labels)
+ *
  * ```ts
  * import type * as Graph from "effect/Graph"
  *
@@ -1427,8 +1574,8 @@ export declare const neighborsDirected: {
  * }
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface GraphVizOptions<N, E> {
     /**
@@ -1450,7 +1597,8 @@ export interface GraphVizOptions<N, E> {
 /**
  * Exports a graph to GraphViz DOT format for visualization.
  *
- * @example
+ * **Example** (Exporting GraphViz DOT)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -1475,14 +1623,15 @@ export interface GraphVizOptions<N, E> {
  * // }
  * ```
  *
- * @since 4.0.0
  * @category utils
+ * @since 4.0.0
  */
 export declare const toGraphViz: {
     /**
      * Exports a graph to GraphViz DOT format for visualization.
      *
-     * @example
+     * **Example** (Exporting GraphViz DOT)
+     *
      * ```ts
      * import { Graph } from "effect"
      *
@@ -1507,14 +1656,15 @@ export declare const toGraphViz: {
      * // }
      * ```
      *
-     * @since 4.0.0
      * @category utils
+     * @since 4.0.0
      */
     <N, E>(options?: GraphVizOptions<N, E>): <T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => string;
     /**
      * Exports a graph to GraphViz DOT format for visualization.
      *
-     * @example
+     * **Example** (Exporting GraphViz DOT)
+     *
      * ```ts
      * import { Graph } from "effect"
      *
@@ -1539,8 +1689,8 @@ export declare const toGraphViz: {
      * // }
      * ```
      *
-     * @since 4.0.0
      * @category utils
+     * @since 4.0.0
      */
     <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>, options?: GraphVizOptions<N, E>): string;
 };
@@ -1557,7 +1707,8 @@ export declare const toGraphViz: {
  * - `subroutine`: Subroutine-style nodes `A[["label"]]`
  * - `cylindrical`: Cylindrical database-style nodes `A[("label")]`
  *
- * @example
+ * **Example** (Selecting Mermaid node shapes)
+ *
  * ```ts
  * import type * as Graph from "effect/Graph"
  *
@@ -1575,8 +1726,8 @@ export declare const toGraphViz: {
  * }
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export type MermaidNodeShape = "rectangle" | "rounded" | "circle" | "diamond" | "hexagon" | "stadium" | "subroutine" | "cylindrical";
 /**
@@ -1588,7 +1739,8 @@ export type MermaidNodeShape = "rectangle" | "rounded" | "circle" | "diamond" |
  * - `LR`: Left to Right (horizontal layout)
  * - `RL`: Right to Left (reverse horizontal)
  *
- * @example
+ * **Example** (Configuring Mermaid directions)
+ *
  * ```ts
  * import type * as Graph from "effect/Graph"
  *
@@ -1608,8 +1760,8 @@ export type MermaidNodeShape = "rectangle" | "rounded" | "circle" | "diamond" |
  * }
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export type MermaidDirection = "TB" | "TD" | "BT" | "RL" | "LR";
 /**
@@ -1622,7 +1774,8 @@ export type MermaidDirection = "TB" | "TD" | "BT" | "RL" | "LR";
  * When not specified, automatically selects based on graph type:
  * directed graphs use "flowchart", undirected graphs use "graph".
  *
- * @example
+ * **Example** (Selecting Mermaid diagram types)
+ *
  * ```ts
  * import type * as Graph from "effect/Graph"
  *
@@ -1640,15 +1793,15 @@ export type MermaidDirection = "TB" | "TD" | "BT" | "RL" | "LR";
  * const autoOptions: Graph.MermaidOptions<string, string> = {}
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export type MermaidDiagramType = "flowchart" | "graph";
 /**
  * Configuration options for Mermaid diagram generation, following GraphViz pattern.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 /**
  * Configuration options for Mermaid diagram generation from graphs.
@@ -1656,7 +1809,8 @@ export type MermaidDiagramType = "flowchart" | "graph";
  * Provides customization for node labels, edge labels, diagram type,
  * layout direction, node shapes, and graph naming in Mermaid format.
  *
- * @example
+ * **Example** (Configuring Mermaid output)
+ *
  * ```ts
  * import type * as Graph from "effect/Graph"
  *
@@ -1676,8 +1830,8 @@ export type MermaidDiagramType = "flowchart" | "graph";
  * }
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface MermaidOptions<N, E> {
     /**
@@ -1715,7 +1869,8 @@ export interface MermaidOptions<N, E> {
  * 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"
  *
@@ -1738,7 +1893,8 @@ export interface MermaidOptions<N, E> {
  * //   0 -->|"2"| 2
  * ```
  *
- * @example
+ * **Example** (Exporting an undirected Mermaid diagram)
+ *
  * ```ts
  * import * as Graph from "effect/Graph"
  *
@@ -1765,7 +1921,8 @@ export interface MermaidOptions<N, E> {
  * //   1 ---|"colleagues"| 2
  * ```
  *
- * @example
+ * **Example** (Customizing Mermaid node shapes)
+ *
  * ```ts
  * import * as Graph from "effect/Graph"
  *
@@ -1816,7 +1973,8 @@ export interface MermaidOptions<N, E> {
  * //   2 --> 3
  * ```
  *
- * @example
+ * **Example** (Visualizing dependency graphs)
+ *
  * ```ts
  * import * as Graph from "effect/Graph"
  *
@@ -1881,8 +2039,8 @@ export interface MermaidOptions<N, E> {
  * @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 declare const toMermaid: {
     /**
@@ -1893,7 +2051,8 @@ export declare const toMermaid: {
      * 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"
      *
@@ -1916,7 +2075,8 @@ export declare const toMermaid: {
      * //   0 -->|"2"| 2
      * ```
      *
-     * @example
+     * **Example** (Exporting an undirected Mermaid diagram)
+     *
      * ```ts
      * import * as Graph from "effect/Graph"
      *
@@ -1943,7 +2103,8 @@ export declare const toMermaid: {
      * //   1 ---|"colleagues"| 2
      * ```
      *
-     * @example
+     * **Example** (Customizing Mermaid node shapes)
+     *
      * ```ts
      * import * as Graph from "effect/Graph"
      *
@@ -1994,7 +2155,8 @@ export declare const toMermaid: {
      * //   2 --> 3
      * ```
      *
-     * @example
+     * **Example** (Visualizing dependency graphs)
+     *
      * ```ts
      * import * as Graph from "effect/Graph"
      *
@@ -2059,8 +2221,8 @@ export declare const toMermaid: {
      * @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
      */
     <N, E>(options?: MermaidOptions<N, E>): <T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => string;
     /**
@@ -2071,7 +2233,8 @@ export declare const toMermaid: {
      * 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"
      *
@@ -2094,7 +2257,8 @@ export declare const toMermaid: {
      * //   0 -->|"2"| 2
      * ```
      *
-     * @example
+     * **Example** (Exporting an undirected Mermaid diagram)
+     *
      * ```ts
      * import * as Graph from "effect/Graph"
      *
@@ -2121,7 +2285,8 @@ export declare const toMermaid: {
      * //   1 ---|"colleagues"| 2
      * ```
      *
-     * @example
+     * **Example** (Customizing Mermaid node shapes)
+     *
      * ```ts
      * import * as Graph from "effect/Graph"
      *
@@ -2172,7 +2337,8 @@ export declare const toMermaid: {
      * //   2 --> 3
      * ```
      *
-     * @example
+     * **Example** (Visualizing dependency graphs)
+     *
      * ```ts
      * import * as Graph from "effect/Graph"
      *
@@ -2237,15 +2403,16 @@ export declare const toMermaid: {
      * @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
      */
     <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>, options?: MermaidOptions<N, E>): string;
 };
 /**
  * Direction for graph traversal, indicating which edges to follow.
  *
- * @example
+ * **Example** (Traversing by direction)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -2266,8 +2433,8 @@ export declare const toMermaid: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export type Direction = "outgoing" | "incoming";
 /**
@@ -2277,7 +2444,8 @@ export type Direction = "outgoing" | "incoming";
  * 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"
  *
@@ -2301,8 +2469,8 @@ export type Direction = "outgoing" | "incoming";
  * console.log(Graph.isAcyclic(cyclic)) // false
  * ```
  *
- * @since 4.0.0
  * @category algorithms
+ * @since 4.0.0
  */
 export declare const isAcyclic: <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => boolean;
 /**
@@ -2312,7 +2480,8 @@ export declare const isAcyclic: <N, E, T extends Kind = "directed">(graph: 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"
  *
@@ -2340,15 +2509,16 @@ export declare const isAcyclic: <N, E, T extends Kind = "directed">(graph: Graph
  * console.log(Graph.isBipartite(triangle)) // false
  * ```
  *
- * @since 4.0.0
  * @category algorithms
+ * @since 4.0.0
  */
 export declare const isBipartite: <N, E>(graph: Graph<N, E, "undirected"> | MutableGraph<N, E, "undirected">) => boolean;
 /**
  * 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"
  *
@@ -2365,15 +2535,16 @@ export declare const isBipartite: <N, E>(graph: Graph<N, E, "undirected"> | Muta
  * console.log(components) // [[0, 1], [2, 3]]
  * ```
  *
- * @since 4.0.0
  * @category algorithms
+ * @since 4.0.0
  */
 export declare const connectedComponents: <N, E>(graph: Graph<N, E, "undirected"> | MutableGraph<N, E, "undirected">) => Array<Array<NodeIndex>>;
 /**
  * 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"
  *
@@ -2390,15 +2561,20 @@ export declare const connectedComponents: <N, E>(graph: Graph<N, E, "undirected"
  * console.log(sccs) // [[0, 1, 2]]
  * ```
  *
- * @since 4.0.0
  * @category algorithms
+ * @since 4.0.0
  */
 export declare const stronglyConnectedComponents: <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => Array<Array<NodeIndex>>;
 /**
- * Result of a shortest path computation containing the path and total distance.
+ * Result of a shortest path computation.
+ *
+ * **Details**
+ *
+ * Contains the node-index path, the total numeric distance, and the edge data
+ * encountered along the path.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface PathResult<E> {
     readonly path: Array<NodeIndex>;
@@ -2406,10 +2582,15 @@ export interface PathResult<E> {
     readonly costs: Array<E>;
 }
 /**
- * Configuration for Dijkstra's algorithm.
+ * Configuration for finding a shortest path with Dijkstra's algorithm.
+ *
+ * **Details**
+ *
+ * Specifies the source and target node indices, plus a cost function that maps
+ * each edge's data to a non-negative numeric weight.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface DijkstraConfig<E> {
     source: NodeIndex;
@@ -2417,12 +2598,17 @@ export interface DijkstraConfig<E> {
     cost: (edgeData: E) => number;
 }
 /**
- * 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**
+ *
+ * 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.
  *
- * 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.
+ * **Example** (Finding shortest paths with Dijkstra)
  *
- * @example
  * ```ts
  * import { Graph } from "effect"
  *
@@ -2447,17 +2633,22 @@ export interface DijkstraConfig<E> {
  * }
  * ```
  *
- * @since 4.0.0
  * @category algorithms
+ * @since 4.0.0
  */
 export declare const dijkstra: {
     /**
-     * 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"
      *
@@ -2482,17 +2673,22 @@ export declare const dijkstra: {
      * }
      * ```
      *
-     * @since 4.0.0
      * @category algorithms
+     * @since 4.0.0
      */
     <E>(config: DijkstraConfig<E>): <N, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => Option.Option<PathResult<E>>;
     /**
-     * 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.
      *
-     * 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.
+     * **Details**
+     *
+     * 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"
      *
@@ -2517,16 +2713,21 @@ export declare const dijkstra: {
      * }
      * ```
      *
-     * @since 4.0.0
      * @category algorithms
+     * @since 4.0.0
      */
     <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>, config: DijkstraConfig<E>): Option.Option<PathResult<E>>;
 };
 /**
- * Result of all-pairs shortest path computation.
+ * Result of an all-pairs shortest path computation.
+ *
+ * **Details**
+ *
+ * Contains distance, node-path, and edge-data maps keyed by source and target
+ * node indices.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface AllPairsResult<E> {
     readonly distances: Map<NodeIndex, Map<NodeIndex, number>>;
@@ -2534,14 +2735,17 @@ export interface AllPairsResult<E> {
     readonly costs: Map<NodeIndex, Map<NodeIndex, Array<E>>>;
 }
 /**
- * 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.
+ *
+ * **Details**
  *
- * 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.
+ * 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.
  *
- * Throws if a negative cycle is detected that affects the path to target.
+ * **Example** (Finding all-pairs shortest paths)
  *
- * @example
  * ```ts
  * import { Graph } from "effect"
  *
@@ -2559,19 +2763,22 @@ export interface AllPairsResult<E> {
  * const pathAToC = result.paths.get(0)?.get(2) // [0, 1, 2]
  * ```
  *
- * @since 4.0.0
  * @category algorithms
+ * @since 4.0.0
  */
 export declare const floydWarshall: {
     /**
-     * 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.
+     *
+     * **Details**
      *
-     * 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.
+     * 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.
      *
-     * Throws if a negative cycle is detected that affects the path to target.
+     * **Example** (Finding all-pairs shortest paths)
      *
-     * @example
      * ```ts
      * import { Graph } from "effect"
      *
@@ -2589,19 +2796,22 @@ export declare const floydWarshall: {
      * const pathAToC = result.paths.get(0)?.get(2) // [0, 1, 2]
      * ```
      *
-     * @since 4.0.0
      * @category algorithms
+     * @since 4.0.0
      */
     <E>(cost: (edgeData: E) => number): <N, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => AllPairsResult<E>;
     /**
-     * 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.
+     *
+     * **Details**
      *
-     * 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.
+     * 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.
      *
-     * Throws if a negative cycle is detected that affects the path to target.
+     * **Example** (Finding all-pairs shortest paths)
      *
-     * @example
      * ```ts
      * import { Graph } from "effect"
      *
@@ -2619,16 +2829,21 @@ export declare const floydWarshall: {
      * const pathAToC = result.paths.get(0)?.get(2) // [0, 1, 2]
      * ```
      *
-     * @since 4.0.0
      * @category algorithms
+     * @since 4.0.0
      */
     <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>, cost: (edgeData: E) => number): AllPairsResult<E>;
 };
 /**
- * Configuration for A* pathfinding algorithm.
+ * Configuration for finding a shortest path with the A* algorithm.
+ *
+ * **Details**
+ *
+ * Specifies the source and target node indices, an edge-cost function, and a
+ * heuristic that estimates the remaining cost from a node to the target.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface AstarConfig<E, N> {
     source: NodeIndex;
@@ -2637,13 +2852,18 @@ export interface AstarConfig<E, N> {
     heuristic: (sourceNodeData: N, targetNodeData: N) => number;
 }
 /**
- * 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.
+ *
+ * **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.
  *
- * 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).
+ * **Example** (Finding shortest paths with A-star)
  *
- * @example
  * ```ts
  * import { Graph } from "effect"
  *
@@ -2674,18 +2894,23 @@ export interface AstarConfig<E, N> {
  * }
  * ```
  *
- * @since 4.0.0
  * @category algorithms
+ * @since 4.0.0
  */
 export declare const astar: {
     /**
-     * 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.
+     *
+     * **Details**
      *
-     * 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).
+     * 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"
      *
@@ -2716,18 +2941,23 @@ export declare const astar: {
      * }
      * ```
      *
-     * @since 4.0.0
      * @category algorithms
+     * @since 4.0.0
      */
     <E, N>(config: AstarConfig<E, N>): <T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => Option.Option<PathResult<E>>;
     /**
-     * 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.
+     *
+     * **Details**
      *
-     * 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).
+     * 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"
      *
@@ -2758,16 +2988,21 @@ export declare const astar: {
      * }
      * ```
      *
-     * @since 4.0.0
      * @category algorithms
+     * @since 4.0.0
      */
     <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>, config: AstarConfig<E, N>): Option.Option<PathResult<E>>;
 };
 /**
- * Configuration for Bellman-Ford algorithm.
+ * Configuration for finding a shortest path with the Bellman-Ford algorithm.
+ *
+ * **Details**
+ *
+ * Specifies the source and target node indices, plus a cost function that maps
+ * each edge's data to a numeric weight.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface BellmanFordConfig<E> {
     source: NodeIndex;
@@ -2775,13 +3010,17 @@ export interface BellmanFordConfig<E> {
     cost: (edgeData: E) => number;
 }
 /**
- * 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**
+ *
+ * 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.
  *
- * 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.
+ * **Example** (Finding shortest paths with Bellman-Ford)
  *
- * @example
  * ```ts
  * import { Graph } from "effect"
  *
@@ -2806,18 +3045,22 @@ export interface BellmanFordConfig<E> {
  * }
  * ```
  *
- * @since 4.0.0
  * @category algorithms
+ * @since 4.0.0
  */
 export declare const bellmanFord: {
     /**
-     * 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**
+     *
+     * 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.
      *
-     * 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.
+     * **Example** (Finding shortest paths with Bellman-Ford)
      *
-     * @example
      * ```ts
      * import { Graph } from "effect"
      *
@@ -2842,18 +3085,22 @@ export declare const bellmanFord: {
      * }
      * ```
      *
-     * @since 4.0.0
      * @category algorithms
+     * @since 4.0.0
      */
     <E>(config: BellmanFordConfig<E>): <N, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => Option.Option<PathResult<E>>;
     /**
-     * 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"
      *
@@ -2878,19 +3125,22 @@ export declare const bellmanFord: {
      * }
      * ```
      *
-     * @since 4.0.0
      * @category algorithms
+     * @since 4.0.0
      */
     <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>, config: BellmanFordConfig<E>): Option.Option<PathResult<E>>;
 };
 /**
- * Concrete class for iterables that produce [NodeIndex, NodeData] tuples.
+ * Iterable wrapper used by graph traversal and listing APIs.
+ *
+ * **Details**
  *
- * 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.
+ * 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"
  *
@@ -2914,8 +3164,8 @@ export declare const bellmanFord: {
  * const nodeEntries = Array.from(Graph.entries(allNodes)) // [[0, "A"], [1, "B"]]
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export declare class Walker<T, N> implements Iterable<[T, N]> {
     readonly [Symbol.iterator]: () => Iterator<[T, N]>;
@@ -2926,7 +3176,8 @@ export declare class Walker<T, N> implements Iterable<[T, N]> {
      * 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"
      *
@@ -2949,8 +3200,8 @@ export declare class Walker<T, N> implements Iterable<[T, N]> {
      * console.log(custom) // [{ id: 0, name: "A" }, { id: 1, name: "B" }]
      * ```
      *
-     * @since 4.0.0
      * @category iterators
+     * @since 4.0.0
      */
     readonly visit: <U>(f: (index: T, data: N) => U) => Iterable<U>;
     constructor(
@@ -2961,7 +3212,8 @@ export declare class Walker<T, N> implements Iterable<[T, N]> {
      * 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"
      *
@@ -2984,8 +3236,8 @@ export declare class Walker<T, N> implements Iterable<[T, N]> {
      * console.log(custom) // [{ id: 0, name: "A" }, { id: 1, name: "B" }]
      * ```
      *
-     * @since 4.0.0
      * @category iterators
+     * @since 4.0.0
      */
     visit: <U>(f: (index: T, data: N) => U) => Iterable<U>);
 }
@@ -2993,22 +3245,23 @@ export declare class Walker<T, N> implements Iterable<[T, N]> {
  * Type alias for node iteration using Walker.
  * NodeWalker is represented as Walker<NodeIndex, N>.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export type NodeWalker<N> = Walker<NodeIndex, N>;
 /**
  * Type alias for edge iteration using Walker.
  * EdgeWalker is represented as Walker<EdgeIndex, Edge<E>>.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export type EdgeWalker<E> = Walker<EdgeIndex, Edge<E>>;
 /**
  * Returns an iterator over the indices in the walker.
  *
- * @example
+ * **Example** (Iterating walker indices)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -3023,14 +3276,15 @@ export type EdgeWalker<E> = Walker<EdgeIndex, Edge<E>>;
  * console.log(indices) // [0, 1]
  * ```
  *
- * @since 4.0.0
  * @category utilities
+ * @since 4.0.0
  */
 export declare const indices: <T, N>(walker: Walker<T, N>) => Iterable<T>;
 /**
  * Returns an iterator over the values (data) in the walker.
  *
- * @example
+ * **Example** (Iterating walker values)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -3045,14 +3299,15 @@ export declare const indices: <T, N>(walker: Walker<T, N>) => Iterable<T>;
  * console.log(values) // ["A", "B"]
  * ```
  *
- * @since 4.0.0
  * @category utilities
+ * @since 4.0.0
  */
 export declare const values: <T, N>(walker: Walker<T, N>) => Iterable<N>;
 /**
  * Returns an iterator over [index, data] entries in the walker.
  *
- * @example
+ * **Example** (Iterating walker entries)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -3067,27 +3322,38 @@ export declare const values: <T, N>(walker: Walker<T, N>) => Iterable<N>;
  * console.log(entries) // [[0, "A"], [1, "B"]]
  * ```
  *
- * @since 4.0.0
  * @category utilities
+ * @since 4.0.0
  */
 export declare const entries: <T, N>(walker: Walker<T, N>) => Iterable<[T, N]>;
 /**
- * Configuration options for search iterators.
+ * Configuration for DFS, BFS, and postorder graph traversals.
+ *
+ * **Details**
+ *
+ * `start` supplies the node indices where traversal begins. If it is omitted,
+ * the iterator is empty. `direction` chooses whether traversal follows
+ * outgoing or incoming edges.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface SearchConfig {
     readonly start?: Array<NodeIndex>;
     readonly direction?: Direction;
 }
 /**
- * Creates a new DFS iterator with optional configuration.
+ * Creates a lazy depth-first traversal iterator from the configured start
+ * nodes.
  *
- * The iterator maintains a stack of nodes to visit and tracks discovered nodes.
- * It provides lazy evaluation of the depth-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 depth-first)
  *
- * @example
  * ```ts
  * import { Graph } from "effect"
  *
@@ -3110,17 +3376,22 @@ export interface SearchConfig {
  * // Can be used programmatically
  * ```
  *
- * @since 4.0.0
  * @category iterators
+ * @since 4.0.0
  */
 export declare const dfs: {
     /**
-     * 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"
      *
@@ -3143,17 +3414,22 @@ export declare const dfs: {
      * // Can be used programmatically
      * ```
      *
-     * @since 4.0.0
      * @category iterators
+     * @since 4.0.0
      */
     (config?: SearchConfig): <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => NodeWalker<N>;
     /**
-     * Creates a new DFS iterator with optional configuration.
+     * Creates a lazy depth-first traversal iterator from the configured start
+     * nodes.
+     *
+     * **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.
      *
-     * The iterator maintains a stack of nodes to visit and tracks discovered nodes.
-     * It provides lazy evaluation of the depth-first search.
+     * **Example** (Traversing depth-first)
      *
-     * @example
      * ```ts
      * import { Graph } from "effect"
      *
@@ -3176,18 +3452,23 @@ export declare const dfs: {
      * // Can be used programmatically
      * ```
      *
-     * @since 4.0.0
      * @category iterators
+     * @since 4.0.0
      */
     <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>, config?: SearchConfig): NodeWalker<N>;
 };
 /**
- * Creates a new BFS iterator with optional configuration.
+ * Creates a lazy breadth-first traversal iterator from the configured start
+ * nodes.
+ *
+ * **Details**
  *
- * The iterator maintains a queue of nodes to visit and tracks discovered nodes.
- * It provides lazy evaluation of the breadth-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 breadth-first)
  *
- * @example
  * ```ts
  * import { Graph } from "effect"
  *
@@ -3210,17 +3491,22 @@ export declare const dfs: {
  * // Can be used programmatically
  * ```
  *
- * @since 4.0.0
  * @category iterators
+ * @since 4.0.0
  */
 export declare const bfs: {
     /**
-     * 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"
      *
@@ -3243,17 +3529,22 @@ export declare const bfs: {
      * // Can be used programmatically
      * ```
      *
-     * @since 4.0.0
      * @category iterators
+     * @since 4.0.0
      */
     (config?: SearchConfig): <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => NodeWalker<N>;
     /**
-     * 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"
      *
@@ -3276,16 +3567,22 @@ export declare const bfs: {
      * // Can be used programmatically
      * ```
      *
-     * @since 4.0.0
      * @category iterators
+     * @since 4.0.0
      */
     <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>, config?: SearchConfig): NodeWalker<N>;
 };
 /**
- * Configuration options for topological sort iterator.
+ * Configuration for the topological sort iterator.
+ *
+ * **Details**
+ *
+ * `initials` optionally supplies the node indices used as initial queue
+ * entries. When omitted, topological sorting starts from all nodes with zero
+ * in-degree.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface TopoConfig {
     readonly initials?: Array<NodeIndex>;
@@ -3296,7 +3593,8 @@ export interface TopoConfig {
  * 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"
  *
@@ -3317,7 +3615,7 @@ export interface TopoConfig {
  * // 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")
@@ -3325,15 +3623,13 @@ export interface TopoConfig {
  *   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 declare const topo: {
     /**
@@ -3342,7 +3638,8 @@ export declare const topo: {
      * 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"
      *
@@ -3363,7 +3660,7 @@ export declare const topo: {
      * // 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")
@@ -3371,15 +3668,13 @@ export declare const topo: {
      *   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
      */
     (config?: TopoConfig): <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => NodeWalker<N>;
     /**
@@ -3388,7 +3683,8 @@ export declare const topo: {
      * 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"
      *
@@ -3409,7 +3705,7 @@ export declare const topo: {
      * // 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")
@@ -3417,26 +3713,28 @@ export declare const topo: {
      *   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
      */
     <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>, config?: TopoConfig): NodeWalker<N>;
 };
 /**
- * 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"
  *
@@ -3455,18 +3753,22 @@ export declare const topo: {
  * }
  * ```
  *
- * @since 4.0.0
  * @category iterators
+ * @since 4.0.0
  */
 export declare const dfsPostOrder: {
     /**
-     * Creates a new DFS postorder iterator with optional configuration.
+     * Creates a lazy depth-first postorder traversal iterator from the configured
+     * start nodes.
+     *
+     * **Details**
      *
-     * 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.
+     * 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.
+     *
+     * **Example** (Traversing in postorder)
      *
-     * @example
      * ```ts
      * import { Graph } from "effect"
      *
@@ -3485,18 +3787,22 @@ export declare const dfsPostOrder: {
      * }
      * ```
      *
-     * @since 4.0.0
      * @category iterators
+     * @since 4.0.0
      */
     (config?: SearchConfig): <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => NodeWalker<N>;
     /**
-     * Creates a new DFS postorder iterator with optional configuration.
+     * Creates a lazy depth-first postorder traversal iterator from the configured
+     * start nodes.
+     *
+     * **Details**
      *
-     * 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.
+     * 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.
+     *
+     * **Example** (Traversing in postorder)
      *
-     * @example
      * ```ts
      * import { Graph } from "effect"
      *
@@ -3515,8 +3821,8 @@ export declare const dfsPostOrder: {
      * }
      * ```
      *
-     * @since 4.0.0
      * @category iterators
+     * @since 4.0.0
      */
     <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>, config?: SearchConfig): NodeWalker<N>;
 };
@@ -3526,7 +3832,8 @@ export declare const dfsPostOrder: {
  * 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"
  *
@@ -3541,8 +3848,8 @@ export declare const dfsPostOrder: {
  * console.log(indices) // [0, 1, 2]
  * ```
  *
- * @since 4.0.0
  * @category iterators
+ * @since 4.0.0
  */
 export declare const nodes: <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => NodeWalker<N>;
 /**
@@ -3551,7 +3858,8 @@ export declare const nodes: <N, E, T extends Kind = "directed">(graph: Graph<N,
  * 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"
  *
@@ -3567,15 +3875,21 @@ export declare const nodes: <N, E, T extends Kind = "directed">(graph: Graph<N,
  * console.log(indices) // [0, 1]
  * ```
  *
- * @since 4.0.0
  * @category iterators
+ * @since 4.0.0
  */
 export declare const edges: <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => EdgeWalker<E>;
 /**
- * Configuration for externals iterator.
+ * Configuration for selecting external nodes.
+ *
+ * **Details**
+ *
+ * `direction` chooses which missing edge direction makes a node external:
+ * `"outgoing"` selects nodes with no outgoing edges, and `"incoming"` selects
+ * nodes with no incoming edges.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface ExternalsConfig {
     readonly direction?: Direction;
@@ -3587,7 +3901,8 @@ export interface ExternalsConfig {
  * 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"
  *
@@ -3614,8 +3929,8 @@ export interface ExternalsConfig {
  * console.log(sources) // [0, 3]
  * ```
  *
- * @since 4.0.0
  * @category iterators
+ * @since 4.0.0
  */
 export declare const externals: {
     /**
@@ -3625,7 +3940,8 @@ export declare const externals: {
      * 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"
      *
@@ -3652,8 +3968,8 @@ export declare const externals: {
      * console.log(sources) // [0, 3]
      * ```
      *
-     * @since 4.0.0
      * @category iterators
+     * @since 4.0.0
      */
     (config?: ExternalsConfig): <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => NodeWalker<N>;
     /**
@@ -3663,7 +3979,8 @@ export declare const externals: {
      * 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"
      *
@@ -3690,8 +4007,8 @@ export declare const externals: {
      * console.log(sources) // [0, 3]
      * ```
      *
-     * @since 4.0.0
      * @category iterators
+     * @since 4.0.0
      */
     <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>, config?: ExternalsConfig): NodeWalker<N>;
 };