tessl/npm-stdio

Standard input/output manager for Node.js with command-line parsing, async file reading, interactive terminal, and progress bars

—

Pending

Overview

Eval results

Files

Command Line Argument Parsing

Name: tessl/npm-stdio
Author: tessl

UNIX-like command-line argument parser with automatic help generation, comprehensive configuration options, and robust error handling.

Capabilities

Main Parsing Function

Parses command-line arguments according to configuration, with automatic help generation and error handling.

/**
 * Parse command-line arguments according to configuration
 * @param config - Configuration object defining available options
 * @param command - Command array (defaults to process.argv)
 * @param options - Execution options for error handling
 * @returns Parsed options and arguments, or null on failure
 */
function getopt(
  config: Config,
  command?: string[],
  options?: Options
): GetoptResponse | null;

Usage Examples:

import { getopt } from "stdio";

// Basic boolean options
const options = getopt({
  verbose: { key: 'v', description: 'Enable verbose output' },
  quiet: { key: 'q', description: 'Suppress output' }
});
// Command: node app.js -v
// Result: { verbose: true }
// Command: node app.js --help (automatically shows help and exits)

// Options with arguments
const options = getopt({
  output: { 
    key: 'o', 
    args: 1, 
    description: 'Output file path',
    required: true 
  },
  include: { 
    key: 'I', 
    args: 1, 
    multiple: true, 
    description: 'Include directories' 
  }
});
// Command: node app.js -o result.txt -I lib -I src file1.txt file2.txt
// Result: { output: 'result.txt', include: ['lib', 'src'], args: ['file1.txt', 'file2.txt'] }

// Default values and validation
const options = getopt({
  port: { 
    key: 'p', 
    args: 1, 
    default: '3000',
    description: 'Server port' 
  },
  _meta_: { 
    minArgs: 1, 
    maxArgs: 3 
  }
});

Configuration Interface

Defines available command-line options with their properties and constraints.

interface Config {
  [key: string]: {
    /** Single-letter short option (e.g., 'v' for -v) */
    key?: string;
    /** Help text description for this option */
    description?: string;
    /** Allow multiple occurrences of this option */
    multiple?: boolean;
    /** Expected number of arguments (number or "*" for variable) */
    args?: number | string;
    /** @deprecated Use 'required' instead */
    mandatory?: boolean;
    /** This option is required */
    required?: boolean;
    /** Default value if option not provided */
    default?: string | string[] | boolean;
    /** Maximum number of positional arguments (only in _meta_) */
    maxArgs?: number;
    /** Minimum number of positional arguments (only in _meta_) */
    minArgs?: number;
  } | boolean | undefined;
}

Special Configuration Keys:

_meta_: Configure positional argument constraints with minArgs, maxArgs, or args

Configuration Examples:

// Boolean flag
{ verbose: { key: 'v', description: 'Verbose output' } }

// Required option with argument
{ config: { key: 'c', args: 1, required: true, description: 'Config file' } }

// Multiple values
{ include: { key: 'I', args: 1, multiple: true, description: 'Include paths' } }

// Variable arguments
{ files: { args: '*', description: 'Input files' } }

// Positional argument constraints
{ _meta_: { minArgs: 1, maxArgs: 5 } }

Execution Options

Controls error handling and program behavior on parsing failures.

interface Options {
  /** Exit process on parsing failure (default: true) */
  exitOnFailure?: boolean;
  /** Throw exception on parsing failure (default: false) */
  throwOnFailure?: boolean;
  /** Print help message on parsing failure (default: true) */
  printOnFailure?: boolean;
}

Response Interface

Contains parsed options, arguments, and their values.

interface GetoptResponse {
  /** Parsed option values */
  [key: string]: string | number | boolean | Array<string | number | boolean>;
  /** Positional arguments (when present) */
  args?: string[];
}

Response Examples:

// Boolean options become true/false
{ verbose: true, quiet: false }

// Single arguments become strings
{ output: 'file.txt', port: '8080' }

// Multiple options become arrays
{ include: ['lib', 'src', 'test'] }

// Positional arguments
{ verbose: true, args: ['input.txt', 'output.txt'] }

Configuration Validation

Built-in validation ensures configuration correctness and prevents conflicts.

Reserved Options:

--help and -h are automatically handled for help display
Cannot be declared in configuration

Validation Rules:

Short keys must be single letters
Required options must be provided
Argument counts must match expectations
Multiple options must use multiple: true

Advanced Features

Automatic Help Generation

Help messages are automatically generated from configuration and displayed on -h or --help:

USAGE: node program.js [OPTION1] [OPTION2]... arg1 arg2...
The following options are supported:
  -v, --verbose          Enable verbose output
  -o, --output <ARG1>    Output file path (required)
  -I, --include <ARG1>   Include directories (multiple)

Error Handling

Comprehensive error handling with descriptive messages:

Unknown options: "Unknown option: --unknown"
Missing required: "Missing option: --output"
Wrong argument count: "Option --port requires 1 arguments, but 0 were provided"
Positional argument violations: "At least 2 positional arguments are required, but 1 were provided"

Flexible Argument Formats

Supports multiple argument formats:

# Separate arguments
node app.js --output file.txt --port 3000

# Equals format
node app.js --output=file.txt --port=3000

# Short option clusters
node app.js -vf file.txt  # equivalent to -v -f file.txt

# Mixed formats
node app.js -v --output=file.txt arg1 arg2

Install with Tessl CLI