effect 4.0.0-beta.70 → 4.0.0-beta.72

package/src/Equivalence.ts

@@ -45,9 +45,9 @@
  *
  * ## See also
  *
- * - {@link Equal} - For structural equality (can convert to Equivalence)
- * - {@link Array_.dedupeWith} - Remove duplicates using an equivalence
- * - {@link Chunk} - Collections that use equivalences for operations
+ * - `Equal` - For structural equality (can convert to Equivalence)
+ * - `Array.dedupeWith` - Remove duplicates using an equivalence
+ * - `Chunk` - Collections that use equivalences for operations
  *
  * @since 2.0.0
  */
@@ -60,13 +60,12 @@ import * as Reducer from "./Reducer.ts"
  *
  * **When to use**
  *
- * - Use as a type annotation for equivalence functions
+ * Use as a type annotation for equivalence functions
  * - Use when implementing custom equivalence logic
  * - Use when working with collection operations that require equivalence relations
  *
  * **Details**
  *
- * - Pure function: does not mutate inputs or have side effects
  * - Returns `boolean`: `true` if values are equivalent, `false` otherwise
  * - Must satisfy reflexive, symmetric, and transitive properties
  *
@@ -109,7 +108,7 @@ export type Equivalence<in A> = (self: A, that: A) => boolean
  *
  * **When to use**
  *
- * - Rarely needed in application code
+ * Use when rarely needed in application code
  * - Use primarily for internal type system operations and HKT (Higher-Kinded Types) abstractions
  * - Use when working with generic type constructors that require type lambdas
  *
@@ -148,13 +147,12 @@ export interface EquivalenceTypeLambda extends TypeLambda {
  *
  * **When to use**
  *
- * - Use when you need a custom equivalence that is not just strict equality
+ * Use when you need a custom equivalence that is not just strict equality
  * - Use when creating equivalences for complex types with custom comparison logic
  * - Use when you want the performance benefit of reference equality optimization
  *
  * **Details**
  *
- * - Does not mutate inputs
  * - First checks reference equality (`===`) for performance; if values are identical, returns `true` without calling the function
  * - Falls back to the provided equivalence function if values are not the same reference
  * - The provided function must satisfy reflexive, symmetric, and transitive properties
@@ -202,14 +200,13 @@ const isStrictEquivalent = (x: unknown, y: unknown) => x === y
  *
  * **When to use**
  *
- * - Use for primitive types where `===` is appropriate
+ * Use when you need primitive types where `===` is appropriate
  * - Use when you need reference equality for objects
  * - Use as a building block for more complex equivalences via {@link mapInput} or {@link combine}
  * - Use when performance is critical and you do not need structural equality
  *
  * **Details**
  *
- * - Does not mutate inputs
  * - Uses JavaScript's strict equality operator (`===`)
  * - For primitives: compares values directly
  * - For objects: compares by reference, so only the same object instance is equivalent
@@ -243,14 +240,18 @@ const isStrictEquivalent = (x: unknown, y: unknown) => x === y
  * ```
  *
  * @see {@link make}
- * @see {@link Equal} for structural equality
+ * @see `Equal` for structural equality
  * @category constructors
  * @since 4.0.0
  */
 export const strictEqual: <A>() => Equivalence<A> = () => isStrictEquivalent
 
 /**
- * An `Equivalence` instance for strings using strict equality (`===`).
+ * Equivalence instance for strings using strict equality (`===`).
+ *
+ * **When to use**
+ *
+ * Use when an API needs an `Equivalence` instance for string equality.
  *
  * **Example** (Comparing strings)
  *
@@ -267,7 +268,12 @@ export const strictEqual: <A>() => Equivalence<A> = () => isStrictEquivalent
 export const String: Equivalence<string> = isStrictEquivalent
 
 /**
- * An `Equivalence` instance for numbers.
+ * Equivalence instance for numbers.
+ *
+ * **When to use**
+ *
+ * Use when an API needs an `Equivalence` instance for numeric equality where
+ * `NaN` equals `NaN`.
  *
  * **Details**
  *
@@ -291,7 +297,11 @@ export const Number: Equivalence<number> = make((self, that) =>
 )
 
 /**
- * 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.
  *
  * **Example** (Comparing booleans)
  *
@@ -308,7 +318,11 @@ export const Number: Equivalence<number> = make((self, that) =>
 export const Boolean: Equivalence<boolean> = isStrictEquivalent
 
 /**
- * An `Equivalence` instance for bigints using strict equality (`===`).
+ * Equivalence instance for bigints using strict equality (`===`).
+ *
+ * **When to use**
+ *
+ * Use when an API needs an `Equivalence` instance for `bigint` equality.
  *
  * **Example** (Comparing bigints)
  *
@@ -329,13 +343,12 @@ export const BigInt: Equivalence<bigint> = isStrictEquivalent
  *
  * **When to use**
  *
- * - Use when you need to combine exactly two equivalences
+ * Use when you need to combine exactly two equivalences
  * - Use when building complex equivalences from simpler ones
  * - Use when you want both conditions to be satisfied
  *
  * **Details**
  *
- * - Does not mutate inputs
  * - Returns `true` only if both equivalences return `true`
  * - Short-circuits: if the first equivalence returns `false`, the second is not called
  * - The result is also an equivalence that satisfies reflexive, symmetric, and transitive properties
@@ -381,13 +394,12 @@ export const combine: {
    *
    * **When to use**
    *
-   * - Use when you need to combine exactly two equivalences
+   * Use when you need to combine exactly two equivalences
    * - Use when building complex equivalences from simpler ones
    * - Use when you want both conditions to be satisfied
    *
    * **Details**
    *
-   * - Does not mutate inputs
    * - Returns `true` only if both equivalences return `true`
    * - Short-circuits: if the first equivalence returns `false`, the second is not called
    * - The result is also an equivalence that satisfies reflexive, symmetric, and transitive properties
@@ -433,13 +445,12 @@ export const combine: {
    *
    * **When to use**
    *
-   * - Use when you need to combine exactly two equivalences
+   * Use when you need to combine exactly two equivalences
    * - Use when building complex equivalences from simpler ones
    * - Use when you want both conditions to be satisfied
    *
    * **Details**
    *
-   * - Does not mutate inputs
    * - Returns `true` only if both equivalences return `true`
    * - Short-circuits: if the first equivalence returns `false`, the second is not called
    * - The result is also an equivalence that satisfies reflexive, symmetric, and transitive properties
@@ -487,14 +498,13 @@ export const combine: {
  *
  * **When to use**
  *
- * - Use when you need to combine three or more equivalences
+ * Use when you need to combine three or more equivalences
  * - Use when you have a dynamic collection of equivalences to combine
  * - Use when building equivalences from arrays or iterables
  * - Prefer this over multiple `combine` calls when you have many equivalences
  *
  * **Details**
  *
- * - Does not mutate inputs
  * - Returns `true` only if all equivalences in the collection return `true`
  * - Short-circuits: stops at the first equivalence that returns `false`
  * - Empty collections return an equivalence that always returns `true`
@@ -564,14 +574,13 @@ export const combineAll = <A>(collection: Iterable<Equivalence<A>>): Equivalence
  *
  * **When to use**
  *
- * - Use when you need an equivalence for a complex type based on a single property
+ * Use when you need an equivalence for a complex type based on a single property
  * - Use when you want to normalize values before comparison, such as case-insensitive strings
  * - Use when creating equivalences that focus on specific fields of objects
  * - Use as a building block for creating equivalences via {@link combine} or {@link combineAll}
  *
  * **Details**
  *
- * - Does not mutate inputs
  * - Applies the transformation function to both values before comparing
  * - The transformation function should be pure and have no side effects
  * - The resulting equivalence compares the transformed values using the provided equivalence
@@ -627,14 +636,13 @@ export const mapInput: {
    *
    * **When to use**
    *
-   * - Use when you need an equivalence for a complex type based on a single property
+   * Use when you need an equivalence for a complex type based on a single property
    * - Use when you want to normalize values before comparison, such as case-insensitive strings
    * - Use when creating equivalences that focus on specific fields of objects
    * - Use as a building block for creating equivalences via {@link combine} or {@link combineAll}
    *
    * **Details**
    *
-   * - Does not mutate inputs
    * - Applies the transformation function to both values before comparing
    * - The transformation function should be pure and have no side effects
    * - The resulting equivalence compares the transformed values using the provided equivalence
@@ -690,14 +698,13 @@ export const mapInput: {
    *
    * **When to use**
    *
-   * - Use when you need an equivalence for a complex type based on a single property
+   * Use when you need an equivalence for a complex type based on a single property
    * - Use when you want to normalize values before comparison, such as case-insensitive strings
    * - Use when creating equivalences that focus on specific fields of objects
    * - Use as a building block for creating equivalences via {@link combine} or {@link combineAll}
    *
    * **Details**
    *
-   * - Does not mutate inputs
    * - Applies the transformation function to both values before comparing
    * - The transformation function should be pure and have no side effects
    * - The resulting equivalence compares the transformed values using the provided equivalence
@@ -758,14 +765,13 @@ export const mapInput: {
  *
  * **When to use**
  *
- * - Use when comparing tuples with different types at each position
+ * Use when comparing tuples with different types at each position
  * - Use when you need different equivalence logic for each tuple element
  * - Use when working with fixed-length tuples instead of arrays
  * - Prefer this over `Array` when you have a known tuple structure with different types
  *
  * **Details**
  *
- * - Does not mutate inputs
  * - Requires tuples to have the same length; different lengths are never equivalent
  * - Applies each equivalence to the corresponding element position
  * - Returns `true` only if all elements are equivalent according to their respective equivalences
@@ -811,8 +817,6 @@ export const mapInput: {
  * ) // true
  * ```
  *
- * @see {@link Array_}
- * @see {@link Struct}
  * @category combinators
  * @since 4.0.0
  */
@@ -852,14 +856,13 @@ export {
    *
    * **When to use**
    *
-   * - Use when comparing arrays with homogeneous element types
+   * Use when comparing arrays with homogeneous element types
    * - Use when all elements should use the same equivalence logic
    * - Use when working with variable-length arrays instead of fixed tuples
    * - Prefer this over `Tuple` when you have arrays of the same type
    *
    * **Details**
    *
-   * - Does not mutate inputs
    * - Requires arrays to have the same length; different lengths are never equivalent
    * - Compares elements positionally, such as index `0` with index `0`
    * - Returns `true` only if all corresponding elements are equivalent
@@ -907,14 +910,13 @@ export {
  *
  * **When to use**
  *
- * - Use when comparing objects with known, fixed property names
+ * Use when comparing objects with known, fixed property names
  * - Use when you need different equivalence logic for different properties
  * - Use when working with struct or interface types with specific fields
  * - Prefer this over `Record` when you have a fixed set of known properties
  *
  * **Details**
  *
- * - Does not mutate inputs
  * - Compares only the properties specified in the struct definition
  * - Properties not in the struct are ignored
  * - Returns `true` only if all specified properties are equivalent according to their equivalences
@@ -990,14 +992,13 @@ export function Struct<R extends Record<string, Equivalence<any>>>(
  *
  * **When to use**
  *
- * - Use when comparing objects with dynamic or unknown property names
+ * Use when comparing objects with dynamic or unknown property names
  * - Use when all property values should use the same equivalence logic
  * - Use when working with record or dictionary types
  * - Prefer this over `Struct` when you have variable properties or need to compare all properties uniformly
  *
  * **Details**
  *
- * - Does not mutate inputs
  * - Compares all properties present in both objects
  * - Requires both objects to have the same set of keys; different keys result in `false`
  * - All property values must be equivalent according to the provided equivalence
@@ -1037,8 +1038,6 @@ export function Struct<R extends Record<string, Equivalence<any>>>(
  * console.log(numberRecordEq(scores1, scores3)) // false
  * ```
  *
- * @see {@link Struct}
- * @see {@link Array_}
  * @category combinators
  * @since 4.0.0
  */
@@ -1064,7 +1063,7 @@ export function Record<A>(value: Equivalence<A>): Equivalence<Record<PropertyKey
  *
  * **When to use**
  *
- * - Use when you need to combine multiple equivalences from a collection using reducer patterns
+ * Use when you need to combine multiple equivalences from a collection using reducer patterns
  * - Use when implementing fold operations over collections of equivalences
  * - Use when working with reducers that operate on equivalences
  *
@@ -1107,7 +1106,11 @@ export function makeReducer<A>() {
 }
 
 /**
- * An `Equivalence` instance for `Date` objects that compares their `getTime()` values using `Equivalence.Number`.
+ * Equivalence instance for `Date` objects that compares their `getTime()` values using `Equivalence.Number`.
+ *
+ * **When to use**
+ *
+ * Use when comparing `Date` values by their millisecond timestamp.
  *
  * **Details**
  *
@@ -1143,9 +1146,9 @@ export function makeReducer<A>() {
  * console.log(Equivalence.Date(d1, d2)) // true (same time value)
  * ```
  *
- * @see {@link Number}
- * @see {@link mapInput}
- * @see {@link strictEqual}
+ * @see {@link Number} for the numeric equivalence applied to each `Date#getTime()` result
+ * @see {@link mapInput} for deriving an equivalence by mapping inputs before comparison
+ * @see {@link strictEqual} for reference equality when two values must be the same object
  * @category instances
  * @since 2.0.0
  */

package/src/ErrorReporter.ts

@@ -65,7 +65,11 @@ import type * as Scope from "./Scope.ts"
  * String literal type used as the runtime type identifier for
  * `ErrorReporter` values.
  *
- * @category Type Identifiers
+ * **When to use**
+ *
+ * Use to refer to the runtime type identifier type in low-level integrations.
+ *
+ * @category type IDs
  * @since 4.0.0
  */
 export type TypeId = "~effect/ErrorReporter"
@@ -73,7 +77,13 @@ export type TypeId = "~effect/ErrorReporter"
 /**
  * Runtime type identifier attached to `ErrorReporter` values.
  *
- * @category Type Identifiers
+ * **Details**
+ *
+ * This marker is part of the runtime representation of `ErrorReporter`
+ * implementations. Most code should create reporters with `make` and register
+ * them with `layer`.
+ *
+ * @category type IDs
  * @since 4.0.0
  */
 export const TypeId: TypeId = "~effect/ErrorReporter"
@@ -82,6 +92,11 @@ export const TypeId: TypeId = "~effect/ErrorReporter"
  * An `ErrorReporter` receives reported failures and forwards them to an
  * external system such as a logging service or error tracker.
  *
+ * **When to use**
+ *
+ * Use as the interface for custom reporters that forward reported Effect
+ * failures to logging, monitoring, or error-tracking systems.
+ *
  * **Details**
  *
  * Reporting is triggered by `Effect.withErrorReporting`,
@@ -89,6 +104,11 @@ export const TypeId: TypeId = "~effect/ErrorReporter"
  * modules. Use {@link make} to create a reporter; it handles deduplication
  * and per-error annotation extraction automatically.
  *
+ * @see {@link make} for creating an `ErrorReporter` from a callback
+ * @see {@link layer} for registering reporters in the environment
+ * @see {@link report} for manually reporting a `Cause`
+ * @see {@link Effect.withErrorReporting} for reporting failures from an effect
+ *
  * @category models
  * @since 4.0.0
  */
@@ -104,6 +124,11 @@ export interface ErrorReporter {
 /**
  * Creates an `ErrorReporter` from a callback.
  *
+ * **When to use**
+ *
+ * Use to define how reported failures are forwarded to a logging, monitoring,
+ * or error-tracking backend.
+ *
  * **Details**
  *
  * The returned reporter automatically deduplicates causes and individual
@@ -124,6 +149,9 @@ export interface ErrorReporter {
  * )
  * ```
  *
+ * @see {@link layer} for registering reporters in the environment
+ * @see {@link report} for manually reporting a `Cause`
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -166,14 +194,13 @@ export const make = (
 }
 
 /**
- * A `Context.Reference` holding the set of active `ErrorReporter`s for the
+ * Context reference that holds the set of active error reporters for the
  * current fiber. Defaults to an empty set (no reporting).
  *
  * **When to use**
  *
- * Prefer {@link layer} to configure reporters via the `Layer` API. Use this
- * reference directly only when you need low-level control (e.g. reading the
- * current reporters or swapping them inside a `FiberRef`).
+ * Use when low-level code needs to read or replace the current set of reporters
+ * directly.
  *
  * @category references
  * @since 4.0.0
@@ -183,6 +210,11 @@ export const CurrentErrorReporters: Context.Reference<ReadonlySet<ErrorReporter>
 /**
  * Creates a `Layer` that registers one or more `ErrorReporter`s.
  *
+ * **When to use**
+ *
+ * Use to provide one or more error reporters to effects that perform error
+ * reporting.
+ *
  * **Details**
  *
  * Reporters can be plain `ErrorReporter` values or effectful
@@ -221,6 +253,9 @@ export const CurrentErrorReporters: Context.Reference<ReadonlySet<ErrorReporter>
  * )
  * ```
  *
+ * @see {@link make} for creating an `ErrorReporter` from a callback
+ * @see {@link CurrentErrorReporters} for low-level access to the current reporters
+ *
  * @category layers
  * @since 4.0.0
  */
@@ -251,13 +286,11 @@ export const layer = <
   )
 
 /**
- * Manually reports a `Cause` to all registered `ErrorReporter`s on the
- * current fiber.
+ * Runs all registered error reporters on the current fiber for a `Cause`.
  *
  * **When to use**
  *
- * This is useful when you want to report an error for observability without
- * actually failing the fiber.
+ * Use to report a failure for observability without failing the current fiber.
  *
  * **Example** (Reporting a cause manually)
  *
@@ -284,6 +317,11 @@ export const report = <E>(cause: Cause.Cause<E>): Effect.Effect<void> =>
 /**
  * Interface that object errors can implement to control reporting behavior.
  *
+ * **When to use**
+ *
+ * Use as the annotation contract for object errors that customize how error
+ * reporting handles them.
+ *
  * **Details**
  *
  * All three annotation properties are optional: `[ErrorReporter.ignore]`
@@ -293,6 +331,11 @@ export const report = <E>(cause: Cause.Cause<E>): Effect.Effect<void> =>
  * augmented with `Reportable`, so these properties are available on `Error`
  * instances at the type level.
  *
+ * @see {@link ignore} for the runtime annotation key that suppresses reports
+ * @see {@link severity} for the runtime annotation key that overrides severity
+ * @see {@link attributes} for the runtime annotation key that attaches reporter
+ * metadata
+ *
  * @category annotations
  * @since 4.0.0
  */
@@ -307,9 +350,14 @@ declare global {
 }
 
 /**
- * String property key used to mark an object error as ignored by error
+ * Defines the string property key used to mark an object error as ignored by error
  * reporting.
  *
+ * **When to use**
+ *
+ * Use to type the property key that suppresses reporting for expected object
+ * errors.
+ *
  * **Details**
  *
  * Set this property to `true` on an error class or object error to prevent it
@@ -322,9 +370,14 @@ declare global {
 export type ignore = "~effect/ErrorReporter/ignore"
 
 /**
- * Runtime property key used to mark an object error as ignored by error
+ * Defines the runtime property key used to mark an object error as ignored by error
  * reporting.
  *
+ * **When to use**
+ *
+ * Use to suppress reporting for expected object errors, such as HTTP 404
+ * responses.
+ *
  * **Details**
  *
  * Set `error[ErrorReporter.ignore]` to `true` to prevent the error from being
@@ -341,6 +394,10 @@ export type ignore = "~effect/ErrorReporter/ignore"
  * }
  * ```
  *
+ * @see {@link isIgnored} for checking whether a value carries this annotation
+ * @see {@link Reportable} for the annotation contract recognized on object
+ * errors
+ *
  * @category annotations
  * @since 4.0.0
  */
@@ -350,6 +407,13 @@ export const ignore: ignore = "~effect/ErrorReporter/ignore"
  * Returns `true` if the given value has the `ErrorReporter.ignore` annotation
  * set to `true`.
  *
+ * **When to use**
+ *
+ * Use to check whether an error value is annotated to be skipped before
+ * forwarding it to error reporting code.
+ *
+ * @see {@link ignore} for the annotation key this predicate reads
+ *
  * @category annotations
  * @since 4.0.0
  */
@@ -357,7 +421,12 @@ export const isIgnored = (u: unknown): boolean =>
   typeof u === "object" && u !== null && ignore in u && u[ignore] === true
 
 /**
- * String property key used to override the severity level of an object error.
+ * Defines the string property key used to override the severity level of an object error.
+ *
+ * **When to use**
+ *
+ * Use to type the property key that overrides the reporting severity for object
+ * errors.
  *
  * **Details**
  *
@@ -370,7 +439,12 @@ export const isIgnored = (u: unknown): boolean =>
 export type severity = "~effect/ErrorReporter/severity"
 
 /**
- * Runtime property key used to override the severity level of an object error.
+ * Defines the runtime property key used to override the severity level of an object error.
+ *
+ * **When to use**
+ *
+ * Use to annotate object errors with the severity reporter callbacks should
+ * receive.
  *
  * **Details**
  *
@@ -387,6 +461,10 @@ export type severity = "~effect/ErrorReporter/severity"
  * }
  * ```
  *
+ * @see {@link getSeverity} for reading the severity stored under this key
+ * @see {@link Reportable} for the annotation contract recognized on object
+ * errors
+ *
  * @category annotations
  * @since 4.0.0
  */
@@ -396,6 +474,14 @@ export const severity: severity = "~effect/ErrorReporter/severity"
  * Reads the `ErrorReporter.severity` annotation from an error object,
  * falling back to `"Info"` when the annotation is unset or invalid.
  *
+ * **When to use**
+ *
+ * Use to inspect the severity that reporter callbacks will receive for an
+ * object error.
+ *
+ * @see {@link severity} for the annotation key used to override severity
+ * @see {@link Reportable} for the annotation properties recognized on object errors
+ *
  * @category annotations
  * @since 4.0.0
  */
@@ -407,9 +493,13 @@ export const getSeverity = (error: object): Severity => {
 }
 
 /**
- * String property key used to attach extra key/value metadata to an object
+ * Defines the string property key used to attach extra key/value metadata to an object
  * error report.
  *
+ * **When to use**
+ *
+ * Use to type the property key that attaches metadata to object error reports.
+ *
  * **Details**
  *
  * Reporters receive these attributes alongside the error, making it easy to
@@ -422,9 +512,14 @@ export const getSeverity = (error: object): Severity => {
 export type attributes = "~effect/ErrorReporter/attributes"
 
 /**
- * Runtime property key used to attach extra key/value metadata to an object
+ * Defines the runtime property key used to attach extra key/value metadata to an object
  * error report.
  *
+ * **When to use**
+ *
+ * Use to attach domain metadata to object errors so reporter callbacks receive
+ * it with the reported failure.
+ *
  * **Details**
  *
  * Set `error[ErrorReporter.attributes]` to a record of metadata that should be
@@ -444,6 +539,12 @@ export type attributes = "~effect/ErrorReporter/attributes"
  * }
  * ```
  *
+ * @see {@link ignore} for suppressing reports for expected object errors
+ * @see {@link severity} for overriding reporter severity
+ * @see {@link getAttributes} for reading the metadata stored under this key
+ * @see {@link Reportable} for the annotation contract recognized on object
+ * errors
+ *
  * @category annotations
  * @since 4.0.0
  */
@@ -453,6 +554,24 @@ export const attributes: attributes = "~effect/ErrorReporter/attributes"
  * Reads the `ErrorReporter.attributes` annotation from an error object,
  * returning an empty record when unset.
  *
+ * **When to use**
+ *
+ * Use to inspect the attributes that reporter callbacks will receive for an
+ * object error.
+ *
+ * **Details**
+ *
+ * Returns the value stored under `ErrorReporter.attributes`, or the module's
+ * shared empty record when the annotation is absent.
+ *
+ * **Gotchas**
+ *
+ * The annotation value is returned as-is; this helper does not validate or
+ * clone it.
+ *
+ * @see {@link attributes} for the annotation key used to attach metadata
+ * @see {@link Reportable} for the annotation properties recognized on object errors
+ *
  * @category annotations
  * @since 4.0.0
  */