Popularity
2.0
Growing
Activity
5.6
-
99
5
17

Description

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

Programming language: JavaScript
License: MIT License
Tags: Database     ODM / ORM     Mongoose     Mongodb     Uuid    
Latest version: v2.4.0

uuid-mongodb alternatives and similar modules

Based on the "ODM / ORM" category.
Alternatively, view uuid-mongodb alternatives based on common mentions on social networks and blogs.

Do you think we are missing an alternative of uuid-mongodb or a related project?

Add another 'ODM / ORM' Module

README

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](examples/ex1-mongodb.js)

    snippet:

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

Mongoose example

  • [examples/ex2-mongoose.js](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](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](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):

<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --> <!-- prettier-ignore --> Carmine DiMascio💻Benjamin Dobell💻 David Pfeffer💻

<!-- ALL-CONTRIBUTORS-LIST:END -->

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

License

[MIT](./LICENSE)


*Note that all licence references and agreements mentioned in the uuid-mongodb README section above are relevant to that project's source code only.