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

package/dist/Stream.d.ts

@@ -426,8 +426,8 @@ export declare const service: <I, S>(service: Context.Key<I, S>) => Stream<S, ne
  *
  * **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)
  *
@@ -683,8 +683,8 @@ export declare const toChannel: <A, E, R>(stream: Stream<A, E, R>) => Channel.Ch
  *
  * **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
@@ -1031,6 +1031,11 @@ export declare const fromIterable: <A>(iterable: Iterable<A>, options?: {
 /**
  * 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
@@ -1113,6 +1118,11 @@ export declare 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
@@ -1359,8 +1369,9 @@ export declare const fromSchedule: <O, E, R>(schedule: Schedule.Schedule<O, unkn
  *
  * **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)
  *
@@ -1887,6 +1898,11 @@ export declare 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
@@ -1923,6 +1939,11 @@ export declare 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
@@ -1962,6 +1983,11 @@ export declare 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
@@ -2002,6 +2028,11 @@ export declare 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
@@ -2034,6 +2065,11 @@ export declare const flattenEffect: <Arg extends Stream<Effect.Effect<any, any,
 /**
  * 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
@@ -2061,6 +2097,11 @@ export declare 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
@@ -2088,6 +2129,11 @@ export declare 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
@@ -3512,6 +3558,11 @@ export declare 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
@@ -3543,6 +3594,11 @@ export declare 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
@@ -3574,6 +3630,11 @@ export declare 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
@@ -3607,6 +3668,12 @@ export declare 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
@@ -3642,6 +3709,12 @@ export declare 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
@@ -3677,6 +3750,12 @@ export declare 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
@@ -3712,6 +3791,11 @@ export declare 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
@@ -3741,6 +3825,11 @@ export declare 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
@@ -3770,6 +3859,11 @@ export declare 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
@@ -3801,6 +3895,11 @@ export declare 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
@@ -3835,6 +3934,11 @@ export declare 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
@@ -3869,6 +3973,11 @@ export declare 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
@@ -4852,6 +4961,11 @@ export declare const zipWithPreviousAndNext: <A, E, R>(self: Stream<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
@@ -4885,6 +4999,11 @@ export declare 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
@@ -4914,6 +5033,11 @@ export declare 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
@@ -4943,6 +5067,11 @@ export declare 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
@@ -4974,6 +5103,11 @@ export declare 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
@@ -5008,6 +5142,11 @@ export declare 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
@@ -5042,6 +5181,11 @@ export declare 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
@@ -5645,8 +5789,8 @@ export declare 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**
  *
@@ -5668,8 +5812,8 @@ export declare 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**
      *
@@ -5697,8 +5841,8 @@ export declare 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**
      *
@@ -6768,8 +6912,8 @@ export declare 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)
  *
@@ -6803,8 +6947,8 @@ export declare 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)
      *
@@ -6838,8 +6982,8 @@ export declare 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)
      *
@@ -7021,7 +7165,11 @@ export declare 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)
  *
@@ -7068,7 +7216,11 @@ export declare 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)
      *
@@ -7115,7 +7267,11 @@ export declare 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)
      *
@@ -7474,7 +7630,7 @@ export declare 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**
@@ -7498,7 +7654,7 @@ export declare 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**
@@ -7522,7 +7678,7 @@ export declare 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**
@@ -7720,8 +7876,12 @@ export declare const orDie: <A, E, R>(self: Stream<A, E, R>) => Stream<A, never,
  * **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)
  *
@@ -7772,9 +7932,8 @@ export declare const ignore: <Arg extends Stream<any, any, any> | {
  *
  * **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)
  *
@@ -8315,6 +8474,11 @@ export declare 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
@@ -8339,6 +8503,11 @@ export declare 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
@@ -8365,6 +8534,11 @@ export declare 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
@@ -8582,6 +8756,11 @@ export declare 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
@@ -8606,6 +8785,11 @@ export declare 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
@@ -8630,6 +8814,11 @@ export declare 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
@@ -8796,9 +8985,10 @@ export declare 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)
  *
@@ -8825,9 +9015,10 @@ export declare 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)
      *
@@ -8854,9 +9045,10 @@ export declare 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)
      *
@@ -10014,6 +10206,11 @@ export declare const mapAccumArray: {
  * 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
@@ -10048,6 +10245,11 @@ export declare 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
@@ -10084,6 +10286,11 @@ export declare 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
@@ -10121,6 +10328,11 @@ export declare 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
@@ -10157,6 +10369,11 @@ export declare 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
@@ -10195,6 +10412,11 @@ export declare 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
@@ -11108,9 +11330,9 @@ export declare const groupByKey: {
  *
  * **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**
  *
@@ -11130,9 +11352,9 @@ export declare 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**
      *
@@ -11152,9 +11374,9 @@ export declare 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**
      *
@@ -14683,6 +14905,11 @@ export declare 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
@@ -14708,6 +14935,11 @@ export declare 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
@@ -14733,6 +14965,11 @@ export declare 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
@@ -15143,6 +15380,11 @@ export declare const mkUint8Array: <E, R>(self: Stream<Uint8Array, E, R>) => Eff
 /**
  * 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.
@@ -15232,6 +15474,11 @@ export declare 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.
@@ -15258,6 +15505,11 @@ export declare 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.
@@ -15286,6 +15538,11 @@ export declare 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.
@@ -15315,6 +15572,11 @@ export declare 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
@@ -15342,6 +15604,11 @@ export declare 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
@@ -15369,6 +15636,11 @@ export declare 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
@@ -15397,6 +15669,11 @@ export declare 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