effect 4.0.0-beta.66 → 4.0.0-beta.68

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"
  *
@@ -54,7 +56,6 @@ export type ReadonlyRecord<in out K extends string | symbol, out A> = {
  * type CommonKeys = Record.ReadonlyRecord.IntersectKeys<"a" | "b", "b" | "c"> // "b"
  * ```
  *
- * @category models
  * @since 2.0.0
  */
 export declare namespace ReadonlyRecord {
@@ -67,7 +68,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 +90,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 +114,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 +143,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 +168,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 +187,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 +208,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 +230,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 +252,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 +288,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 +322,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 +333,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 +343,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"
@@ -336,14 +356,15 @@ export const fromEntries: <Entry extends readonly [string | symbol, any]>(
  * ], ["c", 3]])
  * ```
  *
- * @category conversions
+ * @category converting
  * @since 2.0.0
  */
 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"
@@ -355,14 +376,15 @@ export const collect: {
    * ], ["c", 3]])
    * ```
    *
-   * @category conversions
+   * @category converting
    * @since 2.0.0
    */
   <K extends string, A, B>(f: (key: K, a: A) => B): (self: ReadonlyRecord<K, A>) => Array<B>
   /**
    * 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"
@@ -374,7 +396,7 @@ export const collect: {
    * ], ["c", 3]])
    * ```
    *
-   * @category conversions
+   * @category converting
    * @since 2.0.0
    */
   <K extends string, A, B>(self: ReadonlyRecord<K, A>, f: (key: K, a: A) => B): Array<B>
@@ -392,7 +414,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"
@@ -401,7 +424,7 @@ export const collect: {
  * assert.deepStrictEqual(Record.toEntries(x), [["a", 1], ["b", 2], ["c", 3]])
  * ```
  *
- * @category conversions
+ * @category converting
  * @since 2.0.0
  */
 export const toEntries: <K extends string, A>(self: ReadonlyRecord<K, A>) => Array<[K, A]> = collect((
@@ -412,7 +435,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 +452,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 +469,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 +486,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 +511,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 +530,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 +549,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 +575,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 +596,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 +617,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 +647,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 +667,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 +687,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 +719,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 +736,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 +753,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 +783,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 +803,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 +823,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 +847,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 +869,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 +891,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 +924,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 +943,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 +962,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 +996,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 +1015,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 +1034,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 +1069,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 +1088,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 +1107,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 +1142,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 +1159,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 +1176,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 +1193,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 +1210,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 +1243,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 +1276,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"
@@ -1220,7 +1293,7 @@ export const getSomes: <K extends string, A>(
  * ```
  *
  * @category filtering
- * @since 2.0.0
+ * @since 4.0.0
  */
 export const getFailures = <K extends string, A, E>(
   self: ReadonlyRecord<K, Result<A, E>>
@@ -1239,7 +1312,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"
@@ -1255,7 +1329,7 @@ export const getFailures = <K extends string, A, E>(
  * ```
  *
  * @category filtering
- * @since 2.0.0
+ * @since 4.0.0
  */
 export const getSuccesses = <K extends string, A, E>(
   self: ReadonlyRecord<K, Result<A, E>>
@@ -1272,9 +1346,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 +1368,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 +1392,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 +1437,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 +1459,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 +1477,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 +1494,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 +1511,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 +1528,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 +1557,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 +1600,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 +1626,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 +1652,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 +1682,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 +1701,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 +1720,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 +1758,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 +1775,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 +1792,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 +1809,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 +1826,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 +1858,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 +1875,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 +1892,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 +1922,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 +1942,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 +1962,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 +2016,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 +2036,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 +2056,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 +2100,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 +2120,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 +2140,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 +2184,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"
@@ -2063,7 +2197,7 @@ export const difference: {
  * ```
  *
  * @category instances
- * @since 2.0.0
+ * @since 4.0.0
  */
 export const makeEquivalence = <K extends string, A>(
   equivalence: Equivalence<A>
@@ -2075,7 +2209,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"
@@ -2095,6 +2230,7 @@ export const singleton = <K extends string | symbol, A>(key: K, value: A): Recor
  *
  * Values for keys that exist in both records are combined using the provided `Combiner`.
  *
+ * @category combining
  * @since 4.0.0
  */
 export function makeReducerUnion<K extends string, A>(combiner: Combiner.Combiner<A>): Reducer.Reducer<Record<K, A>> {
@@ -2105,10 +2241,14 @@ 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.
  *
+ * @category combining
  * @since 4.0.0
  */
 export function makeReducerIntersection<K extends string, A>(
@@ -2124,7 +2264,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 +2285,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 +2306,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 +2327,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 +2351,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"
    *