Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 200 lines (134 sloc) 6.254 kb
4edeead @broofa wip
authored
1 # node-uuid
fba452b @broofa wip
authored
2
280ea39 @broofa Use node.js crypto api if available, code cleanup, readme edits.
authored
3 Simple, fast generation of [RFC4122](http://www.ietf.org/rfc/rfc4122.txt) UUIDS.
fba452b @broofa wip
authored
4
280ea39 @broofa Use node.js crypto api if available, code cleanup, readme edits.
authored
5 Features:
9e39894 @broofa v1.0.0
authored
6
d966485 @broofa bug fixes, readme updates
authored
7 * Generate RFC4122 version 1 or version 4 UUIDs
8 * Runs in node.js and all browsers.
9 * Cryptographically strong random # generation on supporting platforms
b68db99 @broofa readme tweak for the uuid nerds
authored
10 * 1.1K minified and gzip'ed (Want something smaller? Check this [crazy shit](https://gist.github.com/982883) out! )
a704ecc @broofa remove docs
authored
11 * [Annotated source code](http://broofa.github.com/node-uuid/docs/uuid.html)
fba452b @broofa wip
authored
12
280ea39 @broofa Use node.js crypto api if available, code cleanup, readme edits.
authored
13 ## Getting Started
14
15 Install it in your browser:
3ab3ad6 @broofa add support for binary uuids. and of course, a complete rewrite to b…
authored
16
27e27f3 @ctavan Add nice syntax highlighting to code snippets in readme
ctavan authored
17 ```html
18 <script src="uuid.js"></script>
19 ```
fba452b @broofa wip
authored
20
280ea39 @broofa Use node.js crypto api if available, code cleanup, readme edits.
authored
21 Or in node.js:
22
23 ```
24 npm install node-uuid
25 ```
a99e3c8 @ctavan Update documentation for new v1() and v4() methods
ctavan authored
26
27e27f3 @ctavan Add nice syntax highlighting to code snippets in readme
ctavan authored
27 ```javascript
8465205 @ctavan Be more consistent with documentation
ctavan authored
28 var uuid = require('node-uuid');
280ea39 @broofa Use node.js crypto api if available, code cleanup, readme edits.
authored
29 ```
a99e3c8 @ctavan Update documentation for new v1() and v4() methods
ctavan authored
30
280ea39 @broofa Use node.js crypto api if available, code cleanup, readme edits.
authored
31 Then create some ids ...
a99e3c8 @ctavan Update documentation for new v1() and v4() methods
ctavan authored
32
280ea39 @broofa Use node.js crypto api if available, code cleanup, readme edits.
authored
33 ```javascript
34 // Generate a v1 (time-based) id
35 uuid.v1(); // -> '6c84fb90-12c4-11e1-840d-7b25c5ee775a'
36
37 // Generate a v4 (random) id
38 uuid.v4(); // -> '110ec58a-a0f2-4ac4-8393-c866d813b8d1'
27e27f3 @ctavan Add nice syntax highlighting to code snippets in readme
ctavan authored
39 ```
1bc4958 @broofa Update readme
authored
40
280ea39 @broofa Use node.js crypto api if available, code cleanup, readme edits.
authored
41 ## API
42
43 ### uuid.v1([`options` [, `buffer` [, `offset`]]])
44
4838cc2 @ctavan Readme tweaks
ctavan authored
45 Generate and return a RFC4122 v1 (timestamp-based) UUID.
d966485 @broofa bug fixes, readme updates
authored
46
47 * `options` - (Object) Optional uuid state to apply. Properties may include:
280ea39 @broofa Use node.js crypto api if available, code cleanup, readme edits.
authored
48
2203030 @mrjbq7 Update README.md
mrjbq7 authored
49 * `node` - (Array) Node id as Array of 6 bytes (per 4.1.6). Default: Randomly generated ID. See note 1.
d966485 @broofa bug fixes, readme updates
authored
50 * `clockseq` - (Number between 0 - 0x3fff) RFC clock sequence. Default: An internally maintained clockseq is used.
d008729 @broofa patch up docs and README, colorize console output in tests, bump vers…
authored
51 * `msecs` - (Number | Date) Time in milliseconds since unix Epoch. Default: The current time is used.
52 * `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.
280ea39 @broofa Use node.js crypto api if available, code cleanup, readme edits.
authored
53
217d1a4 @broofa readme edits
authored
54 * `buffer` - (Array | Buffer) Array or buffer where UUID bytes are to be written.
55 * `offset` - (Number) Starting index in `buffer` at which to begin writing.
1bc4958 @broofa Update readme
authored
56
217d1a4 @broofa readme edits
authored
57 Returns `buffer`, if specified, otherwise the string form of the UUID
280ea39 @broofa Use node.js crypto api if available, code cleanup, readme edits.
authored
58
59 Notes:
60
d966485 @broofa bug fixes, readme updates
authored
61 1. The randomly generated node id is only 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.)
280ea39 @broofa Use node.js crypto api if available, code cleanup, readme edits.
authored
62
63 Example: Generate string UUID with fully-specified options
3ab3ad6 @broofa add support for binary uuids. and of course, a complete rewrite to b…
authored
64
27e27f3 @ctavan Add nice syntax highlighting to code snippets in readme
ctavan authored
65 ```javascript
280ea39 @broofa Use node.js crypto api if available, code cleanup, readme edits.
authored
66 uuid.v1({
67 node: [0x01, 0x23, 0x45, 0x67, 0x89, 0xab],
68 clockseq: 0x1234,
95998e7 @ctavan I think implicit converions of a Date() instance is scary (although i…
ctavan authored
69 msecs: new Date('2011-11-01').getTime(),
280ea39 @broofa Use node.js crypto api if available, code cleanup, readme edits.
authored
70 nsecs: 5678
d966485 @broofa bug fixes, readme updates
authored
71 }); // -> "710b962e-041c-11e1-9234-0123456789ab"
27e27f3 @ctavan Add nice syntax highlighting to code snippets in readme
ctavan authored
72 ```
3ab3ad6 @broofa add support for binary uuids. and of course, a complete rewrite to b…
authored
73
d966485 @broofa bug fixes, readme updates
authored
74 Example: In-place generation of two binary IDs
3ab3ad6 @broofa add support for binary uuids. and of course, a complete rewrite to b…
authored
75
27e27f3 @ctavan Add nice syntax highlighting to code snippets in readme
ctavan authored
76 ```javascript
cebcb7f @broofa update readme
authored
77 // Generate two ids in an array
78 var arr = new Array(32); // -> []
79 uuid.v1(null, arr, 0); // -> [02 a2 ce 90 14 32 11 e1 85 58 0b 48 8e 4f c1 15]
80 uuid.v1(null, arr, 16); // -> [02 a2 ce 90 14 32 11 e1 85 58 0b 48 8e 4f c1 15 02 a3 1c b0 14 32 11 e1 85 58 0b 48 8e 4f c1 15]
d966485 @broofa bug fixes, readme updates
authored
81
82 // Optionally use uuid.unparse() to get stringify the ids
d008729 @broofa patch up docs and README, colorize console output in tests, bump vers…
authored
83 uuid.unparse(buffer); // -> '02a2ce90-1432-11e1-8558-0b488e4fc115'
84 uuid.unparse(buffer, 16) // -> '02a31cb0-1432-11e1-8558-0b488e4fc115'
280ea39 @broofa Use node.js crypto api if available, code cleanup, readme edits.
authored
85 ```
27e27f3 @ctavan Add nice syntax highlighting to code snippets in readme
ctavan authored
86
280ea39 @broofa Use node.js crypto api if available, code cleanup, readme edits.
authored
87 ### uuid.v4([`options` [, `buffer` [, `offset`]]])
27e27f3 @ctavan Add nice syntax highlighting to code snippets in readme
ctavan authored
88
4838cc2 @ctavan Readme tweaks
ctavan authored
89 Generate and return a RFC4122 v4 UUID.
8e8bcea @ctavan Documentation for exported BufferClass
ctavan authored
90
d966485 @broofa bug fixes, readme updates
authored
91 * `options` - (Object) Optional uuid state to apply. Properties may include:
92
93 * `random` - (Number[16]) Array of 16 numbers (0-255) to use in place of randomly generated values
d008729 @broofa patch up docs and README, colorize console output in tests, bump vers…
authored
94 * `rng` - (Function) Random # generator to use. Set to one of the built-in generators - `uuid.mathRNG` (all platforms), `uuid.nodeRNG` (node.js only), `uuid.whatwgRNG` (WebKit only) - or a custom function that returns an array[16] of byte values.
d966485 @broofa bug fixes, readme updates
authored
95
217d1a4 @broofa readme edits
authored
96 * `buffer` - (Array | Buffer) Array or buffer where UUID bytes are to be written.
97 * `offset` - (Number) Starting index in `buffer` at which to begin writing.
915daf1 @ctavan Update docs to include the new options object
ctavan authored
98
217d1a4 @broofa readme edits
authored
99 Returns `buffer`, if specified, otherwise the string form of the UUID
280ea39 @broofa Use node.js crypto api if available, code cleanup, readme edits.
authored
100
101 Example: Generate string UUID with fully-specified options
ce5c311 @ctavan Add some documentation on how to get the first and last timestamp of …
ctavan authored
102
103 ```javascript
280ea39 @broofa Use node.js crypto api if available, code cleanup, readme edits.
authored
104 uuid.v4({
105 random: [
106 0x10, 0x91, 0x56, 0xbe, 0xc4, 0xfb, 0xc1, 0xea,
107 0x71, 0xb4, 0xef, 0xe1, 0x67, 0x1c, 0x58, 0x36
108 ]
ce5c311 @ctavan Add some documentation on how to get the first and last timestamp of …
ctavan authored
109 });
280ea39 @broofa Use node.js crypto api if available, code cleanup, readme edits.
authored
110 // -> "109156be-c4fb-41ea-b1b4-efe1671c5836"
111 ```
112
d966485 @broofa bug fixes, readme updates
authored
113 Example: Generate two IDs in a single buffer
280ea39 @broofa Use node.js crypto api if available, code cleanup, readme edits.
authored
114
115 ```javascript
116 var buffer = new Array(32); // (or 'new Buffer' in node.js)
d966485 @broofa bug fixes, readme updates
authored
117 uuid.v4(null, buffer, 0);
118 uuid.v4(null, buffer, 16);
ce5c311 @ctavan Add some documentation on how to get the first and last timestamp of …
ctavan authored
119 ```
120
280ea39 @broofa Use node.js crypto api if available, code cleanup, readme edits.
authored
121 ### uuid.parse(id[, buffer[, offset]])
122 ### uuid.unparse(buffer[, offset])
123
124 Parse and unparse UUIDs
a1bd1da @ctavan Documentation for parse() and unparse() functions
ctavan authored
125
217d1a4 @broofa readme edits
authored
126 * `id` - (String) UUID(-like) string
127 * `buffer` - (Array | Buffer) Array or buffer where UUID bytes are to be written. Default: A new Array or Buffer is used
128 * `offset` - (Number) Starting index in `buffer` at which to begin writing. Default: 0
a1bd1da @ctavan Documentation for parse() and unparse() functions
ctavan authored
129
280ea39 @broofa Use node.js crypto api if available, code cleanup, readme edits.
authored
130 Example parsing and unparsing a UUID string
38a0ec3 @broofa readme tweaks
authored
131
a1bd1da @ctavan Documentation for parse() and unparse() functions
ctavan authored
132 ```javascript
38a0ec3 @broofa readme tweaks
authored
133 var bytes = uuid.parse('797ff043-11eb-11e1-80d6-510998755d10'); // -> <Buffer 79 7f f0 43 11 eb 11 e1 80 d6 51 09 98 75 5d 10>
134 var string = uuid.unparse(bytes); // -> '797ff043-11eb-11e1-80d6-510998755d10'
a1bd1da @ctavan Documentation for parse() and unparse() functions
ctavan authored
135 ```
136
280ea39 @broofa Use node.js crypto api if available, code cleanup, readme edits.
authored
137 ### uuid.noConflict()
ce5c311 @ctavan Add some documentation on how to get the first and last timestamp of …
ctavan authored
138
280ea39 @broofa Use node.js crypto api if available, code cleanup, readme edits.
authored
139 (Browsers only) Set `uuid` property back to it's previous value.
3ab3ad6 @broofa add support for binary uuids. and of course, a complete rewrite to b…
authored
140
217d1a4 @broofa readme edits
authored
141 Returns the node-uuid object.
3ab3ad6 @broofa add support for binary uuids. and of course, a complete rewrite to b…
authored
142
280ea39 @broofa Use node.js crypto api if available, code cleanup, readme edits.
authored
143 Example:
217d1a4 @broofa readme edits
authored
144
280ea39 @broofa Use node.js crypto api if available, code cleanup, readme edits.
authored
145 ```javascript
146 var myUuid = uuid.noConflict();
147 myUuid.v1(); // -> '6c84fb90-12c4-11e1-840d-7b25c5ee775a'
148 ```
d471972 @broofa readme tweak, fix performance bug, have node and browser test use the…
authored
149
d966485 @broofa bug fixes, readme updates
authored
150 ## Deprecated APIs
151
152 Support for the following v1.2 APIs is available in v1.3, but is deprecated and will be removed in the next major version.
153
154 ### uuid([format [, buffer [, offset]]])
155
156 uuid() has become uuid.v4(), and the `format` argument is now implicit in the `buffer` argument. (i.e. if you specify a buffer, the format is assumed to be binary).
157
158 ### uuid.BufferClass
159
160 The class of container created when generating binary uuid data if no buffer argument is specified. This is expected to go away, with no replacement API.
d471972 @broofa readme tweak, fix performance bug, have node and browser test use the…
authored
161
280ea39 @broofa Use node.js crypto api if available, code cleanup, readme edits.
authored
162 ## Testing
d471972 @broofa readme tweak, fix performance bug, have node and browser test use the…
authored
163
280ea39 @broofa Use node.js crypto api if available, code cleanup, readme edits.
authored
164 In node.js
4f25f28 @broofa unroll for-loop at Cory Ondrejka's suggestion
authored
165
280ea39 @broofa Use node.js crypto api if available, code cleanup, readme edits.
authored
166 ```
167 > cd test
168 > node uuid.js
169 ```
4f25f28 @broofa unroll for-loop at Cory Ondrejka's suggestion
authored
170
280ea39 @broofa Use node.js crypto api if available, code cleanup, readme edits.
authored
171 In Browser
3ab3ad6 @broofa add support for binary uuids. and of course, a complete rewrite to b…
authored
172
280ea39 @broofa Use node.js crypto api if available, code cleanup, readme edits.
authored
173 ```
174 open test/test.html
175 ```
3ab3ad6 @broofa add support for binary uuids. and of course, a complete rewrite to b…
authored
176
d966485 @broofa bug fixes, readme updates
authored
177 ### Benchmarking
d9c4bd9 @ctavan Readme update for uuid.v1()
ctavan authored
178
280ea39 @broofa Use node.js crypto api if available, code cleanup, readme edits.
authored
179 Requires node.js
3ab3ad6 @broofa add support for binary uuids. and of course, a complete rewrite to b…
authored
180
280ea39 @broofa Use node.js crypto api if available, code cleanup, readme edits.
authored
181 ```
182 npm install uuid uuid-js
183 node test/benchmark.js
184 ```
4f25f28 @broofa unroll for-loop at Cory Ondrejka's suggestion
authored
185
4838cc2 @ctavan Readme tweaks
ctavan authored
186 For a more complete discussion of node-uuid performance, please see the `benchmark/README.md` file, and the [benchmark wiki](https://github.com/broofa/node-uuid/wiki/Benchmark)
4f25f28 @broofa unroll for-loop at Cory Ondrejka's suggestion
authored
187
280ea39 @broofa Use node.js crypto api if available, code cleanup, readme edits.
authored
188 For browser performance [checkout the JSPerf tests](http://jsperf.com/node-uuid-performance).
d966485 @broofa bug fixes, readme updates
authored
189
cebcb7f @broofa update readme
authored
190 ## Release notes
d966485 @broofa bug fixes, readme updates
authored
191
d008729 @broofa patch up docs and README, colorize console output in tests, bump vers…
authored
192 v1.3.2:
193 * Improve tests and handling of v1() options (Issue #24)
194 * Expose RNG option to allow for perf testing with different generators
d966485 @broofa bug fixes, readme updates
authored
195
d008729 @broofa patch up docs and README, colorize console output in tests, bump vers…
authored
196 v1.3:
4838cc2 @ctavan Readme tweaks
ctavan authored
197 * Support for version 1 ids, thanks to [@ctavan](https://github.com/ctavan)!
d966485 @broofa bug fixes, readme updates
authored
198 * Support for node.js crypto API
199 * De-emphasizing performance in favor of a) cryptographic quality PRNGs where available and b) more manageable code
Something went wrong with that request. Please try again.