effect 4.0.0-beta.66 → 4.0.0-beta.68

package/dist/Stream.js

@@ -1,4 +1,41 @@
 /**
+ * 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.
+ *
+ * **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
+ *
+ * **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}
+ *
+ * **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
+ *
+ * **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
+ *
  * @since 2.0.0
  */
 // @effect-diagnostics returnEffectInGen:off
@@ -23,6 +60,7 @@ import * as MutableHashMap from "./MutableHashMap.js";
 import * as MutableList from "./MutableList.js";
 import * as Option from "./Option.js";
 import { hasProperty, isNotUndefined, isTagged } from "./Predicate.js";
+import * as PubSub from "./PubSub.js";
 import * as Pull from "./Pull.js";
 import * as Queue from "./Queue.js";
 import * as RcMap from "./RcMap.js";
@@ -33,14 +71,18 @@ import * as Scope from "./Scope.js";
 import * as Sink from "./Sink.js";
 import { isString } from "./String.js";
 /**
- * @since 4.0.0
+ * Runtime identifier stored on `Stream` values and used by `isStream` to
+ * recognize them.
+ *
  * @category Type Identifiers
+ * @since 4.0.0
  */
 export const TypeId = "~effect/Stream";
 /**
  * Checks whether a value is a Stream.
  *
- * @example
+ * **Example** (Checking whether a value is a Stream)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -57,14 +99,15 @@ export const TypeId = "~effect/Stream";
  * Effect.runPromise(program)
  * ```
  *
- * @since 2.0.0
- * @category Guards
+ * @category guards
+ * @since 4.0.0
  */
 export const isStream = u => hasProperty(u, TypeId);
 /**
  * The default chunk size used by Stream constructors and combinators.
  *
- * @example
+ * **Example** (Reading the default chunk size)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -83,7 +126,8 @@ export const DefaultChunkSize = Channel.DefaultChunkSize;
 /**
  * Creates a stream from a array-emitting `Channel`.
  *
- * @example
+ * **Example** (Creating a stream from an array-emitting channel)
+ *
  * ```ts
  * import { Channel, Console, Effect, Stream } from "effect"
  *
@@ -97,15 +141,16 @@ export const DefaultChunkSize = Channel.DefaultChunkSize;
  * // Output: [ 1, 2, 3 ]
  * ```
  *
+ * @category constructors
  * @since 2.0.0
- * @category Constructors
  */
 export const fromChannel = internal.fromChannel;
 /**
  * Either emits the success value of this effect or terminates the stream
  * with the failure value of this effect.
  *
- * @example
+ * **Example** (Creating a stream from an effect)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -119,16 +164,17 @@ export const fromChannel = internal.fromChannel;
  * // Output: [ 42 ]
  * ```
  *
+ * @category constructors
  * @since 2.0.0
- * @category Constructors
  */
 export const fromEffect = effect => fromChannel(Channel.fromEffect(Effect.map(effect, Arr.of)));
 /**
  * Accesses a service from the context and emits it as a single element.
  *
- * @example
+ * **Example** (Accessing a service as a stream)
+ *
  * ```ts
- * import { Effect, Context, Stream } from "effect"
+ * import { Context, Effect, Stream } from "effect"
  *
  * class Greeter extends Context.Service<Greeter, {
  *   readonly greet: (name: string) => string
@@ -151,17 +197,18 @@ export const fromEffect = effect => fromChannel(Channel.fromEffect(Effect.map(ef
  * // Output: [ "Hello, World!" ]
  * ```
  *
- * @since 4.0.0
  * @category Context
+ * @since 4.0.0
  */
 export const service = service => fromEffect(Effect.service(service));
 /**
  * Optionally accesses a service from the context and emits the result as a
  * single element.
  *
- * @example
+ * **Example** (Accessing an optional service as a stream)
+ *
  * ```ts
- * import { Effect, Option, Context, Stream } from "effect"
+ * import { Context, Effect, Option, Stream } from "effect"
  *
  * class Greeter extends Context.Service<Greeter, {
  *   readonly greet: (name: string) => string
@@ -189,14 +236,15 @@ export const service = service => fromEffect(Effect.service(service));
  * // Output: [ "Hello, World!" ]
  * ```
  *
- * @since 4.0.0
  * @category Context
+ * @since 4.0.0
  */
 export const serviceOption = service => fromEffect(Effect.serviceOption(service));
 /**
  * Creates a stream that runs the effect and emits no elements.
  *
- * @example
+ * **Example** (Draining an effect into a stream)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -210,20 +258,15 @@ export const serviceOption = service => fromEffect(Effect.serviceOption(service)
  * // Output: Draining side effect
  * ```
  *
+ * @category constructors
  * @since 4.0.0
- * @category Constructors
  */
 export const fromEffectDrain = effect => fromPull(Effect.succeed(Effect.flatMap(effect, () => Cause.done())));
 /**
  * Creates a stream from an effect producing a value of type `A` which repeats forever.
  *
- * **Previously Known As**
- *
- * This API replaces the following from Effect 3.x:
+ * **Example** (Repeating an effect forever)
  *
- * - `Stream.repeatEffect`
- *
- * @example
  * ```ts
  * import { Console, Effect, Random, Stream } from "effect"
  *
@@ -239,21 +282,16 @@ export const fromEffectDrain = effect => fromPull(Effect.succeed(Effect.flatMap(
  * // Output: [ 3891571149, 4239494205, 2352981603, 2339111046, 1488052210 ]
  * ```
  *
+ * @category constructors
  * @since 4.0.0
- * @category Constructors
  */
 export const fromEffectRepeat = effect => fromPull(Effect.succeed(Effect.map(effect, Arr.of)));
 /**
  * Creates a stream from an effect producing a value of type `A`, which is
  * repeated using the specified schedule.
  *
- * **Previously Known As**
- *
- * This API replaces the following from Effect 3.x:
+ * **Example** (Repeating an effect with a schedule)
  *
- * - `Stream.repeatEffectWithSchedule`
- *
- * @example
  * ```ts
  * import { Console, Effect, Schedule, Stream } from "effect"
  *
@@ -270,8 +308,8 @@ export const fromEffectRepeat = effect => fromPull(Effect.succeed(Effect.map(eff
  * // Output: [ "ping", "ping", "ping" ]
  * ```
  *
- * @since 2.0.0
- * @category Constructors
+ * @category constructors
+ * @since 4.0.0
  */
 export const fromEffectSchedule = (effect, schedule) => fromPull(Effect.gen(function* () {
   const step = yield* Schedule.toStepWithMetadata(schedule);
@@ -290,9 +328,11 @@ export const fromEffectSchedule = (effect, schedule) => fromPull(Effect.gen(func
   });
 }));
 /**
- * Creates a stream that emits void values spaced by the specified duration.
+ * Creates a stream that emits `void` immediately once, then emits another
+ * `void` after each specified interval.
+ *
+ * **Example** (Emitting ticks on an interval)
  *
- * @example
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -308,8 +348,8 @@ export const fromEffectSchedule = (effect, schedule) => fromPull(Effect.gen(func
  * // Output: [ undefined, undefined, undefined ]
  * ```
  *
+ * @category constructors
  * @since 2.0.0
- * @category Constructors
  */
 export const tick = interval => fromPull(Effect.sync(() => {
   let first = true;
@@ -329,7 +369,8 @@ export const tick = interval => fromPull(Effect.sync(() => {
  * A pull effect yields chunks on demand and completes when the upstream stream ends.
  * See `Stream.toPull` for a matching producer.
  *
- * @example
+ * **Example** (Creating a stream from a pull effect)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -347,14 +388,15 @@ export const tick = interval => fromPull(Effect.sync(() => {
  * // Output: [1, 2, 3]
  * ```
  *
+ * @category constructors
  * @since 2.0.0
- * @category Constructors
  */
 export const fromPull = pull => fromChannel(Channel.fromPull(pull));
 /**
  * Derive a stream by transforming its pull effect.
  *
- * @example
+ * **Example** (Transforming a pull effect)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -371,8 +413,8 @@ export const fromPull = pull => fromChannel(Channel.fromPull(pull));
  * // Output: [ 1, 2, 3 ]
  * ```
  *
+ * @category constructors
  * @since 4.0.0
- * @category Constructors
  */
 export const transformPull = (self, f) => fromChannel(Channel.fromTransform((_, scope) => Effect.flatMap(Channel.toPullScoped(self.channel, scope), pull => f(pull, scope))));
 /**
@@ -381,7 +423,8 @@ export const transformPull = (self, f) => fromChannel(Channel.fromTransform((_,
  * A forked scope is also provided to the transformation function, which is
  * closed once the resulting stream has finished processing.
  *
- * @example
+ * **Example** (Transforming a stream by effectfully transforming its pull effect)
+ *
  * ```ts
  * import { Console, Effect, Scope, Stream } from "effect"
  *
@@ -406,14 +449,15 @@ export const transformPull = (self, f) => fromChannel(Channel.fromTransform((_,
  * // Releasing scope
  * ```
  *
+ * @category constructors
  * @since 4.0.0
- * @category Constructors
  */
 export const transformPullBracket = (self, f) => fromChannel(Channel.fromTransformBracket((_, scope, forkedScope) => Effect.flatMap(Channel.toPullScoped(self.channel, scope), pull => f(pull, scope, forkedScope))));
 /**
  * Creates a channel from a stream.
  *
- * @example
+ * **Example** (Converting a stream to a channel)
+ *
  * ```ts
  * import { Channel, Console, Effect, Stream } from "effect"
  *
@@ -428,8 +472,8 @@ export const transformPullBracket = (self, f) => fromChannel(Channel.fromTransfo
  * // Output: [ 1, 2, 3 ]
  * ```
  *
+ * @category constructors
  * @since 2.0.0
- * @category Constructors
  */
 export const toChannel = stream => stream.channel;
 /**
@@ -442,16 +486,8 @@ export const toChannel = stream => stream.channel;
  * You can customize the buffer size and strategy by passing an object as the
  * second argument with the `bufferSize` and `strategy` fields.
  *
- * **Previously Known As**
+ * **Example** (Creating a stream from a callback that can emit values into a queue)
  *
- * This API replaces the following from Effect 3.x:
- *
- * - `Stream.async`
- * - `Stream.asyncEffect`
- * - `Stream.asyncPush`
- * - `Stream.asyncScoped`
- *
- * @example
  * ```ts
  * import { Console, Effect, Queue, Stream } from "effect"
  *
@@ -475,14 +511,15 @@ export const toChannel = stream => stream.channel;
  * Effect.runPromise(program)
  * ```
  *
- * @since 2.0.0
- * @category Constructors
+ * @category constructors
+ * @since 4.0.0
  */
 export const callback = (f, options) => fromChannel(Channel.callbackArray(f, options));
 /**
  * Creates an empty stream.
  *
- * @example
+ * **Example** (Creating an empty stream)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -495,14 +532,15 @@ export const callback = (f, options) => fromChannel(Channel.callbackArray(f, opt
  * // []
  * ```
  *
- * @since 4.0.0
- * @category Constructors
+ * @category constructors
+ * @since 2.0.0
  */
 export const empty = /*#__PURE__*/fromChannel(Channel.empty);
 /**
  * Creates a single-valued pure stream.
  *
- * @example
+ * **Example** (Creating a single-valued pure stream)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -515,14 +553,15 @@ export const empty = /*#__PURE__*/fromChannel(Channel.empty);
  * // [ 3 ]
  * ```
  *
+ * @category constructors
  * @since 2.0.0
- * @category Constructors
  */
 export const succeed = value => fromChannel(Channel.succeed(Arr.of(value)));
 /**
  * Creates a stream from a sequence of values.
  *
- * @example
+ * **Example** (Creating a stream from a sequence of values)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -536,8 +575,8 @@ export const succeed = value => fromChannel(Channel.succeed(Arr.of(value)));
  * Effect.runPromise(program)
  * ```
  *
+ * @category constructors
  * @since 2.0.0
- * @category Constructors
  */
 export const make = (...values) => fromArray(values);
 /**
@@ -545,7 +584,8 @@ export const make = (...values) => fromArray(values);
  *
  * The function is evaluated each time the stream is run.
  *
- * @example
+ * **Example** (Evaluating a value synchronously)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -558,8 +598,8 @@ export const make = (...values) => fromArray(values);
  * // Output: [ 3 ]
  * ```
  *
+ * @category constructors
  * @since 2.0.0
- * @category Constructors
  */
 export const sync = evaluate => fromChannel(Channel.sync(() => Arr.of(evaluate())));
 /**
@@ -567,7 +607,8 @@ export const sync = evaluate => fromChannel(Channel.sync(() => Arr.of(evaluate()
  *
  * The stream factory is evaluated each time the stream is run.
  *
- * @example
+ * **Example** (Creating a lazily constructed stream)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -580,14 +621,15 @@ export const sync = evaluate => fromChannel(Channel.sync(() => Arr.of(evaluate()
  * // Output: [ 1, 2, 3 ]
  * ```
  *
+ * @category constructors
  * @since 2.0.0
- * @category Constructors
  */
 export const suspend = stream => fromChannel(Channel.suspend(() => stream().channel));
 /**
  * Terminates with the specified error.
  *
- * @example
+ * **Example** (Failing a stream)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -601,14 +643,15 @@ export const suspend = stream => fromChannel(Channel.suspend(() => stream().chan
  * Effect.runPromise(program)
  * ```
  *
+ * @category constructors
  * @since 2.0.0
- * @category Constructors
  */
 export const fail = error => fromChannel(Channel.fail(error));
 /**
  * Terminates with the specified lazily evaluated error.
  *
- * @example
+ * **Example** (Failing a stream lazily)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -624,14 +667,15 @@ export const fail = error => fromChannel(Channel.fail(error));
  * // { _id: 'Exit', _tag: 'Failure', cause: { _id: 'Cause', _tag: 'Fail', failure: 'Uh oh!' } }
  * ```
  *
+ * @category constructors
  * @since 2.0.0
- * @category Constructors
  */
 export const failSync = evaluate => fromChannel(Channel.failSync(evaluate));
 /**
  * Creates a stream that fails with the specified `Cause`.
  *
- * @example
+ * **Example** (Failing with a cause)
+ *
  * ```ts
  * import { Cause, Console, Effect, Stream } from "effect"
  *
@@ -648,14 +692,15 @@ export const failSync = evaluate => fromChannel(Channel.failSync(evaluate));
  * Effect.runPromise(program)
  * ```
  *
+ * @category constructors
  * @since 2.0.0
- * @category Constructors
  */
 export const failCause = cause => fromChannel(Channel.failCause(cause));
 /**
  * The stream that dies with the specified defect.
  *
- * @example
+ * **Example** (Dying with a defect)
+ *
  * ```ts
  * import { Cause, Console, Effect, Exit, Stream } from "effect"
  *
@@ -679,14 +724,15 @@ export const failCause = cause => fromChannel(Channel.failCause(cause));
  * // Output: Exit.Failure(Error: Boom)
  * ```
  *
+ * @category constructors
  * @since 2.0.0
- * @category Constructors
  */
 export const die = defect => fromChannel(Channel.die(defect));
 /**
  * The stream that always fails with the specified lazily evaluated `Cause`.
  *
- * @example
+ * **Example** (Failing with a lazy cause)
+ *
  * ```ts
  * import { Cause, Console, Effect, Stream } from "effect"
  *
@@ -704,8 +750,8 @@ export const die = defect => fromChannel(Channel.die(defect));
  * // { _id: 'Exit', _tag: 'Failure', cause: { _id: 'Cause', _tag: 'Fail', failure: 'Connection timeout after retries' } }
  * ```
  *
+ * @category constructors
  * @since 2.0.0
- * @category Constructors
  */
 export const failCauseSync = evaluate => fromChannel(Channel.failCauseSync(evaluate));
 /**
@@ -713,7 +759,8 @@ export const failCauseSync = evaluate => fromChannel(Channel.failCauseSync(evalu
  *
  * The `maxChunkSize` parameter controls how many values are pulled per chunk.
  *
- * @example
+ * **Example** (Consuming values from an iterator)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -734,8 +781,8 @@ export const failCauseSync = evaluate => fromChannel(Channel.failCauseSync(evalu
  * // Output: [ 1, 2, 3 ]
  * ```
  *
+ * @category constructors
  * @since 2.0.0
- * @category Constructors
  */
 export const fromIteratorSucceed = (iterator, maxChunkSize) => fromChannel(Channel.fromIteratorArray(() => iterator, maxChunkSize));
 /**
@@ -745,7 +792,8 @@ export const fromIteratorSucceed = (iterator, maxChunkSize) => fromChannel(Chann
  *
  * - `chunkSize`: Maximum number of values emitted per chunk.
  *
- * @example
+ * **Example** (Creating a stream from an iterable)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -761,16 +809,17 @@ export const fromIteratorSucceed = (iterator, maxChunkSize) => fromChannel(Chann
  * // Output: [ 1, 2, 3 ]
  * ```
  *
+ * @category constructors
  * @since 2.0.0
- * @category Constructors
  */
 export const fromIterable = (iterable, options) => Array.isArray(iterable) && options?.chunkSize === undefined ? fromArray(iterable) : fromChannel(Channel.fromIterableArray(iterable, options?.chunkSize));
 /**
  * Creates a stream from an effect producing an iterable of values.
  *
- * @example
+ * **Example** (Creating a stream from an iterable effect)
+ *
  * ```ts
- * import { Console, Effect, Context, Stream } from "effect"
+ * import { Console, Context, Effect, Stream } from "effect"
  *
  * class UserRepo extends Context.Service<UserRepo, {
  *   readonly list: Effect.Effect<ReadonlyArray<string>>
@@ -796,20 +845,15 @@ export const fromIterable = (iterable, options) => Array.isArray(iterable) && op
  * // Output: [ "user1", "user2" ]
  * ```
  *
+ * @category constructors
  * @since 2.0.0
- * @category Constructors
  */
 export const fromIterableEffect = iterable => unwrap(Effect.map(iterable, fromIterable));
 /**
  * Creates a stream by repeatedly running an effect that yields an iterable of values.
  *
- * **Previously Known As**
- *
- * This API replaces the following from Effect 3.x:
+ * **Example** (Repeating an iterable effect)
  *
- * - `Stream.repeatEffectChunk`
- *
- * @example
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -825,20 +869,15 @@ export const fromIterableEffect = iterable => unwrap(Effect.map(iterable, fromIt
  * // Output: [ 1, 2, 1, 2, 1 ]
  * ```
  *
+ * @category constructors
  * @since 4.0.0
- * @category Constructors
  */
 export const fromIterableEffectRepeat = iterable => flatMap(fromEffectRepeat(iterable), fromIterable);
 /**
  * Creates a stream from an array of values.
  *
- * **Previously Known As**
- *
- * This API replaces the following from Effect 3.x:
+ * **Example** (Creating a stream from an array of values)
  *
- * - `Stream.fromChunk`
- *
- * @example
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -852,14 +891,15 @@ export const fromIterableEffectRepeat = iterable => flatMap(fromEffectRepeat(ite
  * // Output: [ 1, 2, 3 ]
  * ```
  *
+ * @category constructors
  * @since 4.0.0
- * @category Constructors
  */
 export const fromArray = array => Arr.isReadonlyArrayNonEmpty(array) ? fromChannel(Channel.succeed(array)) : empty;
 /**
  * Creates a stream from an effect that produces an array of values.
  *
- * @example
+ * **Example** (Creating a stream from an effect that produces an array of values)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -873,20 +913,15 @@ export const fromArray = array => Arr.isReadonlyArrayNonEmpty(array) ? fromChann
  * // Output: [ "Ada", "Grace" ]
  * ```
  *
+ * @category constructors
  * @since 4.0.0
- * @category Constructors
  */
 export const fromArrayEffect = effect => unwrap(Effect.map(effect, fromArray));
 /**
  * Creates a stream from an arbitrary number of arrays.
  *
- * **Previously Known As**
+ * **Example** (Creating a stream from an arbitrary number of arrays)
  *
- * This API replaces the following from Effect 3.x:
- *
- * - `Stream.fromChunks`
- *
- * @example
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -900,19 +935,18 @@ export const fromArrayEffect = effect => unwrap(Effect.map(effect, fromArray));
  * // Output: [ 1, 2, 3, 4 ]
  * ```
  *
+ * @category constructors
  * @since 4.0.0
- * @category Constructors
  */
 export const fromArrays = (...arrays) => fromChannel(Channel.fromArray(Arr.filter(arrays, Arr.isReadonlyArrayNonEmpty)));
 /**
- * Creates a stream from a queue of values.
+ * Creates a stream that pulls values from a `Queue.Dequeue`.
  *
- * **Options**
+ * The stream emits non-empty batches of queued values and ends when the queue
+ * fails with `Cause.Done`; other queue failures are propagated.
  *
- * - `maxChunkSize`: The maximum number of queued elements to put in one chunk in the stream
- * - `shutdown`: If `true`, the queue will be shutdown after the stream is evaluated (defaults to `false`)
+ * **Example** (Creating a stream from a queue of values)
  *
- * @example
  * ```ts
  * import { Console, Effect, Queue, Stream } from "effect"
  *
@@ -932,14 +966,15 @@ export const fromArrays = (...arrays) => fromChannel(Channel.fromArray(Arr.filte
  * // Output: [ 1, 2, 3 ]
  * ```
  *
- * @since 4.0.0
- * @category Constructors
+ * @category constructors
+ * @since 2.0.0
  */
 export const fromQueue = queue => fromChannel(Channel.fromQueueArray(queue));
 /**
  * Creates a stream from a subscription to a `PubSub`.
  *
- * @example
+ * **Example** (Creating a stream from a subscription to a PubSub)
+ *
  * ```ts
  * import { Console, Effect, Fiber, PubSub, Stream } from "effect"
  *
@@ -964,8 +999,8 @@ export const fromQueue = queue => fromChannel(Channel.fromQueueArray(queue));
  * // Output: [ 1, 2, 3 ]
  * ```
  *
- * @since 4.0.0
- * @category Constructors
+ * @category constructors
+ * @since 2.0.0
  */
 export const fromPubSub = pubsub => fromChannel(Channel.fromPubSubArray(pubsub));
 /**
@@ -973,7 +1008,8 @@ export const fromPubSub = pubsub => fromChannel(Channel.fromPubSubArray(pubsub))
  *
  * `Take` values include end and failure signals.
  *
- * @example
+ * **Example** (Creating a stream from PubSub takes)
+ *
  * ```ts
  * import { Console, Effect, Exit, PubSub, Stream, Take } from "effect"
  *
@@ -994,16 +1030,19 @@ export const fromPubSub = pubsub => fromChannel(Channel.fromPubSubArray(pubsub))
  * // Output: [ 1, 2 ]
  * ```
  *
+ * @category constructors
  * @since 4.0.0
- * @category Constructors
  */
 export const fromPubSubTake = pubsub => fromChannel(Channel.fromPubSubTake(pubsub));
 /**
- * Creates a stream from a `ReadableStream`.
+ * Creates a stream from a lazily supplied Web `ReadableStream`.
  *
- * See https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream.
+ * The stream reads from a `ReadableStreamDefaultReader`, maps read failures
+ * with `onError`, and closes the reader when the stream finalizes. By default
+ * the reader is canceled; set `releaseLockOnEnd` to release the lock instead.
+ *
+ * **Example** (Creating a stream from a ReadableStream)
  *
- * @example
  * ```ts
  * import { Console, Data, Effect, Stream } from "effect"
  *
@@ -1031,8 +1070,8 @@ export const fromPubSubTake = pubsub => fromChannel(Channel.fromPubSubTake(pubsu
  * // Output: [ 1, 2, 3 ]
  * ```
  *
+ * @category constructors
  * @since 2.0.0
- * @category Constructors
  */
 export const fromReadableStream = options => fromChannel(Channel.fromTransform(Effect.fnUntraced(function* (_, scope) {
   const reader = options.evaluate().getReader();
@@ -1048,9 +1087,10 @@ export const fromReadableStream = options => fromChannel(Channel.fromTransform(E
 /**
  * Creates a stream from an AsyncIterable.
  *
- * @example
+ * **Example** (Creating a stream from an AsyncIterable)
+ *
  * ```ts
- * import { Console, Data, Effect, Stream } from "effect"
+ * import { Data, Effect, Stream } from "effect"
  *
  * class StreamError extends Data.TaggedError("StreamError")<{ readonly cause: unknown }> {}
  *
@@ -1060,25 +1100,25 @@ export const fromReadableStream = options => fromChannel(Channel.fromTransform(E
  *   yield 3
  * })()
  *
- * const program = Effect.gen(function*() {
+ * Effect.runPromise(Effect.gen(function*() {
  *   const stream = Stream.fromAsyncIterable(iterable, (cause) => new StreamError({ cause }))
  *   const values = yield* Stream.runCollect(stream)
- *   yield* Console.log(values)
- * })
+ *   yield* Effect.sync(() => console.log(values))
+ * }))
  *
- * Effect.runPromise(program)
- * // Output: [ 1, 2, 3 ]
+ * // [ 1, 2, 3 ]
  * ```
  *
+ * @category constructors
  * @since 2.0.0
- * @category Constructors
  */
 export const fromAsyncIterable = (iterable, onError) => fromChannel(Channel.fromAsyncIterableArray(iterable, onError));
 /**
  * Creates a stream that emits each output of a schedule that does not require input,
  * for as long as the schedule continues.
  *
- * @example
+ * **Example** (Creating a stream from a schedule)
+ *
  * ```ts
  * import { Console, Effect, Schedule, Stream } from "effect"
  *
@@ -1095,8 +1135,8 @@ export const fromAsyncIterable = (iterable, onError) => fromChannel(Channel.from
  * // Output: [ 0, 1, 2 ]
  * ```
  *
+ * @category constructors
  * @since 2.0.0
- * @category Constructors
  */
 export const fromSchedule = schedule => fromPull(Effect.map(Schedule.toStepWithSleep(schedule), step => Pull.catchDone(Effect.map(step(void 0), Arr.of), () => Cause.done())));
 /**
@@ -1105,7 +1145,8 @@ export const fromSchedule = schedule => fromPull(Effect.map(Schedule.toStepWithS
  * Use `PubSub.subscribe` to create the subscription and `Stream.take` or
  * cancellation to control how many values are consumed.
  *
- * @example
+ * **Example** (Creating a stream from a PubSub subscription)
+ *
  * ```ts
  * import { Console, Effect, PubSub, Stream } from "effect"
  *
@@ -1125,33 +1166,42 @@ export const fromSchedule = schedule => fromPull(Effect.map(Schedule.toStepWithS
  * // Output: [ 1, 2 ]
  * ```
  *
+ * @category constructors
  * @since 4.0.0
- * @category Constructors
  */
 export const fromSubscription = pubsub => fromChannel(Channel.fromSubscriptionArray(pubsub));
 /**
  * Creates a stream from an event listener.
  *
- * @example
+ * **Example** (Creating a stream from an event listener)
+ *
  * ```ts
- * import { Console, Effect, Stream } from "effect"
+ * import { Effect, Stream } from "effect"
  *
- * declare const target: Stream.EventListener<number>
+ * class NumberTarget implements Stream.EventListener<number> {
+ *   addEventListener(event: string, f: (event: number) => void) {
+ *     if (event === "data") {
+ *       f(1)
+ *       f(2)
+ *       f(3)
+ *     }
+ *   }
+ *   removeEventListener(_event: string, _f: (event: number) => void) {}
+ * }
  *
- * const program = Effect.gen(function*() {
- *   const stream = Stream.fromEventListener(target, "data").pipe(
+ * Effect.runPromise(Effect.gen(function*() {
+ *   const stream = Stream.fromEventListener(new NumberTarget(), "data").pipe(
  *     Stream.take(3)
  *   )
  *   const values = yield* Stream.runCollect(stream)
- *   yield* Console.log(values)
- * })
+ *   yield* Effect.sync(() => console.log(values))
+ * }))
  *
- * Effect.runPromise(program)
- * // Output: [ 1, 2, 3 ]
+ * // [ 1, 2, 3 ]
  * ```
  *
+ * @category constructors
  * @since 3.1.0
- * @category Constructors
  */
 export const fromEventListener = (target, type, options) => callback(queue => {
   function emit(event) {
@@ -1162,9 +1212,14 @@ export const fromEventListener = (target, type, options) => callback(queue => {
   bufferSize: typeof options === "object" ? options.bufferSize : undefined
 });
 /**
- * Creates a stream by peeling off successive layers of a state value.
+ * Creates a stream by repeatedly applying an effectful step function to a
+ * state.
+ *
+ * Each `readonly [value, nextState]` result emits `value` and continues with
+ * `nextState`; returning `undefined` ends the stream.
+ *
+ * **Example** (Unfolding stream state)
  *
- * @example
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -1178,8 +1233,8 @@ export const fromEventListener = (target, type, options) => callback(queue => {
  * // Output: [ 1, 2, 3, 4, 5 ]
  * ```
  *
+ * @category constructors
  * @since 2.0.0
- * @category Constructors
  */
 export const unfold = (s, f) => fromPull(Effect.sync(() => {
   let state = s;
@@ -1194,10 +1249,10 @@ export const unfold = (s, f) => fromPull(Effect.sync(() => {
  * than the unfolding of the state. This is useful for embedding paginated APIs,
  * hence the name.
  *
- * @example
+ * **Example** (Paginating stream state)
+ *
  * ```ts
- * import { Console, Effect, Stream } from "effect"
- * import * as Option from "effect/Option"
+ * import { Console, Effect, Option, Stream } from "effect"
  *
  * const stream = Stream.paginate(0, (n: number) =>
  *   Effect.succeed(
@@ -1211,8 +1266,8 @@ export const unfold = (s, f) => fromPull(Effect.sync(() => {
  * // Output: [ 0, 1, 2, 3 ]
  * ```
  *
+ * @category constructors
  * @since 2.0.0
- * @category Constructors
  */
 export const paginate = (s, f) => fromPull(Effect.sync(() => {
   let state = s;
@@ -1233,7 +1288,8 @@ export const paginate = (s, f) => fromPull(Effect.sync(() => {
 /**
  * Creates an infinite stream by repeatedly applying a function to a seed value.
  *
- * @example
+ * **Example** (Iterating from a seed value)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -1248,8 +1304,8 @@ export const paginate = (s, f) => fromPull(Effect.sync(() => {
  * // Output: [ 1, 2, 3 ]
  * ```
  *
+ * @category constructors
  * @since 2.0.0
- * @category Constructors
  */
 export const iterate = (value, next) => unfold(value, a => Effect.succeed([a, next(a)]));
 /**
@@ -1258,7 +1314,8 @@ export const iterate = (value, next) => unfold(value, a => Effect.succeed([a, ne
  * If the provided `min` is greater than `max`, the stream will not emit any
  * values.
  *
- * @example
+ * **Example** (Creating a numeric range)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -1270,8 +1327,8 @@ export const iterate = (value, next) => unfold(value, a => Effect.succeed([a, ne
  * Effect.runPromise(program)
  * // Output: [ 1, 2, 3, 4, 5 ]
  * ```
- * @since 4.0.0
- * @category Constructors
+ * @category constructors
+ * @since 2.0.0
  */
 export const range = (min, max, chunkSize = Channel.DefaultChunkSize) => min > max ? empty : fromPull(Effect.sync(() => {
   let start = min;
@@ -1292,7 +1349,8 @@ export const range = (min, max, chunkSize = Channel.DefaultChunkSize) => min > m
 /**
  * The stream that never produces any value or fails with any error.
  *
- * @example
+ * **Example** (Creating a never-ending stream)
+ *
  * ```ts
  * import { Effect, Stream } from "effect"
  *
@@ -1305,14 +1363,15 @@ export const range = (min, max, chunkSize = Channel.DefaultChunkSize) => min > m
  * // []
  * ```
  *
- * @since 4.0.0
- * @category Constructors
+ * @category constructors
+ * @since 2.0.0
  */
 export const never = /*#__PURE__*/fromChannel(Channel.never);
 /**
  * Creates a stream produced from an `Effect`.
  *
- * @example
+ * **Example** (Unwrapping a stream effect)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -1327,15 +1386,16 @@ export const never = /*#__PURE__*/fromChannel(Channel.never);
  * // [1, 2, 3]
  * ```
  *
+ * @category constructors
  * @since 2.0.0
- * @category Constructors
  */
 export const unwrap = effect => fromChannel(Channel.unwrap(Effect.map(effect, toChannel)));
 /**
  * Runs a stream that requires `Scope` in a managed scope, ensuring its
  * finalizers are run when the stream completes.
  *
- * @example
+ * **Example** (Scoping a stream)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -1354,14 +1414,15 @@ export const unwrap = effect => fromChannel(Channel.unwrap(Effect.map(effect, to
  * // [ "resource" ]
  * ```
  *
+ * @category constructors
  * @since 2.0.0
- * @category Constructors
  */
 export const scoped = self => fromChannel(Channel.scoped(self.channel));
 /**
  * Transforms the elements of this stream using the supplied function.
  *
- * @example
+ * **Example** (Mapping stream values)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -1374,8 +1435,8 @@ export const scoped = self => fromChannel(Channel.scoped(self.channel));
  * // [ 1, 3, 5 ]
  * ```
  *
+ * @category mapping
  * @since 2.0.0
- * @category Mapping
  */
 export const map = /*#__PURE__*/dual(2, (self, f) => suspend(() => {
   let i = 0;
@@ -1384,7 +1445,8 @@ export const map = /*#__PURE__*/dual(2, (self, f) => suspend(() => {
 /**
  * Maps both the failure and success channels of a stream.
  *
- * @example
+ * **Example** (Mapping both the failure and success channels of a stream)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -1413,20 +1475,15 @@ export const map = /*#__PURE__*/dual(2, (self, f) => suspend(() => {
  * // Output: [ "error: boom" ]
  * ```
  *
+ * @category mapping
  * @since 2.0.0
- * @category Mapping
  */
 export const mapBoth = /*#__PURE__*/dual(2, (self, options) => self.pipe(map(options.onSuccess), mapError(options.onFailure)));
 /**
  * Transforms each emitted chunk using the provided function, which receives the chunk and its index.
  *
- * **Previously Known As**
- *
- * This API replaces the following from Effect 3.x:
+ * **Example** (Mapping stream chunks)
  *
- * - `Stream.mapChunks`
- *
- * @example
  * ```ts
  * import { Array, Console, Effect, Stream } from "effect"
  *
@@ -1443,14 +1500,15 @@ export const mapBoth = /*#__PURE__*/dual(2, (self, options) => self.pipe(map(opt
  * // Output: [ 1, 2, 4, 5 ]
  * ```
  *
- * @since 2.0.0
- * @category Mapping
+ * @category mapping
+ * @since 4.0.0
  */
 export const mapArray = /*#__PURE__*/dual(2, (self, f) => fromChannel(Channel.map(self.channel, f)));
 /**
  * Maps over elements of the stream with the specified effectful function.
  *
- * @example
+ * **Example** (Effectfully mapping stream values)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -1478,14 +1536,15 @@ export const mapArray = /*#__PURE__*/dual(2, (self, f) => fromChannel(Channel.ma
  * // [2, 4, 6]
  * ```
  *
+ * @category mapping
  * @since 2.0.0
- * @category Mapping
  */
 export const mapEffect = /*#__PURE__*/dual(args => isStream(args[0]), (self, f, options) => self.channel.pipe(Channel.flattenArray, Channel.mapEffect(f, options), Channel.map(Arr.of), fromChannel));
 /**
  * Flattens a stream of `Effect` values into a stream of their results.
  *
- * @example
+ * **Example** (Flattening a stream of Effect values into a stream of their results)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -1500,20 +1559,15 @@ export const mapEffect = /*#__PURE__*/dual(args => isStream(args[0]), (self, f,
  * // Output: [1, 2, 3]
  * ```
  *
+ * @category mapping
  * @since 2.0.0
- * @category Mapping
  */
 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.
  *
- * **Previously Known As**
- *
- * This API replaces the following from Effect 3.x:
+ * **Example** (Effectfully mapping stream chunks)
  *
- * - `Stream.mapChunksEffect`
- *
- * @example
  * ```ts
  * import { Array, Console, Effect, Stream } from "effect"
  *
@@ -1532,8 +1586,8 @@ export const flattenEffect = /*#__PURE__*/dual(args => isStream(args[0]), (self,
  * // Output: [1, 2, 13, 14]
  * ```
  *
+ * @category mapping
  * @since 4.0.0
- * @category Mapping
  */
 export const mapArrayEffect = /*#__PURE__*/dual(2, (self, f) => fromChannel(Channel.mapEffect(self.channel, f)));
 /**
@@ -1541,13 +1595,8 @@ export const mapArrayEffect = /*#__PURE__*/dual(2, (self, f) => fromChannel(Chan
  *
  * The stream ends after the first failure, emitting a `Result.fail` value.
  *
- * **Previously Known As:**
- *
- * This API replaces the following from Effect 3.x:
+ * **Example** (Converting failures to results)
  *
- * - `Stream.either`
- *
- * @example
  * ```ts
  * import { Console, Effect, Result, Stream } from "effect"
  *
@@ -1568,14 +1617,15 @@ export const mapArrayEffect = /*#__PURE__*/dual(2, (self, f) => fromChannel(Chan
  * // Output: [ "success: 1", "success: 2", "failure: boom" ]
  * ```
  *
+ * @category error handling
  * @since 4.0.0
- * @category Error Handling
  */
 export const result = self => self.pipe(map(Result.succeed), catch_(e => succeed(Result.fail(e))));
 /**
  * Runs the provided effect for each element while preserving the elements.
  *
- * @example
+ * **Example** (Tapping stream values)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -1601,14 +1651,15 @@ export const result = self => self.pipe(map(Result.succeed), catch_(e => succeed
  * // [ 2, 4, 6 ]
  * ```
  *
+ * @category sequencing
  * @since 2.0.0
- * @category Sequencing
  */
 export const tap = /*#__PURE__*/dual(args => isStream(args[0]), (self, f, options) => mapEffect(self, a => Effect.as(f(a), a), options));
 /**
  * Returns a stream that effectfully "peeks" at elements and failures.
  *
- * @example
+ * **Example** (Tapping values and errors)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -1633,8 +1684,8 @@ export const tap = /*#__PURE__*/dual(args => isStream(args[0]), (self, f, option
  * // [ 1, 2, 3 ]
  * ```
  *
+ * @category sequencing
  * @since 2.0.0
- * @category Sequencing
  */
 export const tapBoth = /*#__PURE__*/dual(2, (self, options) => self.pipe(tapError(options.onError), tap(options.onElement, {
   concurrency: options.concurrency
@@ -1643,7 +1694,8 @@ export const tapBoth = /*#__PURE__*/dual(2, (self, options) => self.pipe(tapErro
  * Sends all elements emitted by this stream to the specified sink in addition
  * to emitting them.
  *
- * @example
+ * **Example** (Tapping values with a sink)
+ *
  * ```ts
  * import { Console, Effect, Ref, Sink, Stream } from "effect"
  *
@@ -1666,8 +1718,8 @@ export const tapBoth = /*#__PURE__*/dual(2, (self, options) => self.pipe(tapErro
  * // Output: [1, 2, 3]
  * ```
  *
+ * @category sequencing
  * @since 2.0.0
- * @category Sequencing
  */
 export const tapSink = /*#__PURE__*/dual(2, (self, sink) => transformPullBracket(self, Effect.fnUntraced(function* (pull, _, scope) {
   const upstreamLatch = Latch.makeUnsafe();
@@ -1713,9 +1765,15 @@ export const tapSink = /*#__PURE__*/dual(2, (self, sink) => transformPullBracket
   });
 })));
 /**
- * Maps each element to a stream and concatenates the results in order.
+ * Maps each element to a stream and flattens the resulting streams.
+ *
+ * With the default sequential concurrency, inner streams are concatenated in
+ * input order. When `concurrency` is greater than `1` or `"unbounded"`,
+ * multiple inner streams may run at the same time and their outputs are merged
+ * as they arrive.
+ *
+ * **Example** (FlatMapping stream values)
  *
- * @example
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -1731,15 +1789,16 @@ export const tapSink = /*#__PURE__*/dual(2, (self, sink) => transformPullBracket
  * // Output: [ 1, 2, 2, 4, 3, 6 ]
  * ```
  *
+ * @category mapping
  * @since 2.0.0
- * @category Mapping
  */
 export const flatMap = /*#__PURE__*/dual(args => isStream(args[0]), (self, f, options) => self.channel.pipe(Channel.flattenArray, Channel.flatMap(a => f(a).channel, options), fromChannel));
 /**
  * Switches to the latest stream produced by the mapping function, interrupting
  * the previous stream when a new element arrives.
  *
- * @example
+ * **Example** (Switching to the latest stream)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -1755,15 +1814,20 @@ export const flatMap = /*#__PURE__*/dual(args => isStream(args[0]), (self, f, op
  * })
  * ```
  *
+ * @category sequencing
  * @since 4.0.0
- * @category Sequencing
  */
 export const switchMap = /*#__PURE__*/dual(args => isStream(args[0]), (self, f, options) => self.channel.pipe(Channel.flattenArray, Channel.switchMap(a => f(a).channel, options), fromChannel));
 /**
- * Flattens a stream of streams into a single stream by concatenating the
- * inner streams in strict order.
+ * Flattens a stream of streams into a single stream.
+ *
+ * With the default sequential concurrency, inner streams are concatenated in
+ * strict order. When `concurrency` is greater than `1` or `"unbounded"`,
+ * multiple inner streams may run at the same time and their outputs are merged
+ * as they arrive.
+ *
+ * **Example** (Flattening nested streams)
  *
- * @example
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -1782,20 +1846,15 @@ export const switchMap = /*#__PURE__*/dual(args => isStream(args[0]), (self, f,
  * // Output: [ 1, 2, 3, 4, 5, 6 ]
  * ```
  *
+ * @category mapping
  * @since 2.0.0
- * @category Mapping
  */
 export const flatten = /*#__PURE__*/dual(args => isStream(args[0]), (self, options) => flatMap(self, identity, options));
 /**
  * Flattens a stream of non-empty arrays into a stream of elements.
  *
- * **Previously Known As**
- *
- * This API replaces the following from Effect 3.x:
+ * **Example** (Flattening a stream of non-empty arrays into a stream of elements)
  *
- * - `Stream.flattenChunks`
- *
- * @example
  * ```ts
  * import { Array, Console, Effect, Stream } from "effect"
  *
@@ -1810,14 +1869,15 @@ export const flatten = /*#__PURE__*/dual(args => isStream(args[0]), (self, optio
  * // Output: [ 1, 2, 3 ]
  * ```
  *
+ * @category sequencing
  * @since 4.0.0
- * @category Sequencing
  */
 export const flattenArray = self => fromChannel(Channel.flattenArray(self.channel));
 /**
  * Converts this stream to one that runs its effects but emits no elements.
  *
- * @example
+ * **Example** (Draining stream values)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -1830,15 +1890,16 @@ export const flattenArray = self => fromChannel(Channel.flattenArray(self.channe
  * // Output: []
  * ```
  *
+ * @category sequencing
  * @since 2.0.0
- * @category Sequencing
  */
 export const drain = self => fromChannel(Channel.drain(self.channel));
 /**
  * Runs the provided stream in the background while this stream runs, interrupting it
  * when this stream completes and failing if the background stream fails or defects.
  *
- * @example
+ * **Example** (Draining a stream in the background)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -1858,14 +1919,15 @@ export const drain = self => fromChannel(Channel.drain(self.channel));
  * // Output: [ 1, 2 ]
  * ```
  *
+ * @category sequencing
  * @since 2.0.0
- * @category Sequencing
  */
 export const drainFork = /*#__PURE__*/dual(2, (self, that) => mergeEffect(self, runDrain(that)));
 /**
  * Repeats the entire stream according to the provided schedule.
  *
- * @example
+ * **Example** (Repeating a stream on a schedule)
+ *
  * ```ts
  * import { Console, Effect, Schedule, Stream } from "effect"
  *
@@ -1882,14 +1944,15 @@ export const drainFork = /*#__PURE__*/dual(2, (self, that) => mergeEffect(self,
  * // Output: [ 1, 1, 1, 1, 1 ]
  * ```
  *
+ * @category sequencing
  * @since 2.0.0
- * @category Sequencing
  */
 export const repeat = /*#__PURE__*/dual(2, (self, schedule) => fromChannel(Channel.repeat(self.channel, schedule)));
 /**
  * Spaces the stream's elements according to the provided `schedule`.
  *
- * @example
+ * **Example** (Scheduling stream elements)
+ *
  * ```ts
  * import { Console, Effect, Schedule, Stream } from "effect"
  *
@@ -1906,14 +1969,15 @@ export const repeat = /*#__PURE__*/dual(2, (self, schedule) => fromChannel(Chann
  * // Output: [ 1, 2, 3 ]
  * ```
  *
- * @since 2.0.0
  * @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));
 /**
  * Ends the stream if it does not produce a value within the specified duration.
  *
- * @example
+ * **Example** (Timing out a stream)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -1930,16 +1994,23 @@ export const schedule = /*#__PURE__*/dual(2, (self, schedule) => self.channel.pi
  * // Output: [ 1 ]
  * ```
  *
- * @since 2.0.0
  * @category Rate Limiting
+ * @since 2.0.0
  */
 export const timeout = /*#__PURE__*/dual(2, (self, duration) => timeoutOrElse(self, {
   duration,
   orElse: () => empty
 }));
 /**
- * @since 2.0.0
+ * Switches to a fallback stream if this stream does not emit a value within
+ * the specified duration.
+ *
+ * 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
+ * @since 4.0.0
  */
 export const timeoutOrElse = /*#__PURE__*/dual(2, (self, options) => {
   const duration = Duration.fromInputUnsafe(options.duration);
@@ -1983,9 +2054,8 @@ export const timeoutOrElse = /*#__PURE__*/dual(2, (self, options) => {
  * Repeats each element of the stream according to the provided schedule,
  * including the original emission.
  *
- * @since 2.0.0
- * @category Sequencing
- * @example
+ * **Example** (Repeating stream elements)
+ *
  * ```ts
  * import { Console, Effect, Schedule, Stream } from "effect"
  *
@@ -2000,6 +2070,9 @@ export const timeoutOrElse = /*#__PURE__*/dual(2, (self, options) => {
  * Effect.runPromise(program)
  * // Output: [ "A", "A", "B", "B", "C", "C" ]
  * ```
+ *
+ * @category sequencing
+ * @since 2.0.0
  */
 export const repeatElements = /*#__PURE__*/dual(2, (self, schedule) => fromChannel(Channel.fromTransform((upstream, scope) => Effect.map(Channel.toTransform(Channel.flattenArray(self.channel))(upstream, scope), pullElement => {
   let pullRepeat = undefined;
@@ -2018,7 +2091,8 @@ export const repeatElements = /*#__PURE__*/dual(2, (self, schedule) => fromChann
 /**
  * Repeats this stream forever.
  *
- * @example
+ * **Example** (Repeating a stream forever)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -2036,20 +2110,15 @@ export const repeatElements = /*#__PURE__*/dual(2, (self, schedule) => fromChann
  * // Output: [ "A", "B", "A", "B", "A" ]
  * ```
  *
+ * @category sequencing
  * @since 2.0.0
- * @category Sequencing
  */
 export const forever = self => fromChannel(Channel.forever(self.channel));
 /**
  * Submerges the iterables emitted by this stream into the stream's structure.
  *
- * **Previously Known As**
- *
- * This API replaces the following from Effect 3.x:
+ * **Example** (Flattening iterable values)
  *
- * - `Stream.flattenIterables`
- *
- * @example
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -2063,15 +2132,16 @@ export const forever = self => fromChannel(Channel.forever(self.channel));
  * // Output: [ 1, 2, 3, 4 ]
  * ```
  *
+ * @category mapping
  * @since 4.0.0
- * @category Mapping
  */
 export const flattenIterable = self => flatMap(self, fromIterable);
 /**
  * Unwraps `Take` values, emitting elements from non-empty arrays and ending or
  * failing when the `Exit` signals completion.
  *
- * @example
+ * **Example** (Flattening Take values)
+ *
  * ```ts
  * import { Array, Console, Effect, Exit, Stream } from "effect"
  *
@@ -2090,15 +2160,16 @@ export const flattenIterable = self => flatMap(self, fromIterable);
  * // Output: [ 1, 2, 3 ]
  * ```
  *
- * @since 4.0.0
- * @category Sequencing
+ * @category sequencing
+ * @since 2.0.0
  */
 export const flattenTake = self => self.channel.pipe(Channel.flattenArray, Channel.flattenTake, fromChannel);
 /**
  * Concatenates two streams, emitting all elements from the first stream
  * followed by all elements from the second stream.
  *
- * @example
+ * **Example** (Concatenating streams)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -2111,14 +2182,15 @@ export const flattenTake = self => self.channel.pipe(Channel.flattenArray, Chann
  * // Output: [ 1, 2, 3, 4, 5, 6 ]
  * ```
  *
+ * @category sequencing
  * @since 2.0.0
- * @category Sequencing
  */
 export const concat = /*#__PURE__*/dual(2, (self, that) => flatten(fromArray([self, that])));
 /**
  * Prepends the values from the provided iterable before the stream's elements.
  *
- * @example
+ * **Example** (Prepending values)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -2135,8 +2207,8 @@ export const concat = /*#__PURE__*/dual(2, (self, that) => flatten(fromArray([se
  * Effect.runPromise(program)
  * ```
  *
+ * @category sequencing
  * @since 2.0.0
- * @category Sequencing
  */
 export const prepend = /*#__PURE__*/dual(2, (self, values) => concat(fromIterable(values), self));
 /**
@@ -2145,7 +2217,8 @@ export const prepend = /*#__PURE__*/dual(2, (self, values) => concat(fromIterabl
  * By default, the merged stream ends when both streams end. Use
  * `haltStrategy` to change the termination behavior.
  *
- * @example
+ * **Example** (Merging stream values)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -2161,8 +2234,8 @@ export const prepend = /*#__PURE__*/dual(2, (self, values) => concat(fromIterabl
  * // Output: [ 1, 2, 3, 4 ]
  * ```
  *
- * @since 2.0.0
  * @category Merging
+ * @since 2.0.0
  */
 export const merge = /*#__PURE__*/dual(args => isStream(args[0]) && isStream(args[1]), (self, that, options) => fromChannel(Channel.merge(toChannel(self), toChannel(that), options)));
 /**
@@ -2171,9 +2244,8 @@ export const merge = /*#__PURE__*/dual(args => isStream(args[0]) && isStream(arg
  * The effect runs concurrently, fails the stream if it fails, and is interrupted
  * when the stream completes.
  *
- * @since 4.0.0
- * @category Merging
- * @example
+ * **Example** (Merging with a background effect)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -2190,19 +2262,17 @@ export const merge = /*#__PURE__*/dual(args => isStream(args[0]) && isStream(arg
  * // Output: side task
  * // Output: [ 1, 2, 3 ]
  * ```
+ *
+ * @category Merging
+ * @since 4.0.0
  */
 export const mergeEffect = /*#__PURE__*/dual(2, (self, effect) => self.channel.pipe(Channel.mergeEffect(effect), fromChannel));
 /**
  * Merges this stream and the specified stream together, tagging values from the
  * left stream as `Result.succeed` and values from the right stream as `Result.fail`.
  *
- * **Previously Known As**
- *
- * This API replaces the following from Effect 3.x:
+ * **Example** (Merging streams into results)
  *
- * - `Stream.mergeEither`
- *
- * @example
  * ```ts
  * import { Console, Effect, Result, Stream } from "effect"
  *
@@ -2228,8 +2298,8 @@ export const mergeEffect = /*#__PURE__*/dual(2, (self, effect) => self.channel.p
  * // Output: [ "left:left", "right:right" ]
  * ```
  *
- * @since 2.0.0
  * @category Merging
+ * @since 4.0.0
  */
 export const mergeResult = /*#__PURE__*/dual(2, (self, that) => merge(map(self, Result.succeed), map(that, Result.fail)));
 /**
@@ -2239,7 +2309,8 @@ export const mergeResult = /*#__PURE__*/dual(2, (self, that) => merge(map(self,
  * stream are propagated. The merged stream completes when the left stream
  * completes, interrupting the right stream.
  *
- * @example
+ * **Example** (Merging streams while keeping left values)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -2254,8 +2325,8 @@ export const mergeResult = /*#__PURE__*/dual(2, (self, that) => merge(map(self,
  * // Output: [ 1, 2 ]
  * ```
  *
- * @since 2.0.0
  * @category Merging
+ * @since 2.0.0
  */
 export const mergeLeft = /*#__PURE__*/dual(2, (left, right) => mergeEffect(left, runDrain(right)));
 /**
@@ -2265,7 +2336,8 @@ export const mergeLeft = /*#__PURE__*/dual(2, (left, right) => mergeEffect(left,
  * The merged stream ends when the right stream completes, interrupting the
  * left stream. Failures from the left stream still fail the merged stream.
  *
- * @example
+ * **Example** (Merging streams while keeping right values)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -2285,17 +2357,18 @@ export const mergeLeft = /*#__PURE__*/dual(2, (left, right) => mergeEffect(left,
  * // Output: [ 1, 2 ]
  * ```
  *
- * @since 2.0.0
  * @category Merging
+ * @since 2.0.0
  */
 export const mergeRight = /*#__PURE__*/dual(2, (left, right) => mergeEffect(right, runDrain(left)));
 /**
  * Merges a collection of streams, running up to the specified number concurrently.
  *
- * @since 2.0.0
  * @category Merging
+ * @since 2.0.0
+ *
+ * **Example** (Merging streams with bounded concurrency)
  *
- * @example
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -2322,7 +2395,8 @@ export const mergeAll = /*#__PURE__*/dual(2, (streams, options) => flatten(fromI
  *
  * See also `Stream.zip` for the more common point-wise variant.
  *
- * @example
+ * **Example** (Computing cartesian products)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -2337,8 +2411,8 @@ export const mergeAll = /*#__PURE__*/dual(2, (streams, options) => flatten(fromI
  * // Output: [ [ 1, "a" ], [ 1, "b" ], [ 2, "a" ], [ 2, "b" ] ]
  * ```
  *
+ * @category zipping
  * @since 2.0.0
- * @category Zipping
  */
 export const cross = /*#__PURE__*/dual(2, (left, right) => crossWith(left, right, (l, r) => [l, r]));
 /**
@@ -2348,7 +2422,8 @@ export const cross = /*#__PURE__*/dual(2, (left, right) => crossWith(left, right
  *
  * See also `Stream.zipWith` for the more common point-wise variant.
  *
- * @example
+ * **Example** (Combining cartesian products)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -2364,14 +2439,15 @@ export const cross = /*#__PURE__*/dual(2, (left, right) => crossWith(left, right
  * // Output: [ "1-a", "1-b", "2-a", "2-b" ]
  * ```
  *
+ * @category zipping
  * @since 2.0.0
- * @category Zipping
  */
 export const crossWith = /*#__PURE__*/dual(3, (left, right, f) => flatMap(left, l => map(right, r => f(l, r))));
 /**
  * Zips two streams point-wise with a combining function, ending when either stream ends.
  *
- * @example
+ * **Example** (Zipping streams with a function)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -2389,8 +2465,8 @@ export const crossWith = /*#__PURE__*/dual(3, (left, right, f) => flatMap(left,
  * // Output: [ "1-a", "2-b", "3-c" ]
  * ```
  *
+ * @category zipping
  * @since 2.0.0
- * @category Zipping
  */
 export const zipWith = /*#__PURE__*/dual(3, (left, right, f) => zipWithArray(left, right, zipArrays(f)));
 const zipArrays = f => (leftArr, rightArr) => {
@@ -2406,13 +2482,8 @@ const zipArrays = f => (leftArr, rightArr) => {
  *
  * The function returns output plus leftover arrays that carry into the next pull.
  *
- * **Previously Known As**
- *
- * This API replaces the following from Effect 3.x:
+ * **Example** (Zipping stream chunks)
  *
- * - `Stream.zipWithChunks`
- *
- * @example
  * ```ts
  * import { Array, Console, Effect, Stream } from "effect"
  *
@@ -2435,8 +2506,8 @@ const zipArrays = f => (leftArr, rightArr) => {
  * // Output: [[1, "a"], [2, "b"], [3, "c"], [4, "d"], [5, "e"]]
  * ```
  *
- * @since 2.0.0
- * @category Zipping
+ * @category zipping
+ * @since 4.0.0
  */
 export const zipWithArray = /*#__PURE__*/dual(3, (left, right, f) => fromChannel(Channel.fromTransformBracket(Effect.fnUntraced(function* (_, scope) {
   const pullLeft = yield* Channel.toPullScoped(left.channel, scope);
@@ -2475,7 +2546,8 @@ export const zipWithArray = /*#__PURE__*/dual(3, (left, right, f) => fromChannel
  * Zips this stream with another point-wise and emits tuples of elements from
  * both streams. The new stream ends when either stream ends.
  *
- * @example
+ * **Example** (Zipping streams)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -2493,8 +2565,8 @@ export const zipWithArray = /*#__PURE__*/dual(3, (left, right, f) => fromChannel
  * // Output: [[1, "a"], [2, "b"], [3, "c"]]
  * ```
  *
+ * @category zipping
  * @since 2.0.0
- * @category Zipping
  */
 export const zip = /*#__PURE__*/dual(2, (self, that) => zipWith(self, that, (a, a2) => [a, a2]));
 /**
@@ -2503,7 +2575,8 @@ export const zip = /*#__PURE__*/dual(2, (self, that) => zipWith(self, that, (a,
  *
  * The resulting stream ends when either side ends.
  *
- * @example
+ * **Example** (Zipping streams while keeping left values)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -2519,8 +2592,8 @@ export const zip = /*#__PURE__*/dual(2, (self, that) => zipWith(self, that, (a,
  * // Output: [1, 2]
  * ```
  *
+ * @category zipping
  * @since 2.0.0
- * @category Zipping
  */
 export const zipLeft = /*#__PURE__*/dual(2, (left, right) => zipWithArray(left, right, (leftArr, rightArr) => {
   const minLength = Math.min(leftArr.length, rightArr.length);
@@ -2532,7 +2605,8 @@ export const zipLeft = /*#__PURE__*/dual(2, (left, right) => zipWithArray(left,
 /**
  * Zips this stream with another point-wise, keeping only right values and ending when either stream ends.
  *
- * @example
+ * **Example** (Zipping streams while keeping right values)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -2548,8 +2622,8 @@ export const zipLeft = /*#__PURE__*/dual(2, (left, right) => zipWithArray(left,
  * // Output: ["a", "b"]
  * ```
  *
+ * @category zipping
  * @since 2.0.0
- * @category Zipping
  */
 export const zipRight = /*#__PURE__*/dual(2, (left, right) => zipWithArray(left, right, (leftArr, rightArr) => {
   const minLength = Math.min(leftArr.length, rightArr.length);
@@ -2564,7 +2638,8 @@ export const zipRight = /*#__PURE__*/dual(2, (left, right) => zipWithArray(left,
  *
  * The new stream will end when one of the sides ends.
  *
- * @example
+ * **Example** (Zipping and flattening tuples)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -2584,14 +2659,15 @@ export const zipRight = /*#__PURE__*/dual(2, (left, right) => zipWithArray(left,
  * // Output: [[1, "a", "x"], [2, "b", "y"], [3, "c", "z"]]
  * ```
  *
+ * @category zipping
  * @since 2.0.0
- * @category Zipping
  */
 export const zipFlatten = /*#__PURE__*/dual(2, (self, that) => zipWith(self, that, (a, a2) => [...a, a2]));
 /**
  * Zips this stream together with the index of elements.
  *
- * @example
+ * **Example** (Zipping elements with indices)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -2607,15 +2683,16 @@ export const zipFlatten = /*#__PURE__*/dual(2, (self, that) => zipWith(self, tha
  * // Output: [["a", 0], ["b", 1], ["c", 2], ["d", 3]]
  * ```
  *
+ * @category zipping
  * @since 2.0.0
- * @category Zipping
  */
 export const zipWithIndex = self => map(self, (a, i) => [a, i]);
 /**
  * Zips each element with the next element, pairing the final element with
  * `Option.none()`.
  *
- * @example
+ * **Example** (Zipping elements with next values)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -2633,8 +2710,8 @@ export const zipWithIndex = self => map(self, (a, i) => [a, i]);
  * // ]
  * ```
  *
+ * @category zipping
  * @since 2.0.0
- * @category Zipping
  */
 export const zipWithNext = self => mapAccumArray(self, Option.none, (acc, arr) => {
   let i = 0;
@@ -2657,7 +2734,8 @@ export const zipWithNext = self => mapAccumArray(self, Option.none, (acc, arr) =
 /**
  * Zips each element with its previous element, starting with `None`.
  *
- * @example
+ * **Example** (Zipping elements with previous values)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -2677,8 +2755,8 @@ export const zipWithNext = self => mapAccumArray(self, Option.none, (acc, arr) =
  * // ]
  * ```
  *
+ * @category zipping
  * @since 2.0.0
- * @category Zipping
  */
 export const zipWithPrevious = self => mapAccumArray(self, Option.none, (acc, arr) => {
   const pairs = Arr.empty();
@@ -2692,7 +2770,8 @@ export const zipWithPrevious = self => mapAccumArray(self, Option.none, (acc, ar
 /**
  * Zips each element with its previous and next values.
  *
- * @example
+ * **Example** (Zipping elements with neighbors)
+ *
  * ```ts
  * import { Console, Effect, Option, Stream } from "effect"
  *
@@ -2708,8 +2787,8 @@ export const zipWithPrevious = self => mapAccumArray(self, Option.none, (acc, ar
  * // Output: [ [Option.none(), 1, Option.some(2)], [Option.some(1), 2, Option.some(3)], [Option.some(2), 3, Option.none()] ]
  * ```
  *
+ * @category zipping
  * @since 2.0.0
- * @category Zipping
  */
 export const zipWithPreviousAndNext = self => mapAccumArray(self, () => ({
   prev: Option.none(),
@@ -2746,7 +2825,8 @@ export const zipWithPreviousAndNext = self => mapAccumArray(self, () => ({
  * that emitted elements that are not the last value in arrays will never be
  * used for zipping.
  *
- * @example
+ * **Example** (Zipping latest values from many streams)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -2765,8 +2845,8 @@ export const zipWithPreviousAndNext = self => mapAccumArray(self, () => ({
  * // Output: [ [ 1, "a", true ], [ 2, "a", true ], [ 3, "a", true ], [ 3, "b", true ], [ 3, "c", true ], [ 3, "c", false ], [ 3, "c", true ] ]
  * ```
  *
- * @since 2.0.0
- * @category Zipping
+ * @category zipping
+ * @since 3.3.0
  */
 export const zipLatestAll = (...streams) => fromChannel(Channel.suspend(() => {
   const latest = [];
@@ -2794,7 +2874,8 @@ export const zipLatestAll = (...streams) => fromChannel(Channel.suspend(() => {
  * that emitted elements that are not the last value in arrays will never be
  * used for zipping.
  *
- * @example
+ * **Example** (Zipping latest values)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -2809,8 +2890,8 @@ export const zipLatestAll = (...streams) => fromChannel(Channel.suspend(() => {
  * // Output: [ [1, "a"] ]
  * ```
  *
+ * @category zipping
  * @since 2.0.0
- * @category Zipping
  */
 export const zipLatest = /*#__PURE__*/dual(2, (left, right) => zipLatestAll(left, right));
 /**
@@ -2821,7 +2902,8 @@ export const zipLatest = /*#__PURE__*/dual(2, (left, right) => zipLatestAll(left
  * that emitted elements that are not the last value in arrays will never be
  * used for zipping.
  *
- * @example
+ * **Example** (Zipping latest values with a function)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -2840,17 +2922,23 @@ export const zipLatest = /*#__PURE__*/dual(2, (left, right) => zipLatestAll(left
  * })
  * ```
  *
+ * @category zipping
  * @since 2.0.0
- * @category Zipping
  */
 export const zipLatestWith = /*#__PURE__*/dual(3, (left, right, f) => map(zipLatestAll(left, right), ([a, a2]) => f(a, a2)));
 /**
- * Races multiple streams and emits values from the first stream to produce a value, interrupting the rest.
+ * Runs all streams concurrently until one stream emits its first value, then
+ * mirrors that winning stream and interrupts the rest.
+ *
+ * Failures or completion from losing streams before a winner is chosen are
+ * ignored unless every stream fails or completes before emitting. After a
+ * winner is chosen, that stream's later failures are propagated.
  *
- * @since 3.7.0
  * @category Racing
+ * @since 3.5.0
+ *
+ * **Example** (Racing multiple streams)
  *
- * @example
  * ```ts
  * import { Console, Effect, Schedule, Stream } from "effect"
  *
@@ -2884,10 +2972,15 @@ export const raceAll = (...streams) => fromChannel(Channel.fromTransform((_, sco
   return Effect.suspend(() => winner ?? race);
 })));
 /**
- * Returns a stream that mirrors the first upstream to emit an item.
- * As soon as one stream emits, the other is interrupted and failures propagate.
+ * Runs both streams concurrently until one stream emits its first value, then
+ * mirrors that winning stream and interrupts the other.
+ *
+ * A failure or completion from one side before the other side emits does not
+ * win the race unless both sides fail or complete before emitting. After a
+ * winner is chosen, that stream's later failures are propagated.
+ *
+ * **Example** (Racing two streams)
  *
- * @example
  * ```ts
  * import { Console, Effect, Schedule, Stream } from "effect"
  *
@@ -2905,14 +2998,15 @@ export const raceAll = (...streams) => fromChannel(Channel.fromTransform((_, sco
  * // Output: [ 0, 1, 2 ]
  * ```
  *
- * @since 3.7.0
  * @category Racing
+ * @since 3.7.0
  */
 export const race = /*#__PURE__*/dual(2, (left, right) => raceAll(left, right));
 /**
  * Filters a stream to the elements that satisfy a predicate.
  *
- * @example
+ * **Example** (Filtering stream values)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -2928,21 +3022,22 @@ export const race = /*#__PURE__*/dual(2, (left, right) => raceAll(left, right));
  * // Output: [ 2, 4 ]
  * ```
  *
+ * @category filtering
  * @since 2.0.0
- * @category Filtering
  */
 export const filter = /*#__PURE__*/dual(2, (self, predicate) => fromChannel(Channel.filterArray(toChannel(self), predicate)));
 /**
  * Filters and maps stream elements in one pass using a `Filter`.
  *
- * @since 4.0.0
- * @category Filtering
+ * @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.
  *
- * @example
+ * **Example** (Effectfully filtering stream values)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -2957,23 +3052,27 @@ export const filterMap = /*#__PURE__*/dual(2, (self, filter) => fromChannel(Chan
  * // Output: [ 3, 4 ]
  * ```
  *
+ * @category filtering
  * @since 2.0.0
- * @category Filtering
  */
 export const filterEffect = /*#__PURE__*/dual(2, (self, predicate) => fromChannel(Channel.filterArrayEffect(toChannel(self), predicate)));
 /**
  * Effectfully filters and maps elements in a single pass.
  *
- * @since 4.0.0
- * @category Filtering
+ * @category filtering
+ * @since 2.0.0
  */
 export const filterMapEffect = /*#__PURE__*/dual(2, (self, filter) => fromChannel(Channel.filterMapArrayEffect(toChannel(self), filter)));
 /**
- * Partitions a stream using a `Filter` and exposes passing and failing values as queues.
+ * Partitions a stream using a `Filter` and exposes passing and failing values
+ * as scoped queues.
  *
- * Each queue fails with the stream error or `Cause.Done` when the source ends.
+ * The queues are backed by a fiber in the current scope and should be consumed
+ * while that scope remains open. Each queue fails with the stream error or
+ * `Cause.Done` when the source ends.
+ *
+ * **Example** (Partitioning a stream into queues)
  *
- * @example
  * ```ts
  * import { Console, Effect, Result, Stream } from "effect"
  *
@@ -2994,8 +3093,8 @@ export const filterMapEffect = /*#__PURE__*/dual(2, (self, filter) => fromChanne
  * Effect.runPromise(Effect.scoped(program))
  * ```
  *
+ * @category filtering
  * @since 4.0.0
- * @category Filtering
  */
 export const partitionQueue = /*#__PURE__*/dual(args => isStream(args[0]), /*#__PURE__*/Effect.fnUntraced(function* (self, filter, options) {
   const scope = yield* Effect.scope;
@@ -3043,22 +3142,30 @@ export const partitionQueue = /*#__PURE__*/dual(args => isStream(args[0]), /*#__
   return [passes, fails];
 }));
 /**
- * Splits a stream using an effectful `Filter`, producing pass and fail streams.
+ * Splits a stream with an effectful `Filter`, returning scoped streams for
+ * filter successes and failures.
+ *
+ * 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.
  *
+ * @category filtering
  * @since 4.0.0
- * @category Filtering
  */
 export const partitionEffect = /*#__PURE__*/dual(args => isStream(args[0]), (self, filter, options) => Effect.map(partitionQueue(mapEffect(self, a => filter(a), options), result => result, options), ([passes, fails]) => [fromQueue(passes), fromQueue(fails)]));
 /**
- * Splits a stream into excluded and satisfying substreams using a `Filter`.
+ * Splits a stream into scoped excluded and satisfying substreams using a
+ * `Filter`.
  *
- * The faster stream may advance up to `bufferSize` elements ahead of the slower
- * one.
+ * The returned streams are backed by queues in the current scope and should be
+ * consumed while that scope remains open. The faster stream may advance up to
+ * `bufferSize` elements ahead of the slower one.
  *
- * @since 4.0.0
- * @category Filtering
+ * @category filtering
+ * @since 2.0.0
+ *
+ * **Example** (Partitioning a stream)
  *
- * @example
  * ```ts
  * import { Console, Effect, Result, Stream } from "effect"
  *
@@ -3083,7 +3190,8 @@ export const partition = /*#__PURE__*/dual(args => isStream(args[0]), (self, fil
  * Returns the specified stream if the given condition is satisfied, otherwise
  * returns an empty stream.
  *
- * @example
+ * **Example** (Conditionally keeping a stream)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -3098,8 +3206,8 @@ export const partition = /*#__PURE__*/dual(args => isStream(args[0]), (self, fil
  * // Output: []
  * ```
  *
+ * @category filtering
  * @since 2.0.0
- * @category Filtering
  */
 export const when = /*#__PURE__*/dual(2, (self, test) => test.pipe(Effect.map(pass => pass ? self : empty), unwrap));
 /**
@@ -3108,7 +3216,8 @@ export const when = /*#__PURE__*/dual(2, (self, test) => test.pipe(Effect.map(pa
  *
  * The returned stream is only valid within the scope.
  *
- * @example
+ * **Example** (Peeling a stream with a sink)
+ *
  * ```ts
  * import { Console, Effect, Sink, Stream } from "effect"
  *
@@ -3127,8 +3236,8 @@ export const when = /*#__PURE__*/dual(2, (self, test) => test.pipe(Effect.map(pa
  * // Output: [ [1, 2, 3], [4, 5, 6] ]
  * ```
  *
+ * @category destructors
  * @since 2.0.0
- * @category Destructors
  */
 export const peel = /*#__PURE__*/dual(2, /*#__PURE__*/Effect.fnUntraced(function* (self, sink) {
   let cause = undefined;
@@ -3147,10 +3256,13 @@ export const peel = /*#__PURE__*/dual(2, /*#__PURE__*/Effect.fnUntraced(function
  * Buffers up to `capacity` elements so a faster producer can progress
  * independently of a slower consumer.
  *
- * Note: This combinator destroys chunking. Use `Stream.rechunk` afterwards if
- * you need fixed chunk sizes.
+ * Finite buffers use the configured queue strategy: `"suspend"` applies
+ * backpressure, while `"dropping"` and `"sliding"` may discard elements when
+ * the buffer is full. This combinator destroys chunking; use `Stream.rechunk`
+ * afterward if you need fixed chunk sizes.
+ *
+ * **Example** (Buffering stream elements)
  *
- * @example
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -3166,23 +3278,21 @@ export const peel = /*#__PURE__*/dual(2, /*#__PURE__*/Effect.fnUntraced(function
  * // Output: [ 1, 2, 3 ]
  * ```
  *
- * @since 2.0.0
  * @category Rate Limiting
+ * @since 2.0.0
  */
 export const buffer = /*#__PURE__*/dual(2, (self, options) => fromChannel(Channel.bufferArray(self.channel, options)));
 /**
  * Allows a faster producer to progress independently of a slower consumer by
  * buffering up to `capacity` chunks in a queue.
  *
- * This combinator preserves chunking and is best with power-of-2 capacities.
- *
- * **Previously Known As**
- *
- * This API replaces the following from Effect 3.x:
+ * Finite buffers use the configured queue strategy: `"suspend"` applies
+ * backpressure, while `"dropping"` and `"sliding"` may discard chunks when the
+ * buffer is full. This combinator preserves chunking and is best with
+ * power-of-2 capacities.
  *
- * - `Stream.bufferChunks`
+ * **Example** (Buffering stream chunks)
  *
- * @example
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -3197,8 +3307,8 @@ export const buffer = /*#__PURE__*/dual(2, (self, options) => fromChannel(Channe
  * // Output: [ 1, 2, 3, 4 ]
  * ```
  *
- * @since 2.0.0
  * @category Rate Limiting
+ * @since 4.0.0
  */
 export const bufferArray = /*#__PURE__*/dual(2, (self, options) => fromChannel(Channel.buffer(self.channel, options)));
 /**
@@ -3206,13 +3316,8 @@ export const bufferArray = /*#__PURE__*/dual(2, (self, options) => fromChannel(C
  * one fails. Allows recovery from all causes of failure, including
  * interruption if the stream is uninterruptible.
  *
- * **Previously Known As**
- *
- * This API replaces the following from Effect 3.x:
- *
- * - `Stream.catchAllCause`
+ * **Example** (Catching stream causes)
  *
- * @example
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -3234,21 +3339,16 @@ export const bufferArray = /*#__PURE__*/dual(2, (self, options) => fromChannel(C
  * // Output: [ 1, 2, 999 ]
  * ```
  *
- * @since 4.0.0
- * @category Error Handling
+ * @category error handling
+ * @since 2.0.0
  */
 export const catchCause = /*#__PURE__*/dual(2, (self, f) => self.channel.pipe(Channel.catchCause(cause => f(cause).channel), fromChannel));
 /**
  * Runs an effect when the stream fails without changing its values or error,
  * unless the tap effect itself fails.
  *
- * **Previously Known As**
- *
- * This API replaces the following from Effect 3.x:
- *
- * - `Stream.tapErrorCause`
+ * **Example** (Tapping stream causes)
  *
- * @example
  * ```ts
  * import { Cause, Console, Effect, Stream } from "effect"
  *
@@ -3268,8 +3368,8 @@ export const catchCause = /*#__PURE__*/dual(2, (self, f) => self.channel.pipe(Ch
  * // Output: [ 1, 2, 0 ]
  * ```
  *
- * @since 4.0.0
- * @category Error Handling
+ * @category error handling
+ * @since 2.0.0
  */
 export const tapCause = /*#__PURE__*/dual(2, (self, f) => self.channel.pipe(Channel.tapCause(f), fromChannel));
 const catch_ = /*#__PURE__*/dual(2, (self, f) => fromChannel(Channel.catch(self.channel, error => f(error).channel)));
@@ -3277,13 +3377,8 @@ export {
 /**
  * Switches over to the stream produced by the provided function if this one fails.
  *
- * **Previously Known As**
- *
- * This API replaces the following from Effect 3.x:
- *
- * - `Stream.catchAll`
+ * **Example** (Catching stream failures)
  *
- * @example
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -3301,14 +3396,15 @@ export {
  * // Output: [ 1, 2, 999 ]
  * ```
  *
+ * @category error handling
  * @since 4.0.0
- * @category Error Handling
  */
 catch_ as catch };
 /**
  * Effectfully peeks at errors without changing the stream unless the tap fails.
  *
- * @example
+ * **Example** (Effectfully peeking at errors)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -3329,8 +3425,8 @@ catch_ as catch };
  * // [ 1, 2, 999 ]
  * ```
  *
- * @since 4.0.0
- * @category Error Handling
+ * @category error handling
+ * @since 2.0.0
  */
 export const tapError = /*#__PURE__*/dual(2, (self, f) => self.channel.pipe(Channel.tapError(f), fromChannel));
 /**
@@ -3340,13 +3436,8 @@ export const tapError = /*#__PURE__*/dual(2, (self, f) => self.channel.pipe(Chan
  * stream. Non-matching failures propagate downstream, so the error type is
  * preserved unless the filter narrows it.
  *
- * **Previously Known As**
- *
- * This API replaces the following from Effect 3.x:
+ * **Example** (Catching matching failures)
  *
- * - `Stream.catchSome`
- *
- * @example
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -3367,16 +3458,16 @@ export const tapError = /*#__PURE__*/dual(2, (self, f) => self.channel.pipe(Chan
  * Effect.runPromise(program)
  * ```
  *
+ * @category error handling
  * @since 4.0.0
- * @category Error Handling
  */
 export const catchIf = /*#__PURE__*/dual(args => isStream(args[0]), (self, predicate, f, orElse) => fromChannel(Channel.catchIf(toChannel(self), predicate, e => f(e).channel, orElse && (e => orElse(e).channel))));
 /**
  * Recovers from errors that match a `Filter` by switching to a recovery
  * stream.
  *
+ * @category error handling
  * @since 4.0.0
- * @category Error Handling
  */
 export const catchFilter = /*#__PURE__*/dual(args => isStream(args[0]), (self, filter, f, orElse) => fromChannel(Channel.catchFilter(toChannel(self), filter, e => f(e).channel, orElse && (e => orElse(e).channel))));
 /**
@@ -3388,7 +3479,8 @@ export const catchFilter = /*#__PURE__*/dual(args => isStream(args[0]), (self, f
  * Use `catchTag` when your error type is a tagged union with a readonly `_tag`
  * field and you want to handle a specific error case.
  *
- * @example
+ * **Example** (Catching tagged failures)
+ *
  * ```ts
  * import { Console, Data, Effect, Stream } from "effect"
  *
@@ -3409,8 +3501,8 @@ export const catchFilter = /*#__PURE__*/dual(args => isStream(args[0]), (self, f
  * Effect.runPromise(program)
  * ```
  *
- * @since 4.0.0
- * @category Error Handling
+ * @category error handling
+ * @since 2.0.0
  */
 export const catchTag = /*#__PURE__*/dual(args => isStream(args[0]), (self, k, f, orElse) => {
   const pred = Array.isArray(k) ? e => hasProperty(e, "_tag") && k.includes(e._tag) : isTagged(k);
@@ -3419,7 +3511,8 @@ export const catchTag = /*#__PURE__*/dual(args => isStream(args[0]), (self, k, f
 /**
  * Switches to a recovery stream based on matching `_tag` handlers.
  *
- * @example
+ * **Example** (Catching tagged failures with handlers)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -3449,8 +3542,8 @@ export const catchTag = /*#__PURE__*/dual(args => isStream(args[0]), (self, k, f
  * // Output: [ "fallback" ]
  * ```
  *
- * @since 4.0.0
- * @category Error Handling
+ * @category error handling
+ * @since 2.0.0
  */
 export const catchTags = /*#__PURE__*/dual(args => isStream(args[0]), (self, cases, orElse) => {
   let keys;
@@ -3465,7 +3558,8 @@ export const catchTags = /*#__PURE__*/dual(args => isStream(args[0]), (self, cas
  * Use this to handle nested error causes without removing the parent error
  * from the error channel. The handler receives the unwrapped reason.
  *
- * @example
+ * **Example** (Catching a tagged error reason)
+ *
  * ```ts
  * import { Console, Data, Effect, Stream } from "effect"
  *
@@ -3499,14 +3593,15 @@ export const catchTags = /*#__PURE__*/dual(args => isStream(args[0]), (self, cas
  * // Output: [ "retry: 60" ]
  * ```
  *
+ * @category error handling
  * @since 4.0.0
- * @category Error Handling
  */
 export const catchReason = /*#__PURE__*/dual(args => isStream(args[0]), (self, errorTag, reasonTag, f, orElse) => fromChannel(Channel.catchReason(toChannel(self), errorTag, reasonTag, (reason, error) => f(reason, error).channel, orElse && ((reason, error) => orElse(reason, error).channel))));
 /**
  * Catches multiple reasons within a tagged error using an object of handlers.
  *
- * @example
+ * **Example** (Catching tagged error reasons)
+ *
  * ```ts
  * import { Console, Data, Effect, Stream } from "effect"
  *
@@ -3541,8 +3636,8 @@ export const catchReason = /*#__PURE__*/dual(args => isStream(args[0]), (self, e
  * // Output: [ "retry: 60" ]
  * ```
  *
+ * @category error handling
  * @since 4.0.0
- * @category Error Handling
  */
 export const catchReasons = /*#__PURE__*/dual(args => isStream(args[0]), (self, errorTag, cases, orElse) => {
   const handlers = {};
@@ -3556,7 +3651,8 @@ export const catchReasons = /*#__PURE__*/dual(args => isStream(args[0]), (self,
 /**
  * Transforms the errors emitted by this stream using `f`.
  *
- * @example
+ * **Example** (Mapping stream errors)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -3573,21 +3669,16 @@ export const catchReasons = /*#__PURE__*/dual(args => isStream(args[0]), (self,
  * // Output: [ "recovered from mapped: bad" ]
  * ```
  *
+ * @category error handling
  * @since 2.0.0
- * @category Error Handling
  */
 export const mapError = /*#__PURE__*/dual(2, (self, f) => fromChannel(Channel.mapError(self.channel, f)));
 /**
  * Recovers from stream failures by filtering the `Cause` and switching to a recovery stream.
  * Non-matching causes are re-emitted as failures.
  *
- * **Previously Known As**
- *
- * This API replaces the following from Effect 3.x:
- *
- * - `Stream.catchSomeCause`
+ * **Example** (Catching matching causes)
  *
- * @example
  * ```ts
  * import { Cause, Console, Effect, Stream } from "effect"
  *
@@ -3607,22 +3698,23 @@ export const mapError = /*#__PURE__*/dual(2, (self, f) => fromChannel(Channel.ma
  * // Output: [ "Recovered: NetworkError" ]
  * ```
  *
+ * @category error handling
  * @since 4.0.0
- * @category Error Handling
  */
 export const catchCauseIf = /*#__PURE__*/dual(3, (self, predicate, f) => fromChannel(Channel.catchCauseIf(self.channel, predicate, cause => f(cause).channel)));
 /**
  * Recovers from stream failures by filtering the `Cause` and switching to a
  * recovery stream.
  *
+ * @category error handling
  * @since 4.0.0
- * @category Error Handling
  */
 export const catchCauseFilter = /*#__PURE__*/dual(3, (self, filter, f) => fromChannel(Channel.catchCauseFilter(self.channel, filter, (failure, cause) => f(failure, cause).channel)));
 /**
  * Switches to a fallback stream if this stream is empty.
  *
- * @example
+ * **Example** (Switching on empty streams)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -3638,14 +3730,15 @@ export const catchCauseFilter = /*#__PURE__*/dual(3, (self, filter, f) => fromCh
  * // Output: [ 1, 2 ]
  * ```
  *
+ * @category error handling
  * @since 2.0.0
- * @category Error Handling
  */
 export const orElseIfEmpty = /*#__PURE__*/dual(2, (self, orElse) => fromChannel(Channel.orElseIfEmpty(self.channel, _ => toChannel(orElse()))));
 /**
  * Returns a stream that emits a fallback value when this stream fails.
  *
- * @example
+ * **Example** (Recovering with a fallback value)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -3662,14 +3755,15 @@ export const orElseIfEmpty = /*#__PURE__*/dual(2, (self, orElse) => fromChannel(
  * // Output: [ "Recovered: NetworkError" ]
  * ```
  *
+ * @category error handling
  * @since 2.0.0
- * @category Error Handling
  */
 export const orElseSucceed = /*#__PURE__*/dual(2, (self, f) => catch_(self, e => succeed(f(e))));
 /**
  * Turns typed failures into defects, making the stream infallible.
  *
- * @example
+ * **Example** (Turning failures into defects)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -3686,8 +3780,8 @@ export const orElseSucceed = /*#__PURE__*/dual(2, (self, f) => catch_(self, e =>
  * // Output: [ 1, 2, 3 ]
  * ```
  *
+ * @category error handling
  * @since 2.0.0
- * @category Error Handling
  */
 export const orDie = self => fromChannel(Channel.orDie(self.channel));
 /**
@@ -3695,7 +3789,8 @@ export const orDie = self => fromChannel(Channel.orDie(self.channel));
  *
  * Use the `log` option to emit the full {@link Cause} when the stream fails.
  *
- * @example
+ * **Example** (Ignoring stream failures)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -3712,17 +3807,24 @@ export const orDie = self => fromChannel(Channel.orDie(self.channel));
  * // Output: [ 1, 2, 3 ]
  * ```
  *
- * @example
+ * **Example** (Configuring ignore logging)
+ *
  * ```ts
- * import { Stream } from "effect"
+ * import { Effect, Stream } from "effect"
  *
- * const stream = Stream.fail("boom")
+ * Effect.runPromise(Effect.gen(function*() {
+ *   const values = yield* Stream.fail("boom").pipe(
+ *     Stream.ignore({ log: false }),
+ *     Stream.runCollect
+ *   )
+ *   yield* Effect.sync(() => console.log(values))
+ * }))
  *
- * const program = stream.pipe(Stream.ignore({ log: "Error" }))
+ * // []
  * ```
  *
+ * @category error handling
  * @since 4.0.0
- * @category Error Handling
  */
 export const ignore = /*#__PURE__*/dual(args => isStream(args[0]), (self, options) => fromChannel(Channel.ignore(self.channel, options)));
 /**
@@ -3730,20 +3832,25 @@ export const ignore = /*#__PURE__*/dual(args => isStream(args[0]), (self, option
  *
  * Use the `log` option to emit the full {@link Cause} when the stream fails.
  *
- * @example
+ * **Example** (Ignoring stream failure causes)
+ *
  * ```ts
  * import { Effect, Stream } from "effect"
  *
- * const stream = Stream.make(1, 2).pipe(
- *   Stream.concat(Stream.fail("boom")),
- *   Stream.ignoreCause({ log: "Error" })
- * )
+ * Effect.runPromise(Effect.gen(function*() {
+ *   const values = yield* Stream.make(1, 2).pipe(
+ *     Stream.concat(Stream.die("boom")),
+ *     Stream.ignoreCause({ log: false }),
+ *     Stream.runCollect
+ *   )
+ *   yield* Effect.sync(() => console.log(values))
+ * }))
  *
- * const program = Stream.runCollect(stream)
+ * // [ 1, 2 ]
  * ```
  *
+ * @category error handling
  * @since 4.0.0
- * @category Error Handling
  */
 export const ignoreCause = /*#__PURE__*/dual(args => isStream(args[0]), (self, options) => fromChannel(Channel.ignoreCause(self.channel, options)));
 /**
@@ -3755,7 +3862,8 @@ export const ignoreCause = /*#__PURE__*/dual(args => isStream(args[0]), (self, o
  * The schedule is reset as soon as the first element passes through the
  * stream again.
  *
- * @example
+ * **Example** (Retrying stream failures)
+ *
  * ```ts
  * import { Console, Effect, Schedule, Stream } from "effect"
  *
@@ -3774,8 +3882,8 @@ export const ignoreCause = /*#__PURE__*/dual(args => isStream(args[0]), (self, o
  * // Output: [ 1, 1 ]
  * ```
  *
+ * @category error handling
  * @since 2.0.0
- * @category Error Handling
  */
 export const retry = /*#__PURE__*/dual(2, (self, policy) => fromChannel(Channel.retry(self.channel, policy)));
 /**
@@ -3786,9 +3894,10 @@ export const retry = /*#__PURE__*/dual(2, (self, policy) => fromChannel(Channel.
  * `preventFallbackOnPartialStream` to fail instead of mixing partial output with
  * a later fallback.
  *
- * @example
+ * **Example** (Applying an execution plan)
+ *
  * ```ts
- * import { Console, Effect, ExecutionPlan, Layer, Context, Stream } from "effect"
+ * import { Console, Context, Effect, ExecutionPlan, Layer, Stream } from "effect"
  *
  * class Service extends Context.Service<Service>()("Service", {
  *   make: Effect.succeed({
@@ -3815,9 +3924,8 @@ export const retry = /*#__PURE__*/dual(2, (self, policy) => fromChannel(Channel.
  * // Output: [ 1, 2, 3 ]
  * ```
  *
+ * @category error handling
  * @since 3.16.0
- * @category Error Handling
- * @experimental
  */
 export const withExecutionPlan = /*#__PURE__*/dual(args => isStream(args[0]), (self, policy, options) => suspend(() => {
   const preventFallbackOnPartialStream = options?.preventFallbackOnPartialStream ?? false;
@@ -3873,7 +3981,8 @@ export const withExecutionPlan = /*#__PURE__*/dual(args => isStream(args[0]), (s
 /**
  * Takes the first `n` elements from this stream, returning `Stream.empty` when `n < 1`.
  *
- * @example
+ * **Example** (Taking values from the left)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -3889,14 +3998,15 @@ export const withExecutionPlan = /*#__PURE__*/dual(args => isStream(args[0]), (s
  * // Output: [ 1, 2, 3 ]
  * ```
  *
+ * @category filtering
  * @since 2.0.0
- * @category Filtering
  */
 export const take = /*#__PURE__*/dual(2, (self, n) => n < 1 ? empty : takeUntil(self, (_, i) => i === n - 1));
 /**
  * Keeps the last `n` elements from this stream.
  *
- * @example
+ * **Example** (Taking elements from the right)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -3912,8 +4022,8 @@ export const take = /*#__PURE__*/dual(2, (self, n) => n < 1 ? empty : takeUntil(
  * // Output: [ 4, 5, 6 ]
  * ```
  *
+ * @category filtering
  * @since 2.0.0
- * @category Filtering
  */
 export const takeRight = /*#__PURE__*/dual(2, (self, n) => mapAccumArray(self, MutableList.make, (list, arr) => {
   MutableList.appendAll(list, arr);
@@ -3931,7 +4041,8 @@ export const takeRight = /*#__PURE__*/dual(2, (self, n) => mapAccumArray(self, M
  *
  * When `excludeLast` is `true`, the matching element is dropped.
  *
- * @example
+ * **Example** (Taking until a predicate matches)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -3954,8 +4065,8 @@ export const takeRight = /*#__PURE__*/dual(2, (self, n) => mapAccumArray(self, M
  * })
  * ```
  *
+ * @category filtering
  * @since 2.0.0
- * @category Filtering
  */
 export const takeUntil = /*#__PURE__*/dual(args => isStream(args[0]), (self, predicate, options) => transformPull(self, (pull, _scope) => Effect.sync(() => {
   let i = 0;
@@ -3974,7 +4085,8 @@ export const takeUntil = /*#__PURE__*/dual(args => isStream(args[0]), (self, pre
 /**
  * Effectful predicate version of `takeUntil`.
  *
- * @example
+ * **Example** (Taking until an effectful predicate matches)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -3990,8 +4102,8 @@ export const takeUntil = /*#__PURE__*/dual(args => isStream(args[0]), (self, pre
  * // Output: [ 1, 2, 3 ]
  * ```
  *
+ * @category filtering
  * @since 2.0.0
- * @category Filtering
  */
 export const takeUntilEffect = /*#__PURE__*/dual(args => isStream(args[0]), (self, predicate, options) => transformPull(self, (pull, _scope) => Effect.sync(() => {
   let i = 0;
@@ -4012,7 +4124,8 @@ export const takeUntilEffect = /*#__PURE__*/dual(args => isStream(args[0]), (sel
 /**
  * Takes the longest initial prefix of elements that satisfy the predicate.
  *
- * @example
+ * **Example** (Taking while a predicate holds)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -4029,8 +4142,8 @@ export const takeUntilEffect = /*#__PURE__*/dual(args => isStream(args[0]), (sel
  * // Output: [ 1, 2 ]
  * ```
  *
+ * @category filtering
  * @since 2.0.0
- * @category Filtering
  */
 export const takeWhile = /*#__PURE__*/dual(2, (self, predicate) => transformPull(self, (pull, _scope) => Effect.sync(() => {
   let i = 0;
@@ -4049,10 +4162,13 @@ export const takeWhile = /*#__PURE__*/dual(2, (self, predicate) => transformPull
   return pump;
 })));
 /**
- * Takes the longest initial prefix of elements that satisfy the filter.
+ * Takes the longest initial prefix accepted by a `Filter` and emits the
+ * filter's success values.
  *
+ * The stream stops at the first `Result.fail` returned by the filter.
+ *
+ * @category filtering
  * @since 4.0.0
- * @category Filtering
  */
 export const takeWhileFilter = /*#__PURE__*/dual(2, (self, filter) => transformPull(self, (pull, _scope) => Effect.sync(() => {
   let done = false;
@@ -4073,7 +4189,8 @@ export const takeWhileFilter = /*#__PURE__*/dual(2, (self, filter) => transformP
 /**
  * Takes elements from the stream while the effectful predicate is `true`.
  *
- * @example
+ * **Example** (Effectfully taking while a predicate holds)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -4089,8 +4206,8 @@ export const takeWhileFilter = /*#__PURE__*/dual(2, (self, filter) => transformP
  * // Output: [ 1, 2 ]
  * ```
  *
- * @since 2.0.0
- * @category Filtering
+ * @category filtering
+ * @since 4.0.0
  */
 export const takeWhileEffect = /*#__PURE__*/dual(2, (self, predicate) => takeUntilEffect(self, (a, n) => Effect.map(predicate(a, n), b => !b), {
   excludeLast: true
@@ -4098,7 +4215,8 @@ export const takeWhileEffect = /*#__PURE__*/dual(2, (self, predicate) => takeUnt
 /**
  * Drops the first `n` elements from this stream.
  *
- * @example
+ * **Example** (Dropping values from the left)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -4114,8 +4232,8 @@ export const takeWhileEffect = /*#__PURE__*/dual(2, (self, predicate) => takeUnt
  * // Output: [ 3, 4, 5 ]
  * ```
  *
+ * @category filtering
  * @since 2.0.0
- * @category Filtering
  */
 export const drop = /*#__PURE__*/dual(2, (self, n) => transformPull(self, (pull, _scope) => Effect.sync(() => {
   let dropped = 0;
@@ -4131,7 +4249,8 @@ export const drop = /*#__PURE__*/dual(2, (self, n) => transformPull(self, (pull,
  * Drops elements until the specified predicate evaluates to `true`, then drops
  * that matching element.
  *
- * @example
+ * **Example** (Dropping until a predicate matches)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -4144,8 +4263,8 @@ export const drop = /*#__PURE__*/dual(2, (self, n) => transformPull(self, (pull,
  * })
  * ```
  *
+ * @category filtering
  * @since 2.0.0
- * @category Filtering
  */
 export const dropUntil = /*#__PURE__*/dual(2, (self, predicate) => drop(dropWhile(self, (a, i) => !predicate(a, i)), 1));
 /**
@@ -4154,7 +4273,8 @@ export const dropUntil = /*#__PURE__*/dual(2, (self, predicate) => drop(dropWhil
  *
  * The first element that satisfies the predicate is also dropped.
  *
- * @example
+ * **Example** (Dropping until an effectful predicate matches)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -4170,14 +4290,15 @@ export const dropUntil = /*#__PURE__*/dual(2, (self, predicate) => drop(dropWhil
  * // Output: [ 4, 5 ]
  * ```
  *
+ * @category filtering
  * @since 2.0.0
- * @category Filtering
  */
 export const dropUntilEffect = /*#__PURE__*/dual(2, (self, predicate) => drop(dropWhileEffect(self, (a, i) => Effect.map(predicate(a, i), b => !b)), 1));
 /**
  * Drops elements from the stream while the specified predicate evaluates to `true`.
  *
- * @example
+ * **Example** (Dropping while a predicate holds)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -4193,8 +4314,8 @@ export const dropUntilEffect = /*#__PURE__*/dual(2, (self, predicate) => drop(dr
  * // Output: [ 3, 4, 5 ]
  * ```
  *
+ * @category filtering
  * @since 2.0.0
- * @category Filtering
  */
 export const dropWhile = /*#__PURE__*/dual(2, (self, predicate) => transformPull(self, (pull, _scope) => Effect.sync(() => {
   let dropping = true;
@@ -4210,8 +4331,8 @@ export const dropWhile = /*#__PURE__*/dual(2, (self, predicate) => transformPull
 /**
  * Drops elements while the filter succeeds.
  *
+ * @category filtering
  * @since 4.0.0
- * @category Filtering
  */
 export const dropWhileFilter = /*#__PURE__*/dual(2, (self, filter) => transformPull(self, (pull, _scope) => Effect.sync(() => {
   let dropping = true;
@@ -4226,7 +4347,8 @@ export const dropWhileFilter = /*#__PURE__*/dual(2, (self, filter) => transformP
 /**
  * Drops elements while the specified effectful predicate evaluates to `true`.
  *
- * @example
+ * **Example** (Effectfully dropping while a predicate holds)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -4242,8 +4364,8 @@ export const dropWhileFilter = /*#__PURE__*/dual(2, (self, filter) => transformP
  * // Output: [ 3, 4, 5 ]
  * ```
  *
+ * @category filtering
  * @since 2.0.0
- * @category Filtering
  */
 export const dropWhileEffect = /*#__PURE__*/dual(2, (self, predicate) => transformPull(self, (pull, _scope) => Effect.sync(() => {
   let dropping = true;
@@ -4266,7 +4388,8 @@ export const dropWhileEffect = /*#__PURE__*/dual(2, (self, predicate) => transfo
  *
  * Keeps the last `n` elements in memory to drop them on completion.
  *
- * @example
+ * **Example** (Dropping values from the right)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -4282,8 +4405,8 @@ export const dropWhileEffect = /*#__PURE__*/dual(2, (self, predicate) => transfo
  * // Output: [ 1, 2, 3 ]
  * ```
  *
+ * @category filtering
  * @since 2.0.0
- * @category Filtering
  */
 export const dropRight = /*#__PURE__*/dual(2, (self, n) => {
   if (n <= 0) return self;
@@ -4301,7 +4424,8 @@ export const dropRight = /*#__PURE__*/dual(2, (self, n) => {
 /**
  * Exposes the underlying chunks as a stream of non-empty arrays.
  *
- * @example
+ * **Example** (Exposing stream chunks)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -4318,8 +4442,8 @@ export const dropRight = /*#__PURE__*/dual(2, (self, n) => {
  * // Output: [ [ 1, 2 ], [ 3, 4 ] ]
  * ```
  *
- * @since 2.0.0
  * @category Grouping
+ * @since 2.0.0
  */
 export const chunks = self => self.channel.pipe(Channel.map(Arr.of), fromChannel);
 /**
@@ -4327,7 +4451,8 @@ export const chunks = self => self.channel.pipe(Channel.map(Arr.of), fromChannel
  *
  * The size is clamped to at least 1.
  *
- * @example
+ * **Example** (Rechunking stream elements)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -4344,8 +4469,8 @@ export const chunks = self => self.channel.pipe(Channel.map(Arr.of), fromChannel
  * // Output: [ [ 1, 2 ], [ 3, 4 ], [ 5 ] ]
  * ```
  *
- * @since 2.0.0
  * @category Grouping
+ * @since 2.0.0
  */
 export const rechunk = /*#__PURE__*/dual(2, (self, target) => {
   target = Math.max(1, target);
@@ -4390,9 +4515,10 @@ export const rechunk = /*#__PURE__*/dual(2, (self, target) => {
 /**
  * Emits a sliding window of `n` elements.
  *
- * @example
+ * **Example** (Emitting sliding windows)
+ *
  * ```ts
- * import { Console, Effect, Stream, pipe } from "effect"
+ * import { Console, Effect, pipe, Stream } from "effect"
  *
  * Effect.gen(function*() {
  *   const result = yield* pipe(
@@ -4405,13 +4531,15 @@ export const rechunk = /*#__PURE__*/dual(2, (self, target) => {
  * // Output: [ [1, 2], [2, 3], [3, 4], [4, 5] ]
  * ```
  *
- * @since 2.0.0
  * @category Grouping
+ * @since 2.0.0
  */
 export const sliding = /*#__PURE__*/dual(2, (self, chunkSize) => slidingSize(self, chunkSize, 1));
 /**
  * Emits sliding windows of `chunkSize` elements, advancing by `stepSize`.
  *
+ * **Example** (Emitting sliding windows with a step size)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -4427,8 +4555,8 @@ export const sliding = /*#__PURE__*/dual(2, (self, chunkSize) => slidingSize(sel
  * // Output: [ [ 1, 2, 3 ], [ 3, 4, 5 ] ]
  * ```
  *
- * @since 2.0.0
  * @category Grouping
+ * @since 2.0.0
  */
 export const slidingSize = /*#__PURE__*/dual(3, (self, chunkSize, stepSize) => transformPull(self, (upstream, _scope) => Effect.sync(() => {
   let cause = null;
@@ -4468,7 +4596,8 @@ export const slidingSize = /*#__PURE__*/dual(3, (self, chunkSize, stepSize) => t
  *
  * Matching elements act as delimiters and are not included in the output.
  *
- * @example
+ * **Example** (Splitting on matching values)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -4484,8 +4613,8 @@ export const slidingSize = /*#__PURE__*/dual(3, (self, chunkSize, stepSize) => t
  * // Output: [ [1, 2, 3], [5, 6, 7], [9] ]
  * ```
  *
- * @since 2.0.0
  * @category Grouping
+ * @since 2.0.0
  */
 export const split = /*#__PURE__*/dual(2, (self, predicate) => mapAccumArray(self, Arr.empty, (acc, arr) => {
   const out = Arr.empty();
@@ -4512,7 +4641,8 @@ export const split = /*#__PURE__*/dual(2, (self, predicate) => mapAccumArray(sel
  * Where possible, prefer `Stream.combineArray` for a more efficient
  * implementation.
  *
- * @example
+ * **Example** (Combining streams with state)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -4535,8 +4665,8 @@ export const split = /*#__PURE__*/dual(2, (self, predicate) => mapAccumArray(sel
  * // Output: [ "L:A", "R:1", "L:B", "R:2", "L:C", "R:3" ]
  * ```
  *
- * @since 2.0.0
  * @category Merging
+ * @since 2.0.0
  */
 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));
 /**
@@ -4546,13 +4676,8 @@ export const combine = /*#__PURE__*/dual(4, (self, that, s, f) => Channel.combin
  * internal state to control the combining process, with the initial state
  * being specified by `s`.
  *
- * **Previously Known As**
- *
- * This API replaces the following from Effect 3.x:
+ * **Example** (Combining stream chunks with state)
  *
- * - `Stream.combineChunks`
- *
- * @example
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -4577,14 +4702,15 @@ export const combine = /*#__PURE__*/dual(4, (self, that, s, f) => Channel.combin
  * // Output: [ 1, 2, 10, 20 ]
  * ```
  *
- * @since 2.0.0
- * @category Sequencing
+ * @category sequencing
+ * @since 4.0.0
  */
 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.
  *
- * @example
+ * **Example** (Statefully mapping stream values)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -4604,8 +4730,8 @@ export const combineArray = /*#__PURE__*/dual(4, (self, that, s, f) => fromChann
  * // Output: [ 0, 1, 3, 6, 10, 15, 21 ]
  * ```
  *
+ * @category mapping
  * @since 2.0.0
- * @category Mapping
  */
 export const mapAccum = /*#__PURE__*/dual(args => isStream(args[0]), (self, initial, f, options) => fromChannel(Channel.mapAccum(self.channel, initial, (state, arr) => {
   const acc = Arr.empty();
@@ -4626,7 +4752,8 @@ export const mapAccum = /*#__PURE__*/dual(args => isStream(args[0]), (self, init
  *
  * The mapping function runs once per chunk and the state is threaded across chunks.
  *
- * @example
+ * **Example** (Statefully mapping stream chunks)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -4646,8 +4773,8 @@ export const mapAccum = /*#__PURE__*/dual(args => isStream(args[0]), (self, init
  * // Output: [ 3, 10, 21 ]
  * ```
  *
- * @since 2.0.0
- * @category Mapping
+ * @category mapping
+ * @since 4.0.0
  */
 export const mapAccumArray = /*#__PURE__*/dual(args => isStream(args[0]), (self, initial, f, options) => fromChannel(Channel.mapAccum(self.channel, initial, (state, arr) => {
   const [newState, values] = f(state, arr);
@@ -4661,9 +4788,15 @@ export const mapAccumArray = /*#__PURE__*/dual(args => isStream(args[0]), (self,
 } : undefined)));
 const emptyArr = /*#__PURE__*/Arr.empty();
 /**
- * Statefully and effectfully maps over the elements of this stream to produce new elements.
+ * Statefully and effectfully maps each element, emitting zero or more output
+ * values per input.
+ *
+ * The mapping effect receives the current state and element, then returns the
+ * next state plus the values to emit. The state is threaded through the
+ * stream.
+ *
+ * **Example** (Effectfully mapping stream values with state)
  *
- * @example
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -4682,8 +4815,8 @@ const emptyArr = /*#__PURE__*/Arr.empty();
  * // Output: [ 1, 2, 3 ]
  * ```
  *
+ * @category mapping
  * @since 2.0.0
- * @category Mapping
  */
 export const mapAccumEffect = /*#__PURE__*/dual(args => isStream(args[0]), (self, initial, f, options) => self.channel.pipe(Channel.flattenArray, Channel.mapAccum(initial, (state, a) => Effect.map(f(state, a), ([state, values]) => [state, Arr.isReadonlyArrayNonEmpty(values) ? Arr.of(values) : Arr.empty()]), options?.onHalt ? {
   onHalt(state) {
@@ -4692,9 +4825,14 @@ export const mapAccumEffect = /*#__PURE__*/dual(args => isStream(args[0]), (self
   }
 } : undefined), fromChannel));
 /**
- * Statefully and effectfully maps over chunks of this stream to emit new values.
+ * Statefully and effectfully maps each non-empty input chunk, emitting zero or
+ * more output values per chunk.
+ *
+ * The mapping effect receives the current state and chunk, then returns the
+ * next state plus the values to emit. The state is threaded across chunks.
+ *
+ * **Example** (Effectfully mapping stream chunks with state)
  *
- * @example
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -4716,8 +4854,8 @@ export const mapAccumEffect = /*#__PURE__*/dual(args => isStream(args[0]), (self
  * // Output: [ 3, 10 ]
  * ```
  *
- * @since 2.0.0
- * @category Mapping
+ * @category mapping
+ * @since 4.0.0
  */
 export const mapAccumArrayEffect = /*#__PURE__*/dual(args => isStream(args), (self, initial, f, options) => self.channel.pipe(Channel.mapAccum(initial, (state, a) => Effect.map(f(state, a), ([state, values]) => [state, Arr.isReadonlyArrayNonEmpty(values) ? Arr.of(values) : emptyArr]), options?.onHalt ? {
   onHalt(state) {
@@ -4728,7 +4866,8 @@ export const mapAccumArrayEffect = /*#__PURE__*/dual(args => isStream(args), (se
 /**
  * Accumulates state across the stream, emitting the initial state and each updated state.
  *
- * @example
+ * **Example** (Scanning stream state)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -4744,8 +4883,8 @@ export const mapAccumArrayEffect = /*#__PURE__*/dual(args => isStream(args), (se
  * // Output: [ 0, 1, 3, 6 ]
  * ```
  *
- * @since 2.0.0
  * @category Accumulation
+ * @since 2.0.0
  */
 export const scan = /*#__PURE__*/dual(3, (self, initial, f) => suspend(() => {
   let isFirst = true;
@@ -4765,7 +4904,8 @@ export const scan = /*#__PURE__*/dual(3, (self, initial, f) => suspend(() => {
 /**
  * Effectfully accumulates state and emits the initial state plus each accumulated state.
  *
- * @example
+ * **Example** (Effectfully scanning stream state)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -4779,14 +4919,15 @@ export const scan = /*#__PURE__*/dual(3, (self, initial, f) => suspend(() => {
  * })
  * ```
  *
- * @since 2.0.0
  * @category Accumulation
+ * @since 2.0.0
  */
 export const scanEffect = /*#__PURE__*/dual(3, (self, initial, f) => self.channel.pipe(Channel.flattenArray, Channel.scanEffect(initial, f), Channel.map(Arr.of), fromChannel));
 /**
  * Drops earlier elements within the debounce window and emits only the latest element after the pause.
  *
- * @example
+ * **Example** (Debouncing stream elements)
+ *
  * ```ts
  * import { Console, Duration, Effect, Stream } from "effect"
  *
@@ -4803,8 +4944,8 @@ export const scanEffect = /*#__PURE__*/dual(3, (self, initial, f) => self.channe
  * })
  * ```
  *
- * @since 2.0.0
  * @category Rate Limiting
+ * @since 2.0.0
  */
 export const debounce = /*#__PURE__*/dual(2, (self, duration) => transformPull(self, Effect.fnUntraced(function* (pull, scope) {
   const clock = yield* Clock;
@@ -4873,7 +5014,8 @@ export const debounce = /*#__PURE__*/dual(2, (self, duration) => transformPull(s
  *
  * Defaults to the "shape" strategy.
  *
- * @example
+ * **Example** (Throttling stream chunks effectfully)
+ *
  * ```ts
  * import { Console, Effect, Schedule, Stream } from "effect"
  *
@@ -4894,8 +5036,8 @@ export const debounce = /*#__PURE__*/dual(2, (self, duration) => transformPull(s
  * // Output: [0, 1, 2, 3, 4, 5]
  * ```
  *
- * @since 2.0.0
  * @category Rate Limiting
+ * @since 2.0.0
  */
 export const throttleEffect = /*#__PURE__*/dual(2, (self, options) => {
   const burst = options.burst ?? 0;
@@ -4969,7 +5111,8 @@ const throttleShapeEffect = (self, cost, units, duration, burst) => transformPul
  *
  * Defaults to the "shape" strategy.
  *
- * @example
+ * **Example** (Throttling stream chunks)
+ *
  * ```ts
  * import { Console, Effect, Schedule, Stream } from "effect"
  *
@@ -4990,8 +5133,8 @@ const throttleShapeEffect = (self, cost, units, duration, burst) => transformPul
  * })
  * ```
  *
- * @since 2.0.0
  * @category Rate Limiting
+ * @since 2.0.0
  */
 export const throttle = /*#__PURE__*/dual(2, (self, options) => throttleEffect(self, {
   ...options,
@@ -5002,7 +5145,8 @@ export const throttle = /*#__PURE__*/dual(2, (self, options) => throttleEffect(s
  *
  * The final array may be smaller if there are not enough elements to fill it.
  *
- * @example
+ * **Example** (Grouping elements by size)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -5018,15 +5162,16 @@ export const throttle = /*#__PURE__*/dual(2, (self, options) => throttleEffect(s
  * // Output: [ [ 1, 2, 3 ], [ 4, 5, 6 ], [ 7, 8 ] ]
  * ```
  *
- * @since 2.0.0
  * @category Grouping
+ * @since 2.0.0
  */
 export const grouped = /*#__PURE__*/dual(2, (self, n) => chunks(rechunk(self, n)));
 /**
  * Partitions the stream into arrays, emitting when the chunk size is reached
  * or the duration passes.
  *
- * @example
+ * **Example** (Grouping elements by size or time)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -5042,14 +5187,15 @@ export const grouped = /*#__PURE__*/dual(2, (self, n) => chunks(rechunk(self, n)
  * // Output: [ [ 1, 2 ], [ 3 ] ]
  * ```
  *
- * @since 2.0.0
  * @category Grouping
+ * @since 2.0.0
  */
 export const groupedWithin = /*#__PURE__*/dual(3, (self, chunkSize, duration) => aggregateWithin(self, Sink.take(chunkSize), Schedule.spaced(duration)));
 /**
  * Groups elements into keyed substreams using an effectful classifier.
  *
- * @example
+ * **Example** (Grouping elements into keyed substreams using an effectful classifier)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -5074,8 +5220,8 @@ export const groupedWithin = /*#__PURE__*/dual(3, (self, chunkSize, duration) =>
  * // Output: [ [ "odd", [ 1, 3, 5 ] ], [ "even", [ 2, 4 ] ] ]
  * ```
  *
- * @since 2.0.0
  * @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) {
   for (let i = 0; i < arr.length; i++) {
@@ -5089,7 +5235,8 @@ export const groupBy = /*#__PURE__*/dual(args => isStream(args[0]), (self, f, op
 /**
  * Groups elements by a key and emits a stream per key.
  *
- * @example
+ * **Example** (Grouping elements by key)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -5112,8 +5259,8 @@ export const groupBy = /*#__PURE__*/dual(args => isStream(args[0]), (self, f, op
  * // Output: [ [ "odd", [ 1, 3, 5 ] ], [ "even", [ 2, 4 ] ] ]
  * ```
  *
- * @since 2.0.0
  * @category Grouping
+ * @since 2.0.0
  */
 export const groupByKey = /*#__PURE__*/dual(args => isStream(args[0]), (self, f, options) => suspend(() => {
   const batch = MutableHashMap.empty();
@@ -5160,8 +5307,14 @@ const groupByImpl = (self, f, options) => transformPullBracket(self, Effect.fnUn
   return Queue.takeAll(out);
 }));
 /**
- * @since 2.0.0
+ * Groups consecutive elements that have equal keys into non-empty arrays.
+ *
+ * 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
+ * @since 2.0.0
  */
 export const groupAdjacentBy = /*#__PURE__*/dual(2, (self, f) => transformPull(self, (pull, _scope) => Effect.sync(() => {
   let currentKey = undefined;
@@ -5201,7 +5354,8 @@ export const groupAdjacentBy = /*#__PURE__*/dual(2, (self, f) => transformPull(s
 /**
  * Applies a sink transducer to the stream and emits each sink result.
  *
- * @example
+ * **Example** (Transducing with a sink)
+ *
  * ```ts
  * import { Console, Effect, Sink, Stream } from "effect"
  *
@@ -5216,8 +5370,8 @@ export const groupAdjacentBy = /*#__PURE__*/dual(2, (self, f) => transformPull(s
  * })
  * ```
  *
- * @since 2.0.0
  * @category Aggregation
+ * @since 2.0.0
  */
 export const transduce = /*#__PURE__*/dual(2, (self, sink) => transformPull(self, (upstream, scope) => Effect.sync(() => {
   let done;
@@ -5245,7 +5399,8 @@ export const transduce = /*#__PURE__*/dual(2, (self, sink) => transformPull(self
  * The stream runs the upstream and downstream in separate fibers, so the sink can keep
  * consuming input while downstream is busy processing the previous output.
  *
- * @example
+ * **Example** (Aggregating with a sink)
+ *
  * ```ts
  * import { Console, Effect, Sink, Stream } from "effect"
  *
@@ -5262,8 +5417,8 @@ export const transduce = /*#__PURE__*/dual(2, (self, sink) => transformPull(self
  * // [ 6, 15 ]
  * ```
  *
- * @since 2.0.0
  * @category Aggregation
+ * @since 2.0.0
  */
 export const aggregate = /*#__PURE__*/dual(2, (self, sink) => aggregateWithin(self, sink, Schedule.forever));
 /**
@@ -5271,7 +5426,8 @@ export const aggregate = /*#__PURE__*/dual(2, (self, sink) => aggregateWithin(se
  *
  * The schedule can flush the current aggregation even if the sink has not finished.
  *
- * @example
+ * **Example** (Aggregating with a sink and schedule)
+ *
  * ```ts
  * import { Console, Effect, Schedule, Sink, Stream } from "effect"
  *
@@ -5289,8 +5445,8 @@ export const aggregate = /*#__PURE__*/dual(2, (self, sink) => aggregateWithin(se
  * // Output: [ 6, 15 ]
  * ```
  *
- * @since 2.0.0
  * @category Aggregation
+ * @since 2.0.0
  */
 export const aggregateWithin = /*#__PURE__*/dual(3, (self, sink, schedule) => fromChannel(Channel.fromTransformBracket(Effect.fnUntraced(function* (_upstream, _, scope) {
   const pull = yield* Channel.toPullScoped(self.channel, _);
@@ -5348,12 +5504,63 @@ export const aggregateWithin = /*#__PURE__*/dual(3, (self, sink, schedule) => fr
     return Effect.succeed(Effect.suspend(() => sink.transform(sinkUpstream, scope)));
   }).pipe(Effect.flatMap(pull => Effect.raceFirst(catchSinkHalt(pull), stepToBuffer)));
 }))));
+/**
+ * Fan out the stream, producing a fixed-size tuple of streams that each emit
+ * the same elements as the source stream.
+ *
+ * The source stream starts after all downstream streams have been subscribed.
+ * With the default suspend strategy, the source can only advance `capacity`
+ * chunks ahead of the slowest downstream stream. If a downstream stream is
+ * interrupted, it unsubscribes from the broadcast so it no longer contributes
+ * backpressure.
+ *
+ * **Example** (Broadcasting to two consumers)
+ *
+ * ```ts
+ * import { Console, Effect, Stream } from "effect"
+ *
+ * const program = Effect.scoped(
+ *   Effect.gen(function*() {
+ *     const [left, right] = yield* Stream.make(1, 2, 3).pipe(
+ *       Stream.broadcastN({ n: 2, capacity: 8 })
+ *     )
+ *
+ *     const values = yield* Effect.all([
+ *       Stream.runCollect(left),
+ *       Stream.runCollect(right)
+ *     ], { concurrency: "unbounded" })
+ *
+ *     yield* Console.log(values)
+ *   })
+ * )
+ *
+ * Effect.runPromise(program)
+ * // Output: [[1, 2, 3], [1, 2, 3]]
+ * ```
+ *
+ * @category Broadcast
+ * @since 4.0.0
+ */
+export const broadcastN = /*#__PURE__*/dual(2, /*#__PURE__*/Effect.fnUntraced(function* (self, options) {
+  const pubsub = yield* makePubSub(options);
+  const streams = new Array(options.n);
+  const parentScope = yield* Scope.Scope;
+  for (let i = 0; i < options.n; i++) {
+    const scope = Scope.forkUnsafe(parentScope);
+    const subscription = yield* PubSub.subscribe(pubsub).pipe(Effect.provideService(Scope.Scope, scope));
+    streams[i] = Channel.fromEffectTake(PubSub.take(subscription)).pipe(Channel.onExit(exit => Scope.close(scope, exit)), fromChannel);
+  }
+  yield* Channel.runForEach(self.channel, value => PubSub.publish(pubsub, value)).pipe(Effect.onExit(exit => PubSub.publish(pubsub, exit)), Effect.forkScoped);
+  return streams;
+}));
+const makePubSub = options => Effect.acquireRelease(options.capacity === "unbounded" ? PubSub.unbounded(options) : options.strategy === "dropping" ? PubSub.dropping(options) : options.strategy === "sliding" ? PubSub.sliding(options) : PubSub.bounded(options), PubSub.shutdown);
 /**
  * Creates a PubSub-backed stream that multicasts the source to all subscribers.
  *
  * The returned stream is scoped and uses the provided PubSub capacity and replay settings.
  *
- * @example
+ * **Example** (Broadcasting a stream)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -5377,8 +5584,8 @@ export const aggregateWithin = /*#__PURE__*/dual(3, (self, sink, schedule) => fr
  * // Output: [[1, 2, 3], [1, 2, 3]]
  * ```
  *
- * @since 2.0.0
  * @category Broadcast
+ * @since 2.0.0
  */
 export const broadcast = /*#__PURE__*/dual(2, (self, options) => Effect.map(toPubSubTake(self, options), fromPubSubTake));
 /**
@@ -5388,7 +5595,8 @@ export const broadcast = /*#__PURE__*/dual(2, (self, options) => Effect.map(toPu
  * If `idleTimeToLive` is set, the upstream is kept alive for that duration so a later subscriber can continue from
  * the next element instead of restarting.
  *
- * @example
+ * **Example** (Sharing a stream)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -5409,8 +5617,8 @@ export const broadcast = /*#__PURE__*/dual(2, (self, options) => Effect.map(toPu
  * // output: [[1], [1]]
  * ```
  *
- * @since 2.0.0
  * @category Broadcast
+ * @since 3.8.0
  */
 export const share = /*#__PURE__*/dual(2, (self, options) => Effect.map(RcRef.make({
   acquire: broadcast(self, options),
@@ -5422,7 +5630,8 @@ export const share = /*#__PURE__*/dual(2, (self, options) => Effect.map(RcRef.ma
  * The channel receives `NonEmptyReadonlyArray` chunks and can transform both the
  * output elements and error type.
  *
- * @example
+ * **Example** (Piping through a channel)
+ *
  * ```ts
  * import { Array, Channel, Console, Effect, Stream } from "effect"
  *
@@ -5445,8 +5654,8 @@ export const share = /*#__PURE__*/dual(2, (self, options) => Effect.map(RcRef.ma
  * // => [2, 4, 6]
  * ```
  *
- * @since 2.0.0
  * @category Pipe
+ * @since 2.0.0
  */
 export const pipeThroughChannel = /*#__PURE__*/dual(2, (self, channel) => fromChannel(Channel.pipeTo(self.channel, channel)));
 /**
@@ -5456,35 +5665,31 @@ export const pipeThroughChannel = /*#__PURE__*/dual(2, (self, channel) => fromCh
  * Upstream failures are not passed to the channel, so the resulting stream can
  * fail with either the original stream error or the channel error.
  *
- * @example
+ * **Example** (Piping through a channel with failures)
+ *
  * ```ts
- * import type { Channel } from "effect"
- * import { Console, Effect, Stream } from "effect"
+ * import { Array, Channel, Effect, Stream } from "effect"
  *
- * declare const transformChannel: Channel.Channel<
- *   readonly [string, ...Array<string>],
- *   "ChannelError",
- *   unknown,
- *   readonly [number, ...Array<number>],
- *   "StreamError",
- *   unknown,
- *   never
- * >
+ * type NumberChunk = readonly [number, ...Array<number>]
+ *
+ * const stringifyChunks = Channel.identity<NumberChunk, "StreamError", unknown>().pipe(
+ *   Channel.map((chunk) => Array.map(chunk, String))
+ * )
  *
  * Effect.runPromise(Effect.gen(function*() {
  *   const result = yield* Stream.make(1, 2, 3).pipe(
- *     Stream.pipeThroughChannelOrFail(transformChannel),
+ *     Stream.rechunk(2),
+ *     Stream.pipeThroughChannelOrFail(stringifyChunks),
  *     Stream.runCollect
  *   )
  *
- *   yield* Console.log(result)
+ *   yield* Effect.sync(() => console.log(result))
  * }))
- * // Output:
- * // ["1", "2", "3"]
+ * // [ "1", "2", "3" ]
  * ```
  *
- * @since 2.0.0
  * @category Pipe
+ * @since 2.0.0
  */
 export const pipeThroughChannelOrFail = /*#__PURE__*/dual(2, (self, channel) => fromChannel(Channel.pipeToOrFail(self.channel, channel)));
 /**
@@ -5492,7 +5697,8 @@ export const pipeThroughChannelOrFail = /*#__PURE__*/dual(2, (self, channel) =>
  *
  * If the sink completes mid-chunk, the remaining elements become the output stream.
  *
- * @example
+ * **Example** (Piping through a sink)
+ *
  * ```ts
  * import { Console, Effect, Sink, Stream } from "effect"
  *
@@ -5509,14 +5715,15 @@ export const pipeThroughChannelOrFail = /*#__PURE__*/dual(2, (self, channel) =>
  * //=> [ 3, 4 ]
  * ```
  *
- * @since 2.0.0
  * @category Pipe
+ * @since 2.0.0
  */
 export const pipeThrough = /*#__PURE__*/dual(2, (self, sink) => self.channel.pipe(Channel.pipeToOrFail(Sink.toChannel(sink)), Channel.concatWith(([_, leftover]) => leftover ? Channel.succeed(leftover) : Channel.empty), fromChannel));
 /**
  * Collects all elements into an array and emits it as a single element.
  *
- * @example
+ * **Example** (Collecting values into a stream element)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -5531,14 +5738,15 @@ export const pipeThrough = /*#__PURE__*/dual(2, (self, sink) => self.channel.pip
  * // [1, 2, 3]
  * ```
  *
- * @since 2.0.0
  * @category Accumulation
+ * @since 4.0.0
  */
 export const collect = self => fromEffect(runCollect(self));
 /**
  * Accumulates elements into a growing array, emitting the cumulative array for each input chunk.
  *
- * @example
+ * **Example** (Accumulating stream elements)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -5556,8 +5764,8 @@ export const collect = self => fromEffect(runCollect(self));
  * //=> { _id: 'Chunk', values: [ [ 1 ], [ 1, 2 ], [ 1, 2, 3 ] ] }
  * ```
  *
- * @since 2.0.0
  * @category Accumulation
+ * @since 2.0.0
  */
 export const accumulate = self => mapAccumArray(self, Arr.empty, (acc, as) => {
   const combined = Arr.appendAll(acc, as);
@@ -5566,7 +5774,8 @@ export const accumulate = self => mapAccumArray(self, Arr.empty, (acc, as) => {
 /**
  * Emits only elements that differ from the previous one.
  *
- * @example
+ * **Example** (Emitting changed values)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -5583,14 +5792,15 @@ export const accumulate = self => mapAccumArray(self, Arr.empty, (acc, as) => {
  * // [1, 2, 3]
  * ```
  *
- * @since 2.0.0
  * @category Deduplication
+ * @since 2.0.0
  */
 export const changes = self => changesWith(self, Equal.equals);
 /**
  * Returns a stream that only emits elements that are not equal to the previously emitted element, as determined by the specified predicate.
  *
- * @example
+ * **Example** (Emitting values that changed by equivalence)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -5607,8 +5817,8 @@ export const changes = self => changesWith(self, Equal.equals);
  * // ["A", "B"]
  * ```
  *
- * @since 2.0.0
  * @category Deduplication
+ * @since 2.0.0
  */
 export const changesWith = /*#__PURE__*/dual(2, (self, f) => transformPull(self, (pull, _scope) => Effect.sync(() => {
   let first = true;
@@ -5636,7 +5846,8 @@ export const changesWith = /*#__PURE__*/dual(2, (self, f) => transformPull(self,
  *
  * The predicate runs for each element after the first; returning `true` treats it as equal and skips it.
  *
- * @example
+ * **Example** (Effectfully emitting changed values)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -5652,8 +5863,8 @@ export const changesWith = /*#__PURE__*/dual(2, (self, f) => transformPull(self,
  * // { _id: "Chunk", values: [ 1, 2, 3 ] }
  * ```
  *
- * @since 2.0.0
  * @category Deduplication
+ * @since 2.0.0
  */
 export const changesWithEffect = /*#__PURE__*/dual(2, (self, f) => transformPull(self, (pull, _scope) => Effect.sync(() => {
   let first = true;
@@ -5679,7 +5890,8 @@ export const changesWithEffect = /*#__PURE__*/dual(2, (self, f) => transformPull
 /**
  * Decodes Uint8Array chunks into strings using TextDecoder with an optional encoding.
  *
- * @example
+ * **Example** (Decoding Uint8Array chunks into strings using TextDecoder with an optional encoding)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -5701,8 +5913,8 @@ export const changesWithEffect = /*#__PURE__*/dual(2, (self, f) => transformPull
  * // ["Hello", " World"]
  * ```
  *
+ * @category encoding
  * @since 2.0.0
- * @category Encoding
  */
 export const decodeText = /*#__PURE__*/dual(args => isStream(args[0]), (self, options) => suspend(() => {
   const decoder = new TextDecoder(options?.encoding);
@@ -5713,7 +5925,8 @@ export const decodeText = /*#__PURE__*/dual(args => isStream(args[0]), (self, op
 /**
  * Encodes a stream of strings into UTF-8 `Uint8Array` chunks.
  *
- * @example
+ * **Example** (Encoding a stream of strings into UTF-8 Uint8Array chunks)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -5729,8 +5942,8 @@ export const decodeText = /*#__PURE__*/dual(args => isStream(args[0]), (self, op
  * // [[72, 101, 108, 108, 111], [32], [87, 111, 114, 108, 100]]
  * ```
  *
+ * @category encoding
  * @since 2.0.0
- * @category Encoding
  */
 export const encodeText = self => suspend(() => {
   const encoder = new TextEncoder();
@@ -5739,7 +5952,8 @@ export const encodeText = self => suspend(() => {
 /**
  * Splits a stream of strings into lines, handling `\n`, `\r`, and `\r\n` delimiters across chunks.
  *
- * @example
+ * **Example** (Splitting streamed text into lines)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -5752,14 +5966,15 @@ export const encodeText = self => suspend(() => {
  * // ["a", "b", "c"]
  * ```
  *
+ * @category encoding
  * @since 2.0.0
- * @category Encoding
  */
 export const splitLines = self => self.channel.pipe(Channel.pipeTo(Channel.splitLines()), fromChannel);
 /**
  * Inserts the provided element between emitted elements.
  *
- * @example
+ * **Example** (Interspersing stream elements)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -5773,8 +5988,8 @@ export const splitLines = self => self.channel.pipe(Channel.pipeTo(Channel.split
  * // [1, 0, 2, 0, 3, 0, 4]
  * ```
  *
+ * @category sequencing
  * @since 2.0.0
- * @category Sequencing
  */
 export const intersperse = /*#__PURE__*/dual(2, (self, element) => mapArray(self, (arr, i) => {
   const out = i === 0 ? [] : [element];
@@ -5793,7 +6008,8 @@ export const intersperse = /*#__PURE__*/dual(2, (self, element) => mapArray(self
  *
  * The start and end values are always emitted, even when the stream is empty.
  *
- * @example
+ * **Example** (Interspersing stream affixes)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -5810,8 +6026,8 @@ export const intersperse = /*#__PURE__*/dual(2, (self, element) => mapArray(self
  * // [ "[", "a", ",", "b", ",", "c", "]" ]
  * ```
  *
+ * @category sequencing
  * @since 2.0.0
- * @category Sequencing
  */
 export const intersperseAffixes = /*#__PURE__*/dual(2, (self, options) => succeed(options.start).pipe(concat(intersperse(self, options.middle)), concat(succeed(options.end))));
 /**
@@ -5819,7 +6035,8 @@ export const intersperseAffixes = /*#__PURE__*/dual(2, (self, options) => succee
  * each stream; when one ends, the remaining values from the other stream are
  * emitted.
  *
- * @example
+ * **Example** (Interleaving streams)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -5836,8 +6053,8 @@ export const intersperseAffixes = /*#__PURE__*/dual(2, (self, options) => succee
  * Effect.runPromise(program)
  * // [2, 5, 3, 6, 7]
  * ```
- * @since 2.0.0
  * @category Merging
+ * @since 2.0.0
  */
 export const interleave = /*#__PURE__*/dual(2, (self, that) => interleaveWith(self, that, fromIterable(Iterable.forever([true, false]))));
 /**
@@ -5846,7 +6063,8 @@ export const interleave = /*#__PURE__*/dual(2, (self, that) => interleaveWith(se
  * The decider controls how many elements are pulled; if one side ends, pulls for
  * that side are ignored.
  *
- * @example
+ * **Example** (Interleaving two streams deterministically by following a boolean decider stream)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -5866,8 +6084,8 @@ export const interleave = /*#__PURE__*/dual(2, (self, that) => interleaveWith(se
  * // [ 1, 2, 4, 3, 5 ]
  * ```
  *
- * @since 2.0.0
  * @category Merging
+ * @since 2.0.0
  */
 export const interleaveWith = /*#__PURE__*/dual(3, (self, that, decider) => fromChannel(Channel.fromTransform(Effect.fnUntraced(function* (upstream, scope) {
   const pullDecider = yield* Channel.toTransform(Channel.flattenArray(decider.channel))(upstream, scope);
@@ -5905,7 +6123,8 @@ export const interleaveWith = /*#__PURE__*/dual(3, (self, that, decider) => from
  * If the effect completes with a failure before the stream completes, the
  * returned stream will emit that failure.
  *
- * @example
+ * **Example** (Interrupting when an effect completes)
+ *
  * ```ts
  * import { Console, Deferred, Effect, Stream } from "effect"
  *
@@ -5928,14 +6147,15 @@ export const interleaveWith = /*#__PURE__*/dual(3, (self, that, decider) => from
  * // => [1, 2]
  * ```
  *
- * @since 2.0.0
  * @category Interruption
+ * @since 2.0.0
  */
 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).
  *
- * @example
+ * **Example** (Halting a stream after an effect completes)
+ *
  * ```ts
  * import { Console, Deferred, Effect, Stream } from "effect"
  *
@@ -5954,14 +6174,15 @@ export const interruptWhen = /*#__PURE__*/dual(2, (self, effect) => fromChannel(
  * // [1, 2]
  * ```
  *
- * @since 2.0.0
  * @category Interruption
+ * @since 2.0.0
  */
 export const haltWhen = /*#__PURE__*/dual(2, (self, effect) => fromChannel(Channel.haltWhen(self.channel, effect)));
 /**
  * Runs the provided finalizer when the stream exits, passing the exit value.
  *
- * @example
+ * **Example** (Running a finalizer on exit)
+ *
  * ```ts
  * import { Console, Effect, Exit, Stream } from "effect"
  *
@@ -5980,8 +6201,8 @@ export const haltWhen = /*#__PURE__*/dual(2, (self, effect) => fromChannel(Chann
  * // Stream completed successfully
  * ```
  *
- * @since 4.0.0
  * @category Finalization
+ * @since 4.0.0
  */
 export const onExit = /*#__PURE__*/dual(2, (self, finalizer) => fromChannel(Channel.onExit(self.channel, finalizer)));
 /**
@@ -5990,7 +6211,8 @@ export const onExit = /*#__PURE__*/dual(2, (self, finalizer) => fromChannel(Chan
  * Note: Unlike `Effect.onError` there is no guarantee that the provided
  * effect will not be interrupted.
  *
- * @example
+ * **Example** (Running an effect on errors)
+ *
  * ```ts
  * import { Cause, Console, Effect, Stream } from "effect"
  *
@@ -6008,14 +6230,15 @@ export const onExit = /*#__PURE__*/dual(2, (self, finalizer) => fromChannel(Chan
  * // Stream failed: boom
  * ```
  *
+ * @category error handling
  * @since 2.0.0
- * @category Error Handling
  */
 export const onError = /*#__PURE__*/dual(2, (self, cleanup) => fromChannel(Channel.onError(self.channel, cleanup)));
 /**
  * Runs the provided effect before this stream starts.
  *
- * @example
+ * **Example** (Running an effect on start)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -6034,14 +6257,15 @@ export const onError = /*#__PURE__*/dual(2, (self, cleanup) => fromChannel(Chann
  * // [1, 2, 3]
  * ```
  *
- * @since 4.0.0
- * @category Sequencing
+ * @category sequencing
+ * @since 3.6.0
  */
 export const onStart = /*#__PURE__*/dual(2, (self, onStart) => fromChannel(Channel.onStart(self.channel, onStart)));
 /**
  * Runs the provided effect with the first element emitted by the stream.
  *
- * @example
+ * **Example** (Running an effect on the first value)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -6054,14 +6278,15 @@ export const onStart = /*#__PURE__*/dual(2, (self, onStart) => fromChannel(Chann
  * // Output: first=1
  * ```
  *
+ * @category sequencing
  * @since 4.0.0
- * @category Sequencing
  */
 export const onFirst = /*#__PURE__*/dual(2, (self, onFirst) => fromChannel(Channel.onFirst(self.channel, arr => onFirst(arr[0]))));
 /**
  * Runs the provided effect when the stream ends successfully.
  *
- * @example
+ * **Example** (Running an effect on end)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -6078,14 +6303,15 @@ export const onFirst = /*#__PURE__*/dual(2, (self, onFirst) => fromChannel(Chann
  * // [1, 2, 3]
  * ```
  *
- * @since 4.0.0
- * @category Sequencing
+ * @category sequencing
+ * @since 3.6.0
  */
 export const onEnd = /*#__PURE__*/dual(2, (self, onEnd) => fromChannel(Channel.onEnd(self.channel, onEnd)));
 /**
  * Executes the provided finalizer after this stream's finalizers run.
  *
- * @example
+ * **Example** (Ensuring finalization)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -6103,8 +6329,8 @@ export const onEnd = /*#__PURE__*/dual(2, (self, onEnd) => fromChannel(Channel.o
  * //=> [1, 2]
  * ```
  *
- * @since 4.0.0
  * @category Finalization
+ * @since 2.0.0
  */
 export const ensuring = /*#__PURE__*/dual(2, (self, finalizer) => fromChannel(Channel.ensuring(self.channel, finalizer)));
 /**
@@ -6112,11 +6338,10 @@ export const ensuring = /*#__PURE__*/dual(2, (self, finalizer) => fromChannel(Ch
  * service requirements. Use `options.local` to build the layer every time; by
  * default, layers are shared between provide calls.
  *
- * **Previously Known As:** `provideSomeLayer`, `provideSomeContext`.
+ * **Example** (Providing stream requirements)
  *
- * @example
  * ```ts
- * import { Console, Effect, Layer, Context, Stream } from "effect"
+ * import { Console, Context, Effect, Layer, Stream } from "effect"
  *
  * class Env extends Context.Service<Env, { readonly name: string }>()("Env") {}
  *
@@ -6140,16 +6365,17 @@ export const ensuring = /*#__PURE__*/dual(2, (self, finalizer) => fromChannel(Ch
  * // ["Hello, Ada"]
  * ```
  *
+ * @category services
  * @since 4.0.0
- * @category Services
  */
 export const provide = /*#__PURE__*/dual(args => isStream(args[0]), (self, layer, options) => fromChannel(Channel.provide(self.channel, layer, options)));
 /**
  * Provides multiple services to the stream using a context.
  *
- * @example
+ * **Example** (Providing multiple services to the stream using a context)
+ *
  * ```ts
- * import { Console, Effect, Context, Stream } from "effect"
+ * import { Console, Context, Effect, Stream } from "effect"
  *
  * class Config extends Context.Service<Config, { readonly prefix: string }>()("Config") {}
  * class Greeter extends Context.Service<Greeter, { greet: (name: string) => string }>()("Greeter") {}
@@ -6175,17 +6401,18 @@ export const provide = /*#__PURE__*/dual(args => isStream(args[0]), (self, layer
  * // ["Hello!"]
  * ```
  *
- * @since 4.0.0
- * @category Services
+ * @category services
+ * @since 2.0.0
  */
 export const provideContext = /*#__PURE__*/dual(2, (self, context) => fromChannel(Channel.provideContext(self.channel, context)));
 /**
  * Provides the stream with a single required service, eliminating that
  * requirement from its environment.
  *
- * @example
+ * **Example** (Providing a stream service)
+ *
  * ```ts
- * import { Console, Effect, Context, Stream } from "effect"
+ * import { Console, Context, Effect, Stream } from "effect"
  *
  * class Greeter extends Context.Service<Greeter, {
  *   greet: (name: string) => string
@@ -6212,16 +6439,17 @@ export const provideContext = /*#__PURE__*/dual(2, (self, context) => fromChanne
  * //=> ["Hello, Ada"]
  * ```
  *
- * @since 4.0.0
- * @category Services
+ * @category services
+ * @since 2.0.0
  */
 export const provideService = /*#__PURE__*/dual(3, (self, key, service) => fromChannel(Channel.provideService(self.channel, key, service)));
 /**
  * Provides a service to the stream using an effect, removing the requirement and adding the effect's error and environment.
  *
- * @example
+ * **Example** (Providing a stream service effectfully)
+ *
  * ```ts
- * import { Console, Effect, Context, Stream } from "effect"
+ * import { Console, Context, Effect, Stream } from "effect"
  *
  * class ApiConfig extends Context.Service<ApiConfig, { readonly baseUrl: string }>()("ApiConfig") {}
  *
@@ -6251,17 +6479,18 @@ export const provideService = /*#__PURE__*/dual(3, (self, key, service) => fromC
  * // ["https://example.com"]
  * ```
  *
- * @since 4.0.0
- * @category Services
+ * @category services
+ * @since 2.0.0
  */
 export const provideServiceEffect = /*#__PURE__*/dual(3, (self, key, service) => fromChannel(Channel.provideServiceEffect(self.channel, key, service)));
 /**
  * Transforms the stream's required services by mapping the current context
  * to a new one.
  *
- * @example
+ * **Example** (Updating the stream context)
+ *
  * ```ts
- * import { Console, Effect, Context, Stream } from "effect"
+ * import { Console, Context, Effect, Stream } from "effect"
  *
  * class Logger extends Context.Service<Logger, { prefix: string }>()("Logger") {}
  * class Config extends Context.Service<Config, { name: string }>()("Config") {}
@@ -6291,16 +6520,17 @@ export const provideServiceEffect = /*#__PURE__*/dual(3, (self, key, service) =>
  * //=> [ "Hello World" ]
  * ```
  *
- * @since 2.0.0
- * @category Services
+ * @category services
+ * @since 4.0.0
  */
 export const updateContext = /*#__PURE__*/dual(2, (self, f) => fromChannel(Channel.updateContext(self.channel, f)));
 /**
  * Updates a single service in the stream environment by applying a function.
  *
- * @example
+ * **Example** (Updating a stream service)
+ *
  * ```ts
- * import { Console, Effect, Context, Stream } from "effect"
+ * import { Console, Context, Effect, Stream } from "effect"
  *
  * class Counter extends Context.Service<Counter, { count: number }>()("Counter") {}
  *
@@ -6317,14 +6547,15 @@ export const updateContext = /*#__PURE__*/dual(2, (self, f) => fromChannel(Chann
  * // Output: Updated count: 1
  * ```
  *
+ * @category services
  * @since 2.0.0
- * @category Services
  */
 export const updateService = /*#__PURE__*/dual(3, (self, service, f) => updateContext(self, context => Context.add(context, service, f(Context.get(context, service)))));
 /**
  * Wraps the stream with a new span for tracing.
  *
- * @example
+ * **Example** (Wrapping a stream in a span)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -6339,8 +6570,8 @@ export const updateService = /*#__PURE__*/dual(3, (self, service, f) => updateCo
  * // [1, 2, 3]
  * ```
  *
- * @since 4.0.0
- * @category Tracing
+ * @category tracing
+ * @since 2.0.0
  */
 export const withSpan = function () {
   const dataFirst = isStream(arguments[0]);
@@ -6355,9 +6586,10 @@ export const withSpan = function () {
 /**
  * Provides the entry point for do-notation style stream composition.
  *
- * @example
+ * **Example** (Starting stream do notation)
+ *
  * ```ts
- * import { Console, Effect, Stream, pipe } from "effect"
+ * import { Console, Effect, pipe, Stream } from "effect"
  *
  * const program = pipe(
  *   Stream.Do,
@@ -6374,8 +6606,8 @@ export const withSpan = function () {
  * //=> [{ value: 1, next: 2 }, { value: 2, next: 3 }]
  * ```
  *
- * @since 4.0.0
  * @category Do Notation
+ * @since 2.0.0
  */
 export const Do = /*#__PURE__*/succeed({});
 const let_ = /*#__PURE__*/dual(3, (self, name, f) => map(self, a => ({
@@ -6386,7 +6618,8 @@ export {
 /**
  * Adds a computed field to the current Do-notation record.
  *
- * @example
+ * **Example** (Adding a computed field)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -6404,14 +6637,15 @@ export {
  * // [{ x: 2, y: 6 }]
  * ```
  *
- * @since 4.0.0
  * @category Do Notation
+ * @since 2.0.0
  */
 let_ as let };
 /**
  * Binds the result of a stream to a field in the do-notation record.
  *
- * @example
+ * **Example** (Binding a stream value)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -6426,8 +6660,8 @@ let_ as let };
  * // [{ a: 1, b: 2 }, { a: 2, b: 3 }]
  * ```
  *
- * @since 4.0.0
  * @category Do Notation
+ * @since 2.0.0
  */
 export const bind = /*#__PURE__*/dual(args => isStream(args[0]), (self, tag, f, options) => flatMap(self, a => map(f(a), b => ({
   ...a,
@@ -6436,7 +6670,8 @@ export const bind = /*#__PURE__*/dual(args => isStream(args[0]), (self, tag, f,
 /**
  * Binds an Effect-produced value into the do-notation record for each stream element.
  *
- * @example
+ * **Example** (Binding an effect value)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -6454,8 +6689,8 @@ export const bind = /*#__PURE__*/dual(args => isStream(args[0]), (self, tag, f,
  * // [{ value: 1, double: 2 }, { value: 2, double: 4 }]
  * ```
  *
- * @since 4.0.0
  * @category Do Notation
+ * @since 2.0.0
  */
 export const bindEffect = /*#__PURE__*/dual(args => isStream(args[0]), (self, tag, f, options) => mapEffect(self, a => Effect.map(f(a), b => ({
   ...a,
@@ -6464,7 +6699,8 @@ export const bindEffect = /*#__PURE__*/dual(args => isStream(args[0]), (self, ta
 /**
  * Maps each element into a record keyed by the provided name.
  *
- * @example
+ * **Example** (Binding values to a record key)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -6477,7 +6713,7 @@ export const bindEffect = /*#__PURE__*/dual(args => isStream(args[0]), (self, ta
  * ```
  *
  * @category Do Notation
- * @since 4.0.0
+ * @since 2.0.0
  */
 export const bindTo = /*#__PURE__*/dual(2, (self, name) => map(self, a => ({
   [name]: a
@@ -6485,7 +6721,8 @@ export const bindTo = /*#__PURE__*/dual(2, (self, name) => map(self, a => ({
 /**
  * Runs a stream with a sink and returns the sink result.
  *
- * @example
+ * **Example** (Running a stream with a sink)
+ *
  * ```ts
  * import { Console, Effect, Sink, Stream } from "effect"
  *
@@ -6495,14 +6732,15 @@ export const bindTo = /*#__PURE__*/dual(2, (self, name) => map(self, a => ({
  * // 6
  * ```
  *
+ * @category destructors
  * @since 2.0.0
- * @category Destructors
  */
 export const run = /*#__PURE__*/dual(2, (self, sink) => Effect.scopedWith(scope => Channel.toPullScoped(self.channel, scope).pipe(Effect.flatMap(upstream => sink.transform(upstream, scope)), Effect.map(([a]) => a))));
 /**
  * Runs the stream and collects all elements into an array.
  *
- * @example
+ * **Example** (Collecting stream values)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -6517,8 +6755,8 @@ export const run = /*#__PURE__*/dual(2, (self, sink) => Effect.scopedWith(scope
  * // [1, 2, 3, 4, 5]
  * ```
  *
+ * @category destructors
  * @since 2.0.0
- * @category Destructors
  */
 export const runCollect = self => Channel.runFold(self.channel, () => [], (acc, chunk) => {
   for (let i = 0; i < chunk.length; i++) {
@@ -6529,7 +6767,8 @@ export const runCollect = self => Channel.runFold(self.channel, () => [], (acc,
 /**
  * Runs the stream and returns the number of elements emitted.
  *
- * @example
+ * **Example** (Counting stream values)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -6544,14 +6783,15 @@ export const runCollect = self => Channel.runFold(self.channel, () => [], (acc,
  * // 5
  * ```
  *
+ * @category destructors
  * @since 2.0.0
- * @category Destructors
  */
 export const runCount = self => Channel.runFold(self.channel, () => 0, (acc, chunk) => acc + chunk.length);
 /**
  * Runs the stream and returns the numeric sum of its elements.
  *
- * @example
+ * **Example** (Summing stream values)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -6564,8 +6804,8 @@ export const runCount = self => Channel.runFold(self.channel, () => 0, (acc, chu
  * // 6
  * ```
  *
+ * @category destructors
  * @since 2.0.0
- * @category Destructors
  */
 export const runSum = self => Channel.runFold(self.channel, () => 0, (acc, chunk) => {
   for (let i = 0; i < chunk.length; i++) {
@@ -6576,7 +6816,8 @@ export const runSum = self => Channel.runFold(self.channel, () => 0, (acc, chunk
 /**
  * Runs the stream and folds elements using a pure reducer.
  *
- * @example
+ * **Example** (Folding stream values)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -6593,8 +6834,8 @@ export const runSum = self => Channel.runFold(self.channel, () => 0, (acc, chunk
  * // 6
  * ```
  *
+ * @category destructors
  * @since 2.0.0
- * @category Destructors
  */
 export const runFold = /*#__PURE__*/dual(3, (self, initial, f) => Channel.runFold(self.channel, initial, (acc, arr) => {
   for (let i = 0; i < arr.length; i++) {
@@ -6605,7 +6846,8 @@ export const runFold = /*#__PURE__*/dual(3, (self, initial, f) => Channel.runFol
 /**
  * Runs the stream and folds elements using an effectful reducer.
  *
- * @example
+ * **Example** (Effectfully folding stream values)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -6622,8 +6864,8 @@ export const runFold = /*#__PURE__*/dual(3, (self, initial, f) => Channel.runFol
  * // 6
  * ```
  *
+ * @category destructors
  * @since 2.0.0
- * @category Destructors
  */
 export const runFoldEffect = /*#__PURE__*/dual(3, (self, initial, f) => Channel.runFoldEffect(self.channel, initial, (acc, arr) => {
   let i = 0;
@@ -6640,7 +6882,8 @@ export const runFoldEffect = /*#__PURE__*/dual(3, (self, initial, f) => Channel.
 /**
  * Runs the stream and returns the first element as an `Option`.
  *
- * @example
+ * **Example** (Getting the first stream value)
+ *
  * ```ts
  * import { Console, Effect, Option, Stream } from "effect"
  *
@@ -6653,21 +6896,22 @@ export const runFoldEffect = /*#__PURE__*/dual(3, (self, initial, f) => Channel.
  * // 1
  * ```
  *
+ * @category destructors
  * @since 2.0.0
- * @category Destructors
  */
 export const runHead = self => Effect.map(Channel.runHead(self.channel), Option.map(Arr.getUnsafe(0)));
 /**
  * Runs the stream and returns the last element as an `Option`.
  *
+ * @category destructors
  * @since 2.0.0
- * @category Destructors
  */
 export const runLast = self => Effect.map(Channel.runLast(self.channel), Option.map(Arr.lastNonEmpty));
 /**
  * Runs the provided effectful callback for each element of the stream.
  *
- * @example
+ * **Example** (Running an effect for each value)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -6683,8 +6927,8 @@ export const runLast = self => Effect.map(Channel.runLast(self.channel), Option.
  * // Processing: 3
  * ```
  *
+ * @category destructors
  * @since 2.0.0
- * @category Destructors
  */
 export const runForEach = /*#__PURE__*/dual(2, (self, f) => Channel.runForEach(self.channel, arr => {
   let i = 0;
@@ -6698,7 +6942,8 @@ export const runForEach = /*#__PURE__*/dual(2, (self, f) => Channel.runForEach(s
  * Runs the stream, applying the effectful predicate to each element and
  * stopping when it returns `false`.
  *
- * @example
+ * **Example** (Running effects while a predicate holds)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -6719,8 +6964,8 @@ export const runForEach = /*#__PURE__*/dual(2, (self, f) => Channel.runForEach(s
  * // Processing: 3
  * ```
  *
+ * @category destructors
  * @since 2.0.0
- * @category Destructors
  */
 export const runForEachWhile = /*#__PURE__*/dual(2, (self, f) => Channel.runForEachWhile(self.channel, arr => {
   let done = false;
@@ -6737,7 +6982,8 @@ export const runForEachWhile = /*#__PURE__*/dual(2, (self, f) => Channel.runForE
 /**
  * Consumes the stream in chunks, passing each non-empty array to the callback.
  *
- * @example
+ * **Example** (Consuming stream chunks)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -6753,14 +6999,15 @@ export const runForEachWhile = /*#__PURE__*/dual(2, (self, f) => Channel.runForE
  * // Processing chunk: 1, 2, 3, 4, 5
  * ```
  *
- * @since 2.0.0
- * @category Destructors
+ * @category destructors
+ * @since 4.0.0
  */
 export const runForEachArray = /*#__PURE__*/dual(2, (self, f) => Channel.runForEach(self.channel, f));
 /**
  * Runs the stream for its effects, discarding emitted elements.
  *
- * @example
+ * **Example** (Draining a stream run)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -6778,8 +7025,8 @@ export const runForEachArray = /*#__PURE__*/dual(2, (self, f) => Channel.runForE
  * // Processing: 3
  * ```
  *
+ * @category destructors
  * @since 2.0.0
- * @category Destructors
  */
 export const runDrain = self => Channel.runDrain(self.channel);
 /**
@@ -6788,7 +7035,8 @@ export const runDrain = self => Channel.runDrain(self.channel);
  * The pull fails with `Cause.Done` when the stream ends and with the stream
  * error on failure.
  *
- * @example
+ * **Example** (Creating a scoped pull)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -6806,14 +7054,15 @@ export const runDrain = self => Channel.runDrain(self.channel);
  * // [1, 2, 3]
  * ```
  *
+ * @category destructors
  * @since 2.0.0
- * @category Destructors
  */
 export const toPull = self => Channel.toPull(self.channel);
 /**
  * Concatenates all emitted strings into a single string.
  *
- * @example
+ * **Example** (Joining strings from a stream)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -6827,14 +7076,15 @@ export const toPull = self => Channel.toPull(self.channel);
  * // Hello World!
  * ```
  *
+ * @category destructors
  * @since 2.0.0
- * @category Destructors
  */
 export const mkString = self => Channel.runFold(self.channel, () => "", (acc, chunk) => acc + chunk.join(""));
 /**
  * Concatenates the stream's `Uint8Array` chunks into a single `Uint8Array`.
  *
- * @example
+ * **Example** (Joining Uint8Array chunks)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -6848,8 +7098,8 @@ export const mkString = self => Channel.runFold(self.channel, () => "", (acc, ch
  * // [1, 2, 3, 4]
  * ```
  *
+ * @category destructors
  * @since 4.0.0
- * @category Destructors
  */
 export const mkUint8Array = self => Effect.map(Channel.runFold(self.channel, () => ({
   bytes: 0,
@@ -6878,7 +7128,8 @@ export const mkUint8Array = self => Effect.map(Channel.runFold(self.channel, ()
  *
  * See https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream.
  *
- * @example
+ * **Example** (Converting to a ReadableStream with services)
+ *
  * ```ts
  * import { Context, Stream } from "effect"
  *
@@ -6886,8 +7137,8 @@ export const mkUint8Array = self => Effect.map(Channel.runFold(self.channel, ()
  * const readableStream = Stream.toReadableStreamWith(stream, Context.empty())
  * ```
  *
- * @since 2.0.0
- * @category Destructors
+ * @category destructors
+ * @since 4.0.0
  */
 export const toReadableStreamWith = /*#__PURE__*/dual(args => isStream(args[0]), (self, context, options) => {
   let currentResolve = undefined;
@@ -6928,7 +7179,8 @@ export const toReadableStreamWith = /*#__PURE__*/dual(args => isStream(args[0]),
  *
  * See https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream.
  *
- * @example
+ * **Example** (Converting a stream to a ReadableStream)
+ *
  * ```ts
  * import { Stream } from "effect"
  *
@@ -6936,8 +7188,8 @@ export const toReadableStreamWith = /*#__PURE__*/dual(args => isStream(args[0]),
  * const reader = readableStream.getReader()
  * ```
  *
+ * @category destructors
  * @since 2.0.0
- * @category Destructors
  */
 export const toReadableStream = /*#__PURE__*/dual(args => isStream(args[0]), (self, options) => toReadableStreamWith(self, Context.empty(), options));
 /**
@@ -6945,7 +7197,8 @@ export const toReadableStream = /*#__PURE__*/dual(args => isStream(args[0]), (se
  *
  * See https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream.
  *
- * @example
+ * **Example** (Creating a ReadableStream effect)
+ *
  * ```ts
  * import { Console, Effect, Stream } from "effect"
  *
@@ -6959,14 +7212,15 @@ export const toReadableStream = /*#__PURE__*/dual(args => isStream(args[0]), (se
  * Effect.runPromise(effect)
  * ```
  *
+ * @category destructors
  * @since 2.0.0
- * @category Destructors
  */
 export const toReadableStreamEffect = /*#__PURE__*/dual(args => isStream(args[0]), (self, options) => Effect.map(Effect.context(), context => toReadableStreamWith(self, context, options)));
 /**
  * Converts the stream to an `AsyncIterable` using the provided services.
  *
- * @example
+ * **Example** (Converting to an AsyncIterable with services)
+ *
  * ```ts
  * import { Context, Stream } from "effect"
  *
@@ -6978,12 +7232,15 @@ export const toReadableStreamEffect = /*#__PURE__*/dual(args => isStream(args[0]
  *   for await (const value of iterable) {
  *     results.push(value)
  *   }
- *   return results
+ *   console.log(results)
  * }
+ *
+ * collect()
+ * // [ 1, 2, 3 ]
  * ```
  *
- * @since 2.0.0
- * @category Destructors
+ * @category destructors
+ * @since 4.0.0
  */
 export const toAsyncIterableWith = /*#__PURE__*/dual(2, (self, context) => ({
   [Symbol.asyncIterator]() {
@@ -7024,9 +7281,10 @@ export const toAsyncIterableWith = /*#__PURE__*/dual(2, (self, context) => ({
 /**
  * Creates an effect that yields an `AsyncIterable` using the current services.
  *
- * @example
+ * **Example** (Creating an AsyncIterable effect)
+ *
  * ```ts
- * import { Console, Effect, Stream } from "effect"
+ * import { Effect, Stream } from "effect"
  *
  * const stream = Stream.make(1, 2, 3)
  *
@@ -7039,41 +7297,42 @@ export const toAsyncIterableWith = /*#__PURE__*/dual(2, (self, context) => ({
  *     }
  *     return collected
  *   })
- *   yield* Console.log(values)
+ *   yield* Effect.sync(() => console.log(values))
  * })
  *
  * Effect.runPromise(program)
- * //=> [ 1, 2, 3 ]
+ * // [ 1, 2, 3 ]
  * ```
  *
- * @since 2.0.0
- * @category Destructors
+ * @category destructors
+ * @since 3.15.0
  */
 export const toAsyncIterableEffect = self => Effect.map(Effect.context(), context => toAsyncIterableWith(self, context));
 /**
  * Converts a stream to an `AsyncIterable` for `for await...of` consumption.
  *
- * @example
+ * **Example** (Converting to an async iterable)
+ *
  * ```ts
- * import { Effect, Stream } from "effect"
+ * import { Stream } from "effect"
  *
  * const stream = Stream.make(1, 2, 3)
  *
- * const program = Effect.gen(function* () {
+ * const collect = async () => {
  *   const iterable = Stream.toAsyncIterable(stream)
- *   const results = yield* Effect.promise(async () => {
- *     const values: Array<number> = []
- *     for await (const value of iterable) {
- *       values.push(value)
- *     }
- *     return values
- *   })
- *   return results
- * })
+ *   const values: Array<number> = []
+ *   for await (const value of iterable) {
+ *     values.push(value)
+ *   }
+ *   console.log(values)
+ * }
+ *
+ * collect()
+ * // [ 1, 2, 3 ]
  * ```
  *
- * @since 2.0.0
- * @category Destructors
+ * @category destructors
+ * @since 3.15.0
  */
 export const toAsyncIterable = self => toAsyncIterableWith(self, Context.empty());
 /**
@@ -7082,7 +7341,8 @@ export const toAsyncIterable = self => toAsyncIterableWith(self, Context.empty()
  * `shutdownOnEnd` controls whether the PubSub is shut down when the stream ends.
  * It only shuts down when set to `true`.
  *
- * @example
+ * **Example** (Running a stream into a PubSub)
+ *
  * ```ts
  * import { Console, Effect, PubSub, Stream } from "effect"
  *
@@ -7104,8 +7364,8 @@ export const toAsyncIterable = self => toAsyncIterableWith(self, Context.empty()
  * //=> 2
  * ```
  *
+ * @category destructors
  * @since 2.0.0
- * @category Destructors
  */
 export const runIntoPubSub = /*#__PURE__*/dual(args => isStream(args[0]), (self, pubsub, options) => Channel.runIntoPubSubArray(self.channel, pubsub, options));
 /**
@@ -7114,7 +7374,8 @@ export const runIntoPubSub = /*#__PURE__*/dual(args => isStream(args[0]), (self,
  * `shutdownOnEnd` indicates whether the PubSub should be shut down when the
  * stream ends. By default this is `true`.
  *
- * @example
+ * **Example** (Converting a stream to a PubSub for concurrent consumption)
+ *
  * ```ts
  * import { Console, Effect, PubSub, Stream } from "effect"
  *
@@ -7129,8 +7390,8 @@ export const runIntoPubSub = /*#__PURE__*/dual(args => isStream(args[0]), (self,
  * }))
  * ```
  *
+ * @category destructors
  * @since 2.0.0
- * @category Destructors
  */
 export const toPubSub = /*#__PURE__*/dual(2, (self, options) => Channel.toPubSubArray(self.channel, options));
 /**
@@ -7138,7 +7399,8 @@ export const toPubSub = /*#__PURE__*/dual(2, (self, options) => Channel.toPubSub
  *
  * `Take` values include the stream's end and failure signals.
  *
- * @example
+ * **Example** (Converting to a PubSub of takes)
+ *
  * ```ts
  * import { Console, Effect, PubSub, Stream } from "effect"
  *
@@ -7155,14 +7417,20 @@ export const toPubSub = /*#__PURE__*/dual(2, (self, options) => Channel.toPubSub
  * })
  * ```
  *
+ * @category destructors
  * @since 4.0.0
- * @category Destructors
  */
 export const toPubSubTake = /*#__PURE__*/dual(2, (self, options) => Channel.toPubSubTake(self.channel, options));
 /**
- * Converts a stream to a Queue for concurrent consumption.
+ * Creates a scoped dequeue that is fed by the stream for concurrent
+ * consumption.
+ *
+ * Elements are offered to the queue as the stream runs. Stream completion is
+ * signaled with `Cause.Done`, stream failures fail the queue, and the queue is
+ * shut down when the surrounding scope closes.
+ *
+ * **Example** (Converting a stream to a Queue for concurrent consumption)
  *
- * @example
  * ```ts
  * import { Effect, Queue, Stream } from "effect"
  *
@@ -7173,15 +7441,16 @@ export const toPubSubTake = /*#__PURE__*/dual(2, (self, options) => Channel.toPu
  * })
  * ```
  *
+ * @category destructors
  * @since 2.0.0
- * @category Destructors
  */
 export const toQueue = /*#__PURE__*/dual(2, (self, options) => Channel.toQueueArray(self.channel, options));
 /**
  * Runs the stream, offering each element to the provided queue and ending it
  * with `Cause.Done` when the stream completes.
  *
- * @example
+ * **Example** (Running a stream into a queue)
+ *
  * ```ts
  * import { Cause, Effect, Queue, Stream } from "effect"
  *
@@ -7203,8 +7472,8 @@ export const toQueue = /*#__PURE__*/dual(2, (self, options) => Channel.toQueueAr
  * })
  * ```
  *
+ * @category destructors
  * @since 2.0.0
- * @category Destructors
  */
 export const runIntoQueue = /*#__PURE__*/dual(2, (self, queue) => Channel.runIntoQueueArray(self.channel, queue));
 //# sourceMappingURL=Stream.js.map