Add async custom processing support. Add chainArgParserCalls() for configuration. Additionally await thenable implicit and default option values and thenable default argument values

docs/parsing-and-hooks.md

@@ -1,23 +1,30 @@
 # Parsing life cycle and hooks
 
-The processing starts with an array of args. Each command processes and removes the options it understands, and passes the remaining args to the next subcommand.
-The final command calls the action handler.
+The processing starts with an array of args. Each command processes and removes the options it understands, and passes the remaining args to the next subcommand. The final command calls the action handler.
 
 Starting with top-level command (program):
 
-- parse options: parse recognised options (for this command) and remove from args
-- parse env: look for environment variables (for this command)
-- process implied: set any implied option values (for this command)
-- if the first arg is a subcommand
-    - call `preSubcommand` hooks
-    - pass remaining arguments to subcommand, and process same way
+* process options for this command (includes calling or chaining provided argParsers[^1])
+  * recognised options from args
+  * options based on environment variables
+* set implied option values (for this command)
+* remove recognised options from args
+* await thenable option values if parsing with `parseAsync()`
+* if the first arg is a subcommand
+  * call or chain `preSubcommand` hooks[^1]
+  * pass remaining arguments to subcommand, and process same way
 
 Once reach final (leaf) command:
 
-- check for missing mandatory options
-- check for conflicting options
-- check for unknown options
-- process remaining args as command-arguments
-- call `preAction` hooks
-- call action handler
-- call `postAction` hooks
+* check for missing mandatory options
+* check for conflicting options
+* check for unknown options
+* process remaining args as command-arguments (includes calling or chaining provided argParsers[^1])
+* await thenable argument values if parsing with `parseAsync()`
+* if an action handler is provided
+  * call or chain `preAction` hooks[^1]
+  * call or chain action handler[^1]
+  * call or chain `postAction` hooks[^1]
+</details>
+
+[^1]: output a warning suggesting use of `parseAsync()` when parsing with `parse()` and a thenable is returned, unless `process.env.NODE_ENV === 'production'`

lib/argument.js

@@ -16,6 +16,7 @@ class Argument {
     this.description = description || '';
     this.variadic = false;
     this.parseArg = undefined;
+    this.chained = true;
     this.defaultValue = undefined;
     this.defaultValueDescription = undefined;
     this.argChoices = undefined;
@@ -89,6 +90,17 @@ class Argument {
     return this;
   }
 
+  /**
+   * When set to `true` (the default), next call to the function provided via `.argParser()` will be chained to its return value if it is thenable.
+   *
+   * @param {boolean} [chained=true]
+   * @return {Argument}
+   */
+  chainArgParserCalls(chained = true) {
+    this.chained = !!chained;
+    return this;
+  }
+
   /**
    * Only allow argument value to be one of choices.
    *