feat: expose hideBin helper for CJS

README.md

@@ -21,9 +21,22 @@ Yargs helps you build interactive command line tools, by parsing arguments and g
 It gives you:
 
 * commands and (grouped) options (`my-program.js serve --port=5000`).
-* a dynamically generated help menu based on your arguments.
+* a dynamically generated help menu based on your arguments:
 
-> <img width="400" src="https://raw.githubusercontent.com/yargs/yargs/master/screen.png">
+```bash
+mocha [spec..]
+
+Run tests with Mocha
+
+Commands
+  mocha inspect [spec..]  Run tests with Mocha                         [default]
+  mocha init <path>       create a client-side Mocha setup at <path>
+
+Rules & Behavior
+  --allow-uncaught           Allow uncaught errors to propagate        [boolean]
+  --async-only, -A           Require all tests to use a callback (async) or
+                             return a Promise                          [boolean]
+```
 
 * bash-completion shortcuts for commands and options.
 * and [tons more](/docs/api.md).
@@ -46,7 +59,9 @@ npm i yargs@next
 
 ```javascript
 #!/usr/bin/env node
-const {argv} = require('yargs')
+const yargs = require('yargs/yargs')
+const { hideBin } = require('yargs/helpers')
+const argv = yargs(hideBin(process.argv)).argv
 
 if (argv.ships > 3 && argv.distance < 53.5) {
   console.log('Plunder more riffiwobbles!')
@@ -67,7 +82,10 @@ Retreat from the xupptumblers!
 
 ```javascript
 #!/usr/bin/env node
-require('yargs') // eslint-disable-line
+const yargs = require('yargs/yargs')
+const { hideBin } = require('yargs/helpers')
+
+yargs(hideBin(process.argv))
   .command('serve [port]', 'start the server', (yargs) => {
     yargs
       .positional('port', {
@@ -108,7 +126,7 @@ As of `v16`, `yargs` supports [Deno](https://github.com/denoland/deno):
 import yargs from 'https://deno.land/x/yargs/deno.ts'
 import { Arguments, YargsType } from 'https://deno.land/x/yargs/types.ts'
 
-yargs()
+yargs(Deno.args)
   .command('download <files...>', 'download a list of files', (yargs: YargsType) => {
     return yargs.positional('files', {
       describe: 'a list of files to do something with'
@@ -118,7 +136,7 @@ yargs()
   })
   .strictCommands()
   .demandCommand(1)
-  .parse(Deno.args)
+  .argv
 ```
 
 ### ESM

docs/advanced.md

@@ -538,8 +538,10 @@ var argv = require('yargs')
 ### Using the non-singleton interface
 
 To use yargs without running as a singleton, do:
+
 ```js
 const argv = require('yargs/yargs')(process.argv.slice(2))
 ```
 
-This is especially useful when using yargs in a library, as library authors should not pollute the global state.
+We recommend using this approach by default, as the singleton interface is
+considered deprecated as of `v16`.

docs/api.md

@@ -18,25 +18,25 @@ You can run Yargs without any configuration, and it will do its
 best to parse `process.argv`:
 
 ```javascript
-require('yargs').argv
+require('yargs/yargs')(process.argv.slice(2)).argv
 ```
 
 You can also pass in the arguments yourself:
 
 ```javascript
-require('yargs')([ '-x', '1', '-y', '2' ]).argv
+require('yargs/yargs')([ '-x', '1', '-y', '2' ]).argv
 ```
 
 or use `.parse()` to do the same thing:
 
 ```javascript
-require('yargs').parse([ '-x', '1', '-y', '2' ])
+require('yargs/yargs')().parse([ '-x', '1', '-y', '2' ])
 ```
 
 Calling `.parse()` with no arguments is equivalent to calling `yargs.argv`:
 
 ```javascript
-require('yargs').parse()
+require('yargs')(process.argv.slice(2)).parse()
 ```
 
 When passing in the arguments yourself, note that Yargs expects the passed array
@@ -47,6 +47,14 @@ starts with two extra elements:`process.execPath` and the path to the JavaScript
 file being executed. So if you’re getting your arguments from `process.argv` in
 Node, pass `process.argv.slice(2)` to Yargs.
 
+_Note: yargs exposes the helper `hideBin`, handles the `process.argv.slice
+logic for you._
+
+```javascript
+const { hideBin } = require('yargs/helpers')
+const argv = yargs(hideBin(process.argv)).argv
+```
+
 The rest of these methods below come in just before the terminating `.argv` or
 terminating `.parse()`.
 

package.json

@@ -9,7 +9,8 @@
       "require": "./index.cjs"
     },
     "./helpers": {
-      "import": "./helpers.mjs"
+      "import": "./helpers.mjs",
+      "require": "./yargs"
     },
     "./yargs": {
       "require": "./yargs"

test/helpers.cjs

@@ -5,7 +5,7 @@ const assert = require('assert')
 const yargs = require('../yargs');
 const { applyExtends } = require('../yargs');
 
-const HELPER_COUNT = 2;
+const HELPER_COUNT = 3;
 
 describe('helpers', () => {
   it('does not expose additional helpers beyond blessed list', () => {
@@ -24,4 +24,10 @@ describe('helpers', () => {
       assert.strictEqual(argv.bar, 99)
     })
   })
+  describe('hideBin', () => {
+    it('exposes helper for hiding node bin', () => {
+      const argv = yargs.hideBin(['node', 'foo.js', '--hello'])
+      assert.deepStrictEqual(argv, ['--hello'])
+    })
+  })
 })

yargs

@@ -1,8 +1,9 @@
 // TODO: consolidate on using a helpers file at some point in the future, which
 // is the approach currently used to export Parser and  applyExtends for ESM:
-const {applyExtends, cjsPlatformShim, Parser, Yargs} = require('./build/index.cjs')
+const {applyExtends, cjsPlatformShim, Parser, Yargs, processArgv} = require('./build/index.cjs')
 Yargs.applyExtends = (config, cwd, mergeExtends) => {
   return applyExtends(config, cwd, mergeExtends, cjsPlatformShim)
 }
+Yargs.hideBin = processArgv.hideBin
 Yargs.Parser = Parser
 module.exports = Yargs