effect 4.0.0-beta.66 → 4.0.0-beta.67

package/src/Record.ts

@@ -19,7 +19,8 @@ import type { NoInfer } from "./Types.ts"
  * Represents a readonly record with keys of type `K` and values of type `A`.
  * This is the foundational type for immutable key-value mappings in Effect.
  *
- * @example
+ * **Example** (Defining a readonly record type)
+ *
  * ```ts
  * import type { Record } from "effect"
  *
@@ -43,7 +44,8 @@ export type ReadonlyRecord<in out K extends string | symbol, out A> = {
  * Namespace containing utility types for working with readonly records.
  * These types help with type-level operations on record keys and values.
  *
- * @example
+ * **Example** (Using readonly record helper types)
+ *
  * ```ts
  * import type { Record } from "effect"
  *
@@ -67,7 +69,8 @@ export declare namespace ReadonlyRecord {
    * Represents a type that converts literal string keys to generic string type and symbol keys to generic symbol type.
    * This is useful for maintaining type safety while allowing flexible key types in record operations.
    *
-   * @example
+   * **Example** (Converting literal keys to non-literal keys)
+   *
    * ```ts
    * import type { Record } from "effect"
    *
@@ -88,7 +91,8 @@ export declare namespace ReadonlyRecord {
    * Represents the intersection of two key types, handling both literal and non-literal string keys.
    * This type is used in record operations that need to compute overlapping keys.
    *
-   * @example
+   * **Example** (Intersecting record keys)
+   *
    * ```ts
    * import type { Record } from "effect"
    *
@@ -111,15 +115,23 @@ export declare namespace ReadonlyRecord {
  * Type lambda for readonly records, used in higher-kinded type operations.
  * This enables records to work with generic type constructors and functors.
  *
- * @example
- * ```ts
- * import type { Record } from "effect"
+ * **Example** (Applying a readonly record type lambda)
  *
- * // The type lambda allows records to be used as higher-kinded types
- * type RecordTypeLambda = Record.ReadonlyRecordTypeLambda<"key1" | "key2">
- *
- * // This enables mapping over the type parameter
- * type StringRecord = RecordTypeLambda["type"] // ReadonlyRecord<"key1" | "key2", Target>
+ * ```ts
+ * import type { HKT, Record } from "effect"
+ *
+ * type Settings = HKT.Kind<
+ *   Record.ReadonlyRecordTypeLambda<"port" | "retries">,
+ *   never,
+ *   never,
+ *   never,
+ *   number
+ * >
+ *
+ * const defaults: Settings = {
+ *   port: 3000,
+ *   retries: 3
+ * }
  * ```
  *
  * @category type lambdas
@@ -132,7 +144,8 @@ export interface ReadonlyRecordTypeLambda<K extends string = string> extends Typ
 /**
  * Creates a new, empty record.
  *
- * @example
+ * **Example** (Creating an empty record)
+ *
  * ```ts
  * import { Record } from "effect"
  *
@@ -156,7 +169,8 @@ export const empty = <K extends string | symbol = never, V = never>(): Record<
 /**
  * Determine if a record is empty.
  *
- * @example
+ * **Example** (Checking for an empty record)
+ *
  * ```ts
  * import { Record } from "effect"
  * import * as assert from "node:assert"
@@ -174,7 +188,8 @@ export const isEmptyRecord = <K extends string, A>(self: Record<K, A>): self is
 /**
  * Determine if a record is empty.
  *
- * @example
+ * **Example** (Checking for an empty readonly record)
+ *
  * ```ts
  * import { Record } from "effect"
  * import * as assert from "node:assert"
@@ -194,7 +209,8 @@ export const isEmptyReadonlyRecord: <K extends string, A>(
  * Takes an iterable and a projection function and returns a record.
  * The projection function maps each value of the iterable to a tuple of a key and a value, which is then added to the resulting record.
  *
- * @example
+ * **Example** (Building a record from mapped iterable values)
+ *
  * ```ts
  * import { Record } from "effect"
  * import * as assert from "node:assert"
@@ -215,7 +231,8 @@ export const fromIterableWith: {
    * Takes an iterable and a projection function and returns a record.
    * The projection function maps each value of the iterable to a tuple of a key and a value, which is then added to the resulting record.
    *
-   * @example
+   * **Example** (Building a record from mapped iterable values)
+   *
    * ```ts
    * import { Record } from "effect"
    * import * as assert from "node:assert"
@@ -236,7 +253,8 @@ export const fromIterableWith: {
    * Takes an iterable and a projection function and returns a record.
    * The projection function maps each value of the iterable to a tuple of a key and a value, which is then added to the resulting record.
    *
-   * @example
+   * **Example** (Building a record from mapped iterable values)
+   *
    * ```ts
    * import { Record } from "effect"
    * import * as assert from "node:assert"
@@ -271,7 +289,8 @@ export const fromIterableWith: {
 /**
  * Creates a new record from an iterable, utilizing the provided function to determine the key for each element.
  *
- * @example
+ * **Example** (Building a record keyed by iterable values)
+ *
  * ```ts
  * import { Record } from "effect"
  * import * as assert from "node:assert"
@@ -304,7 +323,8 @@ export const fromIterableBy = <A, K extends string | symbol>(
  * If there are conflicting keys when using `fromEntries`, the last occurrence of the key/value pair will overwrite the
  * previous ones. So the resulting record will only have the value of the last occurrence of each key.
  *
- * @example
+ * **Example** (Building a record from entries)
+ *
  * ```ts
  * import { Record } from "effect"
  * import * as assert from "node:assert"
@@ -314,8 +334,8 @@ export const fromIterableBy = <A, K extends string | symbol>(
  * assert.deepStrictEqual(Record.fromEntries(input), { a: 1, b: 2 })
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const fromEntries: <Entry extends readonly [string | symbol, any]>(
   entries: Iterable<Entry>
@@ -324,7 +344,8 @@ export const fromEntries: <Entry extends readonly [string | symbol, any]>(
 /**
  * Transforms the values of a record into an `Array` with a custom mapping function.
  *
- * @example
+ * **Example** (Collecting mapped record values)
+ *
  * ```ts
  * import { Record } from "effect"
  * import * as assert from "node:assert"
@@ -343,7 +364,8 @@ export const collect: {
   /**
    * Transforms the values of a record into an `Array` with a custom mapping function.
    *
-   * @example
+   * **Example** (Collecting mapped record values)
+   *
    * ```ts
    * import { Record } from "effect"
    * import * as assert from "node:assert"
@@ -362,7 +384,8 @@ export const collect: {
   /**
    * Transforms the values of a record into an `Array` with a custom mapping function.
    *
-   * @example
+   * **Example** (Collecting mapped record values)
+   *
    * ```ts
    * import { Record } from "effect"
    * import * as assert from "node:assert"
@@ -392,7 +415,8 @@ export const collect: {
 /**
  * Takes a record and returns an array of tuples containing its keys and values.
  *
- * @example
+ * **Example** (Converting a record to entries)
+ *
  * ```ts
  * import { Record } from "effect"
  * import * as assert from "node:assert"
@@ -412,7 +436,8 @@ export const toEntries: <K extends string, A>(self: ReadonlyRecord<K, A>) => Arr
 /**
  * Returns the number of key/value pairs in a record.
  *
- * @example
+ * **Example** (Getting the record size)
+ *
  * ```ts
  * import { Record } from "effect"
  * import * as assert from "node:assert"
@@ -428,7 +453,8 @@ export const size = <K extends string, A>(self: ReadonlyRecord<K, A>): number =>
 /**
  * Check if a given `key` exists in a record.
  *
- * @example
+ * **Example** (Checking key membership)
+ *
  * ```ts
  * import { Record } from "effect"
  * import * as assert from "node:assert"
@@ -444,7 +470,8 @@ export const has: {
   /**
    * Check if a given `key` exists in a record.
    *
-   * @example
+   * **Example** (Checking key membership)
+   *
    * ```ts
    * import { Record } from "effect"
    * import * as assert from "node:assert"
@@ -460,7 +487,8 @@ export const has: {
   /**
    * Check if a given `key` exists in a record.
    *
-   * @example
+   * **Example** (Checking key membership)
+   *
    * ```ts
    * import { Record } from "effect"
    * import * as assert from "node:assert"
@@ -484,7 +512,8 @@ export const has: {
 /**
  * Retrieve a value at a particular key from a record, returning it wrapped in an `Option`.
  *
- * @example
+ * **Example** (Getting a value as an Option)
+ *
  * ```ts
  * import { Option, Record as R } from "effect"
  * import * as assert from "node:assert"
@@ -502,7 +531,8 @@ export const get: {
   /**
    * Retrieve a value at a particular key from a record, returning it wrapped in an `Option`.
    *
-   * @example
+   * **Example** (Getting a value as an Option)
+   *
    * ```ts
    * import { Option, Record as R } from "effect"
    * import * as assert from "node:assert"
@@ -520,7 +550,8 @@ export const get: {
   /**
    * Retrieve a value at a particular key from a record, returning it wrapped in an `Option`.
    *
-   * @example
+   * **Example** (Getting a value as an Option)
+   *
    * ```ts
    * import { Option, Record as R } from "effect"
    * import * as assert from "node:assert"
@@ -545,7 +576,8 @@ export const get: {
  * Apply a function to the element at the specified key, creating a new record,
  * or return `Option.none()` if the key doesn't exist.
  *
- * @example
+ * **Example** (Modifying a value at a key)
+ *
  * ```ts
  * import { Record } from "effect"
  *
@@ -565,7 +597,8 @@ export const modify: {
    * Apply a function to the element at the specified key, creating a new record,
    * or return `Option.none()` if the key doesn't exist.
    *
-   * @example
+   * **Example** (Modifying a value at a key)
+   *
    * ```ts
    * import { Record } from "effect"
    *
@@ -585,7 +618,8 @@ export const modify: {
    * Apply a function to the element at the specified key, creating a new record,
    * or return `Option.none()` if the key doesn't exist.
    *
-   * @example
+   * **Example** (Modifying a value at a key)
+   *
    * ```ts
    * import { Record } from "effect"
    *
@@ -614,9 +648,14 @@ export const modify: {
 )
 
 /**
- * Replaces a value in the record with the new value passed as parameter.
+ * Replaces the value at an existing key and returns the updated record in
+ * `Option.some`.
+ *
+ * If the key is not present, returns `Option.none()` and leaves the record
+ * unchanged.
+ *
+ * **Example** (Replacing a value at a key)
  *
- * @example
  * ```ts
  * import { Record } from "effect"
  *
@@ -629,9 +668,14 @@ export const modify: {
  */
 export const replace: {
   /**
-   * Replaces a value in the record with the new value passed as parameter.
+   * Replaces the value at an existing key and returns the updated record in
+   * `Option.some`.
+   *
+   * If the key is not present, returns `Option.none()` and leaves the record
+   * unchanged.
+   *
+   * **Example** (Replacing a value at a key)
    *
-   * @example
    * ```ts
    * import { Record } from "effect"
    *
@@ -644,9 +688,14 @@ 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 a value in the record with the new value passed as parameter.
+   * Replaces the value at an existing key and returns the updated record in
+   * `Option.some`.
+   *
+   * If the key is not present, returns `Option.none()` and leaves the record
+   * unchanged.
+   *
+   * **Example** (Replacing a value at a key)
    *
-   * @example
    * ```ts
    * import { Record } from "effect"
    *
@@ -671,7 +720,8 @@ 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.
  *
- * @example
+ * **Example** (Removing a key)
+ *
  * ```ts
  * import { Record } from "effect"
  * import * as assert from "node:assert"
@@ -687,7 +737,8 @@ 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.
    *
-   * @example
+   * **Example** (Removing a key)
+   *
    * ```ts
    * import { Record } from "effect"
    * import * as assert from "node:assert"
@@ -703,7 +754,8 @@ 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.
    *
-   * @example
+   * **Example** (Removing a key)
+   *
    * ```ts
    * import { Record } from "effect"
    * import * as assert from "node:assert"
@@ -732,7 +784,8 @@ export const remove: {
  * of a tuple with the value and the record with the removed property.
  * If the key is not present, returns `Option.none()`.
  *
- * @example
+ * **Example** (Popping a value and removing its key)
+ *
  * ```ts
  * import { Record } from "effect"
  *
@@ -751,7 +804,8 @@ export const pop: {
    * of a tuple with the value and the record with the removed property.
    * If the key is not present, returns `Option.none()`.
    *
-   * @example
+   * **Example** (Popping a value and removing its key)
+   *
    * ```ts
    * import { Record } from "effect"
    *
@@ -770,7 +824,8 @@ export const pop: {
    * of a tuple with the value and the record with the removed property.
    * If the key is not present, returns `Option.none()`.
    *
-   * @example
+   * **Example** (Popping a value and removing its key)
+   *
    * ```ts
    * import { Record } from "effect"
    *
@@ -793,7 +848,8 @@ export const pop: {
 /**
  * Maps a record into another record by applying a transformation function to each of its values.
  *
- * @example
+ * **Example** (Mapping record values)
+ *
  * ```ts
  * import { Record } from "effect"
  * import * as assert from "node:assert"
@@ -814,7 +870,8 @@ export const map: {
   /**
    * Maps a record into another record by applying a transformation function to each of its values.
    *
-   * @example
+   * **Example** (Mapping record values)
+   *
    * ```ts
    * import { Record } from "effect"
    * import * as assert from "node:assert"
@@ -835,7 +892,8 @@ export const map: {
   /**
    * Maps a record into another record by applying a transformation function to each of its values.
    *
-   * @example
+   * **Example** (Mapping record values)
+   *
    * ```ts
    * import { Record } from "effect"
    * import * as assert from "node:assert"
@@ -867,7 +925,8 @@ export const map: {
 /**
  * Maps the keys of a `ReadonlyRecord` while preserving the corresponding values.
  *
- * @example
+ * **Example** (Mapping record keys)
+ *
  * ```ts
  * import { Record } from "effect"
  * import * as assert from "node:assert"
@@ -885,7 +944,8 @@ export const mapKeys: {
   /**
    * Maps the keys of a `ReadonlyRecord` while preserving the corresponding values.
    *
-   * @example
+   * **Example** (Mapping record keys)
+   *
    * ```ts
    * import { Record } from "effect"
    * import * as assert from "node:assert"
@@ -903,7 +963,8 @@ export const mapKeys: {
   /**
    * Maps the keys of a `ReadonlyRecord` while preserving the corresponding values.
    *
-   * @example
+   * **Example** (Mapping record keys)
+   *
    * ```ts
    * import { Record } from "effect"
    * import * as assert from "node:assert"
@@ -936,7 +997,8 @@ export const mapKeys: {
 /**
  * Maps entries of a `ReadonlyRecord` using the provided function, allowing modification of both keys and corresponding values.
  *
- * @example
+ * **Example** (Mapping record entries)
+ *
  * ```ts
  * import { Record } from "effect"
  * import * as assert from "node:assert"
@@ -954,7 +1016,8 @@ export const mapEntries: {
   /**
    * Maps entries of a `ReadonlyRecord` using the provided function, allowing modification of both keys and corresponding values.
    *
-   * @example
+   * **Example** (Mapping record entries)
+   *
    * ```ts
    * import { Record } from "effect"
    * import * as assert from "node:assert"
@@ -972,7 +1035,8 @@ export const mapEntries: {
   /**
    * Maps entries of a `ReadonlyRecord` using the provided function, allowing modification of both keys and corresponding values.
    *
-   * @example
+   * **Example** (Mapping record entries)
+   *
    * ```ts
    * import { Record } from "effect"
    * import * as assert from "node:assert"
@@ -1006,7 +1070,8 @@ export const mapEntries: {
  * Transforms a record by applying the function `f` to each key and value in the original record.
  * If the function succeeds, the key-value pair is included in the output record.
  *
- * @example
+ * **Example** (Filtering and mapping with Result)
+ *
  * ```ts
  * import { Record, Result } from "effect"
  * import * as assert from "node:assert"
@@ -1024,7 +1089,8 @@ export const filterMap: {
    * Transforms a record by applying the function `f` to each key and value in the original record.
    * If the function succeeds, the key-value pair is included in the output record.
    *
-   * @example
+   * **Example** (Filtering and mapping with Result)
+   *
    * ```ts
    * import { Record, Result } from "effect"
    * import * as assert from "node:assert"
@@ -1042,7 +1108,8 @@ export const filterMap: {
    * Transforms a record by applying the function `f` to each key and value in the original record.
    * If the function succeeds, the key-value pair is included in the output record.
    *
-   * @example
+   * **Example** (Filtering and mapping with Result)
+   *
    * ```ts
    * import { Record, Result } from "effect"
    * import * as assert from "node:assert"
@@ -1076,7 +1143,8 @@ export const filterMap: {
 /**
  * Selects properties from a record whose values match the given predicate.
  *
- * @example
+ * **Example** (Filtering record values)
+ *
  * ```ts
  * import { Record } from "effect"
  * import * as assert from "node:assert"
@@ -1092,7 +1160,8 @@ export const filter: {
   /**
    * Selects properties from a record whose values match the given predicate.
    *
-   * @example
+   * **Example** (Filtering record values)
+   *
    * ```ts
    * import { Record } from "effect"
    * import * as assert from "node:assert"
@@ -1108,7 +1177,8 @@ export const filter: {
   /**
    * Selects properties from a record whose values match the given predicate.
    *
-   * @example
+   * **Example** (Filtering record values)
+   *
    * ```ts
    * import { Record } from "effect"
    * import * as assert from "node:assert"
@@ -1124,7 +1194,8 @@ export const filter: {
   /**
    * Selects properties from a record whose values match the given predicate.
    *
-   * @example
+   * **Example** (Filtering record values)
+   *
    * ```ts
    * import { Record } from "effect"
    * import * as assert from "node:assert"
@@ -1140,7 +1211,8 @@ export const filter: {
   /**
    * Selects properties from a record whose values match the given predicate.
    *
-   * @example
+   * **Example** (Filtering record values)
+   *
    * ```ts
    * import { Record } from "effect"
    * import * as assert from "node:assert"
@@ -1172,7 +1244,8 @@ export const filter: {
 /**
  * Given a record with `Option` values, returns a new record containing only the `Some` values, preserving the original keys.
  *
- * @example
+ * **Example** (Extracting Some values)
+ *
  * ```ts
  * import { Option, Record } from "effect"
  * import * as assert from "node:assert"
@@ -1204,7 +1277,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.
  *
- * @example
+ * **Example** (Extracting Result failures)
+ *
  * ```ts
  * import { Record, Result } from "effect"
  * import * as assert from "node:assert"
@@ -1239,7 +1313,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.
  *
- * @example
+ * **Example** (Extracting Result successes)
+ *
  * ```ts
  * import { Record, Result } from "effect"
  * import * as assert from "node:assert"
@@ -1272,9 +1347,14 @@ export const getSuccesses = <K extends string, A, E>(
 }
 
 /**
- * Partitions the elements of a record into two groups: those that match a filter, and those that don't.
+ * Applies a function to each record entry and partitions the returned `Result`
+ * values into two records.
+ *
+ * Failure values are collected in the left record, and success values are
+ * collected in the right record, preserving the original keys.
+ *
+ * **Example** (Partitioning with Result)
  *
- * @example
  * ```ts
  * import { Record, Result } from "effect"
  * import * as assert from "node:assert"
@@ -1289,9 +1369,14 @@ export const getSuccesses = <K extends string, A, E>(
  */
 export const partition: {
   /**
-   * Partitions the elements of a record into two groups: those that match a filter, and those that don't.
+   * Applies a function to each record entry and partitions the returned `Result`
+   * values into two records.
+   *
+   * Failure values are collected in the left record, and success values are
+   * collected in the right record, preserving the original keys.
+   *
+   * **Example** (Partitioning with Result)
    *
-   * @example
    * ```ts
    * import { Record, Result } from "effect"
    * import * as assert from "node:assert"
@@ -1308,9 +1393,14 @@ export const partition: {
     self: ReadonlyRecord<K, A>
   ) => [left: Record<ReadonlyRecord.NonLiteralKey<K>, B>, right: Record<ReadonlyRecord.NonLiteralKey<K>, C>]
   /**
-   * Partitions the elements of a record into two groups: those that match a filter, and those that don't.
+   * Applies a function to each record entry and partitions the returned `Result`
+   * values into two records.
+   *
+   * Failure values are collected in the left record, and success values are
+   * collected in the right record, preserving the original keys.
+   *
+   * **Example** (Partitioning with Result)
    *
-   * @example
    * ```ts
    * import { Record, Result } from "effect"
    * import * as assert from "node:assert"
@@ -1348,7 +1438,8 @@ export const partition: {
  * Partitions a record of `Result` values into two separate records,
  * one with the `Err` values and one with the `Ok` values.
  *
- * @example
+ * **Example** (Separating Result values)
+ *
  * ```ts
  * import { Record, Result } from "effect"
  * import * as assert from "node:assert"
@@ -1369,7 +1460,8 @@ export const separate: <K extends string, A, B>(
 /**
  * Retrieve the keys of a given record as an array.
  *
- * @example
+ * **Example** (Getting record keys)
+ *
  * ```ts
  * import { Record } from "effect"
  * import * as assert from "node:assert"
@@ -1386,7 +1478,8 @@ export const keys = <K extends string | symbol, A>(self: ReadonlyRecord<K, A>):
 /**
  * Retrieve the values of a given record as an array.
  *
- * @example
+ * **Example** (Getting record values)
+ *
  * ```ts
  * import { Record } from "effect"
  * import * as assert from "node:assert"
@@ -1402,7 +1495,8 @@ export 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.
  *
- * @example
+ * **Example** (Setting a record value)
+ *
  * ```ts
  * import { Record } from "effect"
  * import * as assert from "node:assert"
@@ -1418,7 +1512,8 @@ export const set: {
   /**
    * Add a new key-value pair or update an existing key's value in a record.
    *
-   * @example
+   * **Example** (Setting a record value)
+   *
    * ```ts
    * import { Record } from "effect"
    * import * as assert from "node:assert"
@@ -1434,7 +1529,8 @@ export const set: {
   /**
    * Add a new key-value pair or update an existing key's value in a record.
    *
-   * @example
+   * **Example** (Setting a record value)
+   *
    * ```ts
    * import { Record } from "effect"
    * import * as assert from "node:assert"
@@ -1462,21 +1558,30 @@ export const set: {
  * Check if all the keys and values in one record are also found in another record.
  * Uses the provided equivalence function to compare values.
  *
- * @example
- * ```ts
- * import { Equal, Record } from "effect"
- * import * as assert from "node:assert"
+ * **Example** (Checking subrecords with a custom equivalence)
  *
- * const isSubrecord = Record.isSubrecordBy(Equal.asEquivalence<number>())
+ * ```ts
+ * import { Equivalence, Record } from "effect"
  *
- * assert.deepStrictEqual(
- *   Record.isSubrecord({ a: 1 } as Record<string, number>, { a: 1, b: 2 }),
- *   true
- * )
- * assert.deepStrictEqual(
- *   Record.isSubrecord({ a: 1, b: 2 }, { a: 1 } as Record<string, number>),
- *   false
+ * const isSubrecord = Record.isSubrecordBy(
+ *   Equivalence.make<string>((self, that) => self.toLowerCase() === that.toLowerCase())
  * )
+ *
+ * const required: Record.ReadonlyRecord<string, string> = { role: "Admin" }
+ * const available: Record.ReadonlyRecord<string, string> = {
+ *   role: "admin",
+ *   status: "active"
+ * }
+ *
+ * console.log(
+ *   isSubrecord(required, available)
+ * ) // true
+ * console.log(
+ *   isSubrecord({ role: "Admin", status: "inactive" }, available)
+ * ) // false
+ * console.log(
+ *   isSubrecord(required, { role: "editor", status: "active" })
+ * ) // false
  * ```
  *
  * @category predicates
@@ -1496,10 +1601,13 @@ export const isSubrecordBy = <A>(equivalence: Equivalence<A>): {
   })
 
 /**
- * Check if one record is a subrecord of another, meaning it contains all the keys and values found in the second record.
- * This comparison uses default equality checks (`Equal.equivalence()`).
+ * Checks whether the first record is a subrecord of the second record.
+ *
+ * Returns `true` when every key and value in `self` is also present in `that`.
+ * Values are compared with Effect equality via `Equal.asEquivalence()`.
+ *
+ * **Example** (Checking subrecords)
  *
- * @example
  * ```ts
  * import { Record } from "effect"
  * import * as assert from "node:assert"
@@ -1519,10 +1627,13 @@ export const isSubrecordBy = <A>(equivalence: Equivalence<A>): {
  */
 export const isSubrecord: {
   /**
-   * Check if one record is a subrecord of another, meaning it contains all the keys and values found in the second record.
-   * This comparison uses default equality checks (`Equal.equivalence()`).
+   * Checks whether the first record is a subrecord of the second record.
+   *
+   * Returns `true` when every key and value in `self` is also present in `that`.
+   * Values are compared with Effect equality via `Equal.asEquivalence()`.
+   *
+   * **Example** (Checking subrecords)
    *
-   * @example
    * ```ts
    * import { Record } from "effect"
    * import * as assert from "node:assert"
@@ -1542,10 +1653,13 @@ export const isSubrecord: {
    */
   <K extends string, A>(that: ReadonlyRecord<K, A>): (self: ReadonlyRecord<K, A>) => boolean
   /**
-   * Check if one record is a subrecord of another, meaning it contains all the keys and values found in the second record.
-   * This comparison uses default equality checks (`Equal.equivalence()`).
+   * Checks whether the first record is a subrecord of the second record.
+   *
+   * Returns `true` when every key and value in `self` is also present in `that`.
+   * Values are compared with Effect equality via `Equal.asEquivalence()`.
+   *
+   * **Example** (Checking subrecords)
    *
-   * @example
    * ```ts
    * import { Record } from "effect"
    * import * as assert from "node:assert"
@@ -1569,7 +1683,8 @@ export const isSubrecord: {
 /**
  * Reduce a record to a single value by combining its entries with a specified function.
  *
- * @example
+ * **Example** (Reducing record values)
+ *
  * ```ts
  * import { Record } from "effect"
  * import * as assert from "node:assert"
@@ -1587,7 +1702,8 @@ export const reduce: {
   /**
    * Reduce a record to a single value by combining its entries with a specified function.
    *
-   * @example
+   * **Example** (Reducing record values)
+   *
    * ```ts
    * import { Record } from "effect"
    * import * as assert from "node:assert"
@@ -1605,7 +1721,8 @@ export const reduce: {
   /**
    * Reduce a record to a single value by combining its entries with a specified function.
    *
-   * @example
+   * **Example** (Reducing record values)
+   *
    * ```ts
    * import { Record } from "effect"
    * import * as assert from "node:assert"
@@ -1642,7 +1759,8 @@ export const reduce: {
 /**
  * Check if all entries in a record meet a specific condition.
  *
- * @example
+ * **Example** (Checking every record value)
+ *
  * ```ts
  * import { Record } from "effect"
  * import * as assert from "node:assert"
@@ -1658,7 +1776,8 @@ export const every: {
   /**
    * Check if all entries in a record meet a specific condition.
    *
-   * @example
+   * **Example** (Checking every record value)
+   *
    * ```ts
    * import { Record } from "effect"
    * import * as assert from "node:assert"
@@ -1674,7 +1793,8 @@ export const every: {
   /**
    * Check if all entries in a record meet a specific condition.
    *
-   * @example
+   * **Example** (Checking every record value)
+   *
    * ```ts
    * import { Record } from "effect"
    * import * as assert from "node:assert"
@@ -1690,7 +1810,8 @@ export const every: {
   /**
    * Check if all entries in a record meet a specific condition.
    *
-   * @example
+   * **Example** (Checking every record value)
+   *
    * ```ts
    * import { Record } from "effect"
    * import * as assert from "node:assert"
@@ -1706,7 +1827,8 @@ export const every: {
   /**
    * Check if all entries in a record meet a specific condition.
    *
-   * @example
+   * **Example** (Checking every record value)
+   *
    * ```ts
    * import { Record } from "effect"
    * import * as assert from "node:assert"
@@ -1737,7 +1859,8 @@ export const every: {
 /**
  * Check if any entry in a record meets a specific condition.
  *
- * @example
+ * **Example** (Checking for any matching value)
+ *
  * ```ts
  * import { Record } from "effect"
  * import * as assert from "node:assert"
@@ -1753,7 +1876,8 @@ export const some: {
   /**
    * Check if any entry in a record meets a specific condition.
    *
-   * @example
+   * **Example** (Checking for any matching value)
+   *
    * ```ts
    * import { Record } from "effect"
    * import * as assert from "node:assert"
@@ -1769,7 +1893,8 @@ export const some: {
   /**
    * Check if any entry in a record meets a specific condition.
    *
-   * @example
+   * **Example** (Checking for any matching value)
+   *
    * ```ts
    * import { Record } from "effect"
    * import * as assert from "node:assert"
@@ -1798,7 +1923,8 @@ export const some: {
  * Merge 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
+ * **Example** (Merging records with union)
+ *
  * ```ts
  * import { Record } from "effect"
  * import * as assert from "node:assert"
@@ -1817,7 +1943,8 @@ export const union: {
    * Merge 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
+   * **Example** (Merging records with union)
+   *
    * ```ts
    * import { Record } from "effect"
    * import * as assert from "node:assert"
@@ -1836,7 +1963,8 @@ export const union: {
    * Merge 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
+   * **Example** (Merging records with union)
+   *
    * ```ts
    * import { Record } from "effect"
    * import * as assert from "node:assert"
@@ -1889,7 +2017,8 @@ export const union: {
  * Merge 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
+ * **Example** (Merging intersecting keys)
+ *
  * ```ts
  * import { Record } from "effect"
  * import * as assert from "node:assert"
@@ -1908,7 +2037,8 @@ export const intersection: {
    * Merge 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
+   * **Example** (Merging intersecting keys)
+   *
    * ```ts
    * import { Record } from "effect"
    * import * as assert from "node:assert"
@@ -1927,7 +2057,8 @@ export const intersection: {
    * Merge 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
+   * **Example** (Merging intersecting keys)
+   *
    * ```ts
    * import { Record } from "effect"
    * import * as assert from "node:assert"
@@ -1970,7 +2101,8 @@ export const intersection: {
  * Merge two records, preserving only the entries that are unique to each record.
  * Keys that exist in both records are excluded from the result.
  *
- * @example
+ * **Example** (Keeping keys unique to each record)
+ *
  * ```ts
  * import { Record } from "effect"
  * import * as assert from "node:assert"
@@ -1989,7 +2121,8 @@ export const difference: {
    * Merge two records, preserving only the entries that are unique to each record.
    * Keys that exist in both records are excluded from the result.
    *
-   * @example
+   * **Example** (Keeping keys unique to each record)
+   *
    * ```ts
    * import { Record } from "effect"
    * import * as assert from "node:assert"
@@ -2008,7 +2141,8 @@ export const difference: {
    * Merge two records, preserving only the entries that are unique to each record.
    * Keys that exist in both records are excluded from the result.
    *
-   * @example
+   * **Example** (Keeping keys unique to each record)
+   *
    * ```ts
    * import { Record } from "effect"
    * import * as assert from "node:assert"
@@ -2051,7 +2185,8 @@ export const difference: {
  * Create an `Equivalence` for records using the provided `Equivalence` for values.
  * Two records are considered equivalent if they have the same keys and their corresponding values are equivalent.
  *
- * @example
+ * **Example** (Comparing records with a value equivalence)
+ *
  * ```ts
  * import { Equal, Record } from "effect"
  * import * as assert from "node:assert"
@@ -2075,7 +2210,8 @@ export const makeEquivalence = <K extends string, A>(
 /**
  * Create a non-empty record from a single element.
  *
- * @example
+ * **Example** (Creating a singleton record)
+ *
  * ```ts
  * import { Record } from "effect"
  * import * as assert from "node:assert"
@@ -2105,9 +2241,12 @@ export function makeReducerUnion<K extends string, A>(combiner: Combiner.Combine
 }
 
 /**
- * A `Reducer` for combining `Record`s using intersection.
+ * Creates a `Reducer` whose `combine` operation intersects two records and
+ * combines values for keys present in both records.
  *
- * Values are combined using the provided `Combiner`.
+ * 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.
  *
  * @since 4.0.0
  */
@@ -2124,7 +2263,8 @@ export function makeReducerIntersection<K extends string, A>(
  * Returns the first entry that satisfies the specified
  * predicate, or `None` if no such entry exists.
  *
- * @example
+ * **Example** (Finding the first matching entry)
+ *
  * ```ts
  * import { Record } from "effect"
  *
@@ -2144,7 +2284,8 @@ export const findFirst: {
    * Returns the first entry that satisfies the specified
    * predicate, or `None` if no such entry exists.
    *
-   * @example
+   * **Example** (Finding the first matching entry)
+   *
    * ```ts
    * import { Record } from "effect"
    *
@@ -2164,7 +2305,8 @@ export const findFirst: {
    * Returns the first entry that satisfies the specified
    * predicate, or `None` if no such entry exists.
    *
-   * @example
+   * **Example** (Finding the first matching entry)
+   *
    * ```ts
    * import { Record } from "effect"
    *
@@ -2184,7 +2326,8 @@ export const findFirst: {
    * Returns the first entry that satisfies the specified
    * predicate, or `None` if no such entry exists.
    *
-   * @example
+   * **Example** (Finding the first matching entry)
+   *
    * ```ts
    * import { Record } from "effect"
    *
@@ -2207,7 +2350,8 @@ export const findFirst: {
    * Returns the first entry that satisfies the specified
    * predicate, or `None` if no such entry exists.
    *
-   * @example
+   * **Example** (Finding the first matching entry)
+   *
    * ```ts
    * import { Record } from "effect"
    *