effect 4.0.0-beta.66 → 4.0.0-beta.67

package/src/Queue.ts

@@ -1,4 +1,56 @@
 /**
+ * The `Queue` module provides asynchronous queues for communicating between
+ * fibers. A `Queue<A, E>` can receive values of type `A`, deliver them to
+ * consumers in order, and eventually complete or fail with an error of type
+ * `E`.
+ *
+ * **Mental model**
+ *
+ * - A queue is a fiber-aware channel with one write side ({@link Enqueue}) and
+ *   one read side ({@link Dequeue})
+ * - Producers add values with {@link offer} or {@link offerAll}; consumers
+ *   remove values with {@link take}, {@link takeN}, {@link takeBetween}, or
+ *   {@link takeAll}
+ * - Bounded queues use an overflow strategy: {@link bounded} suspends
+ *   producers, {@link dropping} rejects new values, and {@link sliding} drops
+ *   old values
+ * - Queues can be completed with {@link end}, failed with {@link fail} or
+ *   {@link failCause}, interrupted with {@link interrupt}, and shut down with
+ *   {@link shutdown}
+ * - Operations are expressed as `Effect` values so waiting producers and
+ *   consumers compose with interruption, scheduling, and structured
+ *   concurrency
+ *
+ * **Common tasks**
+ *
+ * - Create queues: {@link make}, {@link bounded}, {@link dropping},
+ *   {@link sliding}, {@link unbounded}
+ * - Restrict capabilities: {@link asEnqueue}, {@link asDequeue}
+ * - Produce values: {@link offer}, {@link offerAll}
+ * - Consume values: {@link take}, {@link takeN}, {@link takeBetween},
+ *   {@link takeAll}, {@link poll}, {@link peek}
+ * - Drain or reset buffered values: {@link collect}, {@link clear}
+ * - Signal lifecycle: {@link end}, {@link fail}, {@link failCause},
+ *   {@link interrupt}, {@link shutdown}
+ * - Inspect state: {@link size}, {@link isFull}
+ *
+ * **Gotchas**
+ *
+ * - `take` waits when the queue is empty; use {@link poll} when absence should
+ *   be represented as `Option.None`
+ * - `dropping` and `sliding` queues can lose values by design; use
+ *   {@link bounded} when every offered value must be preserved
+ * - Completion and failure are observed by consumers through the queue's error
+ *   channel, so include `Cause.Done` in the error type when using {@link end}
+ * - The `Unsafe` variants are synchronous, low-level operations; prefer the
+ *   effectful APIs in application code
+ *
+ * **See also**
+ *
+ * - {@link Enqueue} for write-only queue handles
+ * - {@link Dequeue} for read-only queue handles
+ * - {@link Pull} for stream-style completion errors
+ *
  * @since 3.8.0
  */
 import * as Arr from "./Array.ts"
@@ -24,8 +76,8 @@ const DequeueTypeId = "~effect/Queue/Dequeue"
 /**
  * Type guard to check if a value is a Queue.
  *
- * @since 3.8.0
  * @category Guards
+ * @since 3.8.0
  */
 export const isQueue = <A = unknown, E = unknown>(
   u: unknown
@@ -34,8 +86,8 @@ export const isQueue = <A = unknown, E = unknown>(
 /**
  * Type guard to check if a value is an Enqueue.
  *
- * @since 4.0.0
  * @category Guards
+ * @since 4.0.0
  */
 export const isEnqueue = <A = unknown, E = unknown>(
   u: unknown
@@ -44,8 +96,8 @@ export const isEnqueue = <A = unknown, E = unknown>(
 /**
  * Type guard to check if a value is a Dequeue.
  *
- * @since 4.0.0
  * @category Guards
+ * @since 4.0.0
  */
 export const isDequeue = <A = unknown, E = unknown>(
   u: unknown
@@ -54,16 +106,16 @@ export const isDequeue = <A = unknown, E = unknown>(
 /**
  * Converts a Queue to an Enqueue (write-only interface).
  *
- * @since 4.0.0
  * @category Conversions
+ * @since 4.0.0
  */
 export const asEnqueue = <A, E>(self: Queue<A, E>): Enqueue<A, E> => self
 
 /**
  * Convert a Queue to a Dequeue, allowing only read operations.
  *
- * @since 4.0.0
  * @category Conversions
+ * @since 4.0.0
  */
 export const asDequeue: <A, E>(self: Queue<A, E>) => Dequeue<A, E> = identity
 
@@ -73,15 +125,16 @@ export const asDequeue: <A, E>(self: Queue<A, E>) => Dequeue<A, E> = identity
  * This interface represents the write-only part of a Queue, allowing you to offer
  * elements to the queue but not take elements from it.
  *
- * @example
+ * **Example** (Offering through enqueue handles)
+ *
  * ```ts
  * import { Effect, Queue } from "effect"
  *
  * // Function that only needs write access to a queue
  * const producer = (enqueue: Queue.Enqueue<string>) =>
  *   Effect.gen(function*() {
- *     yield* Queue.offer(enqueue as Queue.Queue<string>, "hello")
- *     yield* Queue.offerAll(enqueue as Queue.Queue<string>, ["world", "!"])
+ *     yield* Queue.offer(enqueue, "hello")
+ *     yield* Queue.offerAll(enqueue, ["world", "!"])
  *   })
  *
  * const program = Effect.gen(function*() {
@@ -90,8 +143,8 @@ export const asDequeue: <A, E>(self: Queue<A, E>) => Dequeue<A, E> = identity
  * })
  * ```
  *
- * @since 4.0.0
  * @category Models
+ * @since 4.0.0
  */
 export interface Enqueue<in A, in E = never> extends Inspectable {
   readonly [EnqueueTypeId]: Enqueue.Variance<A, E>
@@ -104,15 +157,22 @@ export interface Enqueue<in A, in E = never> extends Inspectable {
 }
 
 /**
- * @since 4.0.0
+ * Companion namespace containing type-level metadata for the `Enqueue`
+ * write-only queue interface.
+ *
  * @category Models
+ * @since 4.0.0
  */
 export declare namespace Enqueue {
   /**
-   * Variance interface for Enqueue types, defining the type parameter constraints.
+   * Type-level variance marker for `Enqueue`.
+   *
+   * `Enqueue` is contravariant in both its offered value type `A` and failure
+   * type `E`, because values and failures flow into the queue through this
+   * handle.
    *
-   * @since 4.0.0
    * @category Models
+   * @since 4.0.0
    */
   export interface Variance<A, E> {
     _A: Types.Contravariant<A>
@@ -126,9 +186,10 @@ export declare namespace Enqueue {
  * This interface represents the read-only part of a Queue, allowing you to take
  * elements from the queue but not offer elements to it.
  *
- * @example
+ * **Example** (Taking through dequeue handles)
+ *
  * ```ts
- * import { Cause, Effect, Queue } from "effect"
+ * import { Effect, Queue } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const queue = yield* Queue.bounded<string, never>(10)
@@ -145,8 +206,8 @@ export declare namespace Enqueue {
  * })
  * ```
  *
- * @since 3.8.0
  * @category Models
+ * @since 3.8.0
  */
 export interface Dequeue<out A, out E = never> extends Inspectable {
   readonly [DequeueTypeId]: Dequeue.Variance<A, E>
@@ -159,15 +220,21 @@ export interface Dequeue<out A, out E = never> extends Inspectable {
 }
 
 /**
- * @since 4.0.0
+ * Companion namespace containing type-level metadata for the `Dequeue`
+ * read-only queue interface.
+ *
  * @category Models
+ * @since 4.0.0
  */
 export declare namespace Dequeue {
   /**
-   * Variance interface for Dequeue types, defining the type parameter constraints.
+   * Type-level variance marker for `Dequeue`.
+   *
+   * `Dequeue` is covariant in both the taken value type `A` and failure type
+   * `E`, because values and failures are observed through this handle.
    *
-   * @since 3.8.0
    * @category Models
+   * @since 3.8.0
    */
   export interface Variance<A, E> {
     _A: Types.Covariant<A>
@@ -186,9 +253,10 @@ export declare namespace Dequeue {
  *
  * - `Mailbox`
  *
- * @example
+ * **Example** (Offering and taking queue values)
+ *
  * ```ts
- * import { Cause, Effect, Queue } from "effect"
+ * import { Effect, Queue } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   // Create a bounded queue
@@ -207,23 +275,29 @@ export declare namespace Dequeue {
  * })
  * ```
  *
- * @since 3.8.0
  * @category Models
+ * @since 3.8.0
  */
 export interface Queue<in out A, in out E = never> extends Enqueue<A, E>, Dequeue<A, E> {
   readonly [TypeId]: Queue.Variance<A, E>
 }
 
 /**
- * @since 3.8.0
+ * Companion namespace containing type-level metadata and low-level state types
+ * for `Queue`.
+ *
  * @category Models
+ * @since 3.8.0
  */
 export declare namespace Queue {
   /**
-   * Variance interface for Queue types, defining the type parameter constraints.
+   * Type-level variance marker for `Queue`.
+   *
+   * A full `Queue` is invariant in both `A` and `E` because the same handle can
+   * both produce and consume values and failures.
    *
-   * @since 3.8.0
    * @category Models
+   * @since 3.8.0
    */
   export interface Variance<A, E> {
     _A: Types.Invariant<A>
@@ -231,10 +305,15 @@ export declare namespace Queue {
   }
 
   /**
-   * Represents the internal state of a Queue.
+   * Tagged state of a `Queue`.
+   *
+   * `Open` queues can accept offers and takers, `Closing` queues are
+   * completing with a stored failure exit, and `Done` queues have finished.
+   * This is low-level metadata exposed by the queue model; most users should
+   * inspect queues through the public operations.
    *
-   * @since 4.0.0
    * @category Models
+   * @since 4.0.0
    */
   export type State<A, E> =
     | {
@@ -256,10 +335,14 @@ export declare namespace Queue {
     }
 
   /**
-   * Represents an entry in the queue's offer buffer.
+   * Represents a suspended offer waiting to be admitted to a bounded queue.
+   *
+   * An entry is either a single message or a batch with an offset into its
+   * remaining messages, plus a resume callback that completes the suspended
+   * offer when the queue can accept more input.
    *
-   * @since 4.0.0
    * @category Models
+   * @since 4.0.0
    */
   export type OfferEntry<A> =
     | {
@@ -294,9 +377,12 @@ const QueueProto = {
 }
 
 /**
- * A `Queue` is an asynchronous queue that can be offered to and taken from.
+ * Creates a `Queue` with optional capacity and overflow strategy.
  *
- * It also supports signaling that it is done or failed.
+ * By default the queue is unbounded and uses the `"suspend"` strategy. Provide
+ * `capacity` for a bounded queue and choose `"suspend"`, `"dropping"`, or
+ * `"sliding"` to control what happens when the queue is full. The returned
+ * queue can be offered to, taken from, failed, ended, interrupted, or shut down.
  *
  * **Previously Known As**
  *
@@ -304,12 +390,12 @@ const QueueProto = {
  *
  * - `Mailbox.make`
  *
- * @since 3.8.0
  * @category Constructors
- * @example
+ * @since 3.8.0
+ * **Example** (Creating queues)
+ *
  * ```ts
  * import { Cause, Effect, Queue } from "effect"
- * import * as assert from "node:assert"
  *
  * Effect.gen(function*() {
  *   const queue = yield* Queue.make<number, string | Cause.Done>()
@@ -321,15 +407,17 @@ const QueueProto = {
  *
  *   // take messages from the queue
  *   const messages = yield* Queue.takeAll(queue)
- *   assert.deepStrictEqual(messages, [1, 2, 3, 4, 5])
+ *   console.log(messages) // [1, 2, 3, 4, 5]
  *
  *   // signal that the queue is done
  *   yield* Queue.end(queue)
- *   const done = yield* Effect.flip(Queue.takeAll(queue))
- *   assert.deepStrictEqual(done, Cause.Done)
+ *   const done = yield* Effect.flip(Queue.take(queue))
+ *   console.log(Cause.isDone(done)) // true
  *
- *   // signal that the queue has failed
- *   yield* Queue.fail(queue, "boom")
+ *   // signal that another queue has failed
+ *   const failedQueue = yield* Queue.make<number, string>()
+ *   const failed = yield* Queue.fail(failedQueue, "boom")
+ *   console.log(failed) // true
  * })
  * ```
  */
@@ -361,9 +449,10 @@ export const make = <A, E = never>(
  * When the queue reaches capacity, producers will be suspended until space becomes available.
  * This ensures all messages are processed but may slow down producers.
  *
- * @example
+ * **Example** (Creating bounded queues)
+ *
  * ```ts
- * import { Cause, Effect, Queue } from "effect"
+ * import { Effect, Queue } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const queue = yield* Queue.bounded<string>(5)
@@ -377,8 +466,8 @@ export const make = <A, E = never>(
  * })
  * ```
  *
- * @since 2.0.0
  * @category Constructors
+ * @since 2.0.0
  */
 export const bounded = <A, E = never>(capacity: number): Effect<Queue<A, E>> => make({ capacity })
 
@@ -389,9 +478,10 @@ export const bounded = <A, E = never>(capacity: number): Effect<Queue<A, E>> =>
  * This strategy prevents producers from being blocked but may result in message loss.
  * Useful when you want to maintain a rolling window of the most recent messages.
  *
- * @example
+ * **Example** (Creating sliding queues)
+ *
  * ```ts
- * import { Cause, Effect, Queue } from "effect"
+ * import { Effect, Queue } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const queue = yield* Queue.sliding<number>(3)
@@ -409,8 +499,8 @@ export const bounded = <A, E = never>(capacity: number): Effect<Queue<A, E>> =>
  * })
  * ```
  *
- * @since 2.0.0
  * @category Constructors
+ * @since 2.0.0
  */
 export const sliding = <A, E = never>(capacity: number): Effect<Queue<A, E>> => make({ capacity, strategy: "sliding" })
 
@@ -421,9 +511,10 @@ export const sliding = <A, E = never>(capacity: number): Effect<Queue<A, E>> =>
  * This strategy prevents producers from being blocked and preserves existing messages,
  * but new messages may be lost when the queue is full.
  *
- * @example
+ * **Example** (Creating dropping queues)
+ *
  * ```ts
- * import { Cause, Effect, Queue } from "effect"
+ * import { Effect, Queue } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const queue = yield* Queue.dropping<number>(2)
@@ -442,8 +533,8 @@ export const sliding = <A, E = never>(capacity: number): Effect<Queue<A, E>> =>
  * })
  * ```
  *
- * @since 2.0.0
  * @category Constructors
+ * @since 2.0.0
  */
 export const dropping = <A, E = never>(capacity: number): Effect<Queue<A, E>> =>
   make({ capacity, strategy: "dropping" })
@@ -455,9 +546,10 @@ export const dropping = <A, E = never>(capacity: number): Effect<Queue<A, E>> =>
  * can always add messages successfully. This is useful when you want to prioritize
  * producer throughput over memory usage control.
  *
- * @example
+ * **Example** (Creating unbounded queues)
+ *
  * ```ts
- * import { Cause, Effect, Queue } from "effect"
+ * import { Effect, Queue } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const queue = yield* Queue.unbounded<string>()
@@ -469,7 +561,7 @@ export const dropping = <A, E = never>(capacity: number): Effect<Queue<A, E>> =>
  *
  *   // Check current size
  *   const size = yield* Queue.size(queue)
- *   console.log(size) // Some(5)
+ *   console.log(size) // 5
  *
  *   // Take all messages
  *   const messages = yield* Queue.takeAll(queue)
@@ -477,8 +569,8 @@ export const dropping = <A, E = never>(capacity: number): Effect<Queue<A, E>> =>
  * })
  * ```
  *
- * @since 2.0.0
  * @category Constructors
+ * @since 2.0.0
  */
 export const unbounded = <A, E = never>(): Effect<Queue<A, E>> => make()
 
@@ -489,9 +581,10 @@ export const unbounded = <A, E = never>(): Effect<Queue<A, E>> => make()
  * depending on the backpressure strategy. For dropping/sliding queues, it may
  * return false or succeed immediately by dropping/sliding existing messages.
  *
- * @example
+ * **Example** (Offering a value)
+ *
  * ```ts
- * import { Cause, Effect, Queue } from "effect"
+ * import { Effect, Queue } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const queue = yield* Queue.bounded<number>(3)
@@ -542,7 +635,8 @@ export const offer = <A, E>(self: Enqueue<A, E>, message: Types.NoInfer<A>): Eff
  * This is an unsafe operation that directly modifies the queue without Effect wrapping.
  * Use this only when you're certain about the synchronous nature of the operation.
  *
- * @example
+ * **Example** (Offering a value synchronously)
+ *
  * ```ts
  * import { Cause, Effect, Queue } from "effect"
  *
@@ -592,14 +686,15 @@ export const offerUnsafe = <A, E>(self: Enqueue<A, E>, message: Types.NoInfer<A>
  * enough capacity. The operation returns an array of messages that couldn't
  * be added (empty array means all messages were successfully added).
  *
- * @example
+ * **Example** (Offering multiple values)
+ *
  * ```ts
- * import { Cause, Effect, Queue } from "effect"
+ * import { Effect, Queue } from "effect"
  *
  * const program = Effect.gen(function*() {
- *   const queue = yield* Queue.bounded<number>(3)
+ *   const queue = yield* Queue.dropping<number>(3)
  *
- *   // Try to add more messages than capacity
+ *   // Try to add more messages than capacity without suspending
  *   const remaining1 = yield* Queue.offerAll(queue, [1, 2, 3, 4, 5])
  *   console.log(remaining1) // [4, 5] - couldn't fit the last 2
  * })
@@ -628,7 +723,8 @@ export const offerAll = <A, E>(self: Enqueue<A, E>, messages: Iterable<A>): Effe
  *
  * This is an unsafe operation that directly modifies the queue without Effect wrapping.
  *
- * @example
+ * **Example** (Offering multiple values synchronously)
+ *
  * ```ts
  * import { Cause, Effect, Queue } from "effect"
  *
@@ -687,23 +783,21 @@ export const offerAllUnsafe = <A, E>(self: Enqueue<A, E>, messages: Iterable<A>)
  * Fail the queue with an error. If the queue is already done, `false` is
  * returned.
  *
- * @example
+ * **Example** (Failing queues with an error)
+ *
  * ```ts
- * import { Cause, Effect, Queue } from "effect"
+ * import { Effect, Queue } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const queue = yield* Queue.bounded<number, string>(10)
  *
- *   // Add some messages
- *   yield* Queue.offer(queue, 1)
- *   yield* Queue.offer(queue, 2)
- *
  *   // Fail the queue with an error
  *   const failed = yield* Queue.fail(queue, "Something went wrong")
  *   console.log(failed) // true
  *
- *   // Subsequent operations will reflect the failure
- *   // Taking from failed queue will fail with the error
+ *   // Taking from the failed queue fails with the error
+ *   const error = yield* Effect.flip(Queue.take(queue))
+ *   console.log(error) // "Something went wrong"
  * })
  * ```
  *
@@ -716,22 +810,21 @@ export const fail = <A, E>(self: Enqueue<A, E>, error: E) => failCause(self, cor
  * Fail the queue with a cause. If the queue is already done, `false` is
  * returned.
  *
- * @example
+ * **Example** (Failing queues with a cause)
+ *
  * ```ts
  * import { Cause, Effect, Queue } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const queue = yield* Queue.bounded<number, string>(10)
  *
- *   // Add some messages
- *   yield* Queue.offer(queue, 1)
- *
  *   // Create a cause and fail the queue
  *   const cause = Cause.fail("Queue processing failed")
  *   const failed = yield* Queue.failCause(queue, cause)
  *   console.log(failed) // true
  *
- *   // The queue is now in failed state with the specified cause
+ *   // The queue is now done with the specified failure cause
+ *   console.log(queue.state._tag) // "Done"
  * })
  * ```
  *
@@ -743,22 +836,21 @@ export const failCause: {
    * Fail the queue with a cause. If the queue is already done, `false` is
    * returned.
    *
-   * @example
+   * **Example** (Failing queues with a cause)
+   *
    * ```ts
    * import { Cause, Effect, Queue } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const queue = yield* Queue.bounded<number, string>(10)
    *
-   *   // Add some messages
-   *   yield* Queue.offer(queue, 1)
-   *
    *   // Create a cause and fail the queue
    *   const cause = Cause.fail("Queue processing failed")
    *   const failed = yield* Queue.failCause(queue, cause)
    *   console.log(failed) // true
    *
-   *   // The queue is now in failed state with the specified cause
+   *   // The queue is now done with the specified failure cause
+   *   console.log(queue.state._tag) // "Done"
    * })
    * ```
    *
@@ -770,22 +862,21 @@ export const failCause: {
    * Fail the queue with a cause. If the queue is already done, `false` is
    * returned.
    *
-   * @example
+   * **Example** (Failing queues with a cause)
+   *
    * ```ts
    * import { Cause, Effect, Queue } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const queue = yield* Queue.bounded<number, string>(10)
    *
-   *   // Add some messages
-   *   yield* Queue.offer(queue, 1)
-   *
    *   // Create a cause and fail the queue
    *   const cause = Cause.fail("Queue processing failed")
    *   const failed = yield* Queue.failCause(queue, cause)
    *   console.log(failed) // true
    *
-   *   // The queue is now in failed state with the specified cause
+   *   // The queue is now done with the specified failure cause
+   *   console.log(queue.state._tag) // "Done"
    * })
    * ```
    *
@@ -805,7 +896,8 @@ export const failCause: {
  *
  * This is an unsafe operation that directly modifies the queue without Effect wrapping.
  *
- * @example
+ * **Example** (Failing queues with a cause synchronously)
+ *
  * ```ts
  * import { Effect, Cause } from "effect"
  * import { Queue } from "effect"
@@ -813,15 +905,12 @@ export const failCause: {
  * const program = Effect.gen(function*() {
  *   const queue = yield* Queue.bounded<number, string>(10)
  *
- *   // Add some messages
- *   Queue.offerUnsafe(queue, 1)
- *
  *   // Create a cause and fail the queue synchronously
  *   const cause = Cause.fail("Processing error")
  *   const failed = Queue.failCauseUnsafe(queue, cause)
  *   console.log(failed) // true
  *
- *   // The queue is now in failed state
+ *   // The queue is now done with the specified failure cause
  *   console.log(queue.state._tag) // "Done"
  * })
  * ```
@@ -850,7 +939,8 @@ export const failCauseUnsafe = <A, E>(self: Enqueue<A, E>, cause: Cause<E>): boo
  * Signal that the queue is complete. If the queue is already done, `false` is
  * returned.
  *
- * @example
+ * **Example** (Ending queues)
+ *
  * ```ts
  * import { Cause, Effect, Queue } from "effect"
  *
@@ -886,7 +976,8 @@ export const end = <A, E>(self: Enqueue<A, E | Done>): Effect<boolean> => failCa
  *
  * This is an unsafe operation that directly modifies the queue without Effect wrapping.
  *
- * @example
+ * **Example** (Ending queues synchronously)
+ *
  * ```ts
  * import { Cause, Effect, Queue } from "effect"
  *
@@ -902,7 +993,13 @@ export const end = <A, E>(self: Enqueue<A, E | Done>): Effect<boolean> => failCa
  *   const ended = Queue.endUnsafe(queue)
  *   console.log(ended) // true
  *
- *   // The queue is now done
+ *   // Existing messages can still be consumed while the queue is closing
+ *   console.log(queue.state._tag) // "Closing"
+ *
+ *   Queue.takeUnsafe(queue)
+ *   Queue.takeUnsafe(queue)
+ *
+ *   // After buffered messages are consumed, the queue is done
  *   console.log(queue.state._tag) // "Done"
  * })
  * ```
@@ -918,7 +1015,8 @@ export const endUnsafe = <A, E>(self: Enqueue<A, E | Done>) => failCauseUnsafe(s
  * This operation stops accepting new offers but allows existing messages to be consumed.
  * Once all messages are drained, the queue transitions to the Done state with an interrupt cause.
  *
- * @example
+ * **Example** (Interrupting queues gracefully)
+ *
  * ```ts
  * import { Cause, Effect, Queue } from "effect"
  *
@@ -957,12 +1055,18 @@ export const interrupt = <A, E>(self: Enqueue<A, E>): Effect<boolean> =>
   core.withFiber((fiber) => failCause(self, internalEffect.causeInterrupt(fiber.id)))
 
 /**
- * Shutdown the queue, canceling any pending operations.
- * If the queue is already done, `false` is returned.
+ * Shuts down the queue immediately, discarding buffered messages and resuming
+ * pending operations.
+ *
+ * **Details**
+ *
+ * The operation is idempotent and returns `true`, including when the queue has
+ * already been shut down or completed.
+ *
+ * **Example** (Shutting down queues)
  *
- * @example
  * ```ts
- * import { Cause, Effect, Queue } from "effect"
+ * import { Effect, Queue } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const queue = yield* Queue.bounded<number>(2)
@@ -971,10 +1075,7 @@ export const interrupt = <A, E>(self: Enqueue<A, E>): Effect<boolean> =>
  *   yield* Queue.offer(queue, 1)
  *   yield* Queue.offer(queue, 2)
  *
- *   // Try to add more than capacity (will be pending)
- *   const pendingOffer = Queue.offer(queue, 3)
- *
- *   // Shutdown cancels pending operations and clears the queue
+ *   // Shutdown clears buffered messages and prevents further offers
  *   const wasShutdown = yield* Queue.shutdown(queue)
  *   console.log(wasShutdown) // true
  *
@@ -1009,10 +1110,15 @@ export const shutdown = <A, E>(self: Enqueue<A, E>): Effect<boolean> =>
   })
 
 /**
- * Take all messages from the queue, returning an empty array if the queue
- * is empty or done.
+ * Drains and returns all currently buffered messages without waiting for more.
+ *
+ * **Details**
+ *
+ * Returns an empty array when the queue is empty or has completed normally. If
+ * the queue has failed, the effect fails with the queue's error.
+ *
+ * **Example** (Clearing queued values)
  *
- * @example
  * ```ts
  * import { Cause, Effect, Queue } from "effect"
  *
@@ -1053,12 +1159,16 @@ export const clear = <A, E>(self: Dequeue<A, E>): Effect<Array<A>, Pull.ExcludeD
   })
 
 /**
- * Take all messages from the queue, or wait for messages to be available.
+ * Takes all currently available messages, waiting until at least one message
+ * is available when the queue is empty.
  *
- * If the queue is done, the `done` flag will be `true`. If the queue
- * fails, the Effect will fail with the error.
+ * **Details**
+ *
+ * Returns a non-empty array. If the queue completes or fails before a message
+ * can be taken, the effect fails with the queue's terminal error.
+ *
+ * **Example** (Taking all available values)
  *
- * @example
  * ```ts
  * import { Cause, Effect, Queue } from "effect"
  *
@@ -1083,7 +1193,8 @@ export const takeAll = <A, E>(self: Dequeue<A, E>): Effect<Arr.NonEmptyArray<A>,
 /**
  * Take all messages from the queue, until the queue has errored or is done.
  *
- * @example
+ * **Example** (Collecting values until completion)
+ *
  * ```ts
  * import { Cause, Effect, Queue } from "effect"
  *
@@ -1125,13 +1236,17 @@ export const collect = <A, E>(self: Dequeue<A, E | Done>): Effect<Array<A>, Pull
   }) as any
 
 /**
- * Take a specified number of messages from the queue. It will only take
- * up to the capacity of the queue.
+ * Takes up to `n` messages from the queue.
+ *
+ * **Details**
+ *
+ * The operation may wait until enough messages are available to satisfy the
+ * queue's batching rules. If `n` is less than or equal to zero, it succeeds
+ * with an empty array. If the queue completes or fails before messages can be
+ * taken, the effect fails with the queue's terminal error.
  *
- * If the queue is done, the `done` flag will be `true`. If the queue
- * fails, the Effect will fail with the error.
+ * **Example** (Taking a fixed number of values)
  *
- * @example
  * ```ts
  * import { Cause, Effect, Queue } from "effect"
  *
@@ -1149,11 +1264,8 @@ export const collect = <A, E>(self: Dequeue<A, E | Done>): Effect<Array<A>, Pull
  *   const next2 = yield* Queue.takeN(queue, 2)
  *   console.log(next2) // [4, 5]
  *
- *   // End the queue before taking; now it can return fewer than requested
- *   yield* Queue.end(queue)
- *
- *   // Take remaining messages (takes 2, even though we asked for 5)
- *   const remaining = yield* Queue.takeN(queue, 5)
+ *   // Take remaining messages
+ *   const remaining = yield* Queue.takeN(queue, 2)
  *   console.log(remaining) // [6, 7]
  * })
  * ```
@@ -1167,13 +1279,17 @@ export const takeN = <A, E>(
 ): Effect<Array<A>, E> => takeBetween(self, n, n)
 
 /**
- * Take a variable number of messages from the queue, between specified min and max.
- * It will only take up to the capacity of the queue.
+ * Takes between `min` and `max` messages from the queue.
+ *
+ * **Details**
  *
- * If the queue is done, the `done` flag will be `true`. If the queue
- * fails, the Effect will fail with the error.
+ * The operation waits when fewer than the required minimum messages are
+ * available. It returns at most `max` messages. If the queue completes or fails
+ * before the minimum can be satisfied, the effect fails with the queue's
+ * terminal error.
+ *
+ * **Example** (Taking a bounded batch of values)
  *
- * @example
  * ```ts
  * import { Cause, Effect, Queue } from "effect"
  *
@@ -1215,7 +1331,8 @@ export const takeBetween = <A, E>(
  * If the queue is done, it will fail with `Done`. If the
  * queue fails, the Effect will fail with the error.
  *
- * @example
+ * **Example** (Taking one value)
+ *
  * ```ts
  * import { Cause, Effect, Queue } from "effect"
  *
@@ -1234,7 +1351,7 @@ export const takeBetween = <A, E>(
  *   // End the queue
  *   yield* Queue.end(queue)
  *
- *   // Taking from ended queue fails with None
+ *   // Taking from an ended queue fails with Done
  *   const result = yield* Effect.match(Queue.take(queue), {
  *     onFailure: (error: Cause.Done) => true,
  *     onSuccess: (value: string) => false
@@ -1252,11 +1369,16 @@ export const take = <A, E>(self: Dequeue<A, E>): Effect<A, E> =>
   )
 
 /**
- * Tries to take an item from the queue without blocking.
+ * Attempts to take one item from the queue without waiting.
  *
- * Returns `Option.some` with the item if available, or `Option.none` if the queue is empty or done.
+ * **Details**
+ *
+ * Returns `Option.some` when an item is immediately available. Returns
+ * `Option.none` when no item is available, when the queue is done, or when the
+ * immediate take observes a queue failure.
+ *
+ * **Example** (Polling without blocking)
  *
- * @example
  * ```ts
  * import { Effect, Option, Queue } from "effect"
  *
@@ -1296,7 +1418,8 @@ export const poll = <A, E>(self: Dequeue<A, E>): Effect<Option.Option<A>> =>
  *
  * Blocks until an item is available. If the queue is done or fails, the error is propagated.
  *
- * @example
+ * **Example** (Peeking at the next value)
+ *
  * ```ts
  * import { Cause, Effect, Queue } from "effect"
  *
@@ -1325,16 +1448,16 @@ export const peek = <A, E>(self: Dequeue<A, E>): Effect<A, E> =>
   })
 
 /**
- * Take a single message from the queue synchronously, or wait for a message to be
- * available.
+ * Attempts to take one message from the queue synchronously.
  *
- * If the queue is done, it will fail with `Done`. If the
- * queue fails, the Effect will fail with the error.
- * Returns `undefined` if no message is immediately available.
+ * **Details**
+ *
+ * Returns an `Exit` for an immediately available message or for the queue's
+ * terminal state. Returns `undefined` when no message is immediately available.
+ * This operation does not wait or register a taker.
  *
- * This is an unsafe operation that directly accesses the queue without Effect wrapping.
+ * **Example** (Taking one value synchronously)
  *
- * @example
  * ```ts
  * import { Effect, Queue } from "effect"
  *
@@ -1408,11 +1531,14 @@ export {
 }
 
 /**
- * Check the size of the queue.
+ * Returns the current number of buffered messages in the queue.
+ *
+ * **Details**
+ *
+ * Completed queues report a size of `0`.
  *
- * If the queue is complete, it will return `None`.
+ * **Example** (Checking queue size)
  *
- * @example
  * ```ts
  * import { Cause, Effect, Option, Queue } from "effect"
  *
@@ -1447,7 +1573,8 @@ export const size = <A, E>(self: Dequeue<A, E>): Effect<number> => internalEffec
 /**
  * Check if the queue is full.
  *
- * @example
+ * **Example** (Checking if queues are full)
+ *
  * ```ts
  * import { Cause, Effect, Option, Queue } from "effect"
  *
@@ -1469,12 +1596,15 @@ export const size = <A, E>(self: Dequeue<A, E>): Effect<number> => internalEffec
 export const isFull = <A, E>(self: Dequeue<A, E>): Effect<boolean> => internalEffect.sync(() => isFullUnsafe(self))
 
 /**
- * Check the size of the queue synchronously.
+ * Returns the current number of buffered messages in the queue synchronously.
+ *
+ * **Details**
  *
- * If the queue is complete, it will return `None`.
- * This is an unsafe operation that directly accesses the queue without Effect wrapping.
+ * Completed queues report a size of `0`. This unsafe operation reads the queue
+ * state directly without Effect wrapping.
+ *
+ * **Example** (Checking queue size synchronously)
  *
- * @example
  * ```ts
  * import { Cause, Effect, Option, Queue } from "effect"
  *
@@ -1511,7 +1641,8 @@ export const sizeUnsafe = <A, E>(self: Dequeue<A, E>): number => self.state._tag
 /**
  * Check if the queue is full synchronously.
  *
- * @example
+ * **Example** (Checking fullness synchronously)
+ *
  * ```ts
  * import { Cause, Effect, Option, Queue } from "effect"
  *
@@ -1536,7 +1667,8 @@ export const isFullUnsafe = <A, E>(self: Dequeue<A, E>): boolean => sizeUnsafe(s
  * Run an `Effect` into a `Queue`, where success ends the queue and failure
  * fails the queue.
  *
- * @example
+ * **Example** (Running effects into queues)
+ *
  * ```ts
  * import { Cause, Effect, Queue } from "effect"
  *
@@ -1562,15 +1694,16 @@ export const isFullUnsafe = <A, E>(self: Dequeue<A, E>): boolean => sizeUnsafe(s
  * })
  * ```
  *
- * @since 3.8.0
  * @category Completion
+ * @since 3.8.0
  */
 export const into: {
   /**
    * Run an `Effect` into a `Queue`, where success ends the queue and failure
    * fails the queue.
    *
-   * @example
+   * **Example** (Running effects into queues)
+   *
    * ```ts
    * import { Cause, Effect, Queue } from "effect"
    *
@@ -1596,8 +1729,8 @@ export const into: {
    * })
    * ```
    *
-   * @since 3.8.0
    * @category Completion
+   * @since 3.8.0
    */
   <A, E>(self: Enqueue<A, E | Done>): <AX, EX extends E, RX>(
     effect: Effect<AX, EX, RX>
@@ -1606,7 +1739,8 @@ export const into: {
    * Run an `Effect` into a `Queue`, where success ends the queue and failure
    * fails the queue.
    *
-   * @example
+   * **Example** (Running effects into queues)
+   *
    * ```ts
    * import { Cause, Effect, Queue } from "effect"
    *
@@ -1632,8 +1766,8 @@ export const into: {
    * })
    * ```
    *
-   * @since 3.8.0
    * @category Completion
+   * @since 3.8.0
    */
   <AX, E, EX extends E, RX, A>(effect: Effect<AX, EX, RX>, self: Enqueue<A, E | Done>): Effect<boolean, never, RX>
 } = dual(