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

package/src/Graph.ts

@@ -69,6 +69,23 @@ 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
  */
@@ -77,13 +94,37 @@ 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
@@ -97,6 +138,14 @@ export 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
  */
@@ -127,6 +176,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
  */
@@ -138,6 +196,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
  */
@@ -147,7 +215,22 @@ export interface MutableGraph<out N, out E, T extends Kind = "directed"> extends
 }
 
 /**
- * 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
@@ -155,7 +238,20 @@ export interface MutableGraph<out N, out E, T extends Kind = "directed"> extends
 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
@@ -165,6 +261,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
  */
@@ -173,6 +278,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
  */
@@ -264,6 +378,11 @@ const ProtoGraph = {
  * 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
  */
@@ -282,6 +401,15 @@ const missingNode = (node: number) => new GraphError({ message: `Node ${node} do
  * 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
  */
@@ -539,6 +667,21 @@ export 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
@@ -552,6 +695,10 @@ export 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
  */
@@ -575,7 +722,7 @@ export const addNode = <N, E, T extends Kind = "directed">(
 }
 
 /**
- * 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)
  *
@@ -599,7 +746,7 @@ export const addNode = <N, E, T extends Kind = "directed">(
  */
 export 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)
    *
@@ -623,7 +770,7 @@ export 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)
    *
@@ -652,7 +799,7 @@ export const getNode: {
 ): Option.Option<N> => graph.nodes.has(nodeIndex) ? Option.some(graph.nodes.get(nodeIndex)!) : Option.none())
 
 /**
- * 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)
  *
@@ -677,7 +824,7 @@ export const getNode: {
  */
 export 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)
    *
@@ -702,7 +849,7 @@ export 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)
    *
@@ -1283,7 +1430,7 @@ export const mapEdges = <N, E, T extends Kind = "directed">(
 }
 
 /**
- * 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)
  *
@@ -1575,6 +1722,22 @@ const invalidateCycleFlagOnAddition = <N, E, T extends Kind = "directed">(
 /**
  * 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
@@ -1588,6 +1751,11 @@ const invalidateCycleFlagOnAddition = <N, E, T extends Kind = "directed">(
  * })
  * ```
  *
+ * @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
  */
@@ -1803,7 +1971,7 @@ const removeEdgeInternal = <N, E, T extends Kind = "directed">(
 // =============================================================================
 
 /**
- * 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)
  *
@@ -1835,7 +2003,7 @@ export 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)
    *
@@ -1867,7 +2035,7 @@ export 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)
    *
@@ -1900,7 +2068,7 @@ export const getEdge: {
 ): Option.Option<Edge<E>> => Option.fromUndefinedOr(graph.edges.get(edgeIndex)))
 
 /**
- * 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)
  *
@@ -1930,7 +2098,7 @@ export const getEdge: {
  */
 export 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)
    *
@@ -1960,7 +2128,7 @@ export 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)
    *
@@ -2178,7 +2346,7 @@ export const neighbors: {
 })
 
 /**
- * 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)
  *
@@ -2206,7 +2374,7 @@ export const neighbors: {
  */
 export 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)
    *
@@ -2234,7 +2402,7 @@ export 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)
    *
@@ -3367,7 +3535,7 @@ export type Direction = "outgoing" | "incoming"
 // =============================================================================
 
 /**
- * Checks if the graph is acyclic (contains no cycles).
+ * Checks whether the graph is acyclic (contains no cycles).
  *
  * **Details**
  *
@@ -3480,7 +3648,7 @@ export const isAcyclic = <N, E, T extends Kind = "directed">(
 }
 
 /**
- * Checks if an undirected graph is bipartite.
+ * Checks whether an undirected graph is bipartite.
  *
  * **Details**
  *
@@ -3595,7 +3763,7 @@ const getUndirectedNeighbors = <N, E>(
 }
 
 /**
- * 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)
@@ -3654,7 +3822,7 @@ export const connectedComponents = <N, E>(
 }
 
 /**
- * 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)
@@ -3778,11 +3946,27 @@ export const stronglyConnectedComponents = <N, E, T extends Kind = "directed">(
 /**
  * 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
  */
@@ -3795,11 +3979,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
  */
@@ -4058,11 +4256,20 @@ export 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
  */
@@ -4288,11 +4495,20 @@ export 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
  */
@@ -4597,11 +4813,20 @@ export 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
  */
@@ -4864,7 +5089,7 @@ export const bellmanFord: {
 })
 
 /**
- * Iterable wrapper used by graph traversal and listing APIs.
+ * Represents an iterable wrapper used by graph traversal and listing APIs.
  *
  * **Details**
  *
@@ -4987,6 +5212,14 @@ export 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
  */
@@ -4996,6 +5229,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
  */
@@ -5077,12 +5320,26 @@ export 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
  */
@@ -5424,12 +5681,19 @@ export 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
  */
@@ -5930,11 +6194,19 @@ export const edges = <N, E, T extends Kind = "directed">(
 /**
  * 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