Example for findOneAndUpdate is confusing

[davidnewcomb]

Prerequisites

• I have written a descriptive issue title
• I have searched existing issues to ensure the bug has not already been reported

Mongoose version

8.4.1

Node.js version

22.2.0

MongoDB server version

7.0.11

Typescript version (if applicable)

No response

Description

On page: https://mongoosejs.com/docs/tutorials/findoneandupdate.html

Referring to example:

const Character = mongoose.model('Character', new mongoose.Schema({
  name: String,
  age: Number
}));

await Character.create({ name: 'Jean-Luc Picard' });

const filter = { name: 'Jean-Luc Picard' };
const update = { age: 59 };

// `doc` is the document _before_ `update` was applied
let doc = await Character.findOneAndUpdate(filter, update);
doc.name; // 'Jean-Luc Picard'
doc.age; // undefined

doc = await Character.findOne(filter);   <-----
doc.age; // 59                           <-----

The example shows that you have replaced the document and lost the name field. Can you change it to show all the data you get back. It updates and doesn't replace right?

doc = await Character.findOne(filter);
doc.age; // 59
doc.name; // 'Jean-Luc Picard'

Steps to Reproduce

Go to the web page: https://mongoosejs.com/docs/tutorials/findoneandupdate.html

Expected Behavior

Both examples of doc should show the same values.

[davidnewcomb]

And other projects/people have copied the same omission, https://masteringjs.io/tutorials/mongoose/findoneandupdate#getting-started - only they like Star Wars better ;)

[vkarpov15]

How does the following example look?

    const Character = mongoose.model('Character', new mongoose.Schema({
      name: String,
      age: Number
    }));

    const _id = new mongoose.Types.ObjectId('0'.repeat(24));
    let doc = await Character.create({ _id, name: 'Jean-Luc Picard' });
    doc; // { name: 'Jean-Luc Picard', _id: ObjectId('000000000000000000000000') }

    const filter = { name: 'Jean-Luc Picard' };
    const update = { age: 59 };

    // The result of `findOneAndUpdate()` is the document _before_ `update` was applied
    doc = await Character.findOneAndUpdate(filter, update);
    doc; // { name: 'Jean-Luc Picard', _id: ObjectId('000000000000000000000000') }

The example shows that you have replaced the document and lost the name field. Can you change it to show all the data you get back. It updates and doesn't replace right? No, findOneAndUpdate() doesn't replace, that's what findOneAndReplace() is for. This example demonstrates that findOneAndUpdate() returns the "old" document without the updates applied, so there is a name property but no age.

[davidnewcomb]

Excellent, looks great to me. Thanks for cleaning that up.