@neabyte/snowflake

Fast distributed snowflake ID generator for all JavaScript runtimes

What is Snowflake?

Snowflake is a distributed unique ID generation algorithm originally created by Twitter. It produces 64-bit IDs that are:

• Time-ordered - IDs sort roughly by creation time (lexicographically).
• Unique across nodes - Each node gets a machineId (0-1023), preventing collisions.

Features

• ~800,000 IDs/sec - Single-threaded generation performance.
• Universal runtime - Works in Deno, Node.js, Bun, and browsers.
• Decomposition - Parse any Snowflake ID back into timestamp, machineId, and sequence.

Installation

Deno (JSR):

deno add jsr:@neabyte/snowflake

npm:

npm install @neabyte/snowflake

CDN (jsDelivr/esm.sh):

<scripttype="module">importSnowflakefrom'https://cdn.jsdelivr.net/npm/@neabyte/snowflake/dist/index.mjs'</script>

Or via esm.sh:

<scripttype="module">importSnowflakefrom'https://esm.sh/@neabyte/snowflake'</script>

Usage

Basic generation

importSnowflakefrom'@neabyte/snowflake'// Choose an epoch - decade or centuryconstepoch=Snowflake.getDecadeEpoch()// Create a generator with a unique machineId (0-1023)constsf=newSnowflake({machineId: 1,epochOffset: epoch})// Generate an IDconstid=sf.generate()// '851050322686153018'

Decompose an ID

constcomponents=Snowflake.decompose(id,epoch)console.log(components)// {// id: '851050322686153018',// timestamp: 202906208678,// absoluteTime: 1749206408678,// machineId: 1,// sequence: 0// }console.log(newDate(components.absoluteTime).toISOString())// '2026-06-06T10:50:08.678Z'

Multi-node setup

Each server or process gets a unique machineId:

// Server AconstsfA=newSnowflake({machineId: 1,epochOffset: epoch})// Server BconstsfB=newSnowflake({machineId: 2,epochOffset: epoch})// Zero collision guaranteed as long as machineId is unique per node

Epoch helpers

// Start of current decade (e.g., 2020-01-01)Snowflake.getDecadeEpoch()// Start of current century (e.g., 2000-01-01)Snowflake.getCenturyEpoch()// Custom epoch - any past timestamp in millisecondsconstcustomEpoch=newDate('2024-01-01').getTime()

API

new Snowflake(options)

Parameter	Type	Description
options.machineId	number	Unique node identifier (0-1023)
options.epochOffset	number	Epoch start time in milliseconds

Validation:

• machineId must be between 0 and 1023
• epochOffset must be a finite, non-negative number not in the future

sf.generate(): string

Generates a new Snowflake ID as a decimal string.

• Sequence counter resets every millisecond
• Up to 4096 IDs per millisecond per node
• Built-in spin-wait when sequence exceeds 4096

Snowflake.decompose(id, epochOffset?): SnowflakeComponents

Parses a Snowflake ID into its components.

Parameter	Type	Description
id	string | bigint	The Snowflake ID to parse
epochOffset	number	Optional epoch to add to timestamp (default: 0)

Returns:SnowflakeComponents

typeSnowflakeComponents={id: stringtimestamp: number// Milliseconds since epochOffsetabsoluteTime: number// timestamp + epochOffsetmachineId: number// Node identifier (0-1023)sequence: number// Sequence within the millisecond (0-4095)}

Snowflake.getDecadeEpoch(date?): number

Returns the start of the current decade (e.g., 2020-01-01) in milliseconds.

Snowflake.getCenturyEpoch(date?): number

Returns the start of the current century (e.g., 2000-01-01) in milliseconds.

Performance

Benchmarked on Apple M3 Pro:

Operation	Time	Rate
Generate single ID	1.3 µs	~800,000/sec
Generate 1000 IDs	1.3 ms	~760,000/sec
Decompose string ID	290 ns	~3,450,000/sec
Decompose bigint ID	254 ns	~3,930,000/sec

ID Structure

64-bit layout:

| 42 bits timestamp | 10 bits machineId | 12 bits sequence |

• Timestamp: Milliseconds since epochOffset (42 bits = ~139 years range)
• Machine ID: Node identifier (10 bits = 0-1023)
• Sequence: Per-millisecond counter (12 bits = 0-4095)

Testing

# Format, lint, and typecheck
deno task check
# Run unit tests
deno task test# Run benchmarks
deno bench benchmark/

License

This project is licensed under the MIT license. See the LICENSE file for details.