ClusterSingleton

Defined in: src/cluster/singleton/ClusterSingleton.ts:49

Extension that manages every cluster singleton declared in this process.

Reach it through Cluster.singleton; start hands back the location-transparent ActorRef directly, so a singleton is addressed exactly like any other actor:

class JobSchedulerActor extends Actor<SchedulerCommand> {
  static readonly singleton = SingletonKey.of<SchedulerCommand>('job-scheduler');
  onReceive(command: SchedulerCommand): void { … }
}

const scheduler = cluster.singleton.start(JobSchedulerActor);
scheduler.tell({ kind: 'schedule', jobId: '42' });

start is get-or-create per typeName on this node, so calling it from several modules is safe and no getOrCreate wrapper is needed. Nodes that only need to talk to the singleton call ref instead and never host a manager.

Implements

• Extension

Constructors

Constructor

new ClusterSingleton(system): ClusterSingleton

Defined in: src/cluster/singleton/ClusterSingleton.ts:57

Parameters

system

ActorSystem

Returns

ClusterSingleton

Methods

isStarted()

isStarted(reference): boolean

Defined in: src/cluster/singleton/ClusterSingleton.ts:178

True if this node runs a manager for reference — i.e. it can become the host.

Parameters

reference

SingletonReference

Returns

boolean

---

managerFor()

managerFor(reference): Option<ActorRef<unknown>>

Defined in: src/cluster/singleton/ClusterSingleton.ts:173

This node’s manager, if it called start. Diagnostics and tests — application code addresses the singleton through the ref, not the manager.

Parameters

reference

SingletonReference

Returns

Option<ActorRef<unknown>>

---

ref()

Call Signature

ref<TCommand>(key): ActorRef<TCommand>

Defined in: src/cluster/singleton/ClusterSingleton.ts:147

A ref to the singleton without hosting it — the counterpart to ClusterSharding.startProxy.

Works on a node that never calls start: messages route to whichever node currently hosts the singleton. If that node later calls start, the same ref begins delivering through the local mailbox instead of over the wire — the manager is resolved per delivery, not captured.

Type Parameters

TCommand

TCommand

Parameters

key

SingletonKey<TCommand> | SingletonKeyedClass<TCommand>

Returns

ActorRef<TCommand>

Call Signature

ref<TCommand>(typeName): ActorRef<TCommand>

Defined in: src/cluster/singleton/ClusterSingleton.ts:148

A ref to the singleton without hosting it — the counterpart to ClusterSharding.startProxy.

Works on a node that never calls start: messages route to whichever node currently hosts the singleton. If that node later calls start, the same ref begins delivering through the local mailbox instead of over the wire — the manager is resolved per delivery, not captured.

Type Parameters

TCommand

TCommand

Parameters

typeName

string

Returns

ActorRef<TCommand>

---

start()

Call Signature

start<TCommand>(actorClass, options?): ActorRef<TCommand>

Defined in: src/cluster/singleton/ClusterSingleton.ts:109

Start (or look up) the singleton and return the ref to address it with.

// The class declares its own key and takes no constructor arguments.
const scheduler = cluster.singleton.start(JobSchedulerActor);

// Same, but the actor needs dependencies.
const users = cluster.singleton.start(UserRepositoryActor, () => new UserRepositoryActor(shard));

// A bare key, for an actor that does not declare one.
const cron = cluster.singleton.start(SingletonKey.of<CronCommand>('cron'), CronActor);

// Full form — needed for `role` / `lease`, and combinable with the above.
const ingress = cluster.singleton.start(
  StartSingletonOptions.create<IngressCommand>()
    .withTypeName('http-ingress')
    .withActor(() => new HttpIngressActor(port)),
);

Idempotent per typeName on this node: a repeat call returns the same ref and ignores the new options. Every node that may host the singleton has to call this — ref alone never hosts.

Type Parameters

TCommand

TCommand

Parameters

actorClass

SingletonActorClass<TCommand>

options?

StartSingletonOptions<TCommand>

Returns

ActorRef<TCommand>

Call Signature

start<TCommand>(actorClass, factory, options?): ActorRef<TCommand>

Defined in: src/cluster/singleton/ClusterSingleton.ts:113

Start (or look up) the singleton and return the ref to address it with.

// The class declares its own key and takes no constructor arguments.
const scheduler = cluster.singleton.start(JobSchedulerActor);

// Same, but the actor needs dependencies.
const users = cluster.singleton.start(UserRepositoryActor, () => new UserRepositoryActor(shard));

// A bare key, for an actor that does not declare one.
const cron = cluster.singleton.start(SingletonKey.of<CronCommand>('cron'), CronActor);

// Full form — needed for `role` / `lease`, and combinable with the above.
const ingress = cluster.singleton.start(
  StartSingletonOptions.create<IngressCommand>()
    .withTypeName('http-ingress')
    .withActor(() => new HttpIngressActor(port)),
);

Idempotent per typeName on this node: a repeat call returns the same ref and ignores the new options. Every node that may host the singleton has to call this — ref alone never hosts.

Type Parameters

TCommand

TCommand

Parameters

actorClass

SingletonKeyedClass<TCommand>

factory

() => Actor<TCommand>

options?

StartSingletonOptions<TCommand>

Returns

ActorRef<TCommand>

Call Signature

start<TCommand>(key, actor, options?): ActorRef<TCommand>

Defined in: src/cluster/singleton/ClusterSingleton.ts:118

Start (or look up) the singleton and return the ref to address it with.

// The class declares its own key and takes no constructor arguments.
const scheduler = cluster.singleton.start(JobSchedulerActor);

// Same, but the actor needs dependencies.
const users = cluster.singleton.start(UserRepositoryActor, () => new UserRepositoryActor(shard));

// A bare key, for an actor that does not declare one.
const cron = cluster.singleton.start(SingletonKey.of<CronCommand>('cron'), CronActor);

// Full form — needed for `role` / `lease`, and combinable with the above.
const ingress = cluster.singleton.start(
  StartSingletonOptions.create<IngressCommand>()
    .withTypeName('http-ingress')
    .withActor(() => new HttpIngressActor(port)),
);

Idempotent per typeName on this node: a repeat call returns the same ref and ignores the new options. Every node that may host the singleton has to call this — ref alone never hosts.

Type Parameters

TCommand

TCommand

Parameters

key

SingletonKey<TCommand>

actor

ActorClassOrFactory<TCommand>

options?

StartSingletonOptions<TCommand>

Returns

ActorRef<TCommand>

Call Signature

start<TCommand>(options): ActorRef<TCommand>

Defined in: src/cluster/singleton/ClusterSingleton.ts:123

Start (or look up) the singleton and return the ref to address it with.

// The class declares its own key and takes no constructor arguments.
const scheduler = cluster.singleton.start(JobSchedulerActor);

// Same, but the actor needs dependencies.
const users = cluster.singleton.start(UserRepositoryActor, () => new UserRepositoryActor(shard));

// A bare key, for an actor that does not declare one.
const cron = cluster.singleton.start(SingletonKey.of<CronCommand>('cron'), CronActor);

// Full form — needed for `role` / `lease`, and combinable with the above.
const ingress = cluster.singleton.start(
  StartSingletonOptions.create<IngressCommand>()
    .withTypeName('http-ingress')
    .withActor(() => new HttpIngressActor(port)),
);

Idempotent per typeName on this node: a repeat call returns the same ref and ignores the new options. Every node that may host the singleton has to call this — ref alone never hosts.

Type Parameters

TCommand

TCommand

Parameters

options

StartSingletonOptions<TCommand>

Returns

ActorRef<TCommand>

---

stop()

stop(reference): void

Defined in: src/cluster/singleton/ClusterSingleton.ts:161

Take this node out of rotation: stop the local manager (and with it the singleton, if this node was hosting) and drop the local proxy.

Stopping is asynchronous — the manager releases its lease and its envelope path in postStop. Starting the same singleton again on this node has to wait for that to settle.

Parameters

reference

SingletonReference

Returns

void

---

get()

static get(system, cluster): ClusterSingleton

Defined in: src/cluster/singleton/ClusterSingleton.ts:66

Explicit counterpart to cluster.singleton, mirroring ClusterSharding.get(system, cluster) — for callers that hold the system and the cluster separately.

Parameters

system

ActorSystem

cluster

Cluster

Returns

ClusterSingleton