program-builder


This is a TypeScript-first library for building type safe command-line interfaces.

You define your arguments and keyword arguments using a fluent builder, which gives you a Program object. You can then define a main function in terms of the strongly typed arguments of that Program, and finally execute the main function against your program which will parse and provide commandline arguments.

Documentation Website | Examples | API Docs

Installation

``
npm install @wcauchois/program-builder
`

Features

- Positional arguments (required and optional).
- Boolean flags (both "positive", like --unroll-loops; and "inverted", like --no-unroll-loops).
- Keyword flags like --path foo.txt. These can be strings, integers, or floats - or you can provide
a custom conversion function.
- Validations like ensuring that all required arguments are specified (aka: types should not lie).
- Automatic generation of help text and handling of a help argument (-h, --help).
- Executes Promise-returning main functions and correctly exits the process.
- Subcommands.

Example

`typescript
const program = ProgramBuilder.newBuilder()
.arg('filename', { description: A file name })
.optionalArg('extraFilename', { description: An additional optional file name})
.intFlag('--optionalCount,-c', { dest: 'optionalCount', default: null, description: A count })
.intFlag('--requiredCount', { dest: 'requiredCount', description: A count that is required })
.build();

function main(args: Arguments) {
console.log(filename is: ${args.filename}); // args.filename: string
console.log(extraFilename is: ${args.extraFilename}); // args.extraFilename: string | null
console.log(optionalCount is: ${args.count}); // args.optionalCount: number | null
console.log(requiredCount is: ${args.requiredCount}); // args.requiredCount: number
}

program.exec(main);
`

An example invocation of this program would be:

`
$ ts-node main.ts file1.txt file2.txt -c 1 --requiredCount 2
`

You can also view autogenerated help text by executing the program with an -h parameter.

`
$ ts-node main.ts -h
Usage: main.ts [options] [extraFilename]

Options:
--count, -c [count] A count
--requiredCount [requiredCount] A count that is required
``

Beta Software

As of January 2020, Program Builder is a very young library! That said, I think it occupies a valuable
niche offering better type safety than yargs or
commander with less verbosity than
ts-command-line.

The argument parsing library that gives me the most joy is Python's argparse
and I'm striving to create something similarly lightweight but powerful for TypeScript.

At this stage your feedback is extremely valuable, and if you have
anything to say, _please_ file an issue!