mri

What is mri?

The mri npm package is a lightweight option parsing library. It allows for easy parsing of command-line options, providing a simple API to access command-line arguments in a structured way. It's designed for performance and simplicity, making it a great choice for projects that require basic yet efficient argument parsing without the overhead of more complex libraries.

What are mri's main functionalities?

Basic Option Parsing

This code demonstrates how to parse command-line arguments using mri. It slices the process.argv array to ignore the first two entries (node path and script path), then parses the remaining arguments into an options object.

const mri = require('mri');
const args = process.argv.slice(2);
const options = mri(args);
console.log(options);

Specifying Option Types

This example shows how to specify the types of options (boolean, string) and aliases for them. This helps in parsing the command-line arguments more accurately according to the expected types and aliases.

const mri = require('mri');
const args = process.argv.slice(2);
const cliOptions = {
  boolean: ['help', 'version'],
  string: ['output'],
  alias: { h: 'help', v: 'version', o: 'output' }
};
const options = mri(args, cliOptions);
console.log(options);

Other packages similar to mri

yargs

Yargs is a more feature-rich command-line option parsing library compared to mri. It offers advanced features like command handling, automatic help generation, and more detailed option configurations. While mri focuses on simplicity and performance, yargs provides a broader set of functionalities for complex CLI applications.

commander

Commander is another popular option parsing library that provides a high-level API for creating command-line interfaces. It supports subcommands, custom help, auto-completion, and more. Compared to mri, Commander is suited for more complex CLI applications that require structured commands and options.

minimist

Minimist is a minimalist option parsing library similar to mri in terms of simplicity and performance. It provides basic parsing capabilities with a focus on minimal overhead. While mri and minimist share similar goals, mri offers a slightly more modern API and additional features like option type specification.

README

mri

Quickly scan for CLI flags and arguments

This is a fast and lightweight alternative to minimist and yargs-parser.

It only exists because I find that I usually don't need most of what minimist and yargs-parser have to offer. However, mri is similar enough that it might function as a "drop-in replacement" for you, too!

See Comparisons for more info.

Install

$ npm install --save mri

Usage

$ demo-cli --foo --bar=baz -mtv -- hello world

const mri = require('mri');

const argv = process.argv.slice(2);

mri(argv);
//=> { _: ['hello', 'world'], foo:true, bar:'baz', m:true, t:true, v:true }

mri(argv, { boolean:['bar'] });
//=> { _: ['baz', 'hello', 'world'], foo:true, bar:true, m:true, t:true, v:true }

mri(argv, {
  alias: {
    b: 'bar',
    foo: ['f', 'fuz']
  }
});
//=> { _: ['hello', 'world'], foo:true, f:true, fuz:true, b:'baz', bar:'baz', m:true, t:true, v:true }

API

mri(args, options)

Return: Object

args

Type: Array
Default: []

An array of arguments to parse. For CLI usage, send process.argv.slice(2). See process.argv for info.

options.alias

Type: Object
Default: {}

An object of keys whose values are Strings or Array<String> of aliases. These will be added to the parsed output with matching values.

options.boolean

Type: Array|String
Default: []

A single key (or array of keys) that should be parsed as Booleans.

options.default

Type: Object
Default: {}

An key:value object of defaults. If a default is provided for a key, its type (typeof) will be used to cast parsed arguments.

mri(['--foo', 'bar']);
//=> { _:[], foo:'bar' }

mri(['--foo', 'bar'], {
  default: { foo:true, baz:'hello', bat:42 }
});
//=> { _:['bar'], foo:true, baz:'hello', bat:42 }

Note: Because --foo has a default of true, its output is cast to a Boolean. This means that foo=true, making 'bar' an extra argument (_ key).

options.string

Type: Array|String
Default: []

A single key (or array of keys) that should be parsed as Strings.

options.unknown

Type: Function
Default: undefined

Callback that is run when a parsed flag has not been defined as a known key or alias. Its only parameter is the unknown flag itself; eg --foobar or -f.

Once an unknown flag is encountered, parsing will terminate, regardless of your return value.

Note: mri only checks for unknown flags if options.unknown and options.alias are populated. Otherwise, everything will be accepted.

Comparisons

minimist

• mri is 5x faster (see benchmarks)
• Numerical values are cast as Numbers when possible
  • A key (and its aliases) will always honor opts.boolean or opts.string
• Short flag groups are treated as Booleans by default:

  minimist(['-abc', 'hello']);
  //=> { _:[], a:'', b:'', c:'hello' }
  
  mri(['-abc', 'hello']);
  //=> { _:[], a:true, b:true, c:'hello' }
  

• The opts.unknown behaves differently:
  • Unlike minimist, mri will not continue continue parsing after encountering an unknown flag
• Missing options:
  • opts.stopEarly
  • opts['--']
• Ignores newlines (\n) within args (see test)
• Ignores slashBreaks within args (see test)
• Ignores dot-nested flags (see test)

yargs-parser

• mri is 40x faster (see benchmarks)
• Numerical values are cast as Numbers when possible
  • A key (and its aliases) will always honor opts.boolean or opts.string
• Missing options:
  • opts.array
  • opts.config
  • opts.coerce
  • opts.count
  • opts.envPrefix
  • opts.narg
  • opts.normalize
  • opts.configuration
  • opts.number
  • opts['--']
• Missing parser.detailed() method
• No additional configuration object
• Added options.unknown feature

Benchmarks

Running Node.js v10.13.0

Load Times:
  nopt          3.179ms
  yargs-parser  2.137ms
  minimist      0.746ms
  mri           0.517ms

Benchmark:
  minimist      x    328,747 ops/sec ±1.09% (89 runs sampled)
  mri           x  1,622,801 ops/sec ±0.94% (92 runs sampled)
  nopt          x    888,223 ops/sec ±0.22% (92 runs sampled)
  yargs-parser  x     30,538 ops/sec ±0.81% (91 runs sampled)

License

MIT © Luke Edwards