Mailbox overview
Added in v3.8.0
Table of contents
combinators
into
Run an Effect
into a Mailbox
, where success ends the mailbox and failure fails the mailbox.
Signature
export declare const into: {
<A, E>(self: Mailbox<A, E>): <AX, EX extends E, RX>(effect: Effect<AX, EX, RX>) => Effect<boolean, never, RX>
<AX, E, EX extends E, RX, A>(effect: Effect<AX, EX, RX>, self: Mailbox<A, E>): Effect<boolean, never, RX>
}
Added in v3.8.0
constructors
make
A Mailbox
is a queue that can be signaled to be done or failed.
Signature
export declare const make: <A, E = never>(
capacity?: number | { readonly capacity?: number; readonly strategy?: "suspend" | "dropping" | "sliding" } | undefined
) => Effect<Mailbox<A, E>>
Example
import { Effect, Mailbox } from "effect"
Effect.gen(function* () {
const mailbox = yield* Mailbox.make<number, string>()
// add messages to the mailbox
yield* mailbox.offer(1)
yield* mailbox.offer(2)
yield* mailbox.offerAll([3, 4, 5])
// take messages from the mailbox
const [messages, done] = yield* mailbox.takeAll
assert.deepStrictEqual(messages, [1, 2, 3, 4, 5])
assert.strictEqual(done, false)
// signal that the mailbox is done
yield* mailbox.end
const [messages2, done2] = yield* mailbox.takeAll
assert.deepStrictEqual(messages2, [])
assert.strictEqual(done2, true)
// signal that the mailbox has failed
yield* mailbox.fail("boom")
})
Added in v3.8.0
conversions
fromStream
Create a ReadonlyMailbox
from a Stream
.
Signature
export declare const fromStream: {
(options?: {
readonly capacity?: number | undefined
readonly strategy?: "suspend" | "dropping" | "sliding" | undefined
}): <A, E, R>(self: Stream<A, E, R>) => Effect<ReadonlyMailbox<A, E>, never, R | Scope>
<A, E, R>(
self: Stream<A, E, R>,
options?: {
readonly capacity?: number | undefined
readonly strategy?: "suspend" | "dropping" | "sliding" | undefined
}
): Effect<ReadonlyMailbox<A, E>, never, R | Scope>
}
Added in v3.11.0
toChannel
Create a Channel
from a Mailbox
.
Signature
export declare const toChannel: <A, E>(self: ReadonlyMailbox<A, E>) => Channel<Chunk<A>, unknown, E>
Added in v3.8.0
toStream
Create a Stream
from a Mailbox
.
Signature
export declare const toStream: <A, E>(self: ReadonlyMailbox<A, E>) => Stream<A, E>
Added in v3.8.0
guards
isMailbox
Signature
export declare const isMailbox: <A = unknown, E = unknown>(u: unknown) => u is Mailbox<A, E>
Added in v3.8.0
isReadonlyMailbox
Signature
export declare const isReadonlyMailbox: <A = unknown, E = unknown>(u: unknown) => u is ReadonlyMailbox<A, E>
Added in v3.8.0
models
Mailbox (interface)
A Mailbox
is a queue that can be signaled to be done or failed.
Signature
export interface Mailbox<in out A, in out E = never> extends ReadonlyMailbox<A, E> {
readonly [TypeId]: TypeId
/**
* Add a message to the mailbox. Returns `false` if the mailbox is done.
*/
readonly offer: (message: A) => Effect<boolean>
/**
* Add a message to the mailbox. Returns `false` if the mailbox is done.
*/
readonly unsafeOffer: (message: A) => boolean
/**
* Add multiple messages to the mailbox. Returns the remaining messages that
* were not added.
*/
readonly offerAll: (messages: Iterable<A>) => Effect<Chunk<A>>
/**
* Add multiple messages to the mailbox. Returns the remaining messages that
* were not added.
*/
readonly unsafeOfferAll: (messages: Iterable<A>) => Chunk<A>
/**
* Fail the mailbox with an error. If the mailbox is already done, `false` is
* returned.
*/
readonly fail: (error: E) => Effect<boolean>
/**
* Fail the mailbox with a cause. If the mailbox is already done, `false` is
* returned.
*/
readonly failCause: (cause: Cause<E>) => Effect<boolean>
/**
* Signal that the mailbox is complete. If the mailbox is already done, `false` is
* returned.
*/
readonly end: Effect<boolean>
/**
* Signal that the mailbox is done. If the mailbox is already done, `false` is
* returned.
*/
readonly done: (exit: Exit<void, E>) => Effect<boolean>
/**
* Signal that the mailbox is done. If the mailbox is already done, `false` is
* returned.
*/
readonly unsafeDone: (exit: Exit<void, E>) => boolean
/**
* Shutdown the mailbox, canceling any pending operations.
* If the mailbox is already done, `false` is returned.
*/
readonly shutdown: Effect<boolean>
}
Added in v3.8.0
ReadonlyMailbox (interface)
A ReadonlyMailbox
represents a mailbox that can only be read from.
Signature
export interface ReadonlyMailbox<out A, out E = never>
extends Effect<readonly [messages: Chunk<A>, done: boolean], E>,
Inspectable {
readonly [ReadonlyTypeId]: ReadonlyTypeId
/**
* Take all messages from the mailbox, returning an empty Chunk if the mailbox
* is empty or done.
*/
readonly clear: Effect<Chunk<A>, E>
/**
* Take all messages from the mailbox, or wait for messages to be available.
*
* If the mailbox is done, the `done` flag will be `true`. If the mailbox
* fails, the Effect will fail with the error.
*/
readonly takeAll: Effect<readonly [messages: Chunk<A>, done: boolean], E>
/**
* Take a specified number of messages from the mailbox. It will only take
* up to the capacity of the mailbox.
*
* If the mailbox is done, the `done` flag will be `true`. If the mailbox
* fails, the Effect will fail with the error.
*/
readonly takeN: (n: number) => Effect<readonly [messages: Chunk<A>, done: boolean], E>
/**
* Take a single message from the mailbox, or wait for a message to be
* available.
*
* If the mailbox is done, it will fail with `NoSuchElementException`. If the
* mailbox fails, the Effect will fail with the error.
*/
readonly take: Effect<A, E | NoSuchElementException>
/** Wait for the mailbox to be done. */
readonly await: Effect<void, E>
/**
* Check the size of the mailbox.
*
* If the mailbox is complete, it will return `None`.
*/
readonly size: Effect<Option<number>>
/**
* Check the size of the mailbox.
*
* If the mailbox is complete, it will return `None`.
*/
readonly unsafeSize: () => Option<number>
}
Added in v3.8.0
type ids
ReadonlyTypeId
Signature
export declare const ReadonlyTypeId: typeof ReadonlyTypeId
Added in v3.8.0
ReadonlyTypeId (type alias)
Signature
export type ReadonlyTypeId = typeof ReadonlyTypeId
Added in v3.8.0
TypeId
Signature
export declare const TypeId: typeof TypeId
Added in v3.8.0
TypeId (type alias)
Signature
export type TypeId = typeof TypeId
Added in v3.8.0