docs(defaults): clarify that setDefaultsOnInsert is true by defau…

…lt in 6.x Fix #10643
Automattic · Sep 1, 2021 · bb7c021 · bb7c021
1 parent 36d23ce
commit bb7c021
Show file tree

Hide file tree

Showing 2 changed files with 23 additions and 19 deletions.
diff --git a/docs/defaults.md b/docs/defaults.md
@@ -23,20 +23,17 @@ execute that function and use the return value as the default.
 
 ### The `setDefaultsOnInsert` Option
 
-By default, mongoose only applies defaults when you create a new document.
-It will **not** set defaults if you use `update()` and
-`findOneAndUpdate()`. However, mongoose 4.x lets you opt-in to this
-behavior using the `setDefaultsOnInsert` option.
+Mongoose also sets defaults on `update()` and `findOneAndUpdate()` when the `upsert` option is set by adding your schema's defaults to a [MongoDB `$setOnInsert` operator](https://docs.mongodb.org/manual/reference/operator/update/setOnInsert/).
+You can disable this behavior by setting the `setDefaultsOnInsert` option to `false`.
 
-#### Important
+```javascript
+[require:The `setDefaultsOnInsert` option]
+```
 
-The `setDefaultsOnInsert` option relies on the
-[MongoDB `$setOnInsert` operator](https://docs.mongodb.org/manual/reference/operator/update/setOnInsert/).
-The `$setOnInsert` operator was introduced in MongoDB 2.4. If you're
-using MongoDB server < 2.4.0, do **not** use `setDefaultsOnInsert`.
+You can also set `setDefaultsOnInsert` to `false` globally:
 
 ```javascript
-[require:The `setDefaultsOnInsert` option]
+mongoose.set('setDefaultsOnInsert', false);`
 ```
 
 ### Default functions and `this`

diff --git a/test/docs/defaults.test.js b/test/docs/defaults.test.js
@@ -89,7 +89,7 @@ describe('defaults docs', function() {
    * inserted, not if the upsert updated an existing document.
    *
    */
-  it('The `setDefaultsOnInsert` option', function() {
+  it('The `setDefaultsOnInsert` option', async function() {
     const schema = new Schema({
       title: String,
       genre: { type: String, default: 'Action' }
@@ -106,14 +106,21 @@ describe('defaults docs', function() {
       upsert: true
     };
 
-    return Movie.findOneAndUpdate(query, update, options).then(doc => {
-      doc.genre; // 'Action', Mongoose set a default value.
-      // acquit:ignore:start
-      assert.equal(doc.title, 'The Terminator');
-      assert.equal(doc.genre, 'Action');
-      // acquit:ignore:end
-      return doc;
-    });
+    let doc = await Movie.findOneAndUpdate(query, update, options).lean();
+    doc.genre; // 'Action', Mongoose set a default value.
+    // acquit:ignore:start
+    assert.equal(doc.title, 'The Terminator');
+    assert.equal(doc.genre, 'Action');
+    // acquit:ignore:end
+
+    await Movie.deleteMany({});
+
+    doc = await Movie.findOneAndUpdate(query, update, { ...options, setDefaultsOnInsert: false }).lean();
+    doc.genre; // undefined, Mongoose did not set a default value
+    // acquit:ignore:start
+    assert.equal(doc.title, 'The Terminator');
+    assert.equal(doc.genre, void 0);
+    // acquit:ignore:end
   });
 
   /**