0
# Type System
1

2
Built-in type validators for common data types with extensible validation system for custom types. Provides automatic type coercion and validation for command-line arguments.
3

4
## Capabilities
5

6
### Built-in Type Definitions
7

8
Access to nopt's comprehensive type validation system through the `typeDefs` property.
9

10
```javascript { .api }
11
/**
12
 * Built-in type validator definitions
13
 */
14
const typeDefs: TypeDefinitions;
15

16
interface TypeDefinitions {
17
  String: TypeValidator;
18
  Boolean: TypeValidator;
19
  Number: TypeValidator;
20
  Date: TypeValidator;
21
  url: TypeValidator;
22
  path: TypeValidator;
23
  Stream: TypeValidator;
24
  Array: TypeValidator;
25
}
26

27
interface TypeValidator {
28
  type: any;
29
  validate?: (data: object, key: string, value: any) => boolean | void;
30
}
31
```
32

33
**Usage Examples:**
34

35
```javascript
36
const nopt = require("nopt");
37

38
// Access built-in type definitions
39
console.log(nopt.typeDefs);
40

41
// Use in option parsing
42
const types = {
43
  name: nopt.typeDefs.String.type,        // String
44
  count: nopt.typeDefs.Number.type,       // Number  
45
  enabled: nopt.typeDefs.Boolean.type,    // Boolean
46
  created: nopt.typeDefs.Date.type,       // Date
47
  homepage: nopt.typeDefs.url.type,       // URL validation
48
  config: nopt.typeDefs.path.type,        // Path with expansion
49
  output: nopt.typeDefs.Stream.type,      // Node.js Stream
50
  tags: nopt.typeDefs.Array.type          // Array marker
51
};
52
```
53

54
### String Type
55

56
Converts values to strings with validation.
57

58
```javascript { .api }
59
String: {
60
  type: String,
61
  validate: (data: object, key: string, value: any) => void
62
}
63
```
64

65
```javascript
66
// Usage
67
const types = { message: String };
68
const parsed = nopt(types, {}, ["--message", "hello world"]);
69
// Result: { message: "hello world" }
70

71
// Coercion examples
72
const data = { message: 123 };
73
nopt.clean(data, { message: String });
74
// data.message becomes "123"
75
```
76

77
### Boolean Type
78

79
Converts values to booleans with intelligent parsing.
80

81
```javascript { .api }
82
Boolean: {
83
  type: Boolean,
84
  validate: (data: object, key: string, value: any) => void
85
}
86
```
87

88
```javascript
89
// Usage patterns
90
const types = { verbose: Boolean };
91

92
// Various true values
93
nopt(types, {}, ["--verbose"]);           // true (flag present)
94
nopt(types, {}, ["--verbose", "true"]);   // true
95
nopt(types, {}, ["--verbose", "1"]);      // true
96

97
// Various false values  
98
nopt(types, {}, ["--no-verbose"]);        // false (negation)
99
nopt(types, {}, ["--verbose", "false"]);  // false
100
nopt(types, {}, ["--verbose", "0"]);      // false
101
nopt(types, {}, []);                      // undefined (not set)
102
```
103

104
### Number Type
105

106
Converts values to numbers with validation.
107

108
```javascript { .api }
109
Number: {
110
  type: Number,
111
  validate: (data: object, key: string, value: any) => boolean | void
112
}
113
```
114

115
```javascript
116
// Usage
117
const types = { port: Number };
118
const parsed = nopt(types, {}, ["--port", "8080"]);
119
// Result: { port: 8080 }
120

121
// Invalid number handling
122
nopt.invalidHandler = (key, val) => console.error(`Invalid number: ${val}`);
123
nopt(types, {}, ["--port", "not-a-number"]);
124
// Triggers invalidHandler
125
```
126

127
### Date Type
128

129
Converts values to Date objects.
130

131
```javascript { .api }
132
Date: {
133
  type: Date,
134
  validate: (data: object, key: string, value: any) => boolean | void
135
}
136
```
137

138
```javascript
139
// Usage  
140
const types = { created: Date };
141
const parsed = nopt(types, {}, ["--created", "2023-12-25"]);
142
// Result: { created: Date object for 2023-12-25 }
143

144
// Various date formats
145
nopt(types, {}, ["--created", "Dec 25, 2023"]);  // Valid
146
nopt(types, {}, ["--created", "2023-12-25T10:30:00Z"]);  // Valid
147
```
148

149
### URL Type
150

151
Validates URL strings.
152

153
```javascript { .api }
154
url: {
155
  type: "url",
156
  validate: (data: object, key: string, value: any) => boolean | void
157
}
158
```
159

160
```javascript
161
// Usage
162
const types = { homepage: nopt.typeDefs.url.type };
163
const parsed = nopt(types, {}, ["--homepage", "https://example.com"]);
164
// Result: { homepage: "https://example.com" }
165
```
166

167
### Path Type
168

169
Validates and resolves file system paths with tilde expansion.
170

171
```javascript { .api }
172
path: {
173
  type: "path", 
174
  validate: (data: object, key: string, value: any) => boolean | void
175
}
176
```
177

178
```javascript
179
// Usage
180
const types = { config: nopt.typeDefs.path.type };
181

182
// Tilde expansion
183
const parsed = nopt(types, {}, ["--config", "~/config.json"]);
184
// Result: { config: "/home/user/config.json" }
185

186
// Relative path resolution
187
nopt(types, {}, ["--config", "./config.json"]);
188
// Result: { config: "/current/dir/config.json" }
189
```
190

191
### Stream Type
192

193
Validates Node.js Stream objects.
194

195
```javascript { .api }
196
Stream: {
197
  type: Stream,
198
  validate: (data: object, key: string, value: any) => boolean | void
199
}
200
```
201

202
### Array Type
203

204
Marker for array types (no validation function).
205

206
```javascript { .api }
207
Array: {
208
  type: Array
209
}
210
```
211

212
```javascript
213
// Usage for multiple values
214
const types = { files: [String, Array] };
215

216
// Single value stays as string
217
nopt(types, {}, ["--files", "single.txt"]);
218
// Result: { files: "single.txt" }
219

220
// Multiple values become array
221
nopt(types, {}, ["--files", "file1.txt", "--files", "file2.txt"]);
222
// Result: { files: ["file1.txt", "file2.txt"] }
223
```
224

225
### Custom Type Definitions
226

227
Create custom validators for specialized data types.
228

229
```javascript
230
// Custom type example
231
const customTypes = {
232
  ...nopt.typeDefs,
233
  port: {
234
    type: "port",
235
    validate: function(data, key, val) {
236
      const num = parseInt(val);
237
      if (!isNaN(num) && num > 0 && num <= 65535) {
238
        data[key] = num;
239
        return true;
240
      }
241
      return false;
242
    }
243
  },
244
  email: {
245
    type: "email",
246
    validate: function(data, key, val) {
247
      const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
248
      if (emailRegex.test(val)) {
249
        data[key] = val.toLowerCase();
250
        return true;
251
      }
252
      return false;
253
    }
254
  }
255
};
256

257
// Use custom types
258
const types = { 
259
  server: "port",
260
  contact: "email" 
261
};
262

263
const result = nopt(types, {}, ["--server", "8080", "--contact", "USER@EXAMPLE.COM"], {
264
  typeDefs: customTypes
265
});
266
// Result: { server: 8080, contact: "user@example.com" }
267
```
268

269
## Types
270

271
```javascript { .api }
272
// Core type validator interface
273
interface TypeValidator {
274
  type: any;
275
  validate?: (data: object, key: string, value: any) => boolean | void;
276
}
277

278
// Validation function signature
279
type ValidatorFunction = (data: object, key: string, value: any) => boolean | void;
280

281
// Type definition registry
282
interface TypeDefinitions {
283
  [typeName: string]: TypeValidator;
284
}
285
```