feat: tweaks to API surface based on user feedback (#1726)

BREAKING CHANGE: tweaks to ESM/Deno API surface: now exports yargs function by default; getProcessArgvWithoutBin becomes hidBin; types now exported for Deno.

README.md

@@ -105,9 +105,10 @@ See usage examples in [docs](/docs/typescript.md).
 As of `v16`, `yargs` supports [Deno](https://github.com/denoland/deno):
 
 ```typescript
-import { Yargs, YargsType, Arguments } from 'https://deno.land/x/yargs/deno.ts'
+import yargs from 'https://deno.land/x/yargs/deno.ts'
+import { Arguments, YargsType } from 'https://deno.land/x/yargs/types.ts'
 
-Yargs()
+yargs()
   .command('download <files...>', 'download a list of files', (yargs: YargsType) => {
     return yargs.positional('files', {
       describe: 'a list of files to do something with'
@@ -125,9 +126,10 @@ Yargs()
 As of `v16`,`yargs` supports ESM imports:
 
 ```js
-import { Yargs, getProcessArgvWithoutBin } from 'yargs'
+import yargs from 'yargs'
+import { hideBin } from 'yargs/helpers'
 
-Yargs(getProcessArgvWithoutBin())
+yargs(hideBin(process.argv))
   .command('curl <url>', 'fetch the contents of the URL', () => {}, (argv) => {
     console.info(argv)
   })

browser.mjs

@@ -4,4 +4,4 @@ import { YargsWithShim } from './build/lib/yargs-factory.js'
 
 const Yargs = YargsWithShim(browserPlatformShim)
 
-export { Yargs }
+export default Yargs

deno.ts

@@ -1,16 +1,12 @@
 // 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'
+import { YargsInstance as YargsType } from './build/lib/yargs-factory.d.ts'
 
 const WrappedYargs = YargsWithShim(denoPlatformShim)
 
 function Yargs (args?: string[]): YargsType {
   return WrappedYargs(args)
 }
 
-export {
-  Arguments,
-  Yargs,
-  YargsType
-}
+export default Yargs

docs/browser.md

@@ -6,7 +6,7 @@ the browser:
 
 ```html
 <script type="module">
-  import { Yargs } from 'https://unpkg.com/yargs@16.0.0-alpha.3/browser.mjs';
+  import Yargs from 'https://unpkg.com/yargs@16.0.0-beta.1/browser.mjs';
   const yargs = Yargs()
     .scriptName('>')
     .command('clear', 'clear the output window', () => {}, () => {

example/yargs.html

@@ -17,7 +17,7 @@
     <input type="text" placeholder=">" id="input" autocomplete="off" />
     <script type="module">
       // Import the ESM version of the yargs module:
-      import { Yargs } from 'https://unpkg.com/yargs@16.0.0-alpha.3/browser.mjs';
+      import Yargs from 'https://unpkg.com/yargs@16.0.0-beta.1/browser.mjs';
       const yargs = Yargs()
         .scriptName('>')
         .command('clear', 'clear the output window', () => {}, () => {

helpers.mjs

@@ -0,0 +1 @@
+export { hideBin } from './build/lib/utils/process-argv.js'

index.cjs

@@ -4,7 +4,7 @@
 // require('yargs/yargs')(process.argv.slice(2))
 const Yargs = require('./build/index.cjs')
 
-Argv(Yargs.processArgv.getProcessArgvWithoutBin())
+Argv(Yargs.processArgv.hideBin(process.argv))
 
 module.exports = Argv
 

index.mjs

@@ -2,12 +2,7 @@
 
 // Bootstraps yargs for ESM:
 import esmPlatformShim from './lib/platform-shims/esm.mjs'
-import { getProcessArgvWithoutBin } from './build/lib/utils/process-argv.js'
 import { YargsWithShim } from './build/lib/yargs-factory.js'
 
 const Yargs = YargsWithShim(esmPlatformShim)
-
-export {
-  getProcessArgvWithoutBin,
-  Yargs,
-}
+export default Yargs

lib/utils/process-argv.ts

@@ -20,8 +20,8 @@ function isElectronApp () {
   return !!(process as ElectronProcess).versions.electron
 }
 
-export function getProcessArgvWithoutBin () {
-  return process.argv.slice(getProcessArgvBinIndex() + 1)
+export function hideBin (argv: string[]) {
+  return argv.slice(getProcessArgvBinIndex() + 1)
 }
 
 export function getProcessArgvBin () {

package.json

@@ -8,6 +8,9 @@
       "import": "./index.mjs",
       "require": "./index.cjs"
     },
+    "./helpers": {
+      "import": "./helpers.mjs"
+    },
     "./yargs": {
       "require": "./build/index.cjs"
     }
@@ -23,6 +26,7 @@
   "files": [
     "browser.mjs",
     "index.cjs",
+    "helpers.mjs",
     "index.mjs",
     "build",
     "locales",
@@ -37,7 +41,7 @@
     "require-directory": "^2.1.1",
     "string-width": "^4.2.0",
     "y18n": "^4.0.0",
-    "yargs-parser": "^19.0.1"
+    "yargs-parser": "^19.0.4"
   },
   "devDependencies": {
     "@types/chai": "^4.2.11",

test/deno/yargs.test.ts

@@ -3,11 +3,12 @@
 import {
   assertMatch
 } from 'https://deno.land/std/testing/asserts.ts'
-import { Yargs, Arguments } from '../../deno.ts'
+import yargs from '../../deno.ts'
+import { Arguments } from '../../types.ts'
 
 Deno.test('demandCommand(1) throw error if no command provided', () => {
   let err: Error|null = null
-  Yargs()
+  yargs()
     .demandCommand(1)
     .parse(Deno.args, (_err: Error) => {
       err = _err
@@ -18,7 +19,7 @@ Deno.test('demandCommand(1) throw error if no command provided', () => {
 // TODO: we should think of a way to support this functionality
 Deno.test('guesses version # based on package.json', () => {
   let output: string|null = null
-  Yargs()
+  yargs()
     .parse('--version', (_err: Error, argv: Arguments, _output: string) => {
       output = _output
     })

test/esm/yargs-test.mjs

@@ -1,30 +1,30 @@
 /* global describe, it */
 
 import * as assert from 'assert'
-import { Yargs, getProcessArgvWithoutBin } from '../../index.mjs'
+import yargs from '../../index.mjs'
+import { hideBin } from '../../helpers.mjs'
 
 describe('ESM', () => {
   describe('parser', () => {
     it('parses process.argv by default', () => {
-      const parsed = Yargs(['--goodnight', 'moon']).parse()
+      const parsed = yargs(['--goodnight', 'moon']).parse()
       assert.strictEqual(parsed.goodnight, 'moon')
     })
   })
   describe('commandDir',  () => {
     it('throws an error if commndDir() used in ESM mode', () => {
       let err;
       try {
-        Yargs().commandDir('./')
+        yargs().commandDir('./')
       } catch (_err) {
         err = _err
       }
       assert.match(err.message, /not supported yet for ESM/)
     })
   })
-  describe('getProcessArgvWithoutBin', () => {
+  describe('hideBin', () => {
     it('hides bin for standard node.js application', () => {
-      process.argv = ['node', 'foo.js', '--apple', '--banana']
-      const args = getProcessArgvWithoutBin()
+      const args = hideBin(['node', 'foo.js', '--apple', '--banana'])
       assert.deepEqual(args, ['--apple', '--banana'])
     })
   })

types.ts

@@ -0,0 +1,7 @@
+// expose types for the benefit of Deno.
+import { YargsInstance as YargsType, Arguments } from './build/lib/yargs-factory.d.ts'
+
+export {
+  Arguments,
+  YargsType
+}