Awesome Open Source
Awesome Open Source


Codacy Badge All Contributors

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

# 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:

Format Description Example
N 32 digits 00000000000000000000000000000000
D 32 digits separated by hyphens 00000000-0000-0000-0000-000000000000
B 32 digits separated by hyphens, enclosed in braces {00000000-0000-0000-0000-000000000000}
P 32 digits separated by hyphens, enclosed in parentheses (00000000-0000-0000-0000-000000000000)


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 =>
    _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 (with source code)

Native Node MongoDB Driver example

  • examples/ex1-mongodb.js


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

Mongoose example

  • examples/ex2-mongoose.js


     const kittySchema = new mongoose.Schema({
       _id: {
         type: 'object',
         value: { type: 'Buffer' },
         default: () => MUUID.v1(),
       title: String,
  • examples/ex3-mongoose.js


     // 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
       .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
Carmine DiMascio

Benjamin Dobell
Benjamin Dobell

David Pfeffer
David Pfeffer


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



Buy Me A Coffee

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
Javascript (1,533,448
Nodejs (55,199
Hacktoberfest (37,963
Mongodb (14,605
Mongoose (4,238
Binary (1,004
Mongo (898
Uuid (439
Bson (114
Related Projects