effect 4.0.0-beta.70 → 4.0.0-beta.71

package/src/Stream.ts

@@ -1,40 +1,83 @@
 /**
- * The `Stream` module provides a typed, composable way to describe effectful
- * sequences of values. A `Stream<A, E, R>` can emit zero or more `A` values,
- * fail with an `E`, and require services from `R` while preserving
- * backpressure and resource safety.
+ * The `Stream` module describes effectful sequences that may emit many values
+ * over time. A `Stream<A, E, R>` can produce zero or more `A` values, fail with
+ * an `E`, and require services from `R`; the Effect runtime handles
+ * backpressure, interruption, scopes, and finalizers while the stream is being
+ * consumed.
+ *
+ * Streams are useful for files, sockets, queues, subscriptions, paginated APIs,
+ * background jobs, and any workflow where values should be processed
+ * incrementally instead of loaded into memory all at once.
  *
  * **Mental model**
  *
- * - A stream is a lazy description; it runs only when consumed with a `run*` function
- * - Streams are pull-based and emit chunks internally for efficient throughput
- * - `A` is the element type, `E` is the failure type, and `R` is the required context
- * - Stream composition mirrors `Effect`: use `map`, `flatMap`, error handling, and `pipe`
- * - Resource scopes, interruption, and finalizers are tracked by the Effect runtime
- * - Interop functions connect streams to queues, pub/subs, web streams, async iterables, and channels
+ * - A stream is a lazy description; it does not run until consumed with
+ *   {@link run}, {@link runCollect}, {@link runForEach}, or another `run*`
+ *   function.
+ * - Pulling drives evaluation. Operators request values from upstream, and the
+ *   runtime propagates demand instead of pushing unbounded data downstream.
+ * - Values are batched internally as chunks for throughput, while user-facing
+ *   combinators still work with individual elements unless they mention chunks.
+ * - `A` is the element type, `E` is the failure type, and `R` is the required
+ *   service context.
+ * - Composition mirrors `Effect`: use `pipe`, {@link map}, {@link flatMap},
+ *   error handling, resource operators, and service provisioning.
  *
  * **Common tasks**
  *
- * - Create streams: {@link make}, {@link fromIterable}, {@link fromEffect}, {@link fromQueue}
- * - Transform values: {@link map}, {@link mapEffect}, {@link flatMap}, {@link filter}
- * - Combine streams: {@link concat}, {@link merge}, {@link zip}, {@link race}
- * - Control demand and timing: {@link take}, {@link drop}, {@link debounce}, {@link throttle}
- * - Manage errors: {@link catchCause}, {@link catchIf}, {@link mapError}, {@link retry}
- * - Manage resources and services: {@link scoped}, {@link ensuring}, {@link provide}
- * - Consume streams: {@link runCollect}, {@link runForEach}, {@link runFold}, {@link runDrain}
+ * - Create streams from values, effects, and collections with {@link make},
+ *   {@link fromEffect}, {@link fromIterable}, and {@link fromQueue}.
+ * - Transform or select values with {@link map}, {@link mapEffect},
+ *   {@link flatMap}, {@link filter}, and {@link filterMap}.
+ * - Combine streams with {@link concat}, {@link merge}, {@link zip},
+ *   {@link race}, and {@link interleave}.
+ * - Control size and timing with {@link take}, {@link drop}, {@link debounce},
+ *   {@link throttle}, {@link grouped}, and {@link groupedWithin}.
+ * - Handle failures with {@link catchCause}, {@link catchIf},
+ *   {@link mapError}, {@link retry}, and {@link withExecutionPlan}.
+ * - Connect to other protocols with {@link fromReadableStream},
+ *   {@link toReadableStream}, {@link fromAsyncIterable}, {@link toQueue}, and
+ *   {@link runIntoQueue}.
+ * - Consume streams with {@link runCollect}, {@link runForEach},
+ *   {@link runFold}, {@link runDrain}, or a {@link Sink.Sink}.
+ *
+ * **Quickstart**
+ *
+ * **Example** (Transforming and collecting values)
+ *
+ * ```ts
+ * import { Effect, Stream } from "effect"
+ *
+ * const program = Stream.make(1, 2, 3).pipe(
+ *   Stream.map((n) => n * 2),
+ *   Stream.runCollect
+ * )
+ *
+ * Effect.runPromise(program).then(console.log)
+ * // [2, 4, 6]
+ * ```
  *
  * **Gotchas**
  *
- * - A stream is not a collection; constructors and operators build a description until it is run
- * - Re-running a stream re-executes its effects unless it is explicitly shared or backed by external state
- * - Operators such as {@link merge}, {@link race}, and {@link broadcast} introduce concurrency and interruption semantics
- * - Prefer bounded constructors and sinks for large or infinite streams instead of collecting everything into memory
+ * - A stream is not a collection. Constructors and operators build a
+ *   description; effects run each time the stream is consumed.
+ * - {@link runCollect} stores every emitted value in memory. Prefer
+ *   {@link runForEach}, {@link runFold}, or a streaming sink for large or
+ *   infinite streams.
+ * - Operators such as {@link merge}, {@link race}, {@link broadcast}, and
+ *   {@link share} introduce concurrency, so interruption and finalizer timing
+ *   can matter.
+ * - Reusing the same stream value does not share execution by itself. Use
+ *   {@link share}, {@link broadcast}, queues, or external state when multiple
+ *   consumers must observe one running producer.
  *
  * **See also**
  *
- * - {@link Effect.Effect} for single-result effectful programs
- * - {@link Sink.Sink} for consuming and folding streams
- * - {@link Channel.Channel} for the lower-level primitive underlying streams
+ * - {@link Effect.Effect} for single-result effectful programs.
+ * - {@link Sink.Sink} for reusable stream consumers.
+ * - {@link Channel.Channel} for the lower-level primitive behind streams.
+ * - {@link Queue.Queue} and {@link PubSub.PubSub} for coordinating producers
+ *   and consumers.
  *
  * @since 2.0.0
  */
@@ -107,6 +150,13 @@ export type TypeId = "~effect/Stream"
  * Runtime identifier stored on `Stream` values and used by `isStream` to
  * recognize them.
  *
+ * **When to use**
+ *
+ * Use when implementing low-level `Stream` integrations that need direct access
+ * to the runtime brand checked by `isStream`.
+ *
+ * @see {@link isStream} for the public guard that checks this identifier
+ *
  * @category Type Identifiers
  * @since 4.0.0
  */
@@ -756,7 +806,7 @@ export const toChannel = <A, E, R>(
  *
  * **When to use**
  *
- * You can use the `Queue` with the apis from the `Queue` module to emit
+ * 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.
  *
  * By default it uses an "unbounded" buffer size.
@@ -1505,7 +1555,7 @@ export const fromSchedule = <O, E, R>(schedule: Schedule.Schedule<O, unknown, E,
  *
  * **When to use**
  *
- * Use `PubSub.subscribe` to create the subscription and `Stream.take` or
+ * Use to create the subscription and `Stream.take` or
  * cancellation to control how many values are consumed.
  *
  * **Example** (Creating a stream from a PubSub subscription)
@@ -3553,12 +3603,23 @@ export const timeout: {
  * Switches to a fallback stream if this stream does not emit a value within
  * the specified duration.
  *
+ * **When to use**
+ *
+ * Use when a stream should continue with another stream if an upstream pull
+ * waits longer than the allowed duration.
+ *
  * **Details**
  *
  * The timeout is checked for each pull. A zero duration uses `orElse`
  * immediately, while an infinite duration leaves the original stream
  * unchanged.
  *
+ * **Gotchas**
+ *
+ * The fallback stream is not timed after the switch.
+ *
+ * @see {@link timeout} for ending the stream instead of switching to a fallback stream
+ *
  * @category Rate Limiting
  * @since 4.0.0
  */
@@ -3567,12 +3628,23 @@ export const timeoutOrElse: {
    * Switches to a fallback stream if this stream does not emit a value within
    * the specified duration.
    *
+   * **When to use**
+   *
+   * Use when a stream should continue with another stream if an upstream pull
+   * waits longer than the allowed duration.
+   *
    * **Details**
    *
    * The timeout is checked for each pull. A zero duration uses `orElse`
    * immediately, while an infinite duration leaves the original stream
    * unchanged.
    *
+   * **Gotchas**
+   *
+   * The fallback stream is not timed after the switch.
+   *
+   * @see {@link timeout} for ending the stream instead of switching to a fallback stream
+   *
    * @category Rate Limiting
    * @since 4.0.0
    */
@@ -3586,12 +3658,23 @@ export const timeoutOrElse: {
    * Switches to a fallback stream if this stream does not emit a value within
    * the specified duration.
    *
+   * **When to use**
+   *
+   * Use when a stream should continue with another stream if an upstream pull
+   * waits longer than the allowed duration.
+   *
    * **Details**
    *
    * The timeout is checked for each pull. A zero duration uses `orElse`
    * immediately, while an infinite duration leaves the original stream
    * unchanged.
    *
+   * **Gotchas**
+   *
+   * The fallback stream is not timed after the switch.
+   *
+   * @see {@link timeout} for ending the stream instead of switching to a fallback stream
+   *
    * @category Rate Limiting
    * @since 4.0.0
    */
@@ -4561,8 +4644,16 @@ export const mergeRight: {
 /**
  * Merges a collection of streams, running up to the specified number concurrently.
  *
- * @category Merging
- * @since 2.0.0
+ * **When to use**
+ *
+ * Use to merge an iterable of already-created streams while bounding how many
+ * inner streams may run at the same time.
+ *
+ * **Details**
+ *
+ * The `concurrency` option is required and may be a number or `"unbounded"`.
+ * `bufferSize` controls buffering between inner streams, and outputs are
+ * emitted as they arrive under concurrent merging.
  *
  * **Example** (Merging streams with bounded concurrency)
  *
@@ -4584,13 +4675,27 @@ export const mergeRight: {
  * Effect.runPromise(program)
  * // Output: [ "B", "A" ]
  * ```
+ *
+ * @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
+ * @since 2.0.0
  */
 export const mergeAll: {
   /**
    * Merges a collection of streams, running up to the specified number concurrently.
    *
-   * @category Merging
-   * @since 2.0.0
+   * **When to use**
+   *
+   * Use to merge an iterable of already-created streams while bounding how many
+   * inner streams may run at the same time.
+   *
+   * **Details**
+   *
+   * The `concurrency` option is required and may be a number or `"unbounded"`.
+   * `bufferSize` controls buffering between inner streams, and outputs are
+   * emitted as they arrive under concurrent merging.
    *
    * **Example** (Merging streams with bounded concurrency)
    *
@@ -4612,6 +4717,12 @@ export const mergeAll: {
    * Effect.runPromise(program)
    * // Output: [ "B", "A" ]
    * ```
+   *
+   * @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
+   * @since 2.0.0
    */
   (
     options: {
@@ -4622,8 +4733,16 @@ export const mergeAll: {
   /**
    * Merges a collection of streams, running up to the specified number concurrently.
    *
-   * @category Merging
-   * @since 2.0.0
+   * **When to use**
+   *
+   * Use to merge an iterable of already-created streams while bounding how many
+   * inner streams may run at the same time.
+   *
+   * **Details**
+   *
+   * The `concurrency` option is required and may be a number or `"unbounded"`.
+   * `bufferSize` controls buffering between inner streams, and outputs are
+   * emitted as they arrive under concurrent merging.
    *
    * **Example** (Merging streams with bounded concurrency)
    *
@@ -4645,6 +4764,12 @@ export const mergeAll: {
    * Effect.runPromise(program)
    * // Output: [ "B", "A" ]
    * ```
+   *
+   * @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
+   * @since 2.0.0
    */
   <A, E, R>(
     streams: Iterable<Stream<A, E, R>>,
@@ -6261,6 +6386,19 @@ export const filter: {
 /**
  * Filters and maps stream elements in one pass using a `Filter`.
  *
+ * **When to use**
+ *
+ * Use to keep only stream elements accepted by a `Filter` and emit each filter
+ * success value.
+ *
+ * **Details**
+ *
+ * `Result.succeed` values are emitted and `Result.fail` values are skipped.
+ *
+ * @see {@link filter} for keeping original elements with a boolean predicate or refinement
+ * @see {@link filterMapEffect} for an effectful `Filter`
+ * @see {@link partition} for consuming both filter success and failure values
+ *
  * @category filtering
  * @since 2.0.0
  */
@@ -6268,6 +6406,19 @@ export const filterMap: {
   /**
    * Filters and maps stream elements in one pass using a `Filter`.
    *
+   * **When to use**
+   *
+   * Use to keep only stream elements accepted by a `Filter` and emit each filter
+   * success value.
+   *
+   * **Details**
+   *
+   * `Result.succeed` values are emitted and `Result.fail` values are skipped.
+   *
+   * @see {@link filter} for keeping original elements with a boolean predicate or refinement
+   * @see {@link filterMapEffect} for an effectful `Filter`
+   * @see {@link partition} for consuming both filter success and failure values
+   *
    * @category filtering
    * @since 2.0.0
    */
@@ -6275,6 +6426,19 @@ export const filterMap: {
   /**
    * Filters and maps stream elements in one pass using a `Filter`.
    *
+   * **When to use**
+   *
+   * Use to keep only stream elements accepted by a `Filter` and emit each filter
+   * success value.
+   *
+   * **Details**
+   *
+   * `Result.succeed` values are emitted and `Result.fail` values are skipped.
+   *
+   * @see {@link filter} for keeping original elements with a boolean predicate or refinement
+   * @see {@link filterMapEffect} for an effectful `Filter`
+   * @see {@link partition} for consuming both filter success and failure values
+   *
    * @category filtering
    * @since 2.0.0
    */
@@ -6368,21 +6532,63 @@ export const filterEffect: {
 )
 
 /**
- * Effectfully filters and maps elements in a single pass.
+ * Effectfully filters and maps elements in one pass using a `FilterEffect`.
+ *
+ * **When to use**
+ *
+ * Use to apply effectful logic that can reject stream elements or emit
+ * transformed values before they continue downstream.
+ *
+ * **Details**
+ *
+ * `Result.succeed` values are emitted, `Result.fail` values are skipped, and
+ * effect failures fail the stream.
+ *
+ * @see {@link filterMap} for the synchronous `Filter` variant
+ * @see {@link filterEffect} for effectfully keeping original elements
+ * @see {@link mapEffect} for effectfully transforming every element
  *
  * @category filtering
  * @since 2.0.0
  */
 export const filterMapEffect: {
   /**
-   * Effectfully filters and maps elements in a single pass.
+   * Effectfully filters and maps elements in one pass using a `FilterEffect`.
+   *
+   * **When to use**
+   *
+   * Use to apply effectful logic that can reject stream elements or emit
+   * transformed values before they continue downstream.
+   *
+   * **Details**
+   *
+   * `Result.succeed` values are emitted, `Result.fail` values are skipped, and
+   * effect failures fail the stream.
+   *
+   * @see {@link filterMap} for the synchronous `Filter` variant
+   * @see {@link filterEffect} for effectfully keeping original elements
+   * @see {@link mapEffect} for effectfully transforming every element
    *
    * @category filtering
    * @since 2.0.0
    */
   <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 a single pass.
+   * Effectfully filters and maps elements in one pass using a `FilterEffect`.
+   *
+   * **When to use**
+   *
+   * Use to apply effectful logic that can reject stream elements or emit
+   * transformed values before they continue downstream.
+   *
+   * **Details**
+   *
+   * `Result.succeed` values are emitted, `Result.fail` values are skipped, and
+   * effect failures fail the stream.
+   *
+   * @see {@link filterMap} for the synchronous `Filter` variant
+   * @see {@link filterEffect} for effectfully keeping original elements
+   * @see {@link mapEffect} for effectfully transforming every element
    *
    * @category filtering
    * @since 2.0.0
@@ -6738,12 +6944,21 @@ export const partitionQueue: {
  * Splits a stream with an effectful `Filter`, returning scoped streams for
  * filter successes and failures.
  *
+ * **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.
+ *
  * **Details**
  *
  * The returned streams are backed by queues in the current scope and should be
  * consumed while that scope remains open. The first stream emits success values
  * from the filter, and the second emits failure values.
  *
+ * @see {@link partition} for the pure `Filter` variant, which returns the failing stream before the passing stream
+ * @see {@link partitionQueue} for the lower-level queue result
+ * @see {@link filterMapEffect} for effectful filtering that discards failed filter results
+ *
  * @category filtering
  * @since 4.0.0
  */
@@ -6752,12 +6967,21 @@ export const partitionEffect: {
    * Splits a stream with an effectful `Filter`, returning scoped streams for
    * filter successes and failures.
    *
+   * **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.
+   *
    * **Details**
    *
    * The returned streams are backed by queues in the current scope and should be
    * consumed while that scope remains open. The first stream emits success values
    * from the filter, and the second emits failure values.
    *
+   * @see {@link partition} for the pure `Filter` variant, which returns the failing stream before the passing stream
+   * @see {@link partitionQueue} for the lower-level queue result
+   * @see {@link filterMapEffect} for effectful filtering that discards failed filter results
+   *
    * @category filtering
    * @since 4.0.0
    */
@@ -6779,12 +7003,21 @@ export const partitionEffect: {
    * Splits a stream with an effectful `Filter`, returning scoped streams for
    * filter successes and failures.
    *
+   * **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.
+   *
    * **Details**
    *
    * The returned streams are backed by queues in the current scope and should be
    * consumed while that scope remains open. The first stream emits success values
    * from the filter, and the second emits failure values.
    *
+   * @see {@link partition} for the pure `Filter` variant, which returns the failing stream before the passing stream
+   * @see {@link partitionQueue} for the lower-level queue result
+   * @see {@link filterMapEffect} for effectful filtering that discards failed filter results
+   *
    * @category filtering
    * @since 4.0.0
    */
@@ -6825,12 +7058,21 @@ export const partitionEffect: {
        * Splits a stream with an effectful `Filter`, returning scoped streams for
        * filter successes and failures.
        *
+       * **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.
+       *
        * **Details**
        *
        * The returned streams are backed by queues in the current scope and should be
        * consumed while that scope remains open. The first stream emits success values
        * from the filter, and the second emits failure values.
        *
+       * @see {@link partition} for the pure `Filter` variant, which returns the failing stream before the passing stream
+       * @see {@link partitionQueue} for the lower-level queue result
+       * @see {@link filterMapEffect} for effectful filtering that discards failed filter results
+       *
        * @category filtering
        * @since 4.0.0
        */
@@ -6838,12 +7080,21 @@ export const partitionEffect: {
        * Splits a stream with an effectful `Filter`, returning scoped streams for
        * filter successes and failures.
        *
+       * **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.
+       *
        * **Details**
        *
        * The returned streams are backed by queues in the current scope and should be
        * consumed while that scope remains open. The first stream emits success values
        * from the filter, and the second emits failure values.
        *
+       * @see {@link partition} for the pure `Filter` variant, which returns the failing stream before the passing stream
+       * @see {@link partitionQueue} for the lower-level queue result
+       * @see {@link filterMapEffect} for effectful filtering that discards failed filter results
+       *
        * @category filtering
        * @since 4.0.0
        */
@@ -6851,12 +7102,21 @@ export const partitionEffect: {
        * Splits a stream with an effectful `Filter`, returning scoped streams for
        * filter successes and failures.
        *
+       * **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.
+       *
        * **Details**
        *
        * The returned streams are backed by queues in the current scope and should be
        * consumed while that scope remains open. The first stream emits success values
        * from the filter, and the second emits failure values.
        *
+       * @see {@link partition} for the pure `Filter` variant, which returns the failing stream before the passing stream
+       * @see {@link partitionQueue} for the lower-level queue result
+       * @see {@link filterMapEffect} for effectful filtering that discards failed filter results
+       *
        * @category filtering
        * @since 4.0.0
        */
@@ -6864,12 +7124,21 @@ export const partitionEffect: {
        * Splits a stream with an effectful `Filter`, returning scoped streams for
        * filter successes and failures.
        *
+       * **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.
+       *
        * **Details**
        *
        * The returned streams are backed by queues in the current scope and should be
        * consumed while that scope remains open. The first stream emits success values
        * from the filter, and the second emits failure values.
        *
+       * @see {@link partition} for the pure `Filter` variant, which returns the failing stream before the passing stream
+       * @see {@link partitionQueue} for the lower-level queue result
+       * @see {@link filterMapEffect} for effectful filtering that discards failed filter results
+       *
        * @category filtering
        * @since 4.0.0
        */
@@ -6877,12 +7146,21 @@ export const partitionEffect: {
        * Splits a stream with an effectful `Filter`, returning scoped streams for
        * filter successes and failures.
        *
+       * **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.
+       *
        * **Details**
        *
        * The returned streams are backed by queues in the current scope and should be
        * consumed while that scope remains open. The first stream emits success values
        * from the filter, and the second emits failure values.
        *
+       * @see {@link partition} for the pure `Filter` variant, which returns the failing stream before the passing stream
+       * @see {@link partitionQueue} for the lower-level queue result
+       * @see {@link filterMapEffect} for effectful filtering that discards failed filter results
+       *
        * @category filtering
        * @since 4.0.0
        */
@@ -7868,11 +8146,13 @@ export const catchIf: {
    * @category error handling
    * @since 4.0.0
    */
-  <E, EB extends E, A2, E2, R2, A3 = never, E3 = Exclude<E, EB>, R3 = never>(
+  <E, EB extends E, A2, E2, R2, A3 = unassigned, E3 = never, R3 = never>(
     refinement: Refinement<NoInfer<E>, EB>,
     f: (e: EB) => Stream<A2, E2, R2>,
     orElse?: ((e: Exclude<E, EB>) => Stream<A3, E3, R3>) | undefined
-  ): <A, R>(self: Stream<A, E, R>) => Stream<A2 | A | A3, E2 | E3, R2 | R | R3>
+  ): <A, R>(
+    self: Stream<A, E, R>
+  ) => Stream<A | A2 | Exclude<A3, unassigned>, E2 | E3 | (A3 extends unassigned ? Exclude<E, EB> : never), R | R2 | R3>
   /**
    * Recovers from errors that match a predicate by switching to a recovery stream.
    *
@@ -7907,11 +8187,13 @@ export const catchIf: {
    * @category error handling
    * @since 4.0.0
    */
-  <E, A2, E2, R2, A3 = never, E3 = E, R3 = never>(
+  <E, A2, E2, R2, A3 = unassigned, E3 = never, R3 = never>(
     predicate: Predicate<NoInfer<E>>,
     f: (e: NoInfer<E>) => Stream<A2, E2, R2>,
     orElse?: ((e: NoInfer<E>) => Stream<A3, E3, R3>) | undefined
-  ): <A, R>(self: Stream<A, E, R>) => Stream<A2 | A | A3, E2 | E3, R2 | R | R3>
+  ): <A, R>(
+    self: Stream<A, E, R>
+  ) => Stream<A | A2 | Exclude<A3, unassigned>, E2 | E3 | (A3 extends unassigned ? E : never), R | R2 | R3>
   /**
    * Recovers from errors that match a predicate by switching to a recovery stream.
    *
@@ -7946,12 +8228,12 @@ export const catchIf: {
    * @category error handling
    * @since 4.0.0
    */
-  <A, E, R, EB extends E, A2, E2, R2, A3 = never, E3 = Exclude<E, EB>, R3 = never>(
+  <A, E, R, EB extends E, A2, E2, R2, A3 = unassigned, E3 = never, R3 = never>(
     self: Stream<A, E, R>,
     refinement: Refinement<E, EB>,
     f: (e: EB) => Stream<A2, E2, R2>,
     orElse?: ((e: Exclude<E, EB>) => Stream<A3, E3, R3>) | undefined
-  ): Stream<A | A2 | A3, E2 | E3, R | R2 | R3>
+  ): Stream<A | A2 | Exclude<A3, unassigned>, E2 | E3 | (A3 extends unassigned ? Exclude<E, EB> : never), R | R2 | R3>
   /**
    * Recovers from errors that match a predicate by switching to a recovery stream.
    *
@@ -7986,12 +8268,12 @@ export const catchIf: {
    * @category error handling
    * @since 4.0.0
    */
-  <A, E, R, A2, E2, R2, A3 = never, E3 = E, R3 = never>(
+  <A, E, R, A2, E2, R2, A3 = unassigned, E3 = never, R3 = never>(
     self: Stream<A, E, R>,
     predicate: Predicate<E>,
     f: (e: E) => Stream<A2, E2, R2>,
     orElse?: ((e: E) => Stream<A3, E3, R3>) | undefined
-  ): Stream<A | A2 | A3, E2 | E3, R | R2 | R3>
+  ): Stream<A | A2 | Exclude<A3, unassigned>, E2 | E3 | (A3 extends unassigned ? E : never), R | R2 | R3>
 } = dual((args) => isStream(args[0]), <
   A,
   E,
@@ -8021,6 +8303,21 @@ export const catchIf: {
  * Recovers from errors that match a `Filter` by switching to a recovery
  * stream.
  *
+ * **When to use**
+ *
+ * Use to recover from stream errors with a reusable `Filter` when matching can
+ * also narrow or transform the error before choosing the recovery stream.
+ *
+ * **Details**
+ *
+ * Successful filter results are passed to `f`. Failed filter results go to
+ * `orElse` when provided; otherwise the filter failure is re-failed.
+ *
+ * @see {@link catchIf} for predicate or refinement based recovery
+ * @see {@link catchTag} for `_tag` based recovery from one tagged error
+ * @see {@link catchTags} for `_tag` based recovery from multiple tagged errors
+ * @see {@link catchCauseFilter} for filtering full causes
+ *
  * @category error handling
  * @since 4.0.0
  */
@@ -8029,27 +8326,59 @@ export const catchFilter: {
    * Recovers from errors that match a `Filter` by switching to a recovery
    * stream.
    *
+   * **When to use**
+   *
+   * Use to recover from stream errors with a reusable `Filter` when matching can
+   * also narrow or transform the error before choosing the recovery stream.
+   *
+   * **Details**
+   *
+   * Successful filter results are passed to `f`. Failed filter results go to
+   * `orElse` when provided; otherwise the filter failure is re-failed.
+   *
+   * @see {@link catchIf} for predicate or refinement based recovery
+   * @see {@link catchTag} for `_tag` based recovery from one tagged error
+   * @see {@link catchTags} for `_tag` based recovery from multiple tagged errors
+   * @see {@link catchCauseFilter} for filtering full causes
+   *
    * @category error handling
    * @since 4.0.0
    */
-  <E, EB, A2, E2, R2, X, A3 = never, E3 = X, R3 = never>(
+  <E, EB, A2, E2, R2, X, A3 = unassigned, E3 = never, R3 = never>(
     filter: Filter.Filter<NoInfer<E>, EB, X>,
     f: (failure: EB) => Stream<A2, E2, R2>,
     orElse?: ((failure: X) => Stream<A3, E3, R3>) | undefined
-  ): <A, R>(self: Stream<A, E, R>) => Stream<A | A2 | A3, E2 | E3, R | R2 | R3>
+  ): <A, R>(
+    self: Stream<A, E, R>
+  ) => Stream<A | A2 | Exclude<A3, unassigned>, E2 | E3 | (A3 extends unassigned ? X : never), R | R2 | R3>
   /**
    * Recovers from errors that match a `Filter` by switching to a recovery
    * stream.
    *
+   * **When to use**
+   *
+   * Use to recover from stream errors with a reusable `Filter` when matching can
+   * also narrow or transform the error before choosing the recovery stream.
+   *
+   * **Details**
+   *
+   * Successful filter results are passed to `f`. Failed filter results go to
+   * `orElse` when provided; otherwise the filter failure is re-failed.
+   *
+   * @see {@link catchIf} for predicate or refinement based recovery
+   * @see {@link catchTag} for `_tag` based recovery from one tagged error
+   * @see {@link catchTags} for `_tag` based recovery from multiple tagged errors
+   * @see {@link catchCauseFilter} for filtering full causes
+   *
    * @category error handling
    * @since 4.0.0
    */
-  <A, E, R, EB, A2, E2, R2, X, A3 = never, E3 = X, R3 = never>(
+  <A, E, R, EB, A2, E2, R2, X, A3 = unassigned, E3 = never, R3 = never>(
     self: Stream<A, E, R>,
     filter: Filter.Filter<NoInfer<E>, EB, X>,
     f: (failure: EB) => Stream<A2, E2, R2>,
     orElse?: ((failure: X) => Stream<A3, E3, R3>) | undefined
-  ): Stream<A | A2 | A3, E2 | E3, R | R2 | R3>
+  ): Stream<A | A2 | Exclude<A3, unassigned>, E2 | E3 | (A3 extends unassigned ? X : never), R | R2 | R3>
 } = dual((args) => isStream(args[0]), <
   A,
   E,
@@ -8083,7 +8412,7 @@ export const catchFilter: {
  *
  * **When to use**
  *
- * Use `catchTag` when your error type is a tagged union with a readonly `_tag`
+ * Use when your error type is a tagged union with a readonly `_tag`
  * field and you want to handle a specific error case.
  *
  * **Example** (Catching tagged failures)
@@ -8118,7 +8447,7 @@ export const catchTag: {
    *
    * **When to use**
    *
-   * Use `catchTag` when your error type is a tagged union with a readonly `_tag`
+   * Use when your error type is a tagged union with a readonly `_tag`
    * field and you want to handle a specific error case.
    *
    * **Example** (Catching tagged failures)
@@ -8152,8 +8481,8 @@ export const catchTag: {
     A1,
     E1,
     R1,
-    A2 = never,
-    E2 = ExcludeTag<E, K extends Arr.NonEmptyReadonlyArray<string> ? K[number] : K>,
+    A2 = unassigned,
+    E2 = never,
     R2 = never
   >(
     k: K,
@@ -8165,14 +8494,20 @@ export const catchTag: {
       | undefined
   ): <A, R>(
     self: Stream<A, E, R>
-  ) => Stream<A1 | A | A2, E1 | E2, R1 | R | R2>
+  ) => Stream<
+    A | A1 | Exclude<A2, unassigned>,
+    | E1
+    | E2
+    | (A2 extends unassigned ? ExcludeTag<E, K extends Arr.NonEmptyReadonlyArray<string> ? K[number] : K> : never),
+    R | R1 | R2
+  >
   /**
    * Recovers from failures whose `_tag` matches the provided value by switching to
    * the stream returned by `f`.
    *
    * **When to use**
    *
-   * Use `catchTag` when your error type is a tagged union with a readonly `_tag`
+   * Use when your error type is a tagged union with a readonly `_tag`
    * field and you want to handle a specific error case.
    *
    * **Example** (Catching tagged failures)
@@ -8208,8 +8543,8 @@ export const catchTag: {
     R1,
     E1,
     A1,
-    A2 = never,
-    E2 = ExcludeTag<E, K extends Arr.NonEmptyReadonlyArray<string> ? K[number] : K>,
+    A2 = unassigned,
+    E2 = never,
     R2 = never
   >(
     self: Stream<A, E, R>,
@@ -8218,7 +8553,13 @@ export const catchTag: {
     orElse?:
       | ((e: ExcludeTag<E, K extends Arr.NonEmptyReadonlyArray<string> ? K[number] : K>) => Stream<A2, E2, R2>)
       | undefined
-  ): Stream<A1 | A | A2, E1 | E2, R1 | R | R2>
+  ): Stream<
+    A | A1 | Exclude<A2, unassigned>,
+    | E1
+    | E2
+    | (A2 extends unassigned ? ExcludeTag<E, K extends Arr.NonEmptyReadonlyArray<string> ? K[number] : K> : never),
+    R | R1 | R2
+  >
 } = dual(
   (args) => isStream(args[0]),
   <
@@ -8328,19 +8669,20 @@ export const catchTags: {
         [K in E["_tag"]]+?: (error: Extract<E, { _tag: K }>) => Stream<any, any, any>
       } :
       {}),
-    A2 = never,
-    E2 = Exclude<E, { _tag: keyof Cases }>,
+    A2 = unassigned,
+    E2 = never,
     R2 = never
   >(
     cases: Cases,
     orElse?: ((e: Exclude<E, { _tag: keyof Cases }>) => Stream<A2, E2, R2>) | undefined
   ): <A, R>(self: Stream<A, E, R>) => Stream<
     | A
-    | A2
+    | Exclude<A2, unassigned>
     | {
       [K in keyof Cases]: Cases[K] extends ((...args: Array<any>) => Stream<infer A, any, any>) ? A : never
     }[keyof Cases],
     | E2
+    | (A2 extends unassigned ? Exclude<E, { _tag: keyof Cases }> : never)
     | {
       [K in keyof Cases]: Cases[K] extends ((...args: Array<any>) => Stream<any, infer E, any>) ? E : never
     }[keyof Cases],
@@ -8395,8 +8737,8 @@ export const catchTags: {
         [K in E["_tag"]]+?: (error: Extract<E, { _tag: K }>) => Stream<any, any, any>
       } :
       {}),
-    A2 = never,
-    E2 = Exclude<E, { _tag: keyof Cases }>,
+    A2 = unassigned,
+    E2 = never,
     R2 = never
   >(
     self: Stream<A, E, R>,
@@ -8404,11 +8746,12 @@ export const catchTags: {
     orElse?: ((e: Exclude<E, { _tag: keyof Cases }>) => Stream<A2, E2, R2>) | undefined
   ): Stream<
     | A
-    | A2
+    | Exclude<A2, unassigned>
     | {
       [K in keyof Cases]: Cases[K] extends ((...args: Array<any>) => Stream<infer A, any, any>) ? A : never
     }[keyof Cases],
     | E2
+    | (A2 extends unassigned ? Exclude<E, { _tag: keyof Cases }> : never)
     | {
       [K in keyof Cases]: Cases[K] extends ((...args: Array<any>) => Stream<any, infer E, any>) ? E : never
     }[keyof Cases],
@@ -8438,7 +8781,7 @@ export const catchTags: {
  *
  * **When to use**
  *
- * Use this to handle nested error causes without removing the parent error
+ * Use to handle nested error causes without removing the parent error
  * from the error channel. The handler receives the unwrapped reason.
  *
  * **Example** (Catching a tagged error reason)
@@ -8485,7 +8828,7 @@ export const catchReason: {
    *
    * **When to use**
    *
-   * Use this to handle nested error causes without removing the parent error
+   * Use to handle nested error causes without removing the parent error
    * from the error channel. The handler receives the unwrapped reason.
    *
    * **Example** (Catching a tagged error reason)
@@ -8551,13 +8894,17 @@ export const catchReason: {
       | undefined
   ): <A, R>(
     self: Stream<A, E, R>
-  ) => Stream<A | A2 | Exclude<A3, unassigned>, (A3 extends unassigned ? E : ExcludeTag<E, K>) | E2 | E3, R | R2 | R3>
+  ) => Stream<
+    A | A2 | Exclude<A3, unassigned>,
+    ExcludeTag<E, K> | E2 | E3 | (A3 extends unassigned ? ExtractTag<E, K> : never),
+    R | R2 | R3
+  >
   /**
    * Catches a specific reason within a tagged error.
    *
    * **When to use**
    *
-   * Use this to handle nested error causes without removing the parent error
+   * Use to handle nested error causes without removing the parent error
    * from the error channel. The handler receives the unwrapped reason.
    *
    * **Example** (Catching a tagged error reason)
@@ -8618,7 +8965,11 @@ export const catchReason: {
     orElse?:
       | ((reason: ExcludeReason<ExtractTag<E, K>, RK>, error: OmitReason<ExtractTag<E, K>, RK>) => Stream<A3, E3, R3>)
       | undefined
-  ): Stream<A | A2 | Exclude<A3, unassigned>, (A3 extends unassigned ? E : ExcludeTag<E, K>) | E2 | E3, R | R2 | R3>
+  ): Stream<
+    A | A2 | Exclude<A3, unassigned>,
+    ExcludeTag<E, K> | E2 | E3 | (A3 extends unassigned ? ExtractTag<E, K> : never),
+    R | R2 | R3
+  >
 } = dual(
   (args) => isStream(args[0]),
   <
@@ -8641,7 +8992,11 @@ export const catchReason: {
     orElse?:
       | ((reason: ExcludeReason<ExtractTag<E, K>, RK>, error: OmitReason<ExtractTag<E, K>, RK>) => Stream<A3, E3, R3>)
       | undefined
-  ): Stream<A | A2 | Exclude<A3, unassigned>, (A3 extends unassigned ? E : ExcludeTag<E, K>) | E2 | E3, R | R2 | R3> =>
+  ): Stream<
+    A | A2 | Exclude<A3, unassigned>,
+    ExcludeTag<E, K> | E2 | E3 | (A3 extends unassigned ? ExtractTag<E, K> : never),
+    R | R2 | R3
+  > =>
     fromChannel(
       Channel.catchReason(
         toChannel(self),
@@ -8765,8 +9120,9 @@ export const catchReasons: {
     | {
       [RK in keyof Cases]: Cases[RK] extends (...args: Array<any>) => Stream<infer A, any, any> ? A : never
     }[keyof Cases],
-    | (A2 extends unassigned ? E : ExcludeTag<E, K>)
+    | ExcludeTag<E, K>
     | E2
+    | (A2 extends unassigned ? ExtractTag<E, K> : never)
     | {
       [RK in keyof Cases]: Cases[RK] extends (...args: Array<any>) => Stream<any, infer E, any> ? E : never
     }[keyof Cases],
@@ -8848,8 +9204,9 @@ export const catchReasons: {
     | {
       [RK in keyof Cases]: Cases[RK] extends (...args: Array<any>) => Stream<infer A, any, any> ? A : never
     }[keyof Cases],
-    | (A2 extends unassigned ? E : ExcludeTag<E, K>)
+    | ExcludeTag<E, K>
     | E2
+    | (A2 extends unassigned ? ExtractTag<E, K> : never)
     | {
       [RK in keyof Cases]: Cases[RK] extends (...args: Array<any>) => Stream<any, infer E, any> ? E : never
     }[keyof Cases],
@@ -9072,6 +9429,22 @@ export const catchCauseIf: {
  * Recovers from stream failures by filtering the `Cause` and switching to a
  * recovery stream.
  *
+ * **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
+ * `Cause`.
+ *
+ * **Details**
+ *
+ * The filter is applied to the full `Cause`. A successful filter result is
+ * passed to `f` together with the original cause; a failed filter result
+ * re-fails with the residual cause.
+ *
+ * @see {@link catchCauseIf} for predicate-based cause selection
+ * @see {@link catchFilter} for filtering typed error values instead of full causes
+ * @see {@link catchCause} for recovering from every cause without filtering
+ *
  * @category error handling
  * @since 4.0.0
  */
@@ -9080,6 +9453,22 @@ export const catchCauseFilter: {
    * Recovers from stream failures by filtering the `Cause` and switching to a
    * recovery stream.
    *
+   * **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
+   * `Cause`.
+   *
+   * **Details**
+   *
+   * The filter is applied to the full `Cause`. A successful filter result is
+   * passed to `f` together with the original cause; a failed filter result
+   * re-fails with the residual cause.
+   *
+   * @see {@link catchCauseIf} for predicate-based cause selection
+   * @see {@link catchFilter} for filtering typed error values instead of full causes
+   * @see {@link catchCause} for recovering from every cause without filtering
+   *
    * @category error handling
    * @since 4.0.0
    */
@@ -9093,6 +9482,22 @@ export const catchCauseFilter: {
    * Recovers from stream failures by filtering the `Cause` and switching to a
    * recovery stream.
    *
+   * **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
+   * `Cause`.
+   *
+   * **Details**
+   *
+   * The filter is applied to the full `Cause`. A successful filter result is
+   * passed to `f` together with the original cause; a failed filter result
+   * re-fails with the residual cause.
+   *
+   * @see {@link catchCauseIf} for predicate-based cause selection
+   * @see {@link catchFilter} for filtering typed error values instead of full causes
+   * @see {@link catchCause} for recovering from every cause without filtering
+   *
    * @category error handling
    * @since 4.0.0
    */
@@ -9306,7 +9711,9 @@ export const orDie = <A, E, R>(self: Stream<A, E, R>): Stream<A, never, R> => fr
  *
  * **When to use**
  *
- * Use the `log` option to emit the full {@link Cause} when the stream fails.
+ * 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.
  *
  * **Example** (Ignoring stream failures)
  *
@@ -9342,6 +9749,8 @@ export const orDie = <A, E, R>(self: Stream<A, E, R>): Stream<A, never, R> => fr
  * // []
  * ```
  *
+ * @see {@link ignoreCause} for a variant that also ignores defects, not just typed failures
+ *
  * @category error handling
  * @since 4.0.0
  */
@@ -9370,7 +9779,9 @@ export const ignore: <
  *
  * **When to use**
  *
- * Use the `log` option to emit the full {@link Cause} when the stream fails.
+ * 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.
  *
  * **Example** (Ignoring stream failure causes)
  *
@@ -9389,6 +9800,8 @@ export const ignore: <
  * // [ 1, 2 ]
  * ```
  *
+ * @see {@link ignore} to ignore only typed failures without suppressing defects
+ *
  * @category error handling
  * @since 4.0.0
  */
@@ -10373,10 +10786,19 @@ export const takeWhile: {
  * Takes the longest initial prefix accepted by a `Filter` and emits the
  * filter's success values.
  *
+ * **When to use**
+ *
+ * Use to keep the leading stream elements that a `Filter` accepts, emit the
+ * filter's success values, and stop at the first filter failure.
+ *
  * **Details**
  *
  * The stream stops at the first `Result.fail` returned by the filter.
  *
+ * @see {@link takeWhile} for keeping original elements with a boolean predicate or refinement
+ * @see {@link filterMap} for filtering across the whole stream instead of only the leading prefix
+ * @see {@link dropWhileFilter} for dropping the accepted prefix and keeping the remaining original elements
+ *
  * @category filtering
  * @since 4.0.0
  */
@@ -10385,10 +10807,19 @@ export const takeWhileFilter: {
    * Takes the longest initial prefix accepted by a `Filter` and emits the
    * filter's success values.
    *
+   * **When to use**
+   *
+   * Use to keep the leading stream elements that a `Filter` accepts, emit the
+   * filter's success values, and stop at the first filter failure.
+   *
    * **Details**
    *
    * The stream stops at the first `Result.fail` returned by the filter.
    *
+   * @see {@link takeWhile} for keeping original elements with a boolean predicate or refinement
+   * @see {@link filterMap} for filtering across the whole stream instead of only the leading prefix
+   * @see {@link dropWhileFilter} for dropping the accepted prefix and keeping the remaining original elements
+   *
    * @category filtering
    * @since 4.0.0
    */
@@ -10397,10 +10828,19 @@ export const takeWhileFilter: {
    * Takes the longest initial prefix accepted by a `Filter` and emits the
    * filter's success values.
    *
+   * **When to use**
+   *
+   * Use to keep the leading stream elements that a `Filter` accepts, emit the
+   * filter's success values, and stop at the first filter failure.
+   *
    * **Details**
    *
    * The stream stops at the first `Result.fail` returned by the filter.
    *
+   * @see {@link takeWhile} for keeping original elements with a boolean predicate or refinement
+   * @see {@link filterMap} for filtering across the whole stream instead of only the leading prefix
+   * @see {@link dropWhileFilter} for dropping the accepted prefix and keeping the remaining original elements
+   *
    * @category filtering
    * @since 4.0.0
    */
@@ -10881,6 +11321,21 @@ export const dropWhile: {
 /**
  * Drops elements while the filter succeeds.
  *
+ * **When to use**
+ *
+ * Use when you need to remove a leading stream prefix based on a synchronous
+ * `Filter` result while preserving the remaining original stream elements.
+ *
+ * **Details**
+ *
+ * `Result.succeed` drops the current element. The first `Result.fail` stops
+ * dropping, emits that original element, and the rest of the source stream is
+ * emitted without further filtering.
+ *
+ * @see {@link dropWhile} for boolean predicate prefix dropping
+ * @see {@link takeWhileFilter} for keeping the accepted prefix as filter success values
+ * @see {@link dropWhileEffect} for effectful predicate prefix dropping
+ *
  * @category filtering
  * @since 4.0.0
  */
@@ -10888,6 +11343,21 @@ export const dropWhileFilter: {
   /**
    * Drops elements while the filter succeeds.
    *
+   * **When to use**
+   *
+   * Use when you need to remove a leading stream prefix based on a synchronous
+   * `Filter` result while preserving the remaining original stream elements.
+   *
+   * **Details**
+   *
+   * `Result.succeed` drops the current element. The first `Result.fail` stops
+   * dropping, emits that original element, and the rest of the source stream is
+   * emitted without further filtering.
+   *
+   * @see {@link dropWhile} for boolean predicate prefix dropping
+   * @see {@link takeWhileFilter} for keeping the accepted prefix as filter success values
+   * @see {@link dropWhileEffect} for effectful predicate prefix dropping
+   *
    * @category filtering
    * @since 4.0.0
    */
@@ -10895,6 +11365,21 @@ export const dropWhileFilter: {
   /**
    * Drops elements while the filter succeeds.
    *
+   * **When to use**
+   *
+   * Use when you need to remove a leading stream prefix based on a synchronous
+   * `Filter` result while preserving the remaining original stream elements.
+   *
+   * **Details**
+   *
+   * `Result.succeed` drops the current element. The first `Result.fail` stops
+   * dropping, emits that original element, and the rest of the source stream is
+   * emitted without further filtering.
+   *
+   * @see {@link dropWhile} for boolean predicate prefix dropping
+   * @see {@link takeWhileFilter} for keeping the accepted prefix as filter success values
+   * @see {@link dropWhileEffect} for effectful predicate prefix dropping
+   *
    * @category filtering
    * @since 4.0.0
    */
@@ -13955,12 +14440,21 @@ const groupByImpl = <A, E, R, K, V, E2, R2>(
 /**
  * Groups consecutive elements that have equal keys into non-empty arrays.
  *
+ * **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.
+ *
  * **Details**
  *
  * The key is computed with `f`; adjacent elements whose keys are equal by
  * `Equal.equals` are emitted as one `[key, group]`. Later non-adjacent runs
  * with the same key are emitted separately.
  *
+ * @see {@link groupByKey} for grouping all elements with the same key across the stream
+ * @see {@link groupBy} for custom grouped stream construction
+ *
  * @category Grouping
  * @since 2.0.0
  */
@@ -13968,12 +14462,21 @@ export const groupAdjacentBy: {
   /**
    * Groups consecutive elements that have equal keys into non-empty arrays.
    *
+   * **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.
+   *
    * **Details**
    *
    * The key is computed with `f`; adjacent elements whose keys are equal by
    * `Equal.equals` are emitted as one `[key, group]`. Later non-adjacent runs
    * with the same key are emitted separately.
    *
+   * @see {@link groupByKey} for grouping all elements with the same key across the stream
+   * @see {@link groupBy} for custom grouped stream construction
+   *
    * @category Grouping
    * @since 2.0.0
    */
@@ -13981,12 +14484,21 @@ export const groupAdjacentBy: {
   /**
    * Groups consecutive elements that have equal keys into non-empty arrays.
    *
+   * **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.
+   *
    * **Details**
    *
    * The key is computed with `f`; adjacent elements whose keys are equal by
    * `Equal.equals` are emitted as one `[key, group]`. Later non-adjacent runs
    * with the same key are emitted separately.
    *
+   * @see {@link groupByKey} for grouping all elements with the same key across the stream
+   * @see {@link groupBy} for custom grouped stream construction
+   *
    * @category Grouping
    * @since 2.0.0
    */
@@ -14002,12 +14514,21 @@ export const groupAdjacentBy: {
       let toEmit = Arr.empty</**
        * Groups consecutive elements that have equal keys into non-empty arrays.
        *
+       * **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.
+       *
        * **Details**
        *
        * The key is computed with `f`; adjacent elements whose keys are equal by
        * `Equal.equals` are emitted as one `[key, group]`. Later non-adjacent runs
        * with the same key are emitted separately.
        *
+       * @see {@link groupByKey} for grouping all elements with the same key across the stream
+       * @see {@link groupBy} for custom grouped stream construction
+       *
        * @category Grouping
        * @since 2.0.0
        */
@@ -18516,6 +19037,24 @@ export const runHead = <A, E, R>(self: Stream<A, E, R>): Effect.Effect<Option.Op
 /**
  * Runs the stream and returns the last element as an `Option`.
  *
+ * **When to use**
+ *
+ * Use to consume a finite stream when only the final emitted element matters.
+ *
+ * **Details**
+ *
+ * `Option.some` contains the last emitted element. `Option.none` means the
+ * stream completed without emitting.
+ *
+ * **Gotchas**
+ *
+ * The returned effect waits for the stream to complete before it can produce a
+ * value.
+ *
+ * @see {@link runHead} for consuming only the first emitted element
+ * @see {@link runCollect} for collecting every emitted element
+ * @see {@link runDrain} for consuming the stream while discarding emitted elements
+ *
  * @category destructors
  * @since 2.0.0
  */