Awesome Open Source
Awesome Open Source

uuid-mongodb

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

Install

npm install uuid-mongodb

Usage

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

Formatting

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)

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

Modes

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

Examples

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

Native Node MongoDB Driver example

  • examples/ex1-mongodb.js

    snippet:

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

Mongoose example

  • 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 });

Notes

Currently supports UUID v1 and v4

Contributors

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!

License

MIT

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