feat: adds support for ESM and Deno (#1708)

BREAKING CHANGE: find-up replaced with escalade; export map added (limits importable files in Node >= 12); yarser-parser@19.x.x (new decamelize/camelcase implementation).

.github/workflows/ci.yaml

@@ -16,7 +16,7 @@ jobs:
         with:
           node-version: ${{ matrix.node }}
       - run: node --version
-      - run: npm install
+      - run: npm install --engine-strict
       - run: npm test
   windows:
     runs-on: windows-latest
@@ -27,6 +27,34 @@ jobs:
           node-version: 12
       - run: npm install
       - run: npm test
+  esm:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node: [14]
+    steps:
+      - uses: actions/checkout@v1
+      - uses: actions/setup-node@v1
+        with:
+          node-version: ${{ matrix.node }}
+      - run: node --version
+      - run: npm install --engine-strict
+      - run: npm run test:esm
+  deno:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-node@v1
+        with:
+          node-version: 14
+      - run: npm install
+      - run: npm run compile
+      - uses: denolib/setup-deno@v2
+        with:
+          deno-version: v1.x
+      - run: |
+          deno --version
+          deno test --allow-read test/deno/*
   coverage:
     runs-on: ubuntu-latest
     steps:

.gitignore

@@ -6,4 +6,6 @@ node_modules/
 test.js
 coverage
 package-lock.json
+example.*
+.DS_Store
 .npmrc

CHANGELOG.md

@@ -296,125 +296,3 @@ arguments when duplicates are provided
 * dropping Node 6 which hits end of life in April 2019
 * see [yargs-parser@12.0.0 CHANGELOG](https://github.com/yargs/yargs-parser/blob/master/CHANGELOG.md#breaking-changes)
 * we now warn if the yargs stanza package.json is used.
-
-
-
-<a name="12.0.5"></a>
-## [12.0.5](https://github.com/yargs/yargs/compare/v12.0.4...v12.0.5) (2018-11-19)
-
-
-### Bug Fixes
-
-* allows camel-case, variadic arguments, and strict mode to be combined ([#1247](https://github.com/yargs/yargs/issues/1247)) ([eacc035](https://github.com/yargs/yargs/commit/eacc035))
-
-
-
-<a name="12.0.4"></a>
-## [12.0.4](https://github.com/yargs/yargs/compare/v12.0.3...v12.0.4) (2018-11-10)
-
-
-### Bug Fixes
-
-* don't load config when processing positionals ([5d0dc92](https://github.com/yargs/yargs/commit/5d0dc92))
-
-
-
-<a name="12.0.3"></a>
-## [12.0.3](https://github.com/yargs/yargs/compare/v12.0.2...v12.0.3) (2018-10-06)
-
-
-### Bug Fixes
-
-* $0 contains first arg in bundled electron apps ([#1206](https://github.com/yargs/yargs/issues/1206)) ([567820b](https://github.com/yargs/yargs/commit/567820b))
-* accept single function for middleware ([66fd6f7](https://github.com/yargs/yargs/commit/66fd6f7)), closes [#1214](https://github.com/yargs/yargs/issues/1214) [#1214](https://github.com/yargs/yargs/issues/1214)
-* hide `hidden` options from help output even if they are in a group ([#1221](https://github.com/yargs/yargs/issues/1221)) ([da54028](https://github.com/yargs/yargs/commit/da54028))
-* improve Norwegian Bokmål translations ([#1208](https://github.com/yargs/yargs/issues/1208)) ([a458fa4](https://github.com/yargs/yargs/commit/a458fa4))
-* improve Norwegian Nynorsk translations ([#1207](https://github.com/yargs/yargs/issues/1207)) ([d422eb5](https://github.com/yargs/yargs/commit/d422eb5))
-
-
-
-<a name="12.0.2"></a>
-## [12.0.2](https://github.com/yargs/yargs/compare/v12.0.1...v12.0.2) (2018-09-04)
-
-
-### Bug Fixes
-
-* middleware should work regardless of when method is called  ([664b265](https://github.com/yargs/yargs/commit/664b265)), closes [#1178](https://github.com/yargs/yargs/issues/1178)
-* translation not working when using __ with a single parameter ([#1183](https://github.com/yargs/yargs/issues/1183)) ([f449aea](https://github.com/yargs/yargs/commit/f449aea))
-* upgrade os-locale to version that addresses license issue ([#1195](https://github.com/yargs/yargs/issues/1195)) ([efc0970](https://github.com/yargs/yargs/commit/efc0970))
-
-
-
-<a name="12.0.1"></a>
-## [12.0.1](https://github.com/yargs/yargs/compare/v12.0.0...v12.0.1) (2018-06-29)
-
-
-
-<a name="12.0.0"></a>
-# [12.0.0](https://github.com/yargs/yargs/compare/v11.1.0...v12.0.0) (2018-06-26)
-
-
-### Bug Fixes
-
-* .argv and .parse() now invoke identical code path ([#1126](https://github.com/yargs/yargs/issues/1126)) ([f13ebf4](https://github.com/yargs/yargs/commit/f13ebf4))
-* remove the trailing white spaces from the help output ([#1090](https://github.com/yargs/yargs/issues/1090)) ([3f0746c](https://github.com/yargs/yargs/commit/3f0746c))
-* **completion:** Avoid default command and recommendations during completion ([#1123](https://github.com/yargs/yargs/issues/1123)) ([036e7c5](https://github.com/yargs/yargs/commit/036e7c5))
-
-
-### Chores
-
-* test Node.js 6, 8 and 10 ([#1160](https://github.com/yargs/yargs/issues/1160)) ([84f9d2b](https://github.com/yargs/yargs/commit/84f9d2b))
-* upgrade to version of yargs-parser that does not populate value for unset boolean ([#1104](https://github.com/yargs/yargs/issues/1104)) ([d4705f4](https://github.com/yargs/yargs/commit/d4705f4))
-
-
-### Features
-
-* add support for global middleware, useful for shared tasks like metrics ([#1119](https://github.com/yargs/yargs/issues/1119)) ([9d71ac7](https://github.com/yargs/yargs/commit/9d71ac7))
-* allow setting scriptName $0 ([#1143](https://github.com/yargs/yargs/issues/1143)) ([a2f2eae](https://github.com/yargs/yargs/commit/a2f2eae))
-* remove `setPlaceholderKeys` ([#1105](https://github.com/yargs/yargs/issues/1105)) ([6ee2c82](https://github.com/yargs/yargs/commit/6ee2c82))
-
-
-### BREAKING CHANGES
-
-* Options absent from `argv` (not set via CLI argument) are now absent from the parsed result object rather than being set with `undefined`
-* drop Node 4 from testing matrix, such that we'll gradually start drifting away from supporting Node 4.
-* yargs-parser does not populate 'false' when boolean flag is not passed
-* tests that assert against help output will need to be updated
-
-
-
-<a name="11.1.0"></a>
-# [11.1.0](https://github.com/yargs/yargs/compare/v11.0.0...v11.1.0) (2018-03-04)
-
-
-### Bug Fixes
-
-* choose correct config directory when require.main does not exist ([#1056](https://github.com/yargs/yargs/issues/1056)) ([a04678c](https://github.com/yargs/yargs/commit/a04678c))
-
-
-### Features
-
-* allow hidden options to be displayed with --show-hidden ([#1061](https://github.com/yargs/yargs/issues/1061)) ([ea862ae](https://github.com/yargs/yargs/commit/ea862ae))
-* extend *.rc files in addition to json ([#1080](https://github.com/yargs/yargs/issues/1080)) ([11691a6](https://github.com/yargs/yargs/commit/11691a6))
-
-
-
-<a name="11.0.0"></a>
-# [11.0.0](https://github.com/yargs/yargs/compare/v10.1.2...v11.0.0) (2018-01-22)
-
-
-### Bug Fixes
-
-* Set implicit nargs=1 when type=number requiresArg=true ([#1050](https://github.com/yargs/yargs/issues/1050)) ([2b56812](https://github.com/yargs/yargs/commit/2b56812))
-
-
-### Features
-
-* requiresArg is now simply an alias for nargs(1) ([#1054](https://github.com/yargs/yargs/issues/1054)) ([a3ddacc](https://github.com/yargs/yargs/commit/a3ddacc))
-
-
-### BREAKING CHANGES
-
-* requiresArg now has significantly different error output, matching nargs.
-
-[Historical Versions](/docs/CHANGELOG-historical.md)

README.md

@@ -8,14 +8,14 @@
 
 <br>
 
-[![Build Status][travis-image]][travis-url]
+![ci](https://github.com/yargs/yargs/workflows/ci/badge.svg)
 [![NPM version][npm-image]][npm-url]
 [![js-standard-style][standard-image]][standard-url]
 [![Coverage][coverage-image]][coverage-url]
 [![Conventional Commits][conventional-commits-image]][conventional-commits-url]
 [![Slack][slack-image]][slack-url]
 
-## Description :
+## Description
 Yargs helps you build interactive command line tools, by parsing arguments and generating an elegant user interface.
 
 It gives you:
@@ -40,7 +40,7 @@ Bleeding edge version with the most recent features:
 npm i yargs@next
 ```
 
-## Usage :
+## Usage
 
 ### Simple Example
 
@@ -88,7 +88,9 @@ require('yargs') // eslint-disable-line
 
 Run the example above with `--help` to see the help for the application.
 
-## TypeScript
+## Supported Platforms
+
+### TypeScript
 
 yargs has type definitions at [@types/yargs][type-definitions].
 
@@ -98,15 +100,50 @@ npm i @types/yargs --save-dev
 
 See usage examples in [docs](/docs/typescript.md).
 
-## Webpack
+### Deno
+
+As of `v16`, `yargs` supports [Deno](https://github.com/denoland/deno):
+
+```typescript
+import { Yargs, YargsType, Arguments } from 'https://deno.land/x/yargs/deno.ts'
+
+Yargs()
+  .command('download <files...>', 'download a list of files', (yargs: YargsType) => {
+    return yargs.positional('files', {
+      describe: 'a list of files to do something with'
+    })
+  }, (argv: Arguments) => {
+    console.info(argv)
+  })
+  .strictCommands()
+  .demandCommand(1)
+  .parse(Deno.args)
+```
+
+### ESM
+
+As of `v16`,`yargs` supports ESM imports:
+
+```js
+import { Yargs, getProcessArgvWithoutBin } from 'yargs'
+
+Yargs(getProcessArgvWithoutBin())
+  .command('curl <url>', 'fetch the contents of the URL', () => {}, (argv) => {
+    console.info(argv)
+  })
+  .demandCommand(1)
+  .argv
+```
+
+### Usage in Browser
 
-See usage examples of yargs with webpack in [docs](/docs/webpack.md).
+See examples of using yargs in the browser in [docs](/docs/browser.md).
 
-## Community :
+## Community
 
 Having problems? want to contribute? join our [community slack](http://devtoolscommunity.herokuapp.com).
 
-## Documentation :
+## Documentation
 
 ### Table of Contents
 
@@ -131,8 +168,6 @@ Libraries in this ecosystem make a best effort to track
 [Node.js' release schedule](https://nodejs.org/en/about/releases/). Here's [a
 post on why we think this is important](https://medium.com/the-node-js-collection/maintainers-should-consider-following-node-js-release-schedule-ab08ed4de71a).
 
-[travis-url]: https://travis-ci.org/yargs/yargs
-[travis-image]: https://img.shields.io/travis/yargs/yargs/master.svg
 [npm-url]: https://www.npmjs.com/package/yargs
 [npm-image]: https://img.shields.io/npm/v/yargs.svg
 [standard-image]: https://img.shields.io/badge/code%20style-standard-brightgreen.svg

browser.mjs

@@ -0,0 +1,7 @@
+// Bootstrap yargs for browser:
+import browserPlatformShim from './lib/platform-shims/browser.mjs'
+import { YargsWithShim } from './build/lib/yargs-factory.js'
+
+const Yargs = YargsWithShim(browserPlatformShim)
+
+export { Yargs }

deno.ts

@@ -0,0 +1,16 @@
+// Bootstrap yargs for Deno platform:
+import denoPlatformShim from './lib/platform-shims/deno.ts'
+import { YargsWithShim } from './build/lib/yargs-factory.js'
+import { YargsInstance as YargsType, Arguments } from './build/lib/yargs-factory.d.ts'
+
+const WrappedYargs = YargsWithShim(denoPlatformShim)
+
+function Yargs (args?: string[]): YargsType {
+  return WrappedYargs(args)
+}
+
+export {
+  Arguments,
+  Yargs,
+  YargsType
+}