@fastify/type-provider-typebox

A Type Provider for Typebox.

Installation

1npm i @sinclair/typebox # Required as peer dependency
2npm i @fastify/type-provider-typebox

Compatibility

Plugin version	Fastify version
>=5.x	^5.x
>=1.x <5.x	^4.x

Please note that if a Fastify version is out of support, then so are the corresponding versions of this plugin in the table above. See Fastify's LTS policy for more details.

Overview

This package provides enhanced support for TypeBox by integrating it with the Fastify Type Provider infrastructure. It provides a re-export of the TypeBox Type.* builder for convenience as well as providing additional utility types and optional validation infrastructure that can be useful when leveraging TypeBox with Fastify.

Usage

1import Fastify from 'fastify'
2import { Type, TypeBoxTypeProvider } from '@fastify/type-provider-typebox'
3
4const fastify = Fastify().withTypeProvider<TypeBoxTypeProvider>()

Note that the following will not work:

1import Fastify from 'fastify'
2import { Type, TypeBoxTypeProvider } from '@fastify/type-provider-typebox'
3
4const fastify = Fastify()
5
6fastify.withTypeProvider<TypeBoxTypeProvider>()

Example

1import Fastify from 'fastify'
2import { TypeBoxTypeProvider } from '@fastify/type-provider-typebox'
3
4// This package re-export Typebox package
5// but you can also use any builders imported
6// directly from @sinclair/typebox
7import { Type } from '@sinclair/typebox'
8
9
10const fastify = Fastify().withTypeProvider<TypeBoxTypeProvider>()
11
12fastify.post('/', {
13  schema: {
14    body: Type.Object({
15      x: Type.String(),
16      y: Type.Number(),
17      z: Type.Boolean()
18    })
19  }
20}, (req) => {
21  // The `x`, `y`, `z` types are automatically inferred
22  const { x, y, z } = req.body
23})

Type definition of FastifyRequest & FastifyReply + TypeProvider

1import type { TypeBoxTypeProvider } from '@fastify/type-provider-typebox';
2import { Type } from '@fastify/type-provider-typebox';
3import type {
4  ContextConfigDefault,
5  FastifyBaseLogger,
6  FastifyInstance,
7  FastifyReply,
8  FastifyRequest,
9  RawReplyDefaultExpression,
10  RawRequestDefaultExpression,
11  RawServerDefault,
12} from 'fastify';
13import type { RouteGenericInterface } from 'fastify/types/route';
14import type { FastifySchema } from 'fastify/types/schema';
15
16export type FastifyTypeBox = FastifyInstance<
17  RawServerDefault,
18  RawRequestDefaultExpression,
19  RawReplyDefaultExpression,
20  FastifyBaseLogger,
21  TypeBoxTypeProvider
22>;
23
24export type FastifyRequestTypeBox<TSchema extends FastifySchema> = FastifyRequest<
25  RouteGenericInterface,
26  RawServerDefault,
27  RawRequestDefaultExpression,
28  TSchema,
29  TypeBoxTypeProvider
30>;
31
32export type FastifyReplyTypeBox<TSchema extends FastifySchema> = FastifyReply<
33  RouteGenericInterface,
34  RawServerDefault,
35  RawRequestDefaultExpression,
36  RawReplyDefaultExpression,
37  ContextConfigDefault,
38  TSchema,
39  TypeBoxTypeProvider
40>;
41
42export const CreateProductSchema = {
43  body: Type.Object({
44    name: Type.String(),
45    price: Type.Number(),
46  }),
47  response: {
48    201: Type.Object({
49      id: Type.Number(),
50    }),
51  },
52};
53
54export const CreateProductHandler = (
55  req: FastifyRequestTypeBox<typeof CreateProductSchema>,
56  reply: FastifyReplyTypeBox<typeof CreateProductSchema>,
57) => {
58  // The `name` and `price` types are automatically inferred
59  const { name, price } = req.body;
60
61  // The response body type is automatically inferred
62  reply.status(201).send({ id: 'string-value' });
63  //                       ^? error TS2322: Type 'string' is not assignable to type 'number'.
64};

Plugin definition

Note When using plugin types, withTypeProvider is not required in order to register the plugin

1import { Type, FastifyPluginAsyncTypebox } from '@fastify/type-provider-typebox'
2
3const plugin: FastifyPluginAsyncTypebox = async function(fastify, _opts) {
4  fastify.get('/', {
5    schema: {
6      body: Type.Object({
7        x: Type.String(),
8        y: Type.Number(),
9        z: Type.Boolean()
10      })
11    }
12  }, (req) => {
13    /// The `x`, `y`, and `z` types are automatically inferred
14    const { x, y, z } = req.body
15  });
16}

Type Compiler

TypeBox provides an optional type compiler that perform very fast runtime type checking for data received on routes. Note this compiler is limited to types expressable through the TypeBox Type.* namespace only. To enable this compiler, you can call .setValidatorCompiler(...) with the TypeBoxValidatorCompiler export provided by this package.

1import { Type, TypeBoxTypeProvider, TypeBoxValidatorCompiler } from '@fastify/type-provider-typebox'
2import Fastify from 'fastify'
3
4const fastify = Fastify().setValidatorCompiler(TypeBoxValidatorCompiler)
5
6fastify.withTypeProvider<TypeBoxTypeProvider>().get('/', {
7  schema: {
8    querystring: Type.Object({
9      x: Type.String(),
10      y: Type.String(),
11      z: Type.String()
12    })
13  }
14}, (req) => {
15  const { x, y, z } = req.query
16})

For additional information on this compiler, please refer to the TypeBox documentation located here.

License

Licensed under MIT.