effect 4.0.0-beta.66 → 4.0.0-beta.68

package/dist/Layer.js

@@ -11,12 +11,17 @@ import * as Scope from "./Scope.js";
 import * as Tracer from "./Tracer.js";
 const TypeId = "~effect/Layer";
 const MemoMapTypeId = "~effect/Layer/MemoMap";
+const memoMapReuse = (entry, scope) => {
+  entry.observers++;
+  return internalEffect.andThen(internalEffect.scopeAddFinalizerExit(scope, exit => entry.finalizer(exit)), entry.effect);
+};
 /**
  * Returns `true` if the specified value is a `Layer`, `false` otherwise.
  *
- * @example
+ * **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>
@@ -31,8 +36,8 @@ const MemoMapTypeId = "~effect/Layer/MemoMap";
  * console.log(Layer.isLayer(notALayer)) // false
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export const isLayer = u => hasProperty(u, TypeId);
 const LayerProto = {
@@ -56,9 +61,10 @@ const fromBuildUnsafe = build => {
  * The function receives a `MemoMap` for memoization and a `Scope` for resource management.
  * A child scope is created, and if the build fails, the child scope is closed.
  *
- * @example
+ * **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>
@@ -73,8 +79,8 @@ const fromBuildUnsafe = build => {
  * )
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const fromBuild = build => fromBuildUnsafe((memoMap, scope) => {
   const layerScope = Scope.forkUnsafe(scope);
@@ -87,9 +93,10 @@ export const fromBuild = build => fromBuildUnsafe((memoMap, scope) => {
  * This is similar to `fromBuild` but provides automatic memoization of the layer construction.
  * The layer will be memoized based on the provided `MemoMap`.
  *
- * @example
+ * **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>
@@ -104,51 +111,65 @@ export const fromBuild = build => fromBuildUnsafe((memoMap, scope) => {
  * )
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const fromBuildMemo = build => {
   const self = fromBuild((memoMap, scope) => memoMap.getOrElseMemoize(self, scope, build));
   return self;
 };
+const memoMapBuild = (memoMap, layer, scope, build) => {
+  const layerScope = Scope.makeUnsafe();
+  const deferred = Deferred.makeUnsafe();
+  const entry = {
+    observers: 1,
+    effect: Deferred.await(deferred),
+    finalizer: exit => internalEffect.suspend(() => {
+      entry.observers--;
+      if (entry.observers === 0) {
+        memoMap.map.delete(layer);
+        return Scope.close(layerScope, exit);
+      }
+      return internalEffect.void;
+    })
+  };
+  memoMap.map.set(layer, entry);
+  return internalEffect.scopeAddFinalizerExit(scope, entry.finalizer).pipe(internalEffect.flatMap(() => build(memoMap, layerScope)), internalEffect.onExit(exit => {
+    entry.effect = exit;
+    return Deferred.done(deferred, exit);
+  }));
+};
 class MemoMapImpl {
   get [MemoMapTypeId]() {
     return MemoMapTypeId;
   }
+  parent;
+  constructor(parent) {
+    this.parent = parent;
+  }
   map = /*#__PURE__*/new Map();
+  get(layer, scope) {
+    const local = this.map.get(layer);
+    if (local) {
+      return memoMapReuse(local, scope);
+    }
+    return this.parent?.get(layer, scope);
+  }
   getOrElseMemoize(layer, scope, build) {
-    if (this.map.has(layer)) {
-      const entry = this.map.get(layer);
-      entry.observers++;
-      return internalEffect.andThen(internalEffect.scopeAddFinalizerExit(scope, exit => entry.finalizer(exit)), entry.effect);
+    const existing = this.get(layer, scope);
+    if (existing) {
+      return existing;
     }
-    const layerScope = Scope.makeUnsafe();
-    const deferred = Deferred.makeUnsafe();
-    const entry = {
-      observers: 1,
-      effect: Deferred.await(deferred),
-      finalizer: exit => internalEffect.suspend(() => {
-        entry.observers--;
-        if (entry.observers === 0) {
-          this.map.delete(layer);
-          return Scope.close(layerScope, exit);
-        }
-        return internalEffect.void;
-      })
-    };
-    this.map.set(layer, entry);
-    return internalEffect.scopeAddFinalizerExit(scope, entry.finalizer).pipe(internalEffect.flatMap(() => build(this, layerScope)), internalEffect.onExit(exit => {
-      entry.effect = exit;
-      return Deferred.done(deferred, exit);
-    }));
+    return memoMapBuild(this, layer, scope, build);
   }
 }
 /**
  * Constructs a `MemoMap` that can be used to build additional layers.
  *
- * @example
+ * **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>
@@ -168,16 +189,25 @@ class MemoMapImpl {
  * })
  * ```
  *
- * @since 4.0.0
  * @category memo map
+ * @since 4.0.0
  */
 export const makeMemoMapUnsafe = () => 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.
+ *
+ * @category memo map
+ * @since 4.0.0
+ */
+export const forkMemoMapUnsafe = parent => new MemoMapImpl(parent);
 /**
  * Constructs a `MemoMap` that can be used to build additional layers.
  *
- * @example
+ * **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>
@@ -197,18 +227,26 @@ export const makeMemoMapUnsafe = () => new MemoMapImpl();
  * })
  * ```
  *
- * @since 2.0.0
  * @category memo map
+ * @since 2.0.0
  */
 export const makeMemoMap = /*#__PURE__*/internalEffect.sync(makeMemoMapUnsafe);
+/**
+ * Constructs a child `MemoMap` that can reuse layers already memoized in the
+ * parent while isolating any new layer allocations to the child map.
+ *
+ * @category memo map
+ * @since 4.0.0
+ */
+export const forkMemoMap = parent => internalEffect.sync(() => forkMemoMapUnsafe(parent));
 /**
  * A service reference for the current `MemoMap` used in layer construction.
  *
  * This service provides access to the current memoization map during layer building,
  * allowing layers to share memoized results.
  *
- * @since 3.13.0
  * @category models
+ * @since 3.13.0
  */
 export class CurrentMemoMap extends /*#__PURE__*/Context.Service()("effect/Layer/CurrentMemoMap") {
   static getOrCreate = /*#__PURE__*/Context.getOrElse(this, makeMemoMapUnsafe);
@@ -217,9 +255,10 @@ export class CurrentMemoMap extends /*#__PURE__*/Context.Service()("effect/Layer
  * Builds a layer into an `Effect` value, using the specified `MemoMap` to memoize
  * the layer construction.
  *
- * @example
+ * **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>
@@ -257,16 +296,17 @@ export class CurrentMemoMap extends /*#__PURE__*/Context.Service()("effect/Layer
  * })
  * ```
  *
- * @since 2.0.0
  * @category memo map
+ * @since 2.0.0
  */
 export const buildWithMemoMap = /*#__PURE__*/dual(3, (self, memoMap, scope) => internalEffect.provideService(internalEffect.map(self.build(memoMap, scope), Context.add(CurrentMemoMap, memoMap)), CurrentMemoMap, memoMap));
 /**
  * Builds a layer into a scoped value.
  *
- * @example
+ * **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>
@@ -288,8 +328,8 @@ export const buildWithMemoMap = /*#__PURE__*/dual(3, (self, memoMap, scope) => i
  * })
  * ```
  *
- * @since 2.0.0
  * @category destructors
+ * @since 2.0.0
  */
 export const build = self => core.withFiber(fiber => buildWithMemoMap(self, CurrentMemoMap.getOrCreate(fiber.context), Context.getUnsafe(fiber.context, Scope.Scope)));
 /**
@@ -299,9 +339,10 @@ export const build = self => core.withFiber(fiber => buildWithMemoMap(self, Curr
  * the services output by the layer exceed the lifetime of the effect the
  * layer is provided to.
  *
- * @example
+ * **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>
@@ -329,16 +370,17 @@ export const build = self => core.withFiber(fiber => buildWithMemoMap(self, Curr
  * })
  * ```
  *
- * @since 2.0.0
  * @category destructors
+ * @since 2.0.0
  */
 export const buildWithScope = /*#__PURE__*/dual(2, (self, scope) => core.withFiber(fiber => buildWithMemoMap(self, CurrentMemoMap.getOrCreate(fiber.context), scope)));
 /**
  * Constructs a layer from the specified value.
  *
- * @example
+ * **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>
@@ -372,8 +414,8 @@ export const buildWithScope = /*#__PURE__*/dual(2, (self, scope) => core.withFib
  * )
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const succeed = function () {
   if (arguments.length === 1) {
@@ -388,9 +430,10 @@ export const succeed = function () {
  * This is a more general version of `succeed` that allows you to provide multiple
  * services at once through a `Context`.
  *
- * @example
+ * **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>
@@ -411,8 +454,8 @@ export const succeed = function () {
  * const layer = Layer.succeedContext(context)
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const succeedContext = context => fromBuildUnsafe(constant(internalEffect.succeed(context)));
 /**
@@ -421,15 +464,16 @@ export const succeedContext = context => fromBuildUnsafe(constant(internalEffect
  * This layer provides no services and can be used as a neutral element
  * in layer composition or as a starting point for building layers.
  *
- * @example
+ * **Example** (Creating an empty layer)
+ *
  * ```ts
  * import { Layer } from "effect"
  *
  * const emptyLayer = Layer.empty
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const empty = /*#__PURE__*/succeedContext(/*#__PURE__*/Context.empty());
 /**
@@ -438,9 +482,10 @@ export const empty = /*#__PURE__*/succeedContext(/*#__PURE__*/Context.empty());
  * This is a lazy version of `succeed` where the service value is computed
  * synchronously only when the layer is built.
  *
- * @example
+ * **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>
@@ -451,8 +496,8 @@ export const empty = /*#__PURE__*/succeedContext(/*#__PURE__*/Context.empty());
  * }))
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const sync = function () {
   if (arguments.length === 1) {
@@ -467,9 +512,10 @@ export const sync = function () {
  * This is a lazy version of `succeedContext` where the Context is computed
  * synchronously only when the layer is built.
  *
- * @example
+ * **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>
@@ -482,8 +528,8 @@ export const sync = function () {
  * )
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const syncContext = evaluate => fromBuildMemo(constant(internalEffect.sync(evaluate)));
 /**
@@ -493,15 +539,10 @@ export const syncContext = evaluate => fromBuildMemo(constant(internalEffect.syn
  * 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)
  *
- * @example
  * ```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>
@@ -514,8 +555,8 @@ export const syncContext = evaluate => fromBuildMemo(constant(internalEffect.syn
  * )
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const effect = function () {
   if (arguments.length === 1) {
@@ -531,9 +572,10 @@ const effectImpl = (service, effect) => effectContext(internalEffect.map(effect,
  * This allows you to create a Layer from an effectful computation that returns
  * multiple services. The Effect is executed in the scope of the layer.
  *
- * @example
+ * **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,
@@ -547,8 +589,8 @@ const effectImpl = (service, effect) => effectContext(internalEffect.map(effect,
  * )
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const effectContext = effect => fromBuildMemo((_, scope) => Scope.provide(effect, scope));
 /**
@@ -557,13 +599,8 @@ export const effectContext = effect => fromBuildMemo((_, scope) => Scope.provide
  * 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:
+ * **Example** (Running an effect during layer construction)
  *
- * - `Layer.scopedDiscard`
- *
- * @example
  * ```ts
  * import { Effect, Layer } from "effect"
  *
@@ -574,8 +611,8 @@ export const effectContext = effect => fromBuildMemo((_, scope) => Scope.provide
  * )
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const effectDiscard = effect => effectContext(internalEffect.as(effect, Context.empty()));
 /**
@@ -584,9 +621,10 @@ export const effectDiscard = effect => effectContext(internalEffect.as(effect, C
  * The factory is evaluated only when the suspended layer is first built, and
  * the result is memoized with normal layer sharing semantics.
  *
- * @example
+ * **Example** (Choosing a layer lazily)
+ *
  * ```ts
- * import { Layer, Context } from "effect"
+ * import { Context, Layer } from "effect"
  *
  * class Config extends Context.Service<Config, string>()("Config") {}
  *
@@ -599,8 +637,8 @@ export const effectDiscard = effect => effectContext(internalEffect.as(effect, C
  * )
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const suspend = evaluate => fromBuildMemo((memoMap, scope) => internalEffect.suspend(() => evaluate().build(memoMap, scope)));
 /**
@@ -610,9 +648,10 @@ export const suspend = evaluate => fromBuildMemo((memoMap, scope) => internalEff
  * use that Layer directly. The resulting Layer will have the combined error and
  * dependency types from both the outer Effect and the inner Layer.
  *
- * @example
+ * **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>
@@ -625,8 +664,8 @@ export const suspend = evaluate => fromBuildMemo((memoMap, scope) => internalEff
  * const unwrappedLayer = Layer.unwrap(layerEffect)
  * ```
  *
- * @since 4.0.0
  * @category utils
+ * @since 4.0.0
  */
 export const unwrap = self => {
   const service = Context.Service("effect/Layer/unwrap");
@@ -644,9 +683,10 @@ const mergeAllEffect = (layers, memoMap, scope) => {
  * All layers are built concurrently, and their outputs are merged into a single layer.
  * This is useful when you need to combine multiple independent layers.
  *
- * @example
+ * **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>
@@ -666,8 +706,8 @@ const mergeAllEffect = (layers, memoMap, scope) => {
  * const mergedLayer = Layer.mergeAll(dbLayer, loggerLayer)
  * ```
  *
- * @since 2.0.0
  * @category zipping
+ * @since 2.0.0
  */
 export const mergeAll = (...layers) => fromBuild((memoMap, scope) => mergeAllEffect(layers, memoMap, scope));
 /**
@@ -676,9 +716,10 @@ export const mergeAll = (...layers) => fromBuild((memoMap, scope) => mergeAllEff
  * This is a binary version of `mergeAll` that merges exactly two layers or one layer with an array of layers.
  * The layers are built concurrently and their outputs are combined.
  *
- * @example
+ * **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>
@@ -698,8 +739,8 @@ export const mergeAll = (...layers) => fromBuild((memoMap, scope) => mergeAllEff
  * const mergedLayer = Layer.merge(dbLayer, loggerLayer)
  * ```
  *
- * @since 2.0.0
  * @category zipping
+ * @since 2.0.0
  */
 export const merge = /*#__PURE__*/dual(2, (self, that) => mergeAll(self, ...(Array.isArray(that) ? that : [that])));
 const provideWith = (self, that, f) => fromBuild((memoMap, scope) => internalEffect.flatMap(Array.isArray(that) ? mergeAllEffect(that, memoMap, scope) : that.build(memoMap, scope), context => self.build(memoMap, scope).pipe(internalEffect.provideContext(context), internalEffect.map(merged => f(merged, context)))));
@@ -708,9 +749,10 @@ const provideWith = (self, that, f) => fromBuild((memoMap, scope) => internalEff
  * builder, resulting in a new builder with the inputs of this builder as
  * well as any leftover inputs, and the outputs of the specified builder.
  *
- * @example
+ * **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>
@@ -766,8 +808,8 @@ const provideWith = (self, that, f) => fromBuild((memoMap, scope) => internalEff
  * )
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export const provide = /*#__PURE__*/dual(2, (self, that) => provideWith(self, that, identity));
 /**
@@ -775,9 +817,10 @@ export const provide = /*#__PURE__*/dual(2, (self, that) => provideWith(self, th
  * layer, resulting in a new layer with the inputs of this layer, and the
  * outputs of both layers.
  *
- * @example
+ * **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>
@@ -839,16 +882,17 @@ export const provide = /*#__PURE__*/dual(2, (self, that) => provideWith(self, th
  * )
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export const provideMerge = /*#__PURE__*/dual(2, (self, that) => provideWith(self, that, (self, that) => Context.merge(that, self)));
 /**
  * Constructs a layer dynamically based on the output of this layer.
  *
- * @example
+ * **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
@@ -910,44 +954,45 @@ export const provideMerge = /*#__PURE__*/dual(2, (self, that) => provideWith(sel
  * )
  * ```
  *
- * @since 2.0.0
  * @category sequencing
+ * @since 2.0.0
  */
 export const flatMap = /*#__PURE__*/dual(2, (self, f) => fromBuild((memoMap, scope) => internalEffect.flatMap(self.build(memoMap, scope), context => f(context).build(memoMap, scope))));
 /**
  * Performs the specified effect if this layer succeeds.
  *
- * @since 4.0.0
  * @category sequencing
+ * @since 2.0.0
  */
 export const tap = /*#__PURE__*/dual(2, (self, f) => fromBuild((memoMap, scope) => internalEffect.flatMap(self.build(memoMap, scope), context => Scope.provide(internalEffect.as(f(context), context), scope))));
 /**
  * Performs the specified effect if this layer fails.
  *
- * @since 4.0.0
  * @category sequencing
+ * @since 2.0.0
  */
 export const tapError = /*#__PURE__*/dual(2, (self, f) => fromBuild((memoMap, scope) => internalEffect.catch_(self.build(memoMap, scope), error => Scope.provide(internalEffect.andThen(f(error), internalEffect.fail(error)), scope))));
 /**
- * Performs the specified effect if this layer fails.
+ * Performs the specified effect when this layer fails with any cause.
  *
- * **Previously Known As**
- *
- * This API replaces the following from Effect 3.x:
- *
- * - `Layer.tapErrorCause`
+ * **Details**
+ * The callback receives the layer's `Cause`, so it can inspect typed errors,
+ * defects, and interruption information. If the callback succeeds, the layer
+ * fails again with the original cause; if the callback fails, that failure is
+ * added to the layer's error type.
  *
- * @since 4.0.0
  * @category sequencing
+ * @since 4.0.0
  */
 export const tapCause = /*#__PURE__*/dual(2, (self, f) => fromBuild((memoMap, scope) => internalEffect.catchCause(self.build(memoMap, scope), cause => Scope.provide(internalEffect.andThen(f(cause), internalEffect.failCause(cause)), scope))));
 /**
  * Translates effect failure into death of the fiber, making all failures
  * unchecked and not a part of the type of the layer.
  *
- * @example
+ * **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
@@ -959,13 +1004,8 @@ export const tapCause = /*#__PURE__*/dual(2, (self, f) => fromBuild((memoMap, sc
  *
  * // Layer that can fail during construction
  * const flakyDatabaseLayer = Layer.effect(Database)(Effect.gen(function*() {
- *   // Simulate a database connection that might fail
- *   const shouldFail = Math.random() > 0.5
- *   if (shouldFail) {
- *     return yield* new DatabaseError({ message: "Connection failed" })
- *   }
- *
- *   return { query: Effect.fn("Database.query")((sql: string) => Effect.succeed(`Result: ${sql}`)) }
+ *   console.log("connecting")
+ *   return yield* new DatabaseError({ message: "Connection failed" })
  * }))
  *
  * // Convert failures to fiber death - removes error from type
@@ -979,12 +1019,12 @@ export const tapCause = /*#__PURE__*/dual(2, (self, f) => fromBuild((memoMap, sc
  *   Effect.provide(reliableDatabaseLayer)
  * )
  *
- * // If the database layer fails, the entire fiber will die
- * // instead of the effect failing with DatabaseError
+ * // Running the program prints "connecting", then the DatabaseError is
+ * // converted into a fiber defect instead of remaining a typed error.
  * ```
  *
- * @since 2.0.0
  * @category error handling
+ * @since 2.0.0
  */
 export const orDie = self => fromBuildUnsafe((memoMap, scope) => internalEffect.orDie(self.build(memoMap, scope)));
 const catch_ = /*#__PURE__*/dual(2, (self, onError) => fromBuildUnsafe((memoMap, scope) => internalEffect.catch_(self.build(memoMap, scope), e => onError(e).build(memoMap, scope))));
@@ -992,16 +1032,17 @@ export {
 /**
  * Recovers from all errors.
  *
- * @since 4.0.0
  * @category error handling
+ * @since 4.0.0
  */
 catch_ as catch };
 /**
  * Recovers from specific tagged errors.
  *
- * @example
+ * **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") {}
  *
@@ -1018,66 +1059,57 @@ catch_ as catch };
  * )
  * ```
  *
- * @since 4.0.0
  * @category error handling
+ * @since 4.0.0
  */
 export const catchTag = /*#__PURE__*/dual(3, (self, k, f) => fromBuildUnsafe((memoMap, scope) => internalEffect.catchTag(self.build(memoMap, scope), k, error => f(error).build(memoMap, scope))));
 /**
- * Recovers from all errors.
+ * Recovers from any failure cause by switching to another layer.
+ *
+ * **Details**
+ * The handler receives the full `Cause` of the failed layer, including typed
+ * errors, defects, and interruption information, and returns the fallback layer
+ * to build instead.
+ *
+ * **Example** (Recovering from layer failures by cause)
  *
- * @example
  * ```ts
- * import { Data, Effect, Layer, Context } from "effect"
+ * import { Context, Data, Effect, Layer } from "effect"
  *
  * class DatabaseError extends Data.TaggedError("DatabaseError")<{
  *   message: string
  * }> {}
  *
- * class NetworkError extends Data.TaggedError("NetworkError")<{
- *   reason: string
- * }> {}
- *
  * class Database extends Context.Service<Database, {
  *   readonly query: (sql: string) => Effect.Effect<string>
  * }>()("Database") {}
  *
- * class Logger extends Context.Service<Logger, {
- *   readonly log: (msg: string) => Effect.Effect<void>
- * }>()("Logger") {}
- *
- * // Primary database layer that might fail
- * const primaryDatabaseLayer = Layer.effect(Database)(Effect.gen(function*() {
- *   return yield* new DatabaseError({ message: "Primary DB unreachable" })
- *   return { query: Effect.fn("Database.query")((sql: string) => Effect.succeed(`Primary: ${sql}`)) }
- * }))
+ * const primaryDatabaseLayer = Layer.effect(Database)(
+ *   Effect.fail(new DatabaseError({ message: "Primary DB unreachable" }))
+ * )
  *
- * // Fallback layers for different error causes
  * const databaseWithFallback = primaryDatabaseLayer.pipe(
  *   Layer.catchCause(() => {
- *     // For any cause/error, fallback to in-memory database
- *     return Layer.mergeAll(
- *       Layer.succeed(Database)({
- *         query: Effect.fn("Database.query")((sql: string) => Effect.succeed(`Memory: ${sql}`))
- *       }),
- *       Layer.succeed(Logger)({
- *         log: Effect.fn("Logger.log")((msg: string) =>
- *           Effect.sync(() => console.log(`[FALLBACK] ${msg}`))
- *         )
- *       })
- *     )
+ *     return Layer.succeed(Database)({
+ *       query: Effect.fn("Database.query")((sql: string) => Effect.succeed(`Memory: ${sql}`))
+ *     })
  *   })
  * )
  *
  * const program = Effect.gen(function*() {
  *   const database = yield* Database
- *   return yield* database.query("SELECT * FROM users")
+ *   const result = yield* database.query("SELECT * FROM users")
+ *   console.log(result)
  * }).pipe(
  *   Effect.provide(databaseWithFallback)
  * )
+ *
+ * Effect.runPromise(program)
+ * // Memory: SELECT * FROM users
  * ```
  *
- * @since 2.0.0
  * @category error handling
+ * @since 4.0.0
  */
 export const catchCause = /*#__PURE__*/dual(2, (self, onError) => fromBuildUnsafe((memoMap, scope) => internalEffect.catchCause(self.build(memoMap, scope), cause => onError(cause).build(memoMap, scope))));
 /**
@@ -1095,69 +1127,91 @@ export const catchCause = /*#__PURE__*/dual(2, (self, onError) => fromBuildUnsaf
  * This is useful for adapting or extending a service's behavior during the
  * creation of a layer.
  *
- * @since 3.13.0
  * @category utils
+ * @since 3.13.0
  */
 export const updateService = /*#__PURE__*/dual(3, (layer, service, f) => provide(layer, effect(service, internalEffect.map(service, f))));
 /**
  * Creates a fresh version of this layer that will not be shared.
  *
- * @example
+ * **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 count: number
- *   readonly increment: () => Effect.Effect<number>
+ *   readonly id: number
  * }>()("Counter") {}
  *
- * // Layer that creates a counter with shared state
- * const counterLayer = Layer.effect(Counter)(Effect.gen(function*() {
- *   const ref = yield* Ref.make(0)
- *   return {
- *     count: 0,
- *     increment: Effect.fn("Counter.increment")(() =>
- *       Ref.update(ref, (n) => n + 1).pipe(
- *         Effect.flatMap(() => Ref.get(ref))
- *       )
- *     )
- *   }
+ * class Left extends Context.Service<Left, {
+ *   readonly counterId: number
+ * }>()("Left") {}
+ *
+ * class Right extends Context.Service<Right, {
+ *   readonly counterId: number
+ * }>()("Right") {}
+ *
+ * const leftLayer = Layer.effect(Left)(Effect.gen(function*() {
+ *   const counter = yield* Counter
+ *   return { counterId: counter.id }
  * }))
  *
- * // By default, layers are shared - same instance used everywhere
- * const sharedProgram = Effect.gen(function*() {
- *   const counter1 = yield* Counter
- *   const counter2 = yield* Counter
+ * const rightLayer = Layer.effect(Right)(Effect.gen(function*() {
+ *   const counter = yield* Counter
+ *   return { counterId: counter.id }
+ * }))
  *
- *   // Both counter1 and counter2 refer to the same instance
- *   console.log("Shared layer - same instance")
- * }).pipe(
- *   Effect.provide(counterLayer)
- * )
+ * const showIds = Effect.gen(function*() {
+ *   const left = yield* Left
+ *   const right = yield* Right
+ *   console.log(`same Counter: ${left.counterId === right.counterId}`)
+ * })
  *
- * // Fresh layer creates a new instance each time
- * const freshProgram = Effect.gen(function*() {
- *   const counter1 = yield* Counter
- *   const counter2 = yield* Counter
+ * const program = Effect.gen(function*() {
+ *   const nextId = yield* Ref.make(0)
  *
- *   // counter1 and counter2 are different instances
- *   console.log("Fresh layer - different instances")
- * }).pipe(
- *   Effect.provide(Layer.fresh(counterLayer))
- * )
+ *   const counterLayer = Layer.effect(Counter)(Effect.gen(function*() {
+ *     const id = yield* Ref.updateAndGet(nextId, (n) => n + 1)
+ *     console.log("constructed Counter")
+ *     return { id }
+ *   }))
+ *
+ *   const shared = Layer.merge(
+ *     Layer.provide(leftLayer, counterLayer),
+ *     Layer.provide(rightLayer, counterLayer)
+ *   )
+ *
+ *   yield* Effect.provide(showIds, shared)
+ *
+ *   const freshCounterLayer = Layer.fresh(counterLayer)
+ *   const fresh = Layer.merge(
+ *     Layer.provide(leftLayer, freshCounterLayer),
+ *     Layer.provide(rightLayer, freshCounterLayer)
+ *   )
+ *
+ *   yield* Effect.provide(showIds, fresh)
+ * })
+ *
+ * Effect.runPromise(program)
+ * // constructed Counter
+ * // same Counter: true
+ * // constructed Counter
+ * // constructed Counter
+ * // same Counter: false
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export const fresh = self => fromBuildUnsafe((_, scope) => self.build(makeMemoMapUnsafe(), scope));
 /**
  * Builds this layer and uses it until it is interrupted. This is useful when
  * your entire application is a layer, such as an HTTP server.
  *
- * @example
+ * **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>
@@ -1202,8 +1256,8 @@ export const fresh = self => fromBuildUnsafe((_, scope) => self.build(makeMemoMa
  * // Effect.runFork(application)
  * ```
  *
+ * @category converting
  * @since 2.0.0
- * @category conversions
  */
 export const launch = self => internalEffect.scoped(internalEffect.andThen(build(self), internalEffect.never));
 /**
@@ -1211,9 +1265,10 @@ export const launch = self => internalEffect.scoped(internalEffect.andThen(build
  * implementation of the service, and any methods not provided will
  * throw an unimplemented defect when called.
  *
- * @example
+ * **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 }
@@ -1249,8 +1304,8 @@ export const launch = self => internalEffect.scoped(internalEffect.andThen(build
  * )
  * ```
  *
- * @since 4.0.0
  * @category Testing
+ * @since 3.17.0
  */
 export const mock = function () {
   if (arguments.length === 1) {
@@ -1306,7 +1361,8 @@ const ChannelTypeId = "~effect/Channel";
  * This function provides compile-time type checking to ensure that the success
  * value of an layer conforms to a specific type constraint.
  *
- * @example
+ * **Example** (Constraining layer success types)
+ *
  * ```ts
  * import { Layer } from "effect"
  *
@@ -1322,11 +1378,11 @@ const ChannelTypeId = "~effect/Channel";
  * // This would cause a TypeScript compilation error:
  * // const invalidLayer = satisfiesNumber(StringLayer)
  * //                                     ^^^^^^^^^^^
- * // Type 'number' is not assignable to type 'string'
+ * // Type 'string' is not assignable to type 'number'
  * ```
  *
- * @since 4.0.0
  * @category Type constraints
+ * @since 4.0.0
  */
 export const satisfiesSuccessType = () => layer => layer;
 /**
@@ -1335,7 +1391,8 @@ export const satisfiesSuccessType = () => layer => layer;
  * This function provides compile-time type checking to ensure that the error
  * type of an layer conforms to a specific type constraint.
  *
- * @example
+ * **Example** (Constraining layer error types)
+ *
  * ```ts
  * import { Layer } from "effect"
  *
@@ -1355,8 +1412,8 @@ export const satisfiesSuccessType = () => layer => layer;
  * // Type 'string' is not assignable to type 'Error'
  * ```
  *
- * @since 4.0.0
  * @category Type constraints
+ * @since 4.0.0
  */
 export const satisfiesErrorType = () => layer => layer;
 /**
@@ -1365,14 +1422,15 @@ export const satisfiesErrorType = () => layer => layer;
  * This function provides compile-time type checking to ensure that the
  * requirements (context) type of an layer conforms to a specific type constraint.
  *
- * @example
+ * **Example** (Constraining layer service requirements)
+ *
  * ```ts
  * import { Layer } from "effect"
  *
  * declare const FortyTwoLayer: Layer.Layer<never, never, 42>
  * declare const StringLayer: Layer.Layer<never, never, string>
  *
- * // Define a constraint that the success type must be a number
+ * // Define a constraint that the service requirements must be numbers
  * const satisfiesNumber = Layer.satisfiesServicesType<number>()
  *
  * // This works - Layer<never, never, 42> extends Layer<never, never, number>
@@ -1384,8 +1442,8 @@ export const satisfiesErrorType = () => layer => layer;
  * // Type 'string' is not assignable to type 'number'
  * ```
  *
- * @since 4.0.0
  * @category Type constraints
+ * @since 4.0.0
  */
 export const satisfiesServicesType = () => layer => layer;
 /**
@@ -1396,9 +1454,11 @@ export const satisfiesServicesType = () => layer => layer;
  * operations within the layer constructor part of the same trace span. The span
  * is automatically closed when the layer's scope is closed.
  *
- * @example
+ * **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>
@@ -1430,24 +1490,25 @@ export const satisfiesServicesType = () => layer => layer;
  * })
  * ```
  *
- * @since 4.0.0
  * @category tracing
+ * @since 2.0.0
  */
 export const span = (name, options) => {
   options = internalTracer.addSpanStackTrace(options);
   return effect(Tracer.ParentSpan, options?.onEnd ? internalEffect.tap(internalEffect.makeSpanScoped(name, options), span => internalEffect.addFinalizer(exit => options.onEnd(span, exit))) : internalEffect.makeSpanScoped(name, options));
 };
 /**
- * Constructs a new `Layer` which takes an existing span and registers it as the
- * current parent span.
+ * Constructs a layer that provides an existing span as the current parent span.
  *
- * This allows you to create a traced scope for layer construction, making all
- * operations within the layer constructor part of the same trace span. The span
- * is automatically closed when the layer's scope is closed.
+ * **Details**
+ * The supplied span is made available through `Tracer.ParentSpan` for layers
+ * that are built with this layer. This API does not create, end, or close the
+ * span; the caller remains responsible for the span's lifetime.
+ *
+ * **Example** (Using an existing parent span)
  *
- * @example
  * ```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>
@@ -1472,8 +1533,8 @@ export const span = (name, options) => {
  * }))))
  * ```
  *
- * @since 4.0.0
  * @category tracing
+ * @since 2.0.0
  */
 export const parentSpan = span => succeedContext(Tracer.ParentSpan.context(span));
 /**
@@ -1484,9 +1545,10 @@ export const parentSpan = span => succeedContext(Tracer.ParentSpan.context(span)
  * is automatically ended when the layer's scope is closed. This is useful for
  * tracking the lifecycle and performance of layer initialization.
  *
- * @example
+ * **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>
@@ -1531,8 +1593,8 @@ export const parentSpan = span => succeedContext(Tracer.ParentSpan.context(span)
  * )
  * ```
  *
- * @since 4.0.0
  * @category tracing
+ * @since 2.0.0
  */
 export const withSpan = function () {
   const dataFirst = typeof arguments[0] !== "string";
@@ -1545,15 +1607,17 @@ export const withSpan = function () {
   return self => unwrap(internalEffect.map(options?.onEnd !== undefined ? internalEffect.tap(internalEffect.makeSpanScoped(name, options), span => internalEffect.addFinalizer(exit => options.onEnd(span, exit))) : internalEffect.makeSpanScoped(name, options), span => withParentSpan(self, span)));
 };
 /**
- * Wraps a `Layer` with a new tracing span and sets the span as the parent span.
+ * Wraps a layer so spans created during its construction use the supplied span
+ * as their parent.
+ *
+ * **Details**
+ * Use this to attach layer construction to an existing trace hierarchy. This API
+ * does not create or end the supplied parent span.
  *
- * This attaches a layer to an existing trace span, making all operations within
- * the layer children of the provided parent span. This is useful for integrating
- * layer construction into an existing trace hierarchy.
+ * **Example** (Attaching layers to an existing parent span)
  *
- * @example
  * ```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>
@@ -1600,8 +1664,8 @@ export const withSpan = function () {
  * )
  * ```
  *
- * @since 4.0.0
  * @category tracing
+ * @since 2.0.0
  */
 export const withParentSpan = function () {
   const dataFirst = isLayer(arguments[0]);