effect 4.0.0-beta.73 → 4.0.0-beta.75

package/dist/Channel.d.ts

@@ -801,6 +801,11 @@ export declare const fail: <E>(error: E) => Channel<never, E, never>;
  * Constructs a channel that fails immediately with the specified lazily
  * evaluated error.
  *
+ * **When to use**
+ *
+ * Use when the error value should be computed each time the channel runs instead
+ * of when the channel is constructed.
+ *
  * **Example** (Failing with a lazy error)
  *
  * ```ts
@@ -833,6 +838,11 @@ export declare const failSync: <E>(evaluate: LazyArg<E>) => Channel<never, E, ne
 /**
  * Constructs a channel that fails immediately with the specified `Cause`.
  *
+ * **When to use**
+ *
+ * Use when the channel failure must preserve a full `Cause`, such as defects,
+ * interruptions, or combined failures.
+ *
  * **Example** (Failing with causes)
  *
  * ```ts
@@ -1626,6 +1636,11 @@ export declare const mapDone: {
 /**
  * Maps the done value of this channel using the specified effectful function.
  *
+ * **When to use**
+ *
+ * Use when the terminal done value transformation needs services or can fail,
+ * while emitted elements should pass through unchanged.
+ *
  * @category sequencing
  * @since 4.0.0
  */
@@ -1633,6 +1648,11 @@ export declare const mapDoneEffect: {
     /**
      * Maps the done value of this channel using the specified effectful function.
      *
+     * **When to use**
+     *
+     * Use when the terminal done value transformation needs services or can fail,
+     * while emitted elements should pass through unchanged.
+     *
      * @category sequencing
      * @since 4.0.0
      */
@@ -1640,6 +1660,11 @@ export declare const mapDoneEffect: {
     /**
      * Maps the done value of this channel using the specified effectful function.
      *
+     * **When to use**
+     *
+     * Use when the terminal done value transformation needs services or can fail,
+     * while emitted elements should pass through unchanged.
+     *
      * @category sequencing
      * @since 4.0.0
      */
@@ -1649,6 +1674,11 @@ export declare const mapDoneEffect: {
  * Maps each output element with an effectful function, preserving the source
  * channel's done value.
  *
+ * **When to use**
+ *
+ * Use when transforming each channel output needs an Effect, service
+ * dependency, failure channel, or configured concurrency.
+ *
  * **Details**
  *
  * The mapping function receives the output element and its zero-based index.
@@ -1702,6 +1732,11 @@ export declare const mapEffect: {
      * Maps each output element with an effectful function, preserving the source
      * channel's done value.
      *
+     * **When to use**
+     *
+     * Use when transforming each channel output needs an Effect, service
+     * dependency, failure channel, or configured concurrency.
+     *
      * **Details**
      *
      * The mapping function receives the output element and its zero-based index.
@@ -1758,6 +1793,11 @@ export declare const mapEffect: {
      * Maps each output element with an effectful function, preserving the source
      * channel's done value.
      *
+     * **When to use**
+     *
+     * Use when transforming each channel output needs an Effect, service
+     * dependency, failure channel, or configured concurrency.
+     *
      * **Details**
      *
      * The mapping function receives the output element and its zero-based index.
@@ -2408,7 +2448,7 @@ export declare const flatten: <OutElem, OutErr, OutDone, InElem, InErr, InDone,
  * // Outputs: 1, 2, 3, 4, 5, 6, 7, 8, 9
  * ```
  *
- * @category utils
+ * @category transforming
  * @since 4.0.0
  */
 export declare const flattenArray: <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<ReadonlyArray<OutElem>, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>;
@@ -2421,7 +2461,7 @@ export declare const flattenArray: <OutElem, OutErr, OutDone, InElem, InErr, InD
  * Output `Take` values are emitted as non-empty arrays. Failed `Take` values
  * fail the returned channel. Done `Take` values complete the returned channel.
  *
- * @category utils
+ * @category transforming
  * @since 4.0.0
  */
 export declare const flattenTake: <OutElem, OutErr, OutDone, OutErr2, OutDone2, InElem, InErr, InDone, Env>(self: Channel<Take.Take<OutElem, OutErr, OutDone>, OutErr2, OutDone2, InElem, InErr, InDone, Env>) => Channel<Arr.NonEmptyReadonlyArray<OutElem>, OutErr | OutErr2, OutDone, InElem, InErr, InDone, Env>;
@@ -2451,21 +2491,21 @@ export declare const drain: <OutElem, OutErr, OutDone, InElem, InErr, InDone, En
 /**
  * Repeats this channel according to the provided schedule.
  *
- * @category utils
+ * @category repetition
  * @since 4.0.0
  */
 export declare const repeat: {
     /**
      * Repeats this channel according to the provided schedule.
      *
-     * @category utils
+     * @category repetition
      * @since 4.0.0
      */
     <SO, OutDone, SE, SR>(schedule: Schedule.Schedule<SO, Types.NoInfer<OutDone>, SE, SR> | (($: <SO, SE, SR>(_: Schedule.Schedule<SO, NoInfer<OutDone>, SE, SR>) => Schedule.Schedule<SO, OutDone, SE, SR>) => Schedule.Schedule<SO, Types.NoInfer<OutDone>, SE, SR>)): <OutElem, OutErr, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr | SE, OutDone, InElem, InErr, InDone, Env | SR>) => Channel<OutElem, OutErr | SE, OutDone, InElem, InErr, InDone, Env | SR>;
     /**
      * Repeats this channel according to the provided schedule.
      *
-     * @category utils
+     * @category repetition
      * @since 4.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, SO, SE, SR>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, schedule: Schedule.Schedule<SO, OutDone, SE, SR> | (($: <SO, SE, SR>(_: Schedule.Schedule<SO, NoInfer<OutDone>, SE, SR>) => Schedule.Schedule<SO, OutDone, SE, SR>) => Schedule.Schedule<SO, Types.NoInfer<OutDone>, SE, SR>)): Channel<OutElem, OutErr | SE, OutDone, InElem, InErr, InDone, Env | SR>;
@@ -2473,7 +2513,7 @@ export declare const repeat: {
 /**
  * Repeats this channel forever.
  *
- * @category utils
+ * @category repetition
  * @since 4.0.0
  */
 export declare const forever: <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem, OutErr, never, InElem, InErr, InDone, Env>;
@@ -2488,7 +2528,7 @@ export declare const forever: <OutElem, OutErr, OutDone, InElem, InErr, InDone,
  * fails. If the schedule finishes, the returned channel completes with the
  * schedule output.
  *
- * @category utils
+ * @category sequencing
  * @since 4.0.0
  */
 export declare const schedule: {
@@ -2503,7 +2543,7 @@ export declare const schedule: {
      * fails. If the schedule finishes, the returned channel completes with the
      * schedule output.
      *
-     * @category utils
+     * @category sequencing
      * @since 4.0.0
      */
     <SO, OutElem, SE, SR>(schedule: Schedule.Schedule<SO, Types.NoInfer<OutElem>, SE, SR>): <OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr | SE, OutDone, InElem, InErr, InDone, Env | SR>) => Channel<OutElem, OutErr | SE, OutDone | SO, InElem, InErr, InDone, Env | SR>;
@@ -2518,7 +2558,7 @@ export declare const schedule: {
      * fails. If the schedule finishes, the returned channel completes with the
      * schedule output.
      *
-     * @category utils
+     * @category sequencing
      * @since 4.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, SO, SE, SR>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, schedule: Schedule.Schedule<SO, OutElem, SE, SR>): Channel<OutElem, OutErr | SE, OutDone | SO, InElem, InErr, InDone, Env | SR>;
@@ -2739,6 +2779,11 @@ export declare const filterMap: {
 /**
  * Filters output elements with an effectful predicate.
  *
+ * **When to use**
+ *
+ * Use when the keep/discard decision depends on an Effect or service and
+ * predicate failures should fail the returned channel.
+ *
  * **Details**
  *
  * Elements for which the predicate succeeds with `true` are emitted. Elements
@@ -2752,6 +2797,11 @@ export declare const filterEffect: {
     /**
      * Filters output elements with an effectful predicate.
      *
+     * **When to use**
+     *
+     * Use when the keep/discard decision depends on an Effect or service and
+     * predicate failures should fail the returned channel.
+     *
      * **Details**
      *
      * Elements for which the predicate succeeds with `true` are emitted. Elements
@@ -2765,6 +2815,11 @@ export declare const filterEffect: {
     /**
      * Filters output elements with an effectful predicate.
      *
+     * **When to use**
+     *
+     * Use when the keep/discard decision depends on an Effect or service and
+     * predicate failures should fail the returned channel.
+     *
      * **Details**
      *
      * Elements for which the predicate succeeds with `true` are emitted. Elements
@@ -3076,6 +3131,11 @@ export declare const filterMapArray: {
  * Filters each element inside emitted non-empty arrays with an effectful
  * predicate.
  *
+ * **When to use**
+ *
+ * Use when filtering array-valued channel outputs requires Effects or services,
+ * and arrays that become empty should be skipped.
+ *
  * **Details**
  *
  * The predicate receives the element and its index within the array. Elements
@@ -3090,6 +3150,11 @@ export declare const filterArrayEffect: {
      * Filters each element inside emitted non-empty arrays with an effectful
      * predicate.
      *
+     * **When to use**
+     *
+     * Use when filtering array-valued channel outputs requires Effects or services,
+     * and arrays that become empty should be skipped.
+     *
      * **Details**
      *
      * The predicate receives the element and its index within the array. Elements
@@ -3104,6 +3169,11 @@ export declare const filterArrayEffect: {
      * Filters each element inside emitted non-empty arrays with an effectful
      * predicate.
      *
+     * **When to use**
+     *
+     * Use when filtering array-valued channel outputs requires Effects or services,
+     * and arrays that become empty should be skipped.
+     *
      * **Details**
      *
      * The predicate receives the element and its index within the array. Elements
@@ -3119,6 +3189,11 @@ export declare const filterArrayEffect: {
  * Filters and maps each element inside emitted non-empty arrays using an
  * effectful `Filter`.
  *
+ * **When to use**
+ *
+ * Use when array-valued channel outputs need an effectful filter-map that can
+ * fail and can discard arrays that become empty.
+ *
  * **Details**
  *
  * Successful filter results are kept as mapped values. Failed filter results
@@ -3133,6 +3208,11 @@ export declare const filterMapArrayEffect: {
      * Filters and maps each element inside emitted non-empty arrays using an
      * effectful `Filter`.
      *
+     * **When to use**
+     *
+     * Use when array-valued channel outputs need an effectful filter-map that can
+     * fail and can discard arrays that become empty.
+     *
      * **Details**
      *
      * Successful filter results are kept as mapped values. Failed filter results
@@ -3147,6 +3227,11 @@ export declare const filterMapArrayEffect: {
      * Filters and maps each element inside emitted non-empty arrays using an
      * effectful `Filter`.
      *
+     * **When to use**
+     *
+     * Use when array-valued channel outputs need an effectful filter-map that can
+     * fail and can discard arrays that become empty.
+     *
      * **Details**
      *
      * Successful filter results are kept as mapped values. Failed filter results
@@ -3378,6 +3463,11 @@ export declare const scan: {
  * Transforms a channel statefully by scanning over its output with an effectful accumulator function.
  * Emits the intermediate results of the scan operation.
  *
+ * **When to use**
+ *
+ * Use when maintaining accumulated state over channel output requires Effects
+ * or can fail, while still emitting each intermediate state.
+ *
  * **Example** (Scanning channel output with effects)
  *
  * ```ts
@@ -3424,6 +3514,11 @@ export declare const scanEffect: {
      * Transforms a channel statefully by scanning over its output with an effectful accumulator function.
      * Emits the intermediate results of the scan operation.
      *
+     * **When to use**
+     *
+     * Use when maintaining accumulated state over channel output requires Effects
+     * or can fail, while still emitting each intermediate state.
+     *
      * **Example** (Scanning channel output with effects)
      *
      * ```ts
@@ -3470,6 +3565,11 @@ export declare const scanEffect: {
      * Transforms a channel statefully by scanning over its output with an effectful accumulator function.
      * Emits the intermediate results of the scan operation.
      *
+     * **When to use**
+     *
+     * Use when maintaining accumulated state over channel output requires Effects
+     * or can fail, while still emitting each intermediate state.
+     *
      * **Example** (Scanning channel output with effects)
      *
      * ```ts
@@ -3629,6 +3729,11 @@ export declare const catchCause: {
  * Runs an effect with the full failure `Cause` when the channel fails, then
  * fails the returned channel with the original cause.
  *
+ * **When to use**
+ *
+ * Use when observing the full channel failure `Cause` is needed without
+ * changing successful output or replacing the original cause.
+ *
  * **Details**
  *
  * Use this for observing failures, such as logging or metrics. If the observer
@@ -3642,6 +3747,11 @@ export declare const tapCause: {
      * Runs an effect with the full failure `Cause` when the channel fails, then
      * fails the returned channel with the original cause.
      *
+     * **When to use**
+     *
+     * Use when observing the full channel failure `Cause` is needed without
+     * changing successful output or replacing the original cause.
+     *
      * **Details**
      *
      * Use this for observing failures, such as logging or metrics. If the observer
@@ -3655,6 +3765,11 @@ export declare const tapCause: {
      * Runs an effect with the full failure `Cause` when the channel fails, then
      * fails the returned channel with the original cause.
      *
+     * **When to use**
+     *
+     * Use when observing the full channel failure `Cause` is needed without
+     * changing successful output or replacing the original cause.
+     *
      * **Details**
      *
      * Use this for observing failures, such as logging or metrics. If the observer
@@ -3741,7 +3856,7 @@ export declare const catchCauseIf: {
  * **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
+ * `Filter`, while giving the recovery both the selected value and the original
  * `Cause`.
  *
  * **Details**
@@ -3764,7 +3879,7 @@ export declare const catchCauseFilter: {
      * **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
+     * `Filter`, while giving the recovery both the selected value and the original
      * `Cause`.
      *
      * **Details**
@@ -3787,7 +3902,7 @@ export declare const catchCauseFilter: {
      * **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
+     * `Filter`, while giving the recovery both the selected value and the original
      * `Cause`.
      *
      * **Details**
@@ -4410,6 +4525,11 @@ export declare const ignore: <Arg extends Channel<any, any, any, any, any, any,
 /**
  * Ignores all errors in the channel including defects, converting them to an empty channel.
  *
+ * **When to use**
+ *
+ * Use when a channel should become best-effort and all failure causes, including
+ * defects and interruptions, can be converted to empty output.
+ *
  * **Details**
  *
  * Use the `log` option to emit the full {@link Cause} when the channel fails.
@@ -4430,7 +4550,7 @@ export declare const ignoreCause: <Arg extends Channel<any, any, any, any, any,
  * Returns a new channel that retries this channel according to the specified
  * schedule whenever it fails.
  *
- * @category utils
+ * @category error handling
  * @since 4.0.0
  */
 export declare const retry: {
@@ -4438,7 +4558,7 @@ export declare const retry: {
      * Returns a new channel that retries this channel according to the specified
      * schedule whenever it fails.
      *
-     * @category utils
+     * @category error handling
      * @since 4.0.0
      */
     <SO, OutErr, SE, SR>(schedule: Schedule.Schedule<SO, Types.NoInfer<OutErr>, SE, SR> | (($: <SO, SE, SR>(_: Schedule.Schedule<SO, Types.NoInfer<OutErr>, SE, SR>) => Schedule.Schedule<SO, OutErr, SE, SR>) => Schedule.Schedule<SO, Types.NoInfer<OutErr>, SE, SR>)): <OutElem, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr | SE, OutDone, InElem, InErr, InDone, Env | SR>) => Channel<OutElem, OutErr | SE, OutDone, InElem, InErr, InDone, Env | SR>;
@@ -4446,7 +4566,7 @@ export declare const retry: {
      * Returns a new channel that retries this channel according to the specified
      * schedule whenever it fails.
      *
-     * @category utils
+     * @category error handling
      * @since 4.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, SO, SE, SR>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, schedule: Schedule.Schedule<SO, OutErr, SE, SR> | (($: <SO, SE, SR>(_: Schedule.Schedule<SO, Types.NoInfer<OutErr>, SE, SR>) => Schedule.Schedule<SO, OutErr, SE, SR>) => Schedule.Schedule<SO, Types.NoInfer<OutErr>, SE, SR>)): Channel<OutElem, OutErr | SE, OutDone, InElem, InErr, InDone, Env | SR>;
@@ -4566,6 +4686,11 @@ export declare const switchMap: {
 /**
  * Merges multiple channels with specified concurrency and buffering options.
  *
+ * **When to use**
+ *
+ * Use when channel outputs are themselves channels and multiple inner channels
+ * should run with configured concurrency and buffering.
+ *
  * **Example** (Merging nested channels)
  *
  * ```ts
@@ -4591,13 +4716,18 @@ export declare const switchMap: {
  * // Outputs: 1, 2, 3, 4, 5, 6 (order may vary due to concurrency)
  * ```
  *
- * @category utils
+ * @category combining
  * @since 2.0.0
  */
 export declare const mergeAll: {
     /**
      * Merges multiple channels with specified concurrency and buffering options.
      *
+     * **When to use**
+     *
+     * Use when channel outputs are themselves channels and multiple inner channels
+     * should run with configured concurrency and buffering.
+     *
      * **Example** (Merging nested channels)
      *
      * ```ts
@@ -4623,7 +4753,7 @@ export declare const mergeAll: {
      * // Outputs: 1, 2, 3, 4, 5, 6 (order may vary due to concurrency)
      * ```
      *
-     * @category utils
+     * @category combining
      * @since 2.0.0
      */
     (options: {
@@ -4634,6 +4764,11 @@ export declare const mergeAll: {
     /**
      * Merges multiple channels with specified concurrency and buffering options.
      *
+     * **When to use**
+     *
+     * Use when channel outputs are themselves channels and multiple inner channels
+     * should run with configured concurrency and buffering.
+     *
      * **Example** (Merging nested channels)
      *
      * ```ts
@@ -4659,7 +4794,7 @@ export declare const mergeAll: {
      * // Outputs: 1, 2, 3, 4, 5, 6 (order may vary due to concurrency)
      * ```
      *
-     * @category utils
+     * @category combining
      * @since 2.0.0
      */
     <OutElem, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1, OutErr, OutDone, InElem, InErr, InDone, Env>(channels: Channel<Channel<OutElem, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>, OutErr, OutDone, InElem, InErr, InDone, Env>, options: {
@@ -4713,7 +4848,7 @@ export type HaltStrategy = "left" | "right" | "both" | "either";
  * // Order may vary: 1, "a", 2, "b", 3, "c"
  * ```
  *
- * @category utils
+ * @category combining
  * @since 4.0.0
  */
 export declare const merge: {
@@ -4743,7 +4878,7 @@ export declare const merge: {
      * // Order may vary: 1, "a", 2, "b", 3, "c"
      * ```
      *
-     * @category utils
+     * @category combining
      * @since 4.0.0
      */
     <OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>(right: Channel<OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>, options?: {
@@ -4775,7 +4910,7 @@ export declare const merge: {
      * // Order may vary: 1, "a", 2, "b", 3, "c"
      * ```
      *
-     * @category utils
+     * @category combining
      * @since 4.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>(left: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, right: Channel<OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>, options?: {
@@ -4786,12 +4921,17 @@ export declare const merge: {
  * Runs an effect concurrently with a channel while emitting only the channel's
  * output elements.
  *
+ * **When to use**
+ *
+ * Use when a side effect should run for the lifetime of a channel and only the
+ * channel's output elements should be emitted.
+ *
  * **Details**
  *
  * The effect's successful value is ignored. If the effect fails while the
  * channel is running, the returned channel fails with that error.
  *
- * @category utils
+ * @category combining
  * @since 4.0.0
  */
 export declare const mergeEffect: {
@@ -4799,12 +4939,17 @@ export declare const mergeEffect: {
      * Runs an effect concurrently with a channel while emitting only the channel's
      * output elements.
      *
+     * **When to use**
+     *
+     * Use when a side effect should run for the lifetime of a channel and only the
+     * channel's output elements should be emitted.
+     *
      * **Details**
      *
      * The effect's successful value is ignored. If the effect fails while the
      * channel is running, the returned channel fails with that error.
      *
-     * @category utils
+     * @category combining
      * @since 4.0.0
      */
     <X, E, R>(effect: Effect.Effect<X, E, R>): <OutElem, OutDone, OutErr, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem, OutErr | E, OutDone, InElem, InErr, InDone, Env | R>;
@@ -4812,12 +4957,17 @@ export declare const mergeEffect: {
      * Runs an effect concurrently with a channel while emitting only the channel's
      * output elements.
      *
+     * **When to use**
+     *
+     * Use when a side effect should run for the lifetime of a channel and only the
+     * channel's output elements should be emitted.
+     *
      * **Details**
      *
      * The effect's successful value is ignored. If the effect fails while the
      * channel is running, the returned channel fails with that error.
      *
-     * @category utils
+     * @category combining
      * @since 4.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, X, E, R>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, effect: Effect.Effect<X, E, R>): Channel<OutElem, OutErr | E, OutDone, InElem, InErr, InDone, Env | R>;
@@ -4901,7 +5051,7 @@ export declare const encodeText: <Err, Done>() => Channel<Arr.NonEmptyReadonlyAr
  * // Outputs: 2, 4, 6
  * ```
  *
- * @category utils
+ * @category sequencing
  * @since 2.0.0
  */
 export declare const pipeTo: {
@@ -4930,7 +5080,7 @@ export declare const pipeTo: {
      * // Outputs: 2, 4, 6
      * ```
      *
-     * @category utils
+     * @category sequencing
      * @since 2.0.0
      */
     <OutElem2, OutErr2, OutDone2, OutElem, OutErr, OutDone, Env2>(that: Channel<OutElem2, OutErr2, OutDone2, OutElem, OutErr, OutDone, Env2>): <InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem2, OutErr2, OutDone2, InElem, InErr, InDone, Env2 | Env>;
@@ -4959,7 +5109,7 @@ export declare const pipeTo: {
      * // Outputs: 2, 4, 6
      * ```
      *
-     * @category utils
+     * @category sequencing
      * @since 2.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, OutElem2, OutErr2, OutDone2, Env2>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, that: Channel<OutElem2, OutErr2, OutDone2, OutElem, OutErr, OutDone, Env2>): Channel<OutElem2, OutErr2, OutDone2, InElem, InErr, InDone, Env2 | Env>;
@@ -4988,7 +5138,7 @@ export declare const pipeTo: {
  * // Source errors are preserved and not sent to transform channel
  * ```
  *
- * @category utils
+ * @category sequencing
  * @since 2.0.0
  */
 export declare const pipeToOrFail: {
@@ -5016,7 +5166,7 @@ export declare const pipeToOrFail: {
      * // Source errors are preserved and not sent to transform channel
      * ```
      *
-     * @category utils
+     * @category sequencing
      * @since 2.0.0
      */
     <OutElem2, OutErr2, OutDone2, OutElem, OutDone, Env2>(that: Channel<OutElem2, OutErr2, OutDone2, OutElem, never, OutDone, Env2>): <OutErr, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem2, OutErr | OutErr2, OutDone2, InElem, InErr, InDone, Env2 | Env>;
@@ -5044,7 +5194,7 @@ export declare const pipeToOrFail: {
      * // Source errors are preserved and not sent to transform channel
      * ```
      *
-     * @category utils
+     * @category sequencing
      * @since 2.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, OutElem2, OutErr2, OutDone2, Env2>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, that: Channel<OutElem2, OutErr2, OutDone2, OutElem, never, OutDone, Env2>): Channel<OutElem2, OutErr | OutErr2, OutDone2, InElem, InErr, InDone, Env2 | Env>;
@@ -5081,7 +5231,7 @@ export declare const unwrap: <OutElem, OutErr, OutDone, InElem, InErr, InDone, R
  * Runs a channel with a scope provided for the duration of the channel
  * execution, removing the channel's `Scope` requirement.
  *
- * @category utils
+ * @category resource management
  * @since 2.0.0
  */
 export declare const scoped: <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Exclude<Env, Scope.Scope>>;
@@ -5116,7 +5266,7 @@ export declare const scoped: <OutElem, OutErr, OutDone, InElem, InErr, InDone, E
  * )
  * ```
  *
- * @category utils
+ * @category sequencing
  * @since 2.0.0
  */
 export declare const embedInput: {
@@ -5151,7 +5301,7 @@ export declare const embedInput: {
      * )
      * ```
      *
-     * @category utils
+     * @category sequencing
      * @since 2.0.0
      */
     <InElem, InErr, InDone, R>(input: (upstream: Pull.Pull<InElem, InErr, InDone>) => Effect.Effect<void, never, R>): <OutElem, OutErr, OutDone, Env>(self: Channel<OutElem, OutErr, OutDone, unknown, unknown, unknown, Env>) => Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env | R>;
@@ -5186,7 +5336,7 @@ export declare const embedInput: {
      * )
      * ```
      *
-     * @category utils
+     * @category sequencing
      * @since 2.0.0
      */
     <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>;
@@ -5195,6 +5345,11 @@ export declare const embedInput: {
  * Buffers individual output elements in a queue with the configured `capacity`
  * so a faster producer can progress independently of a slower consumer.
  *
+ * **When to use**
+ *
+ * Use when output elements can be decoupled from downstream demand and the
+ * configured backpressure or loss strategy is acceptable.
+ *
  * **Details**
  *
  * Finite queues use the `strategy` option. The default `"suspend"` strategy
@@ -5216,6 +5371,11 @@ export declare const buffer: {
      * Buffers individual output elements in a queue with the configured `capacity`
      * so a faster producer can progress independently of a slower consumer.
      *
+     * **When to use**
+     *
+     * Use when output elements can be decoupled from downstream demand and the
+     * configured backpressure or loss strategy is acceptable.
+     *
      * **Details**
      *
      * Finite queues use the `strategy` option. The default `"suspend"` strategy
@@ -5242,6 +5402,11 @@ export declare const buffer: {
      * Buffers individual output elements in a queue with the configured `capacity`
      * so a faster producer can progress independently of a slower consumer.
      *
+     * **When to use**
+     *
+     * Use when output elements can be decoupled from downstream demand and the
+     * configured backpressure or loss strategy is acceptable.
+     *
      * **Details**
      *
      * Finite queues use the `strategy` option. The default `"suspend"` strategy
@@ -5269,6 +5434,11 @@ export declare const buffer: {
  * Buffers array output elements in a queue with the configured `capacity` so a
  * faster producer can progress independently of a slower consumer.
  *
+ * **When to use**
+ *
+ * Use when emitted arrays are batches of elements and it is acceptable for
+ * buffering to flatten and rebuild those batches.
+ *
  * **Details**
  *
  * Finite queues use the `strategy` option. The default `"suspend"` strategy
@@ -5292,6 +5462,11 @@ export declare const bufferArray: {
      * Buffers array output elements in a queue with the configured `capacity` so a
      * faster producer can progress independently of a slower consumer.
      *
+     * **When to use**
+     *
+     * Use when emitted arrays are batches of elements and it is acceptable for
+     * buffering to flatten and rebuild those batches.
+     *
      * **Details**
      *
      * Finite queues use the `strategy` option. The default `"suspend"` strategy
@@ -5320,6 +5495,11 @@ export declare const bufferArray: {
      * Buffers array output elements in a queue with the configured `capacity` so a
      * faster producer can progress independently of a slower consumer.
      *
+     * **When to use**
+     *
+     * Use when emitted arrays are batches of elements and it is acceptable for
+     * buffering to flatten and rebuild those batches.
+     *
      * **Details**
      *
      * Finite queues use the `strategy` option. The default `"suspend"` strategy
@@ -5359,7 +5539,7 @@ export declare const bufferArray: {
  * channel's done value. If the channel completes first, the original channel's
  * done value is preserved.
  *
- * @category utils
+ * @category interruption
  * @since 2.0.0
  */
 export declare const interruptWhen: {
@@ -5377,7 +5557,7 @@ export declare const interruptWhen: {
      * channel's done value. If the channel completes first, the original channel's
      * done value is preserved.
      *
-     * @category utils
+     * @category interruption
      * @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>;
@@ -5395,7 +5575,7 @@ export declare const interruptWhen: {
      * channel's done value. If the channel completes first, the original channel's
      * done value is preserved.
      *
-     * @category utils
+     * @category interruption
      * @since 2.0.0
      */
     <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>;
@@ -5410,7 +5590,7 @@ export declare const interruptWhen: {
  * fails with that error. If the channel completes first, the channel's done
  * value is preserved.
  *
- * @category utils
+ * @category interruption
  * @since 4.0.0
  */
 export declare const haltWhen: {
@@ -5424,7 +5604,7 @@ export declare const haltWhen: {
      * fails with that error. If the channel completes first, the channel's done
      * value is preserved.
      *
-     * @category utils
+     * @category interruption
      * @since 4.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>;
@@ -5438,7 +5618,7 @@ export declare const haltWhen: {
      * fails with that error. If the channel completes first, the channel's done
      * value is preserved.
      *
-     * @category utils
+     * @category interruption
      * @since 4.0.0
      */
     <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>;
@@ -5451,7 +5631,7 @@ export declare const haltWhen: {
  * The finalizer receives the failure `Cause`. The original channel failure is
  * preserved. The finalizer itself must not fail.
  *
- * @category utils
+ * @category error handling
  * @since 4.0.0
  */
 export declare const onError: {
@@ -5463,7 +5643,7 @@ export declare const onError: {
      * The finalizer receives the failure `Cause`. The original channel failure is
      * preserved. The finalizer itself must not fail.
      *
-     * @category utils
+     * @category error handling
      * @since 4.0.0
      */
     <OutDone, OutErr, Env2>(finalizer: (cause: Cause.Cause<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>;
@@ -5475,7 +5655,7 @@ export declare const onError: {
      * The finalizer receives the failure `Cause`. The original channel failure is
      * preserved. The finalizer itself must not fail.
      *
-     * @category utils
+     * @category error handling
      * @since 4.0.0
      */
     <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>;
@@ -5506,7 +5686,7 @@ export declare const onError: {
  * })
  * ```
  *
- * @category utils
+ * @category resource management
  * @since 4.0.0
  */
 export declare const onExit: {
@@ -5536,7 +5716,7 @@ export declare const onExit: {
      * })
      * ```
      *
-     * @category utils
+     * @category resource management
      * @since 4.0.0
      */
     <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>;
@@ -5566,7 +5746,7 @@ export declare const onExit: {
      * })
      * ```
      *
-     * @category utils
+     * @category resource management
      * @since 4.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, Env2>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, finalizer: (e: Exit.Exit<OutDone, OutErr>) => Effect.Effect<unknown, never, Env2>): Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env2 | Env>;
@@ -5579,7 +5759,7 @@ export declare const onExit: {
  * The effect's successful value is ignored. If the effect fails, the returned
  * channel fails before running the source channel.
  *
- * @category utils
+ * @category hooks
  * @since 4.0.0
  */
 export declare const onStart: {
@@ -5591,7 +5771,7 @@ export declare const onStart: {
      * The effect's successful value is ignored. If the effect fails, the returned
      * channel fails before running the source channel.
      *
-     * @category utils
+     * @category hooks
      * @since 4.0.0
      */
     <A, E, R>(onStart: Effect.Effect<A, E, R>): <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem, OutErr | E, OutDone, InElem, InErr, InDone, Env | R>;
@@ -5603,7 +5783,7 @@ export declare const onStart: {
      * The effect's successful value is ignored. If the effect fails, the returned
      * channel fails before running the source channel.
      *
-     * @category utils
+     * @category hooks
      * @since 4.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, A, E, R>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, onStart: Effect.Effect<A, E, R>): Channel<OutElem, OutErr | E, OutDone, InElem, InErr, InDone, Env | R>;
@@ -5611,39 +5791,54 @@ export declare const onStart: {
 /**
  * Runs an effect the first time the channel emits an output element.
  *
+ * **When to use**
+ *
+ * Use when initialization depends on the first output element rather than only
+ * on channel startup.
+ *
  * **Details**
  *
  * The effect receives the first emitted element. The first element is still
  * emitted unchanged. The effect is not run if the channel completes without
  * emitting an element.
  *
- * @category utils
+ * @category hooks
  * @since 4.0.0
  */
 export declare const onFirst: {
     /**
      * Runs an effect the first time the channel emits an output element.
      *
+     * **When to use**
+     *
+     * Use when initialization depends on the first output element rather than only
+     * on channel startup.
+     *
      * **Details**
      *
      * The effect receives the first emitted element. The first element is still
      * emitted unchanged. The effect is not run if the channel completes without
      * emitting an element.
      *
-     * @category utils
+     * @category hooks
      * @since 4.0.0
      */
     <OutElem, A, E, R>(onFirst: (element: Types.NoInfer<OutElem>) => Effect.Effect<A, E, R>): <OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem, OutErr | E, OutDone, InElem, InErr, InDone, Env | R>;
     /**
      * Runs an effect the first time the channel emits an output element.
      *
+     * **When to use**
+     *
+     * Use when initialization depends on the first output element rather than only
+     * on channel startup.
+     *
      * **Details**
      *
      * The effect receives the first emitted element. The first element is still
      * emitted unchanged. The effect is not run if the channel completes without
      * emitting an element.
      *
-     * @category utils
+     * @category hooks
      * @since 4.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, A, E, R>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, onFirst: (element: Types.NoInfer<OutElem>) => Effect.Effect<A, E, R>): Channel<OutElem, OutErr | E, OutDone, InElem, InErr, InDone, Env | R>;
@@ -5657,7 +5852,7 @@ export declare const onFirst: {
  * not run when the channel fails. If the effect fails, the returned channel
  * fails with that error.
  *
- * @category utils
+ * @category hooks
  * @since 4.0.0
  */
 export declare const onEnd: {
@@ -5670,7 +5865,7 @@ export declare const onEnd: {
      * not run when the channel fails. If the effect fails, the returned channel
      * fails with that error.
      *
-     * @category utils
+     * @category hooks
      * @since 4.0.0
      */
     <A, E, R>(onEnd: Effect.Effect<A, E, R>): <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem, OutErr | E, OutDone, InElem, InErr, InDone, Env | R>;
@@ -5683,7 +5878,7 @@ export declare const onEnd: {
      * not run when the channel fails. If the effect fails, the returned channel
      * fails with that error.
      *
-     * @category utils
+     * @category hooks
      * @since 4.0.0
      */
     <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>;
@@ -5711,7 +5906,7 @@ export declare const onEnd: {
  * )
  * ```
  *
- * @category utils
+ * @category resource management
  * @since 2.0.0
  */
 export declare const ensuring: {
@@ -5738,7 +5933,7 @@ export declare const ensuring: {
      * )
      * ```
      *
-     * @category utils
+     * @category resource management
      * @since 2.0.0
      */
     <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>;
@@ -5765,7 +5960,7 @@ export declare const ensuring: {
      * )
      * ```
      *
-     * @category utils
+     * @category resource management
      * @since 2.0.0
      */
     <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>;
@@ -6043,7 +6238,7 @@ export declare const withSpan: {
 /**
  * The starting channel for Do notation, emitting an empty object.
  *
- * @category Do notation
+ * @category do notation
  * @since 4.0.0
  */
 export declare const Do: Channel<{}>;
@@ -6059,7 +6254,7 @@ export {
 /**
  * Adds a computed field to each object emitted by a channel.
  *
- * @category Do notation
+ * @category do notation
  * @since 4.0.0
  */
 let_ as let };
@@ -6073,7 +6268,7 @@ let_ as let };
  * channel's output becomes the value of the new field. `options.concurrency`
  * and `options.bufferSize` control how derived channels are flattened.
  *
- * @category Do notation
+ * @category do notation
  * @since 4.0.0
  */
 export declare const bind: {
@@ -6087,7 +6282,7 @@ export declare const bind: {
      * channel's output becomes the value of the new field. `options.concurrency`
      * and `options.bufferSize` control how derived channels are flattened.
      *
-     * @category Do notation
+     * @category do notation
      * @since 4.0.0
      */
     <N extends string, OutElem extends object, B, OutErr2, OutDone2, InElem2, InErr2, InDone2, Env2>(name: Exclude<N, keyof OutElem>, f: (a: NoInfer<OutElem>) => Channel<B, OutErr2, OutDone2, InElem2, InErr2, InDone2, Env2>, options?: {
@@ -6106,7 +6301,7 @@ export declare const bind: {
      * channel's output becomes the value of the new field. `options.concurrency`
      * and `options.bufferSize` control how derived channels are flattened.
      *
-     * @category Do notation
+     * @category do notation
      * @since 4.0.0
      */
     <OutElem extends object, OutErr, OutDone, InElem, InErr, InDone, Env, N extends string, B, OutErr2, OutDone2, InElem2, InErr2, InDone2, Env2>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, name: Exclude<N, keyof OutElem>, f: (a: NoInfer<OutElem>) => Channel<B, OutErr2, OutDone2, InElem2, InErr2, InDone2, Env2>, options?: {
@@ -6121,14 +6316,14 @@ export declare const bind: {
  *
  * **When to use**
  *
- * Use when starting a Channel Do-notation chain from an existing output value
- * by assigning that value to a field name.
+ * Use when you need to start 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
+ * @category do notation
  * @since 4.0.0
  */
 export declare const bindTo: {
@@ -6137,14 +6332,14 @@ export declare const bindTo: {
      *
      * **When to use**
      *
-     * Use when starting a Channel Do-notation chain from an existing output value
-     * by assigning that value to a field name.
+     * Use when you need to start 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
+     * @category do notation
      * @since 4.0.0
      */
     <N extends string>(name: N): <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<{
@@ -6155,14 +6350,14 @@ export declare const bindTo: {
      *
      * **When to use**
      *
-     * Use when starting a Channel Do-notation chain from an existing output value
-     * by assigning that value to a field name.
+     * Use when you need to start 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
+     * @category do notation
      * @since 4.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, N extends string>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, name: N): Channel<{
@@ -6485,6 +6680,11 @@ export declare const runFold: {
 /**
  * Runs a channel and effectfully folds all output elements with an accumulator.
  *
+ * **When to use**
+ *
+ * Use when folding channel output needs effects, services, or an additional
+ * failure channel during accumulation.
+ *
  * **Details**
  *
  * The initial accumulator is evaluated lazily. Each output element is passed to
@@ -6498,6 +6698,11 @@ export declare const runFoldEffect: {
     /**
      * Runs a channel and effectfully folds all output elements with an accumulator.
      *
+     * **When to use**
+     *
+     * Use when folding channel output needs effects, services, or an additional
+     * failure channel during accumulation.
+     *
      * **Details**
      *
      * The initial accumulator is evaluated lazily. Each output element is passed to
@@ -6511,6 +6716,11 @@ export declare const runFoldEffect: {
     /**
      * Runs a channel and effectfully folds all output elements with an accumulator.
      *
+     * **When to use**
+     *
+     * Use when folding channel output needs effects, services, or an additional
+     * failure channel during accumulation.
+     *
      * **Details**
      *
      * The initial accumulator is evaluated lazily. Each output element is passed to