StartSettings

Defined in: src/cluster/sharding/ClusterSharding.ts:22

Extends

• ShardingSettings<TMsg>

Type Parameters

TMsg

TMsg

Properties

acquireRetryIntervalMs?

readonly optional acquireRetryIntervalMs?: number

Defined in: src/cluster/sharding/ClusterSharding.ts:39

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

---

allocationStrategy?

readonly optional allocationStrategy?: AllocationStrategy

Defined in: src/cluster/sharding/ClusterSharding.ts:24

Strategy the coordinator uses to allocate and rebalance shards.

---

coordinatorStateStore?

readonly optional coordinatorStateStore?: CoordinatorStateStore

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

Optional persistence backend for the coordinator’s allocation state (regions + shardHome). When set, a new leader elected after the previous leader’s failure can seed its coordinator from the snapshot instead of running tryAllocate from scratch — saves a brief reallocation storm at thousands-of-shards scale.

Unlike rememberEntitiesStore, ClusterSharding does NOT auto-instantiate this — the user must explicitly pass a store (typically new DistributedDataCoordinatorStateStore(dd, ...)). Without it, the v1 rebuild-from-Register behaviour is preserved.

---

entityProps

readonly entityProps: Props<TMsg>

Defined in: src/cluster/sharding/ShardRegion.ts:38

Inherited from

ShardingSettings.entityProps

---

extractEntityId

readonly extractEntityId: (message) => string

Defined in: src/cluster/sharding/ShardRegion.ts:39

Parameters

message

TMsg

Returns

string

Inherited from

ShardingSettings.extractEntityId

---

extractEntityMessage?

readonly optional extractEntityMessage?: (message) => unknown

Defined in: src/cluster/sharding/ShardRegion.ts:40

Parameters

message

TMsg

Returns

unknown

Inherited from

ShardingSettings.extractEntityMessage

---

handOffTimeoutMs?

readonly optional handOffTimeoutMs?: number

Defined in: src/cluster/sharding/ClusterSharding.ts:28

Time to wait for HandOffComplete before force-reallocating.

---

lease?

readonly optional lease?: Lease

Defined in: src/cluster/sharding/ClusterSharding.ts:37

Optional split-brain protection for the coordinator. When set, the elected leader’s coordinator must hold the lease before it processes shard messages — under a network partition that produces two leader views, only the side that successfully acquires the lease ever issues AllocateShard / HandOff directives. See ShardCoordinatorSettings.lease.

---

maxEntities?

readonly optional maxEntities?: number

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

Cap the number of locally-hosted entities (#82). When the region is about to spawn a new entity and the existing count is already maxEntities, the entity with the oldest lastActivity is passivated — same code path users invoke manually via Passivate. Useful for unbounded entity sets (per-user sessions, IoT devices, …) where a memory cap per node matters more than keeping every cold entity resident.

Default: 0 (no cap). Eviction runs only when > 0.

Note: passivation is asynchronous, so during the brief window between “stop the LRU” and “Terminated arrives” the region may hold maxEntities + 1 entities; the cap is a steady-state upper bound rather than a strict instantaneous one.

Inherited from

ShardingSettings.maxEntities

---

numShards?

readonly optional numShards?: number

Defined in: src/cluster/sharding/ShardRegion.ts:41

Inherited from

ShardingSettings.numShards

---

passivationIdleMs?

readonly optional passivationIdleMs?: number

Defined in: src/cluster/sharding/ShardRegion.ts:49

Notify the region after an entity has been idle this many ms.

Inherited from

ShardingSettings.passivationIdleMs

---

proxy?

readonly optional proxy?: boolean

Defined in: src/cluster/sharding/ShardRegion.ts:45

Run as a proxy — route messages but never host entities locally.

Inherited from

ShardingSettings.proxy

---

rebalanceIntervalMs?

readonly optional rebalanceIntervalMs?: number

Defined in: src/cluster/sharding/ClusterSharding.ts:26

Gap between coordinator-driven rebalance passes.

---

rememberEntities?

readonly optional rememberEntities?: boolean

Defined in: src/cluster/sharding/ShardRegion.ts:47

Track entity lifecycle so entities can be re-created on the new owner.

Inherited from

ShardingSettings.rememberEntities

---

rememberEntitiesStore?

readonly optional rememberEntitiesStore?: RememberEntitiesStore | null

Defined in: src/cluster/sharding/ClusterSharding.ts:52

Optional persistence backend for the entity registry — relevant only when rememberEntities: true. When omitted (and rememberEntities: true), the default JournalRememberEntitiesStore is auto-instantiated using the Journal from the system’s PersistenceExtension, so a full cluster cold-start no longer loses the registry. Set to a custom impl to plug in a separate store.

Pass null to opt out of persistence entirely (registry stays in-memory only — the v1 behaviour).

---

role?

readonly optional role?: string

Defined in: src/cluster/sharding/ShardRegion.ts:43

Members must carry this role to be candidates for hosting shards.

Inherited from

ShardingSettings.role

---

typeName

readonly typeName: string

Defined in: src/cluster/sharding/ShardRegion.ts:37

Inherited from

ShardingSettings.typeName