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

package/dist/TxQueue.d.ts

@@ -26,7 +26,8 @@ import type * as Types from "./Types.ts";
  * - **Closing**: No new offers accepted, serving remaining items until empty
  * - **Done**: Terminal state with completion cause, no further operations possible
  *
- * @example
+ * **Example** (Inspecting queue lifecycle states)
+ *
  * ```ts
  * import type { TxQueue } from "effect"
  *
@@ -42,8 +43,8 @@ import type * as Types from "./Types.ts";
  * }
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export type State<_A, E> = {
     readonly _tag: "Open";
@@ -60,31 +61,14 @@ declare const TypeId = "~effect/transactions/TxQueue";
 /**
  * Namespace containing type definitions for TxEnqueue variance annotations.
  *
- * @example
- * ```ts
- * import type { TxQueue } from "effect"
- *
- * // Use variance types for type-level operations
- * declare const variance: TxQueue.TxEnqueue.Variance<number, Error>
- * ```
- *
  * @since 4.0.0
- * @category models
  */
 export declare namespace TxEnqueue {
     /**
      * Variance annotation interface for TxEnqueue contravariance.
      *
-     * @example
-     * ```ts
-     * import type { TxQueue } from "effect"
-     *
-     * // Demonstrates contravariant type behavior for both A and E
-     * declare const variance: TxQueue.TxEnqueue.Variance<string, Error>
-     * ```
-     *
-     * @since 4.0.0
      * @category models
+     * @since 4.0.0
      */
     interface Variance<in A, in E> {
         readonly _A: Types.Contravariant<A>;
@@ -94,31 +78,14 @@ export declare namespace TxEnqueue {
 /**
  * Namespace containing type definitions for TxDequeue variance annotations.
  *
- * @example
- * ```ts
- * import type { TxQueue } from "effect"
- *
- * // Use variance types for type-level operations
- * declare const variance: TxQueue.TxDequeue.Variance<number, Error>
- * ```
- *
  * @since 4.0.0
- * @category models
  */
 export declare namespace TxDequeue {
     /**
      * Variance annotation interface for TxDequeue covariance.
      *
-     * @example
-     * ```ts
-     * import type { TxQueue } from "effect"
-     *
-     * // Demonstrates covariant type behavior for both A and E
-     * declare const variance: TxQueue.TxDequeue.Variance<string, Error>
-     * ```
-     *
-     * @since 4.0.0
      * @category models
+     * @since 4.0.0
      */
     interface Variance<out A, out E> {
         readonly _A: Types.Covariant<A>;
@@ -128,31 +95,14 @@ export declare namespace TxDequeue {
 /**
  * Namespace containing type definitions for TxQueue variance annotations.
  *
- * @example
- * ```ts
- * import type { TxQueue } from "effect"
- *
- * // Use variance types for type-level operations
- * declare const variance: TxQueue.TxQueue.Variance<number, Error>
- * ```
- *
  * @since 4.0.0
- * @category models
  */
 export declare namespace TxQueue {
     /**
      * Variance annotation interface for TxQueue invariance.
      *
-     * @example
-     * ```ts
-     * import type { TxQueue } from "effect"
-     *
-     * // Demonstrates invariant type behavior for both A and E
-     * declare const variance: TxQueue.TxQueue.Variance<string, Error>
-     * ```
-     *
-     * @since 4.0.0
      * @category models
+     * @since 4.0.0
      */
     interface Variance<in out A, in out E> {
         readonly _A: Types.Invariant<A>;
@@ -164,8 +114,8 @@ export declare namespace TxQueue {
  * This interface contains the core properties needed for queue state inspection
  * operations like size, capacity, and completion status.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface TxQueueState extends Inspectable {
     readonly strategy: "bounded" | "unbounded" | "dropping" | "sliding";
@@ -177,10 +127,11 @@ export interface TxQueueState extends Inspectable {
  * A TxEnqueue represents the write-only interface of a transactional queue, providing
  * operations for adding elements (enqueue operations) and inspecting queue state.
  *
- * @example
+ * **Example** (Offering values through enqueue handles)
+ *
  * ```ts
- * import type { Cause } from "effect"
  * import { Effect, TxQueue } from "effect"
+ * import type { Cause } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   // Queue without error channel
@@ -202,8 +153,8 @@ export interface TxQueueState extends Inspectable {
  * })
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface TxEnqueue<in A, in E = never> extends TxQueueState {
     readonly [EnqueueTypeId]: TxEnqueue.Variance<A, E>;
@@ -212,18 +163,20 @@ export interface TxEnqueue<in A, in E = never> extends TxQueueState {
  * A TxDequeue represents the read-only interface of a transactional queue, providing
  * operations for consuming elements (dequeue operations) and inspecting queue state.
  *
- * @example
+ * **Example** (Taking values through dequeue handles)
+ *
  * ```ts
  * import { Effect, TxQueue } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   // Queue without error channel
  *   const queue = yield* TxQueue.bounded<number>(10)
+ *   yield* TxQueue.offer(queue, 42)
  *   const item = yield* TxQueue.take(queue)
+ *   console.log(item) // 42
  *
  *   // Queue with error channel - errors propagate through E-channel
  *   const faultTolerantQueue = yield* TxQueue.bounded<number, string>(10)
- *   yield* TxQueue.offer(faultTolerantQueue, 42)
  *   yield* TxQueue.fail(faultTolerantQueue, "processing failed")
  *
  *   // All dequeue operations now fail with the error directly
@@ -232,8 +185,8 @@ export interface TxEnqueue<in A, in E = never> extends TxQueueState {
  * })
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface TxDequeue<out A, out E = never> extends TxQueueState {
     readonly [DequeueTypeId]: TxDequeue.Variance<A, E>;
@@ -242,7 +195,8 @@ export interface TxDequeue<out A, out E = never> extends TxQueueState {
  * A TxQueue represents a transactional queue data structure that provides both
  * enqueue and dequeue operations with Software Transactional Memory (STM) semantics.
  *
- * @example
+ * **Example** (Combining enqueue and dequeue operations)
+ *
  * ```ts
  * import { Effect, TxQueue } from "effect"
  *
@@ -259,13 +213,14 @@ export interface TxDequeue<out A, out E = never> extends TxQueueState {
  *   const faultTolerantQueue = yield* TxQueue.bounded<number, string>(10)
  *
  *   // Operations can handle queue-level failures
- *   yield* TxQueue.shutdown(faultTolerantQueue)
- *   const result = yield* Effect.flip(TxQueue.take(faultTolerantQueue)) // never
+ *   yield* TxQueue.fail(faultTolerantQueue, "queue failed")
+ *   const result = yield* Effect.flip(TxQueue.take(faultTolerantQueue))
+ *   console.log(result) // "queue failed"
  * })
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface TxQueue<in out A, in out E = never> extends TxEnqueue<A, E>, TxDequeue<A, E> {
     readonly [TypeId]: TxQueue.Variance<A, E>;
@@ -273,7 +228,8 @@ export interface TxQueue<in out A, in out E = never> extends TxEnqueue<A, E>, Tx
 /**
  * Checks if the given value is a TxEnqueue.
  *
- * @example
+ * **Example** (Checking enqueue handles)
+ *
  * ```ts
  * import { TxQueue } from "effect"
  *
@@ -285,14 +241,15 @@ export interface TxQueue<in out A, in out E = never> extends TxEnqueue<A, E>, Tx
  * }
  * ```
  *
- * @since 4.0.0
  * @category guards
+ * @since 4.0.0
  */
 export declare const isTxEnqueue: <A = unknown, E = unknown>(u: unknown) => u is TxEnqueue<A, E>;
 /**
  * Checks if the given value is a TxDequeue.
  *
- * @example
+ * **Example** (Checking dequeue handles)
+ *
  * ```ts
  * import { TxQueue } from "effect"
  *
@@ -304,14 +261,15 @@ export declare const isTxEnqueue: <A = unknown, E = unknown>(u: unknown) => u is
  * }
  * ```
  *
- * @since 4.0.0
  * @category guards
+ * @since 4.0.0
  */
 export declare const isTxDequeue: <A = unknown, E = unknown>(u: unknown) => u is TxDequeue<A, E>;
 /**
  * Checks if the given value is a TxQueue.
  *
- * @example
+ * **Example** (Checking queue handles)
+ *
  * ```ts
  * import { TxQueue } from "effect"
  *
@@ -323,8 +281,8 @@ export declare const isTxDequeue: <A = unknown, E = unknown>(u: unknown) => u is
  * }
  * ```
  *
- * @since 4.0.0
  * @category guards
+ * @since 4.0.0
  */
 export declare const isTxQueue: <A = unknown, E = unknown>(u: unknown) => u is TxQueue<A, E>;
 /**
@@ -333,7 +291,8 @@ export declare const isTxQueue: <A = unknown, E = unknown>(u: unknown) => u is T
  * **Return behavior**: This function returns a new TxQueue reference with
  * the specified capacity. No existing TxQueue instances are modified.
  *
- * @example
+ * **Example** (Creating bounded queues)
+ *
  * ```ts
  * import { Effect, TxQueue } from "effect"
  *
@@ -353,8 +312,8 @@ export declare const isTxQueue: <A = unknown, E = unknown>(u: unknown) => u is T
  * })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const bounded: <A = never, E = never>(capacity: number) => Effect.Effect<TxQueue<A, E>>;
 /**
@@ -363,7 +322,8 @@ export declare const bounded: <A = never, E = never>(capacity: number) => Effect
  * **Return behavior**: This function returns a new TxQueue reference with
  * unlimited capacity. No existing TxQueue instances are modified.
  *
- * @example
+ * **Example** (Creating unbounded queues)
+ *
  * ```ts
  * import { Effect, TxQueue } from "effect"
  *
@@ -383,8 +343,8 @@ export declare const bounded: <A = never, E = never>(capacity: number) => Effect
  * })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const unbounded: <A = never, E = never>() => Effect.Effect<TxQueue<A, E>>;
 /**
@@ -393,7 +353,8 @@ export declare const unbounded: <A = never, E = never>() => Effect.Effect<TxQueu
  * **Return behavior**: This function returns a new TxQueue reference with
  * dropping strategy. No existing TxQueue instances are modified.
  *
- * @example
+ * **Example** (Creating dropping queues)
+ *
  * ```ts
  * import { Effect, TxQueue } from "effect"
  *
@@ -411,8 +372,8 @@ export declare const unbounded: <A = never, E = never>() => Effect.Effect<TxQueu
  * })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const dropping: <A = never, E = never>(capacity: number) => Effect.Effect<TxQueue<A, E>>;
 /**
@@ -421,7 +382,8 @@ export declare const dropping: <A = never, E = never>(capacity: number) => Effec
  * **Return behavior**: This function returns a new TxQueue reference with
  * sliding strategy. No existing TxQueue instances are modified.
  *
- * @example
+ * **Example** (Creating sliding queues)
+ *
  * ```ts
  * import { Effect, TxQueue } from "effect"
  *
@@ -441,17 +403,22 @@ export declare const dropping: <A = never, E = never>(capacity: number) => Effec
  * })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const sliding: <A = never, E = never>(capacity: number) => Effect.Effect<TxQueue<A, E>>;
 /**
- * Offers an item to the queue.
+ * Offers an item to the queue and returns whether it was accepted.
+ *
+ * Open unbounded queues always accept; open bounded queues retry while full;
+ * dropping queues return `false` when full; sliding queues evict the oldest item
+ * when full. Closing or done queues return `false`.
  *
  * **Mutation behavior**: This function mutates the original TxQueue by adding
  * the item according to the queue's strategy. It does not return a new TxQueue reference.
  *
- * @example
+ * **Example** (Offering a value)
+ *
  * ```ts
  * import { Effect, TxQueue } from "effect"
  *
@@ -464,17 +431,22 @@ export declare const sliding: <A = never, E = never>(capacity: number) => Effect
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export declare const offer: {
     /**
-     * Offers an item to the queue.
+     * Offers an item to the queue and returns whether it was accepted.
+     *
+     * Open unbounded queues always accept; open bounded queues retry while full;
+     * dropping queues return `false` when full; sliding queues evict the oldest item
+     * when full. Closing or done queues return `false`.
      *
      * **Mutation behavior**: This function mutates the original TxQueue by adding
      * the item according to the queue's strategy. It does not return a new TxQueue reference.
      *
-     * @example
+     * **Example** (Offering a value)
+     *
      * ```ts
      * import { Effect, TxQueue } from "effect"
      *
@@ -487,17 +459,22 @@ export declare const offer: {
      * })
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 2.0.0
      */
     <A, E>(value: A): (self: TxEnqueue<A, E>) => Effect.Effect<boolean>;
     /**
-     * Offers an item to the queue.
+     * Offers an item to the queue and returns whether it was accepted.
+     *
+     * Open unbounded queues always accept; open bounded queues retry while full;
+     * dropping queues return `false` when full; sliding queues evict the oldest item
+     * when full. Closing or done queues return `false`.
      *
      * **Mutation behavior**: This function mutates the original TxQueue by adding
      * the item according to the queue's strategy. It does not return a new TxQueue reference.
      *
-     * @example
+     * **Example** (Offering a value)
+     *
      * ```ts
      * import { Effect, TxQueue } from "effect"
      *
@@ -510,22 +487,26 @@ export declare const offer: {
      * })
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 2.0.0
      */
     <A, E>(self: TxEnqueue<A, E>, value: A): Effect.Effect<boolean>;
 };
 /**
- * Offers multiple items to the queue.
+ * Offers multiple items to the queue, returning the items that were not
+ * accepted.
  *
- * Returns an array of items that were rejected (not added to the queue).
+ * Each item follows `offer` semantics: bounded queues retry while full,
+ * dropping queues reject new items when full, sliding queues evict old items to
+ * accept new items, and closing or done queues reject all items.
  *
  * **Mutation behavior**: This function mutates the original TxQueue by adding
  * items according to the queue's strategy. It does not return a new TxQueue reference.
  *
- * @example
+ * **Example** (Offering multiple values)
+ *
  * ```ts
- * import { Chunk, Effect, TxQueue } from "effect"
+ * import { Effect, TxQueue } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const queue = yield* TxQueue.bounded<number>(10)
@@ -537,21 +518,25 @@ export declare const offer: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export declare const offerAll: {
     /**
-     * Offers multiple items to the queue.
+     * Offers multiple items to the queue, returning the items that were not
+     * accepted.
      *
-     * Returns an array of items that were rejected (not added to the queue).
+     * Each item follows `offer` semantics: bounded queues retry while full,
+     * dropping queues reject new items when full, sliding queues evict old items to
+     * accept new items, and closing or done queues reject all items.
      *
      * **Mutation behavior**: This function mutates the original TxQueue by adding
      * items according to the queue's strategy. It does not return a new TxQueue reference.
      *
-     * @example
+     * **Example** (Offering multiple values)
+     *
      * ```ts
-     * import { Chunk, Effect, TxQueue } from "effect"
+     * import { Effect, TxQueue } from "effect"
      *
      * const program = Effect.gen(function*() {
      *   const queue = yield* TxQueue.bounded<number>(10)
@@ -563,21 +548,25 @@ export declare const offerAll: {
      * })
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 2.0.0
      */
     <A, E>(values: Iterable<A>): (self: TxEnqueue<A, E>) => Effect.Effect<Array<A>>;
     /**
-     * Offers multiple items to the queue.
+     * Offers multiple items to the queue, returning the items that were not
+     * accepted.
      *
-     * Returns an array of items that were rejected (not added to the queue).
+     * Each item follows `offer` semantics: bounded queues retry while full,
+     * dropping queues reject new items when full, sliding queues evict old items to
+     * accept new items, and closing or done queues reject all items.
      *
      * **Mutation behavior**: This function mutates the original TxQueue by adding
      * items according to the queue's strategy. It does not return a new TxQueue reference.
      *
-     * @example
+     * **Example** (Offering multiple values)
+     *
      * ```ts
-     * import { Chunk, Effect, TxQueue } from "effect"
+     * import { Effect, TxQueue } from "effect"
      *
      * const program = Effect.gen(function*() {
      *   const queue = yield* TxQueue.bounded<number>(10)
@@ -589,18 +578,22 @@ export declare const offerAll: {
      * })
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 2.0.0
      */
     <A, E>(self: TxEnqueue<A, E>, values: Iterable<A>): Effect.Effect<Array<A>>;
 };
 /**
- * Takes an item from the queue.
+ * Takes the next item from the queue, retrying the transaction while the queue
+ * is empty.
+ *
+ * If the queue is done, the effect fails with the queue's completion cause.
  *
  * **Mutation behavior**: This function mutates the original TxQueue by removing
  * the first item. It does not return a new TxQueue reference.
  *
- * @example
+ * **Example** (Taking a value)
+ *
  * ```ts
  * import { Effect, TxQueue } from "effect"
  *
@@ -619,14 +612,15 @@ export declare const offerAll: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export declare const take: <A, E>(self: TxDequeue<A, E>) => Effect.Effect<A, E>;
 /**
  * Tries to take an item from the queue without blocking.
  *
- * @example
+ * **Example** (Polling without blocking)
+ *
  * ```ts
  * import { Effect, Option, TxQueue } from "effect"
  *
@@ -643,8 +637,8 @@ export declare const take: <A, E>(self: TxDequeue<A, E>) => Effect.Effect<A, E>;
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export declare const poll: <A, E>(self: TxDequeue<A, E>) => Effect.Effect<Option.Option<A>>;
 /**
@@ -658,7 +652,8 @@ export declare const poll: <A, E>(self: TxDequeue<A, E>) => Effect.Effect<Option
  * **Mutation behavior**: This function mutates the original TxQueue by removing
  * all items. It does not return a new TxQueue reference.
  *
- * @example
+ * **Example** (Taking all queued values)
+ *
  * ```ts
  * import { Array, Effect, TxQueue } from "effect"
  *
@@ -684,124 +679,127 @@ export declare const poll: <A, E>(self: TxDequeue<A, E>) => Effect.Effect<Option
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export declare const takeAll: <A, E>(self: TxDequeue<A, E>) => Effect.Effect<Arr.NonEmptyArray<A>, E>;
 /**
- * Takes exactly N items from the queue in a single atomic transaction.
+ * Takes up to `n` items from the queue in a single transaction.
  *
- * This function waits (retries the transaction) until N items are available, then takes
- * exactly N items. The only exception is when N exceeds the queue's capacity - in that
- * case, it takes up to the queue's capacity and returns immediately.
- *
- * **Behavior**:
- * - **Normal case**: Waits for exactly N items to be available
- * - **Bounded queue with N > capacity**: Takes up to capacity items immediately
- * - **Closing queue**: Takes available items and transitions to Done state
+ * For an open queue, waits until `min(n, capacity)` items are available, then
+ * removes that many items. If `n` is less than or equal to zero, returns an
+ * empty array without modifying the queue. If the queue is closing, drains the
+ * currently available items and transitions to `Done`. If the queue is already
+ * done, the effect fails with the queue's completion cause.
  *
  * **Mutation behavior**: This function mutates the original TxQueue by removing
  * the taken items. It does not return a new TxQueue reference.
  *
- * @example
+ * **Example** (Taking a fixed number of values)
+ *
  * ```ts
  * import { Effect, TxQueue } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const queue = yield* TxQueue.bounded<number>(5)
- *   yield* TxQueue.offerAll(queue, [1, 2, 3])
+ *   yield* TxQueue.offerAll(queue, [1, 2, 3, 4])
  *
- *   // This will wait until 4 items are available
- *   // (will retry transaction until more items are offered)
  *   const items = yield* TxQueue.takeN(queue, 4)
+ *   console.log(items) // [1, 2, 3, 4]
  *
  *   // This requests more than capacity (5), so takes all available (up to 5)
- *   const all = yield* TxQueue.takeN(queue, 10) // Takes at most 5 items
+ *   yield* TxQueue.offerAll(queue, [5, 6, 7, 8, 9])
+ *   const all = yield* TxQueue.takeN(queue, 10)
+ *   console.log(all) // [5, 6, 7, 8, 9]
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export declare const takeN: {
     /**
-     * Takes exactly N items from the queue in a single atomic transaction.
-     *
-     * This function waits (retries the transaction) until N items are available, then takes
-     * exactly N items. The only exception is when N exceeds the queue's capacity - in that
-     * case, it takes up to the queue's capacity and returns immediately.
+     * Takes up to `n` items from the queue in a single transaction.
      *
-     * **Behavior**:
-     * - **Normal case**: Waits for exactly N items to be available
-     * - **Bounded queue with N > capacity**: Takes up to capacity items immediately
-     * - **Closing queue**: Takes available items and transitions to Done state
+     * For an open queue, waits until `min(n, capacity)` items are available, then
+     * removes that many items. If `n` is less than or equal to zero, returns an
+     * empty array without modifying the queue. If the queue is closing, drains the
+     * currently available items and transitions to `Done`. If the queue is already
+     * done, the effect fails with the queue's completion cause.
      *
      * **Mutation behavior**: This function mutates the original TxQueue by removing
      * the taken items. It does not return a new TxQueue reference.
      *
-     * @example
+     * **Example** (Taking a fixed number of values)
+     *
      * ```ts
      * import { Effect, TxQueue } from "effect"
      *
      * const program = Effect.gen(function*() {
      *   const queue = yield* TxQueue.bounded<number>(5)
-     *   yield* TxQueue.offerAll(queue, [1, 2, 3])
+     *   yield* TxQueue.offerAll(queue, [1, 2, 3, 4])
      *
-     *   // This will wait until 4 items are available
-     *   // (will retry transaction until more items are offered)
      *   const items = yield* TxQueue.takeN(queue, 4)
+     *   console.log(items) // [1, 2, 3, 4]
      *
      *   // This requests more than capacity (5), so takes all available (up to 5)
-     *   const all = yield* TxQueue.takeN(queue, 10) // Takes at most 5 items
+     *   yield* TxQueue.offerAll(queue, [5, 6, 7, 8, 9])
+     *   const all = yield* TxQueue.takeN(queue, 10)
+     *   console.log(all) // [5, 6, 7, 8, 9]
      * })
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 2.0.0
      */
     (n: number): <A, E>(self: TxDequeue<A, E>) => Effect.Effect<Array<A>, E>;
     /**
-     * Takes exactly N items from the queue in a single atomic transaction.
-     *
-     * This function waits (retries the transaction) until N items are available, then takes
-     * exactly N items. The only exception is when N exceeds the queue's capacity - in that
-     * case, it takes up to the queue's capacity and returns immediately.
+     * Takes up to `n` items from the queue in a single transaction.
      *
-     * **Behavior**:
-     * - **Normal case**: Waits for exactly N items to be available
-     * - **Bounded queue with N > capacity**: Takes up to capacity items immediately
-     * - **Closing queue**: Takes available items and transitions to Done state
+     * For an open queue, waits until `min(n, capacity)` items are available, then
+     * removes that many items. If `n` is less than or equal to zero, returns an
+     * empty array without modifying the queue. If the queue is closing, drains the
+     * currently available items and transitions to `Done`. If the queue is already
+     * done, the effect fails with the queue's completion cause.
      *
      * **Mutation behavior**: This function mutates the original TxQueue by removing
      * the taken items. It does not return a new TxQueue reference.
      *
-     * @example
+     * **Example** (Taking a fixed number of values)
+     *
      * ```ts
      * import { Effect, TxQueue } from "effect"
      *
      * const program = Effect.gen(function*() {
      *   const queue = yield* TxQueue.bounded<number>(5)
-     *   yield* TxQueue.offerAll(queue, [1, 2, 3])
+     *   yield* TxQueue.offerAll(queue, [1, 2, 3, 4])
      *
-     *   // This will wait until 4 items are available
-     *   // (will retry transaction until more items are offered)
      *   const items = yield* TxQueue.takeN(queue, 4)
+     *   console.log(items) // [1, 2, 3, 4]
      *
      *   // This requests more than capacity (5), so takes all available (up to 5)
-     *   const all = yield* TxQueue.takeN(queue, 10) // Takes at most 5 items
+     *   yield* TxQueue.offerAll(queue, [5, 6, 7, 8, 9])
+     *   const all = yield* TxQueue.takeN(queue, 10)
+     *   console.log(all) // [5, 6, 7, 8, 9]
      * })
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 2.0.0
      */
     <A, E>(self: TxDequeue<A, E>, n: number): Effect.Effect<Array<A>, E>;
 };
 /**
- * Takes a variable number of items between a specified minimum and maximum from the queue.
- * Waits for at least the minimum number of items to be available.
+ * Takes between `min` and `max` currently available items, waiting for `min` on
+ * an open queue.
+ *
+ * If the queue is closing, drains the currently available items even when fewer
+ * than `min` are available and transitions to `Done`. Invalid ranges
+ * (`min <= 0`, `max <= 0`, or `min > max`) return an empty array. If the queue
+ * is already done, the effect fails with the queue's completion cause.
+ *
+ * **Example** (Taking batches within bounds)
  *
- * @example
  * ```ts
  * import { Effect, TxQueue } from "effect"
  *
@@ -822,15 +820,21 @@ export declare const takeN: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category taking
+ * @since 2.0.0
  */
 export declare const takeBetween: {
     /**
-     * Takes a variable number of items between a specified minimum and maximum from the queue.
-     * Waits for at least the minimum number of items to be available.
+     * Takes between `min` and `max` currently available items, waiting for `min` on
+     * an open queue.
+     *
+     * If the queue is closing, drains the currently available items even when fewer
+     * than `min` are available and transitions to `Done`. Invalid ranges
+     * (`min <= 0`, `max <= 0`, or `min > max`) return an empty array. If the queue
+     * is already done, the effect fails with the queue's completion cause.
+     *
+     * **Example** (Taking batches within bounds)
      *
-     * @example
      * ```ts
      * import { Effect, TxQueue } from "effect"
      *
@@ -851,15 +855,21 @@ export declare const takeBetween: {
      * })
      * ```
      *
-     * @since 4.0.0
      * @category taking
+     * @since 2.0.0
      */
     (min: number, max: number): <A, E>(self: TxDequeue<A, E>) => Effect.Effect<Array<A>, E>;
     /**
-     * Takes a variable number of items between a specified minimum and maximum from the queue.
-     * Waits for at least the minimum number of items to be available.
+     * Takes between `min` and `max` currently available items, waiting for `min` on
+     * an open queue.
+     *
+     * If the queue is closing, drains the currently available items even when fewer
+     * than `min` are available and transitions to `Done`. Invalid ranges
+     * (`min <= 0`, `max <= 0`, or `min > max`) return an empty array. If the queue
+     * is already done, the effect fails with the queue's completion cause.
+     *
+     * **Example** (Taking batches within bounds)
      *
-     * @example
      * ```ts
      * import { Effect, TxQueue } from "effect"
      *
@@ -880,16 +890,20 @@ export declare const takeBetween: {
      * })
      * ```
      *
-     * @since 4.0.0
      * @category taking
+     * @since 2.0.0
      */
     <A, E>(self: TxDequeue<A, E>, min: number, max: number): Effect.Effect<Array<A>, E>;
 };
 /**
- * Views the next item without removing it. If the queue is in a failed state,
- * the error is propagated through the E-channel.
+ * Waits transactionally for the next item and returns it without removing it.
+ *
+ * If the queue is open but empty, the transaction retries until an item is
+ * available or the queue completes. If the queue is done, the queue's
+ * completion cause is propagated through the error channel.
+ *
+ * **Example** (Peeking without removing values)
  *
- * @example
  * ```ts
  * import { Effect, TxQueue } from "effect"
  *
@@ -917,14 +931,15 @@ export declare const takeBetween: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export declare const peek: <A, E>(self: TxDequeue<A, E>) => Effect.Effect<A, E>;
 /**
  * Gets the current size of the queue.
  *
- * @example
+ * **Example** (Reading queue size)
+ *
  * ```ts
  * import { Effect, TxQueue } from "effect"
  *
@@ -937,14 +952,15 @@ export declare const peek: <A, E>(self: TxDequeue<A, E>) => Effect.Effect<A, E>;
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export declare const size: (self: TxQueueState) => Effect.Effect<number>;
 /**
  * Checks if the queue is empty.
  *
- * @example
+ * **Example** (Checking whether a queue is empty)
+ *
  * ```ts
  * import { Effect, TxQueue } from "effect"
  *
@@ -960,14 +976,15 @@ export declare const size: (self: TxQueueState) => Effect.Effect<number>;
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export declare const isEmpty: (self: TxQueueState) => Effect.Effect<boolean>;
 /**
  * Checks if the queue is at capacity.
  *
- * @example
+ * **Example** (Checking whether a queue is full)
+ *
  * ```ts
  * import { Effect, TxQueue } from "effect"
  *
@@ -983,17 +1000,20 @@ export declare const isEmpty: (self: TxQueueState) => Effect.Effect<boolean>;
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export declare const isFull: (self: TxQueueState) => Effect.Effect<boolean>;
 /**
- * Interrupts the queue, transitioning it to a closing state.
+ * Gracefully interrupts the queue with the current fiber's interruption cause.
+ *
+ * If the queue still contains items, it enters the closing state so buffered
+ * items can be drained before consumers observe the interruption. If it is
+ * empty, it transitions directly to done. Returns `false` if the queue was
+ * already closing or done.
  *
- * **Mutation behavior**: This function mutates the original TxQueue by marking
- * it for graceful closure. It does not return a new TxQueue reference.
+ * **Example** (Interrupting queues)
  *
- * @example
  * ```ts
  * import { Effect, TxQueue } from "effect"
  *
@@ -1007,17 +1027,18 @@ export declare const isFull: (self: TxQueueState) => Effect.Effect<boolean>;
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const interrupt: <A, E>(self: TxEnqueue<A, E>) => Effect.Effect<boolean>;
 /**
- * Fails the queue with the specified error.
+ * Fails the queue with the specified error, discarding any buffered items.
+ *
+ * The queue transitions directly to done with `Cause.fail(error)`. Returns
+ * `false` if the queue was already closing or done.
  *
- * **Mutation behavior**: This function mutates the original TxQueue by marking
- * it as failed. It does not return a new TxQueue reference.
+ * **Example** (Failing queues)
  *
- * @example
  * ```ts
  * import { Effect, TxQueue } from "effect"
  *
@@ -1030,17 +1051,18 @@ export declare const interrupt: <A, E>(self: TxEnqueue<A, E>) => Effect.Effect<b
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const fail: {
     /**
-     * Fails the queue with the specified error.
+     * Fails the queue with the specified error, discarding any buffered items.
+     *
+     * The queue transitions directly to done with `Cause.fail(error)`. Returns
+     * `false` if the queue was already closing or done.
      *
-     * **Mutation behavior**: This function mutates the original TxQueue by marking
-     * it as failed. It does not return a new TxQueue reference.
+     * **Example** (Failing queues)
      *
-     * @example
      * ```ts
      * import { Effect, TxQueue } from "effect"
      *
@@ -1053,17 +1075,18 @@ export declare const fail: {
      * })
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <E>(error: E): <A>(self: TxEnqueue<A, E>) => Effect.Effect<boolean>;
     /**
-     * Fails the queue with the specified error.
+     * Fails the queue with the specified error, discarding any buffered items.
+     *
+     * The queue transitions directly to done with `Cause.fail(error)`. Returns
+     * `false` if the queue was already closing or done.
      *
-     * **Mutation behavior**: This function mutates the original TxQueue by marking
-     * it as failed. It does not return a new TxQueue reference.
+     * **Example** (Failing queues)
      *
-     * @example
      * ```ts
      * import { Effect, TxQueue } from "effect"
      *
@@ -1076,18 +1099,20 @@ export declare const fail: {
      * })
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <A, E>(self: TxEnqueue<A, E>, error: E): Effect.Effect<boolean>;
 };
 /**
- * Completes the queue with the specified exit value.
+ * Completes the queue with the specified cause.
+ *
+ * If the queue is empty, it transitions directly to done. If it still contains
+ * items, it enters the closing state so buffered items can be drained before the
+ * cause is observed. Returns `false` if the queue was already closing or done.
  *
- * **Mutation behavior**: This function mutates the original TxQueue by marking
- * it as completed. It does not return a new TxQueue reference.
+ * **Example** (Failing queues with causes)
  *
- * @example
  * ```ts
  * import { Cause, Effect, TxQueue } from "effect"
  *
@@ -1101,17 +1126,19 @@ export declare const fail: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const failCause: {
     /**
-     * Completes the queue with the specified exit value.
+     * Completes the queue with the specified cause.
      *
-     * **Mutation behavior**: This function mutates the original TxQueue by marking
-     * it as completed. It does not return a new TxQueue reference.
+     * If the queue is empty, it transitions directly to done. If it still contains
+     * items, it enters the closing state so buffered items can be drained before the
+     * cause is observed. Returns `false` if the queue was already closing or done.
+     *
+     * **Example** (Failing queues with causes)
      *
-     * @example
      * ```ts
      * import { Cause, Effect, TxQueue } from "effect"
      *
@@ -1125,17 +1152,19 @@ export declare const failCause: {
      * })
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <E>(cause: Cause.Cause<E>): <A>(self: TxEnqueue<A, E>) => Effect.Effect<boolean>;
     /**
-     * Completes the queue with the specified exit value.
+     * Completes the queue with the specified cause.
      *
-     * **Mutation behavior**: This function mutates the original TxQueue by marking
-     * it as completed. It does not return a new TxQueue reference.
+     * If the queue is empty, it transitions directly to done. If it still contains
+     * items, it enters the closing state so buffered items can be drained before the
+     * cause is observed. Returns `false` if the queue was already closing or done.
+     *
+     * **Example** (Failing queues with causes)
      *
-     * @example
      * ```ts
      * import { Cause, Effect, TxQueue } from "effect"
      *
@@ -1149,28 +1178,26 @@ export declare const failCause: {
      * })
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <A, E>(self: TxEnqueue<A, E>, cause: Cause.Cause<E>): Effect.Effect<boolean>;
 };
 /**
- * Ends a queue by signaling completion with a Done error.
+ * Ends a queue by signaling completion with a `Cause.Done` error.
+ *
+ * This is a convenience wrapper around `failCause` for queues whose error
+ * channel can contain `Cause.Done`. If buffered items remain, the queue enters
+ * the closing state and those items may still be consumed before later `take` or
+ * `peek` operations fail with `Cause.Done`.
  *
- * This function provides a clean way to signal the end of a queue by calling
- * `failCause` with `Cause.Done`. This is a convenience function for
- * queues that are typed to accept `Cause.Done` in their error channel.
- * When a queue is ended, all subsequent operations (take, peek, etc.) will fail with
- * `Cause.Done`, propagating through the E-channel.
+ * **Example** (Ending queues)
  *
- * @example
  * ```ts
  * import { Cause, Effect, TxQueue } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const queue = yield* TxQueue.bounded<number, Cause.Done>(10)
- *   yield* TxQueue.offer(queue, 1)
- *   yield* TxQueue.offer(queue, 2)
  *
  *   // Signal the end of the queue
  *   const result = yield* TxQueue.end(queue)
@@ -1185,18 +1212,20 @@ export declare const failCause: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const end: <A, E>(self: TxEnqueue<A, E | Cause.Done>) => Effect.Effect<boolean>;
 /**
- * Clears all elements from the queue without affecting its state.
- * Returns the cleared elements, or an empty array if the queue is done with Done or interrupt.
+ * Removes and returns all currently buffered elements without changing the
+ * queue state.
  *
- * **Mutation behavior**: This function mutates the original TxQueue by removing
- * all elements. It does not return a new TxQueue reference.
+ * If the queue is already done with a `Cause.Done` error, returns an empty
+ * array. If the queue is done for any other cause, including interruption or
+ * failure, that cause is propagated.
+ *
+ * **Example** (Clearing queues)
  *
- * @example
  * ```ts
  * import { Effect, TxQueue } from "effect"
  *
@@ -1215,8 +1244,8 @@ export declare const end: <A, E>(self: TxEnqueue<A, E | Cause.Done>) => Effect.E
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const clear: <A, E>(self: TxEnqueue<A, E>) => Effect.Effect<Array<A>, ExcludeDone<E>>;
 /**
@@ -1229,7 +1258,8 @@ export declare const clear: <A, E>(self: TxEnqueue<A, E>) => Effect.Effect<Array
  * **Mutation behavior**: This function mutates the original TxQueue by clearing
  * its contents and marking it as shutdown. It does not return a new TxQueue reference.
  *
- * @example
+ * **Example** (Shutting down queues)
+ *
  * ```ts
  * import { Effect, TxQueue } from "effect"
  *
@@ -1250,14 +1280,15 @@ export declare const clear: <A, E>(self: TxEnqueue<A, E>) => Effect.Effect<Array
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export declare const shutdown: <A, E>(self: TxEnqueue<A, E>) => Effect.Effect<boolean>;
 /**
  * Checks if the queue is in the open state.
  *
- * @example
+ * **Example** (Checking open state)
+ *
  * ```ts
  * import { Effect, TxQueue } from "effect"
  *
@@ -1273,14 +1304,15 @@ export declare const shutdown: <A, E>(self: TxEnqueue<A, E>) => Effect.Effect<bo
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const isOpen: (self: TxQueueState) => Effect.Effect<boolean>;
 /**
  * Checks if the queue is in the closing state.
  *
- * @example
+ * **Example** (Checking closing state)
+ *
  * ```ts
  * import { Effect, TxQueue } from "effect"
  *
@@ -1297,14 +1329,15 @@ export declare const isOpen: (self: TxQueueState) => Effect.Effect<boolean>;
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const isClosing: (self: TxQueueState) => Effect.Effect<boolean>;
 /**
  * Checks if the queue is done (completed or failed).
  *
- * @example
+ * **Example** (Checking done state)
+ *
  * ```ts
  * import { Effect, TxQueue } from "effect"
  *
@@ -1320,14 +1353,15 @@ export declare const isClosing: (self: TxQueueState) => Effect.Effect<boolean>;
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const isDone: (self: TxQueueState) => Effect.Effect<boolean>;
 /**
  * Checks if the queue is shutdown (legacy compatibility).
  *
- * @example
+ * **Example** (Checking shutdown state)
+ *
  * ```ts
  * import { Effect, TxQueue } from "effect"
  *
@@ -1343,14 +1377,15 @@ export declare const isDone: (self: TxQueueState) => Effect.Effect<boolean>;
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export declare const isShutdown: (self: TxQueueState) => Effect.Effect<boolean>;
 /**
  * Waits for the queue to complete (either successfully or with failure).
  *
- * @example
+ * **Example** (Awaiting queue completion)
+ *
  * ```ts
  * import { Effect, TxQueue } from "effect"
  *
@@ -1366,8 +1401,8 @@ export declare const isShutdown: (self: TxQueueState) => Effect.Effect<boolean>;
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const awaitCompletion: (self: TxQueueState) => Effect.Effect<void>;
 export {};