Tiny Opts Parser

0.0.3 verified Thu Apr 23 auth: no javascript

tiny-opts-parser is an extremely lightweight and minimal command-line interface (CLI) options parser for JavaScript and TypeScript applications. Currently at version 0.0.3, it focuses on providing core argument parsing functionality without the overhead or extensive feature sets found in more comprehensive libraries like Commander, Minimist, or Yargs. It takes an array of strings (typically `process.argv.slice(2)` from Node.js) and an optional configuration object, returning a structured object representing parsed arguments and options. Its design prioritizes simplicity and a small footprint, making it suitable for projects where bundle size or minimal dependency count is critical. Given its very early version number, its release cadence is likely slow and focused on stability rather than rapid feature additions, and users should anticipate a deliberate pace of development. It aims to produce an output format consistent with popular CLI parsers, simplifying migration or usage for developers familiar with other tools.

Common errors

error TypeError: parser is not a function ↓

cause Incorrectly importing the default export or attempting to destructure it as a named export in CommonJS.

fix

For CommonJS, use const parser = require('tiny-opts-parser');. For ESM, use import parser from 'tiny-opts-parser';.

error Argument 'myOption' is a string, expected number. ↓

cause The parser returns values as strings by default, and your application code expects a numeric type.

fix

Explicitly convert the parsed value to a number: const myOption = parseInt(parsedOptions.myOption, 10);.

Warnings

gotcha Early-stage development: Version 0.0.3 indicates that `tiny-opts-parser` is in early development. While functional, users should be aware that future minor releases may introduce breaking changes without explicit major version bumps, as stability guarantees are typically established in higher versions. ↓

fix Pin exact versions of the package in `package.json` (e.g., `"tiny-opts-parser": "0.0.3"`) and thoroughly review any changelog before updating to a new minor version.

gotcha Limited feature set: As a 'tiny' parser, `tiny-opts-parser` deliberately omits advanced CLI features such as built-in command chaining, extensive type validation, or auto-generated help messages. It focuses solely on basic argument parsing. ↓

fix For complex CLI applications requiring rich features, consider more comprehensive libraries like `commander`, `minimist`, or `yargs`. If `tiny-opts-parser` is chosen, be prepared to implement additional logic for validation, help, and command handling manually.

gotcha Implicit type handling: The parser might treat all option values as strings by default, even if they appear to be numbers or booleans (e.g., `--count 10` might result in `count: '10'`). Explicit type coercion may be required in application logic. ↓

fix Manually convert parsed option values to their desired types within your application code (e.g., `parseInt(parsed.count, 10)`, `parsed.myFlag === 'true'`). Consult the documentation for any specific configuration options related to type handling.

gotcha Potential for dormant maintenance: The very low version number (0.0.3) and limited community activity could indicate that the project might not receive frequent updates, bug fixes, or security patches, which could be a concern for long-term projects. ↓

fix Evaluate your project's long-term maintenance needs and reliance on prompt updates. Consider contributing to the project, forking it, or migrating to a more actively maintained alternative if consistent updates and support are critical.

Install

npm install tiny-opts-parser

yarn add tiny-opts-parser

pnpm add tiny-opts-parser

Imports

parser

wrong

import { parser } from 'tiny-opts-parser';

correct

import parser from 'tiny-opts-parser';

The library uses a default export for its primary parser function.

parser

wrong

const { parser } = require('tiny-opts-parser');

correct

const parser = require('tiny-opts-parser');

CommonJS `require` also imports the default export directly.

Quickstart

Demonstrates parsing various CLI argument styles and accessing the resulting structured options object.

import parser from 'tiny-opts-parser';

// Simulate command line arguments as if `node myapp.js -a -bcd def xyz --abcd --foo=bar --num 123` was run
const argsFromCLI = ['-a', '-bcd', 'def', 'xyz', '--abcd', '--foo=bar', '--num', '123'];

// Parse the arguments array
const parsedOptions = parser(argsFromCLI);

console.log('Parsed Options:', parsedOptions);
/* Example output for the argsFromCLI above:
{
  _: ['xyz'],
  a: true,
  b: true,
  c: true,
  d: 'def',
  abcd: true,
  foo: 'bar',
  num: '123' // Note: '123' might be a string, not a number, depending on internal logic
}
*/

// A more practical example demonstrating access to parsed values
const myAppArgs = ['--env', 'production', '-p', '8080', 'serve', '--verbose'];
const parsedAppArgs = parser(myAppArgs);

console.log('Environment:', parsedAppArgs.env);      // Expected: production
console.log('Port:', parsedAppArgs.p);          // Expected: 8080
console.log('Command:', parsedAppArgs._[0]);     // Expected: serve
console.log('Verbose flag present:', parsedAppArgs.verbose); // Expected: true

// Accessing an environment variable (simulated) as part of an app's logic
const apiKey = parsedAppArgs.apiKey ?? process.env.APP_API_KEY ?? 'default-key';
console.log('API Key source:', apiKey === 'default-key' ? 'default' : 'CLI/Env');