Nihilist Postmodern Mistake
    Have ideas to improve npm?Join in the discussion! »

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

    0.16.5 • Public • Published

    TypeBox

    JSON Schema Type Builder with Static Type Resolution for TypeScript

    npm version GitHub CI

    Example

    import { Static, Type } from '@sinclair/typebox'
    
    const T = Type.String() /* const T = { "type": "string" } */
    
    type T = Static<typeof T> /* type T = string */

    Install

    $ npm install @sinclair/typebox --save

    Overview

    TypeBox is a type builder library that creates in-memory JSON Schema objects that can be statically resolved to TypeScript types. The schemas produced by this library are built to match the static type checking rules of the TypeScript compiler. TypeBox allows one to create a single unified type that can be both statically checked by the TypeScript compiler and runtime asserted using standard JSON schema validation.

    TypeBox can be used as a simple tool to build up complex schemas or integrated into RPC or REST services to help validate JSON data received over the wire. TypeBox does not provide any JSON schema validation. Please use libraries such as AJV to validate schemas built with this library.

    Requires TypeScript 4.0.3 and above.

    License MIT

    Contents

    Example

    The following demonstrates TypeBox's general usage.

    import { Type, Static } from '@sinclair/typebox'
    
    //--------------------------------------------------------------------------------------------
    //
    // Let's say you have the following type ...
    //
    //--------------------------------------------------------------------------------------------
    
    type Record = {
        id: string,
        name: string,
        timestamp: number
    }
    
    //--------------------------------------------------------------------------------------------
    //
    // ... you can express this type in the following way.
    //
    //--------------------------------------------------------------------------------------------
    
    const Record = Type.Object({        // const Record = {
        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 Record = Static<typeof Record> // type Record = {
                                        //    id: string,
                                        //    name: string,
                                        //    timestamp: number
                                        // }
    
    //--------------------------------------------------------------------------------------------
    //
    // ... then use the type both as JSON schema and as a TypeScript type.
    //
    //--------------------------------------------------------------------------------------------
    
    function receive(record: Record) { // ... as a type
        if(JSON.validate(Record, {     // ... as a schema
            id: '42', 
            name: 'dave', 
            timestamp: Date.now() 
        })) {
            // ok...
        }
    }

    Types

    The following table outlines the TypeBox mappings between TypeScript and JSON schema.

    ┌────────────────────────────────┬─────────────────────────────┬────────────────────────────────┐
     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.RegEx(/foo/)	  type T = string              const T = {                    
                                                                     type: 'string',             
                                                                     pattern: 'foo'              
                                                                  }                              
       	                                                                                      
    ├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
     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.Dict(            type T = {const T = {                    
        Type.Number()                     [key: string]              type: 'object'              
     )                               } : number                      additionalProperties: {     
       	                                                            type: 'number'            
       	                                                          }                           
       	                                                       }                              
       	                                                                                      
    ├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
     const T = Type.Object({         type T = {const T = {                    
       x: Type.Number(),                x: number,                  type: 'object',              
       y: Type.Number()                 y: number                   additionalProperties: false, })                              }                              properties: {                
                                                                       x: {                      
       	                                                              type: 'number'          
       	                                                            },                        
       	                                                            y: {                      
                                                                         type: 'number'          
       	                                                            }                         
       	                                                         },                           
                                                                    required: ['x', 'y']         
       	                                                       }                              
       	                                                                                      
    ├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
     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,                            enum: [0, 1],               
       B                               B                             type: 'number'              }                               }                            }                              
                                                                                                 
     type T = Type.Enum(Foo)         type T = Foo                                                
                                                                                                 
    ├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
     const T = Type.Union([          type T = string | number     const T = {                    
       Type.String(),                                                anyOf: [{                   
       Type.Number()                                                    type: 'string'           
     ])                                                              }, {                        
                                                                        type: 'number'           
                                                                     }]                          
                                                                  }                              
       	                                                                                      
    ├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
     const T = Type.KeyOf(           type T = keyof {             const T = {                    
       Type.Object({                   x: number,                    enum: ['x', 'y'],           
         x: Type.Number(),             y: number                     type: 'string'              
         y: Type.Number()            }                            }                              
       })                                                                                        
     )                                                                                           
       	                                                                                      
    ├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
     const T = Type.Intersect([      type T = {const T = {                    
        Type.Object({                   x: number                   type: 'object',              
           x: Type.Number()          } & {                          additionalProperties: false, 
        }),                             y: number                   properties: {                
        Type.Object({}                                x: {                       
           y: Type.Number()                                              type: 'number'          
       })                                                             },                         
     })                                                               y: {                       
                                                                         type: 'number'          
                                                                      }                          
                                                                    },                           
                                                                    required: ['x', 'y']         
                                                                  }                              
       	                                                                                      
    ├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
     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                  properties: {                
              Type.Number()         | }>                               x: {                       
           ),                                                            type: 'number'          
           y: Type.Optional(                                          },                         
              Type.Number()                                           y: {                       
           )                                                             type: 'number'          
        })                                                            }                          
     )                                                              }                            
                                                                    required: ['x', 'y']         
                                                                  }                              
       	                                                                                      
    ├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
     const T = Type.Pick(            type T = Pick<{              const T = {                    
        Type.Object({                   x: number,                  type: 'object',              
           x: Type.Number(),            y: number                   properties: {                
           y: Type.Number(),        | }, 'x'>                          x: {                       
         }), ['x']                                                       type: 'number'          
     )                                                                }                          
                                                                    },                           
                                                                    required: ['x']              
                                                                  }                              
                                                                                                 
    ├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
     const T = Type.Omit(            type T = Omit<{              const T = {                    
        Type.Object({                   x: number,                  type: 'object',              
           x: Type.Number(),            y: number                   properties: {                
           y: Type.Number(),        | }, 'x'>                          y: {                       
         }), ['x']                                                       type: 'number'          
     )                                                                }                          
                                                                    },                           
                                                                    required: ['y']              
                                                                  }                              
                                                                                                 
    └────────────────────────────────┴─────────────────────────────┴────────────────────────────────┘

    Modifiers

    TypeBox provides modifiers that can be applied to an objects properties. This allows for optional and readonly to be applied to that property. The following table illustates how they map between TypeScript and JSON Schema.

    ┌────────────────────────────────┬─────────────────────────────┬────────────────────────────────┐
     TypeBox                         TypeScript                   JSON Schema                    
       	                                                                                      
    ├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
     const T = Type.Object({         type T = {                   const T = {                    
       name: Type.Optional(             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.ReadonlyOptional(     readonly name?: string,     type: 'object',              
          Type.String(),             }                              properties: {                
       )	                                                            name: {                   
     })  	                                                              type: 'string'          
       	                                                            }                         
       	                                                         }                            
                                                                  }                              
       	                                                                                      
    └────────────────────────────────┴─────────────────────────────┴────────────────────────────────┘

    Options

    You can pass additional JSON schema properties on the last argument of any given type. The following are some examples.

    // string must be an email
    const T = Type.String({ format: 'email' })
    
    // number must be a multiple of 2
    const T = Type.Number({ multipleOf: 2 })
    
    // array must have at least 5 integer values
    const T = Type.Array(Type.Integer(), { minItems: 5 })

    Strict

    TypeBox includes the properties kind and modifier on each underlying schema. These properties are used to help TypeBox statically resolve the schemas to the appropriate TypeScript type as well as apply the appropriate modifiers to an objects properties (such as optional). These properties are not strictly valid JSON schema so in some cases it may be desirable to omit them. TypeBox provides a Type.Strict() function that will omit these properties if nessasary.

    const T = Type.Object({                 // const T = {
        name: Type.Optional(Type.String())  //   kind: Symbol(ObjectKind),
    })                                      //   type: 'object',
                                            //   properties: {
                                            //     name: {
                                            //       kind: Symbol(StringKind),
                                            //       type: 'string',
                                            //       modifier: Symbol(OptionalModifier)
                                            //     }
                                            //   }
                                            // }
    
    const U = Type.Strict(T)                // const U = {
                                            //     type: 'object', 
                                            //     properties: { 
                                            //         name: { 
                                            //             type: 'string' 
                                            //         } 
                                            //     } 
                                            // }

    Extended Types

    In addition to JSON schema types, TypeBox provides several extended types that allow for function and constructor types to be composed. These additional types are not valid JSON Schema and will not validate using typical JSON Schema validation. However, these types can be used to frame JSON schema and describe callable interfaces that may receive JSON validated data. These types are as follows.

    ┌────────────────────────────────┬─────────────────────────────┬────────────────────────────────┐
     TypeBox                         TypeScript                   Extended Schema                
       	                                                                                      
    ├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
     const T = Type.Constructor([    type T = new (               const T = {                    
    |    Type.String(),                arg0: string,                 type: 'constructor'          
        Type.Number(),                arg1: number                  arguments: [{                
     ], 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                  arguments: [{                
     ], 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.Undefined()      type T = undefined           const T = {
    |                                                                type: 'undefined'            
    |                                                              }                              
       	                                                                                      
    ├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
     const T = Type.Void()           type T = void                const T = {                    
    |                                                                type: 'void'                 │
    |                                │                             │ }                              │
    │   	                         │                             │                                │
    └────────────────────────────────┴─────────────────────────────┴────────────────────────────────┘

    Interfaces

    It is possible to create interfaces from TypeBox types. Consider the following code that creates a ControllerInterface type that has a single function createRecord(...). The following is how one might approach this in TypeScript.

    interface CreateRecordRequest {
        data: string
    }
    
    interface CreateRecordResponse {
        id: string
    }
    
    interface ControllerInterface {
        createRecord(record: CreateRecordRequest): Promise<CreateRecordResponse>
    }
    
    class Controller implements ControllerInterface {
        async createRecord(record: CreateRecordRequest): Promise<CreateRecordResponse> {
            return { id: '1' }
        }
    }

    The following is the TypeBox equivalent.

    import { Type, Static } from '@sinclair/typebox'
    
    type CreateRecordRequest = Static<typeof CreateRecordRequest>
    const CreateRecordRequest = Type.Object({
        data: Type.String()
    })
    type CreateRecordResponse = Static<typeof CreateRecordResponse>
    const CreateRecordResponse = Type.Object({
        id: Type.String()
    })
    
    type ControllerInterface = Static<typeof ControllerInterface>
    const ControllerInterface = Type.Object({
        createRecord: Type.Function([CreateRecordRequest], Type.Promise(CreateRecordResponse))
    })
    
    class Controller implements ControllerInterface {
        async createRecord(record: CreateRecordRequest): Promise<CreateRecordResponse> {
            return { id: '1' }
        }
    }

    Because TypeBox encodes the type information as JSON schema, it now becomes possible to reflect on the JSON schema to produce sharable metadata that can be used as machine readable documentation.

    console.log(JSON.stringify(ControllerInterface, null, 2))
    // outputs:
    //
    // {
    //   "type": "object",
    //   "properties": {
    //     "createRecord": {
    //       "type": "function",
    //       "arguments": [
    //         {
    //           "type": "object",
    //           "properties": {
    //             "data": {
    //               "type": "string"
    //             }
    //           },
    //           "required": [
    //             "data"
    //           ]
    //         }
    //       ],
    //       "returns": {
    //         "type": "promise",
    //         "item": {
    //           "type": "object",
    //           "properties": {
    //             "id": {
    //               "type": "string"
    //             }
    //           },
    //           "required": [
    //             "id"
    //           ]
    //         }
    //       }
    //     }
    //   },
    //   "required": [
    //     "createRecord"
    //   ]
    // }

    Validation

    TypeBox does not provide JSON schema validation out of the box and expects users to select an appropriate JSON schema validation library for their needs. TypeBox schemas should match JSON Schema draft 6 so any library capable of draft 6 should be fine. A good library to use for validation is Ajv. The following example shows setting up Ajv 7 to work with TypeBox.

    $ npm install ajv ajv-formats --save
    import { Type } from '@sinclair/typebox'
    import addFormats from 'ajv-formats'
    import Ajv from 'ajv'
    
    // Setup
    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'
    ]).addKeyword('kind')
      .addKeyword('modifier')
    
    // TypeBox
    const User = Type.Object({
        name: Type.String(),
        email: Type.String({ format: 'email' })
    })
    
    // Validate
    const isValid = ajv.validate(User, { 
        name: 'dave', 
        email: 'dave@domain.com' 
    })
    
    //
    // isValid -> true
    //

    Install

    npm i @sinclair/typebox

    DownloadsWeekly Downloads

    6,176

    Version

    0.16.5

    License

    MIT

    Unpacked Size

    87.5 kB

    Total Files

    6

    Last publish

    Collaborators

    • avatar