Tiny-parse-argv NPM

Tiny Parse Argv

A tiny function for parsing process.argv, a modern rewrite of a sensible subset of minimist.

Features

The following features are provided:

Built-in TypeScript types, and pretty clean and understandable code.
Single/multiple implicit/explicit shorthand flags: -f, -f some, -f 123, -f123, -abc, -abc 123, -abc123, -f some -f other.
Single/multiple implicit/explicit longhand flags: --foo, --foo some, --foo 123, --foo=123, --foo=some, --foo some --foo other.
Explicitly negated flags are false by default: --no-foo, --no-bar.
Eager flags consume multiple consecutive values: -f one two three, --foo one two three.
Arguments: ./app.sh with some list of arguments.
Values that would be interpreted as numbers if they were JavaScript are coerced to numbers automatically.
Flags that could lead to prototype pollution issues are safely ignored.
options.boolean: the value for the listed flags will always be coerced to a boolean.
options.integer: the value for the listed flags will always be coerced to a integer.
options.number: the value for the listed flags will always be coerced to a number.
options.string: the value for the listed flags will always be coerced to a string.
options.eager: the listed flags are considered to be eager, and will consume multiple consecutive non-flag values.
options.unary: the listed flags are considered to be unary, and if multiple values are provided only the last one will be considered.
options.variadic: the listed flags are considered to be variadic, and their value, if present, will always be an array.
options.required: the listed flags are considered to be required, if some are missing options.onMissing will be called.
options.alias: if any aliased flag is assigned then all the aliases for it will be assigned too, automatically.
options.default: an object containing default values, which will be used if not overridded by the argv array.
options.incompatible: an object mapping flags with other flags they are incompatible with.
options.validators: an object mapping flags to custom validation functions for them, returning a boolean.
options.onIncompatible: a function that will be called if any pairs of flags that are incompatible with each other is detected.
options.onInvalid: a function that will be called if any of the provided flags have an invalid value, e.g. a boolean value for a string flag.
options.onMissing: a function that will be called if any of the required flags is missing. If a default value is provided for a flag it won't be considered as missing.
options.onUnknown: a function that will be called if any of the flags are unknown, i.e. not listed as either a boolean, a string, or an alias. If a default value is provided for a flag it won't be considered as unknown.
--: a special flag that stops parsing, everything after it will be copied, untouched, into the -- property of the return object.

Differences with `minimist`

The following differences exist compared to minimist:

option['--'] set to false is not supported, it's as if it's always set to true.
option.boolean set to true is not supported, you should always explicitly list all your supported boolean flags instead.
option.boolean set to a single string is not supported, always provide an array of flags instead.
option.string set to a single string is not supported, always provide an array of flags instead.
option.alias mapping to a single string is not supported, always provide an array of aliases instead.
option.stopEarly is not supported, it's as if it's always set to false.
Dotted flags are not supported, so their paths will not be expanded, you can use path-prop's unflat function for that.

Other than that it should work pretty much identically, since we are basically using the same tests.

Install

npm install --save tiny-parse-argv

Usage

import parseArgv from 'tiny-parse-argv';

parseArgv ([ '-f', '--foo', 'some', 'argument', '--', '--app-flag' ]);
// => { f: true, foo: 'some', _: ['argument'], '--': ['--app-flag'] }