node-mug v0.9.1

node-mug (Meadhbh's UUID Generator)

This package generates RFC 4122 UUIDs, potentially collecting entropy from the /dev/random file.

node-mug now supports "name based" version 3 and 5 UUIDs. These uuids are generated by hashing a supplied "name" with MD5 or SHA1.

Installation

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

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

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.

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:

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:

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

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():

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.

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

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:

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:

Cleaning Up

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

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:

For the non-expresso test, use this command: