Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/tangledbytes/nodejs-snowflake
Generate time sortable 64 bits unique ids for distributed systems (inspired from twitter snowflake)
https://github.com/tangledbytes/nodejs-snowflake
distributed-systems hacktoberfest nodejs nodejs-snowflake rust snowflake twitter typescript wasm webassembly
Last synced: 7 days ago
JSON representation
Generate time sortable 64 bits unique ids for distributed systems (inspired from twitter snowflake)
- Host: GitHub
- URL: https://github.com/tangledbytes/nodejs-snowflake
- Owner: tangledbytes
- License: apache-2.0
- Created: 2019-11-17T04:16:15.000Z (about 5 years ago)
- Default Branch: master
- Last Pushed: 2024-02-26T16:39:27.000Z (11 months ago)
- Last Synced: 2025-01-09T13:31:57.501Z (15 days ago)
- Topics: distributed-systems, hacktoberfest, nodejs, nodejs-snowflake, rust, snowflake, twitter, typescript, wasm, webassembly
- Language: Rust
- Homepage: https://www.npmjs.com/package/nodejs-snowflake
- Size: 247 KB
- Stars: 181
- Watchers: 5
- Forks: 15
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# nodejs-snowflake
[](https://github.com/tangledbytes/nodejs-snowflake/graphs/commit-activity)
[](https://github.com/tangledbytes/nodejs-snowflake/issues/)
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](https://github.com/tangledbytes/nodejs-snowflake/pull/14) for details.
## How to install
```
npm install nodejs-snowflake --save
yarn add nodejs-snowflake
```
## Usage
### Generate ID
```javascript
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
```javascript
{
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.
```javascript
...
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.
```javascript
...
// 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.
```javascript
...
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.
```javascript
...
uid.instanceID(); // The instance id of the current instance, set either by user or randomly generated
```