ActorSystem

Defined in: src/ActorSystem.ts:47

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

config

readonly config: Config

Defined in: src/ActorSystem.ts:62

Full merged configuration in effect for this system.

---

deadLetters

readonly deadLetters: ActorRef

Defined in: src/ActorSystem.ts:60

---

dispatcher

readonly dispatcher: Dispatcher

Defined in: src/ActorSystem.ts:56

---

eventStream

readonly eventStream: EventStream

Defined in: src/ActorSystem.ts:58

---

extensions

readonly extensions: Extensions

Defined in: src/ActorSystem.ts:64

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

---

log

readonly log: Logger

Defined in: src/ActorSystem.ts:59

---

name

readonly name: string

Defined in: src/ActorSystem.ts:48

---

scheduler

readonly scheduler: Scheduler

Defined in: src/ActorSystem.ts:57

---

startedAtMs

readonly startedAtMs: number

Defined in: src/ActorSystem.ts:55

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

cluster

Get Signature

get cluster(): Option<Cluster>

Defined in: src/ActorSystem.ts:195

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

Option<Cluster>

---

isTerminated

Get Signature

get isTerminated(): boolean

Defined in: src/ActorSystem.ts:426

Returns

boolean

Methods

actorSelection()

actorSelection(path): ActorSelection

Defined in: src/ActorSystem.ts:344

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

path

string

Returns

ActorSelection

---

extension()

extension<T>(id): T

Defined in: src/ActorSystem.ts:178

Convenience shortcut for system.extensions.get(id) — the one-liner used throughout the codebase to resolve an extension by its id.

Type Parameters

T

T extends Extension

Parameters

id

ExtensionId<T>

Returns

T

---

http()

http(port, options?): ServerBuilder

Defined in: src/ActorSystem.ts:216

Shortcut — bind an HTTP server on port (and optionally host) with the framework’s default Fastify backend. Equivalent to:

system.extension(HttpExtensionId)
      .newServerAt(host ?? '0.0.0.0', port)
      .useBackend(backend ?? new FastifyBackend())

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

port

number

options?

backend?

HttpServerBackend

host?

string

Returns

ServerBuilder

---

spawn()

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

Defined in: src/ActorSystem.ts:235

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

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/ActorSystem.ts:248

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

T

T

Parameters

actor

ActorClassOrFactory<T>

options?

ActorOptions<T>

Returns

ActorRef<T>

---

spawnTyped()

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

Defined in: src/ActorSystem.ts:263

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

T

T

Parameters

behavior

Behavior<T>

name

string

Returns

ActorRef<T>

---

spawnTypedAnonymous()

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

Defined in: src/ActorSystem.ts:272

Anonymous variant of spawnTyped — the Behavior-DSL counterpart to spawnAnonymous. Pick this when the caller doesn’t need a stable path.

Type Parameters

T

T

Parameters

behavior

Behavior<T>

Returns

ActorRef<T>

---

stop()

stop(ref): void

Defined in: src/ActorSystem.ts:400

Stop any actor by reference. Returns a promise that resolves once it is fully terminated.

Parameters

ref

ActorRef

Returns

void

---

terminate()

terminate(): Promise<void>

Defined in: src/ActorSystem.ts:410

Shut down: stops /user (children first), then /system, and resolves once everything is drained. 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.

Returns

Promise<void>

---

whenTerminated()

whenTerminated(): Promise<void>

Defined in: src/ActorSystem.ts:419

Promise that resolves when the system has finished shutting down.

Returns

Promise<void>

---

create()

static create(name?, options?): ActorSystem

Defined in: src/ActorSystem.ts:167

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

name?

string

options?

ActorSystemOptions = {}

Returns

ActorSystem