@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.

Warning: The API doesn't aim to be "runtime" safe.

Why

• Secure with 0 external dependencies.
• Only ship feature required for SlimIO.
• Light, simple and fast!

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

For help run:

$ node yourscript --help

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|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"));

Benchmark

See benchmark/index.js. This benchmark was not created to serve as a performance comparison with other packages.

Testing argDefinition_t1 on 1,000 iteration!
argDefinition_t1: 1.782ms


Testing argDefinition_t2 on 1,000 iteration!
argDefinition_t2: 1.639ms


Testing parsing_v1 on 1,000 iteration!
parsing_v1: 4.743ms

Licence

MIT