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

package/dist/Channel.js

@@ -28,7 +28,8 @@
  * 2. **Sequencing**: Use the result of one channel to create another
  * 3. **Concatenating**: Combine multiple channels into a single channel
  *
- * @example
+ * **Example** (Creating a simple channel)
+ *
  * ```ts
  * import { Channel } from "effect"
  *
@@ -41,7 +42,8 @@
  * // Running the channel would output: 84
  * ```
  *
- * @example
+ * **Example** (Transforming array-backed channels)
+ *
  * ```ts
  * import { Channel } from "effect"
  *
@@ -85,14 +87,18 @@ import * as String from "./String.js";
 import * as Take from "./Take.js";
 import { ParentSpan } from "./Tracer.js";
 /**
- * @since 4.0.0
+ * Runtime identifier stored on `Channel` values and used by `isChannel` to
+ * recognize them.
+ *
  * @category Type Identifiers
+ * @since 4.0.0
  */
 export const TypeId = "~effect/Channel";
 /**
  * Tests if a value is a `Channel`.
  *
- * @example
+ * **Example** (Checking for channels)
+ *
  * ```ts
  * import { Channel } from "effect"
  *
@@ -123,7 +129,8 @@ const ChannelProto = {
 /**
  * Creates a `Channel` from a transformation function that operates on upstream pulls.
  *
- * @example
+ * **Example** (Creating channels from transforms)
+ *
  * ```ts
  * import { Channel, Effect } from "effect"
  *
@@ -143,7 +150,8 @@ export const fromTransform = transform => {
 /**
  * Transforms a Channel by applying a function to its Pull implementation.
  *
- * @example
+ * **Example** (Transforming pull behavior)
+ *
  * ```ts
  * import { Channel, Effect } from "effect"
  *
@@ -167,7 +175,8 @@ export const transformPull = (self, f) => fromTransform((upstream, scope) => Eff
 /**
  * Creates a `Channel` from an `Effect` that produces a `Pull`.
  *
- * @example
+ * **Example** (Creating channels from pulls)
+ *
  * ```ts
  * import { Channel, Effect } from "effect"
  *
@@ -185,8 +194,8 @@ export const fromPull = effect => fromTransform((_, __) => effect);
  * pulls, but also provides a forked scope that closes when the resulting
  * Channel completes.
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const fromTransformBracket = f => fromTransform(Effect.fnUntraced(function* (upstream, scope) {
   const closableScope = Scope.forkUnsafe(scope);
@@ -197,7 +206,8 @@ export const fromTransformBracket = f => fromTransform(Effect.fnUntraced(functio
 /**
  * Converts a `Channel` back to its underlying transformation function.
  *
- * @example
+ * **Example** (Extracting channel transforms)
+ *
  * ```ts
  * import { Channel } from "effect"
  *
@@ -213,7 +223,8 @@ export const toTransform = channel => channel.transform;
 /**
  * The default chunk size used by channels for batching operations.
  *
- * @example
+ * **Example** (Reading the default chunk size)
+ *
  * ```ts
  * import { Channel } from "effect"
  *
@@ -221,7 +232,7 @@ export const toTransform = channel => channel.transform;
  * ```
  *
  * @category constants
- * @since 2.0.0
+ * @since 4.0.0
  */
 export const DefaultChunkSize = 4096;
 const asyncQueue = (scope, f, options) => Queue.make({
@@ -231,7 +242,8 @@ const asyncQueue = (scope, f, options) => Queue.make({
 /**
  * Creates a `Channel` that interacts with a callback function using a queue.
  *
- * @example
+ * **Example** (Creating channels from callbacks)
+ *
  * ```ts
  * import { Channel, Effect, Queue } from "effect"
  *
@@ -245,13 +257,14 @@ const asyncQueue = (scope, f, options) => Queue.make({
  * ```
  *
  * @category constructors
- * @since 2.0.0
+ * @since 4.0.0
  */
 export const callback = (f, options) => fromTransform((_, scope) => Effect.map(asyncQueue(scope, f, options), Queue.take));
 /**
  * Creates a `Channel` that interacts with a callback function using a queue, emitting arrays.
  *
- * @example
+ * **Example** (Creating array channels from callbacks)
+ *
  * ```ts
  * import { Channel, Effect, Queue } from "effect"
  *
@@ -269,7 +282,8 @@ export const callbackArray = (f, options) => fromTransform((_, scope) => Effect.
 /**
  * Creates a `Channel` that lazily evaluates to another channel.
  *
- * @example
+ * **Example** (Suspending channel creation)
+ *
  * ```ts
  * import { Channel } from "effect"
  *
@@ -282,9 +296,15 @@ export const callbackArray = (f, options) => fromTransform((_, scope) => Effect.
  */
 export const suspend = evaluate => fromTransform((upstream, scope) => Effect.suspend(() => toTransform(evaluate())(upstream, scope)));
 /**
- * Creates a `Channel` with resource management using acquire-use-release pattern.
+ * Acquires a resource, uses it to build a `Channel`, and guarantees that
+ * `release` runs with the channel's `Exit` when the channel completes, fails,
+ * or is interrupted.
+ *
+ * Acquisition is uninterruptible. If acquisition fails, `use` is not run and
+ * `release` is not registered.
+ *
+ * **Example** (Managing resources with acquire-use-release)
  *
- * @example
  * ```ts
  * import { Channel, Effect } from "effect"
  *
@@ -306,9 +326,15 @@ export const acquireUseRelease = (acquire, use, release) => fromTransformBracket
   return yield* toTransform(use(value))(upstream, scope);
 }));
 /**
- * Creates a `Channel` with resource management using acquire-release pattern.
+ * Acquires a resource, emits the acquired value as a single channel element,
+ * and registers `release` in the channel scope.
+ *
+ * The release action runs when the channel scope closes and receives the scope
+ * exit. If acquisition fails, no element is emitted and `release` is not
+ * registered.
+ *
+ * **Example** (Managing resources with acquire-release)
  *
- * @example
  * ```ts
  * import { Channel, Effect } from "effect"
  *
@@ -319,13 +345,14 @@ export const acquireUseRelease = (acquire, use, release) => fromTransformBracket
  * ```
  *
  * @category constructors
- * @since 2.0.0
+ * @since 4.0.0
  */
 export const acquireRelease = /*#__PURE__*/dual(2, (self, release) => unwrap(Effect.map(Effect.acquireRelease(self, release), succeed)));
 /**
  * Creates a `Channel` from an iterator.
  *
- * @example
+ * **Example** (Creating channels from iterators)
+ *
  * ```ts
  * import { Channel } from "effect"
  *
@@ -335,7 +362,7 @@ export const acquireRelease = /*#__PURE__*/dual(2, (self, release) => unwrap(Eff
  * ```
  *
  * @category constructors
- * @since 2.0.0
+ * @since 4.0.0
  */
 export const fromIterator = iterator => fromPull(Effect.sync(() => {
   const iter = iterator();
@@ -347,7 +374,8 @@ export const fromIterator = iterator => fromPull(Effect.sync(() => {
 /**
  * Creates a `Channel` that emits all elements from an array.
  *
- * @example
+ * **Example** (Creating channels from arrays)
+ *
  * ```ts
  * import { Channel } from "effect"
  *
@@ -356,7 +384,7 @@ export const fromIterator = iterator => fromPull(Effect.sync(() => {
  * ```
  *
  * @category constructors
- * @since 2.0.0
+ * @since 4.0.0
  */
 export const fromArray = array => fromPull(Effect.sync(() => {
   let index = 0;
@@ -365,7 +393,8 @@ export const fromArray = array => fromPull(Effect.sync(() => {
 /**
  * Creates a `Channel` that emits all elements from a chunk.
  *
- * @example
+ * **Example** (Creating channels from chunks)
+ *
  * ```ts
  * import { Channel, Chunk } from "effect"
  *
@@ -375,13 +404,14 @@ export const fromArray = array => fromPull(Effect.sync(() => {
  * ```
  *
  * @category constructors
- * @since 2.0.0
+ * @since 4.0.0
  */
 export const fromChunk = chunk => fromArray(Chunk.toReadonlyArray(chunk));
 /**
  * Creates a `Channel` from an iterator that emits arrays of elements.
  *
- * @example
+ * **Example** (Batching iterator output)
+ *
  * ```ts
  * import { Channel } from "effect"
  *
@@ -402,7 +432,8 @@ export const fromChunk = chunk => fromArray(Chunk.toReadonlyArray(chunk));
  * // This will emit arrays: [0, 1], [2], then complete with "finished"
  * ```
  *
- * @example
+ * **Example** (Batching generator output)
+ *
  * ```ts
  * import { Channel } from "effect"
  *
@@ -419,8 +450,8 @@ export const fromChunk = chunk => fromArray(Chunk.toReadonlyArray(chunk));
  * // Emits: [0, 1, 1], [2, 3], then completes
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const fromIteratorArray = (iterator, chunkSize = DefaultChunkSize) => fromPull(Effect.sync(() => {
   const iter = iterator();
@@ -445,7 +476,8 @@ export const fromIteratorArray = (iterator, chunkSize = DefaultChunkSize) => fro
 /**
  * Creates a `Channel` that emits all elements from an iterable.
  *
- * @example
+ * **Example** (Creating channels from iterables)
+ *
  * ```ts
  * import { Channel } from "effect"
  *
@@ -455,13 +487,14 @@ export const fromIteratorArray = (iterator, chunkSize = DefaultChunkSize) => fro
  * ```
  *
  * @category constructors
- * @since 2.0.0
+ * @since 4.0.0
  */
 export const fromIterable = iterable => fromIterator(() => iterable[Symbol.iterator]());
 /**
  * Creates a `Channel` that emits arrays of elements from an iterable.
  *
- * @example
+ * **Example** (Batching iterable output)
+ *
  * ```ts
  * import { Channel } from "effect"
  *
@@ -471,13 +504,14 @@ export const fromIterable = iterable => fromIterator(() => iterable[Symbol.itera
  * ```
  *
  * @category constructors
- * @since 2.0.0
+ * @since 4.0.0
  */
 export const fromIterableArray = (iterable, chunkSize = DefaultChunkSize) => fromIteratorArray(() => iterable[Symbol.iterator](), chunkSize);
 /**
  * Creates a `Channel` that emits a single value and then ends.
  *
- * @example
+ * **Example** (Creating channels that succeed)
+ *
  * ```ts
  * import { Channel } from "effect"
  *
@@ -492,7 +526,8 @@ export const succeed = value => fromEffect(Effect.succeed(value));
 /**
  * Creates a `Channel` that immediately ends with the specified value.
  *
- * @example
+ * **Example** (Ending with a value)
+ *
  * ```ts
  * import { Channel } from "effect"
  *
@@ -514,12 +549,18 @@ export const endSync = evaluate => fromPull(Effect.sync(() => Cause.done(evaluat
 /**
  * Creates a `Channel` that emits a single value computed by a lazy evaluation.
  *
- * @example
+ * **Example** (Computing values lazily)
+ *
  * ```ts
  * import { Channel } from "effect"
  *
- * const channel = Channel.sync(() => Math.random())
- * // Emits a random number computed when the channel runs
+ * let requests = 0
+ *
+ * const channel = Channel.sync(() => {
+ *   requests += 1
+ *   return `request-${requests}`
+ * })
+ * // Emits "request-1" when the channel runs for the first time
  * ```
  *
  * @category constructors
@@ -529,7 +570,8 @@ export const sync = evaluate => fromEffect(Effect.sync(evaluate));
 /**
  * Represents an Channel that emits no elements
  *
- * @example
+ * **Example** (Using empty channels)
+ *
  * ```ts
  * import { Channel } from "effect"
  *
@@ -545,14 +587,15 @@ export const sync = evaluate => fromEffect(Effect.sync(evaluate));
  *   shouldEmit ? Channel.succeed("data") : Channel.empty
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const empty = /*#__PURE__*/fromPull(/*#__PURE__*/Effect.succeed(/*#__PURE__*/Cause.done()));
 /**
  * Represents an Channel that never completes
  *
- * @example
+ * **Example** (Using non-terminating channels)
+ *
  * ```ts
  * import { Channel } from "effect"
  *
@@ -570,14 +613,15 @@ export const empty = /*#__PURE__*/fromPull(/*#__PURE__*/Effect.succeed(/*#__PURE
  *   shouldComplete ? Channel.succeed("done") : Channel.never
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const never = /*#__PURE__*/fromPull(/*#__PURE__*/Effect.succeed(Effect.never));
 /**
  * Constructs a channel that fails immediately with the specified error.
  *
- * @example
+ * **Example** (Failing with an error)
+ *
  * ```ts
  * import { Channel } from "effect"
  *
@@ -600,15 +644,16 @@ export const never = /*#__PURE__*/fromPull(/*#__PURE__*/Effect.succeed(Effect.ne
  * )
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const fail = error => fromPull(Effect.succeed(Effect.fail(error)));
 /**
  * Constructs a channel that fails immediately with the specified lazily
  * evaluated error.
  *
- * @example
+ * **Example** (Failing with a lazy error)
+ *
  * ```ts
  * import { Channel } from "effect"
  *
@@ -619,25 +664,28 @@ export const fail = error => fromPull(Effect.succeed(Effect.fail(error)));
  * })
  *
  * // The error computation is deferred until the channel runs
- * const conditionalError = Channel.failSync(() =>
- *   Math.random() > 0.5 ? "Error A" : "Error B"
- * )
+ * let attempts = 0
+ * const conditionalError = Channel.failSync(() => {
+ *   attempts += 1
+ *   return `Error after attempt ${attempts}`
+ * })
  *
  * // Use with expensive error construction
  * const expensiveError = Channel.failSync(() => {
- *   const timestamp = Date.now()
- *   return new Error(`Failed at: ${timestamp}`)
+ *   const requestId = "request-123"
+ *   return new Error(`Failed while processing ${requestId}`)
  * })
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const failSync = evaluate => fromPull(Effect.failSync(evaluate));
 /**
  * Constructs a channel that fails immediately with the specified `Cause`.
  *
- * @example
+ * **Example** (Failing with causes)
+ *
  * ```ts
  * import { Cause, Channel } from "effect"
  *
@@ -654,39 +702,42 @@ export const failSync = evaluate => fromPull(Effect.failSync(evaluate));
  * const simpleFail = Channel.failCause(failCause)
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const failCause = cause => fromPull(Effect.failCause(cause));
 /**
  * Constructs a channel that fails immediately with the specified lazily
  * evaluated `Cause`.
  *
- * @example
+ * **Example** (Failing with lazy causes)
+ *
  * ```ts
  * import { Cause, Channel } from "effect"
  *
  * // Create a channel that fails with a lazily computed cause
+ * let attempts = 0
  * const failedChannel = Channel.failCauseSync(() => {
- *   const errorType = Math.random() > 0.5 ? "A" : "B"
- *   return Cause.fail(`Runtime error ${errorType}`)
+ *   attempts += 1
+ *   return Cause.fail(`Runtime error after attempt ${attempts}`)
  * })
  *
  * // Create a channel with die cause computation
  * const dieCauseChannel = Channel.failCauseSync(() => {
- *   const timestamp = Date.now()
- *   return Cause.die(`Error at ${timestamp}`)
+ *   const operation = "load-profile"
+ *   return Cause.die(`Unexpected defect during ${operation}`)
  * })
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const failCauseSync = evaluate => fromPull(Effect.failCauseSync(evaluate));
 /**
  * Constructs a channel that fails immediately with the specified defect.
  *
- * @example
+ * **Example** (Dying with defects)
+ *
  * ```ts
  * import { Channel } from "effect"
  *
@@ -703,14 +754,15 @@ export const failCauseSync = evaluate => fromPull(Effect.failCauseSync(evaluate)
  * })
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const die = defect => failCause(Cause.die(defect));
 /**
  * Use an effect to write a single value to the channel.
  *
- * @example
+ * **Example** (Creating channels from effects)
+ *
  * ```ts
  * import { Channel, Data, Effect } from "effect"
  *
@@ -740,8 +792,8 @@ export const die = defect => failCause(Cause.die(defect));
  * )
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const fromEffect = effect => fromPull(Effect.sync(() => {
   let done = false;
@@ -752,26 +804,38 @@ export const fromEffect = effect => fromPull(Effect.sync(() => {
   });
 }));
 /**
- * @since 4.0.0
+ * Creates a channel that evaluates an effect and uses its successful value as
+ * the channel's done value without emitting any output elements.
+ *
+ * If the effect fails, the channel fails with the effect's error.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const fromEffectDone = effect => fromPull(Effect.succeed(Effect.flatMap(effect, Cause.done)));
 /**
  * Use an effect and discard its result.
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const fromEffectDrain = effect => fromPull(Effect.flatMap(effect, () => Cause.done()));
 /**
- * @since 4.0.0
+ * Creates a channel from an effect that produces a `Take`.
+ *
+ * A successful `Take` emits a non-empty array of output elements. A failed
+ * `Take` fails the channel. A done `Take` completes the channel with its done
+ * value.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const fromEffectTake = effect => fromPull(Effect.succeed(Effect.flatMap(effect, Take.toPull)));
 /**
  * Create a channel from a queue
  *
- * @example
+ * **Example** (Creating channels from queues)
+ *
  * ```ts
  * import { Channel, Data, Effect, Queue } from "effect"
  *
@@ -803,14 +867,15 @@ export const fromEffectTake = effect => fromPull(Effect.succeed(Effect.flatMap(e
  * })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const fromQueue = queue => fromPull(Effect.succeed(Queue.take(queue)));
 /**
  * Create a channel from a queue that emits arrays of elements
  *
- * @example
+ * **Example** (Creating batched channels from queues)
+ *
  * ```ts
  * import { Channel, Data, Effect, Queue } from "effect"
  *
@@ -846,19 +911,23 @@ export const fromQueue = queue => fromPull(Effect.succeed(Queue.take(queue)));
  * })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const fromQueueArray = queue => fromPull(Effect.succeed(Queue.takeAll(queue)));
 /**
+ * Creates a channel that forwards upstream input elements, input errors, and
+ * the upstream done value unchanged.
+ *
+ * @category constructors
  * @since 2.0.0
- * @category Constructors
  */
 export const identity = () => fromTransform((upstream, _scope) => Effect.succeed(upstream));
 /**
  * Create a channel from a PubSub subscription
  *
- * @example
+ * **Example** (Creating channels from subscriptions)
+ *
  * ```ts
  * import { Channel, Data, Effect, PubSub } from "effect"
  *
@@ -895,8 +964,8 @@ export const identity = () => fromTransform((upstream, _scope) => Effect.succeed
  * })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const fromSubscription = subscription => fromPull(Effect.succeed(Effect.onInterrupt(PubSub.take(subscription), () => Cause.done())));
 /**
@@ -906,10 +975,8 @@ export const fromSubscription = subscription => fromPull(Effect.succeed(Effect.o
  * arrays of values in chunks. It's useful when you want to process multiple values at once
  * for better performance.
  *
- * @param subscription - The PubSub subscription to read from
- * @param chunkSize - The maximum number of elements to read in each chunk (default: 4096)
+ * **Example** (Batching subscription values)
  *
- * @example
  * ```ts
  * import { Channel, Data, Effect, PubSub } from "effect"
  *
@@ -935,7 +1002,8 @@ export const fromSubscription = subscription => fromPull(Effect.succeed(Effect.o
  * })
  * ```
  *
- * @example
+ * **Example** (Processing subscription values in batches)
+ *
  * ```ts
  * import { Channel, Data, Effect, PubSub } from "effect"
  *
@@ -960,13 +1028,10 @@ export const fromSubscription = subscription => fromPull(Effect.succeed(Effect.o
  * })
  * ```
  *
- * @example
- * ```ts
- * import { Channel, Data, Effect, PubSub } from "effect"
+ * **Example** (Aggregating subscription metrics)
  *
- * class MetricsError extends Data.TaggedError("MetricsError")<{
- *   readonly cause: string
- * }> {}
+ * ```ts
+ * import { Channel, Effect, PubSub } from "effect"
  *
  * const metricsAggregator = Effect.gen(function*() {
  *   const metricsPubSub = yield* PubSub.bounded<
@@ -991,7 +1056,8 @@ export const fromSubscription = subscription => fromPull(Effect.succeed(Effect.o
  *       average: avg,
  *       min,
  *       max,
- *       timestamp: Date.now()
+ *       firstTimestamp: Math.min(...metrics.map((m) => m.timestamp)),
+ *       lastTimestamp: Math.max(...metrics.map((m) => m.timestamp))
  *     }
  *   })
  *
@@ -999,8 +1065,8 @@ export const fromSubscription = subscription => fromPull(Effect.succeed(Effect.o
  * })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const fromSubscriptionArray = subscription => fromPull(Effect.succeed(Effect.onInterrupt(PubSub.takeAll(subscription), () => Cause.done())));
 /**
@@ -1010,9 +1076,8 @@ export const fromSubscriptionArray = subscription => fromPull(Effect.succeed(Eff
  * subscribing to it. The channel outputs individual values as they are published
  * to the PubSub, making it ideal for real-time streaming scenarios.
  *
- * @param pubsub - The PubSub to read from
+ * **Example** (Creating channels from PubSubs)
  *
- * @example
  * ```ts
  * import { Channel, Data, Effect, PubSub } from "effect"
  *
@@ -1036,13 +1101,10 @@ export const fromSubscriptionArray = subscription => fromPull(Effect.succeed(Eff
  * })
  * ```
  *
- * @example
- * ```ts
- * import { Channel, Data, Effect, PubSub } from "effect"
+ * **Example** (Streaming PubSub notifications)
  *
- * class NotificationError extends Data.TaggedError("NotificationError")<{
- *   readonly reason: string
- * }> {}
+ * ```ts
+ * import { Channel, Effect, PubSub } from "effect"
  *
  * const notificationService = Effect.gen(function*() {
  *   const notificationPubSub = yield* PubSub.bounded<string>(50)
@@ -1051,24 +1113,21 @@ export const fromSubscriptionArray = subscription => fromPull(Effect.succeed(Eff
  *   const notificationChannel = Channel.fromPubSub(notificationPubSub)
  *
  *   // Transform notifications to add timestamps
+ *   const receivedAt = "2024-01-01T00:00:00.000Z"
  *   const timestampedChannel = Channel.map(notificationChannel, (message) => ({
  *     message,
- *     timestamp: new Date().toISOString(),
- *     id: Math.random().toString(36).substr(2, 9)
+ *     receivedAt,
+ *     id: `notification:${message}`
  *   }))
  *
  *   return timestampedChannel
  * })
  * ```
  *
- * @example
- * ```ts
- * import { Channel, Data, Effect, PubSub } from "effect"
+ * **Example** (Processing PubSub events)
  *
- * class EventProcessingError extends Data.TaggedError("EventProcessingError")<{
- *   readonly eventType: string
- *   readonly cause: string
- * }> {}
+ * ```ts
+ * import { Channel, Effect, PubSub } from "effect"
  *
  * interface DomainEvent {
  *   readonly type: string
@@ -1088,7 +1147,7 @@ export const fromSubscriptionArray = subscription => fromPull(Effect.succeed(Eff
  *       return {
  *         ...event,
  *         processed: true,
- *         processedAt: Date.now()
+ *         processedAt: event.timestamp + 1
  *       }
  *     }
  *     return event
@@ -1098,8 +1157,8 @@ export const fromSubscriptionArray = subscription => fromPull(Effect.succeed(Eff
  * })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const fromPubSub = pubsub => unwrap(Effect.map(PubSub.subscribe(pubsub), fromSubscription));
 /**
@@ -1109,10 +1168,8 @@ export const fromPubSub = pubsub => unwrap(Effect.map(PubSub.subscribe(pubsub),
  * subscribing to it and collecting values into arrays. The channel outputs
  * arrays of values in chunks, making it ideal for batch processing scenarios.
  *
- * @param pubsub - The PubSub to read from
- * @param chunkSize - The maximum number of elements to collect in each array (default: 4096)
+ * **Example** (Batching PubSub values)
  *
- * @example
  * ```ts
  * import { Channel, Data, Effect, PubSub } from "effect"
  *
@@ -1137,20 +1194,17 @@ export const fromPubSub = pubsub => unwrap(Effect.map(PubSub.subscribe(pubsub),
  * })
  * ```
  *
- * @example
- * ```ts
- * import { Channel, Data, Effect, PubSub } from "effect"
+ * **Example** (Processing PubSub orders in batches)
  *
- * class OrderProcessingError extends Data.TaggedError("OrderProcessingError")<{
- *   readonly orderId: string
- *   readonly reason: string
- * }> {}
+ * ```ts
+ * import { Channel, Effect, PubSub } from "effect"
  *
  * interface Order {
  *   readonly id: string
  *   readonly customerId: string
  *   readonly items: ReadonlyArray<string>
  *   readonly total: number
+ *   readonly submittedAt: number
  * }
  *
  * const orderBatchProcessor = Effect.gen(function*() {
@@ -1170,7 +1224,7 @@ export const fromPubSub = pubsub => unwrap(Effect.map(PubSub.subscribe(pubsub),
  *       batchSize: orderBatch.length,
  *       totalRevenue,
  *       uniqueCustomers: customerCount,
- *       processedAt: Date.now(),
+ *       firstSubmittedAt: Math.min(...orderBatch.map((order) => order.submittedAt)),
  *       orders: orderBatch
  *     }
  *   })
@@ -1179,14 +1233,10 @@ export const fromPubSub = pubsub => unwrap(Effect.map(PubSub.subscribe(pubsub),
  * })
  * ```
  *
- * @example
- * ```ts
- * import { Channel, Data, Effect, PubSub } from "effect"
+ * **Example** (Processing PubSub logs in batches)
  *
- * class LogProcessingError extends Data.TaggedError("LogProcessingError")<{
- *   readonly batchId: string
- *   readonly cause: string
- * }> {}
+ * ```ts
+ * import { Channel, Effect, PubSub } from "effect"
  *
  * interface LogEntry {
  *   readonly timestamp: number
@@ -1213,7 +1263,7 @@ export const fromPubSub = pubsub => unwrap(Effect.map(PubSub.subscribe(pubsub),
  *     }
  *
  *     return {
- *       batchId: Math.random().toString(36).substr(2, 9),
+ *       batchId: `${timeRange.start}-${timeRange.end}`,
  *       totalEntries: logBatch.length,
  *       errorCount,
  *       warnCount,
@@ -1227,27 +1277,37 @@ export const fromPubSub = pubsub => unwrap(Effect.map(PubSub.subscribe(pubsub),
  * })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const fromPubSubArray = pubsub => unwrap(Effect.map(PubSub.subscribe(pubsub), fromSubscriptionArray));
 /**
- * @since 4.0.0
+ * Subscribes to a `PubSub` of `Take` values and exposes them as a channel.
+ *
+ * Output `Take` values are emitted as non-empty arrays. Failed `Take` values
+ * fail the channel. Done `Take` values complete the channel.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const fromPubSubTake = pubsub => unwrap(Effect.map(PubSub.subscribe(pubsub), sub => fromEffectTake(PubSub.take(sub))));
 /**
  * Creates a Channel from a Schedule.
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const fromSchedule = schedule => fromPull(Effect.map(Schedule.toStepWithSleep(schedule), step => step(void 0)));
 /**
- * Creates a Channel from a AsyncIterable.
+ * Creates a channel that pulls values from an `AsyncIterable`.
+ *
+ * Each yielded value is emitted as an output element. The iterator's return
+ * value becomes the channel's done value. Thrown or rejected iterator errors
+ * are converted with `onError`. If the channel scope closes early and the
+ * iterator has a `return` method, that method is called.
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const fromAsyncIterable = (iterable, onError) => fromTransform(Effect.fnUntraced(function* (_, scope) {
   const iter = iterable[Symbol.asyncIterator]();
@@ -1260,16 +1320,22 @@ export const fromAsyncIterable = (iterable, onError) => fromTransform(Effect.fnU
   }), result => result.done ? Cause.done(result.value) : Effect.succeed(result.value));
 }));
 /**
- * Creates a Channel from a AsyncIterable that emits arrays of elements.
+ * Creates a channel from an `AsyncIterable`, emitting each yielded value as a
+ * single-element non-empty array.
+ *
+ * The iterator's return value becomes the channel's done value. Thrown or
+ * rejected iterator errors are converted with `onError`. If the channel scope
+ * closes early and the iterator has a `return` method, that method is called.
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const fromAsyncIterableArray = (iterable, onError) => map(fromAsyncIterable(iterable, onError), Arr.of);
 /**
  * Maps the output of this channel using the specified function.
  *
- * @example
+ * **Example** (Mapping channel output)
+ *
  * ```ts
  * import { Channel, Data } from "effect"
  *
@@ -1301,8 +1367,8 @@ export const fromAsyncIterableArray = (iterable, onError) => map(fromAsyncIterab
  * }))
  * ```
  *
+ * @category sequencing
  * @since 2.0.0
- * @category Sequencing
  */
 export const map = /*#__PURE__*/dual(2, (self, f) => transformPull(self, pull => Effect.sync(() => {
   let i = 0;
@@ -1311,26 +1377,29 @@ export const map = /*#__PURE__*/dual(2, (self, f) => transformPull(self, pull =>
 /**
  * Maps the done value of this channel using the specified function.
  *
- * @since 2.0.0
- * @category Sequencing
+ * @category sequencing
+ * @since 4.0.0
  */
 export const mapDone = /*#__PURE__*/dual(2, (self, f) => mapDoneEffect(self, o => Effect.succeed(f(o))));
 /**
  * Maps the done value of this channel using the specified effectful function.
  *
- * @since 2.0.0
- * @category Sequencing
+ * @category sequencing
+ * @since 4.0.0
  */
 export const mapDoneEffect = /*#__PURE__*/dual(2, (self, f) => transformPull(self, pull => Effect.succeed(Pull.catchDone(pull, done => Effect.flatMap(f(done), Cause.done)))));
 const concurrencyIsSequential = concurrency => concurrency === undefined || concurrency !== "unbounded" && concurrency <= 1;
 /**
- * Returns a new channel, which sequentially combines this channel, together
- * with the provided factory function, which creates a second channel based on
- * the output values of this channel. The result is a channel that will first
- * perform the functions of this channel, before performing the functions of
- * the created channel (including yielding its terminal value).
+ * Maps each output element with an effectful function, preserving the source
+ * channel's done value.
+ *
+ * The mapping function receives the output element and its zero-based index.
+ * By default elements are mapped sequentially. Use `options.concurrency` to
+ * map multiple elements concurrently, and `options.unordered` to allow
+ * concurrently mapped outputs to be emitted as soon as they complete.
+ *
+ * **Example** (Mapping channel output with effects)
  *
- * @example
  * ```ts
  * import { Channel, Data, Effect } from "effect"
  *
@@ -1367,8 +1436,8 @@ const concurrencyIsSequential = concurrency => concurrency === undefined || conc
  * )
  * ```
  *
- * @since 2.0.0
  * @category sequencing
+ * @since 2.0.0
  */
 export const mapEffect = /*#__PURE__*/dual(args => isChannel(args[0]), (self, f, options) => concurrencyIsSequential(options?.concurrency) ? mapEffectSequential(self, f) : mapEffectConcurrent(self, f, options));
 const mapEffectSequential = (self, f) => fromTransform((upstream, scope) => {
@@ -1427,16 +1496,16 @@ const mapEffectConcurrent = (self, f, options) => fromTransformBracket(Effect.fn
  * Returns a new channel which is the same as this one but applies the given
  * function to the input channel’s input elements.
  *
- * @since 2.0.0
  * @category sequencing
+ * @since 2.0.0
  */
 export const mapInput = /*#__PURE__*/dual(2, (self, f) => fromTransform((upstream, scope) => toTransform(self)(Effect.flatMap(upstream, el => f(el)), scope)));
 /**
  * Returns a new channel which is the same as this one but applies the given
  * function to the input errors.
  *
- * @since 2.0.0
  * @category sequencing
+ * @since 2.0.0
  */
 export const mapInputError = /*#__PURE__*/dual(2, (self, f) => fromTransform((upstream, scope) => toTransform(self)(Effect.catch(upstream, err => {
   if (Cause.isDone(err)) return Effect.fail(err);
@@ -1450,7 +1519,8 @@ export const mapInputError = /*#__PURE__*/dual(2, (self, f) => fromTransform((up
  * debugging) on each element emitted by a channel without modifying the
  * elements themselves.
  *
- * @example
+ * **Example** (Tapping channel output)
+ *
  * ```ts
  * import { Channel, Console, Data } from "effect"
  *
@@ -1471,18 +1541,21 @@ export const mapInputError = /*#__PURE__*/dual(2, (self, f) => fromTransform((up
  * // Outputs: 1, 2, 3 (while logging each)
  * ```
  *
- * @since 4.0.0
  * @category sequencing
+ * @since 4.0.0
  */
 export const tap = /*#__PURE__*/dual(args => isChannel(args[0]), (self, f, options) => mapEffect(self, a => Effect.as(f(a), a), options));
 /**
- * Returns a new channel, which sequentially combines this channel, together
- * with the provided factory function, which creates a second channel based on
- * the output values of this channel. The result is a channel that will first
- * perform the functions of this channel, before performing the functions of
- * the created channel (including yielding its terminal value).
+ * Maps each output element to a channel and flattens the child channel
+ * outputs.
+ *
+ * The source channel's done value is preserved. Child channel done values are
+ * used only for child-channel completion. By default child channels are run
+ * sequentially. Use `options.concurrency` and `options.bufferSize` to run child
+ * channels concurrently.
+ *
+ * **Example** (FlatMapping channel output)
  *
- * @example
  * ```ts
  * import { Channel, Data } from "effect"
  *
@@ -1504,8 +1577,8 @@ export const tap = /*#__PURE__*/dual(args => isChannel(args[0]), (self, f, optio
  * // Outputs: "item-1-0", "item-2-0", "item-2-1", "item-3-0", "item-3-1", "item-3-2"
  * ```
  *
- * @since 2.0.0
  * @category sequencing
+ * @since 2.0.0
  */
 export const flatMap = /*#__PURE__*/dual(args => isChannel(args[0]), (self, f, options) => concurrencyIsSequential(options?.concurrency) ? flatMapSequential(self, f) : flatMapConcurrent(self, f, options));
 const flatMapSequential = (self, f) => fromTransform((upstream, scope) => Effect.map(toTransform(self)(upstream, scope), pull => {
@@ -1535,7 +1608,8 @@ const flatMapConcurrent = (self, f, options) => self.pipe(map(f), mergeAll(optio
  * Concatenates this channel with another channel created from the terminal value
  * of this channel. The new channel is created using the provided function.
  *
- * @example
+ * **Example** (Concatenating with completion values)
+ *
  * ```ts
  * import { Channel, Data } from "effect"
  *
@@ -1552,8 +1626,8 @@ const flatMapConcurrent = (self, f, options) => self.pipe(map(f), mergeAll(optio
  * // Outputs: 1, 2, 3, then "Completed processing"
  * ```
  *
- * @since 2.0.0
  * @category sequencing
+ * @since 4.0.0
  */
 export const concatWith = /*#__PURE__*/dual(2, (self, f) => fromTransform((upstream, scope) => Effect.sync(() => {
   let currentPull;
@@ -1573,7 +1647,8 @@ export const concatWith = /*#__PURE__*/dual(2, (self, f) => fromTransform((upstr
  * Concatenates this channel with another channel, so that the second channel
  * starts emitting values after the first channel has completed.
  *
- * @example
+ * **Example** (Concatenating channels)
+ *
  * ```ts
  * import { Channel, Data } from "effect"
  *
@@ -1591,8 +1666,8 @@ export const concatWith = /*#__PURE__*/dual(2, (self, f) => fromTransform((upstr
  * // Outputs: 1, 2, 3, "a", "b", "c"
  * ```
  *
- * @since 2.0.0
  * @category sequencing
+ * @since 4.0.0
  */
 export const concat = /*#__PURE__*/dual(2, (self, that) => concatWith(self, _ => that));
 /**
@@ -1602,8 +1677,8 @@ export const concat = /*#__PURE__*/dual(2, (self, that) => concatWith(self, _ =>
  * some internal state to control the combining process, with the initial
  * state being specified by `s`.
  *
- * @since 4.0.0
  * @category sequencing
+ * @since 4.0.0
  */
 export const combine = /*#__PURE__*/dual(4, (self, that, s, f) => fromTransform(Effect.fnUntraced(function* (upstream, scope) {
   const leftPull = yield* toTransform(self)(upstream, scope);
@@ -1618,8 +1693,15 @@ export const combine = /*#__PURE__*/dual(4, (self, that, s, f) => fromTransform(
   });
 })));
 /**
- * @since 2.0.0
+ * Runs a fallback channel if this channel completes without emitting any
+ * output elements.
+ *
+ * If the source emits at least one element, the source is used unchanged. If
+ * the source completes before emitting an element, the fallback function
+ * receives the source done value and returns the replacement channel.
+ *
  * @category sequencing
+ * @since 4.0.0
  */
 export const orElseIfEmpty = /*#__PURE__*/dual(2, (self, f) => fromTransform((upstream, scope) => Effect.sync(() => {
   let currentPull;
@@ -1640,7 +1722,8 @@ export const orElseIfEmpty = /*#__PURE__*/dual(2, (self, f) => fromTransform((up
 /**
  * Flatten a channel of channels.
  *
- * @example
+ * **Example** (Flattening nested channels)
+ *
  * ```ts
  * import { Channel, Data } from "effect"
  *
@@ -1661,14 +1744,15 @@ export const orElseIfEmpty = /*#__PURE__*/dual(2, (self, f) => fromTransform((up
  * // Outputs: 1, 2, 3, 4, 5, 6
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const flatten = channels => flatMap(channels, identity_);
 /**
  * Flattens a channel that outputs arrays into a channel that outputs individual elements.
  *
- * @example
+ * **Example** (Flattening arrays of channel output)
+ *
  * ```ts
  * import { Channel, Data } from "effect"
  *
@@ -1689,8 +1773,8 @@ export const flatten = channels => flatMap(channels, identity_);
  * // Outputs: 1, 2, 3, 4, 5, 6, 7, 8, 9
  * ```
  *
- * @since 4.0.0
  * @category utils
+ * @since 4.0.0
  */
 export const flattenArray = self => transformPull(self, pull => {
   let array;
@@ -1721,15 +1805,22 @@ export const flattenArray = self => transformPull(self, pull => {
   return Effect.succeed(pump);
 });
 /**
- * @since 4.0.0
+ * Flattens a channel that emits `Take` values into a channel that emits the
+ * `Take` outputs directly.
+ *
+ * Output `Take` values are emitted as non-empty arrays. Failed `Take` values
+ * fail the returned channel. Done `Take` values complete the returned channel.
+ *
  * @category utils
+ * @since 4.0.0
  */
 export const flattenTake = self => mapEffectSequential(self, Take.toPull);
 /**
  * Creates a new channel that consumes all output from the source channel
  * but emits nothing, preserving only the completion value.
  *
- * @example
+ * **Example** (Draining channel output)
+ *
  * ```ts
  * import { Channel } from "effect"
  *
@@ -1743,8 +1834,8 @@ export const flattenTake = self => mapEffectSequential(self, Take.toPull);
  * // Useful for consuming side effects without collecting output
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const drain = self => transformPull(self, pull => Effect.succeed(Effect.forever(pull, {
   disableYield: true
@@ -1752,8 +1843,8 @@ export const drain = self => transformPull(self, pull => Effect.succeed(Effect.f
 /**
  * Repeats this channel according to the provided schedule.
  *
- * @since 4.0.0
  * @category utils
+ * @since 4.0.0
  */
 export const repeat = /*#__PURE__*/dual(2, (self, schedule) => Schedule.toStepWithMetadata(typeof schedule === "function" ? schedule(identity_) : schedule).pipe(Effect.map(step => {
   let meta = Schedule.CurrentMetadata.defaultValue();
@@ -1766,13 +1857,21 @@ export const repeat = /*#__PURE__*/dual(2, (self, schedule) => Schedule.toStepWi
 /**
  * Repeats this channel forever.
  *
- * @since 4.0.0
  * @category utils
+ * @since 4.0.0
  */
 export const forever = self => concatWith(self, () => forever(self));
 /**
- * @since 4.0.0
+ * Runs a schedule step for each output element while preserving the emitted
+ * elements.
+ *
+ * The schedule receives each output element as input. Schedule delays are
+ * applied between emitted elements. If the schedule fails, the returned channel
+ * fails. If the schedule finishes, the returned channel completes with the
+ * schedule output.
+ *
  * @category utils
+ * @since 4.0.0
  */
 export const schedule = /*#__PURE__*/dual(2, (self, schedule) => transformPull(self, (pull, _scope) => Effect.map(Schedule.toStepWithSleep(schedule), step => {
   const pullWithStep = Effect.tap(pull, step);
@@ -1782,7 +1881,8 @@ export const schedule = /*#__PURE__*/dual(2, (self, schedule) => transformPull(s
  * Filters the output elements of a channel using a predicate function.
  * Elements that don't match the predicate are discarded.
  *
- * @example
+ * **Example** (Filtering channel output)
+ *
  * ```ts
  * import { Channel } from "effect"
  *
@@ -1802,30 +1902,48 @@ export const schedule = /*#__PURE__*/dual(2, (self, schedule) => transformPull(s
  * // Outputs: 1, 2, 3 (all typed as numbers)
  * ```
  *
- * @since 2.0.0
- * @category Filtering
+ * @category filtering
+ * @since 4.0.0
  */
 export const filter = /*#__PURE__*/dual(2, (self, predicate) => fromTransform((upstream, scope) => Effect.map(toTransform(self)(upstream, scope), pull => Effect.flatMap(pull, function loop(elem) {
   return predicate(elem) ? Effect.succeed(elem) : Effect.flatMap(pull, loop);
 }))));
 /**
+ * Filters and maps output elements using a `Filter`.
+ *
+ * Successful filter results are emitted as mapped values. Failed filter
+ * results are discarded. The source channel's errors and done value are
+ * preserved.
+ *
+ * @category filtering
  * @since 4.0.0
- * @category Filtering
  */
 export const filterMap = /*#__PURE__*/dual(2, (self, filter) => fromTransform((upstream, scope) => Effect.map(toTransform(self)(upstream, scope), pull => Effect.flatMap(pull, function loop(elem) {
   const result = filter(elem);
   return Result.isFailure(result) ? Effect.flatMap(pull, loop) : Effect.succeed(result.success);
 }))));
 /**
+ * Filters output elements with an effectful predicate.
+ *
+ * Elements for which the predicate succeeds with `true` are emitted. Elements
+ * for which the predicate succeeds with `false` are discarded. Predicate
+ * failures fail the returned channel.
+ *
+ * @category filtering
  * @since 4.0.0
- * @category Filtering
  */
 export const filterEffect = /*#__PURE__*/dual(2, (self, predicate) => fromTransform((upstream, scope) => Effect.map(toTransform(self)(upstream, scope), pull => Effect.flatMap(pull, function loop(elem) {
   return Effect.flatMap(predicate(elem), passes => passes ? Effect.succeed(elem) : Effect.flatMap(pull, loop));
 }))));
 /**
+ * Filters and maps output elements using an effectful `Filter`.
+ *
+ * Successful filter results are emitted as mapped values. Failed filter
+ * results are discarded. Failures from the effectful filter fail the returned
+ * channel.
+ *
+ * @category filtering
  * @since 4.0.0
- * @category Filtering
  */
 export const filterMapEffect = /*#__PURE__*/dual(2, (self, filter) => fromTransform((upstream, scope) => Effect.map(toTransform(self)(upstream, scope), pull => Effect.flatMap(pull, function loop(elem) {
   return Effect.flatMap(filter(elem), result => Result.isFailure(result) ? Effect.flatMap(pull, loop) : Effect.succeed(result.success));
@@ -1834,7 +1952,8 @@ export const filterMapEffect = /*#__PURE__*/dual(2, (self, filter) => fromTransf
  * Filters arrays of elements emitted by a channel, applying the filter
  * to each element within the arrays and only emitting non-empty filtered arrays.
  *
- * @example
+ * **Example** (Filtering array output)
+ *
  * ```ts
  * import { Array, Channel } from "effect"
  *
@@ -1862,8 +1981,8 @@ export const filterMapEffect = /*#__PURE__*/dual(2, (self, filter) => fromTransf
  * // Outputs: [2, 4] (the arrays [1,3,5] and [7,9] are discarded)
  * ```
  *
+ * @category filtering
  * @since 4.0.0
- * @category Filtering
  */
 export const filterArray = /*#__PURE__*/dual(2, (self, predicate) => transformPull(self, pull => Effect.succeed(Effect.flatMap(pull, function loop(arr) {
   const passes = [];
@@ -1875,8 +1994,14 @@ export const filterArray = /*#__PURE__*/dual(2, (self, predicate) => transformPu
   return Arr.isReadonlyArrayNonEmpty(passes) ? Effect.succeed(passes) : Effect.flatMap(pull, loop);
 }))));
 /**
+ * Filters and maps each element inside emitted non-empty arrays using a
+ * `Filter`.
+ *
+ * Successful filter results are kept as mapped values. Failed filter results
+ * are removed from the array. Arrays that become empty are discarded.
+ *
+ * @category filtering
  * @since 4.0.0
- * @category Filtering
  */
 export const filterMapArray = /*#__PURE__*/dual(2, (self, filter) => transformPull(self, pull => Effect.succeed(Effect.flatMap(pull, function loop(arr) {
   const passes = [];
@@ -1889,8 +2014,15 @@ export const filterMapArray = /*#__PURE__*/dual(2, (self, filter) => transformPu
   return Arr.isReadonlyArrayNonEmpty(passes) ? Effect.succeed(passes) : Effect.flatMap(pull, loop);
 }))));
 /**
+ * Filters each element inside emitted non-empty arrays with an effectful
+ * predicate.
+ *
+ * The predicate receives the element and its index within the array. Elements
+ * for which the predicate succeeds with `true` are kept. Arrays that become
+ * empty are discarded. Predicate failures fail the returned channel.
+ *
+ * @category filtering
  * @since 4.0.0
- * @category Filtering
  */
 export const filterArrayEffect = /*#__PURE__*/dual(2, (self, predicate) => transformPull(self, pull => {
   const f = Effect.flatMap(pull, arr => Effect.filter(arr, predicate));
@@ -1899,8 +2031,15 @@ export const filterArrayEffect = /*#__PURE__*/dual(2, (self, predicate) => trans
   }));
 }));
 /**
+ * Filters and maps each element inside emitted non-empty arrays using an
+ * effectful `Filter`.
+ *
+ * Successful filter results are kept as mapped values. Failed filter results
+ * are removed from the array. Arrays that become empty are discarded. Failures
+ * from the effectful filter fail the returned channel.
+ *
+ * @category filtering
  * @since 4.0.0
- * @category Filtering
  */
 export const filterMapArrayEffect = /*#__PURE__*/dual(2, (self, filter) => transformPull(self, pull => Effect.succeed(Effect.flatMap(pull, function loop(arr) {
   return Effect.flatMap(Effect.filterMapEffect(arr, filter), passes => Arr.isReadonlyArrayNonEmpty(passes) ? Effect.succeed(passes) : Effect.flatMap(pull, loop));
@@ -1908,7 +2047,8 @@ export const filterMapArrayEffect = /*#__PURE__*/dual(2, (self, filter) => trans
 /**
  * Statefully maps over a channel with an accumulator, where each element can produce multiple output values.
  *
- * @example
+ * **Example** (Mapping with accumulated state)
+ *
  * ```ts
  * import { Channel, Effect } from "effect"
  *
@@ -1939,8 +2079,8 @@ export const filterMapArrayEffect = /*#__PURE__*/dual(2, (self, filter) => trans
  * )
  * ```
  *
- * @since 2.0.0
- * @category Sequencing
+ * @category sequencing
+ * @since 4.0.0
  */
 export const mapAccum = /*#__PURE__*/dual(args => isChannel(args[0]), (self, initial, f, options) => fromTransform((upstream, scope) => Effect.map(toTransform(self)(upstream, scope), pull => {
   let state = initial();
@@ -1985,7 +2125,8 @@ export const mapAccum = /*#__PURE__*/dual(args => isChannel(args[0]), (self, ini
  * Statefully transforms a channel by scanning over its output with an accumulator function.
  * Emits the intermediate results of the scan operation.
  *
- * @example
+ * **Example** (Scanning channel output)
+ *
  * ```ts
  * import { Channel } from "effect"
  *
@@ -2007,15 +2148,16 @@ export const mapAccum = /*#__PURE__*/dual(args => isChannel(args[0]), (self, ini
  * // Outputs: "", "hello", "hello world", "hello world from", "hello world from effect"
  * ```
  *
- * @since 2.0.0
- * @category Sequencing
+ * @category sequencing
+ * @since 4.0.0
  */
 export const scan = /*#__PURE__*/dual(3, (self, initial, f) => scanEffect(self, initial, (s, a) => Effect.succeed(f(s, a))));
 /**
  * Statefully transforms a channel by scanning over its output with an effectful accumulator function.
  * Emits the intermediate results of the scan operation.
  *
- * @example
+ * **Example** (Scanning channel output with effects)
+ *
  * ```ts
  * import { Channel, Data, Effect } from "effect"
  *
@@ -2052,8 +2194,8 @@ export const scan = /*#__PURE__*/dual(3, (self, initial, f) => scanEffect(self,
  * )
  * ```
  *
- * @since 2.0.0
- * @category Sequencing
+ * @category sequencing
+ * @since 4.0.0
  */
 export const scanEffect = /*#__PURE__*/dual(3, (self, initial, f) => fromTransform((upstream, scope) => Effect.map(toTransform(self)(upstream, scope), pull => {
   let state = initial;
@@ -2073,7 +2215,8 @@ export const scanEffect = /*#__PURE__*/dual(3, (self, initial, f) => fromTransfo
  * Catches any cause of failure from the channel and allows recovery by
  * creating a new channel based on the caught cause.
  *
- * @example
+ * **Example** (Recovering from failure causes)
+ *
  * ```ts
  * import { Cause, Channel, Data } from "effect"
  *
@@ -2101,8 +2244,8 @@ export const scanEffect = /*#__PURE__*/dual(3, (self, initial, f) => fromTransfo
  * // The channel recovers gracefully from errors
  * ```
  *
- * @since 4.0.0
- * @category Error handling
+ * @category error handling
+ * @since 2.0.0
  */
 export const catchCause = /*#__PURE__*/dual(2, (self, f) => fromTransform((upstream, scope) => {
   let forkedScope = Scope.forkUnsafe(scope);
@@ -2122,23 +2265,35 @@ export const catchCause = /*#__PURE__*/dual(2, (self, f) => fromTransform((upstr
   });
 }));
 /**
+ * Runs an effect with the full failure `Cause` when the channel fails, then
+ * fails the returned channel with the original cause.
+ *
+ * Use this for observing failures, such as logging or metrics. If the observer
+ * effect fails, that failure can fail the returned channel.
+ *
+ * @category error handling
  * @since 4.0.0
- * @category Error handling
  */
 export const tapCause = /*#__PURE__*/dual(2, (self, f) => catchCause(self, cause => fromEffectDrain(Effect.flatMap(f(cause), _ => Effect.failCause(cause)))));
 /**
  * Catches causes of failure that match a specific filter, allowing
  * conditional error recovery based on the type of failure.
  *
+ * @category error handling
  * @since 4.0.0
- * @category Error handling
  */
 export const catchCauseIf = /*#__PURE__*/dual(3, (self, predicate, f) => catchCause(self, cause => {
   return predicate(cause) ? f(cause) : failCause(cause);
 }));
 /**
+ * Recovers from channel failures whose full `Cause` is selected by a `Filter`.
+ *
+ * When the filter succeeds, the recovery function receives the selected value
+ * and the original cause. When the filter fails, the returned channel fails
+ * with the residual cause produced by the filter.
+ *
+ * @category error handling
  * @since 4.0.0
- * @category Error handling
  */
 export const catchCauseFilter = /*#__PURE__*/dual(3, (self, filter, f) => catchCause(self, cause => {
   const result = filter(cause);
@@ -2147,33 +2302,57 @@ export const catchCauseFilter = /*#__PURE__*/dual(3, (self, filter, f) => catchC
 const catch_ = /*#__PURE__*/dual(2, (self, f) => catchCauseFilter(self, Cause.findError, e => f(e)));
 export {
 /**
+ * @category error handling
  * @since 4.0.0
- * @category Error handling
  */
 catch_ as catch };
 /**
+ * Runs an effect when the channel fails with a typed error, then preserves the
+ * original channel failure.
+ *
+ * The effect is not run for normal channel completion. If the observer effect
+ * fails, that failure can fail the returned channel.
+ *
+ * @category error handling
  * @since 4.0.0
- * @category Error handling
  */
 export const tapError = /*#__PURE__*/dual(2, (self, f) => transformPull(self, pull => Effect.succeed(Effect.tapError(pull, err => Cause.isDone(err) ? Effect.void : Effect.asVoid(f(err))))));
 /**
+ * Recovers from typed channel errors that match a predicate or refinement.
+ *
+ * Matching errors are handled by the recovery function. Non-matching errors
+ * are handled by `orElse` when provided. Without `orElse`, non-matching errors
+ * are re-failed.
+ *
+ * @category error handling
  * @since 4.0.0
- * @category Error handling
  */
 export const catchIf = /*#__PURE__*/dual(args => isChannel(args[0]), (self, predicate, f, orElse) => catch_(self, err => {
   return predicate(err) ? f(err) : orElse ? orElse(err) : fail(err);
 }));
 /**
+ * Recovers from typed channel errors selected by a `Filter`.
+ *
+ * Successful filter results are handled by the recovery function. Failed
+ * filter results are handled by `orElse` when provided. Without `orElse`,
+ * failed filter results are re-failed.
+ *
+ * @category error handling
  * @since 4.0.0
- * @category Error handling
  */
 export const catchFilter = /*#__PURE__*/dual(args => isChannel(args[0]), (self, filter, f, orElse) => catch_(self, err => {
   const result = filter(err);
   return Result.isFailure(result) ? orElse ? orElse(result.failure) : fail(result.failure) : f(result.success);
 }));
 /**
+ * Recovers from tagged channel errors whose `_tag` matches one or more tags.
+ *
+ * Matching tagged errors are handled by the recovery function. Non-matching
+ * errors are handled by `orElse` when provided. Without `orElse`,
+ * non-matching errors are re-failed.
+ *
+ * @category error handling
  * @since 4.0.0
- * @category Error handling
  */
 export const catchTag = /*#__PURE__*/dual(args => isChannel(args[0]), (self, k, f, orElse) => {
   const pred = Array.isArray(k) ? e => hasProperty(e, "_tag") && k.includes(e._tag) : isTagged(k);
@@ -2182,7 +2361,8 @@ export const catchTag = /*#__PURE__*/dual(args => isChannel(args[0]), (self, k,
 /**
  * Catches a specific reason within a tagged error.
  *
- * @example
+ * **Example** (Recovering from nested reasons)
+ *
  * ```ts
  * import { Channel, Data } from "effect"
  *
@@ -2209,8 +2389,8 @@ export const catchTag = /*#__PURE__*/dual(args => isChannel(args[0]), (self, k,
  * )
  * ```
  *
+ * @category error handling
  * @since 4.0.0
- * @category Error handling
  */
 export const catchReason = /*#__PURE__*/dual(args => isChannel(args[0]), (self, errorTag, reasonTag, f, orElse) => catch_(self, error => {
   if (isTagged(error, errorTag) && hasProperty(error, "reason")) {
@@ -2225,8 +2405,8 @@ export const catchReason = /*#__PURE__*/dual(args => isChannel(args[0]), (self,
 /**
  * Catches multiple reasons within a tagged error using an object of handlers.
  *
+ * @category error handling
  * @since 4.0.0
- * @category Error handling
  */
 export const catchReasons = /*#__PURE__*/dual(args => isChannel(args[0]), (self, errorTag, cases, orElse) => {
   let keys;
@@ -2245,7 +2425,8 @@ export const catchReasons = /*#__PURE__*/dual(args => isChannel(args[0]), (self,
 /**
  * Promotes nested reason errors into the channel error, replacing the parent error.
  *
- * @example
+ * **Example** (Promoting nested reasons)
+ *
  * ```ts
  * import { Channel, Data } from "effect"
  *
@@ -2268,8 +2449,8 @@ export const catchReasons = /*#__PURE__*/dual(args => isChannel(args[0]), (self,
  * const unwrapped = channel.pipe(Channel.unwrapReason("AiError"))
  * ```
  *
+ * @category error handling
  * @since 4.0.0
- * @category Error handling
  */
 export const unwrapReason = /*#__PURE__*/dual(2, (self, errorTag) => catchFilter(self, error => isTagged(error, errorTag) && hasProperty(error, "reason") ? Result.succeed(error.reason) : Result.fail(error), fail));
 /**
@@ -2277,15 +2458,16 @@ export const unwrapReason = /*#__PURE__*/dual(2, (self, errorTag) => catchFilter
  * value of the returned channel is created by applying the specified function
  * to the failure value of this channel.
  *
+ * @category error handling
  * @since 2.0.0
- * @category Error handling
  */
 export const mapError = /*#__PURE__*/dual(2, (self, f) => catch_(self, err => fail(f(err))));
 /**
  * Converts all errors in the channel to defects (unrecoverable failures).
  * This is useful when you want to treat errors as programming errors.
  *
- * @example
+ * **Example** (Converting failures to defects)
+ *
  * ```ts
  * import { Channel, Data } from "effect"
  *
@@ -2302,8 +2484,8 @@ export const mapError = /*#__PURE__*/dual(2, (self, f) => catch_(self, err => fa
  * // Any failure will now become a defect (uncaught exception)
  * ```
  *
- * @since 4.0.0
- * @category Error handling
+ * @category error handling
+ * @since 2.0.0
  */
 export const orDie = self => catch_(self, die);
 /**
@@ -2311,8 +2493,8 @@ export const orDie = self => catch_(self, die);
  *
  * Use the `log` option to emit the full {@link Cause} when the channel fails.
  *
+ * @category error handling
  * @since 4.0.0
- * @category Error handling
  */
 export const ignore = /*#__PURE__*/dual(args => isChannel(args[0]), (self, options) => {
   if (!options?.log) {
@@ -2327,8 +2509,8 @@ const ignoreCause_ = self => catchCause(self, () => empty);
  *
  * Use the `log` option to emit the full {@link Cause} when the channel fails.
  *
+ * @category error handling
  * @since 4.0.0
- * @category Error handling
  */
 export const ignoreCause = /*#__PURE__*/dual(args => isChannel(args[0]), (self, options) => {
   if (!options?.log) return ignoreCause_(self);
@@ -2339,8 +2521,8 @@ export const ignoreCause = /*#__PURE__*/dual(args => isChannel(args[0]), (self,
  * Returns a new channel that retries this channel according to the specified
  * schedule whenever it fails.
  *
- * @since 4.0.0
  * @category utils
+ * @since 4.0.0
  */
 export const retry = /*#__PURE__*/dual(2, (self, schedule) => suspend(() => {
   let step = undefined;
@@ -2361,13 +2543,15 @@ export const retry = /*#__PURE__*/dual(2, (self, schedule) => suspend(() => {
   return loop;
 }));
 /**
- * Returns a new channel, which sequentially combines this channel, together
- * with the provided factory function, which creates a second channel based on
- * the output values of this channel. The result is a channel that will first
- * perform the functions of this channel, before performing the functions of
- * the created channel (including yielding its terminal value).
+ * Maps each output element to a channel and emits values from the most recent
+ * active child channels.
+ *
+ * With the default concurrency of `1`, starting a new child channel interrupts
+ * the previous child channel. Use `options.concurrency` to allow more active
+ * child channels. The source channel's done value is preserved.
+ *
+ * **Example** (Switching mapped channels)
  *
- * @example
  * ```ts
  * import { Channel, Data } from "effect"
  *
@@ -2387,8 +2571,8 @@ export const retry = /*#__PURE__*/dual(2, (self, schedule) => suspend(() => {
  * // Outputs: "value-1", "value-2", "value-3"
  * ```
  *
- * @since 2.0.0
  * @category sequencing
+ * @since 4.0.0
  */
 export const switchMap = /*#__PURE__*/dual(args => isChannel(args[0]), (self, f, options) => self.pipe(map(f), mergeAll({
   ...options,
@@ -2398,7 +2582,8 @@ export const switchMap = /*#__PURE__*/dual(args => isChannel(args[0]), (self, f,
 /**
  * Merges multiple channels with specified concurrency and buffering options.
  *
- * @example
+ * **Example** (Merging nested channels)
+ *
  * ```ts
  * import { Channel, Data } from "effect"
  *
@@ -2422,8 +2607,8 @@ export const switchMap = /*#__PURE__*/dual(args => isChannel(args[0]), (self, f,
  * // Outputs: 1, 2, 3, 4, 5, 6 (order may vary due to concurrency)
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export const mergeAll = /*#__PURE__*/dual(2, (channels, {
   bufferSize = 16,
@@ -2471,7 +2656,8 @@ export const mergeAll = /*#__PURE__*/dual(2, (channels, {
  * Returns a new channel, which is the merge of this channel and the specified
  * channel.
  *
- * @example
+ * **Example** (Merging channels)
+ *
  * ```ts
  * import { Channel, Data } from "effect"
  *
@@ -2492,8 +2678,8 @@ export const mergeAll = /*#__PURE__*/dual(2, (channels, {
  * // Order may vary: 1, "a", 2, "b", 3, "c"
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 4.0.0
  */
 export const merge = /*#__PURE__*/dual(args => isChannel(args[0]) && isChannel(args[1]), (left, right, options) => fromTransformBracket(Effect.fnUntraced(function* (upstream, _scope, forkedScope) {
   const strategy = options?.haltStrategy ?? "both";
@@ -2527,8 +2713,14 @@ export const merge = /*#__PURE__*/dual(args => isChannel(args[0]) && isChannel(a
   return Queue.take(queue);
 })));
 /**
- * @since 4.0.0
+ * Runs an effect concurrently with a channel while emitting only the channel's
+ * output elements.
+ *
+ * The effect's successful value is ignored. If the effect fails while the
+ * channel is running, the returned channel fails with that error.
+ *
  * @category utils
+ * @since 4.0.0
  */
 export const mergeEffect = /*#__PURE__*/dual(2, (self, effect) => merge(self, fromEffectDrain(effect), {
   haltStrategy: "left"
@@ -2543,7 +2735,7 @@ export const mergeEffect = /*#__PURE__*/dual(2, (self, effect) => merge(self, fr
  * if the stream ends without a terminator the final partial line is still
  * emitted.
  *
- * **Example**
+ * **Example** (Splitting string chunks into lines)
  *
  * ```ts
  * import { Effect, Stream } from "effect"
@@ -2557,8 +2749,8 @@ export const mergeEffect = /*#__PURE__*/dual(2, (self, effect) => merge(self, fr
  * }))
  * ```
  *
- * @since 2.0.0
  * @category String manipulation
+ * @since 2.0.0
  */
 export const splitLines = () => fromTransform((upstream, _scope) => Effect.sync(() => {
   // Accumulates text that has not yet been terminated by a line break.
@@ -2646,16 +2838,29 @@ export const splitLines = () => fromTransform((upstream, _scope) => Effect.sync(
   return pullOrFlush;
 }));
 /**
- * @since 4.0.0
+ * Decodes incoming `Uint8Array` chunks into strings using `TextDecoder`.
+ *
+ * Input chunks are decoded with streaming enabled so multi-byte characters may
+ * span `Uint8Array` boundaries. The optional `encoding` and `options` are
+ * passed to `TextDecoder`.
+ *
  * @category String manipulation
+ * @since 4.0.0
  */
 export const decodeText = (encoding, options) => fromTransform((upstream, _scope) => Effect.sync(() => {
   const decoder = new TextDecoder(encoding, options);
-  return Effect.map(upstream, Arr.map(line => decoder.decode(line)));
+  const streamOptions = {
+    stream: true
+  };
+  return Effect.map(upstream, Arr.map(line => decoder.decode(line, streamOptions)));
 }));
 /**
- * @since 4.0.0
+ * Encodes incoming string chunks into `Uint8Array` values using `TextEncoder`.
+ *
+ * Each string inside an emitted array is encoded independently.
+ *
  * @category String manipulation
+ * @since 4.0.0
  */
 export const encodeText = () => fromTransform((upstream, _scope) => Effect.sync(() => {
   const encoder = new TextEncoder();
@@ -2667,7 +2872,8 @@ export const encodeText = () => fromTransform((upstream, _scope) => Effect.sync(
  * and the output type of the specified channel, terminating with the value of
  * the specified channel.
  *
- * @example
+ * **Example** (Piping one channel into another)
+ *
  * ```ts
  * import { Channel, Data } from "effect"
  *
@@ -2685,8 +2891,8 @@ export const encodeText = () => fromTransform((upstream, _scope) => Effect.sync(
  * // Outputs: 2, 4, 6
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export const pipeTo = /*#__PURE__*/dual(2, (self, that) => fromTransform((upstream, scope) => Effect.flatMap(toTransform(self)(upstream, scope), upstream => toTransform(that)(upstream, scope))));
 /**
@@ -2694,7 +2900,8 @@ export const pipeTo = /*#__PURE__*/dual(2, (self, that) => fromTransform((upstre
  * specified channel and preserves this channel's failures without providing
  * them to the other channel for observation.
  *
- * @example
+ * **Example** (Piping while preserving failures)
+ *
  * ```ts
  * import { Channel, Data } from "effect"
  *
@@ -2712,8 +2919,8 @@ export const pipeTo = /*#__PURE__*/dual(2, (self, that) => fromTransform((upstre
  * // Source errors are preserved and not sent to transform channel
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export const pipeToOrFail = /*#__PURE__*/dual(2, (self, that) => fromTransform((upstream, scope) => Effect.flatMap(toTransform(self)(upstream, scope), upstream => {
   const upstreamPull = Effect.catchCause(upstream, cause => Pull.isDoneCause(cause) ? Effect.failCause(cause) : Effect.die(Cause.Done(cause)));
@@ -2723,7 +2930,8 @@ export const pipeToOrFail = /*#__PURE__*/dual(2, (self, that) => fromTransform((
  * Constructs a `Channel` from a scoped effect that will result in a
  * `Channel` if successful.
  *
- * @example
+ * **Example** (Unwrapping channel effects)
+ *
  * ```ts
  * import { Channel, Data, Effect } from "effect"
  *
@@ -2742,8 +2950,8 @@ export const pipeToOrFail = /*#__PURE__*/dual(2, (self, that) => fromTransform((
  * // The resulting channel outputs: 1, 2, 3
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const unwrap = channel => fromTransform((upstream, scope) => {
   let pull;
@@ -2753,41 +2961,52 @@ export const unwrap = channel => fromTransform((upstream, scope) => {
   }));
 });
 /**
- * @since 2.0.0
+ * Runs a channel with a scope provided for the duration of the channel
+ * execution, removing the channel's `Scope` requirement.
+ *
  * @category utils
+ * @since 2.0.0
  */
 export const scoped = self => fromTransformBracket((upstream, scope, forkedScope) => Scope.provide(toTransform(self)(upstream, scope), forkedScope));
 /**
- * Returns a new channel which embeds the given input handler into a Channel.
+ * Runs an input handler against the upstream pull while the wrapped channel
+ * runs without receiving upstream input directly.
  *
- * @example
- * ```ts
- * import { Channel, Data, Effect } from "effect"
+ * The input handler is forked in the channel scope. The wrapped channel is run
+ * with an already-completed input.
  *
- * class EmbedError extends Data.TaggedError("EmbedError")<{
- *   readonly stage: string
- * }> {}
+ * **Example** (Embedding custom input handling)
+ *
+ * ```ts
+ * import { Channel, Effect } from "effect"
  *
  * // Create a base channel
  * const baseChannel = Channel.fromIterable([1, 2, 3])
  *
- * // Embed input handling - simplified example
+ * // Drain the embedded input while the base channel runs
  * const embeddedChannel = Channel.embedInput(
  *   baseChannel,
- *   (_upstream) => Effect.void
+ *   (upstream) =>
+ *     upstream.pipe(
+ *       Effect.tap((message) =>
+ *         Effect.sync(() => console.log(message))
+ *       ),
+ *       Effect.forever,
+ *       Effect.ignore
+ *     )
  * )
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export const embedInput = /*#__PURE__*/dual(2, (self, input) => fromTransformBracket((upstream, scope, forkedScope) => Effect.andThen(Effect.forkIn(input(upstream), forkedScope), toTransform(self)(Cause.done(), scope))));
 /**
  * Allows a faster producer to progress independently of a slower consumer by
  * buffering up to `capacity` elements in a queue.
  *
- * @since 2.0.0
  * @category Buffering
+ * @since 2.0.0
  */
 export const buffer = /*#__PURE__*/dual(2, (self, options) => fromTransform(Effect.fnUntraced(function* (upstream, scope) {
   const pull = yield* toTransform(self)(upstream, scope);
@@ -2805,8 +3024,8 @@ export const buffer = /*#__PURE__*/dual(2, (self, options) => fromTransform(Effe
  * Allows a faster producer to progress independently of a slower consumer by
  * buffering up to `capacity` elements in a queue.
  *
- * @since 2.0.0
  * @category Buffering
+ * @since 4.0.0
  */
 export const bufferArray = /*#__PURE__*/dual(2, (self, options) => fromTransform(Effect.fnUntraced(function* (upstream, scope) {
   const pull = yield* toTransform(self)(upstream, scope);
@@ -2829,15 +3048,22 @@ export const bufferArray = /*#__PURE__*/dual(2, (self, options) => fromTransform
  * returned channel will yield the success value of the underlying channel as
  * its terminal value.
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export const interruptWhen = /*#__PURE__*/dual(2, (self, effect) => merge(self, fromPull(Effect.succeed(Effect.flatMap(effect, Cause.done))), {
   haltStrategy: "either"
 }));
 /**
- * @since 4.0.0
+ * Halts a channel when the specified effect completes or fails.
+ *
+ * If the effect completes before the channel is done, its success value becomes
+ * the returned channel's done value. If the effect fails, the returned channel
+ * fails with that error. If the channel completes first, the channel's done
+ * value is preserved.
+ *
  * @category utils
+ * @since 4.0.0
  */
 export const haltWhen = /*#__PURE__*/dual(2, (self, effect) => fromTransformBracket(Effect.fnUntraced(function* (upstream, scope, forkedScope) {
   const pull = yield* toTransform(self)(upstream, scope);
@@ -2849,8 +3075,13 @@ export const haltWhen = /*#__PURE__*/dual(2, (self, effect) => fromTransformBrac
   return Effect.suspend(() => haltCause ? Effect.failCause(haltCause) : pull);
 })));
 /**
- * @since 4.0.0
+ * Attaches a finalizer that runs only when the channel exits with failure.
+ *
+ * The finalizer receives the failure `Cause`. The original channel failure is
+ * preserved. The finalizer itself must not fail.
+ *
  * @category utils
+ * @since 4.0.0
  */
 export const onError = /*#__PURE__*/dual(2, (self, finalizer) => onExit(self, exit => Exit.isFailure(exit) ? finalizer(exit.cause) : Effect.void));
 /**
@@ -2858,7 +3089,8 @@ export const onError = /*#__PURE__*/dual(2, (self, finalizer) => onExit(self, ex
  * guaranteed to be executed so long as the channel begins execution (and
  * regardless of whether or not it completes).
  *
- * @example
+ * **Example** (Running exit finalizers)
+ *
  * ```ts
  * import { Channel, Console, Data, Exit } from "effect"
  *
@@ -2879,18 +3111,29 @@ export const onError = /*#__PURE__*/dual(2, (self, finalizer) => onExit(self, ex
  * })
  * ```
  *
- * @since 4.0.0
  * @category utils
+ * @since 4.0.0
  */
 export const onExit = /*#__PURE__*/dual(2, (self, finalizer) => fromTransformBracket((upstream, scope, forkedScope) => Scope.addFinalizerExit(forkedScope, finalizer).pipe(Effect.andThen(toTransform(self)(upstream, scope)))));
 /**
- * @since 4.0.0
+ * Runs an effect before the channel starts.
+ *
+ * The effect's successful value is ignored. If the effect fails, the returned
+ * channel fails before running the source channel.
+ *
  * @category utils
+ * @since 4.0.0
  */
 export const onStart = /*#__PURE__*/dual(2, (self, onStart) => unwrap(Effect.as(onStart, self)));
 /**
- * @since 4.0.0
+ * Runs an effect the first time the channel emits an output element.
+ *
+ * The effect receives the first emitted element. The first element is still
+ * emitted unchanged. The effect is not run if the channel completes without
+ * emitting an element.
+ *
  * @category utils
+ * @since 4.0.0
  */
 export const onFirst = /*#__PURE__*/dual(2, (self, onFirst) => transformPull(self, pull => Effect.sync(() => {
   let isFirst = true;
@@ -2901,8 +3144,14 @@ export const onFirst = /*#__PURE__*/dual(2, (self, onFirst) => transformPull(sel
   return Effect.suspend(() => isFirst ? pullFirst : pull);
 })));
 /**
- * @since 4.0.0
+ * Runs an effect when the channel completes successfully.
+ *
+ * The effect runs before the original done value is propagated. The effect is
+ * not run when the channel fails. If the effect fails, the returned channel
+ * fails with that error.
+ *
  * @category utils
+ * @since 4.0.0
  */
 export const onEnd = /*#__PURE__*/dual(2, (self, onEnd) => transformPull(self, pull => Effect.succeed(Pull.catchDone(pull, leftover => Effect.flatMap(onEnd, () => Cause.done(leftover))))));
 /**
@@ -2910,7 +3159,8 @@ export const onEnd = /*#__PURE__*/dual(2, (self, onEnd) => transformPull(self, p
  * guaranteed to be executed so long as the channel begins execution (and
  * regardless of whether or not it completes).
  *
- * @example
+ * **Example** (Ensuring cleanup runs)
+ *
  * ```ts
  * import { Channel, Console, Data } from "effect"
  *
@@ -2928,8 +3178,8 @@ export const onEnd = /*#__PURE__*/dual(2, (self, onEnd) => transformPull(self, p
  * )
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export const ensuring = /*#__PURE__*/dual(2, (self, finalizer) => onExit(self, _ => finalizer));
 const runWith = (self, f, onHalt) => Effect.suspend(() => {
@@ -2940,50 +3190,81 @@ const runWith = (self, f, onHalt) => Effect.suspend(() => {
 /**
  * Create a channel from the specified services.
  *
+ * @category services
  * @since 2.0.0
- * @category Services
  */
 export const contextWith = f => fromTransform((upstream, scope) => Effect.contextWith(context => toTransform(f(context))(upstream, scope)));
 /**
- * Provides a layer or context to the channel, removing the corresponding
- * service requirements. Use `options.local` to build the layer every time; by
- * default, layers are shared between provide calls.
+ * Provides a `Context` to the channel, removing the corresponding service
+ * requirements from the returned channel.
  *
- * @since 4.0.0
- * @category Services
+ * @category services
+ * @since 2.0.0
  */
 export const provideContext = /*#__PURE__*/dual(2, (self, context) => fromTransform((upstream, scope) => Effect.map(Effect.provideContext(toTransform(self)(upstream, scope), context), Effect.provideContext(context))));
 /**
- * @since 4.0.0
- * @category Services
+ * Provides a concrete service for a context key, removing that service
+ * requirement from the returned channel.
+ *
+ * @category services
+ * @since 2.0.0
  */
 export const provideService = /*#__PURE__*/dual(3, (self, key, service) => fromTransform((upstream, scope) => Effect.map(Effect.provideService(toTransform(self)(upstream, scope), key, service), Effect.provideService(key, service))));
 /**
+ * Evaluates an effect to obtain a service, then provides that service to the
+ * channel.
+ *
+ * If the service effect fails, the returned channel fails. The provided service
+ * removes the corresponding service requirement from the returned channel.
+ *
+ * @category services
  * @since 4.0.0
- * @category Services
  */
 export const provideServiceEffect = /*#__PURE__*/dual(3, (self, key, service) => fromTransform((upstream, scope) => Effect.flatMap(service, s => toTransform(provideService(self, key, s))(upstream, scope))));
 /**
+ * Provides a `Layer` or `Context` to the channel, removing the corresponding
+ * service requirements.
+ *
+ * Providing a `Context` delegates to `provideContext`. Providing a `Layer`
+ * builds the layer in the channel scope. Use `options.local` to build a fresh
+ * layer instance for this provision.
+ *
+ * @category services
  * @since 4.0.0
- * @category Services
  */
 export const provide = /*#__PURE__*/dual(args => isChannel(args[0]), (self, layer, options) => Context.isContext(layer) ? provideContext(self, layer) : fromTransform((upstream, scope) => Effect.flatMap(options?.local ? Layer.buildWithMemoMap(layer, Layer.makeMemoMapUnsafe(), scope) : Layer.buildWithScope(layer, scope), context => Effect.map(Effect.provideContext(toTransform(self)(upstream, scope), context), Effect.provideContext(context)))));
 /**
- * @since 2.0.0
- * @category Services
+ * Transforms the current context before running the channel.
+ *
+ * The function receives the surrounding context and returns the context to
+ * provide to the channel. The returned channel requires the services needed to
+ * build that context.
+ *
+ * @category services
+ * @since 4.0.0
  */
 export const updateContext = /*#__PURE__*/dual(2, (self, f) => fromTransform((upstream, scope) => Effect.contextWith(context => {
   const toProvide = f(context);
   return toTransform(provideContext(self, toProvide))(upstream, scope);
 })));
 /**
+ * Updates a service in the current context before running the channel.
+ *
+ * The existing service is read from the context. The updated service is
+ * provided to the channel under the same key.
+ *
+ * @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)))));
 /**
- * @since 4.0.0
- * @category Tracing
+ * Runs the channel inside a tracing span with the specified name and options.
+ *
+ * The created span is provided as the current parent span while the channel
+ * runs. The span is ended with the channel's exit value.
+ *
+ * @category tracing
+ * @since 2.0.0
  */
 export const withSpan = function () {
   const dataFirst = isChannel(arguments[0]);
@@ -3001,8 +3282,10 @@ const withSpanImpl = (self, name, options) => acquireUseRelease(Effect.makeSpan(
   return endSpan(span, exit, clock, timingEnabled);
 }));
 /**
- * @since 4.0.0
+ * The starting channel for Do notation, emitting an empty object.
+ *
  * @category Do notation
+ * @since 4.0.0
  */
 export const Do = /*#__PURE__*/succeed({});
 const let_ = /*#__PURE__*/dual(3, (self, name, f) => map(self, elem => ({
@@ -3011,21 +3294,30 @@ const let_ = /*#__PURE__*/dual(3, (self, name, f) => map(self, elem => ({
 })));
 export {
 /**
- * @since 4.0.0
  * @category Do notation
+ * @since 4.0.0
  */
 let_ as let };
 /**
- * @since 4.0.0
+ * Adds a field to each object emitted by a channel by running another channel
+ * derived from that object.
+ *
+ * The field name must not already exist on the emitted object. The derived
+ * channel's output becomes the value of the new field. `options.concurrency`
+ * and `options.bufferSize` control how derived channels are flattened.
+ *
  * @category Do notation
+ * @since 4.0.0
  */
 export const bind = /*#__PURE__*/dual(args => isChannel(args[0]), (self, name, f, options) => flatMap(self, elem => map(f(elem), b => ({
   ...elem,
   [name]: b
 })), options));
 /**
- * @since 4.0.0
+ * Wraps each output element in an object under the specified field name.
+ *
  * @category Do notation
+ * @since 4.0.0
  */
 export const bindTo = /*#__PURE__*/dual(2, (self, name) => map(self, elem => ({
   [name]: elem
@@ -3033,7 +3325,8 @@ export const bindTo = /*#__PURE__*/dual(2, (self, name) => map(self, elem => ({
 /**
  * Runs a channel and counts the number of elements it outputs.
  *
- * @example
+ * **Example** (Counting channel output)
+ *
  * ```ts
  * import { Channel, Data } from "effect"
  *
@@ -3050,14 +3343,15 @@ export const bindTo = /*#__PURE__*/dual(2, (self, name) => map(self, elem => ({
  * // Effect.runSync(countEffect) // Returns: 5
  * ```
  *
- * @since 2.0.0
  * @category execution
+ * @since 4.0.0
  */
 export const runCount = self => runFold(self, () => 0, acc => acc + 1);
 /**
  * Runs a channel and discards all output elements, returning only the final result.
  *
- * @example
+ * **Example** (Draining channel output at runtime)
+ *
  * ```ts
  * import { Channel, Data } from "effect"
  *
@@ -3078,8 +3372,8 @@ export const runCount = self => runFold(self, () => 0, acc => acc + 1);
  * // Effect.runSync(drainEffect) // Returns: "completed"
  * ```
  *
- * @since 2.0.0
  * @category execution
+ * @since 2.0.0
  */
 export const runDrain = self => runWith(self, pull => Effect.forever(pull, {
   disableYield: true
@@ -3087,7 +3381,8 @@ export const runDrain = self => runWith(self, pull => Effect.forever(pull, {
 /**
  * Runs a channel and applies an effect to each output element.
  *
- * @example
+ * **Example** (Running effects for each output)
+ *
  * ```ts
  * import { Channel, Console, Data } from "effect"
  *
@@ -3107,15 +3402,21 @@ export const runDrain = self => runWith(self, pull => Effect.forever(pull, {
  * // Logs: "Processing: 1", "Processing: 2", "Processing: 3"
  * ```
  *
- * @since 2.0.0
  * @category execution
+ * @since 4.0.0
  */
 export const runForEach = /*#__PURE__*/dual(2, (self, f) => runWith(self, pull => Effect.forever(Effect.flatMap(pull, f), {
   disableYield: true
 })));
 /**
- * @since 2.0.0
+ * Runs a channel and applies an effectful predicate to each output element
+ * until the predicate returns `false`.
+ *
+ * Returning `true` continues consuming the channel. Returning `false` stops
+ * consumption early. The returned effect completes with `void`.
+ *
  * @category execution
+ * @since 4.0.0
  */
 export const runForEachWhile = /*#__PURE__*/dual(2, (self, f) => runWith(self, pull => pull.pipe(Effect.flatMap(f), Effect.flatMap(cont => cont ? Effect.void : Cause.done()), Effect.forever({
   disableYield: true
@@ -3123,7 +3424,8 @@ export const runForEachWhile = /*#__PURE__*/dual(2, (self, f) => runWith(self, p
 /**
  * Runs a channel and collects all output elements into an array.
  *
- * @example
+ * **Example** (Collecting channel output)
+ *
  * ```ts
  * import { Channel, Data } from "effect"
  *
@@ -3140,8 +3442,8 @@ export const runForEachWhile = /*#__PURE__*/dual(2, (self, f) => runWith(self, p
  * // Effect.runSync(collectEffect) // Returns: [1, 2, 3, 4, 5]
  * ```
  *
- * @since 2.0.0
  * @category execution
+ * @since 2.0.0
  */
 export const runCollect = self => runFold(self, () => [], (acc, o) => {
   acc.push(o);
@@ -3150,13 +3452,19 @@ export const runCollect = self => runFold(self, () => [], (acc, o) => {
 /**
  * Runs a channel and outputs the done value.
  *
- * @since 4.0.0
  * @category execution
+ * @since 4.0.0
  */
 export const runDone = self => runWith(self, identity_, Effect.succeed);
 /**
- * @since 2.0.0
+ * Runs a channel until the first output element is available, returning it in
+ * an `Option`.
+ *
+ * Returns `Option.some` with the first output element, or `Option.none` if the
+ * channel completes without emitting output.
+ *
  * @category execution
+ * @since 4.0.0
  */
 export const runHead = self => Effect.suspend(() => {
   let head = Option.none();
@@ -3166,8 +3474,14 @@ export const runHead = self => Effect.suspend(() => {
   })), () => Effect.succeed(head));
 });
 /**
- * @since 2.0.0
+ * Runs a channel to completion and returns the last output element in an
+ * `Option`.
+ *
+ * Returns `Option.some` with the last emitted element, or `Option.none` if the
+ * channel completes without emitting output.
+ *
  * @category execution
+ * @since 4.0.0
  */
 export const runLast = self => Effect.suspend(() => {
   const absent = Symbol(); // Prevent boxing
@@ -3182,7 +3496,8 @@ export const runLast = self => Effect.suspend(() => {
 /**
  * Runs a channel and folds over all output elements with an accumulator.
  *
- * @example
+ * **Example** (Folding channel output)
+ *
  * ```ts
  * import { Channel, Data } from "effect"
  *
@@ -3199,8 +3514,8 @@ export const runLast = self => Effect.suspend(() => {
  * // Effect.runSync(sumEffect) // Returns: 15
  * ```
  *
- * @since 2.0.0
  * @category execution
+ * @since 4.0.0
  */
 export const runFold = /*#__PURE__*/dual(3, (self, initial, f) => Effect.suspend(() => {
   let state = initial();
@@ -3213,8 +3528,14 @@ export const runFold = /*#__PURE__*/dual(3, (self, initial, f) => Effect.suspend
   }), () => Effect.succeed(state));
 }));
 /**
- * @since 2.0.0
+ * Runs a channel and effectfully folds all output elements with an accumulator.
+ *
+ * The initial accumulator is evaluated lazily. Each output element is passed to
+ * the effectful accumulator function. The returned effect succeeds with the
+ * final accumulator value.
+ *
  * @category execution
+ * @since 4.0.0
  */
 export const runFoldEffect = /*#__PURE__*/dual(3, (self, initial, f) => Effect.suspend(() => {
   let state = initial();
@@ -3227,9 +3548,14 @@ export const runFoldEffect = /*#__PURE__*/dual(3, (self, initial, f) => Effect.s
   }), () => Effect.succeed(state));
 }));
 /**
- * Converts a channel to a Pull data structure for low-level consumption.
+ * Converts a channel to a scoped `Pull` for low-level consumption.
+ *
+ * The effect requires a `Scope`. The returned pull should be consumed only
+ * while that scope remains open. Pulls are serialized so only one pull is
+ * evaluated at a time.
+ *
+ * **Example** (Converting channels to pulls)
  *
- * @example
  * ```ts
  * import { Channel, Data, Effect } from "effect"
  *
@@ -3248,8 +3574,8 @@ export const runFoldEffect = /*#__PURE__*/dual(3, (self, initial, f) => Effect.s
  * // Use the Pull to manually consume elements
  * ```
  *
+ * @category destructors
  * @since 2.0.0
- * @category Destructors
  */
 export const toPull = /*#__PURE__*/Effect.fnUntraced(function* (self) {
   const semaphore = Semaphore.makeUnsafe(1);
@@ -3264,7 +3590,8 @@ Effect.catchCause(cause => Effect.succeed(Effect.failCause(cause))));
 /**
  * Converts a channel to a Pull within an existing scope.
  *
- * @example
+ * **Example** (Converting channels to scoped pulls)
+ *
  * ```ts
  * import { Channel, Data, Effect, Scope } from "effect"
  *
@@ -3283,13 +3610,19 @@ Effect.catchCause(cause => Effect.succeed(Effect.failCause(cause))));
  * })
  * ```
  *
+ * @category destructors
  * @since 4.0.0
- * @category Destructors
  */
 export const toPullScoped = (self, scope) => toTransform(self)(Cause.done(), scope);
 /**
+ * Runs a channel and offers each output element into a queue.
+ *
+ * When the channel completes, the queue is ended. When the channel fails, the
+ * queue is failed with the channel's cause. The returned effect itself
+ * completes with `void`.
+ *
+ * @category destructors
  * @since 4.0.0
- * @category Destructors
  */
 export const runIntoQueue = /*#__PURE__*/dual(args => isChannel(args[0]), (self, queue) => Effect.uninterruptibleMask(restore => runForEach(self, value => Queue.offer(queue, value)).pipe(restore, Effect.exit, Effect.flatMap(exit => {
   if (Exit.isSuccess(exit)) {
@@ -3300,8 +3633,15 @@ export const runIntoQueue = /*#__PURE__*/dual(args => isChannel(args[0]), (self,
   return Effect.void;
 }))));
 /**
+ * Runs a channel that emits non-empty arrays and offers each array element into
+ * a queue.
+ *
+ * When the channel completes, the queue is ended. When the channel fails, the
+ * queue is failed with the channel's cause. The returned effect itself
+ * completes with `void`.
+ *
+ * @category destructors
  * @since 4.0.0
- * @category Destructors
  */
 export const runIntoQueueArray = /*#__PURE__*/dual(args => isChannel(args[0]), (self, queue) => Effect.uninterruptibleMask(restore => runForEach(self, value => Queue.offerAll(queue, value)).pipe(restore, Effect.exit, Effect.flatMap(exit => {
   if (Exit.isSuccess(exit)) {
@@ -3312,9 +3652,15 @@ export const runIntoQueueArray = /*#__PURE__*/dual(args => isChannel(args[0]), (
   return Effect.void;
 }))));
 /**
- * Converts a channel to a queue for concurrent consumption.
+ * Creates a scoped queue and forks the channel to feed it for concurrent
+ * consumption.
+ *
+ * Output elements are offered to the queue. Channel completion and failure are
+ * signaled through the queue. The queue is shut down when the surrounding scope
+ * closes.
+ *
+ * **Example** (Converting channels to queues)
  *
- * @example
  * ```ts
  * import { Channel, Data } from "effect"
  *
@@ -3332,8 +3678,8 @@ export const runIntoQueueArray = /*#__PURE__*/dual(args => isChannel(args[0]), (
  * // Multiple consumers can read from the queue
  * ```
  *
- * @since 4.0.0
- * @category Destructors
+ * @category destructors
+ * @since 2.0.0
  */
 export const toQueue = /*#__PURE__*/dual(args => isChannel(args[0]), /*#__PURE__*/Effect.fnUntraced(function* (self, options) {
   const scope = yield* Effect.scope;
@@ -3346,8 +3692,14 @@ export const toQueue = /*#__PURE__*/dual(args => isChannel(args[0]), /*#__PURE__
   return queue;
 }));
 /**
+ * Creates a scoped queue and forks an array-emitting channel to feed it.
+ *
+ * Each element inside emitted non-empty arrays is offered to the queue. Channel
+ * completion and failure are signaled through the queue. The queue is shut down
+ * when the surrounding scope closes.
+ *
+ * @category destructors
  * @since 4.0.0
- * @category Destructors
  */
 export const toQueueArray = /*#__PURE__*/dual(args => isChannel(args[0]), /*#__PURE__*/Effect.fnUntraced(function* (self, options) {
   const scope = yield* Effect.scope;
@@ -3365,8 +3717,8 @@ export const toQueueArray = /*#__PURE__*/dual(args => isChannel(args[0]), /*#__P
  * `shutdownOnEnd` indicates whether the PubSub should be shut down when the
  * channel ends. By default this is `true`.
  *
- * @since 4.0.0
- * @category Destructors
+ * @category destructors
+ * @since 2.0.0
  */
 export const toPubSub = /*#__PURE__*/dual(2, /*#__PURE__*/Effect.fnUntraced(function* (self, options) {
   const pubsub = yield* makePubSub(options);
@@ -3376,19 +3728,26 @@ export const toPubSub = /*#__PURE__*/dual(2, /*#__PURE__*/Effect.fnUntraced(func
   return pubsub;
 }));
 /**
+ * Runs a channel and publishes each output element to a `PubSub`.
+ *
+ * The channel's output values are published as individual PubSub messages. Use
+ * `options.shutdownOnEnd` to shut down the PubSub when channel execution ends.
+ *
+ * @category destructors
  * @since 4.0.0
- * @category Destructors
  */
 export const runIntoPubSub = /*#__PURE__*/dual(args => isChannel(args[0]), (self, pubsub, options) => runForEach(self, value => PubSub.publish(pubsub, value)).pipe(options?.shutdownOnEnd === true ? Effect.ensuring(PubSub.shutdown(pubsub)) : identity_));
 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);
 /**
- * Converts a channel to a PubSub for concurrent consumption.
+ * Converts an array-emitting channel to a scoped `PubSub` for concurrent
+ * consumption.
  *
- * `shutdownOnEnd` indicates whether the PubSub should be shut down when the
- * channel ends. By default this is `true`.
+ * Each element inside emitted non-empty arrays is published as an individual
+ * PubSub message. `shutdownOnEnd` indicates whether the PubSub should be shut
+ * down when the channel ends. By default this is `true`.
  *
+ * @category destructors
  * @since 4.0.0
- * @category Destructors
  */
 export const toPubSubArray = /*#__PURE__*/dual(2, /*#__PURE__*/Effect.fnUntraced(function* (self, options) {
   const pubsub = yield* makePubSub(options);
@@ -3398,15 +3757,26 @@ export const toPubSubArray = /*#__PURE__*/dual(2, /*#__PURE__*/Effect.fnUntraced
   return pubsub;
 }));
 /**
+ * Runs an array-emitting channel and publishes each array element to a
+ * `PubSub`.
+ *
+ * Each element inside emitted non-empty arrays is published as an individual
+ * PubSub message. Use `options.shutdownOnEnd` to shut down the PubSub when
+ * channel execution ends.
+ *
+ * @category destructors
  * @since 4.0.0
- * @category Destructors
  */
 export const runIntoPubSubArray = /*#__PURE__*/dual(args => isChannel(args[0]), (self, pubsub, options) => runForEach(self, value => PubSub.publishAll(pubsub, value)).pipe(options?.shutdownOnEnd === true ? Effect.ensuring(PubSub.shutdown(pubsub)) : identity_));
 /**
- * Converts a channel to a PubSub for concurrent consumption.
+ * Converts a channel to a scoped `PubSub` of `Take` values.
+ *
+ * Emitted non-empty arrays are published as output `Take` values. When the
+ * channel ends, its final `Exit` is published so subscribers can observe
+ * completion or failure.
  *
+ * @category destructors
  * @since 4.0.0
- * @category Destructors
  */
 export const toPubSubTake = /*#__PURE__*/dual(2, /*#__PURE__*/Effect.fnUntraced(function* (self, options) {
   const pubsub = yield* makePubSub(options);