1 | ```javascript --hide
|
2 | runmd.onRequire = path => path.replace(/^uuid/, './');
|
3 | ```
|
4 |
|
5 | # uuid [![Build Status](https://secure.travis-ci.org/kelektiv/node-uuid.svg?branch=master)](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 | ```
|