Skip to content

Commit 27eec18

Browse files
author
Benjamin E. Coe
authored
feat: commandDir now works with ESM files (#2461)
1 parent f9c72a7 commit 27eec18

7 files changed

Lines changed: 87 additions & 35 deletions

File tree

‎docs/advanced.md‎

Lines changed: 33 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -252,7 +252,7 @@ This example uses [jest](https://github.com/facebook/jest) as a test runner, but
252252
.commandDir(directory, [opts])
253253
------------------------------
254254

255-
_Note: `commandDir()` does not work with Deno, see [hierarchy using index.mjs](/docs/advanced.md#esm-hierarchy) for an example of building a complex nested CLI using ESM._
255+
_Note: `commandDir()` does not work with Deno, see [hierarchy using index.mjs](/docs/advanced.md#esm-hierarchy) for an example of building a complex nested CLI using an array of modules._
256256

257257
Apply command modules from a directory relative to the module calling this method.
258258

@@ -290,11 +290,12 @@ can either move your module to a different directory or use the `exclude` or
290290

291291
- `include`: RegExp or function
292292

293-
Allow list certain modules. See [`require-directory`](https://www.npmjs.com/package/require-directory) for details.
293+
294+
Allow list certain modules. Either a regex or callback can be provided. Return `true` from the callback to load the file.
294295

295296
- `exclude`: RegExp or function
296297

297-
Block list certain modules. See [`require-directory`](https://www.npmjs.com/package/require-directory) for details.
298+
Block list certain modules. Either a regex or callback can be provided. Return `true` from the callback to skip the file.
298299

299300
### Example command hierarchy using `.commandDir()`
300301

@@ -313,16 +314,16 @@ Directory structure:
313314

314315
```
315316
myapp/
316-
├─ cli.js
317+
├─ cli.mjs
317318
└─ cmds/
318-
├─ init.js
319-
├─ remote.js
319+
├─ init.mjs
320+
├─ remote.mjs
320321
└─ remote_cmds/
321-
├─ add.js
322-
└─ prune.js
322+
├─ add.mjs
323+
└─ prune.mjs
323324
```
324325

325-
cli.js:
326+
cli.mjs:
326327

327328
```js
328329
#!/usr/bin/env node
@@ -335,60 +336,59 @@ yargs(hideBin(process.argv))
335336
.parse()
336337
```
337338

338-
cmds/init.js:
339+
cmds/init.mjs:
339340

340341
```js
341-
exports.command = 'init [dir]'
342-
exports.desc = 'Create an empty repo'
343-
exports.builder = {
342+
export const command = 'init [dir]'
343+
export const desc = 'Create an empty repo'
344+
export const builder = {
344345
dir: {
345346
default: '.'
346347
}
347348
}
348-
exports.handler = function (argv) {
349+
export function handler (argv) {
349350
console.log('init called for dir', argv.dir)
350351
}
351352
```
352353

353-
cmds/remote.js:
354+
cmds/remote.mjs:
354355

355356
```js
356-
import yargs from 'yargs';
357-
exports.command = 'remote <command>'
358-
exports.desc = 'Manage set of tracked repos'
359-
exports.builder = function (yargs) {
357+
export const command = 'remote <command>'
358+
export const desc = 'Manage set of tracked repos'
359+
export function builder (yargs) {
360360
return yargs().commandDir('remote_cmds')
361361
}
362-
exports.handler = function (argv) {}
362+
export function handler (argv) {}
363363
```
364364

365-
cmds/remote_cmds/add.js:
365+
cmds/remote_cmds/add.mjs:
366366

367367
```js
368-
exports.command = 'add <name> <url>'
369-
exports.desc = 'Add remote named <name> for repo at url <url>'
370-
exports.builder = {}
371-
exports.handler = function (argv) {
368+
export const command = 'add <name> <url>'
369+
export const desc = 'Add remote named <name> for repo at url <url>'
370+
export const builder = {}
371+
export function handler (argv) {
372372
console.log('adding remote %s at url %s', argv.name, argv.url)
373373
}
374374
```
375375

376-
cmds/remote_cmds/prune.js:
376+
cmds/remote_cmds/prune.mjs:
377377

378378
```js
379-
exports.command = 'prune <name> [names..]'
380-
exports.desc = 'Delete tracked branches gone stale for remotes'
381-
exports.builder = {}
382-
exports.handler = function (argv) {
379+
export const command = 'prune <name> [names..]'
380+
export const desc = 'Delete tracked branches gone stale for remotes'
381+
export const builder = {}
382+
export function handler (argv) {
383383
console.log('pruning remotes %s', [].concat(argv.name).concat(argv.names).join(', '))
384384
}
385385
```
386386

387387
<a name="esm-hierarchy"></a>
388388
### Example command hierarchy using index.mjs
389389

390-
To support creating a complex nested CLI when using ESM, the method
391-
`.command()` was extended to accept an array of command modules.
390+
The method
391+
`.command()` accepts an array of command modules.
392392
Rather than using `.commandDir()`, create an `index.mjs` in each command
393393
directory with a list of the commands:
394394

@@ -402,7 +402,7 @@ export const commands = [a, b];
402402

403403
This index will then be imported and registered with your CLI:
404404

405-
cli.js:
405+
cli.mjs:
406406

407407
```js
408408
#!/usr/bin/env node

‎docs/api.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -259,9 +259,9 @@ Apply command modules from a directory relative to the module calling this metho
259259
`commandObject`, `pathToFile`, and `filename` as arguments. Returns `commandObject`
260260
to include the command; any falsy value to exclude/skip it.
261261

262-
`include`: Allow list certain modules. Either a regex or callback can be provided. `true` = load the file.
262+
`include`: Allow list certain modules. Either a regex or callback can be provided. Return `true` from the callback to load the file.
263263

264-
`exclude`: Block list certain modules. Either a regex or callback can be provided. `false` = do not load the file.
264+
`exclude`: Block list certain modules. Either a regex or callback can be provided. Return `true` from the callback to skip the file.
265265

266266
<a name="command"></a>
267267
.command(cmd, desc, [builder], [handler])

‎test/command.mjs‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2452,5 +2452,29 @@ describe('Command', () => {
24522452
' --version Show version number [boolean]',
24532453
]);
24542454
});
2455+
2456+
it('allows commands files to be written as ESM modules', () => {
2457+
const r = checkOutput(() =>
2458+
yargs('remote --help')
2459+
.wrap(null)
2460+
.commandDir('fixtures/esm-command')
2461+
.parse()
2462+
);
2463+
r.exit.should.equal(true);
2464+
r.errors.length.should.equal(0);
2465+
r.logs
2466+
.join('\n')
2467+
.split(/\n+/)
2468+
.should.deep.equal([
2469+
'usage remote <command>',
2470+
'Manage set of tracked repos',
2471+
'Commands:',
2472+
' usage remote add <name> <url> Add remote named <name> for repo at url <url>',
2473+
' usage remote prune <name> [names..] Delete tracked branches gone stale for remotes',
2474+
'Options:',
2475+
' --help Show help [boolean]',
2476+
' --version Show version number [boolean]',
2477+
]);
2478+
});
24552479
});
24562480
});

‎test/fixtures/esm-command/init.mjs‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
export const command = 'init [dir]'
2+
export const desc = 'Create an empty repo'
3+
export const builder = {
4+
dir: {
5+
default: '.'
6+
}
7+
}
8+
export function handler (argv) {
9+
console.log('init called for dir', argv.dir)
10+
}
Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
export const command = 'remote <command>'
2+
export const desc = 'Manage set of tracked repos'
3+
export function builder (yargs) {
4+
return yargs.commandDir('remote_cmds')
5+
}
6+
export function handler (argv) {}
Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
export const command = 'add <name> <url>'
2+
export const desc = 'Add remote named <name> for repo at url <url>'
3+
export const builder = {}
4+
export function handler (argv) {
5+
console.log('adding remote %s at url %s', argv.name, argv.url)
6+
}
Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
export const command = 'prune <name> [names..]'
2+
export const desc = 'Delete tracked branches gone stale for remotes'
3+
export const builder = {}
4+
export function handler (argv) {
5+
console.log('pruning remotes %s', [].concat(argv.name).concat(argv.names).join(', '))
6+
}

0 commit comments

Comments
 (0)