effect 4.0.0-beta.69 → 4.0.0-beta.70

package/src/PrimaryKey.ts

@@ -23,6 +23,8 @@ export const symbol = "~effect/interfaces/PrimaryKey"
 /**
  * An interface for objects that can provide a string-based primary key.
  *
+ * **Details**
+ *
  * Objects implementing this interface must provide a method that returns
  * a unique string identifier.
  *
@@ -53,6 +55,8 @@ export interface PrimaryKey {
 /**
  * Checks whether a value implements the `PrimaryKey` protocol.
  *
+ * **Details**
+ *
  * This is a structural guard for the `PrimaryKey.symbol` property. It does not
  * call the method or verify that it returns a string.
  *

package/src/PubSub.ts

@@ -99,7 +99,7 @@ export interface PubSub<in out A> extends Pipeable {
  *
  * @since 2.0.0
  */
-export namespace PubSub {
+export declare namespace PubSub {
   /**
    * Low-level atomic PubSub interface that handles the core message storage and retrieval.
    *
@@ -135,7 +135,7 @@ export namespace PubSub {
   /**
    * Tracks the pollers currently waiting on each backing subscription.
    *
-   * **Notes**
+   * **Details**
    *
    * This type is part of the low-level `PubSub.Strategy` contract. Most
    * application code should use `subscribe`, `take`, and the other `PubSub`
@@ -312,13 +312,13 @@ export const make = <A>(
  * Creates a bounded `PubSub` that applies backpressure when it reaches
  * capacity.
  *
+ * **Details**
+ *
  * Published messages are retained until all current subscribers have taken
  * them. When the capacity is full, publishers suspend until space is available.
  * Pass an options object to configure both `capacity` and an optional replay
  * buffer for late subscribers.
  *
- *                   with capacity and optional replay buffer size
- *
  * **Example** (Creating a bounded PubSub)
  *
  * ```ts
@@ -354,6 +354,8 @@ export const bounded = <A>(
  * Creates a bounded `PubSub` with the dropping strategy. The `PubSub` will drop new
  * messages if the `PubSub` is at capacity.
  *
+ * **Details**
+ *
  * For best performance use capacities that are powers of two.
  *
  * **Example** (Dropping messages when full)
@@ -405,6 +407,8 @@ export const dropping = <A>(
  * Creates a bounded `PubSub` with the sliding strategy. The `PubSub` will add new
  * messages and drop old messages if the `PubSub` is at capacity.
  *
+ * **Details**
+ *
  * For best performance use capacities that are powers of two.
  *
  * **Example** (Sliding old messages when full)
@@ -555,6 +559,8 @@ export const capacity = <A>(self: PubSub<A>): number => self.pubsub.capacity
  * Returns the current number of messages retained by the `PubSub` for active
  * subscribers.
  *
+ * **Details**
+ *
  * If the `PubSub` has been shut down, the returned effect succeeds with `0`.
  * The size is not a count of waiting subscribers or suspended publishers.
  *
@@ -593,7 +599,7 @@ export const size = <A>(self: PubSub<A>): Effect.Effect<number> => Effect.sync((
  * Synchronously returns the current number of messages retained by the `PubSub`
  * for active subscribers.
  *
- * **Notes**
+ * **Details**
  *
  * Returns `0` after shutdown. Because this is an unsafe synchronous snapshot,
  * prefer `size` in effectful code.
@@ -623,6 +629,8 @@ export const sizeUnsafe = <A>(self: PubSub<A>): number => {
 /**
  * Returns `true` when the `PubSub` has reached its configured capacity.
  *
+ * **Details**
+ *
  * For unbounded PubSubs this is normally `false`.
  *
  * **Example** (Checking whether a PubSub is full)
@@ -696,6 +704,8 @@ export const isEmpty = <A>(self: PubSub<A>): Effect.Effect<boolean> => Effect.ma
  * Shuts down the `PubSub`, interrupting suspended publishers and subscribers
  * and finalizing active subscriptions.
  *
+ * **Details**
+ *
  * After shutdown, `publish` and `publishAll` succeed with `false`,
  * `publishUnsafe` returns `false`, and subscription operations such as `take`
  * interrupt.
@@ -826,6 +836,8 @@ export const awaitShutdown = <A>(self: PubSub<A>): Effect.Effect<void> => self.s
  * Attempts to publish a message synchronously without applying the PubSub
  * strategy's effectful surplus handling.
  *
+ * **Details**
+ *
  * Returns `false` if the `PubSub` is shut down or the message cannot be
  * accepted immediately, for example when a bounded PubSub is full. Prefer
  * `publish` when backpressure or sliding behavior should be honored.
@@ -860,6 +872,8 @@ export const publish: {
    * Attempts to publish a message synchronously without applying the PubSub
    * strategy's effectful surplus handling.
    *
+   * **Details**
+   *
    * Returns `false` if the `PubSub` is shut down or the message cannot be
    * accepted immediately, for example when a bounded PubSub is full. Prefer
    * `publish` when backpressure or sliding behavior should be honored.
@@ -894,6 +908,8 @@ export const publish: {
    * Attempts to publish a message synchronously without applying the PubSub
    * strategy's effectful surplus handling.
    *
+   * **Details**
+   *
    * Returns `false` if the `PubSub` is shut down or the message cannot be
    * accepted immediately, for example when a bounded PubSub is full. Prefer
    * `publish` when backpressure or sliding behavior should be honored.
@@ -1666,6 +1682,8 @@ const takeRemainderLoop = <A>(
 /**
  * Synchronously checks how many messages can be taken from a subscription.
  *
+ * **Details**
+ *
  * Returns `Option.some(count)` while the subscription is active, including
  * replay-buffered messages, and `Option.none()` after the subscription has
  * been shut down. Prefer `remaining` in effectful code.

package/src/Pull.ts

@@ -39,6 +39,8 @@ import * as Result from "./Result.ts"
  * An effectful pull step that either produces a value, fails with `E`, or
  * signals completion with `Cause.Done<Done>`.
  *
+ * **Details**
+ *
  * `Pull` represents completion in the error channel so low-level stream
  * consumers can distinguish ordinary failures from end-of-input and carry a
  * leftover value when needed.
@@ -100,6 +102,8 @@ export type ExcludeDone<E> = Exclude<E, Cause.Done<any>>
  * Handles `Cause.Done` failures in an effect while leaving ordinary failures
  * in the error channel.
  *
+ * **Details**
+ *
  * The handler receives the done leftover value and may recover with a new
  * effect. Non-done errors are preserved.
  *
@@ -115,6 +119,8 @@ export const catchDone: {
    * Handles `Cause.Done` failures in an effect while leaving ordinary failures
    * in the error channel.
    *
+   * **Details**
+   *
    * The handler receives the done leftover value and may recover with a new
    * effect. Non-done errors are preserved.
    *
@@ -132,6 +138,8 @@ export const catchDone: {
    * Handles `Cause.Done` failures in an effect while leaving ordinary failures
    * in the error channel.
    *
+   * **Details**
+   *
    * The handler receives the done leftover value and may recover with a new
    * effect. Non-done errors are preserved.
    *
@@ -169,6 +177,8 @@ export const isDoneFailure = <E>(
 /**
  * Finds a `Cause.Done` failure in a `Cause`.
  *
+ * **Details**
+ *
  * Returns a successful `Result` with the `Cause.Done` value when one is
  * present, otherwise returns a failed `Result` containing the non-done cause.
  *
@@ -186,6 +196,8 @@ export const filterDone: <E>(
 /**
  * Finds a `Cause.Done` failure in a cause whose done value is not used.
  *
+ * **Details**
+ *
  * Returns a successful `Result` with the done marker when present, otherwise
  * returns a failed `Result` with the non-done cause.
  *
@@ -202,6 +214,8 @@ export const filterDoneVoid: <E extends Cause.Done>(
 /**
  * Keeps a `Cause` only when it contains no `Cause.Done` failures.
  *
+ * **Details**
+ *
  * Returns a successful `Result` with the cause when every failure is non-done;
  * otherwise returns a failed `Result` with the original cause.
  *
@@ -234,6 +248,8 @@ export const filterDoneLeftover: <E>(
  * Converts a `Cause` into an `Exit`, treating `Cause.Done` as successful
  * completion.
  *
+ * **Details**
+ *
  * If the cause contains a done value, that leftover becomes the successful
  * value. Otherwise the non-done cause becomes the failure cause.
  *

package/src/Queue.ts

@@ -122,6 +122,8 @@ export const asDequeue: <A, E>(self: Queue<A, E>) => Dequeue<A, E> = identity
 /**
  * An `Enqueue` is a queue that can be offered to.
  *
+ * **Details**
+ *
  * This interface represents the write-only part of a Queue, allowing you to offer
  * elements to the queue but not take elements from it.
  *
@@ -166,6 +168,8 @@ export declare namespace Enqueue {
   /**
    * Type-level variance marker for `Enqueue`.
    *
+   * **Details**
+   *
    * `Enqueue` is contravariant in both its offered value type `A` and failure
    * type `E`, because values and failures flow into the queue through this
    * handle.
@@ -182,6 +186,8 @@ export declare namespace Enqueue {
 /**
  * A `Dequeue` is a queue that can be taken from.
  *
+ * **Details**
+ *
  * This interface represents the read-only part of a Queue, allowing you to take
  * elements from the queue but not offer elements to it.
  *
@@ -228,6 +234,8 @@ export declare namespace Dequeue {
   /**
    * Type-level variance marker for `Dequeue`.
    *
+   * **Details**
+   *
    * `Dequeue` is covariant in both the taken value type `A` and failure type
    * `E`, because values and failures are observed through this handle.
    *
@@ -243,6 +251,8 @@ export declare namespace Dequeue {
 /**
  * A `Queue` is an asynchronous queue that can be offered to and taken from.
  *
+ * **Details**
+ *
  * It also supports signaling that it is done or failed.
  *
  * **Example** (Offering and taking queue values)
@@ -284,6 +294,8 @@ export declare namespace Queue {
   /**
    * Type-level variance marker for `Queue`.
    *
+   * **Details**
+   *
    * A full `Queue` is invariant in both `A` and `E` because the same handle can
    * both produce and consume values and failures.
    *
@@ -298,6 +310,8 @@ export declare namespace Queue {
   /**
    * Tagged state of a `Queue`.
    *
+   * **Details**
+   *
    * `Open` queues can accept offers and takers, `Closing` queues are
    * completing with a stored failure exit, and `Done` queues have finished.
    * This is low-level metadata exposed by the queue model; most users should
@@ -328,6 +342,8 @@ export declare namespace Queue {
   /**
    * Represents a suspended offer waiting to be admitted to a bounded queue.
    *
+   * **Details**
+   *
    * An entry is either a single message or a batch with an offset into its
    * remaining messages, plus a resume callback that completes the suspended
    * offer when the queue can accept more input.
@@ -370,6 +386,8 @@ const QueueProto = {
 /**
  * Creates a `Queue` with optional capacity and overflow strategy.
  *
+ * **Details**
+ *
  * By default the queue is unbounded and uses the `"suspend"` strategy. Provide
  * `capacity` for a bounded queue and choose `"suspend"`, `"dropping"`, or
  * `"sliding"` to control what happens when the queue is full. The returned
@@ -432,6 +450,8 @@ export const make = <A, E = never>(
 /**
  * Creates a bounded queue with the specified capacity that uses backpressure strategy.
  *
+ * **Details**
+ *
  * When the queue reaches capacity, producers will be suspended until space becomes available.
  * This ensures all messages are processed but may slow down producers.
  *
@@ -461,6 +481,8 @@ export const bounded = <A, E = never>(capacity: number): Effect<Queue<A, E>> =>
  * Creates a bounded queue with sliding strategy. When the queue reaches capacity,
  * new elements are added and the oldest elements are dropped.
  *
+ * **When to use**
+ *
  * This strategy prevents producers from being blocked but may result in message loss.
  * Useful when you want to maintain a rolling window of the most recent messages.
  *
@@ -494,6 +516,8 @@ export const sliding = <A, E = never>(capacity: number): Effect<Queue<A, E>> =>
  * Creates a bounded queue with dropping strategy. When the queue reaches capacity,
  * new elements are dropped and the offer operation returns false.
  *
+ * **When to use**
+ *
  * This strategy prevents producers from being blocked and preserves existing messages,
  * but new messages may be lost when the queue is full.
  *
@@ -528,6 +552,8 @@ export const dropping = <A, E = never>(capacity: number): Effect<Queue<A, E>> =>
 /**
  * Creates an unbounded queue that can grow to any size without blocking producers.
  *
+ * **When to use**
+ *
  * Unlike bounded queues, unbounded queues never apply backpressure - producers
  * can always add messages successfully. This is useful when you want to prioritize
  * producer throughput over memory usage control.
@@ -563,6 +589,8 @@ export const unbounded = <A, E = never>(): Effect<Queue<A, E>> => make()
 /**
  * Add a message to the queue. Returns `false` if the queue is done.
  *
+ * **Details**
+ *
  * For bounded queues, this operation may suspend if the queue is at capacity,
  * depending on the backpressure strategy. For dropping/sliding queues, it may
  * return false or succeed immediately by dropping/sliding existing messages.
@@ -618,6 +646,8 @@ export const offer = <A, E>(self: Enqueue<A, E>, message: Types.NoInfer<A>): Eff
 /**
  * Add a message to the queue synchronously. Returns `false` if the queue is done.
  *
+ * **Gotchas**
+ *
  * This is an unsafe operation that directly modifies the queue without Effect wrapping.
  * Use this only when you're certain about the synchronous nature of the operation.
  *
@@ -668,6 +698,8 @@ export const offerUnsafe = <A, E>(self: Enqueue<A, E>, message: Types.NoInfer<A>
  * Add multiple messages to the queue. Returns the remaining messages that
  * were not added.
  *
+ * **Details**
+ *
  * For bounded queues, this operation may suspend if the queue doesn't have
  * enough capacity. The operation returns an array of messages that couldn't
  * be added (empty array means all messages were successfully added).
@@ -707,6 +739,8 @@ export const offerAll = <A, E>(self: Enqueue<A, E>, messages: Iterable<A>): Effe
  * Add multiple messages to the queue synchronously. Returns the remaining messages that
  * were not added.
  *
+ * **Gotchas**
+ *
  * This is an unsafe operation that directly modifies the queue without Effect wrapping.
  *
  * **Example** (Offering multiple values synchronously)
@@ -880,6 +914,8 @@ export const failCause: {
  * Fail the queue with a cause synchronously. If the queue is already done, `false` is
  * returned.
  *
+ * **Gotchas**
+ *
  * This is an unsafe operation that directly modifies the queue without Effect wrapping.
  *
  * **Example** (Failing queues with a cause synchronously)
@@ -959,6 +995,8 @@ export const end = <A, E>(self: Enqueue<A, E | Done>): Effect<boolean> => failCa
  * Signal that the queue is complete synchronously. If the queue is already done, `false` is
  * returned.
  *
+ * **Gotchas**
+ *
  * This is an unsafe operation that directly modifies the queue without Effect wrapping.
  *
  * **Example** (Ending queues synchronously)
@@ -997,6 +1035,8 @@ export const endUnsafe = <A, E>(self: Enqueue<A, E | Done>) => failCauseUnsafe(s
 /**
  * Interrupts the queue gracefully, transitioning it to a closing state.
  *
+ * **Details**
+ *
  * This operation stops accepting new offers but allows existing messages to be consumed.
  * Once all messages are drained, the queue transitions to the Done state with an interrupt cause.
  *
@@ -1313,6 +1353,8 @@ export const takeBetween = <A, E>(
  * Take a single message from the queue, or wait for a message to be
  * available.
  *
+ * **Details**
+ *
  * If the queue is done, it will fail with `Done`. If the
  * queue fails, the Effect will fail with the error.
  *
@@ -1401,6 +1443,8 @@ export const poll = <A, E>(self: Dequeue<A, E>): Effect<Option.Option<A>> =>
 /**
  * Views the next item without removing it.
  *
+ * **Details**
+ *
  * Blocks until an item is available. If the queue is done or fails, the error is propagated.
  *
  * **Example** (Peeking at the next value)

package/src/Random.ts

@@ -39,6 +39,8 @@ import * as Predicate from "./Predicate.ts"
 /**
  * Represents a service for generating pseudo-random numbers.
  *
+ * **Gotchas**
+ *
  * The default implementation is based on `Math.random` and is not
  * cryptographically secure. Replace the service with a cryptographically secure
  * implementation before using these generators for security-sensitive values.
@@ -151,6 +153,8 @@ export const nextBetween = (min: number, max: number): Effect.Effect<number> =>
 /**
  * Generates a random integer between `min` and `max`.
  *
+ * **Details**
+ *
  * The lower bound is rounded up with `Math.ceil` and the upper bound is
  * rounded down with `Math.floor`. By default the range is inclusive; set
  * `options.halfOpen: true` to exclude the upper bound.
@@ -215,9 +219,14 @@ export const shuffle = <A>(elements: Iterable<A>): Effect.Effect<Array<A>> =>
 /**
  * Seeds the pseudo-random number generator with the specified value.
  *
+ * **Details**
+ *
  * Using the same seed produces the same random sequence, which is useful for
- * tests and reproducible simulations. Use an unpredictable seed when uniqueness
- * or unpredictability matters.
+ * tests and reproducible simulations.
+ *
+ * **Gotchas**
+ *
+ * Use an unpredictable seed when uniqueness or unpredictability matters.
  *
  * **Example** (Seeding random generation)
  *
@@ -246,9 +255,14 @@ export const withSeed: {
   /**
    * Seeds the pseudo-random number generator with the specified value.
    *
+   * **Details**
+   *
    * Using the same seed produces the same random sequence, which is useful for
-   * tests and reproducible simulations. Use an unpredictable seed when uniqueness
-   * or unpredictability matters.
+   * tests and reproducible simulations.
+   *
+   * **Gotchas**
+   *
+   * Use an unpredictable seed when uniqueness or unpredictability matters.
    *
    * **Example** (Seeding random generation)
    *
@@ -277,9 +291,14 @@ export const withSeed: {
   /**
    * Seeds the pseudo-random number generator with the specified value.
    *
+   * **Details**
+   *
    * Using the same seed produces the same random sequence, which is useful for
-   * tests and reproducible simulations. Use an unpredictable seed when uniqueness
-   * or unpredictability matters.
+   * tests and reproducible simulations.
+   *
+   * **Gotchas**
+   *
+   * Use an unpredictable seed when uniqueness or unpredictability matters.
    *
    * **Example** (Seeding random generation)
    *

package/src/RcMap.ts

@@ -83,6 +83,7 @@ export interface RcMap<in out K, in out A, in out E = never> extends Pipeable {
 /**
  * Represents the internal state of an RcMap, which can be either Open (active)
  * or Closed (shutdown and no longer accepting operations).
+ *
  * @category models
  * @since 4.0.0
  */
@@ -97,6 +98,7 @@ export declare namespace State {
   /**
    * Represents the open/active state of an RcMap, containing the actual
    * resource map that stores entries.
+   *
    * @category models
    * @since 4.0.0
    */
@@ -108,6 +110,7 @@ export declare namespace State {
   /**
    * Represents the closed state of an RcMap, indicating that the map has been
    * shut down and will no longer accept new operations.
+   *
    * @category models
    * @since 4.0.0
    */
@@ -118,6 +121,7 @@ export declare namespace State {
   /**
    * Represents an individual entry in the RcMap, containing the resource's
    * metadata including reference count, expiration time, and lifecycle management.
+   *
    * @category models
    * @since 4.0.0
    */
@@ -159,9 +163,9 @@ const makeUnsafe = <K, A, E>(options: {
  * by a key. The resources are lazily acquired on the first call to `get` and
  * released when the last reference is released.
  *
- * Complex keys can extend `Equal` and `Hash` to allow lookups by value.
+ * **Details**
  *
- * **Options**
+ * Complex keys can extend `Equal` and `Hash` to allow lookups by value.
  *
  * - `capacity`: The maximum number of resources that can be held in the map.
  * - `idleTimeToLive`: When the reference count reaches zero, the resource will be released after this duration.
@@ -198,9 +202,9 @@ export const make: {
    * by a key. The resources are lazily acquired on the first call to `get` and
    * released when the last reference is released.
    *
-   * Complex keys can extend `Equal` and `Hash` to allow lookups by value.
+   * **Details**
    *
-   * **Options**
+   * Complex keys can extend `Equal` and `Hash` to allow lookups by value.
    *
    * - `capacity`: The maximum number of resources that can be held in the map.
    * - `idleTimeToLive`: When the reference count reaches zero, the resource will be released after this duration.
@@ -243,9 +247,9 @@ export const make: {
    * by a key. The resources are lazily acquired on the first call to `get` and
    * released when the last reference is released.
    *
-   * Complex keys can extend `Equal` and `Hash` to allow lookups by value.
+   * **Details**
    *
-   * **Options**
+   * Complex keys can extend `Equal` and `Hash` to allow lookups by value.
    *
    * - `capacity`: The maximum number of resources that can be held in the map.
    * - `idleTimeToLive`: When the reference count reaches zero, the resource will be released after this duration.

package/src/RcRef.ts

@@ -29,6 +29,8 @@ const TypeId = "~effect/RcRef"
 /**
  * A reference counted reference that manages resource lifecycle.
  *
+ * **Details**
+ *
  * An RcRef wraps a resource that can be acquired and released multiple times.
  * The resource is lazily acquired on the first call to `get` and automatically
  * released when the last reference is released.
@@ -85,7 +87,7 @@ export declare namespace RcRef {
   /**
    * Type-level variance marker for `RcRef`.
    *
-   * **Notes**
+   * **Details**
    *
    * This interface records the covariant value and error types carried by an
    * `RcRef`. It is used by Effect's type machinery and is not normally

package/src/Record.ts

@@ -319,6 +319,8 @@ export const fromIterableBy = <A, K extends string | symbol>(
 /**
  * Builds a record from an iterable of key-value pairs.
  *
+ * **Details**
+ *
  * 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.
  *
@@ -650,6 +652,8 @@ export const modify: {
  * Replaces the value at an existing key and returns the updated record in
  * `Option.some`.
  *
+ * **Details**
+ *
  * If the key is not present, returns `Option.none()` and leaves the record
  * unchanged.
  *
@@ -670,6 +674,8 @@ export const replace: {
    * Replaces the value at an existing key and returns the updated record in
    * `Option.some`.
    *
+   * **Details**
+   *
    * If the key is not present, returns `Option.none()` and leaves the record
    * unchanged.
    *
@@ -690,6 +696,8 @@ export const replace: {
    * Replaces the value at an existing key and returns the updated record in
    * `Option.some`.
    *
+   * **Details**
+   *
    * If the key is not present, returns `Option.none()` and leaves the record
    * unchanged.
    *
@@ -1349,6 +1357,8 @@ export const getSuccesses = <K extends string, A, E>(
  * Applies a function to each record entry and partitions the returned `Result`
  * values into two records.
  *
+ * **Details**
+ *
  * Failure values are collected in the left record, and success values are
  * collected in the right record, preserving the original keys.
  *
@@ -1371,6 +1381,8 @@ export const partition: {
    * Applies a function to each record entry and partitions the returned `Result`
    * values into two records.
    *
+   * **Details**
+   *
    * Failure values are collected in the left record, and success values are
    * collected in the right record, preserving the original keys.
    *
@@ -1395,6 +1407,8 @@ export const partition: {
    * Applies a function to each record entry and partitions the returned `Result`
    * values into two records.
    *
+   * **Details**
+   *
    * Failure values are collected in the left record, and success values are
    * collected in the right record, preserving the original keys.
    *
@@ -1602,6 +1616,8 @@ export const isSubrecordBy = <A>(equivalence: Equivalence<A>): {
 /**
  * Checks whether the first record is a subrecord of the second record.
  *
+ * **Details**
+ *
  * Returns `true` when every key and value in `self` is also present in `that`.
  * Values are compared with Effect equality via `Equal.asEquivalence()`.
  *
@@ -1628,6 +1644,8 @@ export const isSubrecord: {
   /**
    * Checks whether the first record is a subrecord of the second record.
    *
+   * **Details**
+   *
    * Returns `true` when every key and value in `self` is also present in `that`.
    * Values are compared with Effect equality via `Equal.asEquivalence()`.
    *
@@ -1654,6 +1672,8 @@ export const isSubrecord: {
   /**
    * Checks whether the first record is a subrecord of the second record.
    *
+   * **Details**
+   *
    * Returns `true` when every key and value in `self` is also present in `that`.
    * Values are compared with Effect equality via `Equal.asEquivalence()`.
    *
@@ -2226,9 +2246,8 @@ export const singleton = <K extends string | symbol, A>(key: K, value: A): Recor
 } as any)
 
 /**
- * A `Reducer` for combining `Record`s using union.
- *
- * Values for keys that exist in both records are combined using the provided `Combiner`.
+ * Creates a `Reducer` for combining `Record`s using union, with values for keys that exist in both records combined
+ * using the provided `Combiner`.
  *
  * @category combining
  * @since 4.0.0
@@ -2244,6 +2263,8 @@ export function makeReducerUnion<K extends string, A>(combiner: Combiner.Combine
  * Creates a `Reducer` whose `combine` operation intersects two records and
  * combines values for keys present in both records.
  *
+ * **Gotchas**
+ *
  * The reducer's `initialValue` is an empty record. Because intersection with
  * an empty record is empty, the default `combineAll` folds from `{}` and
  * therefore produces `{}` for ordinary non-empty inputs.