effect 4.0.0-beta.70 → 4.0.0-beta.71

package/src/Layer.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
  */
@@ -55,6 +68,12 @@ 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
@@ -118,11 +137,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
  */
@@ -136,6 +166,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
  */
@@ -145,6 +183,14 @@ export type Services<T extends Any> = T extends infer L
 /**
  * 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
  */
@@ -152,6 +198,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
  */
@@ -459,6 +513,15 @@ 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.
  *
+ * **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
  */
@@ -499,6 +562,15 @@ 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.
  *
+ * **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
  */
@@ -507,10 +579,17 @@ export const forkMemoMap = (parent: MemoMap): Effect<MemoMap> => internalEffect.
 /**
  * A service reference 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
@@ -866,7 +945,7 @@ export 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.
  *
@@ -896,7 +975,7 @@ export 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.
    *
@@ -926,7 +1005,7 @@ export 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.
    *
@@ -963,7 +1042,7 @@ export 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.
  *
@@ -1010,7 +1089,7 @@ export 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`.
  *
@@ -1038,7 +1117,7 @@ export const empty: Layer<never> = succeedContext(Context.empty())
  *
  * **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.
  *
@@ -1072,7 +1151,7 @@ export const sync: {
    *
    * **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.
    *
@@ -1106,7 +1185,7 @@ export const sync: {
    *
    * **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.
    *
@@ -1147,7 +1226,7 @@ export const sync: {
  *
  * **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.
  *
@@ -1186,7 +1265,7 @@ export const syncContext = <A>(evaluate: LazyArg<Context.Context<A>>): Layer<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.
@@ -1225,7 +1304,7 @@ export 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.
@@ -1266,7 +1345,7 @@ export 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.
@@ -1318,7 +1397,7 @@ const effectImpl = <I, S, E, R>(
  *
  * **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**
@@ -1359,7 +1438,7 @@ export const effectContext = <A, E, R>(
  *
  * **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)
@@ -1417,7 +1496,7 @@ export const suspend = <A, E, R>(evaluate: LazyArg<Layer<A, E, R>>): Layer<A, E,
  *
  * **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**
@@ -1474,7 +1553,7 @@ const mergeAllEffect = <Layers extends [Layer<never, any, any>, ...Array<Layer<n
  *
  * **When to use**
  *
- * Use this when you need to combine multiple independent layers.
+ * Use when you need to combine multiple independent layers.
  *
  * **Details**
  *
@@ -1526,7 +1605,7 @@ export const mergeAll = <Layers extends [Layer<never, any, any>, ...Array<Layer<
  *
  * **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**
@@ -1570,7 +1649,7 @@ export 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**
@@ -1614,7 +1693,7 @@ export 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**
@@ -1665,7 +1744,7 @@ export 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**
@@ -1709,7 +1788,7 @@ export 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**
@@ -1784,7 +1863,7 @@ const provideWith = (
  *
  * **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.
  *
@@ -1864,7 +1943,7 @@ export 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.
    *
@@ -1944,7 +2023,7 @@ export 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.
    *
@@ -2031,7 +2110,7 @@ export 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.
    *
@@ -2111,7 +2190,7 @@ export 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.
    *
@@ -2201,7 +2280,7 @@ export 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.
@@ -2283,7 +2362,7 @@ export 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.
@@ -2365,7 +2444,7 @@ export 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.
@@ -2454,7 +2533,7 @@ export 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.
@@ -2536,7 +2615,7 @@ export 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.
@@ -2860,11 +2939,20 @@ export 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
  */
@@ -2872,11 +2960,20 @@ export 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
    */
@@ -2884,11 +2981,20 @@ export 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
    */
@@ -2910,12 +3016,20 @@ export 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
  */
@@ -2923,12 +3037,20 @@ export 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
    */
@@ -2936,12 +3058,20 @@ export 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
    */
@@ -2960,6 +3090,11 @@ export 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,
@@ -2967,6 +3102,9 @@ export 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
  */
@@ -2974,6 +3112,11 @@ export 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,
@@ -2981,6 +3124,9 @@ export 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
    */
@@ -2988,6 +3134,11 @@ export 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,
@@ -2995,6 +3146,9 @@ export 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
    */
@@ -3088,7 +3242,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.
    *
@@ -3106,7 +3260,7 @@ export {
  *
  * **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.
  *
@@ -3141,7 +3295,7 @@ export 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.
    *
@@ -3187,7 +3341,7 @@ export 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.
    *
@@ -3259,7 +3413,7 @@ export 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.
  *
@@ -3318,7 +3472,7 @@ export 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.
    *
@@ -3377,7 +3531,7 @@ export 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.
    *
@@ -3450,7 +3604,7 @@ export 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**
@@ -3469,7 +3623,7 @@ export 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**
@@ -3488,7 +3642,7 @@ export 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**
@@ -3520,7 +3674,7 @@ export 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.
@@ -3602,7 +3756,7 @@ export 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**
  *
@@ -3666,11 +3820,19 @@ export const launch = <RIn, E, ROut>(self: Layer<ROut, E, RIn>): Effect<never, E
 /**
  * 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
@@ -4028,6 +4190,20 @@ export const satisfiesServicesType =
  * 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
  */