v3.0.0

What's Changed

Breaking Changes 🛠

This is a fairly big release, and hopefully should be the last breaking change in a little while. My aim with this library is to keep the functionality as stable as possible with as little change as possible. This release brings us to a place which is more closely aligned to the rest of the Fastify ecosystem, which should mean less breaking changes in the future.

Peer Dependencies

• The @fastify/swagger peer dependency range has been restricted to <9.2.0 due to a bug in that version which can cause Fastify to crash. This restriction will be lifted once the issue is patched.
• zod-openapi peer dependency requirement has been bumped to ^3.1.1. This enables us to use any CreateDocumentOptions the downstream library may introduce in the future.

Features

• Add Fast Json Stringify by @samchungy in #179

  This introduces fast-json-stringify which is used natively within Fastify and replaces the default JSON.stringify() serialization. This should result in a performance uplift in your server. If you have any benchmarks, feel free to share them back here.

  This should hopefully just "work" for most users, unless you are manually specifying components within the plugin options, however, I strongly recommend testing it in your own applications in case there are any edge cases in serialization. If you run into any issues, please create an issue

  Migration

  If you only use the ref auto-registering feature you can ignore this section.

  The migration is fairly simple, just pass the components you pass into the plugin also into the new createCustomSerializerCompiler function and pass that result to app.setSerializerCompiler.

  const components: ZodOpenApiComponentsObject = { schemas: { mySchema } };
  await app.register(fastifyZodOpenApiPlugin, {
    components,
  });
  // Create a custom serializer
  const customSerializerCompiler = createSerializerCompiler({
    components,
  });
  app.setSerializerCompiler(customSerializerCompiler);

  You can also return to the pre-existing JSON.stringify() serialization by passing it into the createCustomSerializerCompiler function.

  const customSerializerCompiler = createSerializerCompiler({ stringify: JSON.stringify });

• Add Fastify Error Handling by @samchungy in #175

  This blatantly copies the Error Implementation from fastify-type-provider-zod but adds its own twist.

  Migration

  Request Errors

  Previously, we exported a ValidationError class which was used for both request and response serialization errors. This worked fairly differently to the native Fastify implementation.

  We now export a ValidationRequestError and utilise Fastify's native error formatting to output errors. Instead of logging the entire ZodError in the message, we now emit errors request errors in the following format:

  {
    "code": "FST_ERR_VALIDATION",
    "error": "Bad Request",
    "message": "params/jobId Expected number, received string",
    "statusCode": 400
  }

  Response Errors

  For errors, we now emit a ResponseSerializationError. Previously, when a response serialization error occurred, we would previously leak the implementation details by emitting the ZodError results in the message of the 500 error. This has been changed and by default we will emit the following error:

  {
    "code": "FST_ERR_RESPONSE_SERIALIZATION",
    "error": "Internal Server Error",
    "message": "Response does not match the schema",
    "statusCode": 500
  }

  You can view the documentation on how you can handle and customize these errors.

Fixes

• Remove the need to double pass the openapi version.

  Previously, if you wanted to use an alternate openapi version, you needed to pass the openapi version twice into different plugins.

  const openapi: ZodOpenApiVersion = '3.0.3';
  await app.register(fastifyZodOpenApiPlugin, { openapi });
  await app.register(fastifySwagger, {
    openapi: {
      info: {
        title: 'hello world',
        version: '1.0.0',
      },
      openapi,
    },
  }

  We have changed the implementation to only require you to pass it into the fastify-swagger plugin.

  await app.register(fastifyZodOpenApiPlugin);
  await app.register(fastifySwagger, {
    openapi: {
      info: {
        title: 'hello world',
        version: '1.0.0',
      },
      openapi: '3.0.3' satisfies ZodOpenApiVersion,
    },
  }

New Contributors

• @jpb06 made their first contribution in #165

Full Changelog: v2.0.0...v3.0.0