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

package/src/Stream.ts

@@ -234,7 +234,7 @@ export interface StreamUnifyIgnore {
  * // Equivalent to: Stream<number, string, never>
  * ```
  *
- * @category Type Lambdas
+ * @category type lambdas
  * @since 2.0.0
  */
 export interface StreamTypeLambda extends TypeLambda {
@@ -286,7 +286,7 @@ export interface VarianceStruct<out A, out E, out R> {
  * // SuccessType is number
  * ```
  *
- * @category Type-Level
+ * @category utility types
  * @since 3.4.0
  */
 export type Success<T extends Stream<any, any, any>> = [T] extends [Stream<infer _A, infer _E, infer _R>] ? _A : never
@@ -304,7 +304,7 @@ export type Success<T extends Stream<any, any, any>> = [T] extends [Stream<infer
  * // ErrorType is string
  * ```
  *
- * @category Type-Level
+ * @category utility types
  * @since 3.4.0
  */
 export type Error<T extends Stream<any, any, any>> = [T] extends [Stream<infer _A, infer _E, infer _R>] ? _E : never
@@ -325,7 +325,7 @@ export type Error<T extends Stream<any, any, any>> = [T] extends [Stream<infer _
  * // RequiredServices is { db: Database }
  * ```
  *
- * @category Type-Level
+ * @category utility types
  * @since 4.0.0
  */
 export type Services<T extends Stream<any, any, any>> = [T] extends [Stream<infer _A, infer _E, infer _R>] ? _R
@@ -373,7 +373,7 @@ export const isStream = (u: unknown): u is Stream<unknown, unknown, unknown> =>
  * // Output: 4096
  * ```
  *
- * @category Constants
+ * @category constants
  * @since 2.0.0
  */
 export const DefaultChunkSize: number = Channel.DefaultChunkSize
@@ -464,7 +464,7 @@ export const fromEffect = <A, E, R>(effect: Effect.Effect<A, E, R>): Stream<A, E
  * // Output: [ "Hello, World!" ]
  * ```
  *
- * @category Context
+ * @category context
  * @since 4.0.0
  */
 export const service = <I, S>(service: Context.Key<I, S>): Stream<S, never, I> => fromEffect(Effect.service(service))
@@ -475,8 +475,8 @@ export const service = <I, S>(service: Context.Key<I, S>): Stream<S, never, I> =
  *
  * **When to use**
  *
- * Use to emit an optional dependency as a stream element without requiring that
- * dependency to be present.
+ * Use when you need a stream that emits an optional service from the context
+ * without requiring that service to be present.
  *
  * **Example** (Accessing an optional service as a stream)
  *
@@ -509,7 +509,7 @@ export const service = <I, S>(service: Context.Key<I, S>): Stream<S, never, I> =
  * // Output: [ "Hello, World!" ]
  * ```
  *
- * @category Context
+ * @category context
  * @since 4.0.0
  */
 export const serviceOption = <I, S>(service: Context.Key<I, S>): Stream<Option.Option<S>> =>
@@ -810,8 +810,8 @@ export const toChannel = <A, E, R>(
  *
  * **When to use**
  *
- * Use when you can use the `Queue` with the apis from the `Queue` module to emit
- * values to the stream or to signal the stream ending.
+ * Use when you need callback-based code to emit stream values by offering to a
+ * `Queue`, or signal stream completion through the `Queue` module APIs.
  *
  * By default it uses an "unbounded" buffer size.
  * You can customize the buffer size and strategy by passing an object as the
@@ -1183,6 +1183,11 @@ export const fromIterable = <A>(
 /**
  * Creates a stream from an effect producing an iterable of values.
  *
+ * **When to use**
+ *
+ * Use when the iterable must be acquired from an Effect before the stream emits,
+ * and acquisition services or failures should be part of the stream.
+ *
  * **Example** (Creating a stream from an iterable effect)
  *
  * ```ts
@@ -1272,6 +1277,11 @@ export const fromArray = <A>(array: ReadonlyArray<A>): Stream<A> =>
 /**
  * Creates a stream from an effect that produces an array of values.
  *
+ * **When to use**
+ *
+ * Use when the array must be acquired from an Effect before the stream emits,
+ * and acquisition services or failures should be part of the stream.
+ *
  * **Example** (Creating a stream from an effect that produces an array of values)
  *
  * ```ts
@@ -1559,8 +1569,9 @@ export const fromSchedule = <O, E, R>(schedule: Schedule.Schedule<O, unknown, E,
  *
  * **When to use**
  *
- * Use to create the subscription and `Stream.take` or
- * cancellation to control how many values are consumed.
+ * Use when you already have a `PubSub.Subscription` and want to expose its
+ * messages as a `Stream`, with `Stream.take` or cancellation controlling how
+ * many values are consumed.
  *
  * **Example** (Creating a stream from a PubSub subscription)
  *
@@ -2200,6 +2211,11 @@ export const mapArray: {
 /**
  * Maps over elements of the stream with the specified effectful function.
  *
+ * **When to use**
+ *
+ * Use when each stream element transformation needs an Effect, service
+ * dependency, failure channel, or configured concurrency.
+ *
  * **Example** (Effectfully mapping stream values)
  *
  * ```ts
@@ -2236,6 +2252,11 @@ export const mapEffect: {
   /**
    * Maps over elements of the stream with the specified effectful function.
    *
+   * **When to use**
+   *
+   * Use when each stream element transformation needs an Effect, service
+   * dependency, failure channel, or configured concurrency.
+   *
    * **Example** (Effectfully mapping stream values)
    *
    * ```ts
@@ -2278,6 +2299,11 @@ export const mapEffect: {
   /**
    * Maps over elements of the stream with the specified effectful function.
    *
+   * **When to use**
+   *
+   * Use when each stream element transformation needs an Effect, service
+   * dependency, failure channel, or configured concurrency.
+   *
    * **Example** (Effectfully mapping stream values)
    *
    * ```ts
@@ -2336,6 +2362,11 @@ export const mapEffect: {
 /**
  * Flattens a stream of `Effect` values into a stream of their results.
  *
+ * **When to use**
+ *
+ * Use when stream elements already are effects and their successes should become
+ * stream elements while their failures enter the stream error channel.
+ *
  * **Example** (Flattening a stream of Effect values into a stream of their results)
  *
  * ```ts
@@ -2385,6 +2416,11 @@ export const flattenEffect: <
 /**
  * Maps over non-empty array chunks emitted by the stream effectfully.
  *
+ * **When to use**
+ *
+ * Use when transformation needs to see and replace each non-empty emitted chunk
+ * effectfully instead of mapping individual stream elements.
+ *
  * **Example** (Effectfully mapping stream chunks)
  *
  * ```ts
@@ -2412,6 +2448,11 @@ export const mapArrayEffect: {
   /**
    * Maps over non-empty array chunks emitted by the stream effectfully.
    *
+   * **When to use**
+   *
+   * Use when transformation needs to see and replace each non-empty emitted chunk
+   * effectfully instead of mapping individual stream elements.
+   *
    * **Example** (Effectfully mapping stream chunks)
    *
    * ```ts
@@ -2441,6 +2482,11 @@ export const mapArrayEffect: {
   /**
    * Maps over non-empty array chunks emitted by the stream effectfully.
    *
+   * **When to use**
+   *
+   * Use when transformation needs to see and replace each non-empty emitted chunk
+   * effectfully instead of mapping individual stream elements.
+   *
    * **Example** (Effectfully mapping stream chunks)
    *
    * ```ts
@@ -4146,7 +4192,7 @@ export const prepend: {
  * // Output: [ 1, 2, 3, 4 ]
  * ```
  *
- * @category Merging
+ * @category merging
  * @since 2.0.0
  */
 export const merge: {
@@ -4175,7 +4221,7 @@ export const merge: {
    * // Output: [ 1, 2, 3, 4 ]
    * ```
    *
-   * @category Merging
+   * @category merging
    * @since 2.0.0
    */
   <A2, E2, R2>(
@@ -4209,7 +4255,7 @@ export const merge: {
    * // Output: [ 1, 2, 3, 4 ]
    * ```
    *
-   * @category Merging
+   * @category merging
    * @since 2.0.0
    */
   <A, E, R, A2, E2, R2>(
@@ -4233,6 +4279,11 @@ export const merge: {
 /**
  * Merges this stream with a background effect, keeping the stream's elements.
  *
+ * **When to use**
+ *
+ * Use when an effect should run concurrently for the lifetime of a stream while
+ * only the stream's elements remain in the output.
+ *
  * **Details**
  *
  * The effect runs concurrently, fails the stream if it fails, and is interrupted
@@ -4257,13 +4308,18 @@ export const merge: {
  * // Output: [ 1, 2, 3 ]
  * ```
  *
- * @category Merging
+ * @category merging
  * @since 4.0.0
  */
 export const mergeEffect: {
   /**
    * Merges this stream with a background effect, keeping the stream's elements.
    *
+   * **When to use**
+   *
+   * Use when an effect should run concurrently for the lifetime of a stream while
+   * only the stream's elements remain in the output.
+   *
    * **Details**
    *
    * The effect runs concurrently, fails the stream if it fails, and is interrupted
@@ -4288,13 +4344,18 @@ export const mergeEffect: {
    * // Output: [ 1, 2, 3 ]
    * ```
    *
-   * @category Merging
+   * @category merging
    * @since 4.0.0
    */
   <A2, E2, R2>(effect: Effect.Effect<A2, E2, R2>): <A, E, R>(self: Stream<A, E, R>) => Stream<A, E2 | E, R2 | R>
   /**
    * Merges this stream with a background effect, keeping the stream's elements.
    *
+   * **When to use**
+   *
+   * Use when an effect should run concurrently for the lifetime of a stream while
+   * only the stream's elements remain in the output.
+   *
    * **Details**
    *
    * The effect runs concurrently, fails the stream if it fails, and is interrupted
@@ -4319,7 +4380,7 @@ export const mergeEffect: {
    * // Output: [ 1, 2, 3 ]
    * ```
    *
-   * @category Merging
+   * @category merging
    * @since 4.0.0
    */
   <A, E, R, A2, E2, R2>(self: Stream<A, E, R>, effect: Effect.Effect<A2, E2, R2>): Stream<A, E | E2, R | R2>
@@ -4336,6 +4397,12 @@ export const mergeEffect: {
  * Merges this stream and the specified stream together, tagging values from the
  * left stream as `Result.succeed` and values from the right stream as `Result.fail`.
  *
+ * **When to use**
+ *
+ * Use when values from both streams should be emitted and downstream code needs
+ * left values wrapped as successful `Result` values and right values wrapped as
+ * failed `Result` values.
+ *
  * **Example** (Merging streams into results)
  *
  * ```ts
@@ -4363,7 +4430,7 @@ export const mergeEffect: {
  * // Output: [ "left:left", "right:right" ]
  * ```
  *
- * @category Merging
+ * @category merging
  * @since 4.0.0
  */
 export const mergeResult: {
@@ -4371,6 +4438,12 @@ export const mergeResult: {
    * Merges this stream and the specified stream together, tagging values from the
    * left stream as `Result.succeed` and values from the right stream as `Result.fail`.
    *
+   * **When to use**
+   *
+   * Use when values from both streams should be emitted and downstream code needs
+   * left values wrapped as successful `Result` values and right values wrapped as
+   * failed `Result` values.
+   *
    * **Example** (Merging streams into results)
    *
    * ```ts
@@ -4398,7 +4471,7 @@ export const mergeResult: {
    * // Output: [ "left:left", "right:right" ]
    * ```
    *
-   * @category Merging
+   * @category merging
    * @since 4.0.0
    */
   <A2, E2, R2>(that: Stream<A2, E2, R2>): <A, E, R>(self: Stream<A, E, R>) => Stream<Result.Result<A, A2>, E2 | E, R2 | R>
@@ -4406,6 +4479,12 @@ export const mergeResult: {
    * Merges this stream and the specified stream together, tagging values from the
    * left stream as `Result.succeed` and values from the right stream as `Result.fail`.
    *
+   * **When to use**
+   *
+   * Use when values from both streams should be emitted and downstream code needs
+   * left values wrapped as successful `Result` values and right values wrapped as
+   * failed `Result` values.
+   *
    * **Example** (Merging streams into results)
    *
    * ```ts
@@ -4433,7 +4512,7 @@ export const mergeResult: {
    * // Output: [ "left:left", "right:right" ]
    * ```
    *
-   * @category Merging
+   * @category merging
    * @since 4.0.0
    */
   <A, E, R, A2, E2, R2>(self: Stream<A, E, R>, that: Stream<A2, E2, R2>): Stream<Result.Result<A, A2>, E | E2, R | R2>
@@ -4452,6 +4531,11 @@ export const mergeResult: {
 /**
  * Merges two streams while emitting only the values from the left stream.
  *
+ * **When to use**
+ *
+ * Use when the right stream is needed for its effects or failures, but downstream
+ * consumers should only receive values from the left stream.
+ *
  * **Details**
  *
  * The right stream still runs for its effects, and any failures from the right
@@ -4474,13 +4558,18 @@ export const mergeResult: {
  * // Output: [ 1, 2 ]
  * ```
  *
- * @category Merging
+ * @category merging
  * @since 2.0.0
  */
 export const mergeLeft: {
   /**
    * Merges two streams while emitting only the values from the left stream.
    *
+   * **When to use**
+   *
+   * Use when the right stream is needed for its effects or failures, but downstream
+   * consumers should only receive values from the left stream.
+   *
    * **Details**
    *
    * The right stream still runs for its effects, and any failures from the right
@@ -4503,13 +4592,18 @@ export const mergeLeft: {
    * // Output: [ 1, 2 ]
    * ```
    *
-   * @category Merging
+   * @category merging
    * @since 2.0.0
    */
   <AR, ER, RR>(right: Stream<AR, ER, RR>): <AL, EL, RL>(left: Stream<AL, EL, RL>) => Stream<AL, ER | EL, RR | RL>
   /**
    * Merges two streams while emitting only the values from the left stream.
    *
+   * **When to use**
+   *
+   * Use when the right stream is needed for its effects or failures, but downstream
+   * consumers should only receive values from the left stream.
+   *
    * **Details**
    *
    * The right stream still runs for its effects, and any failures from the right
@@ -4532,7 +4626,7 @@ export const mergeLeft: {
    * // Output: [ 1, 2 ]
    * ```
    *
-   * @category Merging
+   * @category merging
    * @since 2.0.0
    */
   <AL, EL, RL, AR, ER, RR>(left: Stream<AL, EL, RL>, right: Stream<AR, ER, RR>): Stream<AL, EL | ER, RL | RR>
@@ -4546,6 +4640,11 @@ export const mergeLeft: {
  * Merges this stream and the specified stream together, emitting only the
  * values from the right stream while the left stream runs for its effects.
  *
+ * **When to use**
+ *
+ * Use when the left stream is needed for its effects or failures, but downstream
+ * consumers should only receive values from the right stream.
+ *
  * **Details**
  *
  * The merged stream ends when the right stream completes, interrupting the
@@ -4572,7 +4671,7 @@ export const mergeLeft: {
  * // Output: [ 1, 2 ]
  * ```
  *
- * @category Merging
+ * @category merging
  * @since 2.0.0
  */
 export const mergeRight: {
@@ -4580,6 +4679,11 @@ export const mergeRight: {
    * Merges this stream and the specified stream together, emitting only the
    * values from the right stream while the left stream runs for its effects.
    *
+   * **When to use**
+   *
+   * Use when the left stream is needed for its effects or failures, but downstream
+   * consumers should only receive values from the right stream.
+   *
    * **Details**
    *
    * The merged stream ends when the right stream completes, interrupting the
@@ -4606,7 +4710,7 @@ export const mergeRight: {
    * // Output: [ 1, 2 ]
    * ```
    *
-   * @category Merging
+   * @category merging
    * @since 2.0.0
    */
   <AR, ER, RR>(right: Stream<AR, ER, RR>): <AL, EL, RL>(left: Stream<AL, EL, RL>) => Stream<AR, ER | EL, RR | RL>
@@ -4614,6 +4718,11 @@ export const mergeRight: {
    * Merges this stream and the specified stream together, emitting only the
    * values from the right stream while the left stream runs for its effects.
    *
+   * **When to use**
+   *
+   * Use when the left stream is needed for its effects or failures, but downstream
+   * consumers should only receive values from the right stream.
+   *
    * **Details**
    *
    * The merged stream ends when the right stream completes, interrupting the
@@ -4640,7 +4749,7 @@ export const mergeRight: {
    * // Output: [ 1, 2 ]
    * ```
    *
-   * @category Merging
+   * @category merging
    * @since 2.0.0
    */
   <AL, EL, RL, AR, ER, RR>(left: Stream<AL, EL, RL>, right: Stream<AR, ER, RR>): Stream<AR, EL | ER, RL | RR>
@@ -4688,7 +4797,7 @@ export const mergeRight: {
  * @see {@link merge} for merging exactly two streams and choosing a halt strategy
  * @see {@link flatten} for flattening a stream that already emits streams
  *
- * @category Merging
+ * @category merging
  * @since 2.0.0
  */
 export const mergeAll: {
@@ -4730,7 +4839,7 @@ export const mergeAll: {
    * @see {@link merge} for merging exactly two streams and choosing a halt strategy
    * @see {@link flatten} for flattening a stream that already emits streams
    *
-   * @category Merging
+   * @category merging
    * @since 2.0.0
    */
   (
@@ -4777,7 +4886,7 @@ export const mergeAll: {
    * @see {@link merge} for merging exactly two streams and choosing a halt strategy
    * @see {@link flatten} for flattening a stream that already emits streams
    *
-   * @category Merging
+   * @category merging
    * @since 2.0.0
    */
   <A, E, R>(
@@ -5823,6 +5932,11 @@ export const zipWithPreviousAndNext = <A, E, R>(
  * Zips multiple streams so that when a value is emitted by any stream, it is
  * combined with the latest values from the other streams to produce a result.
  *
+ * **When to use**
+ *
+ * Use when each stream should contribute its latest value after all streams have
+ * emitted at least once.
+ *
  * **Gotchas**
  *
  * Note: tracking the latest value is done on a per-array basis. That means
@@ -5894,6 +6008,11 @@ export const zipLatestAll = <T extends ReadonlyArray<Stream<any, any, any>>>(
 /**
  * Combines two streams by emitting each new element with the latest value from the other stream.
  *
+ * **When to use**
+ *
+ * Use when two streams should start emitting combined pairs after both have
+ * produced at least one value.
+ *
  * **Gotchas**
  *
  * Note: tracking the latest value is done on a per-array basis. That means
@@ -5923,6 +6042,11 @@ export const zipLatest: {
   /**
    * Combines two streams by emitting each new element with the latest value from the other stream.
    *
+   * **When to use**
+   *
+   * Use when two streams should start emitting combined pairs after both have
+   * produced at least one value.
+   *
    * **Gotchas**
    *
    * Note: tracking the latest value is done on a per-array basis. That means
@@ -5952,6 +6076,11 @@ export const zipLatest: {
   /**
    * Combines two streams by emitting each new element with the latest value from the other stream.
    *
+   * **When to use**
+   *
+   * Use when two streams should start emitting combined pairs after both have
+   * produced at least one value.
+   *
    * **Gotchas**
    *
    * Note: tracking the latest value is done on a per-array basis. That means
@@ -5990,6 +6119,11 @@ export const zipLatest: {
  * Combines the latest values from both streams whenever either emits, using
  * the provided function.
  *
+ * **When to use**
+ *
+ * Use when two streams should start emitting custom combined values after both
+ * have produced at least one value.
+ *
  * **Gotchas**
  *
  * Note: tracking the latest value is done on a per-array basis. That means
@@ -6024,6 +6158,11 @@ export const zipLatestWith: {
    * Combines the latest values from both streams whenever either emits, using
    * the provided function.
    *
+   * **When to use**
+   *
+   * Use when two streams should start emitting custom combined values after both
+   * have produced at least one value.
+   *
    * **Gotchas**
    *
    * Note: tracking the latest value is done on a per-array basis. That means
@@ -6058,6 +6197,11 @@ export const zipLatestWith: {
    * Combines the latest values from both streams whenever either emits, using
    * the provided function.
    *
+   * **When to use**
+   *
+   * Use when two streams should start emitting custom combined values after both
+   * have produced at least one value.
+   *
    * **Gotchas**
    *
    * Note: tracking the latest value is done on a per-array basis. That means
@@ -6128,7 +6272,7 @@ export const zipLatestWith: {
  * // Output: [ 0, 1, 2 ]
  * ```
  *
- * @category Racing
+ * @category racing
  * @since 3.5.0
  */
 export const raceAll = <S extends ReadonlyArray<Stream<any, any, any>>>(
@@ -6189,7 +6333,7 @@ export const raceAll = <S extends ReadonlyArray<Stream<any, any, any>>>(
  * // Output: [ 0, 1, 2 ]
  * ```
  *
- * @category Racing
+ * @category racing
  * @since 3.7.0
  */
 export const race: {
@@ -6222,7 +6366,7 @@ export const race: {
    * // Output: [ 0, 1, 2 ]
    * ```
    *
-   * @category Racing
+   * @category racing
    * @since 3.7.0
    */
   <AR, ER, RR>(right: Stream<AR, ER, RR>): <AL, EL, RL>(left: Stream<AL, EL, RL>) => Stream<AL | AR, EL | ER, RL | RR>
@@ -6255,7 +6399,7 @@ export const race: {
    * // Output: [ 0, 1, 2 ]
    * ```
    *
-   * @category Racing
+   * @category racing
    * @since 3.7.0
    */
   <AL, EL, RL, AR, ER, RR>(left: Stream<AL, EL, RL>, right: Stream<AR, ER, RR>): Stream<AL | AR, EL | ER, RL | RR>
@@ -6955,8 +7099,8 @@ export const partitionQueue: {
  *
  * **When to use**
  *
- * Use when each stream element must be classified by an effectful `Filter` and
- * both passing and failing mapped values need to be consumed as streams.
+ * Use when you need to classify each stream element with an effectful `Filter`
+ * and consume both passing and failing mapped values as streams.
  *
  * **Details**
  *
@@ -6978,8 +7122,8 @@ export const partitionEffect: {
    *
    * **When to use**
    *
-   * Use when each stream element must be classified by an effectful `Filter` and
-   * both passing and failing mapped values need to be consumed as streams.
+   * Use when you need to classify each stream element with an effectful `Filter`
+   * and consume both passing and failing mapped values as streams.
    *
    * **Details**
    *
@@ -7014,8 +7158,8 @@ export const partitionEffect: {
    *
    * **When to use**
    *
-   * Use when each stream element must be classified by an effectful `Filter` and
-   * both passing and failing mapped values need to be consumed as streams.
+   * Use when you need to classify each stream element with an effectful `Filter`
+   * and consume both passing and failing mapped values as streams.
    *
    * **Details**
    *
@@ -7069,8 +7213,8 @@ export const partitionEffect: {
        *
        * **When to use**
        *
-       * Use when each stream element must be classified by an effectful `Filter` and
-       * both passing and failing mapped values need to be consumed as streams.
+       * Use when you need to classify each stream element with an effectful `Filter`
+       * and consume both passing and failing mapped values as streams.
        *
        * **Details**
        *
@@ -7091,8 +7235,8 @@ export const partitionEffect: {
        *
        * **When to use**
        *
-       * Use when each stream element must be classified by an effectful `Filter` and
-       * both passing and failing mapped values need to be consumed as streams.
+       * Use when you need to classify each stream element with an effectful `Filter`
+       * and consume both passing and failing mapped values as streams.
        *
        * **Details**
        *
@@ -7113,8 +7257,8 @@ export const partitionEffect: {
        *
        * **When to use**
        *
-       * Use when each stream element must be classified by an effectful `Filter` and
-       * both passing and failing mapped values need to be consumed as streams.
+       * Use when you need to classify each stream element with an effectful `Filter`
+       * and consume both passing and failing mapped values as streams.
        *
        * **Details**
        *
@@ -7135,8 +7279,8 @@ export const partitionEffect: {
        *
        * **When to use**
        *
-       * Use when each stream element must be classified by an effectful `Filter` and
-       * both passing and failing mapped values need to be consumed as streams.
+       * Use when you need to classify each stream element with an effectful `Filter`
+       * and consume both passing and failing mapped values as streams.
        *
        * **Details**
        *
@@ -7157,8 +7301,8 @@ export const partitionEffect: {
        *
        * **When to use**
        *
-       * Use when each stream element must be classified by an effectful `Filter` and
-       * both passing and failing mapped values need to be consumed as streams.
+       * Use when you need to classify each stream element with an effectful `Filter`
+       * and consume both passing and failing mapped values as streams.
        *
        * **Details**
        *
@@ -8421,8 +8565,8 @@ export const catchFilter: {
  *
  * **When to use**
  *
- * Use when your error type is a tagged union with a readonly `_tag`
- * field and you want to handle a specific error case.
+ * Use when you need to handle a specific error case from a stream whose error
+ * type is a tagged union with a readonly `_tag` field.
  *
  * **Example** (Catching tagged failures)
  *
@@ -8456,8 +8600,8 @@ export const catchTag: {
    *
    * **When to use**
    *
-   * Use when your error type is a tagged union with a readonly `_tag`
-   * field and you want to handle a specific error case.
+   * Use when you need to handle a specific error case from a stream whose error
+   * type is a tagged union with a readonly `_tag` field.
    *
    * **Example** (Catching tagged failures)
    *
@@ -8516,8 +8660,8 @@ export const catchTag: {
    *
    * **When to use**
    *
-   * Use when your error type is a tagged union with a readonly `_tag`
-   * field and you want to handle a specific error case.
+   * Use when you need to handle a specific error case from a stream whose error
+   * type is a tagged union with a readonly `_tag` field.
    *
    * **Example** (Catching tagged failures)
    *
@@ -8791,7 +8935,11 @@ export const catchTags: {
  * **When to use**
  *
  * Use to handle nested error causes without removing the parent error
- * from the error channel. The handler receives the unwrapped reason.
+ * from the error channel.
+ *
+ * **Details**
+ *
+ * The handler receives the unwrapped reason.
  *
  * **Example** (Catching a tagged error reason)
  *
@@ -8838,7 +8986,11 @@ export const catchReason: {
    * **When to use**
    *
    * Use to handle nested error causes without removing the parent error
-   * from the error channel. The handler receives the unwrapped reason.
+   * from the error channel.
+   *
+   * **Details**
+   *
+   * The handler receives the unwrapped reason.
    *
    * **Example** (Catching a tagged error reason)
    *
@@ -8914,7 +9066,11 @@ export const catchReason: {
    * **When to use**
    *
    * Use to handle nested error causes without removing the parent error
-   * from the error channel. The handler receives the unwrapped reason.
+   * from the error channel.
+   *
+   * **Details**
+   *
+   * The handler receives the unwrapped reason.
    *
    * **Example** (Catching a tagged error reason)
    *
@@ -9441,7 +9597,7 @@ export const catchCauseIf: {
  * **When to use**
  *
  * Use when you need to recover a stream 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**
@@ -9465,7 +9621,7 @@ export const catchCauseFilter: {
    * **When to use**
    *
    * Use when you need to recover a stream 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**
@@ -9494,7 +9650,7 @@ export const catchCauseFilter: {
    * **When to use**
    *
    * Use when you need to recover a stream 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**
@@ -9721,8 +9877,12 @@ export const orDie = <A, E, R>(self: Stream<A, E, R>): Stream<A, never, R> => fr
  * **When to use**
  *
  * Use when you want a failing stream to end gracefully rather than propagate
- * the error. The `log` option controls whether the failure is logged before
- * the stream terminates.
+ * the error.
+ *
+ * **Details**
+ *
+ * The `log` option controls whether the failure is logged before the stream
+ * terminates.
  *
  * **Example** (Ignoring stream failures)
  *
@@ -9788,9 +9948,8 @@ export const ignore: <
  *
  * **When to use**
  *
- * Use when a stream may fail with defects and you want to silently suppress the
- * entire failure cause — including both typed errors and defects — rather than
- * propagate it downstream.
+ * Use when you need to silently suppress a stream's entire failure cause,
+ * including both typed errors and defects, rather than propagate it downstream.
  *
  * **Example** (Ignoring stream failure causes)
  *
@@ -10533,6 +10692,11 @@ export const takeUntil: {
 /**
  * Takes stream elements until an effectful predicate returns `true`.
  *
+ * **When to use**
+ *
+ * Use when the stopping condition needs an Effect or service and predicate
+ * failure should fail the stream.
+ *
  * **Example** (Taking until an effectful predicate matches)
  *
  * ```ts
@@ -10557,6 +10721,11 @@ export const takeUntilEffect: {
   /**
    * Takes stream elements until an effectful predicate returns `true`.
    *
+   * **When to use**
+   *
+   * Use when the stopping condition needs an Effect or service and predicate
+   * failure should fail the stream.
+   *
    * **Example** (Taking until an effectful predicate matches)
    *
    * ```ts
@@ -10586,6 +10755,11 @@ export const takeUntilEffect: {
   /**
    * Takes stream elements until an effectful predicate returns `true`.
    *
+   * **When to use**
+   *
+   * Use when the stopping condition needs an Effect or service and predicate
+   * failure should fail the stream.
+   *
    * **Example** (Taking until an effectful predicate matches)
    *
    * ```ts
@@ -10885,6 +11059,11 @@ export const takeWhileFilter: {
 /**
  * Takes elements from the stream while the effectful predicate is `true`.
  *
+ * **When to use**
+ *
+ * Use when the leading-prefix predicate needs an Effect or service and the
+ * stream should stop before the first false result.
+ *
  * **Example** (Effectfully taking while a predicate holds)
  *
  * ```ts
@@ -10909,6 +11088,11 @@ export const takeWhileEffect: {
   /**
    * Takes elements from the stream while the effectful predicate is `true`.
    *
+   * **When to use**
+   *
+   * Use when the leading-prefix predicate needs an Effect or service and the
+   * stream should stop before the first false result.
+   *
    * **Example** (Effectfully taking while a predicate holds)
    *
    * ```ts
@@ -10933,6 +11117,11 @@ export const takeWhileEffect: {
   /**
    * Takes elements from the stream while the effectful predicate is `true`.
    *
+   * **When to use**
+   *
+   * Use when the leading-prefix predicate needs an Effect or service and the
+   * stream should stop before the first false result.
+   *
    * **Example** (Effectfully taking while a predicate holds)
    *
    * ```ts
@@ -11135,9 +11324,10 @@ export const dropUntil: {
  * Drops all elements of the stream until the specified effectful predicate
  * evaluates to `true`.
  *
- * **Details**
+ * **When to use**
  *
- * The first element that satisfies the predicate is also dropped.
+ * Use when dropping the leading prefix requires an Effect or service and the
+ * first matching element should also be dropped.
  *
  * **Example** (Dropping until an effectful predicate matches)
  *
@@ -11164,9 +11354,10 @@ export const dropUntilEffect: {
    * Drops all elements of the stream until the specified effectful predicate
    * evaluates to `true`.
    *
-   * **Details**
+   * **When to use**
    *
-   * The first element that satisfies the predicate is also dropped.
+   * Use when dropping the leading prefix requires an Effect or service and the
+   * first matching element should also be dropped.
    *
    * **Example** (Dropping until an effectful predicate matches)
    *
@@ -11195,9 +11386,10 @@ export const dropUntilEffect: {
    * Drops all elements of the stream until the specified effectful predicate
    * evaluates to `true`.
    *
-   * **Details**
+   * **When to use**
    *
-   * The first element that satisfies the predicate is also dropped.
+   * Use when dropping the leading prefix requires an Effect or service and the
+   * first matching element should also be dropped.
    *
    * **Example** (Dropping until an effectful predicate matches)
    *
@@ -12266,7 +12458,7 @@ export const split: {
  * // Output: [ "L:A", "R:1", "L:B", "R:2", "L:C", "R:3" ]
  * ```
  *
- * @category Merging
+ * @category merging
  * @since 2.0.0
  */
 export const combine: {
@@ -12303,7 +12495,7 @@ export const combine: {
    * // Output: [ "L:A", "R:1", "L:B", "R:2", "L:C", "R:3" ]
    * ```
    *
-   * @category Merging
+   * @category merging
    * @since 2.0.0
    */
   <A2, E2, R2, S, E, A, A3, E3, R3>(
@@ -12348,7 +12540,7 @@ export const combine: {
    * // Output: [ "L:A", "R:1", "L:B", "R:2", "L:C", "R:3" ]
    * ```
    *
-   * @category Merging
+   * @category merging
    * @since 2.0.0
    */
   <A, E, R, A2, E2, R2, S, A3, E3, R3>(
@@ -12842,6 +13034,11 @@ const emptyArr = Arr.empty<never>()
  * Maps each element statefully and effectfully, emitting zero or more output
  * values per input.
  *
+ * **When to use**
+ *
+ * Use when stateful element mapping needs Effects or can fail while emitting
+ * zero or more values per input element.
+ *
  * **Details**
  *
  * The mapping effect receives the current state and element, then returns the
@@ -12876,6 +13073,11 @@ export const mapAccumEffect: {
    * Maps each element statefully and effectfully, emitting zero or more output
    * values per input.
    *
+   * **When to use**
+   *
+   * Use when stateful element mapping needs Effects or can fail while emitting
+   * zero or more values per input element.
+   *
    * **Details**
    *
    * The mapping effect receives the current state and element, then returns the
@@ -12916,6 +13118,11 @@ export const mapAccumEffect: {
    * Maps each element statefully and effectfully, emitting zero or more output
    * values per input.
    *
+   * **When to use**
+   *
+   * Use when stateful element mapping needs Effects or can fail while emitting
+   * zero or more values per input element.
+   *
    * **Details**
    *
    * The mapping effect receives the current state and element, then returns the
@@ -12974,6 +13181,11 @@ export const mapAccumEffect: {
              * Maps each element statefully and effectfully, emitting zero or more output
              * values per input.
              *
+             * **When to use**
+             *
+             * Use when stateful element mapping needs Effects or can fail while emitting
+             * zero or more values per input element.
+             *
              * **Details**
              *
              * The mapping effect receives the current state and element, then returns the
@@ -13022,6 +13234,11 @@ export const mapAccumEffect: {
  * Maps each non-empty input chunk statefully and effectfully, emitting zero or
  * more output values per chunk.
  *
+ * **When to use**
+ *
+ * Use when stateful mapping should process each emitted non-empty chunk with an
+ * Effect instead of each element separately.
+ *
  * **Details**
  *
  * The mapping effect receives the current state and chunk, then returns the
@@ -13058,6 +13275,11 @@ export const mapAccumArrayEffect: {
    * Maps each non-empty input chunk statefully and effectfully, emitting zero or
    * more output values per chunk.
    *
+   * **When to use**
+   *
+   * Use when stateful mapping should process each emitted non-empty chunk with an
+   * Effect instead of each element separately.
+   *
    * **Details**
    *
    * The mapping effect receives the current state and chunk, then returns the
@@ -13100,6 +13322,11 @@ export const mapAccumArrayEffect: {
    * Maps each non-empty input chunk statefully and effectfully, emitting zero or
    * more output values per chunk.
    *
+   * **When to use**
+   *
+   * Use when stateful mapping should process each emitted non-empty chunk with an
+   * Effect instead of each element separately.
+   *
    * **Details**
    *
    * The mapping effect receives the current state and chunk, then returns the
@@ -14499,9 +14726,9 @@ const groupByImpl = <A, E, R, K, V, E2, R2>(
  *
  * **When to use**
  *
- * Use when a stream is already ordered by the grouping key and you want to emit
- * each consecutive run as a non-empty array while keeping later non-adjacent
- * runs separate.
+ * Use when you already have a stream ordered by the grouping key and want to
+ * emit each consecutive run as a non-empty array while keeping later
+ * non-adjacent runs separate.
  *
  * **Details**
  *
@@ -14521,9 +14748,9 @@ export const groupAdjacentBy: {
    *
    * **When to use**
    *
-   * Use when a stream is already ordered by the grouping key and you want to emit
-   * each consecutive run as a non-empty array while keeping later non-adjacent
-   * runs separate.
+   * Use when you already have a stream ordered by the grouping key and want to
+   * emit each consecutive run as a non-empty array while keeping later
+   * non-adjacent runs separate.
    *
    * **Details**
    *
@@ -14543,9 +14770,9 @@ export const groupAdjacentBy: {
    *
    * **When to use**
    *
-   * Use when a stream is already ordered by the grouping key and you want to emit
-   * each consecutive run as a non-empty array while keeping later non-adjacent
-   * runs separate.
+   * Use when you already have a stream ordered by the grouping key and want to
+   * emit each consecutive run as a non-empty array while keeping later
+   * non-adjacent runs separate.
    *
    * **Details**
    *
@@ -14573,9 +14800,9 @@ export const groupAdjacentBy: {
        *
        * **When to use**
        *
-       * Use when a stream is already ordered by the grouping key and you want to emit
-       * each consecutive run as a non-empty array while keeping later non-adjacent
-       * runs separate.
+       * Use when you already have a stream ordered by the grouping key and want to
+       * emit each consecutive run as a non-empty array while keeping later
+       * non-adjacent runs separate.
        *
        * **Details**
        *
@@ -16571,7 +16798,7 @@ export const intersperseAffixes: {
  * // [2, 5, 3, 6, 7]
  * ```
  *
- * @category Merging
+ * @category merging
  * @since 2.0.0
  */
 export const interleave: {
@@ -16599,7 +16826,7 @@ export const interleave: {
    * // [2, 5, 3, 6, 7]
    * ```
    *
-   * @category Merging
+   * @category merging
    * @since 2.0.0
    */
   <A2, E2, R2>(that: Stream<A2, E2, R2>): <A, E, R>(self: Stream<A, E, R>) => Stream<A2 | A, E2 | E, R2 | R>
@@ -16627,7 +16854,7 @@ export const interleave: {
    * // [2, 5, 3, 6, 7]
    * ```
    *
-   * @category Merging
+   * @category merging
    * @since 2.0.0
    */
   <A, E, R, A2, E2, R2>(self: Stream<A, E, R>, that: Stream<A2, E2, R2>): Stream<A | A2, E | E2, R | R2>
@@ -16670,7 +16897,7 @@ export const interleave: {
  * // [ 1, 2, 4, 3, 5 ]
  * ```
  *
- * @category Merging
+ * @category merging
  * @since 2.0.0
  */
 export const interleaveWith: {
@@ -16703,7 +16930,7 @@ export const interleaveWith: {
    * // [ 1, 2, 4, 3, 5 ]
    * ```
    *
-   * @category Merging
+   * @category merging
    * @since 2.0.0
    */
   <A2, E2, R2, E3, R3>(that: Stream<A2, E2, R2>, decider: Stream<boolean, E3, R3>): <A, E, R>(self: Stream<A, E, R>) => Stream<A2 | A, E2 | E3 | E, R2 | R3 | R>
@@ -16736,7 +16963,7 @@ export const interleaveWith: {
    * // [ 1, 2, 4, 3, 5 ]
    * ```
    *
-   * @category Merging
+   * @category merging
    * @since 2.0.0
    */
   <A, E, R, A2, E2, R2, E3, R3>(
@@ -16790,7 +17017,7 @@ export const interleaveWith: {
          * // [ 1, 2, 4, 3, 5 ]
          * ```
          *
-         * @category Merging
+         * @category merging
          * @since 2.0.0
          */
         retry>(retry);
@@ -16831,7 +17058,7 @@ export const interleaveWith: {
          * // [ 1, 2, 4, 3, 5 ]
          * ```
          *
-         * @category Merging
+         * @category merging
          * @since 2.0.0
          */
         retry>(retry);
@@ -16888,7 +17115,7 @@ export const interleaveWith: {
  * // => [1, 2]
  * ```
  *
- * @category Interruption
+ * @category interruption
  * @since 2.0.0
  */
 export const interruptWhen: {
@@ -16927,7 +17154,7 @@ export const interruptWhen: {
    * // => [1, 2]
    * ```
    *
-   * @category Interruption
+   * @category interruption
    * @since 2.0.0
    */
   <X, E2, R2>(effect: Effect.Effect<X, E2, R2>): <A, E, R>(self: Stream<A, E, R>) => Stream<A, E2 | E, R2 | R>
@@ -16966,7 +17193,7 @@ export const interruptWhen: {
    * // => [1, 2]
    * ```
    *
-   * @category Interruption
+   * @category interruption
    * @since 2.0.0
    */
   <A, E, R, X, E2, R2>(self: Stream<A, E, R>, effect: Effect.Effect<X, E2, R2>): Stream<A, E | E2, R | R2>
@@ -17013,7 +17240,7 @@ export const interruptWhen: {
  * // [1, 2]
  * ```
  *
- * @category Interruption
+ * @category interruption
  * @since 2.0.0
  */
 export const haltWhen: {
@@ -17054,7 +17281,7 @@ export const haltWhen: {
    * // [1, 2]
    * ```
    *
-   * @category Interruption
+   * @category interruption
    * @since 2.0.0
    */
   <X, E2, R2>(effect: Effect.Effect<X, E2, R2>): <A, E, R>(self: Stream<A, E, R>) => Stream<A, E2 | E, R2 | R>
@@ -17095,7 +17322,7 @@ export const haltWhen: {
    * // [1, 2]
    * ```
    *
-   * @category Interruption
+   * @category interruption
    * @since 2.0.0
    */
   <A, E, R, X, E2, R2>(self: Stream<A, E, R>, effect: Effect.Effect<X, E2, R2>): Stream<A, E | E2, R | R2>
@@ -18450,7 +18677,7 @@ export const withSpan: {
  * //=> [{ value: 1, next: 2 }, { value: 2, next: 3 }]
  * ```
  *
- * @category Do Notation
+ * @category do notation
  * @since 2.0.0
  */
 export const Do: Stream<{}> = succeed({})
@@ -18494,7 +18721,7 @@ export {
    * // [{ x: 2, y: 6 }]
    * ```
    *
-   * @category Do Notation
+   * @category do notation
    * @since 2.0.0
    */
   let_ as let
@@ -18519,7 +18746,7 @@ export {
  * // [{ a: 1, b: 2 }, { a: 2, b: 3 }]
  * ```
  *
- * @category Do Notation
+ * @category do notation
  * @since 2.0.0
  */
 export const bind: {
@@ -18542,7 +18769,7 @@ export const bind: {
    * // [{ a: 1, b: 2 }, { a: 2, b: 3 }]
    * ```
    *
-   * @category Do Notation
+   * @category do notation
    * @since 2.0.0
    */
   <N extends string, A, B, E2, R2>(
@@ -18572,7 +18799,7 @@ export const bind: {
    * // [{ a: 1, b: 2 }, { a: 2, b: 3 }]
    * ```
    *
-   * @category Do Notation
+   * @category do notation
    * @since 2.0.0
    */
   <A, E, R, N extends string, B, E2, R2>(
@@ -18617,7 +18844,7 @@ export const bind: {
  * // [{ value: 1, double: 2 }, { value: 2, double: 4 }]
  * ```
  *
- * @category Do Notation
+ * @category do notation
  * @since 2.0.0
  */
 export const bindEffect: {
@@ -18643,7 +18870,7 @@ export const bindEffect: {
    * // [{ value: 1, double: 2 }, { value: 2, double: 4 }]
    * ```
    *
-   * @category Do Notation
+   * @category do notation
    * @since 2.0.0
    */
   <N extends string, A, B, E2, R2>(
@@ -18677,7 +18904,7 @@ export const bindEffect: {
    * // [{ value: 1, double: 2 }, { value: 2, double: 4 }]
    * ```
    *
-   * @category Do Notation
+   * @category do notation
    * @since 2.0.0
    */
   <A, E, R, N extends string, B, E2, R2>(
@@ -18718,7 +18945,7 @@ export const bindEffect: {
  * // [{ value: 1 }, { value: 2 }, { value: 3 }]
  * ```
  *
- * @category Do Notation
+ * @category do notation
  * @since 2.0.0
  */
 export const bindTo: {
@@ -18738,7 +18965,7 @@ export const bindTo: {
    * // [{ value: 1 }, { value: 2 }, { value: 3 }]
    * ```
    *
-   * @category Do Notation
+   * @category do notation
    * @since 2.0.0
    */
   <N extends string>(name: N): <A, E, R>(self: Stream<A, E, R>) => Stream<{ [K in N]: A }, E, R>
@@ -18758,7 +18985,7 @@ export const bindTo: {
    * // [{ value: 1 }, { value: 2 }, { value: 3 }]
    * ```
    *
-   * @category Do Notation
+   * @category do notation
    * @since 2.0.0
    */
   <A, E, R, N extends string>(self: Stream<A, E, R>, name: N): Stream<{ [K in N]: A }, E, R>
@@ -19011,6 +19238,11 @@ export const runFold: {
 /**
  * Runs the stream and folds elements using an effectful reducer.
  *
+ * **When to use**
+ *
+ * Use when reducing stream elements needs Effects, services, or failures in the
+ * reducer.
+ *
  * **Example** (Effectfully folding stream values)
  *
  * ```ts
@@ -19036,6 +19268,11 @@ export const runFoldEffect: {
   /**
    * Runs the stream and folds elements using an effectful reducer.
    *
+   * **When to use**
+   *
+   * Use when reducing stream elements needs Effects, services, or failures in the
+   * reducer.
+   *
    * **Example** (Effectfully folding stream values)
    *
    * ```ts
@@ -19063,6 +19300,11 @@ export const runFoldEffect: {
   /**
    * Runs the stream and folds elements using an effectful reducer.
    *
+   * **When to use**
+   *
+   * Use when reducing stream elements needs Effects, services, or failures in the
+   * reducer.
+   *
    * **Example** (Effectfully folding stream values)
    *
    * ```ts
@@ -19579,6 +19821,11 @@ export const mkUint8Array = <E, R>(self: Stream<Uint8Array, E, R>): Effect.Effec
 /**
  * Converts the stream to a `ReadableStream` using the provided services.
  *
+ * **When to use**
+ *
+ * Use when bridging to Web Streams and you already have the `Context` required
+ * to run the stream outside an `Effect`.
+ *
  * **Details**
  *
  * See https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream.
@@ -19599,6 +19846,11 @@ export const toReadableStreamWith = dual<
   /**
    * Converts the stream to a `ReadableStream` using the provided services.
    *
+   * **When to use**
+   *
+   * Use when bridging to Web Streams and you already have the `Context` required
+   * to run the stream outside an `Effect`.
+   *
    * **Details**
    *
    * See https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream.
@@ -19622,6 +19874,11 @@ export const toReadableStreamWith = dual<
   /**
    * Converts the stream to a `ReadableStream` using the provided services.
    *
+   * **When to use**
+   *
+   * Use when bridging to Web Streams and you already have the `Context` required
+   * to run the stream outside an `Effect`.
+   *
    * **Details**
    *
    * See https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream.
@@ -19766,6 +20023,11 @@ export const toReadableStream: {
 /**
  * Creates an Effect that builds a ReadableStream from the stream.
  *
+ * **When to use**
+ *
+ * Use when bridging to Web Streams from inside an `Effect` so the required
+ * services can be captured from the current context.
+ *
  * **Details**
  *
  * See https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream.
@@ -19792,6 +20054,11 @@ export const toReadableStreamEffect: {
   /**
    * Creates an Effect that builds a ReadableStream from the stream.
    *
+   * **When to use**
+   *
+   * Use when bridging to Web Streams from inside an `Effect` so the required
+   * services can be captured from the current context.
+   *
    * **Details**
    *
    * See https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream.
@@ -19820,6 +20087,11 @@ export const toReadableStreamEffect: {
   /**
    * Creates an Effect that builds a ReadableStream from the stream.
    *
+   * **When to use**
+   *
+   * Use when bridging to Web Streams from inside an `Effect` so the required
+   * services can be captured from the current context.
+   *
    * **Details**
    *
    * See https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream.
@@ -19856,6 +20128,11 @@ export const toReadableStreamEffect: {
       Effect.context</**
        * Creates an Effect that builds a ReadableStream from the stream.
        *
+       * **When to use**
+       *
+       * Use when bridging to Web Streams from inside an `Effect` so the required
+       * services can be captured from the current context.
+       *
        * **Details**
        *
        * See https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream.
@@ -19886,6 +20163,11 @@ export const toReadableStreamEffect: {
 /**
  * Converts the stream to an `AsyncIterable` using the provided services.
  *
+ * **When to use**
+ *
+ * Use when converting outside an Effect and you already have the `Context`
+ * needed to run the stream.
+ *
  * **Example** (Converting to an AsyncIterable with services)
  *
  * ```ts
@@ -19913,6 +20195,11 @@ export const toAsyncIterableWith: {
   /**
    * Converts the stream to an `AsyncIterable` using the provided services.
    *
+   * **When to use**
+   *
+   * Use when converting outside an Effect and you already have the `Context`
+   * needed to run the stream.
+   *
    * **Example** (Converting to an AsyncIterable with services)
    *
    * ```ts
@@ -19940,6 +20227,11 @@ export const toAsyncIterableWith: {
   /**
    * Converts the stream to an `AsyncIterable` using the provided services.
    *
+   * **When to use**
+   *
+   * Use when converting outside an Effect and you already have the `Context`
+   * needed to run the stream.
+   *
    * **Example** (Converting to an AsyncIterable with services)
    *
    * ```ts
@@ -20007,6 +20299,11 @@ export const toAsyncIterableWith: {
 /**
  * Creates an effect that yields an `AsyncIterable` using the current services.
  *
+ * **When to use**
+ *
+ * Use when the `AsyncIterable` should be created inside Effect with the current
+ * context supplying the stream's services.
+ *
  * **Example** (Creating an AsyncIterable effect)
  *
  * ```ts