diff --git a/docs/guide.md b/docs/guide.md index 64dc0d020b4..1d6a6b97fa0 100644 --- a/docs/guide.md +++ b/docs/guide.md @@ -79,6 +79,7 @@ The permitted SchemaTypes are: * [Array](schematypes.html#arrays) * [Decimal128](api/mongoose.html#mongoose_Mongoose-Decimal128) * [Map](schematypes.html#maps) +* [UUID](schematypes.html#uuid) Read more about [SchemaTypes here](schematypes.html). diff --git a/docs/schematypes.md b/docs/schematypes.md index 4564175df5d..15074d317ef 100644 --- a/docs/schematypes.md +++ b/docs/schematypes.md @@ -1,3 +1,4 @@ +

SchemaTypes

SchemaTypes handle definition of path @@ -53,6 +54,7 @@ Check out [Mongoose's plugins search](http://plugins.mongoosejs.io) to find plug - [Decimal128](api/mongoose.html#mongoose_Mongoose-Decimal128) - [Map](#maps) - [Schema](#schemas) +- [UUID](#uuid)

Example

@@ -506,8 +508,6 @@ const Empty4 = new Schema({ any: [{}] });

Maps

-_New in Mongoose 5.1.0_ - A `MongooseMap` is a subclass of [JavaScript's `Map` class](http://thecodebarbarian.com/the-80-20-guide-to-maps-in-javascript.html). In these docs, we'll use the terms 'map' and `MongooseMap` interchangeably. In Mongoose, maps are how you create a nested document with arbitrary keys. @@ -592,6 +592,47 @@ on `socialMediaHandles.$*.oauth`: const user = await User.findOne().populate('socialMediaHandles.$*.oauth'); ``` +

UUID

+ +Mongoose also supports a UUID type that stores UUID instances as [Node.js buffers](https://thecodebarbarian.com/an-overview-of-buffers-in-node-js.html). +We recommend using [ObjectIds](#objectids) rather than UUIDs for unique document ids in Mongoose, but you may use UUIDs if you need to. + +In Node.js, a UUID is represented as an instance of `bson.Binary` type with a [getter](./tutorials/getters-setters.html) that converts the binary to a string when you access it. +Mongoose stores UUIDs as [binary data with subtype 4 in MongoDB](https://www.mongodb.com/docs/manual/reference/bson-types/#binary-data). + +```javascript +const authorSchema = new Schema({ + _id: Schema.Types.UUID, // Can also do `_id: 'UUID'` + name: String +}); + +const Author = mongoose.model('Author', authorSchema); + +const bookSchema = new Schema({ + authorId: { type: Schema.Types.UUID, ref: 'Author' } +}); +const Book = mongoose.model('Book', bookSchema); + +const author = new Author({ name: 'Martin Fowler' }); +console.log(typeof author._id); // 'string' +console.log(author.toObject()._id instanceof mongoose.mongo.BSON.Binary); // true + +const book = new Book({ authorId: '09190f70-3d30-11e5-8814-0f4df9a59c41' }); +``` + +To create UUIDs, we recommend using [Node's built-in UUIDv4 generator](https://nodejs.org/api/crypto.html#cryptorandomuuidoptions). + +```javascript +const { randomUUID } = require('crypto'); + +const schema = new mongoose.Schema({ + docId: { + type: 'UUID', + default: () => randomUUID() + } +}); +``` +

Getters

Getters are like virtuals for paths defined in your schema. For example,