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

package/dist/Record.d.ts

@@ -1,5 +1,76 @@
 /**
- * This module provides utility functions for working with records in TypeScript.
+ * Tools for working with plain JavaScript records as immutable key-value
+ * dictionaries. The module covers construction, lookup, updates, mapping,
+ * filtering, folding, set-like combination, and typed conversions between
+ * records and iterable entries.
+ *
+ * Reach for `Record` when your data is already represented as a plain object
+ * with string or symbol keys and you want typed, data-first or data-last
+ * helpers that return new records instead of mutating the input.
+ *
+ * **Mental model**
+ *
+ * - A `ReadonlyRecord<K, A>` is a plain object whose keys are known by type and
+ *   whose values share a common type.
+ * - Operations such as {@link set}, {@link remove}, {@link map}, and
+ *   {@link filter} allocate new plain objects.
+ * - Lookups and updates that might miss a key return `Option` values through
+ *   APIs such as {@link get}, {@link modify}, {@link replace}, and {@link pop}.
+ * - Many APIs are dual, so they work both as `Record.map(record, f)` and in
+ *   pipelines as `pipe(record, Record.map(f))`.
+ *
+ * **Common tasks**
+ *
+ * - Create records: {@link empty}, {@link singleton}, {@link fromEntries},
+ *   {@link fromIterableBy}, {@link fromIterableWith}
+ * - Inspect records: {@link isEmptyRecord}, {@link size}, {@link has},
+ *   {@link get}, {@link keys}, {@link values}, {@link toEntries}
+ * - Add, update, or remove entries: {@link set}, {@link modify},
+ *   {@link replace}, {@link remove}, {@link pop}
+ * - Transform entries: {@link map}, {@link mapKeys}, {@link mapEntries},
+ *   {@link collect}
+ * - Filter or partition: {@link filter}, {@link filterMap}, {@link getSomes},
+ *   {@link getFailures}, {@link getSuccesses}, {@link partition},
+ *   {@link separate}
+ * - Fold and search: {@link reduce}, {@link every}, {@link some},
+ *   {@link findFirst}
+ * - Combine records: {@link union}, {@link intersection}, {@link difference},
+ *   {@link makeReducerUnion}, {@link makeReducerIntersection}
+ * - Compare records: {@link isSubrecord}, {@link isSubrecordBy},
+ *   {@link makeEquivalence}
+ *
+ * **Gotchas**
+ *
+ * - Iteration-based APIs use `Object.keys`, so they visit enumerable string
+ *   keys. Targeted APIs such as {@link has}, {@link get}, {@link set}, and
+ *   {@link remove} can work with symbol keys, but {@link keys}, {@link values},
+ *   {@link map}, and similar traversal APIs do not visit symbols.
+ * - When duplicate keys are produced by constructors or key-mapping APIs, later
+ *   writes overwrite earlier values according to normal object assignment.
+ *
+ * **Quickstart**
+ *
+ * **Example** (Transforming a record without mutation)
+ *
+ * ```ts
+ * import { Record } from "effect"
+ *
+ * const scores = { alice: 1, bob: 2 }
+ *
+ * const next = Record.set(scores, "carol", 3)
+ * const doubled = Record.map(next, (score) => score * 2)
+ *
+ * console.log(scores) // { alice: 1, bob: 2 }
+ * console.log(doubled) // { alice: 2, bob: 4, carol: 6 }
+ * console.log(Record.get(doubled, "alice")) // Option.some(2)
+ * ```
+ *
+ * **See also**
+ *
+ * - `Struct` for fixed-shape objects where each field may have a
+ *   different type
+ * - `HashMap` for immutable maps with arbitrary key types and Effect
+ *   equality / hashing semantics
  *
  * @since 2.0.0
  */
@@ -148,7 +219,7 @@ export interface ReadonlyRecordTypeLambda<K extends string = string> extends Typ
  */
 export declare const empty: <K extends string | symbol = never, V = never>() => Record<ReadonlyRecord.NonLiteralKey<K>, V>;
 /**
- * Determine if a record is empty.
+ * Determines if a mutable record is empty.
  *
  * **Example** (Checking for an empty record)
  *
@@ -165,7 +236,7 @@ export declare const empty: <K extends string | symbol = never, V = never>() =>
  */
 export declare const isEmptyRecord: <K extends string, A>(self: Record<K, A>) => self is Record<K, never>;
 /**
- * Determine if a record is empty.
+ * Determines if a readonly record is empty.
  *
  * **Example** (Checking for an empty readonly record)
  *
@@ -393,7 +464,7 @@ export declare const toEntries: <K extends string, A>(self: ReadonlyRecord<K, A>
  */
 export declare const size: <K extends string, A>(self: ReadonlyRecord<K, A>) => number;
 /**
- * Check if a given `key` exists in a record.
+ * Checks whether a given `key` exists in a record.
  *
  * **Example** (Checking key membership)
  *
@@ -410,7 +481,7 @@ export declare const size: <K extends string, A>(self: ReadonlyRecord<K, A>) =>
  */
 export declare const has: {
     /**
-     * Check if a given `key` exists in a record.
+     * Checks whether a given `key` exists in a record.
      *
      * **Example** (Checking key membership)
      *
@@ -427,7 +498,7 @@ export declare const has: {
      */
     <K extends string | symbol>(key: NoInfer<K>): <A>(self: ReadonlyRecord<K, A>) => boolean;
     /**
-     * Check if a given `key` exists in a record.
+     * Checks whether a given `key` exists in a record.
      *
      * **Example** (Checking key membership)
      *
@@ -445,7 +516,7 @@ export declare const has: {
     <K extends string | symbol, A>(self: ReadonlyRecord<K, A>, key: NoInfer<K>): boolean;
 };
 /**
- * Retrieve a value at a particular key from a record, returning it wrapped in an `Option`.
+ * Retrieves a value at a particular key from a record safely, returning it wrapped in an `Option`.
  *
  * **Example** (Getting a value as an Option)
  *
@@ -464,7 +535,7 @@ export declare const has: {
  */
 export declare const get: {
     /**
-     * Retrieve a value at a particular key from a record, returning it wrapped in an `Option`.
+     * Retrieves a value at a particular key from a record safely, returning it wrapped in an `Option`.
      *
      * **Example** (Getting a value as an Option)
      *
@@ -483,7 +554,7 @@ export declare const get: {
      */
     <K extends string | symbol>(key: NoInfer<K>): <A>(self: ReadonlyRecord<K, A>) => Option.Option<A>;
     /**
-     * Retrieve a value at a particular key from a record, returning it wrapped in an `Option`.
+     * Retrieves a value at a particular key from a record safely, returning it wrapped in an `Option`.
      *
      * **Example** (Getting a value as an Option)
      *
@@ -503,7 +574,7 @@ export declare const get: {
     <K extends string | symbol, A>(self: ReadonlyRecord<K, A>, key: NoInfer<K>): Option.Option<A>;
 };
 /**
- * Apply a function to the element at the specified key, creating a new record,
+ * Applies a function to the element at the specified key safely, creating a new record,
  * or return `Option.none()` if the key doesn't exist.
  *
  * **Example** (Modifying a value at a key)
@@ -524,7 +595,7 @@ export declare const get: {
  */
 export declare const modify: {
     /**
-     * Apply a function to the element at the specified key, creating a new record,
+     * Applies a function to the element at the specified key safely, creating a new record,
      * or return `Option.none()` if the key doesn't exist.
      *
      * **Example** (Modifying a value at a key)
@@ -545,7 +616,7 @@ export declare const modify: {
      */
     <K extends string | symbol, A, B>(key: NoInfer<K>, f: (a: A) => B): (self: ReadonlyRecord<K, A>) => Option.Option<Record<K, A | B>>;
     /**
-     * Apply a function to the element at the specified key, creating a new record,
+     * Applies a function to the element at the specified key safely, creating a new record,
      * or return `Option.none()` if the key doesn't exist.
      *
      * **Example** (Modifying a value at a key)
@@ -567,7 +638,7 @@ export declare const modify: {
     <K extends string | symbol, A, B>(self: ReadonlyRecord<K, A>, key: NoInfer<K>, f: (a: A) => B): Option.Option<Record<K, A | B>>;
 };
 /**
- * Replaces the value at an existing key and returns the updated record in
+ * Replaces the value at an existing key safely and returns the updated record in
  * `Option.some`.
  *
  * **Details**
@@ -589,7 +660,7 @@ export declare const modify: {
  */
 export declare const replace: {
     /**
-     * Replaces the value at an existing key and returns the updated record in
+     * Replaces the value at an existing key safely and returns the updated record in
      * `Option.some`.
      *
      * **Details**
@@ -611,7 +682,7 @@ export declare const replace: {
      */
     <K extends string | symbol, B>(key: NoInfer<K>, b: B): <A>(self: ReadonlyRecord<K, A>) => Option.Option<Record<K, A | B>>;
     /**
-     * Replaces the value at an existing key and returns the updated record in
+     * Replaces the value at an existing key safely and returns the updated record in
      * `Option.some`.
      *
      * **Details**
@@ -634,8 +705,16 @@ export declare const replace: {
     <K extends string | symbol, A, B>(self: ReadonlyRecord<K, A>, key: NoInfer<K>, b: B): Option.Option<Record<K, A | B>>;
 };
 /**
- * If the given key exists in the record, returns a new record with the key removed.
- * If the key does not exist, returns a shallow copy of the original record.
+ * Removes a key from a record.
+ *
+ * **When to use**
+ *
+ * Use to create a shallow copy of a record without one property.
+ *
+ * **Details**
+ *
+ * If the key is not present, the result is still a shallow copy of the original
+ * record.
  *
  * **Example** (Removing a key)
  *
@@ -651,8 +730,16 @@ export declare const replace: {
  */
 export declare const remove: {
     /**
-     * If the given key exists in the record, returns a new record with the key removed.
-     * If the key does not exist, returns a shallow copy of the original record.
+     * Removes a key from a record.
+     *
+     * **When to use**
+     *
+     * Use to create a shallow copy of a record without one property.
+     *
+     * **Details**
+     *
+     * If the key is not present, the result is still a shallow copy of the original
+     * record.
      *
      * **Example** (Removing a key)
      *
@@ -668,8 +755,16 @@ export declare const remove: {
      */
     <K extends string | symbol, X extends K>(key: X): <A>(self: ReadonlyRecord<K, A>) => Record<Exclude<K, X>, A>;
     /**
-     * If the given key exists in the record, returns a new record with the key removed.
-     * If the key does not exist, returns a shallow copy of the original record.
+     * Removes a key from a record.
+     *
+     * **When to use**
+     *
+     * Use to create a shallow copy of a record without one property.
+     *
+     * **Details**
+     *
+     * If the key is not present, the result is still a shallow copy of the original
+     * record.
      *
      * **Example** (Removing a key)
      *
@@ -686,7 +781,7 @@ export declare const remove: {
     <K extends string | symbol, A, X extends K>(self: ReadonlyRecord<K, A>, key: X): Record<Exclude<K, X>, A>;
 };
 /**
- * Retrieves the value of the property with the given `key` from a record and returns an `Option`
+ * Retrieves the value of the property with the given `key` from a record safely and returns an `Option`
  * of a tuple with the value and the record with the removed property.
  * If the key is not present, returns `Option.none()`.
  *
@@ -706,7 +801,7 @@ export declare const remove: {
  */
 export declare const pop: {
     /**
-     * Retrieves the value of the property with the given `key` from a record and returns an `Option`
+     * Retrieves the value of the property with the given `key` from a record safely and returns an `Option`
      * of a tuple with the value and the record with the removed property.
      * If the key is not present, returns `Option.none()`.
      *
@@ -726,7 +821,7 @@ export declare const pop: {
      */
     <K extends string | symbol, X extends K>(key: X): <A>(self: ReadonlyRecord<K, A>) => Option.Option<[A, Record<Exclude<K, X>, A>]>;
     /**
-     * Retrieves the value of the property with the given `key` from a record and returns an `Option`
+     * Retrieves the value of the property with the given `key` from a record safely and returns an `Option`
      * of a tuple with the value and the record with the removed property.
      * If the key is not present, returns `Option.none()`.
      *
@@ -1074,7 +1169,8 @@ export declare const filter: {
     <K extends string, A>(self: ReadonlyRecord<K, A>, predicate: (a: A, key: K) => boolean): Record<ReadonlyRecord.NonLiteralKey<K>, A>;
 };
 /**
- * Given a record with `Option` values, returns a new record containing only the `Some` values, preserving the original keys.
+ * Returns a new record containing only the `Some` values from a record of
+ * `Option` values, preserving the original keys.
  *
  * **Example** (Extracting Some values)
  *
@@ -1093,7 +1189,8 @@ export declare const filter: {
  */
 export declare const getSomes: <K extends string, A>(self: ReadonlyRecord<K, Option.Option<A>>) => Record<ReadonlyRecord.NonLiteralKey<K>, A>;
 /**
- * Given a record with `Result` values, returns a new record containing only the `Err` values, preserving the original keys.
+ * Returns a new record containing only the `Err` values from a record of
+ * `Result` values, preserving the original keys.
  *
  * **Example** (Extracting Result failures)
  *
@@ -1116,7 +1213,8 @@ export declare const getSomes: <K extends string, A>(self: ReadonlyRecord<K, Opt
  */
 export declare const getFailures: <K extends string, A, E>(self: ReadonlyRecord<K, Result<A, E>>) => Record<ReadonlyRecord.NonLiteralKey<K>, E>;
 /**
- * Given a record with `Result` values, returns a new record containing only the `Ok` values, preserving the original keys.
+ * Returns a new record containing only the `Ok` values from a record of
+ * `Result` values, preserving the original keys.
  *
  * **Example** (Extracting Result successes)
  *
@@ -1232,7 +1330,7 @@ export declare const partition: {
  */
 export declare const separate: <K extends string, A, B>(self: ReadonlyRecord<K, Result<B, A>>) => [Record<ReadonlyRecord.NonLiteralKey<K>, A>, Record<ReadonlyRecord.NonLiteralKey<K>, B>];
 /**
- * Retrieve the keys of a given record as an array.
+ * Retrieves the keys of a given record as an array.
  *
  * **Example** (Getting record keys)
  *
@@ -1248,7 +1346,7 @@ export declare const separate: <K extends string, A, B>(self: ReadonlyRecord<K,
  */
 export declare const keys: <K extends string | symbol, A>(self: ReadonlyRecord<K, A>) => Array<K & string>;
 /**
- * Retrieve the values of a given record as an array.
+ * Retrieves the values of a given record as an array.
  *
  * **Example** (Getting record values)
  *
@@ -1264,7 +1362,7 @@ export declare const keys: <K extends string | symbol, A>(self: ReadonlyRecord<K
  */
 export declare const values: <K extends string, A>(self: ReadonlyRecord<K, A>) => Array<A>;
 /**
- * Add a new key-value pair or update an existing key's value in a record.
+ * Adds a new key-value pair or update an existing key's value in a record.
  *
  * **Example** (Setting a record value)
  *
@@ -1281,7 +1379,7 @@ export declare const values: <K extends string, A>(self: ReadonlyRecord<K, A>) =
  */
 export declare const set: {
     /**
-     * Add a new key-value pair or update an existing key's value in a record.
+     * Adds a new key-value pair or update an existing key's value in a record.
      *
      * **Example** (Setting a record value)
      *
@@ -1298,7 +1396,7 @@ export declare const set: {
      */
     <K extends string | symbol, K1 extends K | ((string | symbol) & {}), B>(key: K1, value: B): <A>(self: ReadonlyRecord<K, A>) => Record<K | K1, A | B>;
     /**
-     * Add a new key-value pair or update an existing key's value in a record.
+     * Adds a new key-value pair or update an existing key's value in a record.
      *
      * **Example** (Setting a record value)
      *
@@ -1316,7 +1414,7 @@ export declare const set: {
     <K extends string | symbol, A, K1 extends K | ((string | symbol) & {}), B>(self: ReadonlyRecord<K, A>, key: K1, value: B): Record<K | K1, A | B>;
 };
 /**
- * Check if all the keys and values in one record are also found in another record.
+ * Checks whether all the keys and values in one record are also found in another record.
  * Uses the provided equivalence function to compare values.
  *
  * **Example** (Checking subrecords with a custom equivalence)
@@ -1438,7 +1536,7 @@ export declare const isSubrecord: {
     <K extends string, A>(self: ReadonlyRecord<K, A>, that: ReadonlyRecord<K, A>): boolean;
 };
 /**
- * Reduce a record to a single value by combining its entries with a specified function.
+ * Reduces a record to a single value by combining its entries with a specified function.
  *
  * **Example** (Reducing record values)
  *
@@ -1457,7 +1555,7 @@ export declare const isSubrecord: {
  */
 export declare const reduce: {
     /**
-     * Reduce a record to a single value by combining its entries with a specified function.
+     * Reduces a record to a single value by combining its entries with a specified function.
      *
      * **Example** (Reducing record values)
      *
@@ -1476,7 +1574,7 @@ export declare const reduce: {
      */
     <Z, V, K extends string>(zero: Z, f: (accumulator: Z, value: V, key: K) => Z): (self: ReadonlyRecord<K, V>) => Z;
     /**
-     * Reduce a record to a single value by combining its entries with a specified function.
+     * Reduces a record to a single value by combining its entries with a specified function.
      *
      * **Example** (Reducing record values)
      *
@@ -1496,7 +1594,7 @@ export declare const reduce: {
     <K extends string, V, Z>(self: ReadonlyRecord<K, V>, zero: Z, f: (accumulator: Z, value: V, key: K) => Z): Z;
 };
 /**
- * Check if all entries in a record meet a specific condition.
+ * Checks whether all entries in a record meet a specific condition.
  *
  * **Example** (Checking every record value)
  *
@@ -1513,7 +1611,7 @@ export declare const reduce: {
  */
 export declare const every: {
     /**
-     * Check if all entries in a record meet a specific condition.
+     * Checks whether all entries in a record meet a specific condition.
      *
      * **Example** (Checking every record value)
      *
@@ -1530,7 +1628,7 @@ export declare const every: {
      */
     <A, K extends string, B extends A>(refinement: (value: A, key: K) => value is B): (self: ReadonlyRecord<K, A>) => self is ReadonlyRecord<K, B>;
     /**
-     * Check if all entries in a record meet a specific condition.
+     * Checks whether all entries in a record meet a specific condition.
      *
      * **Example** (Checking every record value)
      *
@@ -1547,7 +1645,7 @@ export declare const every: {
      */
     <A, K extends string>(predicate: (value: A, key: K) => boolean): (self: ReadonlyRecord<K, A>) => boolean;
     /**
-     * Check if all entries in a record meet a specific condition.
+     * Checks whether all entries in a record meet a specific condition.
      *
      * **Example** (Checking every record value)
      *
@@ -1564,7 +1662,7 @@ export declare const every: {
      */
     <A, K extends string, B extends A>(self: ReadonlyRecord<K, A>, refinement: (value: A, key: K) => value is B): self is ReadonlyRecord<K, B>;
     /**
-     * Check if all entries in a record meet a specific condition.
+     * Checks whether all entries in a record meet a specific condition.
      *
      * **Example** (Checking every record value)
      *
@@ -1582,7 +1680,7 @@ export declare const every: {
     <K extends string, A>(self: ReadonlyRecord<K, A>, predicate: (value: A, key: K) => boolean): boolean;
 };
 /**
- * Check if any entry in a record meets a specific condition.
+ * Checks whether any entry in a record meets a specific condition.
  *
  * **Example** (Checking for any matching value)
  *
@@ -1599,7 +1697,7 @@ export declare const every: {
  */
 export declare const some: {
     /**
-     * Check if any entry in a record meets a specific condition.
+     * Checks whether any entry in a record meets a specific condition.
      *
      * **Example** (Checking for any matching value)
      *
@@ -1616,7 +1714,7 @@ export declare const some: {
      */
     <A, K extends string>(predicate: (value: A, key: K) => boolean): (self: ReadonlyRecord<K, A>) => boolean;
     /**
-     * Check if any entry in a record meets a specific condition.
+     * Checks whether any entry in a record meets a specific condition.
      *
      * **Example** (Checking for any matching value)
      *
@@ -1634,7 +1732,7 @@ export declare const some: {
     <K extends string, A>(self: ReadonlyRecord<K, A>, predicate: (value: A, key: K) => boolean): boolean;
 };
 /**
- * Merge two records, preserving entries that exist in either of the records.
+ * Merges two records, preserving entries that exist in either of the records.
  * For keys that exist in both records, the provided combine function is used to merge the values.
  *
  * **Example** (Merging records with union)
@@ -1654,7 +1752,7 @@ export declare const some: {
  */
 export declare const union: {
     /**
-     * Merge two records, preserving entries that exist in either of the records.
+     * Merges two records, preserving entries that exist in either of the records.
      * For keys that exist in both records, the provided combine function is used to merge the values.
      *
      * **Example** (Merging records with union)
@@ -1674,7 +1772,7 @@ export declare const union: {
      */
     <K1 extends string, A, B, C>(that: ReadonlyRecord<K1, B>, combine: (selfValue: A, thatValue: B) => C): <K0 extends string>(self: ReadonlyRecord<K0, A>) => Record<K0 | K1, A | B | C>;
     /**
-     * Merge two records, preserving entries that exist in either of the records.
+     * Merges two records, preserving entries that exist in either of the records.
      * For keys that exist in both records, the provided combine function is used to merge the values.
      *
      * **Example** (Merging records with union)
@@ -1695,7 +1793,7 @@ export declare const union: {
     <K0 extends string, A, K1 extends string, B, C>(self: ReadonlyRecord<K0, A>, that: ReadonlyRecord<K1, B>, combine: (selfValue: A, thatValue: B) => C): Record<K0 | K1, A | B | C>;
 };
 /**
- * Merge two records, retaining only the entries that exist in both records.
+ * Merges two records, retaining only the entries that exist in both records.
  * For intersecting keys, the provided combine function is used to merge the values.
  *
  * **Example** (Merging intersecting keys)
@@ -1715,7 +1813,7 @@ export declare const union: {
  */
 export declare const intersection: {
     /**
-     * Merge two records, retaining only the entries that exist in both records.
+     * Merges two records, retaining only the entries that exist in both records.
      * For intersecting keys, the provided combine function is used to merge the values.
      *
      * **Example** (Merging intersecting keys)
@@ -1735,7 +1833,7 @@ export declare const intersection: {
      */
     <K1 extends string, A, B, C>(that: ReadonlyRecord<K1, B>, combine: (selfValue: A, thatValue: B) => C): <K0 extends string>(self: ReadonlyRecord<K0, A>) => Record<ReadonlyRecord.IntersectKeys<K0, K1>, C>;
     /**
-     * Merge two records, retaining only the entries that exist in both records.
+     * Merges two records, retaining only the entries that exist in both records.
      * For intersecting keys, the provided combine function is used to merge the values.
      *
      * **Example** (Merging intersecting keys)
@@ -1756,7 +1854,7 @@ export declare const intersection: {
     <K0 extends string, A, K1 extends string, B, C>(self: ReadonlyRecord<K0, A>, that: ReadonlyRecord<K1, B>, combine: (selfValue: A, thatValue: B) => C): Record<ReadonlyRecord.IntersectKeys<K0, K1>, C>;
 };
 /**
- * Merge two records, preserving only the entries that are unique to each record.
+ * Merges two records, preserving only the entries that are unique to each record.
  * Keys that exist in both records are excluded from the result.
  *
  * **Example** (Keeping keys unique to each record)
@@ -1776,7 +1874,7 @@ export declare const intersection: {
  */
 export declare const difference: {
     /**
-     * Merge two records, preserving only the entries that are unique to each record.
+     * Merges two records, preserving only the entries that are unique to each record.
      * Keys that exist in both records are excluded from the result.
      *
      * **Example** (Keeping keys unique to each record)
@@ -1796,7 +1894,7 @@ export declare const difference: {
      */
     <K1 extends string, B>(that: ReadonlyRecord<K1, B>): <K0 extends string, A>(self: ReadonlyRecord<K0, A>) => Record<K0 | K1, A | B>;
     /**
-     * Merge two records, preserving only the entries that are unique to each record.
+     * Merges two records, preserving only the entries that are unique to each record.
      * Keys that exist in both records are excluded from the result.
      *
      * **Example** (Keeping keys unique to each record)
@@ -1856,6 +1954,21 @@ export declare const singleton: <K extends string | symbol, A>(key: K, value: A)
  * Creates a `Reducer` for combining `Record`s using union, with values for keys that exist in both records combined
  * using the provided `Combiner`.
  *
+ * **When to use**
+ *
+ * Use to build a reusable reducer for accumulating many records into one
+ * union-shaped record, preserving keys from every input and combining
+ * overlapping values with the supplied combiner.
+ *
+ * **Details**
+ *
+ * The returned reducer uses `Record.union` for combine and an empty record as
+ * `initialValue`, so the default `combineAll` folds from `{}` and accumulates
+ * keys from each input record.
+ *
+ * @see {@link union} for one-off record merging with the same union semantics
+ * @see {@link makeReducerIntersection} for a reducer that keeps only keys present on both sides
+ *
  * @category combining
  * @since 4.0.0
  */
@@ -1864,12 +1977,20 @@ export declare function makeReducerUnion<K extends string, A>(combiner: Combiner
  * Creates a `Reducer` whose `combine` operation intersects two records and
  * combines values for keys present in both records.
  *
+ * **When to use**
+ *
+ * Use to build a `Reducer` that combines records by retaining only keys shared
+ * by both inputs and combining matching values with a `Combiner`.
+ *
  * **Gotchas**
  *
  * The reducer's `initialValue` is an empty record. Because intersection with
  * an empty record is empty, the default `combineAll` folds from `{}` and
  * therefore produces `{}` for ordinary non-empty inputs.
  *
+ * @see {@link makeReducerUnion} for a reducer that preserves keys from either input record
+ * @see {@link intersection} for applying the shared-key merge to one pair of records
+ *
  * @category combining
  * @since 4.0.0
  */