sinclairzx81TypeBox
Json Schema Type Builder with Static Type Resolution for TypeScript
Install
$ npm install typeboxUsage
A TypeScript engine for Json Schema Reference
import Type from 'typebox'
// Json Schema
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 = Type.Static<typeof T> // type T = {
// x: number,
// y: number,
// z: number
// }
// TypeScript
const { S } = Type.Script({ T }, `
type RenameKey<K> =
K extends 'x' ? 'a' :
K extends 'y' ? 'b' :
K extends 'z' ? 'c' :
K
type S = {
readonly [K in keyof T as RenameKey<K>]: string
}
`)
type S = Type.Static<typeof S> // type S = {
// readonly a: string,
// readonly b: string,
// readonly c: string
// }Overview
TypeBox is a runtime type system 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 system that can be statically checked by TypeScript and validated at runtime using standard Json Schema.
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
Upgrade
If upgrading from @sinclair/typebox refer to the 1.0 migration guide at the following URL.
Type
TypeBox provides many functions to create Json Schema types. Each function returns a small Json Schema fragment that can be composed into more complex types. TypeBox includes a set of functions that are used to construct Json Schema compliant schematics as well as a set of extended functions that return schematics for constructs native to JavaScript.
Example
The following creates a Json Schema type and infers with Static.
import Type from '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 = Type.Static<typeof T> // type T = {
// x: number,
// y: number,
// z: number
// }Schema options can be passed on the last argument of any given type.
const T = Type.String({ // const T = {
format: 'email' // type: 'string',
}) // format: 'email'
// }
const S = Type.Number({ // const S = {
minimum: 0, // type: 'number',
maximum: 100 // minimum: 0,
}) // maximum: 100
// }Value
The Value submodule provides functions for validation and other typed operations on JavaScript values. It includes functions such as Check, Parse, Clone, Encode, and Decode, as well as advanced functions for performing structural Diff and Patch operations on dynamic JavaScript values.
import Value from 'typebox/value'Example
The following uses the Value module to Parse a value.
const T = Type.Object({
x: Type.Number(),
y: Type.Number(),
z: Type.Number()
})
const A = Value.Parse(T, { // const A: {
x: 1, // x: number,
y: 0, // y: number,
z: 0 // z: number
}) // } = ...Compile
The Compile submodule is a high-performance Json Schema compliant JIT compiler that compiles schematics into efficient runtime validators. The compiler is optimized for fast compilation and validation and is known to be one of the fastest validation solutions available for JavaScript.
import { Compile } from 'typebox/compile'Example
The following uses the compiler to Compile and Parse a value.
const C = Compile(Type.Object({ // const C: Validator<{}, TObject<{
x: Type.Number(), // x: TNumber,
y: Type.Number(), // y: TNumber,
z: Type.Number() // z: TNumber
})) // }>>
const A = C.Parse({ // const A: {
x: 0, // x: number,
y: 1, // y: number,
z: 0 // z: number
}) // } = ...Script
Documentation | Example 1 | Example 2
TypeBox is a runtime TypeScript DSL engine that can create, transform, and compute Json Schema using native TypeScript syntax. The engine is implemented symmetrically at runtime and within the TypeScript type system, and is intended for use with the TypeScript 7 native compiler and above.
// Scripted Type
const T = Type.Script(`{
x: number,
y: string,
z: boolean
}`) // const T: TObject<{
// x: TNumber,
// y: TString,
// z: TBoolean
// }>
// Json Schema Introspection
T.type // 'object'
T.required // ['x', 'y', 'z']
T.properties // { x: ..., y: ..., z: ... }
// Scripted Type (Computed)
const S = Type.Script({ T }, `{
[K in keyof T]: T[K] | null
}`) // const S: TObject<{
// x: TUnion<[TNumber, TNull]>,
// y: TUnion<[TString, TNull]>,
// z: TUnion<[TBoolean, TNull]>
// }>
// Standard Inference
type S = Type.Static<typeof S> // type S = {
// x: number | null,
// y: string | null,
// z: boolean | null
// }Schema
Documentation | Example 1 | Example 2
TypeBox is built upon a high-performance validation infrastructure that supports the direct compilation and inference of Json Schema schematics. TypeBox implements Draft 3 to 2020-12 and is compliance tested via the official Json Schema Test Suite. It offers high-performance JIT compilation with automatic fallback to dynamic checking in JIT restricted environments.
Example
The following compiles Json Schema. Type inference is supported.
const C = Compile({
type: 'object',
required: ['x', 'y', 'z'],
properties: {
x: { type: 'number' },
y: { type: 'number' },
z: { type: 'number' }
}
})
const A = C.Parse({ // const A: {
x: 0, // x: number,
y: 0, // y: number,
z: 1 // z: number
}) // } = ...Contribute
TypeBox is open to community contribution. Please ensure you submit an issue before submitting a pull request. The TypeBox project prefers open community discussion before accepting new features.