@sinclair/typebox

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

• Install
• Overview
• Example
• Types
• Function Types
• Functions
• Generics
• Validation

Example

The following shows the general usage.

import { Type, Static } from '@sinclair/typebox'

// Some type...

type Order = {
    email:    string,
    address:  string,
    quantity: number,
    option:   'pizza' | 'salad' | 'pie'
}

// ...can be expressed as...

const Order = Type.Object({
    email:    Type.Format('email'), 
    address:  Type.String(),
    quantity: Type.Number({ minimum: 1, maximum: 99 }),
    option:   Type.Union(
        Type.Literal('pizza'), 
        Type.Literal('salad'),
        Type.Literal('pie')
    )
})

// ... which can be reflected

console.log(JSON.stringify(Order, null, 2))

// ... and statically resolved

type TOrder = Static<typeof Order>

// .. and validated as JSONSchema

JSON.validate(Order, {  // IETF | TC39 ?
    email: 'dave@domain.com', 
    address: '...', 
    quantity: 99, 
    option: 'pie' 
}) 

// ... and so on ...

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
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
Integer	const T = Type.Integer()	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
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' }
Integer	const T = Type.Number()	{ type: 'integer' }
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' }
Format	const T = Type.Format('date-time')	{ type: 'string',format: 'date-time' }
Guid	const T = Type.Guid()	{ type: 'string', format: '' }

Type Modifiers

The following are object property modifiers. Note that Type.Optional(...) will make the schema object property optional. Type.Readonly(...) however has no effect on the underlying schema as is only meaningful to TypeScript.

Type	TypeBox	TypeScript
ReadonlyOptional	const T = Type.Object({ email: Type.ReadonlyOptional(Type.String()) })	type T = { readonly email?: string }
Readonly	const T = Type.Object({ email: Type.Readonly(Type.String()) })	type T = { readonly email: string }
Optional	const T = Type.Object({ email: Type.Optional(Type.String()) })	type T = { email?: string }

Function Types

TypeBox allows function signatures to be composed in a similar way to other types. It uses a custom schema represenation to achieve this. Note, this format is not JSONSchema, rather it uses JSONSchema to encode function arguments and return types. It also provides additional types; Type.Constructor(), Type.Void(), Type.Undefined(), and Type.Promise().

For more information on their using functions, see the Functions and Generics sections below.

Format

The following is an example of how TypeBox encodes function signatures.

type T = (a: string, b: number) => boolean

{
    "type": "function",
    "returns": { "type": "boolean" },
    "arguments": [
        {"type": "string" }, 
        {"type": "number" },
    ]
}

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 > JSON Function

Intrinsic	TypeBox	JSON Function
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>

// X is (arg0: number) => string

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 express that same setup using TypeBox. The resulting type IRecordController contains reflectable interface 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> { /* */  }
}

// Reflect
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')  // true

ajv.validate(Type.String(), 123)      // false