Repository
Current version released
2 years ago
Versions
- 0.34.0Latest
- 0.33.22
- 0.33.22
- 0.33.21
- 0.33.20
- 0.33.20
- 0.33.19
- 0.33.18
- 0.33.18
- 0.33.17
- 0.33.16
- 0.33.15
- 0.33.14
- 0.33.12
- 0.33.11
- 0.33.10
- 0.33.9
- 0.33.8
- 0.33.7
- 0.33.7
- 0.33.6
- 0.33.6
- 0.33.5
- 0.33.4
- 0.33.3
- 0.33.2
- 0.33.2
- 0.33.1
- 0.33.0
- 0.32.35
- 0.32.34
- 0.32.33
- 0.32.32
- 0.32.30
- 0.32.29
- 0.32.28
- 0.32.27
- 0.32.27
- 0.32.25
- 0.32.24
- 0.32.23
- 0.32.22
- 0.32.21
- 0.32.20
- 0.32.19
- 0.32.18
- 0.32.18
- 0.32.17
- 0.32.16
- 0.32.15
- 0.32.14
- 0.32.13
- 0.32.12
- 0.32.11
- 0.32.10
- 0.32.9
- 0.32.8
- 0.32.7
- 0.32.6
- 0.32.5
- 0.32.4
- 0.32.3
- 0.32.2
- 0.32.1
- 0.32.0
- 0.31.28
- 0.31.27
- 0.31.26
- 0.31.25
- 0.31.24
- 0.31.23
- 0.31.23
- 0.31.22
- 0.31.21
- 0.31.20
- 0.31.19
- 0.31.18
- 0.31.17
- 0.31.16
- 0.31.15
- 0.31.14
- 0.31.13
- 0.31.11
- 0.31.10
- 0.31.9
- 0.31.8
- 0.31.8
- 0.31.7
- 0.31.6
- 0.31.5
- 0.31.4
- 0.31.3
- 0.31.2
- 0.31.1
- 0.31.1
- 0.31.0
- 0.30.4
- 0.30.3
- 0.30.2
- 0.30.1
- 0.30.0
- 0.29.6
- 0.29.5
- 0.29.4
- 0.29.3
- 0.29.2
- 0.29.2
- 0.29.1
- 0.29.1
- 0.29.0
- 0.28.20
- 0.28.19
- 0.28.18
- 0.28.17
- 0.28.16
- 0.28.16
- 0.28.15
- 0.28.14
- 0.28.14
- 0.28.13
- 0.28.12
- 0.28.11
- 0.28.10
- 0.28.9
- 0.28.8
- 0.28.7
- 0.28.6
- 0.28.5
- 0.28.4
- 0.28.3
- 0.28.2
- 0.28.1
- 0.28.1
- 0.28.0
- 0.27.8
- 0.27.7
- 0.27.6
- 0.27.5
- 0.27.4
- 0.27.3
- 0.27.2
- 0.27.1
- 0.27.0
- 0.26.8
- 0.26.7
- 0.26.6
- 0.26.5
- 0.26.4
- 0.26.3
- 0.26.2
- 0.26.1
- 0.26.0
- 0.26.0-dev.5
- 0.26.0-dev.4
- 0.26.0-dev.3
- 0.26.0-dev.2
- 0.26.0-dev.1
- 0.26.0-dev
- 0.25.24
- 0.25.23
- 0.25.22
- 0.25.21
- 0.25.20
- 0.25.19
- 0.25.18
- 0.25.17
- 0.25.16
- 0.25.15
- 0.25.14
- 0.25.13
- 0.25.12
- 0.25.11
- 0.25.10
- 0.25.9
- 0.25.8
- 0.25.7
- 0.25.6
- 0.25.5
- 0.25.4
- 0.25.3
- 0.25.2
- 0.25.1
- 0.25.0
- 0.24.51
- 0.24.50
- 0.24.49
- 0.24.48
- 0.24.47
- 0.24.46
- 0.24.45
- 0.24.44
- 0.24.43
- 0.24.42
- 0.24.41
- 0.24.40
- 0.24.39
- 0.24.38
- 0.24.37
- 0.24.36
- 0.24.35
- 0.24.34
- 0.24.33
- 0.24.32
- 0.24.31
- 0.24.30
- 0.24.29
- 0.24.28
- 0.24.27
- 0.24.26
- 0.24.25
- 0.24.24
- 0.24.23
- 0.24.22
- 0.24.21
- 0.24.20
- 0.24.19
- 0.24.18
- 0.24.17
- 0.24.16
- 0.24.15
- 0.24.14
- 0.24.13
- 0.24.12
- 0.24.11
- 0.24.10
- 0.24.9
- 0.24.8
- 0.24.7
- 0.24.6
- 0.24.5
- 0.24.4
- 0.24.3
- 0.24.2
- 0.24.1
- 0.24.0
- 0.23.4
- 0.23.3
- 0.23.1
- 0.23.0
- 0.22.1
- 0.22.0
- 0.21.2
- 0.21.2
- 0.21.1
- 0.21.0
- 0.20.6
- 0.20.5
- 0.20.4
- 0.20.3
- 0.20.2
- 0.20.1
- 0.20.0
- 0.19.2
- 0.19.1
- 0.19.0
- 0.18.1
- 0.18.0
- 0.17.8
- 0.17.7
TypeBox
JSON Schema Type Builder with Static Type Resolution for TypeScript
Install
Node
$ npm install @sinclair/typebox --saveDeno
import { Static, Type } from 'https://deno.land/x/typebox/src/typebox.ts'Example
import { Static, Type } from '@sinclair/typebox'
const T = Type.String() // const T = { type: 'string' }
type T = Static<typeof T> // type T = stringOverview
TypeBox is a type builder library that creates in-memory JSON Schema objects that can be statically inferred as TypeScript types. The schemas produced by this library are designed to match the static type checking rules of the TypeScript compiler. TypeBox allows one to compose unified types that can be statically asserted by the TypeScript compiler as well as 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. It can be used in both TypeScript and JavaScript environments.
License MIT
Contents
- Install
- Overview
- Usage
- Types
- Modifiers
- Options
- Extended Types
- Reference Types
- Recursive Types
- Generic Types
- Unsafe Types
- Values
- Guards
- Strict
- Validation
- Compiler
- Contribute
Usage
The following demonstrates TypeBox’s general usage.
import { Static, Type } 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
// }
//--------------------------------------------------------------------------------------------
//
// ... then use the type both as JSON schema and as a TypeScript type.
//
//--------------------------------------------------------------------------------------------
function receive(value: T) { // ... as a Type
if(JSON.validate(T, value)) { // ... as a Schema
// 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.Object({ │ type T = { │ const T = { │
│ x: Type.Number(), │ x: number, │ type: 'object', │
│ y: Type.Number() │ y: number │ 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, │ anyOf: [{ │
│ B │ B │ type: 'number', │
│ } │ } │ const: 0 │
│ │ │ }, { │
│ const T = Type.Enum(Foo) │ type T = Foo │ type: 'number', │
│ │ │ const: 1 │
│ │ │ }] │
│ │ │ } │
│ │ │ │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ 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 │ type: 'object', │
│ x: Type.Number() │ } & { │ properties: { │
│ }), │ y: number │ x: { │
│ Type.Object({ │ } │ type: 'number' │
│ y: Type.Number() │ │ }, │
│ }) │ │ y: { │
│ ]) │ │ type: 'number' │
│ │ │ } │
│ │ │ }, │
│ │ │ required: ['x', 'y'] │
│ │ │ } │
│ │ │ │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ 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 │ 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 options 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 })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.Uint8Array() │ type T = Uint8Array │ const T = { │
│ │ │ type: 'object', │
│ │ │ specialized: 'Uint8Array' │
│ │ │ } │
│ │ │ │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ 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: 'object', │
│ │ │ specialized: 'Undefined' │
│ │ │ } │
│ │ │ │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Void() │ type T = void │ const T = { │
│ │ │ type: 'null' │
│ │ │ } │
│ │ │ │
└────────────────────────────────┴─────────────────────────────┴────────────────────────────────┘Reference Types
Use Type.Ref(...) to create referenced types. The target type must specify an $id.
const T = Type.String({ $id: 'T' }) // const T = {
// $id: 'T',
// type: 'string'
// }
const R = Type.Ref(T) // const R = {
// $ref: 'T'
// }Recursive Types
Use Type.Recursive(...) to create recursive types.
const Node = Type.Recursive(Node => Type.Object({ // const Node = {
id: Type.String(), // $id: "Node",
nodes: Type.Array(Node), // 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: ...[]
// }
function test(node: Node) {
const id = node.nodes[0].nodes[0].nodes[0] // id is string
.nodes[0].nodes[0].nodes[0]
.nodes[0].nodes[0].nodes[0]
.id
}Generic Types
Generic types can be created using functions. The following creates a generic Nullable<T> type.
import { Type, Static, TSchema } from '@sinclair/typebox'
const Nullable = <T extends TSchema>(type: T) => Type.Union([type, Type.Null()])
const T = Nullable(Type.String()) // const T = {
// anyOf: [{
// type: 'string'
// }, {
// type: 'null'
// }]
// }
type T = Static<typeof T> // type T = string | null
const U = Nullable(Type.Number()) // const U = {
// anyOf: [{
// type: 'number'
// }, {
// type: 'null'
// }]
// }
type U = Static<typeof U> // type U = number | nullUnsafe Types
Use Type.Unsafe(...) to create custom schemas with user defined inference rules.
const T = Type.Unsafe<string>({ type: 'number' }) // const T = {
// type: 'number'
// }
type T = Static<typeof T> // type T = stringThe Type.Unsafe(...) function can be used to create schemas for validators that require specific schema representations. An example of this would be OpenAPI’s nullable and enum schemas which are not provided by TypeBox. The following demonstrates using Type.Unsafe(...) to create these types.
import { Type, Static, TSchema } from '@sinclair/typebox'
//--------------------------------------------------------------------------------------------
//
// Nullable<T>
//
//--------------------------------------------------------------------------------------------
function Nullable<T extends TSchema>(schema: T) {
return Type.Unsafe<Static<T> | null>({ ...schema, nullable: true })
}
const T = Nullable(Type.String()) // const T = {
// type: 'string',
// nullable: true
// }
type T = Static<typeof T> // type T = string | null
//--------------------------------------------------------------------------------------------
//
// StringUnion<[...]>
//
//--------------------------------------------------------------------------------------------
function StringEnum<T extends string[]>(values: [...T]) {
return Type.Unsafe<T[number]>({ enum: values })
}
const T = StringEnum(['A', 'B', 'C']) // const T = {
// enum: ['A', 'B', 'C']
// }
type T = Static<typeof T> // type T = 'A' | 'B' | 'C'Values
Use Value.Create(...) to generate values from types.
import { Value } from '@sinclair/typebox/value'
import { Type } from '@sinclair/typebox'
const T = Type.Object({
x: Type.Number({ default: 1 }),
y: Type.Number(),
})
const V = Value.Create(T) // const V = {
// x: 1,
// y: 0,
// }Use Value.Cast(...) to cast a value into a given type.
import { Value } from '@sinclair/typebox/value'
import { Type } from '@sinclair/typebox'
const T = Type.Object({
x: Type.Number(),
y: Type.Number()
})
const A = Value.Cast(T, null) // const A = { x: 0, y: 0 }
const B = Value.Cast(T, { x: 1 }) // const B = { x: 1, y: 0 }
const C = Value.Cast(T, { x: 1, y: 2, z: 3 }) // const C = { x: 1, y: 2 }Guards
Use a TypeGuard to test if a value meets a TypeBox type specification. Guards can be helpful when reflecting types.
import { TypeGuard } from '@sinclair/typebox/guard'
import { Type } from '@sinclair/typebox'
const T = Type.String()
if(TypeGuard.TString(T)) {
// T is TString
}
Strict
TypeBox schemas contain the Kind and Modifier symbol properties. These properties are provided to enable runtime type reflection on schemas, as well as helping TypeBox internally compose types. 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 necessary.
const T = Type.Object({ // const T = {
name: Type.Optional(Type.String()) // [Kind]: 'Object',
}) // type: 'object',
// properties: {
// name: {
// [Kind]: 'String',
// type: 'string',
// [Modifier]: 'Optional'
// }
// }
// }
const U = Type.Strict(T) // const U = {
// type: 'object',
// properties: {
// name: {
// type: 'string'
// }
// }
// }Validation
TypeBox schemas target JSON Schema draft 6 so any validator capable of draft 6 should be fine. A good library to use for validation in JavaScript environments is AJV. The following example shows setting up AJV 7 to work with TypeBox.
$ npm install ajv ajv-formats --save//--------------------------------------------------------------------------------------------
//
// Import TypeBox and AJV
//
//--------------------------------------------------------------------------------------------
import { Type } from '@sinclair/typebox'
import addFormats from 'ajv-formats'
import Ajv from 'ajv'
//--------------------------------------------------------------------------------------------
//
// Setup AJV validator with the following options and formats
//
//--------------------------------------------------------------------------------------------
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'
])
//--------------------------------------------------------------------------------------------
//
// Create a TypeBox type
//
//--------------------------------------------------------------------------------------------
const T = Type.Object({
x: Type.Number(),
y: Type.Number(),
z: Type.Number(),
})
//--------------------------------------------------------------------------------------------
//
// Validate Data
//
//--------------------------------------------------------------------------------------------
const R = ajv.validate(T, { x: 1, y: 2, z: 3 }) // const R = truePlease refer to the official AJV documentation for additional information on using AJV.
Compiler
TypeBox provides an optional high performance runtime type checker that can be used in applications that require extremely fast validation. This type checker is optimized for TypeBox types only whose schematics are known in advance. If defining custom schemas with Type.Unsafe<T> please consider AJV.
The following demonstrates its use.
import { TypeCompiler } from '@sinclair/typebox/compiler'
import { Type } from '@sinclair/typebox'
const C = TypeCompiler.Compile(Type.Object({ // const C: TypeCheck<TObject<{
x: Type.Number(), // x: TNumber;
y: Type.Number(), // y: TNumber;
z: Type.Number() // z: TNumber;
})) // }>>
const R = C.Check({ x: 1, y: 2, z: 3 }) // const R = true Validation errors can be read with the Errors(...) function.
const C = TypeCompiler.Compile(Type.Object({ // const C: TypeCheck<TObject<{
x: Type.Number(), // x: TNumber;
y: Type.Number(), // y: TNumber;
z: Type.Number() // z: TNumber;
})) // }>>
const value = { }
const errors = [...C.Errors(value)] // const errors = [{
// schema: { type: 'number' },
// path: '/x',
// value: undefined,
// message: 'Expected number'
// }, {
// schema: { type: 'number' },
// path: '/y',
// value: undefined,
// message: 'Expected number'
// }, {
// schema: { type: 'number' },
// path: '/z',
// value: undefined,
// message: 'Expected number'
// }]Compiled routines can be inspected with the .Code() function.
const C = TypeCompiler.Compile(Type.String()) // const C: TypeCheck<TString>
console.log(C.Code()) // return function check(value) {
// return (
// (typeof value === 'string')
// )
// }Benchmarks
This project maintains benchmarks that measure TypeBox and AJV compile and validate performance. These benchmarks can be run locally by cloning this repository and running npm run benchmark. Results show for AJV version 8.11.0.
Validate
This benchmark measures overall validate performance. You can review this benchmark here.
┌──────────────────┬────────────┬────────────┬────────────┬────────────────────────┐
│ (index) │ Iterations │ Ajv │ TypeBox │ Measured │
├──────────────────┼────────────┼────────────┼────────────┼────────────────────────┤
│ Number │ 16000000 │ '76ms ' │ '65ms ' │ '1.17 x faster ' │
│ String │ 16000000 │ '272ms ' │ '151ms ' │ '1.80 x faster ' │
│ Boolean │ 16000000 │ '276ms ' │ '149ms ' │ '1.85 x faster ' │
│ Null │ 16000000 │ '272ms ' │ '151ms ' │ '1.80 x faster ' │
│ RegEx │ 16000000 │ '651ms ' │ '555ms ' │ '1.17 x faster ' │
│ ObjectA │ 16000000 │ '496ms ' │ '322ms ' │ '1.54 x faster ' │
│ ObjectB │ 16000000 │ '721ms ' │ '529ms ' │ '1.36 x faster ' │
│ Tuple │ 16000000 │ '332ms ' │ '192ms ' │ '1.73 x faster ' │
│ Union │ 16000000 │ '333ms ' │ '208ms ' │ '1.60 x faster ' │
│ Recursive │ 16000000 │ '5958ms ' │ '2366ms ' │ '2.52 x faster ' │
│ Vector4 │ 16000000 │ '335ms ' │ '171ms ' │ '1.96 x faster ' │
│ Matrix4 │ 16000000 │ '596ms ' │ '410ms ' │ '1.45 x faster ' │
│ Literal_String │ 16000000 │ '273ms ' │ '151ms ' │ '1.81 x faster ' │
│ Literal_Number │ 16000000 │ '261ms ' │ '150ms ' │ '1.74 x faster ' │
│ Literal_Boolean │ 16000000 │ '312ms ' │ '154ms ' │ '2.03 x faster ' │
│ Array_Number │ 16000000 │ '474ms ' │ '237ms ' │ '2.00 x faster ' │
│ Array_String │ 16000000 │ '457ms ' │ '297ms ' │ '1.54 x faster ' │
│ Array_Boolean │ 16000000 │ '512ms ' │ '354ms ' │ '1.45 x faster ' │
│ Array_ObjectA │ 16000000 │ '41610ms ' │ '26812ms ' │ '1.55 x faster ' │
│ Array_ObjectB │ 16000000 │ '46321ms ' │ '33115ms ' │ '1.40 x faster ' │
│ Array_Tuple │ 16000000 │ '1903ms ' │ '1149ms ' │ '1.66 x faster ' │
│ Array_Vector4 │ 16000000 │ '1506ms ' │ '808ms ' │ '1.86 x faster ' │
│ Array_Matrix4 │ 16000000 │ '6263ms ' │ '5072ms ' │ '1.23 x faster ' │
└──────────────────┴────────────┴────────────┴────────────┴────────────────────────┘Compile
This benchmark measures schema compilation time. You can review this benchmark here.
┌──────────────────┬────────────┬────────────┬────────────┬────────────────────────┐
│ (index) │ Iterations │ Ajv │ TypeBox │ Measured │
├──────────────────┼────────────┼────────────┼────────────┼────────────────────────┤
│ Number │ 2000 │ '386ms ' │ '7ms ' │ '55.14 x faster ' │
│ String │ 2000 │ '308ms ' │ '7ms ' │ '44.00 x faster ' │
│ Boolean │ 2000 │ '313ms ' │ '6ms ' │ '52.17 x faster ' │
│ Null │ 2000 │ '265ms ' │ '4ms ' │ '66.25 x faster ' │
│ RegEx │ 2000 │ '481ms ' │ '7ms ' │ '68.71 x faster ' │
│ ObjectA │ 2000 │ '2788ms ' │ '26ms ' │ '107.23 x faster ' │
│ ObjectB │ 2000 │ '2950ms ' │ '22ms ' │ '134.09 x faster ' │
│ Tuple │ 2000 │ '1255ms ' │ '17ms ' │ '73.82 x faster ' │
│ Union │ 2000 │ '1308ms ' │ '16ms ' │ '81.75 x faster ' │
│ Vector4 │ 2000 │ '1584ms ' │ '12ms ' │ '132.00 x faster ' │
│ Matrix4 │ 2000 │ '931ms ' │ '9ms ' │ '103.44 x faster ' │
│ Literal_String │ 2000 │ '347ms ' │ '7ms ' │ '49.57 x faster ' │
│ Literal_Number │ 2000 │ '380ms ' │ '7ms ' │ '54.29 x faster ' │
│ Literal_Boolean │ 2000 │ '374ms ' │ '4ms ' │ '93.50 x faster ' │
│ Array_Number │ 2000 │ '741ms ' │ '5ms ' │ '148.20 x faster ' │
│ Array_String │ 2000 │ '764ms ' │ '9ms ' │ '84.89 x faster ' │
│ Array_Boolean │ 2000 │ '788ms ' │ '8ms ' │ '98.50 x faster ' │
│ Array_ObjectA │ 2000 │ '3545ms ' │ '25ms ' │ '141.80 x faster ' │
│ Array_ObjectB │ 2000 │ '3685ms ' │ '27ms ' │ '136.48 x faster ' │
│ Array_Tuple │ 2000 │ '2242ms ' │ '13ms ' │ '172.46 x faster ' │
│ Array_Vector4 │ 2000 │ '1784ms ' │ '14ms ' │ '127.43 x faster ' │
│ Array_Matrix4 │ 2000 │ '1622ms ' │ '10ms ' │ '162.20 x faster ' │
└──────────────────┴────────────┴────────────┴────────────┴────────────────────────┘Contribute
TypeBox is open to community contribution. Please ensure you submit an open issue before submitting your pull request. The TypeBox project preferences open community discussion prior to accepting new features.