runmd.onRequire = path => path.replace(/^uuid/, './');
uuid
#
Simple, fast generation of RFC4122 UUIDS.
Features:
- Support for version 1, 3, 4 and 5 UUIDs
- Cross-platform
- Uses cryptographically-strong random number APIs (when available)
- Zero-dependency, small footprint (... but not this small)
[Deprecation warning: The use of require('uuid') is deprecated and will not be supported after version 3.x of this module. Instead, use require('uuid/[v1|v3|v4|v5]') as shown in the examples below.]
Quickstart - CommonJS (Recommended)
npm install uuid
Then generate your uuid version of choice ...
Version 1 (timestamp):
const uuidv1 = require('uuid/v1');
uuidv1(); // RESULT
Version 3 (namespace):
const uuidv3 = require('uuid/v3');
// ... using predefined DNS namespace (for domain names)
uuidv3('hello.example.com', uuidv3.DNS); // RESULT
// ... using predefined URL namespace (for, well, URLs)
uuidv3('http://example.com/hello', uuidv3.URL); // RESULT
// ... using a custom namespace
//
// Note: Custom namespaces should be a UUID string specific to your application!
// E.g. the one here was generated using this modules `uuid` CLI.
const MY_NAMESPACE = '1b671a64-40d5-491e-99b0-da01ff1f3341';
uuidv3('Hello, World!', MY_NAMESPACE); // RESULT
Version 4 (random):
const uuidv4 = require('uuid/v4');
uuidv4(); // RESULT
Version 5 (namespace):
const uuidv5 = require('uuid/v5');
// ... using predefined DNS namespace (for domain names)
uuidv5('hello.example.com', uuidv5.DNS); // RESULT
// ... using predefined URL namespace (for, well, URLs)
uuidv5('http://example.com/hello', uuidv5.URL); // RESULT
// ... using a custom namespace
//
// Note: Custom namespaces should be a UUID string specific to your application!
// E.g. the one here was generated using this modules `uuid` CLI.
const MY_NAMESPACE = '1b671a64-40d5-491e-99b0-da01ff1f3341';
uuidv5('Hello, World!', MY_NAMESPACE); // RESULT
Quickstart - Browser-ready Versions
Browser-ready versions of this module are available via wzrd.in.
For version 1 uuids:
<script src="http://wzrd.in/standalone/uuid%2Fv1@latest"></script>
<script>
uuidv1(); // -> v1 UUID
</script>
For version 3 uuids:
<script src="http://wzrd.in/standalone/uuid%2Fv3@latest"></script>
<script>
uuidv3('http://example.com/hello', uuidv3.URL); // -> v3 UUID
</script>
For version 4 uuids:
<script src="http://wzrd.in/standalone/uuid%2Fv4@latest"></script>
<script>
uuidv4(); // -> v4 UUID
</script>
For version 5 uuids:
<script src="http://wzrd.in/standalone/uuid%2Fv5@latest"></script>
<script>
uuidv5('http://example.com/hello', uuidv5.URL); // -> v5 UUID
</script>
API
Version 1
const uuidv1 = require('uuid/v1');
// Incantations
uuidv1();
uuidv1(options);
uuidv1(options, buffer, offset);
Generate and return a RFC4122 v1 (timestamp-based) UUID.
options- (Object) Optional uuid state to apply. Properties may include:
node- (Array) Node id as Array of 6 bytes (per 4.1.6). Default: Randomly generated ID. See note 1.clockseq- (Number between 0 - 0x3fff) RFC clock sequence. Default: An internally maintained clockseq is used.msecs- (Number) Time in milliseconds since unix Epoch. Default: The current time is used.nsecs- (Number between 0-9999) additional time, in 100-nanosecond units. Ignored ifmsecsis unspecified. Default: internal uuid counter is used, as per 4.2.1.2.
buffer- (Array | Buffer) Array or buffer where UUID bytes are to be written.offset- (Number) Starting index inbufferat which to begin writing.
Returns buffer, if specified, otherwise the string form of the UUID
Note: The <node> id is generated guaranteed to stay constant for the lifetime of the current JS runtime. (Future versions of this module may use persistent storage mechanisms to extend this guarantee.)
Example: Generate string UUID with fully-specified options
const v1options = {
node: [0x01, 0x23, 0x45, 0x67, 0x89, 0xab],
clockseq: 0x1234,
msecs: new Date('2011-11-01').getTime(),
nsecs: 5678
};
uuidv1(v1options); // RESULT
Example: In-place generation of two binary IDs
// Generate two ids in an array
const arr = new Array();
uuidv1(null, arr, 0); // RESULT
uuidv1(null, arr, 16); // RESULT
Version 3
const uuidv3 = require('uuid/v3');
// Incantations
uuidv3(name, namespace);
uuidv3(name, namespace, buffer);
uuidv3(name, namespace, buffer, offset);
Generate and return a RFC4122 v3 UUID.
name- (String | Array[]) "name" to create UUID withnamespace- (String | Array[]) "namespace" UUID either as a String or Array[16] of byte valuesbuffer- (Array | Buffer) Array or buffer where UUID bytes are to be written.offset- (Number) Starting index inbufferat which to begin writing. Default = 0
Returns buffer, if specified, otherwise the string form of the UUID
Example:
uuidv3('hello world', MY_NAMESPACE); // RESULT
Version 4
const uuidv4 = require('uuid/v4')
// Incantations
uuidv4();
uuidv4(options);
uuidv4(options, buffer, offset);
Generate and return a RFC4122 v4 UUID.
options- (Object) Optional uuid state to apply. Properties may include:random- (Number[16]) Array of 16 numbers (0-255) to use in place of randomly generated valuesrng- (Function) Random # generator function that returns an Array[16] of byte values (0-255)buffer- (Array | Buffer) Array or buffer where UUID bytes are to be written.offset- (Number) Starting index inbufferat which to begin writing.
Returns buffer, if specified, otherwise the string form of the UUID
Example: Generate string UUID with predefined random values
const v4options = {
random: [
0x10, 0x91, 0x56, 0xbe, 0xc4, 0xfb, 0xc1, 0xea,
0x71, 0xb4, 0xef, 0xe1, 0x67, 0x1c, 0x58, 0x36
]
};
uuidv4(v4options); // RESULT
Example: Generate two IDs in a single buffer
const buffer = new Array();
uuidv4(null, buffer, 0); // RESULT
uuidv4(null, buffer, 16); // RESULT
Version 5
const uuidv5 = require('uuid/v5');
// Incantations
uuidv5(name, namespace);
uuidv5(name, namespace, buffer);
uuidv5(name, namespace, buffer, offset);
Generate and return a RFC4122 v5 UUID.
name- (String | Array[]) "name" to create UUID withnamespace- (String | Array[]) "namespace" UUID either as a String or Array[16] of byte valuesbuffer- (Array | Buffer) Array or buffer where UUID bytes are to be written.offset- (Number) Starting index inbufferat which to begin writing. Default = 0
Returns buffer, if specified, otherwise the string form of the UUID
Example:
uuidv5('hello world', MY_NAMESPACE); // RESULT
Command Line
UUIDs can be generated from the command line with the uuid command.
$ uuid
ddeb27fb-d9a0-4624-be4d-4615062daed4
$ uuid v1
02d37060-d446-11e7-a9fa-7bdae751ebe1
Type uuid --help for usage details
Testing
npm test
Source
| 1 | ```javascript --hide |
| 2 | runmd.onRequire = path => path.replace(/^uuid/, './'); |
| 3 | ``` |
| 4 | |
| 5 | # uuid [](http://travis-ci.org/kelektiv/node-uuid) # |
| 6 | |
| 7 | Simple, fast generation of [RFC4122](http://www.ietf.org/rfc/rfc4122.txt) UUIDS. |
| 8 | |
| 9 | Features: |
| 10 | |
| 11 | * Support for version 1, 3, 4 and 5 UUIDs |
| 12 | * Cross-platform |
| 13 | * Uses cryptographically-strong random number APIs (when available) |
| 14 | * Zero-dependency, small footprint (... but not [this small](https://gist.github.com/982883)) |
| 15 | |
| 16 | [**Deprecation warning**: The use of `require('uuid')` is deprecated and will not be |
| 17 | supported after version 3.x of this module. Instead, use `require('uuid/[v1|v3|v4|v5]')` as shown in the examples below.] |
| 18 | |
| 19 | ## Quickstart - CommonJS (Recommended) |
| 20 | |
| 21 | ```shell |
| 22 | npm install uuid |
| 23 | ``` |
| 24 | |
| 25 | Then generate your uuid version of choice ... |
| 26 | |
| 27 | Version 1 (timestamp): |
| 28 | |
| 29 | ```javascript --run v1 |
| 30 | const uuidv1 = require('uuid/v1'); |
| 31 | uuidv1(); // RESULT |
| 32 | ``` |
| 33 | |
| 34 | Version 3 (namespace): |
| 35 | |
| 36 | ```javascript --run v3 |
| 37 | const uuidv3 = require('uuid/v3'); |
| 38 | |
| 39 | // ... using predefined DNS namespace (for domain names) |
| 40 | uuidv3('hello.example.com', uuidv3.DNS); // RESULT |
| 41 | |
| 42 | // ... using predefined URL namespace (for, well, URLs) |
| 43 | uuidv3('http://example.com/hello', uuidv3.URL); // RESULT |
| 44 | |
| 45 | // ... using a custom namespace |
| 46 | // |
| 47 | // Note: Custom namespaces should be a UUID string specific to your application! |
| 48 | // E.g. the one here was generated using this modules `uuid` CLI. |
| 49 | const MY_NAMESPACE = '1b671a64-40d5-491e-99b0-da01ff1f3341'; |
| 50 | uuidv3('Hello, World!', MY_NAMESPACE); // RESULT |
| 51 | ``` |
| 52 | |
| 53 | Version 4 (random): |
| 54 | |
| 55 | ```javascript --run v4 |
| 56 | const uuidv4 = require('uuid/v4'); |
| 57 | uuidv4(); // RESULT |
| 58 | ``` |
| 59 | |
| 60 | Version 5 (namespace): |
| 61 | |
| 62 | ```javascript --run v5 |
| 63 | const uuidv5 = require('uuid/v5'); |
| 64 | |
| 65 | // ... using predefined DNS namespace (for domain names) |
| 66 | uuidv5('hello.example.com', uuidv5.DNS); // RESULT |
| 67 | |
| 68 | // ... using predefined URL namespace (for, well, URLs) |
| 69 | uuidv5('http://example.com/hello', uuidv5.URL); // RESULT |
| 70 | |
| 71 | // ... using a custom namespace |
| 72 | // |
| 73 | // Note: Custom namespaces should be a UUID string specific to your application! |
| 74 | // E.g. the one here was generated using this modules `uuid` CLI. |
| 75 | const MY_NAMESPACE = '1b671a64-40d5-491e-99b0-da01ff1f3341'; |
| 76 | uuidv5('Hello, World!', MY_NAMESPACE); // RESULT |
| 77 | ``` |
| 78 | |
| 79 | ## Quickstart - Browser-ready Versions |
| 80 | |
| 81 | Browser-ready versions of this module are available via [wzrd.in](https://github.com/jfhbrook/wzrd.in). |
| 82 | |
| 83 | For version 1 uuids: |
| 84 | |
| 85 | ```html |
| 86 | <script src="http://wzrd.in/standalone/uuid%2Fv1@latest"></script> |
| 87 | <script> |
| 88 | uuidv1(); // -> v1 UUID |
| 89 | </script> |
| 90 | ``` |
| 91 | |
| 92 | For version 3 uuids: |
| 93 | |
| 94 | ```html |
| 95 | <script src="http://wzrd.in/standalone/uuid%2Fv3@latest"></script> |
| 96 | <script> |
| 97 | uuidv3('http://example.com/hello', uuidv3.URL); // -> v3 UUID |
| 98 | </script> |
| 99 | ``` |
| 100 | |
| 101 | For version 4 uuids: |
| 102 | |
| 103 | ```html |
| 104 | <script src="http://wzrd.in/standalone/uuid%2Fv4@latest"></script> |
| 105 | <script> |
| 106 | uuidv4(); // -> v4 UUID |
| 107 | </script> |
| 108 | ``` |
| 109 | |
| 110 | For version 5 uuids: |
| 111 | |
| 112 | ```html |
| 113 | <script src="http://wzrd.in/standalone/uuid%2Fv5@latest"></script> |
| 114 | <script> |
| 115 | uuidv5('http://example.com/hello', uuidv5.URL); // -> v5 UUID |
| 116 | </script> |
| 117 | ``` |
| 118 | |
| 119 | ## API |
| 120 | |
| 121 | ### Version 1 |
| 122 | |
| 123 | ```javascript |
| 124 | const uuidv1 = require('uuid/v1'); |
| 125 | |
| 126 | // Incantations |
| 127 | uuidv1(); |
| 128 | uuidv1(options); |
| 129 | uuidv1(options, buffer, offset); |
| 130 | ``` |
| 131 | |
| 132 | Generate and return a RFC4122 v1 (timestamp-based) UUID. |
| 133 | |
| 134 | * `options` - (Object) Optional uuid state to apply. Properties may include: |
| 135 | |
| 136 | * `node` - (Array) Node id as Array of 6 bytes (per 4.1.6). Default: Randomly generated ID. See note 1. |
| 137 | * `clockseq` - (Number between 0 - 0x3fff) RFC clock sequence. Default: An internally maintained clockseq is used. |
| 138 | * `msecs` - (Number) Time in milliseconds since unix Epoch. Default: The current time is used. |
| 139 | * `nsecs` - (Number between 0-9999) additional time, in 100-nanosecond units. Ignored if `msecs` is unspecified. Default: internal uuid counter is used, as per 4.2.1.2. |
| 140 | |
| 141 | * `buffer` - (Array | Buffer) Array or buffer where UUID bytes are to be written. |
| 142 | * `offset` - (Number) Starting index in `buffer` at which to begin writing. |
| 143 | |
| 144 | Returns `buffer`, if specified, otherwise the string form of the UUID |
| 145 | |
| 146 | Note: The <node> id is generated guaranteed to stay constant for the lifetime of the current JS runtime. (Future versions of this module may use persistent storage mechanisms to extend this guarantee.) |
| 147 | |
| 148 | Example: Generate string UUID with fully-specified options |
| 149 | |
| 150 | ```javascript --run v1 |
| 151 | const v1options = { |
| 152 | node: [0x01, 0x23, 0x45, 0x67, 0x89, 0xab], |
| 153 | clockseq: 0x1234, |
| 154 | msecs: new Date('2011-11-01').getTime(), |
| 155 | nsecs: 5678 |
| 156 | }; |
| 157 | uuidv1(v1options); // RESULT |
| 158 | ``` |
| 159 | |
| 160 | Example: In-place generation of two binary IDs |
| 161 | |
| 162 | ```javascript --run v1 |
| 163 | // Generate two ids in an array |
| 164 | const arr = new Array(); |
| 165 | uuidv1(null, arr, 0); // RESULT |
| 166 | uuidv1(null, arr, 16); // RESULT |
| 167 | ``` |
| 168 | |
| 169 | ### Version 3 |
| 170 | |
| 171 | ```javascript |
| 172 | const uuidv3 = require('uuid/v3'); |
| 173 | |
| 174 | // Incantations |
| 175 | uuidv3(name, namespace); |
| 176 | uuidv3(name, namespace, buffer); |
| 177 | uuidv3(name, namespace, buffer, offset); |
| 178 | ``` |
| 179 | |
| 180 | Generate and return a RFC4122 v3 UUID. |
| 181 | |
| 182 | * `name` - (String | Array[]) "name" to create UUID with |
| 183 | * `namespace` - (String | Array[]) "namespace" UUID either as a String or Array[16] of byte values |
| 184 | * `buffer` - (Array | Buffer) Array or buffer where UUID bytes are to be written. |
| 185 | * `offset` - (Number) Starting index in `buffer` at which to begin writing. Default = 0 |
| 186 | |
| 187 | Returns `buffer`, if specified, otherwise the string form of the UUID |
| 188 | |
| 189 | Example: |
| 190 | |
| 191 | ```javascript --run v3 |
| 192 | uuidv3('hello world', MY_NAMESPACE); // RESULT |
| 193 | ``` |
| 194 | |
| 195 | ### Version 4 |
| 196 | |
| 197 | ```javascript |
| 198 | const uuidv4 = require('uuid/v4') |
| 199 | |
| 200 | // Incantations |
| 201 | uuidv4(); |
| 202 | uuidv4(options); |
| 203 | uuidv4(options, buffer, offset); |
| 204 | ``` |
| 205 | |
| 206 | Generate and return a RFC4122 v4 UUID. |
| 207 | |
| 208 | * `options` - (Object) Optional uuid state to apply. Properties may include: |
| 209 | * `random` - (Number[16]) Array of 16 numbers (0-255) to use in place of randomly generated values |
| 210 | * `rng` - (Function) Random # generator function that returns an Array[16] of byte values (0-255) |
| 211 | * `buffer` - (Array | Buffer) Array or buffer where UUID bytes are to be written. |
| 212 | * `offset` - (Number) Starting index in `buffer` at which to begin writing. |
| 213 | |
| 214 | Returns `buffer`, if specified, otherwise the string form of the UUID |
| 215 | |
| 216 | Example: Generate string UUID with predefined `random` values |
| 217 | |
| 218 | ```javascript --run v4 |
| 219 | const v4options = { |
| 220 | random: [ |
| 221 | 0x10, 0x91, 0x56, 0xbe, 0xc4, 0xfb, 0xc1, 0xea, |
| 222 | 0x71, 0xb4, 0xef, 0xe1, 0x67, 0x1c, 0x58, 0x36 |
| 223 | ] |
| 224 | }; |
| 225 | uuidv4(v4options); // RESULT |
| 226 | ``` |
| 227 | |
| 228 | Example: Generate two IDs in a single buffer |
| 229 | |
| 230 | ```javascript --run v4 |
| 231 | const buffer = new Array(); |
| 232 | uuidv4(null, buffer, 0); // RESULT |
| 233 | uuidv4(null, buffer, 16); // RESULT |
| 234 | ``` |
| 235 | |
| 236 | ### Version 5 |
| 237 | |
| 238 | ```javascript |
| 239 | const uuidv5 = require('uuid/v5'); |
| 240 | |
| 241 | // Incantations |
| 242 | uuidv5(name, namespace); |
| 243 | uuidv5(name, namespace, buffer); |
| 244 | uuidv5(name, namespace, buffer, offset); |
| 245 | ``` |
| 246 | |
| 247 | Generate and return a RFC4122 v5 UUID. |
| 248 | |
| 249 | * `name` - (String | Array[]) "name" to create UUID with |
| 250 | * `namespace` - (String | Array[]) "namespace" UUID either as a String or Array[16] of byte values |
| 251 | * `buffer` - (Array | Buffer) Array or buffer where UUID bytes are to be written. |
| 252 | * `offset` - (Number) Starting index in `buffer` at which to begin writing. Default = 0 |
| 253 | |
| 254 | Returns `buffer`, if specified, otherwise the string form of the UUID |
| 255 | |
| 256 | Example: |
| 257 | |
| 258 | ```javascript --run v5 |
| 259 | uuidv5('hello world', MY_NAMESPACE); // RESULT |
| 260 | ``` |
| 261 | |
| 262 | ## Command Line |
| 263 | |
| 264 | UUIDs can be generated from the command line with the `uuid` command. |
| 265 | |
| 266 | ```shell |
| 267 | $ uuid |
| 268 | ddeb27fb-d9a0-4624-be4d-4615062daed4 |
| 269 | |
| 270 | $ uuid v1 |
| 271 | 02d37060-d446-11e7-a9fa-7bdae751ebe1 |
| 272 | ``` |
| 273 | |
| 274 | Type `uuid --help` for usage details |
| 275 | |
| 276 | ## Testing |
| 277 | |
| 278 | ```shell |
| 279 | npm test |
| 280 | ``` |