Skip to content
English

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.

readonly config: Config

Defined in: src/ActorSystem.ts:311

Full merged configuration in effect for this system.


readonly deadLetterQueue: 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.


readonly deadLetters: ActorRef

Defined in: src/ActorSystem.ts:301


readonly dispatcher: Dispatcher

Defined in: src/ActorSystem.ts:149


readonly eventStream: EventStream

Defined in: src/ActorSystem.ts:181


readonly extensions: Extensions

Defined in: src/ActorSystem.ts:313

Per-system extension registry (serialization, sharding, pubsub, …).


readonly log: Logger

Defined in: src/ActorSystem.ts:182


readonly name: string

Defined in: src/ActorSystem.ts:141


readonly scheduler: Scheduler

Defined in: src/ActorSystem.ts:150


readonly startedAtMs: 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.

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.

Clock


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.

Option<Cluster>


get isTerminated(): boolean

Defined in: src/ActorSystem.ts:1416

boolean

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.

string

ActorSelection


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.

number = ...

Promise<boolean>


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.

T extends Extension

ExtensionId<T>

T


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.

number

HttpServerBackend

string

ServerBuilder


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.

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.

Promise<void>


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 class
system.spawn(() => new Worker(database), 'worker'); // dependencies

T

ActorClassOrFactory<T>

string

ActorOptions<T>

ActorRef<T>


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.

T

ActorClassOrFactory<T>

ActorOptions<T>

ActorRef<T>


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');

T

Behavior<T>

string

ActorRef<T>


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.

T

Behavior<T>

ActorRef<T>


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).

ActorRef

void


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.

TerminateOptions

Promise<void>


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.

Promise<void>


whenTerminated(): Promise<void>

Defined in: src/ActorSystem.ts:1409

Promise that resolves when the system has finished shutting down.

Promise<void>


static create(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.

string

ActorSystemOptions = {}

ActorSystem