effect 4.0.0-beta.74 → 4.0.0-beta.75

package/src/Encoding.ts

@@ -60,6 +60,11 @@ import * as Result from "./Result.ts"
  * Type identifier stored on `EncodingError` values and used by
  * `isEncodingError`.
  *
+ * **When to use**
+ *
+ * Use when implementing low-level `EncodingError`-compatible values that need
+ * to carry the runtime marker.
+ *
  * **Details**
  *
  * This marker is part of the runtime representation of `EncodingError`. Prefer

package/src/Equal.ts

@@ -79,10 +79,8 @@ import { hasProperty } from "./Predicate.ts"
  *
  * **When to use**
  *
- * Use when you use it as the computed property key when implementing custom equality on a
- *   class or object literal.
- * - Use it to check manually whether an object carries an equality method (prefer
- *   {@link isEqual} instead).
+ * Use when you implement custom equality and need the computed property key for
+ * the equality method.
  *
  * **Details**
  *
@@ -118,7 +116,7 @@ export const symbol = "~effect/interfaces/Equal"
  *
  * **When to use**
  *
- * Use when when you need value-based equality for a class (e.g. domain IDs,
+ * Use when you need value-based equality for a class (e.g. domain IDs,
  *   coordinates, money values).
  * - When your type will be stored in `HashMap` or `HashSet`.
  * - When the default structural comparison is too broad or too narrow for
@@ -174,30 +172,24 @@ export interface Equal extends Hash.Hash {
  *
  * **When to use**
  *
- * Use when as the default equality check throughout Effect code.
- * - In data-level assertions or conditional logic where structural comparison
- *   is needed.
- * - In its curried (single-argument) form to build reusable predicates.
+ * Use when you need Effect's default structural equality check.
  *
  * **Details**
  *
- * - Returns a `boolean`; never throws.
- * - Primitives: compared by value. `NaN` equals `NaN`.
- * - Objects implementing {@link Equal}: delegates to their
- *   `[Equal.symbol]` method. If only one operand implements `Equal`, the
- *   result is `false`.
- * - Dates: compared by ISO string representation.
- * - RegExps: compared by string representation.
- * - Arrays: element-by-element recursive comparison (order matters).
- * - Maps / Sets: structural comparison of entries (order-independent).
- * - Plain objects: all own and inherited enumerable keys are compared
- *   recursively.
- * - Functions without an `Equal` implementation are compared by reference.
- * - Circular references are handled; two structures that are circular at the
- *   same depth are considered equal.
- * - Hash values are checked first as a fast-path rejection.
- * - Supports dual (data-last) usage: call with one argument to get a curried
- *   predicate.
+ * Returns a `boolean` and never throws. Primitives are compared by value, and
+ * `NaN` equals `NaN`. Objects implementing `Equal` delegate to their
+ * `[Equal.symbol]` method; if only one operand implements `Equal`, the result
+ * is `false`.
+ *
+ * Dates compare by ISO string, RegExps compare by string representation,
+ * arrays compare element-by-element, Maps and Sets compare entries
+ * order-independently, and plain objects compare enumerable keys recursively.
+ * Functions without an `Equal` implementation compare by reference. Circular
+ * references are handled when both structures are circular at the same depth.
+ *
+ * Hash values are checked first as a fast-path rejection. The function also
+ * supports dual data-last usage: call it with one argument to get a curried
+ * predicate.
  *
  * **Gotchas**
  *
@@ -462,10 +454,8 @@ const compareSets = makeCompareSet(compareBoth)
  *
  * **When to use**
  *
- * Use when to branch on whether a value supports custom equality before calling
- *   its `[Equal.symbol]` method directly.
- * - In generic utility code that needs to distinguish `Equal` implementors
- *   from plain values.
+ * Use when you need generic utility code to distinguish `Equal` implementors
+ * from plain values before calling `[Equal.symbol]` directly.
  *
  * **Details**
  *
@@ -506,8 +496,8 @@ export const isEqual = (u: unknown): u is Equal => hasProperty(u, symbol)
  *
  * **When to use**
  *
- * Use when when an API (e.g. `Array.dedupeWith`, `Equivalence.mapInput`) requires an
- *   `Equivalence` and you want to reuse `Equal.equals`.
+ * Use when you want to pass `Equal.equals` to APIs that require an
+ * `Equivalence`.
  *
  * **Details**
  *
@@ -536,10 +526,8 @@ export const asEquivalence: <A>() => Equivalence<A> = () => equals
  *
  * **When to use**
  *
- * Use when when you have a plain object or array that should be compared by identity
- *   (reference), not by contents.
- * - When you want to preserve the original object unchanged and get a new
- *   reference-equal handle.
+ * Use when you need to compare a plain object or array by identity without
+ * mutating the original value.
  *
  * **Details**
  *
@@ -580,9 +568,8 @@ export const byReference = <T extends object>(obj: T): T => byReferenceUnsafe(ne
  *
  * **When to use**
  *
- * Use when when you want reference equality semantics and can accept that the
- *   original object is **permanently** modified.
- * - When proxy overhead is unacceptable (hot paths, large collections).
+ * Use when you need reference equality without proxy allocation and accept
+ * permanently marking the original object for reference-only equality.
  *
  * **Details**
  *

package/src/Equivalence.ts

@@ -60,9 +60,7 @@ import * as Reducer from "./Reducer.ts"
  *
  * **When to use**
  *
- * Use as a type annotation for equivalence functions
- * - Use when implementing custom equivalence logic
- * - Use when working with collection operations that require equivalence relations
+ * Use as a type annotation when you accept or return an equivalence function.
  *
  * **Details**
  *
@@ -108,9 +106,7 @@ export type Equivalence<in A> = (self: A, that: A) => boolean
  *
  * **When to use**
  *
- * 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
+ * Use when you need to abstract over `Equivalence` in higher-kinded type code.
  *
  * **Details**
  *
@@ -147,15 +143,15 @@ export interface EquivalenceTypeLambda extends TypeLambda {
  *
  * **When to use**
  *
- * 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
+ * Use when you need an equality rule that the built-in instances and input
+ * mapping helpers cannot express, and you can provide a law-abiding comparison.
  *
  * **Details**
  *
- * - 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
+ * The returned equivalence first checks reference equality (`===`) for
+ * performance. If the values are not the same reference, it falls back to the
+ * provided equivalence function, which must satisfy reflexive, symmetric, and
+ * transitive properties.
  *
  * **Example** (Case-insensitive string equivalence)
  *
@@ -200,16 +196,14 @@ const isStrictEquivalent = (x: unknown, y: unknown) => x === y
  *
  * **When to use**
  *
- * 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
+ * Use when you need strict equality (`===`) as the comparison.
  *
  * **Details**
  *
- * - Uses JavaScript's strict equality operator (`===`)
- * - For primitives: compares values directly
- * - For objects: compares by reference, so only the same object instance is equivalent
+ * Uses JavaScript's strict equality operator (`===`). Primitives compare by
+ * value. Objects compare by reference, so only the same object instance is
+ * equivalent. Use this as a building block for more complex equivalences via
+ * `mapInput` or `combine`.
  *
  * **Gotchas**
  *
@@ -251,7 +245,7 @@ export const strictEqual: <A>() => Equivalence<A> = () => isStrictEquivalent
  *
  * **When to use**
  *
- * Use when an API needs an `Equivalence` instance for string equality.
+ * Use when you need to supply case-sensitive string equality.
  *
  * **Example** (Comparing strings)
  *
@@ -272,12 +266,7 @@ export const String: Equivalence<string> = isStrictEquivalent
  *
  * **When to use**
  *
- * Use when an API needs an `Equivalence` instance for numeric equality where
- * `NaN` equals `NaN`.
- *
- * **Details**
- *
- * `NaN` is considered equal to `NaN`.
+ * Use when you need numeric equality that treats NaN as equal to itself.
  *
  * **Example** (Comparing numbers)
  *
@@ -301,7 +290,7 @@ export const Number: Equivalence<number> = make((self, that) =>
  *
  * **When to use**
  *
- * Use when an API needs an `Equivalence` instance for boolean equality.
+ * Use when you need to supply boolean equality.
  *
  * **Example** (Comparing booleans)
  *
@@ -322,7 +311,7 @@ export const Boolean: Equivalence<boolean> = isStrictEquivalent
  *
  * **When to use**
  *
- * Use when an API needs an `Equivalence` instance for `bigint` equality.
+ * Use when you need to supply bigint equality.
  *
  * **Example** (Comparing bigints)
  *
@@ -343,15 +332,14 @@ export const BigInt: Equivalence<bigint> = isStrictEquivalent
  *
  * **When to use**
  *
- * 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
+ * Use when you need to combine exactly two equivalences with AND semantics.
  *
  * **Details**
  *
- * - 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
+ * Returns `true` only if both equivalences return `true`. The comparison
+ * short-circuits when the first equivalence returns `false`. The result is also
+ * an equivalence that satisfies reflexive, symmetric, and transitive
+ * properties.
  *
  * **Example** (Combining name and age equivalences)
  *
@@ -394,15 +382,14 @@ export const combine: {
    *
    * **When to use**
    *
-   * 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
+   * Use when you need to combine exactly two equivalences with AND semantics.
    *
    * **Details**
    *
-   * - 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
+   * Returns `true` only if both equivalences return `true`. The comparison
+   * short-circuits when the first equivalence returns `false`. The result is also
+   * an equivalence that satisfies reflexive, symmetric, and transitive
+   * properties.
    *
    * **Example** (Combining name and age equivalences)
    *
@@ -445,15 +432,14 @@ export const combine: {
    *
    * **When to use**
    *
-   * 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
+   * Use when you need to combine exactly two equivalences with AND semantics.
    *
    * **Details**
    *
-   * - 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
+   * Returns `true` only if both equivalences return `true`. The comparison
+   * short-circuits when the first equivalence returns `false`. The result is also
+   * an equivalence that satisfies reflexive, symmetric, and transitive
+   * properties.
    *
    * **Example** (Combining name and age equivalences)
    *
@@ -498,17 +484,15 @@ export const combine: {
  *
  * **When to use**
  *
- * 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
+ * Use when you need to combine many `Equivalence` instances from an iterable.
  *
  * **Details**
  *
- * - 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`
- * - The result is also an equivalence that satisfies reflexive, symmetric, and transitive properties
+ * Returns `true` only if all equivalences in the collection return `true`. The
+ * comparison stops at the first equivalence that returns `false`. Empty
+ * collections return an equivalence that always returns `true`. The result is
+ * also an equivalence that satisfies reflexive, symmetric, and transitive
+ * properties.
  *
  * **Example** (Combining multiple field equivalences)
  *
@@ -574,10 +558,7 @@ 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 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}
+ * Use when you need an equivalence for one type by comparing a derived value.
  *
  * **Details**
  *
@@ -585,6 +566,8 @@ export const combineAll = <A>(collection: Iterable<Equivalence<A>>): Equivalence
  * - The transformation function should be pure and have no side effects
  * - The resulting equivalence compares the transformed values using the provided equivalence
  * - The result is also an equivalence that satisfies reflexive, symmetric, and transitive properties
+ * - Useful for comparing by one property or normalizing values before
+ *   comparison, such as case-insensitive strings
  *
  * **Example** (Equivalence based on object property)
  *
@@ -636,10 +619,7 @@ export const mapInput: {
    *
    * **When to use**
    *
-   * 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}
+   * Use when you need an equivalence for one type by comparing a derived value.
    *
    * **Details**
    *
@@ -647,6 +627,8 @@ export const mapInput: {
    * - The transformation function should be pure and have no side effects
    * - The resulting equivalence compares the transformed values using the provided equivalence
    * - The result is also an equivalence that satisfies reflexive, symmetric, and transitive properties
+   * - Useful for comparing by one property or normalizing values before
+   *   comparison, such as case-insensitive strings
    *
    * **Example** (Equivalence based on object property)
    *
@@ -698,10 +680,7 @@ export const mapInput: {
    *
    * **When to use**
    *
-   * 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}
+   * Use when you need an equivalence for one type by comparing a derived value.
    *
    * **Details**
    *
@@ -709,6 +688,8 @@ export const mapInput: {
    * - The transformation function should be pure and have no side effects
    * - The resulting equivalence compares the transformed values using the provided equivalence
    * - The result is also an equivalence that satisfies reflexive, symmetric, and transitive properties
+   * - Useful for comparing by one property or normalizing values before
+   *   comparison, such as case-insensitive strings
    *
    * **Example** (Equivalence based on object property)
    *
@@ -765,17 +746,16 @@ export const mapInput: {
  *
  * **When to use**
  *
- * 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
+ * Use when you need an `Equivalence` for fixed-length tuples with per-position
+ * equivalences.
  *
  * **Details**
  *
- * - 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
- * - The result is also an equivalence that satisfies reflexive, symmetric, and transitive properties
+ * Tuples must have the same length; different lengths are never equivalent.
+ * Each equivalence is applied to the corresponding element position. The result
+ * returns `true` only if all elements are equivalent according to their
+ * respective equivalences, and it also satisfies reflexive, symmetric, and
+ * transitive properties.
  *
  * **Example** (Homogeneous tuple equivalence)
  *
@@ -856,10 +836,7 @@ export {
    *
    * **When to use**
    *
-   * 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
+   * Use when you need to compare arrays with one equivalence for every element.
    *
    * **Details**
    *
@@ -910,18 +887,16 @@ export {
  *
  * **When to use**
  *
- * 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
+ * Use when you need an `Equivalence` for objects with known, fixed property
+ * names.
  *
  * **Details**
  *
- * - 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
- * - Supports both string and symbol keys via `Reflect.ownKeys`
- * - The result is also an equivalence that satisfies reflexive, symmetric, and transitive properties
+ * Compares only the properties specified in the struct definition; other
+ * properties are ignored. String and symbol keys are supported via
+ * `Reflect.ownKeys`. The result returns `true` only if all specified properties
+ * are equivalent according to their equivalences, and it also satisfies
+ * reflexive, symmetric, and transitive properties.
  *
  * **Example** (Struct with different equivalences per field)
  *
@@ -992,10 +967,8 @@ export function Struct<R extends Record<string, Equivalence<any>>>(
  *
  * **When to use**
  *
- * 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
+ * Use when you need to compare records with the same equivalence for every
+ * property value.
  *
  * **Details**
  *
@@ -1063,16 +1036,14 @@ 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 implementing fold operations over collections of equivalences
- * - Use when working with reducers that operate on equivalences
+ * Use when you need a reducer that combines equivalences.
  *
  * **Details**
  *
- * - Returns a reducer that combines equivalences using {@link combine}
- * - Uses an equivalence that always returns `true` as the identity element for empty collections
- * - Uses {@link combineAll} for combining collections of equivalences
- * - The reducer can be used with fold operations on collections
+ * Returns a reducer that combines equivalences using `combine`. The identity
+ * element for empty collections is an equivalence that always returns `true`.
+ * The reducer uses `combineAll` for collections of equivalences and can be used
+ * with fold operations.
  *
  * **Example** (Creating a Reducer)
  *
@@ -1110,7 +1081,8 @@ export function makeReducer<A>() {
  *
  * **When to use**
  *
- * Use when comparing `Date` values by their millisecond timestamp.
+ * Use when you need an `Equivalence` for JavaScript date objects by their
+ * millisecond timestamp.
  *
  * **Details**
  *

package/src/ErrorReporter.ts

@@ -199,7 +199,7 @@ export const make = (
  *
  * **When to use**
  *
- * Use when low-level code needs to read or replace the current set of reporters
+ * Use when you need to read or replace the current set of error reporters
  * directly.
  *
  * @category references