effect 4.0.0-beta.83 → 4.0.0-beta.84

package/src/Effect.ts

@@ -1305,8 +1305,8 @@ export const promise: <A>(
 ) => Effect<A> = internal.promise
 
 /**
- * Creates an `Effect` that represents an asynchronous computation that might
- * fail.
+ * Creates an `Effect` from an asynchronous computation that may throw or
+ * reject, mapping failures into the error channel.
  *
  * **When to use**
  *
@@ -1316,19 +1316,24 @@ export const promise: <A>(
  *
  * **Details**
  *
- * Error Handling:
+ * The promise thunk is evaluated when the effect runs. If it returns a promise
+ * that resolves, the resolved value becomes the success value. If the thunk
+ * throws before returning a promise, or if the returned promise rejects, the
+ * thrown or rejected value is mapped into the error channel.
  *
- * There are two ways to handle errors with `tryPromise`:
+ * Passing the thunk directly maps failures to {@link Cause.UnknownError}.
+ * Passing `{ try, catch }` uses `catch` to map failures to an error of type
+ * `E`.
  *
- * 1. If you don't provide a `catch` function, the error is caught and the
- *    effect fails with an `UnknownError`.
- * 2. If you provide a `catch` function, the error is caught and the `catch`
- *    function maps it to an error of type `E`.
+ * The thunk receives an `AbortSignal` that is aborted if the effect is
+ * interrupted. The underlying asynchronous operation only stops if it observes
+ * that signal.
  *
- * Interruptions:
+ * **Gotchas**
  *
- * An optional `AbortSignal` can be provided to allow for interruption of the
- * wrapped `Promise` API.
+ * If `catch` throws while mapping the error, that thrown value is treated as a
+ * defect. Return the error value you want in the error channel instead of
+ * throwing it.
  *
  * **Example** (Wrapping a fetch request that may fail)
  *
@@ -2190,7 +2195,7 @@ export const failCauseSync: <E>(
  * The error channel of the resulting effect is of type `never`, indicating that
  * it cannot recover from this failure.
  *
- * **Example** (Failing when division by zero)
+ * **Example** (Failing on division by zero)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -2215,53 +2220,56 @@ export const failCauseSync: <E>(
  */
 export const die: (defect: unknown) => Effect<never> = internal.die
 
-const try_: <A, E>(options: {
-  try: LazyArg<A>
-  catch: (error: unknown) => E
-}) => Effect<A, E> = internal.try
+const try_: <A, E = Cause.UnknownError>(
+  options: {
+    readonly try: LazyArg<A>
+    readonly catch: (error: unknown) => E
+  } | LazyArg<A>
+) => Effect<A, E> = internal.try
 
 export {
   /**
-   * Creates an `Effect` that represents a synchronous computation that might
-   * fail.
+   * Creates an `Effect` from a synchronous computation that may throw, mapping
+   * thrown values into the error channel.
    *
    * **When to use**
    *
    * Use when you need to perform synchronous operations that might throw, such
-   * as parsing JSON, and convert thrown exceptions into typed Effect failures.
+   * as parsing JSON, and want thrown exceptions captured as Effect errors.
    *
    * **Details**
    *
-   * Error Handling:
+   * The thunk is evaluated when the effect runs. If it returns normally, the
+   * returned value becomes the success value. If it throws, the thrown value is
+   * mapped into the error channel.
    *
-   * There are two ways to handle errors with `try`:
+   * Passing the thunk directly maps failures to {@link Cause.UnknownError}.
+   * Passing `{ try, catch }` uses `catch` to map failures to an error of type
+   * `E`.
    *
-   * 1. If you don't provide a `catch` function, the error is caught and the
-   *    effect fails with an `UnknownError`.
-   * 2. If you provide a `catch` function, the error is caught and the `catch`
-   *    function maps it to an error of type `E`.
+   * **Gotchas**
+   *
+   * If `catch` throws while mapping the error, that thrown value is treated as
+   * a defect. Return the error value you want in the error channel instead of
+   * throwing it.
    *
-   * **Example** (Parsing JSON with typed error mapping)
+   * **Example** (Parsing JSON)
    *
    * ```ts
    * import { Effect } from "effect"
    *
    * const parseJSON = (input: string) =>
-   *   Effect.try({
-   *     try: () => JSON.parse(input),
-   *     catch: (error) => error as Error
-   *   })
+   *   Effect.try(() => JSON.parse(input))
    *
    * // Success case
    * Effect.runPromise(parseJSON("{\"name\": \"Alice\"}")).then(console.log)
    * // Output: { name: "Alice" }
    *
-   * // Failure case
+   * // Failure case maps the thrown value to UnknownError
    * Effect.runPromiseExit(parseJSON("invalid json")).then(console.log)
-   * // Output: Exit.failure with Error
    * ```
    *
-   * **Example** (Mapping synchronous exceptions to a tagged error)
+   * **Example** (Mapping exceptions to a tagged error)
    *
    * ```ts
    * import { Data, Effect } from "effect"
@@ -2417,6 +2425,42 @@ export const fromOption: <A>(
   option: Option<A>
 ) => Effect<A, Cause.NoSuchElementError> = internal.fromOption
 
+/**
+ * Converts an `Option` of an `Effect` into an `Effect` of an `Option`.
+ *
+ * **When to use**
+ *
+ * Use when an effect should run only when an optional value is present, while
+ * preserving absence as a successful `None`.
+ *
+ * **Details**
+ *
+ * - `None` becomes an effect that succeeds with `None`
+ * - `Some(effect)` runs the inner effect and wraps its success value in `Some`
+ * - Inner failures are preserved in the resulting effect
+ *
+ * **Example** (Transposing an Option of an Effect)
+ *
+ * ```ts
+ * import { Effect, Option } from "effect"
+ *
+ * const some = Option.some(Effect.succeed(42))
+ *
+ * //      ┌─── Effect<Option<number>, never, never>
+ * //      ▼
+ * const program = Effect.transposeOption(some)
+ *
+ * Effect.runPromise(program).then(console.log)
+ * // Output: { _id: 'Option', _tag: 'Some', value: 42 }
+ * ```
+ *
+ * @category converting
+ * @since 3.13.0
+ */
+export const transposeOption: <A = never, E = never, R = never>(
+  self: Option<Effect<A, E, R>>
+) => Effect<Option<A>, E, R> = internal.transposeOption
+
 /**
  * Converts a nullable value to an `Effect`, failing with a `NoSuchElementError`
  * when the value is `null` or `undefined`.
@@ -2468,7 +2512,7 @@ export const fromNullishOr: <A>(value: A) => Effect<NonNullable<A>, Cause.NoSuch
  * Since effects are immutable, `flatMap` always returns a new effect instead of
  * changing the original one.
  *
- * **Example** (Syntax)
+ * **Example** (Choosing flatMap syntax variants)
  *
  * ```ts
  * import { Effect, pipe } from "effect"
@@ -2539,7 +2583,7 @@ export const flatMap: {
    * Since effects are immutable, `flatMap` always returns a new effect instead of
    * changing the original one.
    *
-   * **Example** (Syntax)
+   * **Example** (Choosing flatMap syntax variants)
    *
    * ```ts
    * import { Effect, pipe } from "effect"
@@ -2610,7 +2654,7 @@ export const flatMap: {
    * Since effects are immutable, `flatMap` always returns a new effect instead of
    * changing the original one.
    *
-   * **Example** (Syntax)
+   * **Example** (Choosing flatMap syntax variants)
    *
    * ```ts
    * import { Effect, pipe } from "effect"
@@ -2701,7 +2745,7 @@ export const flatten: <A, E, R, E2, R2>(self: Effect<Effect<A, E, R>, E2, R2>) =
  * Failures or requirements from either effect are preserved in the returned
  * effect.
  *
- * **Example** (Syntax)
+ * **Example** (Choosing andThen syntax variants)
  *
  * ```ts
  * import { Effect, pipe } from "effect"
@@ -2777,7 +2821,7 @@ export const andThen: {
    * Failures or requirements from either effect are preserved in the returned
    * effect.
    *
-   * **Example** (Syntax)
+   * **Example** (Choosing andThen syntax variants)
    *
    * ```ts
    * import { Effect, pipe } from "effect"
@@ -2853,7 +2897,7 @@ export const andThen: {
    * Failures or requirements from either effect are preserved in the returned
    * effect.
    *
-   * **Example** (Syntax)
+   * **Example** (Choosing andThen syntax variants)
    *
    * ```ts
    * import { Effect, pipe } from "effect"
@@ -2929,7 +2973,7 @@ export const andThen: {
    * Failures or requirements from either effect are preserved in the returned
    * effect.
    *
-   * **Example** (Syntax)
+   * **Example** (Choosing andThen syntax variants)
    *
    * ```ts
    * import { Effect, pipe } from "effect"
@@ -3005,7 +3049,7 @@ export const andThen: {
    * Failures or requirements from either effect are preserved in the returned
    * effect.
    *
-   * **Example** (Syntax)
+   * **Example** (Choosing andThen syntax variants)
    *
    * ```ts
    * import { Effect, pipe } from "effect"
@@ -3498,7 +3542,7 @@ export const exit: <A, E, R>(
  * effect is not modified. Instead, a new effect is returned with the updated
  * value.
  *
- * **Example** (Syntax)
+ * **Example** (Choosing map syntax variants)
  *
  * ```ts
  * import { Effect, pipe } from "effect"
@@ -3554,7 +3598,7 @@ export const map: {
    * effect is not modified. Instead, a new effect is returned with the updated
    * value.
    *
-   * **Example** (Syntax)
+   * **Example** (Choosing map syntax variants)
    *
    * ```ts
    * import { Effect, pipe } from "effect"
@@ -3610,7 +3654,7 @@ export const map: {
    * effect is not modified. Instead, a new effect is returned with the updated
    * value.
    *
-   * **Example** (Syntax)
+   * **Example** (Choosing map syntax variants)
    *
    * ```ts
    * import { Effect, pipe } from "effect"
@@ -12879,7 +12923,7 @@ export const acquireDisposable: <A extends AsyncDisposable | Disposable, E, R>(
  * is not desired, errors produced by the `release` `Effect` value can be caught
  * and ignored.
  *
- * **Example** (Using a resource with cleanup)
+ * **Example** (Acquiring resources with cleanup)
  *
  * ```ts
  * import { Console, Effect, Exit } from "effect"

package/src/Equal.ts

@@ -26,7 +26,7 @@ import { hasProperty } from "./Predicate.ts"
  *
  * This is a pure constant with no allocation or side effects.
  *
- * **Example** (Implementing Equal on a Class)
+ * **Example** (Implementing Equal on a class)
  *
  * ```ts
  * import { Equal, Hash } from "effect"
@@ -74,7 +74,7 @@ export const symbol = "~effect/interfaces/Equal"
  * - {@link equals} delegates to this method when both operands implement it.
  *   If only one operand implements `Equal`, they are considered unequal.
  *
- * **Example** (Coordinate with Value Equality)
+ * **Example** (Comparing coordinates by value)
  *
  * ```ts
  * import { Equal, Hash } from "effect"
@@ -137,7 +137,7 @@ export interface Equal extends Hash.Hash {
  *   mutated after their first comparison.**
  * - Map and Set comparisons are O(n²) in size.
  *
- * **Example** (Comparing Values)
+ * **Example** (Comparing values)
  *
  * ```ts
  * import { Equal } from "effect"
@@ -404,7 +404,7 @@ const compareSets = makeCompareSet(compareBoth)
  *   {@link symbol}.
  * - Acts as a TypeScript type guard, narrowing the input to {@link Equal}.
  *
- * **Example** (Type Guard)
+ * **Example** (Checking Equal values)
  *
  * ```ts
  * import { Equal, Hash } from "effect"
@@ -445,7 +445,7 @@ export const isEqual = (u: unknown): u is Equal => hasProperty(u, symbol)
  *   {@link equals}.
  * - Pure; allocates a thin wrapper on each call.
  *
- * **Example** (Deduplicating with Equal Semantics)
+ * **Example** (Deduplicating with Equal semantics)
  *
  * ```ts
  * import { Array, Equal } from "effect"
@@ -479,7 +479,7 @@ export const asEquivalence: <A>() => Equivalence<A> = () => equals
  * - Each call creates a **new** proxy, so `byReference(x) !== byReference(x)`.
  * - Does **not** mutate the original object (unlike {@link byReferenceUnsafe}).
  *
- * **Example** (Opting Out of Structural Equality)
+ * **Example** (Opting out of structural equality)
  *
  * ```ts
  * import { Equal } from "effect"
@@ -524,7 +524,7 @@ export const byReference = <T extends object>(obj: T): T => byReferenceUnsafe(ne
  *
  * The marking is irreversible for the lifetime of the object.
  *
- * **Example** (Marking an Object for Reference Equality)
+ * **Example** (Marking an object for reference equality)
  *
  * ```ts
  * import { Equal } from "effect"

package/src/Equivalence.ts

@@ -25,7 +25,7 @@ import * as Reducer from "./Reducer.ts"
  * - Returns `boolean`: `true` if values are equivalent, `false` otherwise
  * - Must satisfy reflexive, symmetric, and transitive properties
  *
- * **Example** (Simple number equivalence)
+ * **Example** (Defining simple number equivalence)
  *
  * ```ts
  * import type { Equivalence } from "effect"
@@ -36,7 +36,7 @@ import * as Reducer from "./Reducer.ts"
  * console.log(numberEq(1, 2)) // false
  * ```
  *
- * **Example** (Custom object equivalence)
+ * **Example** (Defining custom object equivalence)
  *
  * ```ts
  * import type { Equivalence } from "effect"
@@ -128,7 +128,7 @@ export interface EquivalenceTypeLambda extends TypeLambda {
  * console.log(caseInsensitive(str, str)) // true (fast path)
  * ```
  *
- * **Example** (Numeric tolerance equivalence)
+ * **Example** (Comparing numbers with tolerance)
  *
  * ```ts
  * import { Equivalence } from "effect"
@@ -167,7 +167,7 @@ const isStrictEquivalent = (x: unknown, y: unknown) => x === y
  *
  * `NaN !== NaN`, so `NaN` values are never considered equivalent.
  *
- * **Example** (Primitive types)
+ * **Example** (Comparing primitive types)
  *
  * ```ts
  * import { Equivalence } from "effect"
@@ -179,7 +179,7 @@ const isStrictEquivalent = (x: unknown, y: unknown) => x === y
  * console.log(strictEq(NaN, NaN)) // false (NaN !== NaN)
  * ```
  *
- * **Example** (Reference equality for objects)
+ * **Example** (Comparing objects by reference)
  *
  * ```ts
  * import { Equivalence } from "effect"
@@ -486,7 +486,7 @@ export const combine: {
  * console.log(point3DEq(point1, point3)) // false (different z)
  * ```
  *
- * **Example** (Empty collection edge case)
+ * **Example** (Handling empty collections)
  *
  * ```ts
  * import { Equivalence } from "effect"
@@ -527,7 +527,7 @@ export const combineAll = <A>(collection: Iterable<Equivalence<A>>): Equivalence
  * - Useful for comparing by one property or normalizing values before
  *   comparison, such as case-insensitive strings
  *
- * **Example** (Equivalence based on object property)
+ * **Example** (Deriving equivalence from an object property)
  *
  * ```ts
  * import { Equivalence } from "effect"
@@ -588,7 +588,7 @@ export const mapInput: {
    * - Useful for comparing by one property or normalizing values before
    *   comparison, such as case-insensitive strings
    *
-   * **Example** (Equivalence based on object property)
+   * **Example** (Deriving equivalence from an object property)
    *
    * ```ts
    * import { Equivalence } from "effect"
@@ -649,7 +649,7 @@ export const mapInput: {
    * - Useful for comparing by one property or normalizing values before
    *   comparison, such as case-insensitive strings
    *
-   * **Example** (Equivalence based on object property)
+   * **Example** (Deriving equivalence from an object property)
    *
    * ```ts
    * import { Equivalence } from "effect"
@@ -715,7 +715,7 @@ export const mapInput: {
  * respective equivalences, and it also satisfies reflexive, symmetric, and
  * transitive properties.
  *
- * **Example** (Homogeneous tuple equivalence)
+ * **Example** (Comparing homogeneous tuples)
  *
  * ```ts
  * import { Equivalence } from "effect"
@@ -734,7 +734,7 @@ export const mapInput: {
  * console.log(stringTupleEq(tuple1, tuple3)) // false (different third element)
  * ```
  *
- * **Example** (Tuple with custom equivalences)
+ * **Example** (Comparing tuples with custom equivalences)
  *
  * ```ts
  * import { Equivalence } from "effect"
@@ -804,7 +804,7 @@ export {
    * - Empty arrays are considered equivalent
    * - The result is also an equivalence that satisfies reflexive, symmetric, and transitive properties
    *
-   * **Example** (Number array equivalence)
+   * **Example** (Comparing number arrays)
    *
    * ```ts
    * import { Equivalence } from "effect"
@@ -856,7 +856,7 @@ export {
  * are equivalent according to their equivalences, and it also satisfies
  * reflexive, symmetric, and transitive properties.
  *
- * **Example** (Struct with different equivalences per field)
+ * **Example** (Comparing structs with different equivalences per field)
  *
  * ```ts
  * import { Equivalence } from "effect"
@@ -886,7 +886,7 @@ export {
  * console.log(personEq(person1, person3)) // false (different age)
  * ```
  *
- * **Example** (Partial equivalence for specific fields)
+ * **Example** (Comparing specific fields)
  *
  * ```ts
  * import { Equivalence } from "effect"
@@ -937,7 +937,7 @@ export function Struct<R extends Record<string, Equivalence<any>>>(
  * - Empty objects are considered equivalent
  * - The result is also an equivalence that satisfies reflexive, symmetric, and transitive properties
  *
- * **Example** (Record with string values)
+ * **Example** (Defining records with string values)
  *
  * ```ts
  * import { Equivalence } from "effect"
@@ -954,7 +954,7 @@ export function Struct<R extends Record<string, Equivalence<any>>>(
  * console.log(stringRecordEq(record1, record4)) // false (different keys)
  * ```
  *
- * **Example** (Record with number values)
+ * **Example** (Defining records with number values)
  *
  * ```ts
  * import { Equivalence } from "effect"
@@ -1064,7 +1064,7 @@ export function makeReducer<A>() {
  * console.log(Equivalence.Date(invalidDate1, d1)) // false
  * ```
  *
- * **Example** (Reference vs value equality)
+ * **Example** (Comparing reference and value equality)
  *
  * ```ts
  * import { Equivalence } from "effect"

package/src/Exit.ts

@@ -356,7 +356,7 @@ export {
    * Equivalent to `Exit.succeed(undefined)` but shared as a single instance,
    * avoiding allocation for a common case.
    *
-   * **Example** (Using the void Exit)
+   * **Example** (Referencing the void Exit)
    *
    * ```ts
    * import { Exit } from "effect"
@@ -382,7 +382,7 @@ export {
  * Use as a type guard to narrow `Exit<A, E>` to `Success<A, E>` and access the
  * `value` property.
  *
- * **Example** (Narrowing to Success)
+ * **Example** (Narrowing to success)
  *
  * ```ts
  * import { Exit } from "effect"
@@ -410,7 +410,7 @@ export const isSuccess: <A, E>(self: Exit<A, E>) => self is Success<A, E> = effe
  * Use as a type guard to narrow `Exit<A, E>` to `Failure<A, E>` and access the
  * `cause` property.
  *
- * **Example** (Narrowing to Failure)
+ * **Example** (Narrowing to failure)
  *
  * ```ts
  * import { Exit } from "effect"

package/src/Formatter.ts

@@ -23,7 +23,7 @@ import { getRedacted, redact, symbolRedactable } from "./Redactable.ts"
  *
  * This is a pure callable type and carries no runtime implementation. It is contravariant in `Value` and covariant in `Format`.
  *
- * **Example** (Define a custom formatter)
+ * **Example** (Defining a custom formatter)
  *
  * ```ts
  * import type { Formatter } from "effect"
@@ -73,7 +73,7 @@ export interface Formatter<in Value, out Format = string> {
  *   `"\t"`). Defaults to `0` (compact).
  * - `ignoreToString` — skip calling `toString()`. Defaults to `false`.
  *
- * **Example** (Compact output)
+ * **Example** (Formatting compact output)
  *
  * ```ts
  * import { Formatter } from "effect"
@@ -97,7 +97,7 @@ export interface Formatter<in Value, out Format = string> {
  * // }
  * ```
  *
- * **Example** (Circular reference handling)
+ * **Example** (Handling circular references)
  *
  * ```ts
  * import { Formatter } from "effect"
@@ -257,7 +257,7 @@ function safeToString(input: any): string {
  * `Symbol`, `undefined`, and functions, follow standard `JSON.stringify`
  * behavior. The `space` parameter controls indentation and defaults to `0`.
  *
- * **Example** (Compact JSON)
+ * **Example** (Formatting compact JSON)
  *
  * ```ts
  * import { Formatter } from "effect"
@@ -266,7 +266,7 @@ function safeToString(input: any): string {
  * // {"name":"Alice","age":30}
  * ```
  *
- * **Example** (Circular reference handling)
+ * **Example** (Handling circular references)
  *
  * ```ts
  * import { Formatter } from "effect"

package/src/Function.ts

@@ -51,7 +51,7 @@ export interface FunctionTypeLambda extends TypeLambda {
  * whether the current call is data-first. Arity is the common case. Use a
  * predicate when optional arguments make arity ambiguous.
  *
- * **Example** (Using arity to determine data-first or data-last style)
+ * **Example** (Selecting data-first or data-last style by arity)
  *
  * ```ts
  * import { Function, pipe } from "effect"
@@ -65,7 +65,7 @@ export interface FunctionTypeLambda extends TypeLambda {
  * console.log(pipe(2, sum(3))) // 5
  * ```
  *
- * **Example** (Using call signatures to define the overloads)
+ * **Example** (Defining overloads with call signatures)
  *
  * ```ts
  * import { Function, pipe } from "effect"
@@ -79,7 +79,7 @@ export interface FunctionTypeLambda extends TypeLambda {
  * console.log(pipe(2, sum(3))) // 5
  * ```
  *
- * **Example** (Using a predicate to determine data-first or data-last style)
+ * **Example** (Selecting data-first or data-last style with a predicate)
  *
  * ```ts
  * import { Function, pipe } from "effect"
@@ -115,7 +115,7 @@ export const dual: {
    * whether the current call is data-first. Arity is the common case. Use a
    * predicate when optional arguments make arity ambiguous.
    *
-   * **Example** (Using arity to determine data-first or data-last style)
+   * **Example** (Selecting data-first or data-last style by arity)
    *
    * ```ts
    * import { Function, pipe } from "effect"
@@ -129,7 +129,7 @@ export const dual: {
    * console.log(pipe(2, sum(3))) // 5
    * ```
    *
-   * **Example** (Using call signatures to define the overloads)
+   * **Example** (Defining overloads with call signatures)
    *
    * ```ts
    * import { Function, pipe } from "effect"
@@ -143,7 +143,7 @@ export const dual: {
    * console.log(pipe(2, sum(3))) // 5
    * ```
    *
-   * **Example** (Using a predicate to determine data-first or data-last style)
+   * **Example** (Selecting data-first or data-last style with a predicate)
    *
    * ```ts
    * import { Function, pipe } from "effect"
@@ -179,7 +179,7 @@ export const dual: {
    * whether the current call is data-first. Arity is the common case. Use a
    * predicate when optional arguments make arity ambiguous.
    *
-   * **Example** (Using arity to determine data-first or data-last style)
+   * **Example** (Selecting data-first or data-last style by arity)
    *
    * ```ts
    * import { Function, pipe } from "effect"
@@ -193,7 +193,7 @@ export const dual: {
    * console.log(pipe(2, sum(3))) // 5
    * ```
    *
-   * **Example** (Using call signatures to define the overloads)
+   * **Example** (Defining overloads with call signatures)
    *
    * ```ts
    * import { Function, pipe } from "effect"
@@ -207,7 +207,7 @@ export const dual: {
    * console.log(pipe(2, sum(3))) // 5
    * ```
    *
-   * **Example** (Using a predicate to determine data-first or data-last style)
+   * **Example** (Selecting data-first or data-last style with a predicate)
    *
    * ```ts
    * import { Function, pipe } from "effect"
@@ -760,7 +760,7 @@ export const untupled = <A extends ReadonlyArray<unknown>, B>(f: (a: A) => B): (
  * Each function passed after the initial value must accept a single argument,
  * because `pipe` calls each step with only the previous result.
  *
- * **Example** (Using pipeline syntax)
+ * **Example** (Piping values through functions)
  *
  * In this example, `1` is passed to the first function, and each result becomes
  * the input for the next function.

package/src/HashMap.ts

@@ -1867,7 +1867,7 @@ export const map: {
  *
  * The hash and equality behavior of both maps have to be the same.
  *
- * **Example** (FlatMapping values)
+ * **Example** (Flat mapping values)
  *
  * ```ts
  * import { HashMap } from "effect"
@@ -1894,7 +1894,7 @@ export const flatMap: {
    *
    * The hash and equality behavior of both maps have to be the same.
    *
-   * **Example** (FlatMapping values)
+   * **Example** (Flat mapping values)
    *
    * ```ts
    * import { HashMap } from "effect"
@@ -1921,7 +1921,7 @@ export const flatMap: {
    *
    * The hash and equality behavior of both maps have to be the same.
    *
-   * **Example** (FlatMapping values)
+   * **Example** (Flat mapping values)
    *
    * ```ts
    * import { HashMap } from "effect"