A Type Provider for Typebox.
npm i typebox # Required as peer dependency
npm i @fastify/type-provider-typebox| 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.
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.
import Fastify from 'fastify'
import { Type, TypeBoxTypeProvider } from '@fastify/type-provider-typebox'
const fastify = Fastify().withTypeProvider<TypeBoxTypeProvider>()Note that the following will not work:
import Fastify from 'fastify'
import { Type, TypeBoxTypeProvider } from '@fastify/type-provider-typebox'
const fastify = Fastify()
fastify.withTypeProvider<TypeBoxTypeProvider>()import Fastify from 'fastify'
import { TypeBoxTypeProvider } from '@fastify/type-provider-typebox'
// This package re-export Typebox package
// but you can also use any builders imported
// directly from typebox
import { Type } from 'typebox'
const fastify = Fastify().withTypeProvider<TypeBoxTypeProvider>()
fastify.post('/', {
schema: {
body: Type.Object({
x: Type.String(),
y: Type.Number(),
z: Type.Boolean()
})
}
}, (req) => {
// The `x`, `y`, `z` types are automatically inferred
const { x, y, z } = req.body
})import type { TypeBoxTypeProvider } from '@fastify/type-provider-typebox';
import { Type } from '@fastify/type-provider-typebox';
import type {
ContextConfigDefault,
FastifyBaseLogger,
FastifyInstance,
FastifyReply,
FastifyRequest,
RawReplyDefaultExpression,
RawRequestDefaultExpression,
RawServerDefault,
} from 'fastify';
import type { RouteGenericInterface } from 'fastify/types/route';
import type { FastifySchema } from 'fastify/types/schema';
export type FastifyTypeBox = FastifyInstance<
RawServerDefault,
RawRequestDefaultExpression,
RawReplyDefaultExpression,
FastifyBaseLogger,
TypeBoxTypeProvider
>;
export type FastifyRequestTypeBox<TSchema extends FastifySchema> = FastifyRequest<
RouteGenericInterface,
RawServerDefault,
RawRequestDefaultExpression,
TSchema,
TypeBoxTypeProvider
>;
export type FastifyReplyTypeBox<TSchema extends FastifySchema> = FastifyReply<
RouteGenericInterface,
RawServerDefault,
RawRequestDefaultExpression,
RawReplyDefaultExpression,
ContextConfigDefault,
TSchema,
TypeBoxTypeProvider
>;
export const CreateProductSchema = {
body: Type.Object({
name: Type.String(),
price: Type.Number(),
}),
response: {
201: Type.Object({
id: Type.Number(),
}),
},
};
export const CreateProductHandler = (
req: FastifyRequestTypeBox<typeof CreateProductSchema>,
reply: FastifyReplyTypeBox<typeof CreateProductSchema>,
) => {
// The `name` and `price` types are automatically inferred
const { name, price } = req.body;
// The response body type is automatically inferred
reply.status(201).send({ id: 'string-value' });
// ^? error TS2322: Type 'string' is not assignable to type 'number'.
};Note When using plugin types, withTypeProvider is not required in order to register the plugin
import { Type, FastifyPluginAsyncTypebox } from '@fastify/type-provider-typebox'
const plugin: FastifyPluginAsyncTypebox = async function(fastify, _opts) {
fastify.get('/', {
schema: {
body: Type.Object({
x: Type.String(),
y: Type.Number(),
z: Type.Boolean()
})
}
}, (req) => {
/// The `x`, `y`, and `z` types are automatically inferred
const { x, y, z } = req.body
});
}In plain JavaScript projects type-checked with checkJs, the type provider can be
applied with a JSDoc type cast:
import Fastify from 'fastify'
import { Type } from '@fastify/type-provider-typebox'
/** @typedef {import('fastify').FastifyInstance<import('fastify').RawServerDefault, import('fastify').RawRequestDefaultExpression, import('fastify').RawReplyDefaultExpression, import('fastify').FastifyBaseLogger, import('@fastify/type-provider-typebox').TypeBoxTypeProvider>} FastifyTypeBox */
const fastify = /** @type {FastifyTypeBox} */ (Fastify())
fastify.post('/', {
schema: {
body: Type.Object({ x: Type.String() })
}
}, (req) => {
const { x } = req.body // inferred as string
})For plugins, annotate the function with the plugin types instead:
/** @type {import('@fastify/type-provider-typebox').FastifyPluginAsyncTypebox} */
const plugin = async (fastify) => {
// routes registered here get full type inference
}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.
import { Type, TypeBoxTypeProvider, TypeBoxValidatorCompiler } from '@fastify/type-provider-typebox'
import Fastify from 'fastify'
const fastify = Fastify().setValidatorCompiler(TypeBoxValidatorCompiler)
fastify.withTypeProvider<TypeBoxTypeProvider>().get('/', {
schema: {
querystring: Type.Object({
x: Type.String(),
y: Type.String(),
z: Type.String()
})
}
}, (req) => {
const { x, y, z } = req.query
})For additional information on this compiler, please refer to the TypeBox documentation located here.
The Format module of TypeBox can be used to register string formats.
import { Format } from '@fastify/type-provider-typebox'
Format.Set('custom-format', (value) => value === 'custom');
Format.Set('regex-format', (value) => /^my-format$/.test(value));See the official TypeBox documentation for additional information on formats.
TypeBox provides built-in string formats. Call registerAjvFormats() before
compiling schemas to use the string formats from ajv-formats with
TypeBoxValidatorCompiler. This registers 22 formats in TypeBox's global format
registry, replacing any existing validators with the same names.
import { registerAjvFormats } from '@fastify/type-provider-typebox'
registerAjvFormats()The helper uses ajv-formats' full validation mode. Its rules differ from
TypeBox's defaults: url rejects http://localhost:3000, email rejects
user@localhost, date-time accepts a space separator, and uuid accepts the
urn:uuid: prefix. password and binary accept any string.
Numeric formats (int32, int64, float, and double) are not registered because
TypeBox's format registry validates strings. Register custom validators with
Format.Set() after calling the helper to override individual formats.
Licensed under MIT.