www.aleph1.co.uk Git - yaffs-website/blob - node_modules/uuid/README.md

   1 # uuid [![Build Status](https://secure.travis-ci.org/defunctzombie/node-uuid.svg?branch=master)](http://travis-ci.org/defunctzombie/node-uuid) #
   2
   3 [![browser support](https://ci.testling.com/defunctzombie/node-uuid.png)](https://ci.testling.com/defunctzombie/node-uuid)
   4
   5 Simple, fast generation of [RFC4122](http://www.ietf.org/rfc/rfc4122.txt) UUIDS.
   6
   7 Features:
   8
   9 * Generate RFC4122 version 1 or version 4 UUIDs
  10 * Runs in node.js and all browsers.
  11 * Cryptographically strong random # generation on supporting platforms
  12 * 1185 bytes minified and gzip'ed  (Want something smaller?  Check this [crazy shit](https://gist.github.com/982883) out! )
  13 * [Annotated source code](http://broofa.github.com/node-uuid/docs/uuid.html)
  14
  15 ## Getting Started
  16
  17 Install it in your browser:
  18
  19 ```html
  20 <script src="uuid.js"></script>
  21 ```
  22
  23 Or in node.js:
  24
  25 ```
  26 npm install uuid
  27 ```
  28
  29 ```javascript
  30 var uuid = require('uuid');
  31
  32 // Generate a v1 (time-based) id
  33 uuid.v1(); // -> '6c84fb90-12c4-11e1-840d-7b25c5ee775a'
  34
  35 // Generate a v4 (random) id
  36 uuid.v4(); // -> '110ec58a-a0f2-4ac4-8393-c866d813b8d1'
  37 ```
  38
  39 ## API
  40
  41 ### uuid.v1([`options` [, `buffer` [, `offset`]]])
  42
  43 Generate and return a RFC4122 v1 (timestamp-based) UUID.
  44
  45 * `options` - (Object) Optional uuid state to apply. Properties may include:
  46
  47   * `node` - (Array) Node id as Array of 6 bytes (per 4.1.6). Default: Randomly generated ID.  See note 1.
  48   * `clockseq` - (Number between 0 - 0x3fff) RFC clock sequence.  Default: An internally maintained clockseq is used.
  49   * `msecs` - (Number | Date) Time in milliseconds since unix Epoch.  Default: The current time is used.
  50   * `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.
  51
  52 * `buffer` - (Array | Buffer) Array or buffer where UUID bytes are to be written.
  53 * `offset` - (Number) Starting index in `buffer` at which to begin writing.
  54
  55 Returns `buffer`, if specified, otherwise the string form of the UUID
  56
  57 Notes:
  58
  59 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.)
  60
  61 Example: Generate string UUID with fully-specified options
  62
  63 ```javascript
  64 uuid.v1({
  65   node: [0x01, 0x23, 0x45, 0x67, 0x89, 0xab],
  66   clockseq: 0x1234,
  67   msecs: new Date('2011-11-01').getTime(),
  68   nsecs: 5678
  69 });   // -> "710b962e-041c-11e1-9234-0123456789ab"
  70 ```
  71
  72 Example: In-place generation of two binary IDs
  73
  74 ```javascript
  75 // Generate two ids in an array
  76 var arr = new Array(32); // -> []
  77 uuid.v1(null, arr, 0);   // -> [02 a2 ce 90 14 32 11 e1 85 58 0b 48 8e 4f c1 15]
  78 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]
  79
  80 // Optionally use uuid.unparse() to get stringify the ids
  81 uuid.unparse(buffer);    // -> '02a2ce90-1432-11e1-8558-0b488e4fc115'
  82 uuid.unparse(buffer, 16) // -> '02a31cb0-1432-11e1-8558-0b488e4fc115'
  83 ```
  84
  85 ### uuid.v4([`options` [, `buffer` [, `offset`]]])
  86
  87 Generate and return a RFC4122 v4 UUID.
  88
  89 * `options` - (Object) Optional uuid state to apply. Properties may include:
  90
  91   * `random` - (Number[16]) Array of 16 numbers (0-255) to use in place of randomly generated values
  92   * `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.
  93
  94 * `buffer` - (Array | Buffer) Array or buffer where UUID bytes are to be written.
  95 * `offset` - (Number) Starting index in `buffer` at which to begin writing.
  96
  97 Returns `buffer`, if specified, otherwise the string form of the UUID
  98
  99 Example: Generate string UUID with fully-specified options
 100
 101 ```javascript
 102 uuid.v4({
 103   random: [
 104     0x10, 0x91, 0x56, 0xbe, 0xc4, 0xfb, 0xc1, 0xea,
 105     0x71, 0xb4, 0xef, 0xe1, 0x67, 0x1c, 0x58, 0x36
 106   ]
 107 });
 108 // -> "109156be-c4fb-41ea-b1b4-efe1671c5836"
 109 ```
 110
 111 Example: Generate two IDs in a single buffer
 112
 113 ```javascript
 114 var buffer = new Array(32); // (or 'new Buffer' in node.js)
 115 uuid.v4(null, buffer, 0);
 116 uuid.v4(null, buffer, 16);
 117 ```
 118
 119 ### uuid.parse(id[, buffer[, offset]])
 120 ### uuid.unparse(buffer[, offset])
 121
 122 Parse and unparse UUIDs
 123
 124   * `id` - (String) UUID(-like) string
 125   * `buffer` - (Array | Buffer) Array or buffer where UUID bytes are to be written. Default: A new Array or Buffer is used
 126   * `offset` - (Number) Starting index in `buffer` at which to begin writing. Default: 0
 127
 128 Example parsing and unparsing a UUID string
 129
 130 ```javascript
 131 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>
 132 var string = uuid.unparse(bytes); // -> '797ff043-11eb-11e1-80d6-510998755d10'
 133 ```
 134
 135 ### uuid.noConflict()
 136
 137 (Browsers only) Set `uuid` property back to it's previous value.
 138
 139 Returns the uuid object.
 140
 141 Example:
 142
 143 ```javascript
 144 var myUuid = uuid.noConflict();
 145 myUuid.v1(); // -> '6c84fb90-12c4-11e1-840d-7b25c5ee775a'
 146 ```
 147
 148 ## Deprecated APIs
 149
 150 Support for the following v1.2 APIs is available in v1.3, but is deprecated and will be removed in the next major version.
 151
 152 ### uuid([format [, buffer [, offset]]])
 153
 154 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).
 155
 156 ## Testing
 157
 158 In node.js
 159
 160 ```
 161 > cd test
 162 > node test.js
 163 ```
 164
 165 In Browser
 166
 167 ```
 168 open test/test.html
 169 ```
 170
 171 ### Benchmarking
 172
 173 Requires node.js
 174
 175 ```
 176 cd benchmark/
 177 npm install
 178 node benchmark.js
 179 ```
 180
 181 For a more complete discussion of uuid performance, please see the `benchmark/README.md` file, and the [benchmark wiki](https://github.com/broofa/uuid/wiki/Benchmark)
 182
 183 For browser performance [checkout the JSPerf tests](http://jsperf.com/node-uuid-performance).
 184
 185 ## Release notes
 186
 187 ### 2.0.0
 188
 189 * Removed uuid.BufferClass
 190
 191 ### 1.4.0
 192
 193 * Improved module context detection
 194 * Removed public RNG functions
 195
 196 ### 1.3.2
 197
 198 * Improve tests and handling of v1() options (Issue #24)
 199 * Expose RNG option to allow for perf testing with different generators
 200
 201 ### 1.3.0
 202
 203 * Support for version 1 ids, thanks to [@ctavan](https://github.com/ctavan)!
 204 * Support for node.js crypto API
 205 * De-emphasizing performance in favor of a) cryptographic quality PRNGs where available and b) more manageable code