fastify 3.26.0 → 4.0.0-alpha.1

package/docs/Type-Providers.md

@@ -0,0 +1,257 @@
+<h1 align="center">Fastify</h1>
+
+## Type Providers
+
+Type Providers are a TypeScript only feature that enables Fastify to statically infer type information directly from inline JSON Schema. They are an alternative to specifying generic arguments on routes; and can greatly reduce the need to keep associated types for each schema defined in your project.
+
+### Providers
+
+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 Provider packages follow a `fastify-type-provider-{provider-name}` naming convention. 
+
+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)
+
+### Json Schema to Ts
+
+The following sets up a `json-schema-to-ts` Type Provider
+
+```bash
+$ npm install fastify-type-provider-json-schema-to-ts --save
+```
+
+```typescript
+import { JsonSchemaToTsTypeProvider } from 'fastify-type-provider-json-schema-to-ts'
+
+import fastify from 'fastify'
+
+const server = fastify().withTypeProvider<JsonSchemaToTsTypeProvider>()
+
+server.get('/route', {
+    schema: {
+        querystring: {
+            type: 'object',
+            properties: {
+                foo: { type: 'number' },
+                bar: { type: 'string' },
+            },
+            required: ['foo', 'bar']
+        }
+    } as const // don't forget to use const !
+
+}, (request, reply) => {
+
+    // type Query = { foo: number, bar: string }
+
+    const { foo, bar } = request.query // type safe!
+})
+```
+
+### TypeBox
+
+The following sets up a TypeBox Type Provider
+
+```bash
+$ npm install fastify-type-provider-typebox --save
+```
+
+```typescript
+import { TypeBoxTypeProvider, Type } from 'fastify-type-provider-typebox'
+
+import fastify from 'fastify'
+
+const server = fastify({
+    ajv: {
+        customOptions: {
+            strict: 'log',
+            keywords: ['kind', 'modifier'],
+        },
+    },
+}).withTypeProvider<TypeBoxTypeProvider>()
+
+server.get('/route', {
+    schema: {
+        querystring: Type.Object({
+            foo: Type.Number(),
+            bar: Type.String()
+        })
+    }
+}, (request, reply) => {
+
+    // type Query = { foo: number, bar: string }
+
+    const { foo, bar } = request.query // type safe!
+})
+```
+
+TypeBox uses the properties `kind` and `modifier` internally. These properties are not strictly valid JSON schema which will cause `AJV@7` and newer versions to throw an invalid schema error. To remove the error it's either necessary to omit the properties by using [`Type.Strict()`](https://github.com/sinclairzx81/typebox#strict) or use the AJV options for adding custom keywords.
+
+See also the [TypeBox documentation](https://github.com/sinclairzx81/typebox#validation) on how to set up AJV to work with TypeBox.
+
+### Scoped Type-Provider
+
+The provider types don't propagate globally. In encapsulated usage, one can remap the context to use one or more providers (for example, `typebox` and `json-schema-to-ts` can be used in the same application).
+
+Example:
+
+```ts
+import Fastify from 'fastify'
+import { TypeBoxTypeProvider } from '@fastify/type-provider-typebox'
+import { JsonSchemaToTsProvider } from '@fastify/type-provider-json-schema-to-ts'
+import { Type } from '@sinclair/typebox'
+
+const fastify = Fastify()
+
+function pluginWithTypebox(fastify: FastifyInstance, _opts, done): void {
+  fastify.withTypeProvider<TypeBoxTypeProvider>()
+    .get('/', {
+      schema: {
+        body: Type.Object({
+          x: Type.String(),
+          y: Type.Number(),
+          z: Type.Boolean()
+        })
+      }
+    }, (req) => {
+        const { x, y, z } = req.body // type safe
+    });
+  done()
+}
+
+function pluginWithJsonSchema(fastify: FastifyInstance, _opts, done): void {
+  fastify.withTypeProvider<JsonSchemaToTsProvider>()
+    .get('/', {
+      schema: {
+        body: {
+          type: 'object',
+          properties: {
+            x: { type: 'string' },
+            y: { type: 'number' },
+            z: { type: 'boolean' }
+          },
+        } as const
+      }
+    }, (req) => {
+      const { x, y, z } = req.body // type safe
+    });
+  done()
+}
+
+fastify.register(pluginWithJsonSchema)
+fastify.register(pluginWithTypebox)
+```
+
+It's also important to mention that once the types don't propagate globally, _currently_ is not possible to avoid multiple registrations on routes when dealing with several scopes, see bellow:
+
+```ts
+import Fastify from 'fastify'
+import { TypeBoxTypeProvider } from '@fastify/type-provider-typebox'
+import { Type } from '@sinclair/typebox'
+
+const server = Fastify({
+    ajv: {
+        customOptions: {
+            strict: 'log',
+            keywords: ['kind', 'modifier'],
+        },
+    },
+}).withTypeProvider<TypeBoxTypeProvider>()
+
+server.register(plugin1) // wrong
+server.register(plugin2) // correct
+
+function plugin1(fastify: FastifyInstance, _opts, done): void {
+  fastify.get('/', {
+    schema: {
+      body: Type.Object({
+        x: Type.String(),
+        y: Type.Number(),
+        z: Type.Boolean()
+      })
+    }
+  }, (req) => {
+    // it doesn't works! in a new scope needs to call `withTypeProvider` again
+    const { x, y, z } = req.body
+  });
+  done()
+}
+
+function plugin2(fastify: FastifyInstance, _opts, done): void {
+  const server = fastify.withTypeProvider<TypeBoxTypeProvider>()
+
+  server.get('/', {
+    schema: {
+      body: Type.Object({
+        x: Type.String(),
+        y: Type.Number(),
+        z: Type.Boolean()
+      })
+    }
+  }, (req) => {
+    // works
+    const { x, y, z } = req.body
+  });
+  done()
+}
+```
+
+### Type Definition of FastifyInstance + TypeProvider
+
+When working with modules one has to make use of `FastifyInstance` with Type Provider generics. See the example below:
+
+```ts
+// index.ts
+import Fastify from 'fastify'
+import { TypeBoxTypeProvider } from '@fastify/type-provider-typebox'
+import { registerRoutes } from './routes'
+
+const server = Fastify({
+    ajv: {
+        customOptions: {
+            strict: 'log',
+            keywords: ['kind', 'modifier'],
+        },
+    },
+}).withTypeProvider<TypeBoxTypeProvider>()
+
+registerRoutes(server)
+
+server.listen(3000)
+```
+
+```ts
+// routes.ts
+import { Type } from '@sinclair/typebox'
+import {
+  FastifyInstance,
+  FastifyLoggerInstance,
+  RawReplyDefaultExpression,
+  RawRequestDefaultExpression,
+  RawServerDefault
+} from 'fastify'
+import { TypeBoxTypeProvider } from '@fastify/type-provider-typebox'
+
+type FastifyTypebox = FastifyInstance<
+  RawServerDefault,
+  RawRequestDefaultExpression<RawServerDefault>,
+  RawReplyDefaultExpression<RawServerDefault>,
+  FastifyLoggerInstance,
+  TypeBoxTypeProvider
+>;
+
+export function registerRoutes(fastify: FastifyTypebox): void {
+  fastify.get('/', {
+    schema: {
+      body: Type.Object({
+        x: Type.String(),
+        y: Type.Number(),
+        z: Type.Boolean()
+      })
+    }
+  }, (req) => {
+    // works
+    const { x, y, z } = req.body
+  });
+}
+```

package/examples/hooks.js

@@ -37,7 +37,7 @@ fastify
     console.log('onRequest')
     done()
   })
-  .addHook('preParsing', function (request, reply, done) {
+  .addHook('preParsing', function (request, reply, payload, done) {
     console.log('preParsing')
     done()
   })

package/examples/simple-stream.js

@@ -0,0 +1,18 @@
+'use strict'
+
+const fastify = require('../fastify')({
+  logger: false
+})
+
+const Readable = require('stream').Readable
+
+fastify
+  .get('/', function (req, reply) {
+    const stream = Readable.from(['hello world'])
+    reply.send(stream)
+  })
+
+fastify.listen(3000, (err, address) => {
+  if (err) throw err
+  fastify.log.info(`server listening on ${address}`)
+})

package/fastify.d.ts

@@ -5,18 +5,21 @@ import { ConstraintStrategy, HTTPVersion } from 'find-my-way'
 
 import { FastifyRequest, RequestGenericInterface } from './types/request'
 import { RawServerBase, RawServerDefault, RawRequestDefaultExpression, RawReplyDefaultExpression } from './types/utils'
-import { FastifyLoggerInstance, FastifyLoggerOptions } from './types/logger'
+import { FastifyBaseLogger, FastifyLoggerInstance, FastifyLoggerOptions, PinoLoggerOptions } from './types/logger'
 import { FastifyInstance } from './types/instance'
 import { FastifyServerFactory } from './types/serverFactory'
 import { Options as AjvOptions } from '@fastify/ajv-compiler'
+import { Options as FJSOptions } from '@fastify/fast-json-stringify-compiler'
 import { FastifyError } from 'fastify-error'
 import { FastifyReply } from './types/reply'
 import { FastifySchemaValidationError } from './types/schema'
 import { ConstructorAction, ProtoAction } from "./types/content-type-parser";
 import { Socket } from 'net'
-import { Options as FJSOptions } from 'fast-json-stringify'
 import { ValidatorCompiler } from '@fastify/ajv-compiler'
-import { FastifySerializerCompiler } from './types/schema';
+import { SerializerCompiler } from '@fastify/fast-json-stringify-compiler'
+import { FastifySchema } from './types/schema'
+import { FastifyContextConfig } from './types/context'
+import { FastifyTypeProvider, FastifyTypeProviderDefault } from './types/type-provider'
 
 /**
  * Fastify factory function for the standard fastify http, https, or http2 server instance.
@@ -30,31 +33,39 @@ declare function fastify<
   Server extends http2.Http2SecureServer,
   Request extends RawRequestDefaultExpression<Server> = RawRequestDefaultExpression<Server>,
   Reply extends RawReplyDefaultExpression<Server> = RawReplyDefaultExpression<Server>,
-  Logger extends FastifyLoggerInstance = FastifyLoggerInstance
->(opts: FastifyHttp2SecureOptions<Server, Logger>): FastifyInstance<Server, Request, Reply, Logger> & PromiseLike<FastifyInstance<Server, Request, Reply, Logger>>
+  Logger extends FastifyBaseLogger = FastifyLoggerInstance,
+  TypeProvider extends FastifyTypeProvider = FastifyTypeProviderDefault,
+>(opts: FastifyHttp2SecureOptions<Server, Logger>): FastifyInstance<Server, Request, Reply, Logger, TypeProvider> & PromiseLike<FastifyInstance<Server, Request, Reply, Logger, TypeProvider>>
+
 declare function fastify<
   Server extends http2.Http2Server,
   Request extends RawRequestDefaultExpression<Server> = RawRequestDefaultExpression<Server>,
   Reply extends RawReplyDefaultExpression<Server> = RawReplyDefaultExpression<Server>,
-  Logger extends FastifyLoggerInstance = FastifyLoggerInstance
->(opts: FastifyHttp2Options<Server, Logger>): FastifyInstance<Server, Request, Reply, Logger> & PromiseLike<FastifyInstance<Server, Request, Reply, Logger>>
+  Logger extends FastifyBaseLogger = FastifyLoggerInstance,
+  TypeProvider extends FastifyTypeProvider = FastifyTypeProviderDefault,
+>(opts: FastifyHttp2Options<Server, Logger>): FastifyInstance<Server, Request, Reply, Logger, TypeProvider> & PromiseLike<FastifyInstance<Server, Request, Reply, Logger, TypeProvider>>
+
 declare function fastify<
   Server extends https.Server,
   Request extends RawRequestDefaultExpression<Server> = RawRequestDefaultExpression<Server>,
   Reply extends RawReplyDefaultExpression<Server> = RawReplyDefaultExpression<Server>,
-  Logger extends FastifyLoggerInstance = FastifyLoggerInstance
->(opts: FastifyHttpsOptions<Server, Logger>): FastifyInstance<Server, Request, Reply, Logger> & PromiseLike<FastifyInstance<Server, Request, Reply, Logger>>
+  Logger extends FastifyBaseLogger = FastifyLoggerInstance,
+  TypeProvider extends FastifyTypeProvider = FastifyTypeProviderDefault,
+>(opts: FastifyHttpsOptions<Server, Logger>): FastifyInstance<Server, Request, Reply, Logger, TypeProvider> & PromiseLike<FastifyInstance<Server, Request, Reply, Logger, TypeProvider>>
+
 declare function fastify<
   Server extends http.Server,
   Request extends RawRequestDefaultExpression<Server> = RawRequestDefaultExpression<Server>,
   Reply extends RawReplyDefaultExpression<Server> = RawReplyDefaultExpression<Server>,
-  Logger extends FastifyLoggerInstance = FastifyLoggerInstance
->(opts?: FastifyServerOptions<Server, Logger>): FastifyInstance<Server, Request, Reply, Logger> & PromiseLike<FastifyInstance<Server, Request, Reply, Logger>>
+  Logger extends FastifyBaseLogger = FastifyLoggerInstance,
+  TypeProvider extends FastifyTypeProvider = FastifyTypeProviderDefault,
+>(opts?: FastifyServerOptions<Server, Logger>): FastifyInstance<Server, Request, Reply, Logger, TypeProvider> & PromiseLike<FastifyInstance<Server, Request, Reply, Logger, TypeProvider>>
+
 export default fastify
 
 export type FastifyHttp2SecureOptions<
   Server extends http2.Http2SecureServer,
-  Logger extends FastifyLoggerInstance = FastifyLoggerInstance
+  Logger extends FastifyBaseLogger = FastifyLoggerInstance
 > = FastifyServerOptions<Server, Logger> & {
   http2: true,
   https: http2.SecureServerOptions,
@@ -63,7 +74,7 @@ export type FastifyHttp2SecureOptions<
 
 export type FastifyHttp2Options<
   Server extends http2.Http2Server,
-  Logger extends FastifyLoggerInstance = FastifyLoggerInstance
+  Logger extends FastifyBaseLogger = FastifyLoggerInstance
 > = FastifyServerOptions<Server, Logger> & {
   http2: true,
   http2SessionTimeout?: number
@@ -71,7 +82,7 @@ export type FastifyHttp2Options<
 
 export type FastifyHttpsOptions<
   Server extends https.Server,
-  Logger extends FastifyLoggerInstance = FastifyLoggerInstance
+  Logger extends FastifyBaseLogger = FastifyLoggerInstance
 > = FastifyServerOptions<Server, Logger> & {
   https: https.ServerOptions
 }
@@ -92,12 +103,13 @@ export interface ConnectionError extends Error {
  */
 export type FastifyServerOptions<
   RawServer extends RawServerBase = RawServerDefault,
-  Logger extends FastifyLoggerInstance = FastifyLoggerInstance
+  Logger extends FastifyBaseLogger = FastifyLoggerInstance
 > = {
   ignoreTrailingSlash?: boolean,
   connectionTimeout?: number,
   keepAliveTimeout?: number,
   maxRequestsPerSocket?: number,
+  forceCloseConnections?: boolean,
   requestTimeout?: number,
   pluginTimeout?: number,
   bodyLimit?: number,
@@ -106,13 +118,14 @@ export type FastifyServerOptions<
   exposeHeadRoutes?: boolean,
   onProtoPoisoning?: ProtoAction,
   onConstructorPoisoning?: ConstructorAction,
-  logger?: boolean | FastifyLoggerOptions<RawServer> | Logger,
+  logger?: boolean | FastifyLoggerOptions<RawServer> & PinoLoggerOptions | Logger,
   serializerOpts?: FJSOptions | Record<string, unknown>,
   serverFactory?: FastifyServerFactory<RawServer>,
   caseSensitive?: boolean,
   requestIdHeader?: string,
   requestIdLogLabel?: string;
-  genReqId?: <RequestGeneric extends RequestGenericInterface = RequestGenericInterface>(req: FastifyRequest<RequestGeneric, RawServer, RawRequestDefaultExpression<RawServer>>) => string,
+  jsonShorthand?: boolean;
+  genReqId?: <RequestGeneric extends RequestGenericInterface = RequestGenericInterface, TypeProvider extends FastifyTypeProvider = FastifyTypeProviderDefault>(req: FastifyRequest<RequestGeneric, RawServer, RawRequestDefaultExpression<RawServer>, FastifySchema, TypeProvider>) => string,
   trustProxy?: boolean | string | string[] | number | TrustProxyFunction,
   querystringParser?: (str: string) => { [key: string]: unknown },
   /**
@@ -138,7 +151,7 @@ export type FastifyServerOptions<
     };
     compilersFactory?: {
       buildValidator?: ValidatorCompiler;
-      buildSerializer?: (externalSchemas: unknown, serializerOptsServerOption: FastifyServerOptions["serializerOpts"]) => FastifySerializerCompiler<unknown>;
+      buildSerializer?: SerializerCompiler;
     };
   };
   return503OnClosing?: boolean,
@@ -146,10 +159,10 @@ export type FastifyServerOptions<
     customOptions?: AjvOptions,
     plugins?: (Function | [Function, unknown])[]
   },
-  frameworkErrors?: <RequestGeneric extends RequestGenericInterface = RequestGenericInterface>(
+  frameworkErrors?: <RequestGeneric extends RequestGenericInterface = RequestGenericInterface, TypeProvider extends FastifyTypeProvider = FastifyTypeProviderDefault, SchemaCompiler extends FastifySchema = FastifySchema>(
     error: FastifyError,
-    req: FastifyRequest<RequestGeneric, RawServer, RawRequestDefaultExpression<RawServer>>,
-    res: FastifyReply<RawServer, RawRequestDefaultExpression<RawServer>, RawReplyDefaultExpression<RawServer>>
+    req: FastifyRequest<RequestGeneric, RawServer, RawRequestDefaultExpression<RawServer>, FastifySchema, TypeProvider>,
+    res: FastifyReply<RawServer, RawRequestDefaultExpression<RawServer>, RawReplyDefaultExpression<RawServer>, RequestGeneric, FastifyContextConfig, SchemaCompiler, TypeProvider>
   ) => void,
   rewriteUrl?: (req: RawRequestDefaultExpression<RawServer>) => string,
   schemaErrorFormatter?: (errors: FastifySchemaValidationError[], dataVar: string) => Error,
@@ -181,7 +194,7 @@ export { FastifyRequest, RequestGenericInterface } from './types/request'
 export { FastifyReply } from './types/reply'
 export { FastifyPluginCallback, FastifyPluginAsync, FastifyPluginOptions, FastifyPlugin } from './types/plugin'
 export { FastifyInstance, PrintRoutesOptions } from './types/instance'
-export { FastifyLoggerOptions, FastifyLoggerInstance, FastifyLogFn, LogLevel } from './types/logger'
+export { FastifyLoggerOptions, FastifyBaseLogger, FastifyLoggerInstance, FastifyLogFn, LogLevel } from './types/logger'
 export { FastifyContext, FastifyContextConfig } from './types/context'
 export { RouteHandler, RouteHandlerMethod, RouteOptions, RouteShorthandMethod, RouteShorthandOptions, RouteShorthandOptionsWithHandler } from './types/route'
 export * from './types/register'
@@ -191,4 +204,5 @@ export { FastifySchema, FastifySchemaCompiler } from './types/schema'
 export { HTTPMethods, RawServerBase, RawRequestDefaultExpression, RawReplyDefaultExpression, RawServerDefault, ContextConfigDefault, RequestBodyDefault, RequestQuerystringDefault, RequestParamsDefault, RequestHeadersDefault } from './types/utils'
 export * from './types/hooks'
 export { FastifyServerFactory, FastifyServerFactoryHandler } from './types/serverFactory'
+export { FastifyTypeProvider, FastifyTypeProviderDefault } from './types/type-provider'
 export { fastify }