ReplicatedEventSourcedActor
Ce contenu n’est pas encore disponible dans votre langue.
Defined in: src/persistence/ReplicatedEventSourcedActor.ts:116
Base class for user actors. Subclasses must override onReceive.
Lifecycle hooks (preStart, postStop, preRestart, postRestart) have sensible
defaults but can be overridden.
Actors are single-threaded by construction: the runtime guarantees that onReceive is never invoked concurrently for the same actor. If onReceive returns a Promise, the runtime awaits it before starting the next message.
Extends
Section titled “Extends”Actor<Command|ReplicatedEventEnvelope<Event>>
Type Parameters
Section titled “Type Parameters”Command
Section titled “Command”Command
Event
State
Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new ReplicatedEventSourcedActor<
Command,Event,State>():ReplicatedEventSourcedActor<Command,Event,State>
Returns
Section titled “Returns”ReplicatedEventSourcedActor<Command, Event, State>
Inherited from
Section titled “Inherited from”Properties
Section titled “Properties”persistenceId
Section titled “persistenceId”
abstractreadonlypersistenceId:string
Defined in: src/persistence/ReplicatedEventSourcedActor.ts:118
Accessors
Section titled “Accessors”replicaId
Section titled “replicaId”Get Signature
Section titled “Get Signature”get replicaId():
string
Defined in: src/persistence/ReplicatedEventSourcedActor.ts:136
Stable id for this replica — one half of the (replica, seqAtReplica) pair that identifies an event cluster-wide, and a
tie-breaker in the deterministic event order.
Defaults to this node’s cluster address, which is what every replica wanted anyway. Override only when the id must survive a re-address — a fixed datacenter or region name, say — because two replicas that ever share an id will dedupe each other’s events away:
override get replicaId(): ReplicaId { return 'eu-west'; }A getter rather than a field, so the default can read the cluster:
the context is attached after construction. Read from preStart
onwards.
Returns
Section titled “Returns”string
Methods
Section titled “Methods”displayName()
Section titled “displayName()”displayName():
string
Defined in: src/Actor.ts:192
Human-readable name for this actor in log lines and in the DevTools actor tree (#891). Defaults to the full path — which is already the log source, so an actor that doesn’t override this logs exactly as it did before.
override displayName(): string { return `User(${this.entityId})`; }Purely cosmetic. The path stays the identity everywhere that routes,
correlates or aggregates — metric labels, tracing attributes, dead
letters, ActorRef.toString(), every wire identifier — so a display
name is free to be ambiguous, unstable, or shared between actors.
Resolved on every record, not captured once. Two consequences:
keep it cheap and side-effect free, and expect it to be called before
preStart (hence the optional chain — the context is attached after
construction). In exchange a name may be derived from state, and it
updates when that state does. Throwing, or returning anything but a
non-empty string, falls back to the path and warns once: a naming
hook must not be able to take a log line down with it.
ActorOptions.withDisplayName(...) outranks this, for the same reason
withSupervisorStrategy(...) outranks supervisorStrategy
— the spawn site is the more specific statement. It has to: every
Behaviors actor is a TypedActor that inherits this default, so a
method that won would silently swallow the spawn-site value for exactly
the actors that have no subclass to override. For a name that only
becomes known at runtime, this.context.setDisplayName(...) outranks
both.
Returns
Section titled “Returns”string
Inherited from
Section titled “Inherited from”initialState()
Section titled “initialState()”
abstractinitialState():State
Defined in: src/persistence/ReplicatedEventSourcedActor.ts:138
Returns
Section titled “Returns”State
onCommand()
Section titled “onCommand()”
abstractonCommand(state,command):void|Promise<void>
Defined in: src/persistence/ReplicatedEventSourcedActor.ts:140
Parameters
Section titled “Parameters”State
command
Section titled “command”Command
Returns
Section titled “Returns”void | Promise<void>
onEvent()
Section titled “onEvent()”
abstractonEvent(state,event):State
Defined in: src/persistence/ReplicatedEventSourcedActor.ts:139
Parameters
Section titled “Parameters”State
Event
Returns
Section titled “Returns”State
onReceive()
Section titled “onReceive()”onReceive(
message):Promise<void>
Defined in: src/persistence/ReplicatedEventSourcedActor.ts:377
Main message handler. Receives each envelope dequeued from the mailbox. A thrown error (sync or async) is caught by the supervisor.
Parameters
Section titled “Parameters”message
Section titled “message”SubscribeAcknowledgment | Command | ReplicatedEventEnvelope<Event>
Returns
Section titled “Returns”Promise<void>
Overrides
Section titled “Overrides”onRecoveryComplete()
Section titled “onRecoveryComplete()”onRecoveryComplete(
_state):void|Promise<void>
Defined in: src/persistence/ReplicatedEventSourcedActor.ts:169
Recovery hook — called after the local journal has been replayed.
Parameters
Section titled “Parameters”_state
Section titled “_state”State
Returns
Section titled “Returns”void | Promise<void>
postRestart()
Section titled “postRestart()”postRestart(
_reason):void|Promise<void>
Defined in: src/Actor.ts:152
Called on the fresh instance after a restart. Default: call preStart().
Parameters
Section titled “Parameters”_reason
Section titled “_reason”Error
Returns
Section titled “Returns”void | Promise<void>
Inherited from
Section titled “Inherited from”postStop()
Section titled “postStop()”postStop():
void
Defined in: src/persistence/ReplicatedEventSourcedActor.ts:356
Called after the actor has been terminated. Children are already stopped.
Returns
Section titled “Returns”void
Overrides
Section titled “Overrides”preRestart()
Section titled “preRestart()”preRestart(
_reason,_message?):void|Promise<void>
Defined in: src/Actor.ts:119
Called before a restart, on the instance about to be thrown away.
The default calls postStop() and nothing else.
Override to release what the instance holds outside itself — a file handle, an open socket, a broker connection — or to do something other than drop the message that failed.
Stopping this actor’s children is not done here: the framework tears
them down after this hook returns and waits for them before building the
replacement, because postRestart re-runs preStart and a named child
needs its name back. To keep the children instead, see
Actor.stopChildrenOnRestart.
Parameters
Section titled “Parameters”_reason
Section titled “_reason”Error
_message?
Section titled “_message?”Command | ReplicatedEventEnvelope<Event>
Returns
Section titled “Returns”void | Promise<void>
Inherited from
Section titled “Inherited from”preStart()
Section titled “preStart()”preStart():
Promise<void>
Defined in: src/persistence/ReplicatedEventSourcedActor.ts:247
Called after construction and before the first message is processed.
Returns
Section titled “Returns”Promise<void>
Overrides
Section titled “Overrides”stopChildrenOnRestart()
Section titled “stopChildrenOnRestart()”stopChildrenOnRestart():
boolean
Defined in: src/Actor.ts:149
Whether a restart tears this actor’s children down before rebuilding it.
Default: true.
A restart replaces the Actor instance while the cell — and therefore
the child map — survives. Keeping the children was the old behaviour and
it made an ordinary pattern impossible: postRestart re-runs preStart,
so an actor that spawns a named child there hit Child name … is not unique on its first restart and never recovered (#634).
Override to false when the children are expensive to rebuild, hold
state the parent cannot restore, or are supervised independently — a
connection pool, say. They then outlive the restart exactly as before,
and it is on you to make preStart idempotent — by adopting the survivor
from the cell, this.child = this.context.child('name').toNullable() ?? this.context.spawn(Child, 'name'), or with context.spawnAnonymous.
An instance field cannot do it: preStart runs on a fresh instance
after every restart, so this.child ??= … is always unset and re-spawns
into the name the surviving child still holds, which fails the spawn and
restarts the actor again.
This is a separate hook rather than a preRestart override because the
teardown has to be awaited: the new instance cannot be built until the
old children are actually gone, and preRestart has no way to tell the
cell that it started something worth waiting for.
Returns
Section titled “Returns”boolean
Inherited from
Section titled “Inherited from”supervisorStrategy()
Section titled “supervisorStrategy()”supervisorStrategy():
SupervisorStrategy
Defined in: src/Actor.ts:160
Supervisor strategy for this actor’s children. Defaults to restart, up to 10 times per minute, then stop.