TypeBox
JSONSchema Type Builder with Static Type Resolution for TypeScript
Install
$ npm install @sinclair/typebox --save
Overview
TypeBox is a type builder library that allows developers to compose complex in-memory JSONSchema objects that can be resolved to static TypeScript types. The schemas produced by TypeBox can be used directly as validation schemas or reflected upon by navigating the standard JSONSchema properties at runtime. TypeBox can be used as a simple tool to build complex schemas or integrated into RPC or REST services to help validate JSON data received over the wire.
TypeBox does not provide any mechanism for validating JSONSchema. Please refer to libraries such as AJV or similar to validate the schemas created with this library.
Requires TypeScript 3.8.3 and above.
License MIT
Contents
Example
The following shows the general usage.
import { Type, Static } from '@sinclair/typebox'
type Order = {
email: string,
address: string,
quantity: number,
option: 'pizza' | 'salad' | 'pie'
}
const Order = Type.Object({
email: Type.Format('email'),
address: Type.String(),
quantity: Type.Range(1, 99),
option: Type.Union(
Type.Literal('pizza'),
Type.Literal('salad'),
Type.Literal('pie')
)
})
console.log(JSON.stringify(Order, null, 2))
type TOrder = Static<typeof Order>
JSON.validate(Order, {
email: 'dave@domain.com',
address: '...',
quantity: 99,
option: 'pie'
})
Types
TypeBox provides many functions generate JSONschema data types. The following tables list the functions TypeBox provides and their respective TypeScript and JSONSchema equivalents.
TypeBox > TypeScript
Type | TypeBox | TypeScript |
---|
Optional | const T = Type.Object({ email: Type.Optional(Type.String()) }) | type T = { email?: string } |
Readonly | const T = Type.Object({ email: Type.Readonly(Type.String()) }) | type T = { readonly email: string } |
Literal | const T = Type.Literal(123) | type T = 123 |
String | const T = Type.String() | type T = string |
Number | const T = Type.Number() | type T = number |
Boolean | const T = Type.Boolean() | type T = boolean |
Object | const T = Type.Object({ name: Type.String() }) | type T = { name: string } |
Array | const T = Type.Array(Type.Number()) | type T = number[] |
Map | const T = Type.Map(Type.Number()) | type T = { [key: string] } : number |
Intersect | const T = Type.Intersect(Type.String(), Type.Number()) | type T = string & number |
Union | const T = Type.Union(Type.String(), Type.Number()) | type T = string | number |
Tuple | const T = Type.Tuple(Type.String(), Type.Number()) | type T = [string, number] |
Any | const T = Type.Any() | type T = any |
Null | const T = Type.Null() | type T = null |
Pattern | const T = Type.Pattern(/foo/) | type T = string |
Range | const T = Type.Range(20, 30) | type T = number |
Format | const T = Type.Format('date-time') | type T = string |
Guid | const T = Type.Guid() | type T = string |
TypeBox > JSONSchema
Type | TypeBox | JSONSchema |
---|
Literal | const T = Type.Literal(123) | { type: 'number', enum: [123] } |
String | const T = Type.String() | { type: 'string' } |
Number | const T = Type.Number() | { type: 'number' } |
Boolean | const T = Type.Boolean() | { type: 'boolean' } |
Object | const T = Type.Object({ name: Type: String() }) | { type: 'object': properties: { name: { type: 'string' } }, required: ['name'] } |
Array | const T = Type.Array(Type.String()) | { type: 'array': items: { type: 'string' } } |
Map | const T = Type.Map(Type.Number()) | { type: 'object', additionalProperties: { type: 'number' } } |
Intersect | const T = Type.Intersect(Type.Number(), Type.String()) | { allOf: [{ type: 'number'}, {type: 'string'}] } |
Union | const T = Type.Union(Type.Number(), Type.String()) | { oneOf: [{ type: 'number'}, {type: 'string'}] } |
Tuple | const T = Type.Tuple(Type.Number(), Type.String()) | { type: "array", items: [{type: 'string'}, {type: 'number'}], additionalItems: false, minItems: 2, maxItems: 2 } |
Any | const T = Type.Any() | { } |
Null | const T = Type.Null() | { type: 'null' } |
Pattern | const T = Type.Pattern(/foo/) | { type: 'string', pattern: 'foo' } |
Range | const T = Type.Range(20, 30) | { type: 'number', minimum: 20, maximum: 30 } |
Format | const T = Type.Format('date-time') | { type: 'string',format: 'date-time' } |
Guid | const T = Type.Guid() | { type: 'string', format: '' } |
More Types
In addition to the JSONSchema functions, TypeBox also provides some non-standard schemas that provide reflectable metadata for function signatures. These functions allow TypeBox to express function
and constructor
signatures where the arguments and return types may be JSONSchema.
For more information on their use, see the Functions and Generics sections below.
TypeBox > TypeScript
Intrinsic | TypeBox | TypeScript |
---|
Function | const T = Type.Function([Type.String()], Type.String()) | type T = (arg0: string) => string |
Constructor | const T = Type.Constructor([Type.String()], Type.String()) | type T = new (arg0: string) => string |
Promise | const T = Type.Promise(Type.String()) | type T = Promise<string> |
Undefined | const T = Type.Undefined() | type T = undefined |
Void | const T = Type.Void() | type T = void |
TypeBox > TypeBox Schema
Intrinsic | TypeBox | Metadata |
---|
Function | const T = Type.Function([Type.String()], Type.Number()) | { type: 'function', arguments: [ { type: 'string' } ], returns: { type: 'number' } } |
Constructor | const T = Type.Constructor([Type.String()], Type.Number()) | { type: 'constructor', arguments: [ { type: 'string' } ], returns: { type: 'number' } } |
Promise | const T = Type.Promise(Type.String()) | { type: 'promise', item: { type: 'string' } } |
Undefined | const T = Type.Undefined() | { type: 'undefined' } |
Void | const T = Type.Void() | { type: 'void' } |
Functions
The following demonstrates creating function signatures for the following TypeScript types.
TypeScript
type T0 = (a0: number, a1: string) => boolean;
type T1 = (a0: string, a1: () => string) => void;
type T2 = (a0: string) => Promise<number>;
type T3 = () => () => string;
type T4 = new () => string
TypeBox
const T0 = Type.Function([Type.Number(), Type.String()], Type.Boolean())
const T1 = Type.Function([Type.String(), Type.Function([], Type.String())], Type.Void())
const T2 = Type.Function([Type.String()], Type.Promise(Type.Number()))
const T3 = Type.Function([], Type.Function([], Type.String()))
const T4 = Type.Constructor([], Type.String())
Generics
Generic function signatures can be composed with TypeScript functions with Generic Constraints.
TypeScript
type ToString = <T>(t: T) => string
TypeBox
import { Type, Static, TStatic } from '@sinclair/typebox'
const ToString = <G extends TStatic>(T: G) => Type.Function([T], Type.String())
However, it's not possible to statically infer what type ToString
is without first creating some specialized variant of it. The following creates a specialization called NumberToString
.
const NumberToString = ToString(Type.Number())
type X = Static<typeof NumberToString>
To take things a bit further, the following code contains some generic TypeScript REST setup with controllers that take some generic resource of type T
. Below this we expresses that same setup using TypeBox. The resulting type IRecordController
contains reflectable metadata about the RecordController
.
TypeScript
interface IController<T> {
get (): Promise<T>
post (resource: T): Promise<void>
put (resource: T): Promise<void>
delete (resource: T): Promise<void>
}
interface Record {
key: string
value: string
}
class StringController implements IController<Record> {
async get (): Promise<Record> { throw 'not implemented' }
async post (resource: Record): Promise<void> { }
async put (resource: Record): Promise<void> { }
async delete(resource: Record): Promise<void> { }
}
TypeBox
import { Type, Static, TStatic } from '@sinclair/typebox'
const IController = <G extends TStatic>(T: G) => Type.Object({
get: Type.Function([], Type.Promise(T)),
post: Type.Function([T], Type.Promise(Type.Void())),
put: Type.Function([T], Type.Promise(Type.Void())),
delete: Type.Function([T], Type.Promise(Type.Void())),
})
type Record = Static<typeof Record>
const Record = Type.Object({
key: Type.String(),
value: Type.String()
})
type IRecordController = Static<typeof IRecordController>
const IRecordController = IController(Record)
class RecordController implements IRecordController {
async get (): Promise<Record> { throw 'not implemented' }
async post (resource: Record): Promise<void> { }
async put (resource: Record): Promise<void> { }
async delete(resource: Record): Promise<void> { }
}
console.log(IRecordController)
Validation
The following uses the library Ajv to validate a type.
import * Ajv from 'ajv'
const ajv = new Ajv({ })
ajv.validate(Type.String(), 'hello')
ajv.validate(Type.String(), 123)