patch up docs and README, colorize console output in tests, bump vers…

…ion #

README.md

@@ -48,8 +48,8 @@ Generate and return a RFC4122 v1 (timestamp-based) UUID.
 
   * `node` - (Array) Node id as Array of 6 bytes (per 4.1.6). Default: Randomnly generated ID.  See note 1.
   * `clockseq` - (Number between 0 - 0x3fff) RFC clock sequence.  Default: An internally maintained clockseq is used.
-  * `msecs` - (Number | Date) Time in milliseconds since unix Epoch.  Default: The current time is used.  See note 2.
-  * `nsecs` - (Number between 0-9999) additional time, in 100-nanosecond. Ignored if `msecs` is unspecified. Default: internal uuid counter is used, as per 4.2.1.2.
+  * `msecs` - (Number | Date) Time in milliseconds since unix Epoch.  Default: The current time is used.
+  * `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.
 
 * `buffer` - (Array | Buffer) Array or buffer where UUID bytes are to be written.
 * `offset` - (Number) Starting index in `buffer` at which to begin writing.
@@ -59,7 +59,6 @@ Returns `buffer`, if specified, otherwise the string form of the UUID
 Notes:
 
 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.)
-1. Specifying the `msecs` option bypasses the internal logic for ensuring id uniqueness.  In this case you may want to also provide `clockseq` and `nsecs` options as well.
 
 Example: Generate string UUID with fully-specified options
 
@@ -81,8 +80,8 @@ uuid.v1(null, arr, 0);   // -> [02 a2 ce 90 14 32 11 e1 85 58 0b 48 8e 4f c1 15]
 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]
 
 // Optionally use uuid.unparse() to get stringify the ids
-uuid.unparse(buffer);                 // -> '02a2ce90-1432-11e1-8558-0b488e4fc115'
-uuid.unparse(buffer, 16)              // -> '02a31cb0-1432-11e1-8558-0b488e4fc115'
+uuid.unparse(buffer);    // -> '02a2ce90-1432-11e1-8558-0b488e4fc115'
+uuid.unparse(buffer, 16) // -> '02a31cb0-1432-11e1-8558-0b488e4fc115'
 ```
 
 ### uuid.v4([`options` [, `buffer` [, `offset`]]])
@@ -92,7 +91,7 @@ Generate and return a RFC4122 v4 UUID.
 * `options` - (Object) Optional uuid state to apply. Properties may include:
 
   * `random` - (Number[16]) Array of 16 numbers (0-255) to use in place of randomly generated values
-  * `rng` - (Function) Random # generator to use.  Options include `uuid.mathRNG` (all platforms), `uuid.nodeRNG` (node.js only), and `uuid.whatwgRNG` (WebKit browsers only),
+  * `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.
 
 * `buffer` - (Array | Buffer) Array or buffer where UUID bytes are to be written.
 * `offset` - (Number) Starting index in `buffer` at which to begin writing.
@@ -190,8 +189,11 @@ For browser performance [checkout the JSPerf tests](http://jsperf.com/node-uuid-
 
 ## Release notes
 
-v1.3: Includes
+v1.3.2:
+* Improve tests and handling of v1() options (Issue #24)
+* Expose RNG option to allow for perf testing with different generators
 
+v1.3:
 * Support for version 1 ids, thanks to [@ctavan](https://github.com/ctavan)!
 * Support for node.js crypto API
 * De-emphasizing performance in favor of a) cryptographic quality PRNGs where available and b) more manageable code

package.json

@@ -10,5 +10,5 @@
   "dependencies"  : [],
   "lib"           : ".",
   "main"          : "./uuid.js",
-  "version"       : "1.3.1"
+  "version"       : "1.3.2"
 }

test/test.js

@@ -14,7 +14,12 @@ function _log(msg, type) {
     document.write('<div class="' + type + '">' + msg.replace(/\n/g, '<br />') + '</div>');
   }
   if (typeof(console) != 'undefined') {
-    console[type](msg);
+    var color = {
+      log: '\033[30m',
+      warn: '\033[33m',
+      error: '\033[31m'
+    }
+    console[type](color[type] + msg + color.log);
   }
 }
 

uuid.js

@@ -6,17 +6,13 @@
 (function() {
   var _global = this;
 
-  // Random # generation is vital for avoiding uuid collisions, but there's no
-  // silver bullet option since Math.random isn't guaranteed to be
-  // "cryptographic quality".  Instead, we feature-detect based on API
-  // availability.
-  //
-  // (Each RNG API is normalized here to return 128-bits (16 bytes) of random
-  // data)
+  // Unique ID creation requires a high quality random # generator, but
+  // Math.random() does not guarantee "cryptographic quality".  So we feature
+  // detect for more robust APIs, normalizing each method to return 128-bits
+  // (16 bytes) of random data.
   var mathRNG, nodeRNG, whatwgRNG;
 
-  // Math.random-based RNG.  All browsers, fast (~1M/sec), but not guaranteed
-  // to be cryptographic quality.
+  // Math.random()-based RNG.  All platforms, very fast, unknown quality
   var _rndBytes = new Array(16);
   mathRNG = function() {
     var r, b = _rndBytes, i = 0;
@@ -29,9 +25,8 @@
     return b;
   }
 
-  // WHATWG crypto-based RNG (http://wiki.whatwg.org/wiki/Crypto).  Currently
-  // only in WebKit browsers, moderately fast (~100K/sec), guaranteed
-  // cryptographic quality
+  // WHATWG crypto-based RNG - http://wiki.whatwg.org/wiki/Crypto
+  // WebKit only (currently), moderately fast, high quality
   if (_global.crypto && crypto.getRandomValues) {
     var _rnds = new Uint32Array(4);
     whatwgRNG = function() {
@@ -44,17 +39,16 @@
     }
   }
 
-  // Node.js crypto-based RNG
-  // (http://nodejs.org/docs/v0.6.2/api/crypto.html#randomBytes).
-  // node.js only, slow (~10K/sec), guaranteed cryptographic quality
+  // Node.js crypto-based RNG - http://nodejs.org/docs/v0.6.2/api/crypto.html
+  // Node.js only, moderately fast, high quality
   try {
     var _rb = require('crypto').randomBytes;
     nodeRNG = function() {
       return _rb(16);
     };
   } catch (e) {}
 
-  // Pick the RNG to use, preferring quality over speed
+  // Select RNG with best quality
   var _rng = nodeRNG || whatwgRNG || mathRNG;
 
   // Buffer class to use
@@ -130,8 +124,8 @@
     var clockseq = options.clockseq != null ? options.clockseq : _clockseq;
 
     // UUID timestamps are 100 nano-second units since the Gregorian epoch,
-    // 1582-10-15 00:00.  JSNumbers aren't precise enough for this, so time is
-    // represented here as 'msecs' (integer milliseconds) and 'nsecs'
+    // (1582-10-15 00:00).  JSNumbers aren't precise enough for this, so
+    // time is handled internally as 'msecs' (integer milliseconds) and 'nsecs'
     // (100-nanoseconds offset from msecs) since unix epoch, 1970-01-01 00:00.
     var msecs = options.msecs != null ? options.msecs : new Date().getTime();
 
@@ -142,20 +136,18 @@
     // Time since last uuid creation (in msecs)
     var dt = (msecs - _lastMSecs) + (nsecs - _lastNSecs)/10000;
 
-    // Per 4.2.1.2, Bump clockseq on clock regression (but only if clockseq
-    // isn't specified as an option)
+    // Per 4.2.1.2, Bump clockseq on clock regression
     if (dt < 0 && options.clockseq == null) {
       clockseq = clockseq + 1 & 0x3fff;
     }
 
     // Reset nsecs if clock regresses (new clockseq) or we've moved onto a new
-    // time interval (but only if nsecs isn't specified as an option)
+    // time interval
     if ((dt < 0 || msecs > _lastMSecs) && options.nsecs == null) {
       nsecs = 0;
     }
 
-    // Per 4.2.1.2 If generator creates more than one uuid per 100-ns
-    // interval, throw an error
+    // Per 4.2.1.2 Throw error if too many uuids are requested
     if (nsecs >= 10000) {
       throw new Error('uuid.v1(): Can\'t create more than 10M uuids/sec');
     }