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

package/src/Record.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
  */
@@ -166,7 +237,7 @@ export const empty = <K extends string | symbol = never, V = never>(): Record<
 > => ({} as any)
 
 /**
- * Determine if a record is empty.
+ * Determines if a mutable record is empty.
  *
  * **Example** (Checking for an empty record)
  *
@@ -185,7 +256,7 @@ export const isEmptyRecord = <K extends string, A>(self: Record<K, A>): self is
   Object.keys(self).length === 0
 
 /**
- * Determine if a record is empty.
+ * Determines if a readonly record is empty.
  *
  * **Example** (Checking for an empty readonly record)
  *
@@ -452,7 +523,7 @@ export const toEntries: <K extends string, A>(self: ReadonlyRecord<K, A>) => Arr
 export const size = <K extends string, A>(self: ReadonlyRecord<K, A>): number => keys(self).length
 
 /**
- * Check if a given `key` exists in a record.
+ * Checks whether a given `key` exists in a record.
  *
  * **Example** (Checking key membership)
  *
@@ -469,7 +540,7 @@ export const size = <K extends string, A>(self: ReadonlyRecord<K, A>): number =>
  */
 export const has: {
   /**
-   * Check if a given `key` exists in a record.
+   * Checks whether a given `key` exists in a record.
    *
    * **Example** (Checking key membership)
    *
@@ -486,7 +557,7 @@ export 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)
    *
@@ -511,7 +582,7 @@ export const has: {
 )
 
 /**
- * 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)
  *
@@ -530,7 +601,7 @@ export const has: {
  */
 export 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)
    *
@@ -549,7 +620,7 @@ export 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)
    *
@@ -574,7 +645,7 @@ export const get: {
 )
 
 /**
- * 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)
@@ -595,7 +666,7 @@ export const get: {
  */
 export 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)
@@ -616,7 +687,7 @@ export 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)
@@ -649,7 +720,7 @@ export const modify: {
 )
 
 /**
- * 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**
@@ -671,7 +742,7 @@ export const modify: {
  */
 export 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**
@@ -693,7 +764,7 @@ export 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**
@@ -724,8 +795,16 @@ export const replace: {
 )
 
 /**
- * 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)
  *
@@ -741,8 +820,16 @@ export const replace: {
  */
 export 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)
    *
@@ -758,8 +845,16 @@ export 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)
    *
@@ -787,7 +882,7 @@ export const remove: {
 )
 
 /**
- * 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()`.
  *
@@ -807,7 +902,7 @@ export const remove: {
  */
 export 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()`.
    *
@@ -827,7 +922,7 @@ export 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()`.
    *
@@ -1249,7 +1344,8 @@ export const filter: {
 )
 
 /**
- * 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)
  *
@@ -1282,7 +1378,8 @@ export const getSomes: <K extends string, 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)
  *
@@ -1318,7 +1415,8 @@ export const getFailures = <K extends string, A, 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)
  *
@@ -1471,7 +1569,7 @@ export const separate: <K extends string, A, B>(
 ) => [Record<ReadonlyRecord.NonLiteralKey<K>, A>, Record<ReadonlyRecord.NonLiteralKey<K>, B>] = partition(identity)
 
 /**
- * Retrieve the keys of a given record as an array.
+ * Retrieves the keys of a given record as an array.
  *
  * **Example** (Getting record keys)
  *
@@ -1489,7 +1587,7 @@ export const keys = <K extends string | symbol, A>(self: ReadonlyRecord<K, A>):
   Object.keys(self) as 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)
  *
@@ -1506,7 +1604,7 @@ export const keys = <K extends string | symbol, A>(self: ReadonlyRecord<K, A>):
 export const values = <K extends string, A>(self: ReadonlyRecord<K, A>): Array<A> => collect(self, (_, a) => 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)
  *
@@ -1523,7 +1621,7 @@ export const values = <K extends string, A>(self: ReadonlyRecord<K, A>): Array<A
  */
 export 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)
    *
@@ -1540,7 +1638,7 @@ export 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)
    *
@@ -1568,7 +1666,7 @@ export const set: {
 )
 
 /**
- * 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)
@@ -1700,7 +1798,7 @@ export const isSubrecord: {
 } = isSubrecordBy(Equal.asEquivalence())
 
 /**
- * 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)
  *
@@ -1719,7 +1817,7 @@ export const isSubrecord: {
  */
 export 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)
    *
@@ -1738,7 +1836,7 @@ export 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)
    *
@@ -1776,7 +1874,7 @@ export const reduce: {
 )
 
 /**
- * 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)
  *
@@ -1793,7 +1891,7 @@ export const reduce: {
  */
 export 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)
    *
@@ -1810,7 +1908,7 @@ export 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)
    *
@@ -1827,7 +1925,7 @@ export 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)
    *
@@ -1844,7 +1942,7 @@ export 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)
    *
@@ -1876,7 +1974,7 @@ export const every: {
 )
 
 /**
- * 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)
  *
@@ -1893,7 +1991,7 @@ export const every: {
  */
 export 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)
    *
@@ -1910,7 +2008,7 @@ export 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)
    *
@@ -1939,7 +2037,7 @@ export const some: {
 )
 
 /**
- * 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)
@@ -1959,7 +2057,7 @@ export const some: {
  */
 export 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)
@@ -1979,7 +2077,7 @@ export 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)
@@ -2033,7 +2131,7 @@ export const union: {
 )
 
 /**
- * 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)
@@ -2053,7 +2151,7 @@ export const union: {
  */
 export 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)
@@ -2073,7 +2171,7 @@ export 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)
@@ -2117,7 +2215,7 @@ export const intersection: {
 )
 
 /**
- * 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)
@@ -2137,7 +2235,7 @@ export const intersection: {
  */
 export 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)
@@ -2157,7 +2255,7 @@ export 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)
@@ -2249,6 +2347,21 @@ export const singleton = <K extends string | symbol, A>(key: K, value: A): Recor
  * 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
  */
@@ -2263,12 +2376,20 @@ export function makeReducerUnion<K extends string, A>(combiner: Combiner.Combine
  * 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
  */