Snowflake.ts

Snowflake.ts overview

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.

Since v4.0.0

---

Exports Grouped by Category

• Generator
  • Generator (class)
  • layerGenerator
  • makeGenerator
• constants
  • constEpochMillis
• constructors
  • Snowflake
  • make
• models
  • Snowflake (type alias)
• parts
  • dateTime
  • machineId
  • sequence
  • timestamp
  • toParts
• schemas
  • SnowflakeFromBigInt
  • SnowflakeFromBigInt (interface)
  • SnowflakeFromString
  • SnowflakeFromString (interface)
• type IDs
  • TypeId
  • TypeId (type alias)
• utils
  • Snowflake (namespace)
    • Parts (interface)
    • Generator (interface)

---

Generator

Generator (class)

Context service for a stateful snowflake id generator.

Signature

declare class Generator

Source

Since v4.0.0

layerGenerator

Layer that provides the default snowflake Generator service.

Signature

declare const layerGenerator: Layer.Layer<Generator, never, never>

Source

Since v4.0.0

makeGenerator

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, never, never>

Source

Since v4.0.0

constants

constEpochMillis

Defines the custom snowflake epoch in Unix milliseconds.

Signature

declare const constEpochMillis: number

Source

Since v4.0.0

constructors

Snowflake

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

Signature

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

Source

Since v4.0.0

make

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 const make: (options: {
  readonly machineId: MachineId
  readonly sequence: number
  readonly timestamp: number
}) => Snowflake

Source

Since v4.0.0

models

Snowflake (type alias)

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

Signature

type Snowflake = Brand.Branded<bigint, TypeId>

Source

Since v4.0.0

parts

dateTime

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

Signature

declare const dateTime: (snowflake: Snowflake) => DateTime.Utc

Source

Since v4.0.0

machineId

Extracts the machine id component from a snowflake id.

Signature

declare const machineId: (snowflake: Snowflake) => MachineId

Source

Since v4.0.0

sequence

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

Signature

declare const sequence: (snowflake: Snowflake) => number

Source

Since v4.0.0

timestamp

Extracts the Unix timestamp in milliseconds from a snowflake id.

Signature

declare const timestamp: (snowflake: Snowflake) => number

Source

Since v4.0.0

toParts

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

Signature

declare const toParts: (snowflake: Snowflake) => Snowflake.Parts

Source

Since v4.0.0

schemas

SnowflakeFromBigInt

Schema for snowflake ids represented as branded bigints.

Signature

declare const SnowflakeFromBigInt: SnowflakeFromBigInt

Source

Since v4.0.0

SnowflakeFromBigInt (interface)

Schema type for snowflake ids represented as branded bigints.

Signature

export interface SnowflakeFromBigInt extends Schema.brand<Schema.BigInt, TypeId> {}

Source

Since v4.0.0

SnowflakeFromString

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

Signature

declare const SnowflakeFromString: SnowflakeFromString

Source

Since v4.0.0

SnowflakeFromString (interface)

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

Signature

export interface SnowflakeFromString extends Schema.decodeTo<SnowflakeFromBigInt, Schema.String> {}

Source

Since v4.0.0

type IDs

TypeId

Runtime brand identifier for cluster snowflake ids.

Signature

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

Source

Since v4.0.0

TypeId (type alias)

Type-level representation of the cluster snowflake brand identifier.

Signature

type TypeId = typeof TypeId

Source

Since v4.0.0

utils

Snowflake (namespace)

Namespace containing support types for snowflake parts and generators.

Source

Since v4.0.0

Parts (interface)

Decoded components of a snowflake id: Unix timestamp milliseconds, machine id, and sequence number.

Signature

export interface Parts {
  readonly timestamp: number
  readonly machineId: MachineId
  readonly sequence: number
}

Source

Since v4.0.0

Generator (interface)

Stateful generator for runner-local snowflake ids, exposing an unsafe synchronous nextUnsafe operation and an effectful machine id setter.

Signature

export interface Generator {
  readonly nextUnsafe: () => Snowflake
  readonly setMachineId: (machineId: MachineId) => Effect.Effect<void>
}

Source

Since v4.0.0