@fastify/type-provider-json-schema-to-ts

A Type Provider for json-schema-to-ts

Install

1npm i @fastify/type-provider-json-schema-to-ts

TypeScript requirements

It is required to use TypeScript@4.3 or above with strict mode enabled and noStrictGenericChecks disabled. You may take the following configuration (tsconfig.json) as an example:

1{
2  "compilerOptions": {
3    "strict": true,
4    "noStrictGenericChecks": false
5  }
6}

Plugin definition

Note When using plugin types, withTypeProvider is not required to register the plugin.

1const plugin: FastifyPluginAsyncJsonSchemaToTs = async function (
2  fastify,
3  _opts
4) {
5  fastify.get(
6    "/",
7    {
8      schema: {
9        body: {
10          type: "object",
11          properties: {
12            x: { type: "string" },
13            y: { type: "number" },
14            z: { type: "boolean" },
15          },
16          required: ["x", "y", "z"],
17        } as const,
18      },
19    },
20    (req) => {
21      // The `x`, `y`, and `z` types are automatically inferred
22      const { x, y, z } = req.body;
23    }
24  );
25};

Setting FromSchema for the validator and serializer

You can set the FromSchema settings for things like references and deserialization for the validation and serialization schema by setting ValidatorSchemaOptions and SerializerSchemaOptions type parameters. You can use the deserialize option in SerializerSchemaOptions to allow Date objects in place of date-time strings or other special serialization rules handled by fast-json-stringify.

1const userSchema = {
2  type: "object",
3  additionalProperties: false,
4  properties: {
5    givenName: { type: "string" },
6    familyName: { type: "string" },
7  },
8  required: ["givenName", "familyName"],
9} as const satisfies JSONSchema;
10
11const sharedSchema = {
12  $id: "shared-schema",
13  definitions: {
14    user: userSchema,
15  },
16} as const satisfies JSONSchema;
17
18const userProfileSchema = {
19  $id: "userProfile",
20  type: "object",
21  additionalProperties: false,
22  properties: {
23    user: {
24      $ref: "shared-schema#/definitions/user",
25    },
26    joinedAt: { type: "string", format: "date-time" },
27  },
28  required: ["user", "joinedAt"],
29} as const satisfies JSONSchema
30
31
32type UserProfile = FromSchema<typeof userProfileSchema, {
33  references: [typeof sharedSchema]
34  deserialize: [{ pattern: { type: "string"; format: "date-time" }; output: Date }]
35}>;
36
37// Use JsonSchemaToTsProvider with shared schema references
38const fastify = Fastify().withTypeProvider<
39  JsonSchemaToTsProvider<{
40    ValidatorSchemaOptions: {
41      references: [typeof sharedSchema]
42    }
43  }>
44>();
45
46const fastify = Fastify().withTypeProvider<
47  JsonSchemaToTsProvider<{
48    ValidatorSchemaOptions: { references: [typeof sharedSchema] }
49    SerializerSchemaOptions: {
50      references: [typeof userProfileSchema]
51      deserialize: [{ pattern: { type: "string"; format: "date-time" }; output: Date }]
52    }
53  }>
54>()
55
56fastify.get(
57  "/profile",
58  {
59    schema: {
60      body: {
61        type: "object",
62        properties: {
63          user: {
64            $ref: "shared-schema#/definitions/user",
65          },
66        },
67        required: ['user'],
68      },
69      response: {
70        200: { $ref: "userProfile#" },
71      },
72    } as const,
73  },
74  (req, reply) => {
75    // `givenName` and `familyName` are correctly typed as strings
76    const { givenName, familyName } = req.body.user;
77
78    // Construct a compatible response type
79    const profile: UserProfile = {
80      user: { givenName: "John", familyName: "Doe" },
81      joinedAt: new Date(), // Returning a Date object
82    };
83
84    // A type error is surfaced if profile doesn't match the serialization schema
85    reply.send(profile)
86  }
87)

Using References in a Plugin Definition

When defining a plugin, shared schema references and deserialization options can also be used with FastifyPluginAsyncJsonSchemaToTs and FastifyPluginCallbackJsonSchemaToTs.

Example

1const schemaPerson = {
2  $id: "schema:person",
3  type: "object",
4  additionalProperties: false,
5  properties: {
6    givenName: { type: "string" },
7    familyName: { type: "string" },
8    joinedAt: { type: "string", format: "date-time" },
9  },
10  required: ["givenName", "familyName"],
11} as const satisfies JSONSchema;
12
13const plugin: FastifyPluginAsyncJsonSchemaToTs<{
14  ValidatorSchemaOptions: { references: [typeof schemaPerson] }
15  SerializerSchemaOptions: {
16    references: [typeof schemaPerson]
17    deserialize: [{ pattern: { type: "string"; format: "date-time" }; output: Date }]
18  };
19}> = async function (fastify, _opts) {
20  fastify.addSchema(schemaPerson)
21
22  fastify.get(
23    "/profile",
24    {
25      schema: {
26        body: {
27          type: "object",
28          properties: {
29            user: {
30              $ref: "schema:person",
31            },
32          },
33          required: ['user'],
34        },
35        response: {
36          200: { $ref: "schema:person" },
37        },
38      }, // as const satisfies JSONSchema is not required thanks to FastifyPluginAsyncJsonSchemaToTs
39    },
40    (req, reply) => {
41      // `givenName`, `familyName`, and `joinedAt` are correctly typed as strings and validated for format.
42      const { givenName, familyName, joinedAt } = req.body.user;
43
44      // Send a serialized response
45      reply.send({
46        givenName: "John",
47        familyName: "Doe",
48        // Date objects form DB queries can be returned directly and transformed to string by fast-json-stringify
49        joinedAt: new Date(),
50      })
51    }
52  )
53}
54
55const callbackPlugin: FastifyPluginCallbackJsonSchemaToTs<{
56  ValidatorSchemaOptions: { references: [typeof schemaPerson] }
57  SerializerSchemaOptions: {
58    references: [typeof schemaPerson]
59    deserialize: [{ pattern: { type: "string"; format: "date-time" }; output: Date }]
60  };
61}> = (fastify, options, done) => {
62  // Type check for custom options
63  expectType<string>(options.optionA)
64
65  // Schema is already added above
66  // fastify.addSchema(schemaPerson);
67
68  fastify.get(
69    "/callback-profile",
70    {
71      schema: {
72        body: {
73          type: "object",
74          properties: {
75            user: { $ref: "schema:person" },
76          },
77          required: ["user"],
78        },
79        response: {
80          200: { $ref: "schema:person" },
81        },
82      },
83    },
84    (req, reply) => {
85      const { givenName, familyName, joinedAt } = req.body.user
86
87      reply.send({
88        givenName,
89        familyName,
90        joinedAt: new Date(),
91      });
92    }
93  );
94
95  done()
96};