Merge branch 'master' into legacy-object-proto-accessors

.github/workflows/ci.yaml

@@ -10,7 +10,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node: [10, 12, 13, 14]
+        node: [12, 14, 16]
     steps:
       - uses: actions/checkout@v1
       - uses: actions/setup-node@v1
@@ -50,7 +50,7 @@ jobs:
           node-version: 14
       - run: npm install
       - run: npm run compile
-      - uses: denolib/setup-deno@v2
+      - uses: denoland/setup-deno@v1
         with:
           deno-version: v1.x
       - run: |

CHANGELOG.md

@@ -2,6 +2,92 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [17.1.1](https://www.github.com/yargs/yargs/compare/v17.1.0...v17.1.1) (2021-08-13)
+
+
+### Bug Fixes
+
+* positional array defaults should not be combined with provided values ([#2006](https://www.github.com/yargs/yargs/issues/2006)) ([832222d](https://www.github.com/yargs/yargs/commit/832222d7777da49e5c9da6c5801c2dd90d7fa6a2))
+
+## [17.1.0](https://www.github.com/yargs/yargs/compare/v17.0.1...v17.1.0) (2021-08-04)
+
+
+### Features
+
+* update Levenshtein to Damerau-Levenshtein ([#1973](https://www.github.com/yargs/yargs/issues/1973)) ([d2c121b](https://www.github.com/yargs/yargs/commit/d2c121b00f2e1eb2ea8cc3a23a5039b3a4425bea))
+
+
+### Bug Fixes
+
+* coerce middleware should be applied once ([#1978](https://www.github.com/yargs/yargs/issues/1978)) ([14bd6be](https://www.github.com/yargs/yargs/commit/14bd6bebc3027ae929106b20dd198b9dccdeec31))
+* implies should not fail when implied key's value is 0, false or empty string ([#1985](https://www.github.com/yargs/yargs/issues/1985)) ([8010472](https://www.github.com/yargs/yargs/commit/80104727d5f2ec4c5b491c1bdec4c94b2db95d9c))
+* positionals should not overwrite options ([#1992](https://www.github.com/yargs/yargs/issues/1992)) ([9d84309](https://www.github.com/yargs/yargs/commit/9d84309e53ce1d30b1c61035ed5c78827a89df86))
+* strict should fail unknown arguments ([#1977](https://www.github.com/yargs/yargs/issues/1977)) ([c804f0d](https://www.github.com/yargs/yargs/commit/c804f0db78e56b44341cc7a91878c27b1b68b9f2))
+* wrap(null) no longer causes strange indentation behavior ([#1988](https://www.github.com/yargs/yargs/issues/1988)) ([e1871aa](https://www.github.com/yargs/yargs/commit/e1871aa792de219b221179417d410931af70d405))
+
+### [17.0.1](https://www.github.com/yargs/yargs/compare/v17.0.0...v17.0.1) (2021-05-03)
+
+
+### Bug Fixes
+
+* **build:** Node 12 is now minimum version ([#1936](https://www.github.com/yargs/yargs/issues/1936)) ([0924566](https://www.github.com/yargs/yargs/commit/09245666e57facb140e0b45a9e45ca704883e5dd))
+
+## [17.0.0](https://www.github.com/yargs/yargs/compare/v16.2.0...v17.0.0) (2021-05-02)
+
+
+### ⚠ BREAKING CHANGES
+
+* **node:** drop Node 10 (#1919)
+* implicitly private methods are now actually private
+* deprecated reset() method is now private (call yargs() instead).
+* **yargs-factory:** refactor yargs-factory to use class (#1895)
+* .positional() now allowed at root level of yargs.
+* **coerce:** coerce is now applied before validation.
+* **async:** yargs now returns a promise if async or check are asynchronous.
+* **middleware:** global middleware now applied when no command is configured.
+* #1823 contains the following breaking API 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.
+
+### Features
+
+* add commands alias (similar to options function) ([#1850](https://www.github.com/yargs/yargs/issues/1850)) ([00b74ad](https://www.github.com/yargs/yargs/commit/00b74adcb30ab89b4450ef7105ef1ad32d820ebf))
+* add parseSync/parseAsync method ([#1898](https://www.github.com/yargs/yargs/issues/1898)) ([6130ad8](https://www.github.com/yargs/yargs/commit/6130ad89b85dc49e34190e596e14a2fd3e668781))
+* add support for `showVersion`, similar to `showHelp` ([#1831](https://www.github.com/yargs/yargs/issues/1831)) ([1a1e2d5](https://www.github.com/yargs/yargs/commit/1a1e2d554dca3566bc174584394419be0120d207))
+* adds support for async builder ([#1888](https://www.github.com/yargs/yargs/issues/1888)) ([ade29b8](https://www.github.com/yargs/yargs/commit/ade29b864abecaa8c4f8dcc3493f5eb24fb73d84)), closes [#1042](https://www.github.com/yargs/yargs/issues/1042)
+* allow calling standard completion function from custom one ([#1855](https://www.github.com/yargs/yargs/issues/1855)) ([31765cb](https://www.github.com/yargs/yargs/commit/31765cbdce812ee5c16aaae70ab523a2c7e0fcec))
+* allow default completion to be referenced and modified, in custom completion ([#1878](https://www.github.com/yargs/yargs/issues/1878)) ([01619f6](https://www.github.com/yargs/yargs/commit/01619f6191a3ab16bf6b77456d4e9dfa80533907))
+* **async:** add support for async check and coerce ([#1872](https://www.github.com/yargs/yargs/issues/1872)) ([8b95f57](https://www.github.com/yargs/yargs/commit/8b95f57bb2a49b098c6bf23cea88c6f900a34f89))
+* improve support for async/await ([#1823](https://www.github.com/yargs/yargs/issues/1823)) ([169b815](https://www.github.com/yargs/yargs/commit/169b815df7ae190965f04030f28adc3ab92bb4b5))
+* **locale:** add Ukrainian locale ([#1893](https://www.github.com/yargs/yargs/issues/1893)) ([c872dfc](https://www.github.com/yargs/yargs/commit/c872dfc1d87ebaa7fcc79801f649318a16195495))
+* **middleware:** async middleware can now be used before validation. ([e0f9363](https://www.github.com/yargs/yargs/commit/e0f93636e04fa7e02a2c3b1fe465b6a14aa1f06d))
+* **middleware:** global middleware now applied when no command is configured. ([e0f9363](https://www.github.com/yargs/yargs/commit/e0f93636e04fa7e02a2c3b1fe465b6a14aa1f06d))
+* **node:** drop Node 10 ([#1919](https://www.github.com/yargs/yargs/issues/1919)) ([5edeb9e](https://www.github.com/yargs/yargs/commit/5edeb9ea17b1f0190a3590508f2e7911b5f70659))
+
+
+### Bug Fixes
+
+* always cache help message when running commands ([#1865](https://www.github.com/yargs/yargs/issues/1865)) ([d57ca77](https://www.github.com/yargs/yargs/commit/d57ca7751d533d7e0f216cd9fbf7c2b0ec98f791)), closes [#1853](https://www.github.com/yargs/yargs/issues/1853)
+* **async:** don't call parse callback until async ops complete ([#1896](https://www.github.com/yargs/yargs/issues/1896)) ([a93f5ff](https://www.github.com/yargs/yargs/commit/a93f5ff35d7c09b01e0ca93d7d855d2b26593165)), closes [#1888](https://www.github.com/yargs/yargs/issues/1888)
+* **builder:** apply default builder for showHelp/getHelp ([#1913](https://www.github.com/yargs/yargs/issues/1913)) ([395bb67](https://www.github.com/yargs/yargs/commit/395bb67749787d269cabe80ffc3133c2f6958aeb)), closes [#1912](https://www.github.com/yargs/yargs/issues/1912)
+* **builder:** nested builder is now awaited ([#1925](https://www.github.com/yargs/yargs/issues/1925)) ([b5accd6](https://www.github.com/yargs/yargs/commit/b5accd64ccbd3ffb800517fb40d0f59382515fbb))
+* **coerce:** options using coerce now displayed in help ([#1911](https://www.github.com/yargs/yargs/issues/1911)) ([d2128cc](https://www.github.com/yargs/yargs/commit/d2128cc4ffd411eed7111e6a3c561948330e4f6f)), closes [#1909](https://www.github.com/yargs/yargs/issues/1909)
+* completion script name clashing on bash ([#1903](https://www.github.com/yargs/yargs/issues/1903)) ([8f62d9a](https://www.github.com/yargs/yargs/commit/8f62d9a9e8bebf86f988c100ad3c417dc32b2471))
+* **deno:** use actual names for keys instead of inferring ([#1891](https://www.github.com/yargs/yargs/issues/1891)) ([b96ef01](https://www.github.com/yargs/yargs/commit/b96ef01b16bc5377b79d7914dd5495068037fe7b))
+* exclude positionals from default completion ([#1881](https://www.github.com/yargs/yargs/issues/1881)) ([0175677](https://www.github.com/yargs/yargs/commit/0175677b79ffe50a9c5477631288ae10120b8a32))
+* https://github.com/yargs/yargs/issues/1841#issuecomment-804770453 ([b96ef01](https://www.github.com/yargs/yargs/commit/b96ef01b16bc5377b79d7914dd5495068037fe7b))
+* showHelp() and .getHelp() now return same output for commands as --help ([#1826](https://www.github.com/yargs/yargs/issues/1826)) ([36abf26](https://www.github.com/yargs/yargs/commit/36abf26919b5a19f3adec08598539851c34b7086))
+* zsh completion is now autoloadable ([#1856](https://www.github.com/yargs/yargs/issues/1856)) ([d731f9f](https://www.github.com/yargs/yargs/commit/d731f9f9adbc11f918e918443c5bff4149fc6681))
+
+
+### Code Refactoring
+
+* **coerce:** coerce is now applied before validation. ([8b95f57](https://www.github.com/yargs/yargs/commit/8b95f57bb2a49b098c6bf23cea88c6f900a34f89))
+* deprecated reset() method is now private (call yargs() instead). ([376f892](https://www.github.com/yargs/yargs/commit/376f89242733dcd4ecb8040685c40ae1d622931d))
+* implicitly private methods are now actually private ([376f892](https://www.github.com/yargs/yargs/commit/376f89242733dcd4ecb8040685c40ae1d622931d))
+* **yargs-factory:** refactor yargs-factory to use class ([#1895](https://www.github.com/yargs/yargs/issues/1895)) ([376f892](https://www.github.com/yargs/yargs/commit/376f89242733dcd4ecb8040685c40ae1d622931d))
+
 ## [16.2.0](https://www.github.com/yargs/yargs/compare/v16.1.1...v16.2.0) (2020-12-05)
 
 

README.md

@@ -78,6 +78,8 @@ $ ./plunder.js --ships 12 --distance 98.7
 Retreat from the xupptumblers!
 ```
 
+> Note: `hideBin` is a shorthand for [`process.argv.slice(2)`](https://nodejs.org/en/knowledge/command-line/how-to-parse-command-line-arguments/). It has the benefit that it takes into account variations in some environments, e.g., [Electron](https://github.com/electron/electron/issues/4690).
+
 ### Complex Example
 
 ```javascript

docs/api.md

@@ -1,6 +1,9 @@
 Additional documentation
 ===
 
+For more details refer to the offical [API reference](https://yargs.js.org/docs/#api-reference) 
+document on the yargs.js.org website.
+
 This document is the Yargs API reference. There are more documentation files in
 [`docs` in the Yargs source tree](https://github.com/yargs/yargs/tree/master/docs):
 
@@ -11,6 +14,7 @@ This document is the Yargs API reference. There are more documentation files in
 - [Bundling](https://github.com/yargs/yargs/blob/master/docs/bundling.md)
 - [Parsing Tricks](https://github.com/yargs/yargs/blob/master/docs/tricks.md)
 
+
 API reference
 ===
 
@@ -179,7 +183,7 @@ Provide a function to coerce or transform the value(s) given on the
 command line for `key`.
 
 The coercion function should accept one argument, representing the parsed value from
-the command line (an array if multiple values are parsed for the key), and should 
+the command line (an array if multiple values are parsed for the key), and should
 return a new value or throw an error. The returned value will be used as the value for
 `key` (or one of its aliases) in `argv`.
 
@@ -245,13 +249,13 @@ Apply command modules from a directory relative to the module calling this metho
 
 `opts` is an options object (optional). The following options are valid:
 
-`recurse`: Look for command modules in all subdirectories and apply them as a flattened 
+`recurse`: Look for command modules in all subdirectories and apply them as a flattened
 (non-hierarchical) list.
 
 `extensions`: The types of files to look for when requiring command modules.
 
-`visit`: A synchronous function called for each command module encountered. Accepts 
-`commandObject`, `pathToFile`, and `filename` as arguments. Returns `commandObject` 
+`visit`: A synchronous function called for each command module encountered. Accepts
+`commandObject`, `pathToFile`, and `filename` as arguments. Returns `commandObject`
 to include the command; any falsy value to exclude/skip it.
 
 `include`: Allow list certain modules. See [`require-directory`](https://www.npmjs.com/package/require-directory) for details.

docs/typescript.md

@@ -1,3 +1,22 @@
+# Config
+
+The following examples assumes a config of the following:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2015",
+    "module": "CommonJS",
+    "strict": true,
+    "esModuleInterop": true,
+    "moduleResolution": "node"
+  },
+  "include": ["cli.ts"]
+}
+```
+
+Some of the code may be different depending on your config.
+
 # TypeScript usage examples
 
 The TypeScript definitions take into account yargs' `type` key and the presence of
@@ -7,7 +26,7 @@ The following `.options()` definition:
 
 ```typescript
 #!/usr/bin/env node
-import yargs = require('yargs/yargs');
+import yargs from 'yargs/yargs';
 
 const argv = yargs(process.argv.slice(2)).options({
   a: { type: 'boolean', default: false },
@@ -32,9 +51,60 @@ Will result in an `argv` that's typed like so:
   f: string | undefined;
   _: string[];
   $0: string;
-}
+} | Promise<{
+  [x: string]: unknown;
+  a: boolean;
+  b: string;
+  c: number | undefined;
+  d: (string | number)[] | undefined;
+  e: number;
+  f: string | undefined;
+  _: string[];
+  $0: string;
+}>
 ```
 
+As you can see it's a union of the arguments and a promise which resolves to the arguments.
+The reason for this is because in yargs, you can have commands, and those commands can be asynchronous. If they are asynchronous, the parser would resolve after the command is finished.
+
+The reason it's a union is because when you call `.argv`, yargs typing doesn't know if you have any asynchronous commands, so it just gives both of them.
+
+This might result in some errors when accessing the properties:
+
+```typescript
+const argv = yargs(process.argv.slice(2)).options({
+  a: { type: 'boolean', default: false },
+  ...
+}).argv;
+
+argv.a // => Property 'a' does not exist on type...
+```
+
+If you know your program is not using any asynchronous commands, you can simply use [`#parseSync`](https://yargs.js.org/docs/#api-reference-parsesyncargs-context-parsecallback)
+
+```typescript
+const argv = yargs(process.argv.slice(2)).options({
+  a: { type: 'boolean', default: false },
+  ...
+}).parseSync();
+
+argv.a // => No error, type: boolean
+```
+
+If you do have asynchronous commands, you will need to use `await`:
+
+```typescript
+const parser = yargs(process.argv.slice(2)).options({
+  a: { type: 'boolean', default: false },
+  ...
+});
+
+
+(async() => {
+  const argv = await parser.argv;
+  argv.a // => No error, type: boolean
+})();
+```
 
 You will likely want to define an interface for your application, describing the form that
 the parsed `argv` will take:
@@ -51,6 +121,8 @@ interface Arguments {
 }
 ```
 
+# More specific typing for choices()
+
 To improve the `choices` option typing you can also specify its types:
 
 ```typescript

lib/cjs.ts

@@ -13,10 +13,9 @@ import cjsPlatformShim from './platform-shims/cjs.js';
 
 // See https://github.com/yargs/yargs#supported-nodejs-versions for our
 // version support policy. The YARGS_MIN_NODE_VERSION is used for testing only.
-const minNodeVersion =
-  process && process.env && process.env.YARGS_MIN_NODE_VERSION
-    ? Number(process.env.YARGS_MIN_NODE_VERSION)
-    : 10;
+const minNodeVersion = process?.env?.YARGS_MIN_NODE_VERSION
+  ? Number(process.env.YARGS_MIN_NODE_VERSION)
+  : 12;
 if (process && process.version) {
   const major = Number(process.version.match(/v([^.]+)/)![1]);
   if (major < minNodeVersion) {