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

package/src/Layer.ts

@@ -121,7 +121,7 @@ export interface Any {
  * Extracts the service dependencies (RIn) from a Layer type.
  *
  * @category type-level
- * @since 2.0.0
+ * @since 4.0.0
  */
 export type Services<T extends Any> = T extends infer L
   ? L extends Layer<infer _ROut, infer _E, infer _RIn> ? _RIn : never
@@ -152,7 +152,7 @@ const MemoMapTypeId = "~effect/Layer/MemoMap"
  * **Example** (Sharing layer construction with a memo map)
  *
  * ```ts
- * import { Effect, Layer, Context } from "effect"
+ * import { Context, Effect, Layer } from "effect"
  *
  * class Database extends Context.Service<Database, {
  *   readonly query: (sql: string) => Effect.Effect<string>
@@ -211,7 +211,7 @@ const memoMapReuse = <RIn, E, ROut>(
  * **Example** (Checking whether a value is a layer)
  *
  * ```ts
- * import { Effect, Layer, Context } from "effect"
+ * import { Context, Effect, Layer } from "effect"
  *
  * class Database extends Context.Service<Database, {
  *   readonly query: (sql: string) => Effect.Effect<string>
@@ -262,7 +262,7 @@ const fromBuildUnsafe = <ROut, E, RIn>(
  * **Example** (Constructing a layer from a build function)
  *
  * ```ts
- * import { Effect, Layer, Context } from "effect"
+ * import { Context, Effect, Layer } from "effect"
  *
  * class Database extends Context.Service<Database, {
  *   readonly query: (sql: string) => Effect.Effect<string>
@@ -304,7 +304,7 @@ export const fromBuild = <ROut, E, RIn>(
  * **Example** (Memoizing layer construction)
  *
  * ```ts
- * import { Effect, Layer, Context } from "effect"
+ * import { Context, Effect, Layer } from "effect"
  *
  * class Database extends Context.Service<Database, {
  *   readonly query: (sql: string) => Effect.Effect<string>
@@ -406,7 +406,7 @@ class MemoMapImpl implements MemoMap {
  * **Example** (Creating a memo map unsafely)
  *
  * ```ts
- * import { Effect, Layer, Context } from "effect"
+ * import { Context, Effect, Layer } from "effect"
  *
  * class Database extends Context.Service<Database, {
  *   readonly query: (sql: string) => Effect.Effect<string>
@@ -435,8 +435,8 @@ export const makeMemoMapUnsafe = (): MemoMap => new MemoMapImpl()
  * Constructs a child `MemoMap` that can reuse layers already memoized in the
  * parent while isolating any new layer allocations to the child map.
  *
- * @since 4.0.0
  * @category memo map
+ * @since 4.0.0
  */
 export const forkMemoMapUnsafe = (parent: MemoMap): MemoMap => new MemoMapImpl(parent)
 
@@ -446,7 +446,7 @@ export const forkMemoMapUnsafe = (parent: MemoMap): MemoMap => new MemoMapImpl(p
  * **Example** (Creating a memo map in an effect)
  *
  * ```ts
- * import { Effect, Layer, Context } from "effect"
+ * import { Context, Effect, Layer } from "effect"
  *
  * class Database extends Context.Service<Database, {
  *   readonly query: (sql: string) => Effect.Effect<string>
@@ -475,8 +475,8 @@ export const makeMemoMap: Effect<MemoMap> = internalEffect.sync(makeMemoMapUnsaf
  * Constructs a child `MemoMap` that can reuse layers already memoized in the
  * parent while isolating any new layer allocations to the child map.
  *
- * @since 4.0.0
  * @category memo map
+ * @since 4.0.0
  */
 export const forkMemoMap = (parent: MemoMap): Effect<MemoMap> => internalEffect.sync(() => forkMemoMapUnsafe(parent))
 
@@ -503,7 +503,7 @@ export class CurrentMemoMap extends Context.Service<CurrentMemoMap, MemoMap>()("
  * **Example** (Building layers with an explicit memo map)
  *
  * ```ts
- * import { Effect, Layer, Context } from "effect"
+ * import { Context, Effect, Layer } from "effect"
  *
  * class Database extends Context.Service<Database, {
  *   readonly query: (sql: string) => Effect.Effect<string>
@@ -552,7 +552,7 @@ export const buildWithMemoMap: {
    * **Example** (Building layers with an explicit memo map)
    *
    * ```ts
-   * import { Effect, Layer, Context } from "effect"
+   * import { Context, Effect, Layer } from "effect"
    *
    * class Database extends Context.Service<Database, {
    *   readonly query: (sql: string) => Effect.Effect<string>
@@ -601,7 +601,7 @@ export const buildWithMemoMap: {
    * **Example** (Building layers with an explicit memo map)
    *
    * ```ts
-   * import { Effect, Layer, Context } from "effect"
+   * import { Context, Effect, Layer } from "effect"
    *
    * class Database extends Context.Service<Database, {
    *   readonly query: (sql: string) => Effect.Effect<string>
@@ -660,7 +660,7 @@ export const buildWithMemoMap: {
  * **Example** (Building a layer into a context)
  *
  * ```ts
- * import { Effect, Layer, Context } from "effect"
+ * import { Context, Effect, Layer } from "effect"
  *
  * class Database extends Context.Service<Database, {
  *   readonly query: (sql: string) => Effect.Effect<string>
@@ -706,7 +706,7 @@ export const build = <RIn, E, ROut>(
  * **Example** (Building a layer with an explicit scope)
  *
  * ```ts
- * import { Effect, Layer, Scope, Context } from "effect"
+ * import { Context, Effect, Layer, Scope } from "effect"
  *
  * class Database extends Context.Service<Database, {
  *   readonly query: (sql: string) => Effect.Effect<string>
@@ -748,7 +748,7 @@ export const buildWithScope: {
    * **Example** (Building a layer with an explicit scope)
    *
    * ```ts
-   * import { Effect, Layer, Scope, Context } from "effect"
+   * import { Context, Effect, Layer, Scope } from "effect"
    *
    * class Database extends Context.Service<Database, {
    *   readonly query: (sql: string) => Effect.Effect<string>
@@ -790,7 +790,7 @@ export const buildWithScope: {
    * **Example** (Building a layer with an explicit scope)
    *
    * ```ts
-   * import { Effect, Layer, Scope, Context } from "effect"
+   * import { Context, Effect, Layer, Scope } from "effect"
    *
    * class Database extends Context.Service<Database, {
    *   readonly query: (sql: string) => Effect.Effect<string>
@@ -840,7 +840,7 @@ export const buildWithScope: {
  * **Example** (Providing services from values)
  *
  * ```ts
- * import { Effect, Layer, Context } from "effect"
+ * import { Context, Effect, Layer } from "effect"
  *
  * class Database extends Context.Service<Database, {
  *   readonly query: (sql: string) => Effect.Effect<string>
@@ -884,7 +884,7 @@ export const succeed: {
    * **Example** (Providing services from values)
    *
    * ```ts
-   * import { Effect, Layer, Context } from "effect"
+   * import { Context, Effect, Layer } from "effect"
    *
    * class Database extends Context.Service<Database, {
    *   readonly query: (sql: string) => Effect.Effect<string>
@@ -928,7 +928,7 @@ export const succeed: {
    * **Example** (Providing services from values)
    *
    * ```ts
-   * import { Effect, Layer, Context } from "effect"
+   * import { Context, Effect, Layer } from "effect"
    *
    * class Database extends Context.Service<Database, {
    *   readonly query: (sql: string) => Effect.Effect<string>
@@ -983,7 +983,7 @@ export const succeed: {
  * **Example** (Providing multiple services from a context)
  *
  * ```ts
- * import { Effect, Layer, Context } from "effect"
+ * import { Context, Effect, Layer } from "effect"
  *
  * class Database extends Context.Service<Database, {
  *   readonly query: (sql: string) => Effect.Effect<string>
@@ -1038,7 +1038,7 @@ export const empty: Layer<never> = succeedContext(Context.empty())
  * **Example** (Lazily providing a service)
  *
  * ```ts
- * import { Effect, Layer, Context } from "effect"
+ * import { Context, Effect, Layer } from "effect"
  *
  * class Database extends Context.Service<Database, {
  *   readonly query: (sql: string) => Effect.Effect<string>
@@ -1062,7 +1062,7 @@ export const sync: {
    * **Example** (Lazily providing a service)
    *
    * ```ts
-   * import { Effect, Layer, Context } from "effect"
+   * import { Context, Effect, Layer } from "effect"
    *
    * class Database extends Context.Service<Database, {
    *   readonly query: (sql: string) => Effect.Effect<string>
@@ -1086,7 +1086,7 @@ export const sync: {
    * **Example** (Lazily providing a service)
    *
    * ```ts
-   * import { Effect, Layer, Context } from "effect"
+   * import { Context, Effect, Layer } from "effect"
    *
    * class Database extends Context.Service<Database, {
    *   readonly query: (sql: string) => Effect.Effect<string>
@@ -1118,7 +1118,7 @@ export const sync: {
  * **Example** (Lazily providing a context)
  *
  * ```ts
- * import { Effect, Layer, Context } from "effect"
+ * import { Context, Effect, Layer } from "effect"
  *
  * class Database extends Context.Service<Database, {
  *   readonly query: (sql: string) => Effect.Effect<string>
@@ -1144,16 +1144,10 @@ export const syncContext = <A>(evaluate: LazyArg<Context.Context<A>>): Layer<A>
  * The Effect is executed in the scope of the layer, allowing for proper
  * resource management.
  *
- * **Previously Known As**
- *
- * This API replaces the following from Effect 3.x:
- *
- * - `Layer.scoped`
- *
  * **Example** (Creating a layer from an effect)
  *
  * ```ts
- * import { Effect, Layer, Context } from "effect"
+ * import { Context, Effect, Layer } from "effect"
  *
  * class Database extends Context.Service<Database, {
  *   readonly query: (sql: string) => Effect.Effect<string>
@@ -1177,16 +1171,10 @@ export const effect: {
    * The Effect is executed in the scope of the layer, allowing for proper
    * resource management.
    *
-   * **Previously Known As**
-   *
-   * This API replaces the following from Effect 3.x:
-   *
-   * - `Layer.scoped`
-   *
    * **Example** (Creating a layer from an effect)
    *
    * ```ts
-   * import { Effect, Layer, Context } from "effect"
+   * import { Context, Effect, Layer } from "effect"
    *
    * class Database extends Context.Service<Database, {
    *   readonly query: (sql: string) => Effect.Effect<string>
@@ -1212,16 +1200,10 @@ export const effect: {
    * The Effect is executed in the scope of the layer, allowing for proper
    * resource management.
    *
-   * **Previously Known As**
-   *
-   * This API replaces the following from Effect 3.x:
-   *
-   * - `Layer.scoped`
-   *
    * **Example** (Creating a layer from an effect)
    *
    * ```ts
-   * import { Effect, Layer, Context } from "effect"
+   * import { Context, Effect, Layer } from "effect"
    *
    * class Database extends Context.Service<Database, {
    *   readonly query: (sql: string) => Effect.Effect<string>
@@ -1261,7 +1243,7 @@ const effectImpl = <I, S, E, R>(
  * **Example** (Creating a layer from an effectful context)
  *
  * ```ts
- * import { Effect, Layer, Context } from "effect"
+ * import { Context, Effect, Layer } from "effect"
  *
  * class Database extends Context.Service<
  *   Database,
@@ -1288,12 +1270,6 @@ export const effectContext = <A, E, R>(
  * This is useful when you want to run an Effect for its side effects during
  * layer construction, but don't need to provide any services.
  *
- * **Previously Known As**
- *
- * This API replaces the following from Effect 3.x:
- *
- * - `Layer.scopedDiscard`
- *
  * **Example** (Running an effect during layer construction)
  *
  * ```ts
@@ -1321,7 +1297,7 @@ export const effectDiscard = <X, E, R>(effect: Effect<X, E, R>): Layer<never, E,
  * **Example** (Choosing a layer lazily)
  *
  * ```ts
- * import { Layer, Context } from "effect"
+ * import { Context, Layer } from "effect"
  *
  * class Config extends Context.Service<Config, string>()("Config") {}
  *
@@ -1335,7 +1311,7 @@ export const effectDiscard = <X, E, R>(effect: Effect<X, E, R>): Layer<never, E,
  * ```
  *
  * @category constructors
- * @since 4.0.0
+ * @since 2.0.0
  */
 export const suspend = <A, E, R>(evaluate: LazyArg<Layer<A, E, R>>): Layer<A, E, R> =>
   fromBuildMemo((memoMap, scope) => internalEffect.suspend(() => evaluate().build(memoMap, scope)))
@@ -1350,7 +1326,7 @@ export const suspend = <A, E, R>(evaluate: LazyArg<Layer<A, E, R>>): Layer<A, E,
  * **Example** (Unwrapping an effectful layer)
  *
  * ```ts
- * import { Effect, Layer, Context } from "effect"
+ * import { Context, Effect, Layer } from "effect"
  *
  * class Database extends Context.Service<Database, {
  *   readonly query: (sql: string) => Effect.Effect<string>
@@ -1399,7 +1375,7 @@ const mergeAllEffect = <Layers extends [Layer<never, any, any>, ...Array<Layer<n
  * **Example** (Merging independent layers)
  *
  * ```ts
- * import { Effect, Layer, Context } from "effect"
+ * import { Context, Effect, Layer } from "effect"
  *
  * class Database extends Context.Service<Database, {
  *   readonly query: (sql: string) => Effect.Effect<string>
@@ -1439,7 +1415,7 @@ export const mergeAll = <Layers extends [Layer<never, any, any>, ...Array<Layer<
  * **Example** (Merging two layers)
  *
  * ```ts
- * import { Effect, Layer, Context } from "effect"
+ * import { Context, Effect, Layer } from "effect"
  *
  * class Database extends Context.Service<Database, {
  *   readonly query: (sql: string) => Effect.Effect<string>
@@ -1472,7 +1448,7 @@ export const merge: {
    * **Example** (Merging two layers)
    *
    * ```ts
-   * import { Effect, Layer, Context } from "effect"
+   * import { Context, Effect, Layer } from "effect"
    *
    * class Database extends Context.Service<Database, {
    *   readonly query: (sql: string) => Effect.Effect<string>
@@ -1505,7 +1481,7 @@ export const merge: {
    * **Example** (Merging two layers)
    *
    * ```ts
-   * import { Effect, Layer, Context } from "effect"
+   * import { Context, Effect, Layer } from "effect"
    *
    * class Database extends Context.Service<Database, {
    *   readonly query: (sql: string) => Effect.Effect<string>
@@ -1545,7 +1521,7 @@ export const merge: {
    * **Example** (Merging two layers)
    *
    * ```ts
-   * import { Effect, Layer, Context } from "effect"
+   * import { Context, Effect, Layer } from "effect"
    *
    * class Database extends Context.Service<Database, {
    *   readonly query: (sql: string) => Effect.Effect<string>
@@ -1578,7 +1554,7 @@ export const merge: {
    * **Example** (Merging two layers)
    *
    * ```ts
-   * import { Effect, Layer, Context } from "effect"
+   * import { Context, Effect, Layer } from "effect"
    *
    * class Database extends Context.Service<Database, {
    *   readonly query: (sql: string) => Effect.Effect<string>
@@ -1641,7 +1617,7 @@ const provideWith = (
  * **Example** (Providing layer dependencies)
  *
  * ```ts
- * import { Effect, Layer, Context } from "effect"
+ * import { Context, Effect, Layer } from "effect"
  *
  * class Database extends Context.Service<Database, {
  *   readonly query: (sql: string) => Effect.Effect<string>
@@ -1709,7 +1685,7 @@ export const provide: {
    * **Example** (Providing layer dependencies)
    *
    * ```ts
-   * import { Effect, Layer, Context } from "effect"
+   * import { Context, Effect, Layer } from "effect"
    *
    * class Database extends Context.Service<Database, {
    *   readonly query: (sql: string) => Effect.Effect<string>
@@ -1777,7 +1753,7 @@ export const provide: {
    * **Example** (Providing layer dependencies)
    *
    * ```ts
-   * import { Effect, Layer, Context } from "effect"
+   * import { Context, Effect, Layer } from "effect"
    *
    * class Database extends Context.Service<Database, {
    *   readonly query: (sql: string) => Effect.Effect<string>
@@ -1852,7 +1828,7 @@ export const provide: {
    * **Example** (Providing layer dependencies)
    *
    * ```ts
-   * import { Effect, Layer, Context } from "effect"
+   * import { Context, Effect, Layer } from "effect"
    *
    * class Database extends Context.Service<Database, {
    *   readonly query: (sql: string) => Effect.Effect<string>
@@ -1920,7 +1896,7 @@ export const provide: {
    * **Example** (Providing layer dependencies)
    *
    * ```ts
-   * import { Effect, Layer, Context } from "effect"
+   * import { Context, Effect, Layer } from "effect"
    *
    * class Database extends Context.Service<Database, {
    *   readonly query: (sql: string) => Effect.Effect<string>
@@ -1998,7 +1974,7 @@ export const provide: {
  * **Example** (Providing dependencies while retaining services)
  *
  * ```ts
- * import { Effect, Layer, Context } from "effect"
+ * import { Context, Effect, Layer } from "effect"
  *
  * class Database extends Context.Service<Database, {
  *   readonly query: (sql: string) => Effect.Effect<string>
@@ -2072,7 +2048,7 @@ export const provideMerge: {
    * **Example** (Providing dependencies while retaining services)
    *
    * ```ts
-   * import { Effect, Layer, Context } from "effect"
+   * import { Context, Effect, Layer } from "effect"
    *
    * class Database extends Context.Service<Database, {
    *   readonly query: (sql: string) => Effect.Effect<string>
@@ -2146,7 +2122,7 @@ export const provideMerge: {
    * **Example** (Providing dependencies while retaining services)
    *
    * ```ts
-   * import { Effect, Layer, Context } from "effect"
+   * import { Context, Effect, Layer } from "effect"
    *
    * class Database extends Context.Service<Database, {
    *   readonly query: (sql: string) => Effect.Effect<string>
@@ -2227,7 +2203,7 @@ export const provideMerge: {
    * **Example** (Providing dependencies while retaining services)
    *
    * ```ts
-   * import { Effect, Layer, Context } from "effect"
+   * import { Context, Effect, Layer } from "effect"
    *
    * class Database extends Context.Service<Database, {
    *   readonly query: (sql: string) => Effect.Effect<string>
@@ -2301,7 +2277,7 @@ export const provideMerge: {
    * **Example** (Providing dependencies while retaining services)
    *
    * ```ts
-   * import { Effect, Layer, Context } from "effect"
+   * import { Context, Effect, Layer } from "effect"
    *
    * class Database extends Context.Service<Database, {
    *   readonly query: (sql: string) => Effect.Effect<string>
@@ -2388,7 +2364,7 @@ export const provideMerge: {
  * **Example** (Creating services from layer output)
  *
  * ```ts
- * import { Effect, Layer, Context } from "effect"
+ * import { Context, Effect, Layer } from "effect"
  *
  * class Config extends Context.Service<Config, {
  *   readonly dbUrl: string
@@ -2460,7 +2436,7 @@ export const flatMap: {
    * **Example** (Creating services from layer output)
    *
    * ```ts
-   * import { Effect, Layer, Context } from "effect"
+   * import { Context, Effect, Layer } from "effect"
    *
    * class Config extends Context.Service<Config, {
    *   readonly dbUrl: string
@@ -2532,7 +2508,7 @@ export const flatMap: {
    * **Example** (Creating services from layer output)
    *
    * ```ts
-   * import { Effect, Layer, Context } from "effect"
+   * import { Context, Effect, Layer } from "effect"
    *
    * class Config extends Context.Service<Config, {
    *   readonly dbUrl: string
@@ -2616,21 +2592,21 @@ export const flatMap: {
  * Performs the specified effect if this layer succeeds.
  *
  * @category sequencing
- * @since 4.0.0
+ * @since 2.0.0
  */
 export const tap: {
   /**
    * Performs the specified effect if this layer succeeds.
    *
    * @category sequencing
-   * @since 4.0.0
+   * @since 2.0.0
    */
   <ROut, XR extends ROut, RIn2, E2, X>(f: (context: Context.Context<XR>) => Effect<X, E2, RIn2>): <RIn, E>(self: Layer<ROut, E, RIn>) => Layer<ROut, E | E2, RIn | Exclude<RIn2, Scope.Scope>>
   /**
    * Performs the specified effect if this layer succeeds.
    *
    * @category sequencing
-   * @since 4.0.0
+   * @since 2.0.0
    */
   <RIn, E, ROut, XR extends ROut, RIn2, E2, X>(
     self: Layer<ROut, E, RIn>,
@@ -2651,21 +2627,21 @@ export const tap: {
  * Performs the specified effect if this layer fails.
  *
  * @category sequencing
- * @since 4.0.0
+ * @since 2.0.0
  */
 export const tapError: {
   /**
    * Performs the specified effect if this layer fails.
    *
    * @category sequencing
-   * @since 4.0.0
+   * @since 2.0.0
    */
   <E, XE extends E, RIn2, E2, X>(f: (e: XE) => Effect<X, E2, RIn2>): <RIn, ROut>(self: Layer<ROut, E, RIn>) => Layer<ROut, E | E2, RIn | Exclude<RIn2, Scope.Scope>>
   /**
    * Performs the specified effect if this layer fails.
    *
    * @category sequencing
-   * @since 4.0.0
+   * @since 2.0.0
    */
   <RIn, E, XE extends E, ROut, RIn2, E2, X>(self: Layer<ROut, E, RIn>, f: (e: XE) => Effect<X, E2, RIn2>): Layer<ROut, E | E2, RIn | Exclude<RIn2, Scope.Scope>>
 } = dual(2, <RIn, E, XE extends E, ROut, RIn2, E2, X>(
@@ -2688,12 +2664,6 @@ export const tapError: {
  * fails again with the original cause; if the callback fails, that failure is
  * added to the layer's error type.
  *
- * **Previously Known As**
- *
- * This API replaces the following from Effect 3.x:
- *
- * - `Layer.tapErrorCause`
- *
  * @category sequencing
  * @since 4.0.0
  */
@@ -2707,12 +2677,6 @@ export const tapCause: {
    * fails again with the original cause; if the callback fails, that failure is
    * added to the layer's error type.
    *
-   * **Previously Known As**
-   *
-   * This API replaces the following from Effect 3.x:
-   *
-   * - `Layer.tapErrorCause`
-   *
    * @category sequencing
    * @since 4.0.0
    */
@@ -2726,12 +2690,6 @@ export const tapCause: {
    * fails again with the original cause; if the callback fails, that failure is
    * added to the layer's error type.
    *
-   * **Previously Known As**
-   *
-   * This API replaces the following from Effect 3.x:
-   *
-   * - `Layer.tapErrorCause`
-   *
    * @category sequencing
    * @since 4.0.0
    */
@@ -2758,7 +2716,7 @@ export const tapCause: {
  * **Example** (Converting layer failures to defects)
  *
  * ```ts
- * import { Data, Effect, Layer, Context } from "effect"
+ * import { Context, Data, Effect, Layer } from "effect"
  *
  * class DatabaseError extends Data.TaggedError("DatabaseError")<{
  *   message: string
@@ -2830,7 +2788,7 @@ export {
  * **Example** (Recovering from tagged layer errors)
  *
  * ```ts
- * import { Data, Effect, Layer, Context } from "effect"
+ * import { Context, Data, Effect, Layer } from "effect"
  *
  * class ConfigError extends Data.TaggedError("ConfigError") {}
  *
@@ -2857,7 +2815,7 @@ export const catchTag: {
    * **Example** (Recovering from tagged layer errors)
    *
    * ```ts
-   * import { Data, Effect, Layer, Context } from "effect"
+   * import { Context, Data, Effect, Layer } from "effect"
    *
    * class ConfigError extends Data.TaggedError("ConfigError") {}
    *
@@ -2895,7 +2853,7 @@ export const catchTag: {
    * **Example** (Recovering from tagged layer errors)
    *
    * ```ts
-   * import { Data, Effect, Layer, Context } from "effect"
+   * import { Context, Data, Effect, Layer } from "effect"
    *
    * class ConfigError extends Data.TaggedError("ConfigError") {}
    *
@@ -2964,7 +2922,7 @@ export const catchTag: {
  * **Example** (Recovering from layer failures by cause)
  *
  * ```ts
- * import { Data, Effect, Layer, Context } from "effect"
+ * import { Context, Data, Effect, Layer } from "effect"
  *
  * class DatabaseError extends Data.TaggedError("DatabaseError")<{
  *   message: string
@@ -2999,7 +2957,7 @@ export const catchTag: {
  * ```
  *
  * @category error handling
- * @since 2.0.0
+ * @since 4.0.0
  */
 export const catchCause: {
   /**
@@ -3013,7 +2971,7 @@ export const catchCause: {
    * **Example** (Recovering from layer failures by cause)
    *
    * ```ts
-   * import { Data, Effect, Layer, Context } from "effect"
+   * import { Context, Data, Effect, Layer } from "effect"
    *
    * class DatabaseError extends Data.TaggedError("DatabaseError")<{
    *   message: string
@@ -3048,7 +3006,7 @@ export const catchCause: {
    * ```
    *
    * @category error handling
-   * @since 2.0.0
+   * @since 4.0.0
    */
   <E, RIn2, E2, ROut2>(onError: (cause: Cause.Cause<E>) => Layer<ROut2, E2, RIn2>): <RIn, ROut>(self: Layer<ROut, E, RIn>) => Layer<ROut & ROut2, E2, RIn2 | RIn>
   /**
@@ -3062,7 +3020,7 @@ export const catchCause: {
    * **Example** (Recovering from layer failures by cause)
    *
    * ```ts
-   * import { Data, Effect, Layer, Context } from "effect"
+   * import { Context, Data, Effect, Layer } from "effect"
    *
    * class DatabaseError extends Data.TaggedError("DatabaseError")<{
    *   message: string
@@ -3097,7 +3055,7 @@ export const catchCause: {
    * ```
    *
    * @category error handling
-   * @since 2.0.0
+   * @since 4.0.0
    */
   <RIn, E, ROut, RIn2, E2, ROut22>(
     self: Layer<ROut, E, RIn>,
@@ -3190,7 +3148,7 @@ export const updateService: {
  * **Example** (Creating non-shared layer instances)
  *
  * ```ts
- * import { Effect, Layer, Ref, Context } from "effect"
+ * import { Context, Effect, Layer, Ref } from "effect"
  *
  * class Counter extends Context.Service<Counter, {
  *   readonly id: number
@@ -3266,7 +3224,7 @@ export const fresh = <A, E, R>(self: Layer<A, E, R>): Layer<A, E, R> =>
  * **Example** (Launching an application layer)
  *
  * ```ts
- * import { Console, Effect, Layer, Context } from "effect"
+ * import { Console, Context, Effect, Layer } from "effect"
  *
  * class HttpServer extends Context.Service<HttpServer, {
  *   readonly start: () => Effect.Effect<string>
@@ -3311,7 +3269,7 @@ export const fresh = <A, E, R>(self: Layer<A, E, R>): Layer<A, E, R> =>
  * // Effect.runFork(application)
  * ```
  *
- * @category conversions
+ * @category converting
  * @since 2.0.0
  */
 export const launch = <RIn, E, ROut>(self: Layer<ROut, E, RIn>): Effect<never, E, RIn> =>
@@ -3325,7 +3283,7 @@ export const launch = <RIn, E, ROut>(self: Layer<ROut, E, RIn>): Effect<never, E
  * only the methods you need to test while leaving others unimplemented.
  *
  * @category Testing
- * @since 4.0.0
+ * @since 3.17.0
  */
 export type PartialEffectful<A extends object> = Types.Simplify<
   & {
@@ -3352,7 +3310,7 @@ type AnyEffectOrStream =
  * **Example** (Mocking services for tests)
  *
  * ```ts
- * import { Effect, Layer, Context } from "effect"
+ * import { Context, Effect, Layer } from "effect"
  *
  * class UserService extends Context.Service<UserService, {
  *   readonly config: { apiUrl: string }
@@ -3389,7 +3347,7 @@ type AnyEffectOrStream =
  * ```
  *
  * @category Testing
- * @since 4.0.0
+ * @since 3.17.0
  */
 export const mock: {
   /**
@@ -3400,7 +3358,7 @@ export const mock: {
    * **Example** (Mocking services for tests)
    *
    * ```ts
-   * import { Effect, Layer, Context } from "effect"
+   * import { Context, Effect, Layer } from "effect"
    *
    * class UserService extends Context.Service<UserService, {
    *   readonly config: { apiUrl: string }
@@ -3437,7 +3395,7 @@ export const mock: {
    * ```
    *
    * @category Testing
-   * @since 4.0.0
+   * @since 3.17.0
    */
   <I, S extends object>(service: Context.Key<I, S>): (implementation: PartialEffectful<S>) => Layer<I>
   /**
@@ -3448,7 +3406,7 @@ export const mock: {
    * **Example** (Mocking services for tests)
    *
    * ```ts
-   * import { Effect, Layer, Context } from "effect"
+   * import { Context, Effect, Layer } from "effect"
    *
    * class UserService extends Context.Service<UserService, {
    *   readonly config: { apiUrl: string }
@@ -3485,7 +3443,7 @@ export const mock: {
    * ```
    *
    * @category Testing
-   * @since 4.0.0
+   * @since 3.17.0
    */
   <I, S extends object>(
     service: Context.Key<I, S>,
@@ -3650,7 +3608,7 @@ export const satisfiesServicesType =
  * Represents options that can be used to control the behavior of spans created
  * for layers.
  *
- * @category Models
+ * @category models
  * @since 4.0.0
  */
 export interface SpanOptions extends Tracer.SpanOptions {
@@ -3674,7 +3632,8 @@ export interface SpanOptions extends Tracer.SpanOptions {
  * **Example** (Tracing layer construction with a span)
  *
  * ```ts
- * import { Console, Effect, Layer, Context, type Tracer } from "effect"
+ * import { Console, Context, Effect, Layer } from "effect"
+ * import type { Tracer } from "effect"
  *
  * class Database extends Context.Service<Database, {
  *   readonly query: (sql: string) => Effect.Effect<string>
@@ -3707,7 +3666,7 @@ export interface SpanOptions extends Tracer.SpanOptions {
  * ```
  *
  * @category tracing
- * @since 4.0.0
+ * @since 2.0.0
  */
 export const span = (
   name: string,
@@ -3736,7 +3695,7 @@ export const span = (
  * **Example** (Using an existing parent span)
  *
  * ```ts
- * import { Console, Effect, Layer, Context, Tracer } from "effect"
+ * import { Console, Context, Effect, Layer, Tracer } from "effect"
  *
  * class Database extends Context.Service<Database, {
  *   readonly query: (sql: string) => Effect.Effect<string>
@@ -3762,7 +3721,7 @@ export const span = (
  * ```
  *
  * @category tracing
- * @since 4.0.0
+ * @since 2.0.0
  */
 export const parentSpan = (span: Tracer.AnySpan): Layer<Tracer.ParentSpan> =>
   succeedContext(Tracer.ParentSpan.context(span))
@@ -3778,7 +3737,7 @@ export const parentSpan = (span: Tracer.AnySpan): Layer<Tracer.ParentSpan> =>
  * **Example** (Wrapping a layer with a span)
  *
  * ```ts
- * import { Effect, Layer, Context } from "effect"
+ * import { Context, Effect, Layer } from "effect"
  *
  * class Database extends Context.Service<Database, {
  *   readonly query: (sql: string) => Effect.Effect<string>
@@ -3824,7 +3783,7 @@ export const parentSpan = (span: Tracer.AnySpan): Layer<Tracer.ParentSpan> =>
  * ```
  *
  * @category tracing
- * @since 4.0.0
+ * @since 2.0.0
  */
 export const withSpan: {
   /**
@@ -3838,7 +3797,7 @@ export const withSpan: {
    * **Example** (Wrapping a layer with a span)
    *
    * ```ts
-   * import { Effect, Layer, Context } from "effect"
+   * import { Context, Effect, Layer } from "effect"
    *
    * class Database extends Context.Service<Database, {
    *   readonly query: (sql: string) => Effect.Effect<string>
@@ -3884,7 +3843,7 @@ export const withSpan: {
    * ```
    *
    * @category tracing
-   * @since 4.0.0
+   * @since 2.0.0
    */
   (name: string, options?: SpanOptions): <A, E, R>(
     self: Layer<A, E, R>
@@ -3900,7 +3859,7 @@ export const withSpan: {
    * **Example** (Wrapping a layer with a span)
    *
    * ```ts
-   * import { Effect, Layer, Context } from "effect"
+   * import { Context, Effect, Layer } from "effect"
    *
    * class Database extends Context.Service<Database, {
    *   readonly query: (sql: string) => Effect.Effect<string>
@@ -3946,7 +3905,7 @@ export const withSpan: {
    * ```
    *
    * @category tracing
-   * @since 4.0.0
+   * @since 2.0.0
    */
   <A, E, R>(self: Layer<A, E, R>, name: string, options?: SpanOptions): Layer<A, E, Exclude<R, Tracer.ParentSpan>>
 } = function() {
@@ -3992,7 +3951,7 @@ export const withSpan: {
  * **Example** (Attaching layers to an existing parent span)
  *
  * ```ts
- * import { Effect, Layer, Context, Tracer } from "effect"
+ * import { Context, Effect, Layer, Tracer } from "effect"
  *
  * class Database extends Context.Service<Database, {
  *   readonly query: (sql: string) => Effect.Effect<string>
@@ -4040,7 +3999,7 @@ export const withSpan: {
  * ```
  *
  * @category tracing
- * @since 4.0.0
+ * @since 2.0.0
  */
 export const withParentSpan: {
   /**
@@ -4054,7 +4013,7 @@ export const withParentSpan: {
    * **Example** (Attaching layers to an existing parent span)
    *
    * ```ts
-   * import { Effect, Layer, Context, Tracer } from "effect"
+   * import { Context, Effect, Layer, Tracer } from "effect"
    *
    * class Database extends Context.Service<Database, {
    *   readonly query: (sql: string) => Effect.Effect<string>
@@ -4102,7 +4061,7 @@ export const withParentSpan: {
    * ```
    *
    * @category tracing
-   * @since 4.0.0
+   * @since 2.0.0
    */
   (span: Tracer.AnySpan, options?: Tracer.TraceOptions): <A, E, R>(
     self: Layer<A, E, R>
@@ -4118,7 +4077,7 @@ export const withParentSpan: {
    * **Example** (Attaching layers to an existing parent span)
    *
    * ```ts
-   * import { Effect, Layer, Context, Tracer } from "effect"
+   * import { Context, Effect, Layer, Tracer } from "effect"
    *
    * class Database extends Context.Service<Database, {
    *   readonly query: (sql: string) => Effect.Effect<string>
@@ -4166,7 +4125,7 @@ export const withParentSpan: {
    * ```
    *
    * @category tracing
-   * @since 4.0.0
+   * @since 2.0.0
    */
   <A, E, R>(self: Layer<A, E, R>, span: Tracer.AnySpan, options?: Tracer.TraceOptions): Layer<A, E, Exclude<R, Tracer.ParentSpan>>
 } = function() {