npm.devtool.tech
π You can access @sinclair/typebox package with using sinclairTypebox variable in browser devtools!
basic
popularity
size
quality
health
TypeBox
Json Schema Type Builder with Static Type Resolution for TypeScript
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
- Install
- Overview
- Usage
- Types
- Syntax
- Values
- TypeRegistry
- TypeCheck
- TypeSystem
- Error Function
- Workbench
- Codegen
- Ecosystem
- Benchmark
- Contribute
Usage
The following shows general usage.
import { Type, type Static } from '@sinclair/typebox'
//--------------------------------------------------------------------------------------------
//
// Let's say you have the following type ...
//
//--------------------------------------------------------------------------------------------
type T = {
id: string,
name: string,
timestamp: number
}
//--------------------------------------------------------------------------------------------
//
// ... you can express this type in the following way.
//
//--------------------------------------------------------------------------------------------
const T = Type.Object({ // const T = {
id: Type.String(), // type: 'object',
name: Type.String(), // properties: {
timestamp: Type.Integer() // id: {
}) // type: 'string'
// },
// name: {
// type: 'string'
// },
// timestamp: {
// type: 'integer'
// }
// },
// required: [
// 'id',
// 'name',
// 'timestamp'
// ]
// }
//--------------------------------------------------------------------------------------------
//
// ... then infer back to the original static type this way.
//
//--------------------------------------------------------------------------------------------
type T = Static<typeof T> // type T = {
// id: string,
// name: string,
// timestamp: number
// }
//--------------------------------------------------------------------------------------------
//
// ... or use the type to parse JavaScript values.
//
//--------------------------------------------------------------------------------------------
import { Value } from '@sinclair/typebox/value'
const R = Value.Parse(T, value) // const R: {
// id: string,
// name: string,
// timestamp: number
// }
Types
TypeBox types are Json Schema fragments that compose into more complex types. Each fragment is structured such that any Json Schema compliant validator can runtime assert a value the same way TypeScript will statically assert a type. TypeBox offers a set of Json Types which are used to create Json Schema compliant schematics as well as a JavaScript type set used to create schematics for constructs native to JavaScript.
Json Types
The following table lists the supported Json types. These types are fully compatible with the Json Schema Draft 7 specification.
ββββββββββββββββββββββββββββββββββ¬ββββββββββββββββββββββββββββββ¬βββββββββββββββββββββββββββββββββ
β TypeBox β TypeScript β Json Schema β
β β β β
ββββββββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββ€
β const T = Type.Any() β type T = any β const T = { } β
β β β β
ββββββββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββ€
β const T = Type.Unknown() β type T = unknown β const T = { } β
β β β β
ββββββββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββ€
β const T = Type.String() β type T = string β const T = { β
β β β type: 'string' β
β β β } β
β β β β
ββββββββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββ€
β const T = Type.Number() β type T = number β const T = { β
β β β type: 'number' β
β β β } β
β β β β
ββββββββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββ€
β const T = Type.Integer() β type T = number β const T = { β
β β β type: 'integer' β
β β β } β
β β β β
ββββββββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββ€
β const T = Type.Boolean() β type T = boolean β const T = { β
β β β type: 'boolean' β
β β β } β
β β β β
ββββββββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββ€
β const T = Type.Null() β type T = null β const T = { β
β β β type: 'null' β
β β β } β
β β β β
ββββββββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββ€
β const T = Type.Literal(42) β type T = 42 β const T = { β
β β β const: 42, β
β β β type: 'number' β
β β β } β
β β β β
ββββββββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββ€
β const T = Type.Array( β type T = number[] β const T = { β
β Type.Number() β β type: 'array', β
β ) β β items: { β
β β β type: 'number' β
β β β } β
β β β } β
β β β β
ββββββββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββ€
β const T = Type.Object({ β type T = { β const T = { β
β x: Type.Number(), β x: number, β type: 'object', β
β y: Type.Number() β y: number β required: ['x', 'y'], β
β }) β } β properties: { β
β β β x: { β
β β β type: 'number' β
β β β }, β
β β β y: { β
β β β type: 'number' β
β β β } β
β β β } β
β β β } β
β β β β
ββββββββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββ€
β const T = Type.Tuple([ β type T = [number, number] β const T = { β
β Type.Number(), β β type: 'array', β
β Type.Number() β β items: [{ β
β ]) β β type: 'number' β
β β β }, { β
β β β type: 'number' β
β β β }], β
β β β additionalItems: false, β
β β β minItems: 2, β
β β β maxItems: 2 β
β β β } β
β β β β
β β β β
ββββββββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββ€
β enum Foo { β enum Foo { β const T = { β
β A, β A, β anyOf: [{ β
β B β B β type: 'number', β
β } β } β const: 0 β
β β β }, { β
β const T = Type.Enum(Foo) β type T = Foo β type: 'number', β
β β β const: 1 β
β β β }] β
β β β } β
β β β β
ββββββββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββ€
β const T = Type.Const({ β type T = { β const T = { β
β x: 1, β readonly x: 1, β type: 'object', β
β y: 2, β readonly y: 2 β required: ['x', 'y'], β
β } as const) β } β properties: { β
β β β x: { β
β β β type: 'number', β
β β β const: 1 β
β β β }, β
β β β y: { β
β β β type: 'number', β
β β β const: 2 β
β β β } β
β β β } β
β β β } β
β β β β
ββββββββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββ€
β const T = Type.KeyOf( β type T = keyof { β const T = { β
β Type.Object({ β x: number, β anyOf: [{ β
β x: Type.Number(), β y: number β type: 'string', β
β y: Type.Number() β } β const: 'x' β
β }) β β }, { β
β ) β β type: 'string', β
β β β const: 'y' β
β β β }] β
β β β } β
β β β β
ββββββββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββ€
β const T = Type.Union([ β type T = string | number β const T = { β
β Type.String(), β β anyOf: [{ β
β Type.Number() β β type: 'string' β
β ]) β β }, { β
β β β type: 'number' β
β β β }] β
β β β } β
β β β β
ββββββββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββ€
β const T = Type.Intersect([ β type T = { β const T = { β
β Type.Object({ β x: number β allOf: [{ β
β x: Type.Number() β } & { β type: 'object', β
β }), β y: number β required: ['x'], β
β Type.Object({ β } β properties: { β
β y: Type.Number() β β x: { β
β }) β β type: 'number' β
β ]) β β } β
β β β } β
β β β }, { β
β β β type: 'object', |
β β β required: ['y'], β
β β β properties: { β
β β β y: { β
β β β type: 'number' β
β β β } β
β β β } β
β β β }] β
β β β } β
β β β β
ββββββββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββ€
β const T = Type.Composite([ β type T = { β const T = { β
β Type.Object({ β x: number, β type: 'object', β
β x: Type.Number() β y: number β required: ['x', 'y'], β
β }), β } β properties: { β
β Type.Object({ β β x: { β
β y: Type.Number() β β type: 'number' β
β }) β β }, β
β ]) β β y: { β
β β β type: 'number' β
β β β } β
β β β } β
β β β } β
β β β β
ββββββββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββ€
β const T = Type.Never() β type T = never β const T = { β
β β β not: {} β
β β β } β
β β β β
ββββββββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββ€
β const T = Type.Not( | type T = unknown β const T = { β
β Type.String() β β not: { β
β ) β β type: 'string' β
β β β } β
β β β } β
ββββββββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββ€
β const T = Type.Extends( β type T = β const T = { β
β Type.String(), β string extends number β const: false, β
β Type.Number(), β ? true β type: 'boolean' β
β Type.Literal(true), β : false β } β
β Type.Literal(false) β β β
β ) β β β
β β β β
ββββββββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββ€
β const T = Type.Extract( β type T = Extract< β const T = { β
β Type.Union([ β string | number, β type: 'string' β
β Type.String(), β string β } β
β Type.Number(), β > β β
β ]), β β β
β Type.String() β β β
β ) β β β
β β β β
ββββββββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββ€
β const T = Type.Exclude( β type T = Exclude< β const T = { β
β Type.Union([ β string | number, β type: 'number' β
β Type.String(), β string β } β
β Type.Number(), β > β β
β ]), β β β
β Type.String() β β β
β ) β β β
β β β β
ββββββββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββ€
β const T = Type.Mapped( β type T = { β const T = { β
β Type.Union([ β [_ in 'x' | 'y'] : number β type: 'object', β
β Type.Literal('x'), β } β required: ['x', 'y'], β
β Type.Literal('y') β β properties: { β
β ]), β β x: { β
β () => Type.Number() β β type: 'number' β
β ) β β }, β
β β β y: { β
β β β type: 'number' β
β β β } β
β β β } β
β β β } β
β β β β
ββββββββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββ€
β const U = Type.Union([ β type U = 'open' | 'close' β const T = { β
β Type.Literal('open'), β β type: 'string', β
β Type.Literal('close') β type T = `on${U}` β pattern: '^on(open|close)$' β
β ]) β β } β
β β β β
β const T = Type β β β
β .TemplateLiteral([ β β β
β Type.Literal('on'), β β β
β U β β β
β ]) β β β
β β β β
ββββββββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββ€
β const T = Type.Record( β type T = Record< β const T = { β
β Type.String(), β string, β type: 'object', β
β Type.Number() β number β patternProperties: { β
β ) β > β '^.*$': { β
β β β type: 'number' β
β β β } β
β β β } β
β β β } β
β β β β
ββββββββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββ€
β const T = Type.Partial( β type T = Partial<{ β const T = { β
β Type.Object({ β x: number, β type: 'object', β
β x: Type.Number(), β y: number β properties: { β
β y: Type.Number() | }> β x: { β
β }) β β type: 'number' β
β ) β β }, β
β β β y: { β
β β β type: 'number' β
β β β } β
β β β } β
β β β } β
β β β β
ββββββββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββ€
β const T = Type.Required( β type T = Required<{ β const T = { β
β Type.Object({ β x?: number, β type: 'object', β
β x: Type.Optional( β y?: number β required: ['x', 'y'], β
β Type.Number() | }> β properties: { β
β ), β β x: { β
β y: Type.Optional( β β type: 'number' β
β Type.Number() β β }, β
β ) β β y: { β
β }) β β type: 'number' β
β ) β β } β
β β β } β
β β β } β
β β β β
ββββββββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββ€
β const T = Type.Pick( β type T = Pick<{ β const T = { β
β Type.Object({ β x: number, β type: 'object', β
β x: Type.Number(), β y: number β required: ['x'], β
β y: Type.Number() β }, 'x'> β properties: { β
β }), ['x'] | β x: { β
β ) β β type: 'number' β
β β β } β
β β β } β
β β β } β
β β β β
ββββββββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββ€
β const T = Type.Omit( β type T = Omit<{ β const T = { β
β Type.Object({ β x: number, β type: 'object', β
β x: Type.Number(), β y: number β required: ['y'], β
β y: Type.Number() β }, 'x'> β properties: { β
β }), ['x'] | β y: { β
β ) β β type: 'number' β
β β β } β
β β β } β
β β β } β
β β β β
ββββββββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββ€
β const T = Type.Index( β type T = { β const T = { β
β Type.Object({ β x: number, β type: 'number' β
β x: Type.Number(), β y: string β } β
β y: Type.String() β }['x'] β β
β }), ['x'] β β β
β ) β β β
β β β β
ββββββββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββ€
β const A = Type.Tuple([ β type A = [0, 1] β const T = { β
β Type.Literal(0), β type B = [2, 3] β type: 'array', β
β Type.Literal(1) β type T = [ β items: [ β
β ]) β ...A, β { const: 0 }, β
β const B = Type.Tuple([ β ...B β { const: 1 }, β
| Type.Literal(2), β ] β { const: 2 }, β
| Type.Literal(3) β β { const: 3 } β
β ]) β β ], β
β const T = Type.Tuple([ β β additionalItems: false, β
| ...Type.Rest(A), β β minItems: 4, β
| ...Type.Rest(B) β β maxItems: 4 β
β ]) β β } β
β β β β
ββββββββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββ€
β const T = Type.Uncapitalize( β type T = Uncapitalize< β const T = { β
β Type.Literal('Hello') β 'Hello' β type: 'string', β
β ) β > β const: 'hello' β
β β β } β
β β β β
ββββββββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββ€
β const T = Type.Capitalize( β type T = Capitalize< β const T = { β
β Type.Literal('hello') β 'hello' β type: 'string', β
β ) β > β const: 'Hello' β
β β β } β
β β β β
ββββββββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββ€
β const T = Type.Uppercase( β type T = Uppercase< β const T = { β
β Type.Literal('hello') β 'hello' β type: 'string', β
β ) β > β const: 'HELLO' β
β β β } β
β β β β
ββββββββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββ€
β const T = Type.Lowercase( β type T = Lowercase< β const T = { β
β Type.Literal('HELLO') β 'HELLO' β type: 'string', β
β ) β > β const: 'hello' β
β β β } β
β β β β
ββββββββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββ€
β const R = Type.Ref('T') β type R = unknown β const R = { $ref: 'T' } β
β β β β
ββββββββββββββββββββββββββββββββββ΄ββββββββββββββββββββββββββββββ΄βββββββββββββββββββββββββββββββββ
JavaScript Types
TypeBox provides an extended type set that can be used to create schematics for common JavaScript constructs. These types can not be used with any standard Json Schema validator; but can be used to frame schematics for interfaces that may receive Json validated data. JavaScript types are prefixed with the [JavaScript] jsdoc comment for convenience. The following table lists the supported types.
ββββββββββββββββββββββββββββββββββ¬ββββββββββββββββββββββββββββββ¬βββββββββββββββββββββββββββββββββ
β TypeBox β TypeScript β Extended Schema β
β β β β
ββββββββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββ€
β const T = Type.Constructor([ β type T = new ( β const T = { β
β Type.String(), β arg0: string, β type: 'Constructor', β
β Type.Number() β arg0: number β parameters: [{ β
β ], Type.Boolean()) β ) => boolean β type: 'string' β
β β β }, { β
β β β type: 'number' β
β β β }], β
β β β returns: { β
β β β type: 'boolean' β
β β β } β
β β β } β
β β β β
ββββββββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββ€
β const T = Type.Function([ β type T = ( β const T = { β
| Type.String(), β arg0: string, β type: 'Function', β
β Type.Number() β arg1: number β parameters: [{ β
β ], Type.Boolean()) β ) => boolean β type: 'string' β
β β β }, { β
β β β type: 'number' β
β β β }], β
β β β returns: { β
β β β type: 'boolean' β
β β β } β
β β β } β
β β β β
ββββββββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββ€
β const T = Type.Promise( β type T = Promise<string> β const T = { β
β Type.String() β β type: 'Promise', β
β ) β β item: { β
β β β type: 'string' β
β β β } β
β β β } β
β β β β
ββββββββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββ€
β const T = β type T = β const T = { β
β Type.AsyncIterator( β AsyncIterableIterator< β type: 'AsyncIterator', β
β Type.String() β string β items: { β
β ) β > β type: 'string' β
β β β } β
β β β } β
β β β β
ββββββββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββ€
β const T = Type.Iterator( β type T = β const T = { β
β Type.String() β IterableIterator<string> β type: 'Iterator', β
β ) β β items: { β
β β β type: 'string' β
β β β } β
β β β } β
β β β β
ββββββββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββ€
β const T = Type.RegExp(/abc/i) β type T = string β const T = { β
β β β type: 'RegExp' β
β β β source: 'abc' β
β β β flags: 'i' β
β β β } β
β β β β
ββββββββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββ€
β const T = Type.Uint8Array() β type T = Uint8Array β const T = { β
β β β type: 'Uint8Array' β
β β β } β
β β β β
ββββββββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββ€
β const T = Type.Date() β type T = Date β const T = { β
β β β type: 'Date' β
β β β } β
β β β β
ββββββββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββ€
β const T = Type.Undefined() β type T = undefined β const T = { β
β β β type: 'undefined' β
β β β } β
β β β β
ββββββββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββ€
β const T = Type.Symbol() β type T = symbol β const T = { β
β β β type: 'symbol' β
β β β } β
β β β β
ββββββββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββ€
β const T = Type.BigInt() β type T = bigint β const T = { β
β β β type: 'bigint' β
β β β } β
β β β β
ββββββββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββ€
β const T = Type.Void() β type T = void β const T = { β
β β β type: 'void' β
β β β } β
β β β β
ββββββββββββββββββββββββββββββββββ΄ββββββββββββββββββββββββββββββ΄βββββββββββββββββββββββββββββββββ
Import
Import the Type namespace to bring in the full TypeBox type system. This is recommended for most users.
import { Type, type Static } from '@sinclair/typebox'
You can also selectively import types. This enables modern bundlers to tree shake for unused types.
import { Object, Number, String, Boolean, type Static } from '@sinclair/typebox'
Options
You can pass Json Schema options on the last argument of any given type. Option hints specific to each type are provided for convenience.
// String must be an email
const T = Type.String({ // const T = {
format: 'email' // type: 'string',
}) // format: 'email'
// }
// Number must be a multiple of 2
const T = Type.Number({ // const T = {
multipleOf: 2 // type: 'number',
}) // multipleOf: 2
// }
// Array must have at least 5 integer values
const T = Type.Array(Type.Integer(), { // const T = {
minItems: 5 // type: 'array',
}) // minItems: 5,
// items: {
// type: 'integer'
// }
// }
Properties
Object properties can be modified with Readonly and Optional. The following table shows how these modifiers map between TypeScript and Json Schema.
ββββββββββββββββββββββββββββββββββ¬ββββββββββββββββββββββββββββββ¬βββββββββββββββββββββββββββββββββ
β TypeBox β TypeScript β Json Schema β
β β β β
ββββββββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββ€
β const T = Type.Object({ β type T = { β const T = { β
β name: Type.ReadonlyOptional( β readonly name?: string β type: 'object', β
β Type.String() β } β properties: { β
β ) β β name: { β
β }) β β type: 'string' β
β β β } β
β β β } β
β β β } β
β β β β
ββββββββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββ€
β const T = Type.Object({ β type T = { β const T = { β
β name: Type.Readonly( β readonly name: string β type: 'object', β
β Type.String() β } β properties: { β
β ) β β name: { β
β }) β β type: 'string' β
β β β } β
β β β }, β
β β β required: ['name'] β
β β β } β
β β β β
ββββββββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββ€
β const T = Type.Object({ β type T = { β const T = { β
β name: Type.Optional( β name?: string β type: 'object', β
β Type.String() β } β properties: { β
β ) β β name: { β
β }) β β type: 'string' β
β β β } β
β β β } β
β β β } β
β β β β
ββββββββββββββββββββββββββββββββββ΄ββββββββββββββββββββββββββββββ΄βββββββββββββββββββββββββββββββββ
Generic Types
Generic types can be created with functions. TypeBox types extend the TSchema interface so you should constrain parameters to this type. The following creates a generic Vector type.
import { Type, type Static, type TSchema } from '@sinclair/typebox'
const Vector = <T extends TSchema>(T: T) =>
Type.Object({ // type Vector<T> = {
x: T, // x: T,
y: T, // y: T,
z: T // z: T
}) // }
const NumberVector = Vector(Type.Number()) // type NumberVector = Vector<number>
Generic types are often used to create aliases for complex types. The following creates a Nullable generic type.
const Nullable = <T extends TSchema>(schema: T) => Type.Union([schema, Type.Null()])
const T = Nullable(Type.String()) // const T = {
// anyOf: [
// { type: 'string' },
// { type: 'null' }
// ]
// }
type T = Static<typeof T> // type T = string | null
Recursive Types
Use the Recursive function to create a singular recursive type.
const Node = Type.Recursive(Self => Type.Object({ // const Node = {
id: Type.String(), // $id: 'Node',
nodes: Type.Array(Self) // 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 ac