Snowflaker

Snowflaker is a simple snowflake id generator, inspired by the Twitter Snowflake algorithm.

Features

• It generates unique 64-bit integers that can be used as identifiers for distributed systems.
• The generated IDs are based on the current timestamp, machine ID, and process ID, ensuring uniqueness across different machines and processes.
• The generated IDs are lexicographically sortable, meaning that they can be sorted by their numeric value and will also be in chronological order.

Installation

You can install Snowflaker using npm:

npm install snowflaker

https://www.npmjs.com/package/snowflaker

Usage

const { Snowflaker, SnowflakeId } = require("snowflaker");

const machineId = 0; // required, allowed values: 0-15
const processId = 2; // required, allowed values: 0-15
const epoch = new Date("2025-01-01T00:00:00.000Z"); // optional (types: number, Date); default: 0

// Returns an instance of Snowflaker that can be used to generate unique IDs.
// For an instance of Snowflaker, the generated IDs are guaranteed to be unique and sequential.
const snowflaker = new Snowflaker(machineId, processId, epoch);

// Generate a unique ID, using an internal generator which was created with the constructor.
// "id" is an instance of SnowflakeId.
const id = snowflaker.generate();
console.log(id); // Example output: 10286597797490701

The SnowflakeId or SnowflakeID class providers several functions to get the timestamp, machine ID, process ID, and sequence number from the generated ID. It also has a toString() method that returns the ID as a string in different bases (between 2 and 64).

This file contains the implementation and details of the SnowflakeId class: id.ts.

Examples

const snowflaker = new Snowflaker(10, 11, new Date("2025-01-01T00:00:00.000Z"));

const list = [];

console.time("generate");
for (let i = 0; i < 100000; i++) {
  const snowflakeId = snowflaker.generate();
  list.push(snowflakeId);
}
console.timeEnd("generate");
// Generating 100,000 ids usually takes 560-580ms for me, might differ by machines.

for (const snowflakeId of list.slice(0, 10)) {
  console.log(snowflakeId);
  console.log("snowflakeId:", snowflakeId.toNumber());
  console.log("processId:", snowflakeId.processId);
  console.log("workerId:", snowflakeId.workerId);
  console.log("sequence:", snowflakeId.sequence);
  console.log("timestamp:", snowflakeId.timestamp);
  console.log("==============================");
}