0
# TypeBox
1
2
TypeBox is a runtime type builder that creates in-memory JSON Schema objects that infer as TypeScript types. It provides a unified type system that can be statically checked by TypeScript and runtime validated using standard JSON Schema validation, offering a comprehensive API for building complex schema types that match TypeScript's static type checking rules.
3
4
## Package Information
5
6
- **Package Name**: @sinclair/typebox
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @sinclair/typebox`
10
11
## Core Imports
12
13
```typescript
14
import { Type, Value, Static } from "@sinclair/typebox";
15
```
16
17
For individual namespace imports:
18
19
```typescript
20
import { Value } from "@sinclair/typebox/value";
21
import { TypeCompiler } from "@sinclair/typebox/compiler";
22
import { Runtime, Static } from "@sinclair/typebox/parser";
23
import { TypeSystem } from "@sinclair/typebox/system";
24
```
25
26
CommonJS:
27
28
```javascript
29
const { Type, Value, Static } = require("@sinclair/typebox");
30
```
31
32
## Basic Usage
33
34
```typescript
35
import { Type, Value, Static } from "@sinclair/typebox";
36
37
// Create a schema
38
const User = Type.Object({
39
name: Type.String(),
40
age: Type.Number({ minimum: 0 }),
41
email: Type.String({ format: "email" }),
42
isActive: Type.Optional(Type.Boolean())
43
});
44
45
// Infer TypeScript type
46
type UserType = Static<typeof User>;
47
48
// Runtime validation
49
const userData = { name: "Alice", age: 25, email: "alice@example.com" };
50
const isValid = Value.Check(User, userData); // true
51
Value.Assert(User, userData); // throws if invalid
52
53
// Create default values
54
const defaultUser = Value.Create(User);
55
// { name: "", age: 0, email: "", isActive: undefined }
56
```
57
58
## Architecture
59
60
TypeBox is built around several key components:
61
62
- **Type Builders**: Create JSON Schema-compatible type definitions with full TypeScript inference
63
- **Static Type System**: TypeScript utilities that infer types from schemas at compile time
64
- **Value Operations**: Runtime functions for validation, transformation, and value manipulation
65
- **Compilation System**: Optimized code generation for high-performance validation
66
- **Registry System**: Extensible validation and format registration for custom types
67
- **Transform System**: Bidirectional value encoding/decoding with type safety
68
69
## Capabilities
70
71
### Basic Type Creation
72
73
Core JSON Schema compatible types for primitive and structured data. These form the foundation of all TypeBox schemas.
74
75
```typescript { .api }
76
namespace Type {
77
function String(options?: StringOptions): TString;
78
function Number(options?: NumberOptions): TNumber;
79
function Boolean(options?: SchemaOptions): TBoolean;
80
function Array<T extends TSchema>(items: T, options?: ArrayOptions): TArray<T>;
81
function Object<T extends TProperties>(properties: T, options?: ObjectOptions): TObject<T>;
82
function Union<T extends TSchema[]>(...schemas: [...T]): TUnion<T>;
83
}
84
```
85
86
[Basic Types](./basic-types.md)
87
88
### Advanced Type System
89
90
TypeScript-inspired advanced types including utility types, conditional types, and template literals for complex schema composition.
91
92
```typescript { .api }
93
namespace Type {
94
function Partial<T extends TSchema>(schema: T): TPartial<T>;
95
function Pick<T extends TObject, K extends TUnion<TLiteral[]>>(schema: T, keys: K): TPick<T, K>;
96
function Omit<T extends TObject, K extends TUnion<TLiteral[]>>(schema: T, keys: K): TOmit<T, K>;
97
function Extends<L extends TSchema, R extends TSchema, T extends TSchema, F extends TSchema>(left: L, right: R, trueType: T, falseType: F): TExtends<L, R, T, F>;
98
function TemplateLiteral<T extends TTemplateLiteralKind[]>(kinds: [...T]): TTemplateLiteral<T>;
99
}
100
```
101
102
[Advanced Types](./advanced-types.md)
103
104
### JavaScript-Specific Types
105
106
Types that represent JavaScript runtime constructs like functions, constructors, dates, and other built-in objects.
107
108
```typescript { .api }
109
namespace Type {
110
function Function<P extends TSchema[], R extends TSchema>(parameters: [...P], returns: R): TFunction<P, R>;
111
function Constructor<P extends TSchema[], R extends TSchema>(parameters: [...P], returns: R): TConstructor<P, R>;
112
function Date(options?: DateOptions): TDate;
113
function Promise<T extends TSchema>(item: T): TPromise<T>;
114
function RegExp(source: string, flags?: string): TRegExp;
115
}
116
```
117
118
[JavaScript Types](./javascript-types.md)
119
120
### Value Operations
121
122
Runtime functions for validation, transformation, and manipulation of values against TypeBox schemas.
123
124
```typescript { .api }
125
namespace Value {
126
function Check<T extends TSchema>(schema: T, value: unknown): value is Static<T>;
127
function Assert<T extends TSchema>(schema: T, value: unknown): asserts value is Static<T>;
128
function Create<T extends TSchema>(schema: T): Static<T>;
129
function Cast<T extends TSchema>(schema: T, value: unknown): Static<T>;
130
function Clean<T extends TSchema>(schema: T, value: unknown): unknown;
131
}
132
```
133
134
[Value Operations](./value-operations.md)
135
136
### Schema Compilation
137
138
High-performance validation through schema compilation to optimized JavaScript code.
139
140
```typescript { .api }
141
namespace TypeCompiler {
142
function Compile<T extends TSchema>(schema: T): TypeCheck<T>;
143
function Code<T extends TSchema>(schema: T, options?: CodegenOptions): string;
144
}
145
146
interface TypeCheck<T extends TSchema> {
147
Check(value: unknown): value is Static<T>;
148
Errors(value: unknown): ValueErrorIterator;
149
}
150
```
151
152
[Compilation](./compilation.md)
153
154
### Transforms
155
156
Bidirectional value encoding and decoding with full type safety for data serialization and processing.
157
158
```typescript { .api }
159
namespace Type {
160
function Transform<T extends TSchema>(schema: T): TransformDecodeBuilder<T>;
161
}
162
163
interface TransformDecodeBuilder<T extends TSchema> {
164
Decode<U>(decode: (value: Static<T>) => U): TransformEncodeBuilder<T, U>;
165
}
166
167
interface TransformEncodeBuilder<T extends TSchema, U> {
168
Encode<V>(encode: (value: U) => V): TTransform<T, U>;
169
}
170
```
171
172
[Transforms](./transforms.md)
173
174
### Additional Namespaces
175
176
Parser, System, and specialized utilities for advanced schema management, recursive types, and system configuration.
177
178
```typescript { .api }
179
namespace Runtime {
180
function Parse<T extends TSchema>(schema: T, value: unknown): Static<T>;
181
function Check<T extends TSchema>(schema: T, value: unknown): value is Static<T>;
182
}
183
184
namespace TypeSystem {
185
function Policy(policy: Partial<TypeSystemPolicy>): void;
186
function GetPolicy(): TypeSystemPolicy;
187
}
188
189
namespace Type {
190
function Module<T extends TProperties>(properties: T): TModule<T>;
191
function Recursive<T extends TSchema>(callback: (thisType: TThis) => T): TRecursive<T>;
192
function Ref<T extends TSchema = TSchema>(ref: string): TRef<T>;
193
}
194
```
195
196
[Additional Namespaces](./additional-namespaces.md)
197
198
## Core Types
199
200
```typescript { .api }
201
// Base types
202
interface TSchema {
203
[Kind]: string;
204
[Hint]?: string;
205
type?: string;
206
const?: any;
207
enum?: any[];
208
default?: any;
209
title?: string;
210
description?: string;
211
examples?: any[];
212
}
213
214
interface SchemaOptions {
215
title?: string;
216
description?: string;
217
default?: any;
218
examples?: any[];
219
}
220
221
// Static type inference
222
type Static<T extends TSchema> = T extends TString ? string
223
: T extends TNumber ? number
224
: T extends TBoolean ? boolean
225
: T extends TArray<infer U> ? Static<U>[]
226
: T extends TObject<infer U> ? { [K in keyof U]: Static<U[K]> }
227
: unknown;
228
229
// Schema-specific types
230
interface TString extends TSchema {
231
type: 'string';
232
minLength?: number;
233
maxLength?: number;
234
pattern?: string;
235
format?: string;
236
}
237
238
interface TNumber extends TSchema {
239
type: 'number';
240
minimum?: number;
241
maximum?: number;
242
exclusiveMinimum?: number;
243
exclusiveMaximum?: number;
244
multipleOf?: number;
245
}
246
247
interface TBoolean extends TSchema {
248
type: 'boolean';
249
}
250
251
interface TArray<T extends TSchema> extends TSchema {
252
type: 'array';
253
items: T;
254
minItems?: number;
255
maxItems?: number;
256
uniqueItems?: boolean;
257
}
258
259
interface TObject<T extends TProperties> extends TSchema {
260
type: 'object';
261
properties: T;
262
required?: string[];
263
additionalProperties?: boolean;
264
}
265
266
type TProperties = Record<string, TSchema>;
267
```