<!-- -- This file is auto-generated from README_js.md. Changes should be made there. -->
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(); // ⇨ '45745c60-7b1a-11e8-9c9c-2d42b21b1a3e'
Version 3 (namespace):
const uuidv3 = require('uuid/v3');
// ... using predefined DNS namespace (for domain names)
uuidv3('hello.example.com', uuidv3.DNS); // ⇨ '9125a8dc-52ee-365b-a5aa-81b0b3681cf6'
// ... using predefined URL namespace (for, well, URLs)
uuidv3('http://example.com/hello', uuidv3.URL); // ⇨ 'c6235813-3ba4-3801-ae84-e0a6ebb7d138'
// ... 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); // ⇨ 'e8b5a51d-11c8-3310-a6ab-367563f20686'
Version 4 (random):
const uuidv4 = require('uuid/v4');
uuidv4(); // ⇨ '10ba038e-48da-487b-96e8-8d3b99b6d18a'
Version 5 (namespace):
const uuidv5 = require('uuid/v5');
// ... using predefined DNS namespace (for domain names)
uuidv5('hello.example.com', uuidv5.DNS); // ⇨ 'fdda765f-fc57-5604-a269-52a7df8164ec'
// ... using predefined URL namespace (for, well, URLs)
uuidv5('http://example.com/hello', uuidv5.URL); // ⇨ '3bbcee75-cecc-5b56-8031-b6641c1ed1f1'
// ... 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); // ⇨ '630eb68f-e0fa-5ecc-887a-7c7a62614681'
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); // ⇨ '710b962e-041c-11e1-9234-0123456789ab'
Example: In-place generation of two binary IDs
// Generate two ids in an array
const arr = new Array();
uuidv1(null, arr, 0); // ⇨ [ 69, 117, 109, 208, 123, 26, 17, 232, 146, 52, 45, 66, 178, 27, 26, 62 ]
uuidv1(null, arr, 16); // ⇨ [ 69, 117, 109, 208, 123, 26, 17, 232, 146, 52, 45, 66, 178, 27, 26, 62, 69, 117, 109, 209, 123, 26, 17, 232, 146, 52, 45, 66, 178, 27, 26, 62 ]
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); // ⇨ '042ffd34-d989-321c-ad06-f60826172424'
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); // ⇨ '109156be-c4fb-41ea-b1b4-efe1671c5836'
Example: Generate two IDs in a single buffer
const buffer = new Array();
uuidv4(null, buffer, 0); // ⇨ [ 54, 122, 218, 70, 45, 70, 65, 24, 171, 53, 95, 130, 83, 195, 242, 45 ]
uuidv4(null, buffer, 16); // ⇨ [ 54, 122, 218, 70, 45, 70, 65, 24, 171, 53, 95, 130, 83, 195, 242, 45, 108, 204, 255, 103, 171, 86, 76, 94, 178, 225, 188, 236, 150, 20, 151, 87 ]
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); // ⇨ '9f282611-e0fd-5650-8953-89c8e342da0b'
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
---- Markdown generated from README_js.md by RunMD Logo
Source
| 1 | <!-- |
| 2 | -- This file is auto-generated from README_js.md. Changes should be made there. |
| 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 |
| 30 | const uuidv1 = require('uuid/v1'); |
| 31 | uuidv1(); // ⇨ '45745c60-7b1a-11e8-9c9c-2d42b21b1a3e' |
| 32 | |
| 33 | ``` |
| 34 | |
| 35 | Version 3 (namespace): |
| 36 | |
| 37 | ```javascript |
| 38 | const uuidv3 = require('uuid/v3'); |
| 39 | |
| 40 | // ... using predefined DNS namespace (for domain names) |
| 41 | uuidv3('hello.example.com', uuidv3.DNS); // ⇨ '9125a8dc-52ee-365b-a5aa-81b0b3681cf6' |
| 42 | |
| 43 | // ... using predefined URL namespace (for, well, URLs) |
| 44 | uuidv3('http://example.com/hello', uuidv3.URL); // ⇨ 'c6235813-3ba4-3801-ae84-e0a6ebb7d138' |
| 45 | |
| 46 | // ... using a custom namespace |
| 47 | // |
| 48 | // Note: Custom namespaces should be a UUID string specific to your application! |
| 49 | // E.g. the one here was generated using this modules `uuid` CLI. |
| 50 | const MY_NAMESPACE = '1b671a64-40d5-491e-99b0-da01ff1f3341'; |
| 51 | uuidv3('Hello, World!', MY_NAMESPACE); // ⇨ 'e8b5a51d-11c8-3310-a6ab-367563f20686' |
| 52 | |
| 53 | ``` |
| 54 | |
| 55 | Version 4 (random): |
| 56 | |
| 57 | ```javascript |
| 58 | const uuidv4 = require('uuid/v4'); |
| 59 | uuidv4(); // ⇨ '10ba038e-48da-487b-96e8-8d3b99b6d18a' |
| 60 | |
| 61 | ``` |
| 62 | |
| 63 | Version 5 (namespace): |
| 64 | |
| 65 | ```javascript |
| 66 | const uuidv5 = require('uuid/v5'); |
| 67 | |
| 68 | // ... using predefined DNS namespace (for domain names) |
| 69 | uuidv5('hello.example.com', uuidv5.DNS); // ⇨ 'fdda765f-fc57-5604-a269-52a7df8164ec' |
| 70 | |
| 71 | // ... using predefined URL namespace (for, well, URLs) |
| 72 | uuidv5('http://example.com/hello', uuidv5.URL); // ⇨ '3bbcee75-cecc-5b56-8031-b6641c1ed1f1' |
| 73 | |
| 74 | // ... using a custom namespace |
| 75 | // |
| 76 | // Note: Custom namespaces should be a UUID string specific to your application! |
| 77 | // E.g. the one here was generated using this modules `uuid` CLI. |
| 78 | const MY_NAMESPACE = '1b671a64-40d5-491e-99b0-da01ff1f3341'; |
| 79 | uuidv5('Hello, World!', MY_NAMESPACE); // ⇨ '630eb68f-e0fa-5ecc-887a-7c7a62614681' |
| 80 | |
| 81 | ``` |
| 82 | |
| 83 | ## Quickstart - Browser-ready Versions |
| 84 | |
| 85 | Browser-ready versions of this module are available via [wzrd.in](https://github.com/jfhbrook/wzrd.in). |
| 86 | |
| 87 | For version 1 uuids: |
| 88 | |
| 89 | ```html |
| 90 | <script src="http://wzrd.in/standalone/uuid%2Fv1@latest"></script> |
| 91 | <script> |
| 92 | uuidv1(); // -> v1 UUID |
| 93 | </script> |
| 94 | ``` |
| 95 | |
| 96 | For version 3 uuids: |
| 97 | |
| 98 | ```html |
| 99 | <script src="http://wzrd.in/standalone/uuid%2Fv3@latest"></script> |
| 100 | <script> |
| 101 | uuidv3('http://example.com/hello', uuidv3.URL); // -> v3 UUID |
| 102 | </script> |
| 103 | ``` |
| 104 | |
| 105 | For version 4 uuids: |
| 106 | |
| 107 | ```html |
| 108 | <script src="http://wzrd.in/standalone/uuid%2Fv4@latest"></script> |
| 109 | <script> |
| 110 | uuidv4(); // -> v4 UUID |
| 111 | </script> |
| 112 | ``` |
| 113 | |
| 114 | For version 5 uuids: |
| 115 | |
| 116 | ```html |
| 117 | <script src="http://wzrd.in/standalone/uuid%2Fv5@latest"></script> |
| 118 | <script> |
| 119 | uuidv5('http://example.com/hello', uuidv5.URL); // -> v5 UUID |
| 120 | </script> |
| 121 | ``` |
| 122 | |
| 123 | ## API |
| 124 | |
| 125 | ### Version 1 |
| 126 | |
| 127 | ```javascript |
| 128 | const uuidv1 = require('uuid/v1'); |
| 129 | |
| 130 | // Incantations |
| 131 | uuidv1(); |
| 132 | uuidv1(options); |
| 133 | uuidv1(options, buffer, offset); |
| 134 | ``` |
| 135 | |
| 136 | Generate and return a RFC4122 v1 (timestamp-based) UUID. |
| 137 | |
| 138 | * `options` - (Object) Optional uuid state to apply. Properties may include: |
| 139 | |
| 140 | * `node` - (Array) Node id as Array of 6 bytes (per 4.1.6). Default: Randomly generated ID. See note 1. |
| 141 | * `clockseq` - (Number between 0 - 0x3fff) RFC clock sequence. Default: An internally maintained clockseq is used. |
| 142 | * `msecs` - (Number) Time in milliseconds since unix Epoch. Default: The current time is used. |
| 143 | * `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. |
| 144 | |
| 145 | * `buffer` - (Array | Buffer) Array or buffer where UUID bytes are to be written. |
| 146 | * `offset` - (Number) Starting index in `buffer` at which to begin writing. |
| 147 | |
| 148 | Returns `buffer`, if specified, otherwise the string form of the UUID |
| 149 | |
| 150 | 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.) |
| 151 | |
| 152 | Example: Generate string UUID with fully-specified options |
| 153 | |
| 154 | ```javascript |
| 155 | const v1options = { |
| 156 | node: [0x01, 0x23, 0x45, 0x67, 0x89, 0xab], |
| 157 | clockseq: 0x1234, |
| 158 | msecs: new Date('2011-11-01').getTime(), |
| 159 | nsecs: 5678 |
| 160 | }; |
| 161 | uuidv1(v1options); // ⇨ '710b962e-041c-11e1-9234-0123456789ab' |
| 162 | |
| 163 | ``` |
| 164 | |
| 165 | Example: In-place generation of two binary IDs |
| 166 | |
| 167 | ```javascript |
| 168 | // Generate two ids in an array |
| 169 | const arr = new Array(); |
| 170 | uuidv1(null, arr, 0); // ⇨ [ 69, 117, 109, 208, 123, 26, 17, 232, 146, 52, 45, 66, 178, 27, 26, 62 ] |
| 171 | uuidv1(null, arr, 16); // ⇨ [ 69, 117, 109, 208, 123, 26, 17, 232, 146, 52, 45, 66, 178, 27, 26, 62, 69, 117, 109, 209, 123, 26, 17, 232, 146, 52, 45, 66, 178, 27, 26, 62 ] |
| 172 | |
| 173 | ``` |
| 174 | |
| 175 | ### Version 3 |
| 176 | |
| 177 | ```javascript |
| 178 | const uuidv3 = require('uuid/v3'); |
| 179 | |
| 180 | // Incantations |
| 181 | uuidv3(name, namespace); |
| 182 | uuidv3(name, namespace, buffer); |
| 183 | uuidv3(name, namespace, buffer, offset); |
| 184 | ``` |
| 185 | |
| 186 | Generate and return a RFC4122 v3 UUID. |
| 187 | |
| 188 | * `name` - (String | Array[]) "name" to create UUID with |
| 189 | * `namespace` - (String | Array[]) "namespace" UUID either as a String or Array[16] of byte values |
| 190 | * `buffer` - (Array | Buffer) Array or buffer where UUID bytes are to be written. |
| 191 | * `offset` - (Number) Starting index in `buffer` at which to begin writing. Default = 0 |
| 192 | |
| 193 | Returns `buffer`, if specified, otherwise the string form of the UUID |
| 194 | |
| 195 | Example: |
| 196 | |
| 197 | ```javascript |
| 198 | uuidv3('hello world', MY_NAMESPACE); // ⇨ '042ffd34-d989-321c-ad06-f60826172424' |
| 199 | |
| 200 | ``` |
| 201 | |
| 202 | ### Version 4 |
| 203 | |
| 204 | ```javascript |
| 205 | const uuidv4 = require('uuid/v4') |
| 206 | |
| 207 | // Incantations |
| 208 | uuidv4(); |
| 209 | uuidv4(options); |
| 210 | uuidv4(options, buffer, offset); |
| 211 | ``` |
| 212 | |
| 213 | Generate and return a RFC4122 v4 UUID. |
| 214 | |
| 215 | * `options` - (Object) Optional uuid state to apply. Properties may include: |
| 216 | * `random` - (Number[16]) Array of 16 numbers (0-255) to use in place of randomly generated values |
| 217 | * `rng` - (Function) Random # generator function that returns an Array[16] of byte values (0-255) |
| 218 | * `buffer` - (Array | Buffer) Array or buffer where UUID bytes are to be written. |
| 219 | * `offset` - (Number) Starting index in `buffer` at which to begin writing. |
| 220 | |
| 221 | Returns `buffer`, if specified, otherwise the string form of the UUID |
| 222 | |
| 223 | Example: Generate string UUID with predefined `random` values |
| 224 | |
| 225 | ```javascript |
| 226 | const v4options = { |
| 227 | random: [ |
| 228 | 0x10, 0x91, 0x56, 0xbe, 0xc4, 0xfb, 0xc1, 0xea, |
| 229 | 0x71, 0xb4, 0xef, 0xe1, 0x67, 0x1c, 0x58, 0x36 |
| 230 | ] |
| 231 | }; |
| 232 | uuidv4(v4options); // ⇨ '109156be-c4fb-41ea-b1b4-efe1671c5836' |
| 233 | |
| 234 | ``` |
| 235 | |
| 236 | Example: Generate two IDs in a single buffer |
| 237 | |
| 238 | ```javascript |
| 239 | const buffer = new Array(); |
| 240 | uuidv4(null, buffer, 0); // ⇨ [ 54, 122, 218, 70, 45, 70, 65, 24, 171, 53, 95, 130, 83, 195, 242, 45 ] |
| 241 | uuidv4(null, buffer, 16); // ⇨ [ 54, 122, 218, 70, 45, 70, 65, 24, 171, 53, 95, 130, 83, 195, 242, 45, 108, 204, 255, 103, 171, 86, 76, 94, 178, 225, 188, 236, 150, 20, 151, 87 ] |
| 242 | |
| 243 | ``` |
| 244 | |
| 245 | ### Version 5 |
| 246 | |
| 247 | ```javascript |
| 248 | const uuidv5 = require('uuid/v5'); |
| 249 | |
| 250 | // Incantations |
| 251 | uuidv5(name, namespace); |
| 252 | uuidv5(name, namespace, buffer); |
| 253 | uuidv5(name, namespace, buffer, offset); |
| 254 | ``` |
| 255 | |
| 256 | Generate and return a RFC4122 v5 UUID. |
| 257 | |
| 258 | * `name` - (String | Array[]) "name" to create UUID with |
| 259 | * `namespace` - (String | Array[]) "namespace" UUID either as a String or Array[16] of byte values |
| 260 | * `buffer` - (Array | Buffer) Array or buffer where UUID bytes are to be written. |
| 261 | * `offset` - (Number) Starting index in `buffer` at which to begin writing. Default = 0 |
| 262 | |
| 263 | Returns `buffer`, if specified, otherwise the string form of the UUID |
| 264 | |
| 265 | Example: |
| 266 | |
| 267 | ```javascript |
| 268 | uuidv5('hello world', MY_NAMESPACE); // ⇨ '9f282611-e0fd-5650-8953-89c8e342da0b' |
| 269 | |
| 270 | ``` |
| 271 | |
| 272 | ## Command Line |
| 273 | |
| 274 | UUIDs can be generated from the command line with the `uuid` command. |
| 275 | |
| 276 | ```shell |
| 277 | $ uuid |
| 278 | ddeb27fb-d9a0-4624-be4d-4615062daed4 |
| 279 | |
| 280 | $ uuid v1 |
| 281 | 02d37060-d446-11e7-a9fa-7bdae751ebe1 |
| 282 | ``` |
| 283 | |
| 284 | Type `uuid --help` for usage details |
| 285 | |
| 286 | ## Testing |
| 287 | |
| 288 | ```shell |
| 289 | npm test |
| 290 | ``` |
| 291 | |
| 292 | ---- |
| 293 | Markdown generated from [README_js.md](README_js.md) by [](https://github.com/broofa/runmd) |