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

package/dist/Record.d.ts

@@ -14,7 +14,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"
  *
@@ -37,7 +38,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"
  *
@@ -48,7 +50,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 {
@@ -59,7 +60,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"
      *
@@ -78,7 +80,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"
      *
@@ -98,15 +101,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
@@ -118,7 +129,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"
  *
@@ -138,7 +150,8 @@ export declare const empty: <K extends string | symbol = never, V = never>() =>
 /**
  * Determine if a record is empty.
  *
- * @example
+ * **Example** (Checking for an empty record)
+ *
  * ```ts
  * import { Record } from "effect"
  * import * as assert from "node:assert"
@@ -154,7 +167,8 @@ export declare const isEmptyRecord: <K extends string, A>(self: Record<K, A>) =>
 /**
  * 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"
@@ -171,7 +185,8 @@ export declare const isEmptyReadonlyRecord: <K extends string, A>(self: Readonly
  * 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"
@@ -192,7 +207,8 @@ export declare 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"
@@ -213,7 +229,8 @@ export declare 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"
@@ -234,7 +251,8 @@ export declare 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"
@@ -263,7 +281,8 @@ export declare const fromIterableBy: <A, K extends string | symbol>(items: Itera
  * 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"
@@ -273,14 +292,15 @@ export declare const fromIterableBy: <A, K extends string | symbol>(items: Itera
  * assert.deepStrictEqual(Record.fromEntries(input), { a: 1, b: 2 })
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const fromEntries: <Entry extends readonly [string | symbol, any]>(entries: Iterable<Entry>) => Record<ReadonlyRecord.NonLiteralKey<Entry[0]>, Entry[1]>;
 /**
  * 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"
@@ -292,14 +312,15 @@ export declare const fromEntries: <Entry extends readonly [string | symbol, any]
  * ], ["c", 3]])
  * ```
  *
- * @category conversions
+ * @category converting
  * @since 2.0.0
  */
 export declare 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"
@@ -311,14 +332,15 @@ export declare 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"
@@ -330,7 +352,7 @@ export declare 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>;
@@ -338,7 +360,8 @@ export declare 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"
@@ -347,14 +370,15 @@ export declare const collect: {
  * assert.deepStrictEqual(Record.toEntries(x), [["a", 1], ["b", 2], ["c", 3]])
  * ```
  *
- * @category conversions
+ * @category converting
  * @since 2.0.0
  */
 export declare const toEntries: <K extends string, A>(self: ReadonlyRecord<K, A>) => Array<[K, A]>;
 /**
  * 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"
@@ -369,7 +393,8 @@ export declare const size: <K extends string, A>(self: ReadonlyRecord<K, A>) =>
 /**
  * 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"
@@ -385,7 +410,8 @@ export declare 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"
@@ -401,7 +427,8 @@ export declare 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"
@@ -418,7 +445,8 @@ export declare 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"
@@ -436,7 +464,8 @@ export declare 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"
@@ -454,7 +483,8 @@ export declare 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"
@@ -474,7 +504,8 @@ export declare 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"
  *
@@ -494,7 +525,8 @@ export declare 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"
      *
@@ -514,7 +546,8 @@ export declare 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"
      *
@@ -532,9 +565,14 @@ export declare const modify: {
     <K extends string | symbol, A, B>(self: ReadonlyRecord<K, A>, key: NoInfer<K>, f: (a: A) => B): Option.Option<Record<K, A | B>>;
 };
 /**
- * Replaces 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"
  *
@@ -547,9 +585,14 @@ export declare const modify: {
  */
 export declare 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"
      *
@@ -562,9 +605,14 @@ export declare const replace: {
      */
     <K extends string | symbol, B>(key: NoInfer<K>, b: B): <A>(self: ReadonlyRecord<K, A>) => Option.Option<Record<K, A | B>>;
     /**
-     * Replaces 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"
      *
@@ -581,7 +629,8 @@ export declare 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"
@@ -597,7 +646,8 @@ export declare const remove: {
      * If the given key exists in the record, returns a new record with the key removed.
      * If the key does not exist, returns a shallow copy of the original record.
      *
-     * @example
+     * **Example** (Removing a key)
+     *
      * ```ts
      * import { Record } from "effect"
      * import * as assert from "node:assert"
@@ -613,7 +663,8 @@ export declare const remove: {
      * If the given key exists in the record, returns a new record with the key removed.
      * If the key does not exist, returns a shallow copy of the original record.
      *
-     * @example
+     * **Example** (Removing a key)
+     *
      * ```ts
      * import { Record } from "effect"
      * import * as assert from "node:assert"
@@ -631,7 +682,8 @@ export declare 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"
  *
@@ -650,7 +702,8 @@ export declare 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"
      *
@@ -669,7 +722,8 @@ export declare 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"
      *
@@ -687,7 +741,8 @@ export declare 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"
@@ -708,7 +763,8 @@ export declare 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"
@@ -729,7 +785,8 @@ export declare 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"
@@ -751,7 +808,8 @@ export declare 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"
@@ -769,7 +827,8 @@ export declare 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"
@@ -787,7 +846,8 @@ export declare 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"
@@ -806,7 +866,8 @@ export declare 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"
@@ -824,7 +885,8 @@ export declare 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"
@@ -842,7 +904,8 @@ export declare 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"
@@ -862,7 +925,8 @@ export declare 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"
@@ -880,7 +944,8 @@ export declare 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"
@@ -898,7 +963,8 @@ export declare 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"
@@ -916,7 +982,8 @@ export declare 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"
@@ -932,7 +999,8 @@ export declare 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"
@@ -948,7 +1016,8 @@ export declare 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"
@@ -964,7 +1033,8 @@ export declare 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"
@@ -980,7 +1050,8 @@ export declare 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"
@@ -997,7 +1068,8 @@ export declare 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"
@@ -1015,7 +1087,8 @@ export declare const getSomes: <K extends string, A>(self: ReadonlyRecord<K, Opt
 /**
  * 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"
@@ -1031,13 +1104,14 @@ export declare const getSomes: <K extends string, A>(self: ReadonlyRecord<K, Opt
  * ```
  *
  * @category filtering
- * @since 2.0.0
+ * @since 4.0.0
  */
 export declare const getFailures: <K extends string, A, E>(self: ReadonlyRecord<K, Result<A, E>>) => Record<ReadonlyRecord.NonLiteralKey<K>, E>;
 /**
  * Given a record with `Result` values, returns a new record containing only the `Ok` values, preserving the original keys.
  *
- * @example
+ * **Example** (Extracting Result successes)
+ *
  * ```ts
  * import { Record, Result } from "effect"
  * import * as assert from "node:assert"
@@ -1053,13 +1127,18 @@ export declare const getFailures: <K extends string, A, E>(self: ReadonlyRecord<
  * ```
  *
  * @category filtering
- * @since 2.0.0
+ * @since 4.0.0
  */
 export declare const getSuccesses: <K extends string, A, E>(self: ReadonlyRecord<K, Result<A, E>>) => Record<string, A>;
 /**
- * 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"
@@ -1074,9 +1153,14 @@ export declare const getSuccesses: <K extends string, A, E>(self: ReadonlyRecord
  */
 export declare 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"
@@ -1091,9 +1175,14 @@ export declare const partition: {
      */
     <K extends string, A, B, C>(f: (input: A, key: K) => Result<C, B>): (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"
@@ -1112,7 +1201,8 @@ export declare 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"
@@ -1130,7 +1220,8 @@ export declare const separate: <K extends string, A, B>(self: ReadonlyRecord<K,
 /**
  * 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"
@@ -1145,7 +1236,8 @@ export declare const keys: <K extends string | symbol, A>(self: ReadonlyRecord<K
 /**
  * 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"
@@ -1160,7 +1252,8 @@ export declare const values: <K extends string, A>(self: ReadonlyRecord<K, 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"
@@ -1176,7 +1269,8 @@ export declare 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"
@@ -1192,7 +1286,8 @@ export declare 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"
@@ -1210,21 +1305,30 @@ export declare 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
@@ -1235,10 +1339,13 @@ export declare const isSubrecordBy: <A>(equivalence: Equivalence<A>) => {
     <K extends string>(self: ReadonlyRecord<K, A>, that: 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"
@@ -1258,10 +1365,13 @@ export declare const isSubrecordBy: <A>(equivalence: Equivalence<A>) => {
  */
 export declare 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"
@@ -1281,10 +1391,13 @@ export declare 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"
@@ -1307,7 +1420,8 @@ export declare 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"
@@ -1325,7 +1439,8 @@ export declare 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"
@@ -1343,7 +1458,8 @@ export declare 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"
@@ -1362,7 +1478,8 @@ export declare 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"
@@ -1378,7 +1495,8 @@ export declare 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"
@@ -1394,7 +1512,8 @@ export declare 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"
@@ -1410,7 +1529,8 @@ export declare 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"
@@ -1426,7 +1546,8 @@ export declare 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"
@@ -1443,7 +1564,8 @@ export declare 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"
@@ -1459,7 +1581,8 @@ export declare 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"
@@ -1475,7 +1598,8 @@ export declare 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"
@@ -1493,7 +1617,8 @@ export declare 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"
@@ -1512,7 +1637,8 @@ export declare 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"
@@ -1531,7 +1657,8 @@ export declare 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"
@@ -1551,7 +1678,8 @@ export declare 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"
@@ -1570,7 +1698,8 @@ export declare 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"
@@ -1589,7 +1718,8 @@ export declare 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"
@@ -1609,7 +1739,8 @@ export declare 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"
@@ -1628,7 +1759,8 @@ export declare 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"
@@ -1647,7 +1779,8 @@ export declare 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"
@@ -1667,7 +1800,8 @@ export declare 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"
@@ -1679,13 +1813,14 @@ export declare const difference: {
  * ```
  *
  * @category instances
- * @since 2.0.0
+ * @since 4.0.0
  */
 export declare const makeEquivalence: <K extends string, A>(equivalence: Equivalence<A>) => Equivalence<ReadonlyRecord<K, 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"
@@ -1702,14 +1837,19 @@ export declare const singleton: <K extends string | symbol, A>(key: K, value: A)
  *
  * Values for keys that exist in both records are combined using the provided `Combiner`.
  *
+ * @category combining
  * @since 4.0.0
  */
 export declare function makeReducerUnion<K extends string, A>(combiner: Combiner.Combiner<A>): Reducer.Reducer<Record<K, A>>;
 /**
- * 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 declare function makeReducerIntersection<K extends string, A>(combiner: Combiner.Combiner<A>): Reducer.Reducer<Record<K, A>>;
@@ -1717,7 +1857,8 @@ export declare function makeReducerIntersection<K extends string, A>(combiner: C
  * 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"
  *
@@ -1737,7 +1878,8 @@ export declare 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"
      *
@@ -1757,7 +1899,8 @@ export declare 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"
      *
@@ -1777,7 +1920,8 @@ export declare 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"
      *
@@ -1797,7 +1941,8 @@ export declare 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"
      *