3.7 KiB
node-uuid
Simple, fast generation of RFC4122RFC4122(v4) UUIDS. It runs in node.js and all major browsers.
Installation
npm install node-uuid
In browser
<script src="uuid.js"></script>
In node.js
var uuid = require('node-uuid');
Usage
Generate a String UUID
var id = uuid(); // -> '92329D39-6F5C-4520-ABFC-AAB64544E172'
Generate a Binary UUID
// Simple form - allocates a Buffer/Array for you
var buf = uuid('binary');
// node.js -> <Buffer 08 50 05 c8 9c b2 4c 07 ac 07 d1 4f b9 f5 04 51>
// browser -> [8, 80, 5, 200, 156, 178, 76, 7, 172, 7, 209, 79, 185, 245, 4, 81]
// Provide your own Buffer or Array
var buf = new Array(16);
uuid('binary', buf); // -> [8, 80, 5, 200, 156, 178, 76, 7, 172, 7, 209, 79, 185, 245, 4, 81]
var buf = new Buffer(16);
uuid('binary', buf); // -> <Buffer 08 50 05 c8 9c b2 4c 07 ac 07 d1 4f b9 f5 04 51>
// Provide your own Buffer/Array, plus specify offset
// (e.g. here we fill an array with 3 uuids)
var buf = new Buffer(16 \* 3);
uuid('binary', id, 0);
uuid('binary', id, 16);
uuid('binary', id, 32);
Testing
test/test.js generates performance data (similar to test/benchmark.js). It also verifies the syntax of 100K string UUIDs, and logs the distribution of hex digits found therein. For example:
- - - Performance Data - - -
uuid(): 1052631 uuids/second
uuid('binary'): 680272 uuids/second
uuid('binary', buffer): 2702702 uuids/second
- - - Distribution of Hex Digits (% deviation from ideal) - - -
0 |================================| 187705 (0.11%)
1 |================================| 187880 (0.2%)
2 |================================| 186875 (-0.33%)
3 |================================| 186847 (-0.35%)
4 |==================================================| 287433 (-0.02%)
5 |================================| 187910 (0.22%)
6 |================================| 188172 (0.36%)
7 |================================| 187350 (-0.08%)
8 |====================================| 211994 (-0.24%)
9 |====================================| 212664 (0.08%)
A |=====================================| 213185 (0.32%)
B |=====================================| 212877 (0.18%)
C |================================| 187445 (-0.03%)
D |================================| 186737 (-0.41%)
E |================================| 187155 (-0.18%)
F |================================| 187771 (0.14%)
Note that the increased values for 4 and 8-B are expected as part of the RFC4122 syntax (and are accounted for in the deviation calculation). BTW, if someone wants to do the calculation to determine what a statistically significant deviation would be, I'll gladly add that to the test.
In browser
Open test/test.html
In node.js
> node test/test.js
node.js users can also run the node-uuid .vs. uuid.js benchmark:
> node test/benchmark.js
Performance
In node.js
node-uuid is designed to be fast. That said, the target platform is node.js, where it is screaming fast. Here's what I get on my 2.66GHz Macbook Pro for the test/benchmark.js script:
nodeuuid(): 1126126 uuids/second
nodeuuid('binary'): 782472 uuids/second
nodeuuid('binary', buffer): 2688172 uuids/second
uuidjs(): 620347 uuids/second
uuidjs('binary'): 1275510 uuids/second
The uuidjs() entries are for Nikhil Marathe's uuidjs module, and are provided for comparison. uuidjs is a wrapper around the native libuuid library.
In browser
node-uuid performance varies dramatically across browsers. For comprehensive test results, please checkout the JSPerf tests.