0
# ts-interface-checker
1

2
ts-interface-checker is a TypeScript runtime validation library that validates data against TypeScript interfaces. It works with ts-interface-builder to generate runtime checkers from TypeScript interface definitions, enabling robust runtime type checking for JavaScript and TypeScript applications.
3

4
## Package Information
5

6
- **Package Name**: ts-interface-checker
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install ts-interface-checker`
10

11
## Core Imports
12

13
```typescript
14
// Main validation functionality
15
import { createCheckers, Checker, CheckerT } from "ts-interface-checker";
16

17
// Error handling
18
import { VError, IErrorDetail } from "ts-interface-checker";
19

20
// Type definition system
21
import { 
22
  TType, TName, TLiteral, TArray, TTuple, TUnion, TIntersection,
23
  TIface, TFunc, TOptional, TParam, TParamList, TProp,
24
  TEnumType, TEnumLiteral, RestType,
25
  name, lit, array, tuple, union, intersection,
26
  iface, func, opt, param, rest,
27
  enumtype, enumlit, indexKey,
28
  BasicType, ITypeSuite
29
} from "ts-interface-checker";
30

31
// Context system (advanced usage)
32
import { IContext, NoopContext, DetailContext } from "ts-interface-checker";
33
```
34

35
For CommonJS:
36

37
```javascript
38
// Main validation functionality
39
const { createCheckers, Checker, CheckerT } = require("ts-interface-checker");
40

41
// Complete import (all exports)
42
const {
43
  createCheckers, Checker, CheckerT,
44
  VError, IErrorDetail,
45
  TType, TName, TLiteral, TArray, TTuple, TUnion, TIntersection,
46
  TIface, TFunc, TOptional, TParam, TParamList, TProp,
47
  TEnumType, TEnumLiteral, RestType,
48
  name, lit, array, tuple, union, intersection,
49
  iface, func, opt, param, rest,
50
  enumtype, enumlit, indexKey,
51
  BasicType, ITypeSuite,
52
  IContext, NoopContext, DetailContext
53
} = require("ts-interface-checker");
54
```
55

56
## Basic Usage
57

58
```typescript
59
import { createCheckers } from "ts-interface-checker";
60
import myInterfaceTI from "./my-interface-ti"; // Generated by ts-interface-builder
61

62
// Create checkers from generated type suite
63
const { MyInterface } = createCheckers(myInterfaceTI);
64

65
// Validate data
66
MyInterface.check({ name: "Alice", age: 30 }); // OK
67
MyInterface.check({ name: "Bob" }); // Throws: "value.age is missing"
68

69
// Fast boolean check
70
if (MyInterface.test(someData)) {
71
  // Data is valid
72
  console.log("Valid data");
73
}
74

75
// Get detailed validation errors
76
const errors = MyInterface.validate(invalidData);
77
if (errors) {
78
  console.log("Validation errors:", errors);
79
}
80
```
81

82
## Architecture
83

84
ts-interface-checker is built around several key components:
85

86
- **Type Suite System**: Collections of type definitions that can be combined and cross-referenced
87
- **Checker Factory**: `createCheckers()` function that converts type suites into validation instances
88
- **Validation Engine**: Core checking logic with strict and non-strict modes
89
- **Error Reporting**: Detailed error messages with path information for debugging
90
- **Type Definition DSL**: Rich set of type builders for creating complex validation rules
91

92
## Capabilities
93

94
### Checker Creation and Management
95

96
Create checker instances from type suites generated by ts-interface-builder. Supports combining multiple type suites and cross-referencing between types.
97

98
```typescript { .api }
99
function createCheckers(...typeSuite: ITypeSuite[]): ICheckerSuite;
100

101
interface ICheckerSuite {
102
  [name: string]: Checker;
103
}
104

105
interface ITypeSuite {
106
  [name: string]: TType;
107
}
108
```
109

110
[Checker Creation](./checker-creation.md)
111

112
### Data Validation
113

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

116
```typescript { .api }
117
class Checker {
118
  check(value: any): void;
119
  test(value: any): boolean;
120
  validate(value: any): IErrorDetail[] | null;
121
  strictCheck(value: any): void;
122
  strictTest(value: any): boolean;
123
  strictValidate(value: any): IErrorDetail[] | null;
124
  setReportedPath(path: string): void;
125
  getType(): TType;
126
}
127

128
interface CheckerT<T> extends Checker {
129
  test(value: any): value is T;
130
  strictTest(value: any): value is T;
131
}
132
```
133

134
[Data Validation](./data-validation.md)
135

136
### Interface and Method Validation
137

138
Specialized validation for interface properties and method calls, including argument and return value validation.
139

140
```typescript { .api }
141
class Checker {
142
  getProp(prop: string): Checker;
143
  methodArgs(methodName: string): Checker;
144
  methodResult(methodName: string): Checker;
145
  getArgs(): Checker;
146
  getResult(): Checker;
147
}
148
```
149

150
[Interface and Method Validation](./interface-method-validation.md)
151

152
### Type Definition System
153

154
Comprehensive type definition DSL for creating complex type structures including interfaces, unions, arrays, functions, and enums.
155

156
```typescript { .api }
157
// Basic types
158
function name(value: string): TName;
159
function lit(value: any): TLiteral;
160
function array(typeSpec: TypeSpec): TArray;
161
function tuple(...typeSpec: TypeSpec[]): TTuple;
162
function union(...typeSpec: TypeSpec[]): TUnion;
163
function intersection(...typeSpec: TypeSpec[]): TIntersection;
164

165
// Interface and function types
166
function iface(bases: string[], props: {[name: string]: TOptional|TypeSpec}): TIface;
167
function func(resultSpec: TypeSpec, ...params: TParam[]): TFunc;
168
function opt(typeSpec: TypeSpec): TOptional;
169
function param(name: string, typeSpec: TypeSpec, isOpt?: boolean): TParam;
170

171
// Enum types
172
function enumtype(values: {[name: string]: string|number}): TEnumType;
173
function enumlit(name: string, prop: string): TEnumLiteral;
174
```
175

176
[Type Definition System](./type-definition-system.md)
177

178
### Error Handling
179

180
Comprehensive error reporting with path information, nested error details, and custom error types for validation failures.
181

182
```typescript { .api }
183
class VError extends Error {
184
  constructor(public path: string, message: string);
185
}
186

187
interface IErrorDetail {
188
  path: string;
189
  message: string;
190
  nested?: IErrorDetail[];
191
}
192
```
193

194
[Error Handling](./error-handling.md)
195

196
## Types
197

198
```typescript { .api }
199
// Core type specification
200
type TypeSpec = TType | string;
201

202
// Checker function type
203
type CheckerFunc = (value: any, ctx: IContext) => boolean;
204

205
// Abstract base for all type definitions
206
abstract class TType {
207
  abstract getChecker(suite: ITypeSuite, strict: boolean, allowedProps?: Set<string>): CheckerFunc;
208
}
209

210
// Special symbol for index signatures
211
const indexKey: unique symbol;
212
```