PriorityMailboxOptionsType

PriorityMailboxOptionsType<T> = object

Defined in: src/mailbox/PriorityMailboxOptions.ts:33

Plain options-object shape accepted by a PriorityMailbox.

Type Parameters

T

T

Properties

capacity?

readonly optional capacity?: number

Defined in: src/mailbox/PriorityMailboxOptions.ts:45

Maximum queued user messages. Unset means unbounded, which is what a priority mailbox was until #647 and is still the default — the framework does not decide on its own that messages may be destroyed.

It lives here rather than on ActorOptions because ActorOptionsValidator rejects withMailbox combined with withMailboxCapacity: a supplied mailbox brings its own bound, so this is the only door onto one.

---

deadLetterDrops?

readonly optional deadLetterDrops?: boolean

Defined in: src/mailbox/PriorityMailboxOptions.ts:74

Route every dropped envelope to system.deadLetters rather than only counting it (#773). Default false.

Opt-in for the reason BoundedMailboxOptionsType.deadLetterDrops gives — the drop runs on the sender’s stack and a dead letter is a durable capture plus a synchronous publish — and worth the cost more often here than there: a message shed by this mailbox is one the priority function ranked last, which is a claim about importance that only the payload can confirm or refute.

---

onDrop?

readonly optional onDrop?: MailboxDropObserver<T>

Defined in: src/mailbox/PriorityMailboxOptions.ts:62

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) — under drop-lowest-priority that is whichever end lost, which is the arrival exactly when the arrival ranked below the whole backlog.

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

---

onPriorityError?

readonly optional onPriorityError?: (cause, message) => void

Defined in: src/mailbox/PriorityMailboxOptions.ts:99

Optional hook fired each time priorityFor fails to rank a message — it threw, or it answered with something that is not a usable number — and the message was therefore queued at the lowest priority instead (#733).

Worth wiring, because the alternative to the containment is not a clearer failure but a worse one: before #733 a throw escaped into the stack of whichever actor called tell, and restarted it. Contained, the message still arrives — just last — so nothing else in the system says that a priorityFor is broken. This hook is what says it.

cause is what priorityFor threw, or a TypeError describing the value it returned. message is the message it could not rank, which is usually the interesting half: the framework hands priorityFor PoisonPill and Kill as ordinary user messages, so a callback written only for application traffic sees them here first.

Record and return. An observer that throws puts the escape back — this runs on the sender’s stack too — and costs the message its place in the queue, which is exactly what the containment was for. Same contract as onDrop, which is also called with nothing between it and the sender.

Parameters

cause

unknown

message

T

Returns

void

---

overflow?

readonly optional overflow?: PriorityMailboxOverflow

Defined in: src/mailbox/PriorityMailboxOptions.ts:50

What a full mailbox does with the next arrival. Only meaningful together with capacity, and rejected without it. Default reject.

---

priorityFor

readonly priorityFor: PriorityFunction<T>

Defined in: src/mailbox/PriorityMailboxOptions.ts:34