effect 4.0.0-beta.70 → 4.0.0-beta.72

package/dist/Channel.d.ts

@@ -1,60 +1,72 @@
 /**
- * The `Channel` module provides a powerful abstraction for bi-directional communication
- * and streaming operations. A `Channel` is a nexus of I/O operations that supports both
- * reading and writing, forming the foundation for Effect's Stream and Sink abstractions.
- *
- * ## What is a Channel?
- *
- * A `Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>` represents:
- * - **OutElem**: The type of elements the channel outputs
- * - **OutErr**: The type of errors the channel can produce
- * - **OutDone**: The type of the final value when the channel completes
- * - **InElem**: The type of elements the channel reads
- * - **InErr**: The type of errors the channel can receive
- * - **InDone**: The type of the final value from upstream
- * - **Env**: The environment/context required by the channel
- *
- * ## Key Features
- *
- * - **Bi-directional**: Channels can both read and write
- * - **Composable**: Channels can be piped, sequenced, and concatenated
- * - **Resource-safe**: Automatic cleanup and resource management
- * - **Error-handling**: Built-in error propagation and handling
- * - **Concurrent**: Support for concurrent operations
- *
- * ## Composition Patterns
- *
- * 1. **Piping**: Connect channels where output of one becomes input of another
- * 2. **Sequencing**: Use the result of one channel to create another
- * 3. **Concatenating**: Combine multiple channels into a single channel
- *
- * **Example** (Creating a simple channel)
+ * The `Channel` module provides the low-level stream processing primitive used
+ * to build Effect streams, sinks, and stream operators.
+ *
+ * A `Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>` describes a
+ * scoped process that can read elements from an upstream input, emit elements
+ * downstream, fail with a typed error, or complete with a typed done value.
+ * Most application code works with higher-level stream APIs; channels are for
+ * implementing reusable streaming primitives, adapting pull-based sources, and
+ * controlling how input, output, errors, final values, and resources compose.
+ *
+ * **Mental model**
+ *
+ * - `OutElem`, `OutErr`, and `OutDone` describe the values, failures, and final
+ *   value produced by the channel.
+ * - `InElem`, `InErr`, and `InDone` describe the upstream protocol consumed by
+ *   the channel when it is piped after another channel.
+ * - `Env` is the Effect environment required while the channel is interpreted.
+ * - Constructors such as {@link fromArray}, {@link fromIterable},
+ *   {@link fromEffect}, {@link succeed}, and {@link fail} create sources.
+ * - Combinators such as {@link map}, {@link mapEffect}, {@link flatMap}, and
+ *   {@link pipeTo} transform, sequence, and connect channels.
+ * - Execution functions such as {@link runCollect} and {@link runDrain}
+ *   interpret channels that no longer require upstream input.
+ *
+ * **Common tasks**
+ *
+ * - Build finite sources from values, arrays, iterables, queues, pub/sub
+ *   subscriptions, effects, or pulls.
+ * - Transform output elements with pure or effectful functions.
+ * - Connect channels with {@link pipeTo} when one channel's output protocol
+ *   should become another channel's input protocol.
+ * - Sequence dependent channels with {@link flatMap}, or concatenate channels
+ *   with {@link concat}.
+ * - Manage channel-scoped resources with {@link acquireRelease} and
+ *   {@link ensuring}.
+ * - Bridge to lower-level pull loops with {@link toPull} and {@link fromPull}.
+ *
+ * **Example** (Collecting transformed output)
  *
  * ```ts
- * import { Channel } from "effect"
- *
- * // Simple channel that outputs numbers
- * const numberChannel = Channel.succeed(42)
+ * import { Channel, Effect } from "effect"
  *
- * // Transform channel that doubles values
- * const doubleChannel = Channel.map(numberChannel, (n) => n * 2)
+ * const program = Channel.fromArray([1, 2, 3]).pipe(
+ *   Channel.map((n) => n * 2),
+ *   Channel.runCollect
+ * )
  *
- * // Running the channel would output: 84
+ * Effect.runPromise(program).then(console.log)
  * ```
  *
- * **Example** (Transforming array-backed channels)
+ * **Gotchas**
  *
- * ```ts
- * import { Channel } from "effect"
- *
- * // Channel from an array of values
- * const arrayChannel = Channel.fromArray([1, 2, 3, 4, 5])
+ * - A channel's done value is distinct from its emitted elements; use
+ *   done-focused APIs when the final value matters.
+ * - `pipeTo` connects the output side of the left channel to the input side of
+ *   the right channel, so type errors usually mean those protocols do not line
+ *   up.
+ * - Resource finalizers run when the channel scope closes, not when a channel
+ *   value is merely constructed.
+ * - Prefer stream and sink APIs unless you are implementing lower-level
+ *   streaming behavior.
  *
- * // Transform the channel by mapping over values
- * const transformedChannel = Channel.map(arrayChannel, (n) => n * 2)
+ * **See also**
  *
- * // This channel will output: 2, 4, 6, 8, 10
- * ```
+ * - {@link Channel} for the type parameters and variance of channel values.
+ * - {@link pipeTo} for wiring one channel into another.
+ * - {@link runCollect}, {@link runDrain}, and {@link runDone} for common
+ *   execution modes.
  *
  * @since 2.0.0
  */
@@ -83,7 +95,7 @@ import type * as Unify from "./Unify.ts";
 /**
  * String literal type used as the unique brand for `Channel` values.
  *
- * @category Type Identifiers
+ * @category type IDs
  * @since 4.0.0
  */
 export type TypeId = "~effect/Channel";
@@ -91,12 +103,12 @@ export type TypeId = "~effect/Channel";
  * Runtime identifier stored on `Channel` values and used by `isChannel` to
  * recognize them.
  *
- * @category Type Identifiers
+ * @category type IDs
  * @since 4.0.0
  */
 export declare const TypeId: TypeId;
 /**
- * Tests if a value is a `Channel`.
+ * Checks whether a value is a `Channel`.
  *
  * **Example** (Checking for channels)
  *
@@ -306,6 +318,13 @@ export declare const fromPull: <OutElem, OutErr, OutDone, EX, EnvX, Env>(effect:
  * pulls, but also provides a forked scope that closes when the resulting
  * Channel completes.
  *
+ * **When to use**
+ *
+ * Use when building channels that require scoped resource lifecycle management,
+ * providing both the channel scope and a forked scope that automatically closes
+ * when the channel completes.
+ *
+ * @see {@link fromTransform} for a simpler transformation without a forked scope
  * @category constructors
  * @since 4.0.0
  */
@@ -698,7 +717,7 @@ export declare const endSync: <A>(evaluate: LazyArg<A>) => Channel<never, never,
  */
 export declare const sync: <A>(evaluate: LazyArg<A>) => Channel<A>;
 /**
- * Represents an Channel that emits no elements
+ * Represents a `Channel` that emits no elements.
  *
  * **Example** (Using empty channels)
  *
@@ -722,7 +741,7 @@ export declare const sync: <A>(evaluate: LazyArg<A>) => Channel<A>;
  */
 export declare const empty: Channel<never>;
 /**
- * Represents an Channel that never completes
+ * Represents a `Channel` that never completes.
  *
  * **Example** (Using non-terminating channels)
  *
@@ -889,7 +908,7 @@ export declare const failCauseSync: <E>(evaluate: LazyArg<Cause.Cause<E>>) => Ch
  */
 export declare const die: (defect: unknown) => Channel<never, never, never>;
 /**
- * Use an effect to write a single value to the channel.
+ * Uses an effect to write a single value to the channel.
  *
  * **Example** (Creating channels from effects)
  *
@@ -939,7 +958,7 @@ export declare const fromEffect: <A, E, R>(effect: Effect.Effect<A, E, R>) => Ch
  */
 export declare const fromEffectDone: <A, E, R>(effect: Effect.Effect<A, E, R>) => Channel<never, Pull.ExcludeDone<E>, A, unknown, unknown, unknown, R>;
 /**
- * Use an effect and discard its result.
+ * Uses an effect and discards its result.
  *
  * @category constructors
  * @since 4.0.0
@@ -959,7 +978,7 @@ export declare const fromEffectDrain: <A, E, R>(effect: Effect.Effect<A, E, R>)
  */
 export declare const fromEffectTake: <A, E, Done, E2, R>(effect: Effect.Effect<Take.Take<A, E, Done>, E2, R>) => Channel<Arr.NonEmptyReadonlyArray<A>, E | E2, Done, unknown, unknown, unknown, R>;
 /**
- * Create a channel from a queue
+ * Creates a channel from a queue.
  *
  * **Example** (Creating channels from queues)
  *
@@ -999,7 +1018,7 @@ export declare const fromEffectTake: <A, E, Done, E2, R>(effect: Effect.Effect<T
  */
 export declare const fromQueue: <A, E>(queue: Queue.Dequeue<A, E>) => Channel<A, Exclude<E, Cause.Done>>;
 /**
- * Create a channel from a queue that emits arrays of elements
+ * Creates a channel from a queue that emits arrays of elements.
  *
  * **Example** (Creating batched channels from queues)
  *
@@ -1051,7 +1070,7 @@ export declare const fromQueueArray: <A, E>(queue: Queue.Dequeue<A, E>) => Chann
  */
 export declare const identity: <Elem, Err, Done>() => Channel<Elem, Err, Done, Elem, Err, Done>;
 /**
- * Create a channel from a PubSub subscription
+ * Creates a channel from a PubSub subscription.
  *
  * **Example** (Creating channels from subscriptions)
  *
@@ -1096,7 +1115,7 @@ export declare const identity: <Elem, Err, Done>() => Channel<Elem, Err, Done, E
  */
 export declare const fromSubscription: <A>(subscription: PubSub.Subscription<A>) => Channel<A>;
 /**
- * Create a channel from a PubSub subscription that outputs arrays of values.
+ * Creates a channel from a PubSub subscription that outputs arrays of values.
  *
  * **Details**
  *
@@ -1199,7 +1218,7 @@ export declare const fromSubscription: <A>(subscription: PubSub.Subscription<A>)
  */
 export declare const fromSubscriptionArray: <A>(subscription: PubSub.Subscription<A>) => Channel<Arr.NonEmptyReadonlyArray<A>>;
 /**
- * Create a channel from a PubSub that outputs individual values.
+ * Creates a channel from a PubSub that outputs individual values.
  *
  * **Details**
  *
@@ -1293,7 +1312,7 @@ export declare const fromSubscriptionArray: <A>(subscription: PubSub.Subscriptio
  */
 export declare const fromPubSub: <A>(pubsub: PubSub.PubSub<A>) => Channel<A>;
 /**
- * Create a channel from a PubSub that outputs arrays of values.
+ * Creates a channel from a PubSub that outputs arrays of values.
  *
  * **Details**
  *
@@ -2238,33 +2257,54 @@ export declare const concat: {
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, that: Channel<OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>): Channel<OutElem | OutElem1, OutErr1 | OutErr, OutDone1, InElem & InElem1, InErr & InErr1, InDone & InDone1, Env1 | Env>;
 };
 /**
- * Combines the elements from this channel and the specified channel by
- * repeatedly applying the function `f` to extract an element using both sides
- * and conceptually "offer" it to the destination channel. `f` can maintain
- * some internal state to control the combining process, with the initial
- * state being specified by `s`.
+ * Combines two channels with a stateful pull function.
+ *
+ * **When to use**
+ *
+ * Use to coordinate pulling from two channels when each output element depends
+ * on both sides and local state.
+ *
+ * **Details**
+ *
+ * The combining function receives the current state and pull functions for the
+ * left and right channels. It returns the next output element together with the
+ * next state.
  *
  * @category sequencing
  * @since 4.0.0
  */
 export declare const combine: {
     /**
-     * Combines the elements from this channel and the specified channel by
-     * repeatedly applying the function `f` to extract an element using both sides
-     * and conceptually "offer" it to the destination channel. `f` can maintain
-     * some internal state to control the combining process, with the initial
-     * state being specified by `s`.
+     * Combines two channels with a stateful pull function.
+     *
+     * **When to use**
+     *
+     * Use to coordinate pulling from two channels when each output element depends
+     * on both sides and local state.
+     *
+     * **Details**
+     *
+     * The combining function receives the current state and pull functions for the
+     * left and right channels. It returns the next output element together with the
+     * next state.
      *
      * @category sequencing
      * @since 4.0.0
      */
     <OutElem2, OutErr2, OutDone2, InElem2, InErr2, InDone2, Env2, S, OutElem, OutErr, OutDone, A, E, R>(that: Channel<OutElem2, OutErr2, OutDone2, InElem2, InErr2, InDone2, Env2>, s: LazyArg<S>, f: (s: S, pullLeft: Pull.Pull<OutElem, OutErr, OutDone>, pullRight: Pull.Pull<OutElem2, OutErr2, OutDone2>) => Effect.Effect<readonly [A, S], E, R>): <InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<A, Pull.ExcludeDone<E>, Cause.Done.Extract<E>, InElem & InElem2, InErr & InErr2, InDone & InDone2, Env | Env2 | R>;
     /**
-     * Combines the elements from this channel and the specified channel by
-     * repeatedly applying the function `f` to extract an element using both sides
-     * and conceptually "offer" it to the destination channel. `f` can maintain
-     * some internal state to control the combining process, with the initial
-     * state being specified by `s`.
+     * Combines two channels with a stateful pull function.
+     *
+     * **When to use**
+     *
+     * Use to coordinate pulling from two channels when each output element depends
+     * on both sides and local state.
+     *
+     * **Details**
+     *
+     * The combining function receives the current state and pull functions for the
+     * left and right channels. It returns the next output element together with the
+     * next state.
      *
      * @category sequencing
      * @since 4.0.0
@@ -2315,7 +2355,7 @@ export declare const orElseIfEmpty: {
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, f: (leftover: Types.NoInfer<OutDone>) => Channel<OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>): Channel<OutElem | OutElem1, OutErr1 | OutErr, OutDone | OutDone1, InElem & InElem1, InErr & InErr1, InDone & InDone1, Env1 | Env>;
 };
 /**
- * Flatten a channel of channels.
+ * Flattens a channel of channels.
  *
  * **Example** (Flattening nested channels)
  *
@@ -2632,12 +2672,21 @@ export declare const filter: {
 /**
  * Filters and maps output elements using a `Filter`.
  *
+ * **When to use**
+ *
+ * Use to keep only channel output elements accepted by a `Filter` and emit
+ * each filter success value.
+ *
  * **Details**
  *
  * Successful filter results are emitted as mapped values. Failed filter
  * results are discarded. The source channel's errors and done value are
  * preserved.
  *
+ * @see {@link filter} for keeping original output elements with a predicate
+ * @see {@link filterMapEffect} for using an effectful `Filter`
+ * @see {@link filterMapArray} for filtering arrays of output elements
+ *
  * @category filtering
  * @since 4.0.0
  */
@@ -2645,12 +2694,21 @@ export declare const filterMap: {
     /**
      * Filters and maps output elements using a `Filter`.
      *
+     * **When to use**
+     *
+     * Use to keep only channel output elements accepted by a `Filter` and emit
+     * each filter success value.
+     *
      * **Details**
      *
      * Successful filter results are emitted as mapped values. Failed filter
      * results are discarded. The source channel's errors and done value are
      * preserved.
      *
+     * @see {@link filter} for keeping original output elements with a predicate
+     * @see {@link filterMapEffect} for using an effectful `Filter`
+     * @see {@link filterMapArray} for filtering arrays of output elements
+     *
      * @category filtering
      * @since 4.0.0
      */
@@ -2658,12 +2716,21 @@ export declare const filterMap: {
     /**
      * Filters and maps output elements using a `Filter`.
      *
+     * **When to use**
+     *
+     * Use to keep only channel output elements accepted by a `Filter` and emit
+     * each filter success value.
+     *
      * **Details**
      *
      * Successful filter results are emitted as mapped values. Failed filter
      * results are discarded. The source channel's errors and done value are
      * preserved.
      *
+     * @see {@link filter} for keeping original output elements with a predicate
+     * @see {@link filterMapEffect} for using an effectful `Filter`
+     * @see {@link filterMapArray} for filtering arrays of output elements
+     *
      * @category filtering
      * @since 4.0.0
      */
@@ -2712,12 +2779,22 @@ export declare const filterEffect: {
 /**
  * Filters and maps output elements using an effectful `Filter`.
  *
+ * **When to use**
+ *
+ * Use to apply effectful logic that can discard channel output elements and
+ * emit transformed values for the elements that pass.
+ *
  * **Details**
  *
  * Successful filter results are emitted as mapped values. Failed filter
  * results are discarded. Failures from the effectful filter fail the returned
  * channel.
  *
+ * @see {@link filterMap} for using a synchronous `Filter`
+ * @see {@link filterEffect} for effectfully keeping original output elements
+ * @see {@link mapEffect} for effectfully transforming every output element
+ * @see {@link filterMapArrayEffect} for effectful filtering of array outputs
+ *
  * @category filtering
  * @since 4.0.0
  */
@@ -2725,12 +2802,22 @@ export declare const filterMapEffect: {
     /**
      * Filters and maps output elements using an effectful `Filter`.
      *
+     * **When to use**
+     *
+     * Use to apply effectful logic that can discard channel output elements and
+     * emit transformed values for the elements that pass.
+     *
      * **Details**
      *
      * Successful filter results are emitted as mapped values. Failed filter
      * results are discarded. Failures from the effectful filter fail the returned
      * channel.
      *
+     * @see {@link filterMap} for using a synchronous `Filter`
+     * @see {@link filterEffect} for effectfully keeping original output elements
+     * @see {@link mapEffect} for effectfully transforming every output element
+     * @see {@link filterMapArrayEffect} for effectful filtering of array outputs
+     *
      * @category filtering
      * @since 4.0.0
      */
@@ -2738,12 +2825,22 @@ export declare const filterMapEffect: {
     /**
      * Filters and maps output elements using an effectful `Filter`.
      *
+     * **When to use**
+     *
+     * Use to apply effectful logic that can discard channel output elements and
+     * emit transformed values for the elements that pass.
+     *
      * **Details**
      *
      * Successful filter results are emitted as mapped values. Failed filter
      * results are discarded. Failures from the effectful filter fail the returned
      * channel.
      *
+     * @see {@link filterMap} for using a synchronous `Filter`
+     * @see {@link filterEffect} for effectfully keeping original output elements
+     * @see {@link mapEffect} for effectfully transforming every output element
+     * @see {@link filterMapArrayEffect} for effectful filtering of array outputs
+     *
      * @category filtering
      * @since 4.0.0
      */
@@ -3062,7 +3159,7 @@ export declare const filterMapArrayEffect: {
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, B, X, EX, RX>(self: Channel<Arr.NonEmptyReadonlyArray<OutElem>, OutErr, OutDone, InElem, InErr, InDone, Env>, filter: Filter.FilterEffect<OutElem, B, X, EX, RX>): Channel<Arr.NonEmptyReadonlyArray<B>, OutErr | EX, OutDone, InElem, InErr, InDone, Env | RX>;
 };
 /**
- * Statefully maps over a channel with an accumulator, where each element can produce multiple output values.
+ * Maps over a channel statefully with an accumulator, where each element can produce multiple output values.
  *
  * **Example** (Mapping with accumulated state)
  *
@@ -3101,7 +3198,7 @@ export declare const filterMapArrayEffect: {
  */
 export declare const mapAccum: {
     /**
-     * Statefully maps over a channel with an accumulator, where each element can produce multiple output values.
+     * Maps over a channel statefully with an accumulator, where each element can produce multiple output values.
      *
      * **Example** (Mapping with accumulated state)
      *
@@ -3142,7 +3239,7 @@ export declare const mapAccum: {
         readonly onHalt?: ((state: S) => Array<B>) | undefined;
     }): <OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<B, OutErr | E, OutDone, InElem, InErr, InDone, Env | R>;
     /**
-     * Statefully maps over a channel with an accumulator, where each element can produce multiple output values.
+     * Maps over a channel statefully with an accumulator, where each element can produce multiple output values.
      *
      * **Example** (Mapping with accumulated state)
      *
@@ -3184,7 +3281,7 @@ export declare const mapAccum: {
     }): Channel<B, OutErr | E, OutDone, InElem, InErr, InDone, Env | R>;
 };
 /**
- * Statefully transforms a channel by scanning over its output with an accumulator function.
+ * Transforms a channel statefully by scanning over its output with an accumulator function.
  * Emits the intermediate results of the scan operation.
  *
  * **Example** (Scanning channel output)
@@ -3215,7 +3312,7 @@ export declare const mapAccum: {
  */
 export declare const scan: {
     /**
-     * Statefully transforms a channel by scanning over its output with an accumulator function.
+     * Transforms a channel statefully by scanning over its output with an accumulator function.
      * Emits the intermediate results of the scan operation.
      *
      * **Example** (Scanning channel output)
@@ -3246,7 +3343,7 @@ export declare const scan: {
      */
     <S, OutElem>(initial: S, f: (s: S, a: Types.NoInfer<OutElem>) => S): <OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<S, OutErr, OutDone, InElem, InErr, InDone, Env>;
     /**
-     * Statefully transforms a channel by scanning over its output with an accumulator function.
+     * Transforms a channel statefully by scanning over its output with an accumulator function.
      * Emits the intermediate results of the scan operation.
      *
      * **Example** (Scanning channel output)
@@ -3278,7 +3375,7 @@ export declare const scan: {
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, S>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, initial: S, f: (s: S, a: Types.NoInfer<OutElem>) => S): Channel<S, OutErr, OutDone, InElem, InErr, InDone, Env>;
 };
 /**
- * Statefully transforms a channel by scanning over its output with an effectful accumulator function.
+ * Transforms a channel statefully by scanning over its output with an effectful accumulator function.
  * Emits the intermediate results of the scan operation.
  *
  * **Example** (Scanning channel output with effects)
@@ -3324,7 +3421,7 @@ export declare const scan: {
  */
 export declare const scanEffect: {
     /**
-     * Statefully transforms a channel by scanning over its output with an effectful accumulator function.
+     * Transforms a channel statefully by scanning over its output with an effectful accumulator function.
      * Emits the intermediate results of the scan operation.
      *
      * **Example** (Scanning channel output with effects)
@@ -3370,7 +3467,7 @@ export declare const scanEffect: {
      */
     <S, OutElem, E, R>(initial: S, f: (s: S, a: Types.NoInfer<OutElem>) => Effect.Effect<S, E, R>): <OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<S, OutErr | E, OutDone, InElem, InErr, InDone, Env | R>;
     /**
-     * Statefully transforms a channel by scanning over its output with an effectful accumulator function.
+     * Transforms a channel statefully by scanning over its output with an effectful accumulator function.
      * Emits the intermediate results of the scan operation.
      *
      * **Example** (Scanning channel output with effects)
@@ -3572,6 +3669,21 @@ export declare const tapCause: {
  * Catches causes of failure that match a specific filter, allowing
  * conditional error recovery based on the type of failure.
  *
+ * **When to use**
+ *
+ * Use to recover a channel only when its full `Cause` satisfies a boolean
+ * predicate.
+ *
+ * **Details**
+ *
+ * When the predicate matches, the recovery function receives the original
+ * cause. When it does not match, the returned channel fails with the original
+ * cause.
+ *
+ * @see {@link catchCauseFilter} for selecting causes with a `Filter`
+ * @see {@link catchCause} for recovering from every cause
+ * @see {@link catchIf} for recovering from typed channel errors
+ *
  * @category error handling
  * @since 4.0.0
  */
@@ -3580,6 +3692,21 @@ export declare const catchCauseIf: {
      * Catches causes of failure that match a specific filter, allowing
      * conditional error recovery based on the type of failure.
      *
+     * **When to use**
+     *
+     * Use to recover a channel only when its full `Cause` satisfies a boolean
+     * predicate.
+     *
+     * **Details**
+     *
+     * When the predicate matches, the recovery function receives the original
+     * cause. When it does not match, the returned channel fails with the original
+     * cause.
+     *
+     * @see {@link catchCauseFilter} for selecting causes with a `Filter`
+     * @see {@link catchCause} for recovering from every cause
+     * @see {@link catchIf} for recovering from typed channel errors
+     *
      * @category error handling
      * @since 4.0.0
      */
@@ -3588,6 +3715,21 @@ export declare const catchCauseIf: {
      * Catches causes of failure that match a specific filter, allowing
      * conditional error recovery based on the type of failure.
      *
+     * **When to use**
+     *
+     * Use to recover a channel only when its full `Cause` satisfies a boolean
+     * predicate.
+     *
+     * **Details**
+     *
+     * When the predicate matches, the recovery function receives the original
+     * cause. When it does not match, the returned channel fails with the original
+     * cause.
+     *
+     * @see {@link catchCauseFilter} for selecting causes with a `Filter`
+     * @see {@link catchCause} for recovering from every cause
+     * @see {@link catchIf} for recovering from typed channel errors
+     *
      * @category error handling
      * @since 4.0.0
      */
@@ -3596,12 +3738,22 @@ export declare const catchCauseIf: {
 /**
  * Recovers from channel failures whose full `Cause` is selected by a `Filter`.
  *
+ * **When to use**
+ *
+ * Use when you need to recover a channel only from causes selected by a
+ * `Filter`, and the recovery needs both the selected value and the original
+ * `Cause`.
+ *
  * **Details**
  *
  * When the filter succeeds, the recovery function receives the selected value
  * and the original cause. When the filter fails, the returned channel fails
  * with the residual cause produced by the filter.
  *
+ * @see {@link catchCauseIf} for selecting causes with a predicate
+ * @see {@link catchFilter} for selecting typed errors with a `Filter`
+ * @see {@link catchCause} for recovering from every cause
+ *
  * @category error handling
  * @since 4.0.0
  */
@@ -3609,12 +3761,22 @@ export declare const catchCauseFilter: {
     /**
      * Recovers from channel failures whose full `Cause` is selected by a `Filter`.
      *
+     * **When to use**
+     *
+     * Use when you need to recover a channel only from causes selected by a
+     * `Filter`, and the recovery needs both the selected value and the original
+     * `Cause`.
+     *
      * **Details**
      *
      * When the filter succeeds, the recovery function receives the selected value
      * and the original cause. When the filter fails, the returned channel fails
      * with the residual cause produced by the filter.
      *
+     * @see {@link catchCauseIf} for selecting causes with a predicate
+     * @see {@link catchFilter} for selecting typed errors with a `Filter`
+     * @see {@link catchCause} for recovering from every cause
+     *
      * @category error handling
      * @since 4.0.0
      */
@@ -3622,12 +3784,22 @@ export declare const catchCauseFilter: {
     /**
      * Recovers from channel failures whose full `Cause` is selected by a `Filter`.
      *
+     * **When to use**
+     *
+     * Use when you need to recover a channel only from causes selected by a
+     * `Filter`, and the recovery needs both the selected value and the original
+     * `Cause`.
+     *
      * **Details**
      *
      * When the filter succeeds, the recovery function receives the selected value
      * and the original cause. When the filter fails, the returned channel fails
      * with the residual cause produced by the filter.
      *
+     * @see {@link catchCauseIf} for selecting causes with a predicate
+     * @see {@link catchFilter} for selecting typed errors with a `Filter`
+     * @see {@link catchCause} for recovering from every cause
+     *
      * @category error handling
      * @since 4.0.0
      */
@@ -3688,12 +3860,22 @@ export declare const tapError: {
 /**
  * Recovers from typed channel errors that match a predicate or refinement.
  *
+ * **When to use**
+ *
+ * Use to recover from typed channel errors when a predicate or refinement
+ * selects the failures that should switch to a recovery channel.
+ *
  * **Details**
  *
  * Matching errors are handled by the recovery function. Non-matching errors
  * are handled by `orElse` when provided. Without `orElse`, non-matching errors
  * are re-failed.
  *
+ * @see {@link catch_ catch} for recovering from every typed channel error
+ * @see {@link catchFilter} for selecting typed errors with a `Filter`
+ * @see {@link catchTag} for selecting tagged typed errors
+ * @see {@link catchCauseFilter} for selecting full causes with a `Filter`
+ *
  * @category error handling
  * @since 4.0.0
  */
@@ -3701,65 +3883,114 @@ export declare const catchIf: {
     /**
      * Recovers from typed channel errors that match a predicate or refinement.
      *
+     * **When to use**
+     *
+     * Use to recover from typed channel errors when a predicate or refinement
+     * selects the failures that should switch to a recovery channel.
+     *
      * **Details**
      *
      * Matching errors are handled by the recovery function. Non-matching errors
      * are handled by `orElse` when provided. Without `orElse`, non-matching errors
      * are re-failed.
      *
+     * @see {@link catch_ catch} for recovering from every typed channel error
+     * @see {@link catchFilter} for selecting typed errors with a `Filter`
+     * @see {@link catchTag} for selecting tagged typed errors
+     * @see {@link catchCauseFilter} for selecting full causes with a `Filter`
+     *
      * @category error handling
      * @since 4.0.0
      */
-    <OutErr, EB extends OutErr, OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1, OutElem2 = never, OutErr2 = Exclude<OutErr, EB>, OutDone2 = never, InElem2 = unknown, InErr2 = unknown, InDone2 = unknown, Env2 = never>(refinement: Predicate.Refinement<OutErr, EB>, f: (failure: EB) => Channel<OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>, orElse?: ((failure: Exclude<OutErr, EB>) => Channel<OutElem2, OutErr2, OutDone2, InElem2, InErr2, InDone2, Env2>) | undefined): <OutElem, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem | OutElem1 | OutElem2, OutErr1 | OutErr2, OutDone | OutDone1 | OutDone2, InElem & InElem1 & InElem2, InErr & InErr1 & InErr2, InDone & InDone1 & InDone2, Env | Env1 | Env2>;
+    <OutErr, EB extends OutErr, OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1, OutElem2 = Types.unassigned, OutErr2 = never, OutDone2 = never, InElem2 = unknown, InErr2 = unknown, InDone2 = unknown, Env2 = never>(refinement: Predicate.Refinement<OutErr, EB>, f: (failure: EB) => Channel<OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>, orElse?: ((failure: Exclude<OutErr, EB>) => Channel<OutElem2, OutErr2, OutDone2, InElem2, InErr2, InDone2, Env2>) | undefined): <OutElem, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem | OutElem1 | Exclude<OutElem2, Types.unassigned>, OutErr1 | OutErr2 | (OutElem2 extends Types.unassigned ? Exclude<OutErr, EB> : never), OutDone | OutDone1 | OutDone2, InElem & InElem1 & InElem2, InErr & InErr1 & InErr2, InDone & InDone1 & InDone2, Env | Env1 | Env2>;
     /**
      * Recovers from typed channel errors that match a predicate or refinement.
      *
+     * **When to use**
+     *
+     * Use to recover from typed channel errors when a predicate or refinement
+     * selects the failures that should switch to a recovery channel.
+     *
      * **Details**
      *
      * Matching errors are handled by the recovery function. Non-matching errors
      * are handled by `orElse` when provided. Without `orElse`, non-matching errors
      * are re-failed.
      *
+     * @see {@link catch_ catch} for recovering from every typed channel error
+     * @see {@link catchFilter} for selecting typed errors with a `Filter`
+     * @see {@link catchTag} for selecting tagged typed errors
+     * @see {@link catchCauseFilter} for selecting full causes with a `Filter`
+     *
      * @category error handling
      * @since 4.0.0
      */
-    <OutErr, OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1, OutElem2 = never, OutErr2 = OutErr, OutDone2 = never, InElem2 = unknown, InErr2 = unknown, InDone2 = unknown, Env2 = never>(predicate: Predicate.Predicate<OutErr>, f: (failure: OutErr) => Channel<OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>, orElse?: ((failure: OutErr) => Channel<OutElem2, OutErr2, OutDone2, InElem2, InErr2, InDone2, Env2>) | undefined): <OutElem, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem | OutElem1 | OutElem2, OutErr1 | OutErr2, OutDone | OutDone1 | OutDone2, InElem & InElem1 & InElem2, InErr & InErr1 & InErr2, InDone & InDone1 & InDone2, Env | Env1 | Env2>;
+    <OutErr, OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1, OutElem2 = Types.unassigned, OutErr2 = never, OutDone2 = never, InElem2 = unknown, InErr2 = unknown, InDone2 = unknown, Env2 = never>(predicate: Predicate.Predicate<OutErr>, f: (failure: OutErr) => Channel<OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>, orElse?: ((failure: OutErr) => Channel<OutElem2, OutErr2, OutDone2, InElem2, InErr2, InDone2, Env2>) | undefined): <OutElem, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem | OutElem1 | Exclude<OutElem2, Types.unassigned>, OutErr1 | OutErr2 | (OutElem2 extends Types.unassigned ? OutErr : never), OutDone | OutDone1 | OutDone2, InElem & InElem1 & InElem2, InErr & InErr1 & InErr2, InDone & InDone1 & InDone2, Env | Env1 | Env2>;
     /**
      * Recovers from typed channel errors that match a predicate or refinement.
      *
+     * **When to use**
+     *
+     * Use to recover from typed channel errors when a predicate or refinement
+     * selects the failures that should switch to a recovery channel.
+     *
      * **Details**
      *
      * Matching errors are handled by the recovery function. Non-matching errors
      * are handled by `orElse` when provided. Without `orElse`, non-matching errors
      * are re-failed.
      *
+     * @see {@link catch_ catch} for recovering from every typed channel error
+     * @see {@link catchFilter} for selecting typed errors with a `Filter`
+     * @see {@link catchTag} for selecting tagged typed errors
+     * @see {@link catchCauseFilter} for selecting full causes with a `Filter`
+     *
      * @category error handling
      * @since 4.0.0
      */
-    <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, EB extends OutErr, OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1, OutElem2 = never, OutErr2 = Exclude<OutErr, EB>, OutDone2 = never, InElem2 = unknown, InErr2 = unknown, InDone2 = unknown, Env2 = never>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, refinement: Predicate.Refinement<OutErr, EB>, f: (failure: EB) => Channel<OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>, orElse?: ((failure: Exclude<OutErr, EB>) => Channel<OutElem2, OutErr2, OutDone2, InElem2, InErr2, InDone2, Env2>) | undefined): Channel<OutElem | OutElem1 | OutElem2, OutErr1 | OutErr2, OutDone | OutDone1 | OutDone2, InElem & InElem1 & InElem2, InErr & InErr1 & InErr2, InDone & InDone1 & InDone2, Env | Env1 | Env2>;
+    <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, EB extends OutErr, OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1, OutElem2 = Types.unassigned, OutErr2 = never, OutDone2 = never, InElem2 = unknown, InErr2 = unknown, InDone2 = unknown, Env2 = never>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, refinement: Predicate.Refinement<OutErr, EB>, f: (failure: EB) => Channel<OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>, orElse?: ((failure: Exclude<OutErr, EB>) => Channel<OutElem2, OutErr2, OutDone2, InElem2, InErr2, InDone2, Env2>) | undefined): Channel<OutElem | OutElem1 | Exclude<OutElem2, Types.unassigned>, OutErr1 | OutErr2 | (OutElem2 extends Types.unassigned ? Exclude<OutErr, EB> : never), OutDone | OutDone1 | OutDone2, InElem & InElem1 & InElem2, InErr & InErr1 & InErr2, InDone & InDone1 & InDone2, Env | Env1 | Env2>;
     /**
      * Recovers from typed channel errors that match a predicate or refinement.
      *
+     * **When to use**
+     *
+     * Use to recover from typed channel errors when a predicate or refinement
+     * selects the failures that should switch to a recovery channel.
+     *
      * **Details**
      *
      * Matching errors are handled by the recovery function. Non-matching errors
      * are handled by `orElse` when provided. Without `orElse`, non-matching errors
      * are re-failed.
      *
+     * @see {@link catch_ catch} for recovering from every typed channel error
+     * @see {@link catchFilter} for selecting typed errors with a `Filter`
+     * @see {@link catchTag} for selecting tagged typed errors
+     * @see {@link catchCauseFilter} for selecting full causes with a `Filter`
+     *
      * @category error handling
      * @since 4.0.0
      */
-    <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1, OutElem2 = never, OutErr2 = OutErr, OutDone2 = never, InElem2 = unknown, InErr2 = unknown, InDone2 = unknown, Env2 = never>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, predicate: Predicate.Predicate<OutErr>, f: (failure: OutErr) => Channel<OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>, orElse?: ((failure: OutErr) => Channel<OutElem2, OutErr2, OutDone2, InElem2, InErr2, InDone2, Env2>) | undefined): Channel<OutElem | OutElem1 | OutElem2, OutErr1 | OutErr2, OutDone | OutDone1 | OutDone2, InElem & InElem1 & InElem2, InErr & InErr1 & InErr2, InDone & InDone1 & InDone2, Env | Env1 | Env2>;
+    <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1, OutElem2 = Types.unassigned, OutErr2 = never, OutDone2 = never, InElem2 = unknown, InErr2 = unknown, InDone2 = unknown, Env2 = never>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, predicate: Predicate.Predicate<OutErr>, f: (failure: OutErr) => Channel<OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>, orElse?: ((failure: OutErr) => Channel<OutElem2, OutErr2, OutDone2, InElem2, InErr2, InDone2, Env2>) | undefined): Channel<OutElem | OutElem1 | Exclude<OutElem2, Types.unassigned>, OutErr1 | OutErr2 | (OutElem2 extends Types.unassigned ? OutErr : never), OutDone | OutDone1 | OutDone2, InElem & InElem1 & InElem2, InErr & InErr1 & InErr2, InDone & InDone1 & InDone2, Env | Env1 | Env2>;
 };
 /**
  * Recovers from typed channel errors selected by a `Filter`.
  *
+ * **When to use**
+ *
+ * Use to recover from channel errors with a reusable `Filter` when matching
+ * can also narrow or transform the error before choosing the recovery channel.
+ *
  * **Details**
  *
  * Successful filter results are handled by the recovery function. Failed
  * filter results are handled by `orElse` when provided. Without `orElse`,
  * failed filter results are re-failed.
  *
+ * @see {@link catchIf} for selecting typed errors with a predicate
+ * @see {@link catchTag} for selecting tagged typed errors
+ * @see {@link catchCauseFilter} for selecting full causes with a `Filter`
+ *
  * @category error handling
  * @since 4.0.0
  */
@@ -3767,29 +3998,47 @@ export declare const catchFilter: {
     /**
      * Recovers from typed channel errors selected by a `Filter`.
      *
+     * **When to use**
+     *
+     * Use to recover from channel errors with a reusable `Filter` when matching
+     * can also narrow or transform the error before choosing the recovery channel.
+     *
      * **Details**
      *
      * Successful filter results are handled by the recovery function. Failed
      * filter results are handled by `orElse` when provided. Without `orElse`,
      * failed filter results are re-failed.
      *
+     * @see {@link catchIf} for selecting typed errors with a predicate
+     * @see {@link catchTag} for selecting tagged typed errors
+     * @see {@link catchCauseFilter} for selecting full causes with a `Filter`
+     *
      * @category error handling
      * @since 4.0.0
      */
-    <OutErr, EB, X, OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1, OutElem2 = never, OutErr2 = X, OutDone2 = never, InElem2 = unknown, InErr2 = unknown, InDone2 = unknown, Env2 = never>(filter: Filter.Filter<OutErr, EB, X>, f: (failure: EB) => Channel<OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>, orElse?: ((failure: X) => Channel<OutElem2, OutErr2, OutDone2, InElem2, InErr2, InDone2, Env2>) | undefined): <OutElem, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem | OutElem1 | OutElem2, OutErr1 | OutErr2, OutDone | OutDone1 | OutDone2, InElem & InElem1 & InElem2, InErr & InErr1 & InErr2, InDone & InDone1 & InDone2, Env | Env1 | Env2>;
+    <OutErr, EB, X, OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1, OutElem2 = Types.unassigned, OutErr2 = never, OutDone2 = never, InElem2 = unknown, InErr2 = unknown, InDone2 = unknown, Env2 = never>(filter: Filter.Filter<OutErr, EB, X>, f: (failure: EB) => Channel<OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>, orElse?: ((failure: X) => Channel<OutElem2, OutErr2, OutDone2, InElem2, InErr2, InDone2, Env2>) | undefined): <OutElem, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem | OutElem1 | Exclude<OutElem2, Types.unassigned>, OutErr1 | OutErr2 | (OutElem2 extends Types.unassigned ? X : never), OutDone | OutDone1 | OutDone2, InElem & InElem1 & InElem2, InErr & InErr1 & InErr2, InDone & InDone1 & InDone2, Env | Env1 | Env2>;
     /**
      * Recovers from typed channel errors selected by a `Filter`.
      *
+     * **When to use**
+     *
+     * Use to recover from channel errors with a reusable `Filter` when matching
+     * can also narrow or transform the error before choosing the recovery channel.
+     *
      * **Details**
      *
      * Successful filter results are handled by the recovery function. Failed
      * filter results are handled by `orElse` when provided. Without `orElse`,
      * failed filter results are re-failed.
      *
+     * @see {@link catchIf} for selecting typed errors with a predicate
+     * @see {@link catchTag} for selecting tagged typed errors
+     * @see {@link catchCauseFilter} for selecting full causes with a `Filter`
+     *
      * @category error handling
      * @since 4.0.0
      */
-    <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, EB, X, OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1, OutElem2 = never, OutErr2 = X, OutDone2 = never, InElem2 = unknown, InErr2 = unknown, InDone2 = unknown, Env2 = never>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, filter: Filter.Filter<OutErr, EB, X>, f: (failure: EB) => Channel<OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>, orElse?: ((failure: X) => Channel<OutElem2, OutErr2, OutDone2, InElem2, InErr2, InDone2, Env2>) | undefined): Channel<OutElem | OutElem1 | OutElem2, OutErr1 | OutErr2, OutDone | OutDone1 | OutDone2, InElem & InElem1 & InElem2, InErr & InErr1 & InErr2, InDone & InDone1 & InDone2, Env | Env1 | Env2>;
+    <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, EB, X, OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1, OutElem2 = Types.unassigned, OutErr2 = never, OutDone2 = never, InElem2 = unknown, InErr2 = unknown, InDone2 = unknown, Env2 = never>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, filter: Filter.Filter<OutErr, EB, X>, f: (failure: EB) => Channel<OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>, orElse?: ((failure: X) => Channel<OutElem2, OutErr2, OutDone2, InElem2, InErr2, InDone2, Env2>) | undefined): Channel<OutElem | OutElem1 | Exclude<OutElem2, Types.unassigned>, OutErr1 | OutErr2 | (OutElem2 extends Types.unassigned ? X : never), OutDone | OutDone1 | OutDone2, InElem & InElem1 & InElem2, InErr & InErr1 & InErr2, InDone & InDone1 & InDone2, Env | Env1 | Env2>;
 };
 /**
  * Recovers from tagged channel errors whose `_tag` matches one or more tags.
@@ -3816,7 +4065,7 @@ export declare const catchTag: {
      * @category error handling
      * @since 4.0.0
      */
-    <OutErr, const K extends Types.Tags<OutErr> | Arr.NonEmptyReadonlyArray<Types.Tags<OutErr>>, OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1, OutElem2 = never, OutErr2 = Types.ExcludeTag<OutErr, K extends Arr.NonEmptyReadonlyArray<string> ? K[number] : K>, OutDone2 = never, InElem2 = unknown, InErr2 = unknown, InDone2 = unknown, Env2 = never>(k: K, f: (e: Types.ExtractTag<NoInfer<OutErr>, K extends Arr.NonEmptyReadonlyArray<string> ? K[number] : K>) => Channel<OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>, orElse?: ((e: Types.ExcludeTag<NoInfer<OutErr>, K extends Arr.NonEmptyReadonlyArray<string> ? K[number] : K>) => Channel<OutElem2, OutErr2, OutDone2, InElem2, InErr2, InDone2, Env2>) | undefined): <OutElem, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem | OutElem1 | OutElem2, OutErr1 | OutErr2, OutDone | OutDone1 | OutDone2, InElem & InElem1 & InElem2, InErr & InErr1 & InErr2, InDone & InDone1 & InDone2, Env | Env1 | Env2>;
+    <OutErr, const K extends Types.Tags<OutErr> | Arr.NonEmptyReadonlyArray<Types.Tags<OutErr>>, OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1, OutElem2 = Types.unassigned, OutErr2 = never, OutDone2 = never, InElem2 = unknown, InErr2 = unknown, InDone2 = unknown, Env2 = never>(k: K, f: (e: Types.ExtractTag<NoInfer<OutErr>, K extends Arr.NonEmptyReadonlyArray<string> ? K[number] : K>) => Channel<OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>, orElse?: ((e: Types.ExcludeTag<NoInfer<OutErr>, K extends Arr.NonEmptyReadonlyArray<string> ? K[number] : K>) => Channel<OutElem2, OutErr2, OutDone2, InElem2, InErr2, InDone2, Env2>) | undefined): <OutElem, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem | OutElem1 | Exclude<OutElem2, Types.unassigned>, OutErr1 | OutErr2 | (OutElem2 extends Types.unassigned ? Types.ExcludeTag<OutErr, K extends Arr.NonEmptyReadonlyArray<string> ? K[number] : K> : never), OutDone | OutDone1 | OutDone2, InElem & InElem1 & InElem2, InErr & InErr1 & InErr2, InDone & InDone1 & InDone2, Env | Env1 | Env2>;
     /**
      * Recovers from tagged channel errors whose `_tag` matches one or more tags.
      *
@@ -3829,7 +4078,7 @@ export declare const catchTag: {
      * @category error handling
      * @since 4.0.0
      */
-    <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, const K extends Types.Tags<OutErr> | Arr.NonEmptyReadonlyArray<Types.Tags<OutErr>>, OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1, OutElem2 = never, OutErr2 = Types.ExcludeTag<OutErr, K extends Arr.NonEmptyReadonlyArray<string> ? K[number] : K>, OutDone2 = never, InElem2 = unknown, InErr2 = unknown, InDone2 = unknown, Env2 = never>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, k: K, f: (e: Types.ExtractTag<NoInfer<OutErr>, K extends Arr.NonEmptyReadonlyArray<string> ? K[number] : K>) => Channel<OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>, orElse?: ((e: Types.ExcludeTag<NoInfer<OutErr>, K extends Arr.NonEmptyReadonlyArray<string> ? K[number] : K>) => Channel<OutElem2, OutErr2, OutDone2, InElem2, InErr2, InDone2, Env2>) | undefined): Channel<OutElem | OutElem1 | OutElem2, OutErr1 | OutErr2, OutDone | OutDone1 | OutDone2, InElem & InElem1 & InElem2, InErr & InErr1 & InErr2, InDone & InDone1 & InDone2, Env | Env1 | Env2>;
+    <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, const K extends Types.Tags<OutErr> | Arr.NonEmptyReadonlyArray<Types.Tags<OutErr>>, OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1, OutElem2 = Types.unassigned, OutErr2 = never, OutDone2 = never, InElem2 = unknown, InErr2 = unknown, InDone2 = unknown, Env2 = never>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, k: K, f: (e: Types.ExtractTag<NoInfer<OutErr>, K extends Arr.NonEmptyReadonlyArray<string> ? K[number] : K>) => Channel<OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>, orElse?: ((e: Types.ExcludeTag<NoInfer<OutErr>, K extends Arr.NonEmptyReadonlyArray<string> ? K[number] : K>) => Channel<OutElem2, OutErr2, OutDone2, InElem2, InErr2, InDone2, Env2>) | undefined): Channel<OutElem | OutElem1 | Exclude<OutElem2, Types.unassigned>, OutErr1 | OutErr2 | (OutElem2 extends Types.unassigned ? Types.ExcludeTag<OutErr, K extends Arr.NonEmptyReadonlyArray<string> ? K[number] : K> : never), OutDone | OutDone1 | OutDone2, InElem & InElem1 & InElem2, InErr & InErr1 & InErr2, InDone & InDone1 & InDone2, Env | Env1 | Env2>;
 };
 /**
  * Catches a specific reason within a tagged error.
@@ -3900,7 +4149,7 @@ export declare const catchReason: {
      * @category error handling
      * @since 4.0.0
      */
-    <OutErr, K extends Types.Tags<OutErr>, RK extends Types.ReasonTags<Types.ExtractTag<Types.NoInfer<OutErr>, K>>, OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1, OutElem2 = Types.unassigned, OutErr2 = never, OutDone2 = never, InElem2 = unknown, InErr2 = unknown, InDone2 = unknown, Env2 = never>(errorTag: K, reasonTag: RK, f: (reason: Types.ExtractReason<Types.ExtractTag<Types.NoInfer<OutErr>, K>, RK>, error: Types.NarrowReason<Types.ExtractTag<Types.NoInfer<OutErr>, K>, RK>) => Channel<OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>, orElse?: ((reason: Types.ExcludeReason<Types.ExtractTag<Types.NoInfer<OutErr>, K>, RK>, error: Types.OmitReason<Types.ExtractTag<Types.NoInfer<OutErr>, K>, RK>) => Channel<OutElem2, OutErr2, OutDone2, InElem2, InErr2, InDone2, Env2>) | undefined): <OutElem, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem | OutElem1 | Exclude<OutElem2, Types.unassigned>, (OutElem2 extends Types.unassigned ? OutErr : Types.ExcludeTag<OutErr, K>) | OutErr1 | OutErr2, OutDone | OutDone1 | OutDone2, InElem & InElem1 & InElem2, InErr & InErr1 & InErr2, InDone & InDone1 & InDone2, Env | Env1 | Env2>;
+    <OutErr, K extends Types.Tags<OutErr>, RK extends Types.ReasonTags<Types.ExtractTag<Types.NoInfer<OutErr>, K>>, OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1, OutElem2 = Types.unassigned, OutErr2 = never, OutDone2 = never, InElem2 = unknown, InErr2 = unknown, InDone2 = unknown, Env2 = never>(errorTag: K, reasonTag: RK, f: (reason: Types.ExtractReason<Types.ExtractTag<Types.NoInfer<OutErr>, K>, RK>, error: Types.NarrowReason<Types.ExtractTag<Types.NoInfer<OutErr>, K>, RK>) => Channel<OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>, orElse?: ((reason: Types.ExcludeReason<Types.ExtractTag<Types.NoInfer<OutErr>, K>, RK>, error: Types.OmitReason<Types.ExtractTag<Types.NoInfer<OutErr>, K>, RK>) => Channel<OutElem2, OutErr2, OutDone2, InElem2, InErr2, InDone2, Env2>) | undefined): <OutElem, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem | OutElem1 | Exclude<OutElem2, Types.unassigned>, Types.ExcludeTag<OutErr, K> | OutErr1 | OutErr2 | (OutElem2 extends Types.unassigned ? Types.ExtractTag<OutErr, K> : never), OutDone | OutDone1 | OutDone2, InElem & InElem1 & InElem2, InErr & InErr1 & InErr2, InDone & InDone1 & InDone2, Env | Env1 | Env2>;
     /**
      * Catches a specific reason within a tagged error.
      *
@@ -3935,7 +4184,7 @@ export declare const catchReason: {
      * @category error handling
      * @since 4.0.0
      */
-    <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, K extends Types.Tags<OutErr>, RK extends Types.ReasonTags<Types.ExtractTag<Types.NoInfer<OutErr>, K>>, OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1, OutElem2 = Types.unassigned, OutErr2 = never, OutDone2 = never, InElem2 = unknown, InErr2 = unknown, InDone2 = unknown, Env2 = never>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, errorTag: K, reasonTag: RK, f: (reason: Types.ExtractReason<Types.ExtractTag<Types.NoInfer<OutErr>, K>, RK>, error: Types.NarrowReason<Types.ExtractTag<Types.NoInfer<OutErr>, K>, RK>) => Channel<OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>, orElse?: ((reason: Types.ExcludeReason<Types.ExtractTag<Types.NoInfer<OutErr>, K>, RK>, error: Types.OmitReason<Types.ExtractTag<Types.NoInfer<OutErr>, K>, RK>) => Channel<OutElem2, OutErr2, OutDone2, InElem2, InErr2, InDone2, Env2>) | undefined): Channel<OutElem | OutElem1 | Exclude<OutElem2, Types.unassigned>, (OutElem2 extends Types.unassigned ? OutErr : Types.ExcludeTag<OutErr, K>) | OutErr1 | OutErr2, OutDone | OutDone1 | OutDone2, InElem & InElem1 & InElem2, InErr & InErr1 & InErr2, InDone & InDone1 & InDone2, Env | Env1 | Env2>;
+    <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, K extends Types.Tags<OutErr>, RK extends Types.ReasonTags<Types.ExtractTag<Types.NoInfer<OutErr>, K>>, OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1, OutElem2 = Types.unassigned, OutErr2 = never, OutDone2 = never, InElem2 = unknown, InErr2 = unknown, InDone2 = unknown, Env2 = never>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, errorTag: K, reasonTag: RK, f: (reason: Types.ExtractReason<Types.ExtractTag<Types.NoInfer<OutErr>, K>, RK>, error: Types.NarrowReason<Types.ExtractTag<Types.NoInfer<OutErr>, K>, RK>) => Channel<OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>, orElse?: ((reason: Types.ExcludeReason<Types.ExtractTag<Types.NoInfer<OutErr>, K>, RK>, error: Types.OmitReason<Types.ExtractTag<Types.NoInfer<OutErr>, K>, RK>) => Channel<OutElem2, OutErr2, OutDone2, InElem2, InErr2, InDone2, Env2>) | undefined): Channel<OutElem | OutElem1 | Exclude<OutElem2, Types.unassigned>, Types.ExcludeTag<OutErr, K> | OutErr1 | OutErr2 | (OutElem2 extends Types.unassigned ? Types.ExtractTag<OutErr, K> : never), OutDone | OutDone1 | OutDone2, InElem & InElem1 & InElem2, InErr & InErr1 & InErr2, InDone & InDone1 & InDone2, Env | Env1 | Env2>;
 };
 /**
  * Catches multiple reasons within a tagged error using an object of handlers.
@@ -3954,7 +4203,7 @@ export declare const catchReasons: {
         [RK in Types.ReasonTags<Types.ExtractTag<Types.NoInfer<OutErr>, K>>]+?: (reason: Types.ExtractReason<Types.ExtractTag<Types.NoInfer<OutErr>, K>, RK>, error: Types.NarrowReason<Types.ExtractTag<Types.NoInfer<OutErr>, K>, RK>) => Channel<any, any, any, any, any, any, any>;
     }, OutElem2 = Types.unassigned, OutErr2 = never, OutDone2 = never, InElem2 = unknown, InErr2 = unknown, InDone2 = unknown, Env2 = never>(errorTag: K, cases: Cases, orElse?: ((reason: Types.ExcludeReason<Types.ExtractTag<Types.NoInfer<OutErr>, K>, Extract<keyof Cases, string>>, error: Types.OmitReason<Types.ExtractTag<Types.NoInfer<OutErr>, K>, Extract<keyof Cases, string>>) => Channel<OutElem2, OutErr2, OutDone2, InElem2, InErr2, InDone2, Env2>) | undefined): <OutElem, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem | Exclude<OutElem2, Types.unassigned> | {
         [RK in keyof Cases]: Cases[RK] extends (...args: Array<any>) => Channel<infer OutElem1, any, any, any, any, any, any> ? OutElem1 : never;
-    }[keyof Cases], (OutElem2 extends Types.unassigned ? OutErr : Types.ExcludeTag<OutErr, K>) | OutErr2 | {
+    }[keyof Cases], Types.ExcludeTag<OutErr, K> | OutErr2 | (OutElem2 extends Types.unassigned ? Types.ExtractTag<OutErr, K> : never) | {
         [RK in keyof Cases]: Cases[RK] extends (...args: Array<any>) => Channel<any, infer OutErr1, any, any, any, any, any> ? OutErr1 : never;
     }[keyof Cases], OutDone | OutDone2 | {
         [RK in keyof Cases]: Cases[RK] extends (...args: Array<any>) => Channel<any, any, infer OutDone1, any, any, any, any> ? OutDone1 : never;
@@ -3977,7 +4226,7 @@ export declare const catchReasons: {
         [RK in Types.ReasonTags<Types.ExtractTag<OutErr, K>>]+?: (reason: Types.ExtractReason<Types.ExtractTag<OutErr, K>, RK>, error: Types.NarrowReason<Types.ExtractTag<OutErr, K>, RK>) => Channel<any, any, any, any, any, any, any>;
     }, OutElem2 = Types.unassigned, OutErr2 = never, OutDone2 = never, InElem2 = unknown, InErr2 = unknown, InDone2 = unknown, Env2 = never>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, errorTag: K, cases: Cases, orElse?: ((reason: Types.ExcludeReason<Types.ExtractTag<Types.NoInfer<OutErr>, K>, Extract<keyof Cases, string>>, error: Types.OmitReason<Types.ExtractTag<Types.NoInfer<OutErr>, K>, Extract<keyof Cases, string>>) => Channel<OutElem2, OutErr2, OutDone2, InElem2, InErr2, InDone2, Env2>) | undefined): Channel<OutElem | Exclude<OutElem2, Types.unassigned> | {
         [RK in keyof Cases]: Cases[RK] extends (...args: Array<any>) => Channel<infer OutElem1, any, any, any, any, any, any> ? OutElem1 : never;
-    }[keyof Cases], (OutElem2 extends Types.unassigned ? OutErr : Types.ExcludeTag<OutErr, K>) | OutErr2 | {
+    }[keyof Cases], Types.ExcludeTag<OutErr, K> | OutErr2 | (OutElem2 extends Types.unassigned ? Types.ExtractTag<OutErr, K> : never) | {
         [RK in keyof Cases]: Cases[RK] extends (...args: Array<any>) => Channel<any, infer OutErr1, any, any, any, any, any> ? OutErr1 : never;
     }[keyof Cases], OutDone | OutDone2 | {
         [RK in keyof Cases]: Cases[RK] extends (...args: Array<any>) => Channel<any, any, infer OutDone1, any, any, any, any> ? OutDone1 : never;
@@ -4943,16 +5192,42 @@ export declare const embedInput: {
     <OutElem, OutErr, OutDone, Env, InErr, InElem, InDone, R>(self: Channel<OutElem, OutErr, OutDone, unknown, unknown, unknown, Env>, input: (upstream: Pull.Pull<InElem, InErr, InDone>) => Effect.Effect<void, never, R>): Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env | R>;
 };
 /**
- * Allows a faster producer to progress independently of a slower consumer by
- * buffering up to `capacity` elements in a queue.
+ * Buffers individual output elements in a queue with the configured `capacity`
+ * so a faster producer can progress independently of a slower consumer.
+ *
+ * **Details**
+ *
+ * Finite queues use the `strategy` option. The default `"suspend"` strategy
+ * applies backpressure, while `"dropping"` and `"sliding"` can discard output
+ * elements when the queue is full. `"unbounded"` capacity does not use a finite
+ * capacity strategy.
+ *
+ * **Gotchas**
+ *
+ * Dropping and sliding strategies can lose output elements under backpressure.
+ *
+ * @see {@link bufferArray} for buffering elements from array outputs
  *
  * @category Buffering
  * @since 2.0.0
  */
 export declare const buffer: {
     /**
-     * Allows a faster producer to progress independently of a slower consumer by
-     * buffering up to `capacity` elements in a queue.
+     * Buffers individual output elements in a queue with the configured `capacity`
+     * so a faster producer can progress independently of a slower consumer.
+     *
+     * **Details**
+     *
+     * Finite queues use the `strategy` option. The default `"suspend"` strategy
+     * applies backpressure, while `"dropping"` and `"sliding"` can discard output
+     * elements when the queue is full. `"unbounded"` capacity does not use a finite
+     * capacity strategy.
+     *
+     * **Gotchas**
+     *
+     * Dropping and sliding strategies can lose output elements under backpressure.
+     *
+     * @see {@link bufferArray} for buffering elements from array outputs
      *
      * @category Buffering
      * @since 2.0.0
@@ -4964,8 +5239,21 @@ export declare const buffer: {
         readonly strategy?: "dropping" | "sliding" | "suspend" | undefined;
     }): <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>;
     /**
-     * Allows a faster producer to progress independently of a slower consumer by
-     * buffering up to `capacity` elements in a queue.
+     * Buffers individual output elements in a queue with the configured `capacity`
+     * so a faster producer can progress independently of a slower consumer.
+     *
+     * **Details**
+     *
+     * Finite queues use the `strategy` option. The default `"suspend"` strategy
+     * applies backpressure, while `"dropping"` and `"sliding"` can discard output
+     * elements when the queue is full. `"unbounded"` capacity does not use a finite
+     * capacity strategy.
+     *
+     * **Gotchas**
+     *
+     * Dropping and sliding strategies can lose output elements under backpressure.
+     *
+     * @see {@link bufferArray} for buffering elements from array outputs
      *
      * @category Buffering
      * @since 2.0.0
@@ -4978,16 +5266,46 @@ export declare const buffer: {
     }): Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>;
 };
 /**
- * Allows a faster producer to progress independently of a slower consumer by
- * buffering up to `capacity` elements in a queue.
+ * Buffers array output elements in a queue with the configured `capacity` so a
+ * faster producer can progress independently of a slower consumer.
+ *
+ * **Details**
+ *
+ * Finite queues use the `strategy` option. The default `"suspend"` strategy
+ * applies backpressure, while `"dropping"` and `"sliding"` can discard output
+ * elements when the queue is full. `"unbounded"` capacity does not use a finite
+ * capacity strategy.
+ *
+ * **Gotchas**
+ *
+ * Input arrays are offered to the queue element-by-element and outputs are
+ * rebuilt from the currently available queued elements, so upstream array
+ * boundaries are not preserved.
+ *
+ * @see {@link buffer} for buffering output elements without flattening arrays
  *
  * @category Buffering
  * @since 4.0.0
  */
 export declare const bufferArray: {
     /**
-     * Allows a faster producer to progress independently of a slower consumer by
-     * buffering up to `capacity` elements in a queue.
+     * Buffers array output elements in a queue with the configured `capacity` so a
+     * faster producer can progress independently of a slower consumer.
+     *
+     * **Details**
+     *
+     * Finite queues use the `strategy` option. The default `"suspend"` strategy
+     * applies backpressure, while `"dropping"` and `"sliding"` can discard output
+     * elements when the queue is full. `"unbounded"` capacity does not use a finite
+     * capacity strategy.
+     *
+     * **Gotchas**
+     *
+     * Input arrays are offered to the queue element-by-element and outputs are
+     * rebuilt from the currently available queued elements, so upstream array
+     * boundaries are not preserved.
+     *
+     * @see {@link buffer} for buffering output elements without flattening arrays
      *
      * @category Buffering
      * @since 4.0.0
@@ -4999,8 +5317,23 @@ export declare const bufferArray: {
         readonly strategy?: "dropping" | "sliding" | "suspend" | undefined;
     }): <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<Arr.NonEmptyReadonlyArray<OutElem>, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<Arr.NonEmptyReadonlyArray<OutElem>, OutErr, OutDone, InElem, InErr, InDone, Env>;
     /**
-     * Allows a faster producer to progress independently of a slower consumer by
-     * buffering up to `capacity` elements in a queue.
+     * Buffers array output elements in a queue with the configured `capacity` so a
+     * faster producer can progress independently of a slower consumer.
+     *
+     * **Details**
+     *
+     * Finite queues use the `strategy` option. The default `"suspend"` strategy
+     * applies backpressure, while `"dropping"` and `"sliding"` can discard output
+     * elements when the queue is full. `"unbounded"` capacity does not use a finite
+     * capacity strategy.
+     *
+     * **Gotchas**
+     *
+     * Input arrays are offered to the queue element-by-element and outputs are
+     * rebuilt from the currently available queued elements, so upstream array
+     * boundaries are not preserved.
+     *
+     * @see {@link buffer} for buffering output elements without flattening arrays
      *
      * @category Buffering
      * @since 4.0.0
@@ -5013,39 +5346,54 @@ export declare const bufferArray: {
     }): Channel<Arr.NonEmptyReadonlyArray<OutElem>, OutErr, OutDone, InElem, InErr, InDone, Env>;
 };
 /**
- * Returns a new channel, which is the same as this one, except it will be
- * interrupted when the specified effect completes. If the effect completes
- * successfully before the underlying channel is done, then the returned
- * channel will yield the success value of the effect as its terminal value.
- * On the other hand, if the underlying channel finishes first, then the
- * returned channel will yield the success value of the underlying channel as
- * its terminal value.
+ * Interrupts a channel when another effect completes.
+ *
+ * **When to use**
+ *
+ * Use to race channel execution against an external effect whose success can
+ * become the channel's done value.
+ *
+ * **Details**
+ *
+ * If the effect completes first, its success value becomes the returned
+ * channel's done value. If the channel completes first, the original channel's
+ * done value is preserved.
  *
  * @category utils
  * @since 2.0.0
  */
 export declare const interruptWhen: {
     /**
-     * Returns a new channel, which is the same as this one, except it will be
-     * interrupted when the specified effect completes. If the effect completes
-     * successfully before the underlying channel is done, then the returned
-     * channel will yield the success value of the effect as its terminal value.
-     * On the other hand, if the underlying channel finishes first, then the
-     * returned channel will yield the success value of the underlying channel as
-     * its terminal value.
+     * Interrupts a channel when another effect completes.
+     *
+     * **When to use**
+     *
+     * Use to race channel execution against an external effect whose success can
+     * become the channel's done value.
+     *
+     * **Details**
+     *
+     * If the effect completes first, its success value becomes the returned
+     * channel's done value. If the channel completes first, the original channel's
+     * done value is preserved.
      *
      * @category utils
      * @since 2.0.0
      */
     <OutDone2, OutErr2, Env2>(effect: Effect.Effect<OutDone2, OutErr2, Env2>): <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem, OutErr | OutErr2, OutDone | OutDone2, InElem, InErr, InDone, Env2 | Env>;
     /**
-     * Returns a new channel, which is the same as this one, except it will be
-     * interrupted when the specified effect completes. If the effect completes
-     * successfully before the underlying channel is done, then the returned
-     * channel will yield the success value of the effect as its terminal value.
-     * On the other hand, if the underlying channel finishes first, then the
-     * returned channel will yield the success value of the underlying channel as
-     * its terminal value.
+     * Interrupts a channel when another effect completes.
+     *
+     * **When to use**
+     *
+     * Use to race channel execution against an external effect whose success can
+     * become the channel's done value.
+     *
+     * **Details**
+     *
+     * If the effect completes first, its success value becomes the returned
+     * channel's done value. If the channel completes first, the original channel's
+     * done value is preserved.
      *
      * @category utils
      * @since 2.0.0
@@ -5053,7 +5401,7 @@ export declare const interruptWhen: {
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, OutDone2, OutErr2, Env2>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, effect: Effect.Effect<OutDone2, OutErr2, Env2>): Channel<OutElem, OutErr | OutErr2, OutDone | OutDone2, InElem, InErr, InDone, Env2 | Env>;
 };
 /**
- * Halts a channel when the specified effect completes or fails.
+ * Stops a channel when the specified effect completes or fails.
  *
  * **Details**
  *
@@ -5067,7 +5415,7 @@ export declare const interruptWhen: {
  */
 export declare const haltWhen: {
     /**
-     * Halts a channel when the specified effect completes or fails.
+     * Stops a channel when the specified effect completes or fails.
      *
      * **Details**
      *
@@ -5081,7 +5429,7 @@ export declare const haltWhen: {
      */
     <OutDone2, OutErr2, Env2>(effect: Effect.Effect<OutDone2, OutErr2, Env2>): <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem, OutErr | OutErr2, OutDone | OutDone2, InElem, InErr, InDone, Env2 | Env>;
     /**
-     * Halts a channel when the specified effect completes or fails.
+     * Stops a channel when the specified effect completes or fails.
      *
      * **Details**
      *
@@ -5133,9 +5481,8 @@ export declare const onError: {
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, Env2>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, finalizer: (cause: Cause.Cause<OutErr>) => Effect.Effect<unknown, never, Env2>): Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env2 | Env>;
 };
 /**
- * Returns a new channel with an attached finalizer. The finalizer is
- * guaranteed to be executed so long as the channel begins execution (and
- * regardless of whether or not it completes).
+ * Returns a channel with an exit-aware finalizer that is guaranteed to run once
+ * the channel begins execution, whether it succeeds or fails.
  *
  * **Example** (Running exit finalizers)
  *
@@ -5164,9 +5511,8 @@ export declare const onError: {
  */
 export declare const onExit: {
     /**
-     * Returns a new channel with an attached finalizer. The finalizer is
-     * guaranteed to be executed so long as the channel begins execution (and
-     * regardless of whether or not it completes).
+     * Returns a channel with an exit-aware finalizer that is guaranteed to run once
+     * the channel begins execution, whether it succeeds or fails.
      *
      * **Example** (Running exit finalizers)
      *
@@ -5195,9 +5541,8 @@ export declare const onExit: {
      */
     <OutDone, OutErr, Env2>(finalizer: (e: Exit.Exit<OutDone, OutErr>) => Effect.Effect<unknown, never, Env2>): <OutElem, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env2 | Env>;
     /**
-     * Returns a new channel with an attached finalizer. The finalizer is
-     * guaranteed to be executed so long as the channel begins execution (and
-     * regardless of whether or not it completes).
+     * Returns a channel with an exit-aware finalizer that is guaranteed to run once
+     * the channel begins execution, whether it succeeds or fails.
      *
      * **Example** (Running exit finalizers)
      *
@@ -5344,9 +5689,8 @@ export declare const onEnd: {
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, A, E, R>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, onEnd: Effect.Effect<A, E, R>): Channel<OutElem, OutErr | E, OutDone, InElem, InErr, InDone, Env | R>;
 };
 /**
- * Returns a new channel with an attached finalizer. The finalizer is
- * guaranteed to be executed so long as the channel begins execution (and
- * regardless of whether or not it completes).
+ * Returns a channel with a finalizer effect that is guaranteed to run once the
+ * channel begins execution, whether it succeeds or fails.
  *
  * **Example** (Ensuring cleanup runs)
  *
@@ -5372,9 +5716,8 @@ export declare const onEnd: {
  */
 export declare const ensuring: {
     /**
-     * Returns a new channel with an attached finalizer. The finalizer is
-     * guaranteed to be executed so long as the channel begins execution (and
-     * regardless of whether or not it completes).
+     * Returns a channel with a finalizer effect that is guaranteed to run once the
+     * channel begins execution, whether it succeeds or fails.
      *
      * **Example** (Ensuring cleanup runs)
      *
@@ -5400,9 +5743,8 @@ export declare const ensuring: {
      */
     <Env2>(finalizer: Effect.Effect<unknown, never, Env2>): <OutElem, OutDone, OutErr, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env2 | Env>;
     /**
-     * Returns a new channel with an attached finalizer. The finalizer is
-     * guaranteed to be executed so long as the channel begins execution (and
-     * regardless of whether or not it completes).
+     * Returns a channel with a finalizer effect that is guaranteed to run once the
+     * channel begins execution, whether it succeeds or fails.
      *
      * **Example** (Ensuring cleanup runs)
      *
@@ -5429,7 +5771,7 @@ export declare const ensuring: {
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, Env2>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, finalizer: Effect.Effect<unknown, never, Env2>): Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env2 | Env>;
 };
 /**
- * Create a channel from the specified services.
+ * Creates a channel from the specified services.
  *
  * @category services
  * @since 2.0.0
@@ -5486,8 +5828,12 @@ export declare const provideService: {
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, I, S>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, key: Context.Key<I, S>, service: NoInfer<S>): Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Exclude<Env, I>>;
 };
 /**
- * Evaluates an effect to obtain a service, then provides that service to the
- * channel.
+ * Provides a service to the channel after obtaining it from an effect.
+ *
+ * **When to use**
+ *
+ * Use to supply a channel dependency when constructing the service itself is
+ * effectful or can fail.
  *
  * **Details**
  *
@@ -5499,8 +5845,12 @@ export declare const provideService: {
  */
 export declare const provideServiceEffect: {
     /**
-     * Evaluates an effect to obtain a service, then provides that service to the
-     * channel.
+     * Provides a service to the channel after obtaining it from an effect.
+     *
+     * **When to use**
+     *
+     * Use to supply a channel dependency when constructing the service itself is
+     * effectful or can fail.
      *
      * **Details**
      *
@@ -5512,8 +5862,12 @@ export declare const provideServiceEffect: {
      */
     <I, S, ES, RS>(key: Context.Key<I, S>, service: Effect.Effect<NoInfer<S>, ES, RS>): <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem, OutErr | ES, OutDone, InElem, InErr, InDone, Exclude<Env, I> | RS>;
     /**
-     * Evaluates an effect to obtain a service, then provides that service to the
-     * channel.
+     * Provides a service to the channel after obtaining it from an effect.
+     *
+     * **When to use**
+     *
+     * Use to supply a channel dependency when constructing the service itself is
+     * effectful or can fail.
      *
      * **Details**
      *
@@ -5765,6 +6119,15 @@ export declare const bind: {
 /**
  * Wraps each output element in an object under the specified field name.
  *
+ * **When to use**
+ *
+ * Use when starting a Channel Do-notation chain from an existing output value
+ * by assigning that value to a field name.
+ *
+ * @see {@link Do} for starting Do notation from an empty object
+ * @see {@link bind} for adding a field produced by another channel
+ * @see {@link let_ let} for adding a computed field
+ *
  * @category Do notation
  * @since 4.0.0
  */
@@ -5772,6 +6135,15 @@ export declare const bindTo: {
     /**
      * Wraps each output element in an object under the specified field name.
      *
+     * **When to use**
+     *
+     * Use when starting a Channel Do-notation chain from an existing output value
+     * by assigning that value to a field name.
+     *
+     * @see {@link Do} for starting Do notation from an empty object
+     * @see {@link bind} for adding a field produced by another channel
+     * @see {@link let_ let} for adding a computed field
+     *
      * @category Do notation
      * @since 4.0.0
      */
@@ -5781,6 +6153,15 @@ export declare const bindTo: {
     /**
      * Wraps each output element in an object under the specified field name.
      *
+     * **When to use**
+     *
+     * Use when starting a Channel Do-notation chain from an existing output value
+     * by assigning that value to a field name.
+     *
+     * @see {@link Do} for starting Do notation from an empty object
+     * @see {@link bind} for adding a field produced by another channel
+     * @see {@link let_ let} for adding a computed field
+     *
      * @category Do notation
      * @since 4.0.0
      */