@shadow-library/fastify 1.4.0 → 1.5.1

package/cjs/module/fastify-router.js

@@ -23,7 +23,7 @@ const node_assert_1 = __importDefault(require("node:assert"));
 const app_1 = require("@shadow-library/app");
 const class_schema_1 = require("@shadow-library/class-schema");
 const common_1 = require("@shadow-library/common");
-const deepmerge_1 = __importDefault(require("deepmerge"));
+const deepmerge_1 = require("deepmerge");
 const find_my_way_1 = __importDefault(require("find-my-way"));
 const json_stable_stringify_1 = __importDefault(require("json-stable-stringify"));
 /**
@@ -32,11 +32,13 @@ const json_stable_stringify_1 = __importDefault(require("json-stable-stringify")
 const constants_1 = require("../constants.js");
 const decorators_1 = require("../decorators/index.js");
 const services_1 = require("../services/index.js");
+const data_transformers_1 = require("./data-transformers.js");
 /**
  * Declaring the constants
  */
 const httpMethods = Object.values(decorators_1.HttpMethod).filter(m => m !== decorators_1.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 app_1.Router {
     config;
     instance;
@@ -45,12 +47,17 @@ let FastifyRouter = class FastifyRouter extends app_1.Router {
     logger = common_1.Logger.getLogger(constants_1.NAMESPACE, 'FastifyRouter');
     cachedDynamicMiddlewares = new Map();
     childRouter = null;
+    transformers = { ...data_transformers_1.INBUILT_TRANSFORMERS };
     sensitiveTransformer = new class_schema_1.TransformerFactory(s => s['x-fastify']?.sensitive === true);
+    inputDataTransformer = new class_schema_1.TransformerFactory(s => this.isTransformable('input', s));
+    outputDataTransformer = new class_schema_1.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 = common_1.utils.object.pickKeys(config, ['ignoreTrailingSlash', 'ignoreDuplicateSlashes', 'allowUnsafeRegex', 'caseSensitive', 'maxParamLength', 'querystringParser']);
             this.childRouter = (0, find_my_way_1.default)(options);
@@ -59,6 +66,10 @@ let FastifyRouter = class FastifyRouter extends app_1.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')
@@ -67,6 +78,13 @@ let FastifyRouter = class FastifyRouter extends app_1.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');
@@ -88,7 +106,16 @@ let FastifyRouter = class FastifyRouter extends app_1.Router {
             return common_1.utils.string.maskWords(stringified);
         return '****';
     }
+    generateDataTransformer(type) {
+        return (value, schema, ctx) => {
+            const transformType = schema['x-fastify']?.transform?.[type];
+            const transformer = this.transformers[transformType];
+            (0, node_assert_1.default)(transformer, `transformer '${transformType}' not found`);
+            return transformer(value, ctx);
+        };
+    }
     getRequestLogger() {
+        const mask = this.maskField.bind(this);
         return (req, res, done) => {
             const startTime = process.hrtime();
             res.raw.on('finish', () => {
@@ -96,7 +123,7 @@ let FastifyRouter = class FastifyRouter extends app_1.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;
@@ -109,11 +136,11 @@ let FastifyRouter = class FastifyRouter extends app_1.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();
@@ -206,6 +233,52 @@ let FastifyRouter = class FastifyRouter extends app_1.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 = (0, deepmerge_1.all)([{}, 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 ?? {};
@@ -222,7 +295,7 @@ let FastifyRouter = class FastifyRouter extends app_1.Router {
             (0, node_assert_1.default)(metadata.method, 'Route method is required');
             this.logger.debug(`registering route ${metadata.method} ${metadata.path}`);
             const fastifyRouteOptions = common_1.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 === decorators_1.HttpMethod.ALL ? httpMethods : [metadata.method];
@@ -234,45 +307,78 @@ let FastifyRouter = class FastifyRouter extends app_1.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 = (0, deepmerge_1.default)(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' ? class_schema_1.ClassSchema.generate(bodySchema) : bodySchema;
+                const schema = isClassSchema(bodySchema) ? class_schema_1.ClassSchema.generate(bodySchema) : bodySchema;
                 routeOptions.schema.body = schema;
-                if (class_schema_1.ClassSchema.isBranded(schema) && isMaskEnabled) {
-                    const transformer = this.sensitiveTransformer.maybeCompile(schema);
-                    if (transformer)
-                        artifacts.transforms.maskBody = obj => transformer(obj, this.maskField);
+                if (class_schema_1.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' ? class_schema_1.ClassSchema.generate(paramsSchema) : paramsSchema;
+                const schema = isClassSchema(paramsSchema) ? class_schema_1.ClassSchema.generate(paramsSchema) : paramsSchema;
                 routeOptions.schema.params = schema;
-                if (class_schema_1.ClassSchema.isBranded(schema) && isMaskEnabled) {
-                    const transformer = this.sensitiveTransformer.maybeCompile(schema);
-                    if (transformer)
-                        artifacts.transforms.maskParams = obj => transformer(obj, this.maskField);
+                if (class_schema_1.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' ? class_schema_1.ClassSchema.generate(querySchema) : querySchema;
+                const schema = isClassSchema(querySchema) ? class_schema_1.ClassSchema.generate(querySchema) : querySchema;
                 routeOptions.schema.querystring = schema;
-                if (class_schema_1.ClassSchema.isBranded(schema) && isMaskEnabled) {
-                    const transformer = this.sensitiveTransformer.maybeCompile(schema);
-                    if (transformer)
-                        artifacts.transforms.maskQuery = obj => transformer(obj, this.maskField);
+                if (class_schema_1.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) ? class_schema_1.ClassSchema.generate(schemaDef) : schemaDef;
+                    responseSchemas[statusCode] = schema;
+                    if (class_schema_1.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/decorators/http-input.decorator.d.ts

@@ -1,5 +1,4 @@
-import { JSONSchema } from '@shadow-library/class-schema';
-import { Class } from 'type-fest';
+import { JSONSchema, SchemaClass } from '@shadow-library/class-schema';
 /**
  * Defining types
  */
@@ -10,7 +9,7 @@ export declare enum RouteInputType {
     REQUEST = "request",
     RESPONSE = "response"
 }
-export type RouteInputSchemas = Partial<Record<'body' | 'params' | 'query', JSONSchema | Class<unknown>>>;
+export type RouteInputSchemas = Partial<Record<'body' | 'params' | 'query', JSONSchema | SchemaClass>>;
 /**
  * Declaring the constants
  */

package/esm/decorators/http-output.decorator.d.ts

@@ -13,6 +13,9 @@ export interface DynamicRender<T extends JsonObject> {
     template: string;
     data: T;
 }
+/**
+ * Declaring the constants
+ */
 export declare const HttpStatus: (status: number) => MethodDecorator;
 export declare const Header: (name: string, value: string | (() => string)) => MethodDecorator;
 export declare const Redirect: (redirect: string, status?: number) => MethodDecorator;

package/esm/decorators/http-output.decorator.js

@@ -2,17 +2,13 @@
  * Importing npm packages
  */
 import { Route } from '@shadow-library/app';
-import { ClassSchema } from '@shadow-library/class-schema';
 /**
  * Declaring the constants
  */
-const isClass = (schema) => schema.toString().startsWith('class ');
 export const HttpStatus = (status) => Route({ status });
 export const Header = (name, value) => Route({ headers: { [name]: value } });
 export const Redirect = (redirect, status = 301) => Route({ redirect, status });
 export const Render = (render) => Route({ render: render ?? true });
 export function RespondFor(statusCode, schema) {
-    if (isClass(schema))
-        schema = ClassSchema.generate(schema);
     return Route({ schemas: { response: { [statusCode]: schema } } });
 }

package/esm/decorators/index.d.ts

@@ -4,4 +4,5 @@ export * from './http-output.decorator.js';
 export * from './http-route.decorator.js';
 export * from './middleware.decorator.js';
 export * from './sensitive.decorator.js';
+export * from './transform.decorator.js';
 export * from './version.decorator.js';

package/esm/decorators/index.js

@@ -4,4 +4,5 @@ export * from './http-output.decorator.js';
 export * from './http-route.decorator.js';
 export * from './middleware.decorator.js';
 export * from './sensitive.decorator.js';
+export * from './transform.decorator.js';
 export * from './version.decorator.js';

package/esm/decorators/transform.decorator.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Importing npm packages
+ */
+import { TransformerContext } from '@shadow-library/class-schema';
+/**
+ * Importing user defined packages
+ */
+/**
+ * Defining types
+ */
+export interface TransformOptions {
+    input?: TransformTypes;
+    output?: TransformTypes;
+}
+export interface CustomTransformers {
+}
+export interface InbuiltTransformers {
+    'email:normalize': (value: string) => string;
+    'string:trim': (value: string) => string;
+    'int:parse': (value: string) => number;
+    'float:parse': (value: string) => number;
+    'bigint:parse': (value: string) => bigint;
+    'strip:null': (value: any) => any;
+}
+export type TransformTypes = keyof CustomTransformers | keyof InbuiltTransformers;
+export type TransformerFn = (value: any, ctx: TransformerContext) => any;
+/**
+ * Declaring the constants
+ */
+export declare function Transform(type: TransformTypes | TransformOptions): PropertyDecorator;

package/esm/decorators/transform.decorator.js

@@ -0,0 +1,14 @@
+/**
+ * Importing npm packages
+ */
+import { FieldMetadata } from '@shadow-library/class-schema';
+/**
+ * Declaring the constants
+ */
+export function Transform(type) {
+    const options = typeof type === 'string' ? { input: type, output: type } : type;
+    return (target, propertyKey) => {
+        const decorator = FieldMetadata({ 'x-fastify': { transform: options } });
+        decorator(target, propertyKey);
+    };
+}

package/esm/interfaces/server-metadata.interface.d.ts

@@ -2,7 +2,7 @@
  * Importing npm packages
  */
 import { RouteMetadata } from '@shadow-library/app';
-import { JSONSchema } from '@shadow-library/class-schema';
+import { JSONSchema, SchemaClass } from '@shadow-library/class-schema';
 import { FastifyInstance, RouteShorthandOptions } from 'fastify';
 /**
  * Importing user defined packages
@@ -18,7 +18,7 @@ declare module '@shadow-library/app' {
         path?: string;
         version?: number;
         schemas?: RouteInputSchemas & {
-            response?: Record<number | string, JSONSchema>;
+            response?: Record<number | string, JSONSchema | SchemaClass>;
         };
         rawBody?: boolean;
         silentValidation?: boolean;

package/esm/module/data-transformers.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Importing npm packages
+ */
+/**
+ * Importing user defined packages
+ */
+import { InbuiltTransformers } from '../decorators/index.js';
+/**
+ * Defining types
+ */
+/**
+ * Declaring the constants
+ */
+export declare const INBUILT_TRANSFORMERS: InbuiltTransformers;

package/esm/module/data-transformers.js

@@ -0,0 +1,17 @@
+/**
+ * Importing npm packages
+ */
+/**
+ * Defining types
+ */
+/**
+ * Declaring the constants
+ */
+export const INBUILT_TRANSFORMERS = {
+    'email:normalize': value => value.trim().toLowerCase(),
+    'string:trim': value => value.trim(),
+    'int:parse': value => parseInt(value, 10),
+    'float:parse': value => parseFloat(value),
+    'bigint:parse': value => BigInt(value),
+    'strip:null': value => (value === null ? undefined : value),
+};

package/esm/module/fastify-module.interface.d.ts

@@ -8,6 +8,7 @@ import { Promisable } from 'type-fest';
 /**
  * Importing user defined packages
  */
+import { CustomTransformers } from '../decorators/index.js';
 import { ErrorHandler } from '../interfaces/index.js';
 import { ContextService } from '../services/index.js';
 /**
@@ -59,6 +60,10 @@ export interface FastifyConfig extends FastifyServerOptions {
      * The global route prefix for all routes in the Fastify instance
      */
     routePrefix?: string;
+    /**
+     * Object defining custom transformers for request and response data transformation
+     */
+    transformers?: Record<keyof CustomTransformers, (value: any) => any>;
 }
 export interface FastifyModuleOptions extends Partial<FastifyConfig> {
     /**

package/esm/module/fastify-router.d.ts

@@ -1,4 +1,5 @@
 import { ControllerRouteMetadata, Router } from '@shadow-library/app';
+import { Transformer } from '@shadow-library/class-schema';
 import { type FastifyInstance } from 'fastify';
 import { Chain as MockRequestChain, InjectOptions as MockRequestOptions, Response as MockResponse } from 'light-my-request';
 import { JsonObject, JsonValue } from 'type-fest';
@@ -49,12 +50,15 @@ export interface ChildRouteRequest {
     params: Record<string, string>;
     query: Record<string, string>;
 }
+interface Transformers {
+    body?: Transformer;
+    query?: Transformer;
+    params?: Transformer;
+    response?: Record<string, Transformer>;
+}
 interface RouteArtifacts {
-    transforms: {
-        maskBody?(body: object): object;
-        maskQuery?(query: object): object;
-        maskParams?(params: object): object;
-    };
+    masks: Partial<Record<'body' | 'query' | 'params', Transformer>>;
+    transformers: Transformers;
 }
 export declare class FastifyRouter extends Router {
     private readonly config;
@@ -64,17 +68,25 @@ export declare class FastifyRouter extends Router {
     private readonly logger;
     private readonly cachedDynamicMiddlewares;
     private readonly childRouter;
+    private readonly transformers;
     private readonly sensitiveTransformer;
+    private readonly inputDataTransformer;
+    private readonly outputDataTransformer;
     constructor(config: FastifyConfig, instance: FastifyInstance, context: ContextService);
     getInstance(): FastifyInstance;
+    private isTransformable;
     private joinPaths;
+    private addRouteHandler;
     private registerRawBody;
     private maskField;
+    private generateDataTransformer;
     private getRequestLogger;
     private parseControllers;
     private getStatusCode;
     private generateRouteHandler;
     private getMiddlewareHandler;
+    private transformResponseHandler;
+    private transformRequestHandler;
     register(controllers: ControllerRouteMetadata[]): Promise<void>;
     start(): Promise<void>;
     stop(): Promise<void>;