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
```