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

   1 # uuid [![Build Status](https://secure.travis-ci.org/kelektiv/node-uuid.svg?branch=master)](http://travis-ci.org/kelektiv/node-uuid) #
   2
   3 Simple, fast generation of [RFC4122](http://www.ietf.org/rfc/rfc4122.txt) UUIDS.
   4
   5 Features:
   6
   7 * Generate RFC4122 version 1 or version 4 UUIDs
   8 * Runs in node.js and browsers
   9 * Cryptographically strong random number generation on supporting platforms
  10 * Small footprint  (Want something smaller? [Check this out](https://gist.github.com/982883)!)
  11
  12 ## Quickstart - CommonJS (Recommended)
  13
  14 ```shell
  15 npm install uuid
  16 ```
  17
  18 ```javascript
  19 // Generate a v1 UUID (time-based)
  20 const uuidV1 = require('uuid/v1');
  21 uuidV1(); // -> '6c84fb90-12c4-11e1-840d-7b25c5ee775a'
  22
  23 // Generate a v4 UUID (random)
  24 const uuidV4 = require('uuid/v4');
  25 uuidV4(); // -> '110ec58a-a0f2-4ac4-8393-c866d813b8d1'
  26 ```
  27
  28 ## Quickstart - Pre-packaged for browsers (Not recommended)
  29
  30 Browser-ready versions of this module are available via [wzrd.in](https://github.com/jfhbrook/wzrd.in).
  31
  32 ```html
  33 <script src="http://wzrd.in/standalone/uuid@latest"></script>
  34
  35 <script>
  36 uuid.v1(); // -> v1 UUID
  37 uuid.v4(); // -> v4 UUID
  38 </script>
  39 ```
  40
  41 (Note: Do not do this in production.  Just don't.  wzrd.in is a great service, but if you're deploying a "real" service you should be using a packaging tool like browserify or webpack.  If you do go this route you would be well advised to link to a specific version instead of `uuid@latest` to avoid having your code break when we roll out breaking changes.)
  42
  43
  44 ## API
  45
  46 ### uuid(...)
  47
  48 Generate a V4 uuid. See uuid.v4 documentation below.
  49
  50 ### uuid.v1([`options` [, `buffer` [, `offset`]]])
  51
  52 Generate and return a RFC4122 v1 (timestamp-based) UUID.
  53
  54 * `options` - (Object) Optional uuid state to apply. Properties may include:
  55
  56   * `node` - (Array) Node id as Array of 6 bytes (per 4.1.6). Default: Randomly generated ID.  See note 1.
  57   * `clockseq` - (Number between 0 - 0x3fff) RFC clock sequence.  Default: An internally maintained clockseq is used.
  58   * `msecs` - (Number | Date) Time in milliseconds since unix Epoch.  Default: The current time is used.
  59   * `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.
  60
  61 * `buffer` - (Array | Buffer) Array or buffer where UUID bytes are to be written.
  62 * `offset` - (Number) Starting index in `buffer` at which to begin writing.
  63
  64 Returns `buffer`, if specified, otherwise the string form of the UUID
  65
  66 Notes:
  67
  68 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.)
  69
  70 Example: Generate string UUID with fully-specified options
  71
  72 ```javascript
  73 uuid.v1({
  74   node: [0x01, 0x23, 0x45, 0x67, 0x89, 0xab],
  75   clockseq: 0x1234,
  76   msecs: new Date('2011-11-01').getTime(),
  77   nsecs: 5678
  78 });   // -> "710b962e-041c-11e1-9234-0123456789ab"
  79 ```
  80
  81 Example: In-place generation of two binary IDs
  82
  83 ```javascript
  84 // Generate two ids in an array
  85 const arr = new Array(32); // -> []
  86 uuid.v1(null, arr, 0);   // -> [02 a2 ce 90 14 32 11 e1 85 58 0b 48 8e 4f c1 15]
  87 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]
  88 ```
  89
  90 ### uuid.v4([`options` [, `buffer` [, `offset`]]])
  91
  92 Generate and return a RFC4122 v4 UUID.
  93
  94 * `options` - (Object) Optional uuid state to apply. Properties may include:
  95
  96   * `random` - (Number[16]) Array of 16 numbers (0-255) to use in place of randomly generated values
  97   * `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.
  98
  99 * `buffer` - (Array | Buffer) Array or buffer where UUID bytes are to be written.
 100 * `offset` - (Number) Starting index in `buffer` at which to begin writing.
 101
 102 Returns `buffer`, if specified, otherwise the string form of the UUID
 103
 104 Example: Generate string UUID with fully-specified options
 105
 106 ```javascript
 107 uuid.v4({
 108   random: [
 109     0x10, 0x91, 0x56, 0xbe, 0xc4, 0xfb, 0xc1, 0xea,
 110     0x71, 0xb4, 0xef, 0xe1, 0x67, 0x1c, 0x58, 0x36
 111   ]
 112 });
 113 // -> "109156be-c4fb-41ea-b1b4-efe1671c5836"
 114 ```
 115
 116 Example: Generate two IDs in a single buffer
 117
 118 ```javascript
 119 const buffer = new Array(32); // (or 'new Buffer' in node.js)
 120 uuid.v4(null, buffer, 0);
 121 uuid.v4(null, buffer, 16);
 122 ```
 123
 124 ## Testing
 125
 126 ```
 127 npm test
 128 ```
 129
 130 ## Legacy node-uuid package
 131
 132 The code for the legacy node-uuid package is available in the `node-uuid` branch.