Registry / devops / options-parser

options-parser

JSON →
library0.4.0jsnpmunverified

options-parser is a lightweight, full-featured command-line argument parser for Node.js, designed with no external dependencies for a minimal footprint. The current stable version is 0.4.0, indicating it's still in active development, likely with a focus on stability before a 1.0 release. Its key differentiators include built-in type validation for common types (like files), automatic help screen generation with customizable formatting, and robust handling of multi-value options and default values. It provides a structured way to define expected command-line flags and arguments, distinguishing between required, optional, and flag-only parameters, making it suitable for scripting and CLI tool development in Node.js environments.

devops
npm install options-parser
github ↗package ↗
INSTALL
IMPORT
SIG · OPTIONS-PARSER
O
options-parser
devopsjavascriptv0.4.0
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

options
✓ const options = require('options-parser');
✗ import options from 'options-parser';
This package is primarily CommonJS. Direct ESM import (`import options from 'options-parser';`) will not work without an appropriate wrapper or bundler configuration, or Node.js's CJS-to-ESM interop in some cases. The recommended approach for Node.js scripts is `require`.
options.parse
✓ const result = options.parse(optsConfig, argv);
✗ import { parse } from 'options-parser'; parse(optsConfig, argv);
The `parse` function is a method on the `options` object returned by `require`. It is not a named export. Ensure the `options` module is properly imported first.
options.type
✓ const typeValidation = options.type.file.open.write();
✗ const typeValidation = require('options-parser').type.file.open.write();
`options.type` provides built-in type validation functions. It is accessed as a property of the main `options` object after initial `require`. For complex types, its properties are chained.
options.help
✓ options.help(optsConfig, helpOptions);
✗ const { help } = require('options-parser'); help(optsConfig, helpOptions);
The `help` function for generating help screens is also a method on the `options` object, not a direct named export.

This quickstart demonstrates how to define a comprehensive set of command-line options including required fields, flags, default values, multi-value options, and type validation. It then parses a simulated argument array, logs the resulting structured data, and showcases the package's ability to automatically generate a formatted help screen.

const options = require('options-parser'); // Define your command-line options structure const optsConfig = { user: { required: true, help: 'Specify the user name for authentication.' }, all: { short: 'a', flag: true, help: 'Process all available items (boolean flag).' }, host: { short: 'h', default: 'localhost', help: 'Target host address for connection.' }, input: { short: 'i', multi: true, help: 'Input file paths (can be specified multiple times).' }, r: { flag: true, help: 'Enable recursive mode for file operations.' }, db: { default: 'test', help: 'Database name to connect to, defaults to \'test\'.' }, out: { short: 'o', type: options.type.file.open.write(), help: 'Output file path with write access.' } }; // Simulate command line arguments for demonstration purposes. // In a real application, this would typically be `process.argv.slice(2)`. const simulatedArgv = [ '--user=joe', '-a', '--host', 'www.example.com', 'output.txt', '-i', 'file1.txt', '--input', 'file2.txt', '-o', 'out.txt' ]; // Parse the arguments based on the defined configuration const result = options.parse(optsConfig, simulatedArgv); console.log('--- Parsed Options and Arguments ---'); console.log(JSON.stringify(result, null, 2)); // Generate and log the help screen based on the same configuration console.log('\n--- Generated Help Screen ---'); options.help(optsConfig, { output: console.log, columns: 80, paddingLeft: 2 });
Debug
Known issues
gotchaWhen `options.parse()` is called without an `error` callback, any parsing errors (e.g., missing required options, invalid types) will cause an exception to be thrown, terminating the process. This default behavior might not be suitable for all applications.
fix
Pass an `error` callback function as the second or third argument to `options.parse(opts, argv?, error?)` to handle errors programmatically, e.g., `options.parse(opts, (err) => console.error(err.message));`.
affects: >=0.1.0
gotchaThe `default` option should not be used in conjunction with `required: true` or `flag: true`. A default value implies the option is not strictly required, and `flag: true` options do not take values, rendering a default value meaningless for them.
fix
Ensure logical consistency in option definitions. For flags, omit `default`. For required options, `default` should only be considered if the 'required' state implies a non-null default, which can be confusing. Typically, remove `default` from `required: true` options.
affects: >=0.1.0
gotchaIf the `showHelp: true` option is defined for a specific flag, and `flag` is not explicitly set in the option definition, `options-parser` will implicitly set `flag: true` for that option. This can lead to unexpected behavior if you intended the option to take a value.
fix
Always explicitly define `flag: true` or `flag: false` for options, especially when using `showHelp`, to ensure the parser behaves as expected regarding value expectations.
affects: >=0.1.0
breakingAs a package still under version 1.0.0 (currently 0.4.0), API surfaces, especially related to type validation (`options.type`) or the structure of option definitions, might undergo breaking changes in future minor versions without strictly adhering to semantic versioning. Always review release notes when upgrading.
fix
Consult the `options-parser` GitHub repository for release notes and changelogs before upgrading to new minor versions (e.g., 0.4.x to 0.5.x) to identify and adapt to any potential API changes.
affects: <1.0.0
Errors
Common errors & fixes
ReferenceError: options is not defined
The `options` variable was not properly initialized via `require('options-parser')` before being used.
fix
Add `const options = require('options-parser');` at the top of your file to import the module.
TypeError: options.parse is not a function
This error typically occurs when attempting to use ESM `import` syntax or destructuring assignment with a CommonJS module, or if the `options` variable was not assigned the correct module export.
fix
Ensure you are using `const options = require('options-parser');` and accessing `options.parse` as a method on the `options` object.
Option 'user' is required but not present
An option defined with `required: true` in your configuration was not provided in the command-line arguments when `options.parse()` was called.
fix
Supply the missing required option in the command line (e.g., `--user=yourname`) or adjust your option definition if it's not truly required for all use cases.
Unknown option: --unrecognized-flag
A command-line option was provided (e.g., `--unrecognized-flag`) that is not defined in the `opts` object passed to `options.parse()`.
fix
Either define the `unrecognized-flag` option in your `opts` configuration object, or ensure that only expected and defined options are passed on the command line.
Upgrade
Version history
0.4.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
2 hits · last 30 days
node
2
Resources
githubhttps://github.com/janus-toendering/options-parser ↗
packagehttps://www.npmjs.com/package/options-parser ↗