Skip to content

ShardingConfig

Configures how an Effect Cluster runner participates in sharding.

ShardingConfig describes the runner address, shard group membership, shard counts and weights, lock timing, entity mailbox and lifecycle limits, polling intervals, health checks, and local serialization simulation. This module includes the service, default values, programmatic and environment-based layers, a Config description for loading values, and helpers for normalizing assigned shard groups.

8 exports Added in v4.0.0 Source

Configuration

config

Added in v4.0.0 Source

Describes how to load ShardingConfig values, applying the same defaults used by the in-memory defaults object.

Signature

declare const config: Config.Config<ShardingConfig["Service"]>;

configFromEnv

Added in v4.0.0 Source

Effect that loads ShardingConfig from environment variables using the constant-case config provider.

Signature

declare const configFromEnv: Effect<{
  readonly assignedShardGroups: readonly Array<string>;
  readonly availableShardGroups: readonly Array<string>;
  readonly entityMailboxCapacity: number | "unbounded";
  readonly entityMaxIdleTime: Input;
  readonly entityMessagePollInterval: Input;
  readonly entityRegistrationTimeout: Input;
  readonly entityReplyPollInterval: Input;
  readonly entityTerminationTimeout: Input;
  readonly preemptiveShutdown: boolean;
  readonly refreshAssignmentsInterval: Input;
  readonly runnerAddress: Option<RunnerAddress>;
  readonly runnerHealthCheckInterval: Input;
  readonly runnerListenAddress: Option<RunnerAddress>;
  readonly runnerShardWeight: number;
  readonly sendRetryInterval: Input;
  readonly shardLockDisableAdvisory: boolean;
  readonly shardLockExpiration: Input;
  readonly shardLockRefreshInterval: Input;
  readonly shardsPerGroup: number;
  readonly simulateRemoteSerialization: boolean;
}, ConfigError, never>

Converting

shardGroupConfig

Added in v4.0.0 Source

Normalizes the provided ShardingConfig to calculate the available and assigned shard groups.

Signature

declare function shardGroupConfig(config: {
  readonly assignedShardGroups: readonly Array<string>;
  readonly availableShardGroups: readonly Array<string>;
  readonly entityMailboxCapacity: number | "unbounded";
  readonly entityMaxIdleTime: Input;
  readonly entityMessagePollInterval: Input;
  readonly entityRegistrationTimeout: Input;
  readonly entityReplyPollInterval: Input;
  readonly entityTerminationTimeout: Input;
  readonly preemptiveShutdown: boolean;
  readonly refreshAssignmentsInterval: Input;
  readonly runnerAddress: Option<RunnerAddress>;
  readonly runnerHealthCheckInterval: Input;
  readonly runnerListenAddress: Option<RunnerAddress>;
  readonly runnerShardWeight: number;
  readonly sendRetryInterval: Input;
  readonly shardLockDisableAdvisory: boolean;
  readonly shardLockExpiration: Input;
  readonly shardLockRefreshInterval: Input;
  readonly shardsPerGroup: number;
  readonly simulateRemoteSerialization: boolean;
}): {
  readonly assigned: ReadonlySet<string>;
  readonly available: ReadonlySet<string>;
}

Defaults

defaults

Added in v4.0.0 Source

Default values for ShardingConfig, including the default local runner address, shard group, shard count, mailbox settings, polling intervals, and remote serialization simulation.

Signature

declare const defaults: ShardingConfig["Service"];

Layers

layer

Added in v4.0.0 Source

Creates a ShardingConfig layer by merging the provided partial options over defaults.

When to use

Use when you need to wire a cluster runner with explicit ShardingConfig values, especially in tests, local development, or code paths where configuration should be provided programmatically instead of loaded from environment variables.

Details

The merge is shallow: omitted fields use defaults, and provided fields replace the corresponding default value.

Gotchas

This layer only merges and provides configuration; it does not check that cluster-wide settings are consistent across runners. Keep values such as shardsPerGroup and availableShardGroups aligned for runners that should share shard assignments.

See

  • defaults for the values used when an option is omitted
  • layerDefaults for a layer with no overrides
  • layerFromEnv for loading configuration from environment variables before applying explicit overrides

Signature

declare function layer(options?: Partial<{
  readonly assignedShardGroups: readonly Array<string>;
  readonly availableShardGroups: readonly Array<string>;
  readonly entityMailboxCapacity: number | "unbounded";
  readonly entityMaxIdleTime: Input;
  readonly entityMessagePollInterval: Input;
  readonly entityRegistrationTimeout: Input;
  readonly entityReplyPollInterval: Input;
  readonly entityTerminationTimeout: Input;
  readonly preemptiveShutdown: boolean;
  readonly refreshAssignmentsInterval: Input;
  readonly runnerAddress: Option<RunnerAddress>;
  readonly runnerHealthCheckInterval: Input;
  readonly runnerListenAddress: Option<RunnerAddress>;
  readonly runnerShardWeight: number;
  readonly sendRetryInterval: Input;
  readonly shardLockDisableAdvisory: boolean;
  readonly shardLockExpiration: Input;
  readonly shardLockRefreshInterval: Input;
  readonly shardsPerGroup: number;
  readonly simulateRemoteSerialization: boolean;
}>): Layer<ShardingConfig>

layerDefaults

Added in v4.0.0 Source

Layer that provides the default ShardingConfig values.

Signature

declare const layerDefaults: Layer.Layer<ShardingConfig>;

layerFromEnv

Added in v4.0.0 Source

Layer that loads ShardingConfig from environment variables and, when options are provided, overlays those options on top of the loaded values.

Signature

declare function layerFromEnv(options?: Partial<{
  readonly assignedShardGroups: readonly Array<string>;
  readonly availableShardGroups: readonly Array<string>;
  readonly entityMailboxCapacity: number | "unbounded";
  readonly entityMaxIdleTime: Input;
  readonly entityMessagePollInterval: Input;
  readonly entityRegistrationTimeout: Input;
  readonly entityReplyPollInterval: Input;
  readonly entityTerminationTimeout: Input;
  readonly preemptiveShutdown: boolean;
  readonly refreshAssignmentsInterval: Input;
  readonly runnerAddress: Option<RunnerAddress>;
  readonly runnerHealthCheckInterval: Input;
  readonly runnerListenAddress: Option<RunnerAddress>;
  readonly runnerShardWeight: number;
  readonly sendRetryInterval: Input;
  readonly shardLockDisableAdvisory: boolean;
  readonly shardLockExpiration: Input;
  readonly shardLockRefreshInterval: Input;
  readonly shardsPerGroup: number;
  readonly simulateRemoteSerialization: boolean;
}>): Layer<ShardingConfig, ConfigError>

Services

ShardingConfig

Added in v4.0.0 Source

Represents the configuration for the Sharding service on a given runner.

Signature

declare class ShardingConfig extends Shape<"effect/cluster/ShardingConfig", {
  readonly assignedShardGroups: readonly Array<string>;
  readonly availableShardGroups: readonly Array<string>;
  readonly entityMailboxCapacity: number | "unbounded";
  readonly entityMaxIdleTime: Input;
  readonly entityMessagePollInterval: Input;
  readonly entityRegistrationTimeout: Input;
  readonly entityReplyPollInterval: Input;
  readonly entityTerminationTimeout: Input;
  readonly preemptiveShutdown: boolean;
  readonly refreshAssignmentsInterval: Input;
  readonly runnerAddress: Option<RunnerAddress>;
  readonly runnerHealthCheckInterval: Input;
  readonly runnerListenAddress: Option<RunnerAddress>;
  readonly runnerShardWeight: number;
  readonly sendRetryInterval: Input;
  readonly shardLockDisableAdvisory: boolean;
  readonly shardLockExpiration: Input;
  readonly shardLockRefreshInterval: Input;
  readonly shardsPerGroup: number;
  readonly simulateRemoteSerialization: boolean;
}, this> {
  constructor(_: never);
}