feat: add fastify helpers

package.json

@@ -51,6 +51,11 @@
     "typescript": "^5.0.2"
   },
   "dependencies": {
+    "@fastify/cors": "^8.0.0",
+    "@fastify/swagger": "^8.3.1",
+    "@fastify/type-provider-typebox": "^3.2.0",
+    "fastify": "^4.3.0",
+    "fastify-metrics": "^10.2.0",
     "node-pg-migrate": "^6.2.2",
     "pino": "^8.11.0",
     "postgres": "^3.3.4"

src/fastify/fastify.ts

@@ -0,0 +1,46 @@
+import FastifyCors from '@fastify/cors';
+import Fastify, { FastifyInstance } from 'fastify';
+import FastifyMetrics, { IFastifyMetrics } from 'fastify-metrics';
+import { PINO_LOGGER_CONFIG } from '../logger';
+import { TypeBoxTypeProvider } from '@fastify/type-provider-typebox';
+import { isProdEnv } from '../helpers';
+
+/**
+ * Creates a Fastify server that handles Prometheus metrics and CORS headers automatically.
+ * @returns Fastify instance
+ */
+export async function buildFastifyApiServer(): Promise<FastifyInstance> {
+  const fastify = Fastify({
+    trustProxy: true,
+    logger: PINO_LOGGER_CONFIG,
+  }).withTypeProvider<TypeBoxTypeProvider>();
+  if (isProdEnv) {
+    await fastify.register(FastifyMetrics, { endpoint: null });
+  }
+  await fastify.register(FastifyCors);
+  return fastify;
+}
+
+/**
+ * Creates a Fastify server that serves a `/metrics` endpoint with metrics taken from
+ * `FastifyMetrics`.
+ * @param args - Fastify instance metrics decorator
+ * @returns Fastify instance
+ */
+export async function buildPrometheusServer(args: {
+  metrics: IFastifyMetrics;
+}): Promise<FastifyInstance> {
+  const promServer = Fastify({
+    trustProxy: true,
+    logger: PINO_LOGGER_CONFIG,
+  });
+  promServer.route({
+    url: '/metrics',
+    method: 'GET',
+    logLevel: 'info',
+    handler: async (_, reply) => {
+      await reply.type('text/plain').send(await args.metrics.client.register.metrics());
+    },
+  });
+  return promServer;
+}

src/fastify/index.ts

@@ -0,0 +1,2 @@
+export * from './fastify';
+export * from './openapi';

src/fastify/openapi.ts

@@ -0,0 +1,30 @@
+import Fastify, { FastifyPluginAsync, FastifyPluginCallback } from 'fastify';
+import { TypeBoxTypeProvider } from '@fastify/type-provider-typebox';
+import { SwaggerOptions } from '@fastify/swagger';
+import FastifySwagger from '@fastify/swagger';
+import { existsSync, mkdirSync, writeFileSync } from 'fs';
+
+export interface OpenApiGeneratorOptions {
+  apiDefinition: FastifyPluginAsync | FastifyPluginCallback;
+  swaggerOptions?: SwaggerOptions;
+  prefix?: string;
+  outputDirectory?: string;
+}
+
+/**
+ * Generates OpenAPI JSON and YAML spec documents based on a given Fastify API plugin with optional
+ * Swagger definitions.
+ */
+export async function generateOpenApiSpec(options: OpenApiGeneratorOptions) {
+  const fastify = Fastify().withTypeProvider<TypeBoxTypeProvider>();
+  await fastify.register(FastifySwagger, options.swaggerOptions);
+  await fastify.register(options.apiDefinition, { prefix: options.prefix });
+  await fastify.ready();
+
+  const directory = options.outputDirectory ?? './tmp';
+  if (!existsSync(directory)) mkdirSync(directory);
+  writeFileSync(`${directory}/openapi.yaml`, fastify.swagger({ yaml: true }));
+  writeFileSync(`${directory}/openapi.json`, JSON.stringify(fastify.swagger(), null, 2));
+
+  await fastify.close();
+}

src/index.ts

@@ -1,5 +1,6 @@
 export * from './helpers';
 export * from './logger';
+export * from './fastify';
 export * from './postgres';
 export * from './server-version';
 export * from './shutdown-handler';

src/postgres/connection.ts

@@ -6,6 +6,8 @@ import { PG_TYPE_MAPPINGS } from './types';
 
 /** Postgres client instance */
 export type PgSqlClient = postgres.Sql<any> | postgres.TransactionSql<any>;
+/** Postgres pending query or query fragment */
+export type PgSqlQuery = postgres.PendingQuery<postgres.Row[]>;
 
 /** Postgres connection URI string */
 export type PgConnectionUri = string;