Snowflake
Creates compact, sortable identifiers for cluster messages and runtime events.
A snowflake id is a branded bigint built from a millisecond timestamp, a
machine id, and a sequence number for that machine. The parts make generated
ids sortable by time while still being unique for a runner. This module
includes schemas for bigint and string encodings, helpers for creating and
reading ids, and a Clock-backed generator service for cluster runtime use.
Constants
constEpochMillis
Defines the custom snowflake epoch in Unix milliseconds.
Signature
declare const constEpochMillis: numberConstructors
Creates a branded snowflake id from a timestamp, machine id, and sequence number, using the custom snowflake epoch and 10-bit machine id and 12-bit sequence fields.
When to use
Use to pack known timestamp, machine id, and sequence parts into a branded snowflake id.
Gotchas
Machine id values are encoded modulo 1024, and sequence values modulo 4096; values outside those ranges wrap instead of being rejected.
See
- toParts for the inverse operation that decodes a snowflake id into timestamp, machine id, and sequence parts
- makeGenerator for generating ids with Clock-backed timestamp and sequence management
Signature
declare function make(options: { readonly machineId: number & Brand<"~effect/cluster/MachineId">; readonly sequence: number; readonly timestamp: number;}): SnowflakemakeGenerator
Creates a stateful snowflake generator using Clock.
Details
The generator starts with a random machine id, never moves generated timestamps backward, resets the sequence each millisecond, and advances the timestamp when more than 4096 ids are requested in the same millisecond.
Signature
declare const makeGenerator: Effect.Effect<Snowflake.Generator>Constructs a branded cluster snowflake id from a bigint or bigint-compatible string.
Signature
declare const Snowflake: (input: string | number | bigint) => SnowflakeConverting
Getters
Extracts the timestamp from a snowflake id as a DateTime.Utc.
Signature
declare function dateTime(snowflake: Snowflake): UtcExtracts the machine id component from a snowflake id.
Signature
declare function machineId(snowflake: Snowflake): number & Brand<"~effect/cluster/MachineId">Extracts the per-machine sequence component from a snowflake id.
Signature
declare function sequence(snowflake: Snowflake): numberExtracts the Unix timestamp in milliseconds from a snowflake id.
Signature
declare function timestamp(snowflake: Snowflake): numberLayers
layerGenerator
Layer that provides the default snowflake Generator service.
Signature
declare const layerGenerator: Layer.Layer<Generator>Models
Other
Schemas
SnowflakeFromBigInt
Schema for snowflake ids represented as branded bigints.
Signature
declare const SnowflakeFromBigInt: SnowflakeFromBigIntSnowflakeFromBigInt interface
Schema type for snowflake ids represented as branded bigints.
Signature
interface SnowflakeFromBigInt extends brand<Schema.BigInt, TypeId> { constructor(_: never);}SnowflakeFromString
Schema that decodes snowflake ids from strings into branded bigints and encodes them back to strings.
Signature
declare const SnowflakeFromString: SnowflakeFromStringSnowflakeFromString interface
Schema type for snowflake ids decoded from strings into branded bigints.
Signature
interface SnowflakeFromString extends decodeTo<SnowflakeFromBigInt, Schema.String> { constructor(_: never);}