effect 4.0.0-beta.71 → 4.0.0-beta.73

package/src/Stream.ts

@@ -141,7 +141,7 @@ import type * as Unify from "./Unify.ts"
 /**
  * String literal type used as the unique brand for `Stream` values.
  *
- * @category Type Identifiers
+ * @category type IDs
  * @since 4.0.0
  */
 export type TypeId = "~effect/Stream"
@@ -150,14 +150,14 @@ export type TypeId = "~effect/Stream"
  * Runtime identifier stored on `Stream` values and used by `isStream` to
  * recognize them.
  *
- * **When to use**
+ * **Details**
  *
- * Use when implementing low-level `Stream` integrations that need direct access
- * to the runtime brand checked by `isStream`.
+ * This marker is part of the runtime representation of `Stream` values. Prefer
+ * `isStream` when narrowing unknown values.
  *
  * @see {@link isStream} for the public guard that checks this identifier
  *
- * @category Type Identifiers
+ * @category type IDs
  * @since 4.0.0
  */
 export const TypeId: TypeId = "~effect/Stream"
@@ -412,8 +412,7 @@ export const fromChannel: <Arr extends Arr.NonEmptyReadonlyArray<any>, E, R>(
 ) => Stream<Arr extends Arr.NonEmptyReadonlyArray<infer A> ? A : never, E, R> = internal.fromChannel
 
 /**
- * Either emits the success value of this effect or terminates the stream
- * with the failure value of this effect.
+ * Creates a stream from an effect.
  *
  * **Example** (Creating a stream from an effect)
  *
@@ -474,6 +473,11 @@ export const service = <I, S>(service: Context.Key<I, S>): Stream<S, never, I> =
  * Optionally accesses a service from the context and emits the result as a
  * single element.
  *
+ * **When to use**
+ *
+ * Use to emit an optional dependency as a stream element without requiring that
+ * dependency to be present.
+ *
  * **Example** (Accessing an optional service as a stream)
  *
  * ```ts
@@ -683,7 +687,7 @@ export const fromPull = <A, E, R, EX, RX>(
 ): Stream<A, Pull.ExcludeDone<E> | EX, R | RX> => fromChannel(Channel.fromPull(pull))
 
 /**
- * Derive a stream by transforming its pull effect.
+ * Derives a stream by transforming its pull effect.
  *
  * **Example** (Transforming a pull effect)
  *
@@ -1705,9 +1709,17 @@ export const unfold = <S, A, E, R>(
   }))
 
 /**
- * Like `Stream.unfold`, but allows the emission of values to end one step further
- * than the unfolding of the state. This is useful for embedding paginated APIs,
- * hence the name.
+ * Creates a stream by repeatedly evaluating an effectful page function.
+ *
+ * **When to use**
+ *
+ * Use to consume paginated APIs where each step returns a batch of values
+ * together with an optional next state.
+ *
+ * **Details**
+ *
+ * This is similar to {@link unfold}, but each step can emit zero or more values
+ * and independently decide whether another state should be requested.
  *
  * **Example** (Paginating stream state)
  *
@@ -2371,7 +2383,7 @@ export const flattenEffect: <
   )
 
 /**
- * Effectfully maps over non-empty array chunks emitted by the stream.
+ * Maps over non-empty array chunks emitted by the stream effectfully.
  *
  * **Example** (Effectfully mapping stream chunks)
  *
@@ -2398,7 +2410,7 @@ export const flattenEffect: <
  */
 export const mapArrayEffect: {
   /**
-   * Effectfully maps over non-empty array chunks emitted by the stream.
+   * Maps over non-empty array chunks emitted by the stream effectfully.
    *
    * **Example** (Effectfully mapping stream chunks)
    *
@@ -2427,7 +2439,7 @@ export const mapArrayEffect: {
     f: (a: Arr.NonEmptyReadonlyArray<A>, i: number) => Effect.Effect<Arr.NonEmptyReadonlyArray<B>, E2, R2>
   ): <E, R>(self: Stream<A, E, R>) => Stream<B, E | E2, R | R2>
   /**
-   * Effectfully maps over non-empty array chunks emitted by the stream.
+   * Maps over non-empty array chunks emitted by the stream effectfully.
    *
    * **Example** (Effectfully mapping stream chunks)
    *
@@ -2751,8 +2763,7 @@ export const tapBoth: {
   ))
 
 /**
- * Sends all elements emitted by this stream to the specified sink in addition
- * to emitting them.
+ * Runs a sink for all stream elements while still emitting them downstream.
  *
  * **Example** (Tapping values with a sink)
  *
@@ -2783,8 +2794,7 @@ export const tapBoth: {
  */
 export const tapSink: {
   /**
-   * Sends all elements emitted by this stream to the specified sink in addition
-   * to emitting them.
+   * Runs a sink for all stream elements while still emitting them downstream.
    *
    * **Example** (Tapping values with a sink)
    *
@@ -2815,8 +2825,7 @@ export const tapSink: {
    */
   <A, E2, R2>(sink: Sink.Sink<unknown, A, unknown, E2, R2>): <E, R>(self: Stream<A, E, R>) => Stream<A, E2 | E, R2 | R>
   /**
-   * Sends all elements emitted by this stream to the specified sink in addition
-   * to emitting them.
+   * Runs a sink for all stream elements while still emitting them downstream.
    *
    * **Example** (Tapping values with a sink)
    *
@@ -3430,7 +3439,7 @@ export const repeat: {
 ): Stream<A, E | E2, R | R2> => fromChannel(Channel.repeat(self.channel, schedule)))
 
 /**
- * Spaces the stream's elements according to the provided `schedule`.
+ * Schedules the stream's elements according to the provided schedule.
  *
  * **Example** (Scheduling stream elements)
  *
@@ -3450,12 +3459,12 @@ export const repeat: {
  * // Output: [ 1, 2, 3 ]
  * ```
  *
- * @category Rate Limiting
+ * @category rate limiting
  * @since 2.0.0
  */
 export const schedule: {
   /**
-   * Spaces the stream's elements according to the provided `schedule`.
+   * Schedules the stream's elements according to the provided schedule.
    *
    * **Example** (Scheduling stream elements)
    *
@@ -3475,12 +3484,12 @@ export const schedule: {
    * // Output: [ 1, 2, 3 ]
    * ```
    *
-   * @category Rate Limiting
+   * @category rate limiting
    * @since 2.0.0
    */
   <X, E2, R2, A>(schedule: Schedule.Schedule<X, NoInfer<A>, E2, R2>): <E, R>(self: Stream<A, E, R>) => Stream<A, E | E2, R2 | R>
   /**
-   * Spaces the stream's elements according to the provided `schedule`.
+   * Schedules the stream's elements according to the provided schedule.
    *
    * **Example** (Scheduling stream elements)
    *
@@ -3500,7 +3509,7 @@ export const schedule: {
    * // Output: [ 1, 2, 3 ]
    * ```
    *
-   * @category Rate Limiting
+   * @category rate limiting
    * @since 2.0.0
    */
   <A, E, R, X, E2, R2>(self: Stream<A, E, R>, schedule: Schedule.Schedule<X, NoInfer<A>, E2, R2>): Stream<A, E | E2, R | R2>
@@ -3536,7 +3545,7 @@ export const schedule: {
  * // Output: [ 1 ]
  * ```
  *
- * @category Rate Limiting
+ * @category rate limiting
  * @since 2.0.0
  */
 export const timeout: {
@@ -3561,7 +3570,7 @@ export const timeout: {
    * // Output: [ 1 ]
    * ```
    *
-   * @category Rate Limiting
+   * @category rate limiting
    * @since 2.0.0
    */
   (duration: Duration.Input): <A, E, R>(self: Stream<A, E, R>) => Stream<A, E, R>
@@ -3586,7 +3595,7 @@ export const timeout: {
    * // Output: [ 1 ]
    * ```
    *
-   * @category Rate Limiting
+   * @category rate limiting
    * @since 2.0.0
    */
   <A, E, R>(self: Stream<A, E, R>, duration: Duration.Input): Stream<A, E, R>
@@ -3620,7 +3629,7 @@ export const timeout: {
  *
  * @see {@link timeout} for ending the stream instead of switching to a fallback stream
  *
- * @category Rate Limiting
+ * @category rate limiting
  * @since 4.0.0
  */
 export const timeoutOrElse: {
@@ -3645,7 +3654,7 @@ export const timeoutOrElse: {
    *
    * @see {@link timeout} for ending the stream instead of switching to a fallback stream
    *
-   * @category Rate Limiting
+   * @category rate limiting
    * @since 4.0.0
    */
   <B, E2, R2>(
@@ -3675,7 +3684,7 @@ export const timeoutOrElse: {
    *
    * @see {@link timeout} for ending the stream instead of switching to a fallback stream
    *
-   * @category Rate Limiting
+   * @category rate limiting
    * @since 4.0.0
    */
   <A, E, R, B, E2, R2>(
@@ -3882,7 +3891,7 @@ export const repeatElements: {
 export const forever = <A, E, R>(self: Stream<A, E, R>): Stream<A, E, R> => fromChannel(Channel.forever(self.channel))
 
 /**
- * Submerges the iterables emitted by this stream into the stream's structure.
+ * Flattens the iterables emitted by this stream into the stream's structure.
  *
  * **Example** (Flattening iterable values)
  *
@@ -6452,7 +6461,7 @@ export const filterMap: {
 )
 
 /**
- * Effectfully filters elements in a single pass.
+ * Filters elements in a single pass effectfully.
  *
  * **Example** (Effectfully filtering stream values)
  *
@@ -6475,7 +6484,7 @@ export const filterMap: {
  */
 export const filterEffect: {
   /**
-   * Effectfully filters elements in a single pass.
+   * Filters elements in a single pass effectfully.
    *
    * **Example** (Effectfully filtering stream values)
    *
@@ -6498,7 +6507,7 @@ export const filterEffect: {
    */
   <A, EX, RX>(predicate: (a: NoInfer<A>, i: number) => Effect.Effect<boolean, EX, RX>): <E, R>(self: Stream<A, E, R>) => Stream<A, E | EX, R | RX>
   /**
-   * Effectfully filters elements in a single pass.
+   * Filters elements in a single pass effectfully.
    *
    * **Example** (Effectfully filtering stream values)
    *
@@ -6532,7 +6541,7 @@ export const filterEffect: {
 )
 
 /**
- * Effectfully filters and maps elements in one pass using a `FilterEffect`.
+ * Filters and maps elements in one pass effectfully using a `FilterEffect`.
  *
  * **When to use**
  *
@@ -6553,7 +6562,7 @@ export const filterEffect: {
  */
 export const filterMapEffect: {
   /**
-   * Effectfully filters and maps elements in one pass using a `FilterEffect`.
+   * Filters and maps elements in one pass effectfully using a `FilterEffect`.
    *
    * **When to use**
    *
@@ -6574,7 +6583,7 @@ export const filterMapEffect: {
    */
   <A, B, X, EX, RX>(filter: Filter.FilterEffect<NoInfer<A>, B, X, EX, RX>): <E, R>(self: Stream<A, E, R>) => Stream<B, E | EX, R | RX>
   /**
-   * Effectfully filters and maps elements in one pass using a `FilterEffect`.
+   * Filters and maps elements in one pass effectfully using a `FilterEffect`.
    *
    * **When to use**
    *
@@ -7536,7 +7545,7 @@ export const peel: {
  * // Output: [ 1, 2, 3 ]
  * ```
  *
- * @category Rate Limiting
+ * @category rate limiting
  * @since 2.0.0
  */
 export const buffer: {
@@ -7568,7 +7577,7 @@ export const buffer: {
    * // Output: [ 1, 2, 3 ]
    * ```
    *
-   * @category Rate Limiting
+   * @category rate limiting
    * @since 2.0.0
    */
   (
@@ -7605,7 +7614,7 @@ export const buffer: {
    * // Output: [ 1, 2, 3 ]
    * ```
    *
-   * @category Rate Limiting
+   * @category rate limiting
    * @since 2.0.0
    */
   <A, E, R>(
@@ -7650,7 +7659,7 @@ export const buffer: {
  * // Output: [ 1, 2, 3, 4 ]
  * ```
  *
- * @category Rate Limiting
+ * @category rate limiting
  * @since 4.0.0
  */
 export const bufferArray: {
@@ -7681,7 +7690,7 @@ export const bufferArray: {
    * // Output: [ 1, 2, 3, 4 ]
    * ```
    *
-   * @category Rate Limiting
+   * @category rate limiting
    * @since 4.0.0
    */
   (
@@ -7717,7 +7726,7 @@ export const bufferArray: {
    * // Output: [ 1, 2, 3, 4 ]
    * ```
    *
-   * @category Rate Limiting
+   * @category rate limiting
    * @since 4.0.0
    */
   <A, E, R>(
@@ -7982,7 +7991,7 @@ export {
 }
 
 /**
- * Effectfully peeks at errors without changing the stream unless the tap fails.
+ * Peeks at errors effectfully without changing the stream unless the tap fails.
  *
  * **Example** (Effectfully peeking at errors)
  *
@@ -8011,7 +8020,7 @@ export {
  */
 export const tapError: {
   /**
-   * Effectfully peeks at errors without changing the stream unless the tap fails.
+   * Peeks at errors effectfully without changing the stream unless the tap fails.
    *
    * **Example** (Effectfully peeking at errors)
    *
@@ -8040,7 +8049,7 @@ export const tapError: {
    */
   <E, A2, E2, R2>(f: (error: E) => Effect.Effect<A2, E2, R2>): <A, R>(self: Stream<A, E, R>) => Stream<A, E | E2, R2 | R>
   /**
-   * Effectfully peeks at errors without changing the stream unless the tap fails.
+   * Peeks at errors effectfully without changing the stream unless the tap fails.
    *
    * **Example** (Effectfully peeking at errors)
    *
@@ -9824,7 +9833,7 @@ export const ignoreCause: <
   )
 
 /**
- * When the stream fails, retry it according to the given schedule.
+ * Retries the stream according to the given schedule when it fails.
  *
  * **Details**
  *
@@ -9859,7 +9868,7 @@ export const ignoreCause: <
  */
 export const retry: {
   /**
-   * When the stream fails, retry it according to the given schedule.
+   * Retries the stream according to the given schedule when it fails.
    *
    * **Details**
    *
@@ -9900,7 +9909,7 @@ export const retry: {
       ) => Schedule.Schedule<X, NoInfer<E>, E2, R2>)
   ): <A, R>(self: Stream<A, E, R>) => Stream<A, E | E2, R2 | R>
   /**
-   * When the stream fails, retry it according to the given schedule.
+   * Retries the stream according to the given schedule when it fails.
    *
    * **Details**
    *
@@ -9954,7 +9963,7 @@ export const retry: {
 )
 
 /**
- * Apply an `ExecutionPlan` to a stream, retrying with step-provided resources
+ * Applies an `ExecutionPlan` to a stream, retrying with step-provided resources
  * until it succeeds or the plan is exhausted.
  *
  * **Details**
@@ -9998,7 +10007,7 @@ export const retry: {
  */
 export const withExecutionPlan: {
   /**
-   * Apply an `ExecutionPlan` to a stream, retrying with step-provided resources
+   * Applies an `ExecutionPlan` to a stream, retrying with step-provided resources
    * until it succeeds or the plan is exhausted.
    *
    * **Details**
@@ -10045,7 +10054,7 @@ export const withExecutionPlan: {
     options?: { readonly preventFallbackOnPartialStream?: boolean | undefined }
   ): <A, E extends Input, R>(self: Stream<A, E, R>) => Stream<A, E | PolicyE, R2 | Exclude<R, Provides>>
   /**
-   * Apply an `ExecutionPlan` to a stream, retrying with step-provided resources
+   * Applies an `ExecutionPlan` to a stream, retrying with step-provided resources
    * until it succeeds or the plan is exhausted.
    *
    * **Details**
@@ -10122,7 +10131,7 @@ export const withExecutionPlan: {
       })
     )
     let lastError = Option.none</**
-     * Apply an `ExecutionPlan` to a stream, retrying with step-provided resources
+     * Applies an `ExecutionPlan` to a stream, retrying with step-provided resources
      * until it succeeds or the plan is exhausted.
      *
      * **Details**
@@ -10522,7 +10531,7 @@ export const takeUntil: {
 )
 
 /**
- * Effectful predicate version of `takeUntil`.
+ * Takes stream elements until an effectful predicate returns `true`.
  *
  * **Example** (Taking until an effectful predicate matches)
  *
@@ -10546,7 +10555,7 @@ export const takeUntil: {
  */
 export const takeUntilEffect: {
   /**
-   * Effectful predicate version of `takeUntil`.
+   * Takes stream elements until an effectful predicate returns `true`.
    *
    * **Example** (Taking until an effectful predicate matches)
    *
@@ -10575,7 +10584,7 @@ export const takeUntilEffect: {
     }
   ): <E, R>(self: Stream<A, E, R>) => Stream<A, E2 | E, R2 | R>
   /**
-   * Effectful predicate version of `takeUntil`.
+   * Takes stream elements until an effectful predicate returns `true`.
    *
    * **Example** (Taking until an effectful predicate matches)
    *
@@ -11651,7 +11660,7 @@ export const dropRight: {
  * // Output: [ [ 1, 2 ], [ 3, 4 ] ]
  * ```
  *
- * @category Grouping
+ * @category grouping
  * @since 2.0.0
  */
 export const chunks = <A, E, R>(self: Stream<A, E, R>): Stream<Arr.NonEmptyReadonlyArray<A>, E, R> =>
@@ -11661,7 +11670,7 @@ export const chunks = <A, E, R>(self: Stream<A, E, R>): Stream<Arr.NonEmptyReado
   )
 
 /**
- * Re-chunks the stream into arrays of the specified size, preserving element order.
+ * Groups the stream into arrays of the specified size, preserving element order.
  *
  * **Details**
  *
@@ -11685,12 +11694,12 @@ export const chunks = <A, E, R>(self: Stream<A, E, R>): Stream<Arr.NonEmptyReado
  * // Output: [ [ 1, 2 ], [ 3, 4 ], [ 5 ] ]
  * ```
  *
- * @category Grouping
+ * @category grouping
  * @since 2.0.0
  */
 export const rechunk: {
   /**
-   * Re-chunks the stream into arrays of the specified size, preserving element order.
+   * Groups the stream into arrays of the specified size, preserving element order.
    *
    * **Details**
    *
@@ -11714,12 +11723,12 @@ export const rechunk: {
    * // Output: [ [ 1, 2 ], [ 3, 4 ], [ 5 ] ]
    * ```
    *
-   * @category Grouping
+   * @category grouping
    * @since 2.0.0
    */
   (size: number): <A, E, R>(self: Stream<A, E, R>) => Stream<A, E, R>
   /**
-   * Re-chunks the stream into arrays of the specified size, preserving element order.
+   * Groups the stream into arrays of the specified size, preserving element order.
    *
    * **Details**
    *
@@ -11743,7 +11752,7 @@ export const rechunk: {
    * // Output: [ [ 1, 2 ], [ 3, 4 ], [ 5 ] ]
    * ```
    *
-   * @category Grouping
+   * @category grouping
    * @since 2.0.0
    */
   <A, E, R>(self: Stream<A, E, R>, size: number): Stream<A, E, R>
@@ -11752,7 +11761,7 @@ export const rechunk: {
   return transformPull(self, (pull, _scope) =>
     Effect.sync(() => {
       let chunk = Arr.empty</**
-       * Re-chunks the stream into arrays of the specified size, preserving element order.
+       * Groups the stream into arrays of the specified size, preserving element order.
        *
        * **Details**
        *
@@ -11776,7 +11785,7 @@ export const rechunk: {
        * // Output: [ [ 1, 2 ], [ 3, 4 ], [ 5 ] ]
        * ```
        *
-       * @category Grouping
+       * @category grouping
        * @since 2.0.0
        */
       A>() as Arr.NonEmptyArray<A>
@@ -11840,7 +11849,7 @@ export const rechunk: {
  * // Output: [ [1, 2], [2, 3], [3, 4], [4, 5] ]
  * ```
  *
- * @category Grouping
+ * @category grouping
  * @since 2.0.0
  */
 export const sliding: {
@@ -11863,7 +11872,7 @@ export const sliding: {
    * // Output: [ [1, 2], [2, 3], [3, 4], [4, 5] ]
    * ```
    *
-   * @category Grouping
+   * @category grouping
    * @since 2.0.0
    */
   (chunkSize: number): <A, E, R>(self: Stream<A, E, R>) => Stream<Arr.NonEmptyReadonlyArray<A>, E, R>
@@ -11886,7 +11895,7 @@ export const sliding: {
    * // Output: [ [1, 2], [2, 3], [3, 4], [4, 5] ]
    * ```
    *
-   * @category Grouping
+   * @category grouping
    * @since 2.0.0
    */
   <A, E, R>(self: Stream<A, E, R>, chunkSize: number): Stream<Arr.NonEmptyReadonlyArray<A>, E, R>
@@ -11916,7 +11925,7 @@ export const sliding: {
  * // Output: [ [ 1, 2, 3 ], [ 3, 4, 5 ] ]
  * ```
  *
- * @category Grouping
+ * @category grouping
  * @since 2.0.0
  */
 export const slidingSize: {
@@ -11940,7 +11949,7 @@ export const slidingSize: {
    * // Output: [ [ 1, 2, 3 ], [ 3, 4, 5 ] ]
    * ```
    *
-   * @category Grouping
+   * @category grouping
    * @since 2.0.0
    */
   (chunkSize: number, stepSize: number): <A, E, R>(self: Stream<A, E, R>) => Stream<Arr.NonEmptyReadonlyArray<A>, E, R>
@@ -11964,7 +11973,7 @@ export const slidingSize: {
    * // Output: [ [ 1, 2, 3 ], [ 3, 4, 5 ] ]
    * ```
    *
-   * @category Grouping
+   * @category grouping
    * @since 2.0.0
    */
   <A, E, R>(self: Stream<A, E, R>, chunkSize: number, stepSize: number): Stream<Arr.NonEmptyReadonlyArray<A>, E, R>
@@ -11994,7 +12003,7 @@ export const slidingSize: {
          * // Output: [ [ 1, 2, 3 ], [ 3, 4, 5 ] ]
          * ```
          *
-         * @category Grouping
+         * @category grouping
          * @since 2.0.0
          */
         A>()
@@ -12058,7 +12067,7 @@ export const slidingSize: {
  * // Output: [ [1, 2, 3], [5, 6, 7], [9] ]
  * ```
  *
- * @category Grouping
+ * @category grouping
  * @since 2.0.0
  */
 export const split: {
@@ -12086,7 +12095,7 @@ export const split: {
    * // Output: [ [1, 2, 3], [5, 6, 7], [9] ]
    * ```
    *
-   * @category Grouping
+   * @category grouping
    * @since 2.0.0
    */
   <A, B extends A>(refinement: Refinement<NoInfer<A>, B>): <E, R>(self: Stream<A, E, R>) => Stream<Arr.NonEmptyReadonlyArray<Exclude<A, B>>, E, R>
@@ -12114,7 +12123,7 @@ export const split: {
    * // Output: [ [1, 2, 3], [5, 6, 7], [9] ]
    * ```
    *
-   * @category Grouping
+   * @category grouping
    * @since 2.0.0
    */
   <A>(predicate: Predicate<NoInfer<A>>): <E, R>(self: Stream<A, E, R>) => Stream<Arr.NonEmptyReadonlyArray<A>, E, R>
@@ -12142,7 +12151,7 @@ export const split: {
    * // Output: [ [1, 2, 3], [5, 6, 7], [9] ]
    * ```
    *
-   * @category Grouping
+   * @category grouping
    * @since 2.0.0
    */
   <A, E, R, B extends A>(self: Stream<A, E, R>, refinement: Refinement<A, B>): Stream<Arr.NonEmptyReadonlyArray<Exclude<A, B>>, E, R>
@@ -12170,7 +12179,7 @@ export const split: {
    * // Output: [ [1, 2, 3], [5, 6, 7], [9] ]
    * ```
    *
-   * @category Grouping
+   * @category grouping
    * @since 2.0.0
    */
   <A, E, R>(self: Stream<A, E, R>, predicate: Predicate<A>): Stream<Arr.NonEmptyReadonlyArray<A>, E, R>
@@ -12203,7 +12212,7 @@ export const split: {
      * // Output: [ [1, 2, 3], [5, 6, 7], [9] ]
      * ```
      *
-     * @category Grouping
+     * @category grouping
      * @since 2.0.0
      */
     Arr.NonEmptyReadonlyArray<A>>()
@@ -12373,11 +12382,18 @@ export const combine: {
   ))
 
 /**
- * Combines the arrays (chunks) from this stream and the specified stream by
- * repeatedly applying the function `f` to extract an array using both sides and
- * conceptually "offer" it to the destination stream. `f` can maintain some
- * internal state to control the combining process, with the initial state
- * being specified by `s`.
+ * Combines two streams chunk-by-chunk with a stateful pull function.
+ *
+ * **When to use**
+ *
+ * Use to coordinate pulling chunks from two streams when each emitted chunk
+ * depends on both sides and local state.
+ *
+ * **Details**
+ *
+ * The combining function receives the current state and pull functions for the
+ * left and right streams. It returns the next non-empty chunk together with the
+ * next state.
  *
  * **Example** (Combining stream chunks with state)
  *
@@ -12410,11 +12426,18 @@ export const combine: {
  */
 export const combineArray: {
   /**
-   * Combines the arrays (chunks) from this stream and the specified stream by
-   * repeatedly applying the function `f` to extract an array using both sides and
-   * conceptually "offer" it to the destination stream. `f` can maintain some
-   * internal state to control the combining process, with the initial state
-   * being specified by `s`.
+   * Combines two streams chunk-by-chunk with a stateful pull function.
+   *
+   * **When to use**
+   *
+   * Use to coordinate pulling chunks from two streams when each emitted chunk
+   * depends on both sides and local state.
+   *
+   * **Details**
+   *
+   * The combining function receives the current state and pull functions for the
+   * left and right streams. It returns the next non-empty chunk together with the
+   * next state.
    *
    * **Example** (Combining stream chunks with state)
    *
@@ -12455,11 +12478,18 @@ export const combineArray: {
     ) => Effect.Effect<readonly [Arr.NonEmptyReadonlyArray<A3>, S], E3, R3>
   ): <R>(self: Stream<A, E, R>) => Stream<A3, Pull.ExcludeDone<E3>, R2 | R3 | R>
   /**
-   * Combines the arrays (chunks) from this stream and the specified stream by
-   * repeatedly applying the function `f` to extract an array using both sides and
-   * conceptually "offer" it to the destination stream. `f` can maintain some
-   * internal state to control the combining process, with the initial state
-   * being specified by `s`.
+   * Combines two streams chunk-by-chunk with a stateful pull function.
+   *
+   * **When to use**
+   *
+   * Use to coordinate pulling chunks from two streams when each emitted chunk
+   * depends on both sides and local state.
+   *
+   * **Details**
+   *
+   * The combining function receives the current state and pull functions for the
+   * left and right streams. It returns the next non-empty chunk together with the
+   * next state.
    *
    * **Example** (Combining stream chunks with state)
    *
@@ -12518,7 +12548,7 @@ export const combineArray: {
   )))
 
 /**
- * Statefully maps elements, emitting zero or more outputs per input.
+ * Maps elements statefully, emitting zero or more outputs per input.
  *
  * **Example** (Statefully mapping stream values)
  *
@@ -12546,7 +12576,7 @@ export const combineArray: {
  */
 export const mapAccum: {
   /**
-   * Statefully maps elements, emitting zero or more outputs per input.
+   * Maps elements statefully, emitting zero or more outputs per input.
    *
    * **Example** (Statefully mapping stream values)
    *
@@ -12580,7 +12610,7 @@ export const mapAccum: {
     }
   ): <E, R>(self: Stream<A, E, R>) => Stream<B, E, R>
   /**
-   * Statefully maps elements, emitting zero or more outputs per input.
+   * Maps elements statefully, emitting zero or more outputs per input.
    *
    * **Example** (Statefully mapping stream values)
    *
@@ -12627,7 +12657,7 @@ export const mapAccum: {
     initial,
     (state, arr) => {
       const acc = Arr.empty</**
-       * Statefully maps elements, emitting zero or more outputs per input.
+       * Maps elements statefully, emitting zero or more outputs per input.
        *
        * **Example** (Statefully mapping stream values)
        *
@@ -12672,7 +12702,7 @@ export const mapAccum: {
   )))
 
 /**
- * Statefully maps over non-empty chunk arrays, emitting zero or more values per chunk.
+ * Maps over non-empty chunk arrays statefully, emitting zero or more values per chunk.
  *
  * **Details**
  *
@@ -12704,7 +12734,7 @@ export const mapAccum: {
  */
 export const mapAccumArray: {
   /**
-   * Statefully maps over non-empty chunk arrays, emitting zero or more values per chunk.
+   * Maps over non-empty chunk arrays statefully, emitting zero or more values per chunk.
    *
    * **Details**
    *
@@ -12742,7 +12772,7 @@ export const mapAccumArray: {
     }
   ): <E, R>(self: Stream<A, E, R>) => Stream<B, E, R>
   /**
-   * Statefully maps over non-empty chunk arrays, emitting zero or more values per chunk.
+   * Maps over non-empty chunk arrays statefully, emitting zero or more values per chunk.
    *
    * **Details**
    *
@@ -12809,7 +12839,7 @@ export const mapAccumArray: {
 const emptyArr = Arr.empty<never>()
 
 /**
- * Statefully and effectfully maps each element, emitting zero or more output
+ * Maps each element statefully and effectfully, emitting zero or more output
  * values per input.
  *
  * **Details**
@@ -12843,7 +12873,7 @@ const emptyArr = Arr.empty<never>()
  */
 export const mapAccumEffect: {
   /**
-   * Statefully and effectfully maps each element, emitting zero or more output
+   * Maps each element statefully and effectfully, emitting zero or more output
    * values per input.
    *
    * **Details**
@@ -12883,7 +12913,7 @@ export const mapAccumEffect: {
     }
   ): <E, R>(self: Stream<A, E, R>) => Stream<B, E | E2, R | R2>
   /**
-   * Statefully and effectfully maps each element, emitting zero or more output
+   * Maps each element statefully and effectfully, emitting zero or more output
    * values per input.
    *
    * **Details**
@@ -12941,7 +12971,7 @@ export const mapAccumEffect: {
           ([state, values]) => [
             state,
             Arr.isReadonlyArrayNonEmpty(values) ? Arr.of(values) : Arr.empty</**
-             * Statefully and effectfully maps each element, emitting zero or more output
+             * Maps each element statefully and effectfully, emitting zero or more output
              * values per input.
              *
              * **Details**
@@ -12989,7 +13019,7 @@ export const mapAccumEffect: {
   ))
 
 /**
- * Statefully and effectfully maps each non-empty input chunk, emitting zero or
+ * Maps each non-empty input chunk statefully and effectfully, emitting zero or
  * more output values per chunk.
  *
  * **Details**
@@ -13025,7 +13055,7 @@ export const mapAccumEffect: {
  */
 export const mapAccumArrayEffect: {
   /**
-   * Statefully and effectfully maps each non-empty input chunk, emitting zero or
+   * Maps each non-empty input chunk statefully and effectfully, emitting zero or
    * more output values per chunk.
    *
    * **Details**
@@ -13067,7 +13097,7 @@ export const mapAccumArrayEffect: {
     }
   ): <E, R>(self: Stream<A, E, R>) => Stream<B, E | E2, R | R2>
   /**
-   * Statefully and effectfully maps each non-empty input chunk, emitting zero or
+   * Maps each non-empty input chunk statefully and effectfully, emitting zero or
    * more output values per chunk.
    *
    * **Details**
@@ -13257,7 +13287,7 @@ export const scan: {
   }))
 
 /**
- * Effectfully accumulates state and emits the initial state plus each accumulated state.
+ * Accumulates state effectfully and emits the initial state plus each accumulated state.
  *
  * **Example** (Effectfully scanning stream state)
  *
@@ -13279,7 +13309,7 @@ export const scan: {
  */
 export const scanEffect: {
   /**
-   * Effectfully accumulates state and emits the initial state plus each accumulated state.
+   * Accumulates state effectfully and emits the initial state plus each accumulated state.
    *
    * **Example** (Effectfully scanning stream state)
    *
@@ -13301,7 +13331,7 @@ export const scanEffect: {
    */
   <S, A, E2, R2>(initial: S, f: (s: S, a: A) => Effect.Effect<S, E2, R2>): <E, R>(self: Stream<A, E, R>) => Stream<S, E | E2, R | R2>
   /**
-   * Effectfully accumulates state and emits the initial state plus each accumulated state.
+   * Accumulates state effectfully and emits the initial state plus each accumulated state.
    *
    * **Example** (Effectfully scanning stream state)
    *
@@ -13359,7 +13389,7 @@ export const scanEffect: {
  * })
  * ```
  *
- * @category Rate Limiting
+ * @category rate limiting
  * @since 2.0.0
  */
 export const debounce: {
@@ -13384,7 +13414,7 @@ export const debounce: {
    * })
    * ```
    *
-   * @category Rate Limiting
+   * @category rate limiting
    * @since 2.0.0
    */
   (duration: Duration.Input): <A, E, R>(self: Stream<A, E, R>) => Stream<A, E, R>
@@ -13409,7 +13439,7 @@ export const debounce: {
    * })
    * ```
    *
-   * @category Rate Limiting
+   * @category rate limiting
    * @since 2.0.0
    */
   <A, E, R>(self: Stream<A, E, R>, duration: Duration.Input): Stream<A, E, R>
@@ -13484,13 +13514,17 @@ export const debounce: {
 )
 
 /**
- * Delays the arrays of this stream according to the given bandwidth
- * parameters using the token bucket algorithm. Allows for burst processing by
- * allowing the bucket to accumulate tokens up to a `units + burst` threshold.
- * The weight of each array is determined by the effectful `cost` function.
+ * Rate-limits stream chunks with an effectful cost function.
+ *
+ * **When to use**
+ *
+ * Use to throttle chunks when computing each chunk's cost requires an effect.
  *
  * **Details**
  *
+ * Uses a token bucket. The bucket can accumulate up to `units + burst` tokens,
+ * and each chunk consumes the cost returned by the effectful `cost` function.
+ *
  * If using the "enforce" strategy, arrays that do not meet the bandwidth
  * constraints are dropped. If using the "shape" strategy, arrays are delayed
  * until they can be emitted without exceeding the bandwidth constraints.
@@ -13519,18 +13553,22 @@ export const debounce: {
  * // Output: [0, 1, 2, 3, 4, 5]
  * ```
  *
- * @category Rate Limiting
+ * @category rate limiting
  * @since 2.0.0
  */
 export const throttleEffect: {
   /**
-   * Delays the arrays of this stream according to the given bandwidth
-   * parameters using the token bucket algorithm. Allows for burst processing by
-   * allowing the bucket to accumulate tokens up to a `units + burst` threshold.
-   * The weight of each array is determined by the effectful `cost` function.
+   * Rate-limits stream chunks with an effectful cost function.
+   *
+   * **When to use**
+   *
+   * Use to throttle chunks when computing each chunk's cost requires an effect.
    *
    * **Details**
    *
+   * Uses a token bucket. The bucket can accumulate up to `units + burst` tokens,
+   * and each chunk consumes the cost returned by the effectful `cost` function.
+   *
    * If using the "enforce" strategy, arrays that do not meet the bandwidth
    * constraints are dropped. If using the "shape" strategy, arrays are delayed
    * until they can be emitted without exceeding the bandwidth constraints.
@@ -13559,7 +13597,7 @@ export const throttleEffect: {
    * // Output: [0, 1, 2, 3, 4, 5]
    * ```
    *
-   * @category Rate Limiting
+   * @category rate limiting
    * @since 2.0.0
    */
   <A, E2, R2>(
@@ -13572,13 +13610,17 @@ export const throttleEffect: {
     }
   ): <E, R>(self: Stream<A, E, R>) => Stream<A, E2 | E, R2 | R>
   /**
-   * Delays the arrays of this stream according to the given bandwidth
-   * parameters using the token bucket algorithm. Allows for burst processing by
-   * allowing the bucket to accumulate tokens up to a `units + burst` threshold.
-   * The weight of each array is determined by the effectful `cost` function.
+   * Rate-limits stream chunks with an effectful cost function.
+   *
+   * **When to use**
+   *
+   * Use to throttle chunks when computing each chunk's cost requires an effect.
    *
    * **Details**
    *
+   * Uses a token bucket. The bucket can accumulate up to `units + burst` tokens,
+   * and each chunk consumes the cost returned by the effectful `cost` function.
+   *
    * If using the "enforce" strategy, arrays that do not meet the bandwidth
    * constraints are dropped. If using the "shape" strategy, arrays are delayed
    * until they can be emitted without exceeding the bandwidth constraints.
@@ -13607,7 +13649,7 @@ export const throttleEffect: {
    * // Output: [0, 1, 2, 3, 4, 5]
    * ```
    *
-   * @category Rate Limiting
+   * @category rate limiting
    * @since 2.0.0
    */
   <A, E, R, E2, R2>(
@@ -13724,12 +13766,17 @@ const throttleShapeEffect = <A, E, R, E2, R2>(
     }))
 
 /**
- * Delays the arrays of this stream using a token bucket and a per-array cost.
- * Allows bursts by letting the bucket accumulate up to a `units + burst`
- * threshold. The weight of each array is determined by the `cost` function.
+ * Rate-limits stream chunks with a synchronous cost function.
+ *
+ * **When to use**
+ *
+ * Use to throttle chunks when each chunk's cost can be computed synchronously.
  *
  * **Details**
  *
+ * Uses a token bucket. The bucket can accumulate up to `units + burst` tokens,
+ * and each chunk consumes the cost returned by `cost`.
+ *
  * If using the "enforce" strategy, arrays that do not meet the bandwidth
  * constraints are dropped. If using the "shape" strategy, arrays are delayed
  * until they can be emitted without exceeding the bandwidth constraints.
@@ -13758,17 +13805,22 @@ const throttleShapeEffect = <A, E, R, E2, R2>(
  * })
  * ```
  *
- * @category Rate Limiting
+ * @category rate limiting
  * @since 2.0.0
  */
 export const throttle: {
   /**
-   * Delays the arrays of this stream using a token bucket and a per-array cost.
-   * Allows bursts by letting the bucket accumulate up to a `units + burst`
-   * threshold. The weight of each array is determined by the `cost` function.
+   * Rate-limits stream chunks with a synchronous cost function.
+   *
+   * **When to use**
+   *
+   * Use to throttle chunks when each chunk's cost can be computed synchronously.
    *
    * **Details**
    *
+   * Uses a token bucket. The bucket can accumulate up to `units + burst` tokens,
+   * and each chunk consumes the cost returned by `cost`.
+   *
    * If using the "enforce" strategy, arrays that do not meet the bandwidth
    * constraints are dropped. If using the "shape" strategy, arrays are delayed
    * until they can be emitted without exceeding the bandwidth constraints.
@@ -13797,7 +13849,7 @@ export const throttle: {
    * })
    * ```
    *
-   * @category Rate Limiting
+   * @category rate limiting
    * @since 2.0.0
    */
   <A>(
@@ -13810,12 +13862,17 @@ export const throttle: {
     }
   ): <E, R>(self: Stream<A, E, R>) => Stream<A, E, R>
   /**
-   * Delays the arrays of this stream using a token bucket and a per-array cost.
-   * Allows bursts by letting the bucket accumulate up to a `units + burst`
-   * threshold. The weight of each array is determined by the `cost` function.
+   * Rate-limits stream chunks with a synchronous cost function.
+   *
+   * **When to use**
+   *
+   * Use to throttle chunks when each chunk's cost can be computed synchronously.
    *
    * **Details**
    *
+   * Uses a token bucket. The bucket can accumulate up to `units + burst` tokens,
+   * and each chunk consumes the cost returned by `cost`.
+   *
    * If using the "enforce" strategy, arrays that do not meet the bandwidth
    * constraints are dropped. If using the "shape" strategy, arrays are delayed
    * until they can be emitted without exceeding the bandwidth constraints.
@@ -13844,7 +13901,7 @@ export const throttle: {
    * })
    * ```
    *
-   * @category Rate Limiting
+   * @category rate limiting
    * @since 2.0.0
    */
   <A, E, R>(
@@ -13899,7 +13956,7 @@ export const throttle: {
  * // Output: [ [ 1, 2, 3 ], [ 4, 5, 6 ], [ 7, 8 ] ]
  * ```
  *
- * @category Grouping
+ * @category grouping
  * @since 2.0.0
  */
 export const grouped: {
@@ -13927,7 +13984,7 @@ export const grouped: {
    * // Output: [ [ 1, 2, 3 ], [ 4, 5, 6 ], [ 7, 8 ] ]
    * ```
    *
-   * @category Grouping
+   * @category grouping
    * @since 2.0.0
    */
   (n: number): <A, E, R>(self: Stream<A, E, R>) => Stream<Arr.NonEmptyReadonlyArray<A>, E, R>
@@ -13955,7 +14012,7 @@ export const grouped: {
    * // Output: [ [ 1, 2, 3 ], [ 4, 5, 6 ], [ 7, 8 ] ]
    * ```
    *
-   * @category Grouping
+   * @category grouping
    * @since 2.0.0
    */
   <A, E, R>(self: Stream<A, E, R>, n: number): Stream<Arr.NonEmptyReadonlyArray<A>, E, R>
@@ -13985,7 +14042,7 @@ export const grouped: {
  * // Output: [ [ 1, 2 ], [ 3 ] ]
  * ```
  *
- * @category Grouping
+ * @category grouping
  * @since 2.0.0
  */
 export const groupedWithin: {
@@ -14010,7 +14067,7 @@ export const groupedWithin: {
    * // Output: [ [ 1, 2 ], [ 3 ] ]
    * ```
    *
-   * @category Grouping
+   * @category grouping
    * @since 2.0.0
    */
   (chunkSize: number, duration: Duration.Input): <A, E, R>(self: Stream<A, E, R>) => Stream<Array<A>, E, R>
@@ -14035,7 +14092,7 @@ export const groupedWithin: {
    * // Output: [ [ 1, 2 ], [ 3 ] ]
    * ```
    *
-   * @category Grouping
+   * @category grouping
    * @since 2.0.0
    */
   <A, E, R>(self: Stream<A, E, R>, chunkSize: number, duration: Duration.Input): Stream<Array<A>, E, R>
@@ -14079,7 +14136,7 @@ export const groupedWithin: {
  * // Output: [ [ "odd", [ 1, 3, 5 ] ], [ "even", [ 2, 4 ] ] ]
  * ```
  *
- * @category Grouping
+ * @category grouping
  * @since 2.0.0
  */
 export const groupBy: {
@@ -14112,7 +14169,7 @@ export const groupBy: {
    * // Output: [ [ "odd", [ 1, 3, 5 ] ], [ "even", [ 2, 4 ] ] ]
    * ```
    *
-   * @category Grouping
+   * @category grouping
    * @since 2.0.0
    */
   <A, K, V, E2, R2>(
@@ -14151,7 +14208,7 @@ export const groupBy: {
    * // Output: [ [ "odd", [ 1, 3, 5 ] ], [ "even", [ 2, 4 ] ] ]
    * ```
    *
-   * @category Grouping
+   * @category grouping
    * @since 2.0.0
    */
   <A, E, R, K, V, E2, R2>(
@@ -14213,7 +14270,7 @@ export const groupBy: {
  * // Output: [ [ "odd", [ 1, 3, 5 ] ], [ "even", [ 2, 4 ] ] ]
  * ```
  *
- * @category Grouping
+ * @category grouping
  * @since 2.0.0
  */
 export const groupByKey: {
@@ -14244,7 +14301,7 @@ export const groupByKey: {
    * // Output: [ [ "odd", [ 1, 3, 5 ] ], [ "even", [ 2, 4 ] ] ]
    * ```
    *
-   * @category Grouping
+   * @category grouping
    * @since 2.0.0
    */
   <A, K>(
@@ -14281,7 +14338,7 @@ export const groupByKey: {
    * // Output: [ [ "odd", [ 1, 3, 5 ] ], [ "even", [ 2, 4 ] ] ]
    * ```
    *
-   * @category Grouping
+   * @category grouping
    * @since 2.0.0
    */
   <A, E, R, K>(
@@ -14328,7 +14385,7 @@ export const groupByKey: {
      * // Output: [ [ "odd", [ 1, 3, 5 ] ], [ "even", [ 2, 4 ] ] ]
      * ```
      *
-     * @category Grouping
+     * @category grouping
      * @since 2.0.0
      */
     K, /**
@@ -14358,7 +14415,7 @@ export const groupByKey: {
      * // Output: [ [ "odd", [ 1, 3, 5 ] ], [ "even", [ 2, 4 ] ] ]
      * ```
      *
-     * @category Grouping
+     * @category grouping
      * @since 2.0.0
      */
     Arr.NonEmptyArray<A>>()
@@ -14455,7 +14512,7 @@ const groupByImpl = <A, E, R, K, V, E2, R2>(
  * @see {@link groupByKey} for grouping all elements with the same key across the stream
  * @see {@link groupBy} for custom grouped stream construction
  *
- * @category Grouping
+ * @category grouping
  * @since 2.0.0
  */
 export const groupAdjacentBy: {
@@ -14477,7 +14534,7 @@ export const groupAdjacentBy: {
    * @see {@link groupByKey} for grouping all elements with the same key across the stream
    * @see {@link groupBy} for custom grouped stream construction
    *
-   * @category Grouping
+   * @category grouping
    * @since 2.0.0
    */
   <A, K>(f: (a: NoInfer<A>) => K): <E, R>(self: Stream<A, E, R>) => Stream<readonly [K, Arr.NonEmptyArray<A>], E, R>
@@ -14499,7 +14556,7 @@ export const groupAdjacentBy: {
    * @see {@link groupByKey} for grouping all elements with the same key across the stream
    * @see {@link groupBy} for custom grouped stream construction
    *
-   * @category Grouping
+   * @category grouping
    * @since 2.0.0
    */
   <A, E, R, K>(self: Stream<A, E, R>, f: (a: NoInfer<A>) => K): Stream<readonly [K, Arr.NonEmptyArray<A>], E, R>
@@ -14529,7 +14586,7 @@ export const groupAdjacentBy: {
        * @see {@link groupByKey} for grouping all elements with the same key across the stream
        * @see {@link groupBy} for custom grouped stream construction
        *
-       * @category Grouping
+       * @category grouping
        * @since 2.0.0
        */
       readonly [K, Arr.NonEmptyArray<A>]>()
@@ -15041,7 +15098,7 @@ export const aggregateWithin: {
   }))))
 
 /**
- * Fan out the stream, producing a fixed-size tuple of streams that each emit
+ * Creates a fixed-size tuple of streams that each emit
  * the same elements as the source stream.
  *
  * **Details**
@@ -15081,7 +15138,7 @@ export const aggregateWithin: {
  */
 export const broadcastN: {
   /**
-   * Fan out the stream, producing a fixed-size tuple of streams that each emit
+   * Creates a fixed-size tuple of streams that each emit
    * the same elements as the source stream.
    *
    * **Details**
@@ -15132,7 +15189,7 @@ export const broadcastN: {
     }
   ): <A, E, R>(self: Stream<A, E, R>) => Effect.Effect<TupleOf<N, Stream<A, E>>, never, Scope.Scope | R>
   /**
-   * Fan out the stream, producing a fixed-size tuple of streams that each emit
+   * Creates a fixed-size tuple of streams that each emit
    * the same elements as the source stream.
    *
    * **Details**
@@ -15199,7 +15256,7 @@ export const broadcastN: {
     }
   ) {
     const pubsub = yield* makePubSub</**
-     * Fan out the stream, producing a fixed-size tuple of streams that each emit
+     * Creates a fixed-size tuple of streams that each emit
      * the same elements as the source stream.
      *
      * **Details**
@@ -16392,7 +16449,7 @@ export const intersperse: {
   }))
 
 /**
- * Intersperse stream elements with a middle value, adding a start and end value.
+ * Adds a start value, middle value, and end value around stream elements.
  *
  * **Details**
  *
@@ -16421,7 +16478,7 @@ export const intersperse: {
  */
 export const intersperseAffixes: {
   /**
-   * Intersperse stream elements with a middle value, adding a start and end value.
+   * Adds a start value, middle value, and end value around stream elements.
    *
    * **Details**
    *
@@ -16450,7 +16507,7 @@ export const intersperseAffixes: {
    */
   <A2, A3, A4>(options: { readonly start: A2; readonly middle: A3; readonly end: A4 }): <A, E, R>(self: Stream<A, E, R>) => Stream<A2 | A3 | A4 | A, E, R>
   /**
-   * Intersperse stream elements with a middle value, adding a start and end value.
+   * Adds a start value, middle value, and end value around stream elements.
    *
    * **Details**
    *
@@ -16920,7 +16977,21 @@ export const interruptWhen: {
 )
 
 /**
- * Halts evaluation after the current element once the provided effect completes; the effect is forked, its success is discarded, failures fail the stream, and it does not interrupt an in-progress pull (use `interruptWhen` for that).
+ * Stops a stream after the current element when an effect completes.
+ *
+ * **When to use**
+ *
+ * Use to stop before the next pull after an external signal completes.
+ *
+ * **Details**
+ *
+ * The effect is forked, its success value is discarded, and its failure fails
+ * the stream.
+ *
+ * **Gotchas**
+ *
+ * This does not interrupt an in-progress pull. Use {@link interruptWhen} when
+ * the stream should be interrupted immediately.
  *
  * **Example** (Halting a stream after an effect completes)
  *
@@ -16947,7 +17018,21 @@ export const interruptWhen: {
  */
 export const haltWhen: {
   /**
-   * Halts evaluation after the current element once the provided effect completes; the effect is forked, its success is discarded, failures fail the stream, and it does not interrupt an in-progress pull (use `interruptWhen` for that).
+   * Stops a stream after the current element when an effect completes.
+   *
+   * **When to use**
+   *
+   * Use to stop before the next pull after an external signal completes.
+   *
+   * **Details**
+   *
+   * The effect is forked, its success value is discarded, and its failure fails
+   * the stream.
+   *
+   * **Gotchas**
+   *
+   * This does not interrupt an in-progress pull. Use {@link interruptWhen} when
+   * the stream should be interrupted immediately.
    *
    * **Example** (Halting a stream after an effect completes)
    *
@@ -16974,7 +17059,21 @@ export const haltWhen: {
    */
   <X, E2, R2>(effect: Effect.Effect<X, E2, R2>): <A, E, R>(self: Stream<A, E, R>) => Stream<A, E2 | E, R2 | R>
   /**
-   * Halts evaluation after the current element once the provided effect completes; the effect is forked, its success is discarded, failures fail the stream, and it does not interrupt an in-progress pull (use `interruptWhen` for that).
+   * Stops a stream after the current element when an effect completes.
+   *
+   * **When to use**
+   *
+   * Use to stop before the next pull after an external signal completes.
+   *
+   * **Details**
+   *
+   * The effect is forked, its success value is discarded, and its failure fails
+   * the stream.
+   *
+   * **Gotchas**
+   *
+   * This does not interrupt an in-progress pull. Use {@link interruptWhen} when
+   * the stream should be interrupted immediately.
    *
    * **Example** (Halting a stream after an effect completes)
    *
@@ -20094,7 +20193,7 @@ export const runIntoPubSub: {
 ): Effect.Effect<void, E, R> => Channel.runIntoPubSubArray(self.channel, pubsub, options))
 
 /**
- * Converts a stream to a PubSub for concurrent consumption.
+ * Converts a stream to a PubSub of emitted values for concurrent consumption.
  *
  * **Details**
  *
@@ -20122,7 +20221,7 @@ export const runIntoPubSub: {
  */
 export const toPubSub: {
   /**
-   * Converts a stream to a PubSub for concurrent consumption.
+   * Converts a stream to a PubSub of emitted values for concurrent consumption.
    *
    * **Details**
    *
@@ -20161,7 +20260,7 @@ export const toPubSub: {
     }
   ): <A, E, R>(self: Stream<A, E, R>) => Effect.Effect<PubSub.PubSub<A>, never, R | Scope.Scope>
   /**
-   * Converts a stream to a PubSub for concurrent consumption.
+   * Converts a stream to a PubSub of emitted values for concurrent consumption.
    *
    * **Details**
    *
@@ -20218,7 +20317,7 @@ export const toPubSub: {
 )
 
 /**
- * Converts a stream to a PubSub for concurrent consumption.
+ * Converts a stream to a PubSub of `Take` values for concurrent consumption.
  *
  * **Details**
  *
@@ -20247,7 +20346,7 @@ export const toPubSub: {
  */
 export const toPubSubTake: {
   /**
-   * Converts a stream to a PubSub for concurrent consumption.
+   * Converts a stream to a PubSub of `Take` values for concurrent consumption.
    *
    * **Details**
    *
@@ -20285,7 +20384,7 @@ export const toPubSubTake: {
     }
   ): <A, E, R>(self: Stream<A, E, R>) => Effect.Effect<PubSub.PubSub<Take.Take<A, E>>, never, R | Scope.Scope>
   /**
-   * Converts a stream to a PubSub for concurrent consumption.
+   * Converts a stream to a PubSub of `Take` values for concurrent consumption.
    *
    * **Details**
    *