strict-args v0.3.0

NodeJS Strict Args

GitHub Wiki \ GitHub Issue Tracker

A NodeJS arguments library which strictly enforces flag presence, command syntax, alerts on unexpected flags, and manages help and command outputs. This library's goal is to make developing new command line tools in Node easy and user-friendly.

See this project's GitHub Wiki for API documentation.

This library is a spiritual successor to @ava-cassiopeia/really-simple-args, with a focus on stricter syntax checking.

• Quickstart
• Contributing
  • Development

Quickstart

To start, import strict-args as a (non-dev) dependency:

npm install --save strict-args

Then declare the available commands and flags for your tool:

import {StrictArgs, FlagType} from "strict-args";

const strictArgs = new StrictArgs(
    // The name of your tool. This should match how the tool is invoked in the
    // command line, ie. if one types "fakecli" then the name here should be
    // "fakecli".
    /* name= */ "fakecli",
    // The description of your tool. This is printed on the various help screens
    // that StrictArgs will render if needed.
    /* description= */ "A fake CLI that does something interesting.");

// Declare commands, including optional flags for those commands.
strictArgs.registerCommand({
  name: "start",
  description: "Starts the webserver on port 8080.",
  flags: [
    {
      name: "debug",
      description: "If present, enables debug mode.",
      type: FlagType.FLAG, // flags don't take values
    },
    {
      name: "port",
      description: "Optional port for the server to run on. Defaults to 8080.",
      default: "8080",
      type: FlagType.PROPERTY, // properties take values
    },
  ],
});
strictArgs.registerCommand({
  name: "stop",
  description: "Stops any running webserver.",
});

// Optionally register global flags, ie. flags that are available for any
// command.
strictArgs.registerGlobalFlag({
  name: "some-flag",
  description: "Does something interesting when present.",
});

// Register "command listeners". Command listeners are classes which implement
// a common interface, and have a class method which is called whenever the
// specified command is run.
// See the section on command listeners for more information.
strictArgs.addCommandListener("start", (a) => new StartCommandListener(a));

// Once all setup and registration is complete, run parse() to run the program.
// Command listeners will automatically be called if the user specifies a
// command and flags correctly, otherwise the program will exit with a message
// explaining to the user how to use the application / what they did wrong.
strictArgs.parse(process.argv);

Contributing

GitHub Issue Tracker

Feel free to file bugs and feature requests in the GitHub issue tracker.

Pull requests are also very much welcome, and will be reviewed on a "best effort" basis. This is typically within a few days, but can sometimes take awhile as this project is maintained by one human.

More information is available for developing with the codebase below.

Development

NodeJS and NPM are required to do development on this project. You can find installers or installation instructions for both here: nodejs.org. Once those are installed, see below.

When your change feels complete, please send a PR where possible so I can merge your code with the main code and publish it under the relevant NPM package.

To build the TypeScript code, run:

npm run build

To test the TypeScript code, run:

npm test

To test a local, fake CLI (code in manualtest/):

npm run manualtest