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.

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.

Planned Features

• Subcommands.

Example

const program = ProgramBuilder.newBuilder()
  .arg('filename', { description: `A file name` })
  .optionalArg('extraFilename', { description: `An additional optional file name`})
  .intFlag('--count,-c', { dest: 'count', default: 0, 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 | undefined
  console.log(`count is: ${args.count}`); // args.count: number | undefined
  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