gryum / typebox

JSONSchema Type Builder with Static Type Resolution for TypeScript

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. TypeBox internally represents its types as plain JSONSchema objects and leverages TypeScript's Mapped Types to infer schemas to equivalent static type representations. No additional build process is required.

TypeBox can be used as a tool to build and validate complex schemas, or integrated into RPC or REST services to help validate data received over the wire or published directly to consumers to service as developer documentation.

Note that TypeBox does not provide any mechanisms 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
• Other Types
• Functions
• Validation

Example

The following shows the type alias for Order and its TypeBox equivalent.

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.Range(1, 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: '[email protected]', 
    address: '...', 
    quantity: 99, 
    option: 'pie' 
}) 

// ... and so on ...

Types

TypeBox functions generate JSONschema objects. The following table outlines the TypeScript and JSONSchema equivalence.

TypeBox > TypeScript

The following types and modifiers are compatible with JSONschema and have both JSONschema and TypeScript representations.

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

The following shows the TypeBox to JSONSchema mappings. The following schemas are returned from each function.

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.Union(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: '' }

Other Types

TypeBox provides some non-standard JSONSchema functions that TypeBox refers to as Intrinsic types. While these types cannot be used with JSONSchema, they do provide similar reflection and introspection metadata for expressing function signatures with TypeBox.

See Functions section for more details.

TypeBox > Intrinsics

Intrinsic	TypeBox	TypeScript
Function	const T = Type.Function([Type.String()], Type.String())	type T = (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 > Non Schema

Intrinsic	TypeBox	TypeScript
Function	const T = Type.Function([Type.String()], Type.Number())	{ type: 'function', 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

TypeBox provides some capabilities for building typed function signatures. It is important to note however that unlike the other functions available on Type the Type.Function(...) and other intrinsic types do not produce valid JSONSchema. However, the types returned from Type.Function(...) may be comprised of schemas that describe its arguments and return types. Consider the following TypeScript and TypeBox variants.

// TypeScript

type T0 = (a0: number, a0: number) => number;

type T1 = (a0: string, a1: () => string) => void;

type T2 = (a0: string) => Promise<number>;

type T3 = () => () => string;

// Convention

Type.Function([...Arguments], ReturnType)

// TypeBox

const T0 = Type.Function([Type.Number(), Type.Number()], Type.Number())

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()))

Validation

TypeBox does not provide any mechanism for validating JSONSchema out of the box. Users are expected to bring their own JSONSchema validation library. The following demonstrates how you might enable validation with the AJV npm module.

General

import * Ajv from 'ajv'

const ajv = new Ajv({ })

ajv.validate(Type.String(), 'hello')  // true

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

Runtime Type Validation

The following demonstrates how you might want to approach runtime type validation with TypeBox. The following code creates a function that takes a signature type S which is used to infer function arguments. The body of the function validates with the signatures arguments and returns schemas against values passed by the caller.

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

// Some validation function.
declare function validate(schema: any, data: any): boolean;

// A function that returns a closure that validates its 
// arguments and return value from the given signature.
function Func<S extends TFunction>(signature: S, func: Static<S>): Static<S> {    
    const validator = (...params: any[]) => {
        params.forEach((param, index) => {
            if(!validate(signature.arguments[index], param)) {
                console.log('error on argument', index)
            }
        })
        const result = (func as Function)(...params);
        if(!validate(signature.return, result)) {
            console.log('error on return')
        }
        return result
    }
    return validator as Static<S>
}

// Create some function.
const Add = Func(
    Type.Function([
        Type.Number(), 
        Type.Number()
    ], Type.Number()), 
    (a, b) => {
        return a + b
    })

// Call it
Add(20, 30)