effect 4.0.0-beta.70 → 4.0.0-beta.72

package/dist/Graph.d.ts

@@ -60,6 +60,23 @@ declare const TypeId = "~effect/collections/Graph";
 /**
  * Node index for node identification using plain numbers.
  *
+ * **When to use**
+ *
+ * Use when storing or passing the stable identifier of a graph node between
+ * `Graph` operations.
+ *
+ * **Details**
+ *
+ * `addNode` allocates node identifiers from the graph's next node index.
+ *
+ * **Gotchas**
+ *
+ * A `NodeIndex` is an identifier, not an array offset. Removed node identifiers
+ * are not reused.
+ *
+ * @see {@link EdgeIndex} for edge identifiers instead of node identifiers
+ * @see {@link addNode} for creating node identifiers
+ *
  * @category models
  * @since 3.18.0
  */
@@ -67,12 +84,36 @@ export type NodeIndex = number;
 /**
  * Edge index for edge identification using plain numbers.
  *
+ * **When to use**
+ *
+ * Use when you need to keep the identifier for a graph edge so you can later
+ * read, update, remove, or compare that edge.
+ *
+ * **Gotchas**
+ *
+ * An `EdgeIndex` is an identifier, not an array offset. Removed edge
+ * identifiers are not reused.
+ *
+ * @see {@link NodeIndex} for node identifiers instead of edge identifiers
+ * @see {@link Edge} for the edge value addressed by this identifier
+ * @see {@link addEdge} for creating edge identifiers
+ * @see {@link getEdge} for reading edges by identifier
+ *
  * @category models
  * @since 3.18.0
  */
 export type EdgeIndex = number;
 /**
- * Edge data containing source, target, and user data.
+ * Represents edge data containing source, target, and user data.
+ *
+ * **When to use**
+ *
+ * Use as the graph edge value returned by `getEdge` and `edges` when you need
+ * the source node, target node, and stored edge data together.
+ *
+ * @see {@link getEdge} for reading a single edge by identifier
+ * @see {@link addEdge} for adding edges to a graph
+ * @see {@link edges} for iterating graph edges
  *
  * @category models
  * @since 3.18.0
@@ -86,6 +127,14 @@ export declare class Edge<E> extends Data.Class<{
 /**
  * Graph type for distinguishing directed and undirected graphs.
  *
+ * **When to use**
+ *
+ * Use when writing graph-polymorphic types or helpers that need to preserve
+ * whether a graph is directed or undirected.
+ *
+ * @see {@link Graph} for immutable graphs parameterized by kind
+ * @see {@link MutableGraph} for mutable graphs parameterized by kind
+ *
  * @category models
  * @since 3.18.0
  */
@@ -114,6 +163,15 @@ export interface Proto<out N, out E> extends Iterable<readonly [NodeIndex, N]>,
 /**
  * Immutable graph interface.
  *
+ * **When to use**
+ *
+ * Use as the immutable graph model for code that queries, traverses,
+ * transforms, or analyzes graph structure without mutating it.
+ *
+ * @see {@link MutableGraph} for the mutable counterpart used inside mutation scopes
+ * @see {@link DirectedGraph} for a `Graph` fixed to directed edges
+ * @see {@link UndirectedGraph} for a `Graph` fixed to undirected edges
+ *
  * @category models
  * @since 3.18.0
  */
@@ -124,6 +182,16 @@ export interface Graph<out N, out E, T extends Kind = "directed"> extends Proto<
 /**
  * Mutable graph interface.
  *
+ * **When to use**
+ *
+ * Use when adding, removing, or updating nodes and edges inside a graph
+ * mutation scope.
+ *
+ * @see {@link Graph} for the immutable graph interface
+ * @see {@link mutate} for scoped mutation of an immutable graph
+ * @see {@link beginMutation} for opening a mutable graph manually
+ * @see {@link endMutation} for returning to an immutable graph
+ *
  * @category models
  * @since 3.18.0
  */
@@ -132,14 +200,42 @@ export interface MutableGraph<out N, out E, T extends Kind = "directed"> extends
     readonly mutable: true;
 }
 /**
- * Directed graph type alias.
+ * Immutable graph type for source-to-target relationships.
+ *
+ * **When to use**
+ *
+ * Use as the immutable graph type when edge direction is part of the model and
+ * traversal or neighbor queries should follow source-to-target edges.
+ *
+ * **Details**
+ *
+ * `DirectedGraph<N, E>` is a `Graph<N, E, "directed">` with node data of type
+ * `N` and edge data of type `E`.
+ *
+ * @see {@link directed} for constructing directed graphs
+ * @see {@link Graph} for the generic immutable graph type
+ * @see {@link UndirectedGraph} for graphs whose edges connect both endpoints
+ * @see {@link MutableDirectedGraph} for the mutable directed graph type
  *
  * @category models
  * @since 3.18.0
  */
 export type DirectedGraph<N, E> = Graph<N, E, "directed">;
 /**
- * Undirected graph type alias.
+ * Immutable graph type for relationships without source-to-target direction.
+ *
+ * **When to use**
+ *
+ * Use when modeling relationships where each edge connects both endpoints
+ * without a source-to-target direction.
+ *
+ * **Details**
+ *
+ * `UndirectedGraph<N, E>` is a `Graph<N, E, "undirected">`.
+ *
+ * @see {@link undirected} for constructing undirected graphs
+ * @see {@link DirectedGraph} for graphs whose edges have source-to-target direction
+ * @see {@link MutableUndirectedGraph} for the mutable undirected graph type
  *
  * @category models
  * @since 3.18.0
@@ -148,6 +244,15 @@ export type UndirectedGraph<N, E> = Graph<N, E, "undirected">;
 /**
  * Mutable directed graph type alias.
  *
+ * **When to use**
+ *
+ * Use when annotating a temporary graph value that can be changed in place and
+ * whose edges have source-to-target direction.
+ *
+ * @see {@link MutableGraph} for the generic mutable graph type
+ * @see {@link DirectedGraph} for the immutable directed graph type
+ * @see {@link MutableUndirectedGraph} for mutable graphs without edge direction
+ *
  * @category models
  * @since 3.18.0
  */
@@ -155,6 +260,15 @@ export type MutableDirectedGraph<N, E> = MutableGraph<N, E, "directed">;
 /**
  * Mutable undirected graph type alias.
  *
+ * **When to use**
+ *
+ * Use when annotating a temporary graph value that can be changed in place and
+ * whose edges connect both endpoints without direction.
+ *
+ * @see {@link MutableDirectedGraph} for mutable graphs with directed edges
+ * @see {@link UndirectedGraph} for the immutable undirected graph type
+ * @see {@link MutableGraph} for the generic mutable graph type
+ *
  * @category models
  * @since 3.18.0
  */
@@ -167,6 +281,11 @@ declare const GraphError_base: new <A extends Record<string, any> = {}>(args: im
  * invalid, such as referencing a missing node or using unsupported edge
  * weights.
  *
+ * **When to use**
+ *
+ * Use when handling failures thrown by graph operations that reject invalid
+ * graph structure or unsupported algorithm inputs.
+ *
  * @category errors
  * @since 3.18.0
  */
@@ -178,6 +297,15 @@ export declare class GraphError extends GraphError_base<{
  * Returns `true` if a value has the graph runtime type identifier, narrowing
  * it to a `Graph`.
  *
+ * **When to use**
+ *
+ * Use to narrow an unknown value before treating it as a graph value.
+ *
+ * **Gotchas**
+ *
+ * This guard checks the shared graph runtime type identifier and does not
+ * distinguish immutable graphs from mutable graphs.
+ *
  * @category guards
  * @since 4.0.0
  */
@@ -334,6 +462,21 @@ export declare const mutate: {
 /**
  * Adds a new node to a mutable graph and returns its index.
  *
+ * **When to use**
+ *
+ * Use to allocate a new node in a mutable graph before storing edges or
+ * querying it by index.
+ *
+ * **Details**
+ *
+ * The returned index is allocated from the graph's next node index. The mutable
+ * graph stores the node data and initializes empty incoming and outgoing edge
+ * indexes for the new node.
+ *
+ * **Gotchas**
+ *
+ * `NodeIndex` values are identifiers and are not reused after removals.
+ *
  * **Example** (Adding nodes)
  *
  * ```ts
@@ -347,12 +490,16 @@ export declare const mutate: {
  * })
  * ```
  *
+ * @see {@link mutate} for obtaining a mutable graph from an immutable graph
+ * @see {@link addEdge} for connecting existing nodes
+ * @see {@link removeNode} for removing nodes from a mutable graph
+ *
  * @category mutations
  * @since 3.18.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.
+ * Gets the data associated with a node index safely, if it exists.
  *
  * **Example** (Getting node data)
  *
@@ -376,7 +523,7 @@ export declare const addNode: <N, E, T extends Kind = "directed">(mutable: Mutab
  */
 export declare const getNode: {
     /**
-     * Gets the data associated with a node index, if it exists.
+     * Gets the data associated with a node index safely, if it exists.
      *
      * **Example** (Getting node data)
      *
@@ -400,7 +547,7 @@ export declare const getNode: {
      */
     <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.
+     * Gets the data associated with a node index safely, if it exists.
      *
      * **Example** (Getting node data)
      *
@@ -425,7 +572,7 @@ export declare const getNode: {
     <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.
+ * Checks whether a node with the given index exists in the graph.
  *
  * **Example** (Checking node existence)
  *
@@ -450,7 +597,7 @@ export declare const getNode: {
  */
 export declare const hasNode: {
     /**
-     * Checks if a node with the given index exists in the graph.
+     * Checks whether a node with the given index exists in the graph.
      *
      * **Example** (Checking node existence)
      *
@@ -475,7 +622,7 @@ export declare const hasNode: {
      */
     (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.
+     * Checks whether a node with the given index exists in the graph.
      *
      * **Example** (Checking node existence)
      *
@@ -942,7 +1089,7 @@ export declare const mapNodes: <N, E, T extends Kind = "directed">(mutable: Muta
  */
 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.
+ * Swaps source and target nodes for every edge in a mutable graph.
  *
  * **Example** (Reversing edge directions)
  *
@@ -1086,6 +1233,22 @@ export declare const filterEdges: <N, E, T extends Kind = "directed">(mutable: M
 /**
  * Adds a new edge to a mutable graph and returns its index.
  *
+ * **When to use**
+ *
+ * Use to connect two existing nodes in a mutable graph while storing edge data
+ * and receiving the new edge identifier.
+ *
+ * **Details**
+ *
+ * Creates an `Edge` with the source, target, and data at the next edge index,
+ * updates adjacency indexes, and increments the graph's next edge index.
+ * Undirected graphs register the same edge for both endpoints.
+ *
+ * **Gotchas**
+ *
+ * The source and target nodes must already exist in the mutable graph; missing
+ * endpoints throw a `GraphError`.
+ *
  * **Example** (Adding edges)
  *
  * ```ts
@@ -1099,6 +1262,11 @@ export declare const filterEdges: <N, E, T extends Kind = "directed">(mutable: M
  * })
  * ```
  *
+ * @see {@link mutate} for obtaining a mutable graph from an immutable graph
+ * @see {@link addNode} for creating node indexes before connecting them
+ * @see {@link getEdge} for reading the returned edge
+ * @see {@link removeEdge} for removing an edge from a mutable graph
+ *
  * @category mutations
  * @since 3.18.0
  */
@@ -1148,7 +1316,7 @@ export declare const removeNode: <N, E, T extends Kind = "directed">(mutable: Mu
  */
 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.
+ * Gets the edge data associated with an edge index safely, if it exists.
  *
  * **Example** (Getting edge data)
  *
@@ -1176,7 +1344,7 @@ export declare const removeEdge: <N, E, T extends Kind = "directed">(mutable: Mu
  */
 export declare const getEdge: {
     /**
-     * Gets the edge data associated with an edge index, if it exists.
+     * Gets the edge data associated with an edge index safely, if it exists.
      *
      * **Example** (Getting edge data)
      *
@@ -1204,7 +1372,7 @@ export declare const getEdge: {
      */
     <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.
+     * Gets the edge data associated with an edge index safely, if it exists.
      *
      * **Example** (Getting edge data)
      *
@@ -1233,7 +1401,7 @@ export declare const getEdge: {
     <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.
+ * Checks whether an edge exists between two nodes in the graph.
  *
  * **Example** (Checking edge existence)
  *
@@ -1263,7 +1431,7 @@ export declare const getEdge: {
  */
 export declare const hasEdge: {
     /**
-     * Checks if an edge exists between two nodes in the graph.
+     * Checks whether an edge exists between two nodes in the graph.
      *
      * **Example** (Checking edge existence)
      *
@@ -1293,7 +1461,7 @@ export declare const hasEdge: {
      */
     (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.
+     * Checks whether an edge exists between two nodes in the graph.
      *
      * **Example** (Checking edge existence)
      *
@@ -1460,7 +1628,7 @@ export declare const neighbors: {
     <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.
+ * Gets neighbors of a node in a specific direction for bidirectional traversal.
  *
  * **Example** (Traversing directed neighbors)
  *
@@ -1488,7 +1656,7 @@ export declare const neighbors: {
  */
 export declare const neighborsDirected: {
     /**
-     * Get neighbors of a node in a specific direction for bidirectional traversal.
+     * Gets neighbors of a node in a specific direction for bidirectional traversal.
      *
      * **Example** (Traversing directed neighbors)
      *
@@ -1516,7 +1684,7 @@ export declare const neighborsDirected: {
      */
     (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.
+     * Gets neighbors of a node in a specific direction for bidirectional traversal.
      *
      * **Example** (Traversing directed neighbors)
      *
@@ -2437,7 +2605,7 @@ export declare const toMermaid: {
  */
 export type Direction = "outgoing" | "incoming";
 /**
- * Checks if the graph is acyclic (contains no cycles).
+ * Checks whether the graph is acyclic (contains no cycles).
  *
  * **Details**
  *
@@ -2475,7 +2643,7 @@ export type Direction = "outgoing" | "incoming";
  */
 export declare const isAcyclic: <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => boolean;
 /**
- * Checks if an undirected graph is bipartite.
+ * Checks whether an undirected graph is bipartite.
  *
  * **Details**
  *
@@ -2517,7 +2685,7 @@ export declare const isAcyclic: <N, E, T extends Kind = "directed">(graph: Graph
  */
 export declare const isBipartite: <N, E>(graph: Graph<N, E, "undirected"> | MutableGraph<N, E, "undirected">) => boolean;
 /**
- * Find connected components in an undirected graph.
+ * Finds connected components in an undirected graph.
  * Each component is represented as an array of node indices.
  *
  * **Example** (Finding connected components)
@@ -2543,7 +2711,7 @@ export declare const isBipartite: <N, E>(graph: Graph<N, E, "undirected"> | Muta
  */
 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.
+ * Finds strongly connected components in a directed graph using Kosaraju's algorithm.
  * Each SCC is represented as an array of node indices.
  *
  * **Example** (Finding strongly connected components)
@@ -2571,11 +2739,27 @@ export declare const stronglyConnectedComponents: <N, E, T extends Kind = "direc
 /**
  * Result of a shortest path computation.
  *
+ * **When to use**
+ *
+ * Use to read the successful source-to-target shortest path returned by
+ * path-finding algorithms, including the ordered node indices, total distance,
+ * and traversed edge data.
+ *
  * **Details**
  *
  * Contains the node-index path, the total numeric distance, and the edge data
  * encountered along the path.
  *
+ * **Gotchas**
+ *
+ * `costs` contains original edge data, not the numeric output of the cost
+ * function unless the edge data is numeric.
+ *
+ * @see {@link dijkstra} for shortest paths with non-negative edge costs
+ * @see {@link astar} for heuristic shortest-path search
+ * @see {@link bellmanFord} for shortest paths that may include negative edge weights
+ * @see {@link AllPairsResult} for the all-pairs shortest-path result shape
+ *
  * @category models
  * @since 3.18.0
  */
@@ -2587,11 +2771,25 @@ export interface PathResult<E> {
 /**
  * Configuration for finding a shortest path with Dijkstra's algorithm.
  *
+ * **When to use**
+ *
+ * Use when configuring `dijkstra` to find a shortest path between two existing
+ * node indices with non-negative edge costs.
+ *
  * **Details**
  *
  * Specifies the source and target node indices, plus a cost function that maps
  * each edge's data to a non-negative numeric weight.
  *
+ * **Gotchas**
+ *
+ * `dijkstra` throws a `GraphError` when either endpoint does not exist or when
+ * the cost function returns a negative weight.
+ *
+ * @see {@link dijkstra} for the algorithm that consumes this configuration
+ * @see {@link AstarConfig} for heuristic shortest-path search
+ * @see {@link BellmanFordConfig} for shortest paths that may include negative edge weights
+ *
  * @category models
  * @since 3.18.0
  */
@@ -2724,11 +2922,20 @@ export declare const dijkstra: {
 /**
  * Result of an all-pairs shortest path computation.
  *
+ * **When to use**
+ *
+ * Use when storing or passing around the complete output of `floydWarshall` so
+ * callers can look up shortest distances, node paths, and edge data for any
+ * source and target node pair.
+ *
  * **Details**
  *
  * Contains distance, node-path, and edge-data maps keyed by source and target
  * node indices.
  *
+ * @see {@link floydWarshall} for computing an all-pairs shortest path result
+ * @see {@link PathResult} for the single source-to-target result shape used by path-finding algorithms
+ *
  * @category models
  * @since 3.18.0
  */
@@ -2840,11 +3047,20 @@ export declare const floydWarshall: {
 /**
  * Configuration for finding a shortest path with the A* algorithm.
  *
+ * **When to use**
+ *
+ * Use when configuring `astar` for point-to-point shortest-path searches where
+ * node data can provide a heuristic estimate toward the target.
+ *
  * **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.
  *
+ * @see {@link astar} for the algorithm that consumes this configuration
+ * @see {@link DijkstraConfig} for shortest paths without a heuristic
+ * @see {@link BellmanFordConfig} for shortest paths that may include negative edge weights
+ *
  * @category models
  * @since 3.18.0
  */
@@ -2999,11 +3215,20 @@ export declare const astar: {
 /**
  * Configuration for finding a shortest path with the Bellman-Ford algorithm.
  *
+ * **When to use**
+ *
+ * Use when configuring `bellmanFord` to find a shortest path where edge
+ * weights may be negative.
+ *
  * **Details**
  *
  * Specifies the source and target node indices, plus a cost function that maps
  * each edge's data to a numeric weight.
  *
+ * @see {@link bellmanFord} for the algorithm that consumes this configuration
+ * @see {@link DijkstraConfig} for non-negative edge costs
+ * @see {@link AstarConfig} for heuristic shortest-path search
+ *
  * @category models
  * @since 3.18.0
  */
@@ -3134,7 +3359,7 @@ export declare const bellmanFord: {
     <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>, config: BellmanFordConfig<E>): Option.Option<PathResult<E>>;
 };
 /**
- * Iterable wrapper used by graph traversal and listing APIs.
+ * Represents an iterable wrapper used by graph traversal and listing APIs.
  *
  * **Details**
  *
@@ -3249,6 +3474,14 @@ export declare class Walker<T, N> implements Iterable<[T, N]> {
  * Type alias for node iteration using Walker.
  * NodeWalker is represented as Walker<NodeIndex, N>.
  *
+ * **When to use**
+ *
+ * Use as the shared node walker type returned by graph traversal and node
+ * listing APIs.
+ *
+ * @see {@link Walker} for the generic lazy iterator wrapper
+ * @see {@link EdgeWalker} for edge iterators
+ *
  * @category models
  * @since 3.18.0
  */
@@ -3257,6 +3490,16 @@ export type NodeWalker<N> = Walker<NodeIndex, N>;
  * Type alias for edge iteration using Walker.
  * EdgeWalker is represented as Walker<EdgeIndex, Edge<E>>.
  *
+ * **When to use**
+ *
+ * Use to type helpers or parameters that consume edge iterators returned by
+ * `Graph` APIs, where each item is keyed by an `EdgeIndex` and carries the
+ * full `Edge`.
+ *
+ * @see {@link Walker} for the generic lazy iterator wrapper
+ * @see {@link NodeWalker} for node iterators
+ * @see {@link edges} for creating edge walkers
+ *
  * @category models
  * @since 3.18.0
  */
@@ -3333,12 +3576,26 @@ export declare const entries: <T, N>(walker: Walker<T, N>) => Iterable<[T, N]>;
 /**
  * Configuration for DFS, BFS, and postorder graph traversals.
  *
+ * **When to use**
+ *
+ * Use to configure the starting node indices and edge-following direction for
+ * lazy 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.
  *
+ * **Gotchas**
+ *
+ * Traversal creation throws a `GraphError` when any configured `start` node
+ * does not exist.
+ *
+ * @see {@link dfs} for depth-first traversal
+ * @see {@link bfs} for breadth-first traversal
+ * @see {@link dfsPostOrder} for depth-first postorder traversal
+ *
  * @category models
  * @since 3.18.0
  */
@@ -3579,12 +3836,19 @@ export declare const bfs: {
 /**
  * Configuration for the topological sort iterator.
  *
+ * **When to use**
+ *
+ * Use to seed a topological sort with specific initial node indices instead of
+ * starting from every zero in-degree node.
+ *
  * **Details**
  *
  * `initials` optionally supplies the node indices used as initial queue
  * entries. When omitted, topological sorting starts from all nodes with zero
  * in-degree.
  *
+ * @see {@link topo} for the iterator that consumes this configuration
+ *
  * @category models
  * @since 3.18.0
  */
@@ -3896,11 +4160,19 @@ export declare const edges: <N, E, T extends Kind = "directed">(graph: Graph<N,
 /**
  * Configuration for selecting external nodes.
  *
+ * **When to use**
+ *
+ * Use to configure how `externals` identifies graph boundary nodes when you
+ * need sinks with no outgoing edges or sources with no incoming edges.
+ *
  * **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.
+ * nodes with no incoming edges. If omitted, `direction` defaults to
+ * `"outgoing"`.
+ *
+ * @see {@link externals} for the iterator that consumes this configuration
  *
  * @category models
  * @since 3.18.0