mri

mri is designed to be a faster, more lightweight alternative to existing parsers.

Key Differences from minimist

• Performance: mri is approximately 5x faster.
• Short Flag Groups: mri treats short flag groups (e.g., -abc) as Booleans by default, whereas minimist may treat them as strings or empty values.
• Unknown Flags: mri stops parsing immediately upon encountering an unknown flag when options.unknown is used. minimist continues parsing.
• Parsing Logic: mri ignores newlines, slashBreaks, and dot-nested flags, whereas minimist may ignore them in specific ways.
• Missing Options: mri does not support stopEarly or opts['--'].

Key Differences from yargs-parser

• Performance: mri is approximately 40x faster.
• Features: mri lacks several yargs-parser features including array, config, coerce, count, envPrefix, narg, normalize, and number.
• API: mri does not have the parser.detailed() method or a configuration object.

The primary API for mri. It parses an array of arguments into a structured object.

Parameters

• args (Array, default: []): An array of arguments to parse. For standard CLI usage, use process.argv.slice(2).
• options (Object, default: {}): Configuration object to control parsing behavior.

options properties

• alias (Object, default: {}): An object where keys are the primary flag names and values are Strings or Array<String> of aliases. Aliases are added to the output with matching values.
• boolean (Array|String, default: []): A single key or an array of keys that should be parsed strictly as Booleans.
• default (Object, default: {}): A key:value object of default values. If a default is provided, mri uses the typeof the default value to cast the parsed argument.
• string (Array|String, default: []): A single key or an array of keys that should be parsed strictly as Strings.
• unknown (Function, default: undefined): A callback executed when a parsed flag has not been defined as a known key or alias. The callback receives the unknown flag (e.g., --foobar or -f) as its only parameter. Note: Parsing terminates immediately once an unknown flag is encountered. mri only checks for unknown flags if both options.unknown and options.alias are populated.

Returns

• Object: The parsed arguments object. Unparsed positional arguments are collected in the _ key.

const mri = require('mri');

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

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

// Using aliases
mri(argv, {
  alias: {
    b: 'bar',
    foo: ['f', 'fuz']
  }
});

mri(args, opts) is the primary function for parsing command-line arguments and flags. It returns an object where keys represent flag names and values represent their parsed values. Non-flag arguments are collected in a special _ array.

Argument Parsing Behavior

• Flags: Supports --flag, -f, and --flag=value syntax.
• Boolean Flags: Flags like --no-feature set the feature key to false.
• Positional Arguments: Arguments not prefixed with - are added to the _ array.
• End of Flags: The -- delimiter stops flag parsing; all subsequent arguments are treated as positional and added to _.
• Multiple Values: If a flag is provided multiple times, its values are collected into an array.

Options Object

import mri from 'mri';

const args = ['--foo', 'bar', '--baz', '--count', '3', 'positional'];
const parsed = mri(args);

// Result:
// {
//   _: ['positional'],
//   foo: 'bar',
//   baz: true,
//   count: 3
// }