effect 4.0.0-beta.70 → 4.0.0-beta.72

package/dist/Layer.d.ts

@@ -1,30 +1,43 @@
 /**
- * A `Layer<ROut, E, RIn>` describes how to build one or more services in your
- * application. Services can be injected into effects via
- * `Effect.provideService`. Effects can require services via `Effect.service`.
- *
- * A layer is a recipe for producing services from their dependencies:
- *
- * - `ROut` is what the layer provides.
- * - `E` is what can fail while building the layer.
- * - `RIn` is what the layer needs in order to build.
- *
- * Normal application code should ask for services. Layer code should create
- * services. The application entry point should provide the final layer once.
- * Keeping this boundary clear makes programs easier to reuse with production,
- * test, or mock implementations.
- *
- * Construction of services can be effectful and can acquire resources that must
- * be safely released when the services are no longer used. For example, a layer
- * can open a database pool during acquisition and close it in a finalizer.
- *
- * Layers are lazy: they do not build anything until they are provided to a
- * program or explicitly built. By default layers are shared, meaning that if the
- * same layer value is used twice, it is allocated only once and both users share
- * the same service instance.
- *
- * Because of their excellent composition properties, layers are the idiomatic
- * way in Effect to create services that depend on other services.
+ * The `Layer` module provides the dependency-injection building blocks for
+ * Effect applications. A {@link Layer} describes how to acquire one or more
+ * services, which dependencies are needed to acquire them, and which errors can
+ * occur during acquisition.
+ *
+ * **Mental model**
+ *
+ * - Application effects ask for services through context tags.
+ * - Layer code builds those services, often from configuration, clients,
+ *   connection pools, or other services.
+ * - The application boundary provides a final layer to the program.
+ * - Layers are lazy: acquisition starts only when a layer is provided, built, or
+ *   launched.
+ * - Layer acquisition is scoped, so finalizers run when the owning scope closes.
+ * - A layer value is memoized by default; reusing the same layer value shares
+ *   the acquired service instance.
+ *
+ * **Common tasks**
+ *
+ * - Provide an existing service value with {@link succeed}.
+ * - Build a service lazily with {@link sync}, {@link effect}, or
+ *   {@link effectContext}.
+ * - Run setup work that provides no services with {@link effectDiscard}.
+ * - Combine independent layers with {@link merge} or {@link mergeAll}.
+ * - Feed one layer's output into another layer's requirements with
+ *   {@link provide}.
+ * - Keep dependency services in the final output with {@link provideMerge}.
+ * - Materialize a layer manually with {@link build} or {@link buildWithScope}.
+ *
+ * **Gotchas**
+ *
+ * - Sharing is tied to layer identity. Constructing the same layer twice creates
+ *   two distinct values and can acquire two service instances.
+ * - Use {@link fresh} when a layer must be rebuilt even if the same value is
+ *   provided more than once.
+ * - Scoped resources belong in layers when construction and release are part of
+ *   the service lifecycle.
+ * - Normal application code should request services; layer code should create
+ *   services.
  *
  * @since 2.0.0
  */
@@ -45,6 +58,12 @@ declare const TypeId = "~effect/Layer";
 /**
  * A `Layer` describes how to build one or more services for dependency injection.
  *
+ * **When to use**
+ *
+ * Use to model construction of application services for dependency injection,
+ * especially when services have dependencies, can fail during construction, or
+ * need scoped setup and release.
+ *
  * **Details**
  *
  * A `Layer<ROut, E, RIn>` represents `ROut` as the services this layer
@@ -101,11 +120,22 @@ export interface Variance<in ROut, out E, out RIn> {
 /**
  * A type-level constraint for working with any `Layer` type.
  *
+ * **When to use**
+ *
+ * Use to constrain generic parameters or layer collections to any `Layer`
+ * value while preserving its provided, error, and required service types for
+ * inference.
+ *
  * **Details**
  *
  * This interface is used to constrain generic types to `Layer` values without
  * specifying exact type parameters.
  *
+ * @see {@link Layer} for the concrete layer interface
+ * @see {@link Services} for extracting required services from a layer type
+ * @see {@link Error} for extracting construction errors from a layer type
+ * @see {@link Success} for extracting provided services from a layer type
+ *
  * @category utility types
  * @since 3.9.0
  */
@@ -119,6 +149,14 @@ export interface Any {
 /**
  * Extracts the service requirements (`RIn`) from a `Layer` type.
  *
+ * **When to use**
+ *
+ * Use to derive the dependency requirements of a generic or inferred `Layer`
+ * without restating its `RIn` type parameter.
+ *
+ * @see {@link Success} for extracting the services provided by the same `Layer`
+ * @see {@link Error} for extracting the construction failure type from the same `Layer`
+ *
  * @category utility types
  * @since 4.0.0
  */
@@ -126,6 +164,14 @@ export type Services<T extends Any> = T extends infer L ? L extends Layer<infer
 /**
  * Extracts the error type (`E`) from a `Layer` type.
  *
+ * **When to use**
+ *
+ * Use to derive a layer construction error type for helper types, wrappers, or
+ * APIs that preserve a layer failure channel.
+ *
+ * @see {@link Success} for extracting the services provided by the same `Layer`
+ * @see {@link Services} for extracting the dependency requirements of the same `Layer`
+ *
  * @category utility types
  * @since 2.0.0
  */
@@ -133,6 +179,14 @@ export type Error<T extends Any> = T extends Layer<infer _ROut, infer _E, infer
 /**
  * Extracts the service output type (`ROut`) from a `Layer` type.
  *
+ * **When to use**
+ *
+ * Use to derive the services provided by an existing or generic `Layer` without
+ * restating its `ROut` type parameter.
+ *
+ * @see {@link Error} for extracting the layer construction error type instead
+ * @see {@link Services} for extracting the layer input service requirements instead
+ *
  * @category utility types
  * @since 2.0.0
  */
@@ -266,7 +320,7 @@ export declare const fromBuild: <ROut, E, RIn>(build: (memoMap: MemoMap, scope:
  */
 export declare const fromBuildMemo: <ROut, E, RIn>(build: (memoMap: MemoMap, scope: Scope.Scope) => Effect<Context.Context<ROut>, E, RIn>) => Layer<ROut, E, RIn>;
 /**
- * Constructs a `MemoMap` that can be used to build additional layers.
+ * Constructs a `MemoMap` synchronously so it can be used to build additional layers.
  *
  * **Example** (Creating a memo map unsafely)
  *
@@ -296,15 +350,25 @@ export declare const fromBuildMemo: <ROut, E, RIn>(build: (memoMap: MemoMap, sco
  */
 export declare const makeMemoMapUnsafe: () => MemoMap;
 /**
- * Constructs a child `MemoMap` that can reuse layers already memoized in the
- * parent while isolating any new layer allocations to the child map.
+ * Constructs a child `MemoMap` synchronously, allowing it to reuse layers
+ * already memoized in the parent while isolating any new layer allocations to
+ * the child map.
+ *
+ * **When to use**
+ *
+ * Use to synchronously fork a memo map for manual layer building when child
+ * builds should see parent memoized layers without writing newly built layers
+ * back to the parent.
+ *
+ * @see {@link forkMemoMap} for allocating the child memo map inside `Effect`
+ * @see {@link makeMemoMapUnsafe} for creating a root memo map without a parent
  *
  * @category memo map
  * @since 4.0.0
  */
 export declare const forkMemoMapUnsafe: (parent: MemoMap) => MemoMap;
 /**
- * Constructs a `MemoMap` that can be used to build additional layers.
+ * Constructs a `MemoMap` effectfully so it can be used to build additional layers.
  *
  * **Example** (Creating a memo map in an effect)
  *
@@ -334,8 +398,18 @@ export declare const forkMemoMapUnsafe: (parent: MemoMap) => MemoMap;
  */
 export declare const makeMemoMap: Effect<MemoMap>;
 /**
- * Constructs a child `MemoMap` that can reuse layers already memoized in the
- * parent while isolating any new layer allocations to the child map.
+ * Constructs a child `MemoMap` effectfully, allowing it to reuse layers already
+ * memoized in the parent while isolating any new layer allocations to the child
+ * map.
+ *
+ * **When to use**
+ *
+ * Use when a layer build should inherit already memoized layers from an
+ * existing `MemoMap` while keeping newly memoized layers out of the parent map.
+ *
+ * @see {@link makeMemoMap} for creating a root memo map in an `Effect`
+ * @see {@link forkMemoMapUnsafe} for the synchronous constructor variant
+ * @see {@link buildWithMemoMap} for building layers with an explicit memo map
  *
  * @category memo map
  * @since 4.0.0
@@ -343,12 +417,19 @@ export declare const makeMemoMap: Effect<MemoMap>;
 export declare const forkMemoMap: (parent: MemoMap) => Effect<MemoMap>;
 declare const CurrentMemoMap_base: Context.ServiceClass<CurrentMemoMap, "effect/Layer/CurrentMemoMap", MemoMap>;
 /**
- * A service reference for the current `MemoMap` used in layer construction.
+ * Context service for the current `MemoMap` used in layer construction.
+ *
+ * **When to use**
+ *
+ * Use when building custom layer operations that need to access the current
+ * memoization map from the fiber context.
  *
  * **Details**
  *
- * This service provides access to the current memoization map during layer building,
- * allowing layers to share memoized results.
+ * This service wraps a `MemoMap` as a `Context.Service`, making it available
+ * for dependency injection during layer construction.
+ *
+ * @see {@link MemoMap} the memoization map type wrapped by this service
  *
  * @category models
  * @since 3.13.0
@@ -537,11 +618,17 @@ export declare const buildWithMemoMap: {
  */
 export declare const build: <RIn, E, ROut>(self: Layer<ROut, E, RIn>) => Effect<Context.Context<ROut>, E, RIn | Scope.Scope>;
 /**
- * Builds a layer into an `Effect` value. Any resources associated with this
- * layer will be released when the specified scope is closed unless their scope
- * has been extended. This allows building layers where the lifetime of some of
- * the services output by the layer exceed the lifetime of the effect the
- * layer is provided to.
+ * Builds a layer using an explicit scope.
+ *
+ * **When to use**
+ *
+ * Use to control the lifetime of layer resources with a scope supplied by the
+ * caller.
+ *
+ * **Details**
+ *
+ * Resources created by the layer are released when the supplied scope is
+ * closed, unless a resource extends its own scope.
  *
  * **Example** (Building a layer with an explicit scope)
  *
@@ -579,11 +666,17 @@ export declare const build: <RIn, E, ROut>(self: Layer<ROut, E, RIn>) => Effect<
  */
 export declare const buildWithScope: {
     /**
-     * Builds a layer into an `Effect` value. Any resources associated with this
-     * layer will be released when the specified scope is closed unless their scope
-     * has been extended. This allows building layers where the lifetime of some of
-     * the services output by the layer exceed the lifetime of the effect the
-     * layer is provided to.
+     * Builds a layer using an explicit scope.
+     *
+     * **When to use**
+     *
+     * Use to control the lifetime of layer resources with a scope supplied by the
+     * caller.
+     *
+     * **Details**
+     *
+     * Resources created by the layer are released when the supplied scope is
+     * closed, unless a resource extends its own scope.
      *
      * **Example** (Building a layer with an explicit scope)
      *
@@ -621,11 +714,17 @@ export declare const buildWithScope: {
      */
     (scope: Scope.Scope): <RIn, E, ROut>(self: Layer<ROut, E, RIn>) => Effect<Context.Context<ROut>, E, RIn>;
     /**
-     * Builds a layer into an `Effect` value. Any resources associated with this
-     * layer will be released when the specified scope is closed unless their scope
-     * has been extended. This allows building layers where the lifetime of some of
-     * the services output by the layer exceed the lifetime of the effect the
-     * layer is provided to.
+     * Builds a layer using an explicit scope.
+     *
+     * **When to use**
+     *
+     * Use to control the lifetime of layer resources with a scope supplied by the
+     * caller.
+     *
+     * **Details**
+     *
+     * Resources created by the layer are released when the supplied scope is
+     * closed, unless a resource extends its own scope.
      *
      * **Example** (Building a layer with an explicit scope)
      *
@@ -669,7 +768,7 @@ export declare const buildWithScope: {
  *
  * **When to use**
  *
- * Use `succeed` when the service implementation is already constructed and does
+ * Use when the service implementation is already constructed and does
  * not need effectful acquisition. Use `sync` when the service should be created
  * lazily during layer construction.
  *
@@ -699,7 +798,7 @@ export declare const succeed: {
      *
      * **When to use**
      *
-     * Use `succeed` when the service implementation is already constructed and does
+     * Use when the service implementation is already constructed and does
      * not need effectful acquisition. Use `sync` when the service should be created
      * lazily during layer construction.
      *
@@ -729,7 +828,7 @@ export declare const succeed: {
      *
      * **When to use**
      *
-     * Use `succeed` when the service implementation is already constructed and does
+     * Use when the service implementation is already constructed and does
      * not need effectful acquisition. Use `sync` when the service should be created
      * lazily during layer construction.
      *
@@ -760,7 +859,7 @@ export declare const succeed: {
  *
  * **When to use**
  *
- * Use `succeedContext` when you already have a `Context` or need to provide
+ * Use when you already have a `Context` or need to provide
  * multiple services at once. Use `succeed` when you only need to provide one
  * service value.
  *
@@ -805,7 +904,7 @@ export declare const succeedContext: <A>(context: Context.Context<A>) => Layer<A
  *
  * **When to use**
  *
- * Use `Layer.empty` as the no-op branch when conditionally composing layers.
+ * Use when you use `Layer.empty` as the no-op branch when conditionally composing layers.
  * If you need to run an effect during layer construction while still providing
  * no services, use `effectDiscard`.
  *
@@ -828,11 +927,11 @@ export declare const succeedContext: <A>(context: Context.Context<A>) => Layer<A
  */
 export declare const empty: Layer<never>;
 /**
- * Lazily constructs a layer that provides a single service.
+ * Constructs a layer lazily that provides a single service.
  *
  * **When to use**
  *
- * Use `sync` when the service can be created synchronously but should be
+ * Use when the service can be created synchronously but should be
  * deferred until the layer is built. Use `succeed` when the service value is
  * already available.
  *
@@ -862,11 +961,11 @@ export declare const empty: Layer<never>;
  */
 export declare const sync: {
     /**
-     * Lazily constructs a layer that provides a single service.
+     * Constructs a layer lazily that provides a single service.
      *
      * **When to use**
      *
-     * Use `sync` when the service can be created synchronously but should be
+     * Use when the service can be created synchronously but should be
      * deferred until the layer is built. Use `succeed` when the service value is
      * already available.
      *
@@ -896,11 +995,11 @@ export declare const sync: {
      */
     <I, S>(service: Context.Key<I, S>): (evaluate: LazyArg<S>) => Layer<I>;
     /**
-     * Lazily constructs a layer that provides a single service.
+     * Constructs a layer lazily that provides a single service.
      *
      * **When to use**
      *
-     * Use `sync` when the service can be created synchronously but should be
+     * Use when the service can be created synchronously but should be
      * deferred until the layer is built. Use `succeed` when the service value is
      * already available.
      *
@@ -931,11 +1030,11 @@ export declare const sync: {
     <I, S>(service: Context.Key<I, S>, evaluate: LazyArg<Types.NoInfer<S>>): Layer<I>;
 };
 /**
- * Lazily constructs a layer that provides all services in a `Context`.
+ * Constructs a layer lazily that provides all services in a `Context`.
  *
  * **When to use**
  *
- * Use `syncContext` when multiple services can be created synchronously and
+ * Use when multiple services can be created synchronously and
  * should be deferred until the layer is built. Use `sync` when you only need to
  * provide one service.
  *
@@ -972,7 +1071,7 @@ export declare const syncContext: <A>(evaluate: LazyArg<Context.Context<A>>) =>
  *
  * **When to use**
  *
- * Use `effect` when constructing the service requires effects, dependencies, or
+ * Use when constructing the service requires effects, dependencies, or
  * scoped resource acquisition. Use `effectContext` when the effect produces
  * multiple services in a `Context`, and `effectDiscard` when construction work
  * should provide no services.
@@ -1011,7 +1110,7 @@ export declare const effect: {
      *
      * **When to use**
      *
-     * Use `effect` when constructing the service requires effects, dependencies, or
+     * Use when constructing the service requires effects, dependencies, or
      * scoped resource acquisition. Use `effectContext` when the effect produces
      * multiple services in a `Context`, and `effectDiscard` when construction work
      * should provide no services.
@@ -1050,7 +1149,7 @@ export declare const effect: {
      *
      * **When to use**
      *
-     * Use `effect` when constructing the service requires effects, dependencies, or
+     * Use when constructing the service requires effects, dependencies, or
      * scoped resource acquisition. Use `effectContext` when the effect produces
      * multiple services in a `Context`, and `effectDiscard` when construction work
      * should provide no services.
@@ -1090,7 +1189,7 @@ export declare const effect: {
  *
  * **When to use**
  *
- * Use `effectContext` when effectful construction needs to provide multiple
+ * Use when effectful construction needs to provide multiple
  * services at once. Use `effect` when the effect produces one service value.
  *
  * **Details**
@@ -1128,7 +1227,7 @@ export declare const effectContext: <A, E, R>(effect: Effect<Context.Context<A>,
  *
  * **When to use**
  *
- * This is useful when you want to run an Effect for its side effects during
+ * Use when 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.
  *
  * **Example** (Running an effect during layer construction)
@@ -1150,7 +1249,7 @@ export declare const effectContext: <A, E, R>(effect: Effect<Context.Context<A>,
  */
 export declare const effectDiscard: <X, E, R>(effect: Effect<X, E, R>) => Layer<never, E, Exclude<R, Scope.Scope>>;
 /**
- * Lazily constructs a layer using the specified factory.
+ * Constructs a layer lazily using the specified factory.
  *
  * **Details**
  *
@@ -1182,7 +1281,7 @@ export declare const suspend: <A, E, R>(evaluate: LazyArg<Layer<A, E, R>>) => La
  *
  * **When to use**
  *
- * Use this when you have an `Effect` that produces a `Layer` and you want to
+ * Use when you have an `Effect` that produces a `Layer` and you want to
  * use that layer directly.
  *
  * **Details**
@@ -1216,7 +1315,7 @@ export declare const unwrap: <A, E1, R1, E, R>(self: Effect<Layer<A, E1, R1>, E,
  *
  * **When to use**
  *
- * Use this when you need to combine multiple independent layers.
+ * Use when you need to combine multiple independent layers.
  *
  * **Details**
  *
@@ -1261,7 +1360,7 @@ export declare const mergeAll: <Layers extends [Layer<never, any, any>, ...Array
  *
  * **When to use**
  *
- * Use `merge` when composing from an existing layer in a pipeline. Use
+ * Use when composing from an existing layer in a pipeline. Use
  * `mergeAll` when you already have all layers as separate arguments.
  *
  * **Details**
@@ -1305,7 +1404,7 @@ export declare const merge: {
      *
      * **When to use**
      *
-     * Use `merge` when composing from an existing layer in a pipeline. Use
+     * Use when composing from an existing layer in a pipeline. Use
      * `mergeAll` when you already have all layers as separate arguments.
      *
      * **Details**
@@ -1349,7 +1448,7 @@ export declare const merge: {
      *
      * **When to use**
      *
-     * Use `merge` when composing from an existing layer in a pipeline. Use
+     * Use when composing from an existing layer in a pipeline. Use
      * `mergeAll` when you already have all layers as separate arguments.
      *
      * **Details**
@@ -1393,7 +1492,7 @@ export declare const merge: {
      *
      * **When to use**
      *
-     * Use `merge` when composing from an existing layer in a pipeline. Use
+     * Use when composing from an existing layer in a pipeline. Use
      * `mergeAll` when you already have all layers as separate arguments.
      *
      * **Details**
@@ -1437,7 +1536,7 @@ export declare const merge: {
      *
      * **When to use**
      *
-     * Use `merge` when composing from an existing layer in a pipeline. Use
+     * Use when composing from an existing layer in a pipeline. Use
      * `mergeAll` when you already have all layers as separate arguments.
      *
      * **Details**
@@ -1482,7 +1581,7 @@ export declare const merge: {
  *
  * **When to use**
  *
- * Use `provide` when the dependency layer is an implementation detail of the
+ * Use when the dependency layer is an implementation detail of the
  * layer being built and should not be exposed to callers. Use `provideMerge`
  * when callers should also receive the dependency services.
  *
@@ -1562,7 +1661,7 @@ export declare const provide: {
      *
      * **When to use**
      *
-     * Use `provide` when the dependency layer is an implementation detail of the
+     * Use when the dependency layer is an implementation detail of the
      * layer being built and should not be exposed to callers. Use `provideMerge`
      * when callers should also receive the dependency services.
      *
@@ -1642,7 +1741,7 @@ export declare const provide: {
      *
      * **When to use**
      *
-     * Use `provide` when the dependency layer is an implementation detail of the
+     * Use when the dependency layer is an implementation detail of the
      * layer being built and should not be exposed to callers. Use `provideMerge`
      * when callers should also receive the dependency services.
      *
@@ -1722,7 +1821,7 @@ export declare const provide: {
      *
      * **When to use**
      *
-     * Use `provide` when the dependency layer is an implementation detail of the
+     * Use when the dependency layer is an implementation detail of the
      * layer being built and should not be exposed to callers. Use `provideMerge`
      * when callers should also receive the dependency services.
      *
@@ -1802,7 +1901,7 @@ export declare const provide: {
      *
      * **When to use**
      *
-     * Use `provide` when the dependency layer is an implementation detail of the
+     * Use when the dependency layer is an implementation detail of the
      * layer being built and should not be exposed to callers. Use `provideMerge`
      * when callers should also receive the dependency services.
      *
@@ -1883,7 +1982,7 @@ export declare const provide: {
  *
  * **When to use**
  *
- * Use this when callers need access to both the service being built and the
+ * Use when callers need access to both the service being built and the
  * dependency used to build it, such as a health check that needs both a
  * repository and its database. Prefer `provide` when the dependency should stay
  * private.
@@ -1965,7 +2064,7 @@ export declare const provideMerge: {
      *
      * **When to use**
      *
-     * Use this when callers need access to both the service being built and the
+     * Use when callers need access to both the service being built and the
      * dependency used to build it, such as a health check that needs both a
      * repository and its database. Prefer `provide` when the dependency should stay
      * private.
@@ -2047,7 +2146,7 @@ export declare const provideMerge: {
      *
      * **When to use**
      *
-     * Use this when callers need access to both the service being built and the
+     * Use when callers need access to both the service being built and the
      * dependency used to build it, such as a health check that needs both a
      * repository and its database. Prefer `provide` when the dependency should stay
      * private.
@@ -2129,7 +2228,7 @@ export declare const provideMerge: {
      *
      * **When to use**
      *
-     * Use this when callers need access to both the service being built and the
+     * Use when callers need access to both the service being built and the
      * dependency used to build it, such as a health check that needs both a
      * repository and its database. Prefer `provide` when the dependency should stay
      * private.
@@ -2211,7 +2310,7 @@ export declare const provideMerge: {
      *
      * **When to use**
      *
-     * Use this when callers need access to both the service being built and the
+     * Use when callers need access to both the service being built and the
      * dependency used to build it, such as a health check that needs both a
      * repository and its database. Prefer `provide` when the dependency should stay
      * private.
@@ -2508,11 +2607,20 @@ export declare const flatMap: {
 /**
  * Performs the specified effect if this layer succeeds.
  *
+ * **When to use**
+ *
+ * Use to run an effectful observation after a layer has been built
+ * successfully, such as logging or metrics, without changing the services the
+ * layer provides.
+ *
  * **Details**
  *
  * The callback receives the services produced by this layer. Its result is
  * discarded, and the original layer output is preserved.
  *
+ * @see {@link tapError} for running an effect when layer construction fails with a typed error
+ * @see {@link tapCause} for running an effect when layer construction fails with any cause
+ *
  * @category sequencing
  * @since 2.0.0
  */
@@ -2520,11 +2628,20 @@ export declare const tap: {
     /**
      * Performs the specified effect if this layer succeeds.
      *
+     * **When to use**
+     *
+     * Use to run an effectful observation after a layer has been built
+     * successfully, such as logging or metrics, without changing the services the
+     * layer provides.
+     *
      * **Details**
      *
      * The callback receives the services produced by this layer. Its result is
      * discarded, and the original layer output is preserved.
      *
+     * @see {@link tapError} for running an effect when layer construction fails with a typed error
+     * @see {@link tapCause} for running an effect when layer construction fails with any cause
+     *
      * @category sequencing
      * @since 2.0.0
      */
@@ -2532,11 +2649,20 @@ export declare const tap: {
     /**
      * Performs the specified effect if this layer succeeds.
      *
+     * **When to use**
+     *
+     * Use to run an effectful observation after a layer has been built
+     * successfully, such as logging or metrics, without changing the services the
+     * layer provides.
+     *
      * **Details**
      *
      * The callback receives the services produced by this layer. Its result is
      * discarded, and the original layer output is preserved.
      *
+     * @see {@link tapError} for running an effect when layer construction fails with a typed error
+     * @see {@link tapCause} for running an effect when layer construction fails with any cause
+     *
      * @category sequencing
      * @since 2.0.0
      */
@@ -2545,12 +2671,20 @@ export declare const tap: {
 /**
  * Performs the specified effect if this layer fails.
  *
+ * **When to use**
+ *
+ * Use to run logging, metrics, or other effects when layer construction fails
+ * while preserving the original typed error.
+ *
  * **Details**
  *
  * The callback receives the typed error. If the callback succeeds, the layer
  * still fails with the original error; if the callback fails, that failure is
  * added to the layer's error type.
  *
+ * @see {@link tap} for running an effect when layer construction succeeds
+ * @see {@link tapCause} for inspecting the full failure cause, including defects and interruption
+ *
  * @category sequencing
  * @since 2.0.0
  */
@@ -2558,12 +2692,20 @@ export declare const tapError: {
     /**
      * Performs the specified effect if this layer fails.
      *
+     * **When to use**
+     *
+     * Use to run logging, metrics, or other effects when layer construction fails
+     * while preserving the original typed error.
+     *
      * **Details**
      *
      * The callback receives the typed error. If the callback succeeds, the layer
      * still fails with the original error; if the callback fails, that failure is
      * added to the layer's error type.
      *
+     * @see {@link tap} for running an effect when layer construction succeeds
+     * @see {@link tapCause} for inspecting the full failure cause, including defects and interruption
+     *
      * @category sequencing
      * @since 2.0.0
      */
@@ -2571,12 +2713,20 @@ export declare const tapError: {
     /**
      * Performs the specified effect if this layer fails.
      *
+     * **When to use**
+     *
+     * Use to run logging, metrics, or other effects when layer construction fails
+     * while preserving the original typed error.
+     *
      * **Details**
      *
      * The callback receives the typed error. If the callback succeeds, the layer
      * still fails with the original error; if the callback fails, that failure is
      * added to the layer's error type.
      *
+     * @see {@link tap} for running an effect when layer construction succeeds
+     * @see {@link tapCause} for inspecting the full failure cause, including defects and interruption
+     *
      * @category sequencing
      * @since 2.0.0
      */
@@ -2585,6 +2735,11 @@ export declare const tapError: {
 /**
  * Performs the specified effect when this layer fails with any cause.
  *
+ * **When to use**
+ *
+ * Use to run diagnostics or reporting when layer construction fails and the
+ * full `Cause` is needed.
+ *
  * **Details**
  *
  * The callback receives the layer's `Cause`, so it can inspect typed errors,
@@ -2592,6 +2747,9 @@ export declare const tapError: {
  * fails again with the original cause; if the callback fails, that failure is
  * added to the layer's error type.
  *
+ * @see {@link tapError} for observing only typed layer construction errors
+ * @see {@link catchCause} for recovering from a layer construction failure by switching to another layer
+ *
  * @category sequencing
  * @since 4.0.0
  */
@@ -2599,6 +2757,11 @@ export declare const tapCause: {
     /**
      * Performs the specified effect when this layer fails with any cause.
      *
+     * **When to use**
+     *
+     * Use to run diagnostics or reporting when layer construction fails and the
+     * full `Cause` is needed.
+     *
      * **Details**
      *
      * The callback receives the layer's `Cause`, so it can inspect typed errors,
@@ -2606,6 +2769,9 @@ export declare const tapCause: {
      * fails again with the original cause; if the callback fails, that failure is
      * added to the layer's error type.
      *
+     * @see {@link tapError} for observing only typed layer construction errors
+     * @see {@link catchCause} for recovering from a layer construction failure by switching to another layer
+     *
      * @category sequencing
      * @since 4.0.0
      */
@@ -2613,6 +2779,11 @@ export declare const tapCause: {
     /**
      * Performs the specified effect when this layer fails with any cause.
      *
+     * **When to use**
+     *
+     * Use to run diagnostics or reporting when layer construction fails and the
+     * full `Cause` is needed.
+     *
      * **Details**
      *
      * The callback receives the layer's `Cause`, so it can inspect typed errors,
@@ -2620,6 +2791,9 @@ export declare const tapCause: {
      * fails again with the original cause; if the callback fails, that failure is
      * added to the layer's error type.
      *
+     * @see {@link tapError} for observing only typed layer construction errors
+     * @see {@link catchCause} for recovering from a layer construction failure by switching to another layer
+     *
      * @category sequencing
      * @since 4.0.0
      */
@@ -2682,7 +2856,7 @@ export {
  *
  * **When to use**
  *
- * Use `catch` when every typed construction error should use the same recovery
+ * Use when every typed construction error should use the same recovery
  * path. Use `catchTag` to recover from specific tagged errors, and `catchCause`
  * when recovery needs the full failure cause.
  *
@@ -2698,7 +2872,7 @@ catch_ as catch };
  *
  * **When to use**
  *
- * Use `catchTag` when only some tagged construction errors should be recovered.
+ * Use when only some tagged construction errors should be recovered.
  * Use `catchCause` when recovery depends on defects, interruption, or other
  * cause information.
  *
@@ -2733,7 +2907,7 @@ export declare const catchTag: {
      *
      * **When to use**
      *
-     * Use `catchTag` when only some tagged construction errors should be recovered.
+     * Use when only some tagged construction errors should be recovered.
      * Use `catchCause` when recovery depends on defects, interruption, or other
      * cause information.
      *
@@ -2768,7 +2942,7 @@ export declare const catchTag: {
      *
      * **When to use**
      *
-     * Use `catchTag` when only some tagged construction errors should be recovered.
+     * Use when only some tagged construction errors should be recovered.
      * Use `catchCause` when recovery depends on defects, interruption, or other
      * cause information.
      *
@@ -2804,7 +2978,7 @@ export declare const catchTag: {
  *
  * **When to use**
  *
- * Use `catchCause` when recovery needs more than the typed error, such as
+ * Use when recovery needs more than the typed error, such as
  * defects or interruption information. Use `catchTag` when recovery only needs
  * to match specific tagged errors.
  *
@@ -2863,7 +3037,7 @@ export declare const catchCause: {
      *
      * **When to use**
      *
-     * Use `catchCause` when recovery needs more than the typed error, such as
+     * Use when recovery needs more than the typed error, such as
      * defects or interruption information. Use `catchTag` when recovery only needs
      * to match specific tagged errors.
      *
@@ -2922,7 +3096,7 @@ export declare const catchCause: {
      *
      * **When to use**
      *
-     * Use `catchCause` when recovery needs more than the typed error, such as
+     * Use when recovery needs more than the typed error, such as
      * defects or interruption information. Use `catchTag` when recovery only needs
      * to match specific tagged errors.
      *
@@ -2982,7 +3156,7 @@ export declare const catchCause: {
  *
  * **When to use**
  *
- * Use this to adapt or extend a service's behavior during the creation of a
+ * Use to adapt or extend a service's behavior during the creation of a
  * layer.
  *
  * **Details**
@@ -3001,7 +3175,7 @@ export declare const updateService: {
      *
      * **When to use**
      *
-     * Use this to adapt or extend a service's behavior during the creation of a
+     * Use to adapt or extend a service's behavior during the creation of a
      * layer.
      *
      * **Details**
@@ -3020,7 +3194,7 @@ export declare const updateService: {
      *
      * **When to use**
      *
-     * Use this to adapt or extend a service's behavior during the creation of a
+     * Use to adapt or extend a service's behavior during the creation of a
      * layer.
      *
      * **Details**
@@ -3040,7 +3214,7 @@ export declare const updateService: {
  *
  * **When to use**
  *
- * Use `fresh` when two parts of an application must receive separate instances
+ * Use when two parts of an application must receive separate instances
  * of a resource, such as two independent client sessions. Do not use it just to
  * work around confusing composition: by default, sharing the same layer value is
  * usually the desired behavior.
@@ -3120,7 +3294,7 @@ export declare const fresh: <A, E, R>(self: Layer<A, E, R>) => Layer<A, E, R>;
  *
  * **When to use**
  *
- * Use this when your entire application is a layer, such as an HTTP server.
+ * Use when your entire application is a layer, such as an HTTP server.
  *
  * **Details**
  *
@@ -3182,11 +3356,19 @@ export declare const launch: <RIn, E, ROut>(self: Layer<ROut, E, RIn>) => Effect
 /**
  * A utility type for creating partial mocks of services in testing.
  *
+ * **When to use**
+ *
+ * Use to type partial test service implementations where only exercised
+ * effectful members are stubbed.
+ *
  * **Details**
  *
- * This type makes Effect methods and Effect-returning functions optional,
- * while keeping non-Effect properties required. This allows you to provide
- * only the methods you need to test while leaving others unimplemented.
+ * This type makes `Effect`, `Stream`, and `Channel` values and functions
+ * returning them optional, while keeping non-effectful properties required.
+ * This allows you to provide only the methods you need to test while leaving
+ * others unimplemented.
+ *
+ * @see {@link mock} for creating a mock layer from a partial service implementation
  *
  * @category testing
  * @since 3.17.0
@@ -3467,6 +3649,20 @@ export declare const satisfiesServicesType: <RIn>() => <ROut, E, RIn2 extends RI
  * Represents options that can be used to control the behavior of spans created
  * for layers.
  *
+ * **When to use**
+ *
+ * Use to configure tracing metadata, stack trace capture, and `onEnd`
+ * finalization for spans created by `Layer.span` and `Layer.withSpan` during
+ * layer construction.
+ *
+ * **Details**
+ *
+ * Extends `Tracer.SpanOptions` with `onEnd`, which runs when the layer span
+ * ends as the layer scope closes.
+ *
+ * @see {@link span} for creating a layer span
+ * @see {@link withSpan} for wrapping layer construction in a span
+ *
  * @category models
  * @since 4.0.0
  */