ShardId unstable

The ShardId module models the address of a shard inside an Effect Cluster shard group. A shard id is made from a string group and numeric id, and the module gives that pair stable equality, hashing, primary-key behavior, schema support, and conversion to and from the group:id string form used by routing and storage boundaries.

7 exports Since v4.0.0 Source

Constructors

make

unstable

Since v4.0.0

Creates or reuses the cached ShardId for the specified shard group and numeric id.

When to use

Use to create a ShardId when the shard group and numeric id are already known, such as after a routing decision or after decoding stored shard-id parts.

Details

Repeated calls with the same group and id return the same cached ShardId instance. The returned value stores those fields, compares by group and id, formats as group:id, and uses that string form for hashing and primary keys.

Gotchas

make does not compute a shard from an entity id or check whether the shard belongs to the current sharding configuration. Pass the shard group and numeric id produced by the routing or storage layer.

See

toString for formatting an existing shard id as group:id
fromString for constructing a cached shard id from the group:id string form

Signature

declare function make(group: string, id: number): ShardId

Converting

toString

unstable

Since v4.0.0

Formats a shard identifier as group:id.

Signature

declare function toString(shardId: {
  readonly group: string;
  readonly id: number;
}): string

Decoding

fromString

unstable

Since v4.0.0

Parses a group:id string into a cached ShardId.

Details

Throws an Error when the string has no colon separator or the id segment is not numeric.

Signature

declare function fromString(s: string): ShardId

fromStringEncoded

unstable

Since v4.0.0

Parses a group:id string into plain shard id parts.

Details

Throws an Error when the string has no colon separator or the id segment is not numeric.

Signature

declare function fromStringEncoded(s: string): {
  readonly group: string;
  readonly id: number;
}

Guards

isShardId

unstable

Since v4.0.0

Returns true when the value carries the ShardId runtime marker.

Signature

declare function isShardId(u: unknown): u is ShardId

Models

ShardId

interface unstable

Since v4.0.0

Identifier for a shard within a shard group, with equality, hashing, and primary key behavior based on the group:id string form.

Signature

interface ShardId extends Equal, Hash, PrimaryKey {
  readonly "~effect/cluster/ShardId": "~effect/cluster/ShardId";
  readonly group: string;
  readonly id: number;
}

Schemas

ShardId

unstable

Since v4.0.0

Schema for shard identifiers encoded as { group, id } objects and decoded via make.

Signature

declare const ShardId: declare<ShardId, ShardId>