or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

argument-parsing.mdcli-usage.mddata-cleaning.mdindex.mdlibrary-api.mdtype-system.md
tile.json

tessl/npm-nopt

Option parsing for Node.js applications with type validation, shorthand expansion, and abbreviation matching.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/nopt@8.1.x

To install, run

npx @tessl/cli install tessl/npm-nopt@8.1.0

index.mddocs/

nopt

nopt is a powerful command-line option parser for Node.js that provides comprehensive type validation, shorthand expansion, and abbreviation matching. It supports both programmatic API usage and CLI integration, making it ideal for building robust command-line tools with sophisticated argument processing capabilities.

Package Information

  • Package Name: nopt
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install nopt

Core Imports

const nopt = require("nopt");

ESM:

import nopt from "nopt";

For non-singleton library API:

const { lib } = require("nopt");
// or
const lib = require("nopt/lib/nopt-lib");

Basic Usage

const nopt = require("nopt");
const path = require("path");

// Define option types and shorthands
const knownOpts = {
  "verbose": Boolean,
  "output": path,
  "count": Number,
  "files": [String, Array]
};

const shortHands = {
  "v": ["--verbose"],
  "o": ["--output"],
  "c": ["--count"]
};

// Parse command line arguments
const parsed = nopt(knownOpts, shortHands, process.argv, 2);

console.log(parsed);
// Example output: { verbose: true, output: "/path/to/file", count: 5, argv: {...} }

Architecture

nopt is built around several key components:

  • Singleton API: Main module exports providing global configuration and simple usage patterns
  • Library API: Non-singleton interface offering full control over parsing behavior and handlers
  • Type System: Comprehensive type validation with built-in validators for String, Number, Boolean, Date, URL, Path, Stream, and Array types
  • Shorthand Engine: Sophisticated shorthand expansion supporting single-character combinations and multi-word shorthands
  • Abbreviation Matching: Automatic expansion of partial option names to full option names
  • Error Handling: Configurable handlers for invalid values, unknown options, and abbreviation notifications

Capabilities

Argument Parsing

Core command-line argument parsing functionality with type validation and shorthand support. The main interface for processing command-line options.

function nopt(
  types?: object,
  shorthands?: object, 
  args?: string[],
  slice?: number
): ParsedOptions;

interface ParsedOptions {
  [key: string]: any;
  argv: {
    remain: string[];    // Arguments after option parsing
    cooked: string[];    // Arguments after shorthand expansion
    original: string[];  // Original arguments
  };
}

Argument Parsing

Data Cleaning and Validation

Validation and cleaning functionality for option data against type definitions. Useful for validating configuration objects and sanitizing user input.

function clean(
  data: object,
  types?: object,
  typeDefs?: object
): void;

Data Cleaning

Type System

Built-in type validators for common data types with extensible validation system for custom types. Provides automatic type coercion and validation.

const typeDefs: {
  String: { type: String, validate: Function },
  Boolean: { type: Boolean, validate: Function },
  Number: { type: Number, validate: Function },
  Date: { type: Date, validate: Function },
  url: { type: "url", validate: Function },
  path: { type: "path", validate: Function },
  Stream: { type: Stream, validate: Function },
  Array: { type: Array }
};

Type System

Library API

Non-singleton API providing full control over parsing behavior, error handling, and advanced features like dynamic type resolution.

const lib: {
  nopt: (args: string[], options?: NoptOptions) => ParsedOptions,
  clean: (data: object, options?: CleanOptions) => void,
  parse: (args: string[], data: object, remain: string[], options?: ParseOptions) => void,
  validate: (data: object, key: string, value: any, type: any, options?: ValidateOptions) => boolean,
  resolveShort: (arg: string, ...rest: any[]) => string[] | null,
  typeDefs: object
};

interface NoptOptions {
  types?: object;
  shorthands?: object;
  typeDefs?: object;
  invalidHandler?: Function | false;
  unknownHandler?: Function | false;
  abbrevHandler?: Function | false;
  typeDefault?: any[];
  dynamicTypes?: Function;
}

Library API

CLI Usage

Command-line demonstration tool showcasing nopt parsing capabilities with comprehensive examples and option types.

# Installation provides the 'nopt' binary
npm install -g nopt

# Interactive testing
nopt --num 42 --bool --str "hello" --file ~/config.json

CLI Usage

Types

// Core type validator interface
interface TypeValidator {
  type: any;
  validate?: (data: object, key: string, value: any) => boolean | void;
}

// Main parsing result interface  
interface ParsedOptions {
  [key: string]: any;
  argv: {
    remain: string[];    // Arguments after option parsing
    cooked: string[];    // Arguments after shorthand expansion
    original: string[];  // Original arguments
  };
}

// Handler function signatures
type InvalidHandler = (key: string, value: any, type: any, data: object) => void;
type UnknownHandler = (key: string, nextValue?: string) => void;
type AbbrevHandler = (short: string, long: string) => void;