effect 4.0.0-beta.65 → 4.0.0-beta.67

package/dist/TxQueue.js

@@ -14,7 +14,8 @@ const TypeId = "~effect/transactions/TxQueue";
 /**
  * Checks if the given value is a TxEnqueue.
  *
- * @example
+ * **Example** (Checking enqueue handles)
+ *
  * ```ts
  * import { TxQueue } from "effect"
  *
@@ -26,14 +27,15 @@ const TypeId = "~effect/transactions/TxQueue";
  * }
  * ```
  *
- * @since 4.0.0
  * @category guards
+ * @since 4.0.0
  */
 export const isTxEnqueue = u => hasProperty(u, EnqueueTypeId);
 /**
  * Checks if the given value is a TxDequeue.
  *
- * @example
+ * **Example** (Checking dequeue handles)
+ *
  * ```ts
  * import { TxQueue } from "effect"
  *
@@ -45,14 +47,15 @@ export const isTxEnqueue = u => hasProperty(u, EnqueueTypeId);
  * }
  * ```
  *
- * @since 4.0.0
  * @category guards
+ * @since 4.0.0
  */
 export const isTxDequeue = u => hasProperty(u, DequeueTypeId);
 /**
  * Checks if the given value is a TxQueue.
  *
- * @example
+ * **Example** (Checking queue handles)
+ *
  * ```ts
  * import { TxQueue } from "effect"
  *
@@ -64,8 +67,8 @@ export const isTxDequeue = u => hasProperty(u, DequeueTypeId);
  * }
  * ```
  *
- * @since 4.0.0
  * @category guards
+ * @since 4.0.0
  */
 export const isTxQueue = u => hasProperty(u, TypeId);
 // =============================================================================
@@ -107,7 +110,8 @@ const TxQueueProto = {
  * **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"
  *
@@ -127,8 +131,8 @@ const TxQueueProto = {
  * })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const bounded = capacity => Effect.gen(function* () {
   const items = yield* TxChunk.empty();
@@ -148,7 +152,8 @@ export const bounded = capacity => Effect.gen(function* () {
  * **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"
  *
@@ -168,8 +173,8 @@ export const bounded = capacity => Effect.gen(function* () {
  * })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const unbounded = () => Effect.gen(function* () {
   const items = yield* TxChunk.empty();
@@ -189,7 +194,8 @@ export const unbounded = () => Effect.gen(function* () {
  * **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"
  *
@@ -207,8 +213,8 @@ export const unbounded = () => Effect.gen(function* () {
  * })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const dropping = capacity => Effect.gen(function* () {
   const items = yield* TxChunk.empty();
@@ -228,7 +234,8 @@ export const dropping = capacity => Effect.gen(function* () {
  * **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"
  *
@@ -248,8 +255,8 @@ export const dropping = capacity => Effect.gen(function* () {
  * })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const sliding = capacity => Effect.gen(function* () {
   const items = yield* TxChunk.empty();
@@ -267,12 +274,17 @@ export const sliding = capacity => Effect.gen(function* () {
 // Core Queue Operations
 // =============================================================================
 /**
- * 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"
  *
@@ -285,8 +297,8 @@ export const sliding = capacity => Effect.gen(function* () {
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const offer = /*#__PURE__*/dual(2, (self, value) => Effect.gen(function* () {
   const state = yield* TxRef.get(self.stateRef);
@@ -317,16 +329,20 @@ export const offer = /*#__PURE__*/dual(2, (self, value) => Effect.gen(function*
   return yield* Effect.txRetry;
 }).pipe(Effect.tx));
 /**
- * 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)
@@ -338,8 +354,8 @@ export const offer = /*#__PURE__*/dual(2, (self, value) => Effect.gen(function*
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const offerAll = /*#__PURE__*/dual(2, (self, values) => Effect.gen(function* () {
   const rejected = [];
@@ -352,12 +368,16 @@ export const offerAll = /*#__PURE__*/dual(2, (self, values) => Effect.gen(functi
   return rejected;
 }).pipe(Effect.tx));
 /**
- * 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"
  *
@@ -376,8 +396,8 @@ export const offerAll = /*#__PURE__*/dual(2, (self, values) => Effect.gen(functi
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const take = self => Effect.gen(function* () {
   const state = yield* TxRef.get(self.stateRef);
@@ -408,7 +428,8 @@ export const take = self => Effect.gen(function* () {
 /**
  * Tries to take an item from the queue without blocking.
  *
- * @example
+ * **Example** (Polling without blocking)
+ *
  * ```ts
  * import { Effect, Option, TxQueue } from "effect"
  *
@@ -425,8 +446,8 @@ export const take = self => Effect.gen(function* () {
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const poll = self => Effect.gen(function* () {
   const state = yield* TxRef.get(self.stateRef);
@@ -452,7 +473,8 @@ export const poll = self => Effect.gen(function* () {
  * **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"
  *
@@ -478,8 +500,8 @@ export const poll = self => Effect.gen(function* () {
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const takeAll = self => Effect.gen(function* () {
   const state = yield* TxRef.get(self.stateRef);
@@ -505,39 +527,38 @@ export const takeAll = self => Effect.gen(function* () {
   return items;
 }).pipe(Effect.tx);
 /**
- * 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 4.0.0
  */
 export const takeN = /*#__PURE__*/dual(2, (self, n) => Effect.gen(function* () {
   const state = yield* TxRef.get(self.stateRef);
@@ -592,10 +613,16 @@ export const takeN = /*#__PURE__*/dual(2, (self, n) => Effect.gen(function* () {
   return Chunk.toArray(taken);
 }).pipe(Effect.tx));
 /**
- * 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"
  *
@@ -616,8 +643,8 @@ export const takeN = /*#__PURE__*/dual(2, (self, n) => Effect.gen(function* () {
  * })
  * ```
  *
- * @since 4.0.0
  * @category taking
+ * @since 4.0.0
  */
 export const takeBetween = /*#__PURE__*/dual(3, (self, min, max) => Effect.gen(function* () {
   const state = yield* TxRef.get(self.stateRef);
@@ -669,10 +696,14 @@ export const takeBetween = /*#__PURE__*/dual(3, (self, min, max) => Effect.gen(f
   return Chunk.toArray(taken);
 }).pipe(Effect.tx));
 /**
- * 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"
  *
@@ -700,8 +731,8 @@ export const takeBetween = /*#__PURE__*/dual(3, (self, min, max) => Effect.gen(f
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const peek = self => Effect.gen(function* () {
   const state = yield* TxRef.get(self.stateRef);
@@ -718,7 +749,8 @@ export const peek = self => Effect.gen(function* () {
 /**
  * Gets the current size of the queue.
  *
- * @example
+ * **Example** (Reading queue size)
+ *
  * ```ts
  * import { Effect, TxQueue } from "effect"
  *
@@ -731,14 +763,15 @@ export const peek = self => Effect.gen(function* () {
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const size = self => TxChunk.size(self.items);
 /**
  * Checks if the queue is empty.
  *
- * @example
+ * **Example** (Checking whether a queue is empty)
+ *
  * ```ts
  * import { Effect, TxQueue } from "effect"
  *
@@ -754,14 +787,15 @@ export const size = self => TxChunk.size(self.items);
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const isEmpty = self => TxChunk.isEmpty(self.items);
 /**
  * Checks if the queue is at capacity.
  *
- * @example
+ * **Example** (Checking whether a queue is full)
+ *
  * ```ts
  * import { Effect, TxQueue } from "effect"
  *
@@ -777,17 +811,20 @@ export const isEmpty = self => TxChunk.isEmpty(self.items);
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const isFull = self => self.capacity === Number.POSITIVE_INFINITY ? Effect.succeed(false) : Effect.map(size(self), currentSize => currentSize >= self.capacity);
 /**
- * Interrupts the queue, transitioning it to a closing state.
+ * Gracefully interrupts the queue with the current fiber's interruption cause.
  *
- * **Mutation behavior**: This function mutates the original TxQueue by marking
- * it for graceful closure. It does not return a new TxQueue reference.
+ * 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.
+ *
+ * **Example** (Interrupting queues)
  *
- * @example
  * ```ts
  * import { Effect, TxQueue } from "effect"
  *
@@ -801,17 +838,18 @@ export const isFull = self => self.capacity === Number.POSITIVE_INFINITY ? Effec
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const interrupt = self => Effect.withFiber(fiber => failCause(self, Cause.interrupt(fiber.id)));
 /**
- * Fails the queue with the specified error.
+ * Fails the queue with the specified error, discarding any buffered items.
  *
- * **Mutation behavior**: This function mutates the original TxQueue by marking
- * it as failed. It does not return a new TxQueue reference.
+ * The queue transitions directly to done with `Cause.fail(error)`. Returns
+ * `false` if the queue was already closing or done.
+ *
+ * **Example** (Failing queues)
  *
- * @example
  * ```ts
  * import { Effect, TxQueue } from "effect"
  *
@@ -824,8 +862,8 @@ export const interrupt = self => Effect.withFiber(fiber => failCause(self, Cause
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const fail = /*#__PURE__*/dual(2, (self, error) => Effect.gen(function* () {
   const state = yield* TxRef.get(self.stateRef);
@@ -841,12 +879,14 @@ export const fail = /*#__PURE__*/dual(2, (self, error) => Effect.gen(function* (
   return true;
 }).pipe(Effect.tx));
 /**
- * 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"
  *
@@ -860,8 +900,8 @@ export const fail = /*#__PURE__*/dual(2, (self, error) => Effect.gen(function* (
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const failCause = /*#__PURE__*/dual(2, (self, cause) => Effect.gen(function* () {
   const state = yield* TxRef.get(self.stateRef);
@@ -884,22 +924,20 @@ export const failCause = /*#__PURE__*/dual(2, (self, cause) => Effect.gen(functi
   return true;
 }).pipe(Effect.tx));
 /**
- * Ends a queue by signaling completion with a Done error.
+ * Ends a queue by signaling completion with a `Cause.Done` error.
  *
- * 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.
+ * 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`.
+ *
+ * **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)
@@ -914,18 +952,20 @@ export const failCause = /*#__PURE__*/dual(2, (self, cause) => Effect.gen(functi
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const end = self => failCause(self, Cause.fail(Cause.Done()));
 /**
- * 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"
  *
@@ -944,8 +984,8 @@ export const end = self => failCause(self, Cause.fail(Cause.Done()));
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const clear = self => Effect.gen(function* () {
   const state = yield* TxRef.get(self.stateRef);
@@ -970,7 +1010,8 @@ export const clear = self => Effect.gen(function* () {
  * **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"
  *
@@ -991,8 +1032,8 @@ export const clear = self => Effect.gen(function* () {
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const shutdown = self => Effect.gen(function* () {
   yield* Effect.ignore(clear(self));
@@ -1001,7 +1042,8 @@ export const shutdown = self => Effect.gen(function* () {
 /**
  * Checks if the queue is in the open state.
  *
- * @example
+ * **Example** (Checking open state)
+ *
  * ```ts
  * import { Effect, TxQueue } from "effect"
  *
@@ -1017,14 +1059,15 @@ export const shutdown = self => Effect.gen(function* () {
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const isOpen = self => Effect.map(TxRef.get(self.stateRef), state => state._tag === "Open");
 /**
  * Checks if the queue is in the closing state.
  *
- * @example
+ * **Example** (Checking closing state)
+ *
  * ```ts
  * import { Effect, TxQueue } from "effect"
  *
@@ -1041,14 +1084,15 @@ export const isOpen = self => Effect.map(TxRef.get(self.stateRef), state => stat
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const isClosing = self => Effect.map(TxRef.get(self.stateRef), state => state._tag === "Closing");
 /**
  * Checks if the queue is done (completed or failed).
  *
- * @example
+ * **Example** (Checking done state)
+ *
  * ```ts
  * import { Effect, TxQueue } from "effect"
  *
@@ -1064,14 +1108,15 @@ export const isClosing = self => Effect.map(TxRef.get(self.stateRef), state => s
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const isDone = self => Effect.map(TxRef.get(self.stateRef), state => state._tag === "Done");
 /**
  * Checks if the queue is shutdown (legacy compatibility).
  *
- * @example
+ * **Example** (Checking shutdown state)
+ *
  * ```ts
  * import { Effect, TxQueue } from "effect"
  *
@@ -1087,14 +1132,15 @@ export const isDone = self => Effect.map(TxRef.get(self.stateRef), state => stat
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const isShutdown = self => isDone(self);
 /**
  * Waits for the queue to complete (either successfully or with failure).
  *
- * @example
+ * **Example** (Awaiting queue completion)
+ *
  * ```ts
  * import { Effect, TxQueue } from "effect"
  *
@@ -1110,8 +1156,8 @@ export const isShutdown = self => isDone(self);
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const awaitCompletion = self => Effect.gen(function* () {
   const state = yield* TxRef.get(self.stateRef);