From ea8f6040be34f40963f76ccdfe1a7cd2cd68c6dd Mon Sep 17 00:00:00 2001 From: Valeri Karpov Date: Fri, 17 Mar 2023 11:02:29 -0400 Subject: [PATCH 1/3] docs(guide+schematypes): add UUID to schematypes guide Fix #13032 Re: #13025 --- docs/guide.md | 1 + docs/schematypes.md | 49 ++++++++++++++++++++++++++++++++++++++++++--- 2 files changed, 47 insertions(+), 3 deletions(-) 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..71c2c3c6632 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. @@ -585,13 +585,56 @@ const userSchema = new Schema({ const User = mongoose.model('User', userSchema); ``` -To populate every `socialMediaHandles` entry's `oauth` property, you should populate +To populate every `socialMediaHandles` entry's `oauth` property, you should populatex on `socialMediaHandles.$*.oauth`: ```javascript const user = await User.findOne().populate('socialMediaHandles.$*.oauth'); ``` +

UUID

+ +Mongoose also supports a UUID type that stores UUID v4 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 schema = new mongoose.Schema({ + docId: { + type: mongoose.Schema.Types.UUID // Can also do `type: 'UUID'` + } +}); +const Test = mongoose.model('Test', schema); + +const doc = await Test.create({ + docId: '09190f70-3d30-11e5-8814-0f4df9a59c41' +}); + +// 'string' +console.log(typeof doc.docId); +// true +console.log(doc.toObject().docId instanceof mongoose.mongo.BSON.Binary); + +const rawDoc = await Test.collection.findOne({ _id: doc._id }); +// true +console.log(rawDoc.toObject().docId instanceof mongoose.mongo.BSON.Binary); +``` + +To create UUIDs, we recommend using the [uuid npm package](https://www.npmjs.com/package/uuid). + +```javascript +const { v4: uuidv4 } = require('uuid'); + +const schema = new mongoose.Schema({ + docId: { + type: 'UUID', + default: () => uuidv4() + } +}); +``` +

Getters

Getters are like virtuals for paths defined in your schema. For example, From e566d0574fc495d5ad21051296ef7e9a3e92ff74 Mon Sep 17 00:00:00 2001 From: Valeri Karpov Date: Mon, 20 Mar 2023 21:30:51 -0400 Subject: [PATCH 2/3] Update docs/schematypes.md Co-authored-by: Hafez --- docs/schematypes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/schematypes.md b/docs/schematypes.md index 71c2c3c6632..90d45d36a79 100644 --- a/docs/schematypes.md +++ b/docs/schematypes.md @@ -585,7 +585,7 @@ const userSchema = new Schema({ const User = mongoose.model('User', userSchema); ``` -To populate every `socialMediaHandles` entry's `oauth` property, you should populatex +To populate every `socialMediaHandles` entry's `oauth` property, you should populate on `socialMediaHandles.$*.oauth`: ```javascript From d90c9c777297ae8e75e290c52c4173ddc12df357 Mon Sep 17 00:00:00 2001 From: Valeri Karpov Date: Tue, 21 Mar 2023 09:40:50 -0400 Subject: [PATCH 3/3] docs: address code review comments --- docs/schematypes.md | 34 ++++++++++++++++------------------ 1 file changed, 16 insertions(+), 18 deletions(-) diff --git a/docs/schematypes.md b/docs/schematypes.md index 71c2c3c6632..ba5576831fd 100644 --- a/docs/schematypes.md +++ b/docs/schematypes.md @@ -594,43 +594,41 @@ const user = await User.findOne().populate('socialMediaHandles.$*.oauth');

UUID

-Mongoose also supports a UUID type that stores UUID v4 instances as [Node.js buffers](https://thecodebarbarian.com/an-overview-of-buffers-in-node-js.html). +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 schema = new mongoose.Schema({ - docId: { - type: mongoose.Schema.Types.UUID // Can also do `type: 'UUID'` - } +const authorSchema = new Schema({ + _id: Schema.Types.UUID, // Can also do `_id: 'UUID'` + name: String }); -const Test = mongoose.model('Test', schema); -const doc = await Test.create({ - docId: '09190f70-3d30-11e5-8814-0f4df9a59c41' +const Author = mongoose.model('Author', authorSchema); + +const bookSchema = new Schema({ + authorId: { type: Schema.Types.UUID, ref: 'Author' } }); +const Book = mongoose.model('Book', bookSchema); -// 'string' -console.log(typeof doc.docId); -// true -console.log(doc.toObject().docId instanceof mongoose.mongo.BSON.Binary); +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 rawDoc = await Test.collection.findOne({ _id: doc._id }); -// true -console.log(rawDoc.toObject().docId instanceof mongoose.mongo.BSON.Binary); +const book = new Book({ authorId: '09190f70-3d30-11e5-8814-0f4df9a59c41' }); ``` -To create UUIDs, we recommend using the [uuid npm package](https://www.npmjs.com/package/uuid). +To create UUIDs, we recommend using [Node's built-in UUIDv4 generator](https://nodejs.org/api/crypto.html#cryptorandomuuidoptions). ```javascript -const { v4: uuidv4 } = require('uuid'); +const { randomUUID } = require('crypto'); const schema = new mongoose.Schema({ docId: { type: 'UUID', - default: () => uuidv4() + default: () => randomUUID() } }); ```