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.

19 exports Added in v4.0.0 Source

Constants

constEpochMillis

Added in v4.0.0 Source

Defines the custom snowflake epoch in Unix milliseconds.

Signature

declare const constEpochMillis: number;

Constructors

make

Added in v4.0.0 Source

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;
}): Snowflake;

makeGenerator

Added in v4.0.0 Source

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>;

Snowflake

Added in v4.0.0 Source

Constructs a branded cluster snowflake id from a bigint or bigint-compatible string.

Signature

declare const Snowflake: (input: string | number | bigint) => Snowflake;

Converting

toParts

Added in v4.0.0 Source

Decomposes a snowflake id into its timestamp, machine id, and sequence parts.

Signature

declare function toParts(snowflake: Snowflake): Parts;

Getters

dateTime

Added in v4.0.0 Source

Extracts the timestamp from a snowflake id as a DateTime.Utc.

Signature

declare function dateTime(snowflake: Snowflake): Utc;

machineId

Added in v4.0.0 Source

Extracts the machine id component from a snowflake id.

Signature

declare function machineId(snowflake: Snowflake): number & Brand<"~effect/cluster/MachineId">;

sequence

Added in v4.0.0 Source

Extracts the per-machine sequence component from a snowflake id.

Signature

declare function sequence(snowflake: Snowflake): number;

timestamp

Added in v4.0.0 Source

Extracts the Unix timestamp in milliseconds from a snowflake id.

Signature

declare function timestamp(snowflake: Snowflake): number;

Layers

layerGenerator

Added in v4.0.0 Source

Layer that provides the default snowflake Generator service.

Signature

declare const layerGenerator: Layer.Layer<Generator>;

Models

Snowflake type

Added in v4.0.0 Source

Branded bigint identifier composed from a timestamp, machine id, and per-machine sequence number.

Signature

type Snowflake = Brand.Branded<bigint, TypeId>;

Signature

declare const SnowflakeFromBigInt: SnowflakeFromBigInt;

SnowflakeFromBigInt interface

Added in v4.0.0 Source

Schema type for snowflake ids represented as branded bigints.

Signature

interface SnowflakeFromBigInt extends brand<Schema.BigInt, TypeId> {
  constructor(_: never);
}

SnowflakeFromString

Added in v4.0.0 Source

Schema that decodes snowflake ids from strings into branded bigints and encodes them back to strings.

Signature

declare const SnowflakeFromString: SnowflakeFromString;

SnowflakeFromString interface

Added in v4.0.0 Source

Schema type for snowflake ids decoded from strings into branded bigints.

Signature

interface SnowflakeFromString extends decodeTo<SnowflakeFromBigInt, Schema.String> {
  constructor(_: never);
}

Services

Generator

Added in v4.0.0 Source

Context service for a stateful snowflake id generator.

Signature

declare class Generator extends Shape<"effect/cluster/Snowflake/Generator", Generator, this> {
  constructor(_: never);
}

Type IDs

TypeId

Added in v4.0.0 Source

Runtime brand identifier for cluster snowflake ids.

Signature

declare const TypeId: "~effect/cluster/Snowflake";

TypeId type

Added in v4.0.0 Source

Type-level representation of the cluster snowflake brand identifier.

Signature

type TypeId = typeof TypeId;