@shadow-library/fastify 1.3.0 → 1.5.0

package/esm/module/fastify-router.js

@@ -17,7 +17,7 @@ import assert from 'node:assert';
 import { Inject, Injectable, Router } from '@shadow-library/app';
 import { ClassSchema, TransformerFactory } from '@shadow-library/class-schema';
 import { InternalError, Logger, utils } from '@shadow-library/common';
-import merge from 'deepmerge';
+import { all as deepmerge } from 'deepmerge';
 import findMyWay from 'find-my-way';
 import stringify from 'json-stable-stringify';
 /**
@@ -26,11 +26,13 @@ import stringify from 'json-stable-stringify';
 import { FASTIFY_CONFIG, FASTIFY_INSTANCE, HTTP_CONTROLLER_INPUTS, HTTP_CONTROLLER_TYPE, NAMESPACE } from '../constants.js';
 import { HttpMethod } from '../decorators/index.js';
 import { ContextService } from '../services/index.js';
+import { INBUILT_TRANSFORMERS } from './data-transformers.js';
 /**
  * Declaring the constants
  */
 const httpMethods = Object.values(HttpMethod).filter(m => m !== HttpMethod.ALL);
-const DEFAULT_ARTIFACTS = { transforms: {} };
+const DEFAULT_ARTIFACTS = { masks: {}, transformers: {} };
+const isClassSchema = (schema) => typeof schema === 'function' || (Array.isArray(schema) && typeof schema[0] === 'function');
 let FastifyRouter = class FastifyRouter extends Router {
     config;
     instance;
@@ -39,12 +41,17 @@ let FastifyRouter = class FastifyRouter extends Router {
     logger = Logger.getLogger(NAMESPACE, 'FastifyRouter');
     cachedDynamicMiddlewares = new Map();
     childRouter = null;
+    transformers = { ...INBUILT_TRANSFORMERS };
     sensitiveTransformer = new TransformerFactory(s => s['x-fastify']?.sensitive === true);
+    inputDataTransformer = new TransformerFactory(s => this.isTransformable('input', s));
+    outputDataTransformer = new TransformerFactory(s => this.isTransformable('output', s));
     constructor(config, instance, context) {
         super();
         this.config = config;
         this.instance = instance;
         this.context = context;
+        if (config.transformers)
+            Object.assign(this.transformers, config.transformers);
         if (config.enableChildRoutes) {
             const options = utils.object.pickKeys(config, ['ignoreTrailingSlash', 'ignoreDuplicateSlashes', 'allowUnsafeRegex', 'caseSensitive', 'maxParamLength', 'querystringParser']);
             this.childRouter = findMyWay(options);
@@ -53,6 +60,10 @@ let FastifyRouter = class FastifyRouter extends Router {
     getInstance() {
         return this.instance;
     }
+    isTransformable(type, schema) {
+        const transformerType = schema['x-fastify']?.transform?.[type];
+        return typeof transformerType === 'string' && transformerType in this.transformers;
+    }
     joinPaths(...parts) {
         const path = parts
             .filter(p => typeof p === 'string')
@@ -61,6 +72,13 @@ let FastifyRouter = class FastifyRouter extends Router {
             .join('/');
         return `/${path}`;
     }
+    addRouteHandler(routeOptions, hook, handler, action = 'append') {
+        const existingHandlers = Array.isArray(routeOptions[hook]) ? routeOptions[hook] : routeOptions[hook] ? [routeOptions[hook]] : [];
+        if (action === 'prepend')
+            routeOptions[hook] = [handler, ...existingHandlers];
+        else
+            routeOptions[hook] = [...existingHandlers, handler];
+    }
     registerRawBody() {
         const opts = { parseAs: 'buffer' };
         const parser = this.instance.getDefaultJsonParser('error', 'error');
@@ -82,7 +100,16 @@ let FastifyRouter = class FastifyRouter extends Router {
             return utils.string.maskWords(stringified);
         return '****';
     }
+    generateDataTransformer(type) {
+        return (value, schema) => {
+            const transformType = schema['x-fastify']?.transform?.[type];
+            const transformer = this.transformers[transformType];
+            assert(transformer, `transformer '${transformType}' not found`);
+            return transformer(value);
+        };
+    }
     getRequestLogger() {
+        const mask = this.maskField.bind(this);
         return (req, res, done) => {
             const startTime = process.hrtime();
             res.raw.on('finish', () => {
@@ -90,7 +117,7 @@ let FastifyRouter = class FastifyRouter extends Router {
                 if (isLoggingDisabled)
                     return;
                 const { url, config } = req.routeOptions;
-                const { transforms } = config.artifacts ?? DEFAULT_ARTIFACTS;
+                const { masks } = config.artifacts ?? DEFAULT_ARTIFACTS;
                 const metadata = {};
                 metadata.rid = this.context.getRID();
                 metadata.url = url ?? req.raw.url;
@@ -103,11 +130,11 @@ let FastifyRouter = class FastifyRouter extends Router {
                 const resTime = process.hrtime(startTime);
                 metadata.timeTaken = (resTime[0] * 1e3 + resTime[1] * 1e-6).toFixed(3); // Converting time to milliseconds
                 if (req.body)
-                    metadata.body = transforms.maskBody ? transforms.maskBody(structuredClone(req.body)) : req.body;
+                    metadata.body = masks.body ? masks.body(structuredClone(req.body), mask) : req.body;
                 if (req.query)
-                    metadata.query = transforms.maskQuery ? transforms.maskQuery(structuredClone(req.query)) : req.query;
+                    metadata.query = masks.query ? masks.query(structuredClone(req.query), mask) : req.query;
                 if (req.params)
-                    metadata.params = transforms.maskParams ? transforms.maskParams(structuredClone(req.params)) : req.params;
+                    metadata.params = masks.params ? masks.params(structuredClone(req.params), mask) : req.params;
                 this.logger.http(`${req.method} ${metadata.url} -> ${res.statusCode} (${metadata.timeTaken}ms)`, metadata);
             });
             done();
@@ -200,6 +227,52 @@ let FastifyRouter = class FastifyRouter extends Router {
         this.cachedDynamicMiddlewares.set(cacheKey, handler);
         return handler;
     }
+    transformResponseHandler() {
+        const transform = this.generateDataTransformer('output');
+        return async (request, reply, payload) => {
+            const statusCode = String(reply.statusCode);
+            const responseTransformers = request.routeOptions.config.artifacts?.transformers.response;
+            if (!responseTransformers)
+                return payload;
+            let transformer = responseTransformers[statusCode];
+            if (!transformer) {
+                const fallbackStatus = statusCode.charAt(0) + 'xx';
+                transformer = responseTransformers[fallbackStatus];
+                this.logger.debug(`using fallback response transformer for status code ${statusCode}`, { fallbackStatus });
+            }
+            if (transformer) {
+                this.logger.debug(`transforming response for status code ${statusCode}`);
+                const cloned = deepmerge([{}, payload]);
+                const data = transformer(cloned, transform);
+                this.logger.debug(`transformed response for status code ${statusCode}`, { data });
+                return data;
+            }
+            return payload;
+        };
+    }
+    transformRequestHandler() {
+        const transform = this.generateDataTransformer('input');
+        return async (request) => {
+            const transformers = request.routeOptions.config.artifacts?.transformers;
+            if (!transformers)
+                return;
+            if (transformers.body && request.body) {
+                this.logger.debug('transforming request body', { body: request.body });
+                request.body = transformers.body(request.body, transform);
+                this.logger.debug('transformed request body', { body: request.body });
+            }
+            if (transformers.query && request.query) {
+                this.logger.debug('transforming request query', { query: request.query });
+                request.query = transformers.query(request.query, transform);
+                this.logger.debug('transformed request query', { query: request.query });
+            }
+            if (transformers.params && request.params) {
+                this.logger.debug('transforming request params', { params: request.params });
+                request.params = transformers.params(request.params, transform);
+                this.logger.debug('transformed request params', { params: request.params });
+            }
+        };
+    }
     async register(controllers) {
         const { middlewares, routes } = this.parseControllers(controllers);
         const defaultResponseSchemas = this.config.responseSchema ?? {};
@@ -216,7 +289,7 @@ let FastifyRouter = class FastifyRouter extends Router {
             assert(metadata.method, 'Route method is required');
             this.logger.debug(`registering route ${metadata.method} ${metadata.path}`);
             const fastifyRouteOptions = utils.object.omitKeys(metadata, ['path', 'method', 'schemas', 'rawBody', 'status', 'headers', 'redirect', 'render']);
-            const artifacts = { transforms: {} };
+            const artifacts = { masks: {}, transformers: {} };
             const routeOptions = { ...fastifyRouteOptions, config: { metadata, artifacts } };
             routeOptions.url = metadata.path;
             routeOptions.method = metadata.method === HttpMethod.ALL ? httpMethods : [metadata.method];
@@ -228,45 +301,78 @@ let FastifyRouter = class FastifyRouter extends Router {
                 const handler = await this.getMiddlewareHandler(middleware, metadata);
                 if (typeof handler === 'function') {
                     this.logger.debug(`applying '${type}' middleware '${name}'`);
-                    const middlewareHandler = routeOptions[type];
-                    if (middlewareHandler)
-                        middlewareHandler.push(handler);
-                    else
-                        routeOptions[type] = [handler];
+                    this.addRouteHandler(routeOptions, type, handler);
                 }
             }
-            routeOptions.schema = {};
+            const responseSchemas = { ...defaultResponseSchemas };
+            routeOptions.schema = { response: responseSchemas };
             routeOptions.attachValidation = metadata.silentValidation ?? false;
-            routeOptions.schema.response = merge(metadata.schemas?.response ?? {}, defaultResponseSchemas);
-            const { body: bodySchema, params: paramsSchema, query: querySchema } = metadata.schemas ?? {};
+            const { body: bodySchema, params: paramsSchema, query: querySchema, response: responseSchema } = metadata.schemas ?? {};
             const isMaskEnabled = this.config.maskSensitiveData ?? true;
             if (bodySchema) {
-                const schema = typeof bodySchema === 'function' ? ClassSchema.generate(bodySchema) : bodySchema;
+                const schema = isClassSchema(bodySchema) ? ClassSchema.generate(bodySchema) : bodySchema;
                 routeOptions.schema.body = schema;
-                if (ClassSchema.isBranded(schema) && isMaskEnabled) {
-                    const transformer = this.sensitiveTransformer.maybeCompile(schema);
-                    if (transformer)
-                        artifacts.transforms.maskBody = obj => transformer(obj, this.maskField);
+                if (ClassSchema.isBranded(schema)) {
+                    const bodyTransformer = this.inputDataTransformer.maybeCompile(schema);
+                    if (bodyTransformer)
+                        artifacts.transformers.body = bodyTransformer;
+                    if (isMaskEnabled) {
+                        const transformer = this.sensitiveTransformer.maybeCompile(schema);
+                        if (transformer)
+                            artifacts.masks.body = transformer;
+                    }
                 }
             }
             if (paramsSchema) {
-                const schema = typeof paramsSchema === 'function' ? ClassSchema.generate(paramsSchema) : paramsSchema;
+                const schema = isClassSchema(paramsSchema) ? ClassSchema.generate(paramsSchema) : paramsSchema;
                 routeOptions.schema.params = schema;
-                if (ClassSchema.isBranded(schema) && isMaskEnabled) {
-                    const transformer = this.sensitiveTransformer.maybeCompile(schema);
-                    if (transformer)
-                        artifacts.transforms.maskParams = obj => transformer(obj, this.maskField);
+                if (ClassSchema.isBranded(schema)) {
+                    const paramsTransformer = this.inputDataTransformer.maybeCompile(schema);
+                    if (paramsTransformer)
+                        artifacts.transformers.params = paramsTransformer;
+                    if (isMaskEnabled) {
+                        const transformer = this.sensitiveTransformer.maybeCompile(schema);
+                        if (transformer)
+                            artifacts.masks.params = transformer;
+                    }
                 }
             }
             if (querySchema) {
-                const schema = typeof querySchema === 'function' ? ClassSchema.generate(querySchema) : querySchema;
+                const schema = isClassSchema(querySchema) ? ClassSchema.generate(querySchema) : querySchema;
                 routeOptions.schema.querystring = schema;
-                if (ClassSchema.isBranded(schema) && isMaskEnabled) {
-                    const transformer = this.sensitiveTransformer.maybeCompile(schema);
-                    if (transformer)
-                        artifacts.transforms.maskQuery = obj => transformer(obj, this.maskField);
+                if (ClassSchema.isBranded(schema)) {
+                    const queryTransformer = this.inputDataTransformer.maybeCompile(schema);
+                    if (queryTransformer)
+                        artifacts.transformers.query = queryTransformer;
+                    if (isMaskEnabled) {
+                        const transformer = this.sensitiveTransformer.maybeCompile(schema);
+                        if (transformer)
+                            artifacts.masks.query = transformer;
+                    }
                 }
             }
+            if (responseSchema) {
+                const responseTransformers = {};
+                artifacts.transformers.response = responseTransformers;
+                for (const [code, schemaDef] of Object.entries(responseSchema)) {
+                    const statusCode = code.toLowerCase();
+                    const schema = isClassSchema(schemaDef) ? ClassSchema.generate(schemaDef) : schemaDef;
+                    responseSchemas[statusCode] = schema;
+                    if (ClassSchema.isBranded(schema)) {
+                        const transformer = this.outputDataTransformer.maybeCompile(schema);
+                        if (transformer)
+                            responseTransformers[statusCode] = transformer;
+                    }
+                }
+                if (Object.keys(responseTransformers).length > 0) {
+                    const handler = this.transformResponseHandler();
+                    this.addRouteHandler(routeOptions, 'preSerialization', handler);
+                }
+            }
+            if ('body' in artifacts.transformers || 'query' in artifacts.transformers || 'params' in artifacts.transformers) {
+                const handler = this.transformRequestHandler();
+                this.addRouteHandler(routeOptions, 'preHandler', handler, 'prepend');
+            }
             this.logger.debug('route options', { options: routeOptions });
             this.instance.route(routeOptions);
             this.logger.info(`registered route ${metadata.method} ${routeOptions.url}`);

package/esm/module/fastify.utils.d.ts

@@ -1,9 +1,16 @@
 import { ValidationError } from '@shadow-library/common';
-import { SchemaObject } from 'ajv';
+import Ajv, { SchemaObject } from 'ajv';
 import { FastifyInstance } from 'fastify';
 import { FastifyRouteSchemaDef, FastifySchemaValidationError, FastifyValidationResult, SchemaErrorDataVar } from 'fastify/types/schema';
 import { FastifyConfig, FastifyModuleOptions } from './fastify-module.interface.js';
+/**
+ * Defining types
+ */
+export interface AjvValidators {
+    strictValidator: Ajv;
+    lenientValidator: Ajv;
+}
 export declare const notFoundHandler: () => never;
-export declare function compileValidator(routeSchema: FastifyRouteSchemaDef<SchemaObject>): FastifyValidationResult;
+export declare function compileValidator(routeSchema: FastifyRouteSchemaDef<SchemaObject>, validators: AjvValidators): FastifyValidationResult;
 export declare function formatSchemaErrors(errors: FastifySchemaValidationError[], dataVar: SchemaErrorDataVar): ValidationError;
 export declare function createFastifyInstance(config: FastifyConfig, fastifyFactory?: FastifyModuleOptions['fastifyFactory']): Promise<FastifyInstance>;

package/esm/module/fastify.utils.js

@@ -9,17 +9,13 @@ import { fastify } from 'fastify';
  * Importing user defined packages
  */
 import { ServerError, ServerErrorCode } from '../server.error.js';
-/**
- * Defining types
- */
 /**
  * Declaring the constants
  */
 const keywords = ['x-fastify'];
 const allowedHttpParts = ['body', 'params', 'querystring'];
-const strictValidator = new Ajv({ allErrors: true, useDefaults: true, removeAdditional: true, strict: true, keywords });
-const lenientValidator = new Ajv({ allErrors: true, coerceTypes: true, useDefaults: true, removeAdditional: true, strict: true, keywords });
 const notFoundError = new ServerError(ServerErrorCode.S002);
+const defaultAjvOptions = { allErrors: true, useDefaults: true, removeAdditional: true, strict: true, keywords };
 export const notFoundHandler = () => throwError(notFoundError);
 function compileSchema(ajv, schema) {
     if (!schema.$id)
@@ -31,13 +27,13 @@ function compileSchema(ajv, schema) {
     }
     return ajv.getSchema(schema.$id);
 }
-export function compileValidator(routeSchema) {
+export function compileValidator(routeSchema, validators) {
     assert(allowedHttpParts.includes(routeSchema.httpPart), `Invalid httpPart: ${routeSchema.httpPart}`);
     if (routeSchema.httpPart === 'body')
-        return compileSchema(strictValidator, routeSchema.schema);
+        return compileSchema(validators.strictValidator, routeSchema.schema);
     if (routeSchema.httpPart === 'params')
-        return compileSchema(lenientValidator, routeSchema.schema);
-    const validate = compileSchema(lenientValidator, routeSchema.schema);
+        return compileSchema(validators.lenientValidator, routeSchema.schema);
+    const validate = compileSchema(validators.lenientValidator, routeSchema.schema);
     return (data) => {
         validate(data);
         for (const error of validate.errors ?? []) {
@@ -68,10 +64,19 @@ export function formatSchemaErrors(errors, dataVar) {
 export async function createFastifyInstance(config, fastifyFactory) {
     const options = utils.object.omitKeys(config, ['port', 'host', 'errorHandler', 'responseSchema']);
     const { errorHandler } = config;
+    const strictValidator = new Ajv({ ...defaultAjvOptions, ...config.ajv?.customOptions });
+    const lenientValidator = new Ajv({ ...defaultAjvOptions, coerceTypes: true, ...config.ajv?.customOptions });
+    for (let plugin of config.ajv?.plugins ?? []) {
+        if (typeof plugin === 'function')
+            plugin = [plugin, {}];
+        const [ajvPlugin, options] = plugin;
+        ajvPlugin(strictValidator, options);
+        ajvPlugin(lenientValidator, options);
+    }
     const instance = fastify(options);
     instance.setSchemaErrorFormatter(formatSchemaErrors);
     instance.setNotFoundHandler(notFoundHandler);
     instance.setErrorHandler(errorHandler.handle.bind(errorHandler));
-    instance.setValidatorCompiler(compileValidator);
+    instance.setValidatorCompiler(routeSchema => compileValidator(routeSchema, { strictValidator, lenientValidator }));
     return fastifyFactory ? await fastifyFactory(instance) : instance;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shadow-library/fastify",
   "type": "module",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "sideEffects": false,
   "description": "A Fastify wrapper featuring decorator-based routing, middleware and error handling",
   "repository": {