Skip to content
πŸ“‡ Generates and parses MongoDB BSON UUIDs
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
assets add assets Jul 30, 2018
example update examples Nov 26, 2019
lib Update index.js Feb 12, 2020
test Fixed test "should throw when converting an invalid uuid" May 23, 2019
.all-contributorsrc Update .all-contributorsrc May 29, 2019
.eslintrc.json integrate linter May 25, 2019
.gitignore initial version Jul 22, 2018
.npmignore update npmignore Jul 22, 2019
.prettierrc.yaml integrate linter May 25, 2019
.travis.yml Update .travis.yml Feb 12, 2020
LICENSE Create LICENSE Jul 24, 2018 update README Nov 26, 2019
package-lock.json upgrade deps Feb 12, 2020
package.json upgrade deps Feb 12, 2020


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 */)


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

  • example/ex1-mongodb.js


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

Mongoose example

  • example/ex2-mongoose.js


     const kittySchema = new mongoose.Schema({
       _id: {
         type: 'object',
         value: { type: 'Buffer' },
         default: () => MUUID.v1(),
       title: String,
  • example/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);


Currently supports UUID v1 and v4


Thanks goes to these wonderful people (emoji key):

Carmine DiMascio
Carmine DiMascio

Benjamin Dobell
Benjamin Dobell


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



Buy Me A Coffee

You can’t perform that action at this time.