When and under what conditions Document.prototype.isNew returns true?

[haosmos]

Prerequisites

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

Issue

First of all, thank you for your wonderful tool - mongoose!

What do you mean, "a new" document? Or, in other words, when and under what conditions a document is considered "new" and when it is not?

The documentation doesn't say anything about this.

[hasezoey]

From what i know, the document is considered isNew = true if it has been created but not yet saved to the database and has not been retrieved from the database initially:

// the following has "isNew = true"
const newDocNew = new SomeModel();

// after this function it has "isNew = false"
await newDocNew.save();

// the following has "isNew = true" only for some parts inside the function itself, the document returned should be "isNew = false"
const newDocCreate = await SomeMode.create();

// the following has "isNew = false"
const foundDoc = await SomeModel.findOne();

[haosmos]

From what i know, the document is considered isNew = true if it has been created but not yet saved to the database and has not been retrieved from the database initially:

// the following has "isNew = true"
const newDocNew = new SomeModel();

// after this function it has "isNew = false"
await newDocNew.save();

// the following has "isNew = true" only for some parts inside the function itself, the document returned should be "isNew = false"
const newDocCreate = await SomeMode.create();

// the following has "isNew = false"
const foundDoc = await SomeModel.findOne();

got it. Thank you! ✌️

[vkarpov15]

We should improve the docs on this. The docs for isNew saying that this flag "specifies whether the document is new" isn't very helpful.

[hubab00ba]

@vkarpov15 What do you think about adding this information to the flag docs for the cases where it's used in 'post' hook? It's already in the docs but for 'Document.prototype.$locals'

schema.pre('save', function() {
  console.log(doc.isNew) // true
  // Mongoose will set `isNew` to `false` if `save()` succeeds
});

schema.post('save', function(doc) {
  console.log(doc.isNew); // false
});

tldr I forgot about that and spent 1 hour to debug why the flag is with value 'false' on insert in 'post' hook

[vkarpov15]

We'll add a note in the docs that $isNew will be false in post('save') middleware