effect 4.0.0-beta.77 → 4.0.0-beta.79

package/src/FileSystem.ts

@@ -1,55 +1,12 @@
 /**
- * Effect service for reading, writing, inspecting, and watching files.
- *
- * The `FileSystem` service is the portable boundary between Effect programs and
- * the host file system. Programs depend on the service from `effect/FileSystem`;
- * platform packages provide concrete layers at the edge. Operations return
- * `Effect`, `Stream`, or `Sink` values and report failures as `PlatformError`
- * instead of throwing.
- *
- * **Mental model**
- *
- * `FileSystem` is a capability, not a global singleton. Request it with
- * `yield* FileSystem.FileSystem` inside an effect, compose file work like any
- * other effect, and provide a platform or test implementation when the program
- * is run. Scoped operations such as `open`, `makeTempFileScoped`, and
- * `makeTempDirectoryScoped` bind resource cleanup to `Scope`.
- *
- * **Common tasks**
- *
- * - Create, copy, rename, remove, chmod, chown, link, and symlink paths.
- * - Read and write whole files as bytes or strings.
- * - Stream large files with `stream` and `sink`, using binary size helpers such
- *   as `KiB` and `MiB` for chunk sizes and offsets.
- * - Inspect metadata with `stat`, check accessibility with `access` or
- *   `exists`, and canonicalize paths with `realPath`.
- * - Watch files or directories with `watch` when the platform implementation
- *   supports it.
- *
- * **Example** (Write and clean up a temporary file)
- *
- * ```ts
- * import { Effect, FileSystem } from "effect"
- *
- * const program = Effect.gen(function*() {
- *   const fs = yield* FileSystem.FileSystem
- *
- *   const directory = yield* fs.makeTempDirectoryScoped()
- *   const path = `${directory}/message.txt`
- *
- *   yield* fs.writeFileString(path, "hello")
- *   return yield* fs.readFileString(path)
- * })
- * ```
- *
- * **Gotchas**
- *
- * Paths are interpreted by the provided implementation, so relative paths, case
- * sensitivity, permissions, links, and watch behavior are platform-dependent.
- * Size options are normalized to branded bigint byte counts; prefer the `Size`,
- * `KiB`, `MiB`, and related helpers for offsets, chunk sizes, and truncation
- * lengths. A program that uses this service still needs a concrete layer, such
- * as `NodeFileSystem.layer`, before it can access the real file system.
+ * Defines the portable file system service for Effect programs.
+ *
+ * `FileSystem` is the boundary between Effect code and the host file system.
+ * Platform packages provide concrete layers, while this module defines the
+ * operations for reading, writing, inspecting, streaming, and watching files.
+ * Operations return `Effect`, `Stream`, or `Sink` values and fail with
+ * `PlatformError`. The module also includes file handles, size helpers, open
+ * flags, watch events, and the watch backend service.
  *
  * @since 4.0.0
  */

package/src/Filter.ts

@@ -1,37 +1,12 @@
 /**
- * The `Filter` module provides composable functions for accepting, rejecting,
- * narrowing, and transforming values. A `Filter<Input, Pass, Fail>` receives an
- * input and returns a `Result`: success means the value passed the filter, while
- * failure means the value was filtered out.
- *
- * **Mental model**
- *
- * - A filter is a typed predicate that can also transform the successful value
- * - Predicate-based filters pass the original input when the predicate returns `true`
- * - Refinement-based filters narrow the successful type, for example from `unknown` to `string`
- * - Custom filters return `Result.succeed(pass)` or `Result.fail(fail)` directly
- * - Filters compose with logical and sequential combinators instead of throwing exceptions
- * - `FilterEffect` is the effectful form for filters that need asynchronous work, errors, or services
- *
- * **Common tasks**
- *
- * - Build filters: {@link make}, {@link makeEffect}, {@link fromPredicate}, {@link fromPredicateOption}
- * - Narrow unknown values: {@link string}, {@link number}, {@link boolean}, {@link bigint}, {@link symbol}, {@link date}
- * - Match shapes and variants: {@link instanceOf}, {@link tagged}, {@link reason}, {@link has}
- * - Match exact values: {@link equals}, {@link equalsStrict}
- * - Combine alternatives: {@link or}
- * - Require multiple filters: {@link zip}, {@link zipWith}, {@link andLeft}, {@link andRight}
- * - Run filters in sequence: {@link compose}, {@link composePassthrough}
- * - Convert results: {@link toPredicate}, {@link toOption}, {@link toResult}
- * - Adjust failure values: {@link mapFail}
- *
- * **Gotchas**
- *
- * - A failed filter is data in the `Result` failure channel; it is not an exception
- * - `compose` preserves intermediate failure values, while {@link composePassthrough} fails with the original input
- * - `equalsStrict` uses JavaScript `===`; use {@link equals} for structural equality
- * - `fromPredicateOption` fails with the original input when the returned `Option` is `None`
- * - Prefer refinement predicates when you want TypeScript to narrow the successful value type
+ * Defines composable checks that can also transform values.
+ *
+ * A `Filter<Input, Pass, Fail>` receives an input and returns a `Result`.
+ * Success means the value passed the filter, and failure means the value was
+ * filtered out. Filters may also narrow or transform the passing value. This
+ * module includes constructors from predicates, options, and effects, built-in
+ * filters for common JavaScript values and tags, helpers for combining filters,
+ * and conversions to predicates, options, and results.
  *
  * @since 4.0.0
  */

package/src/Formatter.ts

@@ -1,54 +1,11 @@
 /**
- * Utilities for converting arbitrary JavaScript values into human-readable
- * strings, with support for circular references, redaction, and common JS
- * types that `JSON.stringify` handles poorly.
- *
- * Mental model:
- * - A `Formatter<Value, Format>` is a callable `(value: Value) => Format`.
- * - {@link format} is the general-purpose pretty-printer: it handles
- *   primitives, arrays, objects, `BigInt`, `Symbol`, `Date`, `RegExp`,
- *   `Set`, `Map`, class instances, and circular references.
- * - {@link formatJson} is a safe `JSON.stringify` wrapper that silently
- *   drops circular references and applies redaction.
- * - Both functions accept a `space` option for indentation control.
- *
- * Common tasks:
- * - Pretty-print any value for debugging / logging -> {@link format}
- * - Serialize to JSON safely (no circular throws) -> {@link formatJson}
- * - Format a single object property key -> {@link formatPropertyKey}
- * - Format a property path like `["a"]["b"]` -> {@link formatPath}
- * - Format a `Date` to ISO string safely -> {@link formatDate}
- *
- * Gotchas:
- * - {@link format} output is **not** valid JSON; use {@link formatJson} when
- *   you need parseable JSON.
- * - {@link format} calls `toString()` on objects by default; pass
- *   `ignoreToString: true` to disable.
- * - {@link formatJson} silently omits circular references (the key is
- *   dropped from the output).
- * - Values implementing the `Redactable` protocol are automatically
- *   redacted by both {@link format} and {@link formatJson}.
- *
- * **Example** (Pretty-print a value)
+ * Formats JavaScript values into readable strings.
  *
- * ```ts
- * import { Formatter } from "effect"
- *
- * const obj = { name: "Alice", scores: [100, 97] }
- * console.log(Formatter.format(obj))
- * // {"name":"Alice","scores":[100,97]}
- *
- * console.log(Formatter.format(obj, { space: 2 }))
- * // {
- * //   "name": "Alice",
- * //   "scores": [
- * //     100,
- * //     97
- * //   ]
- * // }
- * ```
- *
- * See also: {@link Formatter}, {@link format}, {@link formatJson}
+ * `format` is intended for logs, diagnostics, and error messages. It handles
+ * primitives, objects, arrays, dates, regular expressions, maps, sets, class
+ * instances, errors, circular references, and redactable values. `formatJson`
+ * wraps JSON formatting with redaction and circular-reference handling, and the
+ * module also includes helpers for property keys, paths, and dates.
  *
  * @since 4.0.0
  */

package/src/Function.ts

@@ -1,48 +1,10 @@
 /**
- * The `Function` module provides small, pure helpers for defining, composing,
- * adapting, and reusing TypeScript functions. It is the foundation for the
- * data-first and data-last APIs used throughout Effect, and it includes the
- * core pipeline utilities that make those APIs ergonomic.
- *
- * **Mental model**
- *
- * - {@link pipe} starts with a value and passes it through one unary function at
- *   a time
- * - {@link flow} composes unary functions into a reusable function
- * - {@link dual} builds APIs that support both direct calls and `pipe`-friendly
- *   data-last calls
- * - {@link identity}, {@link constant}, and the `const*` helpers model common
- *   identity and thunk patterns without allocating ad hoc callbacks
- * - {@link tupled}, {@link untupled}, {@link flip}, and {@link apply} adapt
- *   call shapes without changing the underlying behavior
- * - Type helpers such as {@link LazyArg}, {@link FunctionN}, {@link satisfies},
- *   and {@link cast} describe or constrain functions at the type level
- *
- * **Common tasks**
- *
- * - Build readable transformation pipelines: {@link pipe}
- * - Create reusable composed functions: {@link flow}, {@link compose}
- * - Define functions callable in both data-first and data-last style: {@link dual}
- * - Return a value unchanged: {@link identity}
- * - Create thunks and common constant functions: {@link constant},
- *   {@link constTrue}, {@link constFalse}, {@link constNull},
- *   {@link constUndefined}, {@link constVoid}
- * - Convert between rest-argument and tuple-argument functions: {@link tupled},
- *   {@link untupled}
- * - Express impossible branches: {@link absurd}
- * - Cache results for object keys: {@link memoize}
+ * Provides small helpers for defining and reusing TypeScript functions.
  *
- * **Gotchas**
- *
- * - Functions passed to {@link pipe} and {@link flow} are applied left-to-right
- *   and should be unary at each step
- * - {@link dual} uses either an arity or a predicate to decide whether a call is
- *   data-first or data-last; use a predicate when optional arguments make arity
- *   ambiguous
- * - {@link cast} changes only the static TypeScript type and performs no runtime
- *   validation
- * - {@link memoize} is intended for object keys and stores cached values in a
- *   `WeakMap`
+ * The main helpers are `pipe` and `flow` for left-to-right composition and
+ * `dual` for APIs that support both direct and pipe-friendly call styles. The
+ * module also contains small identity, constant, tuple, type-level, and
+ * memoization helpers used across the library.
  *
  * @since 2.0.0
  */

package/src/Graph.ts

@@ -1,53 +1,10 @@
 /**
- * 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}
+ * Models relationships between indexed nodes and edges.
  *
- * **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.
+ * This module provides immutable and scoped-mutable graph data structures. A
+ * graph can be directed or undirected, and it can store user-defined data on
+ * both nodes and edges. The module includes traversal, analysis, path-finding,
+ * transformation, and diagram export utilities.
  *
  * @since 4.0.0
  */
@@ -3579,6 +3536,37 @@ export const isAcyclic = <N, E, T extends Kind = "directed">(
     return graph.acyclic.value
   }
 
+  if (graph.type === "undirected") {
+    const visited = new Set<NodeIndex>()
+
+    for (const startNode of graph.nodes.keys()) {
+      if (visited.has(startNode)) {
+        continue
+      }
+
+      visited.add(startNode)
+      const stack: Array<{ node: NodeIndex; parent: NodeIndex | null }> = [{ node: startNode, parent: null }]
+
+      while (stack.length > 0) {
+        const { node, parent } = stack.pop()!
+        const nodeNeighbors = getUndirectedNeighbors(graph as any, node)
+
+        for (const neighbor of nodeNeighbors) {
+          if (!visited.has(neighbor)) {
+            visited.add(neighbor)
+            stack.push({ node: neighbor, parent: node })
+          } else if (neighbor !== parent) {
+            graph.acyclic = Option.some(false)
+            return false
+          }
+        }
+      }
+    }
+
+    graph.acyclic = Option.some(true)
+    return true
+  }
+
   // Stack-safe DFS cycle detection using iterative approach
   const visited = new Set<NodeIndex>()
   const recursionStack = new Set<NodeIndex>()
@@ -3762,6 +3750,21 @@ const getUndirectedNeighbors = <N, E>(
   return Array.from(neighbors)
 }
 
+const getTraversalNeighbors = <N, E, T extends Kind>(
+  graph: Graph<N, E, T> | MutableGraph<N, E, T>,
+  nodeIndex: NodeIndex,
+  direction: Direction
+): Array<NodeIndex> =>
+  graph.type === "undirected"
+    ? getUndirectedNeighbors(graph as any, nodeIndex)
+    : neighborsDirected(graph, nodeIndex, direction)
+
+const getTraversableNeighbor = <E, T extends Kind>(
+  graph: Graph<unknown, E, T> | MutableGraph<unknown, E, T>,
+  current: NodeIndex,
+  edge: Edge<E>
+): NodeIndex => graph.type === "undirected" && edge.target === current ? edge.source : edge.target
+
 /**
  * Finds connected components in an undirected graph.
  * Each component is represented as an array of node indices.
@@ -4198,7 +4201,7 @@ export const dijkstra: {
       for (const edgeIndex of adjacencyList) {
         const edge = graph.edges.get(edgeIndex)
         if (edge !== undefined) {
-          const neighbor = edge.target
+          const neighbor = getTraversableNeighbor(graph, currentNode, edge)
           const cost = config.cost(edge.data)
 
           // Validate non-negative weights
@@ -4419,6 +4422,15 @@ export const floydWarshall: {
       next.get(i)!.set(j, j)
       edgeMatrix.get(i)!.set(j, edgeData.data)
     }
+
+    if (graph.type === "undirected") {
+      const reverseWeight = distances.get(j)!.get(i)!
+      if (weight < reverseWeight) {
+        distances.get(j)!.set(i, weight)
+        next.get(j)!.set(i, i)
+        edgeMatrix.get(j)!.set(i, edgeData.data)
+      }
+    }
   }
 
   // Floyd-Warshall main loop
@@ -4746,7 +4758,7 @@ export const astar: {
       for (const edgeIndex of adjacencyList) {
         const edge = graph.edges.get(edgeIndex)
         if (edge !== undefined) {
-          const neighbor = edge.target
+          const neighbor = getTraversableNeighbor(graph, currentNode, edge)
           const weight = config.cost(edge.data)
 
           // Validate non-negative weights
@@ -5000,6 +5012,14 @@ export const bellmanFord: {
       weight,
       edgeData: edgeData.data
     })
+    if (graph.type === "undirected" && edgeData.source !== edgeData.target) {
+      edges.push({
+        source: edgeData.target,
+        target: edgeData.source,
+        weight,
+        edgeData: edgeData.data
+      })
+    }
   }
 
   // Relax edges up to V-1 times
@@ -5041,14 +5061,8 @@ export const bellmanFord: {
         affectedNodes.add(node)
 
         // Add all nodes reachable from this node
-        const adjacencyList = graph.adjacency.get(node)
-        if (adjacencyList !== undefined) {
-          for (const edgeIndex of adjacencyList) {
-            const edge = graph.edges.get(edgeIndex)
-            if (edge !== undefined) {
-              queue.push(edge.target)
-            }
-          }
+        for (const neighbor of getTraversalNeighbors(graph, node, "outgoing")) {
+          queue.push(neighbor)
         }
       }
 
@@ -5496,7 +5510,7 @@ export const dfs: {
             continue
           }
 
-          const neighbors = neighborsDirected(graph, current, direction)
+          const neighbors = getTraversalNeighbors(graph, current, direction)
           for (let i = neighbors.length - 1; i >= 0; i--) {
             const neighbor = neighbors[i]
             if (!discovered.has(neighbor)) {
@@ -5655,7 +5669,7 @@ export const bfs: {
           if (!discovered.has(current)) {
             discovered.add(current)
 
-            const neighbors = neighborsDirected(graph, current, direction)
+            const neighbors = getTraversalNeighbors(graph, current, direction)
             for (const neighbor of neighbors) {
               if (!discovered.has(neighbor)) {
                 queue.push(neighbor)
@@ -5846,6 +5860,10 @@ export const topo: {
   graph: Graph<N, E, T> | MutableGraph<N, E, T>,
   config: TopoConfig = {}
 ): NodeWalker<N> => {
+  if (graph.type === "undirected") {
+    throw new GraphError({ message: "Cannot perform topological sort on undirected graph" })
+  }
+
   // Check if graph is acyclic first
   if (!isAcyclic(graph)) {
     throw new GraphError({ message: "Cannot perform topological sort on cyclic graph" })
@@ -6063,7 +6081,7 @@ export const dfsPostOrder: {
 
           if (!current.visitedChildren) {
             current.visitedChildren = true
-            const neighbors = neighborsDirected(graph, current.node, direction)
+            const neighbors = getTraversalNeighbors(graph, current.node, direction)
 
             for (let i = neighbors.length - 1; i >= 0; i--) {
               const neighbor = neighbors[i]

package/src/HKT.ts

@@ -1,53 +1,11 @@
 /**
- * Type-level encoding for higher-kinded types in Effect.
+ * Provides type-level helpers for generic code over container-like types.
  *
- * 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.
- *
- * **Mental model**
- *
- * - 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"
- *
- * interface ReadonlyArrayTypeLambda extends HKT.TypeLambda {
- *   readonly type: ReadonlyArray<this["Target"]>
- * }
- *
- * type StringArray = HKT.Kind<
- *   ReadonlyArrayTypeLambda,
- *   never,
- *   never,
- *   never,
- *   string
- * >
- * ```
+ * TypeScript cannot directly abstract over shapes such as `Option<A>`,
+ * `ReadonlyArray<A>`, or `Effect<A, E, R>`. This module represents those shapes
+ * with `TypeLambda` and applies concrete type arguments with `Kind`. It is
+ * mostly useful when defining generic helpers or type classes that should work
+ * across several data types.
  *
  * @since 2.0.0
  */

package/src/Hash.ts

@@ -1,53 +1,11 @@
 /**
- * The `Hash` module computes Effect hash values and defines the interface for
- * objects that want to provide their own hash implementation. Hashes are small
- * numeric fingerprints used by Effect data structures to bucket values quickly;
- * they are not cryptographic digests and they are not proof that two values are
- * equal.
- *
- * **Mental model**
- *
- * - {@link hash} dispatches by JavaScript type and handles primitives,
- *   arrays, typed arrays, maps, sets, plain objects, dates, regular
- *   expressions, and custom hashable objects
- * - Objects can implement {@link Hash} by defining a method at {@link symbol}
- * - Structural object hashes are cached, so repeated hashing of the same object
- *   is cheap after the first computation
- * - {@link random} gives reference-stable hash values for values that should
- *   be hashed by identity
- * - Lower-level helpers such as {@link combine}, {@link string},
- *   {@link number}, {@link structure}, {@link structureKeys}, and
- *   {@link array} are useful when implementing custom hashes
- *
- * **Quickstart**
- *
- * **Example** (Implementing a custom hash)
- *
- * ```ts
- * import { Hash } from "effect"
- *
- * class UserKey implements Hash.Hash {
- *   constructor(
- *     readonly id: string,
- *     readonly region: string
- *   ) {}
- *
- *   [Hash.symbol](): number {
- *     return Hash.combine(Hash.string(this.region))(Hash.string(this.id))
- *   }
- * }
- *
- * const value = Hash.hash(new UserKey("user-1", "eu"))
- * ```
- *
- * **Gotchas**
- *
- * - Hash collisions are possible; hash-based collections also need equality
- *   semantics to decide whether two values are actually the same
- * - Do not mutate an object after hashing it structurally, because the cached
- *   hash can become stale
- * - Use {@link random} or a custom {@link Hash} implementation for mutable
- *   objects that should be compared by reference identity
+ * Computes Effect hash values and defines the interface for objects that want
+ * to provide their own hash implementation. Hashes are small numeric
+ * fingerprints used by Effect data structures to bucket values quickly; they
+ * are not cryptographic digests and they are not proof that two values are
+ * equal. The module also includes helpers for primitive, structure, array, and
+ * reference-based hashes, plus functions for combining and optimizing numeric
+ * hash values.
  *
  * @since 2.0.0
  */

package/src/HashMap.ts

@@ -1,74 +1,11 @@
 /**
- * The `HashMap` module provides an immutable key-value data structure with
- * efficient lookup, insertion, removal, and transformation operations. A
- * `HashMap<Key, Value>` stores entries by hashing keys and resolving matches
- * with Effect's structural equality semantics.
- *
- * **Mental model**
- *
- * - A `HashMap<Key, Value>` is an immutable collection of key-value pairs
- * - Keys are compared using the `Equal` protocol and are grouped by hashes from
- *   the `Hash` protocol
- * - Plain JavaScript primitives work as keys, and custom objects can define
- *   `Equal` / `Hash` behavior for structural lookup
- * - Lookups with {@link get} return an `Option`, making missing keys explicit
- * - Iteration order is based on the map's internal hash structure and should
- *   not be treated as insertion order
- *
- * **Common tasks**
- *
- * - Create maps: {@link empty}, {@link make}, {@link fromIterable}
- * - Read values: {@link get}, {@link getUnsafe}, {@link has}, {@link hasBy}
- * - Add or update entries: {@link set}, {@link modify}, {@link modifyAt}, {@link setMany}
- * - Remove entries: {@link remove}, {@link removeMany}
- * - Combine maps: {@link union}
- * - Iterate or convert: {@link keys}, {@link values}, {@link entries}, {@link toValues}, {@link toEntries}
- * - Transform values: {@link map}, {@link flatMap}, {@link filter}, {@link filterMap}, {@link compact}
- * - Fold and search: {@link reduce}, {@link findFirst}, {@link some}, {@link every}
- * - Batch updates efficiently: {@link mutate}, {@link beginMutation}, {@link endMutation}
+ * Stores key/value entries in an immutable hash map.
  *
- * **Gotchas**
- *
- * - {@link getUnsafe} throws when the key is absent; prefer {@link get} unless
- *   absence is impossible by construction
- * - Mutating a key object after insertion can make future lookups fail if its
- *   equality or hash changes
- * - Hash collisions are handled by equality checks, so matching hashes alone do
- *   not make two keys equal
- * - Use {@link getHash} and {@link hasHash} only when you already have the
- *   correct hash for the same key
- * - Convert entries to an array and sort them when deterministic presentation is
- *   required
- *
- * **Quickstart**
- *
- * **Example** (Working with immutable maps)
- *
- * ```ts
- * import { HashMap, Option } from "effect"
- *
- * const scores = HashMap.make(["alice", 10], ["bob", 15])
- *
- * const updated = scores.pipe(
- *   HashMap.set("carol", 20),
- *   HashMap.modify("alice", (score) => score + 1)
- * )
- *
- * console.log(HashMap.get(updated, "alice"))
- * // Output: Option.some(11)
- *
- * console.log(HashMap.get(scores, "carol"))
- * // Output: Option.none()
- *
- * console.log(Option.getOrElse(HashMap.get(updated, "dave"), () => 0))
- * // Output: 0
- * ```
- *
- * **See also**
- *
- * - `HashSet` for immutable sets backed by hash semantics
- * - {@link Equal} for structural equality
- * - `Hash` for hash implementations used by hashed collections
+ * A `HashMap<Key, Value>` hashes keys and resolves matches with Effect's
+ * structural equality rules. Lookup, insertion, removal, and transformation
+ * operations return new maps, while temporary mutation helpers support efficient
+ * batch updates. This module also includes constructors, iteration, conversion,
+ * mapping, filtering, and reducing helpers.
  *
  * @since 2.0.0
  */