effect 4.0.0-beta.70 → 4.0.0-beta.72

package/dist/Stream.js

@@ -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
  */
@@ -74,7 +117,14 @@ import { isString } from "./String.js";
  * Runtime identifier stored on `Stream` values and used by `isStream` to
  * recognize them.
  *
- * @category Type Identifiers
+ * **Details**
+ *
+ * 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 IDs
  * @since 4.0.0
  */
 export const TypeId = "~effect/Stream";
@@ -146,8 +196,7 @@ export const DefaultChunkSize = Channel.DefaultChunkSize;
  */
 export const fromChannel = 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)
  *
@@ -205,6 +254,11 @@ export const service = service => fromEffect(Effect.service(service));
  * 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
@@ -395,7 +449,7 @@ export const tick = interval => fromPull(Effect.sync(() => {
  */
 export const fromPull = pull => 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)
  *
@@ -485,7 +539,7 @@ export const toChannel = stream => stream.channel;
  *
  * **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.
@@ -1162,7 +1216,7 @@ export const fromSchedule = schedule => fromPull(Effect.map(Schedule.toStepWithS
  *
  * **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)
@@ -1267,9 +1321,17 @@ export const unfold = (s, f) => fromPull(Effect.sync(() => {
   });
 }));
 /**
- * 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)
  *
@@ -1589,7 +1651,7 @@ export const mapEffect = /*#__PURE__*/dual(args => isStream(args[0]), (self, f,
  */
 export const flattenEffect = /*#__PURE__*/dual(args => isStream(args[0]), (self, options) => mapEffect(self, identity, options));
 /**
- * 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)
  *
@@ -1718,8 +1780,7 @@ export const tapBoth = /*#__PURE__*/dual(2, (self, options) => self.pipe(tapErro
   concurrency: options.concurrency
 })));
 /**
- * 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)
  *
@@ -1980,7 +2041,7 @@ export const drainFork = /*#__PURE__*/dual(2, (self, that) => mergeEffect(self,
  */
 export const repeat = /*#__PURE__*/dual(2, (self, schedule) => 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)
  *
@@ -2000,7 +2061,7 @@ export const repeat = /*#__PURE__*/dual(2, (self, schedule) => fromChannel(Chann
  * // Output: [ 1, 2, 3 ]
  * ```
  *
- * @category Rate Limiting
+ * @category rate limiting
  * @since 2.0.0
  */
 export const schedule = /*#__PURE__*/dual(2, (self, schedule) => self.channel.pipe(Channel.flattenArray, Channel.schedule(schedule), Channel.map(Arr.of), fromChannel));
@@ -2025,7 +2086,7 @@ export const schedule = /*#__PURE__*/dual(2, (self, schedule) => self.channel.pi
  * // Output: [ 1 ]
  * ```
  *
- * @category Rate Limiting
+ * @category rate limiting
  * @since 2.0.0
  */
 export const timeout = /*#__PURE__*/dual(2, (self, duration) => timeoutOrElse(self, {
@@ -2036,13 +2097,24 @@ export const timeout = /*#__PURE__*/dual(2, (self, duration) => timeoutOrElse(se
  * 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.
  *
- * @category Rate Limiting
+ * **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
  */
 export const timeoutOrElse = /*#__PURE__*/dual(2, (self, options) => {
@@ -2148,7 +2220,7 @@ export const repeatElements = /*#__PURE__*/dual(2, (self, schedule) => fromChann
  */
 export const forever = self => 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)
  *
@@ -2405,8 +2477,16 @@ export const mergeRight = /*#__PURE__*/dual(2, (left, right) => mergeEffect(righ
 /**
  * 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)
  *
@@ -2428,6 +2508,12 @@ export const mergeRight = /*#__PURE__*/dual(2, (left, right) => mergeEffect(righ
  * 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 = /*#__PURE__*/dual(2, (streams, options) => flatten(fromIterable(streams), options));
 /**
@@ -3090,12 +3176,25 @@ export const filter = /*#__PURE__*/dual(2, (self, predicate) => fromChannel(Chan
 /**
  * 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
  */
 export const filterMap = /*#__PURE__*/dual(2, (self, filter) => fromChannel(Channel.filterMapArray(toChannel(self), filter)));
 /**
- * Effectfully filters elements in a single pass.
+ * Filters elements in a single pass effectfully.
  *
  * **Example** (Effectfully filtering stream values)
  *
@@ -3118,7 +3217,21 @@ export const filterMap = /*#__PURE__*/dual(2, (self, filter) => fromChannel(Chan
  */
 export const filterEffect = /*#__PURE__*/dual(2, (self, predicate) => fromChannel(Channel.filterArrayEffect(toChannel(self), predicate)));
 /**
- * Effectfully filters and maps elements in a single pass.
+ * Filters and maps elements in one pass effectfully 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
@@ -3208,12 +3321,21 @@ export const partitionQueue = /*#__PURE__*/dual(args => isStream(args[0]), /*#__
  * 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
  */
@@ -3349,7 +3471,7 @@ export const peel = /*#__PURE__*/dual(2, /*#__PURE__*/Effect.fnUntraced(function
  * // Output: [ 1, 2, 3 ]
  * ```
  *
- * @category Rate Limiting
+ * @category rate limiting
  * @since 2.0.0
  */
 export const buffer = /*#__PURE__*/dual(2, (self, options) => fromChannel(Channel.bufferArray(self.channel, options)));
@@ -3380,7 +3502,7 @@ export const buffer = /*#__PURE__*/dual(2, (self, options) => fromChannel(Channe
  * // Output: [ 1, 2, 3, 4 ]
  * ```
  *
- * @category Rate Limiting
+ * @category rate limiting
  * @since 4.0.0
  */
 export const bufferArray = /*#__PURE__*/dual(2, (self, options) => fromChannel(Channel.buffer(self.channel, options)));
@@ -3474,7 +3596,7 @@ export {
  */
 catch_ as catch };
 /**
- * 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)
  *
@@ -3541,6 +3663,21 @@ export const catchIf = /*#__PURE__*/dual(args => isStream(args[0]), (self, predi
  * 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
  */
@@ -3551,7 +3688,7 @@ export const catchFilter = /*#__PURE__*/dual(args => isStream(args[0]), (self, 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)
@@ -3632,7 +3769,7 @@ export const catchTags = /*#__PURE__*/dual(args => isStream(args[0]), (self, cas
  *
  * **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)
@@ -3783,6 +3920,22 @@ export const catchCauseIf = /*#__PURE__*/dual(3, (self, predicate, f) => fromCha
  * 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
  */
@@ -3866,7 +4019,9 @@ export const orDie = self => fromChannel(Channel.orDie(self.channel));
  *
  * **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)
  *
@@ -3902,6 +4057,8 @@ export const orDie = self => fromChannel(Channel.orDie(self.channel));
  * // []
  * ```
  *
+ * @see {@link ignoreCause} for a variant that also ignores defects, not just typed failures
+ *
  * @category error handling
  * @since 4.0.0
  */
@@ -3911,7 +4068,9 @@ export const ignore = /*#__PURE__*/dual(args => isStream(args[0]), (self, option
  *
  * **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)
  *
@@ -3930,12 +4089,14 @@ export const ignore = /*#__PURE__*/dual(args => isStream(args[0]), (self, option
  * // [ 1, 2 ]
  * ```
  *
+ * @see {@link ignore} to ignore only typed failures without suppressing defects
+ *
  * @category error handling
  * @since 4.0.0
  */
 export const ignoreCause = /*#__PURE__*/dual(args => isStream(args[0]), (self, options) => fromChannel(Channel.ignoreCause(self.channel, options)));
 /**
- * When the stream fails, retry it according to the given schedule.
+ * Retries the stream according to the given schedule when it fails.
  *
  * **Details**
  *
@@ -3970,7 +4131,7 @@ export const ignoreCause = /*#__PURE__*/dual(args => isStream(args[0]), (self, o
  */
 export const retry = /*#__PURE__*/dual(2, (self, policy) => fromChannel(Channel.retry(self.channel, policy)));
 /**
- * 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**
@@ -4170,7 +4331,7 @@ export const takeUntil = /*#__PURE__*/dual(args => isStream(args[0]), (self, pre
   return pump;
 })));
 /**
- * Effectful predicate version of `takeUntil`.
+ * Takes stream elements until an effectful predicate returns `true`.
  *
  * **Example** (Taking until an effectful predicate matches)
  *
@@ -4252,10 +4413,19 @@ export const takeWhile = /*#__PURE__*/dual(2, (self, predicate) => transformPull
  * 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
  */
@@ -4422,6 +4592,21 @@ export const dropWhile = /*#__PURE__*/dual(2, (self, predicate) => transformPull
 /**
  * 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
  */
@@ -4535,12 +4720,12 @@ export const dropRight = /*#__PURE__*/dual(2, (self, n) => {
  * // Output: [ [ 1, 2 ], [ 3, 4 ] ]
  * ```
  *
- * @category Grouping
+ * @category grouping
  * @since 2.0.0
  */
 export const chunks = self => self.channel.pipe(Channel.map(Arr.of), fromChannel);
 /**
- * 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**
  *
@@ -4564,7 +4749,7 @@ export const chunks = self => self.channel.pipe(Channel.map(Arr.of), fromChannel
  * // Output: [ [ 1, 2 ], [ 3, 4 ], [ 5 ] ]
  * ```
  *
- * @category Grouping
+ * @category grouping
  * @since 2.0.0
  */
 export const rechunk = /*#__PURE__*/dual(2, (self, target) => {
@@ -4626,7 +4811,7 @@ export const rechunk = /*#__PURE__*/dual(2, (self, target) => {
  * // Output: [ [1, 2], [2, 3], [3, 4], [4, 5] ]
  * ```
  *
- * @category Grouping
+ * @category grouping
  * @since 2.0.0
  */
 export const sliding = /*#__PURE__*/dual(2, (self, chunkSize) => slidingSize(self, chunkSize, 1));
@@ -4650,7 +4835,7 @@ export const sliding = /*#__PURE__*/dual(2, (self, chunkSize) => slidingSize(sel
  * // Output: [ [ 1, 2, 3 ], [ 3, 4, 5 ] ]
  * ```
  *
- * @category Grouping
+ * @category grouping
  * @since 2.0.0
  */
 export const slidingSize = /*#__PURE__*/dual(3, (self, chunkSize, stepSize) => transformPull(self, (upstream, _scope) => Effect.sync(() => {
@@ -4710,7 +4895,7 @@ export const slidingSize = /*#__PURE__*/dual(3, (self, chunkSize, stepSize) => t
  * // Output: [ [1, 2, 3], [5, 6, 7], [9] ]
  * ```
  *
- * @category Grouping
+ * @category grouping
  * @since 2.0.0
  */
 export const split = /*#__PURE__*/dual(2, (self, predicate) => mapAccumArray(self, Arr.empty, (acc, arr) => {
@@ -4769,11 +4954,18 @@ export const split = /*#__PURE__*/dual(2, (self, predicate) => mapAccumArray(sel
  */
 export const combine = /*#__PURE__*/dual(4, (self, that, s, f) => Channel.combine(Channel.flattenArray(self.channel), Channel.flattenArray(that.channel), s, f).pipe(Channel.map(Arr.of), fromChannel));
 /**
- * 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)
  *
@@ -4806,7 +4998,7 @@ export const combine = /*#__PURE__*/dual(4, (self, that, s, f) => Channel.combin
  */
 export const combineArray = /*#__PURE__*/dual(4, (self, that, s, f) => fromChannel(Channel.combine(self.channel, that.channel, s, f)));
 /**
- * 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)
  *
@@ -4847,7 +5039,7 @@ export const mapAccum = /*#__PURE__*/dual(args => isStream(args[0]), (self, init
   }
 } : undefined)));
 /**
- * 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**
  *
@@ -4889,7 +5081,7 @@ export const mapAccumArray = /*#__PURE__*/dual(args => isStream(args[0]), (self,
 } : undefined)));
 const emptyArr = /*#__PURE__*/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**
@@ -4928,7 +5120,7 @@ export const mapAccumEffect = /*#__PURE__*/dual(args => isStream(args[0]), (self
   }
 } : undefined), fromChannel));
 /**
- * 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**
@@ -5007,7 +5199,7 @@ export const scan = /*#__PURE__*/dual(3, (self, initial, f) => suspend(() => {
   }));
 }));
 /**
- * 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)
  *
@@ -5049,7 +5241,7 @@ export const scanEffect = /*#__PURE__*/dual(3, (self, initial, f) => self.channe
  * })
  * ```
  *
- * @category Rate Limiting
+ * @category rate limiting
  * @since 2.0.0
  */
 export const debounce = /*#__PURE__*/dual(2, (self, duration) => transformPull(self, Effect.fnUntraced(function* (pull, scope) {
@@ -5108,13 +5300,17 @@ export const debounce = /*#__PURE__*/dual(2, (self, duration) => transformPull(s
   });
 })));
 /**
- * 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.
@@ -5143,7 +5339,7 @@ export const debounce = /*#__PURE__*/dual(2, (self, duration) => transformPull(s
  * // Output: [0, 1, 2, 3, 4, 5]
  * ```
  *
- * @category Rate Limiting
+ * @category rate limiting
  * @since 2.0.0
  */
 export const throttleEffect = /*#__PURE__*/dual(2, (self, options) => {
@@ -5208,12 +5404,17 @@ const throttleShapeEffect = (self, cost, units, duration, burst) => transformPul
   })));
 }));
 /**
- * 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.
@@ -5242,7 +5443,7 @@ const throttleShapeEffect = (self, cost, units, duration, burst) => transformPul
  * })
  * ```
  *
- * @category Rate Limiting
+ * @category rate limiting
  * @since 2.0.0
  */
 export const throttle = /*#__PURE__*/dual(2, (self, options) => throttleEffect(self, {
@@ -5273,7 +5474,7 @@ export const throttle = /*#__PURE__*/dual(2, (self, options) => throttleEffect(s
  * // Output: [ [ 1, 2, 3 ], [ 4, 5, 6 ], [ 7, 8 ] ]
  * ```
  *
- * @category Grouping
+ * @category grouping
  * @since 2.0.0
  */
 export const grouped = /*#__PURE__*/dual(2, (self, n) => chunks(rechunk(self, n)));
@@ -5298,7 +5499,7 @@ export const grouped = /*#__PURE__*/dual(2, (self, n) => chunks(rechunk(self, n)
  * // Output: [ [ 1, 2 ], [ 3 ] ]
  * ```
  *
- * @category Grouping
+ * @category grouping
  * @since 2.0.0
  */
 export const groupedWithin = /*#__PURE__*/dual(3, (self, chunkSize, duration) => aggregateWithin(self, Sink.take(chunkSize), Schedule.spaced(duration)));
@@ -5331,7 +5532,7 @@ export const groupedWithin = /*#__PURE__*/dual(3, (self, chunkSize, duration) =>
  * // Output: [ [ "odd", [ 1, 3, 5 ] ], [ "even", [ 2, 4 ] ] ]
  * ```
  *
- * @category Grouping
+ * @category grouping
  * @since 2.0.0
  */
 export const groupBy = /*#__PURE__*/dual(args => isStream(args[0]), (self, f, options) => groupByImpl(self, Effect.fnUntraced(function* (arr, queues, queueMap) {
@@ -5370,7 +5571,7 @@ export const groupBy = /*#__PURE__*/dual(args => isStream(args[0]), (self, f, op
  * // Output: [ [ "odd", [ 1, 3, 5 ] ], [ "even", [ 2, 4 ] ] ]
  * ```
  *
- * @category Grouping
+ * @category grouping
  * @since 2.0.0
  */
 export const groupByKey = /*#__PURE__*/dual(args => isStream(args[0]), (self, f, options) => suspend(() => {
@@ -5420,13 +5621,22 @@ const groupByImpl = (self, f, options) => transformPullBracket(self, Effect.fnUn
 /**
  * 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.
  *
- * @category Grouping
+ * @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
  */
 export const groupAdjacentBy = /*#__PURE__*/dual(2, (self, f) => transformPull(self, (pull, _scope) => Effect.sync(() => {
@@ -5622,7 +5832,7 @@ export const aggregateWithin = /*#__PURE__*/dual(3, (self, sink, schedule) => fr
   }).pipe(Effect.flatMap(pull => Effect.raceFirst(catchSinkHalt(pull), stepToBuffer)));
 }))));
 /**
- * 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**
@@ -6135,7 +6345,7 @@ export const intersperse = /*#__PURE__*/dual(2, (self, element) => mapArray(self
   return out;
 }));
 /**
- * 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**
  *
@@ -6290,7 +6500,21 @@ export const interleaveWith = /*#__PURE__*/dual(3, (self, that, decider) => from
  */
 export const interruptWhen = /*#__PURE__*/dual(2, (self, effect) => fromChannel(Channel.interruptWhen(self.channel, effect)));
 /**
- * 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)
  *
@@ -7043,6 +7267,24 @@ export const runHead = self => Effect.map(Channel.runHead(self.channel), Option.
 /**
  * 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
  */
@@ -7519,7 +7761,7 @@ export const toAsyncIterable = self => toAsyncIterableWith(self, Context.empty()
  */
 export const runIntoPubSub = /*#__PURE__*/dual(args => isStream(args[0]), (self, pubsub, options) => 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**
  *
@@ -7547,7 +7789,7 @@ export const runIntoPubSub = /*#__PURE__*/dual(args => isStream(args[0]), (self,
  */
 export const toPubSub = /*#__PURE__*/dual(2, (self, options) => Channel.toPubSubArray(self.channel, options));
 /**
- * Converts a stream to a PubSub for concurrent consumption.
+ * Converts a stream to a PubSub of `Take` values for concurrent consumption.
  *
  * **Details**
  *