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

package/src/Channel.ts

@@ -1059,6 +1059,11 @@ export const fail = <E>(error: E): Channel<never, E, never> => fromPull(Effect.s
  * 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
@@ -1092,6 +1097,11 @@ export const failSync = <E>(evaluate: LazyArg<E>): Channel<never, E, never> => f
 /**
  * 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
@@ -1992,6 +2002,11 @@ export 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
  */
@@ -1999,6 +2014,11 @@ export 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
    */
@@ -2008,6 +2028,11 @@ export 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
    */
@@ -2036,6 +2061,11 @@ const concurrencyIsSequential = (
  * 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.
@@ -2089,6 +2119,11 @@ export 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.
@@ -2150,6 +2185,11 @@ export 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.
@@ -3521,7 +3561,7 @@ export const flatten = <
  * // Outputs: 1, 2, 3, 4, 5, 6, 7, 8, 9
  * ```
  *
- * @category utils
+ * @category transforming
  * @since 4.0.0
  */
 export const flattenArray = <
@@ -3572,7 +3612,7 @@ export const flattenArray = <
  * 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 const flattenTake = <
@@ -3636,14 +3676,14 @@ export const drain = <
 /**
  * Repeats this channel according to the provided schedule.
  *
- * @category utils
+ * @category repetition
  * @since 4.0.0
  */
 export const repeat: {
   /**
    * Repeats this channel according to the provided schedule.
    *
-   * @category utils
+   * @category repetition
    * @since 4.0.0
    */
   <SO, OutDone, SE, SR>(
@@ -3658,7 +3698,7 @@ export const repeat: {
   /**
    * 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>(
@@ -3708,7 +3748,7 @@ export const repeat: {
 /**
  * Repeats this channel forever.
  *
- * @category utils
+ * @category repetition
  * @since 4.0.0
  */
 export const forever = <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>(
@@ -3726,7 +3766,7 @@ export const forever = <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>(
  * fails. If the schedule finishes, the returned channel completes with the
  * schedule output.
  *
- * @category utils
+ * @category sequencing
  * @since 4.0.0
  */
 export const schedule: {
@@ -3741,7 +3781,7 @@ export 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>(
@@ -3758,7 +3798,7 @@ export 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>(
@@ -4048,6 +4088,11 @@ export 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
@@ -4061,6 +4106,11 @@ export 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
@@ -4076,6 +4126,11 @@ export 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
@@ -4487,6 +4542,11 @@ export 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
@@ -4501,6 +4561,11 @@ export 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
@@ -4519,6 +4584,11 @@ export 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
@@ -4550,6 +4620,11 @@ export 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
@@ -4564,6 +4639,11 @@ export 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
@@ -4580,6 +4660,11 @@ export 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
@@ -4951,6 +5036,11 @@ export 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
@@ -4997,6 +5087,11 @@ export 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
@@ -5058,6 +5153,11 @@ export 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
@@ -5337,6 +5437,11 @@ export 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
@@ -5350,6 +5455,11 @@ export 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
@@ -5378,6 +5488,11 @@ export 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
@@ -5609,7 +5724,7 @@ export 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**
@@ -5632,7 +5747,7 @@ export 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**
@@ -5687,7 +5802,7 @@ export 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**
@@ -7456,6 +7571,11 @@ const ignoreCause_ = <
 /**
  * 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.
@@ -7495,7 +7615,7 @@ export const ignoreCause: <
  * 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 const retry: {
@@ -7503,7 +7623,7 @@ export 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>(
@@ -7521,7 +7641,7 @@ export 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>(
@@ -7773,6 +7893,11 @@ export 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
@@ -7798,13 +7923,18 @@ export const switchMap: {
  * // Outputs: 1, 2, 3, 4, 5, 6 (order may vary due to concurrency)
  * ```
  *
- * @category utils
+ * @category combining
  * @since 2.0.0
  */
 export 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
@@ -7830,7 +7960,7 @@ export const mergeAll: {
    * // Outputs: 1, 2, 3, 4, 5, 6 (order may vary due to concurrency)
    * ```
    *
-   * @category utils
+   * @category combining
    * @since 2.0.0
    */
   (
@@ -7861,6 +7991,11 @@ export 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
@@ -7886,7 +8021,7 @@ export 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>(
@@ -7951,6 +8086,11 @@ export const mergeAll: {
         const queue = yield* Queue.bounded</**
          * 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
@@ -7976,12 +8116,17 @@ export const mergeAll: {
          * // Outputs: 1, 2, 3, 4, 5, 6 (order may vary due to concurrency)
          * ```
          *
-         * @category utils
+         * @category combining
          * @since 2.0.0
          */
         OutElem, /**
          * 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
@@ -8007,7 +8152,7 @@ export const mergeAll: {
          * // Outputs: 1, 2, 3, 4, 5, 6 (order may vary due to concurrency)
          * ```
          *
-         * @category utils
+         * @category combining
          * @since 2.0.0
          */
         OutErr | OutErr1 | Cause.Done<OutDone>>(
@@ -8110,7 +8255,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 const merge: {
@@ -8140,7 +8285,7 @@ export 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>(
@@ -8185,7 +8330,7 @@ export const merge: {
    * // Order may vary: 1, "a", 2, "b", 3, "c"
    * ```
    *
-   * @category utils
+   * @category combining
    * @since 4.0.0
    */
   <
@@ -8276,7 +8421,7 @@ export const merge: {
      * // Order may vary: 1, "a", 2, "b", 3, "c"
      * ```
      *
-     * @category utils
+     * @category combining
      * @since 4.0.0
      */
     OutElem | OutElem1, /**
@@ -8305,7 +8450,7 @@ export const merge: {
      * // Order may vary: 1, "a", 2, "b", 3, "c"
      * ```
      *
-     * @category utils
+     * @category combining
      * @since 4.0.0
      */
     OutErr | OutErr1 | Cause.Done<OutDone | OutDone1>>(0)
@@ -8369,12 +8514,17 @@ export 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 const mergeEffect: {
@@ -8382,12 +8532,17 @@ export 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>(
@@ -8397,12 +8552,17 @@ export 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>(
@@ -8628,7 +8788,7 @@ export const encodeText = <Err, Done>(): Channel<
  * // Outputs: 2, 4, 6
  * ```
  *
- * @category utils
+ * @category sequencing
  * @since 2.0.0
  */
 export const pipeTo: {
@@ -8657,7 +8817,7 @@ export 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>(
@@ -8688,7 +8848,7 @@ export 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>(
@@ -8730,7 +8890,7 @@ export const pipeTo: {
  * // Source errors are preserved and not sent to transform channel
  * ```
  *
- * @category utils
+ * @category sequencing
  * @since 2.0.0
  */
 export const pipeToOrFail: {
@@ -8758,7 +8918,7 @@ export 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>(
@@ -8788,7 +8948,7 @@ export 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>(
@@ -8867,7 +9027,7 @@ export const unwrap = <OutElem, OutErr, OutDone, InElem, InErr, InDone, R2, E, 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 const scoped = <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>(
@@ -8911,7 +9071,7 @@ export const scoped = <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>(
  * )
  * ```
  *
- * @category utils
+ * @category sequencing
  * @since 2.0.0
  */
 export const embedInput: {
@@ -8946,7 +9106,7 @@ export const embedInput: {
    * )
    * ```
    *
-   * @category utils
+   * @category sequencing
    * @since 2.0.0
    */
   <InElem, InErr, InDone, R>(
@@ -8987,7 +9147,7 @@ export const embedInput: {
    * )
    * ```
    *
-   * @category utils
+   * @category sequencing
    * @since 2.0.0
    */
   <OutElem, OutErr, OutDone, Env, InErr, InElem, InDone, R>(
@@ -9016,6 +9176,11 @@ export 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
@@ -9037,6 +9202,11 @@ export 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
@@ -9065,6 +9235,11 @@ export 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
@@ -9101,6 +9276,11 @@ export 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
@@ -9121,6 +9301,11 @@ export 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
@@ -9155,6 +9340,11 @@ export 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
@@ -9178,6 +9368,11 @@ export 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
@@ -9208,6 +9403,11 @@ export 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
@@ -9246,6 +9446,11 @@ export 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
@@ -9268,6 +9473,11 @@ export 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
@@ -9314,7 +9524,7 @@ export 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 const interruptWhen: {
@@ -9332,7 +9542,7 @@ export 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>(
@@ -9352,7 +9562,7 @@ export 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>(
@@ -9379,7 +9589,7 @@ export 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 const haltWhen: {
@@ -9393,7 +9603,7 @@ export 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>(
@@ -9409,7 +9619,7 @@ export 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>(
@@ -9443,7 +9653,7 @@ export 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 const onError: {
@@ -9455,7 +9665,7 @@ export 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>(
@@ -9471,7 +9681,7 @@ export 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>(
@@ -9510,7 +9720,7 @@ export const onError: {
  * })
  * ```
  *
- * @category utils
+ * @category resource management
  * @since 4.0.0
  */
 export const onExit: {
@@ -9540,7 +9750,7 @@ export const onExit: {
    * })
    * ```
    *
-   * @category utils
+   * @category resource management
    * @since 4.0.0
    */
   <OutDone, OutErr, Env2>(
@@ -9574,7 +9784,7 @@ export const onExit: {
    * })
    * ```
    *
-   * @category utils
+   * @category resource management
    * @since 4.0.0
    */
   <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, Env2>(
@@ -9599,7 +9809,7 @@ export 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 const onStart: {
@@ -9611,7 +9821,7 @@ export 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>(
@@ -9625,7 +9835,7 @@ export 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>(
@@ -9640,26 +9850,36 @@ export 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 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>(
@@ -9668,13 +9888,18 @@ export 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, OutErr, OutDone, InElem, InErr, InDone, Env, A, E, R>(
@@ -9704,7 +9929,7 @@ export 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 const onEnd: {
@@ -9717,7 +9942,7 @@ export 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>(
@@ -9732,7 +9957,7 @@ export 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>(
@@ -9772,7 +9997,7 @@ export const onEnd: {
  * )
  * ```
  *
- * @category utils
+ * @category resource management
  * @since 2.0.0
  */
 export const ensuring: {
@@ -9799,7 +10024,7 @@ export 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>(
@@ -9828,7 +10053,7 @@ export const ensuring: {
    * )
    * ```
    *
-   * @category utils
+   * @category resource management
    * @since 2.0.0
    */
   <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, Env2>(
@@ -10283,7 +10508,7 @@ const withSpanImpl = <OutElem, OutErr, OutDone, InElem, InErr, InDone, R>(
 /**
  * The starting channel for Do notation, emitting an empty object.
  *
- * @category Do notation
+ * @category do notation
  * @since 4.0.0
  */
 export const Do: Channel<{}> = succeed({})
@@ -10337,7 +10562,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
@@ -10353,7 +10578,7 @@ export {
  * 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 const bind: {
@@ -10367,7 +10592,7 @@ export 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>(
@@ -10398,7 +10623,7 @@ export 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
    */
   <
@@ -10478,14 +10703,14 @@ export 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 const bindTo: {
@@ -10494,14 +10719,14 @@ export 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>(
@@ -10520,14 +10745,14 @@ export 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>(
@@ -10977,6 +11202,11 @@ export 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
@@ -10990,6 +11220,11 @@ export 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
@@ -11005,6 +11240,11 @@ export 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