ElysiaJS

Appearance

Primitive Type ​

TypeBox API is designed around and similar to TypeScript type.

There are a lot of familiar names and behaviors that intersect with TypeScript counter-parts like: String, Number, Boolean, and Object as well as more advanced features like Intersect, KeyOf, Tuple for versatility.

If you are familiar with TypeScript, creating a TypeBox schema has the same behavior as writing a TypeScript type except it provides an actual type validation in runtime.

To create your first schema, import Elysia.t from Elysia and start with the most basic type:

typescript
import { Elysia, t } from 'elysia'

new Elysia()
    .get('/', () => 'Hello World!', {
        body: t.String()
    })
    .listen(3000)
import { Elysia, t } from 'elysia'

new Elysia()
    .get('/', () => 'Hello World!', {
        body: t.String()
    })
    .listen(3000)

This code tells Elysia to validate an incoming HTTP body, make sure that the body is String, and if it is String, then allow it to flow through the request pipeline and handler.

If the shape doesn't match, then it will throw an error, into Error Life Cycle.

Elysia Life Cycle

Basic Type ​

TypeBox provides a basic primitive type with the same behavior as same as TypeScript type.

The following table lists the most common basic type:

TypeBoxTypeScript
typescript
t.String()
t.String()
typescript
string
string
typescript
t.Number()
t.Number()
typescript
number
number
typescript
t.Boolean()
t.Boolean()
typescript
boolean
boolean
typescript
t.Array(
    t.Number()
)
t.Array(
    t.Number()
)
typescript
number[]
number[]
typescript
t.Object({
    x: t.Number()
})
t.Object({
    x: t.Number()
})
typescript
{
    x: number
}
{
    x: number
}
typescript
t.Null()
t.Null()
typescript
null
null
typescript
t.Literal(42)
t.Literal(42)
typescript
42
42

Elysia extends all types from TypeBox allowing you to reference most of the API from TypeBox to use in Elysia.

See TypeBox's Type for additional types that are supported by TypeBox.

Attribute ​

TypeBox can accept an argument for more comprehensive behavior based on JSON Schema 7 specification.

TypeBoxTypeScript
typescript
t.String({
    format: 'email'
})
t.String({
    format: 'email'
})
typescript
[email protected]
[email protected]
typescript
t.Number({
    minimum: 10,
    maximum: 100
})
t.Number({
    minimum: 10,
    maximum: 100
})
typescript
10
10
typescript
t.Array(
    t.Number(),
    {
        /**
         * Minimum number of items
         */
        minItems: 1,
        /**
         * Maximum number of items
         */
        maxItems: 5
    }
)
t.Array(
    t.Number(),
    {
        /**
         * Minimum number of items
         */
        minItems: 1,
        /**
         * Maximum number of items
         */
        maxItems: 5
    }
)
typescript
[1, 2, 3, 4, 5]
[1, 2, 3, 4, 5]
typescript
t.Object(
    {
        x: t.Number()
    },
    {
        /**
         * @default false
         * Accept additional properties
         * that not specified in schema
         * but still match the type
         */
        additionalProperties: true
    }
)
t.Object(
    {
        x: t.Number()
    },
    {
        /**
         * @default false
         * Accept additional properties
         * that not specified in schema
         * but still match the type
         */
        additionalProperties: true
    }
)
typescript
x: 100
y: 200
x: 100
y: 200

See JSON Schema 7 specification For more explanation for each attribute.


Honorable Mention ​

The following are common patterns that are often found useful when creating a schema.

Union ​

Allow multiple types via union.

TypeBoxTypeScriptValue
typescript
t.Union([
    t.String(),
    t.Number()
])
t.Union([
    t.String(),
    t.Number()
])
typescript
string | number
string | number
Hello
123
Hello
123

Optional ​

Provided in a property of t.Object, allowing the field to be undefined or optional.

TypeBoxTypeScriptValue
typescript
t.Object({
    x: t.Number(),
    y: t.Optional(t.Number())
})
t.Object({
    x: t.Number(),
    y: t.Optional(t.Number())
})
typescript
{
    x: number,
    y?: number
}
{
    x: number,
    y?: number
}
typescript
{
    x: 123
}
{
    x: 123
}

Partial ​

Allowing all of the fields in t.Object to be optional.

TypeBoxTypeScriptValue
typescript
t.Partial(
    t.Object({
        x: t.Number(),
        y: t.Number()
    })
)
t.Partial(
    t.Object({
        x: t.Number(),
        y: t.Number()
    })
)
typescript
{
    x?: number,
    y?: number
}
{
    x?: number,
    y?: number
}
typescript
{
    y: 123
}
{
    y: 123
}

Custom Error ​

TypeBox offers an additional "error" property, allowing us to return a custom error message if the field is invalid.

TypeBoxError
typescript
t.String({
    format: 'email',
    error: 'Invalid email :('
})
t.String({
    format: 'email',
    error: 'Invalid email :('
})
Invalid Email :(
Invalid Email :(
typescript
t.Object({
    x: t.Number()
}, {
    error: 'Invalid object UwU'
})
t.Object({
    x: t.Number()
}, {
    error: 'Invalid object UwU'
})
Invalid object UwU
Invalid object UwU