Reorder generic parameter of FastifyRequest for ease of use (fastify#2373)

* Reorder generic parameter of FastifyRequest for ease of use

* Update FastifyRequest doc to include typed request example

Author: thomasthiebaud

docs/TypeScript.md

@@ -627,8 +627,8 @@ Check out the main [Learn by Example](#learn-by-example) section for detailed gu
 
 #### Request
 
-##### fastify.FastifyRequest<[RawServer][RawServerGeneric], [RawRequest][RawRequestGeneric], [RequestGeneric][FastifyRequestGenericInterface]> 
-[src](./../types/request.d.ts#L29)
+##### fastify.FastifyRequest<[RequestGeneric][FastifyRequestGenericInterface], [RawServer][RawServerGeneric], [RawRequest][RawRequestGeneric]> 
+[src](./../types/request.d.ts#L15)
 
 This interface contains properties of Fastify request object. The properties added here disregard what kind of request object (http vs http2) and disregard what route level it is serving; thus calling `request.body` inside a GET request will not throw an error (but good luck sending a GET request with a body 😉).
 
@@ -655,6 +655,15 @@ declare module 'fastify' {
     someProp: string
   }
 }
+
+// Or you can type your request using
+type CustomRequest = FastifyRequest<{
+  Body: { test: boolean };
+}>
+
+server.get('/typedRequest', async (request: CustomRequest, reply: FastifyReply) => {
+  return request.body.test
+})
 ```
 
 ##### fastify.RequestGenericInterface

fastify.d.ts

@@ -3,7 +3,7 @@ import * as http2 from 'http2'
 import * as https from 'https'
 import * as LightMyRequest from 'light-my-request'
 
-import { FastifyRequest } from './types/request'
+import { FastifyRequest, RequestGenericInterface } from './types/request'
 import { RawServerBase, RawServerDefault, RawRequestDefaultExpression, RawReplyDefaultExpression } from './types/utils'
 import { FastifyLoggerInstance, FastifyLoggerOptions } from './types/logger'
 import { FastifyInstance } from './types/instance'
@@ -89,7 +89,7 @@ export type FastifyServerOptions<
   caseSensitive?: boolean,
   requestIdHeader?: string,
   requestIdLogLabel?: string;
-  genReqId?: (req: FastifyRequest<RawServer, RawRequestDefaultExpression<RawServer>>) => string,
+  genReqId?: <RequestGeneric extends RequestGenericInterface = RequestGenericInterface>(req: FastifyRequest<RequestGeneric, RawServer, RawRequestDefaultExpression<RawServer>>) => string,
   trustProxy?: boolean | string | string[] | number | TrustProxyFunction,
   querystringParser?: (str: string) => { [key: string]: string | string[] },
   versioning?: {
@@ -106,9 +106,9 @@ export type FastifyServerOptions<
     customOptions?: ajv.Options,
     plugins?: Function[]
   },
-  frameworkErrors?: (
+  frameworkErrors?: <RequestGeneric extends RequestGenericInterface = RequestGenericInterface>(
     error: FastifyError,
-    req: FastifyRequest<RawServer, RawRequestDefaultExpression<RawServer>>,
+    req: FastifyRequest<RequestGeneric, RawServer, RawRequestDefaultExpression<RawServer>>,
     res: FastifyReply<RawServer, RawRequestDefaultExpression<RawServer>, RawReplyDefaultExpression<RawServer>>
   ) => void,
   rewriteUrl?: (req: RawRequestDefaultExpression<RawServer>) => string

test/types/reply.test-d.ts

@@ -7,7 +7,7 @@ const getHandler: RouteHandlerMethod = function (_request, reply) {
   expectType<RawReplyDefaultExpression>(reply.raw)
   expectType<FastifyContext<ContextConfigDefault>>(reply.context)
   expectType<FastifyLoggerInstance>(reply.log)
-  expectType<FastifyRequest<RawServerDefault, RawRequestDefaultExpression, RequestGenericInterface>>(reply.request)
+  expectType<FastifyRequest<RequestGenericInterface, RawServerDefault, RawRequestDefaultExpression>>(reply.request)
   expectType<(statusCode: number) => FastifyReply>(reply.code)
   expectType<(statusCode: number) => FastifyReply>(reply.status)
   expectType<number>(reply.statusCode)

test/types/request.test-d.ts

@@ -2,6 +2,8 @@ import { expectType } from 'tsd'
 import fastify, { RouteHandlerMethod, RawRequestDefaultExpression, RequestBodyDefault, RequestGenericInterface } from '../../fastify'
 import { RawServerDefault, RequestParamsDefault, RequestHeadersDefault, RequestQuerystringDefault, RawReplyDefaultExpression } from '../../types/utils'
 import { FastifyLoggerInstance } from '../../types/logger'
+import { FastifyRequest } from '../../types/request'
+import { FastifyReply } from '../../types/reply'
 
 interface RequestBody {
   content: string;
@@ -28,6 +30,13 @@ interface RequestData extends RequestGenericInterface {
 
 type Handler = RouteHandlerMethod<RawServerDefault, RawRequestDefaultExpression, RawReplyDefaultExpression, RequestData>
 
+type CustomRequest = FastifyRequest<{
+  Body: RequestBody;
+  Querystring: RequestQuerystring;
+  Params: RequestParams;
+  Headers: RequestHeaders;
+}>
+
 const getHandler: RouteHandlerMethod = function (request, _reply) {
   expectType<string>(request.url)
   expectType<string>(request.method)
@@ -55,6 +64,18 @@ const postHandler: Handler = function (request) {
   expectType<string>(request.headers['x-foobar'])
 }
 
+function putHandler(request: CustomRequest, reply: FastifyReply) {
+  expectType<RequestBody>(request.body)
+  expectType<RequestParams>(request.params)
+  expectType<RequestHeaders & RawRequestDefaultExpression['headers']>(request.headers)
+  expectType<RequestQuerystring>(request.query)
+  expectType<string>(request.body.content)
+  expectType<string>(request.query.from)
+  expectType<number>(request.params.id)
+  expectType<string>(request.headers['x-foobar'])
+}
+
 const server = fastify()
 server.get('/get', getHandler)
 server.post('/post', postHandler)
+server.put('/put', putHandler)

types/content-type-parser.d.ts

@@ -14,8 +14,8 @@ export type FastifyBodyParser<
   RawServer extends RawServerBase = RawServerDefault,
   RawRequest extends RawRequestDefaultExpression<RawServer> = RawRequestDefaultExpression<RawServer>,
   RequestGeneric extends RequestGenericInterface = RequestGenericInterface,
-> = ((request: FastifyRequest<RawServer, RawRequest, RequestGeneric>, rawBody: RawBody, done: ContentTypeParserDoneFunction) => void)
-| ((request: FastifyRequest<RawServer, RawRequest, RequestGeneric>, rawBody: RawBody) => Promise<any>)
+> = ((request: FastifyRequest<RequestGeneric, RawServer, RawRequest>, rawBody: RawBody, done: ContentTypeParserDoneFunction) => void)
+| ((request: FastifyRequest<RequestGeneric, RawServer, RawRequest>, rawBody: RawBody) => Promise<any>)
 
 /**
  * Content Type Parser method that operates on request content
@@ -24,8 +24,8 @@ export type FastifyContentTypeParser<
   RawServer extends RawServerBase = RawServerDefault,
   RawRequest extends RawRequestDefaultExpression<RawServer> = RawRequestDefaultExpression<RawServer>,
   RequestGeneric extends RequestGenericInterface = RequestGenericInterface,
-> = ((request: FastifyRequest<RawServer, RawRequest, RequestGeneric>, payload: RawRequest) => Promise<any>)
-| ((request: FastifyRequest<RawServer, RawRequest, RequestGeneric>, payload: RawRequest, done: ContentTypeParserDoneFunction) => void)
+> = ((request: FastifyRequest<RequestGeneric, RawServer, RawRequest>, payload: RawRequest) => Promise<any>)
+| ((request: FastifyRequest<RequestGeneric, RawServer, RawRequest>, payload: RawRequest, done: ContentTypeParserDoneFunction) => void)
 
 /**
  * Natively, Fastify only supports 'application/json' and 'text/plain' content types. The default charset is utf-8. If you need to support different content types, you can use the addContentTypeParser API. The default JSON and/or plain text parser can be changed.

types/hooks.d.ts

@@ -29,7 +29,7 @@ export interface onRequestHookHandler<
   ContextConfig = ContextConfigDefault
 > {
   (
-    request: FastifyRequest<RawServer, RawRequest, RequestGeneric>,
+    request: FastifyRequest<RequestGeneric, RawServer, RawRequest>,
     reply: FastifyReply<RawServer, RawRequest, RawReply, RequestGeneric, ContextConfig>,
     done: HookHandlerDoneFunction
   ): Promise<unknown> | void;
@@ -47,7 +47,7 @@ export interface preParsingHookHandler<
   ContextConfig = ContextConfigDefault
 > {
   (
-    request: FastifyRequest<RawServer, RawRequest, RequestGeneric>,
+    request: FastifyRequest<RequestGeneric, RawServer, RawRequest>,
     reply: FastifyReply<RawServer, RawRequest, RawReply, RequestGeneric, ContextConfig>,
     payload: RequestPayload,
     done: <TError extends Error = FastifyError>(err?: TError | null, res?: RequestPayload) => void
@@ -65,7 +65,7 @@ export interface preValidationHookHandler<
   ContextConfig = ContextConfigDefault
 > {
   (
-    request: FastifyRequest<RawServer, RawRequest, RequestGeneric>,
+    request: FastifyRequest<RequestGeneric, RawServer, RawRequest>,
     reply: FastifyReply<RawServer, RawRequest, RawReply, RequestGeneric, ContextConfig>,
     done: HookHandlerDoneFunction
   ): Promise<unknown> | void;
@@ -82,7 +82,7 @@ export interface preHandlerHookHandler<
   ContextConfig = ContextConfigDefault
 > {
   (
-    request: FastifyRequest<RawServer, RawRequest, RequestGeneric>,
+    request: FastifyRequest<RequestGeneric, RawServer, RawRequest>,
     reply: FastifyReply<RawServer, RawRequest, RawReply, RequestGeneric, ContextConfig>,
     done: HookHandlerDoneFunction
   ): Promise<unknown> | void;
@@ -107,7 +107,7 @@ export interface preSerializationHookHandler<
   ContextConfig = ContextConfigDefault
 > {
   (
-    request: FastifyRequest<RawServer, RawRequest, RequestGeneric>,
+    request: FastifyRequest<RequestGeneric, RawServer, RawRequest>,
     reply: FastifyReply<RawServer, RawRequest, RawReply, RequestGeneric, ContextConfig>,
     payload: PreSerializationPayload,
     done: DoneFuncWithErrOrRes
@@ -127,7 +127,7 @@ export interface onSendHookHandler<
   ContextConfig = ContextConfigDefault
 > {
   (
-    request: FastifyRequest<RawServer, RawRequest, RequestGeneric>,
+    request: FastifyRequest<RequestGeneric, RawServer, RawRequest>,
     reply: FastifyReply<RawServer, RawRequest, RawReply, RequestGeneric, ContextConfig>,
     payload: OnSendPayload,
     done: DoneFuncWithErrOrRes
@@ -146,7 +146,7 @@ export interface onResponseHookHandler<
   ContextConfig = ContextConfigDefault
 > {
   (
-    request: FastifyRequest<RawServer, RawRequest, RequestGeneric>,
+    request: FastifyRequest<RequestGeneric, RawServer, RawRequest>,
     reply: FastifyReply<RawServer, RawRequest, RawReply, RequestGeneric, ContextConfig>,
     done: HookHandlerDoneFunction
   ): Promise<unknown> | void;
@@ -167,7 +167,7 @@ export interface onErrorHookHandler<
   TError extends Error = FastifyError
 > {
   (
-    request: FastifyRequest<RawServer, RawRequest, RequestGeneric>,
+    request: FastifyRequest<RequestGeneric, RawServer, RawRequest>,
     reply: FastifyReply<RawServer, RawRequest, RawReply, RequestGeneric, ContextConfig>,
     error: TError,
     done: () => void

types/instance.d.ts

@@ -219,15 +219,15 @@ export interface FastifyInstance<
   /**
    * Set the 404 handler
    */
-  setNotFoundHandler(
-    handler: (request: FastifyRequest<RawServer, RawRequest>, reply: FastifyReply<RawServer, RawRequest, RawReply>) => void
+  setNotFoundHandler<RequestGeneric extends RequestGenericInterface = RequestGenericInterface>(
+    handler: (request: FastifyRequest<RequestGeneric, RawServer, RawRequest>, reply: FastifyReply<RawServer, RawRequest, RawReply>) => void
   ): void;
 
   /**
    * Set a function that will be called whenever an error happens
    */
-  setErrorHandler<TError extends Error = FastifyError>(
-    handler: (this: FastifyInstance<RawServer, RawRequest, RawReply, Logger>, error: TError, request: FastifyRequest<RawServer, RawRequest>, reply: FastifyReply<RawServer, RawRequest, RawReply>) => void
+  setErrorHandler<TError extends Error = FastifyError, RequestGeneric extends RequestGenericInterface = RequestGenericInterface>(
+    handler: (this: FastifyInstance<RawServer, RawRequest, RawReply, Logger>, error: TError, request: FastifyRequest<RequestGeneric, RawServer, RawRequest>, reply: FastifyReply<RawServer, RawRequest, RawReply>) => void
   ): void;
 
   /**

types/logger.d.ts

@@ -1,6 +1,6 @@
 import { FastifyError } from 'fastify-error'
 import { RawServerBase, RawServerDefault, RawRequestDefaultExpression, RawReplyDefaultExpression } from './utils'
-import { FastifyRequest } from './request'
+import { FastifyRequest, RequestGenericInterface } from './request'
 
 /**
  * Standard Fastify logging function
@@ -60,5 +60,5 @@ export interface FastifyLoggerOptions<
     };
   };
   level?: string;
-  genReqId?: (req: FastifyRequest<RawServer, RawRequest>) => string;
+  genReqId?: <RequestGeneric extends RequestGenericInterface = RequestGenericInterface>(req: FastifyRequest<RequestGeneric, RawServer, RawRequest>) => string;
 }

types/plugin.d.ts

@@ -1,6 +1,6 @@
 import { FastifyInstance } from './instance'
 import { FastifyError } from 'fastify-error'
-import { RawServerBase, RawServerDefault, RawRequestDefaultExpression, RawReplyDefaultExpression } from './utils'
+import { RawServerBase, RawRequestDefaultExpression, RawReplyDefaultExpression } from './utils'
 
 /**
  * FastifyPlugin

types/reply.d.ts

@@ -17,7 +17,7 @@ export interface FastifyReply<
   raw: RawReply;
   context: FastifyContext<ContextConfig>;
   log: FastifyLoggerInstance;
-  request: FastifyRequest<RawServer, RawRequest, RequestGeneric>;
+  request: FastifyRequest<RequestGeneric, RawServer, RawRequest>;
   code(statusCode: number): FastifyReply<RawServer, RawRequest, RawReply, RequestGeneric, ContextConfig>;
   status(statusCode: number): FastifyReply<RawServer, RawRequest, RawReply, RequestGeneric, ContextConfig>;
   statusCode: number;

types/request.d.ts

@@ -13,9 +13,9 @@ export interface RequestGenericInterface {
  * It defaults to http.IncomingMessage, and it also extends the relative request object.
  */
 export interface FastifyRequest<
+  RequestGeneric extends RequestGenericInterface = RequestGenericInterface,
   RawServer extends RawServerBase = RawServerDefault,
   RawRequest extends RawRequestDefaultExpression<RawServer> = RawRequestDefaultExpression<RawServer>,
-  RequestGeneric extends RequestGenericInterface = RequestGenericInterface
 > {
   id: any;
   params: RequestGeneric['Params'];

types/route.d.ts

@@ -119,6 +119,6 @@ export type RouteHandlerMethod<
   ContextConfig = ContextConfigDefault
 > = (
   this: FastifyInstance<RawServer, RawRequest, RawReply>,
-  request: FastifyRequest<RawServer, RawRequest, RequestGeneric>,
+  request: FastifyRequest<RequestGeneric, RawServer, RawRequest>,
   reply: FastifyReply<RawServer, RawRequest, RawReply, RequestGeneric, ContextConfig>
 ) => void | Promise<any>

types/utils.d.ts

@@ -24,7 +24,7 @@ export type RawRequestDefaultExpression<
   RawServer extends RawServerBase = RawServerDefault
 > = RawServer extends http.Server | https.Server ? http.IncomingMessage
   : RawServer extends http2.Http2Server | http2.Http2SecureServer ? http2.Http2ServerRequest
-  : never
+    : never
 
 /**
  * The default reply type based on the server type. Utilizes generic constraining.
@@ -33,7 +33,7 @@ export type RawReplyDefaultExpression<
   RawServer extends RawServerBase = RawServerDefault
 > = RawServer extends http.Server | https.Server ? http.ServerResponse
   : RawServer extends http2.Http2Server | http2.Http2SecureServer ? http2.Http2ServerResponse
-  : never
+    : never
 
 export type RequestBodyDefault = unknown
 export type RequestQuerystringDefault = unknown