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

package/dist/Queue.d.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";
@@ -17,36 +69,36 @@ declare const DequeueTypeId = "~effect/Queue/Dequeue";
 /**
  * Type guard to check if a value is a Queue.
  *
- * @since 3.8.0
- * @category Guards
+ * @category guards
+ * @since 2.0.0
  */
 export declare const isQueue: <A = unknown, E = unknown>(u: unknown) => u is Queue<A, E>;
 /**
  * Type guard to check if a value is an Enqueue.
  *
- * @since 4.0.0
- * @category Guards
+ * @category guards
+ * @since 2.0.0
  */
 export declare const isEnqueue: <A = unknown, E = unknown>(u: unknown) => u is Enqueue<A, E>;
 /**
  * Type guard to check if a value is a Dequeue.
  *
- * @since 4.0.0
- * @category Guards
+ * @category guards
+ * @since 2.0.0
  */
 export declare const isDequeue: <A = unknown, E = unknown>(u: unknown) => u is Dequeue<A, E>;
 /**
  * Converts a Queue to an Enqueue (write-only interface).
  *
+ * @category converting
  * @since 4.0.0
- * @category Conversions
  */
 export declare const asEnqueue: <A, E>(self: Queue<A, E>) => Enqueue<A, E>;
 /**
  * Convert a Queue to a Dequeue, allowing only read operations.
  *
+ * @category converting
  * @since 4.0.0
- * @category Conversions
  */
 export declare const asDequeue: <A, E>(self: Queue<A, E>) => Dequeue<A, E>;
 /**
@@ -55,15 +107,16 @@ export declare const asDequeue: <A, E>(self: Queue<A, E>) => Dequeue<A, E>;
  * 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*() {
@@ -72,8 +125,8 @@ export declare const asDequeue: <A, E>(self: Queue<A, E>) => Dequeue<A, E>;
  * })
  * ```
  *
- * @since 4.0.0
- * @category Models
+ * @category models
+ * @since 2.0.0
  */
 export interface Enqueue<in A, in E = never> extends Inspectable {
     readonly [EnqueueTypeId]: Enqueue.Variance<A, E>;
@@ -85,15 +138,21 @@ export interface Enqueue<in A, in E = never> extends Inspectable {
     scheduleRunning: boolean;
 }
 /**
- * @since 4.0.0
- * @category Models
+ * Companion namespace containing type-level metadata for the `Enqueue`
+ * write-only queue interface.
+ *
+ * @since 2.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.
+     *
+     * @category models
      * @since 4.0.0
-     * @category Models
      */
     interface Variance<A, E> {
         _A: Types.Contravariant<A>;
@@ -106,9 +165,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)
@@ -125,8 +185,8 @@ export declare namespace Enqueue {
  * })
  * ```
  *
- * @since 3.8.0
- * @category Models
+ * @category models
+ * @since 2.0.0
  */
 export interface Dequeue<out A, out E = never> extends Inspectable {
     readonly [DequeueTypeId]: Dequeue.Variance<A, E>;
@@ -138,15 +198,20 @@ export interface Dequeue<out A, out E = never> extends Inspectable {
     scheduleRunning: boolean;
 }
 /**
- * @since 4.0.0
- * @category Models
+ * Companion namespace containing type-level metadata for the `Dequeue`
+ * read-only queue interface.
+ *
+ * @since 2.0.0
  */
 export declare namespace Dequeue {
     /**
-     * Variance interface for Dequeue types, defining the type parameter constraints.
+     * Type-level variance marker for `Dequeue`.
      *
-     * @since 3.8.0
-     * @category Models
+     * `Dequeue` is covariant in both the taken value type `A` and failure type
+     * `E`, because values and failures are observed through this handle.
+     *
+     * @category models
+     * @since 4.0.0
      */
     interface Variance<A, E> {
         _A: Types.Covariant<A>;
@@ -158,15 +223,10 @@ export declare namespace Dequeue {
  *
  * It also supports signaling that it is done or failed.
  *
- * **Previously Known As**
+ * **Example** (Offering and taking queue values)
  *
- * This API replaces the following from Effect 3.x:
- *
- * - `Mailbox`
- *
- * @example
  * ```ts
- * import { Cause, Effect, Queue } from "effect"
+ * import { Effect, Queue } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   // Create a bounded queue
@@ -185,32 +245,42 @@ export declare namespace Dequeue {
  * })
  * ```
  *
- * @since 3.8.0
- * @category Models
+ * @category models
+ * @since 2.0.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
- * @category Models
+ * Companion namespace containing type-level metadata and low-level state types
+ * for `Queue`.
+ *
+ * @since 2.0.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
+     * @category models
+     * @since 4.0.0
      */
     interface Variance<A, E> {
         _A: Types.Invariant<A>;
         _E: Types.Invariant<E>;
     }
     /**
-     * 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.
      *
+     * @category models
      * @since 4.0.0
-     * @category Models
      */
     type State<A, E> = {
         readonly _tag: "Open";
@@ -228,10 +298,14 @@ export declare namespace Queue {
         readonly exit: Failure<never, E>;
     };
     /**
-     * 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.
+     *
+     * @category models
      * @since 4.0.0
-     * @category Models
      */
     type OfferEntry<A> = {
         readonly _tag: "Array";
@@ -245,22 +319,17 @@ export declare namespace Queue {
     };
 }
 /**
- * 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.
- *
- * **Previously Known As**
- *
- * This API replaces the following from Effect 3.x:
+ * 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.
  *
- * - `Mailbox.make`
+ * **Example** (Creating queues)
  *
- * @since 3.8.0
- * @category Constructors
- * @example
  * ```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>()
@@ -272,17 +341,22 @@ export declare namespace Queue {
  *
  *   // 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
  * })
  * ```
+ *
+ * @category constructors
+ * @since 4.0.0
  */
 export declare const make: <A, E = never>(options?: {
     readonly capacity?: number | undefined;
@@ -294,9 +368,10 @@ export declare const make: <A, E = never>(options?: {
  * 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)
@@ -310,8 +385,8 @@ export declare const make: <A, E = never>(options?: {
  * })
  * ```
  *
+ * @category constructors
  * @since 2.0.0
- * @category Constructors
  */
 export declare const bounded: <A, E = never>(capacity: number) => Effect<Queue<A, E>>;
 /**
@@ -321,9 +396,10 @@ export declare const bounded: <A, E = never>(capacity: number) => Effect<Queue<A
  * 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)
@@ -341,8 +417,8 @@ export declare const bounded: <A, E = never>(capacity: number) => Effect<Queue<A
  * })
  * ```
  *
+ * @category constructors
  * @since 2.0.0
- * @category Constructors
  */
 export declare const sliding: <A, E = never>(capacity: number) => Effect<Queue<A, E>>;
 /**
@@ -352,9 +428,10 @@ export declare const sliding: <A, E = never>(capacity: number) => Effect<Queue<A
  * 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)
@@ -373,8 +450,8 @@ export declare const sliding: <A, E = never>(capacity: number) => Effect<Queue<A
  * })
  * ```
  *
+ * @category constructors
  * @since 2.0.0
- * @category Constructors
  */
 export declare const dropping: <A, E = never>(capacity: number) => Effect<Queue<A, E>>;
 /**
@@ -384,9 +461,10 @@ export declare const dropping: <A, E = never>(capacity: number) => Effect<Queue<
  * 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>()
@@ -398,7 +476,7 @@ export declare const dropping: <A, E = never>(capacity: number) => Effect<Queue<
  *
  *   // 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)
@@ -406,8 +484,8 @@ export declare const dropping: <A, E = never>(capacity: number) => Effect<Queue<
  * })
  * ```
  *
+ * @category constructors
  * @since 2.0.0
- * @category Constructors
  */
 export declare const unbounded: <A, E = never>() => Effect<Queue<A, E>>;
 /**
@@ -417,9 +495,10 @@ export declare const unbounded: <A, E = never>() => Effect<Queue<A, E>>;
  * 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)
@@ -436,7 +515,7 @@ export declare const unbounded: <A, E = never>() => Effect<Queue<A, E>>;
  * ```
  *
  * @category Offering
- * @since 4.0.0
+ * @since 2.0.0
  */
 export declare const offer: <A, E>(self: Enqueue<A, E>, message: Types.NoInfer<A>) => Effect<boolean>;
 /**
@@ -445,7 +524,8 @@ export declare const offer: <A, E>(self: Enqueue<A, E>, message: Types.NoInfer<A
  * 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"
  *
@@ -476,21 +556,22 @@ export declare const offerUnsafe: <A, E>(self: Enqueue<A, E>, message: Types.NoI
  * 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
  * })
  * ```
  *
  * @category Offering
- * @since 4.0.0
+ * @since 2.0.0
  */
 export declare const offerAll: <A, E>(self: Enqueue<A, E>, messages: Iterable<A>) => Effect<Array<A>>;
 /**
@@ -499,7 +580,8 @@ export declare const offerAll: <A, E>(self: Enqueue<A, E>, messages: Iterable<A>
  *
  * 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"
  *
@@ -525,23 +607,21 @@ export declare const offerAllUnsafe: <A, E>(self: Enqueue<A, E>, messages: Itera
  * 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"
  * })
  * ```
  *
@@ -553,22 +633,21 @@ export declare const fail: <A, E>(self: Enqueue<A, E>, error: E) => Effect<boole
  * 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"
  * })
  * ```
  *
@@ -580,22 +659,21 @@ export declare 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"
      * })
      * ```
      *
@@ -607,22 +685,21 @@ export declare 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"
      * })
      * ```
      *
@@ -637,23 +714,20 @@ export declare 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"
+ * import { Cause, Effect, Queue } from "effect"
  *
  * 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"
  * })
  * ```
@@ -666,7 +740,8 @@ export declare const failCauseUnsafe: <A, E>(self: Enqueue<A, E>, cause: Cause<E
  * 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"
  *
@@ -701,7 +776,8 @@ export declare const end: <A, E>(self: Enqueue<A, E | Done>) => Effect<boolean>;
  *
  * 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"
  *
@@ -717,7 +793,13 @@ export declare const end: <A, E>(self: Enqueue<A, E | Done>) => Effect<boolean>;
  *   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"
  * })
  * ```
@@ -732,7 +814,8 @@ export declare const endUnsafe: <A, E>(self: Enqueue<A, E | Done>) => boolean;
  * 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"
  *
@@ -769,12 +852,18 @@ export declare const endUnsafe: <A, E>(self: Enqueue<A, E | Done>) => boolean;
  */
 export declare const interrupt: <A, E>(self: Enqueue<A, E>) => Effect<boolean>;
 /**
- * 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)
@@ -783,10 +872,7 @@ export declare 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
  *
@@ -797,14 +883,19 @@ export declare const interrupt: <A, E>(self: Enqueue<A, E>) => Effect<boolean>;
  * ```
  *
  * @category Completion
- * @since 4.0.0
+ * @since 2.0.0
  */
 export declare 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"
  *
@@ -833,12 +924,16 @@ export declare const shutdown: <A, E>(self: Enqueue<A, E>) => Effect<boolean>;
  */
 export declare const clear: <A, E>(self: Dequeue<A, E>) => Effect<Array<A>, Pull.ExcludeDone<E>>;
 /**
- * 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.
+ *
+ * **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.
  *
- * If the queue is done, the `done` flag will be `true`. If the queue
- * fails, the Effect will fail with the error.
+ * **Example** (Taking all available values)
  *
- * @example
  * ```ts
  * import { Cause, Effect, Queue } from "effect"
  *
@@ -855,13 +950,14 @@ export declare const clear: <A, E>(self: Dequeue<A, E>) => Effect<Array<A>, Pull
  * ```
  *
  * @category Taking
- * @since 4.0.0
+ * @since 2.0.0
  */
 export declare const takeAll: <A, E>(self: Dequeue<A, E>) => Effect<Arr.NonEmptyArray<A>, E>;
 /**
  * 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"
  *
@@ -884,13 +980,17 @@ export declare const takeAll: <A, E>(self: Dequeue<A, E>) => Effect<Arr.NonEmpty
  */
 export declare const collect: <A, E>(self: Dequeue<A, E | Done>) => Effect<Array<A>, Pull.ExcludeDone<E>>;
 /**
- * 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**
  *
- * If the queue is done, the `done` flag will be `true`. If the queue
- * fails, the Effect will fail with the error.
+ * 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.
+ *
+ * **Example** (Taking a fixed number of values)
  *
- * @example
  * ```ts
  * import { Cause, Effect, Queue } from "effect"
  *
@@ -908,27 +1008,28 @@ export declare const collect: <A, E>(self: Dequeue<A, E | Done>) => Effect<Array
  *   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]
  * })
  * ```
  *
  * @category Taking
- * @since 4.0.0
+ * @since 2.0.0
  */
 export declare const takeN: <A, E>(self: Dequeue<A, E>, n: number) => Effect<Array<A>, E>;
 /**
- * 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.
  *
- * If the queue is done, the `done` flag will be `true`. If the queue
- * fails, the Effect will fail with the error.
+ * **Details**
+ *
+ * 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"
  *
@@ -952,7 +1053,7 @@ export declare const takeN: <A, E>(self: Dequeue<A, E>, n: number) => Effect<Arr
  * ```
  *
  * @category Taking
- * @since 4.0.0
+ * @since 2.0.0
  */
 export declare const takeBetween: <A, E>(self: Dequeue<A, E>, min: number, max: number) => Effect<Array<A>, E>;
 /**
@@ -962,7 +1063,8 @@ export declare const takeBetween: <A, E>(self: Dequeue<A, E>, min: number, max:
  * 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"
  *
@@ -981,7 +1083,7 @@ export declare const takeBetween: <A, E>(self: Dequeue<A, E>, min: number, max:
  *   // 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
@@ -991,15 +1093,20 @@ export declare const takeBetween: <A, E>(self: Dequeue<A, E>, min: number, max:
  * ```
  *
  * @category Taking
- * @since 4.0.0
+ * @since 2.0.0
  */
 export declare 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.
+ *
+ * **Details**
  *
- * Returns `Option.some` with the item if available, or `Option.none` if the queue is empty or done.
+ * 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"
  *
@@ -1020,7 +1127,7 @@ export declare const take: <A, E>(self: Dequeue<A, E>) => Effect<A, E>;
  * ```
  *
  * @category Taking
- * @since 4.0.0
+ * @since 2.0.0
  */
 export declare const poll: <A, E>(self: Dequeue<A, E>) => Effect<Option.Option<A>>;
 /**
@@ -1028,7 +1135,8 @@ export declare 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"
  *
@@ -1047,16 +1155,16 @@ export declare const poll: <A, E>(self: Dequeue<A, E>) => Effect<Option.Option<A
  */
 export declare 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"
  *
@@ -1095,11 +1203,14 @@ export {
  */
 await_ as await };
 /**
- * Check the size of the queue.
+ * Returns the current number of buffered messages in the queue.
+ *
+ * **Details**
  *
- * If the queue is complete, it will return `None`.
+ * Completed queues report a size of `0`.
+ *
+ * **Example** (Checking queue size)
  *
- * @example
  * ```ts
  * import { Cause, Effect, Option, Queue } from "effect"
  *
@@ -1127,13 +1238,14 @@ await_ as await };
  * ```
  *
  * @category Size
- * @since 4.0.0
+ * @since 2.0.0
  */
 export declare const size: <A, E>(self: Dequeue<A, E>) => Effect<number>;
 /**
  * Check if the queue is full.
  *
- * @example
+ * **Example** (Checking if queues are full)
+ *
  * ```ts
  * import { Cause, Effect, Option, Queue } from "effect"
  *
@@ -1150,16 +1262,19 @@ export declare const size: <A, E>(self: Dequeue<A, E>) => Effect<number>;
  * ```
  *
  * @category Size
- * @since 4.0.0
+ * @since 2.0.0
  */
 export declare const isFull: <A, E>(self: Dequeue<A, E>) => Effect<boolean>;
 /**
- * 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"
  *
@@ -1195,7 +1310,8 @@ export declare const sizeUnsafe: <A, E>(self: Dequeue<A, E>) => number;
 /**
  * Check if the queue is full synchronously.
  *
- * @example
+ * **Example** (Checking fullness synchronously)
+ *
  * ```ts
  * import { Cause, Effect, Option, Queue } from "effect"
  *
@@ -1219,7 +1335,8 @@ export declare const isFullUnsafe: <A, E>(self: Dequeue<A, E>) => boolean;
  * 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"
  *
@@ -1245,15 +1362,16 @@ export declare const isFullUnsafe: <A, E>(self: Dequeue<A, E>) => boolean;
  * })
  * ```
  *
- * @since 3.8.0
  * @category Completion
+ * @since 4.0.0
  */
 export declare 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"
      *
@@ -1279,15 +1397,16 @@ export declare const into: {
      * })
      * ```
      *
-     * @since 3.8.0
      * @category Completion
+     * @since 4.0.0
      */
     <A, E>(self: Enqueue<A, E | Done>): <AX, EX extends E, RX>(effect: Effect<AX, EX, RX>) => Effect<boolean, never, RX>;
     /**
      * 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"
      *
@@ -1313,8 +1432,8 @@ export declare const into: {
      * })
      * ```
      *
-     * @since 3.8.0
      * @category Completion
+     * @since 4.0.0
      */
     <AX, E, EX extends E, RX, A>(effect: Effect<AX, EX, RX>, self: Enqueue<A, E | Done>): Effect<boolean, never, RX>;
 };