@slimio/arg-parser

ArgParser

Secure and reliable Command Line Argument parser for Node.js ! ArgParser was designed to be embedded in a SlimIO agent, most popular library was not matching our expectation (and security needs).

It does not aim to replace (or to be) popular CLI lib like yargs or commander. Please, do not use this package if you do not know what you are doing.

Requirements

• Node.js v10 or higher

Why

• Secure with 0 external dependencies.
• Only ship feature required for SlimIO.
• Use and return modern collection (Map over Object).

Non-goals

• Performance over maintainability and readability.
• Features over security.

Getting Started

This package is available in the Node Package Repository and can be easily installed with npm or yarn.

$ npm i @slimio/arg-parser
# or
$ yarn add @slimio/arg-parser

Usage example

Create the following javascript script:

const { parseArg, argDefinition } = require("@slimio/arg-parser");

const result = parseArg([
    argDefinition("-c --colors [array]", "Array of colors"),
    argDefinition("--verbose", "Enable verbose mode!")
]);

console.log(result);

And then run the following command line:

$ node yourscript --colors red blue --verbose
$ Map { 'colors' => [ 'red', 'blue' ], 'verbose' => true }

API

argDefinition(cmd: string, description?: string): Command

Generate a new Command definition. cmd argument is a string pattern that will be matched against the following regex:

/^(-{1}(?<shortcut>[a-z]){1})?\s?(-{2}(?<name>[a-z]+)){1}\s?(\[(?<type>number|string|boolean|array)(=(?<defaultVal>.*))?\])?$/;

Take a look at the root directory example for more examples of how to use addCommand !

const { parseArg, argDefinition } = require("@slimio/arg-parser");

const result = parseArg([
    argDefinition("--verbose", "Enable verbose mode!"),
    argDefinition("-a --autoreload [number=500]", "Configuration Autoreload delay in number")
]);

A command is described as follow on TypeScript:

interface Command {
    name: string;
    type: string;
    description: string;
    shortcut?: string;
    defaultVal?: number | string | boolean | any[];
}

Feel free to redefine the wrapper as you want !

parseArg< T >(argDefinitions: Command[], argv?: string[]): Map< keyof T, T[keyof T] >

Parse Argv (or any input string[]). Return a ECMAScript6 Map Object.

const { parseArg, argDefinition } = require("@slimio/arg-parser");

const argv = parseArg([
    argDefinition("--level [number=1]")
], ["--level", "10"]);
console.log(argv.get("level"));

Under the hood we use TypeScript with the following type

export type ArgvResult<T> = Map<keyof T, T[keyof T]>;

help(argDefinitions: Command[]): void

Display all commands information

const cmdDef = [
    ArgParser.argDefinition("-p --product [number=10]", "Product number description"),
    ArgParser.argDefinition("-t --truc [string]"),
    ArgParser.argDefinition("--bidule")
];

ArgParser.help(cmdDef);

// output ->
// Usage :
//     - node file.js <command>
//     - node file.js <command> <value>
//
// <command>     <type>   <default>  <description>
// -p --product  number   10         Product number description
// -t --truc     string
// --bidule      boolean  true

Dependencies

This project have no dependencies.

License

MIT