effect 4.0.0-beta.102 → 4.0.0-beta.103

package/dist/Channel.js

@@ -23,6 +23,7 @@ import { addSpanStackTrace } from "./internal/tracer.js";
 import * as Iterable from "./Iterable.js";
 import * as Latch from "./Latch.js";
 import * as Layer from "./Layer.js";
+import * as MutableRef from "./MutableRef.js";
 import * as Option from "./Option.js";
 import { pipeArguments } from "./Pipeable.js";
 import { hasProperty, isTagged } from "./Predicate.js";
@@ -50,12 +51,12 @@ export const TypeId = "~effect/Channel";
  *
  * **Example** (Checking for channels)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Channel } from "effect"
  *
  * const channel = Channel.succeed(42)
- * console.log(Channel.isChannel(channel)) // true
- * console.log(Channel.isChannel("not a channel")) // false
+ * Channel.isChannel(channel) // => true
+ * Channel.isChannel("not a channel") // => false
  * ```
  *
  * @category guards
@@ -82,12 +83,13 @@ const ChannelProto = {
  *
  * **Example** (Creating channels from transforms)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Channel, Effect } from "effect"
  *
  * const channel = Channel.fromTransform((upstream, scope) =>
  *   Effect.succeed(upstream)
  * )
+ * await Effect.runPromise(Channel.runCollect(channel)) // => []
  * ```
  *
  * @category constructors
@@ -103,7 +105,7 @@ export const fromTransform = transform => {
  *
  * **Example** (Transforming pull behavior)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Channel, Effect } from "effect"
  *
  * // Transform a channel by modifying its pull behavior
@@ -116,7 +118,7 @@ export const fromTransform = transform => {
  *       Effect.map(pull, (value) => value * 2)
  *     )
  * )
- * // Outputs: 2, 4, 6
+ * await Effect.runPromise(Channel.runCollect(transformedChannel)) // => [2, 4, 6]
  * ```
  *
  * @category constructors
@@ -128,12 +130,18 @@ export const transformPull = (self, f) => fromTransform((upstream, scope) => Eff
  *
  * **Example** (Creating channels from pulls)
  *
- * ```ts
- * import { Channel, Effect } from "effect"
+ * ```ts import.meta.vitest
+ * import { Cause, Channel, Effect } from "effect"
  *
- * const channel = Channel.fromPull(
- *   Effect.succeed(Effect.succeed(42))
- * )
+ * const channel = Channel.fromPull(Effect.sync(() => {
+ *   let emitted = false
+ *   return Effect.suspend(() => {
+ *     if (emitted) return Cause.done()
+ *     emitted = true
+ *     return Effect.succeed(42)
+ *   })
+ * }))
+ * await Effect.runPromise(Channel.runCollect(channel)) // => [42]
  * ```
  *
  * @category constructors
@@ -166,12 +174,13 @@ export const fromTransformBracket = f => fromTransform(Effect.fnUntraced(functio
  *
  * **Example** (Extracting channel transforms)
  *
- * ```ts
- * import { Channel } from "effect"
+ * ```ts import.meta.vitest
+ * import { Channel, Effect } from "effect"
  *
  * const channel = Channel.succeed(42)
  * const transform = Channel.toTransform(channel)
- * // transform can now be used directly
+ * typeof transform // => "function"
+ * Effect.runSync(Channel.runCollect(channel)) // => [42]
  * ```
  *
  * @category destructors
@@ -183,10 +192,10 @@ export const toTransform = channel => channel.transform;
  *
  * **Example** (Reading the default chunk size)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Channel } from "effect"
  *
- * console.log(Channel.DefaultChunkSize) // 4096
+ * Channel.DefaultChunkSize // => 4096
  * ```
  *
  * @category constants
@@ -202,7 +211,7 @@ const asyncQueue = (scope, f, options) => Queue.make({
  *
  * **Example** (Creating channels from callbacks)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Channel, Effect, Queue } from "effect"
  *
  * const channel = Channel.callback<number>((queue) =>
@@ -210,8 +219,10 @@ const asyncQueue = (scope, f, options) => Queue.make({
  *     yield* Queue.offer(queue, 1)
  *     yield* Queue.offer(queue, 2)
  *     yield* Queue.offer(queue, 3)
+ *     yield* Queue.end(queue)
  *   })
  * )
+ * await Effect.runPromise(Channel.runCollect(channel)) // => [1, 2, 3]
  * ```
  *
  * @category constructors
@@ -223,14 +234,15 @@ export const callback = (f, options) => fromTransform((_, scope) => Effect.map(a
  *
  * **Example** (Creating array channels from callbacks)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Channel, Effect, Queue } from "effect"
  *
  * const channel = Channel.callbackArray<number>(Effect.fn(function*(queue) {
  *   yield* Queue.offer(queue, 1)
  *   yield* Queue.offer(queue, 2)
+ *   yield* Queue.end(queue)
  * }))
- * // Emits arrays of numbers instead of individual numbers
+ * await Effect.runPromise(Channel.runCollect(channel)) // => [[1, 2]]
  * ```
  *
  * @category constructors
@@ -242,11 +254,11 @@ export const callbackArray = (f, options) => fromTransform((_, scope) => Effect.
  *
  * **Example** (Suspending channel creation)
  *
- * ```ts
- * import { Channel } from "effect"
+ * ```ts import.meta.vitest
+ * import { Channel, Effect } from "effect"
  *
  * const channel = Channel.suspend(() => Channel.succeed(42))
- * // The inner channel is not created until the suspended channel is run
+ * Effect.runSync(Channel.runCollect(channel)) // => [42]
  * ```
  *
  * @category constructors
@@ -265,14 +277,16 @@ export const suspend = evaluate => fromTransform((upstream, scope) => Effect.sus
  *
  * **Example** (Managing resources with acquire-use-release)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Channel, Effect } from "effect"
  *
+ * const released: Array<string> = []
  * const channel = Channel.acquireUseRelease(
  *   Effect.succeed("resource"),
  *   (resource) => Channel.succeed(resource.toUpperCase()),
- *   (resource, exit) => Effect.log(`Released: ${resource}`)
+ *   (resource, exit) => Effect.sync(() => released.push(resource))
  * )
+ * const observed = [await Effect.runPromise(Channel.runCollect(channel)), released] // => [["RESOURCE"], ["resource"]]
  * ```
  *
  * @category constructors
@@ -297,13 +311,15 @@ export const acquireUseRelease = (acquire, use, release) => fromTransformBracket
  *
  * **Example** (Managing resources with acquire-release)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Channel, Effect } from "effect"
  *
+ * const released: Array<string> = []
  * const channel = Channel.acquireRelease(
  *   Effect.succeed("resource"),
- *   (resource, exit) => Effect.log(`Released: ${resource}`)
+ *   (resource, exit) => Effect.sync(() => released.push(resource))
  * )
+ * const observed = [await Effect.runPromise(Channel.runCollect(channel)), released] // => [["resource"], ["resource"]]
  * ```
  *
  * @category constructors
@@ -315,12 +331,12 @@ export const acquireRelease = /*#__PURE__*/dual(2, (self, release) => unwrap(Eff
  *
  * **Example** (Creating channels from iterators)
  *
- * ```ts
- * import { Channel } from "effect"
+ * ```ts import.meta.vitest
+ * import { Channel, Effect } from "effect"
  *
  * const numbers = [1, 2, 3, 4, 5]
  * const channel = Channel.fromIterator(() => numbers[Symbol.iterator]())
- * // Emits: 1, 2, 3, 4, 5
+ * Effect.runSync(Channel.runCollect(channel)) // => [1, 2, 3, 4, 5]
  * ```
  *
  * @category constructors
@@ -338,11 +354,11 @@ export const fromIterator = iterator => fromPull(Effect.sync(() => {
  *
  * **Example** (Creating channels from arrays)
  *
- * ```ts
- * import { Channel } from "effect"
+ * ```ts import.meta.vitest
+ * import { Channel, Effect } from "effect"
  *
  * const channel = Channel.fromArray([1, 2, 3, 4, 5])
- * // Emits: 1, 2, 3, 4, 5
+ * Effect.runSync(Channel.runCollect(channel)) // => [1, 2, 3, 4, 5]
  * ```
  *
  * @category constructors
@@ -357,12 +373,12 @@ export const fromArray = array => fromPull(Effect.sync(() => {
  *
  * **Example** (Creating channels from chunks)
  *
- * ```ts
- * import { Channel, Chunk } from "effect"
+ * ```ts import.meta.vitest
+ * import { Channel, Chunk, Effect } from "effect"
  *
  * const chunk = Chunk.make(1, 2, 3)
  * const channel = Channel.fromChunk(chunk)
- * // Emits: 1, 2, 3
+ * Effect.runSync(Channel.runCollect(channel)) // => [1, 2, 3]
  * ```
  *
  * @category constructors
@@ -374,8 +390,8 @@ export const fromChunk = chunk => fromArray(Chunk.toReadonlyArray(chunk));
  *
  * **Example** (Batching iterator output)
  *
- * ```ts
- * import { Channel } from "effect"
+ * ```ts import.meta.vitest
+ * import { Channel, Effect } from "effect"
  *
  * // Create a channel from a simple iterator
  * const numberIterator = (): Iterator<number, string> => {
@@ -391,13 +407,13 @@ export const fromChunk = chunk => fromArray(Chunk.toReadonlyArray(chunk));
  * }
  *
  * const channel = Channel.fromIteratorArray(() => numberIterator(), 2)
- * // This will emit arrays: [0, 1], [2], then complete with "finished"
+ * Effect.runSync(Channel.runCollect(channel)) // => [[0, 1], [2]]
  * ```
  *
  * **Example** (Batching generator output)
  *
- * ```ts
- * import { Channel } from "effect"
+ * ```ts import.meta.vitest
+ * import { Channel, Effect } from "effect"
  *
  * // Create channel from a generator function
  * function* fibonacci(): Generator<number, void, unknown> {
@@ -409,7 +425,7 @@ export const fromChunk = chunk => fromArray(Chunk.toReadonlyArray(chunk));
  * }
  *
  * const fibChannel = Channel.fromIteratorArray(() => fibonacci(), 3)
- * // Emits: [0, 1, 1], [2, 3], then completes
+ * Effect.runSync(Channel.runCollect(fibChannel)) // => [[0, 1, 1], [2, 3]]
  * ```
  *
  * @category constructors
@@ -440,12 +456,12 @@ export const fromIteratorArray = (iterator, chunkSize = DefaultChunkSize) => fro
  *
  * **Example** (Creating channels from iterables)
  *
- * ```ts
- * import { Channel } from "effect"
+ * ```ts import.meta.vitest
+ * import { Channel, Effect } from "effect"
  *
  * const set = new Set([1, 2, 3])
  * const channel = Channel.fromIterable(set)
- * // Emits: 1, 2, 3
+ * Effect.runSync(Channel.runCollect(channel)) // => [1, 2, 3]
  * ```
  *
  * @category constructors
@@ -457,12 +473,12 @@ export const fromIterable = iterable => fromIterator(() => iterable[Symbol.itera
  *
  * **Example** (Batching iterable output)
  *
- * ```ts
- * import { Channel } from "effect"
+ * ```ts import.meta.vitest
+ * import { Channel, Effect } from "effect"
  *
  * const numbers = [1, 2, 3, 4, 5]
- * const channel = Channel.fromIterableArray(numbers)
- * // Emits arrays like: [1, 2, 3, 4], [5] (based on chunk size)
+ * const channel = Channel.fromIterableArray(numbers, 4)
+ * Effect.runSync(Channel.runCollect(channel)) // => [[1, 2, 3, 4], [5]]
  * ```
  *
  * @category constructors
@@ -474,11 +490,11 @@ export const fromIterableArray = (iterable, chunkSize = DefaultChunkSize) => fro
  *
  * **Example** (Creating channels that succeed)
  *
- * ```ts
- * import { Channel } from "effect"
+ * ```ts import.meta.vitest
+ * import { Channel, Effect } from "effect"
  *
  * const channel = Channel.succeed(42)
- * // Emits: 42
+ * Effect.runSync(Channel.runCollect(channel)) // => [42]
  * ```
  *
  * @category constructors
@@ -490,11 +506,11 @@ export const succeed = value => fromEffect(Effect.succeed(value));
  *
  * **Example** (Ending with a value)
  *
- * ```ts
- * import { Channel } from "effect"
+ * ```ts import.meta.vitest
+ * import { Channel, Effect } from "effect"
  *
  * const channel = Channel.end("done")
- * // Ends immediately with "done", emits nothing
+ * Effect.runSync(Channel.runCollect(channel)) // => []
  * ```
  *
  * @category constructors
@@ -513,8 +529,8 @@ export const endSync = evaluate => fromPull(Effect.sync(() => Cause.done(evaluat
  *
  * **Example** (Computing values lazily)
  *
- * ```ts
- * import { Channel } from "effect"
+ * ```ts import.meta.vitest
+ * import { Channel, Effect } from "effect"
  *
  * let requests = 0
  *
@@ -522,7 +538,7 @@ export const endSync = evaluate => fromPull(Effect.sync(() => Cause.done(evaluat
  *   requests += 1
  *   return `request-${requests}`
  * })
- * // Emits "request-1" when the channel runs for the first time
+ * Effect.runSync(Channel.runCollect(channel)) // => ["request-1"]
  * ```
  *
  * @category constructors
@@ -534,8 +550,8 @@ export const sync = evaluate => fromEffect(Effect.sync(evaluate));
  *
  * **Example** (Creating empty channels)
  *
- * ```ts
- * import { Channel } from "effect"
+ * ```ts import.meta.vitest
+ * import { Channel, Effect } from "effect"
  *
  * // Create an empty channel
  * const emptyChannel = Channel.empty
@@ -547,6 +563,8 @@ export const sync = evaluate => fromEffect(Effect.sync(evaluate));
  * // Empty channel can be used as a no-op in conditional logic
  * const conditionalChannel = (shouldEmit: boolean) =>
  *   shouldEmit ? Channel.succeed("data") : Channel.empty
+ *
+ * Effect.runSync(Channel.runCollect(conditionalChannel(true))) // => ["data"]
  * ```
  *
  * @category constructors
@@ -558,7 +576,7 @@ export const empty = /*#__PURE__*/fromPull(/*#__PURE__*/Effect.succeed(/*#__PURE
  *
  * **Example** (Creating non-terminating channels)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Channel } from "effect"
  *
  * // Create a channel that never completes
@@ -573,6 +591,8 @@ export const empty = /*#__PURE__*/fromPull(/*#__PURE__*/Effect.succeed(/*#__PURE
  * // Never channel is useful for testing or as a placeholder
  * const conditionalChannel = (shouldComplete: boolean) =>
  *   shouldComplete ? Channel.succeed("done") : Channel.never
+ *
+ * Channel.isChannel(conditionalChannel(false)) // => true
  * ```
  *
  * @category constructors
@@ -584,26 +604,11 @@ export const never = /*#__PURE__*/fromPull(/*#__PURE__*/Effect.succeed(Effect.ne
  *
  * **Example** (Failing with an error)
  *
- * ```ts
- * import { Channel } from "effect"
+ * ```ts import.meta.vitest
+ * import { Channel, Effect, Exit } from "effect"
  *
- * // Create a channel that fails with a string error
  * const failedChannel = Channel.fail("Something went wrong")
- *
- * // Create a channel that fails with a custom error
- * class CustomError extends Error {
- *   constructor(message: string) {
- *     super(message)
- *     this.name = "CustomError"
- *   }
- * }
- * const customErrorChannel = Channel.fail(new CustomError("Custom error"))
- *
- * // Use in error handling by piping to another channel
- * const channelWithFallback = Channel.concatWith(
- *   failedChannel,
- *   () => Channel.succeed("fallback value")
- * )
+ * Effect.runSync(Effect.exit(Channel.runCollect(failedChannel))) // => Exit.fail("Something went wrong")
  * ```
  *
  * @category constructors
@@ -621,27 +626,18 @@ export const fail = error => fromPull(Effect.succeed(Effect.fail(error)));
  *
  * **Example** (Failing with a lazy error)
  *
- * ```ts
- * import { Channel } from "effect"
+ * ```ts import.meta.vitest
+ * import { Channel, Effect, Exit } from "effect"
  *
- * // Create a channel that fails with a lazily computed error
- * const failedChannel = Channel.failSync(() => {
- *   console.log("Computing error...")
- *   return new Error("Computed at runtime")
- * })
- *
- * // The error computation is deferred until the channel runs
  * let attempts = 0
  * const conditionalError = Channel.failSync(() => {
  *   attempts += 1
  *   return `Error after attempt ${attempts}`
  * })
- *
- * // Use with expensive error construction
- * const expensiveError = Channel.failSync(() => {
- *   const requestId = "request-123"
- *   return new Error(`Failed while processing ${requestId}`)
- * })
+ * const observed = [
+ *   Effect.runSync(Effect.exit(Channel.runCollect(conditionalError))),
+ *   attempts
+ * ] // => [Exit.fail("Error after attempt 1"), 1]
  * ```
  *
  * @category constructors
@@ -658,20 +654,12 @@ export const failSync = evaluate => fromPull(Effect.failSync(evaluate));
  *
  * **Example** (Failing with causes)
  *
- * ```ts
- * import { Cause, Channel } from "effect"
+ * ```ts import.meta.vitest
+ * import { Cause, Channel, Effect, Exit } from "effect"
  *
- * // Create a channel that fails with a simple cause
  * const simpleCause = Cause.fail("Simple error")
  * const failedChannel = Channel.failCause(simpleCause)
- *
- * // Create a channel with a die cause
- * const dieCause = Cause.die(new Error("System error"))
- * const dieFailure = Channel.failCause(dieCause)
- *
- * // Create a channel with a simple fail cause
- * const failCause = Cause.fail("Simple error")
- * const simpleFail = Channel.failCause(failCause)
+ * Effect.runSync(Effect.exit(Channel.runCollect(failedChannel))) // => Exit.failCause(simpleCause)
  * ```
  *
  * @category constructors
@@ -684,8 +672,8 @@ export const failCause = cause => fromPull(Effect.failCause(cause));
  *
  * **Example** (Failing with lazy causes)
  *
- * ```ts
- * import { Cause, Channel } from "effect"
+ * ```ts import.meta.vitest
+ * import { Cause, Channel, Effect, Exit } from "effect"
  *
  * // Create a channel that fails with a lazily computed cause
  * let attempts = 0
@@ -694,11 +682,10 @@ export const failCause = cause => fromPull(Effect.failCause(cause));
  *   return Cause.fail(`Runtime error after attempt ${attempts}`)
  * })
  *
- * // Create a channel with die cause computation
- * const dieCauseChannel = Channel.failCauseSync(() => {
- *   const operation = "load-profile"
- *   return Cause.die(`Unexpected defect during ${operation}`)
- * })
+ * const observed = [
+ *   Effect.runSync(Effect.exit(Channel.runCollect(failedChannel))),
+ *   attempts
+ * ] // => [Exit.fail("Runtime error after attempt 1"), 1]
  * ```
  *
  * @category constructors
@@ -710,20 +697,12 @@ export const failCauseSync = evaluate => fromPull(Effect.failCauseSync(evaluate)
  *
  * **Example** (Dying with defects)
  *
- * ```ts
- * import { Channel } from "effect"
- *
- * // Create a channel that dies with a string defect
- * const diedChannel = Channel.die("Unrecoverable error")
- *
- * // Create a channel that dies with an Error object
- * const errorDefect = Channel.die(new Error("System failure"))
+ * ```ts import.meta.vitest
+ * import { Cause, Channel, Effect, Exit } from "effect"
  *
- * // Die with any value as a defect
- * const objectDefect = Channel.die({
- *   code: "SYSTEM_FAILURE",
- *   details: "Critical system component failed"
- * })
+ * const defect = "Unrecoverable error"
+ * const diedChannel = Channel.die(defect)
+ * Effect.runSync(Effect.exit(Channel.runCollect(diedChannel))) // => Exit.failCause(Cause.die(defect))
  * ```
  *
  * @category constructors
@@ -735,33 +714,13 @@ export const die = defect => failCause(Cause.die(defect));
  *
  * **Example** (Creating channels from effects)
  *
- * ```ts
- * import { Channel, Data, Effect } from "effect"
- *
- * class DatabaseError extends Data.TaggedError("DatabaseError")<{
- *   readonly message: string
- * }> {}
+ * ```ts import.meta.vitest
+ * import { Channel, Effect } from "effect"
  *
- * // Create a channel from a successful effect
  * const successChannel = Channel.fromEffect(
  *   Effect.succeed("Hello from effect!")
  * )
- *
- * // Create a channel from an effect that might fail
- * const fetchUserChannel = Channel.fromEffect(
- *   Effect.tryPromise({
- *     try: () => fetch("/api/user").then((res) => res.json()),
- *     catch: (error) => new DatabaseError({ message: String(error) })
- *   })
- * )
- *
- * // Channel from effect with async computation
- * const asyncChannel = Channel.fromEffect(
- *   Effect.gen(function*() {
- *     yield* Effect.sleep("100 millis")
- *     return "Async result"
- *   })
- * )
+ * Effect.runSync(Channel.runCollect(successChannel)) // => ["Hello from effect!"]
  * ```
  *
  * @category constructors
@@ -812,35 +771,17 @@ export const fromEffectTake = effect => fromPull(Effect.succeed(Effect.flatMap(e
  *
  * **Example** (Creating channels from queues)
  *
- * ```ts
- * import { Channel, Data, Effect, Queue } from "effect"
- *
- * class QueueError extends Data.TaggedError("QueueError")<{
- *   readonly reason: string
- * }> {}
+ * ```ts import.meta.vitest
+ * import { Cause, Channel, Effect, Queue } from "effect"
  *
  * const program = Effect.gen(function*() {
- *   // Create a bounded queue
- *   const queue = yield* Queue.bounded<string, QueueError>(10)
- *
- *   // Add some items to the queue
- *   yield* Queue.offer(queue, "item1")
- *   yield* Queue.offer(queue, "item2")
- *   yield* Queue.offer(queue, "item3")
- *
- *   // Create a channel from the queue
+ *   const queue = yield* Queue.bounded<string, Cause.Done>(3)
+ *   yield* Queue.offerAll(queue, ["item1", "item2", "item3"])
+ *   yield* Queue.end(queue)
  *   const channel = Channel.fromQueue(queue)
- *
- *   // The channel will read items from the queue one by one
- *   return channel
- * })
- *
- * // Sliding queue example
- * const slidingProgram = Effect.gen(function*() {
- *   const slidingQueue = yield* Queue.sliding<number, QueueError>(5)
- *   yield* Queue.offerAll(slidingQueue, [1, 2, 3, 4, 5, 6])
- *   return Channel.fromQueue(slidingQueue)
+ *   return yield* Channel.runCollect(channel)
  * })
+ * await Effect.runPromise(program) // => ["item1", "item2", "item3"]
  * ```
  *
  * @category constructors
@@ -852,39 +793,17 @@ export const fromQueue = queue => fromPull(Effect.succeed(Queue.take(queue)));
  *
  * **Example** (Creating batched channels from queues)
  *
- * ```ts
- * import { Channel, Data, Effect, Queue } from "effect"
- *
- * class ProcessingError extends Data.TaggedError("ProcessingError")<{
- *   readonly stage: string
- * }> {}
+ * ```ts import.meta.vitest
+ * import { Cause, Channel, Effect, Queue } from "effect"
  *
  * const program = Effect.gen(function*() {
- *   // Create a queue for batch processing
- *   const queue = yield* Queue.bounded<number, ProcessingError>(100)
- *
- *   // Fill queue with data
- *   yield* Queue.offerAll(queue, [1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
- *
- *   // Create a channel that reads arrays from the queue
+ *   const queue = yield* Queue.bounded<number, Cause.Done>(4)
+ *   yield* Queue.offerAll(queue, [1, 2, 3, 4])
+ *   yield* Queue.end(queue)
  *   const arrayChannel = Channel.fromQueueArray(queue)
- *
- *   // This will emit non-empty arrays of elements instead of individual items
- *   // Useful for batch processing scenarios
- *   return arrayChannel
- * })
- *
- * // High-throughput processing example
- * const batchProcessor = Effect.gen(function*() {
- *   const dataQueue = yield* Queue.dropping<string, ProcessingError>(1000)
- *   const batchChannel = Channel.fromQueueArray(dataQueue)
- *
- *   // Process data in batches for better performance
- *   return Channel.map(
- *     batchChannel,
- *     (batch) => batch.map((item) => item.toUpperCase())
- *   )
+ *   return yield* Channel.runCollect(arrayChannel)
  * })
+ * await Effect.runPromise(program) // => [[1, 2, 3, 4]]
  * ```
  *
  * @category constructors
@@ -904,8 +823,8 @@ export const identity = () => fromTransform((upstream, _scope) => Effect.succeed
  *
  * **Example** (Creating channels from subscriptions)
  *
- * ```ts
- * import { Channel, Data, Effect, PubSub } from "effect"
+ * ```ts import.meta.vitest
+ * import { Channel, Data, Effect, Option, PubSub } from "effect"
  *
  * class SubscriptionError extends Data.TaggedError("SubscriptionError")<{
  *   readonly reason: string
@@ -930,6 +849,8 @@ export const identity = () => fromTransform((upstream, _scope) => Effect.succeed
  *   // The channel will receive all published messages
  *   return channel
  * })
+ * const result = Effect.scoped(Effect.flatMap(program, Channel.runHead))
+ * await Effect.runPromise(result) // => Option.some("Hello")
  *
  * // Real-time notifications example
  * const notificationChannel = Effect.gen(function*() {
@@ -955,8 +876,8 @@ export const fromSubscription = subscription => fromPull(Effect.succeed(Effect.o
  *
  * **Example** (Batching subscription values)
  *
- * ```ts
- * import { Channel, Data, Effect, PubSub } from "effect"
+ * ```ts import.meta.vitest
+ * import { Channel, Data, Effect, Option, PubSub } from "effect"
  *
  * class StreamError extends Data.TaggedError("StreamError")<{
  *   readonly message: string
@@ -978,12 +899,14 @@ export const fromSubscription = subscription => fromPull(Effect.succeed(Effect.o
  *   // The channel will output arrays like [1, 2, 3] and [4]
  *   return channel
  * })
+ * const result = Effect.scoped(Effect.flatMap(program, Channel.runHead))
+ * await Effect.runPromise(result) // => Option.some([1, 2, 3, 4])
  * ```
  *
  * **Example** (Processing subscription values in batches)
  *
- * ```ts
- * import { Channel, Data, Effect, PubSub } from "effect"
+ * ```ts import.meta.vitest
+ * import { Channel, Data, Effect, Option, PubSub } from "effect"
  *
  * class BatchProcessingError extends Data.TaggedError("BatchProcessingError")<{
  *   readonly reason: string
@@ -997,19 +920,21 @@ export const fromSubscription = subscription => fromPull(Effect.succeed(Effect.o
  *   const batchChannel = Channel.fromSubscriptionArray(subscription)
  *
  *   // Transform to process each batch
- *   const processedChannel = Channel.map(batchChannel, (batch) => {
- *     console.log(`Processing batch of ${batch.length} items:`, batch)
- *     return batch.map((item) => item.toUpperCase())
- *   })
+ *   const processedChannel = Channel.map(batchChannel, (batch) =>
+ *     batch.map((item) => item.toUpperCase())
+ *   )
  *
+ *   yield* PubSub.publishAll(pubsub, ["one", "two"])
  *   return processedChannel
  * })
+ * const batch = Effect.scoped(Effect.flatMap(batchProcessor, Channel.runHead))
+ * await Effect.runPromise(batch) // => Option.some(["ONE", "TWO"])
  * ```
  *
  * **Example** (Aggregating subscription metrics)
  *
- * ```ts
- * import { Channel, Effect, PubSub } from "effect"
+ * ```ts import.meta.vitest
+ * import { Channel, Effect, Option, PubSub } from "effect"
  *
  * const metricsAggregator = Effect.gen(function*() {
  *   const metricsPubSub = yield* PubSub.bounded<
@@ -1039,8 +964,12 @@ export const fromSubscription = subscription => fromPull(Effect.succeed(Effect.o
  *     }
  *   })
  *
+ *   yield* PubSub.publish(metricsPubSub, { timestamp: 1, value: 10 })
  *   return aggregatedChannel
  * })
+ * const metric = Effect.scoped(Effect.flatMap(metricsAggregator, Channel.runHead))
+ * const result = await Effect.runPromise(metric)
+ * Option.map(result, ({ count, sum, average, min, max }) => ({ count, sum, average, min, max })) // => Option.some({ count: 1, sum: 10, average: 10, min: 10, max: 10 })
  * ```
  *
  * @category constructors
@@ -1058,15 +987,15 @@ export const fromSubscriptionArray = subscription => fromPull(Effect.succeed(Eff
  *
  * **Example** (Creating channels from PubSubs)
  *
- * ```ts
- * import { Channel, Data, Effect, PubSub } from "effect"
+ * ```ts import.meta.vitest
+ * import { Channel, Data, Effect, Option, PubSub } from "effect"
  *
  * class StreamError extends Data.TaggedError("StreamError")<{
  *   readonly message: string
  * }> {}
  *
  * const program = Effect.gen(function*() {
- *   const pubsub = yield* PubSub.bounded<number>(16)
+ *   const pubsub = yield* PubSub.unbounded<number>({ replay: 3 })
  *
  *   // Create a channel that reads individual values
  *   const channel = Channel.fromPubSub(pubsub)
@@ -1079,15 +1008,17 @@ export const fromSubscriptionArray = subscription => fromPull(Effect.succeed(Eff
  *   // The channel will output: 1, 2, 3 (individual values)
  *   return channel
  * })
+ * const result = Effect.scoped(Effect.flatMap(program, Channel.runHead))
+ * await Effect.runPromise(result) // => Option.some(1)
  * ```
  *
  * **Example** (Streaming PubSub notifications)
  *
- * ```ts
- * import { Channel, Effect, PubSub } from "effect"
+ * ```ts import.meta.vitest
+ * import { Channel, Effect, Option, PubSub } from "effect"
  *
  * const notificationService = Effect.gen(function*() {
- *   const notificationPubSub = yield* PubSub.bounded<string>(50)
+ *   const notificationPubSub = yield* PubSub.unbounded<string>({ replay: 1 })
  *
  *   // Create a channel for real-time notifications
  *   const notificationChannel = Channel.fromPubSub(notificationPubSub)
@@ -1100,14 +1031,17 @@ export const fromSubscriptionArray = subscription => fromPull(Effect.succeed(Eff
  *     id: `notification:${message}`
  *   }))
  *
+ *   yield* PubSub.publish(notificationPubSub, "ready")
  *   return timestampedChannel
  * })
+ * const notification = Effect.scoped(Effect.flatMap(notificationService, Channel.runHead))
+ * await Effect.runPromise(notification) // => Option.some({ message: "ready", receivedAt: "2024-01-01T00:00:00.000Z", id: "notification:ready" })
  * ```
  *
  * **Example** (Processing PubSub events)
  *
- * ```ts
- * import { Channel, Effect, PubSub } from "effect"
+ * ```ts import.meta.vitest
+ * import { Channel, Effect, Option, PubSub } from "effect"
  *
  * interface DomainEvent {
  *   readonly type: string
@@ -1116,7 +1050,7 @@ export const fromSubscriptionArray = subscription => fromPull(Effect.succeed(Eff
  * }
  *
  * const eventProcessor = Effect.gen(function*() {
- *   const eventPubSub = yield* PubSub.bounded<DomainEvent>(100)
+ *   const eventPubSub = yield* PubSub.unbounded<DomainEvent>({ replay: 1 })
  *
  *   // Create a channel for processing domain events
  *   const eventChannel = Channel.fromPubSub(eventPubSub)
@@ -1133,8 +1067,11 @@ export const fromSubscriptionArray = subscription => fromPull(Effect.succeed(Eff
  *     return event
  *   })
  *
+ *   yield* PubSub.publish(eventPubSub, { type: "user.created", payload: {}, timestamp: 1 })
  *   return processedChannel
  * })
+ * const event = Effect.scoped(Effect.flatMap(eventProcessor, Channel.runHead))
+ * const result = await Effect.runPromise(event) // => Option.some({ type: "user.created", payload: {}, timestamp: 1, processed: true, processedAt: 2 })
  * ```
  *
  * @category constructors
@@ -1152,15 +1089,15 @@ export const fromPubSub = pubsub => unwrap(Effect.map(PubSub.subscribe(pubsub),
  *
  * **Example** (Batching PubSub values)
  *
- * ```ts
- * import { Channel, Data, Effect, PubSub } from "effect"
+ * ```ts import.meta.vitest
+ * import { Channel, Data, Effect, Option, PubSub } from "effect"
  *
  * class BatchError extends Data.TaggedError("BatchError")<{
  *   readonly message: string
  * }> {}
  *
  * const program = Effect.gen(function*() {
- *   const pubsub = yield* PubSub.bounded<number>(16)
+ *   const pubsub = yield* PubSub.unbounded<number>({ replay: 4 })
  *
  *   // Create a channel that reads arrays of values
  *   const channel = Channel.fromPubSubArray(pubsub)
@@ -1174,12 +1111,14 @@ export const fromPubSub = pubsub => unwrap(Effect.map(PubSub.subscribe(pubsub),
  *   // The channel will output arrays like [1, 2, 3] and [4]
  *   return channel
  * })
+ * const result = Effect.scoped(Effect.flatMap(program, Channel.runHead))
+ * await Effect.runPromise(result) // => Option.some([1, 2, 3, 4])
  * ```
  *
  * **Example** (Processing PubSub orders in batches)
  *
- * ```ts
- * import { Channel, Effect, PubSub } from "effect"
+ * ```ts import.meta.vitest
+ * import { Channel, Effect, Option, PubSub } from "effect"
  *
  * interface Order {
  *   readonly id: string
@@ -1190,7 +1129,7 @@ export const fromPubSub = pubsub => unwrap(Effect.map(PubSub.subscribe(pubsub),
  * }
  *
  * const orderBatchProcessor = Effect.gen(function*() {
- *   const orderPubSub = yield* PubSub.bounded<Order>(100)
+ *   const orderPubSub = yield* PubSub.unbounded<Order>({ replay: 1 })
  *
  *   // Create a channel that processes orders in batches
  *   const orderChannel = Channel.fromPubSubArray(orderPubSub)
@@ -1211,14 +1150,20 @@ export const fromPubSub = pubsub => unwrap(Effect.map(PubSub.subscribe(pubsub),
  *     }
  *   })
  *
+ *   yield* PubSub.publish(orderPubSub, {
+ *     id: "1", customerId: "a", items: ["book"], total: 10, submittedAt: 1
+ *   })
  *   return processedChannel
  * })
+ * const order = Effect.scoped(Effect.flatMap(orderBatchProcessor, Channel.runHead))
+ * const result = await Effect.runPromise(order)
+ * Option.map(result, (batch) => [batch.batchSize, batch.totalRevenue, batch.uniqueCustomers]) // => Option.some([1, 10, 1])
  * ```
  *
  * **Example** (Processing PubSub logs in batches)
  *
- * ```ts
- * import { Channel, Effect, PubSub } from "effect"
+ * ```ts import.meta.vitest
+ * import { Channel, Effect, Option, PubSub } from "effect"
  *
  * interface LogEntry {
  *   readonly timestamp: number
@@ -1228,7 +1173,7 @@ export const fromPubSub = pubsub => unwrap(Effect.map(PubSub.subscribe(pubsub),
  * }
  *
  * const logAggregator = Effect.gen(function*() {
- *   const logPubSub = yield* PubSub.bounded<LogEntry>(500)
+ *   const logPubSub = yield* PubSub.unbounded<LogEntry>({ replay: 1 })
  *
  *   // Create a channel that collects logs in batches
  *   const logChannel = Channel.fromPubSubArray(logPubSub)
@@ -1255,8 +1200,17 @@ export const fromPubSub = pubsub => unwrap(Effect.map(PubSub.subscribe(pubsub),
  *     }
  *   })
  *
+ *   yield* PubSub.publish(logPubSub, {
+ *     timestamp: 1,
+ *     level: "info",
+ *     message: "ready",
+ *     source: "app"
+ *   } satisfies LogEntry)
  *   return analysisChannel
  * })
+ * const log = Effect.scoped(Effect.flatMap(logAggregator, Channel.runHead))
+ * const result = await Effect.runPromise(log)
+ * Option.map(result, (batch) => [batch.batchId, batch.totalEntries, batch.infoCount]) // => Option.some(["1-1", 1, 1])
  * ```
  *
  * @category constructors
@@ -1282,6 +1236,162 @@ export const fromPubSubTake = pubsub => unwrap(Effect.map(PubSub.subscribe(pubsu
  * @since 4.0.0
  */
 export const fromSchedule = schedule => fromPull(Effect.map(Schedule.toStepWithSleep(schedule), step => step(void 0)));
+/**
+ * Creates a channel from a lazily supplied Web `ReadableStream`.
+ *
+ * **Example** (Reading from a Web stream)
+ *
+ * ```ts import.meta.vitest
+ * import { Channel, Effect } from "effect"
+ *
+ * const channel = Channel.fromReadableStream({
+ *   evaluate: () => new ReadableStream({
+ *     start(controller) {
+ *       controller.enqueue(1)
+ *       controller.close()
+ *     }
+ *   }),
+ *   onError: (cause) => new Error(String(cause))
+ * })
+ *
+ * await Effect.runPromise(Channel.runCollect(channel)) // => [[1]]
+ * ```
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export const fromReadableStream = options => fromTransform((_, scope) => readableStreamToPullUnsafe({
+  scope,
+  readable: options.evaluate(),
+  onError: options.onError,
+  releaseLockOnEnd: options.releaseLockOnEnd
+}));
+/** @internal */
+export const pullIntoWritableStream = options => Effect.acquireUseRelease(Effect.sync(() => options.writable.getWriter()), writer => {
+  const loop = options.pull.pipe(Effect.flatMap(chunk => Effect.forEach(chunk, value => Effect.tryPromise({
+    try: () => writer.ready.then(() => writer.write(value)),
+    catch: options.onError
+  }), {
+    discard: true
+  })), Effect.forever({
+    disableYield: true
+  }));
+  const withClose = options.closeOnDone !== false ? Pull.catchDone(loop, done => Effect.andThen(Effect.tryPromise({
+    try: () => writer.close(),
+    catch: options.onError
+  }), Cause.done(done))) : loop;
+  return Effect.onError(withClose, cause => Pull.isDoneCause(cause) ? Effect.void : Effect.promise(() => writer.abort(cause).catch(constVoid)));
+}, writer => Effect.sync(() => writer.releaseLock()));
+/**
+ * Creates a channel that writes upstream values to a lazily supplied Web
+ * `WritableStream`.
+ *
+ * **Example** (Writing channel input)
+ *
+ * ```ts import.meta.vitest
+ * import { Channel, Effect } from "effect"
+ *
+ * const written: Array<number> = []
+ * const sink = Channel.fromWritableStream<never, Error, number>({
+ *   evaluate: () => new WritableStream({
+ *     write(value) {
+ *       written.push(value)
+ *     }
+ *   }),
+ *   onError: (cause) => new Error(String(cause))
+ * })
+ *
+ * const program = Channel.fromArray([[1, 2] as [number, number]]).pipe(
+ *   Channel.pipeTo(sink),
+ *   Channel.runDrain
+ * )
+ *
+ * await Effect.runPromise(program)
+ * written // => [1, 2]
+ * ```
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export const fromWritableStream = options => fromTransform(pull => {
+  const writable = options.evaluate();
+  return Effect.succeed(pullIntoWritableStream({
+    ...options,
+    writable,
+    pull
+  }));
+});
+/**
+ * Creates a channel backed by a Web `TransformStream`, writing upstream values
+ * while emitting transformed values from its readable side.
+ *
+ * **Example** (Transforming channel input)
+ *
+ * ```ts import.meta.vitest
+ * import { Channel, Effect } from "effect"
+ *
+ * const transform = Channel.fromTransformStream<never, number, number, Error>({
+ *   evaluate: () => new TransformStream({
+ *     transform(value, controller) {
+ *       controller.enqueue(value * 2)
+ *     }
+ *   }),
+ *   onError: (cause) => new Error(String(cause))
+ * })
+ *
+ * const program = Channel.fromArray([[1, 2] as [number, number]]).pipe(
+ *   Channel.pipeTo(transform),
+ *   Channel.runCollect
+ * )
+ *
+ * await Effect.runPromise(program) // => [[2], [4]]
+ * ```
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export const fromTransformStream = options => fromTransform((upstream, scope) => {
+  const transform = options.evaluate();
+  const exit = MutableRef.make(undefined);
+  return pullIntoWritableStream({
+    pull: upstream,
+    writable: transform.writable,
+    onError: options.onError,
+    closeOnDone: options.closeOnDone
+  }).pipe(Effect.catchCause(cause => {
+    if (!Pull.isDoneCause(cause)) {
+      exit.current = Exit.failCause(cause);
+    }
+    return Effect.void;
+  }), Effect.forkIn(scope), Effect.flatMap(() => readableStreamToPullUnsafe({
+    scope,
+    exit,
+    readable: transform.readable,
+    onError: options.onError,
+    releaseLockOnEnd: options.releaseLockOnEnd
+  })));
+});
+const readableStreamToPullUnsafe = options => {
+  const reader = options.readable.getReader();
+  const exit = options.exit ?? MutableRef.make(undefined);
+  const pull = Effect.suspend(() => {
+    if (exit.current) return exit.current;
+    return Effect.matchCauseEffect(Effect.tryPromise({
+      try: () => reader.read(),
+      catch: options.onError
+    }), {
+      onFailure: cause => exit.current ?? Effect.failCause(cause),
+      onSuccess: ({
+        done,
+        value
+      }) => {
+        if (exit.current) return exit.current;
+        return done ? Cause.done() : Effect.succeed(Arr.of(value));
+      }
+    });
+  });
+  return Effect.as(Scope.addFinalizer(options.scope, options.releaseLockOnEnd ? Effect.sync(() => reader.releaseLock()) : Effect.promise(() => reader.cancel().catch(constVoid))), pull);
+};
 /**
  * Creates a channel that pulls values from an `AsyncIterable`.
  *
@@ -1324,8 +1434,8 @@ export const fromAsyncIterableArray = (iterable, onError) => map(fromAsyncIterab
  *
  * **Example** (Mapping channel output)
  *
- * ```ts
- * import { Channel, Data } from "effect"
+ * ```ts import.meta.vitest
+ * import { Channel, Data, Effect } from "effect"
  *
  * class TransformError extends Data.TaggedError("TransformError")<{
  *   readonly reason: string
@@ -1334,12 +1444,12 @@ export const fromAsyncIterableArray = (iterable, onError) => map(fromAsyncIterab
  * // Basic mapping of channel values
  * const numbersChannel = Channel.fromIterable([1, 2, 3, 4, 5])
  * const doubledChannel = Channel.map(numbersChannel, (n) => n * 2)
- * // Outputs: 2, 4, 6, 8, 10
+ * Effect.runSync(Channel.runCollect(doubledChannel)) // => [2, 4, 6, 8, 10]
  *
  * // Transform string data
  * const wordsChannel = Channel.fromIterable(["hello", "world", "effect"])
  * const upperCaseChannel = Channel.map(wordsChannel, (word) => word.toUpperCase())
- * // Outputs: "HELLO", "WORLD", "EFFECT"
+ * Effect.runSync(Channel.runCollect(upperCaseChannel)) // => ["HELLO", "WORLD", "EFFECT"]
  *
  * // Complex object transformation
  * type User = { id: number; name: string }
@@ -1353,6 +1463,7 @@ export const fromAsyncIterableArray = (iterable, onError) => map(fromAsyncIterab
  *   displayName: `User: ${user.name}`,
  *   isActive: true
  * }))
+ * Effect.runSync(Channel.runCollect(displayChannel)) // => [{ displayName: "User: Alice", isActive: true }, { displayName: "User: Bob", isActive: true }]
  * ```
  *
  * @category sequencing
@@ -1400,40 +1511,15 @@ const concurrencyIsSequential = concurrency => concurrency === undefined || conc
  *
  * **Example** (Mapping channel output with effects)
  *
- * ```ts
- * import { Channel, Data, Effect } from "effect"
- *
- * class NetworkError extends Data.TaggedError("NetworkError")<{
- *   readonly url: string
- * }> {}
- *
- * // Transform values using effectful operations
- * const urlsChannel = Channel.fromIterable([
- *   "/api/users/1",
- *   "/api/users/2",
- *   "/api/users/3"
- * ])
- *
- * const fetchDataChannel = Channel.mapEffect(
- *   urlsChannel,
- *   (url) =>
- *     Effect.tryPromise({
- *       try: () => fetch(url).then((res) => res.json()),
- *       catch: () => new NetworkError({ url })
- *     })
- * )
+ * ```ts import.meta.vitest
+ * import { Channel, Effect } from "effect"
  *
- * // Concurrent processing with options
  * const numbersChannel = Channel.fromIterable([1, 2, 3, 4, 5])
  * const processedChannel = Channel.mapEffect(
  *   numbersChannel,
- *   (n) =>
- *     Effect.gen(function*() {
- *       yield* Effect.sleep("100 millis") // Simulate async work
- *       return n * n
- *     }),
- *   { concurrency: 3, unordered: true }
+ *   (n) => Effect.succeed(n * n)
  * )
+ * await Effect.runPromise(Channel.runCollect(processedChannel)) // => [1, 4, 9, 16, 25]
  * ```
  *
  * @category sequencing
@@ -1523,8 +1609,8 @@ export const mapInputError = /*#__PURE__*/dual(2, (self, f) => fromTransform((up
  *
  * **Example** (Tapping channel output)
  *
- * ```ts
- * import { Channel, Console, Data } from "effect"
+ * ```ts import.meta.vitest
+ * import { Channel, Data, Effect } from "effect"
  *
  * class LogError extends Data.TaggedError("LogError")<{
  *   readonly message: string
@@ -1534,13 +1620,13 @@ export const mapInputError = /*#__PURE__*/dual(2, (self, f) => fromTransform((up
  * const numberChannel = Channel.fromIterable([1, 2, 3])
  *
  * // Tap into each output element to perform side effects
+ * const processed: Array<number> = []
  * const tappedChannel = Channel.tap(
  *   numberChannel,
- *   (n) => Console.log(`Processing number: ${n}`)
+ *   (n) => Effect.sync(() => processed.push(n))
  * )
  *
- * // The channel still outputs the same elements but logs each one
- * // Outputs: 1, 2, 3 (while logging each)
+ * const observed = [await Effect.runPromise(Channel.runCollect(tappedChannel)), processed] // => [[1, 2, 3], [1, 2, 3]]
  * ```
  *
  * @category sequencing
@@ -1560,8 +1646,8 @@ export const tap = /*#__PURE__*/dual(args => isChannel(args[0]), (self, f, optio
  *
  * **Example** (Flat mapping channel output)
  *
- * ```ts
- * import { Channel, Data } from "effect"
+ * ```ts import.meta.vitest
+ * import { Channel, Data, Effect } from "effect"
  *
  * class ProcessError extends Data.TaggedError("ProcessError")<{
  *   readonly cause: string
@@ -1577,8 +1663,7 @@ export const tap = /*#__PURE__*/dual(args => isChannel(args[0]), (self, f, optio
  *     Channel.fromIterable(Array.from({ length: n }, (_, i) => `item-${n}-${i}`))
  * )
  *
- * // Flattens nested channels into a single stream
- * // Outputs: "item-1-0", "item-2-0", "item-2-1", "item-3-0", "item-3-1", "item-3-2"
+ * Effect.runSync(Channel.runCollect(flatMappedChannel)) // => ["item-1-0", "item-2-0", "item-2-1", "item-3-0", "item-3-1", "item-3-2"]
  * ```
  *
  * @category sequencing
@@ -1614,8 +1699,8 @@ const flatMapConcurrent = (self, f, options) => self.pipe(map(f), mergeAll(optio
  *
  * **Example** (Concatenating with completion values)
  *
- * ```ts
- * import { Channel, Data } from "effect"
+ * ```ts import.meta.vitest
+ * import { Channel, Data, Effect } from "effect"
  *
  * class ConcatError extends Data.TaggedError("ConcatError")<{
  *   readonly reason: string
@@ -1626,8 +1711,7 @@ const flatMapConcurrent = (self, f, options) => self.pipe(map(f), mergeAll(optio
  *   Channel.concatWith((sum: void) => Channel.succeed(`Completed processing`))
  * )
  *
- * // Concatenates additional channel based on completion value
- * // Outputs: 1, 2, 3, then "Completed processing"
+ * Effect.runSync(Channel.runCollect(numberChannel)) // => [1, 2, 3, "Completed processing"]
  * ```
  *
  * @category sequencing
@@ -1653,8 +1737,8 @@ export const concatWith = /*#__PURE__*/dual(2, (self, f) => fromTransform((upstr
  *
  * **Example** (Concatenating channels)
  *
- * ```ts
- * import { Channel, Data } from "effect"
+ * ```ts import.meta.vitest
+ * import { Channel, Data, Effect } from "effect"
  *
  * class ConcatError extends Data.TaggedError("ConcatError")<{
  *   readonly reason: string
@@ -1667,7 +1751,7 @@ export const concatWith = /*#__PURE__*/dual(2, (self, f) => fromTransform((upstr
  * // Concatenate them
  * const concatenatedChannel = Channel.concat(firstChannel, secondChannel)
  *
- * // Outputs: 1, 2, 3, "a", "b", "c"
+ * Effect.runSync(Channel.runCollect(concatenatedChannel)) // => [1, 2, 3, "a", "b", "c"]
  * ```
  *
  * @category sequencing
@@ -1737,8 +1821,8 @@ export const orElseIfEmpty = /*#__PURE__*/dual(2, (self, f) => fromTransform((up
  *
  * **Example** (Flattening nested channels)
  *
- * ```ts
- * import { Channel, Data } from "effect"
+ * ```ts import.meta.vitest
+ * import { Channel, Data, Effect } from "effect"
  *
  * class FlattenError extends Data.TaggedError("FlattenError")<{
  *   readonly cause: string
@@ -1754,7 +1838,7 @@ export const orElseIfEmpty = /*#__PURE__*/dual(2, (self, f) => fromTransform((up
  * // Flatten the nested channels
  * const flattenedChannel = Channel.flatten(nestedChannels)
  *
- * // Outputs: 1, 2, 3, 4, 5, 6
+ * Effect.runSync(Channel.runCollect(flattenedChannel)) // => [1, 2, 3, 4, 5, 6]
  * ```
  *
  * @category constructors
@@ -1766,8 +1850,8 @@ export const flatten = channels => flatMap(channels, identity_);
  *
  * **Example** (Flattening arrays of channel output)
  *
- * ```ts
- * import { Channel, Data } from "effect"
+ * ```ts import.meta.vitest
+ * import { Channel, Data, Effect } from "effect"
  *
  * class FlattenError extends Data.TaggedError("FlattenError")<{
  *   readonly message: string
@@ -1783,7 +1867,7 @@ export const flatten = channels => flatMap(channels, identity_);
  * // Flatten the arrays into individual elements
  * const flattenedChannel = Channel.flattenArray(arrayChannel)
  *
- * // Outputs: 1, 2, 3, 4, 5, 6, 7, 8, 9
+ * Effect.runSync(Channel.runCollect(flattenedChannel)) // => [1, 2, 3, 4, 5, 6, 7, 8, 9]
  * ```
  *
  * @category transforming
@@ -1836,8 +1920,8 @@ export const flattenTake = self => mapEffectSequential(self, Take.toPull);
  *
  * **Example** (Draining channel output)
  *
- * ```ts
- * import { Channel } from "effect"
+ * ```ts import.meta.vitest
+ * import { Channel, Effect } from "effect"
  *
  * // Create a channel that outputs values
  * const sourceChannel = Channel.fromIterable([1, 2, 3, 4, 5])
@@ -1845,8 +1929,7 @@ export const flattenTake = self => mapEffectSequential(self, Take.toPull);
  * // Drain all output, keeping only the completion
  * const drainedChannel = Channel.drain(sourceChannel)
  *
- * // The channel completes but emits no values
- * // Useful for consuming side effects without collecting output
+ * Effect.runSync(Channel.runCollect(drainedChannel)) // => []
  * ```
  *
  * @category constructors
@@ -1900,15 +1983,15 @@ export const schedule = /*#__PURE__*/dual(2, (self, schedule) => transformPull(s
  *
  * **Example** (Filtering channel output)
  *
- * ```ts
- * import { Channel } from "effect"
+ * ```ts import.meta.vitest
+ * import { Channel, Effect } from "effect"
  *
  * // Create a channel with mixed numbers
  * const numbersChannel = Channel.fromIterable([1, 2, 3, 4, 5, 6, 7, 8])
  *
  * // Filter to keep only even numbers
  * const evenChannel = Channel.filter(numbersChannel, (n) => n % 2 === 0)
- * // Outputs: 2, 4, 6, 8
+ * Effect.runSync(Channel.runCollect(evenChannel)) // => [2, 4, 6, 8]
  *
  * // Filter with type refinement
  * const mixedChannel = Channel.fromIterable([1, "hello", 2, "world", 3])
@@ -1916,7 +1999,7 @@ export const schedule = /*#__PURE__*/dual(2, (self, schedule) => transformPull(s
  *   mixedChannel,
  *   (value): value is number => typeof value === "number"
  * )
- * // Outputs: 1, 2, 3 (all typed as numbers)
+ * Effect.runSync(Channel.runCollect(numbersOnlyChannel)) // => [1, 2, 3]
  * ```
  *
  * @category filtering
@@ -2001,8 +2084,8 @@ export const filterMapEffect = /*#__PURE__*/dual(2, (self, filter) => fromTransf
  *
  * **Example** (Filtering array output)
  *
- * ```ts
- * import { Array, Channel } from "effect"
+ * ```ts import.meta.vitest
+ * import { Array, Channel, Effect } from "effect"
  *
  * const nonEmptyArrayPredicate = Array.isReadonlyArrayNonEmpty
  *
@@ -2015,7 +2098,7 @@ export const filterMapEffect = /*#__PURE__*/dual(2, (self, filter) => fromTransf
  *
  * // Filter arrays to keep only even numbers
  * const evenArraysChannel = Channel.filterArray(arrayChannel, (n) => n % 2 === 0)
- * // Outputs: [2, 4], [6, 8, 10], [12, 14]
+ * Effect.runSync(Channel.runCollect(evenArraysChannel)) // => [[2, 4], [6, 8, 10], [12, 14]]
  * // Note: Only non-empty filtered arrays are emitted
  *
  * // Arrays that would become empty after filtering are discarded entirely
@@ -2025,7 +2108,7 @@ export const filterMapEffect = /*#__PURE__*/dual(2, (self, filter) => fromTransf
  *   Array.make(7, 9)
  * ]).pipe(Channel.filter(nonEmptyArrayPredicate))
  * const filteredOddChannel = Channel.filterArray(oddChannel, (n) => n % 2 === 0)
- * // Outputs: [2, 4] (the arrays [1,3,5] and [7,9] are discarded)
+ * Effect.runSync(Channel.runCollect(filteredOddChannel)) // => [[2, 4]]
  * ```
  *
  * @category filtering
@@ -2112,7 +2195,7 @@ export const filterMapArrayEffect = /*#__PURE__*/dual(2, (self, filter) => trans
  *
  * **Example** (Mapping with accumulated state)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Channel, Effect } from "effect"
  *
  * // Create a channel with numbers
@@ -2128,8 +2211,6 @@ export const filterMapArrayEffect = /*#__PURE__*/dual(2, (self, filter) => trans
  *     return [newSum, [current, newSum]] as const
  *   }
  * )
- * // Outputs: 1, 1, 2, 3, 3, 6, 4, 10
- *
  * // Using with Effect for async processing
  * const asyncMapAccum = Channel.mapAccum(
  *   numbersChannel,
@@ -2140,6 +2221,8 @@ export const filterMapArrayEffect = /*#__PURE__*/dual(2, (self, filter) => trans
  *       return [newAcc, [`${value}-processed`, newAcc]] as const
  *     })
  * )
+ * Effect.runSync(Channel.runCollect(runningSum)) // => [1, 1, 2, 3, 3, 6, 4, 10]
+ * Effect.runSync(Channel.runCollect(asyncMapAccum)) // => ["1-processed", "1", "2-processed", "12", "3-processed", "123", "4-processed", "1234"]
  * ```
  *
  * @category sequencing
@@ -2190,15 +2273,15 @@ export const mapAccum = /*#__PURE__*/dual(args => isChannel(args[0]), (self, ini
  *
  * **Example** (Scanning channel output)
  *
- * ```ts
- * import { Channel } from "effect"
+ * ```ts import.meta.vitest
+ * import { Channel, Effect } from "effect"
  *
  * // Create a channel with numbers
  * const numbersChannel = Channel.fromIterable([1, 2, 3, 4, 5])
  *
  * // Scan to create running sum
  * const runningSumChannel = Channel.scan(numbersChannel, 0, (sum, n) => sum + n)
- * // Outputs: 0, 1, 3, 6, 10, 15
+ * Effect.runSync(Channel.runCollect(runningSumChannel)) // => [0, 1, 3, 6, 10, 15]
  * // Note: emits the initial value and each intermediate result
  *
  * // Scan with string concatenation
@@ -2208,7 +2291,7 @@ export const mapAccum = /*#__PURE__*/dual(args => isChannel(args[0]), (self, ini
  *   "",
  *   (sentence, word) => sentence === "" ? word : `${sentence} ${word}`
  * )
- * // Outputs: "", "hello", "hello world", "hello world from", "hello world from effect"
+ * Effect.runSync(Channel.runCollect(sentenceChannel)) // => ["", "hello", "hello world", "hello world from", "hello world from effect"]
  * ```
  *
  * @category sequencing
@@ -2226,7 +2309,7 @@ export const scan = /*#__PURE__*/dual(3, (self, initial, f) => scanEffect(self,
  *
  * **Example** (Scanning channel output with effects)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Channel, Data, Effect } from "effect"
  *
  * class ScanError extends Data.TaggedError("ScanError")<{
@@ -2242,12 +2325,10 @@ export const scan = /*#__PURE__*/dual(3, (self, initial, f) => scanEffect(self,
  *   "",
  *   (acc, value) =>
  *     Effect.gen(function*() {
- *       // Simulate async work
- *       yield* Effect.sleep("10 millis")
  *       return acc + value.toString()
  *     })
  * )
- * // Outputs: "", "1", "12", "123", "1234"
+ * await Effect.runPromise(Channel.runCollect(asyncScanChannel)) // => ["", "1", "12", "123", "1234"]
  *
  * // Scan with error handling
  * const errorHandlingScan = Channel.scanEffect(
@@ -2260,6 +2341,7 @@ export const scan = /*#__PURE__*/dual(3, (self, initial, f) => scanEffect(self,
  *     return Effect.succeed(sum + n)
  *   }
  * )
+ * await Effect.runPromise(Channel.runCollect(errorHandlingScan)) // => [0, 1, 3, 6, 10]
  * ```
  *
  * @category sequencing
@@ -2285,8 +2367,8 @@ export const scanEffect = /*#__PURE__*/dual(3, (self, initial, f) => fromTransfo
  *
  * **Example** (Recovering from failure causes)
  *
- * ```ts
- * import { Cause, Channel, Data } from "effect"
+ * ```ts import.meta.vitest
+ * import { Cause, Channel, Data, Effect } from "effect"
  *
  * class ProcessError extends Data.TaggedError("ProcessError")<{
  *   readonly reason: string
@@ -2309,7 +2391,7 @@ export const scanEffect = /*#__PURE__*/dual(3, (self, initial, f) => fromTransfo
  *   return Channel.succeed("Recovered from interruption")
  * })
  *
- * // The channel recovers gracefully from errors
+ * Effect.runSync(Channel.runCollect(recoveredChannel)) // => ["Recovered from failure"]
  * ```
  *
  * @category error handling
@@ -2494,8 +2576,8 @@ export const catchTag = /*#__PURE__*/dual(args => isChannel(args[0]), (self, k,
  *
  * **Example** (Recovering from nested reasons)
  *
- * ```ts
- * import { Channel, Data } from "effect"
+ * ```ts import.meta.vitest
+ * import { Channel, Data, Effect } from "effect"
  *
  * class RateLimitError extends Data.TaggedError("RateLimitError")<{
  *   retryAfter: number
@@ -2509,15 +2591,15 @@ export const catchTag = /*#__PURE__*/dual(args => isChannel(args[0]), (self, k,
  *   reason: RateLimitError | QuotaExceededError
  * }> {}
  *
- * const channel = Channel.fail(
- *   new AiError({ reason: new RateLimitError({ retryAfter: 60 }) })
- * )
+ * const reason = new RateLimitError({ retryAfter: 60 })
+ * const channel = Channel.fail(new AiError({ reason }))
  *
  * const recovered = channel.pipe(
  *   Channel.catchReason("AiError", "RateLimitError", (reason) =>
  *     Channel.succeed(`retry: ${reason.retryAfter}`)
  *   )
  * )
+ * Effect.runSync(Channel.runCollect(recovered)) // => ["retry: 60"]
  * ```
  *
  * @category error handling
@@ -2558,8 +2640,8 @@ export const catchReasons = /*#__PURE__*/dual(args => isChannel(args[0]), (self,
  *
  * **Example** (Promoting nested reasons)
  *
- * ```ts
- * import { Channel, Data } from "effect"
+ * ```ts import.meta.vitest
+ * import { Channel, Data, Effect, Exit } from "effect"
  *
  * class RateLimitError extends Data.TaggedError("RateLimitError")<{
  *   retryAfter: number
@@ -2573,11 +2655,11 @@ export const catchReasons = /*#__PURE__*/dual(args => isChannel(args[0]), (self,
  *   reason: RateLimitError | QuotaExceededError
  * }> {}
  *
- * const channel = Channel.fail(
- *   new AiError({ reason: new RateLimitError({ retryAfter: 60 }) })
- * )
+ * const reason = new RateLimitError({ retryAfter: 60 })
+ * const channel = Channel.fail(new AiError({ reason }))
  *
  * const unwrapped = channel.pipe(Channel.unwrapReason("AiError"))
+ * Effect.runSync(Effect.exit(Channel.runCollect(unwrapped))) // => Exit.fail(reason)
  * ```
  *
  * @category error handling
@@ -2599,20 +2681,21 @@ export const mapError = /*#__PURE__*/dual(2, (self, f) => catch_(self, err => fa
  *
  * **Example** (Converting failures to defects)
  *
- * ```ts
- * import { Channel, Data } from "effect"
+ * ```ts import.meta.vitest
+ * import { Cause, Channel, Data, Effect, Exit } from "effect"
  *
  * class ValidationError extends Data.TaggedError("ValidationError")<{
  *   readonly field: string
  * }> {}
  *
  * // Create a channel that might fail
- * const failingChannel = Channel.fail(new ValidationError({ field: "email" }))
+ * const error = new ValidationError({ field: "email" })
+ * const failingChannel = Channel.fail(error)
  *
  * // Convert failures to defects
  * const fatalChannel = Channel.orDie(failingChannel)
  *
- * // Any failure will now become a defect (uncaught exception)
+ * Effect.runSync(Effect.exit(Channel.runCollect(fatalChannel))) // => Exit.failCause(Cause.die(error))
  * ```
  *
  * @category error handling
@@ -2694,8 +2777,8 @@ export const retry = /*#__PURE__*/dual(2, (self, schedule) => suspend(() => {
  *
  * **Example** (Switching mapped channels)
  *
- * ```ts
- * import { Channel, Data } from "effect"
+ * ```ts import.meta.vitest
+ * import { Channel, Data, Effect } from "effect"
  *
  * class SwitchError extends Data.TaggedError("SwitchError")<{
  *   readonly reason: string
@@ -2710,7 +2793,7 @@ export const retry = /*#__PURE__*/dual(2, (self, schedule) => suspend(() => {
  *   (n) => Channel.fromIterable([`value-${n}`])
  * )
  *
- * // Outputs: "value-1", "value-2", "value-3"
+ * await Effect.runPromise(Channel.runCollect(switchedChannel)) // => ["value-3"]
  * ```
  *
  * @category sequencing
@@ -2731,8 +2814,8 @@ export const switchMap = /*#__PURE__*/dual(args => isChannel(args[0]), (self, f,
  *
  * **Example** (Merging nested channels)
  *
- * ```ts
- * import { Channel, Data } from "effect"
+ * ```ts import.meta.vitest
+ * import { Channel, Data, Effect } from "effect"
  *
  * class MergeAllError extends Data.TaggedError("MergeAllError")<{
  *   readonly reason: string
@@ -2747,11 +2830,11 @@ export const switchMap = /*#__PURE__*/dual(args => isChannel(args[0]), (self, f,
  *
  * // Merge all channels with bounded concurrency
  * const mergedChannel = Channel.mergeAll({
- *   concurrency: 2,
+ *   concurrency: 1,
  *   bufferSize: 16
  * })(nestedChannels)
  *
- * // Outputs: 1, 2, 3, 4, 5, 6 (order may vary due to concurrency)
+ * await Effect.runPromise(Channel.runCollect(mergedChannel)) // => [1, 2, 3, 4, 5, 6]
  * ```
  *
  * @category combining
@@ -2819,24 +2902,18 @@ export const mergeAll = /*#__PURE__*/dual(2, (channels, {
  *
  * **Example** (Merging channels)
  *
- * ```ts
- * import { Channel, Data } from "effect"
- *
- * class MergeError extends Data.TaggedError("MergeError")<{
- *   readonly source: string
- * }> {}
+ * ```ts import.meta.vitest
+ * import { Channel, Effect } from "effect"
  *
  * // Create two channels
  * const leftChannel = Channel.fromIterable([1, 2, 3])
  * const rightChannel = Channel.fromIterable(["a", "b", "c"])
  *
- * // Merge them with "either" halt strategy
- * const mergedChannel = Channel.merge(leftChannel, rightChannel, {
- *   haltStrategy: "either"
- * })
+ * // The default "both" strategy waits for both channels to complete
+ * const mergedChannel = Channel.merge(leftChannel, rightChannel)
  *
- * // Outputs elements from both channels concurrently
- * // Order may vary: 1, "a", 2, "b", 3, "c"
+ * const values = await Effect.runPromise(Channel.runCollect(mergedChannel))
+ * values.map(String).sort() // => ["1", "2", "3", "a", "b", "c"]
  * ```
  *
  * @category combining
@@ -2907,19 +2984,16 @@ export const mergeEffect = /*#__PURE__*/dual(2, (self, effect) => merge(self, fr
  *
  * **Example** (Splitting string chunks into lines)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, Stream } from "effect"
  *
- * Effect.runPromise(Effect.gen(function*() {
- *   const result = yield* Stream.runCollect(
- *     Stream.splitLines(Stream.make("hel", "lo\r\nwor", "ld\n"))
- *   )
- *   console.log(result)
- *   // [ 'hello', 'world' ]
- * }))
+ * const result = await Effect.runPromise(Stream.runCollect(
+ *   Stream.splitLines(Stream.make("hel", "lo\r\nwor", "ld\n"))
+ * ))
+ * result // => ["hello", "world"]
  * ```
  *
- * @category String manipulation
+ * @category splitting
  * @since 2.0.0
  */
 export const splitLines = () => fromTransform((upstream, _scope) => Effect.sync(() => {
@@ -3016,7 +3090,7 @@ export const splitLines = () => fromTransform((upstream, _scope) => Effect.sync(
  * span `Uint8Array` boundaries. The optional `encoding` and `options` are
  * passed to `TextDecoder`.
  *
- * @category String manipulation
+ * @category decoding
  * @since 4.0.0
  */
 export const decodeText = (encoding, options) => fromTransform((upstream, _scope) => Effect.sync(() => {
@@ -3033,7 +3107,7 @@ export const decodeText = (encoding, options) => fromTransform((upstream, _scope
  *
  * Each string inside an emitted array is encoded independently.
  *
- * @category String manipulation
+ * @category encoding
  * @since 4.0.0
  */
 export const encodeText = () => fromTransform((upstream, _scope) => Effect.sync(() => {
@@ -3048,8 +3122,8 @@ export const encodeText = () => fromTransform((upstream, _scope) => Effect.sync(
  *
  * **Example** (Piping one channel into another)
  *
- * ```ts
- * import { Channel, Data } from "effect"
+ * ```ts import.meta.vitest
+ * import { Channel, Data, Effect } from "effect"
  *
  * class PipeError extends Data.TaggedError("PipeError")<{
  *   readonly stage: string
@@ -3062,7 +3136,7 @@ export const encodeText = () => fromTransform((upstream, _scope) => Effect.sync(
  * // Pipe the source into the transform
  * const pipedChannel = Channel.pipeTo(sourceChannel, transformChannel)
  *
- * // Outputs: 2, 4, 6
+ * Effect.runSync(Channel.runCollect(pipedChannel)) // => [2, 4, 6]
  * ```
  *
  * @category sequencing
@@ -3076,21 +3150,22 @@ export const pipeTo = /*#__PURE__*/dual(2, (self, that) => fromTransform((upstre
  *
  * **Example** (Piping while preserving failures)
  *
- * ```ts
- * import { Channel, Data } from "effect"
+ * ```ts import.meta.vitest
+ * import { Channel, Data, Effect, Exit } from "effect"
  *
  * class SourceError extends Data.TaggedError("SourceError")<{
  *   readonly code: number
  * }> {}
  *
  * // Create a failing source channel
- * const failingSource = Channel.fail(new SourceError({ code: 404 }))
- * const safeTransform = Channel.succeed("transformed")
+ * const error = new SourceError({ code: 404 })
+ * const failingSource = Channel.fail(error)
+ * const safeTransform = Channel.identity<never, never, never>()
  *
  * // Pipe while preserving source failures
  * const safePipedChannel = Channel.pipeToOrFail(failingSource, safeTransform)
  *
- * // Source errors are preserved and not sent to transform channel
+ * Effect.runSync(Effect.exit(Channel.runCollect(safePipedChannel))) // => Exit.fail(error)
  * ```
  *
  * @category sequencing
@@ -3106,7 +3181,7 @@ export const pipeToOrFail = /*#__PURE__*/dual(2, (self, that) => fromTransform((
  *
  * **Example** (Unwrapping channel effects)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Channel, Data, Effect } from "effect"
  *
  * class UnwrapError extends Data.TaggedError("UnwrapError")<{
@@ -3121,7 +3196,7 @@ export const pipeToOrFail = /*#__PURE__*/dual(2, (self, that) => fromTransform((
  * // Unwrap the effect to get the channel
  * const unwrappedChannel = Channel.unwrap(channelEffect)
  *
- * // The resulting channel outputs: 1, 2, 3
+ * Effect.runSync(Channel.runCollect(unwrappedChannel)) // => [1, 2, 3]
  * ```
  *
  * @category constructors
@@ -3153,7 +3228,7 @@ export const scoped = self => fromTransformBracket((upstream, scope, forkedScope
  *
  * **Example** (Embedding custom input handling)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Channel, Effect } from "effect"
  *
  * // Create a base channel
@@ -3164,13 +3239,11 @@ export const scoped = self => fromTransformBracket((upstream, scope, forkedScope
  *   baseChannel,
  *   (upstream) =>
  *     upstream.pipe(
- *       Effect.tap((message) =>
- *         Effect.sync(() => console.log(message))
- *       ),
  *       Effect.forever,
  *       Effect.ignore
  *     )
  * )
+ * await Effect.runPromise(Channel.runCollect(embeddedChannel)) // => [1, 2, 3]
  * ```
  *
  * @category sequencing
@@ -3199,7 +3272,7 @@ export const embedInput = /*#__PURE__*/dual(2, (self, input) => fromTransformBra
  *
  * @see {@link bufferArray} for buffering elements from array outputs
  *
- * @category Buffering
+ * @category buffering
  * @since 2.0.0
  */
 export const buffer = /*#__PURE__*/dual(2, (self, options) => fromTransform(Effect.fnUntraced(function* (upstream, scope) {
@@ -3238,7 +3311,7 @@ export const buffer = /*#__PURE__*/dual(2, (self, options) => fromTransform(Effe
  *
  * @see {@link buffer} for buffering output elements without flattening arrays
  *
- * @category Buffering
+ * @category buffering
  * @since 4.0.0
  */
 export const bufferArray = /*#__PURE__*/dual(2, (self, options) => fromTransform(Effect.fnUntraced(function* (upstream, scope) {
@@ -3317,8 +3390,8 @@ export const onError = /*#__PURE__*/dual(2, (self, finalizer) => onExit(self, ex
  *
  * **Example** (Running exit finalizers)
  *
- * ```ts
- * import { Channel, Console, Data, Exit } from "effect"
+ * ```ts import.meta.vitest
+ * import { Channel, Data, Effect, Exit } from "effect"
  *
  * class ExitError extends Data.TaggedError("ExitError")<{
  *   readonly stage: string
@@ -3328,13 +3401,12 @@ export const onError = /*#__PURE__*/dual(2, (self, finalizer) => onExit(self, ex
  * const dataChannel = Channel.fromIterable([1, 2, 3])
  *
  * // Attach exit handler
+ * const exits: Array<Exit.Exit<void, ExitError>> = []
  * const channelWithExit = Channel.onExit(dataChannel, (exit) => {
- *   if (Exit.isSuccess(exit)) {
- *     return Console.log(`Channel completed successfully with: ${exit.value}`)
- *   } else {
- *     return Console.log(`Channel failed with: ${exit.cause}`)
- *   }
+ *   exits.push(exit)
+ *   return Effect.void
  * })
+ * const observed = [await Effect.runPromise(Channel.runCollect(channelWithExit)), exits] // => [[1, 2, 3], [Exit.void]]
  * ```
  *
  * @category resource management
@@ -3397,8 +3469,8 @@ export const onEnd = /*#__PURE__*/dual(2, (self, onEnd) => transformPull(self, p
  *
  * **Example** (Ensuring cleanup runs)
  *
- * ```ts
- * import { Channel, Console, Data } from "effect"
+ * ```ts import.meta.vitest
+ * import { Channel, Data, Effect } from "effect"
  *
  * class EnsureError extends Data.TaggedError("EnsureError")<{
  *   readonly operation: string
@@ -3408,10 +3480,12 @@ export const onEnd = /*#__PURE__*/dual(2, (self, onEnd) => transformPull(self, p
  * const dataChannel = Channel.fromIterable([1, 2, 3])
  *
  * // Ensure cleanup always runs
+ * const events: Array<string> = []
  * const channelWithCleanup = Channel.ensuring(
  *   dataChannel,
- *   Console.log("Cleanup executed regardless of success or failure")
+ *   Effect.sync(() => events.push("cleanup"))
  * )
+ * const observed = [await Effect.runPromise(Channel.runCollect(channelWithCleanup)), events] // => [[1, 2, 3], ["cleanup"]]
  * ```
  *
  * @category resource management
@@ -3426,7 +3500,7 @@ const runWith = (self, f, onHalt) => Effect.suspend(() => {
 /**
  * Creates a channel from the specified services.
  *
- * @category services
+ * @category accessors
  * @since 2.0.0
  */
 export const contextWith = f => fromTransform((upstream, scope) => Effect.contextWith(context => toTransform(f(context))(upstream, scope)));
@@ -3434,7 +3508,7 @@ export const contextWith = f => fromTransform((upstream, scope) => Effect.contex
  * Provides a `Context` to the channel, removing the corresponding service
  * requirements from the returned channel.
  *
- * @category services
+ * @category providing 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))));
@@ -3442,7 +3516,7 @@ export const provideContext = /*#__PURE__*/dual(2, (self, context) => fromTransf
  * Provides a concrete service for a context key, removing that service
  * requirement from the returned channel.
  *
- * @category services
+ * @category providing 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))));
@@ -3459,7 +3533,7 @@ export const provideService = /*#__PURE__*/dual(3, (self, key, service) => fromT
  * If the service effect fails, the returned channel fails. The provided service
  * removes the corresponding service requirement from the returned channel.
  *
- * @category services
+ * @category providing services
  * @since 4.0.0
  */
 export const provideServiceEffect = /*#__PURE__*/dual(3, (self, key, service) => fromTransform((upstream, scope) => Effect.flatMap(service, s => toTransform(provideService(self, key, s))(upstream, scope))));
@@ -3473,7 +3547,7 @@ export const provideServiceEffect = /*#__PURE__*/dual(3, (self, key, service) =>
  * builds the layer in the channel scope. Use `options.local` to build a fresh
  * layer instance for this provision.
  *
- * @category services
+ * @category providing services
  * @since 4.0.0
  */
 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)))));
@@ -3486,7 +3560,7 @@ export const provide = /*#__PURE__*/dual(args => isChannel(args[0]), (self, laye
  * provide to the channel. The returned channel requires the services needed to
  * build that context.
  *
- * @category services
+ * @category providing services
  * @since 4.0.0
  */
 export const updateContext = /*#__PURE__*/dual(2, (self, f) => fromTransform((upstream, scope) => Effect.contextWith(context => {
@@ -3501,7 +3575,7 @@ export const updateContext = /*#__PURE__*/dual(2, (self, f) => fromTransform((up
  * The existing service is read from the context. The updated service is
  * provided to the channel under the same key.
  *
- * @category services
+ * @category providing services
  * @since 2.0.0
  */
 export const updateService = /*#__PURE__*/dual(3, (self, service, f) => updateContext(self, context => Context.add(context, service, f(Context.get(context, service)))));
@@ -3534,7 +3608,7 @@ const withSpanImpl = (self, name, options) => acquireUseRelease(Effect.makeSpan(
 /**
  * The starting channel for Do notation, emitting an empty object.
  *
- * @category do notation
+ * @category constructors
  * @since 4.0.0
  */
 export const Do = /*#__PURE__*/succeed({});
@@ -3546,7 +3620,7 @@ export {
 /**
  * Adds a computed field to each object emitted by a channel.
  *
- * @category do notation
+ * @category mapping
  * @since 4.0.0
  */
 let_ as let };
@@ -3560,7 +3634,7 @@ let_ as let };
  * channel's output becomes the value of the new field. `options.concurrency`
  * and `options.bufferSize` control how derived channels are flattened.
  *
- * @category do notation
+ * @category sequencing
  * @since 4.0.0
  */
 export const bind = /*#__PURE__*/dual(args => isChannel(args[0]), (self, name, f, options) => flatMap(self, elem => map(f(elem), b => ({
@@ -3579,7 +3653,7 @@ export const bind = /*#__PURE__*/dual(args => isChannel(args[0]), (self, name, f
  * @see {@link bind} for adding a field produced by another channel
  * @see {@link let_ let} for adding a computed field
  *
- * @category do notation
+ * @category mapping
  * @since 4.0.0
  */
 export const bindTo = /*#__PURE__*/dual(2, (self, name) => map(self, elem => ({
@@ -3590,8 +3664,8 @@ export const bindTo = /*#__PURE__*/dual(2, (self, name) => map(self, elem => ({
  *
  * **Example** (Counting channel output)
  *
- * ```ts
- * import { Channel, Data } from "effect"
+ * ```ts import.meta.vitest
+ * import { Channel, Data, Effect } from "effect"
  *
  * class CountError extends Data.TaggedError("CountError")<{
  *   readonly reason: string
@@ -3603,10 +3677,10 @@ export const bindTo = /*#__PURE__*/dual(2, (self, name) => map(self, elem => ({
  * // Count the elements
  * const countEffect = Channel.runCount(numbersChannel)
  *
- * // Effect.runSync(countEffect) // Returns: 5
+ * Effect.runSync(countEffect) // => 5
  * ```
  *
- * @category execution
+ * @category running
  * @since 4.0.0
  */
 export const runCount = self => runFold(self, () => 0, acc => acc + 1);
@@ -3615,8 +3689,8 @@ export const runCount = self => runFold(self, () => 0, acc => acc + 1);
  *
  * **Example** (Draining channel output at runtime)
  *
- * ```ts
- * import { Channel, Data } from "effect"
+ * ```ts import.meta.vitest
+ * import { Channel, Data, Effect } from "effect"
  *
  * class DrainError extends Data.TaggedError("DrainError")<{
  *   readonly stage: string
@@ -3624,18 +3698,15 @@ export const runCount = self => runFold(self, () => 0, acc => acc + 1);
  *
  * // Create a channel that outputs elements and completes with a result
  * const resultChannel = Channel.fromIterable([1, 2, 3])
- * const completedChannel = Channel.concatWith(
- *   resultChannel,
- *   () => Channel.succeed("completed")
- * )
+ * const completedChannel = Channel.concat(resultChannel, Channel.end("completed"))
  *
  * // Drain all elements and get only the final result
  * const drainEffect = Channel.runDrain(completedChannel)
  *
- * // Effect.runSync(drainEffect) // Returns: "completed"
+ * Effect.runSync(drainEffect) // => "completed"
  * ```
  *
- * @category execution
+ * @category running
  * @since 2.0.0
  */
 export const runDrain = self => runWith(self, pull => Effect.forever(pull, {
@@ -3646,8 +3717,8 @@ export const runDrain = self => runWith(self, pull => Effect.forever(pull, {
  *
  * **Example** (Running effects for each output)
  *
- * ```ts
- * import { Channel, Console, Data } from "effect"
+ * ```ts import.meta.vitest
+ * import { Channel, Data, Effect } from "effect"
  *
  * class ForEachError extends Data.TaggedError("ForEachError")<{
  *   readonly element: unknown
@@ -3656,16 +3727,18 @@ export const runDrain = self => runWith(self, pull => Effect.forever(pull, {
  * // Create a channel with numbers
  * const numbersChannel = Channel.fromIterable([1, 2, 3])
  *
- * // Run forEach to log each element
+ * // Run forEach to process each element
+ * const processed: Array<number> = []
  * const forEachEffect = Channel.runForEach(
  *   numbersChannel,
- *   (n) => Console.log(`Processing: ${n}`)
+ *   (n) => Effect.sync(() => processed.push(n))
  * )
  *
- * // Logs: "Processing: 1", "Processing: 2", "Processing: 3"
+ * await Effect.runPromise(forEachEffect)
+ * processed // => [1, 2, 3]
  * ```
  *
- * @category execution
+ * @category running
  * @since 4.0.0
  */
 export const runForEach = /*#__PURE__*/dual(2, (self, f) => runWith(self, pull => Effect.forever(Effect.flatMap(pull, f), {
@@ -3680,7 +3753,7 @@ export const runForEach = /*#__PURE__*/dual(2, (self, f) => runWith(self, pull =
  * Returning `true` continues consuming the channel. Returning `false` stops
  * consumption early. The returned effect completes with `void`.
  *
- * @category execution
+ * @category running
  * @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({
@@ -3691,8 +3764,8 @@ export const runForEachWhile = /*#__PURE__*/dual(2, (self, f) => runWith(self, p
  *
  * **Example** (Collecting channel output)
  *
- * ```ts
- * import { Channel, Data } from "effect"
+ * ```ts import.meta.vitest
+ * import { Channel, Data, Effect } from "effect"
  *
  * class CollectError extends Data.TaggedError("CollectError")<{
  *   readonly reason: string
@@ -3704,10 +3777,10 @@ export const runForEachWhile = /*#__PURE__*/dual(2, (self, f) => runWith(self, p
  * // Collect all elements into an array
  * const collectEffect = Channel.runCollect(numbersChannel)
  *
- * // Effect.runSync(collectEffect) // Returns: [1, 2, 3, 4, 5]
+ * Effect.runSync(collectEffect) // => [1, 2, 3, 4, 5]
  * ```
  *
- * @category execution
+ * @category running
  * @since 2.0.0
  */
 export const runCollect = self => runFold(self, () => [], (acc, o) => {
@@ -3717,7 +3790,7 @@ export const runCollect = self => runFold(self, () => [], (acc, o) => {
 /**
  * Runs a channel and outputs the done value.
  *
- * @category execution
+ * @category running
  * @since 4.0.0
  */
 export const runDone = self => runWith(self, identity_, Effect.succeed);
@@ -3730,7 +3803,7 @@ export const runDone = self => runWith(self, identity_, Effect.succeed);
  * Returns `Option.some` with the first output element, or `Option.none` if the
  * channel completes without emitting output.
  *
- * @category execution
+ * @category running
  * @since 4.0.0
  */
 export const runHead = self => Effect.suspend(() => {
@@ -3749,7 +3822,7 @@ export const runHead = self => Effect.suspend(() => {
  * Returns `Option.some` with the last emitted element, or `Option.none` if the
  * channel completes without emitting output.
  *
- * @category execution
+ * @category running
  * @since 4.0.0
  */
 export const runLast = self => Effect.suspend(() => {
@@ -3767,8 +3840,8 @@ export const runLast = self => Effect.suspend(() => {
  *
  * **Example** (Folding channel output)
  *
- * ```ts
- * import { Channel, Data } from "effect"
+ * ```ts import.meta.vitest
+ * import { Channel, Data, Effect } from "effect"
  *
  * class FoldError extends Data.TaggedError("FoldError")<{
  *   readonly operation: string
@@ -3780,10 +3853,10 @@ export const runLast = self => Effect.suspend(() => {
  * // Fold to calculate sum
  * const sumEffect = Channel.runFold(numbersChannel, () => 0, (acc, n) => acc + n)
  *
- * // Effect.runSync(sumEffect) // Returns: 15
+ * Effect.runSync(sumEffect) // => 15
  * ```
  *
- * @category execution
+ * @category running
  * @since 4.0.0
  */
 export const runFold = /*#__PURE__*/dual(3, (self, initial, f) => Effect.suspend(() => {
@@ -3810,7 +3883,7 @@ export const runFold = /*#__PURE__*/dual(3, (self, initial, f) => Effect.suspend
  * the effectful accumulator function. The returned effect succeeds with the
  * final accumulator value.
  *
- * @category execution
+ * @category running
  * @since 4.0.0
  */
 export const runFoldEffect = /*#__PURE__*/dual(3, (self, initial, f) => Effect.suspend(() => {
@@ -3834,7 +3907,7 @@ export const runFoldEffect = /*#__PURE__*/dual(3, (self, initial, f) => Effect.s
  *
  * **Example** (Converting channels to pulls)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Channel, Data, Effect } from "effect"
  *
  * class PullError extends Data.TaggedError("PullError")<{
@@ -3844,12 +3917,11 @@ export const runFoldEffect = /*#__PURE__*/dual(3, (self, initial, f) => Effect.s
  * // Create a channel
  * const numbersChannel = Channel.fromIterable([1, 2, 3])
  *
- * // Convert to Pull within a scope
- * const pullEffect = Effect.scoped(
- *   Channel.toPull(numbersChannel)
- * )
- *
- * // Use the Pull to manually consume elements
+ * const program = Effect.scoped(Effect.gen(function*() {
+ *   const pull = yield* Channel.toPull(numbersChannel)
+ *   return [yield* pull, yield* pull, yield* pull]
+ * }))
+ * await Effect.runPromise(program) // => [1, 2, 3]
  * ```
  *
  * @category destructors
@@ -3870,7 +3942,7 @@ Effect.catchCause(cause => Effect.succeed(Effect.failCause(cause))));
  *
  * **Example** (Converting channels to scoped pulls)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Channel, Data, Effect, Scope } from "effect"
  *
  * class ScopedPullError extends Data.TaggedError("ScopedPullError")<{
@@ -3882,10 +3954,11 @@ Effect.catchCause(cause => Effect.succeed(Effect.failCause(cause))));
  *
  * // Convert to Pull with explicit scope
  * const scopedPullEffect = Effect.gen(function*() {
- *   const scope = yield* Scope.make()
+ *   const scope = yield* Effect.scope
  *   const pull = yield* Channel.toPullScoped(numbersChannel, scope)
- *   return pull
+ *   return [yield* pull, yield* pull, yield* pull]
  * })
+ * await Effect.runPromise(Effect.scoped(scopedPullEffect)) // => [1, 2, 3]
  * ```
  *
  * @category destructors
@@ -3945,8 +4018,8 @@ export const runIntoQueueArray = /*#__PURE__*/dual(args => isChannel(args[0]), (
  *
  * **Example** (Converting channels to queues)
  *
- * ```ts
- * import { Channel, Data } from "effect"
+ * ```ts import.meta.vitest
+ * import { Channel, Data, Effect, Queue } from "effect"
  *
  * class QueueError extends Data.TaggedError("QueueError")<{
  *   readonly operation: string
@@ -3956,10 +4029,11 @@ export const runIntoQueueArray = /*#__PURE__*/dual(args => isChannel(args[0]), (
  * const dataChannel = Channel.fromIterable([1, 2, 3, 4, 5])
  *
  * // Convert to queue for concurrent processing
- * const queueEffect = Channel.toQueue(dataChannel, { capacity: 32 })
- *
- * // The queue can be used for concurrent consumption
- * // Multiple consumers can read from the queue
+ * const program = Effect.scoped(Effect.gen(function*() {
+ *   const queue = yield* Channel.toQueue(dataChannel, { capacity: 32 })
+ *   return yield* Queue.takeBetween(queue, 5, 5)
+ * }))
+ * await Effect.runPromise(program) // => [1, 2, 3, 4, 5]
  * ```
  *
  * @category destructors