![Introducing Enhanced Alert Actions and Triage Functionality](https://cdn.sanity.io/images/cgdhsj6q/production/fe71306d515f85de6139b46745ea7180362324f0-2530x946.png?w=800&fit=max&auto=format)
Product
Introducing Enhanced Alert Actions and Triage Functionality
Socket now supports four distinct alert actions instead of the previous two, and alert triaging allows users to override the actions taken for all individual alerts.
@sinclair/typebox
Advanced tools
Package description
The @sinclair/typebox package is a TypeScript utility designed to create type-safe schemas with a consistent syntax. It is primarily used for defining data structures with TypeScript types and validating data at runtime using a separate validation library like Ajv.
Type Creation
Allows the creation of TypeScript types for various data structures such as strings, numbers, objects, arrays, etc. The created types can be used for compile-time type checking and runtime validation.
{"const T = Type.String()"}
Type Composition
Enables the composition of complex types by combining simpler types. This is useful for defining the shape of objects, with optional and required fields.
{"const UserType = Type.Object({ name: Type.String(), age: Type.Optional(Type.Number()) })"}
Type Validation
Provides a way to validate data at runtime against the defined types using a validation library like Ajv. This ensures that the data conforms to the specified schema.
{"const T = Type.String(); const validate = ajv.compile(T); const isValid = validate('hello');"}
Joi is a powerful schema description language and data validator for JavaScript. It allows for detailed descriptions of data structures with a wide range of validation options. Compared to @sinclair/typebox, Joi has a more extensive API and built-in validation without the need for an external library.
Yup is a JavaScript schema builder for value parsing and validation. It defines a schema with an expressive API and handles both validation and error messages. Unlike @sinclair/typebox, Yup includes its own validation methods and does not rely on TypeScript for type definitions.
Zod is a TypeScript-first schema declaration and validation library. It offers a similar experience to @sinclair/typebox by leveraging TypeScript for type safety while also providing runtime validation. Zod's API is designed to be more concise and it includes its own validation logic.
Readme
$ npm install @sinclair/typebox --save
TypeBox is a type builder library that allows developers to compose complex in-memory JSONSchema objects that can be resolved to static TypeScript types. The schemas produced by TypeBox can be used directly as validation schemas or reflected upon by navigating the standard JSONSchema properties at runtime. TypeBox can be used as a simple tool to build complex schemas or integrated into RPC or REST services to help validate JSON data received over the wire.
TypeBox does not provide any mechanism for validating JSONSchema. Please refer to libraries such as AJV or similar to validate the schemas created with this library.
Requires TypeScript 3.8.3 and above.
License MIT
The following shows the general usage.
import { Type, Static } from '@sinclair/typebox'
// Some type...
type Order = {
email: string,
address: string,
quantity: number,
option: 'pizza' | 'salad' | 'pie'
}
// ...can be expressed as...
const Order = Type.Object({
email: Type.Format('email'),
address: Type.String(),
quantity: Type.Number({ minimum: 1, maximum: 99 }),
option: Type.Union(
Type.Literal('pizza'),
Type.Literal('salad'),
Type.Literal('pie')
)
})
// ... which can be reflected
console.log(JSON.stringify(Order, null, 2))
// ... and statically resolved
type TOrder = Static<typeof Order>
// .. and validated as JSONSchema
JSON.validate(Order, { // IETF | TC39 ?
email: 'dave@domain.com',
address: '...',
quantity: 99,
option: 'pie'
})
// ... and so on ...
TypeBox provides many functions generate JSONschema data types. The following tables list the functions TypeBox provides and their respective TypeScript and JSONSchema equivalents.
Type | TypeBox | TypeScript |
---|---|---|
Literal | const T = Type.Literal(123) | type T = 123 |
String | const T = Type.String() | type T = string |
Number | const T = Type.Number() | type T = number |
Integer | const T = Type.Integer() | type T = number |
Boolean | const T = Type.Boolean() | type T = boolean |
Object | const T = Type.Object({ name: Type.String() }) | type T = { name: string } |
Array | const T = Type.Array(Type.Number()) | type T = number[] |
Map | const T = Type.Map(Type.Number()) | type T = { [key: string] } : number |
Intersect | const T = Type.Intersect(Type.String(), Type.Number()) | type T = string & number |
Union | const T = Type.Union(Type.String(), Type.Number()) | type T = string | number |
Tuple | const T = Type.Tuple(Type.String(), Type.Number()) | type T = [string, number] |
Any | const T = Type.Any() | type T = any |
Null | const T = Type.Null() | type T = null |
Pattern | const T = Type.Pattern(/foo/) | type T = string |
Format | const T = Type.Format('date-time') | type T = string |
Guid | const T = Type.Guid() | type T = string |
Type | TypeBox | JSONSchema |
---|---|---|
Literal | const T = Type.Literal(123) | { type: 'number', enum: [123] } |
String | const T = Type.String() | { type: 'string' } |
Number | const T = Type.Number() | { type: 'number' } |
Integer | const T = Type.Number() | { type: 'integer' } |
Boolean | const T = Type.Boolean() | { type: 'boolean' } |
Object | const T = Type.Object({ name: Type: String() }) | { type: 'object': properties: { name: { type: 'string' } }, required: ['name'] } |
Array | const T = Type.Array(Type.String()) | { type: 'array': items: { type: 'string' } } |
Map | const T = Type.Map(Type.Number()) | { type: 'object', additionalProperties: { type: 'number' } } |
Intersect | const T = Type.Intersect(Type.Number(), Type.String()) | { allOf: [{ type: 'number'}, {type: 'string'}] } |
Union | const T = Type.Union(Type.Number(), Type.String()) | { oneOf: [{ type: 'number'}, {type: 'string'}] } |
Tuple | const T = Type.Tuple(Type.Number(), Type.String()) | { type: "array", items: [{type: 'string'}, {type: 'number'}], additionalItems: false, minItems: 2, maxItems: 2 } |
Any | const T = Type.Any() | { } |
Null | const T = Type.Null() | { type: 'null' } |
Pattern | const T = Type.Pattern(/foo/) | { type: 'string', pattern: 'foo' } |
Format | const T = Type.Format('date-time') | { type: 'string',format: 'date-time' } |
Guid | const T = Type.Guid() | { type: 'string', format: '' } |
The following are object property modifiers. Note that Type.Optional(...)
will make the schema object property optional. Type.Readonly(...)
however has no effect on the underlying schema as is only meaningful to TypeScript.
Type | TypeBox | TypeScript |
---|---|---|
ReadonlyOptional | const T = Type.Object({ email: Type.ReadonlyOptional(Type.String()) }) | type T = { readonly email?: string } |
Readonly | const T = Type.Object({ email: Type.Readonly(Type.String()) }) | type T = { readonly email: string } |
Optional | const T = Type.Object({ email: Type.Optional(Type.String()) }) | type T = { email?: string } |
TypeBox allows function signatures to be composed in a similar way to other types. It uses a custom schema represenation to achieve this. Note, this format is not JSONSchema, rather it uses JSONSchema to encode function arguments
and return
types. It also provides additional types; Type.Constructor()
, Type.Void()
, Type.Undefined()
, and Type.Promise()
.
For more information on their using functions, see the Functions and Generics sections below.
The following is an example of how TypeBox encodes function signatures.
type T = (a: string, b: number) => boolean
{
"type": "function",
"returns": { "type": "boolean" },
"arguments": [
{"type": "string" },
{"type": "number" },
]
}
Intrinsic | TypeBox | TypeScript |
---|---|---|
Function | const T = Type.Function([Type.String()], Type.String()) | type T = (arg0: string) => string |
Constructor | const T = Type.Constructor([Type.String()], Type.String()) | type T = new (arg0: string) => string |
Promise | const T = Type.Promise(Type.String()) | type T = Promise<string> |
Undefined | const T = Type.Undefined() | type T = undefined |
Void | const T = Type.Void() | type T = void |
Intrinsic | TypeBox | JSON Function |
---|---|---|
Function | const T = Type.Function([Type.String()], Type.Number()) | { type: 'function', arguments: [ { type: 'string' } ], returns: { type: 'number' } } |
Constructor | const T = Type.Constructor([Type.String()], Type.Number()) | { type: 'constructor', arguments: [ { type: 'string' } ], returns: { type: 'number' } } |
Promise | const T = Type.Promise(Type.String()) | { type: 'promise', item: { type: 'string' } } |
Undefined | const T = Type.Undefined() | { type: 'undefined' } |
Void | const T = Type.Void() | { type: 'void' } |
The following demonstrates creating function signatures for the following TypeScript types.
type T0 = (a0: number, a1: string) => boolean;
type T1 = (a0: string, a1: () => string) => void;
type T2 = (a0: string) => Promise<number>;
type T3 = () => () => string;
type T4 = new () => string
const T0 = Type.Function([Type.Number(), Type.String()], Type.Boolean())
const T1 = Type.Function([Type.String(), Type.Function([], Type.String())], Type.Void())
const T2 = Type.Function([Type.String()], Type.Promise(Type.Number()))
const T3 = Type.Function([], Type.Function([], Type.String()))
const T4 = Type.Constructor([], Type.String())
Generic function signatures can be composed with TypeScript functions with Generic Constraints.
type ToString = <T>(t: T) => string
import { Type, Static, TStatic } from '@sinclair/typebox'
const ToString = <G extends TStatic>(T: G) => Type.Function([T], Type.String())
However, it's not possible to statically infer what type ToString
is without first creating some specialized variant of it. The following creates a specialization called NumberToString
.
const NumberToString = ToString(Type.Number())
type X = Static<typeof NumberToString>
// X is (arg0: number) => string
To take things a bit further, the following code contains some generic TypeScript REST setup with controllers that take some generic resource of type T
. Below this we express that same setup using TypeBox. The resulting type IRecordController
contains reflectable interface metadata about the RecordController
.
interface IController<T> {
get (): Promise<T>
post (resource: T): Promise<void>
put (resource: T): Promise<void>
delete (resource: T): Promise<void>
}
interface Record {
key: string
value: string
}
class StringController implements IController<Record> {
async get (): Promise<Record> { throw 'not implemented' }
async post (resource: Record): Promise<void> { /* */ }
async put (resource: Record): Promise<void> { /* */ }
async delete(resource: Record): Promise<void> { /* */ }
}
import { Type, Static, TStatic } from '@sinclair/typebox'
const IController = <G extends TStatic>(T: G) => Type.Object({
get: Type.Function([], Type.Promise(T)),
post: Type.Function([T], Type.Promise(Type.Void())),
put: Type.Function([T], Type.Promise(Type.Void())),
delete: Type.Function([T], Type.Promise(Type.Void())),
})
type Record = Static<typeof Record>
const Record = Type.Object({
key: Type.String(),
value: Type.String()
})
type IRecordController = Static<typeof IRecordController>
const IRecordController = IController(Record)
class RecordController implements IRecordController {
async get (): Promise<Record> { throw 'not implemented' }
async post (resource: Record): Promise<void> { /* */ }
async put (resource: Record): Promise<void> { /* */ }
async delete(resource: Record): Promise<void> { /* */ }
}
// Reflect
console.log(IRecordController)
The following uses the library Ajv to validate a type.
import * Ajv from 'ajv'
const ajv = new Ajv({ })
ajv.validate(Type.String(), 'hello') // true
ajv.validate(Type.String(), 123) // false
FAQs
Json Schema Type Builder with Static Type Resolution for TypeScript
We found that @sinclair/typebox demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Product
Socket now supports four distinct alert actions instead of the previous two, and alert triaging allows users to override the actions taken for all individual alerts.
Security News
Polyfill.io has been serving malware for months via its CDN, after the project's open source maintainer sold the service to a company based in China.
Security News
OpenSSF is warning open source maintainers to stay vigilant against reputation farming on GitHub, where users artificially inflate their status by manipulating interactions on closed issues and PRs.