TypeBox

JSON Schema Type Builder with Static Type Resolution for TypeScript



[![npm version](https://badge.fury.io/js/%40sinclair%2Ftypebox.svg)](https://badge.fury.io/js/%40sinclair%2Ftypebox) [![Downloads](https://img.shields.io/npm/dm/%40sinclair%2Ftypebox.svg)](https://www.npmjs.com/package/%40sinclair%2Ftypebox) [![GitHub CI](https://github.com/sinclairzx81/typebox/workflows/GitHub%20CI/badge.svg)](https://github.com/sinclairzx81/typebox/actions)
## Install #### Node ```bash $ npm install @sinclair/typebox --save ``` #### Deno ```typescript import { Static, Type } from 'https://deno.land/x/typebox/src/typebox.ts' ``` ## Example ```typescript import { Static, Type } from '@sinclair/typebox' const T = Type.String() // const T = { type: 'string' } type T = Static // type T = string ``` ## Overview 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 enables one to create unified types that can be statically checked by TypeScript and runtime asserted using standard JSON Schema validation. TypeBox can be used as a simple tool to build up complex schemas or integrated into RPC or REST services to help validate data received over the wire. It offers a type system aligned to the capabilities of TypeScript and can be used equally well in JavaScript environments. License MIT ## Contents - [Install](#Install) - [Overview](#Overview) - [Usage](#Usage) - [Types](#Types) - [Modifiers](#Modifiers) - [Options](#Options) - [Extended Types](#Extended-Types) - [Reference Types](#Reference-Types) - [Recursive Types](#Recursive-Types) - [Generic Types](#Generic-Types) - [Unsafe Types](#Unsafe-Types) - [Conditional Types](#Conditional-Types) - [Values](#Values) - [Guards](#Guards) - [Strict](#Strict) - [Validation](#Validation) - [Compiler](#Compiler) - [Benchmark](#Benchmark) - [Contribute](#Contribute) ## Usage The following demonstrates TypeBox's general usage. ```typescript 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 // 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. ```typescript ┌────────────────────────────────┬─────────────────────────────┬────────────────────────────────┐ │ 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. ```typescript ┌────────────────────────────────┬─────────────────────────────┬────────────────────────────────┐ │ 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. ```typescript // 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. ```typescript ┌────────────────────────────────┬─────────────────────────────┬────────────────────────────────┐ │ TypeBox │ TypeScript │ Extended Schema │ │ │ │ │ ├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤ │ const T = Type.Constructor([ │ type T = new ( │ const T = { │ │ Type.String(), │ arg0: string, │ type: 'constructor' │ │ Type.Number() │ arg1: number │ parameters: [{ │ │ ], Type.Boolean()) │ ) => boolean │ type: 'string' │ │ │ │ }, { │ │ │ │ type: 'number' │ │ │ │ }], │ │ │ │ return: { │ │ │ │ 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' │ │ │ │ }], │ │ │ │ return: { │ │ │ │ type: 'boolean' │ │ │ │ } │ │ │ │ } │ │ │ │ │ ├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤ │ const T = Type.Uint8Array() │ type T = Uint8Array │ const T = { │ │ │ │ type: 'object', │ │ │ │ specialized: 'Uint8Array' │ │ │ │ } │ │ │ │ │ ├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤ │ const T = Type.Promise( │ type T = Promise │ 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`. ```typescript 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. ```typescript 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 // type Node = { // id: string // nodes: Node[] // } 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` type. ```typescript import { Type, Static, TSchema } from '@sinclair/typebox' const Nullable = (type: T) => Type.Union([type, Type.Null()]) const T = Nullable(Type.String()) // const T = { // anyOf: [{ // type: 'string' // }, { // type: 'null' // }] // } type T = Static // type T = string | null const U = Nullable(Type.Number()) // const U = { // anyOf: [{ // type: 'number' // }, { // type: 'null' // }] // } type U = Static // type U = number | null ``` ## Unsafe Types Use `Type.Unsafe(...)` to create custom schemas with user defined inference rules. ```typescript const T = Type.Unsafe({ type: 'number' }) // const T = { // type: 'number' // } type T = Static // type T = string ``` The `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. ```typescript import { Type, Static, TSchema } from '@sinclair/typebox' //-------------------------------------------------------------------------------------------- // // Nullable // //-------------------------------------------------------------------------------------------- function Nullable(schema: T) { return Type.Unsafe | null>({ ...schema, nullable: true }) } const T = Nullable(Type.String()) // const T = { // type: 'string', // nullable: true // } type T = Static // type T = string | null //-------------------------------------------------------------------------------------------- // // StringUnion<[...]> // //-------------------------------------------------------------------------------------------- function StringEnum(values: [...T]) { return Type.Unsafe({ enum: values }) } const T = StringEnum(['A', 'B', 'C']) // const T = { // enum: ['A', 'B', 'C'] // } type T = Static // type T = 'A' | 'B' | 'C' ``` ## Conditional Types Use `Conditional.Extends(...)` to create conditional mapped types. ```typescript import { Conditional } from '@sinclair/typebox/conditional' ``` The following table shows the TypeBox mappings between TypeScript and JSON schema. ```typescript ┌────────────────────────────────┬─────────────────────────────┬────────────────────────────────┐ │ TypeBox │ TypeScript │ JSON Schema │ │ │ │ │ ├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤ │ const T = Conditional.Extends( │ type T = │ const T = { │ │ Type.String(), │ string extends number │ const: false, │ │ Type.Number(), │ true : false │ type: 'boolean' │ │ Type.Literal(true), │ │ } │ │ Type.Literal(false) │ │ │ │ ) │ │ │ │ │ │ │ ├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤ │ const T = Conditional.Extract( │ type T = Extract< │ const T = { │ │ Type.Union([ │ 'a' | 'b' | 'c', │ anyOf: [{ │ │ Type.Literal('a'), │ 'a' | 'f' │ const: 'a' │ │ Type.Literal('b'), │ > │ type: 'string' │ │ Type.Literal('c') │ │ }] │ │ ]), │ │ } │ │ Type.Union([ │ │ │ │ Type.Literal('a'), │ │ │ │ Type.Literal('f') │ │ │ │ ]) │ │ │ │ ) │ │ │ │ │ │ │ ├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤ │ const T = Conditional.Exclude( │ type T = Exclude< │ const T = { │ │ Type.Union([ │ 'a' | 'b' | 'c', │ anyOf: [{ │ │ Type.Literal('a'), │ 'a' │ const: 'b', │ │ Type.Literal('b'), │ > │ type: 'string' │ │ Type.Literal('c') │ │ }, { │ │ ]), │ │ const: 'c', │ │ Type.Union([ │ │ type: 'string' │ │ Type.Literal('a') │ │ }] │ │ ]) │ │ } │ │ ) │ │ │ │ │ │ │ └────────────────────────────────┴─────────────────────────────┴────────────────────────────────┘ ``` ## Values Use `Value.Create(...)` to generate values from types. ```typescript 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. ```typescript 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. ```typescript 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. ```typescript 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](https://www.npmjs.com/package/ajv). The following example shows setting up Ajv to work with TypeBox. ```bash $ npm install ajv ajv-formats --save ``` ```typescript //-------------------------------------------------------------------------------------------- // // 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 = true ``` Please refer to the official Ajv [documentation](https://ajv.js.org/guide/getting-started.html) 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` please consider Ajv. The following demonstrates its use. ```typescript import { TypeCompiler } from '@sinclair/typebox/compiler' import { Type } from '@sinclair/typebox' const C = TypeCompiler.Compile(Type.Object({ // const C: TypeCheck> const R = C.Check({ x: 1, y: 2, z: 3 }) // const R = true ``` Validation errors can be read with the `Errors(...)` function. ```typescript const C = TypeCompiler.Compile(Type.Object({ // const C: TypeCheck> 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. ```typescript const C = TypeCompiler.Compile(Type.String()) // const C: TypeCheck console.log(C.Code()) // return function check(value) { // return ( // (typeof value === 'string') // ) // } ``` ## Benchmark This project maintains benchmarks that measure Ajv and TypeCompiler validate and compile performance. These benchmarks can be run locally by cloning this repository and running `npm run benchmark`. Results show against Ajv version 8.11.0. ### Validate This benchmark measures validation performance for varying types. You can review this benchmark [here](https://github.com/sinclairzx81/typebox/blob/master/benchmark/check.ts). ```typescript ┌──────────────────┬────────────┬──────────────┬──────────────┬──────────────┐ │ (index) │ Iterations │ Ajv │ TypeCompiler │ Performance │ ├──────────────────┼────────────┼──────────────┼──────────────┼──────────────┤ │ Number │ 16000000 │ ' 73 ms' │ ' 65 ms' │ ' 1.12 x' │ │ String │ 16000000 │ ' 281 ms' │ ' 161 ms' │ ' 1.75 x' │ │ Boolean │ 16000000 │ ' 302 ms' │ ' 151 ms' │ ' 2.00 x' │ │ Null │ 16000000 │ ' 281 ms' │ ' 149 ms' │ ' 1.89 x' │ │ RegEx │ 16000000 │ ' 689 ms' │ ' 550 ms' │ ' 1.25 x' │ │ ObjectA │ 16000000 │ ' 470 ms' │ ' 311 ms' │ ' 1.51 x' │ │ ObjectB │ 16000000 │ ' 667 ms' │ ' 556 ms' │ ' 1.20 x' │ │ Tuple │ 16000000 │ ' 362 ms' │ ' 190 ms' │ ' 1.91 x' │ │ Union │ 16000000 │ ' 387 ms' │ ' 209 ms' │ ' 1.85 x' │ │ Recursive │ 16000000 │ ' 6327 ms' │ ' 2773 ms' │ ' 2.28 x' │ │ Vector4 │ 16000000 │ ' 362 ms' │ ' 172 ms' │ ' 2.10 x' │ │ Matrix4 │ 16000000 │ ' 607 ms' │ ' 418 ms' │ ' 1.45 x' │ │ Literal_String │ 16000000 │ ' 314 ms' │ ' 151 ms' │ ' 2.08 x' │ │ Literal_Number │ 16000000 │ ' 281 ms' │ ' 147 ms' │ ' 1.91 x' │ │ Literal_Boolean │ 16000000 │ ' 289 ms' │ ' 148 ms' │ ' 1.95 x' │ │ Array_Number │ 16000000 │ ' 475 ms' │ ' 230 ms' │ ' 2.07 x' │ │ Array_String │ 16000000 │ ' 463 ms' │ ' 297 ms' │ ' 1.56 x' │ │ Array_Boolean │ 16000000 │ ' 521 ms' │ ' 348 ms' │ ' 1.50 x' │ │ Array_ObjectA │ 16000000 │ ' 43842 ms' │ ' 28375 ms' │ ' 1.55 x' │ │ Array_ObjectB │ 16000000 │ ' 45055 ms' │ ' 32882 ms' │ ' 1.37 x' │ │ Array_Tuple │ 16000000 │ ' 1424 ms' │ ' 1105 ms' │ ' 1.29 x' │ │ Array_Union │ 16000000 │ ' 3505 ms' │ ' 1350 ms' │ ' 2.60 x' │ │ Array_Recursive │ 16000000 │ ' 117087 ms' │ ' 42982 ms' │ ' 2.72 x' │ │ Array_Vector4 │ 16000000 │ ' 1500 ms' │ ' 817 ms' │ ' 1.84 x' │ │ Array_Matrix4 │ 16000000 │ ' 6126 ms' │ ' 4965 ms' │ ' 1.23 x' │ └──────────────────┴────────────┴──────────────┴──────────────┴──────────────┘ ``` ### Compile This benchmark measures compilation performance for varying types. You can review this benchmark [here](https://github.com/sinclairzx81/typebox/blob/master/benchmark/compile.ts). ```typescript ┌──────────────────┬────────────┬──────────────┬──────────────┬──────────────┐ │ (index) │ Iterations │ Ajv │ TypeCompiler │ Performance │ ├──────────────────┼────────────┼──────────────┼──────────────┼──────────────┤ │ Number │ 2000 │ ' 387 ms' │ ' 7 ms' │ ' 55.29 x' │ │ String │ 2000 │ ' 340 ms' │ ' 6 ms' │ ' 56.67 x' │ │ Boolean │ 2000 │ ' 314 ms' │ ' 5 ms' │ ' 62.80 x' │ │ Null │ 2000 │ ' 259 ms' │ ' 5 ms' │ ' 51.80 x' │ │ RegEx │ 2000 │ ' 491 ms' │ ' 7 ms' │ ' 70.14 x' │ │ ObjectA │ 2000 │ ' 2850 ms' │ ' 26 ms' │ ' 109.62 x' │ │ ObjectB │ 2000 │ ' 2989 ms' │ ' 22 ms' │ ' 135.86 x' │ │ Tuple │ 2000 │ ' 1283 ms' │ ' 17 ms' │ ' 75.47 x' │ │ Union │ 2000 │ ' 1292 ms' │ ' 16 ms' │ ' 80.75 x' │ │ Vector4 │ 2000 │ ' 1588 ms' │ ' 12 ms' │ ' 132.33 x' │ │ Matrix4 │ 2000 │ ' 934 ms' │ ' 7 ms' │ ' 133.43 x' │ │ Literal_String │ 2000 │ ' 340 ms' │ ' 5 ms' │ ' 68.00 x' │ │ Literal_Number │ 2000 │ ' 402 ms' │ ' 4 ms' │ ' 100.50 x' │ │ Literal_Boolean │ 2000 │ ' 381 ms' │ ' 6 ms' │ ' 63.50 x' │ │ Array_Number │ 2000 │ ' 750 ms' │ ' 8 ms' │ ' 93.75 x' │ │ Array_String │ 2000 │ ' 760 ms' │ ' 6 ms' │ ' 126.67 x' │ │ Array_Boolean │ 2000 │ ' 796 ms' │ ' 7 ms' │ ' 113.71 x' │ │ Array_ObjectA │ 2000 │ ' 3617 ms' │ ' 26 ms' │ ' 139.12 x' │ │ Array_ObjectB │ 2000 │ ' 3823 ms' │ ' 26 ms' │ ' 147.04 x' │ │ Array_Tuple │ 2000 │ ' 2263 ms' │ ' 13 ms' │ ' 174.08 x' │ │ Array_Union │ 2000 │ ' 1725 ms' │ ' 16 ms' │ ' 107.81 x' │ │ Array_Vector4 │ 2000 │ ' 2445 ms' │ ' 14 ms' │ ' 174.64 x' │ │ Array_Matrix4 │ 2000 │ ' 1638 ms' │ ' 11 ms' │ ' 148.91 x' │ └──────────────────┴────────────┴──────────────┴──────────────┴──────────────┘ ``` ## 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.