diff --git a/docs/guides.md b/docs/guides.md index ba4d6bbf2d4..d9072c39542 100644 --- a/docs/guides.md +++ b/docs/guides.md @@ -33,6 +33,7 @@ integrating Mongoose with external tools and frameworks. ### Integrations * [Promises](/docs/promises.html) +* [Lodash](/docs/lodash.html) * [AWS Lambda](/docs/lambda.html) * [Browser Library](/docs/browser.html) * [GeoJSON](/docs/geojson.html) diff --git a/docs/lodash.md b/docs/lodash.md new file mode 100644 index 00000000000..9dad5b4ee51 --- /dev/null +++ b/docs/lodash.md @@ -0,0 +1,39 @@ +# Using Mongoose with Lodash + +For the most part, Mongoose works well with [Lodash](https://lodash.com/). +However, there are a few caveats that you should know about. + +* [`cloneDeep()`](#clonedeep) + +## `cloneDeep()` + +You should not use [Lodash's `cloneDeep()` function](https://lodash.com/docs/4.17.15#cloneDeep) on any Mongoose objects. +This includes [connections](./connections.html), [model classes](./models.html), and [queries](./queries.html), but is _especially_ important for [documents](./documents.html). +For example, you may be tempted to do the following: + +```javascript +const _ = require('lodash'); + +const doc = await MyModel.findOne(); + +const newDoc = _.cloneDeep(doc); +newDoc.myProperty = 'test'; +await newDoc.save(); +``` + +However, the above code will throw the following error if `MyModel` has any array properties. + +```no-highlight +TypeError: this.__parentArray.$path is not a function +``` + +This is because Lodash's `cloneDeep()` function doesn't [handle proxies](https://stackoverflow.com/questions/50663784/lodash-clonedeep-remove-proxy-from-object), and [Mongoose arrays are proxies as of Mongoose 6](https://thecodebarbarian.com/introducing-mongoose-6.html#arrays-as-proxies). +You typically don't have to deep clone Mongoose documents, but, if you have to, use the following alternative to `cloneDeep()`: + +```javascript +const doc = await MyModel.findOne(); + +const newDoc = new MyModel().init(doc.toObject()); +newDoc.myProperty = 'test'; +await newDoc.save(); +``` \ No newline at end of file diff --git a/docs/source/index.js b/docs/source/index.js index 5f3a059950d..78a79ea55d7 100644 --- a/docs/source/index.js +++ b/docs/source/index.js @@ -62,6 +62,7 @@ exports['docs/jobs.pug'] = { jobs }; exports['docs/change-streams.md'] = { title: 'MongoDB Change Streams in NodeJS with Mongoose', markdown: true }; +exports['docs/lodash.md'] = { title: 'Using Mongoose with Lodash', markdown: true }; for (const props of Object.values(exports)) { props.jobs = jobs;