TxQueue
Transactional queues whose state changes participate in Effect transactions.
A TxQueue<A, E> stores values of type A, exposes write-only TxEnqueue and read-only TxDequeue handles, and can complete, fail, or shut down with causes observed by consumers. Queue operations can retry transactionally when they cannot proceed, such as taking from an empty open queue or offering to a full bounded queue. This makes the queue useful for coordinating producers and consumers alongside other transactional state changes.
Combinators
awaitCompletion
Signature
declare function awaitCompletion(self: TxQueueState): Effect<void>;Removes and returns all currently buffered elements.
Details
If the queue is closing, draining its buffered elements transitions it to done. 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.
Signature
declare function clear<A, E>(self: TxEnqueue<A, E>): Effect<Array<A>, ExcludeDone<E>>;Ends a queue by signaling completion with a Cause.Done error.
Details
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.
Signature
declare function end<A, E>(self: TxEnqueue<A, Done<void> | E>): Effect<boolean>;Fails the queue with the specified error, discarding any buffered items.
Details
The queue transitions directly to done with Cause.fail(error). Returns false if the queue was already closing or done.
Signature
declare const fail: {
<E>(error: E): <A>(self: TxEnqueue<A, E>) => Effect<boolean>;
<A, E>(self: TxEnqueue<A, E>, error: E): Effect<boolean>;
};Completes the queue with the specified cause.
Details
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.
Signature
declare const failCause: {
<E>(cause: Cause<E>): <A>(self: TxEnqueue<A, E>) => Effect<boolean>;
<A, E>(self: TxEnqueue<A, E>, cause: Cause<E>): Effect<boolean>;
};Interrupts the queue gracefully with the current fiber's interruption cause.
Details
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.
Signature
declare function interrupt<A, E>(self: TxEnqueue<A, E>): Effect<boolean>;Offers an item to the queue and returns whether it was accepted.
Details
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. This function mutates the original TxQueue by adding the item according to the queue's strategy. It does not return a new TxQueue reference.
Signature
declare const offer: {
<A, E>(value: A): (self: TxEnqueue<A, E>) => Effect<boolean>;
<A, E>(self: TxEnqueue<A, E>, value: A): Effect<boolean>;
};Offers multiple items to the queue, returning the items that were not accepted.
Details
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. This function mutates the original TxQueue by adding items according to the queue's strategy. It does not return a new TxQueue reference.
Signature
declare const offerAll: {
<A, E>(values: Iterable<A>): (self: TxEnqueue<A, E>) => Effect<Array<A>>;
<A, E>(self: TxEnqueue<A, E>, values: Iterable<A>): Effect<Array<A>>;
};Waits transactionally for the next item and returns it without removing it.
Details
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.
Signature
declare function peek<A, E>(self: TxDequeue<A, E>): Effect<A, E>;Tries to take an item from the queue without blocking.
Signature
declare function poll<A, E>(self: TxDequeue<A, E>): Effect<Option<A>>;Shuts down the queue immediately by clearing all items and interrupting it (legacy compatibility).
Details
This operation clears all items from the queue using clear, then interrupts the queue using interrupt. This function mutates the original TxQueue by clearing its contents and marking it as shutdown. It does not return a new TxQueue reference.
Signature
declare function shutdown<A, E>(self: TxEnqueue<A, E>): Effect<boolean>;Gets the current size of the queue.
Signature
declare function size(self: TxQueueState): Effect<number>;Takes the next item from the queue, retrying the transaction while the queue is empty.
Details
If the queue is done, the effect fails with the queue's completion cause. This function mutates the original TxQueue by removing the first item. It does not return a new TxQueue reference.
Signature
declare function take<A, E>(self: TxDequeue<A, E>): Effect<A, E>;Takes all items from the queue. Blocks if the queue is empty.
Details
If the queue is already in a failed state, the error is propagated through the E-channel. This follows the same patterns as take and waits when there are no elements. It returns a non-empty array because it blocks until at least one item is available. This function mutates the original TxQueue by removing all items. It does not return a new TxQueue reference.
Signature
declare function takeAll<A, E>(self: TxDequeue<A, E>): Effect<[A, ...Array<A>], E>;Takes up to n items from the queue in a single transaction.
Details
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. This function mutates the original TxQueue by removing the taken items. It does not return a new TxQueue reference.
Signature
declare const takeN: {
(n: number): <A, E>(self: TxDequeue<A, E>) => Effect<Array<A>, E>;
<A, E>(self: TxDequeue<A, E>, n: number): Effect<Array<A>, E>;
};Constructors
Creates a new bounded TxQueue with the specified capacity.
Details
This function returns a new TxQueue reference with the specified capacity. No existing TxQueue instances are modified.
Signature
declare function bounded<A = never, E = never>(capacity: number): Effect<TxQueue<A, E>>;Creates a new dropping TxQueue with the specified capacity that drops new items when full.
Details
This function returns a new TxQueue reference with dropping strategy. No existing TxQueue instances are modified.
Signature
declare function dropping<A = never, E = never>(capacity: number): Effect<TxQueue<A, E>>;Creates a new sliding TxQueue with the specified capacity that evicts old items when full.
Details
This function returns a new TxQueue reference with sliding strategy. No existing TxQueue instances are modified.
Signature
declare function sliding<A = never, E = never>(capacity: number): Effect<TxQueue<A, E>>;Creates a new unbounded TxQueue with unlimited capacity.
Details
This function returns a new TxQueue reference with unlimited capacity. No existing TxQueue instances are modified.
Signature
declare function unbounded<A = never, E = never>(): Effect<TxQueue<A, E>>;Guards
isTxDequeue
Checks whether the given value is a TxDequeue.
Signature
declare function isTxDequeue<A = unknown, E = unknown>(u: unknown): u is TxDequeue<A, E>;isTxEnqueue
Checks whether the given value is a TxEnqueue.
Signature
declare function isTxEnqueue<A = unknown, E = unknown>(u: unknown): u is TxEnqueue<A, E>;Checks whether the given value is a TxQueue.
Signature
declare function isTxQueue<A = unknown, E = unknown>(u: unknown): u is TxQueue<A, E>;Models
Represents the state of a transactional queue with sophisticated lifecycle management.
Details
The queue progresses through three states: - Open: Accepting offers and serving takes normally - Closing: No new offers accepted, serving remaining items until empty - Done: Terminal state with completion cause, no further operations possible
Signature
type State<_A, E> =
| {
readonly _tag: "Open";
}
| {
readonly _tag: "Closing";
readonly cause: Cause.Cause<E>;
}
| {
readonly _tag: "Done";
readonly cause: Cause.Cause<E>;
};A TxDequeue represents the read-only interface of a transactional queue, providing operations for consuming elements (dequeue operations) and inspecting queue state.
Signature
interface TxDequeue<out A, out E = never> extends TxQueueState {
readonly "~effect/transactions/TxQueue/Dequeue": Variance<A, E>;
}A TxEnqueue represents the write-only interface of a transactional queue, providing operations for adding elements (enqueue operations) and inspecting queue state.
Signature
interface TxEnqueue<in A, in E = never> extends TxQueueState {
readonly "~effect/transactions/TxQueue/Enqueue": Variance<A, E>;
}A TxQueue represents a transactional queue data structure that provides both enqueue and dequeue operations with Software Transactional Memory (STM) semantics.
Signature
interface TxQueue<in out A, in out E = never> extends TxEnqueue<A, E>, TxDequeue<A, E> {
readonly "~effect/transactions/TxQueue": Variance<A, E>;
}TxQueueState interface
Represents the shared state of a transactional queue that can be inspected. This interface contains the core properties needed for queue state inspection operations like size, capacity, and completion status.
Signature
interface TxQueueState extends Inspectable {
readonly capacity: number;
readonly items: TxChunk<any>;
readonly stateRef: TxRef<State<any, any>>;
readonly strategy: "sliding" | "dropping" | "unbounded" | "bounded";
}Other
Namespace containing type definitions for TxDequeue variance annotations.
Namespace containing type definitions for TxEnqueue variance annotations.
Namespace containing type definitions for TxQueue variance annotations.
Predicates
Checks whether the queue is in the closing state.
Signature
declare function isClosing(self: TxQueueState): Effect<boolean>;Checks whether the queue is done (completed or failed).
Signature
declare function isDone(self: TxQueueState): Effect<boolean>;Checks whether the queue is empty.
Signature
declare function isEmpty(self: TxQueueState): Effect<boolean>;Checks whether the queue is at capacity.
Signature
declare function isFull(self: TxQueueState): Effect<boolean>;Checks whether the queue is in the open state.
Signature
declare function isOpen(self: TxQueueState): Effect<boolean>;isShutdown
Checks whether the queue is shutdown (legacy compatibility).
Signature
declare function isShutdown(self: TxQueueState): Effect<boolean>;Taking
takeBetween
Takes between min and max currently available items, waiting for min on an open queue.
Details
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.
Signature
declare const takeBetween: {
(min: number, max: number): <A, E>(self: TxDequeue<A, E>) => Effect<Array<A>, E>;
<A, E>(self: TxDequeue<A, E>, min: number, max: number): Effect<Array<A>, E>;
};
Waits for the queue to complete (either successfully or with failure).