classy-commander

A TypeScript wrapper for Commander that lets you easily declare commands using classes & decorators and provides you with strongly typed arguments.

Features

• Write commands as modular classes that can be easily tested
• Specify command usage via a class with decorators
• Command values
• Optional values
• Options
• Options with values
• Automatic coercion
• Version from package.json
• Support for Inversion of Control containers like Inversify

Install

npm install classy-commander --save

Usage

First enable support for decorators in your tsconfig.json compiler options.

{
  "compilerOptions": {
    "emitDecoratorMetadata": true,
    "experimentalDecorators": true,
  }
}

Let's create a simple Calculator CLI app with a command that adds two numbers.

Our entry-point looks like this.

./calc.ts

import * as cli from 'classy-commander';

import './commands/add.ts';

cli.execute();

Our add command looks like this.

./commands/add.ts

import { Command, command, value } from 'classy-commander';

export class AddCommandParams {
  @value()
  value1: number = 0;

  @value()
  value2: number = 0;
}

@command('add', AddCommandParams, 'Adds two numbers')
export class AddCommand implements Command<AddCommandParams> {

  execute(params: AddCommandParams) {
    const { value1, value2 } = params;

    const result = value1 + value2;

    console.log(`${value1} + ${value2} = ${result}`);
  }

}

For simplicity, we'll use ts-node to run our app.

Running ts-node ./calc add 1 2 outputs:

1 + 2 = 3

Using optional values

But what if we want to add 3 numbers?

Lets allow adding an optional third number.

import { Command, command, value } from 'classy-commander';

export class AddCommandParams {
  @value()
  value1: number = 0;

  @value()
  value2: number = 0;

  @value({ optional: true })
  value3: number = 0;
}

@command('add', AddCommandParams, 'Adds two or three numbers')
export class AddCommand implements Command<AddCommandParams> {

  execute(params: AddCommandParams) {
    const { value1, value2, value3 } = params;

    const result = value1 + value2 + value3;

    if (value3) {
      console.log(`${value1} + ${value2} + ${value3} = ${result}`);
    } else {
      console.log(`${value1} + ${value2} = ${result}`);
    }
  }

}

Running ts-node ./calc add 1 2 3 now outputs:

1 + 2 + 3 = 6

Adding two numbers still works. ts-node ./calc add 1 2 outputs:

1 + 2 = 6

Variadic Arguments

Okay, but what if we want to add 4 numbers, or 5? This could get messy.

It's time to turn our values into a variadic value.

import { Command, command, value } from 'classy-commander';

export class AddCommandParams {
  @value({ variadic: { type: Number } })
  values: number[] = [];
}

@command('add', AddCommandParams, 'Adds two or more numbers')
export class AddCommand implements Command<AddCommandParams> {

  execute(params: AddCommandParams) {
    const { values } = params;

    const result = values.reduce((total, val) => total + val, 0);

    console.log(`${values.join(' + ')} = ${result}`);
  }

}

Running ts-node ./calc add 1 2 3 4 5 now outputs:

1 + 2 + 3 + 4 + 5 = 15

Using options

Let's add an option to show thousand separators.

import { Command, command, option, value } from 'classy-commander';

export class AddCommandParams {
  @value({ variadic: { type: Number } })
  values: number[] = [];

  @option({ shortName: 't' })
  thousandSeparators: boolean = false;
}

@command('add', AddCommandParams, 'Adds two or more numbers')
export class AddCommand implements Command<AddCommandParams> {

  execute(params: AddCommandParams) {
    const { values, thousandSeparators } = params;

    const result = values.reduce((total, val) => total + val, 0);

    const format = (val: number) => val.toLocaleString(undefined, {
      useGrouping: thousandSeparators
    });

    console.log(`${values.map((val) => format(val)).join(' + ')} = ${format(result)}`);
  }

}

Running ts-node ./calc add 500 1000 --thousandSeparators or ts-node ./calc add 500 1000 -t will output:

500 + 1,000 = 1,500

Using option values

Lets add an option with a value that lets us specify the number of decimal places to show.

import { Command, command, option, value } from 'classy-commander';

export class AddCommandParams {
  @value({ variadic: { type: Number } })
  values: number[] = [];

  @option({ shortName: 't' })
  thousandSeparators: boolean = false;

  @option({ shortName: 'd', valueName: 'count' })
  decimalPlaces: number = 0;
}

@command('add', AddCommandParams, 'Adds two or more numbers')
export class AddCommand implements Command<AddCommandParams> {

  execute(params: AddCommandParams) {
    const { values, thousandSeparators, decimalPlaces } = params;

    const result = values.reduce((total, val) => total + val, 0);

    const format = (val: number) => val.toLocaleString(undefined, {
      useGrouping: thousandSeparators,
      maximumFractionDigits: decimalPlaces
    });

    console.log(`${values.map((val) => format(val)).join(' + ')} = ${format(result)}`);
  }

}

Running ts-node ./calc add 1 2.2345 --decimalPlaces 2 will output:

1 + 2.23 = 3.23

Getting usage

Running ts-node ./calc.ts --help outputs:

  Usage: calc [options] [command]

Options:

  -h, --help                 output usage information

Commands:

  add [options] <values...>

Running ts-node ./calc.ts add --help shows the usage for our add command:

Usage: add [options] <values...>

Options:

  -t, --thousandSeparators
  -d, --decimalPlaces <count>   (default: 0)
  -h, --help                   output usage information

Dependency Injection

To keep our add command easy to test, lets move that heavy math into a calculator service, and have that service automatically injected into the command when it gets created. Let's use the awesome Inversify library which has excellent support for TypeScript (though in principal we could use any JavaScript Dependency Injection library).

Let's start by adding the calculator service.

./services/calculator.ts

import { injectable } from 'inversify';

@injectable()
export class Calculator {
  add(...amounts: number[]) {
    return amounts.reduce((total, amount) => total + amount, 0);
  }
}

Now lets update our add command to use the service.

./commands/add.ts

import { injectable } from 'inversify';
import { Command, command, option, value } from 'classy-commander';
import { Calculator } from '../services/calculator';

export class AddCommandParams {
  @value({ variadic: { type: Number } })
  values: number[] = [];

  @option({ shortName: 't' })
  thousandSeparators: boolean = false;

  @option({ shortName: 'd', valueName: 'count' })
  decimalPlaces: number = 0;
}

@command('add', AddCommandParams, 'Adds two or more numbers')
@injectable()
export class AddCommand implements Command<AddCommandParams> {
  constructor(private calculator: Calculator) {
  }

  execute(params: AddCommandParams) {
    const { values, thousandSeparators, decimalPlaces } = params;

    const result = this.calculator.add(...values);

    const format = (val: number) => val.toLocaleString(undefined, {
      useGrouping: thousandSeparators,
      maximumFractionDigits: decimalPlaces
    });

    console.log(`${values.map((val) => format(val)).join(' + ')} = ${format(result)}`);
  }

}

Finally, in our entrypoint, lets create our inversify container and pass it to classy-commander.

./calc.ts

import { Container } from 'inversify';
import * as cli from 'classy-commander';

import './commands/add.ts';
import './services/calculator';

const container = new Container({ autoBindInjectable: true });

cli
  .ioc(container)
  .execute();

Specifying the version

There are two ways to specify the version of your CLI:

Using the version in your package.json.

import * as cli from 'classy-commander';

...

cli
  .versionFromPackage(__dirname)
  .execute();

Or manually.

import * as cli from 'classy-commander';

...

cli
  .version('1.2.3')
  .execute();

Loading commands from a directory

Maybe we end up adding a bunch of commands to our CLI app and we don't want to manually import each command in our entry point like below:

import * as cli from 'classy-commander';

import './commands/add.ts';
import './commands/subtract.ts';
import './commands/multiply.ts';
import './commands/divide.ts';
import './commands/square.ts';
import './commands/squareRoot.ts';
import './commands/cube.ts';
import './commands/cubeRoot.ts';

cli.execute();

We can tell classy-commander to dynamically load all commands from a directory thus reducing our imports.

import * as cli from 'classy-commander';
import * as path from 'path';

async function run() {
  await cli.commandsFromDirectory(path.join(__dirname, '/commands'));
  cli.execute();
}

run().catch(console.error);

Contributing

Got an issue or a feature request? Log it.

Pull-requests are also welcome. 😸

Changelog

3.2.16 (2020-03-02)

<a name="3.2.15"></a>