effect 4.0.0-beta.74 → 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)
  *
@@ -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**
  *
@@ -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**
    *
@@ -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**
    *
@@ -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**
    *
@@ -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**
    *
@@ -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)
  *
@@ -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)
    *
@@ -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)
    *
@@ -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)
    *
@@ -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)
    *
@@ -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**
    *
@@ -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)
  *
@@ -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**
  *

package/src/Logger.ts

@@ -245,8 +245,8 @@ export const CurrentLoggers: Context.Reference<ReadonlySet<Logger<unknown, any>>
  *
  * **When to use**
  *
- * Use to keep stdout reserved for protocol messages or data output while still
- * allowing Effect runtime logs to be emitted.
+ * Use to route built-in logger output to stderr while keeping stdout reserved
+ * for protocol messages or data output.
  *
  * **Details**
  *
@@ -267,8 +267,8 @@ export const LogToStderr: Context.Reference<boolean> = effect.LogToStderr
  *
  * **When to use**
  *
- * Use when this allows you to modify, enhance, or completely change the output format
- * of an existing logger without recreating the entire logging logic.
+ * Use when an existing logger's output should be transformed without recreating the
+ * logging logic.
  *
  * **Example** (Transforming logger output)
  *
@@ -304,8 +304,8 @@ export const map = dual<
    *
    * **When to use**
    *
-   * Use when this allows you to modify, enhance, or completely change the output format
-   * of an existing logger without recreating the entire logging logic.
+   * Use when an existing logger's output should be transformed without recreating the
+   * logging logic.
    *
    * **Example** (Transforming logger output)
    *
@@ -343,8 +343,8 @@ export const map = dual<
    *
    * **When to use**
    *
-   * Use when this allows you to modify, enhance, or completely change the output format
-   * of an existing logger without recreating the entire logging logic.
+   * Use when an existing logger's output should be transformed without recreating the
+   * logging logic.
    *
    * **Example** (Transforming logger output)
    *
@@ -383,8 +383,8 @@ export const map = dual<
  *
  * **When to use**
  *
- * Use when this is useful for taking any logger that produces string or object output
- * and routing it to the console for development or debugging purposes.
+ * Use when a logger's string or object output should be routed to `console.log` for
+ * development or debugging.
  *
  * **Example** (Writing logger output with console.log)
  *
@@ -420,8 +420,8 @@ export const withConsoleLog = <Message, Output>(
  *
  * **When to use**
  *
- * Use when this is particularly useful for error logging where you want to ensure
- * log messages appear in the error stream (stderr) rather than standard output.
+ * Use when logger output should be routed to `console.error`, such as error logs that
+ * should appear on stderr instead of stdout.
  *
  * **Example** (Writing logger output with console.error)
  *
@@ -460,12 +460,9 @@ export const withConsoleError = <Message, Output>(
  * Will use the appropriate console method (i.e. `console.log`, `console.error`,
  * etc.) based upon the current `LogLevel`.
  *
- * - `Debug` -> `console.debug`
- * - `Info` -> `console.info`
- * - `Trace` -> `console.trace`
- * - `Warn` -> `console.warn`
- * - `Error` and `Fatal` -> `console.error`
- * - Others -> `console.log`
+ * `Debug` uses `console.debug`, `Info` uses `console.info`, `Trace` uses
+ * `console.trace`, `Warn` uses `console.warn`, `Error` and `Fatal` use
+ * `console.error`, and all other levels use `console.log`.
  *
  * **Example** (Writing logs with level-based console methods)
  *

package/src/Match.ts

@@ -1678,7 +1678,7 @@ export {
    *
    * **When to use**
    *
-   * Use when a match branch should handle only the literal `null` value.
+   * Use to handle only the `null` literal in a match branch.
    *
    * **Details**
    *
@@ -1926,7 +1926,7 @@ export const instanceOf: <A extends abstract new(...args: any) => any>(
  *
  * **When to use**
  *
- * Use when constructor matching needs the unsafe refinement type.
+ * Use when you need constructor matching to use the unsafe refinement type.
  *
  * **Details**
  *