common-bin

Abstraction bin tool wrap yargs, to provide more convenient usage, support async / await style.

---

Install

1$ npm i common-bin

Build a bin tool for your team

You maybe need a custom xxx-bin to implement more custom features.

Now you can implement a Command sub class to do that.

Example: Write your own git command

This example will show you how to create a new my-git tool.

• Full demo: my-git

1test/fixtures/my-git
2├── bin
3│   └── my-git.js
4├── command
5│   ├── remote
6│   │   ├── add.js
7│   │   └── remove.js
8│   ├── clone.js
9│   └── remote.js
10├── index.js
11└── package.json

my-git.js

1#!/usr/bin/env node
2
3'use strict';
4
5const Command = require('..');
6new Command().start();

Main Command

Just extend Command, and use as your bin start point.

You can use this.yargs to custom yargs config, see http://yargs.js.org/docs for more detail.

1const Command = require('common-bin');
2const pkg = require('./package.json');
3
4class MainCommand extends Command {
5  constructor(rawArgv) {
6    super(rawArgv);
7    this.usage = 'Usage: my-git <command> [options]';
8
9    // load entire command directory
10    this.load(path.join(__dirname, 'command'));
11
12    // or load special command file
13    // this.add(path.join(__dirname, 'test_command.js'));
14
15    // more custom with `yargs` api, such as you can use `my-git -V`
16    this.yargs.alias('V', 'version');
17  }
18}
19
20module.exports = MainCommand;

CloneCommand

1const Command = require('common-bin');
2class CloneCommand extends Command {
3  constructor(rawArgv) {
4    super(rawArgv);
5
6    this.options = {
7      depth: {
8        type: 'number',
9        description: 'Create a shallow clone with a history truncated to the specified number of commits',
10      },
11    };
12  }
13
14  async run({ argv }) {
15    console.log('git clone %s to %s with depth %d', argv._[0], argv._[1], argv.depth);
16  }
17
18  get description() {
19    return 'Clone a repository into a new directory';
20  }
21}
22
23module.exports = CloneCommand;

Run result

1$ my-git clone gh://node-modules/common-bin dist --depth=1
2
3git clone gh://node-modules/common-bin to dist with depth 1

Concept

Command

Define the main logic of command

Method:

• async start() - start your program, only use once in your bin file.
• async run(context)
  • should implement this to provide command handler, will exec when not found sub command.
  • Support generator / async function / normal function which return promise.
  • context is { cwd, env, argv, rawArgv }
    • cwd - process.cwd()
    • env - clone env object from process.env
    • argv - argv parse result by yargs, { _: [ 'start' ], '$0': '/usr/local/bin/common-bin', baseDir: 'simple'}
    • rawArgv - the raw argv, [ "--baseDir=simple" ]
• load(fullPath) - register the entire directory to commands
• add(name, target) - register special command with command name, target could be full path of file or Class.
• alias(alias, name) - register a command with an existing command
• showHelp() - print usage message to console.
• options= - a setter, shortcut for yargs.options
• usage= - a setter, shortcut for yargs.usage

Properties:

• description - {String} a getter, only show this description when it's a sub command in help console
• helper - {Object} helper instance
• yargs - {Object} yargs instance for advanced custom usage
• options - {Object} a setter, set yargs' options
• version - {String} customize version, can be defined as a getter to support lazy load.
• parserOptions - {Object} control context parse rule.
  • execArgv - {Boolean} whether extract execArgv to context.execArgv
  • removeAlias - {Boolean} whether remove alias key from argv
  • removeCamelCase - {Boolean} whether remove camel case key from argv

You can define options by set this.options

1this.options = {
2  baseDir: {
3    alias: 'b',
4    demandOption: true,
5    description: 'the target directory',
6    coerce: str => path.resolve(process.cwd(), str),
7  },
8  depth: {
9    description: 'level to clone',
10    type: 'number',
11    default: 1,
12  },
13  size: {
14    description: 'choose a size',
15    choices: ['xs', 's', 'm', 'l', 'xl']
16  },
17};

You can define version by define this.version getter:

1get version() {
2  return 'v1.0.0';
3}

Helper

• async forkNode(modulePath, args, opt) - fork child process, wrap with promise and gracefull exit
• async spawn(cmd, args, opt) - spawn a new process, wrap with promise and gracefull exit
• async npmInstall(npmCli, name, cwd) - install node modules, wrap with promise
• async callFn(fn, args, thisArg) - call fn, support gernerator / async / normal function return promise
• unparseArgv(argv, opts) - unparse argv and change it to array style

Extend Helper

1// index.js
2const Command = require('common-bin');
3const helper = require('./helper');
4class MainCommand extends Command {
5  constructor(rawArgv) {
6    super(rawArgv);
7
8    // load sub command
9    this.load(path.join(__dirname, 'command'));
10
11    // custom helper
12    Object.assign(this.helper, helper);
13  }
14}

Advanced Usage

Single Command

Just need to provide options and run().

1const Command = require('common-bin');
2class MainCommand extends Command {
3  constructor(rawArgv) {
4    super(rawArgv);
5    this.options = {
6      baseDir: {
7        description: 'target directory',
8      },
9    };
10  }
11
12  async run(context) {
13    console.log('run default command at %s', context.argv.baseDir);
14  }
15}

Sub Command

Also support sub command such as my-git remote add <name> <url> --tags.

1// test/fixtures/my-git/command/remote.js
2class RemoteCommand extends Command {
3  constructor(rawArgv) {
4    // DO NOT forgot to pass params to super
5    super(rawArgv);
6    // load sub command for directory
7    this.load(path.join(__dirname, 'remote'));
8  }
9
10  async run({ argv }) {
11    console.log('run remote command with %j', argv._);
12  }
13
14  get description() {
15    return 'Manage set of tracked repositories';
16  }
17}
18
19// test/fixtures/my-git/command/remote/add.js
20class AddCommand extends Command {
21  constructor(rawArgv) {
22    super(rawArgv);
23
24    this.options = {
25      tags: {
26        type: 'boolean',
27        default: false,
28        description: 'imports every tag from the remote repository',
29      },
30    };
31
32  }
33
34  async run({ argv }) {
35    console.log('git remote add %s to %s with tags=%s', argv.name, argv.url, argv.tags);
36  }
37
38  get description() {
39    return 'Adds a remote named <name> for the repository at <url>';
40  }
41}

see remote.js for more detail.

Async Support

1class SleepCommand extends Command {
2  async run() {
3    await sleep('1s');
4    console.log('sleep 1s');
5  }
6
7  get description() {
8    return 'sleep showcase';
9  }
10}
11
12function sleep(ms) {
13  return new Promise(resolve => setTimeout(resolve, ms));
14}

see async-bin for more detail.

Bash-Completions

1$ # exec below will print usage for auto bash completion
2$ my-git completion
3$ # exec below will mount auto completion to your bash
4$ my-git completion >> ~/.bashrc

Migrating from v1 to v3

bin

• run method is not longer exist.

1// 1.x
2const run = require('common-bin').run;
3run(require('../lib/my_program'));
4
5// 3.x
6// require a main Command
7const Command = require('..');
8new Command().start();

Program

• Program is just a Command sub class, you can call it Main Command now.
• addCommand() is replace with add().
• Recommand to use load() to load the whole command directory.

1// 1.x
2this.addCommand('test', path.join(__dirname, 'test_command.js'));
3
4// 3.x
5const Command = require('common-bin');
6const pkg = require('./package.json');
7
8class MainCommand extends Command {
9  constructor() {
10    super();
11
12    this.add('test', path.join(__dirname, 'test_command.js'));
13    // or load the entire directory
14    this.load(path.join(__dirname, 'command'));
15  }
16}

Command

• help() is not use anymore.
• should provide name, description, options.
• async run() arguments had change to object, recommand to use destructuring style - { cwd, env, argv, rawArgv }
  • argv is an object parse by yargs, not args.
  • rawArgv is equivalent to old args

1// 1.x
2class TestCommand extends Command {
3  * run(cwd, args) {
4    console.log('run mocha test at %s with %j', cwd, args);
5  }
6}
7
8// 3.x
9class TestCommand extends Command {
10  constructor() {
11    super();
12    // my-bin test --require=co-mocha
13    this.options = {
14      require: {
15        description: 'require module name',
16      },
17    };
18  }
19
20  async run({ cwd, env, argv, rawArgv }) {
21    console.log('run mocha test at %s with %j', cwd, argv);
22  }
23
24  get description() {
25    return 'unit test';
26  }
27}

helper

• getIronNodeBin is remove.
• child.kill now support signal.

License

MIT

Contributors

atian25	fengmk2	popomore	dead-horse	whxaxes	DiamondYuan
tenpend	hacke2	liuqipeng417	Jarvis2018

This project follows the git-contributor spec, auto updated at Sat Jun 04 2022 00:31:29 GMT+0800.