README.md (7915B)
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(); // ⇨ '2c5ea4c0-4067-11e9-8bad-9b1deb4d3b7d' 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(); // ⇨ '1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed' 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 ## API 84 85 ### Version 1 86 87 ```javascript 88 const uuidv1 = require('uuid/v1'); 89 90 // Incantations 91 uuidv1(); 92 uuidv1(options); 93 uuidv1(options, buffer, offset); 94 ``` 95 96 Generate and return a RFC4122 v1 (timestamp-based) UUID. 97 98 * `options` - (Object) Optional uuid state to apply. Properties may include: 99 100 * `node` - (Array) Node id as Array of 6 bytes (per 4.1.6). Default: Randomly generated ID. See note 1. 101 * `clockseq` - (Number between 0 - 0x3fff) RFC clock sequence. Default: An internally maintained clockseq is used. 102 * `msecs` - (Number) Time in milliseconds since unix Epoch. Default: The current time is used. 103 * `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. 104 105 * `buffer` - (Array | Buffer) Array or buffer where UUID bytes are to be written. 106 * `offset` - (Number) Starting index in `buffer` at which to begin writing. 107 108 Returns `buffer`, if specified, otherwise the string form of the UUID 109 110 Note: The default [node id](https://tools.ietf.org/html/rfc4122#section-4.1.6) (the last 12 digits in the UUID) is generated once, randomly, on process startup, and then remains unchanged for the duration of the process. 111 112 Example: Generate string UUID with fully-specified options 113 114 ```javascript 115 const v1options = { 116 node: [0x01, 0x23, 0x45, 0x67, 0x89, 0xab], 117 clockseq: 0x1234, 118 msecs: new Date('2011-11-01').getTime(), 119 nsecs: 5678 120 }; 121 uuidv1(v1options); // ⇨ '710b962e-041c-11e1-9234-0123456789ab' 122 123 ``` 124 125 Example: In-place generation of two binary IDs 126 127 ```javascript 128 // Generate two ids in an array 129 const arr = new Array(); 130 uuidv1(null, arr, 0); // ⇨ 131 // [ 132 // 44, 94, 164, 192, 64, 103, 133 // 17, 233, 146, 52, 155, 29, 134 // 235, 77, 59, 125 135 // ] 136 uuidv1(null, arr, 16); // ⇨ 137 // [ 138 // 44, 94, 164, 192, 64, 103, 17, 233, 139 // 146, 52, 155, 29, 235, 77, 59, 125, 140 // 44, 94, 164, 193, 64, 103, 17, 233, 141 // 146, 52, 155, 29, 235, 77, 59, 125 142 // ] 143 144 ``` 145 146 ### Version 3 147 148 ```javascript 149 const uuidv3 = require('uuid/v3'); 150 151 // Incantations 152 uuidv3(name, namespace); 153 uuidv3(name, namespace, buffer); 154 uuidv3(name, namespace, buffer, offset); 155 ``` 156 157 Generate and return a RFC4122 v3 UUID. 158 159 * `name` - (String | Array[]) "name" to create UUID with 160 * `namespace` - (String | Array[]) "namespace" UUID either as a String or Array[16] of byte values 161 * `buffer` - (Array | Buffer) Array or buffer where UUID bytes are to be written. 162 * `offset` - (Number) Starting index in `buffer` at which to begin writing. Default = 0 163 164 Returns `buffer`, if specified, otherwise the string form of the UUID 165 166 Example: 167 168 ```javascript 169 uuidv3('hello world', MY_NAMESPACE); // ⇨ '042ffd34-d989-321c-ad06-f60826172424' 170 171 ``` 172 173 ### Version 4 174 175 ```javascript 176 const uuidv4 = require('uuid/v4') 177 178 // Incantations 179 uuidv4(); 180 uuidv4(options); 181 uuidv4(options, buffer, offset); 182 ``` 183 184 Generate and return a RFC4122 v4 UUID. 185 186 * `options` - (Object) Optional uuid state to apply. Properties may include: 187 * `random` - (Number[16]) Array of 16 numbers (0-255) to use in place of randomly generated values 188 * `rng` - (Function) Random # generator function that returns an Array[16] of byte values (0-255) 189 * `buffer` - (Array | Buffer) Array or buffer where UUID bytes are to be written. 190 * `offset` - (Number) Starting index in `buffer` at which to begin writing. 191 192 Returns `buffer`, if specified, otherwise the string form of the UUID 193 194 Example: Generate string UUID with predefined `random` values 195 196 ```javascript 197 const v4options = { 198 random: [ 199 0x10, 0x91, 0x56, 0xbe, 0xc4, 0xfb, 0xc1, 0xea, 200 0x71, 0xb4, 0xef, 0xe1, 0x67, 0x1c, 0x58, 0x36 201 ] 202 }; 203 uuidv4(v4options); // ⇨ '109156be-c4fb-41ea-b1b4-efe1671c5836' 204 205 ``` 206 207 Example: Generate two IDs in a single buffer 208 209 ```javascript 210 const buffer = new Array(); 211 uuidv4(null, buffer, 0); // ⇨ 212 // [ 213 // 155, 29, 235, 77, 59, 214 // 125, 75, 173, 155, 221, 215 // 43, 13, 123, 61, 203, 216 // 109 217 // ] 218 uuidv4(null, buffer, 16); // ⇨ 219 // [ 220 // 155, 29, 235, 77, 59, 125, 75, 173, 221 // 155, 221, 43, 13, 123, 61, 203, 109, 222 // 27, 157, 107, 205, 187, 253, 75, 45, 223 // 155, 93, 171, 141, 251, 189, 75, 237 224 // ] 225 226 ``` 227 228 ### Version 5 229 230 ```javascript 231 const uuidv5 = require('uuid/v5'); 232 233 // Incantations 234 uuidv5(name, namespace); 235 uuidv5(name, namespace, buffer); 236 uuidv5(name, namespace, buffer, offset); 237 ``` 238 239 Generate and return a RFC4122 v5 UUID. 240 241 * `name` - (String | Array[]) "name" to create UUID with 242 * `namespace` - (String | Array[]) "namespace" UUID either as a String or Array[16] of byte values 243 * `buffer` - (Array | Buffer) Array or buffer where UUID bytes are to be written. 244 * `offset` - (Number) Starting index in `buffer` at which to begin writing. Default = 0 245 246 Returns `buffer`, if specified, otherwise the string form of the UUID 247 248 Example: 249 250 ```javascript 251 uuidv5('hello world', MY_NAMESPACE); // ⇨ '9f282611-e0fd-5650-8953-89c8e342da0b' 252 253 ``` 254 255 ## Command Line 256 257 UUIDs can be generated from the command line with the `uuid` command. 258 259 ```shell 260 $ uuid 261 ddeb27fb-d9a0-4624-be4d-4615062daed4 262 263 $ uuid v1 264 02d37060-d446-11e7-a9fa-7bdae751ebe1 265 ``` 266 267 Type `uuid --help` for usage details 268 269 ## Testing 270 271 ```shell 272 npm test 273 ``` 274 275 ---- 276 Markdown generated from [README_js.md](README_js.md) by [](https://github.com/broofa/runmd)