@untool/yargs

 

@untool/yargs is a core mixin powering untool's command line interface and allowing other mixins to define their own commands. These custom commands will work exactly as those defined by untool's own modules and can be called using executables such as Hops CLI.

Installation

$ yarn add @untool/yargs # OR npm install @untool/yargs

CLI

@untool/yargs does not define any commands of its own, but only takes care of basically setting up yargs.

@untool/yargs provides a basic command line interface you can use to control your application. It is called un - and it is best used inside your package.json scripts section.

{
  "scripts": {
    "start": "un start"
  }
}

Alternatively, you can call it directly inside your project using npx or yarn exec. Call it without any command to see the available commands and options.

$ yarn exec un start # OR npx un start

API

@untool/yargs only has a couple of semi-private exports, but it exposes a couple of mixin hooks other mixins can implement, allowing them to alter or extend its functionality. These hooks will be called either by @untool/yargs itself or by others.

bootstrap() (parallel)

Within this method, you are expected to set up your application. If you need to do something asynchronous at this point, just return a Promise.

const { Mixin } = require('@untool/core');

module.exports = class FooMixin extends Mixin {
  bootstrap(yargs) {
    return Promise.resolve();
  }
};

registerCommands(yargs) (sequence)

This is the most relevant hook provided by @untool/yargs: it enables other mixins to register their respective commands. Implementations of this mixin method will receive a single argument: a yargs instance.

const { Mixin } = require('@untool/core');

module.exports = class FooMixin extends Mixin {
  registerCommands(yargs) {
    yargs.command(
      this.configureCommand({
        command: 'foo',
        builder: {},
        handler: (argv) => {},
      })
    );
  }
};

configureCommand(definition) (sequence)

By implementing this method, your mixin can intercept and alter command configuration. Its main purpose is to enable you to add arguments to commands defined by other mixins.

const { Mixin } = require('@untool/core');

module.exports = class FooBarMixin extends Mixin {
  configureCommand(definition) {
    if (definition.command === 'foo') {
      definition.builder.bar = {
        alias: 'b',
        default: false,
        describe: 'Enable bar',
        type: 'boolean',
      };
    }
  }
};

Caveat: please be advised that, while we strive to keep the definition argument very stable, it may change between minor versions of @untool/* packages that provide commands. Additionally, other mixins may alter the command you want to modify in relevant ways, so code accordingly.

handleArguments(argv) (sequence)

Your mixin's implementation of this method will receive the parsed CLI arguments passed to @untool/yargs. You may want to implement it if you need to alter mixin behaviour according to these args.

const { Mixin } = require('@untool/core');

module.exports = class FooMixin extends Mixin {
  handleArguments(argv) {
    this.options = { ...this.options, ...argv };
  }
};

handleError(error, recoverable) (override)

By implementing this method, you can handle exceptions occuring in your application - even uncaught errors and unhandled promise rejections. If receoverable' is 'false, @untool/yargs will automatically terminate the running process.

const { Mixin } = require('@untool/core');
const { logError } = require('./logger');

module.exports = class FooMixin extends Mixin {
  handleError(error, recoverable) {
    logError(error);
  }
};