0.34.33 • Published 3 months ago

@sinclair/typebox v0.34.33

Weekly downloads
5,421
License
MIT
Repository
github
Last release
3 months ago

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'                 │
│                                │                             │ }                              │
│                                │                             │                                │
└────────────────────────────────┴─────────────────────────────┴────────────────────────────────┘

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 generic functions.

const Nullable = <T extends TSchema>(T: T) => {     // type Nullable<T> = T | null
  return Type.Union([T, Type.Null()])
}

const T = Nullable(Type.String())                  // type T = Nullable<string>

Recursive Types

Use the Recursive function to create recursive types.

const Node = Type.Recursive(This => Type.Object({    // const Node = {
  id: Type.String(),                                 //   $id: 'Node',
  nodes: Type.Array(This)                            //   type: 'object',
}), { $id: 'Node' })                                 //   properties: {
                                                     //     id: {
                                                     //       type: 'string'
                                                     //     },
                                                     //     nodes: {
                                                     //       type: 'array',
                                                     //       items: {
                                                     //         $ref: 'Node'
                                                     //       }
                                                     //     }
                                                     //   },
                                                     //   required: [
                                                     //     'id',
                                                     //     'nodes'
                                                     //   ]
                                                     // }

type Node = Static<typeof Node>                      // type Node = {
                                                     //   id: string
                                                     //   nodes: Node[]
                                                     // }

function test(node: Node) {
  const id = node.nodes[0].nodes[0].id               // id is string
}

Module Types

Module types are containers for a set of referential types. Modules act as namespaces, enabling types to reference one another via string identifiers. Modules support both singular and mutually recursive references, as well as deferred dereferencing for computed types such as Partial. Types imported from a module are expressed using the Json Schema $defs keyword.

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
  }),                                           // }>
})
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

@argoncs/server@argoncs/upload@api-components-nodejs/fastify-rest-interface@nickcherry/nickjsevo-searchdelivery-parametersintegration-services-browser-compemeris-dexinfogym-app-shared@chijs/core@samelogic/micro-surveyenginemq-clientautoapprove.titles@project-carbon/server@project-carbon/sharedtitles-workflow-server@cocs/backend@cocs/common@scow/config@scow/lib-config@infinitebrahmanuniverse/nolb-_sinactivepieces-youtrackpiece-line@everything-registry/sub-chunk-837@anjirauto/piece-gmail@anjirauto/piece-openai@anjirauto/piece-telegram-bot@anjirauto/piece-woocommerce@exotjs/exot@anjirauto/ap-google-my-business@anjirauto/piece-spotify@dennisrijsdijk/streamdeck-ts@tracktile/veritas@integration-app/endpoint-sdksveltekit-superformstest-activepieceswobe-validatorwinter-cardano-meshwaitsocketspiceflowvitest-iteratorvidulivoluptatummolestiae@activepieces/piece-pushover@acedempire/piece-twilio-v2@dmitrymin/eventmapper-common@dopt/ai-assistant-definition@dopt/ai-assistant-javascript@dopt/block-api-types@dopt/block-types@directus/themes@draftiy/json-form-builder@coasy/piece-coasy@clusterio/host@clusterio/lib@clusterio/plugin-global_chat@clusterio/plugin-inventory_sync@clusterio/plugin-player_auth@clusterio/plugin-research_sync@clusterio/plugin-subspace_storage@clusterio/controller@cthunline/games@d-dev/eslint-plugin@comapeo/cloud@comapeo/core@connext/chain-abstraction@connext/channel-commitments@connext/nxtp-adapters-subgraph@connext/nxtp-sdk@connext/nxtp-txservice@connext/vector-protocol@connext/vector-types@console-cat/sdk@cyruskao/twse-notifier@d0rtal/common-types@d0rtal/types@devacour/auth-web@devacour/iam-web@devacour/model-base@devacour/platform-typebox@devacour/web-fastify2@devacour/web-render@devacour/web-schema@developbharat/turbo@dragonnaked311/twitter-scraper-edge@dovetail-ui/ui@bemoje/openai-gpt-client@bemoje/bfind@rosepg/rose-cli@rromadhoni/fastisfy@rsdk/cli.cmd.kafka@rsdk/cli.common@rsdk/yarn.constraintsbuild-serviceiota-is-clientiota-is-sdkjaz-ts-utilskeq-cli@indiex/silo@danielrataj/piece-slack-event
0.33.21

8 months ago

0.33.20

8 months ago

0.33.22

8 months ago

0.33.19

8 months ago

0.33.18

8 months ago

0.34.32

3 months ago

0.34.33

3 months ago

0.34.30

4 months ago

0.34.31

3 months ago

0.34.21

5 months ago

0.34.22

5 months ago

0.34.20

5 months ago

0.34.29

4 months ago

0.34.27

4 months ago

0.34.28

4 months ago

0.34.25

5 months ago

0.34.26

4 months ago

0.34.23

5 months ago

0.34.24

5 months ago

0.34.10

7 months ago

0.34.11

7 months ago

0.34.18

5 months ago

0.34.19

5 months ago

0.34.16

5 months ago

0.34.17

5 months ago

0.34.14

6 months ago

0.34.15

5 months ago

0.34.12

7 months ago

0.34.13

6 months ago

0.34.6

7 months ago

0.34.5

7 months ago

0.34.4

8 months ago

0.34.3

8 months ago

0.34.2

8 months ago

0.34.1

8 months ago

0.34.0

8 months ago

0.34.9

7 months ago

0.34.8

7 months ago

0.34.7

7 months ago

0.33.17

9 months ago

0.33.16

9 months ago

0.33.15

9 months ago

0.33.14

9 months ago

0.33.13

9 months ago

0.33.10

10 months ago

0.33.7

11 months ago

0.33.6

11 months ago

0.33.5

11 months ago

0.33.4

11 months ago

0.33.3

11 months ago

0.33.2

11 months ago

0.33.1

11 months ago

0.33.0

11 months ago

0.33.12

10 months ago

0.33.9

10 months ago

0.33.11

10 months ago

0.33.8

10 months ago

0.32.31

1 year ago

0.32.35

12 months ago

0.32.34

1 year ago

0.32.33

1 year ago

0.32.32

1 year ago

0.32.30

1 year ago

0.32.29

1 year ago

0.32.28

1 year ago

0.32.27

1 year ago

0.32.26

1 year ago

0.32.25

1 year ago

0.32.24

1 year ago

0.32.23

1 year ago

0.32.22

1 year ago

0.32.21

1 year ago

0.32.20

1 year ago

0.32.19

1 year ago

0.32.18

1 year ago

0.32.17

1 year ago

0.32.16

1 year ago

0.32.15

1 year ago

0.32.14

1 year ago

0.32.13

1 year ago

0.32.12

1 year ago

0.32.11

1 year ago

0.32.10

1 year ago

0.32.9

1 year ago

0.32.8

1 year ago

0.32.7

1 year ago

0.32.6

1 year ago

0.32.5

1 year ago

0.32.4

2 years ago

0.32.3

2 years ago

0.32.2

2 years ago

0.32.1

2 years ago

0.32.0

2 years ago

0.32.0-dev-28

2 years ago

0.32.0-dev-24

2 years ago

0.32.0-dev-25

2 years ago

0.32.0-dev-26

2 years ago

0.32.0-dev-27

2 years ago

0.32.0-dev-22

2 years ago

0.32.0-dev-23

2 years ago

0.32.0-dev-21

2 years ago

0.32.0-dev-20

2 years ago

0.32.0-dev-18

2 years ago

0.32.0-dev-19

2 years ago

0.32.0-dev-17

2 years ago

0.32.0-dev-16

2 years ago

0.32.0-dev-15

2 years ago

0.32.0-dev-14

2 years ago

0.29.0

2 years ago

0.29.6

2 years ago

0.29.5

2 years ago

0.29.4

2 years ago

0.29.3

2 years ago

0.29.2

2 years ago

0.29.1

2 years ago

0.31.0-dev-2

2 years ago

0.31.0-dev-1

2 years ago

0.30.0-dev-6

2 years ago

0.30.0-dev-7

2 years ago

0.30.0-dev-4

2 years ago

0.30.0-dev-5

2 years ago

0.30.0-dev-2

2 years ago

0.30.0-dev-3

2 years ago

0.30.0-dev-1

2 years ago

0.30.4

2 years ago

0.30.3

2 years ago

0.30.2

2 years ago

0.30.1

2 years ago

0.30.0

2 years ago

0.31.9

2 years ago

0.31.8

2 years ago

0.31.7

2 years ago

0.31.6

2 years ago

0.31.5

2 years ago

0.31.4

2 years ago

0.31.3

2 years ago

0.31.2

2 years ago

0.31.1

2 years ago

0.31.0

2 years ago

0.31.10

2 years ago

0.31.11

2 years ago

0.31.12

2 years ago

0.31.13

2 years ago

0.31.14

2 years ago

0.31.15

2 years ago

0.31.16

2 years ago

0.31.17

2 years ago

0.31.18

2 years ago

0.31.19

2 years ago

0.32.0-dev-10

2 years ago

0.32.0-dev-11

2 years ago

0.32.0-dev-12

2 years ago

0.32.0-dev-13

2 years ago

0.31.20

2 years ago

0.31.21

2 years ago

0.31.22

2 years ago

0.31.23

2 years ago

0.31.24

2 years ago

0.31.25

2 years ago

0.31.26

2 years ago

0.31.27

2 years ago

0.31.28

2 years ago

0.32.0-dev-7

2 years ago

0.32.0-dev-6

2 years ago

0.32.0-dev-9

2 years ago

0.32.0-dev-8

2 years ago

0.32.0-dev-3

2 years ago

0.32.0-dev-2

2 years ago

0.32.0-dev-5

2 years ago

0.32.0-dev-4

2 years ago

0.32.0-dev-1

2 years ago

0.28.20

2 years ago

0.28.19

2 years ago

0.28.18

2 years ago

0.28.17

2 years ago

0.28.12

2 years ago

0.28.11

2 years ago

0.28.10

2 years ago

0.28.16

2 years ago

0.28.15

2 years ago

0.28.14

2 years ago

0.28.13

2 years ago

0.28.9

2 years ago

0.26.0-dev.3

2 years ago

0.26.0-dev.2

2 years ago

0.26.0-dev.5

2 years ago

0.26.0-dev.4

2 years ago

0.26.0-dev.1

2 years ago

0.26.3

2 years ago

0.26.2

2 years ago

0.26.1

2 years ago

0.26.0

2 years ago

0.26.8

2 years ago

0.26.7

2 years ago

0.26.6

2 years ago

0.26.5

2 years ago

0.26.4

2 years ago

0.27.2

2 years ago

0.27.1

2 years ago

0.27.0

2 years ago

0.27.8

2 years ago

0.27.7

2 years ago

0.27.6

2 years ago

0.27.5

2 years ago

0.27.4

2 years ago

0.27.3

2 years ago

0.26.0-dev

2 years ago

0.28.1

2 years ago

0.28.0

2 years ago

0.25.22

2 years ago

0.25.23

2 years ago

0.25.24

2 years ago

0.28.8

2 years ago

0.28.7

2 years ago

0.28.6

2 years ago

0.28.5

2 years ago

0.28.4

2 years ago

0.28.3

2 years ago

0.28.2

2 years ago

0.25.18

2 years ago

0.25.19

2 years ago

0.25.14

3 years ago

0.25.15

3 years ago

0.25.16

3 years ago

0.25.17

2 years ago

0.25.11

3 years ago

0.25.12

3 years ago

0.25.13

3 years ago

0.25.21

2 years ago

0.25.20

2 years ago

0.24.47

3 years ago

0.24.46

3 years ago

0.24.49

3 years ago

0.24.48

3 years ago

0.25.10

3 years ago

0.24.45

3 years ago

0.25.4

3 years ago

0.25.3

3 years ago

0.25.2

3 years ago

0.25.1

3 years ago

0.25.0

3 years ago

0.25.9

3 years ago

0.25.8

3 years ago

0.25.7

3 years ago

0.25.6

3 years ago

0.25.5

3 years ago

0.24.50

3 years ago

0.24.51

3 years ago

0.24.43

3 years ago

0.24.42

3 years ago

0.24.44

3 years ago

0.24.41

3 years ago

0.24.40

3 years ago

0.24.39

3 years ago

0.24.36

3 years ago

0.24.35

3 years ago

0.24.38

3 years ago

0.24.37

3 years ago

0.24.32

3 years ago

0.24.31

3 years ago

0.24.34

3 years ago

0.24.33

3 years ago

0.24.30

3 years ago

0.24.29

3 years ago

0.24.28

3 years ago

0.24.25

3 years ago

0.24.24

3 years ago

0.24.27

3 years ago

0.24.26

3 years ago

0.24.21

3 years ago

0.24.20

3 years ago

0.24.23

3 years ago

0.24.22

3 years ago

0.24.18

3 years ago

0.24.17

3 years ago

0.24.19

3 years ago

0.24.14

3 years ago

0.24.13

3 years ago

0.24.16

3 years ago

0.24.15

3 years ago

0.24.10

3 years ago

0.24.12

3 years ago

0.24.11

3 years ago

0.24.5

3 years ago

0.24.4

3 years ago

0.24.3

3 years ago

0.24.2

3 years ago

0.24.1

3 years ago

0.24.0

3 years ago

0.24.9

3 years ago

0.24.8

3 years ago

0.24.7

3 years ago

0.24.6

3 years ago

0.23.5

3 years ago

0.23.4

3 years ago

0.23.3

3 years ago

0.23.2

4 years ago

0.23.1

4 years ago

0.23.0

4 years ago

0.21.2

4 years ago

0.21.1

4 years ago

0.21.0

4 years ago

0.20.6

4 years ago

0.22.1

4 years ago

0.22.0

4 years ago

0.20.5

4 years ago

0.20.4

4 years ago

0.20.3

4 years ago

0.20.2

4 years ago

0.20.1

4 years ago

0.20.0

4 years ago

0.19.0

4 years ago

0.19.1

4 years ago

0.19.2

4 years ago

0.18.1

4 years ago

0.18.0

4 years ago

0.17.8

4 years ago

0.17.5

4 years ago

0.17.6

4 years ago

0.17.7

4 years ago

0.17.3

4 years ago

0.17.4

4 years ago

0.17.2

4 years ago

0.17.0

4 years ago

0.17.1

4 years ago

0.16.6

4 years ago

0.16.7

4 years ago

0.16.5

4 years ago

0.16.4

4 years ago

0.16.3

4 years ago

0.16.2

4 years ago

0.16.1

4 years ago

0.16.0

4 years ago

0.15.0

4 years ago

0.14.0

4 years ago

0.14.1

4 years ago

0.12.9

4 years ago

0.12.8

4 years ago

0.12.7

5 years ago

0.12.6

5 years ago

0.12.5

5 years ago

0.12.4

5 years ago

0.12.3

5 years ago

0.12.2

5 years ago

0.12.0

5 years ago

0.12.1

5 years ago

0.11.0

5 years ago

0.10.1

5 years ago

0.10.0

5 years ago

0.9.16

5 years ago

0.9.15

5 years ago

0.9.14

5 years ago

0.9.13

5 years ago

0.9.12

5 years ago

0.9.10

5 years ago

0.9.11

5 years ago

0.9.9

5 years ago

0.9.8

5 years ago

0.9.7

5 years ago

0.9.6

5 years ago

0.9.5

5 years ago

0.9.4

5 years ago

0.9.3

5 years ago

0.9.2

5 years ago

0.9.1

5 years ago

0.9.0

5 years ago

0.8.1

5 years ago

0.8.0

5 years ago