Advanced* NodeJS Command Line Interpreter

See the Release History

Motivation

This is a TypeScript port and improvement from one of my earlier projects, that I decided to make available as a utility, after using it in various other projects. This typescript based library (ES2015) allows for setting up command line interfaces in a declarative way. I hope it will save you a lot of time.

Disclaimer

i've called this package *advanced as it is an advancement of the previous version, and has quite a few of new features. But it's up to you to make up your own mind :-)

Features

Declare a new CLI Command by creating a Command instance
Declare arguments by adding them to the command instance
Add parsers for built-in and custom argument types
- String
  - Pattern (RegExp based)
    
    Example
    
    --examplePattern BE1234567890
  - RegExp (an expression)
    
    Example
    
    --exampleWithoutFlags ^yes|no$ --exampleWithFlags "/^yes|no$/i"
  - Path (ParsedPath)
    
    Example
    
    --examplePath /some/path/to/a/file/or/dir
- Boolean
  
  Example
  
  --example yes (true) --example false (fals) --example (flag)
- Number
  
  Example
  
  --exampleFloat 1234.5678 --exampleInt 1234
  - Integer (Number)
    
    Example
    
    --example 1234
- Date (understands literal now)
  
  Example
  
  --when 2021-01-01
- Moment (understands literals now, today, tomorrow, yesterday)
  
  Example
  
  --from 2021-01-01T00:00:00.000+0100 --to today
- Enum
  - String
  - Numerical
- ... whatever you implement a parser for
Declare single vs array arguments (comma separated)
Performs validation if required
Conditionally required arguments (based on value or absence of other arguments for example)
Named arguments (--say Hello)
Argument shortcodes (-s Hello)
Positional arguments (cp <source> <target>)
Boolean flag arguments (-R) without value (cp -R <source> <target>)
Set a callback for execution of the command, or provide a diffent callback every time
Parsing command lines
- Parse a string
- Parse a string array ()
- Parse process argv
Execute after parsing
Provide help text and usage (by default on --help or -?)
Use a custom logger (defaults to console)
Strict mode (disallow undeclared arguments)
Loading command arguments from an object or file (json, yaml...)

Usage

Installation

# Install via NPM
npm install --save node-commandline-advanced

# Optionally install moment if you are using the moment parser
npm install --save moment

Note

The library contains TypeScript declarations and source maps

Declaring a command

// A demo command with strict parsing disabled and a description.
const demoCommand = new Command("demo", {strict: false})
	.info("A demo command");

Declaring arguments

const demoCommand = new Command("demo", true)
	.info("A demo command")
	// A flag argument
	.addArgument({
		name: "fast",
		shortCode: "f",
		description: "Execute fast!",
		// required: false // ALWAYS FALSE FOR FLAGS,
		parser: BooleanParser,
		// array: false // ALWAYS FALSE FOR FLAGS
	})
	.addArgument({
		name: "in",
		shortCode: "i",
		description: "Input file",
		// required: true // REQUIRED BY DEFAULT
		// parser: null // Default parser parses strings,
		array: true // Allow for multiple input files!
	})
	.addArgument({
		name: "optional",
		required: false
	})

All options for `addArgument(...)`

See the IArgument Type as a reference

name: string

The name of the argument. This name will be used in order to add the argument value into the argument Map.

Must be unique.

parser: IArgumentParser

The parser defines the type, and can be either:

A class (constructor) implementing IArgumentParser<T>
An intance of IArgumentParser<T>

A parser instance provides both the parse function and the name property. The name is intended to provide the type for documentation and help output.

Array arguments

Arguments declared as array will first be split on each comma character. Then, the parser will be applied to each part. You can escape a comma within an argument using a backslash.

For example:

--example one,two,three,fo\,ur will be parsed as ["one","tow","three", "fo,ur"]

Parsing a command line

// Assume the previously declared demoCommand...
// parsing will throw if the input is invalid!
const instance = demoCommand.parse("--fast", "-i", "/some/path,/some/other/path");
const fast: Boolean = instance.get("fast");
const inputFiles: String[] = instance.get("in");
const optional: string = instance.get("optional", "Some optional default");

Parsing Node process args

export {myCommand} from "./my-command.ts";
// Set async handler
myCommand.onExecute(async function (args) {
	// this is the command instance

	// Do something async ;-)
	return Promise.resolve(args);
});

// If this module is the main module, parse process args and execute!
if (require.main === module) {
	const instance = myCommand.parseProcessArgs();
	export default instance.execute();
}

Loading argumens from a file

export {myCommand} from "./my-command.ts";
// Set async handler
myCommand.onExecute(async function (args) {
// this is the command instance

	// Do something async ;-)
	return Promise.resolve(args);
});

// If this module is the main module, parse process args and execute!
if (require.main === module) {
	/**
	 * The second argument is a parser that parsed from string to object, the encoding is optional and defaults to utf-8
	 * The sectionName option indicates under what key in the object to find the config arguments.
	 */
	const instance = myCommand.loadFromFile("/some/file.json", (data) => JSON.parse(data), {encoding: "utf-8", sectionName: "test"});
	// Note that loadFromObject() is available too, and works in a similar way (skips the parser).
	export default instance.execute();
}

Override --help

By default, the command instance will add the "help" argument with shortcode "?" if not declared by your command upon parsing. If the command typed is invalid, the output will be sent to the console.

Override logging

You can prevent or redirect logging by providing an alternative logger. Setting the logger to null will prevent logging. The logger expexts the IConsole interface

const command = new Command("demo", {logger: console});

Parsers

A parser allows conversion of a string argument into a typed value. They can either be passed to the argument as a class (newable) or as an instance (required if the parser needs extra information, like the EnumParser or the PatternParser).

// The enum parsers must be either instantiated with an Enum
parser: new EnumParser(Demo1Enum)
// or extended as a custom parser
parser: Demo1EnumParser
// Same for PatternParser
const ipAddressPattern = /^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$/
parser: new PatternParser(ipAddressPattern)

The following argument parsers are supported out of the box

parser	type	remark
null	String	Default
BooleanParser	Boolean	Case insensitive, supports 0/1, yes/no, true/false
DateParser	Date	Checks for invalid dates, supports 'now' literal
MomentParser	Moment	Requires MomentJS optional dependency, supports 'now','today','tomorrow','yesterdat' literals.
NumberParser	Number
IntParser	Number	Restricted to integers
ObjectParser	Object	Parses JSON into an object
PathParser	ParsedPath	Does not check for target existence
RegExpParser	RegExp	Parses patterns AND flags if provided
EnumParser	enum type	Parses enum keys to their respective values

License and Copyright

This software is distributed under the included MIT license.
See the included LICENSE file

Depencencies

moment.js - MIT license

This project can optionally use (but does not depend upon or distribute) the momentjs library.

daankets/node-cli-advanced