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
Module Types
TypeBox Modules are containers for related types. They provide a referential namespace, enabling types to reference one another via string identifiers. Modules support both singular and mutually recursive referencing within the context of a module, as well as referential computed types (such as Partial + Ref). All Module types must be imported before use. TypeBox represents an imported type with the $defs Json Schema keyword.
Usage
The following creates a Module with User and PartialUser types. Note that the PartialUser type is specified as a Partial + Ref to the User type. It is not possible to perform a Partial operation directly on a reference, so TypeBox will return a TComputed type that defers the Partial operation until all types are resolved. The TComputed type is evaluated when calling Import on the Module.
// Module with PartialUser and User types
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
}), // }>
})
// Types must be imported before use.
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]>,