Queue
Passes values asynchronously between fibers.
A Queue<A, E> accepts values, hands each value to one consumer in offer order, and can complete, fail, interrupt, or shut down. Queues can be bounded or unbounded, and bounded queues can suspend, drop, or slide values when producers are faster than consumers.
Completion
Signature
declare function end<A, E>(self: Enqueue<A, Done<void> | E>): Effect<boolean>;Signals queue completion synchronously.
When to use
Use when implementing low-level queue integrations that must complete a queue without wrapping the operation in Effect.
Details
Returns false if the queue is already done.
Gotchas
This is an unsafe operation that directly modifies the queue without Effect wrapping.
Signature
declare function endUnsafe<A, E>(self: Enqueue<A, Done<void> | E>): boolean;Fails the queue with an error. If the queue is already done, false is returned.
Signature
declare function fail<A, E>(self: Enqueue<A, E>, error: E): Effect<boolean, never, never>;Fails the queue with a cause. If the queue is already done, false is returned.
Signature
declare const failCause: {
<E>(cause: Cause<E>): <A>(self: Enqueue<A, E>) => Effect<boolean>;
<A, E>(self: Enqueue<A, E>, cause: Cause<E>): Effect<boolean>;
};failCauseUnsafe
Fails the queue with a cause synchronously. If the queue is already done, false is returned.
When to use
Use when queue completion must be driven from synchronous internals while preserving the full failure Cause.
Gotchas
This is an unsafe operation that directly modifies the queue without Effect wrapping.
Signature
declare function failCauseUnsafe<A, E>(self: Enqueue<A, E>, cause: Cause<E>): boolean;Interrupts the queue gracefully, transitioning it to a closing state.
Details
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.
Signature
declare function interrupt<A, E>(self: Enqueue<A, E>): Effect<boolean>;Runs an Effect into a Queue, where success ends the queue and failure fails the queue.
Signature
declare const into: {
<A, E>(
self: Enqueue<A, Done<void> | E>,
): <AX, EX, RX>(effect: Effect<AX, EX, RX>) => Effect<boolean, never, RX>;
<AX, E, EX, RX, A>(
effect: Effect<AX, EX, RX>,
self: Enqueue<A, Done<void> | E>,
): Effect<boolean, never, RX>;
};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.
Signature
declare function shutdown<A, E>(self: Enqueue<A, E>): Effect<boolean>;Constructors
Creates a bounded queue with the specified capacity that uses backpressure strategy.
Details
When the queue reaches capacity, producers will be suspended until space becomes available. This ensures all messages are processed but may slow down producers.
Signature
declare function bounded<A, E = never>(capacity: number): Effect<Queue<A, E>>;Creates a bounded queue with dropping strategy. When the queue reaches capacity, new elements are dropped and the offer operation returns false.
When to use
Use when you need producer offers not to block while preserving existing queued messages, even if new messages may be dropped when the queue is full.
Signature
declare function dropping<A, E = never>(capacity: number): Effect<Queue<A, E>>;Creates a Queue with optional capacity and overflow strategy.
Details
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.
Signature
declare function make<A, E = never>(options?: {
readonly capacity?: number;
readonly strategy?: "sliding" | "dropping" | "suspend";
}): Effect<Queue<A, E>>;Creates a bounded queue with sliding strategy. When the queue reaches capacity, new elements are added and the oldest elements are dropped.
When to use
Use when you need producer offers not to block and can accept dropping the oldest messages, such as when maintaining a rolling window of recent values.
Signature
declare function sliding<A, E = never>(capacity: number): Effect<Queue<A, E>>;Creates an unbounded queue that can grow to any size without blocking producers.
When to use
Use when you need producers to add messages without backpressure and accept unbounded memory growth.
Signature
declare function unbounded<A, E = never>(): Effect<Queue<A, E>>;Converting
Narrows a Queue to a Dequeue, exposing the consumer side of the queue.
When to use
Use to pass a queue to code that should consume values while keeping producer-side operations out of that code's TypeScript type.
Gotchas
This is a type-level narrowing operation. It returns the same queue object and does not create a runtime wrapper.
See
Signature
declare const asDequeue: <A, E>(self: Queue<A, E>) => Dequeue<A, E>;Converts a Queue to its write-only Enqueue interface.
When to use
Use to expose only the producer side of a Queue to code that should offer values or signal queue lifecycle.
Gotchas
This is a type-level capability restriction. It returns the same queue object, so it does not hide read operations at runtime.
See
Signature
declare function asEnqueue<A, E>(self: Queue<A, E>): Enqueue<A, E>;Guards
Type guard to check if a value is a Dequeue.
When to use
Use to narrow an unknown value before passing it to read-side queue operations.
See
Signature
declare function isDequeue<A = unknown, E = unknown>(u: unknown): u is Dequeue<A, E>;Type guard to check if a value is an Enqueue.
When to use
Use to narrow an unknown value before calling queue operations that require write-side access.
Gotchas
A full Queue also satisfies this guard because every queue includes the enqueue side.
See
Signature
declare function isEnqueue<A = unknown, E = unknown>(u: unknown): u is Enqueue<A, E>;Type guard to check if a value is a Queue.
When to use
Use to narrow an unknown value to a full Queue before passing it to APIs that need both offering and taking capabilities.
See
Signature
declare function isQueue<A = unknown, E = unknown>(u: unknown): u is Queue<A, E>;Models
A Dequeue is a queue that can be taken from.
Details
This interface represents the read-only part of a Queue, allowing you to take elements from the queue but not offer elements to it.
Signature
interface Dequeue<out A, out E = never> extends Inspectable {
readonly "~effect/Queue/Dequeue": Variance<A, E>;
capacity: number;
readonly dispatcher: SchedulerDispatcher;
messages: MutableList<any>;
scheduleRunning: boolean;
state: State<any, any>;
readonly strategy: "sliding" | "dropping" | "suspend";
}An Enqueue is a queue that can be offered to.
Details
This interface represents the write-only part of a Queue, allowing you to offer elements to the queue but not take elements from it.
Signature
interface Enqueue<in A, in E = never> extends Inspectable {
readonly "~effect/Queue/Enqueue": Variance<A, E>;
capacity: number;
readonly dispatcher: SchedulerDispatcher;
messages: MutableList<any>;
scheduleRunning: boolean;
state: State<any, any>;
readonly strategy: "sliding" | "dropping" | "suspend";
}A Queue is an asynchronous queue that can be offered to and taken from.
Details
It also supports signaling that it is done or failed.
Signature
interface Queue<in out A, in out E = never> extends Enqueue<A, E>, Dequeue<A, E> {
readonly "~effect/Queue": Variance<A, E>;
}Offering
Adds a message to the queue. Returns false if the queue is done.
Details
For bounded queues, this operation may suspend if the queue is at capacity, depending on the backpressure strategy. For dropping/sliding queues, it may return false or succeed immediately by dropping/sliding existing messages.
Signature
declare function offer<A, E>(self: Enqueue<A, E>, message: NoInfer<A>): Effect<boolean>;Adds multiple messages to the queue. Returns the remaining messages that were not added.
When to use
Use when producers can submit a batch at once and need to know which messages did not fit under the queue's capacity strategy.
Details
For bounded queues, this operation may suspend if the queue doesn't have enough capacity. The operation returns an array of messages that couldn't be added (empty array means all messages were successfully added).
Signature
declare function offerAll<A, E>(self: Enqueue<A, E>, messages: Iterable<A>): Effect<Array<A>>;offerAllUnsafe
Adds multiple messages to the queue synchronously. Returns the remaining messages that were not added.
When to use
Use when queue internals or a performance boundary need a synchronous batch offer and can handle any messages that do not fit.
Gotchas
This is an unsafe operation that directly modifies the queue without Effect wrapping.
Signature
declare function offerAllUnsafe<A, E>(self: Enqueue<A, E>, messages: Iterable<A>): Array<A>;offerUnsafe
Adds a message to the queue synchronously. Returns false if the queue is done.
When to use
Use when you are already in synchronous queue internals or a performance boundary where wrapping the mutation in Effect is intentionally avoided.
Gotchas
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.
Signature
declare function offerUnsafe<A, E>(self: Enqueue<A, E>, message: NoInfer<A>): boolean;Other
Signature
declare function await<A, E>(self: Dequeue<A, E>): Effect<void, Exclude<E, Done<void>>>;Companion namespace containing type-level metadata for the Dequeue read-only queue interface.
Companion namespace containing type-level metadata for the Enqueue write-only queue interface.
Companion namespace containing type-level metadata and low-level state types for Queue.
Predicates
Checks whether the queue is full.
Signature
declare function isFull<A, E>(self: Dequeue<A, E>): Effect<boolean>;isFullUnsafe
Checks whether the queue is full synchronously.
When to use
Use when an immediate Queue capacity snapshot is needed outside effectful code and racing queue changes are acceptable.
Signature
declare function isFullUnsafe<A, E>(self: Dequeue<A, E>): boolean;Sizes
Returns the current number of buffered messages in the queue.
Details
After end, a queue remains Closing while buffered messages are drained, and its size continues to include those messages. A Done queue reports a size of 0.
Signature
declare function size<A, E>(self: Dequeue<A, E>): Effect<number>;sizeUnsafe
Returns the current number of buffered messages in the queue synchronously.
When to use
Use when you need an immediate Queue size snapshot for diagnostics or internals and do not need the read wrapped in Effect.
Details
After endUnsafe, a queue remains Closing while buffered messages are drained, and its size continues to include those messages. A Done queue reports a size of 0. This unsafe operation reads the queue state directly without Effect wrapping.
Signature
declare function sizeUnsafe<A, E>(self: Dequeue<A, E>): number;Taking
Takes 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.
Signature
declare function clear<A, E>(self: Dequeue<A, E>): Effect<Array<A>, Exclude<E, Done<any>>>;Takes all messages from the queue, until the queue has errored or is done.
Signature
declare function collect<A, E>(
self: Dequeue<A, Done<void> | E>,
): Effect<Array<A>, Exclude<E, Done<any>>>;Peeks at the next item without removing it.
Details
Blocks until an item is available. If the queue is done or fails, the error is propagated.
Signature
declare function peek<A, E>(self: Dequeue<A, E>): Effect<A, E>;Attempts to take one item from the queue without waiting.
Details
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.
Signature
declare function poll<A, E>(self: Dequeue<A, E>): Effect<Option<A>>;Takes a single message from the queue, or wait for a message to be available.
Details
If the queue is done, it will fail with Done. If the queue fails, the Effect will fail with the error.
Signature
declare function take<A, E>(self: Dequeue<A, E>): Effect<A, E>;Takes all currently available messages, waiting until at least one message is available when the queue is empty.
When to use
Use when consumers should process the next non-empty batch of buffered messages instead of repeatedly taking one message at a time.
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.
Signature
declare function takeAll<A, E>(self: Dequeue<A, E>): Effect<[A, ...Array<A>], E>;takeBetween
Takes between min and max messages from the queue.
Details
The operation waits when fewer than the required minimum messages are available. It returns at most max messages. If the queue completes or fails before the minimum can be satisfied, the effect fails with the queue's terminal error.
Signature
declare function takeBetween<A, E>(
self: Dequeue<A, E>,
min: number,
max: number,
): Effect<Array<A>, E>;Takes up to n messages from the queue.
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.
Signature
declare function takeN<A, E>(self: Dequeue<A, E>, n: number): Effect<Array<A>, E>;takeUnsafe
Attempts to take one message from the queue synchronously.
When to use
Use when polling queue internals must not suspend or register a waiting taker, and undefined is an acceptable result for an empty queue.
Details
Returns an Exit for an immediately available message or for the queue's terminal state. Returns undefined when no message is immediately available. This operation does not wait or register a taker.
Signature
declare function takeUnsafe<A, E>(self: Dequeue<A, E>): Exit<A, E> | undefined;
Signals queue completion.
When to use
Use to stop accepting new offers while allowing already queued messages to be consumed.
Details
Returns
falseif the queue is already done.