Documentation / @andrew_l/snowflake / Snowflake

Class: Snowflake

A class for generating and deconstructing Twitter snowflakes.

A Twitter snowflake is a 64-bit unsigned integer with 4 fields that have a fixed epoch value.

If we have a snowflake 266241948824764416 we can represent it as binary:

64                                          22     17     12          0
000000111011000111100001101001000101000000  00001  00000  000000000000
         number of ms since epoch           worker  pid    increment

Constructors

Constructor

new Snowflake(opts): Snowflake

Parameters

opts

number | bigint | SnowflakeOptions | Date

Returns

Snowflake

Properties

decode

decode: (id) => DeconstructedSnowflake

Alias for deconstruct

Deconstructs a snowflake given a snowflake ID

Parameters

id

string | bigint | Uint8Array<ArrayBufferLike>

the snowflake to deconstruct

Returns

DeconstructedSnowflake

a deconstructed snowflake

Example

const epoch = new Date('2000-01-01T00:00:00.000Z');
const snowflake = new Snowflake(epoch).deconstruct('3971046231244935168');

Accessors

epoch

Get Signature

get epoch(): number

The epoch for this snowflake, as a number

Returns

number

---

increment

Get Signature

get increment(): number

Get incrementor for generating snowflakes

Returns

number

Set Signature

set increment(value): void

Sets the incrementor for generating snowflakes that will be used by default for the generate method

Parameters

value

number | bigint

The new value

Returns

void

---

processId

Get Signature

get processId(): number

Gets the configured process ID

Returns

number

Set Signature

set processId(value): void

Sets the process ID that will be used by default for the generate method

Parameters

value

number | bigint

The new value, will be masked with 0b11111

Returns

void

---

workerId

Get Signature

get workerId(): number

Gets the configured worker ID

Returns

number

Set Signature

set workerId(value): void

Sets the worker ID that will be used by default for the generate method

Parameters

value

number | bigint

The new value, will be masked with 0b11111

Returns

void

Methods

deconstruct()

deconstruct(id): DeconstructedSnowflake

Deconstructs a snowflake given a snowflake ID

Parameters

id

string | bigint | Uint8Array<ArrayBufferLike>

the snowflake to deconstruct

Returns

DeconstructedSnowflake

a deconstructed snowflake

Example

const epoch = new Date('2000-01-01T00:00:00.000Z');
const snowflake = new Snowflake(epoch).deconstruct('3971046231244935168');

---

generate()

generate(timestamp?): bigint

Generates a Snowflake ID as bigint.

Parameters

timestamp?

number | Date

Returns

bigint

---

generateBuffer()

generateBuffer(timestamp?): Uint8Array

Generates a snowflake given an epoch and optionally a timestamp

Parameters

timestamp?

number | Date

Returns

Uint8Array

A unique snowflake as Uint8Array

Example

const epoch = new Date('2000-01-01T00:00:00.000Z');
const snowflake = new Snowflake({ epoch }).generate();

---

generateBufferUnsafe()

generateBufferUnsafe(timestamp?): Uint8Array

Generates a Snowflake ID as a Uint8Array buffer.

⚠️ Returns a reference to the same internal Uint8Array instance. Its contents may be overwritten on the next ID generation call.

This method is intended for high-performance scenarios where you immediately transform the buffer (e.g., to base62) before calling again. Avoid storing or mutating the returned buffer directly.

Parameters

timestamp?

number | Date

Returns

Uint8Array

---

generateString()

generateString(timestamp?): string

Generates a Snowflake ID as a decimal string.

Same digits as generate().toString(), produced by the packer's decimal builder without going through BigInt.

Parameters

timestamp?

number | Date

Returns

string

---

setHighest()

setHighest(): void

Sets most highest values for generating snowflakes that will be used by default for the generate method

Returns

void

---

setLowest()

setLowest(): void

Sets most lowest values for generating snowflakes that will be used by default for the generate method

Returns

void

---

timestampFrom()

timestampFrom(id): number

Retrieves the timestamp field's value from a snowflake.

Parameters

id

string | bigint | Uint8Array<ArrayBufferLike>

The snowflake to get the timestamp value from.

Returns

number

The UNIX timestamp that is stored in id.

---

withHighest()

withHighest<Result>(fn): Result

Execute a function in context of most highest values for generating snowflakes

Type Parameters

Result

Result = undefined

Parameters

fn

(instance) => Result

Returns

Result

Example

const epoch = new Date('2000-01-01T00:00:00.000Z');
const snowflake = new Snowflake();
const id = snowflake.withLowest((v) => v.generate(epoch)); // the highest possible id for that epoch

---

withLowest()

withLowest<Result>(fn): Result

Execute a function in context of most lowest values for generating snowflakes

Type Parameters

Result

Result = undefined

Parameters

fn

(instance) => Result

Returns

Result

Example

const epoch = new Date('2000-01-01T00:00:00.000Z');
const snowflake = new Snowflake();
const id = snowflake.withLowest((v) => v.generate(epoch)); // the lowest possible id for that epoch

---

bufferFrom()

static bufferFrom(value): Uint8Array

Parse value as Uint8Array buffer

Parameters

value

string | bigint

Returns

Uint8Array

---

compare()

static compare(a, b): -1 | 0 | 1

Returns a number indicating whether a reference snowflake comes before, or after, or is same as the given snowflake in sort order.

Parameters

a

string | bigint | Uint8Array<ArrayBufferLike>

The first snowflake to compare.

b

string | bigint | Uint8Array<ArrayBufferLike>

The second snowflake to compare.

Returns

-1 | 0 | 1

-1 if a is older than b, 0 if a and b are equals, 1 if a is newer than b.