Rollback the implementation of .exists() method to be syntactically consistent (+ add similar method with correct naming)

[Thomas-lmre]

Prerequisites

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

🚀 Feature Proposal

Description

The exists method in common frameworks and implementation implies the same thing : a boolean (or promise that resolve to a boolean).

Changing the meaning of this function can be extremely misleading for everyone that will make assumptions, this change produce a breaking change (even if the value is "truthy").

Consider the snippet bellow, even if code like this may be extremely rare, its remains inconsistent syntactically :

const exists = await Model.exists({});

if (exists) {} // works
if (exists === false) {} // never trigger
if (exists === true) {} // never trigger

Proposition

I know the functionality provided by the new implementation is wanted, so bellow my proposition :

• revert the changes to this signature (as of 5.13.X version) :

prototype.exists({}): Promise<boolean>

• add a method to keep the exists functionality :

prototype.findOneId({}) : Promise<{_id: ObjectId}|null>

Motivation

Keeping code consistent, understandable for anyone, with no misleading syntax or behaviours

Someone that doesn't know mongoose, should be able to read the code and understand it without documentation.

Example

No response

edit: typo

[vkarpov15]

I disagree with this change. We did have Model.exists() return a Promise<boolean>, but we think the syntax is better if exists() returns a query to allow chaining, like Model.exists(filter).session(session). Using truthy/falsy versus === true or === false is sufficiently common in JavaScript that I don't think this causes any significant confusion.

[Thomas-lmre]

If I can defends my proposition in this last comment, my proposition allows you to continue the usage of chaining :

Model.findOneId(filter).session(session) // clearer synthax

While model.exists() keeps his consistency into doing exactly what it is intended for

I agree that it's not causing this significant confusion, but it will allows mongoose to gain functionalities with a more robust base in the future.

Please consider my proposition in futures version (like 7.XX)

Whatever your choice is, thank you for you work !

[VictorJozwicki]

I disagree with this change. We did have Model.exists() return a Promise<boolean>, but we think the syntax is better if exists() returns a query to allow chaining, like Model.exists(filter).session(session).

I must say I'm intrigued as well by this change in 6.X.

It is now a query which can be chained, but what is the usefulness of an {_id: 'foo'}, considering the name of the function ? Am I missing something ?

MyModel.exists({ answer: 42 }) is equivalent to MyModel.findOne({ answer: 42 }).select({ _id: 1 }).lean()

In the same way that estimatedDocumentCount() is a query that gives you a number, couldn't Model.exists() return a query that ultimately resolve as a boolean allowing for something more familiar and let the users requiring an _id to do the query themselves ?

A new method can be created to mimic MyModel.findOne({ answer: 42 }).select({ _id: 1 }).lean() if this is used often.

Using truthy/falsy versus === true or === false is sufficiently common in JavaScript that I don't think this causes any significant confusion.

Using TypeScript, receiving a {_id: 'foo'} from a method called .exists() is not optimal/readable as the type would not be a boolean.

[AbdelrahmanHafez]

The reason exists returns a document with an _id in it instead of boolean is because it's information that we already have, a document with _id/null is richer information than just true/false. The reason we have this information is that Model.findOne(filter).select('_id').lean() is how exists works under the hood, there are many situations where having the _id handy is useful.

I can see the argument of the naming being confusing since in SQL exists returns a boolean, and in mongoose it used to return boolean, shouldn't be a problem with TS and/or using if (documentExists) { ... } though.

Our options seem to be:

1. We can keep exists as is and accept it as part of the mongoose API.
2. Make exists return a boolean, and create an existsDoc that returns null/document with _id only.

I'm leaning towards option 1 to avoid cluttering the public API, and the current implementation can easily be converted to a boolean if needed, with the benefit of information richness.

[Thomas-lmre]

In my sense, the argument that the return is richer should not be taken into consideration, it's not what the function is intended to do to the first place. With this argument, we could go further and make the function return the entire model because it's richer. But still, it's not what the function is supposed to do.

I understand the need, and that allowing chaining is a needed feature and that you try to keep that in you last message. But please retake a look in the initial proposal : I suggest your second solution with a different name : findOneId.

-> Names exists and existsDoc when coexisting together are too similar, we can't identify what those do in a first look
-> Names exists and findOneId when coexisting together are self explicit, the first will give you access to a boolean, the second to an _id.

In conclusion, I would go with your option 2 but with a different naming for existsDoc which is ambiguous.

Edit: typos