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.
Configuration
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
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 maxResidentEntities: number | "unbounded"; 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 unprocessedMessageBatchSize: number;}, ConfigError, never>Converting
Defaults
Layers
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 maxResidentEntities: number | "unbounded"; 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 unprocessedMessageBatchSize: number;}>): Layer<ShardingConfig>layerDefaults
Layer that provides the default ShardingConfig values.
Signature
declare const layerDefaults: Layer.Layer<ShardingConfig>layerFromEnv
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 maxResidentEntities: number | "unbounded"; 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 unprocessedMessageBatchSize: number;}>): Layer<ShardingConfig, ConfigError>Services
ShardingConfig
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 maxResidentEntities: number | "unbounded"; 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 unprocessedMessageBatchSize: number;}, this> { constructor(_: never);}