effect 4.0.0-beta.67 → 4.0.0-beta.68

package/dist/Effect.js

@@ -15,7 +15,7 @@ import { internalCall } from "./Utils.js";
  * Runtime identifier used to recognize `Effect` values.
  *
  * @category Type identifiers
- * @since 2.0.0
+ * @since 4.0.0
  */
 export const TypeId = core.EffectTypeId;
 /**
@@ -30,7 +30,7 @@ export const TypeId = core.EffectTypeId;
  * console.log(Effect.isEffect("hello")) // false
  * ```
  *
- * @category Guards
+ * @category guards
  * @since 2.0.0
  */
 export const isEffect = core.isEffect;
@@ -190,7 +190,7 @@ export const all = internal.all;
  * ```
  *
  * @category Collecting
- * @since 3.0.0
+ * @since 2.0.0
  */
 export const partition = internal.partition;
 /**
@@ -227,7 +227,7 @@ export const partition = internal.partition;
  * ```
  *
  * @category Error Accumulation
- * @since 4.0.0
+ * @since 2.0.0
  */
 export const validate = internal.validate;
 /**
@@ -287,8 +287,7 @@ export const findFirstFilter = internal.findFirstFilter;
  * **Example** (Applying Effects to Iterable Elements)
  *
  * ```ts
- * import { Effect } from "effect"
- * import { Console } from "effect"
+ * import { Console, Effect } from "effect"
  *
  * const result = Effect.forEach(
  *   [1, 2, 3, 4, 5],
@@ -309,8 +308,7 @@ export const findFirstFilter = internal.findFirstFilter;
  * **Example** (Using discard to Ignore Results)
  *
  * ```ts
- * import { Effect } from "effect"
- * import { Console } from "effect"
+ * import { Console, Effect } from "effect"
  *
  * // Apply effects but discard the results
  * const result = Effect.forEach(
@@ -382,7 +380,7 @@ export const whileLoop = internal.whileLoop;
  * This defect is not a standard error but indicates a flaw in the logic that
  * was expected to be error-free. You can think of it similar to an unexpected
  * crash in the program, which can be further managed or logged using tools like
- * {@link catchAllDefect}.
+ * {@link catchDefect}.
  *
  * **Interruptions**
  *
@@ -646,7 +644,7 @@ export const suspend = internal.suspend;
  * This defect is not a standard error but indicates a flaw in the logic that
  * was expected to be error-free. You can think of it similar to an unexpected
  * crash in the program, which can be further managed or logged using tools like
- * {@link catchAllDefect}.
+ * {@link catchDefect}.
  *
  * @see {@link try_ | try} for a version that can handle failures.
  *
@@ -698,12 +696,6 @@ undefined_ as undefined };
  * Use `Effect.callback` when integrating APIs that complete through callbacks
  * instead of returning a `Promise`.
  *
- * **Previously Known As**
- *
- * This API replaces the following from Effect 3.x:
- *
- * - `Effect.async`
- *
  * **Example** (Usage)
  *
  * ```ts
@@ -722,7 +714,7 @@ undefined_ as undefined };
  * ```
  *
  * @category Creating Effects
- * @since 2.0.0
+ * @since 4.0.0
  */
 export const callback = internal.callback;
 /**
@@ -755,8 +747,7 @@ export const never = internal.never;
  * **Example** (Usage)
  *
  * ```ts
- * import { Effect } from "effect"
- * import { pipe } from "effect/Function"
+ * import { Effect, pipe } from "effect"
  *
  * const program = pipe(
  *   Effect.Do,
@@ -767,7 +758,7 @@ export const never = internal.never;
  * ```
  *
  * @category Do notation
- * @since 4.0.0
+ * @since 2.0.0
  */
 export const Do = internal.Do;
 /**
@@ -775,7 +766,7 @@ export const Do = internal.Do;
  * record used in do notation pipelines.
  *
  * @category Do notation
- * @since 4.0.0
+ * @since 2.0.0
  */
 export const bindTo = internal.bindTo;
 const let_ = internal.let;
@@ -784,14 +775,14 @@ export {
  * Adds a computed plain value to the do notation record.
  *
  * @category Do notation
- * @since 4.0.0
+ * @since 2.0.0
  */
 let_ as let };
 /**
  * Adds an `Effect` value to the do notation record under a given name.
  *
  * @category Do notation
- * @since 4.0.0
+ * @since 2.0.0
  */
 export const bind = internal.bind;
 /**
@@ -853,7 +844,7 @@ export const gen = internal.gen;
  *
  * 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 catchAll} or {@link catchTag}.
+ * functions like {@link catchTag} or {@link catchTags}.
  *
  * @see {@link succeed} to create an effect that represents a successful value.
  *
@@ -961,8 +952,7 @@ 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 dieSync} for a variant that throws a specified error, evaluated lazily.
- * @see {@link dieMessage} for a variant that throws a `RuntimeException` with a message.
+ * @see {@link die} for a variant that dies with an already computed defect.
  *
  * **Example** (Terminating on Division by Zero with a Specified Error)
  *
@@ -1093,7 +1083,7 @@ export const yieldNow = internal.yieldNow;
  * ```
  *
  * @category Creating Effects
- * @since 2.0.0
+ * @since 4.0.0
  */
 export const yieldNowWith = internal.yieldNowWith;
 /**
@@ -1113,7 +1103,7 @@ export const yieldNowWith = internal.yieldNowWith;
  * ```
  *
  * @category Creating Effects
- * @since 2.0.0
+ * @since 4.0.0
  */
 export const withFiber = core.withFiber;
 // -----------------------------------------------------------------------------
@@ -1138,7 +1128,7 @@ export const withFiber = core.withFiber;
  * // { _id: 'Exit', _tag: 'Failure', cause: { _id: 'Cause', _tag: 'Fail', failure: 'Something went wrong' } }
  * ```
  *
- * @category Conversions
+ * @category converting
  * @since 4.0.0
  */
 export const fromResult = internal.fromResult;
@@ -1164,7 +1154,7 @@ export const fromResult = internal.fromResult;
  * // { _id: 'Exit', _tag: 'Failure', cause: { _id: 'Cause', _tag: 'Fail', failure: { _id: 'NoSuchElementError' } } }
  * ```
  *
- * @category Conversions
+ * @category converting
  * @since 4.0.0
  */
 export const fromOption = internal.fromOption;
@@ -1190,7 +1180,7 @@ export const fromOption = internal.fromOption;
  * // Output: hello
  * ```
  *
- * @category Conversions
+ * @category converting
  * @since 4.0.0
  */
 export const fromNullishOr = internal.fromNullishOr;
@@ -1258,7 +1248,7 @@ export const fromNullishOr = internal.fromNullishOr;
  *
  * @see {@link tap} for a version that ignores the result of the effect.
  *
- * @category Sequencing
+ * @category sequencing
  * @since 2.0.0
  */
 export const flatMap = internal.flatMap;
@@ -1279,7 +1269,7 @@ export const flatMap = internal.flatMap;
  * })
  * ```
  *
- * @category Sequencing
+ * @category sequencing
  * @since 2.0.0
  */
 export const flatten = internal.flatten;
@@ -1312,12 +1302,6 @@ export const flatten = internal.flatten;
  * Failures or requirements from either effect are preserved in the returned
  * effect.
  *
- * **Previously Known As**
- *
- * This API replaces the following from Effect 3.x:
- *
- * - `Effect.zipRight`
- *
  * **Example** (Applying a Discount Based on Fetched Amount)
  *
  * ```ts
@@ -1358,7 +1342,7 @@ export const flatten = internal.flatten;
  * // Output: 190
  * ```
  *
- * @category Sequencing
+ * @category sequencing
  * @since 2.0.0
  */
 export const andThen = internal.andThen;
@@ -1379,17 +1363,10 @@ export const andThen = internal.andThen;
  * next part of the chain. Note that if the side effect fails, the entire chain
  * will fail too.
  *
- * **Previously Known As**
- *
- * This API replaces the following from Effect 3.x:
- *
- * - `Effect.zipLeft`
- *
  * **Example** (Logging a step in a pipeline)
  *
  * ```ts
- * import { Data, Effect, pipe } from "effect"
- * import { Console } from "effect"
+ * import { Console, Data, Effect, pipe } from "effect"
  *
  * class DiscountRateError extends Data.TaggedError("DiscountRateError")<{}> {}
  *
@@ -1419,7 +1396,7 @@ export const andThen = internal.andThen;
  * // 95
  * ```
  *
- * @category Sequencing
+ * @category sequencing
  * @since 2.0.0
  */
 export const tap = internal.tap;
@@ -1446,12 +1423,6 @@ export const tap = internal.tap;
  * The resulting effect cannot fail directly because all recoverable failures
  * are represented inside the `Result` type.
  *
- * **Previously Known As**
- *
- * This API replaces the following from Effect 3.x:
- *
- * - `Effect.either`
- *
  * **Example** (Usage)
  *
  * ```ts
@@ -1592,7 +1563,7 @@ export const exit = internal.exit;
  * @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
+ * @category mapping
  * @since 2.0.0
  */
 export const map = internal.map;
@@ -1614,7 +1585,7 @@ export const map = internal.map;
  * // Output: "new value"
  * ```
  *
- * @category Mapping
+ * @category mapping
  * @since 2.0.0
  */
 export const as = internal.as;
@@ -1634,7 +1605,7 @@ export const as = internal.as;
  * // { _id: 'Option', _tag: 'Some', value: 42 }
  * ```
  *
- * @category Mapping
+ * @category mapping
  * @since 2.0.0
  */
 export const asSome = internal.asSome;
@@ -1655,7 +1626,7 @@ export const asSome = internal.asSome;
  * // undefined (void)
  * ```
  *
- * @category Mapping
+ * @category mapping
  * @since 2.0.0
  */
 export const asVoid = internal.asVoid;
@@ -1682,7 +1653,7 @@ export const asVoid = internal.asVoid;
  * const flipped = Effect.flip(program)
  * ```
  *
- * @category Mapping
+ * @category mapping
  * @since 2.0.0
  */
 export const flip = internal.flip;
@@ -1754,7 +1725,7 @@ export const flip = internal.flip;
  * // [ 1, 'hello' ]
  * ```
  *
- * @category Zipping
+ * @category zipping
  * @since 2.0.0
  */
 export const zip = internal.zip;
@@ -1801,7 +1772,7 @@ export const zip = internal.zip;
  * // 6
  * ```
  *
- * @category Zipping
+ * @category zipping
  * @since 2.0.0
  */
 export const zipWith = internal.zipWith;
@@ -1825,13 +1796,7 @@ export {
  *
  * @see {@link catchCause} for a version that can recover from both recoverable and unrecoverable errors.
  *
- * **Previously Known As**
- *
- * This API replaces the following from Effect 3.x:
- *
- * - `Effect.catchAll`
- *
- * @category Error Handling
+ * @category error handling
  * @since 4.0.0
  */
 catch_ as catch };
@@ -1873,7 +1838,7 @@ catch_ as catch };
  * )
  * ```
  *
- * @category Error Handling
+ * @category error handling
  * @since 2.0.0
  */
 export const catchTag = internal.catchTag;
@@ -1917,7 +1882,7 @@ export const catchTag = internal.catchTag;
  * })
  * ```
  *
- * @category Error Handling
+ * @category error handling
  * @since 2.0.0
  */
 export const catchTags = internal.catchTags;
@@ -1954,7 +1919,7 @@ export const catchTags = internal.catchTags;
  * )
  * ```
  *
- * @category Error Handling
+ * @category error handling
  * @since 4.0.0
  */
 export const catchReason = internal.catchReason;
@@ -1990,7 +1955,7 @@ export const catchReason = internal.catchReason;
  * )
  * ```
  *
- * @category Error Handling
+ * @category error handling
  * @since 4.0.0
  */
 export const catchReasons = internal.catchReasons;
@@ -2022,7 +1987,7 @@ export const catchReasons = internal.catchReasons;
  * const unwrapped = program.pipe(Effect.unwrapReason("AiError"))
  * ```
  *
- * @category Error Handling
+ * @category error handling
  * @since 4.0.0
  */
 export const unwrapReason = internal.unwrapReason;
@@ -2043,12 +2008,6 @@ export const unwrapReason = internal.unwrapReason;
  * they often indicate serious issues. However, in some cases, such as
  * dynamically loaded plugins, controlled recovery might be needed.
  *
- * **Previously Known As**
- *
- * This API replaces the following from Effect 3.x:
- *
- * - `Effect.catchAllCause`
- *
  * **Example** (Usage)
  *
  * ```ts
@@ -2068,7 +2027,7 @@ export const unwrapReason = internal.unwrapReason;
  * })
  * ```
  *
- * @category Error Handling
+ * @category error handling
  * @since 4.0.0
  */
 export const catchCause = internal.catchCause;
@@ -2091,12 +2050,6 @@ export const catchCause = internal.catchCause;
  * they often indicate serious issues. In some cases, such as dynamically loaded
  * plugins, controlled recovery may be needed.
  *
- * **Previously Known As**
- *
- * This API replaces the following from Effect 3.x:
- *
- * - `Effect.catchAllDefect`
- *
  * **Example** (Usage)
  *
  * ```ts
@@ -2115,7 +2068,7 @@ export const catchCause = internal.catchCause;
  * })
  * ```
  *
- * @category Error Handling
+ * @category error handling
  * @since 4.0.0
  */
 export const catchDefect = internal.catchDefect;
@@ -2129,13 +2082,6 @@ export const catchDefect = internal.catchDefect;
  * matching. Non-matching errors re-fail with the original cause. Defects and
  * interrupts are not caught.
  *
- * **Previously Known As**
- *
- * This API replaces the following:
- *
- * - `Effect.catchSome` (Effect 3.x)
- * - `Effect.catchIf`
- *
  * **Example** (Usage)
  *
  * ```ts
@@ -2162,14 +2108,14 @@ export const catchDefect = internal.catchDefect;
  * )
  * ```
  *
- * @category Error Handling
+ * @category error handling
  * @since 2.0.0
  */
 export const catchIf = internal.catchIf;
 /**
  * Recovers from specific errors using a `Filter`.
  *
- * @category Error Handling
+ * @category error handling
  * @since 4.0.0
  */
 export const catchFilter = internal.catchFilter;
@@ -2191,14 +2137,8 @@ export const catchFilter = internal.catchFilter;
  * Effect.runPromise(none).then(console.log) // { _id: 'Option', _tag: 'None' }
  * ```
  *
- * **Previously Known As**
- *
- * This API replaces the following from Effect 3.x:
- *
- * - `Effect.optionFromOptional`
- *
- * @category Error Handling
- * @since 2.0.0
+ * @category error handling
+ * @since 4.0.0
  */
 export const catchNoSuchElement = internal.catchNoSuchElement;
 /**
@@ -2208,12 +2148,6 @@ export const catchNoSuchElement = internal.catchNoSuchElement;
  * that match a specific predicate. This is useful when you want to handle
  * only certain types of errors while letting others propagate.
  *
- * **Previously Known As**
- *
- * This API replaces the following from Effect 3.x:
- *
- * - `Effect.catchSomeCause`
- *
  * **Example** (Usage)
  *
  * ```ts
@@ -2237,14 +2171,14 @@ export const catchNoSuchElement = internal.catchNoSuchElement;
  * // Then: "Fallback response"
  * ```
  *
- * @category Error Handling
+ * @category error handling
  * @since 4.0.0
  */
 export const catchCauseIf = internal.catchCauseIf;
 /**
  * Recovers from specific failures based on a `Filter`.
  *
- * @category Error Handling
+ * @category error handling
  * @since 4.0.0
  */
 export const catchCauseFilter = internal.catchCauseFilter;
@@ -2259,7 +2193,7 @@ 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 orElseFail} if you want to replace the error with a new one.
+ * @see {@link mapError} if you want to replace the error with a new one.
  *
  * **Example** (Usage)
  *
@@ -2280,7 +2214,7 @@ export const catchCauseFilter = internal.catchCauseFilter;
  * )
  * ```
  *
- * @category Error Handling
+ * @category error handling
  * @since 2.0.0
  */
 export const mapError = internal.mapError;
@@ -2316,7 +2250,7 @@ export const mapError = internal.mapError;
  * @see {@link map} for a version that operates on the success channel.
  * @see {@link mapError} for a version that operates on the error channel.
  *
- * @category Mapping
+ * @category mapping
  * @since 2.0.0
  */
 export const mapBoth = internal.mapBoth;
@@ -2329,7 +2263,7 @@ export const mapBoth = internal.mapBoth;
  * Use `orDie` when a typed failure represents an unrecoverable bug or invalid
  * state and should not be handled as a recoverable error.
  *
- * @see {@link orDieWith} if you need to customize the error.
+ * @see {@link mapError} to transform the error before converting it into a defect with {@link orDie}.
  *
  * **Example** (Propagating an Error as a Defect)
  *
@@ -2386,7 +2320,7 @@ export const orDie = internal.orDie;
  * // expected error: NetworkError
  * ```
  *
- * @category Sequencing
+ * @category sequencing
  * @since 2.0.0
  */
 export const tapError = internal.tapError;
@@ -2422,7 +2356,7 @@ export const tapError = internal.tapError;
  * // expected error: 504
  * ```
  *
- * @category Sequencing
+ * @category sequencing
  * @since 2.0.0
  */
 export const tapErrorTag = internal.tapErrorTag;
@@ -2436,12 +2370,6 @@ export const tapErrorTag = internal.tapErrorTag;
  * the operation succeeds, the original cause is preserved. If the operation
  * fails, its error is also represented in the returned effect.
  *
- * **Previously Known As**
- *
- * This API replaces the following from Effect 3.x:
- *
- * - `Effect.tapErrorCause`
- *
  * **Example** (Usage)
  *
  * ```ts
@@ -2459,8 +2387,8 @@ export const tapErrorTag = internal.tapErrorTag;
  * // Then: { _id: 'Exit', _tag: 'Failure', cause: ... }
  * ```
  *
- * @category Sequencing
- * @since 2.0.0
+ * @category sequencing
+ * @since 4.0.0
  */
 export const tapCause = internal.tapCause;
 /**
@@ -2489,14 +2417,14 @@ export const tapCause = internal.tapCause;
  * // Then: { _id: 'Exit', _tag: 'Failure', cause: ... }
  * ```
  *
- * @category Sequencing
+ * @category sequencing
  * @since 4.0.0
  */
 export const tapCauseIf = internal.tapCauseIf;
 /**
  * Conditionally executes a side effect based on the cause of a failed effect.
  *
- * @category Sequencing
+ * @category sequencing
  * @since 4.0.0
  */
 export const tapCauseFilter = internal.tapCauseFilter;
@@ -2544,7 +2472,7 @@ export const tapCauseFilter = internal.tapCauseFilter;
  * //   ... stack trace ...
  * ```
  *
- * @category Sequencing
+ * @category sequencing
  * @since 2.0.0
  */
 export const tapDefect = internal.tapDefect;
@@ -2627,7 +2555,7 @@ 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
+ * @category error handling
  * @since 2.0.0
  */
 export const retry = internalSchedule.retry;
@@ -2685,7 +2613,7 @@ export const retry = internalSchedule.retry;
  * // Network data
  * ```
  *
- * @category Error Handling
+ * @category error handling
  * @since 2.0.0
  */
 export const retryOrElse = internalSchedule.retryOrElse;
@@ -2715,9 +2643,9 @@ export const retryOrElse = internalSchedule.retryOrElse;
  * // Output: "Caught cause: Something went wrong"
  * ```
  *
- * @see {@link unsandbox} to restore the original error handling.
+ * @see {@link sandbox} to expose failures as full causes.
  *
- * @category Error Handling
+ * @category error handling
  * @since 2.0.0
  */
 export const sandbox = internal.sandbox;
@@ -2758,13 +2686,7 @@ export const sandbox = internal.sandbox;
  * const programWarn = task.pipe(Effect.ignore({ log: "Warn", message: "Ignoring task failure" }))
  * ```
  *
- * **Previously Known As**
- *
- * This API replaces the following from Effect 3.x:
- *
- * - `Effect.ignoreLogged`
- *
- * @category Error Handling
+ * @category error handling
  * @since 2.0.0
  */
 export const ignore = internal.ignore;
@@ -2785,7 +2707,7 @@ export const ignore = internal.ignore;
  * const programLog = task.pipe(Effect.ignoreCause({ log: true, message: "Ignoring failure cause" }))
  * ```
  *
- * @category Error Handling
+ * @category error handling
  * @since 4.0.0
  */
 export const ignoreCause = internal.ignoreCause;
@@ -2800,7 +2722,7 @@ export const ignoreCause = internal.ignoreCause;
  * **Example** (Usage)
  *
  * ```ts
- * import { Effect, ExecutionPlan, Layer, Context } from "effect"
+ * import { Context, Effect, ExecutionPlan, Layer } from "effect"
  *
  * const Endpoint = Context.Service<{ url: string }>("Endpoint")
  *
@@ -2830,7 +2752,7 @@ export const withExecutionPlan = internalExecutionPlan.withExecutionPlan;
  * If the `defectsOnly` option is set to `true`, only defects (unrecoverable
  * errors) will be reported, while regular failures will be ignored.
  *
- * @category Error Handling
+ * @category error handling
  * @since 4.0.0
  */
 export const withErrorReporting = internal.withErrorReporting;
@@ -2932,9 +2854,7 @@ export const firstSuccessOf = internal.firstSuccessOf;
  * your program waits for a task to finish, ensuring that it doesn't hang
  * indefinitely if the task takes too long.
  *
- * @see {@link timeoutFail} for a version that raises a custom error.
- * @see {@link timeoutFailCause} for a version that raises a custom defect.
- * @see {@link timeoutTo} for a version that allows specifying both success and timeout handlers.
+ * @see {@link timeoutOrElse} for a version that allows specifying both success and timeout handlers.
  *
  * **Example** (Usage)
  *
@@ -2982,9 +2902,7 @@ export const timeout = internal.timeout;
  * source effect fails before the timeout, that failure is preserved.
  *
  * @see {@link timeout} for a version that raises a `TimeoutException`.
- * @see {@link timeoutFail} for a version that raises a custom error.
- * @see {@link timeoutFailCause} for a version that raises a custom defect.
- * @see {@link timeoutTo} for a version that allows specifying both success and timeout handlers.
+ * @see {@link timeoutOrElse} for a version that allows specifying both success and timeout handlers.
  *
  * **Example** (Usage)
  *
@@ -3053,7 +2971,7 @@ export const timeoutOption = internal.timeoutOption;
  * ```
  *
  * @category Delays & Timeouts
- * @since 3.1.0
+ * @since 4.0.0
  */
 export const timeoutOrElse = internal.timeoutOrElse;
 /**
@@ -3271,21 +3189,21 @@ export const raceFirst = internal.raceFirst;
  * // Use Effect.filterMapEffect for effectful Filter.Filter callbacks
  * ```
  *
- * @category Filtering
+ * @category filtering
  * @since 2.0.0
  */
 export const filter = internal.filter;
 /**
  * Filters and maps elements of an iterable with a `Filter`.
  *
- * @category Filtering
- * @since 4.0.0
+ * @category filtering
+ * @since 2.0.0
  */
 export const filterMap = internal.filterMap;
 /**
  * Effectfully filters and maps elements of an iterable with a `FilterEffect`.
  *
- * @category Filtering
+ * @category filtering
  * @since 4.0.0
  */
 export const filterMapEffect = internal.filterMapEffect;
@@ -3317,14 +3235,14 @@ export const filterMapEffect = internal.filterMapEffect;
  * // Result: "Number 5 is odd" (since 5 is not even)
  * ```
  *
- * @category Filtering
+ * @category filtering
  * @since 2.0.0
  */
 export const filterOrElse = internal.filterOrElse;
 /**
  * Filters an effect with a `Filter`, providing an alternative effect on failure.
  *
- * @category Filtering
+ * @category filtering
  * @since 4.0.0
  */
 export const filterMapOrElse = internal.filterMapOrElse;
@@ -3355,14 +3273,14 @@ export const filterMapOrElse = internal.filterMapOrElse;
  * // Result: Effect.fail("Expected even number, got 5")
  * ```
  *
- * @category Filtering
+ * @category filtering
  * @since 2.0.0
  */
 export const filterOrFail = internal.filterOrFail;
 /**
  * Filters an effect with a `Filter`, failing when the filter fails.
  *
- * @category Filtering
+ * @category filtering
  * @since 4.0.0
  */
 export const filterMapOrFail = internal.filterMapOrFail;
@@ -3402,8 +3320,7 @@ export const filterMapOrFail = internal.filterMapOrFail;
  * // { _id: 'Option', _tag: 'Some', value: undefined }
  * ```
  *
- * @see {@link whenEffect} for a version that allows the condition to be an effect.
- * @see {@link unless} for a version that executes the effect when the condition is `false`.
+ * @see {@link when} for conditional execution with a boolean condition.
  *
  * @category Conditional Operators
  * @since 2.0.0
@@ -3501,7 +3418,7 @@ export const match = internal.match;
  * @see {@link matchEffect} if you need to perform side effects in the handlers.
  *
  * @category Pattern Matching
- * @since 2.0.0
+ * @since 4.0.0
  */
 export const matchEager = internal.matchEager;
 /**
@@ -3569,7 +3486,7 @@ export const matchCause = internal.matchCause;
  * ```
  *
  * @category Pattern Matching
- * @since 3.8.0
+ * @since 4.0.0
  */
 export const matchCauseEager = internal.matchCauseEager;
 /**
@@ -3765,7 +3682,7 @@ export const isSuccess = internal.isSuccess;
  * **Example** (Usage)
  *
  * ```ts
- * import { Console, Effect, Option, Context } from "effect"
+ * import { Console, Context, Effect, Option } from "effect"
  *
  * const Logger = Context.Service<{
  *   log: (msg: string) => void
@@ -3805,7 +3722,7 @@ export const context = internal.context;
  * **Example** (Usage)
  *
  * ```ts
- * import { Console, Effect, Option, Context } from "effect"
+ * import { Console, Context, Effect, Option } from "effect"
  *
  * const Logger = Context.Service<{
  *   log: (msg: string) => void
@@ -3849,7 +3766,7 @@ export const contextWith = internal.contextWith;
  * **Example** (Usage)
  *
  * ```ts
- * import { Effect, Layer, Context } from "effect"
+ * import { Context, Effect, Layer } from "effect"
  *
  * interface Database {
  *   readonly query: (sql: string) => Effect.Effect<string>
@@ -3888,7 +3805,7 @@ export const provide = internalLayer.provide;
  * **Example** (Usage)
  *
  * ```ts
- * import { Effect, Context } from "effect"
+ * import { Context, Effect } from "effect"
  *
  * // Define service keys
  * const Logger = Context.Service<{
@@ -3914,7 +3831,7 @@ export const provide = internalLayer.provide;
  * ```
  *
  * @category Environment
- * @since 2.0.0
+ * @since 4.0.0
  */
 export const provideContext = internal.provideContext;
 /**
@@ -3923,7 +3840,7 @@ export const provideContext = internal.provideContext;
  * **Example** (Usage)
  *
  * ```ts
- * import { Effect, Context } from "effect"
+ * import { Context, Effect } from "effect"
  *
  * interface Database {
  *   readonly query: (sql: string) => Effect.Effect<string>
@@ -3954,7 +3871,7 @@ export const service = internal.service;
  * **Example** (Usage)
  *
  * ```ts
- * import { Effect, Option, Context } from "effect"
+ * import { Context, Effect, Option } from "effect"
  *
  * // Define a service key
  * const Logger = Context.Service<{
@@ -3988,7 +3905,7 @@ export const serviceOption = internal.serviceOption;
  * **Example** (Usage)
  *
  * ```ts
- * import { Effect, Context } from "effect"
+ * import { Context, Effect } from "effect"
  *
  * // Define services
  * const Logger = Context.Service<{
@@ -4029,7 +3946,7 @@ export const updateContext = internal.updateContext;
  * **Example** (Usage)
  *
  * ```ts
- * import { Console, Effect, Context } from "effect"
+ * import { Console, Context, Effect } from "effect"
  *
  * // Define a counter service
  * const Counter = Context.Service<{ count: number }>("Counter")
@@ -4068,7 +3985,7 @@ export const updateService = internal.updateService;
  * **Example** (Usage)
  *
  * ```ts
- * import { Console, Effect, Context } from "effect"
+ * import { Console, Context, Effect } from "effect"
  *
  * // Define a service for configuration
  * const Config = Context.Service<{
@@ -4113,7 +4030,7 @@ export const provideService = internal.provideService;
  * **Example** (Usage)
  *
  * ```ts
- * import { Console, Effect, Context } from "effect"
+ * import { Console, Context, Effect } from "effect"
  *
  * // Define a database connection service
  * interface DatabaseConnection {
@@ -4186,7 +4103,7 @@ export const provideServiceEffect = internal.provideServiceEffect;
  * // [1, 2, 3, 4, 5]
  * ```
  *
- * @category References
+ * @category references
  * @since 2.0.0
  */
 export const withConcurrency = internal.withConcurrency;
@@ -4222,7 +4139,7 @@ export const withConcurrency = internal.withConcurrency;
  * // Releasing resource
  * ```
  *
- * @category Resource Management & Finalization
+ * @category resource management
  * @since 2.0.0
  */
 export const scope = internal.scope;
@@ -4255,7 +4172,7 @@ export const scope = internal.scope;
  * // Output: "Releasing resource"
  * ```
  *
- * @category Resource Management & Finalization
+ * @category resource management
  * @since 2.0.0
  */
 export const scoped = internal.scoped;
@@ -4295,8 +4212,8 @@ export const scoped = internal.scoped;
  * // Manual finalizer
  * ```
  *
- * @category Resource Management & Finalization
- * @since 2.0.0
+ * @category resource management
+ * @since 3.11.0
  */
 export const scopedWith = internal.scopedWith;
 /**
@@ -4350,7 +4267,7 @@ export const scopedWith = internal.scopedWith;
  * )
  * ```
  *
- * @category Resource Management & Finalization
+ * @category resource management
  * @since 2.0.0
  */
 export const acquireRelease = internal.acquireRelease;
@@ -4367,13 +4284,13 @@ export const acquireRelease = internal.acquireRelease;
  * JavaScript disposal protocal instead of requiring an explicit release
  * function.
  *
- * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/using}
+ * @see [JavaScript `using` declarations](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/using)
  *
  * **Example** (Usage)
  *
  * ```ts
  * import sqlite from "node:sqlite";
- * import { Effect } from "effect";
+ * import { Effect } from "effect"
  *
  * const program = Effect.scoped(
  *   Effect.gen(function* () {
@@ -4389,7 +4306,7 @@ export const acquireRelease = internal.acquireRelease;
  * )
  * ```
  *
- * @category Resource Management & Finalization
+ * @category resource management
  * @since 4.0.0
  */
 export const acquireDisposable = internal.acquireDisposable;
@@ -4462,7 +4379,7 @@ export const acquireDisposable = internal.acquireDisposable;
  * // Closing connection to db://localhost:5432 (success)
  * ```
  *
- * @category Resource Management & Finalization
+ * @category resource management
  * @since 2.0.0
  */
 export const acquireUseRelease = internal.acquireUseRelease;
@@ -4505,7 +4422,7 @@ export const acquireUseRelease = internal.acquireUseRelease;
  * // operation result
  * ```
  *
- * @category Resource Management & Finalization
+ * @category resource management
  * @since 2.0.0
  */
 export const addFinalizer = internal.addFinalizer;
@@ -4546,7 +4463,7 @@ export const addFinalizer = internal.addFinalizer;
  * // 42
  * ```
  *
- * @category Resource Management & Finalization
+ * @category resource management
  * @since 2.0.0
  */
 export const ensuring = internal.ensuring;
@@ -4557,7 +4474,7 @@ export const ensuring = internal.ensuring;
  * **Example** (Usage)
  *
  * ```ts
- * import { Cause, Data, Console, Effect } from "effect"
+ * import { Cause, Console, Data, Effect } from "effect"
  *
  * class TaskError extends Data.TaggedError("TaskError")<{ readonly message: string }> {}
  *
@@ -4574,7 +4491,7 @@ export const ensuring = internal.ensuring;
  * // TaskError: Something went wrong
  * ```
  *
- * @category Resource Management & Finalization
+ * @category resource management
  * @since 2.0.0
  */
 export const onError = internal.onError;
@@ -4599,14 +4516,14 @@ export const onError = internal.onError;
  * )
  * ```
  *
- * @category Resource Management & Finalization
+ * @category resource management
  * @since 4.0.0
  */
 export const onErrorIf = internal.onErrorIf;
 /**
  * Runs the finalizer only when this effect fails and the cause matches the provided `Filter`.
  *
- * @category Resource Management & Finalization
+ * @category resource management
  * @since 4.0.0
  */
 export const onErrorFilter = internal.onErrorFilter;
@@ -4619,8 +4536,8 @@ export const onErrorFilter = internal.onErrorFilter;
  * This low-level operator preserves the source effect's result unless the
  * finalizer fails. Prefer `onExit` for normal cleanup logic.
  *
- * @category Resource Management & Finalization
- * @since 2.0.0
+ * @category resource management
+ * @since 4.0.0
  */
 export const onExitPrimitive = internal.onExitPrimitive;
 /**
@@ -4647,7 +4564,7 @@ export const onExitPrimitive = internal.onExitPrimitive;
  * // 42
  * ```
  *
- * @category Resource Management & Finalization
+ * @category resource management
  * @since 2.0.0
  */
 export const onExit = internal.onExit;
@@ -4670,14 +4587,14 @@ export const onExit = internal.onExit;
  * )
  * ```
  *
- * @category Resource Management & Finalization
+ * @category resource management
  * @since 4.0.0
  */
 export const onExitIf = internal.onExitIf;
 /**
  * Runs the cleanup effect only when the `Exit` matches the provided `Filter`.
  *
- * @category Resource Management & Finalization
+ * @category resource management
  * @since 4.0.0
  */
 export const onExitFilter = internal.onExitFilter;
@@ -5110,9 +5027,7 @@ export const forever = internal.forever;
  *
  * ```ts
  * // Success Example
- * import { Effect } from "effect"
- * import { Schedule } from "effect"
- * import { Console } from "effect"
+ * import { Console, Effect, Schedule } from "effect"
  *
  * const action = Console.log("success")
  * const policy = Schedule.addDelay(Schedule.recurs(2), () => Effect.succeed("100 millis"))
@@ -5125,8 +5040,7 @@ export const forever = internal.forever;
  *
  * ```ts
  * // Failure Example
- * import { Effect } from "effect"
- * import { Schedule } from "effect"
+ * import { Effect, Schedule } from "effect"
  *
  * let count = 0
  *
@@ -5166,8 +5080,7 @@ export const repeat = internalSchedule.repeat;
  * **Example** (Usage)
  *
  * ```ts
- * import { Console, Effect, Schedule } from "effect"
- * import * as Option from "effect/Option"
+ * import { Console, Effect, Option, Schedule } from "effect"
  *
  * let attempt = 0
  * const task = Effect.gen(function*() {
@@ -5324,7 +5237,7 @@ export const scheduleFrom = internalSchedule.scheduleFrom;
  * })
  * ```
  *
- * @category Tracing
+ * @category tracing
  * @since 2.0.0
  */
 export const tracer = internal.tracer;
@@ -5345,7 +5258,7 @@ export const tracer = internal.tracer;
  * // const traced = Effect.withTracer(program, customTracer)
  * ```
  *
- * @category Tracing
+ * @category tracing
  * @since 2.0.0
  */
 export const withTracer = internal.withTracer;
@@ -5369,7 +5282,7 @@ export const withTracer = internal.withTracer;
  * )
  * ```
  *
- * @category Tracing
+ * @category tracing
  * @since 2.0.0
  */
 export const withTracerEnabled = internal.withTracerEnabled;
@@ -5388,7 +5301,7 @@ export const withTracerEnabled = internal.withTracerEnabled;
  * )
  * ```
  *
- * @category Tracing
+ * @category tracing
  * @since 2.0.0
  */
 export const withTracerTiming = internal.withTracerTiming;
@@ -5416,7 +5329,7 @@ export const withTracerTiming = internal.withTracerTiming;
  * })
  * ```
  *
- * @category Tracing
+ * @category tracing
  * @since 2.0.0
  */
 export const annotateSpans = internal.annotateSpans;
@@ -5441,7 +5354,7 @@ export const annotateSpans = internal.annotateSpans;
  * const traced = Effect.withSpan(program, "user-operation")
  * ```
  *
- * @category Tracing
+ * @category tracing
  * @since 2.0.0
  */
 export const annotateCurrentSpan = internal.annotateCurrentSpan;
@@ -5467,7 +5380,7 @@ export const annotateCurrentSpan = internal.annotateCurrentSpan;
  * const traced = Effect.withSpan(program, "my-span")
  * ```
  *
- * @category Tracing
+ * @category tracing
  * @since 2.0.0
  */
 export const currentSpan = internal.currentSpan;
@@ -5499,7 +5412,7 @@ export const currentSpan = internal.currentSpan;
  * const traced = Effect.withSpan(program, "parent-span")
  * ```
  *
- * @category Tracing
+ * @category tracing
  * @since 2.0.0
  */
 export const currentParentSpan = internal.currentParentSpan;
@@ -5532,7 +5445,7 @@ export const currentParentSpan = internal.currentParentSpan;
  * // Output: Current span annotations: { userId: "123", operation: "data-processing" }
  * ```
  *
- * @category Tracing
+ * @category tracing
  * @since 2.0.0
  */
 export const spanAnnotations = internal.spanAnnotations;
@@ -5557,7 +5470,7 @@ export const spanAnnotations = internal.spanAnnotations;
  * })
  * ```
  *
- * @category Tracing
+ * @category tracing
  * @since 2.0.0
  */
 export const spanLinks = internal.spanLinks;
@@ -5610,7 +5523,7 @@ export const spanLinks = internal.spanLinks;
  * })
  * ```
  *
- * @category Tracing
+ * @category tracing
  * @since 2.0.0
  */
 export const linkSpans = internal.linkSpans;
@@ -5635,7 +5548,7 @@ export const linkSpans = internal.linkSpans;
  * })
  * ```
  *
- * @category Tracing
+ * @category tracing
  * @since 2.0.0
  */
 export const makeSpan = internal.makeSpan;
@@ -5661,7 +5574,7 @@ export const makeSpan = internal.makeSpan;
  * )
  * ```
  *
- * @category Tracing
+ * @category tracing
  * @since 2.0.0
  */
 export const makeSpanScoped = internal.makeSpanScoped;
@@ -5687,7 +5600,7 @@ export const makeSpanScoped = internal.makeSpanScoped;
  * )
  * ```
  *
- * @category Tracing
+ * @category tracing
  * @since 2.0.0
  */
 export const useSpan = internal.useSpan;
@@ -5709,7 +5622,7 @@ export const useSpan = internal.useSpan;
  * })
  * ```
  *
- * @category Tracing
+ * @category tracing
  * @since 2.0.0
  */
 export const withSpan = internal.withSpan;
@@ -5732,7 +5645,7 @@ export const withSpan = internal.withSpan;
  * )
  * ```
  *
- * @category Tracing
+ * @category tracing
  * @since 2.0.0
  */
 export const withSpanScoped = internal.withSpanScoped;
@@ -5752,7 +5665,7 @@ export const withSpanScoped = internal.withSpanScoped;
  * })
  * ```
  *
- * @category Tracing
+ * @category tracing
  * @since 2.0.0
  */
 export const withParentSpan = internal.withParentSpan;
@@ -5946,7 +5859,7 @@ export const forkScoped = internal.forkScoped;
  * ```
  *
  * @category Supervision & Fibers
- * @since 2.0.0
+ * @since 4.0.0
  */
 export const forkDetach = internal.forkDetach;
 /**
@@ -5995,7 +5908,7 @@ export const fiber = internal.fiber;
  * ```
  *
  * @category Supervision & Fibers
- * @since 4.0.0
+ * @since 2.0.0
  */
 export const fiberId = internal.fiberId;
 /**
@@ -6014,10 +5927,7 @@ export const fiberId = internal.fiberId;
  * **Example** (Running an Effect in the Background)
  *
  * ```ts
- * import { Effect } from "effect"
- * import { Schedule } from "effect"
- * import { Fiber } from "effect"
- * import { Console } from "effect"
+ * import { Console, Effect, Fiber, Schedule } from "effect"
  *
  * //      ┌─── Effect<number, never, never>
  * //      ▼
@@ -6045,7 +5955,7 @@ export const runFork = internal.runFork;
  * **Example** (Usage)
  *
  * ```ts
- * import { Effect, Context } from "effect"
+ * import { Context, Effect } from "effect"
  *
  * interface Logger {
  *   log: (message: string) => void
@@ -6078,7 +5988,7 @@ export const runForkWith = internal.runForkWith;
  * **Example** (Usage)
  *
  * ```ts
- * import { Console, Effect, Exit, Context } from "effect"
+ * import { Console, Context, Effect, Exit } from "effect"
  *
  * interface Logger {
  *   log: (message: string) => Effect.Effect<void>
@@ -6148,7 +6058,7 @@ export const runCallbackWith = internal.runCallbackWith;
  * ```
  *
  * @category Running Effects
- * @since 4.0.0
+ * @since 2.0.0
  */
 export const runCallback = internal.runCallback;
 /**
@@ -6195,7 +6105,7 @@ export const runPromise = internal.runPromise;
  * **Example** (Usage)
  *
  * ```ts
- * import { Effect, Context } from "effect"
+ * import { Context, Effect } from "effect"
  *
  * interface Config {
  *   apiUrl: string
@@ -6273,7 +6183,7 @@ export const runPromiseExit = internal.runPromiseExit;
  * **Example** (Usage)
  *
  * ```ts
- * import { Effect, Exit, Context } from "effect"
+ * import { Context, Effect, Exit } from "effect"
  *
  * interface Database {
  *   query: (sql: string) => string
@@ -6368,7 +6278,7 @@ export const runSync = internal.runSync;
  * **Example** (Usage)
  *
  * ```ts
- * import { Effect, Context } from "effect"
+ * import { Context, Effect } from "effect"
  *
  * interface MathService {
  *   add: (a: number, b: number) => number
@@ -6471,7 +6381,7 @@ export const runSyncExit = internal.runSyncExit;
  * **Example** (Usage)
  *
  * ```ts
- * import { Effect, Exit, Context } from "effect"
+ * import { Context, Effect, Exit } from "effect"
  *
  * // Define a logger service
  * const Logger = Context.Service<{
@@ -6553,7 +6463,7 @@ export const fnUntraced = internal.fnUntraced;
  * ```
  *
  * @category Function
- * @since 3.12.0
+ * @since 3.11.0
  */
 export const fn = internal.fn;
 // ========================================================================
@@ -6605,7 +6515,7 @@ export const clockWith = internal.clockWith;
  * })
  * ```
  *
- * @category Logging
+ * @category logging
  * @since 2.0.0
  */
 export const logWithLevel = internal.logWithLevel;
@@ -6633,7 +6543,7 @@ export const logWithLevel = internal.logWithLevel;
  * // 4
  * ```
  *
- * @category Logging
+ * @category logging
  * @since 2.0.0
  */
 export const log = /*#__PURE__*/internal.logWithLevel();
@@ -6662,7 +6572,7 @@ export const log = /*#__PURE__*/internal.logWithLevel();
  * // timestamp=2023-... level=FATAL message="System shutting down"
  * ```
  *
- * @category Logging
+ * @category logging
  * @since 2.0.0
  */
 export const logFatal = /*#__PURE__*/internal.logWithLevel("Fatal");
@@ -6692,7 +6602,7 @@ export const logFatal = /*#__PURE__*/internal.logWithLevel("Fatal");
  * // timestamp=2023-... level=WARN message="Using deprecated API endpoint"
  * ```
  *
- * @category Logging
+ * @category logging
  * @since 2.0.0
  */
 export const logWarning = /*#__PURE__*/internal.logWithLevel("Warn");
@@ -6725,7 +6635,7 @@ export const logWarning = /*#__PURE__*/internal.logWithLevel("Warn");
  * // timestamp=2023-... level=ERROR message="Caught error: Something went wrong"
  * ```
  *
- * @category Logging
+ * @category logging
  * @since 2.0.0
  */
 export const logError = /*#__PURE__*/internal.logWithLevel("Error");
@@ -6753,7 +6663,7 @@ export const logError = /*#__PURE__*/internal.logWithLevel("Error");
  * // timestamp=2023-... level=INFO message="Application version: 1.2.3"
  * ```
  *
- * @category Logging
+ * @category logging
  * @since 2.0.0
  */
 export const logInfo = /*#__PURE__*/internal.logWithLevel("Info");
@@ -6782,7 +6692,7 @@ export const logInfo = /*#__PURE__*/internal.logWithLevel("Info");
  * // timestamp=2023-... level=DEBUG message="Variable state: x=10 y=20 z=30"
  * ```
  *
- * @category Logging
+ * @category logging
  * @since 2.0.0
  */
 export const logDebug = /*#__PURE__*/internal.logWithLevel("Debug");
@@ -6814,7 +6724,7 @@ export const logDebug = /*#__PURE__*/internal.logWithLevel("Debug");
  * // timestamp=2023-... level=TRACE message="Exiting function processData"
  * ```
  *
- * @category Logging
+ * @category logging
  * @since 2.0.0
  */
 export const logTrace = /*#__PURE__*/internal.logWithLevel("Trace");
@@ -6843,8 +6753,8 @@ export const logTrace = /*#__PURE__*/internal.logWithLevel("Trace");
  * // Output includes both default and custom log outputs
  * ```
  *
- * @category Logging
- * @since 2.0.0
+ * @category logging
+ * @since 4.0.0
  */
 export const withLogger = /*#__PURE__*/dual(2, (effect, logger) => internal.updateService(effect, internal.CurrentLoggers, loggers => new Set([...loggers, logger])));
 /**
@@ -6874,7 +6784,7 @@ export const withLogger = /*#__PURE__*/dual(2, (effect, logger) => internal.upda
  * // All log messages will include the userId and operation annotations
  * ```
  *
- * @category Logging
+ * @category logging
  * @since 2.0.0
  */
 export const annotateLogs = /*#__PURE__*/dual(args => isEffect(args[0]), (effect, ...args) => internal.updateService(effect, CurrentLogAnnotations, annotations => {
@@ -6911,8 +6821,8 @@ export const annotateLogs = /*#__PURE__*/dual(args => isEffect(args[0]), (effect
  * Effect.runPromise(program)
  * ```
  *
- * @category Logging
- * @since 4.0.0
+ * @category logging
+ * @since 3.1.0
  */
 export const annotateLogsScoped = internal.annotateLogsScoped;
 /**
@@ -6943,7 +6853,7 @@ export const annotateLogsScoped = internal.annotateLogsScoped;
  * // All log messages will include span information showing the nested operation context
  * ```
  *
- * @category Logging
+ * @category logging
  * @since 2.0.0
  */
 export const withLogSpan = /*#__PURE__*/dual(2, (effect, label) => internal.flatMap(internal.currentTimeMillis, now => internal.updateService(effect, CurrentLogSpans, spans => {