node-mug (Meadhbh's UUID Generator)

• Generates all RFC 4122 UUID versions: time-base, hash-based, random
• Able to use /dev/random (or any other entropy source file)
• Properly increments v1 UUID clock field if successive timestamps are the same
• Actually uses the hardware address to calculate v1 UUIDs
• Supports multiple simultaneous UUID generators

Installation

The easiest way to install this package is to use npm:

    npm install node-mug

If you want to check out the source, use the git command:

    git clone git://github.com/OhMeadhbh/node-mug.git

Usage

Initialization

After importing the node-mug package, create a UUID generator with the createInstance() function. By default, node-mug will generate version 4 (randomly generated) UUIDs.

    var mug = require( 'node-mug' );
    var UUIDGenerator;

    mug.createInstance( function ( g ) {
        UUIDGenerator = g;
    } );

Generating Random (Version 4) UUIDs

Once you have a generator, call the generate() function with a callback to generate UUIDs. The single parameter to the callback will be a UUID object that includes toString() and toURN():

    UUIDGenerator.generate( function ( uuid ) {
        console.log( uuid.toString() );
        console.log( uuid.toURN() );
     });

The generate() call will usually allocate a new buffer to hold the UUID. If you want to use a pre-allocated buffer, you can pass it as the third parameter to the generate() call. UUID buffers must be at least 16 octets.

    var uuidBuffer = new Buffer( 16 );

    V4Generator.generate( function ( uuid ) {
        console.log( uuid.toString() );
        console.log( uuid.toURN() );
     }, null, uuidBuffer );

So, putting it all together, here's a program that generates 10 random UUIDs:

    var mug = require('node-mug');

    var generatorCallback = function ( uuid ) {
        console.log( uuid.toString() );
    };

    var createCallback = function( g ) {
        for( i = 0; i < 10; i++ ) {
            g.generate( generatorCallback );
        }
    };

    mug.createInstance( createCallback );

Using an Alternate Entropy Source with Version 4 (Random) UUID Generators

By default, this package will read entropy from /dev/random. This device will block if there is insufficient entropy in the entropy pool. This is done to ensure the package is "secure by default."

Ensuring the system has sufficient entropy can be difficult in some situations. However, many developers find that the output of /dev/urandom (which does not block) is suitably unpredictable.

If you want to use a file other than /dev/random, pass an options object as the first parameter to the createInstance call:

    var mug = require('node-mug');
    var V4Generator;

    mug.createInstance( {source: '/dev/urandom', version: mug.RANDOM}, function ( g ) {
        V4Generator = g;
    } );

Note that the version element of the options object is optional. The createInstance() function creates a RANDOM uuid generator by default. Still, it is good practice to explicitly set this option as defaults may change in the future and it better expresses the programmer's intent.

Creating Version 3 or 5 (Name Based) UUID Generators

To create a generator that generates name based uuids, pass in an options object with a version element set to mug.MD5 or mug.SHA1:

    //This creates a MD5 name based uuid generator
    var mug = require( 'node-mug' );
    var V3Generator;
    
    function V3createCallback ( g ) {
        V3Generator = g;
    };
    
    mug.createInstance( {version: mug.MD5}, V3createCallback );

And here's an example of creating a SHA1 name based UUID generator:

    //This creates a SHA1 name based uuid generator
    var mug = require( 'node-mug' );
    var V5Generator;
    
    function V5createCallback ( g ) {
        V5Generator = g;
    };
    
    mug.createInstance( {version: mug.SHA1}, V5createCallback );

Generating Name Based (Version 3 or 5) UUIDs

Generating name based UUIDs is similar to creating random UUIDs. The primary difference is you add a "name" parameter to the generate() call. The name is hashed and used to generate the UUID.

This example will output two SHA1 name-based UUIDs. The second call uses a pre-allocated buffer:

    var mug = require('node-mug');
    var uuidBuffer = new Buffer( 16 );
    
    function generatorCallback ( uuid ) {
        console.log( uuid.toString() );
    }
    
    function createCallback ( generator ) {
        generator.generate( generatorCallback, "example 1" );
        generator.generate( generatorCallback, "example 2", uuidBuffer );
    }
    
    mug.createInstance( {version: mug.MD5}, createCallback );

Creating a Version 1 (Time & MAC Address Based) UUID Generator

To create a generator that generates time based uuids, pass in an options object with a version element set to mug.TIME:

    //This creates a time name based uuid generator
    var mug = require( 'node-mug' );
    var V1Generator;
    
    function V1createCallback ( g ) {
        V1Generator = g;
    };
    
    mug.createInstance( {version: mug.TIME}, V1createCallback );

Generating Time Based (Version 1) UUIDs

Generating time based UUIDs uses the same pattern as random or name-based UUIDs. After creating the generator, call the generator() function passing in a callback function; the newly generated UUID will be passed as a parameter to the callback.

This example will output three time-based UUIDs.

    var mug = require('node-mug');
    
    function generatorCallback ( uuid ) {
        console.log( uuid.toString() );
    }
    
    function createCallback ( generator ) {
        generator.generate( generatorCallback );
        generator.generate( generatorCallback );
        generator.generate( generatorCallback );
    }
    
    mug.createInstance( {version: mug.TIME}, createCallback );

The NullUUID Object

A special UUID object representing the null UUID is exported by the node-mug package as NullUUID. The following example demonstrates its use:

    var mug = require('node-mug');

    console.log( mug.NullUUID.toString() );

Cleaning Up

You SHOULD call the close() function on UUID generator objects when you're done with them:

    V4Generator.close();

Testing

There is an expresso-based test and a non expresso based test. Before running either, cd into the test directory. For the expresso test, use the command:

    expresso testMug.js

For the non-expresso test, use this command:

    node test/nonExpressoTest.js