{"id":13720,"library":"oppa","title":"Oppa Argument Parser","description":"Oppa is a typesafe options and arguments parser for Node.js, designed for command-line interfaces. It provides a fluent API for defining command-line arguments, including support for long/short names, aliases, boolean flags (with `--no-` prefix auto-handling), multi-value arguments, and custom validators. A key differentiator is its strong TypeScript integration, which ensures the parsed result is fully type-checked at compile-time, eliminating common runtime errors associated with parsing untyped arguments. It also automatically generates comprehensive `--help` and `--version` output. The current stable version is 0.4.0, released in June 2021, indicating a slower release cadence. It requires Node.js >=10, with specific build fixes for Node.js 10 in versions 0.3.3 and later.","status":"maintenance","version":"0.4.0","language":"javascript","source_language":"en","source_url":"https://github.com/grantila/oppa","tags":["javascript","oppa","argument","option","parser","options","arguments","typescript"],"install":[{"cmd":"npm install oppa","lang":"bash","label":"npm"},{"cmd":"yarn add oppa","lang":"bash","label":"yarn"},{"cmd":"pnpm add oppa","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Primary export for creating a new parser instance. While CommonJS `require` might work with older Node.js versions, ESM `import` is the recommended pattern, especially for TypeScript projects.","wrong":"const { oppa } = require('oppa')","symbol":"oppa","correct":"import { oppa } from 'oppa'"},{"note":"Type export for the Oppa instance itself, useful for type hinting or extending the parser configuration.","symbol":"Oppa","correct":"import { Oppa } from 'oppa'"},{"note":"Type helper to infer the exact TypeScript type of the parsed options object from an oppa instance, leveraging the parser's configuration.","symbol":"TypeOf","correct":"import { TypeOf } from 'oppa'"}],"quickstart":{"code":"import { oppa } from 'oppa';\n\nconst cliArgs = process.argv.slice(2); // Get actual CLI arguments\n\nconst parser = oppa({\n    name: 'myapp',\n    version: '1.2.3',\n    usage: 'myapp [options] <files...>',\n    description: 'A utility for file operations.',\n    noExit: true, // Prevent process exit for better testing/embedding\n    throwOnError: true // Throw errors instead of printing help and exiting\n})\n.add({\n    name: 'file',\n    alias: 'f',\n    type: 'string',\n    description: 'The primary file to process.',\n    defaultValue: 'default.txt'\n})\n.add({\n    name: 'retry',\n    alias: 'r',\n    type: 'number',\n    description: 'Number of retries before failing.',\n    defaultValue: 3,\n    validator: (v: number) => v >= 0\n})\n.add({\n    name: 'force',\n    type: 'boolean',\n    defaultValue: false,\n    description: 'Force operation, overwriting existing files.'\n})\n.add({\n    name: 'verbose',\n    alias: 'v',\n    type: 'boolean',\n    description: 'Enable verbose logging.',\n    noHelpAlias: true // Allows -v to be used here, if --version is also noVersionAlias\n});\n\ntry {\n    const result = parser.parse(cliArgs);\n\n    if (result.args.force) {\n        console.log('Force mode enabled.');\n    }\n    console.log(`Processing file: ${result.args.file}`);\n    console.log(`Retries configured: ${result.args.retry}`);\n    if (result.rest.length > 0) {\n        console.log(`Additional files: ${result.rest.join(', ')}`);\n    }\n    // Example of accessing type-safe properties\n    // result.args.retry.toFixed(0); // This is type-safe due to 'type: number'\n} catch (error) {\n    if (error instanceof Error) {\n        console.error(`CLI Error: ${error.message}`);\n    } else {\n        console.error('An unknown CLI error occurred.');\n    }\n    parser.showHelp(); // Show help on error if throwOnError is true\n    process.exit(1);\n}\n","lang":"typescript","description":"Demonstrates defining various argument types (string, number, boolean), setting defaults, applying validators, and handling parsed results with TypeScript safety. It also shows how to configure `noExit` and `throwOnError` for programmatic control."},"warnings":[{"fix":"Evaluate if the current feature set meets your application's needs. If active development, latest Node.js compatibility, or rapid bug fixes are critical, consider alternative argument parsers.","message":"The `oppa` package has not been updated since June 2021 (v0.4.0). While functional, it might not receive active maintenance for new Node.js features, security patches, or bug fixes promptly.","severity":"gotcha","affected_versions":">=0.4.0"},{"fix":"Initialize `oppa` with `{ noExit: true }` to prevent automatic process termination. You will then need to handle program termination or continuation explicitly in your application logic.","message":"By default, `oppa` will call `process.exit()` after printing help or version information, or on encountering an error (unless `throwOnError` is true). This can interrupt program flow in test environments or when embedding the parser in a larger application.","severity":"gotcha","affected_versions":"*"},{"fix":"Ensure your Node.js environment is version 10 or greater. Version 0.3.3 specifically addressed a build issue for Node.js 10, making it the minimum recommended version for stable Node.js 10 support.","message":"Oppa requires Node.js version 10 or higher. Using it with older versions (e.g., Node.js 8) may lead to unexpected errors or runtime failures due to ES2018 build targets.","severity":"gotcha","affected_versions":"<0.3.3"},{"fix":"Initialize `oppa` with `{ allowUnknown: true }` to collect unknown arguments in the `result.unknown` array instead of throwing an error. This allows your application to gracefully handle or ignore unrecognized input.","message":"The default behavior for unknown arguments (i.e., arguments not explicitly defined using `.add()`) is to throw an error. This can lead to abrupt program termination if users provide unexpected flags.","severity":"gotcha","affected_versions":"*"},{"fix":"Initialize `oppa` with `{ noHelpAlias: true }` and/or `{ noVersionAlias: true }` to prevent the automatic creation of `-h` and `-v` aliases, freeing them up for your custom argument definitions.","message":"The auto-generated `--help` and `--version` arguments implicitly create short aliases `-h` and `-v`. If you intend to use these short aliases for other custom arguments (e.g., `-v` for `verbose`), it will cause conflicts.","severity":"gotcha","affected_versions":">=0.2.0"}],"env_vars":null,"search_vec":"'0.3.3':120 '0.4.0':97 '10':110,117 '2021':101 'alias':36 'also':84 'api':24 'argument':2,10,30,48,82,125,129 'associ':78 'auto':43 'auto-handl':42 'automat':85 'boolean':37 'build':113 'cadenc':106 'check':69 'command':17,28 'command-lin':16,27 'common':75 'compil':72 'compile-tim':71 'comprehens':87 'current':93 'custom':50 'defin':26 'design':14 'differenti':54 'elimin':74 'ensur':61 'error':77 'fix':114 'flag':38 'fluent':23 'fulli':66 'generat':86 'handl':44 'help':88 'includ':31 'indic':102 'integr':59 'interfac':19 'javascript':123 'june':100 'key':53 'later':122 'line':18,29 'long/short':34 'multi':46 'multi-valu':45 'name':35 'node.js':13,109,116 'oppa':1,4,124 'option':8,126,128 'output':91 'pars':63,80 'parser':3,11,127 'prefix':41 'provid':21 'releas':98,105 'requir':108 'result':64 'runtim':76 'slower':104 'specif':112 'stabl':94 'strong':57 'support':32 'time':73 'type':68 'type-check':67 'typesaf':7 'typescript':58,130 'untyp':81 'valid':51 'valu':47 'version':90,95,119","created_at":"2026-04-20T01:55:57.594554+00:00","updated_at":"2026-04-20T01:55:57.594554+00:00","problems":[{"fix":"Ensure that optional arguments are checked for `undefined` before use, or provide `defaultValue` in your `.add()` definition. If it's a type mismatch, explicitly set the `type` property (e.g., `type: 'string'`) in your argument definition, and TypeScript will catch such errors at compile-time.","cause":"Attempting to call a method or access a property on a parsed option that is `undefined` because it was not provided in the arguments, or trying to use a method that doesn't exist on its inferred type (e.g., `toLowerCase()` on a boolean).","error":"TypeError: Cannot read properties of undefined (reading 'toLowerCase')"},{"fix":"Either define the argument using `.add()` in your parser configuration, or initialize `oppa` with `{ allowUnknown: true }` to collect unknown arguments in the `result.unknown` array instead of throwing an error.","cause":"The parser encountered a command-line argument (`--foo`) that was not explicitly defined using `.add()`, and the `allowUnknown` option is not enabled.","error":"Oppa: unknown argument: --foo"},{"fix":"Initialize `oppa` with `{ noExit: true }` to prevent automatic process termination. This allows test runners to complete without interruption and gives your application explicit control over exiting.","cause":"This error typically occurs in test runners when `oppa`'s default behavior of calling `process.exit()` is triggered (e.g., by `--help`, `--version`, or an error without `throwOnError`).","error":"Error: process.exit() was called"},{"fix":"Review the `validator` function for the specific argument and ensure it correctly handles expected input ranges or formats. Inform the user about the valid input for that argument in the help text.","cause":"A custom `validator` function defined for an argument returned `false` (or threw an error), indicating the provided value is invalid.","error":"Oppa: Argument validation failed for 'retries'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.5.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/grantila/oppa","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/oppa","openapi_spec":null,"status_page":null,"smithery":null,"categories":["http-networking","testing"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}