@sinclair/typebox
TypeScript icon, indicating that this package has built-in type declarations

0.34.11 • Public • Published

TypeBox

Json Schema Type Builder with Static Type Resolution for TypeScript



npm version Downloads Build License

Install

$ npm install @sinclair/typebox --save

Example

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

const T = Type.Object({                              // const T = {
  x: Type.Number(),                                  //   type: 'object',
  y: Type.Number(),                                  //   required: ['x', 'y', 'z'],
  z: Type.Number()                                   //   properties: {
})                                                   //     x: { type: 'number' },
                                                     //     y: { type: 'number' },
                                                     //     z: { type: 'number' }
                                                     //   }
                                                     // }

type T = Static<typeof T>                            // type T = {
                                                     //   x: number,
                                                     //   y: number,
                                                     //   z: number
                                                     // }

Overview

TypeBox is a runtime type builder that creates in-memory Json Schema objects that infer as TypeScript types. The schematics produced by this library are designed to match the static type checking rules of the TypeScript compiler. TypeBox offers a unified type that can be statically checked by TypeScript and runtime asserted using standard Json Schema validation.

This library is designed to allow Json Schema to compose similar to how types compose within TypeScript's type system. It can be used as a simple tool to build up complex schematics or integrated into REST and RPC services to help validate data received over the wire.

License MIT

Contents

Usage

The following shows general usage.

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

//--------------------------------------------------------------------------------------------
//
// Let's say you have the following type ...
//
//--------------------------------------------------------------------------------------------

type T = {
  id: string,
  name: string,
  timestamp: number
}

//--------------------------------------------------------------------------------------------
//
// ... you can express this type in the following way.
//
//--------------------------------------------------------------------------------------------

const T = Type.Object({                              // const T = {
  id: Type.String(),                                 //   type: 'object',
  name: Type.String(),                               //   properties: {
  timestamp: Type.Integer()                          //     id: {
})                                                   //       type: 'string'
                                                     //     },
                                                     //     name: {
                                                     //       type: 'string'
                                                     //     },
                                                     //     timestamp: {
                                                     //       type: 'integer'
                                                     //     }
                                                     //   },
                                                     //   required: [
                                                     //     'id',
                                                     //     'name',
                                                     //     'timestamp'
                                                     //   ]
                                                     // }

//--------------------------------------------------------------------------------------------
//
// ... then infer back to the original static type this way.
//
//--------------------------------------------------------------------------------------------

type T = Static<typeof T>                            // type T = {
                                                     //   id: string,
                                                     //   name: string,
                                                     //   timestamp: number
                                                     // }

//--------------------------------------------------------------------------------------------
//
// ... or use the type to parse JavaScript values.
//
//--------------------------------------------------------------------------------------------

import { Value } from '@sinclair/typebox/value'

const R = Value.Parse(T, value)                      // const R: {
                                                     //   id: string,
                                                     //   name: string,
                                                     //   timestamp: number
                                                     // }

Types

TypeBox types are Json Schema fragments that compose into more complex types. Each fragment is structured such that any Json Schema compliant validator can runtime assert a value the same way TypeScript will statically assert a type. TypeBox offers a set of Json Types which are used to create Json Schema compliant schematics as well as a JavaScript type set used to create schematics for constructs native to JavaScript.

Json Types

The following table lists the supported Json types. These types are fully compatible with the Json Schema Draft 7 specification.

┌────────────────────────────────┬─────────────────────────────┬────────────────────────────────┐
 TypeBox                         TypeScript                   Json Schema                    
                                                                                             
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
 const T = Type.Any()            type T = any                 const T = { }                  
                                                                                             
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
 const T = Type.Unknown()        type T = unknown             const T = { }                  
                                                                                             
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
 const T = Type.String()         type T = string              const T = {                    
                                                                type: 'string'               
                                                              }                              
                                                                                             
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
 const T = Type.Number()         type T = number              const T = {                    
                                                                type: 'number'               
                                                              }                              
                                                                                             
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
 const T = Type.Integer()        type T = number              const T = {                    
                                                                type: 'integer'              
                                                              }                              
                                                                                             
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
 const T = Type.Boolean()        type T = boolean             const T = {                    
                                                                type: 'boolean'              
                                                              }                              
                                                                                             
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
 const T = Type.Null()           type T = null                const T = {                    
                                                                type: 'null'                 
                                                              }                              
                                                                                             
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
 const T = Type.Literal(42)      type T = 42                  const T = {                    
                                                                const: 42,                   
                                                                type: 'number'               
                                                              }                              
                                                                                             
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
 const T = Type.Array(           type T = number[]            const T = {                    
   Type.Number()                                                type: 'array',               
 )                                                              items: {                     
                                                                  type: 'number'             
                                                                }                            
                                                              }                              
                                                                                             
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
 const T = Type.Object({         type T = {const T = {                    
   x: Type.Number(),               x: number,                   type: 'object',              
   y: Type.Number()                y: number                    required: ['x', 'y'], })                              }                              properties: {                
                                                                  x: {                       
                                                                    type: 'number'           
                                                                  },                         
                                                                  y: {                       
                                                                    type: 'number'           
                                                                  }                          
                                                                }                            
                                                              }                              
                                                                                             
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
 const T = Type.Tuple([          type T = [number, number]    const T = {                    
   Type.Number(),                                               type: 'array',               
   Type.Number()                                                items: [{                    
 ])                                                               type: 'number'             
                                                                }, {                         
                                                                  type: 'number'             
                                                                }],                          
                                                                additionalItems: false,      
                                                                minItems: 2,                 
                                                                maxItems: 2                  
                                                              }                              
                                                                                             
                                                                                             
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
 enum Foo {                      enum Foo {                   const T = {                    
   A,                              A,                           anyOf: [{                    
   B                               B                              type: 'number', }                               }                                const: 0                   
                                                                }, { const T = Type.Enum(Foo)        type T = Foo                     type: 'number',            
                                                                  const: 1                   
                                                                }]                           
                                                              }                              
                                                                                             
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
 const T = Type.Const({          type T = {const T = {                    
   x: 1,                           readonly x: 1,               type: 'object',              
   y: 2,                           readonly y: 2                required: ['x', 'y'], } as const)                     }                              properties: {                
                                                                  x: {                       
                                                                    type: 'number',          
                                                                    const: 1                 
                                                                  },                         
                                                                  y: {                       
                                                                    type: 'number',          
                                                                    const: 2                 
                                                                  }                          
                                                                }                            
                                                              }                              
                                                                                             
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
 const T = Type.KeyOf(           type T = keyof {             const T = {                    
   Type.Object({                   x: number,                   anyOf: [{                    
     x: Type.Number(),             y: number                      type: 'string',            
     y: Type.Number()            }                                const: 'x'                 
   })                                                           }, {                         
 )                                                                type: 'string',            
                                                                  const: 'y'                 
                                                                }]                           
                                                              }                              
                                                                                             
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
 const T = Type.Union([          type T = string | number     const T = {                    
   Type.String(),                                               anyOf: [{                    
   Type.Number()                                                  type: 'string'             
 ])                                                             }, {                         
                                                                  type: 'number'             
                                                                }]                           
                                                              }                              
                                                                                             
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
 const T = Type.Intersect([      type T = {                   const T = {                    
   Type.Object({                   x: number                    allOf: [{                    
     x: Type.Number()            } & {                            type: 'object',   }),                             y: number                      required: ['x'],           
   Type.Object({}                                properties: {              
     y: Type.Number()                                               x: {                     
   })                                                                 type: 'number'         
 ])                                                                 }                        
                                                                  }                          
                                                                }, {                         
                                                                  type: 'object',            |
                                                                  required: ['y'],           
                                                                  properties: {              
                                                                    y: {                     
                                                                      type: 'number'         
                                                                    }                        
                                                                  }                          
                                                                }]                           
                                                              }                              
                                                                                             
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
 const T = Type.Composite([      type T = {                   const T = {                    
   Type.Object({                   x: number,                   type: 'object',              
     x: Type.Number()              y: number                    required: ['x', 'y'],        
   }),                           }                              properties: {                
   Type.Object({                                                  x: {                       
     y: Type.Number()                                               type: 'number'           
   })                                                             },                         
 ])                                                               y: {                       
                                                                    type: 'number'           
                                                                  }                          
                                                                }                            
                                                              }                              
                                                                                             
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
 const T = Type.Never()          type T = never               const T = {                    
                                                                not: {}                      
                                                              }                              
                                                                                             
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
 const T = Type.Not(            | type T = unknown             const T = {                    
   Type.String()                                                not: {                       
 )                                                                type: 'string'             
                                                                }                            
                                                              }                              
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
 const T = Type.Extends(         type T =                     const T = {                    
   Type.String(),                 string extends number         const: false,                
   Type.Number(),                   ? true                      type: 'boolean'              
   Type.Literal(true),              : false                   }                              
   Type.Literal(false)                                                                       
 )                                                                                           
                                                                                             
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
 const T = Type.Extract(         type T = Extract<            const T = {                    
   Type.Union([                    string | number,             type: 'string'               
     Type.String(),                string                     }                              
     Type.Number(),              >                                                           
   ]),                                                                                       
   Type.String()                                                                             
 )                                                                                           
                                                                                             
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
 const T = Type.Exclude(         type T = Exclude<            const T = {                    
   Type.Union([                    string | number,             type: 'number'               
     Type.String(),                string                     }                              
     Type.Number(),              >                                                           
   ]),                                                                                       
   Type.String()                                                                             
 )                                                                                           
                                                                                             
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
 const T = Type.Mapped(          type T = {                   const T = {                    
   Type.Union([                    [_ in 'x' | 'y'] : number    type: 'object',              
     Type.Literal('x'),          }                              required: ['x', 'y'],        
     Type.Literal('y')                                          properties: {                
   ]),                                                            x: {                       
   () => Type.Number()                                              type: 'number'           
 )                                                                },                         
                                                                  y: {                       
                                                                    type: 'number'           
                                                                  }                          
                                                                }                            
                                                              }                              
                                                                                             
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
 const U = Type.Union([          type U = 'open' | 'close'    const T = {                    
   Type.Literal('open'),                                        type: 'string',              
   Type.Literal('close')         type T = `on${U}`              pattern: '^on(open|close)$'  
 ])                                                           }                              
                                                                                             
 const T = Type                                                                              
   .TemplateLiteral([                                                                        
      Type.Literal('on'),                                                                    
      U                                                                                      
   ])                                                                                        
                                                                                             
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
 const T = Type.Record(          type T = Record<             const T = {                    
   Type.String(),                  string,                      type: 'object',              
   Type.Number()                   number                       patternProperties: {         
 )                               >                                '^.*$': {                  
                                                                    type: 'number'           
                                                                  }                          
                                                                }                            
                                                              }                              
                                                                                             
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
 const T = Type.Partial(         type T = Partial<{           const T = {                    
   Type.Object({                   x: number,                   type: 'object',              
     x: Type.Number(),             y: number                    properties: {                
     y: Type.Number()           | }>                               x: {                       
   })                                                               type: 'number'           
 )                                                                },                         
                                                                  y: {                       
                                                                    type: 'number'           
                                                                  }                          
                                                                }                            
                                                              }                              
                                                                                             
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
 const T = Type.Required(        type T = Required<{          const T = {                    
   Type.Object({                   x?: number,                  type: 'object',              
     x: Type.Optional(             y?: number                   required: ['x', 'y'],        
       Type.Number()            | }>                             properties: {                
     ),                                                           x: {                       
     y: Type.Optional(                                              type: 'number'           
       Type.Number()                                              },                         
     )                                                            y: {                       
   })                                                               type: 'number'           
 )                                                                }                          
                                                                }                            
                                                              }                              
                                                                                             
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
 const T = Type.Pick(            type T = Pick<{              const T = {                    
   Type.Object({                   x: number,                   type: 'object',              
     x: Type.Number(),             y: number                    required: ['x'],             
     y: Type.Number()            }, 'x'>                        properties: {                
   }), ['x']                    |                                  x: {                       
 )                                                                  type: 'number'           
                                                                  }                          
                                                                }                            
                                                              }                              
                                                                                             
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
 const T = Type.Omit(            type T = Omit<{              const T = {                    
   Type.Object({                   x: number,                   type: 'object',              
     x: Type.Number(),             y: number                    required: ['y'],             
     y: Type.Number()            }, 'x'>                        properties: {                
   }), ['x']                    |                                  y: {                       
 )                                                                  type: 'number'           
                                                                  }                          
                                                                }                            
                                                              }                              
                                                                                             
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
 const T = Type.Index(           type T = {                   const T = {                    
   Type.Object({                   x: number,                   type: 'number'               
     x: Type.Number(),             y: string                  }                              
     y: Type.String()            }['x']                                                      
   }), ['x']                                                                                 
 )                                                                                           
                                                                                             
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
 const A = Type.Tuple([          type A = [0, 1]              const T = {                    
   Type.Literal(0),              type B = [2, 3]                type: 'array',               
   Type.Literal(1)               type T = [                     items: [                     
 ])                                ...A,                          { const: 0 },              
 const B = Type.Tuple([            ...B                           { const: 1 },              
|   Type.Literal(2),              ]                                { const: 2 },              
|   Type.Literal(3)                                                { const: 3 }               
 ])                                                             ],                           
 const T = Type.Tuple([                                         additionalItems: false,      
|   ...Type.Rest(A),                                             minItems: 4,                 
|   ...Type.Rest(B)                                              maxItems: 4                  
 ])                                                           }                              
                                                                                             
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
 const T = Type.Uncapitalize(    type T = Uncapitalize<       const T = {                    
   Type.Literal('Hello')           'Hello'                      type: 'string',              
 )                               >                              const: 'hello'               
                                                              }                              
                                                                                             
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
 const T = Type.Capitalize(      type T = Capitalize<         const T = {                    
   Type.Literal('hello')           'hello'                      type: 'string',              
 )                               >                              const: 'Hello'               
                                                              }                              
                                                                                             
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
 const T = Type.Uppercase(       type T = Uppercase<          const T = {                    
   Type.Literal('hello')           'hello'                      type: 'string',              
 )                               >                              const: 'HELLO'               
                                                              }                              
                                                                                             
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
 const T = Type.Lowercase(       type T = Lowercase<          const T = {                    
   Type.Literal('HELLO')           'HELLO'                      type: 'string',              
 )                               >                              const: 'hello'               
                                                              }                              
                                                                                             
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
 const R = Type.Ref('T')         type R = unknown             const R = { $ref: 'T' }        
                                                                                             
└────────────────────────────────┴─────────────────────────────┴────────────────────────────────┘

JavaScript Types

TypeBox provides an extended type set that can be used to create schematics for common JavaScript constructs. These types can not be used with any standard Json Schema validator; but can be used to frame schematics for interfaces that may receive Json validated data. JavaScript types are prefixed with the [JavaScript] jsdoc comment for convenience. The following table lists the supported types.

┌────────────────────────────────┬─────────────────────────────┬────────────────────────────────┐
 TypeBox                         TypeScript                   Extended Schema                
                                                                                             
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
 const T = Type.Constructor([    type T = new (               const T = {                    
   Type.String(),                 arg0: string,                 type: 'Constructor',         
   Type.Number()                  arg0: number                  parameters: [{               
 ], Type.Boolean())              ) => boolean                     type: 'string'             
                                                                }, {                         
                                                                  type: 'number'             
                                                                }],                          
                                                                returns: {                   
                                                                  type: 'boolean'            
                                                                }                            
                                                              }                              
                                                                                             
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
 const T = Type.Function([       type T = (                   const T = {                    
|   Type.String(),                 arg0: string,                 type: 'Function',            
   Type.Number()                  arg1: number                  parameters: [{               
 ], Type.Boolean())              ) => boolean                     type: 'string'             
                                                                }, {                         
                                                                  type: 'number'             
                                                                }],                          
                                                                returns: {                   
                                                                  type: 'boolean'            
                                                                }                            
                                                              }                              
                                                                                             
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
 const T = Type.Promise(         type T = Promise<string>     const T = {                    
   Type.String()                                                type: 'Promise',             
 )                                                              item: {                      
                                                                  type: 'string'             
                                                                }                            
                                                              }                              
                                                                                             
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
 const T =                       type T =                     const T = {                    
   Type.AsyncIterator(             AsyncIterableIterator<       type: 'AsyncIterator',       
     Type.String()                  string                      items: {                     
   )                               >                              type: 'string'             
                                                                }                            
                                                              }                              
                                                                                             
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
 const T = Type.Iterator(        type T =                     const T = {                    
   Type.String()                   IterableIterator<string>     type: 'Iterator',            
 )                                                              items: {                     
                                                                  type: 'string'             
                                                                }                            
                                                              }                              
                                                                                             
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
 const T = Type.RegExp(/abc/i)   type T = string              const T = {                    
                                                                type: 'RegExp'               
                                                                source: 'abc'                
                                                                flags: 'i'                   
                                                              }                              
                                                                                             
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
 const T = Type.Uint8Array()     type T = Uint8Array          const T = {                    
                                                                type: 'Uint8Array'           
                                                              }                              
                                                                                             
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
 const T = Type.Date()           type T = Date                const T = {                    
                                                                type: 'Date'                 
                                                              }                              
                                                                                             
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
 const T = Type.Undefined()      type T = undefined           const T = {                    
                                                                type: 'undefined'            
                                                              }                              
                                                                                             
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
 const T = Type.Symbol()         type T = symbol              const T = {                    
                                                                type: 'symbol'               
                                                              }                              
                                                                                             
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
 const T = Type.BigInt()         type T = bigint              const T = {                    
                                                                type: 'bigint'               
                                                              }                              
                                                                                             
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
 const T = Type.Void()           type T = void                const T = {                    
                                                                type: 'void'                 
                                                              }                              
                                                                                             
└────────────────────────────────┴─────────────────────────────┴────────────────────────────────┘

Import

Import the Type namespace to bring in the full TypeBox type system. This is recommended for most users.

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

You can also selectively import types. This enables modern bundlers to tree shake for unused types.

import { Object, Number, String, Boolean, type Static } from '@sinclair/typebox'

Options

You can pass Json Schema options on the last argument of any given type. Option hints specific to each type are provided for convenience.

// String must be an email
const T = Type.String({                              // const T = {
  format: 'email'                                    //   type: 'string',
})                                                   //   format: 'email'
                                                     // }

// Number must be a multiple of 2
const T = Type.Number({                              // const T = {
  multipleOf: 2                                      //  type: 'number',
})                                                   //  multipleOf: 2
                                                     // }

// Array must have at least 5 integer values
const T = Type.Array(Type.Integer(), {               // const T = {
  minItems: 5                                        //   type: 'array',
})                                                   //   minItems: 5,
                                                     //   items: {
                                                     //     type: 'integer'
                                                     //   }
                                                     // }

Properties

Object properties can be modified with Readonly and Optional. The following table shows how these modifiers map between TypeScript and Json Schema.

┌────────────────────────────────┬─────────────────────────────┬────────────────────────────────┐
 TypeBox                         TypeScript                   Json Schema                    
                                                                                             
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
 const T = Type.Object({         type T = {                   const T = {                    
   name: Type.ReadonlyOptional(    readonly name?: string       type: 'object',              
     Type.String()               }                              properties: {                
   )                                                              name: {                    
 })  	                                                             type: 'string'           
                                                                  }                          
                                                                }                            
                                                              }                              
                                                                                             
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
 const T = Type.Object({         type T = {                   const T = {                    
   name: Type.Readonly(            readonly name: string        type: 'object',              
     Type.String()               }                              properties: {                
   )                                                              name: {                    
 })  	                                                             type: 'string'           
                                                                  }                          
                                                                },                           
                                                                required: ['name']           
                                                              }                              
                                                                                             
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
 const T = Type.Object({         type T = {                   const T = {                    
   name: Type.Optional(            name?: string                type: 'object',              
     Type.String()               }                              properties: {                
   )                                                              name: {                    
 })  	                                                             type: 'string'           
                                                                  }                          
                                                                }                            
                                                              }                              
                                                                                             
└────────────────────────────────┴─────────────────────────────┴────────────────────────────────┘

Generic Types

Generic types can be created with functions. TypeBox types extend the TSchema interface so you should constrain parameters to this type. The following creates a generic Vector type.

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

const Vector = <T extends TSchema>(T: T) => 
  Type.Object({                                      // type Vector<T> = {
    x: T,                                            //   x: T,
    y: T,                                            //   y: T,
    z: T                                             //   z: T
  })                                                 // }

const NumberVector = Vector(Type.Number())           // type NumberVector = Vector<number>

Generic types are often used to create aliases for complex types. The following creates a Nullable generic type.

const Nullable = <T extends TSchema>(schema: T) => Type.Union([schema, Type.Null()])

const T = Nullable(Type.String())                    // const T = {
                                                     //   anyOf: [
                                                     //     { type: 'string' },
                                                     //     { type: 'null' }
                                                     //   ]
                                                     // }

type T = Static<typeof T>                            // type T = string | null

Module Types

TypeBox Modules are containers for related types. They provide a referential namespace, enabling types to reference one another via string identifiers. Modules support both singular and mutually recursive referencing within the context of a module, as well as referential computed types (such as Partial + Ref). All Module types must be imported before use. TypeBox represents an imported type with the $defs Json Schema keyword.

Usage

The following creates a Module with User and PartialUser types. Note that the PartialUser type is specified as a Partial + Ref to the User type. It is not possible to perform a Partial operation directly on a reference, so TypeBox will return a TComputed type that defers the Partial operation until all types are resolved. The TComputed type is evaluated when calling Import on the Module.

// Module with PartialUser and User types

const Module = Type.Module({

  PartialUser: Type.Partial(Type.Ref('User')),  // TComputed<'Partial', [TRef<'User'>]>

  User: Type.Object({                           // TObject<{
    id: Type.String(),                          //   user: TString,
    name: Type.String(),                        //   name: TString,
    email: Type.String()                        //   email: TString
  }),                                           // }>
  
})

// Types must be imported before use.

const User = Module.Import('User')               // const User: TImport<{...}, 'User'>

type User = Static<typeof User>                  // type User = { 
                                                 //   id: string,
                                                 //   name: string,
                                                 //   email: string
                                                 // }

const PartialUser = Module.Import('PartialUser') // const PartialUser: TImport<{...}, 'PartialUser'>

type PartialUser = Static<typeof PartialUser>    // type PartialUser = { 
                                                 //   id?: string,
                                                 //   name?: string,
                                                 //   email?: string
                                                 // }

Template Literal Types

TypeBox supports template literal types with the TemplateLiteral function. This type can be created using a syntax similar to the TypeScript template literal syntax or composed from exterior types. TypeBox encodes template literals as regular expressions which enables the template to be checked by Json Schema validators. This type also supports regular expression parsing that enables template patterns to be used for generative types. The following shows both TypeScript and TypeBox usage.

// TypeScript

type K = `prop${'A'|'B'|'C'}`                        // type T = 'propA' | 'propB' | 'propC'

type R = Record<K, string>                           // type R = {
                                                     //   propA: string
                                                     //   propB: string
                                                     //   propC: string
                                                     // }

// TypeBox

const K = Type.TemplateLiteral('prop${A|B|C}')       // const K: TTemplateLiteral<[
                                                     //   TLiteral<'prop'>,
                                                     //   TUnion<[
                                                     //      TLiteral<'A'>,
                                                     //      TLiteral<'B'>,
                                                     //      TLiteral<'C'>,
                                                     //   ]>
                                                     // ]>

const R = Type.Record(K, Type.String())              // const R: TObject<{
                                                     //   propA: TString,
                                                     //   propB: TString,
                                                     //   propC: TString,
                                                     // }>

Indexed Access Types

TypeBox supports indexed access types with the Index function. This function enables uniform access to interior property and element types without having to extract them from the underlying schema representation. Index types are supported for Object, Array, Tuple, Union and Intersect types.

const T = Type.Object({                              // type T = {
  x: Type.Number(),                                  //   x: number,
  y: Type.String(),                                  //   y: string,
  z: Type.Boolean()                                  //   z: boolean
})                                                   // }

const A = Type.Index(T, ['x'])                       // type A = T['x']
                                                     //
                                                     // ... evaluated as
                                                     //
                                                     // const A: TNumber

const B = Type.Index(T, ['x', 'y'])                  // type B = T['x' | 'y']
                                                     //
                                                     // ... evaluated as
                                                     //
                                                     // const B: TUnion<[
                                                     //   TNumber,
                                                     //   TString,
                                                     // ]>

const C = Type.Index(T, Type.KeyOf(T))               // type C = T[keyof T]
                                                     //
                                                     // ... evaluated as
                                                     // 
                                                     // const C: TUnion<[
                                                     //   TNumber,
                                                     //   TString,
                                                     //   TBoolean
                                                     // ]>

Mapped Types

TypeBox supports mapped types with the Mapped function. This function accepts two arguments, the first is a union type typically derived from KeyOf, the second is a mapping function that receives a mapping key K that can be used to index properties of a type. The following implements a mapped type that remaps each property to be T | null

const T = Type.Object({                              // type T = {
  x: Type.Number(),                                  //   x: number,
  y: Type.String(),                                  //   y: string,
  z: Type.Boolean()                                  //   z: boolean
})                                                   // }

const M = Type.Mapped(Type.KeyOf(T), K => {          // type M = { [K in keyof T]: T[K] | null }
  return Type.Union([Type.Index(T, K), Type.Null()]) //
})                                                   // ... evaluated as
                                                     // 
                                                     // const M: TObject<{
                                                     //   x: TUnion<[TNumber, TNull]>,
                                                     //   y: TUnion<[TString, TNull]>,
                                                     //   z: TUnion<[TBoolean, TNull]>
                                                     // }>

Conditional Types

TypeBox supports runtime conditional types with the Extends function. This function performs a structural assignability check against the first (left) and second (right) arguments and will return either the third (true) or fourth (false) argument based on the result. The conditional types Exclude and Extract are also supported. The following shows both TypeScript and TypeBox examples of conditional types.

// Extends
const A = Type.Extends(                              // type A = string extends number ? 1 : 2
  Type.String(),                                     //   
  Type.Number(),                                     // ... evaluated as
  Type.Literal(1),                                   //
  Type.Literal(2)                                    // const A: TLiteral<2>
)

// Extract
const B = Type.Extract(                              // type B = Extract<1 | 2 | 3, 1>
  Type.Union([                                       //
    Type.Literal(1),                                 // ... evaluated as
    Type.Literal(2),                                 //
    Type.Literal(3)                                  // const B: TLiteral<1>
  ]), 
  Type.Literal(1)
)

// Exclude
const C = Type.Exclude(                              // type C = Exclude<1 | 2 | 3, 1>
  Type.Union([                                       // 
    Type.Literal(1),                                 // ... evaluated as
    Type.Literal(2),                                 //
    Type.Literal(3)                                  // const C: TUnion<[
  ]),                                                //   TLiteral<2>,
  Type.Literal(1)                                    //   TLiteral<3>,
)                                                    // ]>

Transform Types

TypeBox supports value decoding and encoding with Transform types. These types work in tandem with the Encode and Decode functions available on the Value and TypeCompiler submodules. Transform types can be used to convert Json encoded values into constructs more natural to JavaScript. The following creates a Transform type to decode numbers into Dates using the Value submodule.

import { Value } from '@sinclair/typebox/value'

const T = Type.Transform(Type.Number())
  .Decode(value => new Date(value))                  // decode: number to Date
  .Encode(value => value.getTime())                  // encode: Date to number

const D = Value.Decode(T, 0)                         // const D = Date(1970-01-01T00:00:00.000Z)
const E = Value.Encode(T, D)                         // const E = 0

Use the StaticEncode or StaticDecode types to infer a Transform type.

import { Static, StaticDecode, StaticEncode } from '@sinclair/typebox'

const T = Type.Transform(Type.Array(Type.Number(), { uniqueItems: true }))         
  .Decode(value => new Set(value))
  .Encode(value => [...value])

type D = StaticDecode<typeof T>                      // type D = Set<number>      
type E = StaticEncode<typeof T>                      // type E = Array<number>
type T = Static<typeof T>                            // type T = Array<number>

Unsafe Types

TypeBox supports user defined types with Unsafe. This type allows you to specify both schema representation and inference type. The following creates an Unsafe type with a number schema that infers as string.

const T = Type.Unsafe<string>({ type: 'number' })    // const T = { type: 'number' }

type T = Static<typeof T>                            // type T = string - ?

The Unsafe type is often used to create schematics for extended specifications like OpenAPI.

const Nullable = <T extends TSchema>(schema: T) => Type.Unsafe<Static<T> | null>({ 
  ...schema, nullable: true 
})

const T = Nullable(Type.String())                    // const T = {
                                                     //   type: 'string',
                                                     //   nullable: true
                                                     // }

type T = Static<typeof T>                            // type T = string | null

const StringEnum = <T extends string[]>(values: [...T]) => Type.Unsafe<T[number]>({ 
  type: 'string', enum: values 
})
const S = StringEnum(['A', 'B', 'C'])                // const S = {
                                                     //   enum: ['A', 'B', 'C']
                                                     // }

type S = Static<typeof T>                            // type S = 'A' | 'B' | 'C'

TypeGuard

TypeBox can check its own types with the TypeGuard module. This module is written for type introspection and provides structural tests for every built-in TypeBox type. Functions of this module return is guards which can be used with control flow assertions to obtain schema inference for unknown values. The following guards that the value T is TString.

import { TypeGuard, Kind } from '@sinclair/typebox'

const T = { [Kind]: 'String', type: 'string' }

if(TypeGuard.IsString(T)) {

  // T is TString
}

Syntax Types

TypeBox has support for parsing TypeScript type annotations directly into TypeBox types. This feature supports both runtime and static parsing, with TypeBox implementing TypeScript parsers within the TypeScript type system itself. Syntax Types use the TypeBox Json Schema representations as an AST target for TypeScript types, providing a direct mapping between TypeScript syntax and Json Schema. Syntax Types are offered as a syntactical frontend to the Standard Type Builder API.

This feature is available via optional import.

import { Parse } from '@sinclair/typebox/syntax'

Parse

Use the Parse function to transform a TypeScript type annotation into a TypeBox type. This function will return the parsed TypeBox type or undefined on error.

const A = Parse('string')                           // const A: TString

const B = Parse('[1, 2, 3]')                        // const B: TTuple<[
                                                    //   TLiteral<1>,
                                                    //   TLiteral<2>,
                                                    //   TLiteral<3>
                                                    // ]>

const C = Parse(`{ x: number, y: number }`)         // const C: TObject<{
                                                    //   x: TNumber
                                                    //   y: TNumber
                                                    // }>

Syntax Types can compose with Standard Types created via the Type Builder API

const T = Type.Object({                             // const T: TObject<{
  x: Parse('number'),                               //   x: TNumber,
  y: Parse('string'),                               //   y: TString,
  z: Parse('boolean')                               //   z: TBoolean
})                                                  // }>

Standard Types can also be passed to and referenced within Syntax Types.

const X = Type.Number()
const Y = Type.String()
const Z = Type.Boolean()

const T = Parse({ X, Y, Z }, `{ 
  x: X, 
  y: Y, 
  z: Z 
}`)

Syntax Types also support Module parsing.

const Foo = Parse(`module Foo {

  export type PartialUser = Pick<User, 'id'> & Partial<Omit<User, 'id'>>

  export interface User {
    id: string
    name: string
    email: string
  }

}`)

const PartialUser = Foo.Import('PartialUser')       // TImport<{...}, 'PartialUser'>

type PartialUser = Static<typeof PartialUser>       // type PartialUser = {
                                                    //   id: string,
                                                    // } & {
                                                    //   name?: string,
                                                    //   email?: string,
                                                    // }

Static

Syntax Types provide two Static types specific to inferring TypeBox and TypeScript types from strings.

import { StaticParseAsSchema, StaticParseAsType } from '@sinclair/typebox/syntax' 

// Will infer as a TSchema

type S = StaticParseAsSchema<{}, '{ x: number }'>   // type S: TObject<{
                                                    //   x: TNumber
                                                    // }>

// Will infer as a type

type T = StaticParseAsType<{}, '{ x: number }'>     // type T = {
                                                    //   x: number
                                                    // }                      

Limitations

TypeBox parses TypeScript types directly within the TypeScript type system. This process does come with an inference cost, which scales with the size and complexity of the types being parsed. Although TypeBox strives to optimize Syntax Types, users should be aware of the following structures:

// Excessively wide structures will result in instantiation limits exceeding
const A = Parse(`[
  0, 1, 2, 3, 4, 5, 6, 7,
  0, 1, 2, 3, 4, 5, 6, 7,
  0, 1, 2, 3, 4, 5, 6, 7,
  0, 1, 2, 3, 4, 5, 6, 7,
  0, 1, 2, 3, 4, 5, 6, 7,
  0, 1, 2, 3, 4, 5, 6, 7,
  0, 1, 2, 3, 4, 5, 6, 7,
  0, 1, 2, 3, 4, 5, 6, 7,
]`)

// Excessively nested structures will result in instantiation limits exceeding
const B = Parse(`{
  x: {
    y: {
      z: {
        w: 1 <-- Type instantiation is excessively deep and possibly infinite.
      } 
    }
  }  
}`)

If Syntax Types exceed TypeScript's instantiation limits, users are advised to fall back to the Standard Type Builder API. Alternatively, TypeBox offers a ParseOnly function that parses the TypeScript syntax at runtime without statically inferring the schema.

import { ParseOnly } from '@sinclair/typebox/syntax'

// const A: TSchema | undefined 

const A = ParseOnly(`{
  x: {
    y: {
      z: {
        w: 1
      } 
    }
  }  
}`)

For more information on static parsing, refer to the ParseBox project.

Values

TypeBox provides an optional Value submodule that can be used to perform structural operations on JavaScript values. This submodule includes functionality to create, check and cast values from types as well as check equality, clone, diff and patch JavaScript values. This submodule is provided via optional import.

import { Value } from '@sinclair/typebox/value'

Assert

Use the Assert function to assert a value is valid.

let value: unknown = 1

Value.Assert(Type.Number(), value)                   // throws AssertError if invalid

Create

Use the Create function to create a value from a type. TypeBox will use default values if specified.

const T = Type.Object({ x: Type.Number(), y: Type.Number({ default: 42 }) })

const A = Value.Create(T)                            // const A = { x: 0, y: 42 }

Clone

Use the Clone function to deeply clone a value.

const A = Value.Clone({ x: 1, y: 2, z: 3 })          // const A = { x: 1, y: 2, z: 3 }

Check

Use the Check function to type check a value.

const T = Type.Object({ x: Type.Number() })

const R = Value.Check(T, { x: 1 })                   // const R = true

Convert

Use the Convert function to convert a value into its target type if a reasonable conversion is possible. This function may return an invalid value and should be checked before use. Its return type is unknown.

const T = Type.Object({ x: Type.Number() })

const R1 = Value.Convert(T, { x: '3.14' })           // const R1 = { x: 3.14 }

const R2 = Value.Convert(T, { x: 'not a number' })   // const R2 = { x: 'not a number' }

Clean

Use Clean to remove excess properties from a value. This function does not check the value and returns an unknown type. You should Check the result before use. Clean is a mutable operation. To avoid mutation, Clone the value first.

const T = Type.Object({ 
  x: Type.Number(), 
  y: Type.Number() 
})

const X = Value.Clean(T, null)                        // const 'X = null

const Y = Value.Clean(T, { x: 1 })                    // const 'Y = { x: 1 }

const Z = Value.Clean(T, { x: 1, y: 2, z: 3 })        // const 'Z = { x: 1, y: 2 }

Default

Use Default to generate missing properties on a value using default schema annotations if available. This function does not check the value and returns an unknown type. You should Check the result before use. Default is a mutable operation. To avoid mutation, Clone the value first.

const T = Type.Object({ 
  x: Type.Number({ default: 0 }), 
  y: Type.Number({ default: 0 })
})

const X = Value.Default(T, null)                        // const 'X = null - non-enumerable

const Y = Value.Default(T, { })                         // const 'Y = { x: 0, y: 0 }

const Z = Value.Default(T, { x: 1 })                    // const 'Z = { x: 1, y: 0 }

Cast

Use the Cast function to upcast a value into a target type. This function will retain as much infomation as possible from the original value. The Cast function is intended to be used in data migration scenarios where existing values need to be upgraded to match a modified type.

const T = Type.Object({ x: Type.Number(), y: Type.Number() }, { additionalProperties: false })

const X = Value.Cast(T, null)                        // const X = { x: 0, y: 0 }

const Y = Value.Cast(T, { x: 1 })                    // const Y = { x: 1, y: 0 }

const Z = Value.Cast(T, { x: 1, y: 2, z: 3 })        // const Z = { x: 1, y: 2 }

Decode

Use the Decode function to decode a value from a type or throw if the value is invalid. The return value will infer as the decoded type. This function will run Transform codecs if available.

const A = Value.Decode(Type.String(), 'hello')        // const A = 'hello'

const B = Value.Decode(Type.String(), 42)             // throw

Encode

Use the Encode function to encode a value to a type or throw if the value is invalid. The return value will infer as the encoded type. This function will run Transform codecs if available.

const A = Value.Encode(Type.String(), 'hello')        // const A = 'hello'

const B = Value.Encode(Type.String(), 42)             // throw

Parse

Use the Parse function to parse a value. This function calls the Clone Clean, Default, Convert, Assert and Decode Value functions in this exact order to process a value.

const R = Value.Parse(Type.String(), 'hello')      // const R: string = "hello"

const E = Value.Parse(Type.String(), undefined)    // throws AssertError 

You can override the order in which functions are run, or omit functions entirely using the following.

// Runs no functions.

const R = Value.Parse([], Type.String(), 12345)

// Runs the Assert() function.

const E = Value.Parse(['Assert'], Type.String(), 12345)

// Runs the Convert() function followed by the Assert() function.

const S = Value.Parse(['Convert', 'Assert'], Type.String(), 12345)

Equal

Use the Equal function to deeply check for value equality.

const R = Value.Equal(                               // const R = true
  { x: 1, y: 2, z: 3 },
  { x: 1, y: 2, z: 3 }
)

Hash

Use the Hash function to create a FNV1A-64 non cryptographic hash of a value.

const A = Value.Hash({ x: 1, y: 2, z: 3 })           // const A = 2910466848807138541n

const B = Value.Hash({ x: 1, y: 4, z: 3 })           // const B = 1418369778807423581n

Diff

Use the Diff function to generate a sequence of edits that will transform one value into another.

const E = Value.Diff(                                // const E = [
  { x: 1, y: 2, z: 3 },                              //   { type: 'update', path: '/y', value: 4 },
  { y: 4, z: 5, w: 6 }                               //   { type: 'update', path: '/z', value: 5 },
)                                                    //   { type: 'insert', path: '/w', value: 6 },
                                                     //   { type: 'delete', path: '/x' }
                                                     // ]

Patch

Use the Patch function to apply a sequence of edits.

const A = { x: 1, y: 2 }

const B = { x: 3 }

const E = Value.Diff(A, B)                           // const E = [
                                                     //   { type: 'update', path: '/x', value: 3 },
                                                     //   { type: 'delete', path: '/y' }
                                                     // ]

const C = Value.Patch<typeof B>(A, E)                // const C = { x: 3 }

Errors

Use the Errors function to enumerate validation errors.

const T = Type.Object({ x: Type.Number(), y: Type.Number() })

const R = [...Value.Errors(T, { x: '42' })]          // const R = [{
                                                     //   schema: { type: 'number' },
                                                     //   path: '/x',
                                                     //   value: '42',
                                                     //   message: 'Expected number'
                                                     // }, {
                                                     //   schema: { type: 'number' },
                                                     //   path: '/y',
                                                     //   value: undefined,
                                                     //   message: 'Expected number'
                                                     // }]

Mutate

Use the Mutate function to perform a deep mutable value assignment while retaining internal references.

const Y = { z: 1 }                                   // const Y = { z: 1 }
const X = { y: Y }                                   // const X = { y: { z: 1 } }
const A = { x: X }                                   // const A = { x: { y: { z: 1 } } }

Value.Mutate(A, { x: { y: { z: 2 } } })              // A' = { x: { y: { z: 2 } } }

const R0 = A.x.y.z === 2                             // const R0 = true
const R1 = A.x.y === Y                               // const R1 = true
const R2 = A.x === X                                 // const R2 = true

Pointer

Use ValuePointer to perform mutable updates on existing values using RFC6901 Json Pointers.

import { ValuePointer } from '@sinclair/typebox/value'

const A = { x: 0, y: 0, z: 0 }

ValuePointer.Set(A, '/x', 1)                         // A' = { x: 1, y: 0, z: 0 }
ValuePointer.Set(A, '/y', 1)                         // A' = { x: 1, y: 1, z: 0 }
ValuePointer.Set(A, '/z', 1)                         // A' = { x: 1, y: 1, z: 1 }

TypeRegistry

The TypeBox type system can be extended with additional types and formats using the TypeRegistry and FormatRegistry modules. These modules integrate deeply with TypeBox's internal type checking infrastructure and can be used to create application specific types, or register schematics for alternative specifications.

TypeRegistry

Use the TypeRegistry to register a type. The Kind must match the registered type name.

import { TSchema, Kind, TypeRegistry } from '@sinclair/typebox'

TypeRegistry.Set('Foo', (schema, value) => value === 'foo')

const Foo = { [Kind]: 'Foo' } as TSchema 

const A = Value.Check(Foo, 'foo')                    // const A = true

const B = Value.Check(Foo, 'bar')                    // const B = false

FormatRegistry

Use the FormatRegistry to register a string format.

import { FormatRegistry } from '@sinclair/typebox'

FormatRegistry.Set('foo', (value) => value === 'foo')

const T = Type.String({ format: 'foo' })

const A = Value.Check(T, 'foo')                      // const A = true

const B = Value.Check(T, 'bar')                      // const B = false

TypeCheck

TypeBox types target Json Schema Draft 7 and are compatible with any validator that supports this specification. TypeBox also provides a built in type checking compiler designed specifically for TypeBox types that offers high performance compilation and value checking.

The following sections detail using Ajv and the TypeBox compiler infrastructure.

Ajv

The following shows the recommended setup for Ajv.

$ npm install ajv ajv-formats --save
import { Type }   from '@sinclair/typebox'
import addFormats from 'ajv-formats'
import Ajv        from 'ajv'

const ajv = addFormats(new Ajv({}), [
  'date-time',
  'time',
  'date',
  'email',
  'hostname',
  'ipv4',
  'ipv6',
  'uri',
  'uri-reference',
  'uuid',
  'uri-template',
  'json-pointer',
  'relative-json-pointer',
  'regex'
])

const validate = ajv.compile(Type.Object({
  x: Type.Number(),
  y: Type.Number(),
  z: Type.Number()
}))

const R = validate({ x: 1, y: 2, z: 3 })             // const R = true

TypeCompiler

The TypeBox TypeCompiler is a high performance JIT validation compiler that transforms TypeBox types into optimized JavaScript validation routines. The compiler is tuned for fast compilation as well as fast value assertion. It is built to serve as a validation backend that can be integrated into larger applications. It can also be used for code generation.

The TypeCompiler is provided as an optional import.

import { TypeCompiler } from '@sinclair/typebox/compiler'

Use the Compile function to JIT compile a type. Note that compilation is generally an expensive operation and should only be performed once per type during application start up. TypeBox does not cache previously compiled types, and applications are expected to hold references to each compiled type for the lifetime of the application.

const C = TypeCompiler.Compile(Type.Object({         // const C: TypeCheck<TObject<{
  x: Type.Number(),                                  //     x: TNumber;
  y: Type.Number(),                                  //     y: TNumber;
  z: Type.Number()                                   //     z: TNumber;
}))                                                  // }>>

const R = C.Check({ x: 1, y: 2, z: 3 })              // const R = true

Use the Errors function to generate diagnostic errors for a value. The Errors function will return an iterator that when enumerated; will perform an exhaustive check across the entire value yielding any error found. For performance, this function should only be called after a failed Check. Applications may also choose to yield only the first value to avoid exhaustive error generation.

const C = TypeCompiler.Compile(Type.Object({         // const C: TypeCheck<TObject<{
  x: Type.Number(),                                  //     x: TNumber;
  y: Type.Number(),                                  //     y: TNumber;
  z: Type.Number()                                   //     z: TNumber;
}))                                                  // }>>

const value = { }

const first = C.Errors(value).First()                // const first = {
                                                     //   schema: { type: 'number' },
                                                     //   path: '/x',
                                                     //   value: undefined,
                                                     //   message: 'Expected number'
                                                     // }

const all = [...C.Errors(value)]                     // const all = [{
                                                     //   schema: { type: 'number' },
                                                     //   path: '/x',
                                                     //   value: undefined,
                                                     //   message: 'Expected number'
                                                     // }, {
                                                     //   schema: { type: 'number' },
                                                     //   path: '/y',
                                                     //   value: undefined,
                                                     //   message: 'Expected number'
                                                     // }, {
                                                     //   schema: { type: 'number' },
                                                     //   path: '/z',
                                                     //   value: undefined,
                                                     //   message: 'Expected number'
                                                     // }]

Use the Code function to generate assertion functions as strings. This function can be used to generate code that can be written to disk as importable modules. This technique is sometimes referred to as Ahead of Time (AOT) compilation. The following generates code to check a string.

const C = TypeCompiler.Code(Type.String())           // const C = `return function check(value) {
                                                     //   return (
                                                     //     (typeof value === 'string')
                                                     //   )
                                                     // }`

TypeSystem

The TypeBox TypeSystem module provides configurations to use either Json Schema or TypeScript type checking semantics. Configurations made to the TypeSystem module are observed by the TypeCompiler, Value and Error modules.

Policies

TypeBox validates using standard Json Schema assertion policies by default. The TypeSystemPolicy module can override some of these to have TypeBox assert values inline with TypeScript static checks. It also provides overrides for certain checking rules related to non-serializable values (such as void) which can be helpful in Json based protocols such as Json Rpc 2.0.

The following overrides are available.

import { TypeSystemPolicy } from '@sinclair/typebox/system'

// Disallow undefined values for optional properties (default is false)
//
// const A: { x?: number } = { x: undefined } - disallowed when enabled

TypeSystemPolicy.ExactOptionalPropertyTypes = true

// Allow arrays to validate as object types (default is false)
//
// const A: {} = [] - allowed in TS

TypeSystemPolicy.AllowArrayObject = true

// Allow numeric values to be NaN or + or - Infinity (default is false)
//
// const A: number = NaN - allowed in TS

TypeSystemPolicy.AllowNaN = true

// Allow void types to check with undefined and null (default is false)
//
// Used to signal void return on Json-Rpc 2.0 protocol

TypeSystemPolicy.AllowNullVoid = true

Error Function

Error messages in TypeBox can be customized by defining an ErrorFunction. This function allows for the localization of error messages as well as enabling custom error messages for custom types. By default, TypeBox will generate messages using the en-US locale. To support additional locales, you can replicate the function found in src/errors/function.ts and create a locale specific translation. The function can then be set via SetErrorFunction.

The following example shows an inline error function that intercepts errors for String, Number and Boolean only. The DefaultErrorFunction is used to return a default error message.

import { SetErrorFunction, DefaultErrorFunction, ValueErrorType } from '@sinclair/typebox/errors'

SetErrorFunction((error) => { // i18n override
  switch(error.errorType) {
    /* en-US */ case ValueErrorType.String: return 'Expected string'
    /* fr-FR */ case ValueErrorType.Number: return 'Nombre attendu'  
    /* ko-KR */ case ValueErrorType.Boolean: return '예상 부울'      
    /* en-US */ default: return DefaultErrorFunction(error)          
  }
})
const T = Type.Object({                              // const T: TObject<{
  x: Type.String(),                                  //  TString,
  y: Type.Number(),                                  //  TNumber,
  z: Type.Boolean()                                  //  TBoolean
})                                                   // }>

const E = [...Value.Errors(T, {                      // const E = [{
  x: null,                                           //   type: 48,
  y: null,                                           //   schema: { ... },
  z: null                                            //   path: '/x',
})]                                                  //   value: null,
                                                     //   message: 'Expected string'
                                                     // }, {
                                                     //   type: 34,
                                                     //   schema: { ... },
                                                     //   path: '/y',
                                                     //   value: null,
                                                     //   message: 'Nombre attendu'
                                                     // }, {
                                                     //   type: 14,
                                                     //   schema: { ... },
                                                     //   path: '/z',
                                                     //   value: null,
                                                     //   message: '예상 부울'
                                                     // }]

TypeBox Workbench

TypeBox offers a web based code generation tool that can convert TypeScript types into TypeBox types as well as several other ecosystem libraries.

TypeBox Workbench Link Here

TypeBox Codegen

TypeBox provides a code generation library that can be integrated into toolchains to automate type translation between TypeScript and TypeBox. This library also includes functionality to transform TypeScript types to other ecosystem libraries.

TypeBox Codegen Link Here

Ecosystem

The following is a list of community packages that offer general tooling, extended functionality and framework integration support for TypeBox.

Package Description
drizzle-typebox Generates TypeBox types from Drizzle ORM schemas
elysia Fast and friendly Bun web framework
fastify-type-provider-typebox Fastify TypeBox integration with the Fastify Type Provider
feathersjs The API and real-time application framework
fetch-typebox Drop-in replacement for fetch that brings easy integration with TypeBox
h3-typebox Schema validation utilities for h3 using TypeBox & Ajv
http-wizard Type safe http client library for Fastify
json2typebox Creating TypeBox code from Json Data
nominal-typebox Allows devs to integrate nominal types into TypeBox schemas
openapi-box Generate TypeBox types from OpenApi IDL + Http client library
prismabox Converts a prisma.schema to typebox schema matching the database models
schema2typebox Creating TypeBox code from Json Schemas
sveltekit-superforms A comprehensive SvelteKit form library for server and client validation
ts2typebox Creating TypeBox code from Typescript types
typebox-form-parser Parses form and query data based on TypeBox schemas
typebox-validators Advanced validators supporting discriminated and heterogeneous unions

Benchmark

This project maintains a set of benchmarks that measure Ajv, Value and TypeCompiler compilation and validation performance. These benchmarks can be run locally by cloning this repository and running npm run benchmark. The results below show for Ajv version 8.12.0 running on Node 20.10.0.

For additional comparative benchmarks, please refer to typescript-runtime-type-benchmarks.

Compile

This benchmark measures compilation performance for varying types.

┌────────────────────────────┬────────────┬──────────────┬──────────────┬──────────────┐
 (index)                     Iterations  Ajv           TypeCompiler  Performance  
├────────────────────────────┼────────────┼──────────────┼──────────────┼──────────────┤
 Literal_String              1000        '    211 ms'  '      8 ms'  '   26.38 x' 
 Literal_Number              1000        '    185 ms'  '      5 ms'  '   37.00 x' 
 Literal_Boolean             1000        '    195 ms'  '      4 ms'  '   48.75 x' 
 Primitive_Number            1000        '    149 ms'  '      7 ms'  '   21.29 x' 
 Primitive_String            1000        '    135 ms'  '      5 ms'  '   27.00 x' 
 Primitive_String_Pattern    1000        '    193 ms'  '     10 ms'  '   19.30 x' 
 Primitive_Boolean           1000        '    152 ms'  '      4 ms'  '   38.00 x' 
 Primitive_Null              1000        '    147 ms'  '      4 ms'  '   36.75 x' 
 Object_Unconstrained        1000        '   1065 ms'  '     26 ms'  '   40.96 x' 
 Object_Constrained          1000        '   1183 ms'  '     26 ms'  '   45.50 x' 
 Object_Vector3              1000        '    407 ms'  '      9 ms'  '   45.22 x' 
 Object_Box3D                1000        '   1777 ms'  '     24 ms'  '   74.04 x' 
 Tuple_Primitive             1000        '    485 ms'  '     11 ms'  '   44.09 x' 
 Tuple_Object                1000        '   1344 ms'  '     17 ms'  '   79.06 x' 
 Composite_Intersect         1000        '    606 ms'  '     14 ms'  '   43.29 x' 
 Composite_Union             1000        '    522 ms'  '     17 ms'  '   30.71 x' 
 Math_Vector4                1000        '    851 ms'  '      9 ms'  '   94.56 x' 
 Math_Matrix4                1000        '    406 ms'  '     10 ms'  '   40.60 x' 
 Array_Primitive_Number      1000        '    367 ms'  '      6 ms'  '   61.17 x' 
 Array_Primitive_String      1000        '    339 ms'  '      7 ms'  '   48.43 x' 
 Array_Primitive_Boolean     1000        '    325 ms'  '      5 ms'  '   65.00 x' 
 Array_Object_Unconstrained  1000        '   1863 ms'  '     21 ms'  '   88.71 x' 
 Array_Object_Constrained    1000        '   1535 ms'  '     18 ms'  '   85.28 x' 
 Array_Tuple_Primitive       1000        '    829 ms'  '     14 ms'  '   59.21 x' 
 Array_Tuple_Object          1000        '   1674 ms'  '     14 ms'  '  119.57 x' 
 Array_Composite_Intersect   1000        '    789 ms'  '     13 ms'  '   60.69 x' 
 Array_Composite_Union       1000        '    822 ms'  '     15 ms'  '   54.80 x' 
 Array_Math_Vector4          1000        '   1129 ms'  '     14 ms'  '   80.64 x' 
 Array_Math_Matrix4          1000        '    673 ms'  '      9 ms'  '   74.78 x' 
└────────────────────────────┴────────────┴──────────────┴──────────────┴──────────────┘

Validate

This benchmark measures validation performance for varying types.

┌────────────────────────────┬────────────┬──────────────┬──────────────┬──────────────┬──────────────┐
 (index)                     Iterations  ValueCheck    Ajv           TypeCompiler  Performance  
├────────────────────────────┼────────────┼──────────────┼──────────────┼──────────────┼──────────────┤
 Literal_String              1000000     '     17 ms'  '      5 ms'  '      5 ms'  '    1.00 x' 
 Literal_Number              1000000     '     14 ms'  '     18 ms'  '      9 ms'  '    2.00 x' 
 Literal_Boolean             1000000     '     14 ms'  '     20 ms'  '      9 ms'  '    2.22 x' 
 Primitive_Number            1000000     '     17 ms'  '     19 ms'  '      9 ms'  '    2.11 x' 
 Primitive_String            1000000     '     17 ms'  '     18 ms'  '     10 ms'  '    1.80 x' 
 Primitive_String_Pattern    1000000     '    172 ms'  '     46 ms'  '     41 ms'  '    1.12 x' 
 Primitive_Boolean           1000000     '     14 ms'  '     19 ms'  '     10 ms'  '    1.90 x' 
 Primitive_Null              1000000     '     16 ms'  '     19 ms'  '      9 ms'  '    2.11 x' 
 Object_Unconstrained        1000000     '    437 ms'  '     28 ms'  '     14 ms'  '    2.00 x' 
 Object_Constrained          1000000     '    653 ms'  '     46 ms'  '     37 ms'  '    1.24 x' 
 Object_Vector3              1000000     '    201 ms'  '     22 ms'  '     12 ms'  '    1.83 x' 
 Object_Box3D                1000000     '    961 ms'  '     37 ms'  '     19 ms'  '    1.95 x' 
 Object_Recursive            1000000     '   3715 ms'  '    363 ms'  '    174 ms'  '    2.09 x' 
 Tuple_Primitive             1000000     '    107 ms'  '     23 ms'  '     11 ms'  '    2.09 x' 
 Tuple_Object                1000000     '    375 ms'  '     28 ms'  '     15 ms'  '    1.87 x' 
 Composite_Intersect         1000000     '    377 ms'  '     22 ms'  '     12 ms'  '    1.83 x' 
 Composite_Union             1000000     '    337 ms'  '     30 ms'  '     17 ms'  '    1.76 x' 
 Math_Vector4                1000000     '    137 ms'  '     23 ms'  '     11 ms'  '    2.09 x' 
 Math_Matrix4                1000000     '    576 ms'  '     37 ms'  '     28 ms'  '    1.32 x' 
 Array_Primitive_Number      1000000     '    145 ms'  '     23 ms'  '     12 ms'  '    1.92 x' 
 Array_Primitive_String      1000000     '    152 ms'  '     22 ms'  '     13 ms'  '    1.69 x' 
 Array_Primitive_Boolean     1000000     '    131 ms'  '     20 ms'  '     13 ms'  '    1.54 x' 
 Array_Object_Unconstrained  1000000     '   2821 ms'  '     62 ms'  '     45 ms'  '    1.38 x' 
 Array_Object_Constrained    1000000     '   2958 ms'  '    119 ms'  '    134 ms'  '    0.89 x' 
 Array_Object_Recursive      1000000     '  14695 ms'  '   1621 ms'  '    635 ms'  '    2.55 x' 
 Array_Tuple_Primitive       1000000     '    478 ms'  '     35 ms'  '     28 ms'  '    1.25 x' 
 Array_Tuple_Object          1000000     '   1623 ms'  '     63 ms'  '     48 ms'  '    1.31 x' 
 Array_Composite_Intersect   1000000     '   1582 ms'  '     43 ms'  '     30 ms'  '    1.43 x' 
 Array_Composite_Union       1000000     '   1331 ms'  '     76 ms'  '     40 ms'  '    1.90 x' 
 Array_Math_Vector4          1000000     '    564 ms'  '     38 ms'  '     24 ms'  '    1.58 x' 
 Array_Math_Matrix4          1000000     '   2382 ms'  '    111 ms'  '     83 ms'  '    1.34 x' 
└────────────────────────────┴────────────┴──────────────┴──────────────┴──────────────┴──────────────┘

Compression

The following table lists esbuild compiled and minified sizes for each TypeBox module.

┌──────────────────────┬────────────┬────────────┬─────────────┐
 (index)               Compiled    Minified    Compression 
├──────────────────────┼────────────┼────────────┼─────────────┤
 typebox/compiler      '122.4 kb'  ' 53.4 kb'  '2.29 x'    
 typebox/errors        ' 67.6 kb'  ' 29.6 kb'  '2.28 x'    
 typebox/syntax        '132.9 kb'  ' 54.2 kb'  '2.45 x'    
 typebox/system        '  7.4 kb'  '  3.2 kb'  '2.33 x'    
 typebox/value         '150.1 kb'  ' 62.2 kb'  '2.41 x'    
 typebox               '106.8 kb'  ' 43.2 kb'  '2.47 x'    
└──────────────────────┴────────────┴────────────┴─────────────┘

Contribute

TypeBox is open to community contribution. Please ensure you submit an open issue before submitting your pull request. The TypeBox project prefers open community discussion before accepting new features.

Package Sidebar

Install

npm i @sinclair/typebox

Weekly Downloads

32,716,889

Version

0.34.11

License

MIT

Unpacked Size

1.69 MB

Total Files

1053

Last publish

Collaborators

  • sinclair