0
# Data Cleaning and Validation
1

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

4
## Capabilities
5

6
### Clean Function
7

8
Validates and cleans existing option data according to type definitions.
9

10
```javascript { .api }
11
/**
12
 * Clean and validate existing option data against type definitions
13
 * @param data - Object containing option data to clean
14
 * @param types - Object defining expected types for each option
15
 * @param typeDefs - Type validator definitions (optional, defaults to nopt.typeDefs)
16
 */
17
function clean(
18
  data: object,
19
  types?: object,
20
  typeDefs?: object
21
): void;
22
```
23

24
**Usage Examples:**
25

26
```javascript
27
const nopt = require("nopt");
28
const path = require("path");
29

30
// Define types
31
const types = {
32
  verbose: Boolean,
33
  output: path,
34
  count: Number,
35
  tags: [String, Array]
36
};
37

38
// Clean dirty data
39
const dirtyData = {
40
  verbose: "true",      // String that should be boolean
41
  output: "~/output",   // Path with tilde expansion needed
42
  count: "42",          // String that should be number
43
  tags: "javascript",   // String that could be array
44
  unknown: "value"      // Unknown property
45
};
46

47
// Clean the data (modifies in place)
48
nopt.clean(dirtyData, types);
49

50
console.log(dirtyData);
51
// Result: {
52
//   verbose: true,
53
//   output: "/home/user/output", 
54
//   count: 42,
55
//   tags: "javascript",
56
//   // 'unknown' property removed
57
//   argv: { remain: [], cooked: [], original: [] }
58
// }
59
```
60

61
### Validation Behavior
62

63
**Type Coercion:**
64
```javascript
65
const data = { count: "123", flag: "false" };
66
const types = { count: Number, flag: Boolean };
67

68
nopt.clean(data, types);
69
// data.count becomes 123 (number)
70
// data.flag becomes false (boolean)
71
```
72

73
**Array Handling:**
74
```javascript
75
const data = { 
76
  tags: "single-tag",
77
  items: ["item1", "item2"]
78
};
79
const types = { 
80
  tags: [String, Array],
81
  items: [String, Array] 
82
};
83

84
nopt.clean(data, types);
85
// data.tags remains "single-tag" (valid string)
86
// data.items remains ["item1", "item2"] (valid array)
87
```
88

89
**Invalid Value Handling:**
90
```javascript
91
const nopt = require("nopt");
92

93
// Set up invalid handler
94
nopt.invalidHandler = function(key, value, type, data) {
95
  console.error(`Cannot convert '${value}' to ${type} for option '${key}'`);
96
  delete data[key]; // Remove invalid property
97
};
98

99
const data = { count: "not-a-number" };
100
const types = { count: Number };
101

102
nopt.clean(data, types);
103
// Logs error message and removes 'count' property
104
```
105

106
### Custom Type Definitions
107

108
```javascript
109
// Using custom type definitions
110
const customTypeDefs = {
111
  ...nopt.typeDefs,
112
  Email: {
113
    type: "Email",
114
    validate: function(data, key, val) {
115
      const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
116
      if (emailRegex.test(val)) {
117
        data[key] = val.toLowerCase();
118
        return true;
119
      }
120
      return false;
121
    }
122
  }
123
};
124

125
const data = { email: "USER@EXAMPLE.COM" };
126
const types = { email: "Email" };
127

128
nopt.clean(data, types, customTypeDefs);
129
// data.email becomes "user@example.com"
130
```
131

132
## Types
133

134
```javascript { .api }
135
// Type definition interface
136
interface TypeValidator {
137
  type: any;
138
  validate?: (data: object, key: string, value: any) => boolean | void;
139
}
140

141
// Built-in type definitions
142
interface TypeDefinitions {
143
  String: TypeValidator;
144
  Boolean: TypeValidator; 
145
  Number: TypeValidator;
146
  Date: TypeValidator;
147
  url: TypeValidator;
148
  path: TypeValidator;
149
  Stream: TypeValidator;
150
  Array: TypeValidator;
151
}
152

153
// Handler function for invalid values
154
type InvalidHandler = (key: string, value: any, type: any, data: object) => void;
155
```