@artworker/sdk NPM

@akashrajpurohit/snowflake-id is a Node.js library for generating unique and distributed IDs that are suitable for use as primary keys in distributed systems.

It generates 64-bit IDs (in string format) that are composed of a timestamp, a worker ID, and a sequence number. These IDs are based on Twitter's Snowflake ID generation algorithm.

Read in detail about what are Snowflake IDs

Installation 🚀

You can install @akashrajpurohit/snowflake-id using pnpm/npm/yarn:

pnpm add @akashrajpurohit/snowflake-id

# OR

npm install @akashrajpurohit/snowflake-id

# OR

yarn add @akashrajpurohit/snowflake-id

Usage 💻

Here's an example of how to use @akashrajpurohit/snowflake-id:

const { SnowflakeId } = require('@akashrajpurohit/snowflake-id');

const snowflake = SnowflakeId({
  workerId: 1,
  nodeIdBits: 10,
  sequenceBits: 12,
  epoch: 1683982358000,
});

console.log(snowflake.generate()); // 14755887168818983731200

This will generate a unique ID in string format.

Configuration options ⚙️

The SnowflakeId constructor takes an options object with the following properties:

workerId (optional): A number between 0 and (2^nodeIdBits)-1 that represents the ID of the worker generating the IDs.
Defaults to 0 if not specified.
nodeIdBits (optional): The number of bits used to represent the worker ID.
Defaults to 10 if not specified.
sequenceBits (optional): The number of bits used to represent the sequence number.
Defaults to 12 if not specified.
epoch (optional): A timestamp in milliseconds representing the start of the ID generation.
Defaults to January 1, 1970 at 00:00:00 UTC if not specified.

Methods 🧮

The SnowflakeId instance has the following methods:

generate(): Generates a unique ID in string format.

Error Handling 😱

The SnowflakeId instance throws an error if the clock moves backwards, i.e., if the current timestamp is less than the last timestamp.

This can happen if the system clock is adjusted manually or if the system clock drifts significantly.

If this happens, the library throws an Error with the message Clock is moving backwards!.

Examples 🔠

Here's an example of how to generate 10 IDs:

import { SnowflakeId } from '@akashrajpurohit/snowflake-id';

const snowflake = SnowflakeId();

for (let i = 0; i < 10; i++) {
  console.log(snowflake.generate());
}

And here's an example of how to generate IDs using different worker IDs:

import { SnowflakeId } from '@akashrajpurohit/snowflake-id';

const worker1 = SnowflakeId({ workerId: 1 });
const worker2 = SnowflakeId({ workerId: 2 });

console.log(worker1.generate()); // Generates an ID with worker ID 1
console.log(worker2.generate()); // Generates an ID with worker ID 2

While using it in distributed systems, it is highly recommended that you set a unique workerId to reduce collisions of IDS.

While the implementation detail depends on you, one simple way to set a possible unique workerId is to use process.pid.

import { SnowflakeId } from '@akashrajpurohit/snowflake-id';

const workerId = process.pid % 1024; // Using PID as workerId
const snowflake = SnowflakeId({ workerId });

const id = snowflake.generate(); // Generate a new Snowflake ID
console.log(id);

Notes 📝

It is recommended to use a higher nodeIdBits or sequenceBits value if you expect to generate IDs on multiple machines, as this reduces the chance of ID collisions.
The workerId parameter can be omitted, in which case the workerId would be set to 0. However, if you expect to generate IDs on multiple machines, it is recommended to set a specific workerId value to reduce the chance of ID collisions.
The epoch timestamp should be set as close to the current time as possible to maximize the lifespan of the generator. If the epoch is set too far in the past or future, the generator may not be able to generate IDs for the full lifespan of the generator.

Bugs or Requests 🐛

If you encounter any problems feel free to open an issue. If you feel the project is missing a feature, please raise a ticket on GitHub and I'll look into it. Pull requests are also welcome.