Tiny Parse Argv

A tiny function for parsing process.argv, a modern rewrite 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 tiny-parse-argv

Usage

import parseArgv from 'tiny-parse-argv';

// Let's parse some arguments

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

License

MIT © Fabio Spampinato