Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Add documentation for zod type provider #4456

Merged
merged 8 commits into from
Jun 25, 2023
Merged
Changes from 5 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
40 changes: 38 additions & 2 deletions docs/Reference/Type-Providers.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,15 +11,16 @@ keep associated types for each schema defined in your project.

Type Providers are offered as additional packages you will need to install into
your project. Each provider uses a different inference library under the hood;
allowing you to select the library most appropriate for your needs. Type
allowing you to select the library most appropriate for your needs. Official Type
Provider packages follow a `@fastify/type-provider-{provider-name}` naming
convention.
convention, and there are several community ones available as well.

The following inference packages are supported:

- `json-schema-to-ts` -
[github](https://github.com/ThomasAribart/json-schema-to-ts)
- `typebox` - [github](https://github.com/sinclairzx81/typebox)
- `zod` - [github](https://github.com/colinhacks/zod)

### Json Schema to Ts

Expand Down Expand Up @@ -91,6 +92,41 @@ See also the [TypeBox
documentation](https://github.com/sinclairzx81/typebox#validation) on how to set
up AJV to work with TypeBox.

### Zod

The following sets up a Zod Type Provider
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd mention this is not an official package.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree. And would we be adding a section here for every community module? I'm not sure this documentation belongs here. The module itself should explain how to use it.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree, but discoverability is an important thing too.
Would it be better if code sample was replaced with a link to zod provider repo?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see it is already listed under https://www.fastify.io/ecosystem/. Are you wanting to create another such list in this document?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this part of documentation already has a list, which gives a false impression of what type providers exist.

not everyone going to go through a random dump of ecosystem doc

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Surprising fact (😉): I have not paid this doc any attention. The only reason I have given any review of it this time is because you specifically asked me for one.

I think it is a mistake to have two lists with the same information in the documentation. In my opinion, we'd either note here that folks should review the ecosystem list for modules named as described, or update the ecosystem doc to remove any type providers in that list and add a section that states "see this other doc for the list".

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

what do you think about adding "type provider" section to ecosystem doc and linking it from here?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, that sounds good too.


```bash
$ npm i fastify-type-provider-zod
```

```typescript
import { ZodTypeProvider, validatorCompiler, serializerCompiler } from "fastify-type-provider-zod";
import { z } from 'zod';

import fastify from 'fastify'

const server = fastify().withTypeProvider<ZodTypeProvider>()

// This part is necessary if you also want to use zod for validating your requests and responses
server.setValidatorCompiler(validatorCompiler)
server.setSerializerCompiler(serializerCompiler)

server.get('/route', {
schema: {
querystring: z.object({
foo: z.number(),
bar: z.string(),
})
}
}, (request, reply) => {

// type Query = { foo: number, bar: string }

const { foo, bar } = request.query // type safe!
})
```

### Scoped Type-Provider

The provider types don't propagate globally. In encapsulated usage, one can
Expand Down