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

package/dist/Queue.js

@@ -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.js";
@@ -16,36 +68,36 @@ 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 const isQueue = u => hasProperty(u, TypeId);
 /**
  * Type guard to check if a value is an Enqueue.
  *
- * @since 4.0.0
- * @category Guards
+ * @category guards
+ * @since 2.0.0
  */
 export const isEnqueue = u => hasProperty(u, EnqueueTypeId);
 /**
  * Type guard to check if a value is a Dequeue.
  *
- * @since 4.0.0
- * @category Guards
+ * @category guards
+ * @since 2.0.0
  */
 export const isDequeue = u => hasProperty(u, DequeueTypeId);
 /**
  * Converts a Queue to an Enqueue (write-only interface).
  *
+ * @category converting
  * @since 4.0.0
- * @category Conversions
  */
 export const asEnqueue = self => self;
 /**
  * Convert a Queue to a Dequeue, allowing only read operations.
  *
+ * @category converting
  * @since 4.0.0
- * @category Conversions
  */
 export const asDequeue = identity;
 const variance = {
@@ -66,22 +118,17 @@ 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**
+ * **Example** (Creating queues)
  *
- * This API replaces the following from Effect 3.x:
- *
- * - `Mailbox.make`
- *
- * @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>()
@@ -93,17 +140,22 @@ 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
  * })
  * ```
+ *
+ * @category constructors
+ * @since 4.0.0
  */
 export const make = options => core.withFiber(fiber => {
   const self = Object.create(QueueProto);
@@ -126,9 +178,10 @@ export const make = options => core.withFiber(fiber => {
  * 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)
@@ -142,8 +195,8 @@ export const make = options => core.withFiber(fiber => {
  * })
  * ```
  *
+ * @category constructors
  * @since 2.0.0
- * @category Constructors
  */
 export const bounded = capacity => make({
   capacity
@@ -155,9 +208,10 @@ export const bounded = capacity => make({
  * 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)
@@ -175,8 +229,8 @@ export const bounded = capacity => make({
  * })
  * ```
  *
+ * @category constructors
  * @since 2.0.0
- * @category Constructors
  */
 export const sliding = capacity => make({
   capacity,
@@ -189,9 +243,10 @@ export const sliding = capacity => make({
  * 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)
@@ -210,8 +265,8 @@ export const sliding = capacity => make({
  * })
  * ```
  *
+ * @category constructors
  * @since 2.0.0
- * @category Constructors
  */
 export const dropping = capacity => make({
   capacity,
@@ -224,9 +279,10 @@ export const dropping = capacity => make({
  * 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>()
@@ -238,7 +294,7 @@ export const dropping = capacity => make({
  *
  *   // 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)
@@ -246,8 +302,8 @@ export const dropping = capacity => make({
  * })
  * ```
  *
+ * @category constructors
  * @since 2.0.0
- * @category Constructors
  */
 export const unbounded = () => make();
 /**
@@ -257,9 +313,10 @@ export const unbounded = () => 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)
@@ -276,7 +333,7 @@ export const unbounded = () => make();
  * ```
  *
  * @category Offering
- * @since 4.0.0
+ * @since 2.0.0
  */
 export const offer = (self, message) => internalEffect.suspend(() => {
   if (self.state._tag !== "Open") {
@@ -308,7 +365,8 @@ export const offer = (self, message) => internalEffect.suspend(() => {
  * 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"
  *
@@ -357,21 +415,22 @@ export const offerUnsafe = (self, message) => {
  * 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 const offerAll = (self, messages) => internalEffect.suspend(() => {
   if (self.state._tag !== "Open") {
@@ -391,7 +450,8 @@ export const offerAll = (self, messages) => internalEffect.suspend(() => {
  *
  * 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"
  *
@@ -444,23 +504,21 @@ export const offerAllUnsafe = (self, messages) => {
  * 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"
  * })
  * ```
  *
@@ -472,22 +530,21 @@ export const fail = (self, error) => failCause(self, core.causeFail(error));
  * 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"
  * })
  * ```
  *
@@ -501,23 +558,20 @@ export const failCause = /*#__PURE__*/dual(2, (self, cause) => internalEffect.sy
  *
  * 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"
  * })
  * ```
@@ -546,7 +600,8 @@ export const failCauseUnsafe = (self, cause) => {
  * 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"
  *
@@ -581,7 +636,8 @@ export const end = self => failCause(self, core.causeFail(core.Done()));
  *
  * 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"
  *
@@ -597,7 +653,13 @@ export const end = self => failCause(self, core.causeFail(core.Done()));
  *   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"
  * })
  * ```
@@ -612,7 +674,8 @@ export const endUnsafe = self => failCauseUnsafe(self, core.causeFail(core.Done(
  * 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"
  *
@@ -649,12 +712,18 @@ export const endUnsafe = self => failCauseUnsafe(self, core.causeFail(core.Done(
  */
 export const interrupt = self => 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)
@@ -663,10 +732,7 @@ export const interrupt = self => core.withFiber(fiber => failCause(self, interna
  *   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
  *
@@ -677,7 +743,7 @@ export const interrupt = self => core.withFiber(fiber => failCause(self, interna
  * ```
  *
  * @category Completion
- * @since 4.0.0
+ * @since 2.0.0
  */
 export const shutdown = self => internalEffect.sync(() => {
   if (self.state._tag === "Done") {
@@ -699,10 +765,15 @@ export const shutdown = self => internalEffect.sync(() => {
   return true;
 });
 /**
- * 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"
  *
@@ -741,12 +812,16 @@ export const clear = self => internalEffect.suspend(() => {
   return internalEffect.succeed(messages);
 });
 /**
- * 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"
  *
@@ -763,13 +838,14 @@ export const clear = self => internalEffect.suspend(() => {
  * ```
  *
  * @category Taking
- * @since 4.0.0
+ * @since 2.0.0
  */
 export const takeAll = self => takeBetween(self, 1, Number.POSITIVE_INFINITY);
 /**
  * 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"
  *
@@ -803,13 +879,17 @@ export const collect = self => internalEffect.suspend(() => {
   }), () => internalEffect.void), out);
 });
 /**
- * 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.
  *
- * 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 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"
  *
@@ -827,27 +907,28 @@ export const collect = self => internalEffect.suspend(() => {
  *   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 const takeN = (self, n) => 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"
  *
@@ -871,7 +952,7 @@ export const takeN = (self, n) => takeBetween(self, n, n);
  * ```
  *
  * @category Taking
- * @since 4.0.0
+ * @since 2.0.0
  */
 export const takeBetween = (self, min, max) => internalEffect.suspend(() => takeBetweenUnsafe(self, min, max) ?? internalEffect.andThen(awaitTake(self), takeBetween(self, 1, max)));
 /**
@@ -881,7 +962,8 @@ export const takeBetween = (self, min, max) => internalEffect.suspend(() => take
  * 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"
  *
@@ -900,7 +982,7 @@ export const takeBetween = (self, min, max) => internalEffect.suspend(() => take
  *   // 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
@@ -910,15 +992,20 @@ export const takeBetween = (self, min, max) => internalEffect.suspend(() => take
  * ```
  *
  * @category Taking
- * @since 4.0.0
+ * @since 2.0.0
  */
 export const take = self => internalEffect.suspend(() => takeUnsafe(self) ?? internalEffect.andThen(awaitTake(self), take(self)));
 /**
- * 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"
  *
@@ -939,7 +1026,7 @@ export const take = self => internalEffect.suspend(() => takeUnsafe(self) ?? int
  * ```
  *
  * @category Taking
- * @since 4.0.0
+ * @since 2.0.0
  */
 export const poll = self => internalEffect.suspend(() => {
   const result = takeUnsafe(self);
@@ -956,7 +1043,8 @@ export const poll = self => internalEffect.suspend(() => {
  *
  * 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"
  *
@@ -983,16 +1071,16 @@ export const peek = self => internalEffect.suspend(() => {
   return internalEffect.andThen(awaitTake(self), peek(self));
 });
 /**
- * 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**
  *
- * This is an unsafe operation that directly accesses the queue without Effect wrapping.
+ * 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.
+ *
+ * **Example** (Taking one value synchronously)
  *
- * @example
  * ```ts
  * import { Effect, Queue } from "effect"
  *
@@ -1061,11 +1149,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"
  *
@@ -1093,13 +1184,14 @@ await_ as await };
  * ```
  *
  * @category Size
- * @since 4.0.0
+ * @since 2.0.0
  */
 export const size = self => internalEffect.sync(() => sizeUnsafe(self));
 /**
  * Check if the queue is full.
  *
- * @example
+ * **Example** (Checking if queues are full)
+ *
  * ```ts
  * import { Cause, Effect, Option, Queue } from "effect"
  *
@@ -1116,16 +1208,19 @@ export const size = self => internalEffect.sync(() => sizeUnsafe(self));
  * ```
  *
  * @category Size
- * @since 4.0.0
+ * @since 2.0.0
  */
 export const isFull = self => 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"
  *
@@ -1161,7 +1256,8 @@ export const sizeUnsafe = self => self.state._tag === "Done" ? 0 : self.messages
 /**
  * Check if the queue is full synchronously.
  *
- * @example
+ * **Example** (Checking fullness synchronously)
+ *
  * ```ts
  * import { Cause, Effect, Option, Queue } from "effect"
  *
@@ -1185,7 +1281,8 @@ export const isFullUnsafe = self => sizeUnsafe(self) === self.capacity;
  * 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"
  *
@@ -1211,8 +1308,8 @@ export const isFullUnsafe = self => sizeUnsafe(self) === self.capacity;
  * })
  * ```
  *
- * @since 3.8.0
  * @category Completion
+ * @since 4.0.0
  */
 export const into = /*#__PURE__*/dual(2, (effect, self) => internalEffect.uninterruptibleMask(restore => internalEffect.matchCauseEffect(restore(effect), {
   onFailure: cause => failCause(self, cause),