fastify-zod-query-coercion

v1.0.0

Published

4 days ago

A Fastify plugin that automatically converts query parameter types based on Zod schemas

Downloads

896

fastify-zod-query-coercion

A Fastify plugin that automatically coerces query string parameters to match Zod schemas.

Install

npm install fastify-zod-query-coercion

Usage

import Fastify from 'fastify';
import { serializerCompiler, validatorCompiler, type FastifyZodOpenApiTypeProvider } from 'fastify-zod-openapi';
import fastifyZodQueryCoercion from 'fastify-zod-query-coercion';
import { z } from 'zod';

const fastify = Fastify().withTypeProvider<FastifyZodOpenApiTypeProvider>();

// Set up Zod validation
fastify.setValidatorCompiler(validatorCompiler);
fastify.setSerializerCompiler(serializerCompiler);

// Register the plugin
await fastify.register(fastifyZodQueryCoercion);

// Define a route with a Zod schema for query parameters
fastify.get('/example', {
  schema: {
    querystring: z.object({
      id: z.number(),
      name: z.string(),
      isActive: z.boolean(),
      tags: z.array(z.string()),
    }),
  },
  handler: (request, reply) => {
    const { id, name, isActive, tags } = request.query;
    console.log({
      id: typeof id, // 'number'
      name: typeof name, // 'string'
      isActive: typeof isActive, // 'boolean'
      tags: Array.isArray(tags), // true
    });
    reply.send({ id, name, isActive, tags });
  },
});

fastify.listen({ port: 3000 }, (err) => {
  if (err) throw err;
  console.log('Server is running on http://localhost:3000');
  console.log('Try: http://localhost:3000/example?id=123&name=John&isActive=true&tags=a&tags=b');
});

How It Works

The plugin intercepts route definitions and transforms the Zod schemas for query parameters. It uses Zod's z.preprocess() to apply coercion rules similar to Ajv, ensuring that string inputs from query parameters are correctly converted to their intended types before Zod validation occurs.

Coercion Rules

This plugin follows Ajv coercion rules for Zod schemas. The coercion is applied before Zod validation occurs, ensuring that string inputs from query parameters are correctly converted to their intended types.

Currently Supported Coercion Rules

Boolean:
- String "true" → true
- String "false" → false
Number:
- String representation of a number → Number (e.g., "123" → 123, "3.14" → 3.14)
BigInt:
- String representation of a bigint → BigInt (e.g., "123" → 123n)
String:
- Any string value → Remains unchanged
Date:
- String representation of a number or ISO date → Date (e.g., "2023-10-01T00:00:00.000Z" → new Date("2023-10-01T00:00:00.000Z"))
Null:
- String "null" → null
Array:
- Single non-array value → Array with that single value (e.g., "foo" → ["foo"])
Tuple:
- Single non-array value → Tuple with that single value (e.g., "foo" → ["foo"])
Set:
- Single non-array value → Set with that single value (e.g., "foo" → new Set(["foo"]))
- Array → Set with array values (e.g., ["foo", "bar"] → new Set(["foo", "bar"]))

These coercion rules are applied recursively to nested schemas, including those within unions, optionals, and other complex types.

For a comprehensive list of supported Zod types, detailed coercion rules, and information about unsupported types, please refer to COERCION_RULES.md.

Route Parameters Support

By default, only query string parameters are processed. This plugin supports coercing both query string and route parameters. To enable route parameter coercion, include "params" in the coerceTypes option when registering the plugin.

// Register the plugin with route parameter coercion
await fastify.register(fastifyZodQueryCoercion, {
  coerceTypes: ['querystring', 'params']
});

// Define a route with a Zod schema for route parameters
fastify.get('/users/:userId', {
  schema: {
    params: z.object({
      userId: z.number(),
    }),
    querystring: z.object({
      isActive: z.boolean(),
    }),
  },
  handler: (request, reply) => {
    const { userId } = request.params;
    const { isActive } = request.query;
    console.log({
      userId: typeof userId, // 'number'
      isActive: typeof isActive, // 'boolean'
    });
    reply.send({ userId, isActive });
  },
});

fastify.listen({ port: 3000 }, (err) => {
  if (err) throw err;
  console.log('Server is running on http://localhost:3000');
  console.log('Try: http://localhost:3000/users/123?isActive=true');
});

API Reference