doc.parent() and doc.ownerDocument() consistency

[chumager]

Do you want to request a feature or report a bug?
feature
What is the current behavior?
doc.parent() always exists, but doc.ownerDocument() don't.

If a call doc.parent() from a root document it returns undefined.

doc.ownerDocument() isn't in the API documentation.

IMHO doc.parent() and doc.ownerDocument() should return this if is a root document, and for consistency, both functions should always exists.

If I made a plugin who needs some data from ownerDocument, I've to do things like:

const {field} = this.ownerDocument?.() || this;

And I've a lot of definitions like this.

For example in vue.js this.$root is always defined even though this is the root.

This is useful in case you want to know if it's not a subDocument:

if(this !== this.ownerDocument()){
  //some stuff
}

this consistency let you be more agnostic about the data structure.

What is the expected behavior?
First of all it would be good if those functions were in the API docs.
Second, I think it's a good idea to have the functions always defined.
And last, those functions should return this in case of a root document.

What are the versions of Node.js, Mongoose and MongoDB you are using? Note that "latest" is not a version.
mongoose: 6.0.9
node: 16.11.0
mongodb attlas: 4.4.9

[vkarpov15]

Makes sense. Right now we sometimes use if (this.ownerDocument == null) in our code to check if we're looking at a top-level document, but I can see the argument for consistency. We'll fix this.

[chumager]

IMHO besides this is a good solution for me, it could be a breaking change for developers.

I while ago, in between patches, doc.parent() disappears for root documents and I'd to change all my related code (a lot), then it changed back, and I'd to change all again.

If someone uses if (this.ownerDocument == null) it'll break his code.

[vkarpov15]

In that case maybe we move it to 6.1.0. We added parent() in a minor release, so wouldn't be too far off to use ownerDocument.