You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
nodejs-snowflake is a fast and reliable way to generate time sortable 64 bit ids written for distributed systems.
8
-
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.
11
+
The main ID generation function is written in Rust which interoperates with NodeJS via WASM, this makes the process of ID generation extremely fast.
9
12
10
-
**Version 1.6 Updates**
11
-
- Add `GetIDFromTimestamp` function which can be used in database queries.
12
-
13
-
**Version 1.5 Updates**
14
-
- Add `GetMachineIDFromID` help extracting machine id from the generated ids, even if they were generated on different machines
13
+
> ⚠️ 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.
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.
25
-
26
-
```javascript
27
-
28
-
const { UniqueID } =require('nodejs-snowflake');
29
-
30
-
constuid=newUniqueID({
31
-
returnNumber:true
32
-
});
33
-
34
-
constID=uid.getUniqueID(); // This id is in javascript bigint format
35
-
36
-
```
37
-
38
-
### VERSION 1.5.x Notice
39
-
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.
40
-
41
-
```javascript
42
-
43
-
const { UniqueID } =require('nodejs-snowflake');
44
-
45
-
constuid=newUniqueID({
46
-
...,
47
-
machineID:2345// Any number between 0 - 4095. If not provided then a random number will be used
48
-
});
49
-
50
-
```
51
-
52
22
## Usage
53
23
54
24
### Generate ID
55
25
56
26
```javascript
57
-
const { UniqueID } =require('nodejs-snowflake');
27
+
const { Snowflake } =require('nodejs-snowflake');
58
28
59
-
constuid=newUniqueID(config);
29
+
constuid=newSnowflake(config);
60
30
61
31
uid.getUniqueID(); // A 64 bit id is returned
62
32
63
-
uid.asyncGetUniqueID().then(id=>console.log(id)); // Promisified version of the above method
64
-
65
33
```
66
34
67
35
#### Configuration
68
36
UniqueID constructor takes in the following configuration
69
37
70
38
```javascript
71
39
{
72
-
returnNumber: boolean, // Defaults to false. If set to true, the returned ids will be of type bigint or else of type string
73
-
customEpoch: number, // Defaults to 1546300800000 (01-01-2019). This is UNIX timestamp in ms
74
-
machineID: number // A value ranging between 0 - 4095. If not provided then a random value will be used
40
+
custom_epoch: number, // Defaults to Date.now(). This is UNIX timestamp in ms
41
+
instance_id: number // A value ranging between 0 - 4095. If not provided then a random value will be used
75
42
}
76
43
```
77
44
78
-
### Get timestamp from the ID
79
-
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.
45
+
### Get ID corresponding to a Timestamp
46
+
This can be extremely helpful in writing database queries where the requirement could be to get entries created after a certain timestamp.
80
47
81
48
```javascript
82
49
...
83
50
84
-
uid.getTimestampFromID(id); // Here id can be either as as string or as a bigint
51
+
constid=uid.idFromTimestamp(Date.now()); // Here id will always be BigInt
52
+
53
+
console.log(id); // A 64 bit id is returned corresponding to the timestamp given
85
54
86
55
```
87
56
88
-
### Get machine id from the ID
89
-
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.
57
+
### Get timestamp from the ID
58
+
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.
90
59
91
60
```javascript
92
61
...
93
62
94
-
constmid=uid.getMachineIDFromID(id); // Here id can be either as as string or as a bigint
63
+
// Pass the custom epoch that was used to generate this ID
console.log(mid);//2345 -> This is the 12 bit long machine id where this token was generated
66
+
console.log(ts)//Timestamp of creation of the id
97
67
98
68
```
99
69
100
-
### Get ID corresponding to a Timestamp
101
-
This can be extremely helpful in writing database queries where the requirement could be to get entries created after a certain timestamp.
70
+
### Get machine id from the ID
71
+
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.
102
72
103
73
```javascript
104
74
...
105
75
106
-
constid=uid.IDFromTimestamp(Date.now()); // Here id will always be BigInt
76
+
constmid=Snowflake.instanceIDFromID(id);
107
77
108
-
console.log(id); //A 64 bit id is returned corresponding to the timestamp given
78
+
console.log(mid); //2345 -> This is the 12 bit long machine id where this token was generated
109
79
110
80
```
111
81
@@ -115,23 +85,6 @@ This solely exits to find the machine id of current machine in case the user did
115
85
```javascript
116
86
...
117
87
118
-
uid.machineID; // The machine id of the current machine, set either by user or randomly generated
119
-
120
-
```
121
-
122
-
123
-
## Basic benchmark
124
-
```bash
125
-
# Run for 1sec while invoking function every ms (default)
126
-
npm run benchmark
127
-
128
-
# All the arguments
129
-
# --time -> Total time for which the id should be generated
130
-
# --type -> Return type of the id (could be number or string)
131
-
# --interval -> Time interval in which id generation function should invoked
0 commit comments