ShardInfo

ShardInfo<TMessage> = object

Defined in: src/cluster/sharding/ShardInfo.ts:20

One shard of a sharded type, as reported by ClusterSharding.shards().

Carries both halves of what “list the shards” is usually asked for: the placement data (which node, which region, how many entities) and a live ref you can send to. The ref is materialised on the asking node — the wire payload behind it is plain data — so the shape is deliberately not JSON-serialisable. Surfaces that need a serialisable view (the /cluster/shards management endpoint, the DevTools frames) keep their own DTOs rather than dragging a ref through JSON.

It is a snapshot: entityCount was true when the hosting region answered, and node only holds until the next rebalance. Hold the ref, not the placement, if you intend to keep talking to the shard.

Type Parameters

TMessage

TMessage = unknown

Properties

entityCount

readonly entityCount: number

Defined in: src/cluster/sharding/ShardInfo.ts:27

Live entities in the shard when its region answered.

---

local

readonly local: boolean

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

True when the shard is hosted by the node that asked.

---

node

readonly node: NodeAddress

Defined in: src/cluster/sharding/ShardInfo.ts:23

Node currently hosting the shard.

---

ref

readonly ref: ActorRef<ShardMessage<TMessage>>

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

---

regionPath

readonly regionPath: string

Defined in: src/cluster/sharding/ShardInfo.ts:25

Path of the region on that node — the shard sits directly beneath it.

---

resident

readonly resident: boolean

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

Whether the shard actor was materialised when its region answered.

A shard that passivated while empty stays allocated, addressable and reachable through ref — it is re-created on the next message — but it is not running right now. entityCount: 0 cannot tell you that on its own, since a running-but-empty shard reports the same count, so this is what to read when tuning shardPassivationIdleMs or counting the actors a node actually holds.

---

shardId

readonly shardId: number

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