scanargs

Typescript node package to manage commands arguments.

Notes

• Node.js >= 10.0.0
• Typescript compiled in ECMAScript with target version ES2017 (aka ES8)

Setup

$ npm install --save scanargs

Usage

In your command, set arguments as below

// classically:
$ example --port=8080 --logger=true
// is equivalent to:
$ example --port 8080 --logger true
$ example -p=8080 -l=true
$ example -p 8080 -l true

// with package.json scripts (note the extra double hyphen):
$ npm run script -- --port=8080 --logger=true

In your typescript code, import the scanargs package

import { Scanargs } from ('scanargs');

In your javascript code, require the scanargs package

const { Scanargs } = require('scanargs');

Typescript example

Code

import { Scanargs } from 'scanargs';

// you can instantiate with options you need
// you can also instantiate with an empty array in the second parameter
const scan = new Scanargs(process.argv, [{ name: 'param' }]);

// if you prefer, you can also set/replace options after instantiation
// (especially if you have instantiated with an empty array)
scan.options = [
    { name: 'port', default: 3000 },
    { name: 'logger', default: false },
    { name: 'throwError' }
];

console.log(`${JSON.stringify(scan.scan(), null, 2)}`);

Command

$ ts-node example.ts --port="8080" -l=true --throwError=false --arg=azerty

Console

{
  "port": 8080,
  "logger": true,
  "throwError": "false"
}

Note: As 'arg' is not defined in options, it is not returned/recognized as an argument.

Javascript example

Code

const { Scanargs } = require('scanargs');
const scan = new Scanargs(process.argv, [{name: 'param'}]);

console.log(`bin [ ${scan.getNode()} ] file [ ${scan.getNode()} ] param [ ${scan.scan().param} ]`);

Command

$ node example.js --param=azerty

Console

bin [ /usr/bin/node ] file [ /usr/bin/node ] param [ azerty ]

Constructor Scanargs

It creates a Scanargs object which will parse the command arguments.
It needs two mandatory parameters:

• the first one is classically the result of the process.argv node property
• the second one is a definition of the arguments you want to retrieve and use in your code

Typescript example:

const myOptions: Option[] = [
    { name: 'myFirstArgument' },
    { name: 'mySecondArgument' }
];
const scan = new Scanargs(process.argv, myOptions);

Options

It's an array of Option passed to the constructor or to the setter options.
An Option is defined as below

{
  name: string;
  alias: string;
  default: any;
}

• name is mandatory.
  • It's the name of a command argument you want to retrieve.
  • It's the string you type after the double hyphen (--).
    (for example: --foo)
• alias is optional.
  • It's the argument short-name.
  • It's the string you type after the hyphen (-).
  • If it's not set the default alias is defined to the first letter of name.
    (for example: if name is 'foo' then the default alias is 'f': -f)
• default is optional.
  • If it's defined, it gives its type (number, string, boolean) to the passed value.
  • If it's not defined, the value type is always string

Setter options

As shown in the above examples, you can set Options with the setter in the same way you do with the constructor.
Typescript example:

const scan = new Scanargs(process.argv, []);
scan.options = [
    { name: 'myFirstArgument' },
    { name: 'mySecondArgument' }
];

scan()

It returns the parsed arguments into a json object.
So to retrieve the argument value you want, just get the key of this one.
Example:

console.log(scan.scan().myFirstArgument);

Examples

Let's assume that you define these Options in a typescript file: example.ts

[
  { name: 'port', default: 3000 },
  { name: 'logger', default: false },
  { name: 'throwError' }
];

Then
example 1

$ ts-node example.ts -p=8080 --logger true --throwError=false

will return

{
  "port": 8080,
  "logger": true,
  "throwError": "false"
}

throwError is of type string and not of boolean type since it has no boolean default value

example 2

$ ts-node example.ts -p 8080

will return

{
  "port": 8080,
  "logger": false
}

logger has a default boolean value set to false, so this value is returned
throwError has no default value so nothing is returned

example 3

$ ts-node example.ts -p -l --foo

will return

{
  "port": 3000,
  "logger": true
}

the port argument is present without any value but the returned value is set to its default value
the logger argument is present without any value but the returned value is set to true because the type of its default value is boolean
the foo argument is ignored because it is not an Option

example 4

$ ts-node example.ts --throwError

will return

{
  "port": 3000,
  "logger": false
}

the port argument is not present but the returned value is set to its default value
the logger argument is not present but the returned value is set to its default value
the throwError argument is present without any value but there is no returned value because no default value is set