Async/await guide

[JulioJu]

Hi @libook @mhombach @vkarpov15

Following the issue #7461 I would propose to improve API documentation.

For instance, for https://mongoosejs.com/docs/api.html#model_Model.findOneAndUpdate

[Note: I've deleted a proposal here, because it was so bad]

Or instead as A query is not a fully-fledged promise (see https://mongoosejs.com/docs/promises.html) we could say instead:

Returns
    Query (a thenable object)

Like that a user that know what is a Promise and a thenable and what is a callback could know easy how to use this function. When I've started with Mongoose, I thought falsely « dash, mongoose API doesn't return Promise contrary to the mongodb native driver ».

It should be done for all CRUD operations, into lib/model.js and lib/query.js.

Furthermore https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/mongoose/index.d.ts should be updated accordingly. At least for this TypeScript definition file, we could say that: « findOneAndUpdate and others CRUD operations are Promises ».

What do you think about that?

[JulioJu]

Also, the example could be updated to:

A.findOneAndUpdate(conditions, update, options, callback) // returns Query and executes the request
A.findOneAndUpdate(conditions, update, options)  // returns Query (execute the request like for a Promise)
A.findOneAndUpdate(conditions, update, callback) // returns Query and executes the request
A.findOneAndUpdate(conditions, update)           // returns Query (execute the request like for a Promise)
A.findOneAndUpdate()                             // returns Query (execute the request like for a Promise)

[JulioJu]

Please check DefinitelyTyped/DefinitelyTyped#32874

In this sample, for DefinitelyTyped/DefinitelyTyped@4b0c6cd , I have marked as promise only when { RawResult: true }

But for the others, maybe DocumentQuery could inherit from PromiseConstructor ? : see https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/mongoose/index.d.ts#L1715

As it we could use async / await in TypeScript, like @mhombach @vkarpov15 you described at #7461 .

[vkarpov15]

There is some nuance that prevents us from having queries inherit from promises. See https://mongoosejs.com/docs/queries.html#queries-are-not-promises for more details. With #7398 we should be able to make queries extend from promises.

I'm not sure I like adding parentheses after queries return value. Maybe we add examples of using async/await with queries to the API docs instead?

[JulioJu]

Ok I see,

But for DefinitelyTyped/DefinitelyTyped#32874 the problem is that if Query doesn't inherit from PromiseConstructor, tslint gives errors await-promise and no-invalid-await .

If you say that it's not a good idea to say in the TypeScript definition file that Query inherits from Promises, maybe in the doc we could add a small note to say that tslint errors await-promise and no-invalid-await are false positives?

[libook]

Hi @JulioJu, thanks for your concern for my issue.

As we know, 'Queries' are not Promises but 'thenable' objects.
And the await command is not only for Promises. Actually, await command works with thenable objects.

//This will return a thenable object.
function foo(x) {
  return {
    then: function(resolve, reject) {
      setTimeout(resolve, 3000, 'The x is: ' + x);
      return this;
    }
  };
}

(async () => await foo(2))().then(console.log);//Use await to execute the thenable object.

I guess this is how Queries support await command.

So, what if this is a issue of tslint? Checking whether the object has a then method, instead of checking whether the object is a Promise.

I don't use TypeScript and tslint. So there may be something I don't know. I'll be happy if you point them out.

[JulioJu]

@libook tanks.

Maybe a better example is the following (Query is in Mongoose library, myMongooseService could be in a Service file, and the last line in a route file provider, for instance).

function Query(x) {
    return {
        then: function(resolve, reject) {
            setTimeout(resolve, 3000, 'The x is: ' + x);
            return this;
        }
    };
}

myMongooseService = async () => {
    const x = await Query(2);
    console.log('coucou', x);
    return x;
}


myMongooseService().then(m => { console.log('main', m); });

Preceding could be polyfill in es6 with the following (and it demonstrates why your affirmation is true and how it works, even if it's the worst solution):

myMongooseService = () => {
    return Promise.resolve(Query(2))
    .then(r => {
            console.log('coucou', r);
        });
};

myMongooseService().then(m => { console.log('main', m); });

Preceding could be polyfill in es5 / es3 (this sample show that Promise.resolve syntax presented above is not useful in this case, even if await syntax sugar could stay cool).

myMongooseService = () => {
    return Query(2)
    .then(r => {
            console.log('coucou', r);
        });
};

myMongooseService().then(m => { console.log('main', m); });

---

Note: your sample could be polyfill in es6 too: (and it demonstrates why your affirmation is true and how it works)

(() => {
    return Promise.resolve(foo(2));
})().then(console.log);

or simply

Promise.resolve(foo(2)).then(console.log);

or more simply (this sample show that Promise is not useful in this case, even if await syntax could stay cool)

foo(2).then(console.log);

---

The preceding samples work, because each then handler of the Promise is omitted, then handler apply to the foo(2) function, see also https://javascript.info/promise-chaining )

[JulioJu]

With further tests, tslint check check whether the object has a then method, sorry.

[JulioJu]

Therefore, for DefinitelyTyped/DefinitelyTyped#32874 all it's ok, I've tested ;-).

For the doc https://mongoosejs.com/docs/api.html I propose to comment like following: 

Returns
    Query, a thenable object

Example
A.findOneAndUpdate(conditions, update, options, callback) // returns Query and executes the request
A.findOneAndUpdate(conditions, update, options)  // returns Query
A.findOneAndUpdate(conditions, update, callback) // returns Query and executes the request
A.findOneAndUpdate(conditions, update)           // returns Query
A.findOneAndUpdate()                             // returns Query

Maybe somewhere in the doc, something like #7506 (comment) could be added to explain how and why Mongoose work with await / async. Indeed, it's difficult to understand for a newbie like me with for instance https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/await or other existing famous tutorials. In fact, about await they say only “ The await expression causes async function execution to pause until a Promise is resolved ”, they speak never about then.