ActorSystem
このコンテンツはまだ日本語訳がありません。
Defined in: src/ActorSystem.ts:140
The ActorSystem is the top-level container for actors. It owns the root guardians, the event stream, the scheduler, and the default dispatcher. Create one per logical application.
Properties
Section titled “Properties”config
Section titled “config”
readonlyconfig:Config
Defined in: src/ActorSystem.ts:311
Full merged configuration in effect for this system.
deadLetterQueue
Section titled “deadLetterQueue”
readonlydeadLetterQueue:DeadLetterQueue
Defined in: src/ActorSystem.ts:309
Bounded record of the messages this system could not deliver.
Always present, and capturing nothing unless actor-ts.dead-letters.store
says otherwise — so list() on a default system answers “nothing kept”,
which is the truth, rather than throwing or being undefined.
deadLetters
Section titled “deadLetters”
readonlydeadLetters:ActorRef
Defined in: src/ActorSystem.ts:301
dispatcher
Section titled “dispatcher”
readonlydispatcher:Dispatcher
Defined in: src/ActorSystem.ts:149
eventStream
Section titled “eventStream”
readonlyeventStream:EventStream
Defined in: src/ActorSystem.ts:181
extensions
Section titled “extensions”
readonlyextensions:Extensions
Defined in: src/ActorSystem.ts:313
Per-system extension registry (serialization, sharding, pubsub, …).
readonlylog:Logger
Defined in: src/ActorSystem.ts:182
readonlyname:string
Defined in: src/ActorSystem.ts:141
scheduler
Section titled “scheduler”
readonlyscheduler:Scheduler
Defined in: src/ActorSystem.ts:150
startedAtMs
Section titled “startedAtMs”
readonlystartedAtMs:number
Defined in: src/ActorSystem.ts:148
Wall-clock time this system was created. Stamped first in the
constructor, so Date.now() - startedAtMs is the system’s uptime —
the one clock that survives a monitoring tool attaching, detaching,
or reconnecting halfway through the run.
Accessors
Section titled “Accessors”Get Signature
Section titled “Get Signature”get clock():
Clock
Defined in: src/ActorSystem.ts:165
What time it is, according to this system.
The same object as scheduler, narrowed to the one method, and the
narrowing is the point: a component that only reads the time should take
system.clock rather than the whole scheduler, so its dependency says
what it actually needs and a test can supply a clock without also
granting it the power to arm timers.
Under a ManualScheduler this is virtual time, which is the whole point:
a component reading it advances with advance() instead of with the wall
clock, and a test can say “a minute passed” in a millisecond.
Returns
Section titled “Returns”cluster
Section titled “cluster”Get Signature
Section titled “Get Signature”get cluster():
Option<Cluster>
Defined in: src/ActorSystem.ts:721
The Cluster this system joined, or None if it never did (#833).
Filled in by Cluster.join, so a local-only system stays local — the
getter never starts a cluster. Inside an actor prefer
this.context.cluster (same Option) or this.cluster (unwrapped,
for code that already knows it is clustered).
The Cluster type is imported type-only and the value import is just
the extension id, which is why core can hand out a cluster without
depending on the cluster layer at runtime — the same split
EntityContext uses.
Returns
Section titled “Returns”Option<Cluster>
isTerminated
Section titled “isTerminated”Get Signature
Section titled “Get Signature”get isTerminated():
boolean
Defined in: src/ActorSystem.ts:1416
Returns
Section titled “Returns”boolean
Methods
Section titled “Methods”actorSelection()
Section titled “actorSelection()”actorSelection(
path):ActorSelection
Defined in: src/ActorSystem.ts:921
Build an ActorSelection that resolves a path at lookup time. Accepts
- a fully-qualified URI (“actor-ts://sys/user/foo/bar”)
- an absolute path (“/user/foo/bar” or “user/foo/bar”) Wildcards are not supported in v1.
Parameters
Section titled “Parameters”string
Returns
Section titled “Returns”awaitQuiescence()
Section titled “awaitQuiescence()”awaitQuiescence(
timeoutMs?):Promise<boolean>
Defined in: src/ActorSystem.ts:1291
Wait until nothing under /user has work left it can dispatch, or until
timeoutMs elapses. Resolves true if the tree went quiet, false if
the budget ran out first.
“Quiet” is per cell: no turn in flight and no dispatchable message queued.
Because a cell is marked busy at tell time — synchronously, by the
sender’s turn — a reply that has been sent but not yet run already counts,
which is what carries the wait across a ping-pong, a router fan-out or a
supervision restart instead of flushing one mailbox once.
Two kinds of mailbox are deliberately not waited on, because neither
drains at a rate a shutdown could wait for: one parked by
context.throttle(...), and one suspended while its actor’s supervisor
decides. Both are treated as quiet, and whatever is still queued in them
is dead-lettered by the ordinary teardown.
Only /user is inspected. Framework actors under /system — cluster
heartbeats, failure detectors, broker reconnect loops — are never quiet by
design, so including them would spend the whole budget on every shutdown.
Work that is not in a mailbox yet is not waited for either: a scheduled
tick, or a tell from a promise the handler did not await, can still
arrive after this resolves.
Parameters
Section titled “Parameters”timeoutMs?
Section titled “timeoutMs?”number = ...
Returns
Section titled “Returns”Promise<boolean>
extension()
Section titled “extension()”extension<
T>(id):T
Defined in: src/ActorSystem.ts:704
Convenience shortcut for system.extensions.get(id) — the one-liner
used throughout the codebase to resolve an extension by its id.
Type Parameters
Section titled “Type Parameters”T extends Extension
Parameters
Section titled “Parameters”ExtensionId<T>
Returns
Section titled “Returns”T
http()
Section titled “http()”http(
port,options?):ServerBuilder
Defined in: src/ActorSystem.ts:753
Shortcut — bind an HTTP server on port (and optionally host)
with the framework’s default Fastify backend. Equivalent to:
system.extension(HttpExtensionId) .newServerAt(host ?? '127.0.0.1', port) .useBackend(backend ?? new FastifyBackend())The default host is loopback, and that is a change (#1408). It used
to be the IPv4 wildcard, which made the shortest and most-copied form of
this call the one that published the server on every interface — a
decision nothing at the call site recorded and most callers never made.
A server that should be reachable from outside the host now says so, by
passing the interface it means through options.host.
The wildcard is deliberately not spelled out here: this comment is a
copy-paste surface, and tests/unit/ci/ExampleBindAddresses.test.ts
flags one baked into a snippet for exactly that reason (#756).
For non-default backends, pass backend: — typically
new ExpressBackend(opts) or new HonoBackend(opts). Returns
the ServerBuilder so you can chain .bind(routes):
const binding = await system.http(8080).bind(routes);Note — FastifyBackend is a hard dependency of the framework
(not a peer-dep), so the default path needs no extra installs.
Parameters
Section titled “Parameters”number
options?
Section titled “options?”backend?
Section titled “backend?”HttpServerBackend
string
Returns
Section titled “Returns”ServerBuilder
runUntilTerminated()
Section titled “runUntilTerminated()”runUntilTerminated(
signals?):Promise<void>
Defined in: src/ActorSystem.ts:1483
Run until the process is asked to stop, then shut down gracefully —
the whole of a service’s main after the actors are wired:
const system = ActorSystem.create('orders', systemOptions);await system.http(8080).bind(routes);await system.runUntilTerminated();The startup graph needs no call of its own here: the system starts it as
the last step of create, /ready stays false until it completes, and a
startup task that fails takes the system down — at which point this
promise rejects with the startup’s error, after the handlers and the
keep-alive below have come off. A main that awaits it therefore exits
by itself, non-zero, without catching anything (#1473).
Installs SIGTERM/SIGINT handlers that start
CoordinatedShutdown, resolves once the system is fully down,
and detaches the handlers on the way out. That last step is why this
exists as a method rather than a documented three-liner: the handlers
have to come off in a finally, or a Deno program that shuts down for
any other reason — a terminate() from inside, an operator command —
never exits, because a Deno.addSignalListener listener holds the event
loop open and has no unref.
What replaces the hand-rolled process.on('SIGTERM', () => { … }) is
not just the signal plumbing but the ordering. A handler that
calls a bare terminate() stops the actors first and only then, if ever,
releases the port and leaves the cluster; the pipeline unbinds in
service-unbind, closes brokers in service-stop and leaves the
cluster in cluster-leave, all before actor-system-terminate — so a
rolling deploy takes the node out of rotation while its actors can
still finish what they are holding.
Resolves when the pipeline is finished, not merely when the system is down: a task registered alongside the built-in terminator in the final phase runs in parallel with it, and returning while one of those is still going would hand back a “shutdown complete” that is not.
The process stays alive for as long as this promise is pending, and
that is a guarantee this method makes rather than one it inherits. A
signal handler is not a reason for a runtime to keep running: Node’s
signal handles are unref’d, so a system with nothing else on the event
loop — no bound port, no open socket, every timer unref’d — used to
drain its loop the moment it started waiting and exit instead of ever
receiving the SIGTERM it had just armed itself for. Bun refs its
handles and Deno’s Deno.addSignalListener cannot be unref’d at all, so
the same program waited correctly on two runtimes out of three (#549).
A keep-alive timer, released in the same finally as the handlers,
makes the three agree.
Parameters
Section titled “Parameters”signals?
Section titled “signals?”readonly ProcessSignal[]
Which signals to listen for. Defaults to SIGTERM and SIGINT. One the runtime cannot deliver is skipped — Windows has no SIGTERM under any runtime — so this never fails to start over a platform difference. Note that skipping them all does not turn this into a no-op: the promise still waits, and the process still stays alive, until something shuts the system down from inside.
Naming any signal here is an explicit request and always installs.
Leaving it unset takes the default from
actor-ts.coordinated-shutdown.run-by-process-signals, which a host
process that owns SIGTERM itself can turn off — the wait and the
keep-alive are unaffected, only the handlers go.
Returns
Section titled “Returns”Promise<void>
spawn()
Section titled “spawn()”spawn<
T>(actor,name,options?):ActorRef<T>
Defined in: src/ActorSystem.ts:773
Spawn a top-level user actor under /user with a deterministic
caller-supplied name. The name must be unique among siblings
(i.e. children of /user) — if a child with the same name
already exists, the call throws.
For an auto-generated name, see spawnAnonymous.
system.spawn(Greeter, 'greeter'); // zero-arg classsystem.spawn(() => new Worker(database), 'worker'); // dependenciesType Parameters
Section titled “Type Parameters”T
Parameters
Section titled “Parameters”string
options?
Section titled “options?”ActorOptions<T>
Returns
Section titled “Returns”ActorRef<T>
spawnAnonymous()
Section titled “spawnAnonymous()”spawnAnonymous<
T>(actor,options?):ActorRef<T>
Defined in: src/ActorSystem.ts:790
Spawn a top-level user actor under /user with an auto-generated name. Use when the caller doesn’t care about the path — e.g. one-shot async work, throwaway helpers. For a deterministic name, see spawn.
Type Parameters
Section titled “Type Parameters”T
Parameters
Section titled “Parameters”options?
Section titled “options?”ActorOptions<T>
Returns
Section titled “Returns”ActorRef<T>
spawnTyped()
Section titled “spawnTyped()”spawnTyped<
T>(behavior,name):ActorRef<T>
Defined in: src/ActorSystem.ts:840
Spawn a typed Behavior under /user with a deterministic name —
the Behavior-DSL counterpart to spawn. Wraps the Behavior
in typedActor(behavior) so callers don’t have to thread a factory
through the typed API.
const ref = system.spawnTyped(counter(0), 'counter');Type Parameters
Section titled “Type Parameters”T
Parameters
Section titled “Parameters”behavior
Section titled “behavior”Behavior<T>
string
Returns
Section titled “Returns”ActorRef<T>
spawnTypedAnonymous()
Section titled “spawnTypedAnonymous()”spawnTypedAnonymous<
T>(behavior):ActorRef<T>
Defined in: src/ActorSystem.ts:849
Anonymous variant of spawnTyped — the Behavior-DSL counterpart to spawnAnonymous. Pick this when the caller doesn’t need a stable path.
Type Parameters
Section titled “Type Parameters”T
Parameters
Section titled “Parameters”behavior
Section titled “behavior”Behavior<T>
Returns
Section titled “Returns”ActorRef<T>
stop()
Section titled “stop()”stop(
ref):void
Defined in: src/ActorSystem.ts:983
Stop an actor once it has worked through its mailbox — fire and forget.
The same graceful stop ActorRef.stop() performs, and like it this
returns nothing: the JSDoc promised a promise for a signature that never
had one (#663). Await the stop with gracefulStop(ref, timeoutMs).
Parameters
Section titled “Parameters”Returns
Section titled “Returns”void
terminate()
Section titled “terminate()”terminate(
options?):Promise<void>
Defined in: src/ActorSystem.ts:1056
Shut down: drains /user, stops it (children first), then /system, and
resolves once everything is torn down. The two guardians go in sequence
so a user actor’s postStop can still reach the framework actors it
depends on — see GUARDIAN_SHUTDOWN_ORDER.
The drain in front is what makes ref.tell(x); await system.terminate()
deliver x (#663). It has to be here rather than inside the cascade
because a terminate is a system command: ActorCell.run() re-checks
its system queue after every await, so a terminate that lands in a
running turn’s await window is picked up before the user message queued
behind it — and the cell that has flipped to terminating no longer
dequeues user messages at all, so the rest went to dead letters. Waiting
for quiescence before the first terminate is enqueued is the only
ordering that does not fight that, and it leaves the teardown itself
exactly as it was.
Bounded by actor-ts.system.shutdown-drain-timeout; set it to 0 to skip
the drain entirely. See awaitQuiescence for what “quiet” means
and which mailboxes are deliberately not waited on.
The coordinated-shutdown pipeline runs only when asked for. On its
own this is the teardown above and nothing more: no task registered with
CoordinatedShutdown runs, so the HTTP unbind, the cluster leave
and every phase task the application added are skipped — a bound port
keeps answering and a joined node stays up for its peers. Pass
runCoordinatedShutdown: true and every phase runs first, with
ActorSystemTerminateReason; the promise then resolves once the
pipeline has finished and the system is down, as runUntilTerminated()
does. The teardown follows the run even when the run does not end in one
— terminate-actor-system = false leaves the last phase without its
terminator, and a failing phase with recover = false halts the pipeline
short of it — because the caller asked for a terminated system, and a
terminate() that left one running would be the worse surprise (#1455).
Unless exit-process ends the process where the run ends — at the halt,
or after a last phase with no terminator in it — once the dead-letter
queue and the log sinks are flushed: nothing follows process.exit, this
teardown included.
actor-ts.coordinated-shutdown.run-by-actor-system-terminate = true makes
that the default for every call that does not choose; a call’s own
runCoordinatedShutdown still wins over the config, false included.
Outside a run, once a teardown has started, a later call joins it whichever form it takes: a pipeline started over a half-stopped tree would unbind and leave after the actors it exists to protect have already gone.
While a coordinated-shutdown run is in flight, terminate() starts
nothing and resolves at once, in either form — whoever started the run,
a signal, a run() or another terminate(). Joining the run instead
would stall the commonest such caller: a task of that run awaiting
terminate() waits on its own run, and holds its phase until the phase’s
budget abandons it. Tearing down on the spot would stop the actors in
the middle of the pipeline and run every later phase on a dead system.
The run ends in the teardown anyway; a caller outside the pipeline that
needs the system down awaits whenTerminated. A task of the run
must not: the teardown it would wait for is in the last phase, which
cannot start before the task’s own phase ends, so the wait is the same
stall — only a task of actor-system-terminate runs beside the
terminator. Nor is the request dropped: a run that does not end in the
teardown — no terminator in its last phase, or a halt before it — is
followed by one, unless exit-process ends the process at the end of
that run, which nothing follows.
A startup still running is abandoned, in either form (#1473): the
running tasks’ signals abort, no further phase starts, and
whenReady rejects with an abandonment error. That is not a
startup failure — the caller asked for the system to go — so it starts no
shutdown of its own and runUntilTerminated() resolves as usual.
Parameters
Section titled “Parameters”options?
Section titled “options?”Returns
Section titled “Returns”Promise<void>
whenReady()
Section titled “whenReady()”whenReady():
Promise<void>
Defined in: src/ActorSystem.ts:1382
Resolves once the startup graph has run every phase — the tasks passed to
ActorSystemOptions.withCoordinatedStartup, and those the framework adds
itself, such as opening the selected persistence stores — which the
system starts by itself as the last step of create (#1473).
Rejects with an error naming the phase and the task when a task fails or outlives its phase’s budget — by then the system is already shutting down — and with an abandonment error when the system is terminated before startup finished. The same promise every call; a system with no startup tasks is ready at once.
Nothing has to await it: the startup readiness check keeps /ready
false while the graph runs, and a failed startup takes the system down on
its own. It is for the code that must not run before startup has — a
first message that needs the journal open, say.
Returns
Section titled “Returns”Promise<void>
whenTerminated()
Section titled “whenTerminated()”whenTerminated():
Promise<void>
Defined in: src/ActorSystem.ts:1409
Promise that resolves when the system has finished shutting down.
Returns
Section titled “Returns”Promise<void>
create()
Section titled “create()”
staticcreate(name?,options?):ActorSystem
Defined in: src/ActorSystem.ts:693
Create a new actor system. Omitting name falls back to
actor-ts.system.name and, failing that, to "default" — so a
deployment can name its system from config without a rebuild.
Parameters
Section titled “Parameters”string
options?
Section titled “options?”ActorSystemOptions = {}
Returns
Section titled “Returns”ActorSystem
