effect 4.0.0-beta.71 → 4.0.0-beta.72

package/src/Layer.ts

@@ -479,7 +479,7 @@ class MemoMapImpl implements MemoMap {
 }
 
 /**
- * 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)
  *
@@ -510,8 +510,9 @@ class MemoMapImpl implements MemoMap {
 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.
+ * 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**
  *
@@ -528,7 +529,7 @@ export const makeMemoMapUnsafe = (): MemoMap => new MemoMapImpl()
 export const forkMemoMapUnsafe = (parent: MemoMap): MemoMap => new MemoMapImpl(parent)
 
 /**
- * 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)
  *
@@ -559,8 +560,9 @@ export const forkMemoMapUnsafe = (parent: MemoMap): MemoMap => new MemoMapImpl(p
 export const makeMemoMap: Effect<MemoMap> = internalEffect.sync(makeMemoMapUnsafe)
 
 /**
- * Constructs a child `MemoMap` that can reuse layers already memoized in the
- * parent while isolating any new layer allocations to the child map.
+ * 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**
  *
@@ -577,7 +579,7 @@ export const makeMemoMap: Effect<MemoMap> = internalEffect.sync(makeMemoMapUnsaf
 export const forkMemoMap = (parent: MemoMap): Effect<MemoMap> => internalEffect.sync(() => forkMemoMapUnsafe(parent))
 
 /**
- * A service reference for the current `MemoMap` used in layer construction.
+ * Context service for the current `MemoMap` used in layer construction.
  *
  * **When to use**
  *
@@ -802,11 +804,17 @@ export const build = <RIn, E, ROut>(
   )
 
 /**
- * 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)
  *
@@ -844,11 +852,17 @@ export const build = <RIn, E, ROut>(
  */
 export 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)
    *
@@ -886,11 +900,17 @@ export 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)
    *
@@ -1113,7 +1133,7 @@ export const succeedContext = <A>(context: Context.Context<A>): Layer<A> =>
 export const empty: Layer<never> = succeedContext(Context.empty())
 
 /**
- * Lazily constructs a layer that provides a single service.
+ * Constructs a layer lazily that provides a single service.
  *
  * **When to use**
  *
@@ -1147,7 +1167,7 @@ export const empty: Layer<never> = succeedContext(Context.empty())
  */
 export const sync: {
   /**
-   * Lazily constructs a layer that provides a single service.
+   * Constructs a layer lazily that provides a single service.
    *
    * **When to use**
    *
@@ -1181,7 +1201,7 @@ export 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**
    *
@@ -1222,7 +1242,7 @@ export const sync: {
 } as any
 
 /**
- * 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**
  *
@@ -1462,7 +1482,7 @@ export const effectDiscard = <X, E, R>(effect: Effect<X, E, R>): Layer<never, E,
   effectContext(internalEffect.as(effect, Context.empty()))
 
 /**
- * Lazily constructs a layer using the specified factory.
+ * Constructs a layer lazily using the specified factory.
  *
  * **Details**
  *

package/src/LayerMap.ts

@@ -115,8 +115,7 @@ export interface LayerMap<in out K, in out I, in out E = never> {
 }
 
 /**
- * A `LayerMap` allows you to create a map of Layer's that can be used to
- * dynamically access resources based on a key.
+ * Creates a `LayerMap` that dynamically provides resources based on a key.
  *
  * **Example** (Creating a layer map)
  *

package/src/LogLevel.ts

@@ -111,7 +111,7 @@ export type LogLevel = "All" | "Fatal" | "Error" | "Warn" | "Info" | "Debug" | "
 export type Severity = "Fatal" | "Error" | "Warn" | "Info" | "Debug" | "Trace"
 
 /**
- * All `LogLevel` values in order from `All` through the concrete severities to
+ * Returns all `LogLevel` values in order from `All` through the concrete severities to
  * `None`.
  *
  * **When to use**
@@ -138,7 +138,7 @@ export type Severity = "Fatal" | "Error" | "Warn" | "Info" | "Debug" | "Trace"
 export const values: ReadonlyArray<LogLevel> = ["All", "Fatal", "Error", "Warn", "Info", "Debug", "Trace", "None"]
 
 /**
- * An `Order` instance for `LogLevel` that defines the severity ordering.
+ * Order instance for `LogLevel` that defines the severity ordering.
  *
  * **When to use**
  *
@@ -166,7 +166,7 @@ export const values: ReadonlyArray<LogLevel> = ["All", "Fatal", "Error", "Warn",
 export const Order: Ord.Order<LogLevel> = effect.LogLevelOrder
 
 /**
- * An `Equivalence` instance for log levels using strict equality (`===`).
+ * Equivalence instance for log levels using strict equality (`===`).
  *
  * **When to use**
  *

package/src/Logger.ts

@@ -853,7 +853,7 @@ export const formatStructured: Logger<unknown, {
 export const formatJson = map(formatStructured, Formatter.formatJson)
 
 /**
- * Creates, in a scope, a logger that batches the output of another logger.
+ * Creates a scoped logger that batches the output of another logger.
  *
  * **Details**
  *
@@ -907,7 +907,7 @@ export const formatJson = map(formatStructured, Formatter.formatJson)
  */
 export const batched = dual<
   /**
-   * Creates, in a scope, a logger that batches the output of another logger.
+   * Creates a scoped logger that batches the output of another logger.
    *
    * **Details**
    *
@@ -968,7 +968,7 @@ export const batched = dual<
     self: Logger<Message, Output>
   ) => Effect.Effect<Logger<Message, void>, never, Scope.Scope>,
   /**
-   * Creates, in a scope, a logger that batches the output of another logger.
+   * Creates a scoped logger that batches the output of another logger.
    *
    * **Details**
    *
@@ -1404,7 +1404,7 @@ export const layer = <
   )
 
 /**
- * Creates, in a scope, a logger that writes string logger output to a file.
+ * Creates a scoped logger that writes string logger output to a file.
  *
  * **Details**
  *
@@ -1503,7 +1503,7 @@ export const layer = <
  */
 export const toFile = dual<
   /**
-   * Creates, in a scope, a logger that writes string logger output to a file.
+   * Creates a scoped logger that writes string logger output to a file.
    *
    * **Details**
    *
@@ -1611,7 +1611,7 @@ export const toFile = dual<
     self: Logger<Message, string>
   ) => Effect.Effect<Logger<Message, void>, PlatformError, Scope.Scope | FileSystem.FileSystem>,
   /**
-   * Creates, in a scope, a logger that writes string logger output to a file.
+   * Creates a scoped logger that writes string logger output to a file.
    *
    * **Details**
    *

package/src/ManagedRuntime.ts

@@ -51,7 +51,7 @@ import type { Mutable } from "./Types.ts"
 const TypeId = "~effect/ManagedRuntime"
 
 /**
- * Checks if the provided argument is a `ManagedRuntime`.
+ * Checks whether the provided argument is a `ManagedRuntime`.
  *
  * **When to use**
  *

package/src/Match.ts

@@ -671,14 +671,9 @@ export const withReturnType: <Ret>() => <I, F, R, A, Pr, _>(
  *
  * **Details**
  *
- * This function enables pattern matching by checking whether a given value
- * satisfies a condition. It supports both direct value comparisons and
- * predicate functions. If the condition is met, the associated function is
- * executed.
- *
- * This function is useful when defining matchers that need to check for
- * specific values or apply logical conditions to determine a match. It works
- * well with structured objects and primitive types.
+ * Supports both direct value comparisons and predicate functions. If the
+ * pattern matches, the associated function is executed and the matched input is
+ * removed from the remaining cases tracked by the matcher.
  *
  * **Example** (Matching with Values and Predicates)
  *
@@ -916,15 +911,10 @@ export const discriminator: <D extends string>(
  *
  * **Details**
  *
- * This function is useful for working with discriminated unions where the
- * discriminant field follows a hierarchical or namespaced structure. It allows
- * you to match values based on whether the specified field starts with a given
- * prefix, making it easier to handle grouped cases.
- *
- * Instead of checking for exact matches, this function lets you match values
- * that share a common prefix. For example, if your discriminant field contains
- * hierarchical names like `"A"`, `"A.A"`, and `"B"`, you can match all values
- * starting with `"A"` using a single rule.
+ * Instead of checking for exact matches, this helper matches values that share
+ * a common prefix. For example, if the discriminant field contains hierarchical
+ * names like `"A"`, `"A.A"`, and `"B"`, a single `"A"` rule can match both
+ * `"A"` and `"A.A"`.
  *
  * **Example** (Matching discriminator prefixes)
  *
@@ -1087,15 +1077,17 @@ export const discriminatorsExhaustive: <D extends string>(
   internal.discriminatorsExhaustive
 
 /**
- * The `Match.tag` function allows pattern matching based on the `_tag` field in
- * a [Discriminated Union](https://www.typescriptlang.org/docs/handbook/typescript-in-5-minutes-func.html#discriminated-unions).
- * You can specify multiple tags to match within a single pattern.
+ * Matches discriminated union members by their `_tag` field.
+ *
+ * **When to use**
+ *
+ * Use to handle one or more `_tag` cases with the same matcher branch.
  *
  * **Details**
  *
- * The `Match.tag` function relies on the convention within the Effect ecosystem
- * of naming the tag field as `"_tag"`. Ensure that your discriminated unions
- * follow this naming convention for proper functionality.
+ * This helper follows the Effect convention that discriminated unions use
+ * `"_tag"` as their discriminator field. Use {@link discriminator} for a
+ * different discriminator field.
  *
  * **Example** (Matching a Discriminated Union by Tag)
  *
@@ -1298,7 +1290,7 @@ export const tagsExhaustive: <
   internal.tagsExhaustive
 
 /**
- * Excludes a specific value from matching while allowing all others.
+ * Creates a pattern that excludes a specific value while allowing all others.
  *
  * **When to use**
  *
@@ -1307,11 +1299,8 @@ export const tagsExhaustive: <
  *
  * **Details**
  *
- * This function is useful when you need to **handle all values except one or
- * more specific cases**. Instead of listing all possible matches manually, this
- * function simplifies the logic by allowing you to specify values to exclude.
- * Any excluded value will bypass the provided function and continue matching
- * through other cases.
+ * Any excluded value bypasses the provided function and continues matching
+ * through later cases.
  *
  * **Example** (Ignoring a Specific Value)
  *
@@ -1666,8 +1655,7 @@ export {
    *
    * **When to use**
    *
-   * Use when a matcher should handle only inputs whose value is exactly
-   * `undefined`.
+   * Use when a matcher should handle only inputs with no defined value.
    *
    * **Details**
    *
@@ -1934,7 +1922,7 @@ export const instanceOf: <A extends abstract new(...args: any) => any>(
 ) => SafeRefinement<InstanceType<A>, never> = internal.instanceOf
 
 /**
- * Unsafe variant of `instanceOf` that allows matching without type narrowing.
+ * Checks whether a value is an instance of a constructor without type-safe narrowing.
  *
  * **When to use**
  *
@@ -2026,7 +2014,7 @@ export const orElse: <RA, Ret, F extends (_: RA) => Ret>(
 
 // TODO(4.0): Rename to "orThrow"? Like Result.getOrThrow
 /**
- * Throws an error if no pattern matches.
+ * Returns a matcher that throws an error if no pattern matches.
  *
  * **When to use**
  *
@@ -2165,10 +2153,17 @@ export const option: <I, F, R, A, Pr, Ret>(
 ) => [Pr] extends [never] ? (input: I) => Option.Option<Unify<A>> : Option.Option<Unify<A>> = internal.option
 
 /**
- * The `Match.exhaustive` method finalizes the pattern matching process by
- * ensuring that all possible cases are accounted for. If any case is missing,
- * TypeScript will produce a type error. This is particularly useful when
- * working with unions, as it helps prevent unintended gaps in pattern matching.
+ * Completes a matcher that handles every remaining input case.
+ *
+ * **When to use**
+ *
+ * Use to require TypeScript to reject incomplete matcher definitions before the
+ * matcher is turned into a function.
+ *
+ * **Details**
+ *
+ * If any case is still unmatched, the matcher does not type-check as
+ * exhaustive.
  *
  * **Example** (Ensuring All Cases Are Covered)
  *

package/src/Metric.ts

@@ -1708,9 +1708,14 @@ export declare namespace Metric {
 export const CurrentMetricAttributesKey = "effect/Metric/CurrentMetricAttributes" as const
 
 /**
- * `Context.Reference` for metric attributes applied from the current Effect
+ * Context reference for metric attributes applied from the current Effect
  * context.
  *
+ * **When to use**
+ *
+ * Use to provide default attributes that should be merged into metric updates
+ * and reads in a scoped part of a program.
+ *
  * **Details**
  *
  * The default value is an empty attribute set. Metric reads and updates merge
@@ -1756,7 +1761,7 @@ export const CurrentMetricAttributes = Context.Reference<Metric.AttributeSet>(Cu
 const MetricRegistryKey = "~effect/observability/Metric/MetricRegistryKey"
 
 /**
- * `Context.Reference` for the metric registry in the current context.
+ * Context reference for the metric registry in the current context.
  *
  * **When to use**
  *
@@ -4386,9 +4391,14 @@ export const dump: Effect<string> = InternalEffect.flatMap(InternalEffect.contex
 })
 
 /**
- * Synchronously captures a snapshot of all registered metrics using the provided
+ * Captures a snapshot of all registered metrics synchronously using the provided
  * service context.
  *
+ * **When to use**
+ *
+ * Use to read metric snapshots from an explicit `Context` in low-level
+ * integrations, exporters, or debugging tools that already have the context.
+ *
  * **Details**
  *
  * This is the "unsafe" version that bypasses Effect's safety guarantees and requires
@@ -4519,8 +4529,7 @@ const attributesToString = (attributes: Metric.AttributeSet): string => {
 // Metric Boundaries
 
 /**
- * A helper method to create histogram bucket boundaries from an iterable set
- * of values.
+ * Creates histogram bucket boundaries from an iterable set of values.
  *
  * **Details**
  *
@@ -4583,7 +4592,7 @@ const attributesToString = (attributes: Metric.AttributeSet): string => {
  * })
  * ```
  *
- * @category Boundaries
+ * @category boundaries
  * @since 4.0.0
  */
 export const boundariesFromIterable = (iterable: Iterable<number>): ReadonlyArray<number> =>
@@ -4634,7 +4643,7 @@ export const boundariesFromIterable = (iterable: Iterable<number>): ReadonlyArra
  * })
  * ```
  *
- * @category Boundaries
+ * @category boundaries
  * @since 4.0.0
  */
 export const linearBoundaries = (options: {
@@ -4645,8 +4654,7 @@ export const linearBoundaries = (options: {
   boundariesFromIterable(Arr.makeBy(options.count - 1, (n) => options.start + n + options.width))
 
 /**
- * A helper method to create histogram bucket boundaries with exponentially
- * increasing values.
+ * Creates histogram bucket boundaries with exponentially increasing values.
  *
  * **Details**
  *
@@ -4695,7 +4703,7 @@ export const linearBoundaries = (options: {
  * })
  * ```
  *
- * @category Boundaries
+ * @category boundaries
  * @since 4.0.0
  */
 export const exponentialBoundaries = (options: {
@@ -4757,7 +4765,7 @@ const fiberFailures = counter("child_fiber_failures", {
  * })
  * ```
  *
- * @category Runtime Metrics
+ * @category metrics
  * @since 4.0.0
  */
 export const FiberRuntimeMetricsKey: "effect/observability/Metric/FiberRuntimeMetricsKey" =
@@ -4799,7 +4807,7 @@ export const FiberRuntimeMetricsKey: "effect/observability/Metric/FiberRuntimeMe
  * })
  * ```
  *
- * @category Runtime Metrics
+ * @category metrics
  * @since 4.0.0
  */
 export interface FiberRuntimeMetricsService {
@@ -4808,7 +4816,13 @@ export interface FiberRuntimeMetricsService {
 }
 
 /**
- * `Context.Reference` for the optional fiber runtime metrics service.
+ * Context reference for the optional service that records fiber runtime
+ * metrics.
+ *
+ * **When to use**
+ *
+ * Use to provide or inspect the service that receives fiber start and end
+ * notifications for automatic runtime metrics.
  *
  * **Details**
  *
@@ -4856,7 +4870,7 @@ export interface FiberRuntimeMetricsService {
  * })
  * ```
  *
- * @category Runtime Metrics
+ * @category runtime metrics
  * @since 4.0.0
  */
 export const FiberRuntimeMetrics = Context.Reference<FiberRuntimeMetricsService | undefined>(
@@ -4906,7 +4920,7 @@ export const FiberRuntimeMetrics = Context.Reference<FiberRuntimeMetricsService
  * })
  * ```
  *
- * @category Runtime Metrics
+ * @category metrics
  * @since 4.0.0
  */
 export const FiberRuntimeMetricsImpl: FiberRuntimeMetricsService = {
@@ -4925,7 +4939,7 @@ export const FiberRuntimeMetricsImpl: FiberRuntimeMetricsService = {
 }
 
 /**
- * A Layer that enables automatic collection of fiber runtime metrics across
+ * Layer that enables automatic collection of fiber runtime metrics across
  * an entire Effect application.
  *
  * **When to use**
@@ -5019,13 +5033,13 @@ export const FiberRuntimeMetricsImpl: FiberRuntimeMetricsService = {
  * )
  * ```
  *
- * @category Runtime Metrics
+ * @category metrics
  * @since 4.0.0
  */
 export const enableRuntimeMetricsLayer = Layer.succeed(FiberRuntimeMetrics)(FiberRuntimeMetricsImpl)
 
 /**
- * A Layer that disables automatic collection of fiber runtime metrics.
+ * Layer that disables automatic collection of fiber runtime metrics.
  *
  * **Example** (Disabling runtime metrics with a layer)
  *
@@ -5060,7 +5074,7 @@ export const enableRuntimeMetricsLayer = Layer.succeed(FiberRuntimeMetrics)(Fibe
  * })
  * ```
  *
- * @category Runtime Metrics
+ * @category metrics
  * @since 4.0.0
  */
 export const disableRuntimeMetricsLayer = Layer.succeed(FiberRuntimeMetrics)(undefined)
@@ -5144,7 +5158,7 @@ export const disableRuntimeMetricsLayer = Layer.succeed(FiberRuntimeMetrics)(und
  * )
  * ```
  *
- * @category Runtime Metrics
+ * @category metrics
  * @since 4.0.0
  */
 export const enableRuntimeMetrics: <A, E, R>(self: Effect<A, E, R>) => Effect<A, E, R> = InternalEffect.provideService(
@@ -5232,7 +5246,7 @@ export const enableRuntimeMetrics: <A, E, R>(self: Effect<A, E, R>) => Effect<A,
  * )
  * ```
  *
- * @category Runtime Metrics
+ * @category metrics
  * @since 4.0.0
  */
 export const disableRuntimeMetrics: <A, E, R>(self: Effect<A, E, R>) => Effect<A, E, R> = InternalEffect.provideService(