@relab/fastify-kit

Development kit to setup Fastify server with the following features:

• Fastify REST API
• Typed routes (Typescript & Zod)
• Typed error outputs
• Swagger (including schema for request/response as well as error outputs)
• Health check endpoints
• Secure with API Key
• Graceful shutdown

⚠️ It is for internal usage only. Use it on your own risk.

Requirements

• Node 18+
• Fastify 4+
• Zod 3+

Installation

NPM

npm install --save @relab/fastify-kit

PNPM

npm add @relab/fastify-kit

Usage

index.ts

1import { CorrelationId } from '@relab/fastify-correlation-id'
2import { HealthChecks } from '@relab/fastify-health-check'
3import { ApiKey, createFastifyApp, ErrorsHandling, HealthStatus, OpenApi, SecurityGuards } from '@relab/fastify-kit'
4import { handleShutdown, onShutdown } from '@relab/graceful-shutdown'
5import { logger } from '@relab/pino-logger'
6
7const app = createFastifyApp(FastifyOptions)
8    .register(CorrelationId)
9    .register(ErrorsHandling, ErrorsHandlingOptions)
10    .register(HealthStatus, HealthStatusOptions)
11    .register(HealthChecks, HealthCheckOptions)
12    .register(ApiKey(securitySchemes), ApiKeyOptions)
13    .register(SecurityGuards)
14    .register(OpenApi, OpenApiOptions)
15    .registerRoutes(Object.values(Routes))
16

routes.ts

1import { Route } from '@relab/fastify-kit'
2import { z } from 'zod'
3
4import { MessageActionSchema } from '../dto/message/action'
5import { MessageRecipientSchema } from '../dto/message/recipient'
6import { MessageSubject } from '../dto/message/subject'
7import { authorize } from '../security'
8
9const SendGenericMessageRequestSchema = z
10    .object({
11        to: z.array(MessageRecipientSchema).min(1).describe('Recipient list'),
12        subject: MessageSubject,
13        content: z
14            .object({
15                preview: z.string().optional().describe('Text that displayed in preview section for the message'),
16                header: z.string().describe('Header text in message body'),
17                text: z.string().describe('Message content'),
18                actions: z.array(MessageActionSchema).optional().describe('Actions'),
19            })
20            .describe('Message content'),
21    })
22    .describe('Send generic message request')
23    .ref('SendGenericMessageRequest')
24
25const SendGenericMessageResponseSchema = z
26    .object({
27        sent: z.array(z.string()).describe('The list of recipients to whom the message was sent'),
28    })
29    .ref('SendGenericMessageResponse')
30
31export const SendGenericMessageRoute: Route = async app => {
32    app.route({
33        method: 'POST',
34        url: '/send/generic/:id',
35        schema: {
36            operationId: 'MyApp.Email.SendGeneric',
37
38            summary: 'Send generic email message to the recipients',
39            description: 'Send generic email message to the recipients',
40
41            tags: ['email'],
42
43            body: SendGenericMessageRequestSchema,
44            response: {
45                200: SendGenericMessageResponseSchema,
46            },
47
48            security: authorize('api-key'),
49        },
50        handler: (req, reply) => {
51            for (const recipient of req.body.to) {
52                req.log.info(
53                    {
54                        subject: req.body.subject,
55                    },
56                    'Sending message to %s (%s)',
57                    recipient.name ?? 'n/a',
58                    recipient.email
59                )
60            }
61
62            return {
63                sent: req.body.to.map(x => x.email),
64            }
65        },
66    })
67}
68

License

Released under MIT by Sergey Zwezdin.