effect 4.0.0-beta.69 → 4.0.0-beta.70

package/dist/Effect.js

@@ -45,7 +45,7 @@ export const isEffect = core.isEffect;
  * first failure; with concurrent execution, effects that have already started
  * may be interrupted, while effects not yet started are skipped.
  *
- * **Options**
+ * Options:
  *
  * Use `concurrency` to control sequential or concurrent execution. Use
  * `mode: "result"` to run every effect and collect each success or failure as a
@@ -159,7 +159,6 @@ export const isEffect = core.isEffect;
  * ```
  *
  * @see {@link forEach} for iterating over elements and applying an effect.
- *
  * @category Collecting
  * @since 2.0.0
  */
@@ -168,6 +167,8 @@ export const all = internal.all;
  * Applies an effectful function to each element and partitions failures and
  * successes.
  *
+ * **Details**
+ *
  * The returned tuple is `[excluded, satisfying]`, where:
  *
  * - `excluded` contains all failures.
@@ -196,6 +197,8 @@ export const partition = internal.partition;
 /**
  * Applies an effectful function to each element and accumulates all failures.
  *
+ * **Details**
+ *
  * This function always evaluates every element. If at least one effect fails,
  * all failures are returned as a non-empty array and successes are discarded.
  * If all effects succeed, it returns all collected successes.
@@ -233,6 +236,8 @@ export const validate = internal.validate;
 /**
  * Returns the first element that satisfies an effectful predicate.
  *
+ * **Details**
+ *
  * The predicate receives the element and its index. Evaluation short-circuits
  * as soon as an element matches.
  *
@@ -254,6 +259,8 @@ export const findFirst = internal.findFirst;
 /**
  * Returns the first value that passes an effectful `FilterEffect`.
  *
+ * **Details**
+ *
  * The filter receives the element and index. Evaluation short-circuits on the
  * first `Result.succeed` and returns the transformed value in `Option.some`.
  *
@@ -272,18 +279,16 @@ export const findFirstFilter = internal.findFirstFilter;
  * If any effect fails, the iteration stops immediately (short-circuiting), and
  * the error is propagated.
  *
- * **Concurrency**
+ * Concurrency:
  *
  * The `concurrency` option controls how many operations are performed
  * concurrently. By default, the operations are performed sequentially.
  *
- * **Discarding Results**
+ * Discarding Results:
  *
  * If the `discard` option is set to `true`, the intermediate results are not
  * collected, and the final result of the operation is `void`.
  *
- * @see {@link all} for combining multiple effects into one.
- *
  * **Example** (Mapping over an iterable with effects)
  *
  * ```ts
@@ -328,6 +333,7 @@ export const findFirstFilter = internal.findFirstFilter;
  * // undefined
  * ```
  *
+ * @see {@link all} for combining multiple effects into one.
  * @category Collecting
  * @since 2.0.0
  */
@@ -368,7 +374,7 @@ export const whileLoop = internal.whileLoop;
  * Creates an `Effect` that represents an asynchronous computation guaranteed to
  * succeed.
  *
- * **When to Use**
+ * **When to use**
  *
  * Use `promise` when you are sure the operation will not reject.
  *
@@ -382,13 +388,11 @@ export const whileLoop = internal.whileLoop;
  * crash in the program, which can be further managed or logged using tools like
  * {@link catchDefect}.
  *
- * **Interruptions**
+ * Interruptions:
  *
  * An optional `AbortSignal` can be provided to allow for interruption of the
  * wrapped `Promise` API.
  *
- * @see {@link tryPromise} for a version that can handle failures.
- *
  * **Example** (Wrapping a non-rejecting Promise)
  *
  * ```ts
@@ -409,6 +413,7 @@ export const whileLoop = internal.whileLoop;
  * const program = delay("Async operation completed successfully!")
  * ```
  *
+ * @see {@link tryPromise} for a version that can handle failures.
  * @category Creating Effects
  * @since 2.0.0
  */
@@ -417,7 +422,7 @@ export const promise = internal.promise;
  * Creates an `Effect` that represents an asynchronous computation that might
  * fail.
  *
- * **When to Use**
+ * **When to use**
  *
  * In situations where you need to perform asynchronous operations that might
  * fail, such as fetching data from an API, you can use the `tryPromise`
@@ -425,7 +430,9 @@ export const promise = internal.promise;
  * throw exceptions by capturing those exceptions and transforming them into
  * manageable errors.
  *
- * **Error Handling**
+ * **Details**
+ *
+ * Error Handling:
  *
  * There are two ways to handle errors with `tryPromise`:
  *
@@ -434,7 +441,7 @@ export const promise = internal.promise;
  * 2. If you provide a `catch` function, the error is caught and the `catch`
  *    function maps it to an error of type `E`.
  *
- * **Interruptions**
+ * Interruptions:
  *
  * An optional `AbortSignal` can be provided to allow for interruption of the
  * wrapped `Promise` API.
@@ -475,7 +482,6 @@ export const promise = internal.promise;
  * ```
  *
  * @see {@link promise} if the effectful computation is asynchronous and does not throw errors.
- *
  * @category Creating Effects
  * @since 2.0.0
  */
@@ -483,13 +489,11 @@ export const tryPromise = internal.tryPromise;
 /**
  * Creates an `Effect` that always succeeds with a given value.
  *
- * **When to Use**
+ * **When to use**
  *
  * Use this function when you need an effect that completes successfully with a
  * specific value without any errors or external dependencies.
  *
- * @see {@link fail} to create an effect that represents a failure.
- *
  * **Example** (Creating a successful effect)
  *
  * ```ts
@@ -502,6 +506,7 @@ export const tryPromise = internal.tryPromise;
  * const success = Effect.succeed(42)
  * ```
  *
+ * @see {@link fail} to create an effect that represents a failure.
  * @category Creating Effects
  * @since 2.0.0
  */
@@ -545,7 +550,7 @@ export const succeedSome = internal.succeedSome;
 /**
  * Delays the creation of an `Effect` until it is actually needed.
  *
- * **When to Use**
+ * **When to use**
  *
  * Use `suspend` when you need to defer the evaluation of an effect until it is required. This is particularly useful for optimizing expensive computations, managing circular dependencies, or resolving type inference issues.
  *
@@ -632,7 +637,7 @@ export const suspend = internal.suspend;
 /**
  * Creates an `Effect` that represents a synchronous side-effectful computation.
  *
- * **When to Use**
+ * **When to use**
  *
  * Use `sync` when you are sure the operation will not fail.
  *
@@ -646,8 +651,6 @@ export const suspend = internal.suspend;
  * crash in the program, which can be further managed or logged using tools like
  * {@link catchDefect}.
  *
- * @see {@link try_ | try} for a version that can handle failures.
- *
  * **Example** (Capturing synchronous logging in an Effect)
  *
  * ```ts
@@ -663,6 +666,7 @@ export const suspend = internal.suspend;
  * const program = log("Hello, World!")
  * ```
  *
+ * @see {@link try_ | try} for a version that can handle failures.
  * @category Creating Effects
  * @since 2.0.0
  */
@@ -670,6 +674,8 @@ export const sync = internal.sync;
 const void_ = internal.void;
 export {
 /**
+ * Returns an effect that succeeds with `void`.
+ *
  * @category Creating Effects
  * @since 2.0.0
  */
@@ -677,6 +683,8 @@ void_ as void };
 const undefined_ = internal.undefined;
 export {
 /**
+ * Returns an effect that succeeds with `undefined`.
+ *
  * @category Creating Effects
  * @since 4.0.0
  */
@@ -684,6 +692,11 @@ undefined_ as undefined };
 /**
  * Creates an `Effect` from a callback-based asynchronous API.
  *
+ * **When to use**
+ *
+ * Use `Effect.callback` when integrating APIs that complete through callbacks
+ * instead of returning a `Promise`.
+ *
  * **Details**
  *
  * The registration function receives a `resume` callback and, when requested,
@@ -691,11 +704,6 @@ undefined_ as undefined };
  * complete the fiber; later calls are ignored. Return an optional cleanup
  * effect from the registration function to run if the fiber is interrupted.
  *
- * **When to Use**
- *
- * Use `Effect.callback` when integrating APIs that complete through callbacks
- * instead of returning a `Promise`.
- *
  * **Example** (Integrating callback APIs)
  *
  * ```ts
@@ -789,7 +797,7 @@ export const bind = internal.bind;
  * Provides a way to write effectful code using generator functions, simplifying
  * control flow and error handling.
  *
- * **When to Use**
+ * **When to use**
  *
  * `gen` allows you to write code that looks and behaves like synchronous
  * code, but it can handle asynchronous tasks, errors, and complex control flow
@@ -840,14 +848,12 @@ export const gen = internal.gen;
 /**
  * Creates an `Effect` that represents a recoverable error.
  *
- * **When to Use**
+ * **When to use**
  *
  * Use this function to explicitly signal an error in an `Effect`. The error
  * will keep propagating unless it is handled. You can handle the error with
  * functions like {@link catchTag} or {@link catchTags}.
  *
- * @see {@link succeed} to create an effect that represents a successful value.
- *
  * **Example** (Creating a failed effect)
  *
  * ```ts
@@ -862,6 +868,7 @@ export const gen = internal.gen;
  * )
  * ```
  *
+ * @see {@link succeed} to create an effect that represents a successful value.
  * @category Creating Effects
  * @since 2.0.0
  */
@@ -869,6 +876,8 @@ export const fail = internal.fail;
 /**
  * Creates an `Effect` that represents a recoverable error using a lazy evaluation.
  *
+ * **Details**
+ *
  * This function is useful when you need to create an error effect but want to
  * defer the computation of the error value until the effect is actually run.
  *
@@ -892,6 +901,8 @@ export const failSync = internal.failSync;
 /**
  * Creates an `Effect` that represents a failure with a specific `Cause`.
  *
+ * **Details**
+ *
  * This function allows you to create effects that fail with complex error
  * structures, including multiple errors, defects, interruptions, and more.
  *
@@ -915,6 +926,8 @@ export const failCause = internal.failCause;
 /**
  * Creates an `Effect` that represents a failure with a `Cause` computed lazily.
  *
+ * **Details**
+ *
  * This function is useful when you need to create a failure effect with a
  * complex cause but want to defer the computation until the effect is run.
  *
@@ -938,7 +951,7 @@ export const failCauseSync = internal.failCauseSync;
 /**
  * Creates an effect that terminates a fiber with a specified error.
  *
- * **When to Use**
+ * **When to use**
  *
  * Use `die` when encountering unexpected conditions in your code that should
  * not be handled as regular errors but instead represent unrecoverable defects.
@@ -952,8 +965,6 @@ export const failCauseSync = internal.failCauseSync;
  * The error channel of the resulting effect is of type `never`, indicating that
  * it cannot recover from this failure.
  *
- * @see {@link die} for a variant that dies with an already computed defect.
- *
  * **Example** (Failing when division by zero)
  *
  * ```ts
@@ -974,6 +985,7 @@ export const failCauseSync = internal.failCauseSync;
  * //   ...stack trace...
  * ```
  *
+ * @see {@link die} for a variant that dies with an already computed defect.
  * @category Creating Effects
  * @since 2.0.0
  */
@@ -984,14 +996,16 @@ export {
  * Creates an `Effect` that represents a synchronous computation that might
  * fail.
  *
- * **When to Use**
+ * **When to use**
  *
  * In situations where you need to perform synchronous operations that might
  * fail, such as parsing JSON, you can use the `try` constructor. This
  * constructor is designed to handle operations that could throw exceptions by
  * capturing those exceptions and transforming them into manageable errors.
  *
- * **Error Handling**
+ * **Details**
+ *
+ * Error Handling:
  *
  * There are two ways to handle errors with `try`:
  *
@@ -1000,9 +1014,6 @@ export {
  * 2. If you provide a `catch` function, the error is caught and the `catch`
  *    function maps it to an error of type `E`.
  *
- * @see {@link sync} if the effectful computation is synchronous and does not
- * throw errors.
- *
  * **Example** (Parsing JSON with typed error mapping)
  *
  * ```ts
@@ -1040,6 +1051,8 @@ export {
  * // Output: Exit.failure with custom Error message
  * ```
  *
+ * @see {@link sync} if the effectful computation is synchronous and does not
+ * throw errors.
  * @category Creating Effects
  * @since 2.0.0
  */
@@ -1135,6 +1148,8 @@ export const fromResult = internal.fromResult;
 /**
  * Converts an `Option` into an `Effect`.
  *
+ * **Details**
+ *
  * `Option.some` becomes a successful effect with the contained value, while
  * `Option.none` becomes a failed effect with `NoSuchElementError`.
  *
@@ -1191,15 +1206,11 @@ export const fromNullishOr = internal.fromNullishOr;
  * Chains effects to produce new `Effect` instances, useful for combining
  * operations that depend on previous results.
  *
- * **Syntax**
+ * **When to use**
  *
- * ```ts skip-type-checking
- * const flatMappedEffect = pipe(myEffect, Effect.flatMap(transformation))
- * // or
- * const flatMappedEffect = Effect.flatMap(myEffect, transformation)
- * // or
- * const flatMappedEffect = myEffect.pipe(Effect.flatMap(transformation))
- * ```
+ * Use `flatMap` when you need to chain multiple effects, ensuring that each
+ * step produces a new `Effect` while flattening any nested effects that may
+ * occur.
  *
  * **Details**
  *
@@ -1211,11 +1222,18 @@ export const fromNullishOr = internal.fromNullishOr;
  * Since effects are immutable, `flatMap` always returns a new effect instead of
  * changing the original one.
  *
- * **When to Use**
+ * **Example** (Syntax)
  *
- * Use `flatMap` when you need to chain multiple effects, ensuring that each
- * step produces a new `Effect` while flattening any nested effects that may
- * occur.
+ * ```ts
+ * import { Effect, pipe } from "effect"
+ *
+ * const myEffect = Effect.succeed(1)
+ * const transformation = (n: number) => Effect.succeed(n + 1)
+ *
+ * const flatMappedWithPipe = pipe(myEffect, Effect.flatMap(transformation))
+ * const flatMappedWithDataFirst = Effect.flatMap(myEffect, transformation)
+ * const flatMappedWithMethod = myEffect.pipe(Effect.flatMap(transformation))
+ * ```
  *
  * **Example** (Sequencing dependent effects)
  *
@@ -1247,7 +1265,6 @@ export const fromNullishOr = internal.fromNullishOr;
  * ```
  *
  * @see {@link tap} for a version that ignores the result of the effect.
- *
  * @category sequencing
  * @since 2.0.0
  */
@@ -1277,17 +1294,7 @@ export const flatten = internal.flatten;
  * Runs this effect and then runs another effect, optionally using the first
  * effect's success value to choose the next effect.
  *
- * **Syntax**
- *
- * ```ts skip-type-checking
- * const transformedEffect = pipe(myEffect, Effect.andThen(anotherEffect))
- * // or
- * const transformedEffect = Effect.andThen(myEffect, anotherEffect)
- * // or
- * const transformedEffect = myEffect.pipe(Effect.andThen(anotherEffect))
- * ```
- *
- * **When to Use**
+ * **When to use**
  *
  * Use `andThen` when one effect must run after another and the second effect
  * may depend on the first effect's success value.
@@ -1302,6 +1309,19 @@ export const flatten = internal.flatten;
  * Failures or requirements from either effect are preserved in the returned
  * effect.
  *
+ * **Example** (Syntax)
+ *
+ * ```ts
+ * import { Effect, pipe } from "effect"
+ *
+ * const myEffect = Effect.succeed(1)
+ * const anotherEffect = Effect.succeed("done")
+ *
+ * const transformedWithPipe = pipe(myEffect, Effect.andThen(anotherEffect))
+ * const transformedWithDataFirst = Effect.andThen(myEffect, anotherEffect)
+ * const transformedWithMethod = myEffect.pipe(Effect.andThen(anotherEffect))
+ * ```
+ *
  * **Example** (Sequencing a discount calculation after fetching a total)
  *
  * ```ts
@@ -1350,7 +1370,7 @@ export const andThen = internal.andThen;
  * Runs a side effect with the result of an effect without changing the original
  * value.
  *
- * **When to Use**
+ * **When to use**
  *
  * Use `tap` when you want to perform a side effect, like logging or tracking,
  * without modifying the main value. This is useful when you need to observe or
@@ -1522,16 +1542,6 @@ export const exit = internal.exit;
 /**
  * Transforms the value inside an effect by applying a function to it.
  *
- * **Syntax**
- *
- * ```ts skip-type-checking
- * const mappedEffect = pipe(myEffect, Effect.map(transformation))
- * // or
- * const mappedEffect = Effect.map(myEffect, transformation)
- * // or
- * const mappedEffect = myEffect.pipe(Effect.map(transformation))
- * ```
- *
  * **Details**
  *
  * `map` takes a function and applies it to the value contained within an
@@ -1541,6 +1551,19 @@ export const exit = internal.exit;
  * effect is not modified. Instead, a new effect is returned with the updated
  * value.
  *
+ * **Example** (Syntax)
+ *
+ * ```ts
+ * import { Effect, pipe } from "effect"
+ *
+ * const myEffect = Effect.succeed(1)
+ * const transformation = (n: number) => n + 1
+ *
+ * const mappedWithPipe = pipe(myEffect, Effect.map(transformation))
+ * const mappedWithDataFirst = Effect.map(myEffect, transformation)
+ * const mappedWithMethod = myEffect.pipe(Effect.map(transformation))
+ * ```
+ *
  * **Example** (Adding a service charge)
  *
  * ```ts
@@ -1562,7 +1585,6 @@ export const exit = internal.exit;
  * @see {@link mapError} for a version that operates on the error channel.
  * @see {@link mapBoth} for a version that operates on both channels.
  * @see {@link flatMap} or {@link andThen} for a version that can return a new effect.
- *
  * @category mapping
  * @since 2.0.0
  */
@@ -1570,6 +1592,8 @@ export const map = internal.map;
 /**
  * Replaces the value inside an effect with a constant value.
  *
+ * **Details**
+ *
  * `as` allows you to ignore the original value inside an effect and
  * replace it with a new constant value.
  *
@@ -1634,6 +1658,8 @@ export const asVoid = internal.asVoid;
  * The `flip` function swaps the success and error channels of an effect,
  * so that the success becomes the error, and the error becomes the success.
  *
+ * **Details**
+ *
  * This function is useful when you need to reverse the flow of an effect,
  * treating the previously successful values as errors and vice versa. This can
  * be helpful in scenarios where you want to handle a success as a failure or
@@ -1663,17 +1689,16 @@ export const flip = internal.flip;
 /**
  * Combines two effects into a single effect, producing a tuple with the results of both effects.
  *
+ * **Details**
+ *
  * The `zip` function executes the first effect (left) and then the second effect (right).
  * Once both effects succeed, their results are combined into a tuple.
  *
- * **Concurrency**
+ * Concurrency:
  *
  * By default, `zip` processes the effects sequentially. To execute the effects concurrently,
  * use the `{ concurrent: true }` option.
  *
- * @see {@link zipWith} for a version that combines the results with a custom function.
- * @see {@link validate} for a version that accumulates errors.
- *
  * **Example** (Combining two effects sequentially)
  *
  * ```ts
@@ -1725,6 +1750,8 @@ export const flip = internal.flip;
  * // [ 1, 'hello' ]
  * ```
  *
+ * @see {@link zipWith} for a version that combines the results with a custom function.
+ * @see {@link validate} for a version that accumulates errors.
  * @category zipping
  * @since 2.0.0
  */
@@ -1733,13 +1760,15 @@ export const zip = internal.zip;
  * Combines two effects sequentially and applies a function to their results to
  * produce a single value.
  *
- * **When to Use**
+ * **When to use**
  *
  * The `zipWith` function is similar to {@link zip}, but instead of returning a
  * tuple of results, it applies a provided function to the results of the two
  * effects, combining them into a single value.
  *
- * **Concurrency**
+ * **Details**
+ *
+ * Concurrency:
  *
  * By default, the effects are run sequentially. To execute them concurrently,
  * use the `{ concurrent: true }` option.
@@ -1804,7 +1833,7 @@ catch_ as catch };
  * Catches and handles specific errors by their `_tag` field, which is used as a
  * discriminator.
  *
- * **When to Use**
+ * **When to use**
  *
  * `catchTag` is useful when your errors are tagged with a readonly `_tag` field
  * that identifies the error type. You can use this function to handle specific
@@ -1845,7 +1874,7 @@ export const catchTag = internal.catchTag;
 /**
  * Handles multiple errors in a single block of code using their `_tag` field.
  *
- * **When to Use**
+ * **When to use**
  *
  * `catchTags` is a convenient way to handle multiple error types at
  * once. Instead of using {@link catchTag} multiple times, you can pass an
@@ -1889,6 +1918,8 @@ export const catchTags = internal.catchTags;
 /**
  * Catches a specific reason within a tagged error.
  *
+ * **Details**
+ *
  * Use this to handle nested error causes without removing the parent error
  * from the error channel. The handler receives the unwrapped reason.
  *
@@ -1995,14 +2026,16 @@ export const unwrapReason = internal.unwrapReason;
  * Handles both recoverable and unrecoverable errors by providing a recovery
  * effect.
  *
- * **When to Use**
+ * **When to use**
  *
  * The `catchCause` function allows you to handle all errors, including
  * unrecoverable defects, by providing a recovery effect. The recovery logic is
  * based on the `Cause` of the error, which provides detailed information about
  * the failure.
  *
- * **When to Recover from Defects**
+ * **Details**
+ *
+ * When to Recover from Defects:
  *
  * Defects are unexpected errors that typically shouldn't be recovered from, as
  * they often indicate serious issues. However, in some cases, such as
@@ -2034,7 +2067,7 @@ export const catchCause = internal.catchCause;
 /**
  * Recovers from defects using a provided recovery function.
  *
- * **When to Use**
+ * **When to use**
  *
  * Use this sparingly, usually at integration boundaries where defects must be
  * reported or translated for an external system.
@@ -2044,7 +2077,7 @@ export const catchCause = internal.catchCause;
  * `catchDefect` handles unexpected defects, such as thrown exceptions or
  * values passed to `die`, without catching typed failures or interruptions.
  *
- * **When to Recover from Defects**
+ * When to Recover from Defects:
  *
  * Defects are unexpected errors that typically should not be recovered from, as
  * they often indicate serious issues. In some cases, such as dynamically loaded
@@ -2075,7 +2108,7 @@ export const catchDefect = internal.catchDefect;
 /**
  * Recovers from specific errors using a `Predicate` or `Refinement`.
  *
- * **When to Use**
+ * **When to use**
  *
  * `catchIf` lets you recover from errors that match a condition. Use a
  * `Refinement` for type narrowing or a `Predicate` for simple boolean
@@ -2122,6 +2155,8 @@ export const catchFilter = internal.catchFilter;
 /**
  * Catches `NoSuchElementError` failures and converts them to `Option.none`.
  *
+ * **Details**
+ *
  * Success values become `Option.some`, `NoSuchElementError` becomes
  * `Option.none`, and all other errors are preserved.
  *
@@ -2144,6 +2179,8 @@ export const catchNoSuchElement = internal.catchNoSuchElement;
 /**
  * Recovers from specific failures based on a predicate.
  *
+ * **Details**
+ *
  * This function allows you to conditionally catch and recover from failures
  * that match a specific predicate. This is useful when you want to handle
  * only certain types of errors while letting others propagate.
@@ -2186,15 +2223,13 @@ export const catchCauseFilter = internal.catchCauseFilter;
  * The `mapError` function is used to transform or modify the error
  * produced by an effect, without affecting its success value.
  *
+ * **Details**
+ *
  * This function is helpful when you want to enhance the error with additional
  * information, change the error type, or apply custom error handling while
  * keeping the original behavior of the effect's success values intact. It only
  * operates on the error channel and leaves the success channel unchanged.
  *
- * @see {@link map} for a version that operates on the success channel.
- * @see {@link mapBoth} for a version that operates on both channels.
- * @see {@link mapError} if you want to replace the error with a new one.
- *
  * **Example** (Transforming the error channel)
  *
  * ```ts
@@ -2214,6 +2249,9 @@ export const catchCauseFilter = internal.catchCauseFilter;
  * )
  * ```
  *
+ * @see {@link map} for a version that operates on the success channel.
+ * @see {@link mapBoth} for a version that operates on both channels.
+ * @see {@link mapError} if you want to replace the error with a new one.
  * @category error handling
  * @since 2.0.0
  */
@@ -2258,13 +2296,11 @@ export const mapBoth = internal.mapBoth;
  * Converts typed failures from the error channel into defects, removing the
  * error type from the returned effect.
  *
- * **When to Use**
+ * **When to use**
  *
  * Use `orDie` when a typed failure represents an unrecoverable bug or invalid
  * state and should not be handled as a recoverable error.
  *
- * @see {@link mapError} to transform the error before converting it into a defect with {@link orDie}.
- *
  * **Example** (Converting typed failures into defects)
  *
  * ```ts
@@ -2287,6 +2323,7 @@ export const mapBoth = internal.mapBoth;
  * //   ...stack trace...
  * ```
  *
+ * @see {@link mapError} to transform the error before converting it into a defect with {@link orDie}.
  * @category Converting Failures to Defects
  * @since 2.0.0
  */
@@ -2327,6 +2364,8 @@ export const tapError = internal.tapError;
 /**
  * Runs an effectful handler when a failure's `_tag` matches.
  *
+ * **Details**
+ *
  * Use this with tagged-union errors to perform side effects for one tag or a
  * list of tags. When the handler succeeds, the original failure is preserved;
  * if the handler fails, its error is also included in the returned effect.
@@ -2394,6 +2433,8 @@ export const tapCause = internal.tapCause;
 /**
  * Conditionally executes a side effect based on the cause of a failed effect.
  *
+ * **Details**
+ *
  * This function allows you to tap into the cause of an effect's failure only when
  * the cause matches a specific predicate. This is useful for conditional logging,
  * monitoring, or other side effects based on the type of failure.
@@ -2479,6 +2520,8 @@ export const tapDefect = internal.tapDefect;
 /**
  * Retries an effect until it succeeds, discarding failures.
  *
+ * **Details**
+ *
  * Yields between attempts so other fibers can run.
  *
  * **Example** (Retrying until success)
@@ -2514,6 +2557,11 @@ export const eventually = internal.eventually;
 /**
  * Retries typed failures from an effect according to a retry policy.
  *
+ * **When to use**
+ *
+ * Use `retry` when typed failures may be transient, such as network issues or
+ * temporary resource unavailability.
+ *
  * **Details**
  *
  * The policy can be a `Schedule`, a schedule builder, or a `Retry.Options`
@@ -2523,11 +2571,6 @@ export const eventually = internal.eventually;
  *
  * Defects and interruptions are not retried as typed failures.
  *
- * **When to Use**
- *
- * Use `retry` when typed failures may be transient, such as network issues or
- * temporary resource unavailability.
- *
  * **Example** (Retrying with a schedule)
  *
  * ```ts
@@ -2554,7 +2597,6 @@ export const eventually = internal.eventually;
  *
  * @see {@link retryOrElse} for a version that allows you to run a fallback.
  * @see {@link repeat} if your retry condition is based on successful outcomes rather than errors.
- *
  * @category error handling
  * @since 2.0.0
  */
@@ -2562,6 +2604,11 @@ export const retry = internalSchedule.retry;
 /**
  * Retries a failing effect and runs a fallback effect if retries are exhausted.
  *
+ * **When to use**
+ *
+ * This function is useful when you want to handle failures gracefully by
+ * specifying an alternative action after repeated failures.
+ *
  * **Details**
  *
  * The `Effect.retryOrElse` function attempts to retry a failing effect multiple
@@ -2570,13 +2617,6 @@ export const retry = internalSchedule.retry;
  * If the retries are exhausted and the effect still fails, it runs a fallback
  * effect instead.
  *
- * **When to Use**
- *
- * This function is useful when you want to handle failures gracefully by
- * specifying an alternative action after repeated failures.
- *
- * @see {@link retry} for a version that does not run a fallback effect.
- *
  * **Example** (Falling back after retries are exhausted)
  *
  * ```ts
@@ -2613,6 +2653,7 @@ export const retry = internalSchedule.retry;
  * // Network data
  * ```
  *
+ * @see {@link retry} for a version that does not run a fallback effect.
  * @category error handling
  * @since 2.0.0
  */
@@ -2652,7 +2693,7 @@ export const sandbox = internal.sandbox;
 /**
  * Discards both the success and failure values of an effect.
  *
- * **When to Use**
+ * **When to use**
  *
  * `ignore` allows you to run an effect without caring about its result, whether
  * it succeeds or fails. This is useful when you only care about the side
@@ -2693,6 +2734,8 @@ export const ignore = internal.ignore;
 /**
  * Ignores the effect's failure cause, including defects and interruptions.
  *
+ * **Details**
+ *
  * Use the `log` option to emit the full {@link Cause} when the effect fails,
  * and `message` to prepend a custom log message.
  *
@@ -2715,6 +2758,8 @@ export const ignoreCause = internal.ignoreCause;
  * Apply an `ExecutionPlan` to an effect, retrying with step-provided resources
  * until it succeeds or the plan is exhausted.
  *
+ * **Details**
+ *
  * Each attempt updates `ExecutionPlan.CurrentMetadata` (attempt and step index),
  * and retry timing is derived per step (the first attempt uses the remaining
  * attempts schedule; later retries apply the step schedule at least once).
@@ -2749,6 +2794,8 @@ export const withExecutionPlan = internalExecutionPlan.withExecutionPlan;
 /**
  * Runs an effect and reports any errors to the configured `ErrorReporter`s.
  *
+ * **Details**
+ *
  * If the `defectsOnly` option is set to `true`, only defects (unrecoverable
  * errors) will be reported, while regular failures will be ignored.
  *
@@ -2800,6 +2847,12 @@ export const orElseSucceed = internal.orElseSucceed;
  * Runs a sequence of effects and returns the result of the first successful
  * one.
  *
+ * **When to use**
+ *
+ * Use `firstSuccessOf` when you have prioritized fallback strategies, such as
+ * attempting multiple APIs, reading configuration from several sources, or
+ * trying alternative resource locations in order.
+ *
  * **Details**
  *
  * This function executes the provided effects in sequence, stopping at the
@@ -2810,12 +2863,6 @@ export const orElseSucceed = internal.orElseSucceed;
  * effect. If the collection is empty, the returned effect defects with an
  * `Error` whose message is `"Received an empty collection of effects"`.
  *
- * **When to Use**
- *
- * Use `firstSuccessOf` when you have prioritized fallback strategies, such as
- * attempting multiple APIs, reading configuration from several sources, or
- * trying alternative resource locations in order.
- *
  * **Example** (Trying alternatives until one succeeds)
  *
  * ```ts
@@ -2848,14 +2895,14 @@ export const firstSuccessOf = internal.firstSuccessOf;
  * Adds a time limit to an effect, triggering a timeout if the effect exceeds
  * the duration.
  *
+ * **Details**
+ *
  * The `timeout` function allows you to specify a time limit for an
  * effect's execution. If the effect does not complete within the given time, a
  * `TimeoutException` is raised. This can be useful for controlling how long
  * your program waits for a task to finish, ensuring that it doesn't hang
  * indefinitely if the task takes too long.
  *
- * @see {@link timeoutOrElse} for a version that allows specifying both success and timeout handlers.
- *
  * **Example** (Failing when work takes too long)
  *
  * ```ts
@@ -2886,6 +2933,7 @@ export const firstSuccessOf = internal.firstSuccessOf;
  * // }
  * ```
  *
+ * @see {@link timeoutOrElse} for a version that allows specifying both success and timeout handlers.
  * @category Delays & Timeouts
  * @since 2.0.0
  */
@@ -2939,6 +2987,8 @@ export const timeoutOption = internal.timeoutOption;
 /**
  * Applies a timeout to an effect, with a fallback effect executed if the timeout is reached.
  *
+ * **Details**
+ *
  * This function is useful when you want to set a maximum duration for an operation
  * and provide an alternative action if the timeout is exceeded.
  *
@@ -3023,6 +3073,8 @@ export const sleep = internal.sleep;
 /**
  * Measures the runtime of an effect and returns the duration with its result.
  *
+ * **Details**
+ *
  * The original success, failure, or interruption is preserved; only the success
  * value is paired with the duration.
  *
@@ -3047,6 +3099,11 @@ export const timed = internal.timed;
 /**
  * Runs multiple effects concurrently and returns the first successful result.
  *
+ * **When to use**
+ *
+ * Use `raceAll` when early failures should be ignored until a success occurs
+ * or all effects fail.
+ *
  * **Details**
  *
  * Early failures do not finish the race; `raceAll` keeps waiting until one
@@ -3054,13 +3111,6 @@ export const timed = internal.timed;
  * remaining effects are interrupted. If every effect fails, the returned effect
  * fails with a cause containing the collected failure reasons.
  *
- * **When to Use**
- *
- * Use `raceAll` when early failures should be ignored until a success occurs
- * or all effects fail.
- *
- * @see {@link race} for a version that handles only two effects.
- *
  * **Example** (Racing many effects)
  *
  * ```ts
@@ -3077,6 +3127,7 @@ export const timed = internal.timed;
  * // Result: "Fast" (after ~100ms)
  * ```
  *
+ * @see {@link race} for a version that handles only two effects.
  * @category Racing
  * @since 2.0.0
  */
@@ -3114,6 +3165,8 @@ export const raceAllFirst = internal.raceAllFirst;
 /**
  * Races two effects and returns the first successful result.
  *
+ * **Details**
+ *
  * If one effect succeeds, the other is interrupted and `onWinner` can observe the
  * winning fiber. If both fail, the race fails.
  *
@@ -3142,6 +3195,8 @@ export const race = internal.race;
  * Races two effects and returns the result of the first one to complete, whether
  * it succeeds or fails.
  *
+ * **Details**
+ *
  * The losing effect is interrupted, and `onWinner` can observe the winning fiber.
  *
  * **Example** (Observing the winning fiber)
@@ -3291,6 +3346,11 @@ export const filterMapOrFail = internal.filterMapOrFail;
  * Conditionally runs an effect based on the result of an effectful boolean
  * condition.
  *
+ * **When to use**
+ *
+ * Use this when an effectful check decides whether to run another effect while
+ * representing the skipped case explicitly.
+ *
  * **Details**
  *
  * The condition effect is evaluated first. If it succeeds with `true`, the
@@ -3298,11 +3358,6 @@ export const filterMapOrFail = internal.filterMapOrFail;
  * succeeds with `false`, the source effect is skipped and the result is
  * `Option.none`. If the condition effect fails, that failure is preserved.
  *
- * **When to Use**
- *
- * Use this when an effectful check decides whether to run another effect while
- * representing the skipped case explicitly.
- *
  * **Example** (Conditionally running an effect)
  *
  * ```ts
@@ -3321,7 +3376,6 @@ export const filterMapOrFail = internal.filterMapOrFail;
  * ```
  *
  * @see {@link when} for conditional execution with a boolean condition.
- *
  * @category Conditional Operators
  * @since 2.0.0
  */
@@ -3333,6 +3387,11 @@ export const when = internal.when;
  * Handles both success and failure cases of an effect without performing side
  * effects.
  *
+ * **When to use**
+ *
+ * This is useful for structuring your code to respond differently to success or
+ * failure without triggering side effects.
+ *
  * **Details**
  *
  * `match` lets you define custom handlers for both success and failure
@@ -3340,13 +3399,6 @@ export const when = internal.when;
  * to process the result if the effect succeeds, or handle the error if the
  * effect fails.
  *
- * **When to Use**
- *
- * This is useful for structuring your code to respond differently to success or
- * failure without triggering side effects.
- *
- * @see {@link matchEffect} if you need to perform side effects in the handlers.
- *
  * **Example** (Matching success and failure values)
  *
  * ```ts
@@ -3379,6 +3431,7 @@ export const when = internal.when;
  * // Output: "failure: Uh oh!"
  * ```
  *
+ * @see {@link matchEffect} if you need to perform side effects in the handlers.
  * @category Pattern Matching
  * @since 2.0.0
  */
@@ -3387,6 +3440,12 @@ export const match = internal.match;
  * Handles both success and failure cases of an effect without performing side
  * effects, with eager evaluation for resolved effects.
  *
+ * **When to use**
+ *
+ * Use this when you need to handle both success and failure cases and want
+ * optimal performance for resolved effects. This is particularly useful in
+ * scenarios where you frequently work with already computed values.
+ *
  * **Details**
  *
  * `matchEager` works like `match` but provides better performance for resolved
@@ -3394,12 +3453,6 @@ export const match = internal.match;
  * the handlers immediately without fiber scheduling. For unresolved effects,
  * it falls back to the regular `match` behavior.
  *
- * **When to Use**
- *
- * Use this when you need to handle both success and failure cases and want
- * optimal performance for resolved effects. This is particularly useful in
- * scenarios where you frequently work with already computed values.
- *
  * **Example** (Pattern matching eagerly when possible)
  *
  * ```ts
@@ -3416,7 +3469,6 @@ export const match = internal.match;
  *
  * @see {@link match} for the non-eager version.
  * @see {@link matchEffect} if you need to perform side effects in the handlers.
- *
  * @category Pattern Matching
  * @since 4.0.0
  */
@@ -3424,17 +3476,17 @@ export const matchEager = internal.matchEager;
 /**
  * Handles failures by matching the cause of failure.
  *
- * **Details**
- *
- * The `matchCause` function allows you to handle failures with access to the
- * full cause of the failure within a fiber.
- *
- * **When to Use**
+ * **When to use**
  *
  * This is useful for differentiating between different types of errors, such as
  * regular failures, defects, or interruptions. You can provide specific
  * handling logic for each failure type based on the cause.
  *
+ * **Details**
+ *
+ * The `matchCause` function allows you to handle failures with access to the
+ * full cause of the failure within a fiber.
+ *
  * **Example** (Matching on success or failure causes)
  *
  * ```ts
@@ -3454,7 +3506,6 @@ export const matchEager = internal.matchEager;
  * @see {@link matchCauseEffect} if you need to perform side effects in the
  * handlers.
  * @see {@link match} if you don't need to handle the cause of the failure.
- *
  * @category Pattern Matching
  * @since 2.0.0
  */
@@ -3462,18 +3513,18 @@ export const matchCause = internal.matchCause;
 /**
  * Handles failures by matching the cause of failure with eager evaluation.
  *
+ * **When to use**
+ *
+ * This is useful when you have effects that are likely to be already resolved
+ * and you want to avoid the overhead of the effect pipeline. For pending effects,
+ * it automatically falls back to the regular `matchCause` behavior.
+ *
  * **Details**
  *
  * `matchCauseEager` works like `matchCause` but provides better performance for resolved
  * effects by immediately applying the matching function instead of deferring it
  * through the effect pipeline.
  *
- * **When to Use**
- *
- * This is useful when you have effects that are likely to be already resolved
- * and you want to avoid the overhead of the effect pipeline. For pending effects,
- * it automatically falls back to the regular `matchCause` behavior.
- *
  * **Example** (Eagerly matching already completed effects)
  *
  * ```ts
@@ -3492,6 +3543,8 @@ export const matchCauseEager = internal.matchCauseEager;
 /**
  * Eagerly handles success or failure with effectful handlers when the effect is already resolved.
  *
+ * **Details**
+ *
  * If the effect is an `Exit`, the matching handler runs immediately; otherwise it behaves like
  * {@link matchCauseEffect}.
  *
@@ -3557,19 +3610,16 @@ export const matchCauseEffect = internal.matchCauseEffect;
 /**
  * Handles both success and failure by running effectful handlers.
  *
+ * **When to use**
+ *
+ * Use this when the failure or success branch must run additional effects.
+ *
  * **Details**
  *
  * Use `matchEffect` when either branch needs to return an `Effect`, such as
  * performing logging, recovery, notification, or other effectful work. The
  * returned effect succeeds or fails according to the handler that is run.
  *
- * **When to Use**
- *
- * Use this when the failure or success branch must run additional effects.
- *
- * @see {@link match} if you don't need side effects and only want to handle the
- * result or failure.
- *
  * **Example** (Matching success and failure with effectful handlers)
  *
  * ```ts
@@ -3611,6 +3661,8 @@ export const matchCauseEffect = internal.matchCauseEffect;
  * // failure: Uh oh!
  * ```
  *
+ * @see {@link match} if you don't need side effects and only want to handle the
+ * result or failure.
  * @category Pattern Matching
  * @since 2.0.0
  */
@@ -3621,6 +3673,8 @@ export const matchEffect = internal.matchEffect;
 /**
  * Determines whether an effect fails.
  *
+ * **Details**
+ *
  * Defects are not converted; if the effect dies, the resulting effect dies too.
  *
  * **Example** (Checking whether an effect fails)
@@ -3644,6 +3698,8 @@ export const isFailure = internal.isFailure;
 /**
  * Returns whether an effect completes successfully.
  *
+ * **Details**
+ *
  * Returns `false` for failures in the error channel, but defects still fail the
  * effect.
  *
@@ -3675,6 +3731,8 @@ export const isSuccess = internal.isSuccess;
 /**
  * Returns the complete context.
  *
+ * **Details**
+ *
  * This function allows you to access all services that are currently available
  * in the effect's environment. This can be useful for debugging, introspection,
  * or when you need to pass the entire context to another function.
@@ -3715,6 +3773,8 @@ export const context = internal.context;
 /**
  * Transforms the current context using the provided function.
  *
+ * **Details**
+ *
  * This function allows you to access the complete context and perform
  * computations based on all available services. This is useful when you need
  * to conditionally execute logic based on what services are available.
@@ -3940,6 +4000,8 @@ export const updateContext = internal.updateContext;
  * Runs an effect with a service implementation transformed by the provided
  * function.
  *
+ * **Details**
+ *
  * The service must be available in the effect's context; `updateService`
  * replaces it for the wrapped effect with the value returned by the updater.
  *
@@ -3974,14 +4036,14 @@ export const updateService = internal.updateService;
  * The `provideService` function is used to provide an actual
  * implementation for a service in the context of an effect.
  *
+ * **Details**
+ *
  * This function allows you to associate a service with its implementation so
  * that it can be used in your program. You define the service (e.g., a random
  * number generator), and then you use `provideService` to link that
  * service to its implementation. Once the implementation is provided, the
  * effect can be run successfully without further requirements.
  *
- * @see {@link provide} for providing multiple layers to an effect.
- *
  * **Example** (Providing a service value)
  *
  * ```ts
@@ -4013,6 +4075,7 @@ export const updateService = internal.updateService;
  * // data
  * ```
  *
+ * @see {@link provide} for providing multiple layers to an effect.
  * @category Context
  * @since 2.0.0
  */
@@ -4275,6 +4338,8 @@ export const acquireRelease = internal.acquireRelease;
  * This function constructs a scoped resource from an Effect that acquires a
  * disposable value.
  *
+ * **Details**
+ *
  * The resource is automatically disposed when the surrounding
  * {@link Scope} is closed, using {@link Symbol.dispose} for
  * synchronous disposables or {@link Symbol.asyncDispose} for asynchronous
@@ -4284,8 +4349,6 @@ export const acquireRelease = internal.acquireRelease;
  * JavaScript disposal protocal instead of requiring an explicit release
  * function.
  *
- * @see [JavaScript `using` declarations](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/using)
- *
  * **Example** (Acquiring a disposable resource)
  *
  * ```ts
@@ -4306,6 +4369,7 @@ export const acquireRelease = internal.acquireRelease;
  * )
  * ```
  *
+ * @see [JavaScript `using` declarations](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/using)
  * @category resource management
  * @since 4.0.0
  */
@@ -4316,6 +4380,8 @@ export const acquireDisposable = internal.acquireDisposable;
  * etc.) will not be interrupted, and that the resource will always be released
  * when the `Effect` value completes execution.
  *
+ * **Details**
+ *
  * `acquireUseRelease` does the following:
  *
  *   1. Ensures that the `Effect` value that acquires the resource will not be
@@ -4388,6 +4454,8 @@ export const acquireUseRelease = internal.acquireUseRelease;
  * The finalizer is guaranteed to be run when the scope is closed, and it may
  * depend on the `Exit` value that the scope is closed with.
  *
+ * **Details**
+ *
  * Finalizers are useful for cleanup operations that must run regardless of
  * whether the effect succeeds or fails. They're commonly used for resource
  * cleanup, logging, or other side effects that should always occur.
@@ -4431,6 +4499,8 @@ export const addFinalizer = internal.addFinalizer;
  * specified `finalizer` is guaranteed to be executed, whether this effect
  * succeeds, fails, or is interrupted.
  *
+ * **Details**
+ *
  * For use cases that need access to the effect's result, see `onExit`.
  *
  * Finalizers offer very powerful guarantees, but they are low-level, and
@@ -4605,24 +4675,19 @@ export const onExitFilter = internal.onExitFilter;
  * Returns an effect that lazily computes a result and caches it for subsequent
  * evaluations.
  *
- * **Details**
- *
- * This function wraps an effect and ensures that its result is computed only
- * once. Once the result is computed, it is cached, meaning that subsequent
- * evaluations of the same effect will return the cached result without
- * re-executing the logic.
- *
- * **When to Use**
+ * **When to use**
  *
  * Use this function when you have an expensive or time-consuming operation that
  * you want to avoid repeating. The first evaluation will compute the result,
  * and all following evaluations will immediately return the cached value,
  * improving performance and reducing unnecessary work.
  *
- * @see {@link cachedWithTTL} for a similar function that includes a
- * time-to-live duration for the cached value.
- * @see {@link cachedInvalidateWithTTL} for a similar function that includes an
- * additional effect for manually invalidating the cached value.
+ * **Details**
+ *
+ * This function wraps an effect and ensures that its result is computed only
+ * once. Once the result is computed, it is cached, meaning that subsequent
+ * evaluations of the same effect will return the cached result without
+ * re-executing the logic.
  *
  * **Example** (Memoizing an effect until invalidated)
  *
@@ -4662,6 +4727,10 @@ export const onExitFilter = internal.onExitFilter;
  * // result 3
  * ```
  *
+ * @see {@link cachedWithTTL} for a similar function that includes a
+ * time-to-live duration for the cached value.
+ * @see {@link cachedInvalidateWithTTL} for a similar function that includes an
+ * additional effect for manually invalidating the cached value.
  * @category Caching
  * @since 2.0.0
  */
@@ -4670,6 +4739,17 @@ export const cached = internal.cached;
  * Returns an effect that caches its result for a specified `Duration`,
  * known as "timeToLive" (TTL).
  *
+ * **When to use**
+ *
+ * Use this function when you have an effect that involves costly operations or
+ * computations, and you want to avoid repeating them within a short time frame.
+ *
+ * It's ideal for scenarios where the result of an effect doesn't change
+ * frequently and can be reused for a specified duration.
+ *
+ * By caching the result, you can improve efficiency and reduce unnecessary
+ * computations, especially in performance-critical applications.
+ *
  * **Details**
  *
  * This function is used to cache the result of an effect for a specified amount
@@ -4682,22 +4762,6 @@ export const cached = internal.cached;
  * After the specified duration has passed, the cache expires, and the effect
  * will be recomputed upon the next evaluation.
  *
- * **When to Use**
- *
- * Use this function when you have an effect that involves costly operations or
- * computations, and you want to avoid repeating them within a short time frame.
- *
- * It's ideal for scenarios where the result of an effect doesn't change
- * frequently and can be reused for a specified duration.
- *
- * By caching the result, you can improve efficiency and reduce unnecessary
- * computations, especially in performance-critical applications.
- *
- * @see {@link cached} for a similar function that caches the result
- * indefinitely.
- * @see {@link cachedInvalidateWithTTL} for a similar function that includes an
- * additional effect for manually invalidating the cached value.
- *
  * **Example** (Memoizing an effect with TTL)
  *
  * ```ts
@@ -4730,6 +4794,10 @@ export const cached = internal.cached;
  * // result 2
  * ```
  *
+ * @see {@link cached} for a similar function that caches the result
+ * indefinitely.
+ * @see {@link cachedInvalidateWithTTL} for a similar function that includes an
+ * additional effect for manually invalidating the cached value.
  * @category Caching
  * @since 2.0.0
  */
@@ -4738,6 +4806,16 @@ export const cachedWithTTL = internal.cachedWithTTL;
  * Caches an effect's result for a specified duration and allows manual
  * invalidation before expiration.
  *
+ * **When to use**
+ *
+ * Use this function when you have an effect whose result needs to be cached for
+ * a certain period, but you also want the option to refresh the cache manually
+ * before the expiration time.
+ *
+ * This is useful when you need to ensure that the cached data remains valid for
+ * a certain period but still want to invalidate it if the underlying data
+ * changes or if you want to force a recomputation.
+ *
  * **Details**
  *
  * This function behaves similarly to {@link cachedWithTTL} by caching the
@@ -4751,21 +4829,6 @@ export const cachedWithTTL = internal.cachedWithTTL;
  * Once the cache is invalidated, the next time the effect is evaluated, the
  * result will be recomputed, and the cache will be refreshed.
  *
- * **When to Use**
- *
- * Use this function when you have an effect whose result needs to be cached for
- * a certain period, but you also want the option to refresh the cache manually
- * before the expiration time.
- *
- * This is useful when you need to ensure that the cached data remains valid for
- * a certain period but still want to invalidate it if the underlying data
- * changes or if you want to force a recomputation.
- *
- * @see {@link cached} for a similar function that caches the result
- * indefinitely.
- * @see {@link cachedWithTTL} for a similar function that caches the result for
- * a specified duration but does not include an effect for manual invalidation.
- *
  * **Example** (Memoizing with TTL and invalidation)
  *
  * ```ts
@@ -4801,6 +4864,10 @@ export const cachedWithTTL = internal.cachedWithTTL;
  * // result 2
  * ```
  *
+ * @see {@link cached} for a similar function that caches the result
+ * indefinitely.
+ * @see {@link cachedWithTTL} for a similar function that caches the result for
+ * a specified duration but does not include an effect for manual invalidation.
  * @category Caching
  * @since 2.0.0
  */
@@ -5112,6 +5179,8 @@ export const repeatOrElse = internalSchedule.repeatOrElse;
 /**
  * Returns an array of `n` identical effects.
  *
+ * **Details**
+ *
  * Use with `Effect.all` to run the replicated effects and collect results.
  *
  * @category Collecting
@@ -5121,6 +5190,8 @@ export const replicate = internal.replicate;
 /**
  * Performs this effect `n` times and collects results with `Effect.all` semantics.
  *
+ * **Details**
+ *
  * Use `concurrency` to control parallelism and `discard: true` to ignore results.
  *
  * **Example** (Replicating an effect)
@@ -5477,6 +5548,8 @@ export const spanLinks = internal.spanLinks;
 /**
  * For all spans in this effect, add a link with the provided span.
  *
+ * **Details**
+ *
  * This is useful for connecting spans that are related but not in a direct
  * parent-child relationship. For example, you might want to link spans from
  * parallel operations or connect spans across different traces.
@@ -5556,6 +5629,8 @@ export const makeSpan = internal.makeSpan;
  * Create a new span for tracing, and automatically close it when the Scope
  * finalizes.
  *
+ * **Details**
+ *
  * The span is not added to the current span stack, so no child spans will be
  * created for it.
  *
@@ -5582,6 +5657,8 @@ export const makeSpanScoped = internal.makeSpanScoped;
  * Create a new span for tracing, and automatically close it when the effect
  * completes.
  *
+ * **Details**
+ *
  * The span is not added to the current span stack, so no child spans will be
  * created for it.
  *
@@ -5629,6 +5706,8 @@ export const withSpan = internal.withSpan;
 /**
  * Wraps the effect with a new span for tracing.
  *
+ * **Details**
+ *
  * The span is ended when the Scope is finalized.
  *
  * **Example** (Creating a scoped child span)
@@ -5708,6 +5787,8 @@ export const request = internalRequest.request;
  * Low-level entry point that registers a request with a resolver and delivers the exit value via `onExit`.
  * Use this when you already have a `Context` and need to enqueue a request outside an `Effect`.
  *
+ * **Details**
+ *
  * It returns a canceler that removes the pending request entry.
  *
  * @category Requests & Batching
@@ -5722,6 +5803,8 @@ export const requestUnsafe = internalRequest.requestUnsafe;
  * returning the fiber immediately, without waiting for it to begin executing
  * the effect.
  *
+ * **Details**
+ *
  * You can use the `forkChild` method whenever you want to execute an effect in a
  * new fiber, concurrently and without "blocking" the fiber executing other
  * effects. Using fibers can be tricky, so instead of using this method
@@ -5915,7 +5998,7 @@ export const fiberId = internal.fiberId;
  * The foundational function for running effects, returning a "fiber" that can
  * be observed or interrupted.
  *
- * **When to Use**
+ * **When to use**
  *
  * `runFork` is used to run an effect in the background by creating a
  * fiber. It is the base function for all other run functions. It starts a fiber
@@ -5983,6 +6066,8 @@ export const runForkWith = internal.runForkWith;
 /**
  * Forks an effect with the provided services, registers `onExit` as a fiber observer, and returns an interruptor.
  *
+ * **Details**
+ *
  * The returned interruptor calls `fiber.interruptUnsafe`, optionally with an interruptor id.
  *
  * **Example** (Running with services and a callback)
@@ -6026,6 +6111,8 @@ export const runCallbackWith = internal.runCallbackWith;
  * Runs an effect asynchronously, registering `onExit` as a fiber observer and
  * returning an interruptor.
  *
+ * **Details**
+ *
  * The interruptor calls `fiber.interruptUnsafe` with the optional interruptor
  * id.
  *
@@ -6064,7 +6151,7 @@ export const runCallback = internal.runCallback;
 /**
  * Executes an effect and returns the result as a `Promise`.
  *
- * **When to Use**
+ * **When to use**
  *
  * Use `runPromise` when you need to execute an effect and work with the
  * result using `Promise` syntax, typically for compatibility with other
@@ -6073,8 +6160,6 @@ export const runCallback = internal.runCallback;
  * If the effect succeeds, the promise will resolve with the result. If the
  * effect fails, the promise will reject with an error.
  *
- * @see {@link runPromiseExit} for a version that returns an `Exit` type instead of rejecting.
- *
  * **Example** (Running a successful effect as a Promise)
  *
  * ```ts
@@ -6095,6 +6180,7 @@ export const runCallback = internal.runCallback;
  * // (FiberFailure) Error: my error
  * ```
  *
+ * @see {@link runPromiseExit} for a version that returns an `Exit` type instead of rejecting.
  * @category Running Effects
  * @since 2.0.0
  */
@@ -6133,7 +6219,7 @@ export const runPromiseWith = internal.runPromiseWith;
  * Runs an effect and returns a `Promise` that resolves to an `Exit`, which
  * represents the outcome (success or failure) of the effect.
  *
- * **When to Use**
+ * **When to use**
  *
  * Use `runPromiseExit` when you need to determine if an effect succeeded
  * or failed, including any defects, and you want to work with a `Promise`.
@@ -6214,7 +6300,7 @@ export const runPromiseExitWith = internal.runPromiseExitWith;
 /**
  * Executes an effect synchronously and returns its success value.
  *
- * **When to Use**
+ * **When to use**
  *
  * Use `runSync` only for effects that can complete synchronously.
  *
@@ -6224,9 +6310,6 @@ export const runPromiseExitWith = internal.runPromiseExitWith;
  * `runSync` throws a `FiberFailure` instead of returning a value. Use
  * `runSyncExit` when you want the failure captured as an `Exit`.
  *
- * @see {@link runSyncExit} for a version that returns an `Exit` type instead of
- * throwing an error.
- *
  * **Example** (Running a synchronous effect)
  *
  * ```ts
@@ -6268,6 +6351,8 @@ export const runPromiseExitWith = internal.runPromiseExitWith;
  * // (FiberFailure) AsyncFiberException: Fiber #0 cannot be resolved synchronously. This is caused by using runSync on an effect that performs async work
  * ```
  *
+ * @see {@link runSyncExit} for a version that returns an `Exit` type instead of
+ * throwing an error.
  * @category Running Effects
  * @since 2.0.0
  */
@@ -6307,7 +6392,7 @@ export const runSyncWith = internal.runSyncWith;
  * Runs an effect synchronously and returns the result as an `Exit` type, which
  * represents the outcome (success or failure) of the effect.
  *
- * **When to Use**
+ * **When to use**
  *
  * Use `runSyncExit` to find out whether an effect succeeded or failed,
  * including any defects, without dealing with asynchronous operations.
@@ -6418,6 +6503,8 @@ export const runSyncExitWith = internal.runSyncExitWith;
 /**
  * Creates an Effect-returning function without tracing.
  *
+ * **Details**
+ *
  * `Effect.fnUntraced` also acts as a `pipe` function, so you can append transforms after the body.
  *
  * **Example** (Defining untraced effect functions)
@@ -6440,6 +6527,8 @@ export const fnUntraced = internal.fnUntraced;
 /**
  * Creates a traced function with an optional span name and `SpanOptionsNoTrace` that adds spans and stack frames, plus pipeable post-processing that receives the Effect and the original arguments.
  *
+ * **Details**
+ *
  * Pipeable functions run after the body and can transform the resulting Effect.
  *
  * **Example** (Defining traced effect functions)
@@ -6500,6 +6589,8 @@ export const clockWith = internal.clockWith;
 /**
  * Creates a logger function that logs at the specified level.
  *
+ * **Details**
+ *
  * If no level is provided, the logger uses the fiber's current log level and
  * extracts any `Cause` values from the message list.
  *
@@ -6801,6 +6892,8 @@ export const annotateLogs = /*#__PURE__*/dual(args => isEffect(args[0]), (effect
 /**
  * Adds log annotations to the current scope.
  *
+ * **Details**
+ *
  * This differs from `annotateLogs`, which only annotates a specific effect.
  * `annotateLogsScoped` updates annotations for the entire current `Scope` and
  * restores the previous annotations when the scope closes.
@@ -6866,6 +6959,8 @@ export const withLogSpan = /*#__PURE__*/dual(2, (effect, label) => internal.flat
 /**
  * Updates the `Metric` every time the `Effect` is executed.
  *
+ * **Details**
+ *
  * Also accepts an optional function which can be used to map the `Exit` value
  * of the `Effect` into a valid `Input` for the `Metric`.
  *
@@ -6921,6 +7016,8 @@ export const track = /*#__PURE__*/dual(args => isEffect(args[0]), (self, metric,
  * Updates the provided `Metric` every time the wrapped `Effect` succeeds with
  * a value.
  *
+ * **Details**
+ *
  * Also accepts an optional function which can be used to map the success value
  * of the `Effect` into a valid `Input` for the `Metric`.
  *
@@ -6972,6 +7069,8 @@ export const trackSuccesses = /*#__PURE__*/dual(args => isEffect(args[0]), (self
  * Updates the provided `Metric` every time the wrapped `Effect` fails with an
  * **expected** error.
  *
+ * **Details**
+ *
  * Also accepts an optional function which can be used to map the error value
  * of the `Effect` into a valid `Input` for the `Metric`.
  *
@@ -7025,6 +7124,8 @@ export const trackErrors = /*#__PURE__*/dual(args => isEffect(args[0]), (self, m
  * Updates the provided `Metric` every time the wrapped `Effect` fails with an
  * **unexpected** error (i.e. a defect).
  *
+ * **Details**
+ *
  * Also accepts an optional function which can be used to map the defect value
  * of the `Effect` into a valid `Input` for the `Metric`.
  *
@@ -7079,6 +7180,8 @@ export const trackDefects = /*#__PURE__*/dual(args => isEffect(args[0]), (self,
  * Updates the provided `Metric` with the `Duration` of time (in nanoseconds)
  * that the wrapped `Effect` took to complete.
  *
+ * **Details**
+ *
  * Also accepts an optional function which can be used to map the `Duration`
  * that the wrapped `Effect` took to complete into a valid `Input` for the
  * `Metric`.
@@ -7136,6 +7239,8 @@ export const trackDuration = /*#__PURE__*/dual(args => isEffect(args[0]), (self,
 /**
  * Service that holds the current transaction state, it includes
  *
+ * **Details**
+ *
  * - a journal that stores any non committed change to TxRef values
  * - a retry flag to know if the transaction should be retried
  *
@@ -7160,6 +7265,8 @@ export class Transaction extends /*#__PURE__*/Context.Service()("effect/Effect/T
  * Defines a transaction boundary. Transactions are "all or nothing" with respect to changes
  * made to transactional values (i.e. TxRef) that occur within the transaction body.
  *
+ * **Details**
+ *
  * If called inside an active transaction, `tx` composes with the current transaction and reuses
  * its journal and retry state instead of creating a nested boundary.
  *
@@ -7278,10 +7385,9 @@ function clearTransaction(state) {
 /**
  * Signals that the current transaction needs to be retried.
  *
- * NOTE: the transaction retries on any change to transactional values (i.e. TxRef) accessed in its body.
+ * **Details**
  *
- * @category Transactions
- * @since 4.0.0
+ * NOTE: the transaction retries on any change to transactional values (i.e. TxRef) accessed in its body.
  *
  * **Example** (Retrying transactions)
  *
@@ -7311,6 +7417,9 @@ function clearTransaction(state) {
  *
  * Effect.runPromise(program).catch(console.error)
  * ```
+ *
+ * @category Transactions
+ * @since 4.0.0
  */
 export const txRetry = /*#__PURE__*/flatMap(Transaction, state => {
   state.retry = true;
@@ -7383,6 +7492,8 @@ export const effectify = (fn, onError, onSyncError) => (...args) => callback(res
 /**
  * Ensures that an effect's success type extends a given type `A`.
  *
+ * **Details**
+ *
  * This function provides compile-time type checking to ensure that the success
  * value of an effect conforms to a specific type constraint.
  *
@@ -7410,6 +7521,8 @@ export const satisfiesSuccessType = () => effect => effect;
 /**
  * Ensures that an effect's error type extends a given type `E`.
  *
+ * **Details**
+ *
  * This function provides compile-time type checking to ensure that the error
  * type of an effect conforms to a specific type constraint.
  *
@@ -7439,6 +7552,8 @@ export const satisfiesErrorType = () => effect => effect;
 /**
  * Ensures that an effect's requirements type extends a given type `R`.
  *
+ * **Details**
+ *
  * This function provides compile-time type checking to ensure that the
  * requirements (context) type of an effect conforms to a specific type constraint.
  *
@@ -7467,13 +7582,15 @@ export const satisfiesServicesType = () => effect => effect;
  * An optimized version of `map` that checks if an effect is already resolved
  * and applies the mapping function eagerly when possible.
  *
- * **When to Use**
+ * **When to use**
  *
  * `mapEager` provides better performance for effects that are already resolved
  * by applying the transformation immediately instead of deferring it through
  * the effect pipeline.
  *
- * **Behavior**
+ * **Details**
+ *
+ * Behavior:
  *
  * - For **Success effects**: Applies the mapping function immediately to the value
  * - For **Failure effects**: Returns the failure as-is without applying the mapping
@@ -7501,13 +7618,15 @@ export const mapEager = internal.mapEager;
  * An optimized version of `mapError` that checks if an effect is already resolved
  * and applies the error mapping function eagerly when possible.
  *
- * **When to Use**
+ * **When to use**
  *
  * `mapErrorEager` provides better performance for effects that are already resolved
  * by applying the error transformation immediately instead of deferring it through
  * the effect pipeline.
  *
- * **Behavior**
+ * **Details**
+ *
+ * Behavior:
  *
  * - For **Success effects**: Returns the success as-is (no error to transform)
  * - For **Failure effects**: Applies the mapping function immediately to the error
@@ -7538,13 +7657,15 @@ export const mapErrorEager = internal.mapErrorEager;
  * An optimized version of `mapBoth` that checks if an effect is already resolved
  * and applies the appropriate mapping function eagerly when possible.
  *
- * **When to Use**
+ * **When to use**
  *
  * `mapBothEager` provides better performance for effects that are already resolved
  * by applying the transformation immediately instead of deferring it through
  * the effect pipeline.
  *
- * **Behavior**
+ * **Details**
+ *
+ * Behavior:
  *
  * - For **Success effects**: Applies the `onSuccess` function immediately to the value
  * - For **Failure effects**: Applies the `onFailure` function immediately to the error
@@ -7577,13 +7698,15 @@ export const mapBothEager = internal.mapBothEager;
  * An optimized version of `flatMap` that checks if an effect is already resolved
  * and applies the flatMap function eagerly when possible.
  *
- * **When to Use**
+ * **When to use**
  *
  * `flatMapEager` provides better performance for effects that are already resolved
  * by applying the transformation immediately instead of deferring it through
  * the effect pipeline.
  *
- * **Behavior**
+ * **Details**
+ *
+ * Behavior:
  *
  * - For **Success effects**: Applies the flatMap function immediately to the value
  * - For **Failure effects**: Returns the failure as-is without applying the flatMap
@@ -7614,13 +7737,15 @@ export const flatMapEager = internal.flatMapEager;
  * An optimized version of `catch` that checks if an effect is already resolved
  * and applies the catch function eagerly when possible.
  *
- * **When to Use**
+ * **When to use**
  *
  * `catchEager` provides better performance for effects that are already resolved
  * by applying the error recovery immediately instead of deferring it through
  * the effect pipeline.
  *
- * **Behavior**
+ * **Details**
+ *
+ * Behavior:
  *
  * - For **Success effects**: Returns the success as-is (no error to catch)
  * - For **Failure effects**: Applies the catch function immediately to the error
@@ -7660,6 +7785,8 @@ export const catchEager = internal.catchEager;
 /**
  * Creates untraced function effects with eager evaluation optimization.
  *
+ * **Details**
+ *
  * Executes generator functions eagerly when all yielded effects are synchronous,
  * stopping at the first async effect and deferring to normal execution.
  *