BoundedMailboxOptionsType

BoundedMailboxOptionsType = object

Defined in: src/mailbox/BoundedMailboxOptions.ts:14

Plain options-object shape accepted by a BoundedMailbox.

Properties

capacity

readonly capacity: number

Defined in: src/mailbox/BoundedMailboxOptions.ts:15

---

deadLetterDrops?

readonly optional deadLetterDrops?: boolean

Defined in: src/mailbox/BoundedMailboxOptions.ts:49

Route every dropped envelope to system.deadLetters, so an overflow leaves a forensic record and not only a counter (#773). Default false.

Opt-in rather than always-on because the cost lands in the worst possible place: the drop happens on the sender’s stack, and DeadLetterRef.tell runs the durable capture sink and then publishes synchronously to every event-stream subscriber. A bound exists to absorb a burst cheaply; turning each shed message into a fan-out undoes that. Turn it on for the actors whose losses you would have to explain afterwards — a command stream, a delivery confirmation — and leave it off for the telemetry firehose the bound was drawn for.

What the dead letter carries is what every other loss path in the framework carries: the message, its sender, and this actor as the recipient. See DropReportingMailbox.deadLetterDrops.

---

onDrop?

readonly optional onDrop?: MailboxDropObserver

Defined in: src/mailbox/BoundedMailboxOptions.ts:31

Optional hook fired each time a message is dropped by the overflow policy. Receives the policy that triggered the drop so the consumer can label metrics, and the envelope that was discarded (#773) — which under drop-head is the message evicted to make room, not the arrival.

Yours alone: the cell reports to actor_mailbox_dropped_total through DropReportingMailbox.observeDrops, which runs alongside this rather than replacing it.

Runs on the sender’s stack, with nothing between it and the tell — so record and return. A hook that throws puts the throw into a sender that has no idea the receiver was bounded.

---

overflow?

readonly optional overflow?: BoundedMailboxOverflow

Defined in: src/mailbox/BoundedMailboxOptions.ts:16