0
# nopt
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: nopt
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install nopt`
10

11
## Core Imports
12

13
```javascript
14
const nopt = require("nopt");
15
```
16

17
ESM:
18

19
```javascript
20
import nopt from "nopt";
21
```
22

23
For non-singleton library API:
24

25
```javascript
26
const { lib } = require("nopt");
27
// or
28
const lib = require("nopt/lib/nopt-lib");
29
```
30

31
## Basic Usage
32

33
```javascript
34
const nopt = require("nopt");
35
const path = require("path");
36

37
// Define option types and shorthands
38
const knownOpts = {
39
  "verbose": Boolean,
40
  "output": path,
41
  "count": Number,
42
  "files": [String, Array]
43
};
44

45
const shortHands = {
46
  "v": ["--verbose"],
47
  "o": ["--output"],
48
  "c": ["--count"]
49
};
50

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

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

58
## Architecture
59

60
nopt is built around several key components:
61

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

69
## Capabilities
70

71
### Argument Parsing
72

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

75
```javascript { .api }
76
function nopt(
77
  types?: object,
78
  shorthands?: object, 
79
  args?: string[],
80
  slice?: number
81
): ParsedOptions;
82

83
interface ParsedOptions {
84
  [key: string]: any;
85
  argv: {
86
    remain: string[];    // Arguments after option parsing
87
    cooked: string[];    // Arguments after shorthand expansion
88
    original: string[];  // Original arguments
89
  };
90
}
91
```
92

93
[Argument Parsing](./argument-parsing.md)
94

95
### Data Cleaning and Validation
96

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

99
```javascript { .api }
100
function clean(
101
  data: object,
102
  types?: object,
103
  typeDefs?: object
104
): void;
105
```
106

107
[Data Cleaning](./data-cleaning.md)
108

109
### Type System
110

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

113
```javascript { .api }
114
const typeDefs: {
115
  String: { type: String, validate: Function },
116
  Boolean: { type: Boolean, validate: Function },
117
  Number: { type: Number, validate: Function },
118
  Date: { type: Date, validate: Function },
119
  url: { type: "url", validate: Function },
120
  path: { type: "path", validate: Function },
121
  Stream: { type: Stream, validate: Function },
122
  Array: { type: Array }
123
};
124
```
125

126
[Type System](./type-system.md)
127

128
### Library API
129

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

132
```javascript { .api }
133
const lib: {
134
  nopt: (args: string[], options?: NoptOptions) => ParsedOptions,
135
  clean: (data: object, options?: CleanOptions) => void,
136
  parse: (args: string[], data: object, remain: string[], options?: ParseOptions) => void,
137
  validate: (data: object, key: string, value: any, type: any, options?: ValidateOptions) => boolean,
138
  resolveShort: (arg: string, ...rest: any[]) => string[] | null,
139
  typeDefs: object
140
};
141

142
interface NoptOptions {
143
  types?: object;
144
  shorthands?: object;
145
  typeDefs?: object;
146
  invalidHandler?: Function | false;
147
  unknownHandler?: Function | false;
148
  abbrevHandler?: Function | false;
149
  typeDefault?: any[];
150
  dynamicTypes?: Function;
151
}
152
```
153

154
[Library API](./library-api.md)
155

156
### CLI Usage
157

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

160
```bash { .api }
161
# Installation provides the 'nopt' binary
162
npm install -g nopt
163

164
# Interactive testing
165
nopt --num 42 --bool --str "hello" --file ~/config.json
166
```
167

168
[CLI Usage](./cli-usage.md)
169

170
## Types
171

172
```javascript { .api }
173
// Core type validator interface
174
interface TypeValidator {
175
  type: any;
176
  validate?: (data: object, key: string, value: any) => boolean | void;
177
}
178

179
// Main parsing result interface  
180
interface ParsedOptions {
181
  [key: string]: any;
182
  argv: {
183
    remain: string[];    // Arguments after option parsing
184
    cooked: string[];    // Arguments after shorthand expansion
185
    original: string[];  // Original arguments
186
  };
187
}
188

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