effect 4.0.0-beta.102 → 4.0.0-beta.104

package/src/TxQueue.ts

@@ -36,19 +36,11 @@ import type * as Types from "./Types.ts"
  *
  * **Example** (Inspecting queue lifecycle states)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import type { TxQueue } from "effect"
  *
- * // State progression example
- * declare const state: TxQueue.State<string, Error>
- *
- * if (state._tag === "Open") {
- *   console.log("Queue is accepting new items")
- * } else if (state._tag === "Closing") {
- *   console.log("Queue is draining, cause:", state.cause)
- * } else {
- *   console.log("Queue is done, cause:", state.cause)
- * }
+ * const state: TxQueue.State<string, Error> = { _tag: "Open" }
+ * state._tag // => "Open"
  * ```
  *
  * @category models
@@ -146,7 +138,7 @@ export interface TxQueueState extends Inspectable {
  *
  * **Example** (Offering values through enqueue handles)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, TxQueue } from "effect"
  * import type { Cause } from "effect"
  *
@@ -167,7 +159,11 @@ export interface TxQueueState extends Inspectable {
  *   >(5)
  *   yield* TxQueue.offer(completableQueue, "task")
  *   yield* TxQueue.end(completableQueue)
+ *
+ *   return accepted
  * })
+ *
+ * await Effect.runPromise(program) // => true
  * ```
  *
  * @category models
@@ -183,7 +179,7 @@ export interface TxEnqueue<in A, in E = never> extends TxQueueState {
  *
  * **Example** (Taking values through dequeue handles)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, TxQueue } from "effect"
  *
  * const program = Effect.gen(function*() {
@@ -191,7 +187,6 @@ export interface TxEnqueue<in A, in E = never> extends TxQueueState {
  *   const queue = yield* TxQueue.bounded<number>(10)
  *   yield* TxQueue.offer(queue, 42)
  *   const item = yield* TxQueue.take(queue)
- *   console.log(item) // 42
  *
  *   // Queue with error channel - errors propagate through E-channel
  *   const faultTolerantQueue = yield* TxQueue.bounded<number, string>(10)
@@ -200,7 +195,10 @@ export interface TxEnqueue<in A, in E = never> extends TxQueueState {
  *   // All dequeue operations now fail with the error directly
  *   const takeResult = yield* Effect.flip(TxQueue.take(faultTolerantQueue)) // "processing failed"
  *   const peekResult = yield* Effect.flip(TxQueue.peek(faultTolerantQueue)) // "processing failed"
+ *   return [item, takeResult, peekResult] as const
  * })
+ *
+ * await Effect.runPromise(program) // => [42, "processing failed", "processing failed"]
  * ```
  *
  * @category models
@@ -216,7 +214,7 @@ export interface TxDequeue<out A, out E = never> extends TxQueueState {
  *
  * **Example** (Combining enqueue and dequeue operations)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, TxQueue } from "effect"
  *
  * const program = Effect.gen(function*() {
@@ -226,7 +224,6 @@ export interface TxDequeue<out A, out E = never> extends TxQueueState {
  *   // Single operations - automatically transactional
  *   const accepted = yield* TxQueue.offer(queue, 42)
  *   const item = yield* TxQueue.take(queue) // Effect<number, never>
- *   console.log(item) // 42
  *
  *   // Queue with error channel
  *   const faultTolerantQueue = yield* TxQueue.bounded<number, string>(10)
@@ -234,8 +231,10 @@ export interface TxDequeue<out A, out E = never> extends TxQueueState {
  *   // Operations can handle queue-level failures
  *   yield* TxQueue.fail(faultTolerantQueue, "queue failed")
  *   const result = yield* Effect.flip(TxQueue.take(faultTolerantQueue))
- *   console.log(result) // "queue failed"
+ *   return [accepted, item, result] as const
  * })
+ *
+ * await Effect.runPromise(program) // => [true, 42, "queue failed"]
  * ```
  *
  * @category models
@@ -250,15 +249,11 @@ export interface TxQueue<in out A, in out E = never> extends TxEnqueue<A, E>, Tx
  *
  * **Example** (Checking enqueue handles)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { TxQueue } from "effect"
  *
- * declare const someValue: unknown
- *
- * if (TxQueue.isTxEnqueue(someValue)) {
- *   // someValue is now typed as TxEnqueue<unknown, unknown>
- *   console.log("This is a TxEnqueue")
- * }
+ * const someValue: unknown = {}
+ * TxQueue.isTxEnqueue(someValue) // => false
  * ```
  *
  * @category guards
@@ -271,15 +266,11 @@ export const isTxEnqueue = <A = unknown, E = unknown>(u: unknown): u is TxEnqueu
  *
  * **Example** (Checking dequeue handles)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { TxQueue } from "effect"
  *
- * declare const someValue: unknown
- *
- * if (TxQueue.isTxDequeue(someValue)) {
- *   // someValue is now typed as TxDequeue<unknown, unknown>
- *   console.log("This is a TxDequeue")
- * }
+ * const someValue: unknown = {}
+ * TxQueue.isTxDequeue(someValue) // => false
  * ```
  *
  * @category guards
@@ -292,15 +283,11 @@ export const isTxDequeue = <A = unknown, E = unknown>(u: unknown): u is TxDequeu
  *
  * **Example** (Checking queue handles)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { TxQueue } from "effect"
  *
- * declare const someValue: unknown
- *
- * if (TxQueue.isTxQueue(someValue)) {
- *   // someValue is now typed as TxQueue<unknown, unknown>
- *   console.log("This is a TxQueue")
- * }
+ * const someValue: unknown = {}
+ * TxQueue.isTxQueue(someValue) // => false
  * ```
  *
  * @category guards
@@ -344,7 +331,7 @@ const TxQueueProto = {
  *
  * **Example** (Creating bounded queues)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, TxQueue } from "effect"
  *
  * const program = Effect.gen(function*() {
@@ -358,9 +345,10 @@ const TxQueueProto = {
  *   yield* TxQueue.offer(queue, 1)
  *   yield* TxQueue.offer(queue, 2)
  *
- *   const item = yield* TxQueue.take(queue)
- *   console.log(item) // 1
+ *   return yield* TxQueue.take(queue)
  * })
+ *
+ * await Effect.runPromise(program) // => 1
  * ```
  *
  * @category constructors
@@ -390,7 +378,7 @@ export const bounded = <A = never, E = never>(
  *
  * **Example** (Creating unbounded queues)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, TxQueue } from "effect"
  *
  * const program = Effect.gen(function*() {
@@ -404,9 +392,10 @@ export const bounded = <A = never, E = never>(
  *   yield* TxQueue.offer(queue, "hello")
  *   yield* TxQueue.offer(queue, "world")
  *
- *   const size = yield* TxQueue.size(queue)
- *   console.log(size) // 2
+ *   return yield* TxQueue.size(queue)
  * })
+ *
+ * await Effect.runPromise(program) // => 2
  * ```
  *
  * @category constructors
@@ -434,7 +423,7 @@ export const unbounded = <A = never, E = never>(): Effect.Effect<TxQueue<A, E>>
  *
  * **Example** (Creating dropping queues)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, TxQueue } from "effect"
  *
  * const program = Effect.gen(function*() {
@@ -446,9 +435,10 @@ export const unbounded = <A = never, E = never>(): Effect.Effect<TxQueue<A, E>>
  *   yield* TxQueue.offer(queue, 2)
  *
  *   // This will be dropped (returns false)
- *   const accepted = yield* TxQueue.offer(queue, 3)
- *   console.log(accepted) // false
+ *   return yield* TxQueue.offer(queue, 3)
  * })
+ *
+ * await Effect.runPromise(program) // => false
  * ```
  *
  * @category constructors
@@ -478,7 +468,7 @@ export const dropping = <A = never, E = never>(
  *
  * **Example** (Creating sliding queues)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, TxQueue } from "effect"
  *
  * const program = Effect.gen(function*() {
@@ -492,9 +482,10 @@ export const dropping = <A = never, E = never>(
  *   // This will evict item 1 and add 3
  *   yield* TxQueue.offer(queue, 3)
  *
- *   const item = yield* TxQueue.take(queue)
- *   console.log(item) // 2 (item 1 was evicted)
+ *   return yield* TxQueue.take(queue)
  * })
+ *
+ * await Effect.runPromise(program) // => 2
  * ```
  *
  * @category constructors
@@ -528,16 +519,17 @@ export const sliding = <A = never, E = never>(
  *
  * **Example** (Offering a value)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, TxQueue } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const queue = yield* TxQueue.bounded<number>(10)
  *
  *   // Offer an item - returns true if accepted
- *   const accepted = yield* TxQueue.offer(queue, 42)
- *   console.log(accepted) // true
+ *   return yield* TxQueue.offer(queue, 42)
  * })
+ *
+ * await Effect.runPromise(program) // => true
  * ```
  *
  * @category combinators
@@ -557,16 +549,17 @@ export const offer: {
    *
    * **Example** (Offering a value)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Effect, TxQueue } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const queue = yield* TxQueue.bounded<number>(10)
    *
    *   // Offer an item - returns true if accepted
-   *   const accepted = yield* TxQueue.offer(queue, 42)
-   *   console.log(accepted) // true
+   *   return yield* TxQueue.offer(queue, 42)
    * })
+   *
+   * await Effect.runPromise(program) // => true
    * ```
    *
    * @category combinators
@@ -586,16 +579,17 @@ export const offer: {
    *
    * **Example** (Offering a value)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Effect, TxQueue } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const queue = yield* TxQueue.bounded<number>(10)
    *
    *   // Offer an item - returns true if accepted
-   *   const accepted = yield* TxQueue.offer(queue, 42)
-   *   console.log(accepted) // true
+   *   return yield* TxQueue.offer(queue, 42)
    * })
+   *
+   * await Effect.runPromise(program) // => true
    * ```
    *
    * @category combinators
@@ -651,17 +645,17 @@ export const offer: {
  *
  * **Example** (Offering multiple values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, TxQueue } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const queue = yield* TxQueue.bounded<number>(10)
  *
  *   // Offer multiple items - returns rejected items as array
- *   const rejected = yield* TxQueue.offerAll(queue, [1, 2, 3, 4, 5])
- *   console.log(rejected) // [] if all accepted
- *   console.log(rejected.length) // 0
+ *   return yield* TxQueue.offerAll(queue, [1, 2, 3, 4, 5])
  * })
+ *
+ * await Effect.runPromise(program) // => []
  * ```
  *
  * @category combinators
@@ -678,17 +672,17 @@ export const offerAll: {
    *
    * **Example** (Offering multiple values)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Effect, TxQueue } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const queue = yield* TxQueue.bounded<number>(10)
    *
    *   // Offer multiple items - returns rejected items as array
-   *   const rejected = yield* TxQueue.offerAll(queue, [1, 2, 3, 4, 5])
-   *   console.log(rejected) // [] if all accepted
-   *   console.log(rejected.length) // 0
+   *   return yield* TxQueue.offerAll(queue, [1, 2, 3, 4, 5])
    * })
+   *
+   * await Effect.runPromise(program) // => []
    * ```
    *
    * @category combinators
@@ -705,17 +699,17 @@ export const offerAll: {
    *
    * **Example** (Offering multiple values)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Effect, TxQueue } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const queue = yield* TxQueue.bounded<number>(10)
    *
    *   // Offer multiple items - returns rejected items as array
-   *   const rejected = yield* TxQueue.offerAll(queue, [1, 2, 3, 4, 5])
-   *   console.log(rejected) // [] if all accepted
-   *   console.log(rejected.length) // 0
+   *   return yield* TxQueue.offerAll(queue, [1, 2, 3, 4, 5])
    * })
+   *
+   * await Effect.runPromise(program) // => []
    * ```
    *
    * @category combinators
@@ -724,11 +718,13 @@ export const offerAll: {
   <A, E>(self: TxEnqueue<A, E>, values: Iterable<A>): Effect.Effect<Array<A>>
 } = dual(
   2,
-  <A, E>(self: TxEnqueue<A, E>, values: Iterable<A>): Effect.Effect<Array<A>> =>
-    Effect.gen(function*() {
+  <A, E>(self: TxEnqueue<A, E>, values: Iterable<A>): Effect.Effect<Array<A>> => {
+    const valuesArray = Array.from(values)
+
+    return Effect.gen(function*() {
       const rejected: Array<A> = []
 
-      for (const value of values) {
+      for (const value of valuesArray) {
         const accepted = yield* offer(self, value)
         if (!accepted) {
           rejected.push(value)
@@ -737,6 +733,7 @@ export const offerAll: {
 
       return rejected
     }).pipe(Effect.tx)
+  }
 )
 
 /**
@@ -749,8 +746,8 @@ export const offerAll: {
  *
  * **Example** (Taking a value)
  *
- * ```ts
- * import { Effect, TxQueue } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Exit, TxQueue } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const queue = yield* TxQueue.bounded<number, string>(10)
@@ -758,13 +755,14 @@ export const offerAll: {
  *
  *   // Take an item - blocks if empty
  *   const item = yield* TxQueue.take(queue)
- *   console.log(item) // 42
  *
  *   // When queue fails, take fails with the same error
  *   yield* TxQueue.fail(queue, "queue error")
- *   const result = yield* Effect.flip(TxQueue.take(queue))
- *   console.log(result) // "queue error"
+ *   const result = yield* Effect.exit(TxQueue.take(queue))
+ *   return [item, result] as const
  * })
+ *
+ * await Effect.runPromise(program) // => [42, Exit.fail("queue error")]
  * ```
  *
  * @category combinators
@@ -806,7 +804,7 @@ export const take = <A, E>(self: TxDequeue<A, E>): Effect.Effect<A, E> =>
  *
  * **Example** (Polling without blocking)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, Option, TxQueue } from "effect"
  *
  * const program = Effect.gen(function*() {
@@ -814,12 +812,13 @@ export const take = <A, E>(self: TxDequeue<A, E>): Effect.Effect<A, E> =>
  *
  *   // Poll returns Option.none if empty
  *   const maybe = yield* TxQueue.poll(queue)
- *   console.log(Option.isNone(maybe)) // true
  *
  *   yield* TxQueue.offer(queue, 42)
  *   const item = yield* TxQueue.poll(queue)
- *   console.log(Option.getOrNull(item)) // 42
+ *   return [maybe, item] as const
  * })
+ *
+ * await Effect.runPromise(program) // => [Option.none(), Option.some(42)]
  * ```
  *
  * @category combinators
@@ -839,6 +838,11 @@ export const poll = <A, E>(self: TxDequeue<A, E>): Effect.Effect<Option.Option<A
     }
 
     yield* TxChunk.drop(self.items, 1)
+
+    if (state._tag === "Closing" && (yield* isEmpty(self))) {
+      yield* TxRef.set(self.stateRef, { _tag: "Done", cause: state.cause })
+    }
+
     return Option.some(head.value)
   }).pipe(Effect.tx)
 
@@ -851,17 +855,15 @@ export const poll = <A, E>(self: TxDequeue<A, E>): Effect.Effect<Option.Option<A
  *
  * **Example** (Taking all queued values)
  *
- * ```ts
- * import { Array, Effect, TxQueue } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Exit, TxQueue } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const queue = yield* TxQueue.bounded<number, string>(10)
  *   yield* TxQueue.offerAll(queue, [1, 2, 3, 4, 5])
  *
  *   // Take all items atomically - returns NonEmptyArray
- *   const items = yield* TxQueue.takeAll(queue)
- *   console.log(items) // [1, 2, 3, 4, 5]
- *   console.log(Array.isArrayNonEmpty(items)) // true
+ *   return yield* TxQueue.takeAll(queue)
  * })
  *
  * // Error propagation example
@@ -871,9 +873,11 @@ export const poll = <A, E>(self: TxDequeue<A, E>): Effect.Effect<Option.Option<A
  *   yield* TxQueue.fail(queue, "processing error")
  *
  *   // takeAll() propagates the queue error through E-channel
- *   const result = yield* Effect.flip(TxQueue.takeAll(queue))
- *   console.log(result) // "processing error"
+ *   return yield* Effect.exit(TxQueue.takeAll(queue))
  * })
+ *
+ * await Effect.runPromise(program) // => [1, 2, 3, 4, 5]
+ * await Effect.runPromise(errorExample) // => Exit.fail("processing error")
  * ```
  *
  * @category combinators
@@ -916,7 +920,7 @@ export const takeAll = <A, E>(self: TxDequeue<A, E>): Effect.Effect<Arr.NonEmpty
  *
  * **Example** (Taking a fixed number of values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, TxQueue } from "effect"
  *
  * const program = Effect.gen(function*() {
@@ -924,13 +928,14 @@ export const takeAll = <A, E>(self: TxDequeue<A, E>): Effect.Effect<Arr.NonEmpty
  *   yield* TxQueue.offerAll(queue, [1, 2, 3, 4])
  *
  *   const items = yield* TxQueue.takeN(queue, 4)
- *   console.log(items) // [1, 2, 3, 4]
  *
  *   // This requests more than capacity (5), so takes all available (up to 5)
  *   yield* TxQueue.offerAll(queue, [5, 6, 7, 8, 9])
  *   const all = yield* TxQueue.takeN(queue, 10)
- *   console.log(all) // [5, 6, 7, 8, 9]
+ *   return [items, all] as const
  * })
+ *
+ * await Effect.runPromise(program) // => [[1, 2, 3, 4], [5, 6, 7, 8, 9]]
  * ```
  *
  * @category combinators
@@ -946,7 +951,7 @@ export const takeN: {
    *
    * **Example** (Taking a fixed number of values)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Effect, TxQueue } from "effect"
    *
    * const program = Effect.gen(function*() {
@@ -954,13 +959,14 @@ export const takeN: {
    *   yield* TxQueue.offerAll(queue, [1, 2, 3, 4])
    *
    *   const items = yield* TxQueue.takeN(queue, 4)
-   *   console.log(items) // [1, 2, 3, 4]
    *
    *   // This requests more than capacity (5), so takes all available (up to 5)
    *   yield* TxQueue.offerAll(queue, [5, 6, 7, 8, 9])
    *   const all = yield* TxQueue.takeN(queue, 10)
-   *   console.log(all) // [5, 6, 7, 8, 9]
+   *   return [items, all] as const
    * })
+   *
+   * await Effect.runPromise(program) // => [[1, 2, 3, 4], [5, 6, 7, 8, 9]]
    * ```
    *
    * @category combinators
@@ -976,7 +982,7 @@ export const takeN: {
    *
    * **Example** (Taking a fixed number of values)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Effect, TxQueue } from "effect"
    *
    * const program = Effect.gen(function*() {
@@ -984,13 +990,14 @@ export const takeN: {
    *   yield* TxQueue.offerAll(queue, [1, 2, 3, 4])
    *
    *   const items = yield* TxQueue.takeN(queue, 4)
-   *   console.log(items) // [1, 2, 3, 4]
    *
    *   // This requests more than capacity (5), so takes all available (up to 5)
    *   yield* TxQueue.offerAll(queue, [5, 6, 7, 8, 9])
    *   const all = yield* TxQueue.takeN(queue, 10)
-   *   console.log(all) // [5, 6, 7, 8, 9]
+   *   return [items, all] as const
    * })
+   *
+   * await Effect.runPromise(program) // => [[1, 2, 3, 4], [5, 6, 7, 8, 9]]
    * ```
    *
    * @category combinators
@@ -1064,7 +1071,7 @@ export const takeN: {
  *
  * **Example** (Taking batches within bounds)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, TxQueue } from "effect"
  *
  * const program = Effect.gen(function*() {
@@ -1073,15 +1080,16 @@ export const takeN: {
  *
  *   // Take between 2 and 5 items
  *   const batch1 = yield* TxQueue.takeBetween(queue, 2, 5)
- *   console.log(batch1) // [1, 2, 3, 4, 5] - took 5 (up to max)
  *
  *   // Take between 1 and 10 items (but only 3 remain)
  *   const batch2 = yield* TxQueue.takeBetween(queue, 1, 10)
- *   console.log(batch2) // [6, 7, 8] - took 3 (all remaining)
  *
  *   // Would wait for at least 1 item to be available
  *   // const batch3 = yield* TxQueue.takeBetween(queue, 1, 3)
+ *   return [batch1, batch2] as const
  * })
+ *
+ * await Effect.runPromise(program) // => [[1, 2, 3, 4, 5], [6, 7, 8]]
  * ```
  *
  * @category taking
@@ -1098,7 +1106,7 @@ export const takeBetween: {
    *
    * **Example** (Taking batches within bounds)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Effect, TxQueue } from "effect"
    *
    * const program = Effect.gen(function*() {
@@ -1107,15 +1115,16 @@ export const takeBetween: {
    *
    *   // Take between 2 and 5 items
    *   const batch1 = yield* TxQueue.takeBetween(queue, 2, 5)
-   *   console.log(batch1) // [1, 2, 3, 4, 5] - took 5 (up to max)
    *
    *   // Take between 1 and 10 items (but only 3 remain)
    *   const batch2 = yield* TxQueue.takeBetween(queue, 1, 10)
-   *   console.log(batch2) // [6, 7, 8] - took 3 (all remaining)
    *
    *   // Would wait for at least 1 item to be available
    *   // const batch3 = yield* TxQueue.takeBetween(queue, 1, 3)
+   *   return [batch1, batch2] as const
    * })
+   *
+   * await Effect.runPromise(program) // => [[1, 2, 3, 4, 5], [6, 7, 8]]
    * ```
    *
    * @category taking
@@ -1132,7 +1141,7 @@ export const takeBetween: {
    *
    * **Example** (Taking batches within bounds)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Effect, TxQueue } from "effect"
    *
    * const program = Effect.gen(function*() {
@@ -1141,15 +1150,16 @@ export const takeBetween: {
    *
    *   // Take between 2 and 5 items
    *   const batch1 = yield* TxQueue.takeBetween(queue, 2, 5)
-   *   console.log(batch1) // [1, 2, 3, 4, 5] - took 5 (up to max)
    *
    *   // Take between 1 and 10 items (but only 3 remain)
    *   const batch2 = yield* TxQueue.takeBetween(queue, 1, 10)
-   *   console.log(batch2) // [6, 7, 8] - took 3 (all remaining)
    *
    *   // Would wait for at least 1 item to be available
    *   // const batch3 = yield* TxQueue.takeBetween(queue, 1, 3)
+   *   return [batch1, batch2] as const
    * })
+   *
+   * await Effect.runPromise(program) // => [[1, 2, 3, 4, 5], [6, 7, 8]]
    * ```
    *
    * @category taking
@@ -1218,8 +1228,8 @@ export const takeBetween: {
  *
  * **Example** (Peeking without removing values)
  *
- * ```ts
- * import { Effect, TxQueue } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Exit, TxQueue } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const queue = yield* TxQueue.bounded<number, string>(10)
@@ -1227,11 +1237,10 @@ export const takeBetween: {
  *
  *   // Peek at the next item without removing it
  *   const item = yield* TxQueue.peek(queue)
- *   console.log(item) // 42
  *
  *   // Item is still in the queue
  *   const size = yield* TxQueue.size(queue)
- *   console.log(size) // 1
+ *   return [item, size] as const
  * })
  *
  * // Error handling example
@@ -1240,9 +1249,11 @@ export const takeBetween: {
  *   yield* TxQueue.fail(queue, "queue failed")
  *
  *   // peek() propagates the queue error through E-channel
- *   const result = yield* Effect.flip(TxQueue.peek(queue))
- *   console.log(result) // "queue failed"
+ *   return yield* Effect.exit(TxQueue.peek(queue))
  * })
+ *
+ * await Effect.runPromise(program) // => [42, 1]
+ * await Effect.runPromise(errorExample) // => Exit.fail("queue failed")
  * ```
  *
  * @category combinators
@@ -1269,16 +1280,17 @@ export const peek = <A, E>(self: TxDequeue<A, E>): Effect.Effect<A, E> =>
  *
  * **Example** (Reading queue size)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, TxQueue } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const queue = yield* TxQueue.bounded<number>(10)
  *   yield* TxQueue.offerAll(queue, [1, 2, 3])
  *
- *   const size = yield* TxQueue.size(queue)
- *   console.log(size) // 3
+ *   return yield* TxQueue.size(queue)
  * })
+ *
+ * await Effect.runPromise(program) // => 3
  * ```
  *
  * @category combinators
@@ -1291,22 +1303,23 @@ export const size = (self: TxQueueState): Effect.Effect<number> => TxChunk.size(
  *
  * **Example** (Checking whether a queue is empty)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, TxQueue } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const queue = yield* TxQueue.bounded<number>(10)
  *
  *   const empty = yield* TxQueue.isEmpty(queue)
- *   console.log(empty) // true
  *
  *   yield* TxQueue.offer(queue, 42)
  *   const stillEmpty = yield* TxQueue.isEmpty(queue)
- *   console.log(stillEmpty) // false
+ *   return [empty, stillEmpty] as const
  * })
+ *
+ * await Effect.runPromise(program) // => [true, false]
  * ```
  *
- * @category combinators
+ * @category predicates
  * @since 2.0.0
  */
 export const isEmpty = (self: TxQueueState): Effect.Effect<boolean> => TxChunk.isEmpty(self.items)
@@ -1316,22 +1329,23 @@ export const isEmpty = (self: TxQueueState): Effect.Effect<boolean> => TxChunk.i
  *
  * **Example** (Checking whether a queue is full)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, TxQueue } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const queue = yield* TxQueue.bounded<number>(2)
  *
  *   const full = yield* TxQueue.isFull(queue)
- *   console.log(full) // false
  *
  *   yield* TxQueue.offerAll(queue, [1, 2])
  *   const nowFull = yield* TxQueue.isFull(queue)
- *   console.log(nowFull) // true
+ *   return [full, nowFull] as const
  * })
+ *
+ * await Effect.runPromise(program) // => [false, true]
  * ```
  *
- * @category combinators
+ * @category predicates
  * @since 2.0.0
  */
 export const isFull = (self: TxQueueState): Effect.Effect<boolean> =>
@@ -1348,7 +1362,7 @@ export const isFull = (self: TxQueueState): Effect.Effect<boolean> =>
  *
  * **Example** (Interrupting queues)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, TxQueue } from "effect"
  *
  * const program = Effect.gen(function*() {
@@ -1356,9 +1370,10 @@ export const isFull = (self: TxQueueState): Effect.Effect<boolean> =>
  *   yield* TxQueue.offer(queue, 42)
  *
  *   // Interrupt gracefully - allows remaining items to be consumed
- *   const result = yield* TxQueue.interrupt(queue)
- *   console.log(result) // true
+ *   return yield* TxQueue.interrupt(queue)
  * })
+ *
+ * await Effect.runPromise(program) // => true
  * ```
  *
  * @category combinators
@@ -1376,16 +1391,17 @@ export const interrupt = <A, E>(self: TxEnqueue<A, E>): Effect.Effect<boolean> =
  *
  * **Example** (Failing queues)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, TxQueue } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const queue = yield* TxQueue.bounded<number, string>(10)
  *
  *   // Fail the queue with an error
- *   const result = yield* TxQueue.fail(queue, "connection lost")
- *   console.log(result) // true
+ *   return yield* TxQueue.fail(queue, "connection lost")
  * })
+ *
+ * await Effect.runPromise(program) // => true
  * ```
  *
  * @category combinators
@@ -1401,16 +1417,17 @@ export const fail: {
    *
    * **Example** (Failing queues)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Effect, TxQueue } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const queue = yield* TxQueue.bounded<number, string>(10)
    *
    *   // Fail the queue with an error
-   *   const result = yield* TxQueue.fail(queue, "connection lost")
-   *   console.log(result) // true
+   *   return yield* TxQueue.fail(queue, "connection lost")
    * })
+   *
+   * await Effect.runPromise(program) // => true
    * ```
    *
    * @category combinators
@@ -1426,16 +1443,17 @@ export const fail: {
    *
    * **Example** (Failing queues)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Effect, TxQueue } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const queue = yield* TxQueue.bounded<number, string>(10)
    *
    *   // Fail the queue with an error
-   *   const result = yield* TxQueue.fail(queue, "connection lost")
-   *   console.log(result) // true
+   *   return yield* TxQueue.fail(queue, "connection lost")
    * })
+   *
+   * await Effect.runPromise(program) // => true
    * ```
    *
    * @category combinators
@@ -1469,7 +1487,7 @@ export const fail: {
  *
  * **Example** (Failing queues with causes)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cause, Effect, TxQueue } from "effect"
  *
  * const program = Effect.gen(function*() {
@@ -1478,8 +1496,10 @@ export const fail: {
  *   // Complete with specific cause
  *   const cause = Cause.interrupt()
  *   const result = yield* TxQueue.failCause(queue, cause)
- *   console.log(result) // true
+ *   return [cause, result] as const
  * })
+ *
+ * await Effect.runPromise(program) // => [Cause.interrupt(), true]
  * ```
  *
  * @category combinators
@@ -1495,7 +1515,7 @@ export const failCause: {
    *
    * **Example** (Failing queues with causes)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Cause, Effect, TxQueue } from "effect"
    *
    * const program = Effect.gen(function*() {
@@ -1504,8 +1524,10 @@ export const failCause: {
    *   // Complete with specific cause
    *   const cause = Cause.interrupt()
    *   const result = yield* TxQueue.failCause(queue, cause)
-   *   console.log(result) // true
+   *   return [cause, result] as const
    * })
+   *
+   * await Effect.runPromise(program) // => [Cause.interrupt(), true]
    * ```
    *
    * @category combinators
@@ -1521,7 +1543,7 @@ export const failCause: {
    *
    * **Example** (Failing queues with causes)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Cause, Effect, TxQueue } from "effect"
    *
    * const program = Effect.gen(function*() {
@@ -1530,8 +1552,10 @@ export const failCause: {
    *   // Complete with specific cause
    *   const cause = Cause.interrupt()
    *   const result = yield* TxQueue.failCause(queue, cause)
-   *   console.log(result) // true
+   *   return [cause, result] as const
    * })
+   *
+   * await Effect.runPromise(program) // => [Cause.interrupt(), true]
    * ```
    *
    * @category combinators
@@ -1569,23 +1593,23 @@ export const failCause: {
  *
  * **Example** (Ending queues)
  *
- * ```ts
- * import { Cause, Effect, TxQueue } from "effect"
+ * ```ts import.meta.vitest
+ * import { Cause, Effect, Exit, TxQueue } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const queue = yield* TxQueue.bounded<number, Cause.Done>(10)
  *
  *   // Signal the end of the queue
  *   const result = yield* TxQueue.end(queue)
- *   console.log(result) // true
  *
  *   // All operations will now fail with Done
- *   const takeResult = yield* Effect.flip(TxQueue.take(queue))
- *   console.log(Cause.isDone(takeResult)) // true
+ *   const takeResult = yield* Effect.exit(TxQueue.take(queue))
  *
- *   const peekResult = yield* Effect.flip(TxQueue.peek(queue))
- *   console.log(Cause.isDone(peekResult)) // true
+ *   const peekResult = yield* Effect.exit(TxQueue.peek(queue))
+ *   return [result, takeResult, peekResult] as const
  * })
+ *
+ * await Effect.runPromise(program) // => [true, Exit.fail(Cause.Done()), Exit.fail(Cause.Done())]
  * ```
  *
  * @category combinators
@@ -1595,16 +1619,15 @@ export const end = <A, E>(self: TxEnqueue<A, E | Cause.Done>): Effect.Effect<boo
   failCause(self, Cause.fail(Cause.Done()))
 
 /**
- * Removes and returns all currently buffered elements without changing the
- * queue state.
+ * Removes and returns all currently buffered elements.
  *
  * **Details**
  *
- * If the queue is already done with a `Cause.Done` error, returns an empty array. If the queue is done for any other cause, including interruption or failure, that cause is propagated.
+ * If the queue is closing, draining its buffered elements transitions it to done. If the queue is already done with a `Cause.Done` error, returns an empty array. If the queue is done for any other cause, including interruption or failure, that cause is propagated.
  *
  * **Example** (Clearing queues)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, TxQueue } from "effect"
  *
  * const program = Effect.gen(function*() {
@@ -1612,14 +1635,14 @@ export const end = <A, E>(self: TxEnqueue<A, E | Cause.Done>): Effect.Effect<boo
  *   yield* TxQueue.offerAll(queue, [1, 2, 3, 4, 5])
  *
  *   const sizeBefore = yield* TxQueue.size(queue)
- *   console.log(sizeBefore) // 5
  *
  *   const cleared = yield* TxQueue.clear(queue)
- *   console.log(cleared) // [1, 2, 3, 4, 5]
  *
  *   const sizeAfter = yield* TxQueue.size(queue)
- *   console.log(sizeAfter) // 0
+ *   return [sizeBefore, cleared, sizeAfter] as const
  * })
+ *
+ * await Effect.runPromise(program) // => [5, [1, 2, 3, 4, 5], 0]
  * ```
  *
  * @category combinators
@@ -1637,6 +1660,9 @@ export const clear = <A, E>(self: TxEnqueue<A, E>): Effect.Effect<Array<A>, Excl
     }
     const chunk = yield* TxChunk.get(self.items)
     yield* TxChunk.set(self.items, Chunk.empty())
+    if (state._tag === "Closing") {
+      yield* TxRef.set(self.stateRef, { _tag: "Done", cause: state.cause })
+    }
     return Chunk.toArray(chunk)
   }).pipe(Effect.tx)
 
@@ -1649,7 +1675,7 @@ export const clear = <A, E>(self: TxEnqueue<A, E>): Effect.Effect<Array<A>, Excl
  *
  * **Example** (Shutting down queues)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, TxQueue } from "effect"
  *
  * const program = Effect.gen(function*() {
@@ -1657,16 +1683,16 @@ export const clear = <A, E>(self: TxEnqueue<A, E>): Effect.Effect<Array<A>, Excl
  *   yield* TxQueue.offerAll(queue, [1, 2, 3, 4, 5])
  *
  *   const sizeBefore = yield* TxQueue.size(queue)
- *   console.log(sizeBefore) // 5
  *
  *   yield* TxQueue.shutdown(queue)
  *
  *   const sizeAfter = yield* TxQueue.size(queue)
- *   console.log(sizeAfter) // 0 (cleared)
  *
  *   const isShutdown = yield* TxQueue.isShutdown(queue)
- *   console.log(isShutdown) // true (interrupted)
+ *   return [sizeBefore, sizeAfter, isShutdown] as const
  * })
+ *
+ * await Effect.runPromise(program) // => [5, 0, true]
  * ```
  *
  * @category combinators
@@ -1683,22 +1709,23 @@ export const shutdown = <A, E>(self: TxEnqueue<A, E>): Effect.Effect<boolean> =>
  *
  * **Example** (Checking open state)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, TxQueue } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const queue = yield* TxQueue.bounded<number>(10)
  *
  *   const open = yield* TxQueue.isOpen(queue)
- *   console.log(open) // true
  *
  *   yield* TxQueue.interrupt(queue)
  *   const stillOpen = yield* TxQueue.isOpen(queue)
- *   console.log(stillOpen) // false
+ *   return [open, stillOpen] as const
  * })
+ *
+ * await Effect.runPromise(program) // => [true, false]
  * ```
  *
- * @category combinators
+ * @category predicates
  * @since 4.0.0
  */
 export const isOpen = (self: TxQueueState): Effect.Effect<boolean> =>
@@ -1709,7 +1736,7 @@ export const isOpen = (self: TxQueueState): Effect.Effect<boolean> =>
  *
  * **Example** (Checking closing state)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, TxQueue } from "effect"
  *
  * const program = Effect.gen(function*() {
@@ -1717,15 +1744,16 @@ export const isOpen = (self: TxQueueState): Effect.Effect<boolean> =>
  *   yield* TxQueue.offer(queue, 42)
  *
  *   const closing = yield* TxQueue.isClosing(queue)
- *   console.log(closing) // false
  *
  *   yield* TxQueue.interrupt(queue)
  *   const nowClosing = yield* TxQueue.isClosing(queue)
- *   console.log(nowClosing) // true
+ *   return [closing, nowClosing] as const
  * })
+ *
+ * await Effect.runPromise(program) // => [false, true]
  * ```
  *
- * @category combinators
+ * @category predicates
  * @since 4.0.0
  */
 export const isClosing = (self: TxQueueState): Effect.Effect<boolean> =>
@@ -1736,22 +1764,23 @@ export const isClosing = (self: TxQueueState): Effect.Effect<boolean> =>
  *
  * **Example** (Checking done state)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, TxQueue } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const queue = yield* TxQueue.bounded<number>(10)
  *
  *   const done = yield* TxQueue.isDone(queue)
- *   console.log(done) // false
  *
  *   yield* TxQueue.interrupt(queue)
  *   const nowDone = yield* TxQueue.isDone(queue)
- *   console.log(nowDone) // true
+ *   return [done, nowDone] as const
  * })
+ *
+ * await Effect.runPromise(program) // => [false, true]
  * ```
  *
- * @category combinators
+ * @category predicates
  * @since 4.0.0
  */
 export const isDone = (self: TxQueueState): Effect.Effect<boolean> =>
@@ -1762,22 +1791,23 @@ export const isDone = (self: TxQueueState): Effect.Effect<boolean> =>
  *
  * **Example** (Checking shutdown state)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, TxQueue } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const queue = yield* TxQueue.bounded<number>(10)
  *
  *   const isShutdown = yield* TxQueue.isShutdown(queue)
- *   console.log(isShutdown) // false
  *
  *   yield* TxQueue.shutdown(queue)
  *   const nowShutdown = yield* TxQueue.isShutdown(queue)
- *   console.log(nowShutdown) // true
+ *   return [isShutdown, nowShutdown] as const
  * })
+ *
+ * await Effect.runPromise(program) // => [false, true]
  * ```
  *
- * @category combinators
+ * @category predicates
  * @since 2.0.0
  */
 export const isShutdown = (self: TxQueueState): Effect.Effect<boolean> => isDone(self)
@@ -1787,19 +1817,20 @@ export const isShutdown = (self: TxQueueState): Effect.Effect<boolean> => isDone
  *
  * **Example** (Awaiting queue completion)
  *
- * ```ts
- * import { Effect, TxQueue } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Fiber, TxQueue } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const queue = yield* TxQueue.bounded<number, string>(10)
  *
- *   // In another fiber, end the queue
- *   yield* Effect.forkChild(Effect.delay(TxQueue.interrupt(queue), "100 millis"))
+ *   const waiter = yield* Effect.forkChild(TxQueue.awaitCompletion(queue))
+ *   yield* TxQueue.interrupt(queue)
  *
- *   // Wait for completion - succeeds when queue ends
- *   yield* TxQueue.awaitCompletion(queue)
- *   console.log("Queue completed successfully")
+ *   yield* Fiber.join(waiter)
+ *   return "Queue completed successfully"
  * })
+ *
+ * await Effect.runPromise(program) // => "Queue completed successfully"
  * ```
  *
  * @category combinators