ShardCoordinatorSettings

Defined in: src/cluster/sharding/ShardCoordinator.ts:62

Properties

acquireRetryIntervalMs?

readonly optional acquireRetryIntervalMs?: number

Defined in: src/cluster/sharding/ShardCoordinator.ts:86

Retry interval for lease.acquire() after a failed attempt. Default: 5 s.

---

allocationStrategy

readonly allocationStrategy: AllocationStrategy

Defined in: src/cluster/sharding/ShardCoordinator.ts:65

---

cluster

readonly cluster: Cluster

Defined in: src/cluster/sharding/ShardCoordinator.ts:64

---

coordinatorStateStore?

readonly optional coordinatorStateStore?: CoordinatorStateStore

Defined in: src/cluster/sharding/ShardCoordinator.ts:115

Optional persistence backend for the allocation state itself (regions + shardHome). Without it, LeaderChanged triggers a full rebuild from Register gossip — fine for a few hundred shards, painful at thousands. With it, the new leader loads the last-known snapshot from the store (e.g. DistributedData) and skips the reallocation storm.

ClusterSharding does NOT auto-instantiate this — the user must explicitly start a DistributedData extension first and pass new DistributedDataCoordinatorStateStore(...). Without that opt-in, ShardCoordinator keeps the v1 rebuild-from- Register behaviour (backwards-compat).

---

handOffTimeoutMs?

readonly optional handOffTimeoutMs?: number

Defined in: src/cluster/sharding/ShardCoordinator.ts:68

---

lease?

readonly optional lease?: Lease

Defined in: src/cluster/sharding/ShardCoordinator.ts:84

Optional split-brain protection. When set, the elected leader’s coordinator must hold the lease before it processes shard messages. Under a network partition where two nodes converge to “I am the leader” gossip views, only the side that successfully acquires the lease ever issues AllocateShard / HandOff directives — the other side stays passive and drops messages (regions retry naturally on their next cache miss).

Without a lease the coordinator gates only on isLeader() — v1 behaviour, no extra coordination.

---

localResolver

readonly localResolver: (path) => ActorRef<unknown> | null

Defined in: src/cluster/sharding/ShardCoordinator.ts:71

Resolver for local actor paths — used when coordinator lives on the same node as a region.

Parameters

path

string

Returns

ActorRef<unknown> | null

---

rebalanceIntervalMs?

readonly optional rebalanceIntervalMs?: number

Defined in: src/cluster/sharding/ShardCoordinator.ts:67

---

rememberEntities?

readonly optional rememberEntities?: boolean

Defined in: src/cluster/sharding/ShardCoordinator.ts:69

---

rememberEntitiesStore?

readonly optional rememberEntitiesStore?: RememberEntitiesStore

Defined in: src/cluster/sharding/ShardCoordinator.ts:100

Optional persistence backend for the entity registry. Only used when rememberEntities: true. Without it, entitiesPerShard stays in-memory only and a full cluster restart loses the registry — until messages re-arrive and trigger fresh EntityStarted notifications. Set to a JournalRememberEntitiesStore (or any custom impl) to make the registry survive cold-starts.

The ClusterSharding extension auto-instantiates the default JournalRememberEntitiesStore (using the active Journal) when rememberEntities: true and no explicit store is provided — so most users don’t need to touch this field.

---

role?

readonly optional role?: string

Defined in: src/cluster/sharding/ShardCoordinator.ts:66

---

typeName

readonly typeName: string

Defined in: src/cluster/sharding/ShardCoordinator.ts:63