@rosen-bridge/fastify-enhanced 0.1.0 → 1.0.0

package/lib/fastify.ts

@@ -1,41 +1,26 @@
-import swagger from '@fastify/swagger';
-import swaggerUi from '@fastify/swagger-ui';
-import Fastify, { FastifyBaseLogger, FastifyInstance } from 'fastify';
+import 'zod-openapi/extend';
+
 import {
-  ZodTypeProvider,
-  jsonSchemaTransform,
+  type FastifyZodOpenApiTypeProvider,
+  fastifyZodOpenApiPlugin,
   validatorCompiler,
-} from 'fastify-type-provider-zod';
-import type { FastifySerializerCompiler } from 'fastify/types/schema';
-import * as http from 'http';
+} from 'fastify-zod-openapi';
+import Fastify from 'fastify';
 import JsonBigIntFactory from 'json-bigint';
-import type { ZodAny } from 'zod';
+
 import { FastifyWithZod, SwaggerOpts } from './types';
+import { registerSwagger } from './swagger';
+import { makeJsonParser } from './jsonParser';
+import { makeSerializerCompiler } from './serializerCompiler';
 
 /**
  * creates an instance of Fastify with Zod validation library as validator and
  * type provider
- *
- * @param {string} [swaggerPath='/swagger']
- * @param {boolean} [jsonHandler=JsonBigIntFactory({
- *     alwaysParseAsBig: false,
- *     useNativeBigInt: true,
- *   })]
- * @param {*} [opts={ logger: true }]
- * @return {Promise<
- *   FastifyInstance<
- *     http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>,
- *     http.IncomingMessage,
- *     http.ServerResponse<http.IncomingMessage>,
- *     FastifyBaseLogger,
- *     ZodTypeProvider
- *   >
- * >}
  */
-export const createFastify = async (
+export const makeFastify = async (
   swaggerOpts: SwaggerOpts = {
     path: '/swagger',
-    title: '',
+    title: 'api',
     description: '',
     version: '0.0.1',
   },
@@ -43,155 +28,26 @@ export const createFastify = async (
   jsonHandler = JsonBigIntFactory({
     alwaysParseAsBig: false,
     useNativeBigInt: true,
+    storeAsString: true,
   })
 ): Promise<FastifyWithZod> => {
-  const fastify = Fastify(opts).withTypeProvider<ZodTypeProvider>();
+  const fastify =
+    Fastify(opts).withTypeProvider<FastifyZodOpenApiTypeProvider>();
+
   fastify.setValidatorCompiler(validatorCompiler);
 
-  const serializerCompiler = getSerializerCompiler(jsonHandler);
+  const serializerCompiler = makeSerializerCompiler(jsonHandler);
   fastify.setSerializerCompiler(serializerCompiler);
 
+  await fastify.register(fastifyZodOpenApiPlugin);
+
   fastify.addContentTypeParser<string>(
     'application/json',
     { parseAs: 'string' },
-    function (req, body, done) {
-      try {
-        const json = jsonHandler.parse(body);
-        done(null, json);
-      } catch (err) {
-        if (err instanceof Error || err === null) {
-          done(err, undefined);
-        } else {
-          const wrappedErr = new Error(
-            `An unexpected error occurred while trying to parse request body`,
-            { cause: err }
-          );
-          done(wrappedErr, undefined);
-        }
-      }
-    }
+    makeJsonParser(jsonHandler)
   );
 
-  await addSwaggerRoute(fastify, swaggerOpts);
-  return fastify;
-};
-
-/**
- * creates a Fastify serializer compiler based on Zod validation library and
- * using the passed json parser/serializer
- *
- * @param {typeof JSON} jsonHandler
- * @return {(FastifySerializerCompiler<
- *   | ZodAny
- *   | {
- *       properties: ZodAny;
- *     }
- * >)}
- */
-const getSerializerCompiler = (
-  jsonHandler: ReturnType<typeof JsonBigIntFactory>
-): FastifySerializerCompiler<
-  | ZodAny
-  | {
-      properties: ZodAny;
-    }
-> => {
-  const hasOwnProperty = <T, K extends PropertyKey>(
-    obj: T,
-    prop: K
-  ): obj is T & Record<K, any> => {
-    return Object.prototype.hasOwnProperty.call(obj, prop);
-  };
-
-  /**
-   * resolve the right schema to be used
-   *
-   * @param {(ZodAny | { properties: ZodAny })} maybeSchema
-   * @return {Pick<ZodAny, 'safeParse'>}
-   */
-  function resolveSchema(
-    maybeSchema: ZodAny | { properties: ZodAny }
-  ): Pick<ZodAny, 'safeParse'> {
-    if (hasOwnProperty(maybeSchema, 'safeParse')) {
-      return maybeSchema;
-    }
-    if (hasOwnProperty(maybeSchema, 'properties')) {
-      return maybeSchema.properties;
-    }
-    throw new Error(`Invalid schema passed: ${JSON.stringify(maybeSchema)}`);
-  }
-
-  class ResponseValidationError extends Error {
-    public details: Record<string, any>;
+  await registerSwagger(fastify, swaggerOpts);
 
-    constructor(validationResult: Record<string, any>) {
-      super("Response doesn't match the schema");
-      this.name = 'ResponseValidationError';
-      this.details = validationResult.error;
-    }
-  }
-
-  /**
-   * creates a serializer compiler based on Zod library
-   *
-   * @param { schema: maybeSchema }
-   */
-  const serializerCompiler: FastifySerializerCompiler<
-    ZodAny | { properties: ZodAny }
-  > =
-    ({ schema: maybeSchema }) =>
-    (data) => {
-      const schema: Pick<ZodAny, 'safeParse'> = resolveSchema(maybeSchema);
-
-      const result = schema.safeParse(data);
-      if (result.success) {
-        return jsonHandler.stringify(result.data);
-      }
-
-      throw new ResponseValidationError(result);
-    };
-
-  return serializerCompiler;
-};
-
-/**
- * adds swagger to the fastify instance
- *
- * @param {Awaited<ReturnType<typeof createFastify>>} fastify
- * @param {string} path
- */
-const addSwaggerRoute = async (fastify: FastifyWithZod, opts: SwaggerOpts) => {
-  fastify.register(swagger, {
-    openapi: {
-      info: {
-        title: opts.title,
-        description: opts.description,
-        version: opts.version,
-      },
-      servers: [],
-    },
-    transform: jsonSchemaTransform,
-  });
-
-  fastify.register(swaggerUi, {
-    routePrefix: opts.path,
-    uiConfig: {
-      docExpansion: 'full',
-      deepLinking: false,
-    },
-    uiHooks: {
-      onRequest: function (request: any, reply: any, next: () => void) {
-        next();
-      },
-      preHandler: function (request: any, reply: any, next: () => void) {
-        next();
-      },
-    },
-    staticCSP: true,
-    transformStaticCSP: (header: any) => header,
-    transformSpecification: (swaggerObject: any, request: any, reply: any) => {
-      return swaggerObject;
-    },
-    transformSpecificationClone: true,
-  });
+  return fastify;
 };

package/lib/index.ts

@@ -1,3 +1,3 @@
-export { ZodTypeProvider } from 'fastify-type-provider-zod';
-export * from './dataTypes';
+export type { FastifyZodOpenApiTypeProvider } from 'fastify-zod-openapi';
 export * from './fastify';
+export * from './types';

package/lib/jsonParser.ts

@@ -0,0 +1,23 @@
+import { ContentTypeParserDoneFunction } from 'fastify/types/content-type-parser';
+import JsonBigIntFactory from 'json-bigint';
+
+export const makeJsonParser = (
+  jsonHandler: ReturnType<typeof JsonBigIntFactory>
+) => {
+  return (req: unknown, body: string, done: ContentTypeParserDoneFunction) => {
+    try {
+      const json = jsonHandler.parse(body);
+      done(null, json);
+    } catch (err) {
+      if (err instanceof Error || err === null) {
+        done(err, undefined);
+      } else {
+        const wrappedErr = new Error(
+          `An unexpected error occurred while trying to parse request body`,
+          { cause: err }
+        );
+        done(wrappedErr, undefined);
+      }
+    }
+  };
+};

package/lib/serializerCompiler.ts

@@ -0,0 +1,42 @@
+import { FastifySerializerCompiler } from 'fastify/types/schema';
+import { ZodAny } from 'zod';
+import JsonBigIntFactory from 'json-bigint';
+
+import { ResponseValidationError } from './error';
+import { hasOwnProperty } from './utils';
+
+type SerType = FastifySerializerCompiler<ZodAny | { properties: ZodAny }>;
+type JsonHandler = ReturnType<typeof JsonBigIntFactory>;
+
+/**
+ * creates a Fastify serializer compiler based on Zod validation library and
+ * using the passed json parser/serializer
+ */
+export const makeSerializerCompiler =
+  (jsonHandler: JsonHandler): SerType =>
+  (schemaDef) =>
+  (data) => {
+    const schema: Pick<ZodAny, 'safeParse'> = resolveSchema(schemaDef.schema);
+
+    const result = schema.safeParse(data);
+    if (result.success) {
+      return jsonHandler.stringify(result.data);
+    }
+
+    throw new ResponseValidationError(result);
+  };
+
+/**
+ * resolve the right schema to be used
+ */
+const resolveSchema = (
+  maybeSchema: ZodAny | { properties: ZodAny }
+): Pick<ZodAny, 'safeParse'> => {
+  if (hasOwnProperty(maybeSchema, 'safeParse')) {
+    return maybeSchema;
+  }
+  if (hasOwnProperty(maybeSchema, 'properties')) {
+    return maybeSchema.properties;
+  }
+  throw new Error(`Invalid schema passed: ${JSON.stringify(maybeSchema)}`);
+};

package/lib/swagger.ts

@@ -0,0 +1,52 @@
+import swagger from '@fastify/swagger';
+import swaggerUi from '@fastify/swagger-ui';
+import {
+  fastifyZodOpenApiTransform,
+  fastifyZodOpenApiTransformObject,
+} from 'fastify-zod-openapi';
+import { ZodOpenApiVersion } from 'zod-openapi';
+
+import { FastifyWithZod, SwaggerOpts } from './types';
+
+/**
+ * adds swagger to the fastify instance
+ */
+export const registerSwagger = async (
+  fastify: FastifyWithZod,
+  opts: SwaggerOpts
+) => {
+  await fastify.register(swagger, {
+    openapi: {
+      openapi: '3.1.0' as ZodOpenApiVersion,
+      info: {
+        title: opts.title,
+        description: opts.description,
+        version: opts.version,
+      },
+    },
+    transform: fastifyZodOpenApiTransform,
+    transformObject: fastifyZodOpenApiTransformObject,
+  });
+
+  await fastify.register(swaggerUi, {
+    routePrefix: opts.path,
+    uiConfig: {
+      docExpansion: 'full',
+      deepLinking: false,
+    },
+    uiHooks: {
+      onRequest: (request: any, reply: any, next: () => void) => {
+        next();
+      },
+      preHandler: (request: any, reply: any, next: () => void) => {
+        next();
+      },
+    },
+    staticCSP: true,
+    transformStaticCSP: (header: any) => header,
+    transformSpecification: (swaggerObject: any, request: any, reply: any) => {
+      return swaggerObject;
+    },
+    transformSpecificationClone: true,
+  });
+};

package/lib/types.ts

@@ -1,13 +1,13 @@
-import { FastifyBaseLogger, FastifyInstance } from 'fastify';
-import { ZodTypeProvider } from 'fastify-type-provider-zod';
 import * as http from 'http';
+import { FastifyBaseLogger, FastifyInstance } from 'fastify';
+import type { FastifyZodOpenApiTypeProvider } from 'fastify-zod-openapi';
 
 export type FastifyWithZod = FastifyInstance<
   http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>,
   http.IncomingMessage,
   http.ServerResponse<http.IncomingMessage>,
   FastifyBaseLogger,
-  ZodTypeProvider
+  FastifyZodOpenApiTypeProvider
 >;
 
 export interface SwaggerOpts {

package/lib/utils.ts

@@ -0,0 +1,6 @@
+export const hasOwnProperty = <T, K extends PropertyKey>(
+  obj: T,
+  prop: K
+): obj is T & Record<K, any> => {
+  return Object.prototype.hasOwnProperty.call(obj, prop);
+};

package/package.json

@@ -1,42 +1,41 @@
 {
   "name": "@rosen-bridge/fastify-enhanced",
-  "version": "0.1.0",
+  "version": "1.0.0",
   "description": "a wrapper around fastify web framework to make it even better",
   "repository": "git+https://github.com/rosen-bridge/utils.git",
-  "license": "GPL-3.0",
+  "license": "MIT",
   "author": "Rosen Team",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
     "build": "tsc --build tsconfig.build.json",
-    "coverage": "npm run test -- --coverage",
+    "coverage": "npm run test -- --run --coverage",
     "lint": "eslint --fix . && npm run prettify",
     "prettify": "prettier --write . --ignore-path ./.gitignore",
     "release": "npm run build && npm publish --access public",
-    "test": "NODE_OPTIONS=--experimental-specifier-resolution=node vitest",
+    "test": "NODE_OPTIONS='--import tsx' vitest",
+    "test:bin": "tsx tests/bin.ts",
     "type-check": "tsc --noEmit"
   },
   "devDependencies": {
-    "@types/node": "^18.19.2",
-    "@typescript-eslint/eslint-plugin": "^6.7.0",
-    "@typescript-eslint/parser": "^6.7.0",
-    "@vitest/coverage-c8": "^0.26.3",
-    "eslint": "^8.16.0",
-    "eslint-config-prettier": "^8.5.0",
-    "prettier": "2.7.1",
-    "typescript": "^5.0.0",
-    "vitest": "^0.26.2"
+    "@types/node": "^20.11.0",
+    "@vitest/coverage-istanbul": "^2.0.5",
+    "tsx": "^4.19.2",
+    "typescript": "^5.8.3",
+    "vitest": "^2.0.5",
+    "@types/json-bigint": "^1.0.1"
   },
   "engines": {
-    "node": ">=18.12.0"
+    "node": ">=20.11.0"
   },
   "dependencies": {
-    "@fastify/swagger": "^8.12.0",
-    "@fastify/swagger-ui": "^1.10.2",
-    "fastify": "^4.24.3",
-    "fastify-type-provider-zod": "^1.1.9",
+    "@fastify/swagger": "^9.5.1",
+    "@fastify/swagger-ui": "^5.2.3",
+    "fastify": "^5.3.3",
+    "fastify-zod-openapi": "^4.1.2",
     "json-bigint": "^1.0.0",
-    "zod": "^3.22.4"
+    "zod": "^3.25.56",
+    "zod-openapi": "^4.2.4"
   }
 }

package/tests/bin.ts

@@ -0,0 +1,13 @@
+// for manual testing
+
+import { makeFastify } from '../lib/fastify';
+import { FastifyWithZod } from '../lib/types';
+import { mockRoutes } from './mockRoute';
+
+const host = '127.0.0.1';
+const port = 1338;
+const mockServer: FastifyWithZod = await makeFastify();
+mockServer.register(async (s: FastifyWithZod) => mockRoutes(s));
+await mockServer.ready();
+await mockServer.listen({ host, port });
+console.log(`api service started at http://${host}:${port}`);

package/tests/e2e.spec.ts

@@ -0,0 +1,74 @@
+import { FastifyWithZod, makeFastify } from '../lib';
+import { mockRoutes } from './mockRoute';
+import { apiSpec } from './testData';
+
+describe('e2e', () => {
+  let mockServer: FastifyWithZod;
+
+  beforeEach(async () => {
+    mockServer = await makeFastify();
+    await mockServer.register(async () => mockRoutes(mockServer));
+  });
+
+  afterEach(async () => {
+    await mockServer.close();
+  });
+
+  /**
+   * @target fastifyServer[POST /mock] should respond with string representation of the bigint fields in the request body
+   * @dependencies
+   * @scenario
+   * - define a mock post route with bigint fields in its request body schema
+   * - send the request
+   * @expected
+   * - response status should have been 200
+   * - response should have matched the string representation of the same bigint fields as input
+   */
+  it('should respond with string representation of the bigint fields in the request body', async () => {
+    // act
+    const result = await mockServer.inject({
+      method: 'POST',
+      url: '/mock',
+      body: {
+        num1: 10_000,
+        num2: '999',
+        num3: '10100',
+      },
+    });
+
+    // assert
+    expect(result.statusCode).toEqual(200);
+    expect(result.json()).toEqual({
+      array: [
+        {
+          num1: '10000',
+          num2: '999',
+          num3: '10100',
+        },
+      ],
+      sum: '21099',
+    });
+  });
+
+  /**
+   * @target fastifyServer[POST /mock] should add routes to the swagger doc with support for bigint type
+   * @dependencies
+   * @scenario
+   * - define a mock post route with bigint fields in its request body schema
+   * - send a request to get openapi doc
+   * @expected
+   * - response status should have been 200
+   * - response should have matched the correct openapi doc with int64 as type of bigint fields
+   */
+  it('should add routes to the swagger doc with support for bigint type', async () => {
+    // act
+    const result = await mockServer.inject({
+      method: 'GET',
+      url: '/swagger/json',
+    });
+
+    // assert
+    expect(result.statusCode).toEqual(200);
+    expect(result.body).toEqual(JSON.stringify(apiSpec));
+  });
+});

package/tests/mockRoute.ts

@@ -0,0 +1,104 @@
+import { z } from 'zod';
+
+import { FastifyWithZod } from '../lib';
+
+/**
+ * two mock routes
+ * @param server
+ */
+export const mockRoutes = (server: FastifyWithZod) => {
+  server.get(
+    '/health',
+    {
+      schema: {
+        response: {
+          200: HealthResponseSchema,
+          500: ErrorResponseSchema,
+        },
+      },
+    },
+    async (request, reply) => {
+      try {
+        reply.status(200).send({
+          message: 673n,
+          number: 673,
+        });
+      } catch (error: any) {
+        reply.status(500).send({ message: error.message });
+      }
+    }
+  );
+
+  server.post(
+    '/mock',
+    {
+      schema: {
+        body: RequestSchema,
+        response: {
+          200: SuccessResponseSchema,
+          500: ErrorResponseSchema,
+        },
+      },
+    },
+    async (request, reply) => {
+      try {
+        reply.status(200).send({
+          array: [
+            {
+              num1: request.body.num1.toString(),
+              num2: request.body.num2.toString(),
+              num3: request.body.num3?.toString(),
+            },
+          ],
+          sum: (
+            request.body.num1 +
+            request.body.num2 +
+            (request.body.num3 ?? 0n)
+          ).toString(),
+        });
+      } catch (error: any) {
+        reply.status(500).send({ message: error.message });
+      }
+    }
+  );
+};
+
+export const RequestSchema = z.object({
+  num1: z.coerce.bigint(),
+  num2: z.coerce.bigint(),
+  num3: z.coerce.bigint(),
+  num4: z.optional(z.coerce.bigint()),
+});
+
+export const ResponseObjectSchema = z.object({
+  num1: z.string(),
+  num2: z.string(),
+  num3: z.string(),
+  num4: z.optional(z.string()),
+});
+
+export const SuccessResponseSchema = z.object({
+  array: z.array(ResponseObjectSchema),
+  sum: z.string(),
+});
+
+export const HealthResponseSchema = {
+  content: {
+    'application/json': {
+      schema: z.object({
+        message: z.bigint(),
+        number: z.number(),
+      }),
+    },
+  },
+};
+
+export const ErrorResponseSchema = {
+  content: {
+    'application/json': {
+      schema: z.object({
+        message: z.string(),
+      }),
+    },
+  },
+};