@vkhang2stack/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.

Installation 🚀

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

pnpm add @vkhang2stack/snowflake-id

# OR

npm install @vkhang2stack/snowflake-id

# OR

yarn add @vkhang2stack/snowflake-id

Usage 💻

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

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

const snowflake = SnowflakeId({
  workerId: 1,
  epoch: 1597017600000,
});

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 ID of the worker generating the Snowflake IDs.

  Defaults to 0 if not specified.

• epoch (optional): A timestamp in milliseconds representing the start of the ID generation.

  Defaults to August 10, 2020 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 😱

There are two errors that can be thrown by the SnowflakeId instance:

• Invalid Epoch Error: The SnowflakeId instance throws an error if the epoch timestamp is invalid, i.e., if the epoch timestamp is greater than the current timestamp.

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

Examples 🔠

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

import { SnowflakeId } from '@vkhang2stack/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 '@vkhang2stack/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 '@vkhang2stack/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 📝

• 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.

Where to find me? 👀