Nonstick Pancake Maker

    uuid-mongodb
    TypeScript icon, indicating that this package has built-in type declarations

    2.5.1 • Public • Published

    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

    Keywords

    Install

    npm i uuid-mongodb

    DownloadsWeekly Downloads

    8,756

    Version

    2.5.1

    License

    MIT

    Unpacked Size

    14.4 MB

    Total Files

    1203

    Last publish

    Collaborators

    • cdimascio