Generates and parses BSON UUIDs for use with MongoDB. BSON UUIDs provide better performance than their string counterparts.

Inspired by @srcagency's mongo-uuid

npm install uuid-mongodb

const MUUID = require('uuid-mongodb'); // Create a v1 binary UUID const mUUID1 = MUUID.v1(); // Create a v4 binary UUID const mUUID4 = MUUID.v4(); // Print a string representation of a binary UUID mUUID1.toString() // Create a binary UUID from a valid uuid string const mUUID2 = MUUID.from('393967e0-8de1-11e8-9eb6-529269fb1459') // Create a binary UUID from a MongoDb Binary // This is useful to get MUUIDs helpful toString() method const mUUID3 = MUUID.from(/** MongoDb Binary of SUBTYPE_UUID */)

UUIDs may be formatted using the following options:

example:

const mUUID4 = MUUID.v4(); mUUID1.toString(); // equivalent to `D` separated by hyphens mUUID1.toString('P'); // enclosed in parens, separated by hypens mUUID1.toString('B'); // enclosed in braces, separated by hyphens mUUID1.toString('N'); // 32 digits

uuid-mongodb offers two modes:

• canonical (default) - A string format that emphasizes type preservation at the expense of readability and interoperability.
• relaxed - A string format that emphasizes readability and interoperability at the expense of type preservation.

The mode is set globally as such:

const mUUID = MUUID.mode('relaxed'); // use relaxed mode

Mode only impacts how JSON.stringify(...) represents a UUID:

e.g. JSON.stringy(mUUID.v1()) outputs the following:

"DEol4JenEeqVKusA+dzMMA==" // when in 'canonical' mode "1ac34980-97a7-11ea-8bab-b5327b548666" // when in 'relaxed' mode

Query using binary UUIDs

const uuid = MUUID.from('393967e0-8de1-11e8-9eb6-529269fb1459'); return collection.then(c => c.findOne({ _id: uuid, }) );

Work with binary UUIDs returned in query results

return collection .then(c => c.findOne({ _id: uuid })) .then(doc => { const uuid = MUUID.from(doc._id).toString(); // do stuff });

• examples/ex1-mongodb.js

  snippet:

   const insertResult = await collection.insertOne({ _id: MUUID.v1(), name: 'carmine', });

• examples/ex2-mongoose.js

  snippet:

   const kittySchema = new mongoose.Schema({ _id: { type: 'object', value: { type: 'Buffer' }, default: () => MUUID.v1(), }, title: String, });

• examples/ex3-mongoose.js

  snippet:

   // Define a simple schema const kittySchema = new mongoose.Schema({ _id: { type: 'object', value: { type: 'Buffer' }, default: () => MUUID.v1(), }, title: String, }); // no need for auto getter for _id will add a virtual later kittySchema.set('id', false); // virtual getter for custom _id kittySchema .virtual('id') .get(function() { return MUUID.from(this._id).toString(); }) .set(function(val) { this._id = MUUID.from(val); });

• examples/ex4-mongoose.js

 const uuid = MUUID.v4(); // save record and wait for it to commit await new Data({ uuid }).save(); // retrieve the record const result = await Data.findOne({ uuid });

Currently supports UUID v1 and v4

Thanks goes to these wonderful people (emoji key):

Carmine DiMascio 💻

Benjamin Dobell 💻

David Pfeffer 💻

This project follows the all-contributors specification. Contributions of any kind welcome!

MIT