effect 4.0.0-beta.73 → 4.0.0-beta.75

package/src/Layer.ts

@@ -965,9 +965,8 @@ export const buildWithScope: {
  *
  * **When to use**
  *
- * 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.
+ * Use when you need a `Layer` that provides a service from an already
+ * constructed implementation without effectful acquisition.
  *
  * **Example** (Creating a layer from a service implementation)
  *
@@ -995,9 +994,8 @@ export const succeed: {
    *
    * **When to use**
    *
-   * 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.
+   * Use when you need a `Layer` that provides a service from an already
+   * constructed implementation without effectful acquisition.
    *
    * **Example** (Creating a layer from a service implementation)
    *
@@ -1025,9 +1023,8 @@ export const succeed: {
    *
    * **When to use**
    *
-   * 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.
+   * Use when you need a `Layer` that provides a service from an already
+   * constructed implementation without effectful acquisition.
    *
    * **Example** (Creating a layer from a service implementation)
    *
@@ -1062,9 +1059,8 @@ export const succeed: {
  *
  * **When to use**
  *
- * 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.
+ * Use when you need a `Layer` built from an existing `Context`, including when
+ * you need to provide multiple services at once.
  *
  * **Details**
  *
@@ -1109,9 +1105,7 @@ export const succeedContext = <A>(context: Context.Context<A>): Layer<A> =>
  *
  * **When to use**
  *
- * 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`.
+ * Use as the no-op branch when conditionally composing layers.
  *
  * **Example** (Disabling optional lifecycle work)
  *
@@ -1137,9 +1131,8 @@ export const empty: Layer<never> = succeedContext(Context.empty())
  *
  * **When to use**
  *
- * 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.
+ * Use when you need a `Layer` that provides one service whose value is created
+ * synchronously, but creation should be deferred until the layer is built.
  *
  * **Details**
  *
@@ -1171,9 +1164,8 @@ export const sync: {
    *
    * **When to use**
    *
-   * 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.
+   * Use when you need a `Layer` that provides one service whose value is created
+   * synchronously, but creation should be deferred until the layer is built.
    *
    * **Details**
    *
@@ -1205,9 +1197,8 @@ export const sync: {
    *
    * **When to use**
    *
-   * 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.
+   * Use when you need a `Layer` that provides one service whose value is created
+   * synchronously, but creation should be deferred until the layer is built.
    *
    * **Details**
    *
@@ -1246,9 +1237,8 @@ export const sync: {
  *
  * **When to use**
  *
- * 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.
+ * Use when you need a `Layer` that creates multiple services synchronously but
+ * defers that work until the layer is built.
  *
  * **Details**
  *
@@ -1285,10 +1275,8 @@ export const syncContext = <A>(evaluate: LazyArg<Context.Context<A>>): Layer<A>
  *
  * **When to use**
  *
- * 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.
+ * Use when you need to construct a `Layer`-provided service with an `Effect`,
+ * dependencies, or scoped resource acquisition.
  *
  * **Details**
  *
@@ -1324,10 +1312,8 @@ export const effect: {
    *
    * **When to use**
    *
-   * 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.
+   * Use when you need to construct a `Layer`-provided service with an `Effect`,
+   * dependencies, or scoped resource acquisition.
    *
    * **Details**
    *
@@ -1365,10 +1351,8 @@ export const effect: {
    *
    * **When to use**
    *
-   * 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.
+   * Use when you need to construct a `Layer`-provided service with an `Effect`,
+   * dependencies, or scoped resource acquisition.
    *
    * **Details**
    *
@@ -1417,8 +1401,8 @@ const effectImpl = <I, S, E, R>(
  *
  * **When to use**
  *
- * Use when effectful construction needs to provide multiple
- * services at once. Use `effect` when the effect produces one service value.
+ * Use when you need a `Layer` that effectfully constructs a `Context` with
+ * multiple services.
  *
  * **Details**
  *
@@ -1458,8 +1442,8 @@ export const effectContext = <A, E, R>(
  *
  * **When to use**
  *
- * 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.
+ * Use when layer construction should run an Effect for its side effects while providing no
+ * services.
  *
  * **Example** (Running an effect during layer construction)
  *
@@ -1540,7 +1524,7 @@ export const suspend = <A, E, R>(evaluate: LazyArg<Layer<A, E, R>>): Layer<A, E,
  * const unwrappedLayer = Layer.unwrap(layerEffect)
  * ```
  *
- * @category utils
+ * @category converting
  * @since 4.0.0
  */
 export const unwrap = <A, E1, R1, E, R>(
@@ -1625,8 +1609,8 @@ export const mergeAll = <Layers extends [Layer<never, any, any>, ...Array<Layer<
  *
  * **When to use**
  *
- * Use when composing from an existing layer in a pipeline. Use
- * `mergeAll` when you already have all layers as separate arguments.
+ * Use to combine an existing `Layer` with another `Layer` or an array of
+ * layers while preserving pipeline style.
  *
  * **Details**
  *
@@ -1669,8 +1653,8 @@ export const merge: {
    *
    * **When to use**
    *
-   * Use when composing from an existing layer in a pipeline. Use
-   * `mergeAll` when you already have all layers as separate arguments.
+   * Use to combine an existing `Layer` with another `Layer` or an array of
+   * layers while preserving pipeline style.
    *
    * **Details**
    *
@@ -1713,8 +1697,8 @@ export const merge: {
    *
    * **When to use**
    *
-   * Use when composing from an existing layer in a pipeline. Use
-   * `mergeAll` when you already have all layers as separate arguments.
+   * Use to combine an existing `Layer` with another `Layer` or an array of
+   * layers while preserving pipeline style.
    *
    * **Details**
    *
@@ -1764,8 +1748,8 @@ export const merge: {
    *
    * **When to use**
    *
-   * Use when composing from an existing layer in a pipeline. Use
-   * `mergeAll` when you already have all layers as separate arguments.
+   * Use to combine an existing `Layer` with another `Layer` or an array of
+   * layers while preserving pipeline style.
    *
    * **Details**
    *
@@ -1808,8 +1792,8 @@ export const merge: {
    *
    * **When to use**
    *
-   * Use when composing from an existing layer in a pipeline. Use
-   * `mergeAll` when you already have all layers as separate arguments.
+   * Use to combine an existing `Layer` with another `Layer` or an array of
+   * layers while preserving pipeline style.
    *
    * **Details**
    *
@@ -1883,9 +1867,7 @@ const provideWith = (
  *
  * **When to use**
  *
- * 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.
+ * Use when you need to hide an implementation dependency layer from callers.
  *
  * **Details**
  *
@@ -1953,7 +1935,7 @@ const provideWith = (
  *
  * @see {@link provideMerge} for retaining the dependency services
  *
- * @category utils
+ * @category providing services
  * @since 2.0.0
  */
 export const provide: {
@@ -1963,9 +1945,7 @@ export const provide: {
    *
    * **When to use**
    *
-   * 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.
+   * Use when you need to hide an implementation dependency layer from callers.
    *
    * **Details**
    *
@@ -2033,7 +2013,7 @@ export const provide: {
    *
    * @see {@link provideMerge} for retaining the dependency services
    *
-   * @category utils
+   * @category providing services
    * @since 2.0.0
    */
   <RIn, E, ROut>(that: Layer<ROut, E, RIn>): <RIn2, E2, ROut2>(self: Layer<ROut2, E2, RIn2>) => Layer<ROut2, E | E2, RIn | Exclude<RIn2, ROut>>
@@ -2043,9 +2023,7 @@ export const provide: {
    *
    * **When to use**
    *
-   * 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.
+   * Use when you need to hide an implementation dependency layer from callers.
    *
    * **Details**
    *
@@ -2113,7 +2091,7 @@ export const provide: {
    *
    * @see {@link provideMerge} for retaining the dependency services
    *
-   * @category utils
+   * @category providing services
    * @since 2.0.0
    */
   <const Layers extends [Any, ...Array<Any>]>(that: Layers): <A, E, R>(
@@ -2130,9 +2108,7 @@ export const provide: {
    *
    * **When to use**
    *
-   * 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.
+   * Use when you need to hide an implementation dependency layer from callers.
    *
    * **Details**
    *
@@ -2200,7 +2176,7 @@ export const provide: {
    *
    * @see {@link provideMerge} for retaining the dependency services
    *
-   * @category utils
+   * @category providing services
    * @since 2.0.0
    */
   <RIn2, E2, ROut2, RIn, E, ROut>(self: Layer<ROut2, E2, RIn2>, that: Layer<ROut, E, RIn>): Layer<ROut2, E | E2, RIn | Exclude<RIn2, ROut>>
@@ -2210,9 +2186,7 @@ export const provide: {
    *
    * **When to use**
    *
-   * 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.
+   * Use when you need to hide an implementation dependency layer from callers.
    *
    * **Details**
    *
@@ -2280,7 +2254,7 @@ export const provide: {
    *
    * @see {@link provideMerge} for retaining the dependency services
    *
-   * @category utils
+   * @category providing services
    * @since 2.0.0
    */
   <A, E, R, const Layers extends [Any, ...Array<Any>]>(self: Layer<A, E, R>, that: Layers): Layer<
@@ -2300,10 +2274,12 @@ export const provide: {
  *
  * **When to use**
  *
- * 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.
+ * Use when you need to compose `Layer`s while keeping both the constructed
+ * service and the dependency used to build it available.
+ *
+ * **Details**
+ *
+ * Prefer {@link provide} when the dependency should stay private.
  *
  * **Example** (Providing dependencies while retaining services)
  *
@@ -2372,7 +2348,7 @@ export const provide: {
  *
  * @see {@link provide} for keeping dependency services private
  *
- * @category utils
+ * @category providing services
  * @since 2.0.0
  */
 export const provideMerge: {
@@ -2382,10 +2358,12 @@ export const provideMerge: {
    *
    * **When to use**
    *
-   * 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.
+   * Use when you need to compose `Layer`s while keeping both the constructed
+   * service and the dependency used to build it available.
+   *
+   * **Details**
+   *
+   * Prefer {@link provide} when the dependency should stay private.
    *
    * **Example** (Providing dependencies while retaining services)
    *
@@ -2454,7 +2432,7 @@ export const provideMerge: {
    *
    * @see {@link provide} for keeping dependency services private
    *
-   * @category utils
+   * @category providing services
    * @since 2.0.0
    */
   <RIn, E, ROut>(that: Layer<ROut, E, RIn>): <RIn2, E2, ROut2>(self: Layer<ROut2, E2, RIn2>) => Layer<ROut | ROut2, E | E2, RIn | Exclude<RIn2, ROut>>
@@ -2464,10 +2442,12 @@ export const provideMerge: {
    *
    * **When to use**
    *
-   * 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.
+   * Use when you need to compose `Layer`s while keeping both the constructed
+   * service and the dependency used to build it available.
+   *
+   * **Details**
+   *
+   * Prefer {@link provide} when the dependency should stay private.
    *
    * **Example** (Providing dependencies while retaining services)
    *
@@ -2536,7 +2516,7 @@ export const provideMerge: {
    *
    * @see {@link provide} for keeping dependency services private
    *
-   * @category utils
+   * @category providing services
    * @since 2.0.0
    */
   <const Layers extends [Any, ...Array<Any>]>(that: Layers): <A, E, R>(
@@ -2553,10 +2533,12 @@ export const provideMerge: {
    *
    * **When to use**
    *
-   * 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.
+   * Use when you need to compose `Layer`s while keeping both the constructed
+   * service and the dependency used to build it available.
+   *
+   * **Details**
+   *
+   * Prefer {@link provide} when the dependency should stay private.
    *
    * **Example** (Providing dependencies while retaining services)
    *
@@ -2625,7 +2607,7 @@ export const provideMerge: {
    *
    * @see {@link provide} for keeping dependency services private
    *
-   * @category utils
+   * @category providing services
    * @since 2.0.0
    */
   <RIn2, E2, ROut2, RIn, E, ROut>(self: Layer<ROut2, E2, RIn2>, that: Layer<ROut, E, RIn>): Layer<ROut | ROut2, E | E2, RIn | Exclude<RIn2, ROut>>
@@ -2635,10 +2617,12 @@ export const provideMerge: {
    *
    * **When to use**
    *
-   * 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.
+   * Use when you need to compose `Layer`s while keeping both the constructed
+   * service and the dependency used to build it available.
+   *
+   * **Details**
+   *
+   * Prefer {@link provide} when the dependency should stay private.
    *
    * **Example** (Providing dependencies while retaining services)
    *
@@ -2707,7 +2691,7 @@ export const provideMerge: {
    *
    * @see {@link provide} for keeping dependency services private
    *
-   * @category utils
+   * @category providing services
    * @since 2.0.0
    */
   <A, E, R, const Layers extends [Any, ...Array<Any>]>(self: Layer<A, E, R>, that: Layers): Layer<
@@ -3262,9 +3246,8 @@ export {
    *
    * **When to use**
    *
-   * 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.
+   * Use when every typed `Layer` construction error should use the same
+   * recovery path.
    *
    * @see {@link catchTag} for recovering from specific tagged errors
    * @see {@link catchCause} for recovering with access to the full cause
@@ -3280,9 +3263,7 @@ export {
  *
  * **When to use**
  *
- * Use when only some tagged construction errors should be recovered.
- * Use `catchCause` when recovery depends on defects, interruption, or other
- * cause information.
+ * Use when only some tagged `Layer` construction errors should be recovered.
  *
  * **Example** (Recovering from tagged layer errors)
  *
@@ -3315,9 +3296,7 @@ export const catchTag: {
    *
    * **When to use**
    *
-   * Use when only some tagged construction errors should be recovered.
-   * Use `catchCause` when recovery depends on defects, interruption, or other
-   * cause information.
+   * Use when only some tagged `Layer` construction errors should be recovered.
    *
    * **Example** (Recovering from tagged layer errors)
    *
@@ -3361,9 +3340,7 @@ export const catchTag: {
    *
    * **When to use**
    *
-   * Use when only some tagged construction errors should be recovered.
-   * Use `catchCause` when recovery depends on defects, interruption, or other
-   * cause information.
+   * Use when only some tagged `Layer` construction errors should be recovered.
    *
    * **Example** (Recovering from tagged layer errors)
    *
@@ -3433,9 +3410,8 @@ export const catchTag: {
  *
  * **When to use**
  *
- * 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.
+ * Use when you need `Layer` recovery to inspect more than the typed error,
+ * such as defects or interruption information.
  *
  * **Details**
  *
@@ -3492,9 +3468,8 @@ export const catchCause: {
    *
    * **When to use**
    *
-   * 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.
+   * Use when you need `Layer` recovery to inspect more than the typed error,
+   * such as defects or interruption information.
    *
    * **Details**
    *
@@ -3551,9 +3526,8 @@ export const catchCause: {
    *
    * **When to use**
    *
-   * 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.
+   * Use when you need `Layer` recovery to inspect more than the typed error,
+   * such as defects or interruption information.
    *
    * **Details**
    *
@@ -3634,7 +3608,7 @@ export const catchCause: {
  * transformation function `f`, and replaces the old service with the
  * transformed one.
  *
- * @category utils
+ * @category providing services
  * @since 3.13.0
  */
 export const updateService: {
@@ -3653,7 +3627,7 @@ export const updateService: {
    * transformation function `f`, and replaces the old service with the
    * transformed one.
    *
-   * @category utils
+   * @category providing services
    * @since 3.13.0
    */
   <I, A>(service: Context.Key<I, A>, f: (a: Types.NoInfer<A>) => A): <A1, E1, R1>(layer: Layer<A1, E1, R1>) => Layer<A1, E1, I | R1>
@@ -3672,7 +3646,7 @@ export const updateService: {
    * transformation function `f`, and replaces the old service with the
    * transformed one.
    *
-   * @category utils
+   * @category providing services
    * @since 3.13.0
    */
   <A1, E1, R1, I, A>(
@@ -3694,10 +3668,13 @@ export const updateService: {
  *
  * **When to use**
  *
- * 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.
+ * Use when you need two parts of an application to receive separate instances
+ * of a resource, such as two independent client sessions.
+ *
+ * **Gotchas**
+ *
+ * Do not use it just to work around confusing composition. By default, sharing
+ * the same layer value is usually the desired behavior.
  *
  * **Example** (Creating non-shared layer instances)
  *
@@ -3765,7 +3742,7 @@ export const updateService: {
  * // same Counter: false
  * ```
  *
- * @category utils
+ * @category layers
  * @since 2.0.0
  */
 export const fresh = <A, E, R>(self: Layer<A, E, R>): Layer<A, E, R> =>
@@ -3776,7 +3753,8 @@ export const fresh = <A, E, R>(self: Layer<A, E, R>): Layer<A, E, R> =>
  *
  * **When to use**
  *
- * Use when your entire application is a layer, such as an HTTP server.
+ * Use when you model your entire application as a layer, such as an HTTP
+ * server.
  *
  * **Details**
  *
@@ -4224,7 +4202,7 @@ export const satisfiesServicesType =
  * @see {@link span} for creating a layer span
  * @see {@link withSpan} for wrapping layer construction in a span
  *
- * @category models
+ * @category options
  * @since 4.0.0
  */
 export interface SpanOptions extends Tracer.SpanOptions {