README.md

nodejs-snowflake

nodejs-snowflake is a fast and reliable way to generate time sortable 64 bit ids written for distributed systems.
The main ID generation function is written in Rust which interoperates with NodeJS via WASM, this makes the process of ID generation extremely fast.

⚠️ Version 2 Alert! Version 2 of nodejs-snowflake has a lot of breaking changes and is a complete rewrite. Consider going through entire doc to understand the migration path. Checkout Version 2 PR Notes for details.

How to install

npm install nodejs-snowflake --save
yarn add nodejs-snowflake

Usage

Generate ID

const { Snowflake } = require('nodejs-snowflake');

const uid = new Snowflake(config);

uid.getUniqueID(); // A 64 bit id is returned

Configuration

UniqueID constructor takes in the following configuration

{
    custom_epoch: number, // Defaults to Date.now(). This is UNIX timestamp in ms
    instance_id: number // A value ranging between 0 - 4095. If not provided then a random value will be used
}

Get ID corresponding to a Timestamp

This can be extremely helpful in writing database queries where the requirement could be to get entries created after a certain timestamp.

...

const id = uid.idFromTimestamp(Date.now()); // Here id will always be BigInt

console.log(id); // A 64 bit id is returned corresponding to the timestamp given

Get timestamp from the ID

Get the timestamp of creation of the ID can be extracted by using this method. This method will work even if this instance or machine wasn't actually used to generate this id.

...

// Pass the custom epoch that was used to generate this ID
const ts = Snowflake.timestampFromID(id, uid.customEpoch());

console.log(ts) // Timestamp of creation of the id

Get machine id from the ID

Get the machine id of the machine on which the token was generated. This method will work even if this instance or machine wasn't actually used to generate this id.

...

const mid = Snowflake.instanceIDFromID(id);

console.log(mid); // 2345 -> This is the 12 bit long machine id where this token was generated

Get the current machine id

This solely exits to find the machine id of current machine in case the user didn't provided as machine id and relied on the randomly generated value.

...

uid.instanceID(); // The instance id of the current instance, set either by user or randomly generated