effect 4.0.0-beta.74 → 4.0.0-beta.75

package/src/Stream.ts

@@ -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)
  *
@@ -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
@@ -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
@@ -4264,6 +4315,11 @@ 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
@@ -4295,6 +4351,11 @@ 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -4481,6 +4565,11 @@ 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
@@ -4510,6 +4599,11 @@ 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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)
    *
@@ -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**
        *
@@ -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