ActorContext

Defined in: src/ActorContext.ts:17

Runtime API given to every Actor. Access through this.context inside an Actor subclass.

Type Parameters

TMessage

TMessage = unknown

Properties

children

readonly children: readonly ActorRef<unknown>[]

Defined in: src/ActorContext.ts:44

Snapshot of direct children.

---

cluster

readonly cluster: Option<Cluster>

Defined in: src/ActorContext.ts:38

The Cluster this actor’s system joined, None on a local-only system (#833). Ask this when the actor has to work either way — it answers rather than throws.

Inside code that only ever runs clustered, prefer the this.cluster getter on Actor: same object, no unwrapping.

---

entity

readonly entity: Option<EntityContext>

Defined in: src/ActorContext.ts:58

Sharding identity when ClusterSharding started this actor as an entity, None for every other actor.

Set on the entity itself and nowhere else — an entity’s own children get None — so Some here means “I am the entity”, not “I live under one”. A child that needs the id gets it passed down.

Inside an entity, prefer the this.entityId / this.entity getters on Actor: they answer the same question without the unwrapping, because entity code already knows it is an entity.

---

log

readonly log: Logger

Defined in: src/ActorContext.ts:64

Logger bound to this actor’s path, and to whatever Actor.displayName() currently resolves to.

---

parent

readonly parent: Option<ActorRef<unknown>>

Defined in: src/ActorContext.ts:41

Parent actor, or None for the root guardian.

---

path

readonly path: ActorPath

Defined in: src/ActorContext.ts:22

The ActorPath of this actor.

---

self

readonly self: ActorRef<TMessage>

Defined in: src/ActorContext.ts:19

A reference to this actor.

---

sender

readonly sender: Option<ActorRef<unknown>>

Defined in: src/ActorContext.ts:25

The sender of the message currently being processed, or None.

---

stashSize

readonly stashSize: number

Defined in: src/ActorContext.ts:192

Number of currently-stashed messages.

---

system

readonly system: ActorSystem

Defined in: src/ActorContext.ts:28

The enclosing ActorSystem.

---

timers

readonly timers: TimerScheduler<TMessage>

Defined in: src/ActorContext.ts:225

Per-actor scheduling facade. Timers are identified by user-supplied string keys and are automatically cancelled when the actor stops.

Methods

actorSelection()

actorSelection(path): ActorSelection

Defined in: src/ActorContext.ts:120

Build an ActorSelection that resolves a full-path lookup. Delegates to the enclosing ActorSystem — same semantics as system.actorSelection.

Parameters

path

string

Returns

ActorSelection

---

become()

become(behavior, discardOld?): void

Defined in: src/ActorContext.ts:162

Replace the current behaviour. When discardOld is false, the previous behaviour is pushed onto a stack and can be restored via unbecome().

Parameters

behavior

Receive<TMessage>

discardOld?

boolean

Returns

void

---

cancelReceiveTimeout()

cancelReceiveTimeout(): void

Defined in: src/ActorContext.ts:174

Disable the receive timeout.

Returns

void

---

cancelThrottle()

cancelThrottle(): void

Defined in: src/ActorContext.ts:247

Remove any active throttle, restoring unlimited dequeue rate.

Returns

void

---

child()

child(name): Option<ActorRef<unknown>>

Defined in: src/ActorContext.ts:114

Look up a direct child by name. None if no such child exists.

Parameters

name

string

Returns

Option<ActorRef<unknown>>

---

disableExplainPlan()

disableExplainPlan(): void

Defined in: src/ActorContext.ts:214

Stop recording and discard what was recorded.

Returns

void

---

enableExplainPlan()

enableExplainPlan(options?): void

Defined in: src/ActorContext.ts:211

Start recording this actor’s recent message handlings — type, sender, mailbox wait, handling time and outcome — for the DevTools explain plan or for reading back in code.

Opt-in per actor because it is not free: recording every message on every actor would cost more than many of the handlers being measured. Enabling it also starts timestamping this actor’s incoming envelopes, which is what makes the mailbox-wait figure possible.

override preStart(): void {
  this.context.enableExplainPlan({ capacity: 100 });
}

Parameters

options?

capacity?

number

Returns

void

---

explainPlan()

explainPlan(): readonly MessageExplain[]

Defined in: src/ActorContext.ts:217

Recorded handlings, oldest first. Empty while recording is off.

Returns

readonly MessageExplain[]

---

setDisplayName()

setDisplayName(name): void

Defined in: src/ActorContext.ts:81

Name this actor in log lines and in the DevTools tree from inside the running actor (#891) — for a name that only becomes known at runtime (after recovery, after the first message), and for Behaviors actors, which have no subclass to override Actor.displayName() on:

Behaviors.setup<Command>((context) => {
  context.setDisplayName(`User(${userId})`);
  return Behaviors.receive(...);
});

Takes effect on the very next record, and outranks both ActorOptions.withDisplayName(...) and the method. Purely cosmetic — the path stays the identity everywhere that routes or correlates.

Parameters

name

string

Returns

void

---

setReceiveTimeout()

setReceiveTimeout(ms): void

Defined in: src/ActorContext.ts:171

Fire a ReceiveTimeout message when no user message has been received in ms. Pass 0 to disable.

Parameters

ms

number

Returns

void

---

spawn()

spawn<T>(actor, name, options?): ActorRef<T>

Defined in: src/ActorContext.ts:88

Spawn a child actor under this one with a deterministic caller-supplied name. The name must be unique among siblings. For an auto-generated name, see spawnAnonymous.

Type Parameters

T

T

Parameters

actor

ActorClassOrFactory<T>

name

string

options?

ActorOptions<T>

Returns

ActorRef<T>

---

spawnAnonymous()

spawnAnonymous<T>(actor, options?): ActorRef<T>

Defined in: src/ActorContext.ts:96

Spawn a child actor under this one with an auto-generated name. Useful for one-shot helpers and other transient children where the caller doesn’t need a stable path. For a deterministic name, see spawn.

Type Parameters

T

T

Parameters

actor

ActorClassOrFactory<T>

options?

ActorOptions<T>

Returns

ActorRef<T>

---

spawnTyped()

spawnTyped<T>(behavior, name): ActorRef<T>

Defined in: src/ActorContext.ts:105

Spawn a typed-Behavior child with a deterministic name — the Behavior-DSL counterpart to spawn. Wraps the Behavior in typedActor internally so callers don’t have to.

const child = this.context.spawnTyped(counter(0), 'counter');

Type Parameters

T

T

Parameters

behavior

Behavior<T>

name

string

Returns

ActorRef<T>

---

spawnTypedAnonymous()

spawnTypedAnonymous<T>(behavior): ActorRef<T>

Defined in: src/ActorContext.ts:111

Anonymous variant of spawnTyped — the Behavior-DSL counterpart to spawnAnonymous.

Type Parameters

T

T

Parameters

behavior

Behavior<T>

Returns

ActorRef<T>

---

stash()

stash(): void

Defined in: src/ActorContext.ts:183

Buffer the message currently being handled. It is reinserted into the mailbox when unstashAll() is called. Throws if called outside a user-message handler or if the stash is full.

Returns

void

---

stop()

stop(ref): void

Defined in: src/ActorContext.ts:123

Ask the runtime to stop the given actor. Equivalent to ref.stop().

Parameters

ref

ActorRef

Returns

void

---

stopSelf()

stopSelf(): void

Defined in: src/ActorContext.ts:126

Stop this actor itself.

Returns

void

---

throttle()

throttle(options): void

Defined in: src/ActorContext.ts:244

Throttle this actor’s user-message processing to a token-bucket rate (#83). Every dequeue from the user mailbox consumes one token; when the bucket is empty the cell behaves per ThrottleOnExcess. System messages (Terminated, supervision, watchNotify) are NOT throttled — they always run immediately, so timer fires and lifecycle events stay responsive.

Calling throttle again replaces the existing limiter; pass { qps: Infinity } or call cancelThrottle to remove one.

Cluster-aware variants (split a budget across cluster-router routees, etc.) are out of scope here — this is per-actor only.

Parameters

options

ThrottleOptions

Returns

void

---

unbecome()

unbecome(): void

Defined in: src/ActorContext.ts:165

Pop the behaviour stack, restoring the previous behaviour.

Returns

void

---

unstashAll()

unstashAll(): void

Defined in: src/ActorContext.ts:189

Prepend every stashed message back onto the user mailbox in the order they were stashed. The buffer is empty afterwards.

Returns

void

---

unwatch()

unwatch(ref): ActorRef

Defined in: src/ActorContext.ts:156

Stop watching — whether registered via watch or watchWith.

Parameters

ref

ActorRef

Returns

ActorRef

---

watch()

watch(ref): ActorRef

Defined in: src/ActorContext.ts:129

Start death-watching an actor. A Terminated message is sent when it stops.

Parameters

ref

ActorRef

Returns

ActorRef

---

watchWith()

watchWith(ref, message): ActorRef

Defined in: src/ActorContext.ts:153

Death-watch ref, but deliver message instead of Terminated(ref).

Terminated answers “did that one die?”, which forces every watcher to carry the signal in its protocol and to re-derive the meaning of the death from Terminated.actor. A watcher that watches several kinds of actor — workers, a connection, a peer — ends up with one handler branching on ref identity. watchWith moves that decision to registration time, so each death arrives as the domain message the watcher already handles:

this.context.watchWith(worker, { kind: 'workerLost', name });
this.context.watchWith(connection, { kind: 'connectionLost' });

message must belong to this actor’s own protocol — it is delivered to onReceive like any other user message, not as a signal.

Last call wins: watchWith on an already-watched ref replaces whatever the previous watch/watchWith registered, and a later plain watch drops the custom message again. The registration is consumed by the death it describes — watching the same name again after a restart is a new subject and needs a new call.

Parameters

ref

ActorRef

message

TMessage

Returns

ActorRef