0.31.12 • Published 9 months ago
@n1k1t/typebox v0.31.12
Install
Npm
$ npm install @sinclair/typebox --saveEsm + Deno
import { Type, Static } from 'https://esm.sh/@sinclair/typebox'Example
import { 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 Json Schema objects that infer as TypeScript types. The schemas 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 or runtime checked using standard Json Schema validation.
TypeBox is designed to be a runtime type system based on industry standard specifications. It offers serializable and publishable types as standard, a fully extensible type system capable of supporting multiple schema specifications, a high performance runtime validation compiler, various tools for working with dynamic data and offers detailed structured error reporting. It can either be used as a simple tool to build up complex schemas or integrated into applications to enable high performance runtime validation for data received over the wire.
License MIT
Contents
- Install
- Overview
- Usage
- Types
- Values
- TypeRegistry
- TypeCheck
- TypeSystem
- Workbench
- Codegen
- Ecosystem
- Benchmark
- Contribute
Usage
The following shows general usage.
import { 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
// }
//--------------------------------------------------------------------------------------------
//
// ... then use the type both as Json Schema and as a TypeScript type.
//
//--------------------------------------------------------------------------------------------
import { Value } from '@sinclair/typebox/value'
function receive(value: T) { // ... as a Static Type
if(Value.Check(T, value)) { // ... as a Json Schema
// ok...
}
}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.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 : false │ type: 'boolean' │
│ Type.Literal(true), │ │ } │
│ 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 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 = [...A, ...B] │ items: [ │
│ ]) │ │ { const: 0 }, │
│ const B = Type.Tuple([ │ │ { 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 T = Type.Object({ │ type T = { │ const R = { │
│ x: Type.Number(), │ x: number, │ $ref: 'T' │
│ y: Type.Number() │ y: number │ } │
│ }, { $id: 'T' }) | } │ │
│ │ │ │
│ const R = Type.Ref(T) │ type R = 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' │
│ │ │ }], │
│ │ │ 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.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/) │ type T = string │ const T = { │
│ │ │ type: 'string' │
│ │ │ pattern: 'abc' │
│ │ │ } │
│ │ │ │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Uint8Array() │ type T = Uint8Array │ const T = { │
│ │ │ type: 'Uint8Array' │
│ │ │ } │
│ │ │ │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Date() │ type T = Date │ const T = { │
│ │ │ type: 'Date' │
│ │ │ } │
│ │ │ │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Undefined() │ type T = undefined │ const T = { │
│ │ │ type: 'undefined' │
│ │ │ } │
│ │ │ │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Symbol() │ type T = symbol │ const T = { │
│ │ │ type: 'symbol' │
│ │ │ } │
│ │ │ │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.BigInt() │ type T = bigint │ const T = { │
│ │ │ type: 'bigint' │
│ │ │ } │
│ │ │ │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Void() │ type T = void │ const T = { │
│ │ │ type: 'void' │
│ │ │ } │
│ │ │ │
└────────────────────────────────┴─────────────────────────────┴────────────────────────────────┘Options
You can pass Json Schema options on the last argument of any type. Option hints specific to each type are provided for convenience.
// String must be an email
const T = Type.String({ // const T = {
format: 'email' // type: 'string',
}) // format: 'email'
// }
// Number must be a multiple of 2
const T = Type.Number({ // const T = {
multipleOf: 2 // type: 'number',
}) // multipleOf: 2
// }
// Array must have at least 5 integer values
const T = Type.Array(Type.Integer(), { // const T = {
minItems: 5 // type: 'array',
}) // minItems: 5,
// items: {
// type: 'integer'
// }
// }Properties
Object properties can be modified with Readonly and Optional. The following table shows how these modifiers map between TypeScript and Json Schema.
┌────────────────────────────────┬─────────────────────────────┬────────────────────────────────┐
│ TypeBox │ TypeScript │ Json Schema │
│ │ │ │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Object({ │ type T = { │ const T = { │
│ name: Type.ReadonlyOptional( │ readonly name?: string │ type: 'object', │
│ Type.String() │ } │ properties: { │
│ ) │ │ name: { │
│ }) │ │ type: 'string' │
│ │ │ } │
│ │ │ } │
│ │ │ } │
│ │ │ │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Object({ │ type T = { │ const T = { │
│ name: Type.Readonly( │ readonly name: string │ type: 'object', │
│ Type.String() │ } │ properties: { │
│ ) │ │ name: { │
│ }) │ │ type: 'string' │
│ │ │ } │
│ │ │ }, │
│ │ │ required: ['name'] │
│ │ │ } │
│ │ │ │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Object({ │ type T = { │ const T = { │
│ name: Type.Optional( │ name?: string │ type: 'object', │
│ Type.String() │ } │ properties: { │
│ ) │ │ name: { │
│ }) │ │ type: 'string' │
│ │ │ } │
│ │ │ } │
│ │ │ } │
│ │ │ │
└────────────────────────────────┴─────────────────────────────┴────────────────────────────────┘Generic Types
Generic types can be created with generic functions. All types extend the base type TSchema. It is common to constrain generic function arguments to this type. The following creates a generic Vector type.
import { Type, Static, TSchema } from '@sinclair/typebox'
const Vector = <T extends TSchema>(t: T) => Type.Object({ x: t, y: t, z: t })
const NumberVector = Vector(Type.Number()) // const NumberVector = {
// type: 'object',
// required: ['x', 'y', 'z'],
// properties: {
// x: { type: 'number' },
// y: { type: 'number' },
// z: { type: 'number' }
// }
// }
type NumberVector = Static<typeof NumberVector> // type NumberVector = {
// x: number,
// y: number,
// z: number
// }Generic types are often used to create aliases for more 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 | nullReference Types
Reference types are supported with Ref.
const T = Type.String({ $id: 'T' }) // const T = {
// $id: 'T',
// type: 'string'
// }
const R = Type.Ref<typeof T>('T') // const R = {
// $ref: 'T'
// }
type R = Static<typeof R> // type R = stringRecursive Types
TypeBox supports singular recursive data structures. Recursive type inference is also supported. The following creates a recursive Node data structure.
const Node = Type.Recursive(This => Type.Object({ // const Node = {
id: Type.String(), // $id: 'Node',
nodes: Type.Array(This) // type: 'object',
}), { $id: 'Node' }) // properties: {
// id: {
// type: 'string'
// },
// nodes: {
// type: 'array',
// items: {
// $ref: 'Node'
// }
// }
// },
// required: [
// 'id',
// 'nodes'
// ]
// }
type Node = Static<typeof Node> // type Node = {
// id: string
// nodes: Node[]
// }
function test(node: Node) {
const id = node.nodes[0].nodes[0].id // id is string
}Conditional Types
TypeBox supports runtime conditional types with Extends. This type will perform a structural assignability check for the first two arguments and returns one of the second two arguments based on the result. The Extends type is modelled after TypeScript conditional types. The Exclude and Extract conditional types are also supported.
// TypeScript
type T0 = string extends number ? true : false // type T0 = false
type T1 = Extract<(1 | 2 | 3), 1> // type T1 = 1
type T2 = Exclude<(1 | 2 | 3), 1> // type T2 = 2 | 3
// TypeBox
const T0 = Type.Extends( // const T0: TLiteral<false> = {
Type.String(), // type: 'boolean',
Type.Number(), // const: false
Type.Literal(true), // }
Type.Literal(false)
)
const T1 = Type.Extract( // const T1: TLiteral<1> = {
Type.Union([ // type: 'number',
Type.Literal(1), // const: 1
Type.Literal(2), // }
Type.Literal(3)
]),
Type.Literal(1)
)
const T2 = Type.Exclude( // const T2: TUnion<[
Type.Union([ // TLiteral<2>,
Type.Literal(1), // TLiteral<3>
Type.Literal(2), // ]> = {
Type.Literal(3) // anyOf: [{
]), // type: 'number',
Type.Literal(1) // const: 2
) // }, {
// type: 'number',
// const: 3
// }]
// }Template Literal Types
TypeBox supports template literal types with TemplateLiteral. This type can be created using a string syntax that is similar to the TypeScript template literal syntax. This type can also be constructed by passing an array of Union and Literal types in sequence. The following example shows the string syntax.
// TypeScript
type T = `option${'A'|'B'|'C'}` // type T = 'optionA' | 'optionB' | 'optionC'
type R = Record<T, string> // type R = {
// optionA: string
// optionB: string
// optionC: string
// }
// TypeBox
const T = Type.TemplateLiteral('option${A|B|C}') // const T = {
// pattern: '^option(A|B|C)$',
// type: 'string'
// }
const R = Type.Record(T, Type.String()) // const R = {
// type: 'object',
// required: ['optionA', 'optionB'],
// properties: {
// optionA: {
// type: 'string'
// },
// optionB: {
// type: 'string'
// }
// optionC: {
// type: 'string'
// }
// }
// }Indexed Access Types
TypeBox supports Indexed Access Types with Index. This type enables uniform access to interior property and array element types without having to extract them from the underlying schema representation. This type is supported for Object, Array, Tuple, Union and Intersect types.
const T = Type.Object({ // const T = {
x: Type.Number(), // type: 'object',
y: Type.String(), // required: ['x', 'y', 'z'],
z: Type.Boolean() // properties: {
}) // x: { type: 'number' },
// y: { type: 'string' },
// z: { type: 'string' }
// }
// }
const A = Type.Index(T, ['x']) // const A = { type: 'number' }
const B = Type.Index(T, ['x', 'y']) // const B = {
// anyOf: [
// { type: 'number' },
// { type: 'string' }
// ]
// }
const C = Type.Index(T, Type.KeyOf(T)) // const C = {
// anyOf: [
// { type: 'number' },
// { type: 'string' },
// { type: 'boolean' }
// ]
// }Rest Types
TypeBox provides the Rest type to uniformly extract variadic tuples from Intersect, Union and Tuple types. This type can be useful to remap variadic types into different forms. The following uses Rest to remap a Tuple into a Union.
const T = Type.Tuple([ // const T = {
Type.String(), // type: 'array',
Type.Number() // items: [
]) // { type: 'string' },
// { type: 'number' }
// ],
// additionalItems: false,
// minItems: 2,
// maxItems: 2,
// }
const R = Type.Rest(T) // const R = [
// { type: 'string' },
// { type: 'number' }
// ]
const U = Type.Union(R) // const U = {
// anyOf: [
// { type: 'string' },
// { type: 'number' }
// ]
// }