uuid-mongodb
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
-
snippet:
const insertResult = await collection.insertOne({ _id: MUUID.v1(), name: 'carmine', });
Mongoose example
-
snippet:
const kittySchema = new mongoose.Schema({ _id: { type: 'object', value: { type: 'Buffer' }, default: () => MUUID.v1(), }, title: String, });
-
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); });
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 |
 Benjamin Dobell |
 David Pfeffer |
This project follows the all-contributors specification. Contributions of any kind welcome!
49 Jan 1, 2023
5.4k Dec 31, 2022
13 Dec 23, 2021
2k Dec 30, 2022
1 Jan 4, 2022
19 Dec 25, 2022
21 Dec 25, 2022
5 Dec 13, 2022
25.2k Dec 30, 2022
9.6k Dec 28, 2022
1.4k Nov 30, 2022
570 Dec 14, 2022
494 Dec 29, 2022
35 Dec 12, 2022
1 Jan 3, 2022
2 Jul 17, 2022
2 Dec 15, 2022
6.1k Jan 9, 2023
30.1k Jan 3, 2023