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 C++ using N-API which makes the process of id generation extremely fast. The usage of C++ for id generation also guaratees that the generated number will be of size 64 bits.
Version 1.6 Updates
- Add
GetIDFromTimestamp
function which can be used in database queries.
Version 1.5 Updates
- Add
GetMachineIDFromID
help extracting machine id from the generated ids, even if they were generated on different machines
npm install nodejs-snowflake --save
yarn add nodejs-snowflake
The ID generator produces ids faster if the return type is bigint, but this option is disabled by default. Do the following to enable this feature.
const { UniqueID } = require('nodejs-snowflake');
const uid = new UniqueID({
returnNumber: true
});
const ID = uid.getUniqueID(); // This id is in javascript bigint format
In earlier versions of nodejs-snowflake, mac address was used for generating the unique ids. This is no longer supported in versions 1.5.x due to multiple reasons. Instead of the mac address it now uses "machine id" (value can range from 0 - 4095) which are supposed to be passed by the user. If no machine id is passed by the user then a random number would be used. The benefit of this approach is now the library supports extraction of machine id from the generated ids (irrespective of the machine used to generate it) which can be very useful in error detection in a clustered environment.
const { UniqueID } = require('nodejs-snowflake');
const uid = new UniqueID({
...,
machineID: 2345 // Any number between 0 - 4095. If not provided then a random number will be used
});
const { UniqueID } = require('nodejs-snowflake');
const uid = new UniqueID(config);
uid.getUniqueID(); // A 64 bit id is returned
uid.asyncGetUniqueID().then(id => console.log(id)); // Promisified version of the above method
UniqueID constructor takes in the following configuration
{
returnNumber: boolean, // Defaults to false. If set to true, the returned ids will be of type bigint or else of type string
customEpoch: number, // Defaults to 1546300800000 (01-01-2019). This is UNIX timestamp in ms
machineID: number // A value ranging between 0 - 4095. If not provided then a random value will be used
}
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.
...
uid.getTimestampFromID(id); // Here id can be either as as string or as a bigint
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 = uid.getMachineIDFromID(id); // Here id can be either as as string or as a bigint
console.log(mid); // 2345 -> This is the 12 bit long machine id where this token was generated
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
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.machineID; // The machine id of the current machine, set either by user or randomly generated
# Run for 1sec while invoking function every ms (default)
npm run benchmark
# All the arguments
# --time -> Total time for which the id should be generated
# --type -> Return type of the id (could be number or string)
# --interval -> Time interval in which id generation function should invoked
# UNITS OF TIME
# 1s = 1 second, 1m = 1 millisecond, 1u = 1 microsecond
npm run benchmark -- --time=2s --type=number --interval=1u