ShardId

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 Added in v4.0.0 Source

Constructors

make

Added in v4.0.0 Source

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

Added in v4.0.0 Source

Formats a shard identifier as group:id.

Signature

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

Decoding

fromString

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

Returns true when the value carries the ShardId runtime marker.

Signature

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

Models

ShardId interface

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Signature

declare const ShardId: declare<ShardId, ShardId>;