feat!: improve support for async/await

[bcoe]

In node@15 top level await is now supported 🎉.

This means that we can have yargs return a promise in more situations, with users writing code that looks like this:

import yargs from './index.mjs';
import { setTimeout } from 'timers/promises';

const argv = await yargs(process.argv.slice(2))
  .command(
    'foo',
    'foo commnd',
    () => {},
    async (argv) => {
      console.info('second')
      await setTimeout(1000)
    }
  )
  .middleware(async (argv) => {
    console.info('first')
    await setTimeout(1000)
    argv.value = 99
  }).argv;
console.info('third', argv)

This PR begins work to add better first class support of promises to yargs.

---

TODO:

• write unit tests for scenarios outlined in Accepting sync and async callbacks while keeping yargs functions sync-only is incoherent #1420 broke into several steps.
• add tests for async behavior of .parse() (Refs: Accepting sync and async callbacks while keeping yargs functions sync-only is incoherent #1420).
• add tests for async behavior of top level .argv (Refs: Accepting sync and async callbacks while keeping yargs functions sync-only is incoherent #1420).
• add tests for, and document `async getHelp() (Refs: Accepting sync and async callbacks while keeping yargs functions sync-only is incoherent #1420).
• add tests for async getCompletion()/completion (Refs: Accepting sync and async callbacks while keeping yargs functions sync-only is incoherent #1420, bug: custom completion with promise does trigger validation #1235).
• write unit tests for any TODO comments added during this work.
• should command builders accept a promise? see Allow command builder to accept a promise #1042 -- we will land this work separately before the next major.
• add async support to coerce/check, see Ability to do async stuff in check() and coerce() #859 -- we will land this work separately before the next major.
• make global middleware work without defining command (this work should be in separate breaking PR). broken into ticket Registered middleware should be called even if no commands are defined #1849
• add documentation for new async behavior.

BREAKING CHANGES:

• now returns a promise if handler is async.
• onFinishCommand removed, in favor of being able to await promise.
• getCompletion now invokes callback with err and `completions, returns promise of completions.

Fixes #1791, #1420, #1235

[bcoe]

For anyone who would like to try this and give feedback (which is greatly appreciated):

npm i yargs@next

[bcoe]

@mleguen @SkeLLLa @petrgrishin @dapplion this PR removes onFinishCommand in favor of a variety of work to make commands work better with promises. You can now simply await yargs when it has an async command.

I would love your feedback. You can install this version of yargs like so:

npm i yargs@next

[dapplion]

@mleguen @SkeLLLa @petrgrishin @dapplion this PR removes onFinishCommand in favor of a variety of work to make commands work better with promises. You can now simply await yargs when it has an async command.

I would love your feedback. You can install this version of yargs like so:

npm i yargs@next

The overall direction looks great! Can't wait to have this on master

[bcoe]

Add a note that this will be returned after the handler has finished.

[mdy970]

Hi

[dossy]

I was surprised and disappointed by the removal of onFinishCommand().

package.json indicates node >= 12 which should have been changed to node >= 15 if you're going to remove onFinishCommand() in yargs@17.

[jesec]

@bcoe The typing is wrong. See my comment in #2175 (comment).