0
# Data Validation
1

2
Core validation functionality with multiple validation modes, detailed error reporting, and TypeScript type guard support.
3

4
## Capabilities
5

6
### Basic Validation Methods
7

8
Core validation methods for checking data against type definitions.
9

10
```typescript { .api }
11
/**
12
 * Check that the given value satisfies this checker's type, or throw Error
13
 * @param value - Value to validate
14
 * @throws VError if validation fails
15
 */
16
check(value: any): void;
17

18
/**
19
 * A fast check for whether or not the given value satisfies this Checker's type.
20
 * Returns true or false, does not produce an error message, and is fast on both success and failure.
21
 * @param value - Value to test
22
 * @returns true if valid, false otherwise
23
 */
24
test(value: any): boolean;
25

26
/**
27
 * Returns a non-empty array of error objects describing errors if the given value
28
 * does not satisfy this Checker's type, or null if it does.
29
 * @param value - Value to validate
30
 * @returns Array of error details or null if valid
31
 */
32
validate(value: any): IErrorDetail[] | null;
33
```
34

35
**Usage Examples:**
36

37
```typescript
38
import { createCheckers } from "ts-interface-checker";
39
import userTypes from "./user-ti";
40

41
const { User } = createCheckers(userTypes);
42

43
// Basic validation - throws on failure
44
try {
45
  User.check({ name: "Alice", age: 30 }); // OK
46
  User.check({ name: "Bob" }); // Throws: "value.age is missing"
47
} catch (error) {
48
  console.error(error.message);
49
}
50

51
// Fast boolean test
52
const data1 = { name: "Charlie", age: 25 };
53
const data2 = { name: "Dave" };
54

55
if (User.test(data1)) {
56
  console.log("data1 is valid");
57
}
58
if (!User.test(data2)) {
59
  console.log("data2 is invalid");
60
}
61

62
// Detailed error information
63
const errors = User.validate(data2);
64
if (errors) {
65
  errors.forEach(error => {
66
    console.log(`${error.path}: ${error.message}`);
67
  });
68
}
69
```
70

71
### Strict Validation Methods
72

73
Strict validation ensures objects and tuples have no extra members, preventing backward compatibility issues.
74

75
```typescript { .api }
76
/**
77
 * Check that the given value satisfies this checker's type strictly.
78
 * This checks that objects and tuples have no extra members.
79
 * @param value - Value to validate
80
 * @throws VError if validation fails
81
 */
82
strictCheck(value: any): void;
83

84
/**
85
 * A fast strict check for whether or not the given value satisfies this Checker's type.
86
 * @param value - Value to test  
87
 * @returns true if valid, false otherwise
88
 */
89
strictTest(value: any): boolean;
90

91
/**
92
 * Returns error details for strict validation failures
93
 * @param value - Value to validate
94
 * @returns Array of error details or null if valid
95
 */
96
strictValidate(value: any): IErrorDetail[] | null;
97
```
98

99
**Usage Examples:**
100

101
```typescript
102
const userData = {
103
  name: "Alice",
104
  age: 30,
105
  extra: "not allowed" // Extra property
106
};
107

108
// Regular validation allows extra properties
109
User.check(userData); // OK
110

111
// Strict validation rejects extra properties
112
try {
113
  User.strictCheck(userData); // Throws: "value.extra is extraneous"
114
} catch (error) {
115
  console.error(error.message);
116
}
117

118
// Strict boolean test
119
if (!User.strictTest(userData)) {
120
  console.log("Data has extra properties");
121
}
122
```
123

124
### Type Guard Support
125

126
TypeScript type guard functionality through CheckerT interface.
127

128
```typescript { .api }
129
/**
130
 * Typed checker interface with type guard functionality
131
 */
132
interface CheckerT<T> extends Checker {
133
  test(value: any): value is T;
134
  strictTest(value: any): value is T;
135
}
136
```
137

138
**Usage Examples:**
139

140
```typescript
141
import { createCheckers, CheckerT } from "ts-interface-checker";
142
import { User } from "./user"; // TypeScript interface
143
import userTypes from "./user-ti";
144

145
const checkers = createCheckers(userTypes) as {
146
  User: CheckerT<User>
147
};
148

149
const unknownData: unknown = { name: "Alice", age: 30 };
150

151
// Type guard narrows unknown to User type
152
if (checkers.User.test(unknownData)) {
153
  // TypeScript knows unknownData is User type
154
  console.log(unknownData.name); // No type error
155
  console.log(unknownData.age);  // No type error
156
}
157

158
// Strict type guard
159
if (checkers.User.strictTest(unknownData)) {
160
  // TypeScript knows unknownData is User type with no extra properties
161
  console.log(unknownData.name);
162
}
163
```
164

165
### Path Reporting
166

167
Customize error path reporting for better debugging context.
168

169
```typescript { .api }
170
/**
171
 * Set the path to report in errors, instead of the default "value"
172
 * @param path - Custom path name for error reporting
173
 */
174
setReportedPath(path: string): void;
175
```
176

177
**Usage Examples:**
178

179
```typescript
180
const { User } = createCheckers(userTypes);
181

182
// Default error path
183
try {
184
  User.check({ name: "Alice" }); // Throws: "value.age is missing"
185
} catch (error) {
186
  console.error(error.message);
187
}
188

189
// Custom error path
190
User.setReportedPath("user");
191
try {
192
  User.check({ name: "Bob" }); // Throws: "user.age is missing"
193
} catch (error) {
194
  console.error(error.message);
195
}
196
```
197

198
### Type Information Access
199

200
Access the underlying type definition from a Checker instance.
201

202
```typescript { .api }
203
/**
204
 * Return the type for which this is a checker
205
 * @returns The underlying TType instance
206
 */
207
getType(): TType;
208
```
209

210
**Usage Examples:**
211

212
```typescript
213
const { User } = createCheckers(userTypes);
214
const userType = User.getType();
215

216
// Can be used to introspect type structure
217
console.log(userType instanceof TIface); // true for interface types
218
```