StartShardingOptionsType

Defined in: src/cluster/sharding/StartShardingOptions.ts:15

Plain options-object shape accepted by ClusterSharding.start — the region-side ShardingOptionsType plus the coordinator-side fields (allocation, rebalance, lease, persistence backends).

Extends

• ShardingOptionsType<TMessage>

Type Parameters

TMessage

TMessage

Properties

acquireRetryIntervalMs?

readonly optional acquireRetryIntervalMs?: number

Defined in: src/cluster/sharding/StartShardingOptions.ts:32

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

---

allocationStrategy?

readonly optional allocationStrategy?: AllocationStrategy

Defined in: src/cluster/sharding/StartShardingOptions.ts:17

Strategy the coordinator uses to allocate and rebalance shards.

---

coordinatorStateStore?

readonly optional coordinatorStateStore?: CoordinatorStateStore

Defined in: src/cluster/sharding/StartShardingOptions.ts:59

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.

---

entityActor

readonly entityActor: ActorClassOrFactory<TMessage>

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

The entity actor — its class, or a factory when it needs dependencies. Distinct from ActorOptionsType.entity, which is the identity ClusterSharding stamps onto each entity it spawns.

Inherited from

ShardingOptionsType.entityActor

---

entityOptions?

readonly optional entityOptions?: ActorOptions<TMessage>

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

Spawn options applied to every entity of this type.

Inherited from

ShardingOptionsType.entityOptions

---

extractEntityId

readonly extractEntityId: (message) => string

Defined in: src/cluster/sharding/ShardingOptions.ts:42

Parameters

message

TMessage

Returns

string

Inherited from

ShardingOptionsType.extractEntityId

---

extractEntityMessage?

readonly optional extractEntityMessage?: (message) => unknown

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

Parameters

message

TMessage

Returns

unknown

Inherited from

ShardingOptionsType.extractEntityMessage

---

handOffTimeoutMs?

readonly optional handOffTimeoutMs?: number

Defined in: src/cluster/sharding/StartShardingOptions.ts:21

Time to wait for HandOffComplete before force-reallocating.

---

lease?

readonly optional lease?: Lease

Defined in: src/cluster/sharding/StartShardingOptions.ts:30

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 ShardCoordinatorOptionsType.lease.

---

maxEntities?

readonly optional maxEntities?: number

Defined in: src/cluster/sharding/ShardingOptions.ts:103

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

ShardingOptionsType.maxEntities

---

numShards?

readonly optional numShards?: number

Defined in: src/cluster/sharding/ShardingOptions.ts:44

Inherited from

ShardingOptionsType.numShards

---

passivationIdleMs?

readonly optional passivationIdleMs?: number

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

Passivate an entity after it has been idle this many ms.

Default: 5 minutes (passivation-idle in reference.conf). 0 disables the sweep and keeps every entity resident until something else stops it.

Two consequences worth knowing before turning it down or off. An entity that holds state in memory and does not rebuild it in preStart loses that state when it passivates — persistent entities recover, plain ones do not. And under rememberEntities a passivation is a forget: the region relays EntityStopped to the coordinator, which drops the entity from the registry, so it is no longer among those revived after a node failure.

Inherited from

ShardingOptionsType.passivationIdleMs

---

proxy?

readonly optional proxy?: boolean

Defined in: src/cluster/sharding/ShardingOptions.ts:48

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

Inherited from

ShardingOptionsType.proxy

---

rebalanceIntervalMs?

readonly optional rebalanceIntervalMs?: number

Defined in: src/cluster/sharding/StartShardingOptions.ts:19

Gap between coordinator-driven rebalance passes.

---

rememberEntities?

readonly optional rememberEntities?: boolean

Defined in: src/cluster/sharding/ShardingOptions.ts:50

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

Inherited from

ShardingOptionsType.rememberEntities

---

rememberEntitiesStore?

readonly optional rememberEntitiesStore?: RememberEntitiesStore | null

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

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/ShardingOptions.ts:46

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

Inherited from

ShardingOptionsType.role

---

shardPassivationIdleMs?

readonly optional shardPassivationIdleMs?: number

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

Stop a shard once it has stood empty this many ms — the shard-level counterpart to passivationIdleMs (#892).

A shard actor appears when the coordinator allocates the shard to this node and, without this, is only ever stopped again by a handoff. So once its last entity passivates it stays resident holding an empty map; and since entity ids spread over the hash space, a long-running node ends up with one such shard per numShards.

Unset, it follows passivationIdleMs: a shard stands empty precisely because its entities went idle, so the same window applies one level up. Set it to decouple the two — a larger value trades memory for fewer re-creations, 0 keeps empty shards resident while entities still passivate.

Only an empty shard is ever stopped, and the region keeps ownership, so the next message re-creates it transparently.

Inherited from

ShardingOptionsType.shardPassivationIdleMs

---

typeName

readonly typeName: string

Defined in: src/cluster/sharding/ShardingOptions.ts:33

Inherited from

ShardingOptionsType.typeName