effect 4.0.0-beta.70 → 4.0.0-beta.71

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,6 +94,21 @@ 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
  */
@@ -85,6 +117,15 @@ export type EdgeIndex = number
 /**
  * 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
  */
@@ -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
  */
@@ -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
  */
@@ -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

package/src/HKT.ts

@@ -1,36 +1,52 @@
 /**
- * This module provides utilities for Higher-Kinded Types (HKT) in TypeScript.
+ * Type-level encoding for higher-kinded types in Effect.
  *
- * Higher-Kinded Types are types that take other types as parameters, similar to how
- * functions take values as parameters. They enable generic programming over type
- * constructors, allowing you to write code that works with any container type
- * (like Array, Option, Effect, etc.) in a uniform way.
+ * TypeScript cannot abstract directly over type constructors such as
+ * `Option<_>`, `ReadonlyArray<_>`, or `Effect<_, _, _>`. This module encodes
+ * those constructors with {@link TypeLambda} and applies them with
+ * {@link Kind}, so libraries can define generic APIs that work across many
+ * Effect data types.
  *
- * The HKT system in Effect uses TypeLambdas to encode type-level functions that
- * can represent complex type relationships with multiple type parameters, including
- * contravariant, covariant, and invariant positions.
+ * **Mental model**
  *
- * **Example** (Encoding type lambdas)
+ * - A {@link TypeLambda} is a type-level function with four slots: `In`,
+ *   `Out2`, `Out1`, and `Target`
+ * - A concrete type lambda defines `readonly type` in terms of those slots
+ * - {@link Kind} fills the slots and reads the lambda's resulting concrete type
+ * - {@link TypeClass} lets an interface carry the lambda it implements through
+ *   {@link URI}
+ * - Effect modules expose their own type lambdas when they support generic
+ *   higher-kinded programming
+ *
+ * **Common tasks**
+ *
+ * - Define a type lambda for a data type by extending {@link TypeLambda}
+ * - Apply a lambda to type arguments with {@link Kind}
+ * - Write type class interfaces that are parameterized by a lambda
+ *
+ * **Gotchas**
+ *
+ * - The slot names are positional; check the concrete lambda to see how `In`,
+ *   `Out2`, `Out1`, and `Target` map to that data type's parameters
+ * - Use `never` for slots that a lambda does not read
+ * - HKT values are type-level encodings; they do not create runtime wrappers
+ *
+ * **Example** (Defining a simple type lambda)
  *
  * ```ts
  * import type { HKT } from "effect"
  *
- * // Define a TypeLambda for Array
- * interface ArrayTypeLambda extends HKT.TypeLambda {
- *   readonly type: Array<this["Target"]>
+ * interface ReadonlyArrayTypeLambda extends HKT.TypeLambda {
+ *   readonly type: ReadonlyArray<this["Target"]>
  * }
  *
- * // Use Kind to get the concrete type
- * type MyArray = HKT.Kind<ArrayTypeLambda, never, never, never, string>
- * // MyArray is Array<string>
- *
- * // Define a TypeClass that works with any HKT
- * interface Functor<F extends HKT.TypeLambda> extends HKT.TypeClass<F> {
- *   map<A, B>(
- *     fa: HKT.Kind<F, never, never, never, A>,
- *     f: (a: A) => B
- *   ): HKT.Kind<F, never, never, never, B>
- * }
+ * type StringArray = HKT.Kind<
+ *   ReadonlyArrayTypeLambda,
+ *   never,
+ *   never,
+ *   never,
+ *   string
+ * >
  * ```
  *
  * @since 2.0.0
@@ -40,6 +56,10 @@ import type * as Types from "./Types.ts"
 /**
  * A unique symbol used to associate `TypeClass` implementations with their `TypeLambda`.
  *
+ * **When to use**
+ *
+ * Use to link type class implementations to the `TypeLambda` they operate on.
+ *
  * **Details**
  *
  * This symbol is used internally by the HKT system to link runtime type class
@@ -77,6 +97,10 @@ export declare const URI: unique symbol
 /**
  * Base interface for type classes that work with Higher-Kinded Types.
  *
+ * **When to use**
+ *
+ * Use to define type class interfaces parameterized by a `TypeLambda`.
+ *
  * **Details**
  *
  * A `TypeClass` defines operations that can be performed on any type constructor
@@ -115,6 +139,10 @@ export interface TypeClass<F extends TypeLambda> {
 /**
  * Base interface for defining Higher-Kinded Type parameters.
  *
+ * **When to use**
+ *
+ * Use to encode a type constructor for higher-kinded generic programming.
+ *
  * **Details**
  *
  * A `TypeLambda` encodes the "shape" of a type constructor, specifying how many
@@ -157,6 +185,10 @@ export interface TypeLambda {
 /**
  * Applies type parameters to a `TypeLambda` to get the concrete type.
  *
+ * **When to use**
+ *
+ * Use to apply a `TypeLambda` to type parameters and obtain its concrete type.
+ *
  * **Details**
  *
  * This type-level function takes a `TypeLambda` and four type parameters, then