State of TypeScript and Fastify

[Ethan-Arrowood]

Hi folks! I wanted to open a discussion about the state of TypeScript in fastify. We've had many new contributes join us helping improve TypeScript support across the ecosystem. Here are some questions to get us started.

1. What are some pain points in the current definitions you'd like to be fixed?
2. What aspect of the definitions do you enjoy and not enjoy using?
3. What external tools or utilities have you used to help you use fastify with TypeScript?
4. What server implementation patterns have you found successful when using fastify with TypeScript?

Furthermore, if there is something else you'd like to see discussed feel free to ask the question! Everyone (users & contributors) are encourage to reply (yes, even the folks who don't use TypeScript but want better support for things like code-hints in their editor) ❤️

[L2jLiga]

Hi,

1. What are some pain points in the current definitions you'd like to be fixed?
2. What aspect of the definitions do you enjoy and not enjoy using?

The biggest pain point for me is generics and hooks, such things like support in hooks arrays of functions, or just functions which may use done or Promise

Example

{
  preValidation: ((
      request: FastifyRequest<{ Querystring: { fileName: string | string[] } }>, _reply: FastifyReply, done: () => void,
    ) => {
      if (!Array.isArray(request.query.fileName)) request.query.fileName = [request.query.fileName];
      done();
    }) as preValidationHookHandler
}

without casting it as `preValidationHookHandler explicitely I'm facing with error

TS2322: Type '(request: FastifyRequest<{ Querystring: { fileName: string | string[]; };}>, _reply: FastifyReply, done: () => void) => void' is not assignable to type 'preValidationHookHandler<Server, IncomingMessage, ServerResponse, RouteGenericInterface, unknown> | preValidationHookHandler<...>[] | undefined'.
   Type '(request: FastifyRequest<{ Querystring: { fileName: string | string[]; };}>, _reply: FastifyReply, done: () => void) => void' is not assignable to type 'preValidationHookHandler<Server, IncomingMessage, ServerResponse, RouteGenericInterface, unknown>'.
     Types of parameters 'request' and 'request' are incompatible.       Type 'FastifyRequest<RouteGenericInterface, Server, IncomingMessage>' is not assignable to type 'FastifyRequest<{ Querystring: { fileName: string | string[]; }; }, Server, IncomingMessage>'.
         Type 'RouteGenericInterface' is not assignable to type '{ Querystring: { fileName: string | string[]; }; }'.
           Types of property 'Querystring' are incompatible.
             Type 'unknown' is not assignable to type '{ fileName: string | string[]; }'.

  route.d.ts(39, 3): The expected type comes from property 'preValidation' which is declared here on type 'RouteShorthandOptions<Server, IncomingMessage, ServerResponse, RouteGenericInterface, unknown>'

3. What external tools or utilities have you used to help you use fastify with TypeScript?
4. What server implementation patterns have you found successful when using fastify with TypeScript?

I've written own library to deal with it, so my solution is to use fastify-decorators combined it with typebox and typeorm, I even have own plugin for my library 😄

In general my TS code looks like several controllers, services, entities, I also use separated files for schemas and their TS types :)

Example

schemas.ts:

import { Type } from '@sinclair/typebox'

export const filesSchema = Type.Object({
  fileName: Type.Array(Type.String()),
}, {
  examples: [
    {
      name: 'Single file',
      summary: 'Single file',
      value: { fileName: 'sample.xd' },
    },
    {
      name: 'Multiple files',
      summary: 'Multiple files',
      value: { fileName: ['sample.xd', 'sample2.xd'] },
    },
  ],
})

export type Files = Static<typeof filesSchema>

FileController.ts:

import { Controller, GET } from 'fastify-decorators'
import { filesSchema, Files } from './schemas.js'

@Controller('/files')
export class FilesController {
  @GET('/', { schema: { query: filesSchema } })
  async getFiles(request: FastifyRequest<{ Querystring: Files  }>) {
    // async stuff here
  }
}

[Ethan-Arrowood]

I agree that is not a good experience with the hooks. I think the situation with generics in the type system needs an overall improvement.

[Ethan-Arrowood]

The decorator stuff is great. Honestly I'm starting to think that that model is best for a TypeScript x Fastify app. Nest.js has tremendous success with the pattern.

[airhorns]

A big pain point for me is that you need to use module augmentation to add types for the decorators that you add. I totally understand why it is necessary, but it is arcane syntax that I would guess many aren't familiar with, and requires a pretty deep understanding of the TS module concepts to get right.

Another one is that the types aren't aware of the encapsulation context, so you can't quite trust the types of the decorators anyways. If you decorate within an encapsulation context, you either have to type all FastifyRequests with that type which is a lie outside the context, or not decorate at all, which is a lie inside the context. It is also no fun to decorate twice with the same plugin but using a different type, like say fastify-passport with two different user logins and user types, one for your actual users and one for your staff accessing an admin area.

Having a blessed path for maintaining JSON schemas and derived types without writing them out twice would be dandy as well.

[spiffytech]

I tried pulling in the next branch, but all the Fastify plugins I use demand fastify@3.x so I didn't get very far with that.

I checked the types on next and it looks like encapsulated/scoped extensions to FastifyRequest are not presently supported. Both FastifyInstance and the route handler types hardcode FastifyRequest with no generic parameter to override that, so I don't see a way pass around a custom request type that my routes pick up.

[RafaelGSS]

It's a pending feature. See: #3529

[rubenferreira97]

As far as I know is not possible to scope TS declaration merging.

Please acknowledge these words as constructive criticism, but didn't fastify team acknowledge in February (via feedback) that declaration merging is a "band aid solution" and shouldn't already have looked for another architectural/structural solution? Declaration merging IS the problem of unscoped instances. I am aware that fastify wasn't build on TypeScript but I think it can do better.

Another issue for developers is they can't specify/build a custom plugin with custom types (Eg: Request, Reply, etc...). We have so many generics but then for some "basic" stuff we have no control.

Fastify is awesome, but needless to say there is always room for improvement.

[RafaelGSS]

Fastify is awesome, but needless to say there is always room for improvement.

Sure thing. Feel free to open an issue or use the above one linked to discuss a better approach for that. It would be certainly useful.

[mcollina]

Please acknowledge these words as constructive criticism, but didn't fastify team acknowledge in February (via feedback) that declaration merging is a "band aid solution" and shouldn't already have looked for another architectural/structural solution?

No, would you like to look for another solution? As always, all contributions are welcome here. I would love to read your thoughts and your designs.

You can express criticism on the technical front and we often have some heated debates between ourselves too - it's part of OSS. However criticizing how volunteers decide to spend their own time is not tolerated. Those comments will quickly antagonize this community. Be constructive and do not demand free work.

[delvedor]

What are some pain points in the current definitions you'd like to be fixed?

Having an out-of-the-box system to translate json schemas to types would be awesome.
The bets solution would be to offer one that just works™ and a way to inject your own, in the same way we are doing for validations and ajv.

[Ethan-Arrowood]

I love this idea!

[Ethan-Arrowood]

Check out this encapsulation solution I came up with:

type Server = {
  decorate: (key: string, value: any) => void
  get: (url: string, handler: (request: unknown, response: unknown) => void) => void
}
type Options = unknown

type FPlugin<S = unknown> = (server: Server & S, options: Options) => Promise<void>
type EncapsulatedFPlugin<P extends FPlugin<any>> = FPlugin<Parameters<P>[0]>

type AuthDecoration = {
  foo: string
}

const authPlugin: FPlugin<AuthDecoration> = async (server, options) => {
  server.decorate('foo', 'bar')
}

const privateRoute: EncapsulatedFPlugin<typeof authPlugin> = async (server, options) => {
  server.get('/', (request, response) => {
    server.foo
  })
}

TypeScript Playground

This could be potentially useful for properly encapsulated fastify plugin types without the need of TypeScript decorator syntax

[Ethan-Arrowood]

My idea with this is that whenever I build fastify apps, I already put all of my plugins and routes into their files and functions so that the encapsulation organization makes more sense implicitly. I think with a TypeScript utility like this, it would be a better experience for TS folks than the existing augmentation method.

[lachlancollins]

Hi Fastify team, love the work you're doing!

I just have a suggestion based on my experience using documentation for other projects - I'm wondering if it would be possible to integrate TS info into the each of the docs rather than having it as its own separate page (e.g. including info on how to type plugins within the plugins documentation)?

Also as a bonus suggestion - I've never worked with metalsmith so I'm not sure how hard it would be to add this functionality, but having some sort of code toggle between JS and TS examples would be amazing :) The example below is from the Redux Toolkit docs.

[Eomm]

Would you like to join this discussion: https://github.com/fastify/website/issues/291 ?