ActorOptionsType

ActorOptionsType<TMessage> = object

Defined in: src/ActorOptions.ts:44

Plain options-object shape accepted wherever an actor is spawned.

Type Parameters

TMessage

TMessage = unknown

Properties

dispatcher?

readonly optional dispatcher?: Dispatcher

Defined in: src/ActorOptions.ts:53

Run this actor on a different dispatcher than the system’s.

---

displayName?

readonly optional displayName?: string

Defined in: src/ActorOptions.ts:127

Human-readable name for log lines and the DevTools tree (#891) — the spawn-site counterpart to overriding Actor.displayName(), for a framework-constructed actor with no subclass of your own: a Behaviors actor, a sharded entity, a singleton.

Outranks the method, exactly as supervisorStrategy outranks Actor.supervisorStrategy(). Purely cosmetic — the path stays the identity everywhere that routes or correlates.

---

entity?

readonly optional entity?: EntityContext

Defined in: src/ActorOptions.ts:137

Spawn this actor as a sharded entity with the given identity, readable back off this.entityId / this.context.entity.

ClusterSharding sets this itself for every entity a shard creates. It is public for the test bench: an entity that derives its persistenceId from this.entityId is otherwise unspawnable without a cluster standing behind it.

---

internal?

readonly optional internal?: boolean

Defined in: src/ActorOptions.ts:116

This actor belongs to the tooling, not to the application.

Whole-system instrumentation skips it, which is what keeps a debugger from observing itself: DevTools’ own hub publishes the spans it just recorded, so tracing it feeds its own output back in. Children inherit the mark — a tooling actor’s children are tooling.

---

mailbox?

readonly optional mailbox?: MailboxFactory<TMessage>

Defined in: src/ActorOptions.ts:107

Custom mailbox — PriorityMailbox, or a BoundedMailbox configured beyond what mailboxCapacity / mailboxOverflow express, or a Mailbox subclass of your own. Omit for the default unbounded FIFO queue.

Drops still reach actor_mailbox_dropped_total: the cell registers its observer on whatever you return, provided the mailbox implements DropReportingMailbox (BoundedMailbox does). Any onDrop of your own keeps firing alongside it.

---

mailboxCapacity?

readonly optional mailboxCapacity?: number

Defined in: src/ActorOptions.ts:88

Bound this actor’s mailbox at mailboxCapacity queued user messages. Unset means unbounded, which is the default — so setting this is the act that introduces message loss, and mailboxOverflow decides which message is lost. Cannot be combined with mailbox, which brings its own bound.

What it never loses is anything the framework posts through ActorCell.postSignalEnvelope. That door — not the message that goes through it — is the rule: since #729 it stamps Envelope.undroppable and routes to Mailbox.enqueueSignal, a lane no overflow policy can shed. Two senders use it, a death-watch Terminated and the websocket-accept command that hands an upgraded socket to its hub (#717). So bounding a watcher costs it backlog and not the deaths it is watching for, and bounding a hub cannot orphan a socket it has already accepted.

---

mailboxOverflow?

readonly optional mailboxOverflow?: BoundedMailboxOverflow

Defined in: src/ActorOptions.ts:95

What a full mailbox does with an arriving message. Only meaningful together with mailboxCapacity — an unbounded mailbox is never full — so setting it alone is rejected rather than silently ignored. Defaults to DEFAULT_MAILBOX_OVERFLOW.

---

supervisorStrategy?

readonly optional supervisorStrategy?: SupervisorStrategy

Defined in: src/ActorOptions.ts:51

How the parent handles this actor’s failures. Distinct from the supervisorStrategy() override inside the actor class, which governs its children. Set here, a single child opts out of its parent’s policy without affecting its siblings.

---

throughput?

readonly optional throughput?: number

Defined in: src/ActorOptions.ts:71

User messages this actor handles per dispatcher turn before it yields (#409). Unset falls through to actor-ts.actor.throughput, then to the built-in default — so this is the highest-precedence layer, not a replacement for the system-wide setting.

Raise it for an actor that is a throughput bottleneck and whose handler is short; the scheduling round trip it amortises costs more than such a handler does. Lower it toward 1 for an actor whose handler is slow enough that a full batch would keep timers and I/O waiting — the batch runs to its budget without yielding, so the budget is the latency other work can see.

A batch always ends early on anything that changes the actor’s situation: an empty mailbox, a suspend or stop, and a throttle bucket that runs out mid-batch.