effect 4.0.0-beta.70 → 4.0.0-beta.71

package/src/Channel.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)
- *
- * ```ts
- * import { Channel } from "effect"
+ * **Gotchas**
  *
- * // 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
  */
@@ -424,6 +436,13 @@ export const fromPull = <OutElem, OutErr, OutDone, EX, EnvX, Env>(
  * 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
  */
@@ -3920,12 +3939,21 @@ export 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
  */
@@ -3933,12 +3961,21 @@ export 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
    */
@@ -3948,12 +3985,21 @@ export 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
    */
@@ -4045,12 +4091,22 @@ export 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
  */
@@ -4058,12 +4114,22 @@ export 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
    */
@@ -4073,12 +4139,22 @@ export 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
    */
@@ -5340,6 +5416,21 @@ export 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
  */
@@ -5348,6 +5439,21 @@ export 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
    */
@@ -5383,6 +5489,21 @@ export 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
    */
@@ -5464,12 +5585,22 @@ export 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
  */
@@ -5477,12 +5608,22 @@ export 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
    */
@@ -5522,12 +5663,22 @@ export 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
    */
@@ -5812,12 +5963,22 @@ export 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
  */
@@ -5825,12 +5986,22 @@ export 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
    */
@@ -5844,8 +6015,8 @@ export const catchIf: {
     InErr1,
     InDone1,
     Env1,
-    OutElem2 = never,
-    OutErr2 = Exclude<OutErr, EB>,
+    OutElem2 = Types.unassigned,
+    OutErr2 = never,
     OutDone2 = never,
     InElem2 = unknown,
     InErr2 = unknown,
@@ -5867,8 +6038,8 @@ export const catchIf: {
     InDone,
     Env
   >(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<
-    OutElem | OutElem1 | OutElem2,
-    OutErr1 | OutErr2,
+    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,
@@ -5878,12 +6049,22 @@ export 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
    */
@@ -5896,8 +6077,8 @@ export const catchIf: {
     InErr1,
     InDone1,
     Env1,
-    OutElem2 = never,
-    OutErr2 = OutErr,
+    OutElem2 = Types.unassigned,
+    OutErr2 = never,
     OutDone2 = never,
     InElem2 = unknown,
     InErr2 = unknown,
@@ -5919,8 +6100,8 @@ export const catchIf: {
     InDone,
     Env
   >(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<
-    OutElem | OutElem1 | OutElem2,
-    OutErr1 | OutErr2,
+    OutElem | OutElem1 | Exclude<OutElem2, Types.unassigned>,
+    OutErr1 | OutErr2 | (OutElem2 extends Types.unassigned ? OutErr : never),
     OutDone | OutDone1 | OutDone2,
     InElem & InElem1 & InElem2,
     InErr & InErr1 & InErr2,
@@ -5930,12 +6111,22 @@ export 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
    */
@@ -5955,8 +6146,8 @@ export const catchIf: {
     InErr1,
     InDone1,
     Env1,
-    OutElem2 = never,
-    OutErr2 = Exclude<OutErr, EB>,
+    OutElem2 = Types.unassigned,
+    OutErr2 = never,
     OutDone2 = never,
     InElem2 = unknown,
     InErr2 = unknown,
@@ -5972,8 +6163,8 @@ export const catchIf: {
       ) => Channel<OutElem2, OutErr2, OutDone2, InElem2, InErr2, InDone2, Env2>)
       | undefined
   ): Channel<
-    OutElem | OutElem1 | OutElem2,
-    OutErr1 | OutErr2,
+    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,
@@ -5983,12 +6174,22 @@ export 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
    */
@@ -6007,8 +6208,8 @@ export const catchIf: {
     InErr1,
     InDone1,
     Env1,
-    OutElem2 = never,
-    OutErr2 = OutErr,
+    OutElem2 = Types.unassigned,
+    OutErr2 = never,
     OutDone2 = never,
     InElem2 = unknown,
     InErr2 = unknown,
@@ -6024,8 +6225,8 @@ export const catchIf: {
       ) => Channel<OutElem2, OutErr2, OutDone2, InElem2, InErr2, InDone2, Env2>)
       | undefined
   ): Channel<
-    OutElem | OutElem1 | OutElem2,
-    OutErr1 | OutErr2,
+    OutElem | OutElem1 | Exclude<OutElem2, Types.unassigned>,
+    OutErr1 | OutErr2 | (OutElem2 extends Types.unassigned ? OutErr : never),
     OutDone | OutDone1 | OutDone2,
     InElem & InElem1 & InElem2,
     InErr & InErr1 & InErr2,
@@ -6094,12 +6295,21 @@ export const catchIf: {
 /**
  * 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
  */
@@ -6107,12 +6317,21 @@ export 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
    */
@@ -6127,8 +6346,8 @@ export const catchFilter: {
     InErr1,
     InDone1,
     Env1,
-    OutElem2 = never,
-    OutErr2 = X,
+    OutElem2 = Types.unassigned,
+    OutErr2 = never,
     OutDone2 = never,
     InElem2 = unknown,
     InErr2 = unknown,
@@ -6150,8 +6369,8 @@ export const catchFilter: {
     InDone,
     Env
   >(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<
-    OutElem | OutElem1 | OutElem2,
-    OutErr1 | OutErr2,
+    OutElem | OutElem1 | Exclude<OutElem2, Types.unassigned>,
+    OutErr1 | OutErr2 | (OutElem2 extends Types.unassigned ? X : never),
     OutDone | OutDone1 | OutDone2,
     InElem & InElem1 & InElem2,
     InErr & InErr1 & InErr2,
@@ -6161,12 +6380,21 @@ export 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
    */
@@ -6187,8 +6415,8 @@ export const catchFilter: {
     InErr1,
     InDone1,
     Env1,
-    OutElem2 = never,
-    OutErr2 = X,
+    OutElem2 = Types.unassigned,
+    OutErr2 = never,
     OutDone2 = never,
     InElem2 = unknown,
     InErr2 = unknown,
@@ -6204,8 +6432,8 @@ export const catchFilter: {
       ) => Channel<OutElem2, OutErr2, OutDone2, InElem2, InErr2, InDone2, Env2>)
       | undefined
   ): Channel<
-    OutElem | OutElem1 | OutElem2,
-    OutErr1 | OutErr2,
+    OutElem | OutElem1 | Exclude<OutElem2, Types.unassigned>,
+    OutErr1 | OutErr2 | (OutElem2 extends Types.unassigned ? X : never),
     OutDone | OutDone1 | OutDone2,
     InElem & InElem1 & InElem2,
     InErr & InErr1 & InErr2,
@@ -6309,8 +6537,8 @@ export const catchTag: {
     InErr1,
     InDone1,
     Env1,
-    OutElem2 = never,
-    OutErr2 = Types.ExcludeTag<OutErr, K extends Arr.NonEmptyReadonlyArray<string> ? K[number] : K>,
+    OutElem2 = Types.unassigned,
+    OutErr2 = never,
     OutDone2 = never,
     InElem2 = unknown,
     InErr2 = unknown,
@@ -6334,8 +6562,12 @@ export const catchTag: {
     InDone,
     Env
   >(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<
-    OutElem | OutElem1 | OutElem2,
-    OutErr1 | OutErr2,
+    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,
@@ -6370,8 +6602,8 @@ export const catchTag: {
     InErr1,
     InDone1,
     Env1,
-    OutElem2 = never,
-    OutErr2 = Types.ExcludeTag<OutErr, K extends Arr.NonEmptyReadonlyArray<string> ? K[number] : K>,
+    OutElem2 = Types.unassigned,
+    OutErr2 = never,
     OutDone2 = never,
     InElem2 = unknown,
     InErr2 = unknown,
@@ -6389,8 +6621,12 @@ export const catchTag: {
       ) => Channel<OutElem2, OutErr2, OutDone2, InElem2, InErr2, InDone2, Env2>)
       | undefined
   ): Channel<
-    OutElem | OutElem1 | OutElem2,
-    OutErr1 | OutErr2,
+    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,
@@ -6557,7 +6793,10 @@ export const catchReason: {
     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,
+    | Types.ExcludeTag<OutErr, K>
+    | OutErr1
+    | OutErr2
+    | (OutElem2 extends Types.unassigned ? Types.ExtractTag<OutErr, K> : never),
     OutDone | OutDone1 | OutDone2,
     InElem & InElem1 & InElem2,
     InErr & InErr1 & InErr2,
@@ -6638,7 +6877,10 @@ export const catchReason: {
       | undefined
   ): Channel<
     OutElem | OutElem1 | Exclude<OutElem2, Types.unassigned>,
-    (OutElem2 extends Types.unassigned ? OutErr : Types.ExcludeTag<OutErr, K>) | OutErr1 | OutErr2,
+    | Types.ExcludeTag<OutErr, K>
+    | OutErr1
+    | OutErr2
+    | (OutElem2 extends Types.unassigned ? Types.ExtractTag<OutErr, K> : never),
     OutDone | OutDone1 | OutDone2,
     InElem & InElem1 & InElem2,
     InErr & InErr1 & InErr2,
@@ -6685,7 +6927,10 @@ export const catchReason: {
     | undefined
 ): Channel<
   OutElem | OutElem1 | Exclude<OutElem2, Types.unassigned>,
-  (OutElem2 extends Types.unassigned ? OutErr : Types.ExcludeTag<OutErr, K>) | OutErr1 | OutErr2,
+  | Types.ExcludeTag<OutErr, K>
+  | OutErr1
+  | OutErr2
+  | (OutElem2 extends Types.unassigned ? Types.ExtractTag<OutErr, K> : never),
   OutDone | OutDone1 | OutDone2,
   InElem & InElem1 & InElem2,
   InErr & InErr1 & InErr2,
@@ -6761,8 +7006,9 @@ export const catchReasons: {
       [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>)
+    | 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
@@ -6843,8 +7089,9 @@ export const catchReasons: {
       [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>)
+    | 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
@@ -8748,6 +8995,19 @@ export const embedInput: {
  * Allows a faster producer to progress independently of a slower consumer by
  * buffering up to `capacity` elements in a queue.
  *
+ * **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
  */
@@ -8756,6 +9016,19 @@ export const buffer: {
    * Allows a faster producer to progress independently of a slower consumer by
    * buffering up to `capacity` elements in a queue.
    *
+   * **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
    */
@@ -8771,6 +9044,19 @@ export const buffer: {
    * Allows a faster producer to progress independently of a slower consumer by
    * buffering up to `capacity` elements in a queue.
    *
+   * **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
    */
@@ -8794,6 +9080,19 @@ export const buffer: {
      * Allows a faster producer to progress independently of a slower consumer by
      * buffering up to `capacity` elements in a queue.
      *
+     * **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
      */
@@ -8801,6 +9100,19 @@ export const buffer: {
      * Allows a faster producer to progress independently of a slower consumer by
      * buffering up to `capacity` elements in a queue.
      *
+     * **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
      */
@@ -8822,6 +9134,21 @@ export const buffer: {
  * Allows a faster producer to progress independently of a slower consumer by
  * buffering up to `capacity` elements in a queue.
  *
+ * **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
  */
@@ -8830,6 +9157,21 @@ export const bufferArray: {
    * Allows a faster producer to progress independently of a slower consumer by
    * buffering up to `capacity` elements in a queue.
    *
+   * **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
    */
@@ -8845,6 +9187,21 @@ export const bufferArray: {
    * Allows a faster producer to progress independently of a slower consumer by
    * buffering up to `capacity` elements in a queue.
    *
+   * **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
    */
@@ -8868,6 +9225,21 @@ export const bufferArray: {
      * Allows a faster producer to progress independently of a slower consumer by
      * buffering up to `capacity` elements in a queue.
      *
+     * **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
      */
@@ -8875,6 +9247,21 @@ export const bufferArray: {
      * Allows a faster producer to progress independently of a slower consumer by
      * buffering up to `capacity` elements in a queue.
      *
+     * **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
      */
@@ -10047,6 +10434,15 @@ export 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
  */
@@ -10054,6 +10450,15 @@ export 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
    */
@@ -10071,6 +10476,15 @@ export 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
    */