ShardingOptionsType

ShardingOptionsType<TMessage> = object

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

Plain options-object shape for a sharded region. Consumed by ShardRegion.settingsToConfig and extended by StartShardingOptionsType — the coordinator-side superset that ClusterSharding.start accepts.

Extended by

• StartShardingOptionsType

Type Parameters

TMessage

TMessage

Properties

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.

---

entityOptions?

readonly optional entityOptions?: ActorOptions<TMessage>

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

Spawn options applied to every entity of this type.

---

extractEntityId

readonly extractEntityId: (message) => string

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

Parameters

message

TMessage

Returns

string

---

extractEntityMessage?

readonly optional extractEntityMessage?: (message) => unknown

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

Parameters

message

TMessage

Returns

unknown

---

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.

---

numShards?

readonly optional numShards?: number

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

---

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.

---

proxy?

readonly optional proxy?: boolean

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

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

---

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.

---

role?

readonly optional role?: string

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

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

---

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.

---

typeName

readonly typeName: string

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