ActorSystem

Defined in: src/ActorSystem.ts:70

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:78

Full merged configuration in effect for this system.

---

deadLetters

readonly deadLetters: ActorRef

Defined in: src/ActorSystem.ts:76

---

dispatcher

readonly dispatcher: Dispatcher

Defined in: src/ActorSystem.ts:72

---

eventStream

readonly eventStream: EventStream

Defined in: src/ActorSystem.ts:74

---

extensions

readonly extensions: Extensions

Defined in: src/ActorSystem.ts:80

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

---

log

readonly log: Logger

Defined in: src/ActorSystem.ts:75

---

name

readonly name: string

Defined in: src/ActorSystem.ts:71

---

scheduler

readonly scheduler: Scheduler

Defined in: src/ActorSystem.ts:73

Accessors

isTerminated

Get Signature

get isTerminated(): boolean

Defined in: src/ActorSystem.ts:273

Returns

boolean

Methods

actorSelection()

actorSelection(path): ActorSelection

Defined in: src/ActorSystem.ts:228

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:144

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, opts?): ServerBuilder

Defined in: src/ActorSystem.ts:165

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

opts?

backend?

HttpServerBackend

host?

string

Returns

ServerBuilder

---

spawn()

spawn<T>(props, name): ActorRef<T>

Defined in: src/ActorSystem.ts:181

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.

Type Parameters

T

T

Parameters

props

Props<T>

name

string

Returns

ActorRef<T>

---

spawnAnonymous()

spawnAnonymous<T>(props): ActorRef<T>

Defined in: src/ActorSystem.ts:194

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

props

Props<T>

Returns

ActorRef<T>

---

spawnTyped()

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

Defined in: src/ActorSystem.ts:209

Spawn a typed Behavior under /user with a deterministic name — the Behavior-DSL counterpart to spawn. Wraps the Behavior in typedProps(behavior) so callers don’t have to thread Props 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:218

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:252

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:257

Shut down: stops /user (children first) and resolves once everything is drained.

Returns

Promise<void>

---

whenTerminated()

whenTerminated(): Promise<void>

Defined in: src/ActorSystem.ts:266

Promise that resolves when the system has finished shutting down.

Returns

Promise<void>

---

create()

static create(name?, settings?): ActorSystem

Defined in: src/ActorSystem.ts:136

Create a new actor system.

Parameters

name?

string = 'default'

settings?

ActorSystemSettings = {}

Returns

ActorSystem