effect 3.8.4 → 3.9.0

package/dist/dts/Record.d.ts

@@ -96,7 +96,47 @@ export declare const isEmptyReadonlyRecord: <K extends string, A>(self: Readonly
  * @since 2.0.0
  */
 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.
+     *
+     * @param self - An iterable of values to be mapped to a record.
+     * @param f - A projection function that maps values of the iterable to a tuple of a key and a value.
+     *
+     * @example
+     * import { fromIterableWith } from "effect/Record"
+     *
+     * const input = [1, 2, 3, 4]
+     *
+     * assert.deepStrictEqual(
+     *   fromIterableWith(input, a => [String(a), a * 2]),
+     *   { '1': 2, '2': 4, '3': 6, '4': 8 }
+     * )
+     *
+     * @category constructors
+     * @since 2.0.0
+     */
     <A, K extends string | symbol, B>(f: (a: A) => readonly [K, B]): (self: Iterable<A>) => Record<ReadonlyRecord.NonLiteralKey<K>, B>;
+    /**
+     * 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.
+     *
+     * @param self - An iterable of values to be mapped to a record.
+     * @param f - A projection function that maps values of the iterable to a tuple of a key and a value.
+     *
+     * @example
+     * import { fromIterableWith } from "effect/Record"
+     *
+     * const input = [1, 2, 3, 4]
+     *
+     * assert.deepStrictEqual(
+     *   fromIterableWith(input, a => [String(a), a * 2]),
+     *   { '1': 2, '2': 4, '3': 6, '4': 8 }
+     * )
+     *
+     * @category constructors
+     * @since 2.0.0
+     */
     <A, K extends string | symbol, B>(self: Iterable<A>, f: (a: A) => readonly [K, B]): Record<ReadonlyRecord.NonLiteralKey<K>, B>;
 };
 /**
@@ -160,7 +200,37 @@ export declare const fromEntries: <Entry extends readonly [string | symbol, any]
  * @since 2.0.0
  */
 export declare const collect: {
+    /**
+     * Transforms the values of a record into an `Array` with a custom mapping function.
+     *
+     * @param self - The record to transform.
+     * @param f - The custom mapping function to apply to each key/value of the record.
+     *
+     * @example
+     * import { collect } from "effect/Record"
+     *
+     * const x = { a: 1, b: 2, c: 3 }
+     * assert.deepStrictEqual(collect(x, (key, n) => [key, n]), [["a", 1], ["b", 2], ["c", 3]])
+     *
+     * @category conversions
+     * @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.
+     *
+     * @param self - The record to transform.
+     * @param f - The custom mapping function to apply to each key/value of the record.
+     *
+     * @example
+     * import { collect } from "effect/Record"
+     *
+     * const x = { a: 1, b: 2, c: 3 }
+     * assert.deepStrictEqual(collect(x, (key, n) => [key, n]), [["a", 1], ["b", 2], ["c", 3]])
+     *
+     * @category conversions
+     * @since 2.0.0
+     */
     <K extends string, A, B>(self: ReadonlyRecord<K, A>, f: (key: K, a: A) => B): Array<B>;
 };
 /**
@@ -206,7 +276,35 @@ export declare const size: <K extends string, A>(self: ReadonlyRecord<K, A>) =>
  * @since 2.0.0
  */
 export declare const has: {
+    /**
+     * Check if a given `key` exists in a record.
+     *
+     * @param self - the record to look in.
+     * @param key - the key to look for in the record.
+     *
+     * @example
+     * import { empty, has } from "effect/Record"
+     *
+     * assert.deepStrictEqual(has({ a: 1, b: 2 }, "a"), true);
+     * assert.deepStrictEqual(has(empty<string>(), "c"), false);
+     *
+     * @since 2.0.0
+     */
     <K extends string | symbol>(key: NoInfer<K>): <A>(self: ReadonlyRecord<K, A>) => boolean;
+    /**
+     * Check if a given `key` exists in a record.
+     *
+     * @param self - the record to look in.
+     * @param key - the key to look for in the record.
+     *
+     * @example
+     * import { empty, has } from "effect/Record"
+     *
+     * assert.deepStrictEqual(has({ a: 1, b: 2 }, "a"), true);
+     * assert.deepStrictEqual(has(empty<string>(), "c"), false);
+     *
+     * @since 2.0.0
+     */
     <K extends string | symbol, A>(self: ReadonlyRecord<K, A>, key: NoInfer<K>): boolean;
 };
 /**
@@ -226,7 +324,39 @@ export declare const has: {
  * @since 2.0.0
  */
 export declare const get: {
+    /**
+     * Retrieve a value at a particular key from a record, returning it wrapped in an `Option`.
+     *
+     * @param self - The record to retrieve value from.
+     * @param key - Key to retrieve from record.
+     *
+     * @example
+     * import { Record as R, Option } from "effect"
+     *
+     * const person: Record<string, unknown> = { name: "John Doe", age: 35 }
+     *
+     * assert.deepStrictEqual(R.get(person, "name"), Option.some("John Doe"))
+     * assert.deepStrictEqual(R.get(person, "email"), Option.none())
+     *
+     * @since 2.0.0
+     */
     <K extends string | symbol>(key: NoInfer<K>): <A>(self: ReadonlyRecord<K, A>) => Option.Option<A>;
+    /**
+     * Retrieve a value at a particular key from a record, returning it wrapped in an `Option`.
+     *
+     * @param self - The record to retrieve value from.
+     * @param key - Key to retrieve from record.
+     *
+     * @example
+     * import { Record as R, Option } from "effect"
+     *
+     * const person: Record<string, unknown> = { name: "John Doe", age: 35 }
+     *
+     * assert.deepStrictEqual(R.get(person, "name"), Option.some("John Doe"))
+     * assert.deepStrictEqual(R.get(person, "email"), Option.none())
+     *
+     * @since 2.0.0
+     */
     <K extends string | symbol, A>(self: ReadonlyRecord<K, A>, key: NoInfer<K>): Option.Option<A>;
 };
 /**
@@ -254,7 +384,55 @@ export declare const get: {
  * @since 2.0.0
  */
 export declare const modify: {
+    /**
+     * Apply a function to the element at the specified key, creating a new record.
+     * If the key does not exist, the record is returned unchanged.
+     *
+     * @param self - The record to be updated.
+     * @param key - The key of the element to modify.
+     * @param f - The function to apply to the element.
+     *
+     * @example
+     * import { Record as R } from "effect"
+     *
+     * const f = (x: number) => x * 2
+     *
+     * assert.deepStrictEqual(
+     *  R.modify({ a: 3 }, 'a', f),
+     *  { a: 6 }
+     * )
+     * assert.deepStrictEqual(
+     *  R.modify({ a: 3 } as Record<string, number>, 'b', f),
+     *  { a: 3 }
+     * )
+     *
+     * @since 2.0.0
+     */
     <K extends string | symbol, A, B>(key: NoInfer<K>, f: (a: A) => B): (self: ReadonlyRecord<K, A>) => Record<K, A | B>;
+    /**
+     * Apply a function to the element at the specified key, creating a new record.
+     * If the key does not exist, the record is returned unchanged.
+     *
+     * @param self - The record to be updated.
+     * @param key - The key of the element to modify.
+     * @param f - The function to apply to the element.
+     *
+     * @example
+     * import { Record as R } from "effect"
+     *
+     * const f = (x: number) => x * 2
+     *
+     * assert.deepStrictEqual(
+     *  R.modify({ a: 3 }, 'a', f),
+     *  { a: 6 }
+     * )
+     * assert.deepStrictEqual(
+     *  R.modify({ a: 3 } as Record<string, number>, 'b', f),
+     *  { a: 3 }
+     * )
+     *
+     * @since 2.0.0
+     */
     <K extends string | symbol, A, B>(self: ReadonlyRecord<K, A>, key: NoInfer<K>, f: (a: A) => B): Record<K, A | B>;
 };
 /**
@@ -282,7 +460,55 @@ export declare const modify: {
  * @since 2.0.0
  */
 export declare const modifyOption: {
+    /**
+     * Apply a function to the element at the specified key, creating a new record,
+     * or return `None` if the key doesn't exist.
+     *
+     * @param self - The record to be updated.
+     * @param key - The key of the element to modify.
+     * @param f - The function to apply to the element.
+     *
+     * @example
+     * import { Record as R, Option } from "effect"
+     *
+     * const f = (x: number) => x * 2
+     *
+     * assert.deepStrictEqual(
+     *  R.modifyOption({ a: 3 }, 'a', f),
+     *  Option.some({ a: 6 })
+     * )
+     * assert.deepStrictEqual(
+     *  R.modifyOption({ a: 3 } as Record<string, number>, 'b', f),
+     *  Option.none()
+     * )
+     *
+     * @since 2.0.0
+     */
     <K extends string | symbol, A, B>(key: NoInfer<K>, f: (a: A) => B): (self: ReadonlyRecord<K, A>) => Option.Option<Record<K, A | B>>;
+    /**
+     * Apply a function to the element at the specified key, creating a new record,
+     * or return `None` if the key doesn't exist.
+     *
+     * @param self - The record to be updated.
+     * @param key - The key of the element to modify.
+     * @param f - The function to apply to the element.
+     *
+     * @example
+     * import { Record as R, Option } from "effect"
+     *
+     * const f = (x: number) => x * 2
+     *
+     * assert.deepStrictEqual(
+     *  R.modifyOption({ a: 3 }, 'a', f),
+     *  Option.some({ a: 6 })
+     * )
+     * assert.deepStrictEqual(
+     *  R.modifyOption({ a: 3 } as Record<string, number>, 'b', f),
+     *  Option.none()
+     * )
+     *
+     * @since 2.0.0
+     */
     <K extends string | symbol, A, B>(self: ReadonlyRecord<K, A>, key: NoInfer<K>, f: (a: A) => B): Option.Option<Record<K, A | B>>;
 };
 /**
@@ -304,7 +530,43 @@ export declare const modifyOption: {
  * @since 2.0.0
  */
 export declare const replaceOption: {
+    /**
+     * Replaces a value in the record with the new value passed as parameter.
+     *
+     * @param self - The record to be updated.
+     * @param key - The key to search for in the record.
+     * @param b - The new value to replace the existing value with.
+     *
+     * @example
+     * import { Record, Option } from "effect"
+     *
+     * assert.deepStrictEqual(
+     *   Record.replaceOption({ a: 1, b: 2, c: 3 }, 'a', 10),
+     *   Option.some({ a: 10, b: 2, c: 3 })
+     * )
+     * assert.deepStrictEqual(Record.replaceOption(Record.empty<string>(), 'a', 10), Option.none())
+     *
+     * @since 2.0.0
+     */
     <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.
+     *
+     * @param self - The record to be updated.
+     * @param key - The key to search for in the record.
+     * @param b - The new value to replace the existing value with.
+     *
+     * @example
+     * import { Record, Option } from "effect"
+     *
+     * assert.deepStrictEqual(
+     *   Record.replaceOption({ a: 1, b: 2, c: 3 }, 'a', 10),
+     *   Option.some({ a: 10, b: 2, c: 3 })
+     * )
+     * assert.deepStrictEqual(Record.replaceOption(Record.empty<string>(), 'a', 10), Option.none())
+     *
+     * @since 2.0.0
+     */
     <K extends string | symbol, A, B>(self: ReadonlyRecord<K, A>, key: NoInfer<K>, b: B): Option.Option<Record<K, A | B>>;
 };
 /**
@@ -322,7 +584,35 @@ export declare const replaceOption: {
  * @since 2.0.0
  */
 export declare const remove: {
+    /**
+     * If the given key exists in the record, returns a new record with the key removed,
+     * otherwise returns a copy of the original record.
+     *
+     * @param self - the record to remove the key from.
+     * @param key - the key to remove from the record.
+     *
+     * @example
+     * import { remove } from "effect/Record"
+     *
+     * assert.deepStrictEqual(remove({ a: 1, b: 2 }, "a"), { b: 2 })
+     *
+     * @since 2.0.0
+     */
     <K extends string | symbol, X extends K>(key: X): <A>(self: ReadonlyRecord<K, A>) => Record<Exclude<K, X>, A>;
+    /**
+     * If the given key exists in the record, returns a new record with the key removed,
+     * otherwise returns a copy of the original record.
+     *
+     * @param self - the record to remove the key from.
+     * @param key - the key to remove from the record.
+     *
+     * @example
+     * import { remove } from "effect/Record"
+     *
+     * assert.deepStrictEqual(remove({ a: 1, b: 2 }, "a"), { b: 2 })
+     *
+     * @since 2.0.0
+     */
     <K extends string | symbol, A, X extends K>(self: ReadonlyRecord<K, A>, key: X): Record<Exclude<K, X>, A>;
 };
 /**
@@ -343,7 +633,41 @@ export declare const remove: {
  * @since 2.0.0
  */
 export declare const pop: {
+    /**
+     * Retrieves the value of the property with the given `key` from a record and returns an `Option`
+     * of a tuple with the value and the record with the removed property.
+     * If the key is not present, returns `O.none`.
+     *
+     * @param self - The input record.
+     * @param key - The key of the property to retrieve.
+     *
+     * @example
+     * import { Record as R, Option } from "effect"
+     *
+     * assert.deepStrictEqual(R.pop({ a: 1, b: 2 }, "a"), Option.some([1, { b: 2 }]))
+     * assert.deepStrictEqual(R.pop({ a: 1, b: 2 } as Record<string, number>, "c"), Option.none())
+     *
+     * @category record
+     * @since 2.0.0
+     */
     <K extends string | symbol, X extends K>(key: X): <A>(self: ReadonlyRecord<K, A>) => Option.Option<[A, Record<Exclude<K, X>, A>]>;
+    /**
+     * Retrieves the value of the property with the given `key` from a record and returns an `Option`
+     * of a tuple with the value and the record with the removed property.
+     * If the key is not present, returns `O.none`.
+     *
+     * @param self - The input record.
+     * @param key - The key of the property to retrieve.
+     *
+     * @example
+     * import { Record as R, Option } from "effect"
+     *
+     * assert.deepStrictEqual(R.pop({ a: 1, b: 2 }, "a"), Option.some([1, { b: 2 }]))
+     * assert.deepStrictEqual(R.pop({ a: 1, b: 2 } as Record<string, number>, "c"), Option.none())
+     *
+     * @category record
+     * @since 2.0.0
+     */
     <K extends string | symbol, A, X extends K>(self: ReadonlyRecord<K, A>, key: X): Option.Option<[A, Record<Exclude<K, X>, A>]>;
 };
 /**
@@ -367,7 +691,47 @@ export declare const pop: {
  * @since 2.0.0
  */
 export declare const map: {
+    /**
+     * Maps a record into another record by applying a transformation function to each of its values.
+     *
+     * @param self - The record to be mapped.
+     * @param f - A transformation function that will be applied to each of the values in the record.
+     *
+     * @example
+     * import { map } from "effect/Record"
+     *
+     * const f = (n: number) => `-${n}`
+     *
+     * assert.deepStrictEqual(map({ a: 3, b: 5 }, f), { a: "-3", b: "-5" })
+     *
+     * const g = (n: number, key: string) => `${key.toUpperCase()}-${n}`
+     *
+     * assert.deepStrictEqual(map({ a: 3, b: 5 }, g), { a: "A-3", b: "B-5" })
+     *
+     * @category mapping
+     * @since 2.0.0
+     */
     <K extends string, A, B>(f: (a: A, key: NoInfer<K>) => B): (self: ReadonlyRecord<K, A>) => Record<K, B>;
+    /**
+     * Maps a record into another record by applying a transformation function to each of its values.
+     *
+     * @param self - The record to be mapped.
+     * @param f - A transformation function that will be applied to each of the values in the record.
+     *
+     * @example
+     * import { map } from "effect/Record"
+     *
+     * const f = (n: number) => `-${n}`
+     *
+     * assert.deepStrictEqual(map({ a: 3, b: 5 }, f), { a: "-3", b: "-5" })
+     *
+     * const g = (n: number, key: string) => `${key.toUpperCase()}-${n}`
+     *
+     * assert.deepStrictEqual(map({ a: 3, b: 5 }, g), { a: "A-3", b: "B-5" })
+     *
+     * @category mapping
+     * @since 2.0.0
+     */
     <K extends string, A, B>(self: ReadonlyRecord<K, A>, f: (a: A, key: NoInfer<K>) => B): Record<K, B>;
 };
 /**
@@ -382,7 +746,29 @@ export declare const map: {
  * @since 2.0.0
  */
 export declare const mapKeys: {
+    /**
+     * Maps the keys of a `ReadonlyRecord` while preserving the corresponding values.
+     *
+     * @example
+     * import { mapKeys } from "effect/Record"
+     *
+     * assert.deepStrictEqual(mapKeys({ a: 3, b: 5 }, (key) => key.toUpperCase()), { A: 3, B: 5 })
+     *
+     * @category mapping
+     * @since 2.0.0
+     */
     <K extends string, A, K2 extends string>(f: (key: K, a: A) => K2): (self: ReadonlyRecord<K, A>) => Record<K2, A>;
+    /**
+     * Maps the keys of a `ReadonlyRecord` while preserving the corresponding values.
+     *
+     * @example
+     * import { mapKeys } from "effect/Record"
+     *
+     * assert.deepStrictEqual(mapKeys({ a: 3, b: 5 }, (key) => key.toUpperCase()), { A: 3, B: 5 })
+     *
+     * @category mapping
+     * @since 2.0.0
+     */
     <K extends string, A, K2 extends string>(self: ReadonlyRecord<K, A>, f: (key: K, a: A) => K2): Record<K2, A>;
 };
 /**
@@ -397,7 +783,29 @@ export declare const mapKeys: {
  * @since 2.0.0
  */
 export declare const mapEntries: {
+    /**
+     * Maps entries of a `ReadonlyRecord` using the provided function, allowing modification of both keys and corresponding values.
+     *
+     * @example
+     * import { mapEntries } from "effect/Record"
+     *
+     * assert.deepStrictEqual(mapEntries({ a: 3, b: 5 }, (a, key) => [key.toUpperCase(), a + 1]), { A: 4, B: 6 })
+     *
+     * @category mapping
+     * @since 2.0.0
+     */
     <K extends string, A, K2 extends string, B>(f: (a: A, key: K) => readonly [K2, B]): (self: ReadonlyRecord<K, A>) => Record<K2, B>;
+    /**
+     * Maps entries of a `ReadonlyRecord` using the provided function, allowing modification of both keys and corresponding values.
+     *
+     * @example
+     * import { mapEntries } from "effect/Record"
+     *
+     * assert.deepStrictEqual(mapEntries({ a: 3, b: 5 }, (a, key) => [key.toUpperCase(), a + 1]), { A: 4, B: 6 })
+     *
+     * @category mapping
+     * @since 2.0.0
+     */
     <K extends string, A, K2 extends string, B>(self: ReadonlyRecord<K, A>, f: (a: A, key: K) => [K2, B]): Record<K2, B>;
 };
 /**
@@ -417,7 +825,39 @@ export declare const mapEntries: {
  * @since 2.0.0
  */
 export declare const filterMap: {
+    /**
+     * Transforms a record into a record by applying the function `f` to each key and value in the original record.
+     * If the function returns `Some`, the key-value pair is included in the output record.
+     *
+     * @param self - The input record.
+     * @param f - The transformation function.
+     *
+     * @example
+     * import { Record, Option } from "effect"
+     *
+     * const x = { a: 1, b: 2, c: 3 }
+     * const f = (a: number, key: string) => a > 2 ? Option.some(a * 2) : Option.none()
+     * assert.deepStrictEqual(Record.filterMap(x, f), { c: 6 })
+     *
+     * @since 2.0.0
+     */
     <K extends string, A, B>(f: (a: A, key: K) => Option.Option<B>): (self: ReadonlyRecord<K, A>) => Record<ReadonlyRecord.NonLiteralKey<K>, B>;
+    /**
+     * Transforms a record into a record by applying the function `f` to each key and value in the original record.
+     * If the function returns `Some`, the key-value pair is included in the output record.
+     *
+     * @param self - The input record.
+     * @param f - The transformation function.
+     *
+     * @example
+     * import { Record, Option } from "effect"
+     *
+     * const x = { a: 1, b: 2, c: 3 }
+     * const f = (a: number, key: string) => a > 2 ? Option.some(a * 2) : Option.none()
+     * assert.deepStrictEqual(Record.filterMap(x, f), { c: 6 })
+     *
+     * @since 2.0.0
+     */
     <K extends string, A, B>(self: ReadonlyRecord<K, A>, f: (a: A, key: K) => Option.Option<B>): Record<ReadonlyRecord.NonLiteralKey<K>, B>;
 };
 /**
@@ -436,9 +876,69 @@ export declare const filterMap: {
  * @since 2.0.0
  */
 export declare const filter: {
+    /**
+     * Selects properties from a record whose values match the given predicate.
+     *
+     * @param self - The record to filter.
+     * @param predicate - A function that returns a `boolean` value to determine if the entry should be included in the new record.
+     *
+     * @example
+     * import { filter } from "effect/Record"
+     *
+     * const x = { a: 1, b: 2, c: 3, d: 4 }
+     * assert.deepStrictEqual(filter(x, (n) => n > 2), { c: 3, d: 4 })
+     *
+     * @category filtering
+     * @since 2.0.0
+     */
     <K extends string, A, B extends A>(refinement: (a: NoInfer<A>, key: K) => a is B): (self: ReadonlyRecord<K, A>) => Record<ReadonlyRecord.NonLiteralKey<K>, B>;
+    /**
+     * Selects properties from a record whose values match the given predicate.
+     *
+     * @param self - The record to filter.
+     * @param predicate - A function that returns a `boolean` value to determine if the entry should be included in the new record.
+     *
+     * @example
+     * import { filter } from "effect/Record"
+     *
+     * const x = { a: 1, b: 2, c: 3, d: 4 }
+     * assert.deepStrictEqual(filter(x, (n) => n > 2), { c: 3, d: 4 })
+     *
+     * @category filtering
+     * @since 2.0.0
+     */
     <K extends string, A>(predicate: (A: NoInfer<A>, key: K) => boolean): (self: ReadonlyRecord<K, A>) => Record<ReadonlyRecord.NonLiteralKey<K>, A>;
+    /**
+     * Selects properties from a record whose values match the given predicate.
+     *
+     * @param self - The record to filter.
+     * @param predicate - A function that returns a `boolean` value to determine if the entry should be included in the new record.
+     *
+     * @example
+     * import { filter } from "effect/Record"
+     *
+     * const x = { a: 1, b: 2, c: 3, d: 4 }
+     * assert.deepStrictEqual(filter(x, (n) => n > 2), { c: 3, d: 4 })
+     *
+     * @category filtering
+     * @since 2.0.0
+     */
     <K extends string, A, B extends A>(self: ReadonlyRecord<K, A>, refinement: (a: A, key: K) => a is B): Record<ReadonlyRecord.NonLiteralKey<K>, B>;
+    /**
+     * Selects properties from a record whose values match the given predicate.
+     *
+     * @param self - The record to filter.
+     * @param predicate - A function that returns a `boolean` value to determine if the entry should be included in the new record.
+     *
+     * @example
+     * import { filter } from "effect/Record"
+     *
+     * const x = { a: 1, b: 2, c: 3, d: 4 }
+     * assert.deepStrictEqual(filter(x, (n) => n > 2), { c: 3, d: 4 })
+     *
+     * @category filtering
+     * @since 2.0.0
+     */
     <K extends string, A>(self: ReadonlyRecord<K, A>, predicate: (a: A, key: K) => boolean): Record<ReadonlyRecord.NonLiteralKey<K>, A>;
 };
 /**
@@ -505,7 +1005,39 @@ export declare const getRights: <K extends string, R, L>(self: ReadonlyRecord<K,
  * @since 2.0.0
  */
 export declare const partitionMap: {
+    /**
+     * Partitions the elements of a record into two groups: those that match a predicate, and those that don't.
+     *
+     * @param self - The record to partition.
+     * @param f - The predicate function to apply to each element.
+     *
+     * @example
+     * import { Record, Either } from "effect"
+     *
+     * const x = { a: 1, b: 2, c: 3 }
+     * const f = (n: number) => (n % 2 === 0 ? Either.right(n) : Either.left(n))
+     * assert.deepStrictEqual(Record.partitionMap(x, f), [{ a: 1, c: 3 }, { b: 2}])
+     *
+     * @category filtering
+     * @since 2.0.0
+     */
     <K extends string, A, B, C>(f: (a: A, key: K) => Either<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 predicate, and those that don't.
+     *
+     * @param self - The record to partition.
+     * @param f - The predicate function to apply to each element.
+     *
+     * @example
+     * import { Record, Either } from "effect"
+     *
+     * const x = { a: 1, b: 2, c: 3 }
+     * const f = (n: number) => (n % 2 === 0 ? Either.right(n) : Either.left(n))
+     * assert.deepStrictEqual(Record.partitionMap(x, f), [{ a: 1, c: 3 }, { b: 2}])
+     *
+     * @category filtering
+     * @since 2.0.0
+     */
     <K extends string, A, B, C>(self: ReadonlyRecord<K, A>, f: (a: A, key: K) => Either<C, B>): [left: Record<ReadonlyRecord.NonLiteralKey<K>, B>, right: Record<ReadonlyRecord.NonLiteralKey<K>, C>];
 };
 /**
@@ -544,15 +1076,83 @@ export declare const separate: <K extends string, A, B>(self: ReadonlyRecord<K,
  * @since 2.0.0
  */
 export declare const partition: {
+    /**
+     * Partitions a record into two separate records based on the result of a predicate function.
+     *
+     * @param self - The input record to partition.
+     * @param predicate - The partitioning function to determine the partitioning of each value of the record.
+     *
+     * @example
+     * import { partition } from "effect/Record"
+     *
+     * assert.deepStrictEqual(
+     *   partition({ a: 1, b: 3 }, (n) => n > 2),
+     *   [{ a: 1 }, { b: 3 }]
+     * )
+     *
+     * @category filtering
+     * @since 2.0.0
+     */
     <K extends string, A, B extends A>(refinement: (a: NoInfer<A>, key: K) => a is B): (self: ReadonlyRecord<K, A>) => [
         excluded: Record<ReadonlyRecord.NonLiteralKey<K>, Exclude<A, B>>,
         satisfying: Record<ReadonlyRecord.NonLiteralKey<K>, B>
     ];
+    /**
+     * Partitions a record into two separate records based on the result of a predicate function.
+     *
+     * @param self - The input record to partition.
+     * @param predicate - The partitioning function to determine the partitioning of each value of the record.
+     *
+     * @example
+     * import { partition } from "effect/Record"
+     *
+     * assert.deepStrictEqual(
+     *   partition({ a: 1, b: 3 }, (n) => n > 2),
+     *   [{ a: 1 }, { b: 3 }]
+     * )
+     *
+     * @category filtering
+     * @since 2.0.0
+     */
     <K extends string, A>(predicate: (a: NoInfer<A>, key: K) => boolean): (self: ReadonlyRecord<K, A>) => [excluded: Record<ReadonlyRecord.NonLiteralKey<K>, A>, satisfying: Record<ReadonlyRecord.NonLiteralKey<K>, A>];
+    /**
+     * Partitions a record into two separate records based on the result of a predicate function.
+     *
+     * @param self - The input record to partition.
+     * @param predicate - The partitioning function to determine the partitioning of each value of the record.
+     *
+     * @example
+     * import { partition } from "effect/Record"
+     *
+     * assert.deepStrictEqual(
+     *   partition({ a: 1, b: 3 }, (n) => n > 2),
+     *   [{ a: 1 }, { b: 3 }]
+     * )
+     *
+     * @category filtering
+     * @since 2.0.0
+     */
     <K extends string, A, B extends A>(self: ReadonlyRecord<K, A>, refinement: (a: A, key: K) => a is B): [
         excluded: Record<ReadonlyRecord.NonLiteralKey<K>, Exclude<A, B>>,
         satisfying: Record<ReadonlyRecord.NonLiteralKey<K>, B>
     ];
+    /**
+     * Partitions a record into two separate records based on the result of a predicate function.
+     *
+     * @param self - The input record to partition.
+     * @param predicate - The partitioning function to determine the partitioning of each value of the record.
+     *
+     * @example
+     * import { partition } from "effect/Record"
+     *
+     * assert.deepStrictEqual(
+     *   partition({ a: 1, b: 3 }, (n) => n > 2),
+     *   [{ a: 1 }, { b: 3 }]
+     * )
+     *
+     * @category filtering
+     * @since 2.0.0
+     */
     <K extends string, A>(self: ReadonlyRecord<K, A>, predicate: (a: A, key: K) => boolean): [excluded: Record<ReadonlyRecord.NonLiteralKey<K>, A>, satisfying: Record<ReadonlyRecord.NonLiteralKey<K>, A>];
 };
 /**
@@ -587,7 +1187,37 @@ export declare const values: <K extends string, A>(self: ReadonlyRecord<K, A>) =
  * @since 2.0.0
  */
 export declare const set: {
+    /**
+     * Add a new key-value pair or update an existing key's value in a record.
+     *
+     * @param self - The record to which you want to add or update a key-value pair.
+     * @param key - The key you want to add or update.
+     * @param values - The value you want to associate with the key.
+     *
+     * @example
+     * import { set } from "effect/Record"
+     *
+     * assert.deepStrictEqual(set("a", 5)({ a: 1, b: 2 }), { a: 5, b: 2 });
+     * assert.deepStrictEqual(set("c", 5)({ a: 1, b: 2 }), { a: 1, b: 2, c: 5 });
+     *
+     * @since 2.0.0
+     */
     <K extends string | symbol, K1 extends K | ((string | symbol) & {}), B>(key: K1, value: B): <A>(self: ReadonlyRecord<K, A>) => Record<K | K1, A | B>;
+    /**
+     * Add a new key-value pair or update an existing key's value in a record.
+     *
+     * @param self - The record to which you want to add or update a key-value pair.
+     * @param key - The key you want to add or update.
+     * @param values - The value you want to associate with the key.
+     *
+     * @example
+     * import { set } from "effect/Record"
+     *
+     * assert.deepStrictEqual(set("a", 5)({ a: 1, b: 2 }), { a: 5, b: 2 });
+     * assert.deepStrictEqual(set("c", 5)({ a: 1, b: 2 }), { a: 1, b: 2, c: 5 });
+     *
+     * @since 2.0.0
+     */
     <K extends string | symbol, A, K1 extends K | ((string | symbol) & {}), B>(self: ReadonlyRecord<K, A>, key: K1, value: B): Record<K | K1, A | B>;
 };
 /**
@@ -607,7 +1237,39 @@ export declare const set: {
  * @since 2.0.0
  */
 export declare const replace: {
+    /**
+     * Replace a key's value in a record and return the updated record.
+     * If the key does not exist in the record, a copy of the original record is returned.
+     *
+     * @param self - The original record.
+     * @param key - The key to replace.
+     * @param value - The new value to associate with the key.
+     *
+     * @example
+     * import { Record } from "effect"
+     *
+     * assert.deepStrictEqual(Record.replace("a", 3)({ a: 1, b: 2 }), { a: 3, b: 2 });
+     * assert.deepStrictEqual(Record.replace("c", 3)({ a: 1, b: 2 }), { a: 1, b: 2 });
+     *
+     * @since 2.0.0
+     */
     <K extends string | symbol, B>(key: NoInfer<K>, value: B): <A>(self: ReadonlyRecord<K, A>) => Record<K, A | B>;
+    /**
+     * Replace a key's value in a record and return the updated record.
+     * If the key does not exist in the record, a copy of the original record is returned.
+     *
+     * @param self - The original record.
+     * @param key - The key to replace.
+     * @param value - The new value to associate with the key.
+     *
+     * @example
+     * import { Record } from "effect"
+     *
+     * assert.deepStrictEqual(Record.replace("a", 3)({ a: 1, b: 2 }), { a: 3, b: 2 });
+     * assert.deepStrictEqual(Record.replace("c", 3)({ a: 1, b: 2 }), { a: 1, b: 2 });
+     *
+     * @since 2.0.0
+     */
     <K extends string | symbol, A, B>(self: ReadonlyRecord<K, A>, key: NoInfer<K>, value: B): Record<K, A | B>;
 };
 /**
@@ -633,7 +1295,25 @@ export declare const isSubrecordBy: <A>(equivalence: Equivalence<A>) => {
  * @since 2.0.0
  */
 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()`).
+     *
+     * @param self - The first record to check.
+     * @param that - The second record to compare against.
+     *
+     * @since 2.0.0
+     */
     <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()`).
+     *
+     * @param self - The first record to check.
+     * @param that - The second record to compare against.
+     *
+     * @since 2.0.0
+     */
     <K extends string, A>(self: ReadonlyRecord<K, A>, that: ReadonlyRecord<K, A>): boolean;
 };
 /**
@@ -647,7 +1327,27 @@ export declare const isSubrecord: {
  * @since 2.0.0
  */
 export declare const reduce: {
+    /**
+     * Reduce a record to a single value by combining its entries with a specified function.
+     *
+     * @param self - The record to reduce.
+     * @param zero - The initial value of the accumulator.
+     * @param f - The function to combine entries (accumulator, value, key).
+     *
+     * @category folding
+     * @since 2.0.0
+     */
     <Z, V, K extends string>(zero: Z, f: (accumulator: Z, value: V, key: K) => Z): (self: ReadonlyRecord<K, V>) => Z;
+    /**
+     * Reduce a record to a single value by combining its entries with a specified function.
+     *
+     * @param self - The record to reduce.
+     * @param zero - The initial value of the accumulator.
+     * @param f - The function to combine entries (accumulator, value, key).
+     *
+     * @category folding
+     * @since 2.0.0
+     */
     <K extends string, V, Z>(self: ReadonlyRecord<K, V>, zero: Z, f: (accumulator: Z, value: V, key: K) => Z): Z;
 };
 /**
@@ -659,9 +1359,41 @@ export declare const reduce: {
  * @since 2.0.0
  */
 export declare const every: {
+    /**
+     * Check if all entries in a record meet a specific condition.
+     *
+     * @param self - The record to check.
+     * @param predicate - The condition to test entries (value, key).
+     *
+     * @since 2.0.0
+     */
     <A, K extends string, B extends A>(refinement: (value: A, key: K) => value is B): (self: ReadonlyRecord<K, A>) => self is ReadonlyRecord<K, B>;
+    /**
+     * Check if all entries in a record meet a specific condition.
+     *
+     * @param self - The record to check.
+     * @param predicate - The condition to test entries (value, key).
+     *
+     * @since 2.0.0
+     */
     <A, K extends string>(predicate: (value: A, key: K) => boolean): (self: ReadonlyRecord<K, A>) => boolean;
+    /**
+     * Check if all entries in a record meet a specific condition.
+     *
+     * @param self - The record to check.
+     * @param predicate - The condition to test entries (value, key).
+     *
+     * @since 2.0.0
+     */
     <A, K extends string, B extends A>(self: ReadonlyRecord<K, A>, refinement: (value: A, key: K) => value is B): self is ReadonlyRecord<K, B>;
+    /**
+     * Check if all entries in a record meet a specific condition.
+     *
+     * @param self - The record to check.
+     * @param predicate - The condition to test entries (value, key).
+     *
+     * @since 2.0.0
+     */
     <K extends string, A>(self: ReadonlyRecord<K, A>, predicate: (value: A, key: K) => boolean): boolean;
 };
 /**
@@ -673,7 +1405,23 @@ export declare const every: {
  * @since 2.0.0
  */
 export declare const some: {
+    /**
+     * Check if any entry in a record meets a specific condition.
+     *
+     * @param self - The record to check.
+     * @param predicate - The condition to test entries (value, key).
+     *
+     * @since 2.0.0
+     */
     <A, K extends string>(predicate: (value: A, key: K) => boolean): (self: ReadonlyRecord<K, A>) => boolean;
+    /**
+     * Check if any entry in a record meets a specific condition.
+     *
+     * @param self - The record to check.
+     * @param predicate - The condition to test entries (value, key).
+     *
+     * @since 2.0.0
+     */
     <K extends string, A>(self: ReadonlyRecord<K, A>, predicate: (value: A, key: K) => boolean): boolean;
 };
 /**
@@ -686,7 +1434,25 @@ export declare const some: {
  * @since 2.0.0
  */
 export declare const union: {
+    /**
+     * Merge two records, preserving entries that exist in either of the records.
+     *
+     * @param self - The first record.
+     * @param that - The second record to combine with the first.
+     * @param combine - A function to specify how to merge entries with the same key.
+     *
+     * @since 2.0.0
+     */
     <K1 extends string, A, B, C>(that: ReadonlyRecord<K1, B>, combine: (selfValue: A, thatValue: B) => C): <K0 extends string>(self: ReadonlyRecord<K0, A>) => Record<K0 | K1, A | B | C>;
+    /**
+     * Merge two records, preserving entries that exist in either of the records.
+     *
+     * @param self - The first record.
+     * @param that - The second record to combine with the first.
+     * @param combine - A function to specify how to merge entries with the same key.
+     *
+     * @since 2.0.0
+     */
     <K0 extends string, A, K1 extends string, B, C>(self: ReadonlyRecord<K0, A>, that: ReadonlyRecord<K1, B>, combine: (selfValue: A, thatValue: B) => C): Record<K0 | K1, A | B | C>;
 };
 /**
@@ -699,7 +1465,25 @@ export declare const union: {
  * @since 2.0.0
  */
 export declare const intersection: {
+    /**
+     * Merge two records, retaining only the entries that exist in both records.
+     *
+     * @param self - The first record.
+     * @param that - The second record to merge with the first.
+     * @param combine - A function to specify how to merge entries with the same key.
+     *
+     * @since 2.0.0
+     */
     <K1 extends string, A, B, C>(that: ReadonlyRecord<K1, B>, combine: (selfValue: A, thatValue: B) => C): <K0 extends string>(self: ReadonlyRecord<K0, A>) => Record<ReadonlyRecord.IntersectKeys<K0, K1>, C>;
+    /**
+     * Merge two records, retaining only the entries that exist in both records.
+     *
+     * @param self - The first record.
+     * @param that - The second record to merge with the first.
+     * @param combine - A function to specify how to merge entries with the same key.
+     *
+     * @since 2.0.0
+     */
     <K0 extends string, A, K1 extends string, B, C>(self: ReadonlyRecord<K0, A>, that: ReadonlyRecord<K1, B>, combine: (selfValue: A, thatValue: B) => C): Record<ReadonlyRecord.IntersectKeys<K0, K1>, C>;
 };
 /**
@@ -711,7 +1495,23 @@ export declare const intersection: {
  * @since 2.0.0
  */
 export declare const difference: {
+    /**
+     * Merge two records, preserving only the entries that are unique to each record.
+     *
+     * @param self - The first record.
+     * @param that - The second record to compare with the first.
+     *
+     * @since 2.0.0
+     */
     <K1 extends string, B>(that: ReadonlyRecord<K1, B>): <K0 extends string, A>(self: ReadonlyRecord<K0, A>) => Record<K0 | K1, A | B>;
+    /**
+     * Merge two records, preserving only the entries that are unique to each record.
+     *
+     * @param self - The first record.
+     * @param that - The second record to compare with the first.
+     *
+     * @since 2.0.0
+     */
     <K0 extends string, A, K1 extends string, B>(self: ReadonlyRecord<K0, A>, that: ReadonlyRecord<K1, B>): Record<K0 | K1, A | B>;
 };
 /**