Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/fastify/fastify-type-provider-typebox
A Type Provider for Typebox
https://github.com/fastify/fastify-type-provider-typebox
fastify fastify-plugin
Last synced: 2 days ago
JSON representation
A Type Provider for Typebox
- Host: GitHub
- URL: https://github.com/fastify/fastify-type-provider-typebox
- Owner: fastify
- License: mit
- Created: 2021-12-03T00:58:16.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2024-12-05T12:37:27.000Z (17 days ago)
- Last Synced: 2024-12-13T15:17:27.362Z (9 days ago)
- Topics: fastify, fastify-plugin
- Language: TypeScript
- Size: 134 KB
- Stars: 154
- Watchers: 13
- Forks: 27
- Open Issues: 21
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# @fastify/type-provider-typebox
[](https://github.com/fastify/fastify-type-provider-typebox/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/@fastify/type-provider-typebox)
[](https://github.com/neostandard/neostandard)
A Type Provider for [Typebox](https://github.com/sinclairzx81/typebox).
## Installation
```sh
npm i @sinclair/typebox # Required as peer dependency
npm i @fastify/type-provider-typebox
```
### Compatibility
| Plugin version | Fastify version |
| ---------------|-----------------|
| `^5.x` | `^5.x` |
| `^1.x` | `^4.x` |
Please note that if a Fastify version is out of support, then so are the corresponding version(s) of this plugin
in the table above.
See [Fastify's LTS policy](https://github.com/fastify/fastify/blob/main/docs/Reference/LTS.md) for more details.
## Overview
This package provides enhanced support for TypeBox by integrating it with the Fastify [Type Provider](https://fastify.dev/docs/latest/Reference/Type-Providers/) 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
```ts
import Fastify from 'fastify'
import { Type, TypeBoxTypeProvider } from '@fastify/type-provider-typebox'
const fastify = Fastify().withTypeProvider()
```
Note that the following will not work:
```ts
import Fastify from 'fastify'
import { Type, TypeBoxTypeProvider } from '@fastify/type-provider-typebox'
const fastify = Fastify()
fastify.withTypeProvider()
```
## Example
```ts
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 @sinclair/typebox
import { Type } from '@sinclair/typebox'
const fastify = Fastify().withTypeProvider()
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
})
```
## Type definition of FastifyRequest & FastifyReply + TypeProvider
```ts
import {
FastifyReply,
FastifyRequest,
RawRequestDefaultExpression,
RawServerDefault,
RawReplyDefaultExpression,
ContextConfigDefault
} from 'fastify';
import { RouteGenericInterface } from 'fastify/types/route';
import { FastifySchema } from 'fastify/types/schema';
import { Type, TypeBoxTypeProvider } from '@fastify/type-provider-typebox';
export type FastifyRequestTypebox = FastifyRequest<
RouteGenericInterface,
RawServerDefault,
RawRequestDefaultExpression,
TSchema,
TypeBoxTypeProvider
>;
export type FastifyReplyTypebox = FastifyReply<
RawServerDefault,
RawRequestDefaultExpression,
RawReplyDefaultExpression,
RouteGenericInterface,
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,
reply: FastifyReplyTypebox
) => {
// 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'.
};
```
## Plugin definition
> **Note**
> When using plugin types, withTypeProvider is not required in order to register the plugin
```ts
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
});
}
```
## 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.
```ts
import { Type, TypeBoxTypeProvider, TypeBoxValidatorCompiler } from '@fastify/type-provider-typebox'
import Fastify from 'fastify'
const fastify = Fastify().setValidatorCompiler(TypeBoxValidatorCompiler)
fastify.withTypeProvider().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](https://github.com/sinclairzx81/typebox#Compiler).
## License
Licensed under [MIT](./LICENSE).