fastify-typebox v0.9.2

Install

$ npm install fastify-typebox --save

Overview

This library provides enhanced TypeBox support for Fastify. It enables automatic type inference for Fastify requests with no additional type hinting required. This library achieves this by remapping the Fastify interface using TypeScript conditional types only. It reconstructs Fastify Request and Reply types making them fully TypeBox aware.

Requires TypeScript 4.3.5 and above.

License MIT

Contents

• Usage
• Request
• Params
• Reply
• Plugins

Usage

The following demonstrates general usage.

import Fastify, { Type } from 'fastify-typebox'

const fastify = Fastify()

fastify.post('/users/:userId', { 
    schema: {
        body: Type.Object({
            x: Type.Number(),
            y: Type.Number()
        }),
        response: {
            200: Type.Object({
                result: Type.Number()
            })
        }
    }
}, (request, reply) => {
    
    // -------------------------------------
    // Requests
    // -------------------------------------

    // type Params = { userId: string }

    const { userId } = request.params

    // type Body = { x: number, y: number }

    const { x, y } = request.body             

    // -------------------------------------
    // Replies
    // -------------------------------------

    // type Response = { 200: { result: number } }

    reply.send({ result: 100 })                // error: no status code specified

    reply.status(400).send({ result: 42 })     // error: 400 status code not defined

    reply.status(200).send({ result: '42' })   // error: result type is not number

    reply.status(200).send({ result: x + y  })  // ok: !
})

Request

Fastify TypeBox request handling works exactly the same as Fastify. However you must specify schemas as TypeBox types. Fastify TypeBox will then automatically infer the correct types in the Fastify route handlers.

fastify.get('/records', {
    schema: {
        querystring: Type.Object({
            offset: Type.Integer({ minimum: 0 }),
            limit: Type.Integer({ maximum: 64 }),
        }),
        response: {
            200: Type.Array(
                Type.Object({
                    id: Type.String({format: 'uuid' }),
                    email: Type.String({format: 'email' })
                })
            )
        }
    }
}, async (request, reply) => {
    const { offset, limit } = request.query
    const records = await get(offset, limit)
    reply.status(200).send(records)
})

Params

Fastify TypeBox supports automatic param inference from urls. Param properties are always inferred as strings.

fastify.get('/users/:userId', (request, reply) => {
    const { userId } = request.params // userId is string
})

Reply

Fastify TypeBox implements static type checking which is derived from the status codes specified for a route. Users must call status(...) prior to calling send(...) where the specified status code is used to select the appropriate response schema.

fastify.get('/action', {
    schema: {
        response: {
            200: Type.String(),
            401: Type.Boolean(),
            500: Type.Number(),
        }
    }
}, (request, reply) => {
    reply.status(200).send('ok')  // must be string
    reply.status(401).send(false) // must be boolean
    reply.status(500).send(42)    // must be number
})

Plugins

Fastify TypeBox provides mappings for Fastify plugins. To enable type inference for the plugin, specify FastifyTypeBoxInstance instead of FastifyInstance for the instance parameter type.

import { FastifyTypeBoxInstance } from 'fastify-typebox'

async function MyPlugin(instance: FastifyTypeBoxInstance, options: { config: any }) {

    instance.get('/hello', (request, reply) => reply.send('world'))
}

...

fastify.register(MyPlugin, { config: 'xyz' })