@wcauchois/program-builder

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

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<typeof program>) {
  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] <filename> [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!