ClusterSharding

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

User-facing entry point. Attaches to an ActorSystem + Cluster pair and lets you start a sharded region for each entity type. A ShardCoordinator is spawned lazily on every node; only the one hosted by the current cluster leader is active — the rest act as warm standbys.

Properties

cluster

readonly cluster: Cluster

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

---

system

readonly system: ActorSystem

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

Methods

entityRefFor()

Call Signature

entityRefFor<TMessage>(key, entityId): ActorRef<TMessage>

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

A handle to one entity, addressed by id. Location-transparent: the entity may live on this node or any other, and it may move between them — the handle keeps working, because it routes through the local region exactly like a normal message does.

const entity = cluster.sharding.entityRefFor<Command>('counter', 'user-42');
entity.tell({ kind: 'increment', by: 1 });     // no id inside the message
const value = await entity.ask<number>({ kind: 'get' });

Synchronous by design — the shard id is hash(entityId) % numShards, so nothing has to be looked up, and a message for a shard whose home is not known yet is buffered by the region just as it always was.

Unlike the region ref, messages sent through the handle do not go through extractEntityId: the envelope names its entity, so the message type no longer has to carry a routing key of its own.

Type Parameters

TMessage

TMessage

Parameters

key

ShardKey<TMessage> | ShardKeyedClass<TMessage>

entityId

string

Returns

ActorRef<TMessage>

Throws

if no region for typeName has been started on this node — a proxy region (startProxy) is enough.

Call Signature

entityRefFor<TMessage>(typeName, entityId): ActorRef<TMessage>

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

A handle to one entity, addressed by id. Location-transparent: the entity may live on this node or any other, and it may move between them — the handle keeps working, because it routes through the local region exactly like a normal message does.

const entity = cluster.sharding.entityRefFor<Command>('counter', 'user-42');
entity.tell({ kind: 'increment', by: 1 });     // no id inside the message
const value = await entity.ask<number>({ kind: 'get' });

Synchronous by design — the shard id is hash(entityId) % numShards, so nothing has to be looked up, and a message for a shard whose home is not known yet is buffered by the region just as it always was.

Unlike the region ref, messages sent through the handle do not go through extractEntityId: the envelope names its entity, so the message type no longer has to carry a routing key of its own.

Type Parameters

TMessage

TMessage

Parameters

typeName

string

entityId

string

Returns

ActorRef<TMessage>

Throws

if no region for typeName has been started on this node — a proxy region (startProxy) is enough.

---

shardRefFor()

shardRefFor<TMessage>(typeName, shardId, timeoutMs?): Promise<ActorRef<ShardMessage<TMessage>>>

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

A ref to one shard. Allocates the shard if it has no home yet — the same thing a first message for it would have done.

The ref is the real thing: the local shard actor when this node hosts it, a RemoteActorRef at /system/cluster/sharding/region-<type>/shard-<n> otherwise. tell therefore works from anywhere. ask only works when the shard is local, because a one-shot ask ref is not addressable from another node — to query a remote shard, send GetShardStats with your own actor’s self as replyTo, or use shards for the cluster-wide picture.

Type Parameters

TMessage

TMessage = unknown

Parameters

typeName

string

shardId

number

timeoutMs?

number = 5_000

Returns

Promise<ActorRef<ShardMessage<TMessage>>>

Throws

if no region for typeName has been started on this node, or if the shard cannot be placed within timeoutMs (AskTimeoutError).

---

shards()

shards<TMessage>(typeName, timeoutMs?): Promise<readonly ShardInfo<TMessage>[]>

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

Every shard of typeName that currently has a home, cluster-wide — where it lives, how many entities it is holding, and a live ref to it (#151).

for (const shard of await cluster.sharding.shards<Command>('counter')) {
  console.log(shard.shardId, `${shard.node}`, shard.entityCount);
}

The coordinator owns the shard map but not the entity counts — only the region hosting a shard knows those — so this costs one fan-out to the registered regions. A region that does not answer in time contributes entityCount: 0 rather than failing the whole call; the result is a snapshot, not a subscription (for a live feed, subscribe to ShardMapChanged).

Shards with no home yet are absent: nothing has asked for them, so the coordinator has had no reason to allocate them. Use shardRefFor to place one on purpose.

Type Parameters

TMessage

TMessage = unknown

Parameters

typeName

string

timeoutMs?

number = 5_000

Returns

Promise<readonly ShardInfo<TMessage>[]>

Throws

if no region for typeName has been started on this node, or if the coordinator does not answer within timeoutMs (AskTimeoutError) — which is what a leader election in flight looks like from here.

---

start()

Call Signature

start<TMessage>(entityClass, options?): ActorRef<TMessage>

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

Start a sharded region for a type. Several calling shapes:

// The entity class declares its own key, including how a command names
// its entity — nothing left to repeat at the call site.
sharding.start(UserActor);

// Same, but the entity needs dependencies.
sharding.start(CartActor, () => new CartActor(deps));

// Shorthand: pass the entity class by name.
sharding.start('counter', CounterEntity, {
  extractEntityId: (message) => message.id,
});

// Shorthand: pass a factory.  Useful for closures / DI / no-arg new.
sharding.start('cart', () => new CartEntity(deps),
  StartShardingOptions.create<CartMessage>().withExtractEntityId((message) => message.entityId));

// Full-form: every option via the builder.
sharding.start(
  StartShardingOptions.create<CounterMessage>()
    .withTypeName('counter')
    .withEntityActor(CounterEntity)
    .withExtractEntityId((message) => message.id),
);

Type Parameters

TMessage

TMessage

Parameters

entityClass

ShardEntityClass<TMessage>

options?

StartShardingOptions<TMessage>

Returns

ActorRef<TMessage>

Call Signature

start<TMessage>(entityClass, factory, options?): ActorRef<TMessage>

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

Start a sharded region for a type. Several calling shapes:

// The entity class declares its own key, including how a command names
// its entity — nothing left to repeat at the call site.
sharding.start(UserActor);

// Same, but the entity needs dependencies.
sharding.start(CartActor, () => new CartActor(deps));

// Shorthand: pass the entity class by name.
sharding.start('counter', CounterEntity, {
  extractEntityId: (message) => message.id,
});

// Shorthand: pass a factory.  Useful for closures / DI / no-arg new.
sharding.start('cart', () => new CartEntity(deps),
  StartShardingOptions.create<CartMessage>().withExtractEntityId((message) => message.entityId));

// Full-form: every option via the builder.
sharding.start(
  StartShardingOptions.create<CounterMessage>()
    .withTypeName('counter')
    .withEntityActor(CounterEntity)
    .withExtractEntityId((message) => message.id),
);

Type Parameters

TMessage

TMessage

Parameters

entityClass

ShardKeyedClass<TMessage>

factory

() => Actor<TMessage>

options?

StartShardingOptions<TMessage>

Returns

ActorRef<TMessage>

Call Signature

start<TMessage>(key, entity, options?): ActorRef<TMessage>

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

Start a sharded region for a type. Several calling shapes:

// The entity class declares its own key, including how a command names
// its entity — nothing left to repeat at the call site.
sharding.start(UserActor);

// Same, but the entity needs dependencies.
sharding.start(CartActor, () => new CartActor(deps));

// Shorthand: pass the entity class by name.
sharding.start('counter', CounterEntity, {
  extractEntityId: (message) => message.id,
});

// Shorthand: pass a factory.  Useful for closures / DI / no-arg new.
sharding.start('cart', () => new CartEntity(deps),
  StartShardingOptions.create<CartMessage>().withExtractEntityId((message) => message.entityId));

// Full-form: every option via the builder.
sharding.start(
  StartShardingOptions.create<CounterMessage>()
    .withTypeName('counter')
    .withEntityActor(CounterEntity)
    .withExtractEntityId((message) => message.id),
);

Type Parameters

TMessage

TMessage

Parameters

key

ShardKey<TMessage>

entity

ActorClassOrFactory<TMessage>

options?

StartShardingOptions<TMessage>

Returns

ActorRef<TMessage>

Call Signature

start<TMessage>(options): ActorRef<TMessage>

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

Start a sharded region for a type. Several calling shapes:

// The entity class declares its own key, including how a command names
// its entity — nothing left to repeat at the call site.
sharding.start(UserActor);

// Same, but the entity needs dependencies.
sharding.start(CartActor, () => new CartActor(deps));

// Shorthand: pass the entity class by name.
sharding.start('counter', CounterEntity, {
  extractEntityId: (message) => message.id,
});

// Shorthand: pass a factory.  Useful for closures / DI / no-arg new.
sharding.start('cart', () => new CartEntity(deps),
  StartShardingOptions.create<CartMessage>().withExtractEntityId((message) => message.entityId));

// Full-form: every option via the builder.
sharding.start(
  StartShardingOptions.create<CounterMessage>()
    .withTypeName('counter')
    .withEntityActor(CounterEntity)
    .withExtractEntityId((message) => message.id),
);

Type Parameters

TMessage

TMessage

Parameters

options

StartShardingOptions<TMessage>

Returns

ActorRef<TMessage>

Call Signature

start<TMessage>(typeName, entity, options?): ActorRef<TMessage>

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

Start a sharded region for a type. Several calling shapes:

// The entity class declares its own key, including how a command names
// its entity — nothing left to repeat at the call site.
sharding.start(UserActor);

// Same, but the entity needs dependencies.
sharding.start(CartActor, () => new CartActor(deps));

// Shorthand: pass the entity class by name.
sharding.start('counter', CounterEntity, {
  extractEntityId: (message) => message.id,
});

// Shorthand: pass a factory.  Useful for closures / DI / no-arg new.
sharding.start('cart', () => new CartEntity(deps),
  StartShardingOptions.create<CartMessage>().withExtractEntityId((message) => message.entityId));

// Full-form: every option via the builder.
sharding.start(
  StartShardingOptions.create<CounterMessage>()
    .withTypeName('counter')
    .withEntityActor(CounterEntity)
    .withExtractEntityId((message) => message.id),
);

Type Parameters

TMessage

TMessage

Parameters

typeName

string

entity

ActorClassOrFactory<TMessage>

options?

StartShardingOptions<TMessage>

Returns

ActorRef<TMessage>

---

startProxy()

Call Signature

startProxy<TMessage>(key): ActorRef<TMessage>

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

Start a proxy region — routes to the cluster but never hosts entities. Takes a key (or the class declaring one) or the same builder as start; proxy is forced on internally, so any withProxy(...) on the passed builder is overridden.

A proxy hosts nothing, so it needs neither an entity actor nor an extractor — placeholders stand in for both, which is what lets the key form be a single argument.

Type Parameters

TMessage

TMessage

Parameters

key

ShardKey<TMessage> | ShardKeyedClass<TMessage>

Returns

ActorRef<TMessage>

Call Signature

startProxy<TMessage>(options): ActorRef<TMessage>

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

Start a proxy region — routes to the cluster but never hosts entities. Takes a key (or the class declaring one) or the same builder as start; proxy is forced on internally, so any withProxy(...) on the passed builder is overridden.

A proxy hosts nothing, so it needs neither an entity actor nor an extractor — placeholders stand in for both, which is what lets the key form be a single argument.

Type Parameters

TMessage

TMessage

Parameters

options

StartShardingOptions<TMessage>

Returns

ActorRef<TMessage>

---

get()

static get(system, cluster): ClusterSharding

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

Parameters

system

ActorSystem

cluster

Cluster

Returns

ClusterSharding