basic-args

Basic argument parsing library using yargs-parser with built-in help screen

Features

• Flagged arguments (e.g., --version) with types, descriptions, aliases, and defaults.
• Positional arguments
• Help screen: Automatically generated with positionals, options, and user-defined usage examples.
• Extraneous arguments are stored in the _ property unless errorOnExtra is true.
• Validation: Optional validate hook to check yargs parsed arguments before returning.
• Preprocessing: Optional preprocess hook to modify raw arguments before parsing.

Installation

npm install basic-args

Usage

See index.d.ts for the full API.

CommonJS Import

const args = require('basic-args')({
  name: 'basic-args-example',
  version: '1.0.0',
  description: 'A basic example of basic-args',
  options: {
    version: { type: String, description: 'Version to connect as', alias: 'v' },
    port: { type: Number, description: 'Port to listen on', default: 25565 },
    online: { type: Boolean, description: 'Whether to run in online mode' },
    path: { type: String, description: 'Path to the server directory', default: '.' }
  },
  positionals: [
    { name: 'input', type: String, description: 'Input file path' },
    { name: 'output', type: String, description: 'Output file path' }
  ],
  examples: [
    'basic-args-example <inputFile> <outputFile> [--version str]',
    'basic-args-example input.txt output.txt --version 1.16         Start server with version 1.16'
  ]
})

console.log(args)

Running the above with basic-args-example input.txt output.txt --version 1.16 (or using -v 1.16) yields:

{ input: 'input.txt', output: 'output.txt', version: '1.16', port: 25565, online: false, path: '.' }

Help Screen

Running with --help (or the configured helpCommand) displays the help screen:

basic-args-example - v1.0.0
A basic example of basic-args

Positionals:
  input     Input file path
  output    Output file path

Options:
  --version, -v Version to connect as
  --port        Port to listen on  (default: 25565)
  --online      Whether to run in online mode
  --path        Path to the server directory  (default: .)

Usage:
  basic-args-example input.txt output.txt --version 1.16  Start server with version 1.16
  basic-args-example input.txt output.txt --version 1.16         Start server with version 1.16

Configuration

• name: Program name (shown in help).
• version: Program version (shown in help).
• description: Program description (shown in help).
• options: Object mapping option names to { type, description, alias?, default? }.
• positionals: Array of { name, type, description? } for required positional arguments.
• examples: Array of strings for usage examples in the help screen.
• errorOnExtra: If true, errors on unrecognized options (default: false).
• throwOnError: If true, throws errors instead of exiting (default: false).
• helpCommand: Command to trigger help screen (default: help).
• preprocess: Function to preprocess raw arguments.
• validate: Function to validate parsed arguments.

Notes

• Positional arguments are required and must match the order and number defined in positionals.
• Extra positional arguments are stored in _ unless errorOnExtra is true.
• Boolean options don’t accept values (e.g., --online is true, not --online true). Use String type for custom handling.
• Use the second argument to pass custom args instead of process.argv:

require('basic-args')(options, ['--version', '1.16'])

ES6 Import

import basicArg from 'basic-args'
const args = basicArg({
  name: 'basic-args-example',
  version: '1.0.0',
  description: 'A basic example of basic-args',
  throwOnError: false,
  helpCommand: 'help',
  options: {
    version: { type: String, description: 'Version to connect as', alias: 'v' },
    port: { type: Number, description: 'Port to listen on', default: 25565 },
    online: { type: Boolean, description: 'Whether to run in online mode' },
    path: { type: String, description: 'Path to the server directory', default: '.' }
  },
  positionals: [
    { name: 'input', type: String, description: 'Input file path' },
    { name: 'output', type: String, description: 'Output file path' }
  ],
  examples: [
    'basic-args-example input.txt output.txt --version 1.16  Start server with version 1.16',
    'basic-args-example input.txt output.txt --port 8080      Start server on port 8080',
    'basic-args-example input.txt output.txt --online        Start server in online mode'
  ]
})

Testing

npm test

History

See history

1.5.0

• Add positional arguments support (#8) (thanks @extremeheat)

1.4.1

• Fix string/number parsing (#6) (thanks @extremeheat)

1.4.0

• Add a preprocess() hook before any parsing is done by basic-args (thanks @extremeheat)
• Exit normally when using --help argument (thanks @extremeheat)
• Create commands.yml workflow (thanks @extremeheat)

1.3.0

• Add a validate function
  • This allows users to validate the output (and raise the help screen on error) before returning the result arg dict, where it wouldn't be possible to print the help screen again.

1.2.0

• Extraneous arguments are stored in the _ index of the output. The nested _ contains positionals.

1.1.0

• Add command alias implementation

1.0.0

Initial