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

package/dist/Equivalence.d.ts

@@ -5,9 +5,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**
  *
@@ -52,9 +50,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**
  *
@@ -90,15 +86,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)
  *
@@ -139,16 +135,14 @@ export declare const make: <A>(isEquivalent: (self: A, that: A) => boolean) => E
  *
  * **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**
  *
@@ -189,7 +183,7 @@ export declare const strictEqual: <A>() => Equivalence<A>;
  *
  * **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)
  *
@@ -209,12 +203,7 @@ export declare const String: Equivalence<string>;
  *
  * **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)
  *
@@ -235,7 +224,7 @@ export declare const Number: Equivalence<number>;
  *
  * **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)
  *
@@ -255,7 +244,7 @@ export declare const Boolean: Equivalence<boolean>;
  *
  * **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)
  *
@@ -275,15 +264,14 @@ export declare const BigInt: Equivalence<bigint>;
  *
  * **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)
  *
@@ -326,15 +314,14 @@ export declare 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)
      *
@@ -377,15 +364,14 @@ export declare 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)
      *
@@ -429,17 +415,15 @@ export declare 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)
  *
@@ -496,10 +480,7 @@ export declare const combineAll: <A>(collection: Iterable<Equivalence<A>>) => Eq
  *
  * **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**
  *
@@ -507,6 +488,8 @@ export declare const combineAll: <A>(collection: Iterable<Equivalence<A>>) => Eq
  * - 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)
  *
@@ -558,10 +541,7 @@ export declare 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**
      *
@@ -569,6 +549,8 @@ export declare 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)
      *
@@ -620,10 +602,7 @@ export declare 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**
      *
@@ -631,6 +610,8 @@ export declare 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)
      *
@@ -683,17 +664,16 @@ export declare 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)
  *
@@ -751,10 +731,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**
  *
@@ -803,18 +780,16 @@ Array_ as Array };
  *
  * **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)
  *
@@ -876,10 +851,8 @@ export declare function Struct<R extends Record<string, Equivalence<any>>>(field
  *
  * **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**
  *
@@ -931,16 +904,14 @@ export declare function Record<A>(value: Equivalence<A>): Equivalence<Record<Pro
  *
  * **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)
  *
@@ -971,7 +942,8 @@ export declare function makeReducer<A>(): Reducer.Reducer<Equivalence<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/dist/Equivalence.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Equivalence.d.ts","sourceRoot":"","sources":["../src/Equivalence.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Equivalence.d.ts","sourceRoot":"","sources":["../src/Equivalence.ts"],"names":[],"mappings":"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"}

package/dist/Equivalence.js

@@ -58,15 +58,15 @@ import * as Reducer from "./Reducer.js";
  *
  * **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)
  *
@@ -108,16 +108,14 @@ const isStrictEquivalent = (x, y) => 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**
  *
@@ -158,7 +156,7 @@ export const strictEqual = () => 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)
  *
@@ -178,12 +176,7 @@ export const 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)
  *
@@ -204,7 +197,7 @@ export const Number = /*#__PURE__*/make((self, that) => globalThis.Number.isNaN(
  *
  * **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)
  *
@@ -224,7 +217,7 @@ export const 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)
  *
@@ -244,15 +237,14 @@ export const 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)
  *
@@ -295,17 +287,15 @@ export const combine = /*#__PURE__*/dual(2, (self, that) => make((x, y) => self(
  *
  * **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)
  *
@@ -369,10 +359,7 @@ export const combineAll = collection => make((x, y) => {
  *
  * **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**
  *
@@ -380,6 +367,8 @@ export const combineAll = collection => make((x, y) => {
  * - 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)
  *
@@ -431,17 +420,16 @@ export const mapInput = /*#__PURE__*/dual(2, (self, f) => make((x, y) => self(f(
  *
  * **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)
  *
@@ -517,10 +505,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**
  *
@@ -569,18 +554,16 @@ Array_ as Array };
  *
  * **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)
  *
@@ -648,10 +631,8 @@ export function Struct(fields) {
  *
  * **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**
  *
@@ -715,16 +696,14 @@ export function Record(value) {
  *
  * **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)
  *
@@ -757,7 +736,8 @@ export function makeReducer() {
  *
  * **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**
  *