❄️ Hyperflake

A simple and lightweight Node.js library to generate unique snowflake like IDs starting from beginning of the 21th century.

Bug report

Feature request

hyperflake 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 hyperflake using pnpm/npm/yarn:

pnpm  add  hyperflake

# OR

npm  install  hyperflake

# OR

yarn  add  hyperflake

Methods 🧮

The SnowflakeId instance has the following methods:

• generate(): Generates a unique ID in string format.
• decode(): Retrive timestamp when the ID was generated.

Usage 💻

Here's an example of how to use hyperflake:

const { SnowflakeId } = require('hyperflake');

const snowflake = SnowflakeId();

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

This will generate a unique ID in string format.

Validating IDs ✅

You can validate IDs generated by hyperflake using the decode() method:

const { SnowflakeId } = require('hyperflake');

const snowflake = SnowflakeId();

const id = snowflake.generate();

console.log(snowflake.decode(id)); // Number<timestamp>

This will return the timestamp when the ID was generated.

Also you can head to https://hyperflake-validator-ui.vercel.app to validate your IDs using a simple Web UI.

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 'hyperflake';

const snowflake = SnowflakeId();

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

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.