effect 4.0.0-beta.71 → 4.0.0-beta.73

package/src/Boolean.ts

@@ -63,12 +63,12 @@ import * as predicate from "./Predicate.ts"
 import * as Reducer from "./Reducer.ts"
 
 /**
- * Reference to the global `Boolean` constructor for JavaScript truthiness
+ * Exposes the global boolean constructor for JavaScript truthiness
  * coercion.
  *
  * **When to use**
  *
- * Use when you want native `Boolean` constructor coercion from the Effect module
+ * Use to access native JavaScript truthiness coercion from the Effect module
  * namespace.
  *
  * **Gotchas**
@@ -97,7 +97,7 @@ import * as Reducer from "./Reducer.ts"
 export const Boolean = globalThis.Boolean
 
 /**
- * Tests if a value is a `boolean`.
+ * Checks whether a value is a `boolean`.
  *
  * **When to use**
  *
@@ -119,8 +119,7 @@ export const Boolean = globalThis.Boolean
 export const isBoolean: (input: unknown) => input is boolean = predicate.isBoolean
 
 /**
- * This function returns the result of either of the given functions depending on the value of the boolean parameter.
- * It is useful when you have to run one of two functions depending on the boolean value.
+ * Chooses between two lazy branches based on a boolean value.
  *
  * **When to use**
  *
@@ -146,8 +145,7 @@ export const isBoolean: (input: unknown) => input is boolean = predicate.isBoole
  */
 export const match: {
   /**
-   * This function returns the result of either of the given functions depending on the value of the boolean parameter.
-   * It is useful when you have to run one of two functions depending on the boolean value.
+   * Chooses between two lazy branches based on a boolean value.
    *
    * **When to use**
    *
@@ -178,8 +176,7 @@ export const match: {
    }
   ): (value: boolean) => A | B
   /**
-   * This function returns the result of either of the given functions depending on the value of the boolean parameter.
-   * It is useful when you have to run one of two functions depending on the boolean value.
+   * Chooses between two lazy branches based on a boolean value.
    *
    * **When to use**
    *
@@ -221,8 +218,8 @@ export const match: {
  *
  * **When to use**
  *
- * Use when an API needs an `Order` instance for booleans with `false` before
- * `true`.
+ * Use when sorting or comparing boolean values through APIs that accept an
+ * ordering instance where `false` comes before `true`.
  *
  * **Example** (Comparing booleans)
  *
@@ -240,11 +237,12 @@ export const match: {
 export const Order: order.Order<boolean> = order.Boolean
 
 /**
- * An `Equivalence` instance for booleans using strict equality (`===`).
+ * Equivalence instance for booleans using strict equality (`===`).
  *
  * **When to use**
  *
- * Use when an API needs an `Equivalence` instance for boolean equality.
+ * Use when checking boolean equality through APIs that accept an equivalence
+ * relation.
  *
  * **Example** (Comparing booleans for equivalence)
  *
@@ -792,7 +790,7 @@ export const implies: {
 } = dual(2, (self, that) => self ? that : true)
 
 /**
- * This utility function is used to check if all the elements in a collection of boolean values are `true`.
+ * Checks whether every boolean in a collection is `true`.
  *
  * **When to use**
  *
@@ -824,7 +822,7 @@ export const every = (collection: Iterable<boolean>): boolean => {
 }
 
 /**
- * This utility function is used to check if at least one of the elements in a collection of boolean values is `true`.
+ * Checks whether at least one boolean in a collection is `true`.
  *
  * **When to use**
  *
@@ -856,7 +854,7 @@ export const some = (collection: Iterable<boolean>): boolean => {
 }
 
 /**
- * A `Reducer` for combining `boolean`s using AND.
+ * Reducer for combining `boolean`s using AND.
  *
  * **When to use**
  *
@@ -881,7 +879,7 @@ export const some = (collection: Iterable<boolean>): boolean => {
 export const ReducerAnd: Reducer.Reducer<boolean> = Reducer.make((a, b) => a && b, true)
 
 /**
- * A `Reducer` for combining `boolean`s using OR.
+ * Reducer for combining `boolean`s using OR.
  *
  * **When to use**
  *

package/src/Brand.ts

@@ -132,8 +132,7 @@ export interface Constructor<in out B extends Brand<any>> {
 }
 
 /**
- * A `BrandError` is returned when a branded type is constructed from an invalid
- * value.
+ * Error returned when a branded type is constructed from an invalid value.
  *
  * **Details**
  *
@@ -145,7 +144,7 @@ export interface Constructor<in out B extends Brand<any>> {
  * `BrandError` is an error-like model with `_tag`, `name`, `message`, and
  * `toString`; it does not extend JavaScript `Error`.
  *
- * @category models
+ * @category errors
  * @since 4.0.0
  */
 export class BrandError {

package/src/Cache.ts

@@ -1751,7 +1751,7 @@ export const set: {
 )
 
 /**
- * Checks if the cache contains an entry for the specified key.
+ * Checks whether the cache contains an entry for the specified key.
  *
  * **Details**
  *
@@ -1841,7 +1841,7 @@ export const set: {
  */
 export const has: {
   /**
-   * Checks if the cache contains an entry for the specified key.
+   * Checks whether the cache contains an entry for the specified key.
    *
    * **Details**
    *
@@ -1931,7 +1931,7 @@ export const has: {
    */
   <Key, A>(key: Key): <E, R>(self: Cache<Key, A, E, R>) => Effect.Effect<boolean>
   /**
-   * Checks if the cache contains an entry for the specified key.
+   * Checks whether the cache contains an entry for the specified key.
    *
    * **Details**
    *
@@ -2173,8 +2173,8 @@ export const invalidate: {
   }))
 
 /**
- * Conditionally invalidates the entry associated with the specified key in the cache
- * if the predicate returns true for the cached value.
+ * Invalidates the entry associated with the specified key in the cache when the
+ * predicate returns true for the cached value.
  *
  * **Example** (Invalidating entries conditionally)
  *
@@ -2239,8 +2239,8 @@ export const invalidate: {
  */
 export const invalidateWhen: {
   /**
-   * Conditionally invalidates the entry associated with the specified key in the cache
-   * if the predicate returns true for the cached value.
+   * Invalidates the entry associated with the specified key in the cache when the
+   * predicate returns true for the cached value.
    *
    * **Example** (Invalidating entries conditionally)
    *
@@ -2305,8 +2305,8 @@ export const invalidateWhen: {
    */
   <Key, A>(key: Key, f: Predicate<A>): <E, R>(self: Cache<Key, A, E, R>) => Effect.Effect<boolean>
   /**
-   * Conditionally invalidates the entry associated with the specified key in the cache
-   * if the predicate returns true for the cached value.
+   * Invalidates the entry associated with the specified key in the cache when the
+   * predicate returns true for the cached value.
    *
    * **Example** (Invalidating entries conditionally)
    *

package/src/Cause.ts

@@ -91,7 +91,7 @@ import type * as Types from "./Types.ts"
 /**
  * Unique brand for `Cause` values, used for runtime type checks via {@link isCause}.
  *
- * @category symbols
+ * @category type IDs
  * @since 4.0.0
  */
 export const TypeId: "~effect/Cause" = core.CauseTypeId
@@ -99,7 +99,7 @@ export const TypeId: "~effect/Cause" = core.CauseTypeId
 /**
  * Unique brand for `Reason` values, used for runtime type checks via {@link isReason}.
  *
- * @category symbols
+ * @category type IDs
  * @since 4.0.0
  */
 export const ReasonTypeId: "~effect/Cause/Reason" = core.CauseReasonTypeId
@@ -146,7 +146,7 @@ export interface Cause<out E> extends Pipeable, Inspectable, Equal {
 }
 
 /**
- * Tests if an arbitrary value is a `Cause`.
+ * Checks whether an arbitrary value is a `Cause`.
  *
  * **Example** (runtime type check)
  *
@@ -163,7 +163,7 @@ export interface Cause<out E> extends Pipeable, Inspectable, Equal {
 export const isCause: (self: unknown) => self is Cause<unknown> = core.isCause
 
 /**
- * Tests if an arbitrary value is a `Reason` (`Fail`, `Die`, or `Interrupt`).
+ * Checks whether an arbitrary value is a `Reason` (`Fail`, `Die`, or `Interrupt`).
  *
  * **Example** (runtime type check)
  *
@@ -468,7 +468,7 @@ export interface Interrupt extends Cause.ReasonProto<"Interrupt"> {
  *
  * **Details**
  *
- * - Returns a new `Cause`; does not mutate the input array.
+ * - Returns a new `Cause`.
  * - An empty array produces a cause equivalent to `empty`.
  *
  * **Gotchas**
@@ -499,7 +499,7 @@ export const fromReasons: <E>(
 ) => Cause<E> = core.causeFromReasons
 
 /**
- * A `Cause` with an empty `reasons` array.
+ * Represents a `Cause` with an empty `reasons` array.
  *
  * **When to use**
  *
@@ -608,8 +608,8 @@ export const interrupt: (fiberId?: number | undefined) => Cause<never> = effect.
  *
  * **When to use**
  *
- * Use when you need to construct individual reasons for
- * {@link fromReasons} or for direct comparison.
+ * Use when constructing a standalone typed failure reason for
+ * {@link fromReasons} or direct comparison.
  *
  * **Example** (creating a Fail reason)
  *
@@ -634,8 +634,8 @@ export const makeFailReason = <E>(error: E): Fail<E> => new core.Fail(error)
  *
  * **When to use**
  *
- * Use when you need to construct individual reasons for
- * {@link fromReasons} or for direct comparison.
+ * Use when constructing a standalone defect reason for {@link fromReasons} or
+ * direct comparison.
  *
  * **Example** (creating a Die reason)
  *
@@ -661,8 +661,8 @@ export const makeDieReason = (defect: unknown): Die => new core.Die(defect)
  *
  * **When to use**
  *
- * Use when you need to construct individual reasons for
- * {@link fromReasons} or for direct comparison.
+ * Use when constructing a standalone interrupt reason for {@link fromReasons}
+ * or direct comparison.
  *
  * **Example** (creating an Interrupt reason)
  *
@@ -722,8 +722,7 @@ export const hasInterruptsOnly: <E>(self: Cause<E>) => boolean = effect.hasInter
  *
  * If at least one `Fail` reason exists, this returns a new `Cause`
  * containing the mapped failures. If the cause has no `Fail` reasons, the
- * original cause is returned unchanged. In either case, the original cause is
- * not mutated.
+ * original cause is returned unchanged.
  *
  * **Example** (mapping errors to uppercase)
  *
@@ -756,8 +755,7 @@ export const map: {
    *
    * If at least one `Fail` reason exists, this returns a new `Cause`
    * containing the mapped failures. If the cause has no `Fail` reasons, the
-   * original cause is returned unchanged. In either case, the original cause is
-   * not mutated.
+   * original cause is returned unchanged.
    *
    * **Example** (mapping errors to uppercase)
    *
@@ -790,8 +788,7 @@ export const map: {
    *
    * If at least one `Fail` reason exists, this returns a new `Cause`
    * containing the mapped failures. If the cause has no `Fail` reasons, the
-   * original cause is returned unchanged. In either case, the original cause is
-   * not mutated.
+   * original cause is returned unchanged.
    *
    * **Example** (mapping errors to uppercase)
    *
@@ -1306,8 +1303,7 @@ export const filterInterruptors: <E>(self: Cause<E>) => Result.Result<Set<number
 export const prettyErrors: <E>(self: Cause<E>) => Array<Error> = effect.causePrettyErrors
 
 /**
- * Renders a `Cause` as a human-readable string for logging or
- * debugging.
+ * Formats a `Cause` as a human-readable string for logging or debugging.
  *
  * **When to use**
  *
@@ -1384,7 +1380,7 @@ export interface YieldableError extends Error, Pipeable, Inspectable {
 }
 
 /**
- * Tests if an arbitrary value is a `NoSuchElementError`.
+ * Checks whether an arbitrary value is a `NoSuchElementError`.
  *
  * **Example** (runtime type check)
  *
@@ -1403,7 +1399,7 @@ export const isNoSuchElementError: (u: unknown) => u is NoSuchElementError = cor
 /**
  * Unique brand for `NoSuchElementError`.
  *
- * @category symbols
+ * @category type IDs
  * @since 4.0.0
  */
 export const NoSuchElementErrorTypeId: "~effect/Cause/NoSuchElementError" = core.NoSuchElementErrorTypeId
@@ -1470,7 +1466,7 @@ export interface NoSuchElementError extends YieldableError {
 export const NoSuchElementError: new(message?: string) => NoSuchElementError = core.NoSuchElementError
 
 /**
- * Tests if an arbitrary value is a `Done` signal.
+ * Checks whether an arbitrary value is a `Done` signal.
  *
  * **Example** (runtime type check)
  *
@@ -1489,7 +1485,7 @@ export const isDone: (u: unknown) => u is Done<any> = core.isDone
 /**
  * Unique brand for `Done` values.
  *
- * @category symbols
+ * @category type IDs
  * @since 4.0.0
  */
 export const DoneTypeId: "~effect/Cause/Done" = core.DoneTypeId
@@ -1603,13 +1599,13 @@ export const done: <A = void>(value?: A) => Effect.Effect<never, Done<A>> = core
 /**
  * Unique brand for `TimeoutError`.
  *
- * @category symbols
+ * @category type IDs
  * @since 4.0.0
  */
 export const TimeoutErrorTypeId: "~effect/Cause/TimeoutError" = effect.TimeoutErrorTypeId
 
 /**
- * Tests if an arbitrary value is a `TimeoutError`.
+ * Checks whether an arbitrary value is a `TimeoutError`.
  *
  * **Example** (runtime type check)
  *
@@ -1671,13 +1667,13 @@ export const TimeoutError: new(message?: string) => TimeoutError = effect.Timeou
 /**
  * Unique brand for `IllegalArgumentError`.
  *
- * @category symbols
+ * @category type IDs
  * @since 4.0.0
  */
 export const IllegalArgumentErrorTypeId: "~effect/Cause/IllegalArgumentError" = effect.IllegalArgumentErrorTypeId
 
 /**
- * Tests if an arbitrary value is an `IllegalArgumentError`.
+ * Checks whether an arbitrary value is an `IllegalArgumentError`.
  *
  * **Example** (runtime type check)
  *
@@ -1737,7 +1733,7 @@ export interface IllegalArgumentError extends YieldableError {
 export const IllegalArgumentError: new(message?: string) => IllegalArgumentError = effect.IllegalArgumentError
 
 /**
- * Tests if an arbitrary value is an `ExceededCapacityError`.
+ * Checks whether an arbitrary value is an `ExceededCapacityError`.
  *
  * **Example** (runtime type check)
  *
@@ -1756,7 +1752,7 @@ export const isExceededCapacityError: (u: unknown) => u is ExceededCapacityError
 /**
  * Unique brand for `ExceededCapacityError`.
  *
- * @category symbols
+ * @category type IDs
  * @since 4.0.0
  */
 export const ExceededCapacityErrorTypeId: "~effect/Cause/ExceededCapacityError" = effect.ExceededCapacityErrorTypeId
@@ -1819,13 +1815,13 @@ export const ExceededCapacityError: new(message?: string) => ExceededCapacityErr
  * Unique brand present on `AsyncFiberError` values and used by
  * `isAsyncFiberError` for runtime checks.
  *
- * @category symbols
+ * @category type IDs
  * @since 4.0.0
  */
 export const AsyncFiberErrorTypeId: "~effect/Cause/AsyncFiberError" = effect.AsyncFiberErrorTypeId
 
 /**
- * Tests if an arbitrary value is an `AsyncFiberError`.
+ * Checks whether an arbitrary value is an `AsyncFiberError`.
  *
  * **Example** (runtime type check)
  *
@@ -1911,13 +1907,13 @@ export const AsyncFiberError: new(fiber: Fiber<unknown, unknown>) => AsyncFiberE
 /**
  * Unique brand for `UnknownError`.
  *
- * @category symbols
+ * @category type IDs
  * @since 4.0.0
  */
 export const UnknownErrorTypeId: "~effect/Cause/UnknownError" = effect.UnknownErrorTypeId
 
 /**
- * Tests if an arbitrary value is an `UnknownError`.
+ * Checks whether an arbitrary value is an `UnknownError`.
  *
  * **Example** (runtime type check)
  *
@@ -1992,7 +1988,7 @@ export const UnknownError: new(cause: unknown, message?: string) => UnknownError
  * retrieved later via {@link reasonAnnotations} or {@link annotations}.
  * The runtime uses this to attach stack traces and spans.
  *
- * - Returns a new `Cause`; does not mutate the input.
+ * - Returns a new `Cause`.
  * - By default, existing keys are preserved. Pass `{ overwrite: true }` to
  *   replace them.
  *
@@ -2029,7 +2025,7 @@ export const annotate: {
    * retrieved later via {@link reasonAnnotations} or {@link annotations}.
    * The runtime uses this to attach stack traces and spans.
    *
-   * - Returns a new `Cause`; does not mutate the input.
+   * - Returns a new `Cause`.
    * - By default, existing keys are preserved. Pass `{ overwrite: true }` to
    *   replace them.
    *
@@ -2069,7 +2065,7 @@ export const annotate: {
    * retrieved later via {@link reasonAnnotations} or {@link annotations}.
    * The runtime uses this to attach stack traces and spans.
    *
-   * - Returns a new `Cause`; does not mutate the input.
+   * - Returns a new `Cause`.
    * - By default, existing keys are preserved. Pass `{ overwrite: true }` to
    *   replace them.
    *
@@ -2162,7 +2158,7 @@ export const reasonAnnotations: <E>(self: Reason<E>) => Context.Context<never> =
 export const annotations: <E>(self: Cause<E>) => Context.Context<never> = effect.causeAnnotations
 
 /**
- * `Context` key for the stack frame captured at the point of failure.
+ * Context annotation used to store the stack frame captured at the point of failure.
  *
  * **When to use**
  *
@@ -2185,7 +2181,7 @@ export const annotations: <E>(self: Cause<E>) => Context.Context<never> = effect
 export class StackTrace extends Context.Service<StackTrace, StackFrame>()("effect/Cause/StackTrace") {}
 
 /**
- * `Context` key for the stack frame captured at the point of
+ * Context annotation used to store the stack frame captured at the point of
  * interruption.
  *
  * **When to use**