@joro/optimist NPM

Simply maps common command-line options to an object, turning their values to literal types.

Usage

Install Optimist using npm:

npm install --save-dev @joro/optimist

Or yarn:

yarn add --dev @joro/optimist

Get started by simply requiring optimist module and define an optional default values:

const optimist = require('@joro/optimist');

const defaults = {
  option1: 'string',
  option2: [true, false],
  option3: {
    defaults: -1.1,
    aliases: 'opt3'
  },
  option4: {
    defaults: [null, undefined],
    aliases: ['opt4']
  }
};

console.log(optimist(process.argv.slice(2), defaults));

Now, if we execute our script with the following arguments:

node <script.js> --option1 string --option2 -opt3 -1.1 -opt4=undefined

It will output an optimized representation of the given options:

{
  _: [],
  option1: 'string',
  option2: true,
  option3: -1.1,
  option4: undefined
}

Options and Values

Valid options syntax are marked with a -- or -, and values are separated with a space or =. Single options are parsed with an implicit true value.

Number values like -1.1 are treated as both an option or a value depending on the position of arguments, e.g in -123=value and --option=-123, the former is an option name while the latter is a value. Values such as boolean, number, null, or undefined types are parsed as literals. Others will remain as raw string.

Defaults and Aliases

Referring to the above example, the given defaults are used to determine if the actual command-line arguments contains valid or invalid options as well as provide default values to those options not explicitly specified. Such defaults are defined as the following:

option1: Represents an option with a single default value.
- Matches: --option1 'string' or --option1=string
option2: Represents an option with multiple required values.
- Matches: --option2 or --option2=false
option3: Represents an option with a single default value including an alias.
- Matches: --option3 -1.1 or -opt3=-1.1
option4: Represents an option with multiple required values including an alias.
- Matches: --option4 null or -opt4=undefined

Note: For multiple values, the actual default value is the first element (index [0]), e.g in [true, false], true is the default value.
Note: Use the aliases property to define a name alias. Doing so, will let you use the defaults property for default values. Aliases will always return their exact option name, e.g, --opt3=value will return option3:value.

Returned Value

The returned object contains an option:value pairs including a ['_'] property containing a list of all invalid options. An invalid option is captured if its name or value is not defined in the defaults. If there are no provided defaults, then only the syntax will be parsed.