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

package/dist/Stream.d.ts

@@ -201,7 +201,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 {
@@ -250,7 +250,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;
@@ -267,7 +267,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;
@@ -287,7 +287,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 : never;
@@ -332,7 +332,7 @@ export declare const isStream: (u: unknown) => u is Stream<unknown, unknown, unk
  * // Output: 4096
  * ```
  *
- * @category Constants
+ * @category constants
  * @since 2.0.0
  */
 export declare const DefaultChunkSize: number;
@@ -416,7 +416,7 @@ export declare const fromEffect: <A, E, R>(effect: Effect.Effect<A, E, R>) => St
  * // Output: [ "Hello, World!" ]
  * ```
  *
- * @category Context
+ * @category context
  * @since 4.0.0
  */
 export declare const service: <I, S>(service: Context.Key<I, S>) => Stream<S, never, I>;
@@ -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)
  *
@@ -460,7 +460,7 @@ export declare const service: <I, S>(service: Context.Key<I, S>) => Stream<S, ne
  * // Output: [ "Hello, World!" ]
  * ```
  *
- * @category Context
+ * @category context
  * @since 4.0.0
  */
 export declare const serviceOption: <I, S>(service: Context.Key<I, S>) => Stream<Option.Option<S>>;
@@ -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
@@ -3442,7 +3488,7 @@ export declare const prepend: {
  * // Output: [ 1, 2, 3, 4 ]
  * ```
  *
- * @category Merging
+ * @category merging
  * @since 2.0.0
  */
 export declare const merge: {
@@ -3471,7 +3517,7 @@ export declare const merge: {
      * // Output: [ 1, 2, 3, 4 ]
      * ```
      *
-     * @category Merging
+     * @category merging
      * @since 2.0.0
      */
     <A2, E2, R2>(that: Stream<A2, E2, R2>, options?: {
@@ -3502,7 +3548,7 @@ export declare const merge: {
      * // Output: [ 1, 2, 3, 4 ]
      * ```
      *
-     * @category Merging
+     * @category merging
      * @since 2.0.0
      */
     <A, E, R, A2, E2, R2>(self: Stream<A, E, R>, that: Stream<A2, E2, R2>, options?: {
@@ -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
@@ -3536,13 +3587,18 @@ export declare const merge: {
  * // Output: [ 1, 2, 3 ]
  * ```
  *
- * @category Merging
+ * @category merging
  * @since 4.0.0
  */
 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
@@ -3567,13 +3623,18 @@ export declare 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
@@ -3598,7 +3659,7 @@ export declare 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>;
@@ -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
@@ -3634,7 +3701,7 @@ export declare const mergeEffect: {
  * // Output: [ "left:left", "right:right" ]
  * ```
  *
- * @category Merging
+ * @category merging
  * @since 4.0.0
  */
 export declare const mergeResult: {
@@ -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
@@ -3669,7 +3742,7 @@ export declare 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>;
@@ -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
@@ -3704,7 +3783,7 @@ export declare 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>;
@@ -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
@@ -3734,13 +3818,18 @@ export declare const mergeResult: {
  * // Output: [ 1, 2 ]
  * ```
  *
- * @category Merging
+ * @category merging
  * @since 2.0.0
  */
 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
@@ -3763,13 +3852,18 @@ export declare 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
@@ -3792,7 +3886,7 @@ export declare 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>;
@@ -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
@@ -3827,7 +3926,7 @@ export declare const mergeLeft: {
  * // Output: [ 1, 2 ]
  * ```
  *
- * @category Merging
+ * @category merging
  * @since 2.0.0
  */
 export declare const mergeRight: {
@@ -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
@@ -3861,7 +3965,7 @@ export declare 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>;
@@ -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
@@ -3895,7 +4004,7 @@ export declare 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>;
@@ -3938,7 +4047,7 @@ export declare 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 declare const mergeAll: {
@@ -3980,7 +4089,7 @@ export declare 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
      */
     (options: {
@@ -4025,7 +4134,7 @@ export declare 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>(streams: Iterable<Stream<A, E, R>>, options: {
@@ -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
@@ -5100,7 +5244,7 @@ export declare const zipLatestWith: {
  * // Output: [ 0, 1, 2 ]
  * ```
  *
- * @category Racing
+ * @category racing
  * @since 3.5.0
  */
 export declare const raceAll: <S extends ReadonlyArray<Stream<any, any, any>>>(...streams: S) => Stream<Success<S[number]>, Error<S[number]>, Services<S[number]>>;
@@ -5133,7 +5277,7 @@ export declare const raceAll: <S extends ReadonlyArray<Stream<any, any, any>>>(.
  * // Output: [ 0, 1, 2 ]
  * ```
  *
- * @category Racing
+ * @category racing
  * @since 3.7.0
  */
 export declare const race: {
@@ -5166,7 +5310,7 @@ export declare 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>;
@@ -5199,7 +5343,7 @@ export declare 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>;
@@ -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)
      *
@@ -9608,7 +9800,7 @@ export declare const split: {
  * // Output: [ "L:A", "R:1", "L:B", "R:2", "L:C", "R:3" ]
  * ```
  *
- * @category Merging
+ * @category merging
  * @since 2.0.0
  */
 export declare const combine: {
@@ -9645,7 +9837,7 @@ export declare 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>(that: Stream<A2, E2, R2>, s: LazyArg<S>, f: (s: S, pullLeft: Pull.Pull<A, E, void>, pullRight: Pull.Pull<A2, E2, void>) => Effect.Effect<readonly [A3, S], E3, R3>): <R>(self: Stream<A, E, R>) => Stream<A3, E3, R2 | R3 | R>;
@@ -9682,7 +9874,7 @@ export declare 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>(self: Stream<A, E, R>, that: Stream<A2, E2, R2>, s: LazyArg<S>, f: (s: S, pullLeft: Pull.Pull<A, E, void>, pullRight: Pull.Pull<A2, E2, void>) => Effect.Effect<readonly [A3, S], E3, R3>): Stream<A3, E3, R | R2 | R3>;
@@ -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**
      *
@@ -12570,7 +12792,7 @@ export declare const intersperseAffixes: {
  * // [2, 5, 3, 6, 7]
  * ```
  *
- * @category Merging
+ * @category merging
  * @since 2.0.0
  */
 export declare const interleave: {
@@ -12598,7 +12820,7 @@ export declare 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>;
@@ -12626,7 +12848,7 @@ export declare 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>;
@@ -12660,7 +12882,7 @@ export declare const interleave: {
  * // [ 1, 2, 4, 3, 5 ]
  * ```
  *
- * @category Merging
+ * @category merging
  * @since 2.0.0
  */
 export declare const interleaveWith: {
@@ -12693,7 +12915,7 @@ export declare 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>;
@@ -12726,7 +12948,7 @@ export declare const interleaveWith: {
      * // [ 1, 2, 4, 3, 5 ]
      * ```
      *
-     * @category Merging
+     * @category merging
      * @since 2.0.0
      */
     <A, E, R, A2, E2, R2, E3, R3>(self: Stream<A, E, R>, that: Stream<A2, E2, R2>, decider: Stream<boolean, E3, R3>): Stream<A | A2, E | E2 | E3, R | R2 | R3>;
@@ -12766,7 +12988,7 @@ export declare const interleaveWith: {
  * // => [1, 2]
  * ```
  *
- * @category Interruption
+ * @category interruption
  * @since 2.0.0
  */
 export declare const interruptWhen: {
@@ -12805,7 +13027,7 @@ export declare 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>;
@@ -12844,7 +13066,7 @@ export declare 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>;
@@ -12886,7 +13108,7 @@ export declare const interruptWhen: {
  * // [1, 2]
  * ```
  *
- * @category Interruption
+ * @category interruption
  * @since 2.0.0
  */
 export declare const haltWhen: {
@@ -12927,7 +13149,7 @@ export declare 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>;
@@ -12968,7 +13190,7 @@ export declare 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>;
@@ -14207,7 +14429,7 @@ export declare const withSpan: {
  * //=> [{ value: 1, next: 2 }, { value: 2, next: 3 }]
  * ```
  *
- * @category Do Notation
+ * @category do notation
  * @since 2.0.0
  */
 export declare const Do: Stream<{}>;
@@ -14242,7 +14464,7 @@ export {
  * // [{ x: 2, y: 6 }]
  * ```
  *
- * @category Do Notation
+ * @category do notation
  * @since 2.0.0
  */
 let_ as let };
@@ -14265,7 +14487,7 @@ let_ as let };
  * // [{ a: 1, b: 2 }, { a: 2, b: 3 }]
  * ```
  *
- * @category Do Notation
+ * @category do notation
  * @since 2.0.0
  */
 export declare const bind: {
@@ -14288,7 +14510,7 @@ export declare 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>(tag: Exclude<N, keyof A>, f: (_: NoInfer<A>) => Stream<B, E2, R2>, options?: {
@@ -14316,7 +14538,7 @@ export declare 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>(self: Stream<A, E, R>, tag: Exclude<N, keyof A>, f: (_: NoInfer<A>) => Stream<B, E2, R2>, options?: {
@@ -14348,7 +14570,7 @@ export declare const bind: {
  * // [{ value: 1, double: 2 }, { value: 2, double: 4 }]
  * ```
  *
- * @category Do Notation
+ * @category do notation
  * @since 2.0.0
  */
 export declare const bindEffect: {
@@ -14374,7 +14596,7 @@ export declare 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>(tag: Exclude<N, keyof A>, f: (_: NoInfer<A>) => Effect.Effect<B, E2, R2>, options?: {
@@ -14406,7 +14628,7 @@ export declare 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>(self: Stream<A, E, R>, tag: Exclude<N, keyof A>, f: (_: NoInfer<A>) => Effect.Effect<B, E2, R2>, options?: {
@@ -14433,7 +14655,7 @@ export declare const bindEffect: {
  * // [{ value: 1 }, { value: 2 }, { value: 3 }]
  * ```
  *
- * @category Do Notation
+ * @category do notation
  * @since 2.0.0
  */
 export declare const bindTo: {
@@ -14453,7 +14675,7 @@ export declare 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<{
@@ -14475,7 +14697,7 @@ export declare 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<{
@@ -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