@shadow-library/fastify 0.0.9 → 0.0.11

package/esm/module/error-response.dto.d.ts

@@ -1,3 +1,12 @@
+/**
+ * Importing user defined packages
+ */
+/**
+ * Defining types
+ */
+/**
+ * Declaring the constants
+ */
 export declare class ErrorFieldDto {
     field: string;
     msg: string;

package/esm/module/error-response.dto.js

@@ -7,7 +7,19 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
+/**
+ * Importing npm packages
+ */
 import { Field, Schema } from '@shadow-library/class-schema';
+/**
+ * Importing user defined packages
+ */
+/**
+ * Defining types
+ */
+/**
+ * Declaring the constants
+ */
 let ErrorFieldDto = class ErrorFieldDto {
     field;
     msg;

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

@@ -1,24 +1,79 @@
+/**
+ * Importing npm packages
+ */
 import { FactoryProvider, ModuleMetadata } from '@shadow-library/app';
 import { JSONSchema } from '@shadow-library/class-schema';
 import { FastifyInstance, FastifyServerOptions } from 'fastify';
 import { Promisable } from 'type-fest';
+/**
+ * Importing user defined packages
+ */
 import { ErrorHandler } from '../interfaces/index.js';
+/**
+ * Defining types
+ */
 export interface FastifyConfig extends FastifyServerOptions {
+    /**
+     * The host on which the Fastify instance is to be started
+     * @default '127.0.0.1'
+     */
     host: string;
+    /**
+     * The port on which the Fastify instance is to be started
+     * @default 8080
+     */
     port: number;
+    /**
+     * The error handler to be used to handle errors thrown by the Fastify instance
+     * @default DefaultErrorHandler
+     */
     errorHandler: ErrorHandler;
+    /**
+     * The schema to be used to validate the response of the Fastify instance
+     * @default { '4xx': errorResponseSchema, '5xx': errorResponseSchema }
+     */
     responseSchema?: Record<string | number, JSONSchema>;
+    /**
+     * Enables internal execution of child routes (e.g., for SSR data fetching) without making actual HTTP requests.
+     * Useful for loading data while reusing middleware logic and shared context.
+     * @default false
+     */
     enableChildRoutes?: boolean;
+    /**
+     * Masks fields marked as sensitive in API inputs (body, query, and URL params) when written to logs.
+     * @default true
+     */
     maskSensitiveData?: boolean;
 }
 export interface FastifyModuleOptions extends Partial<FastifyConfig> {
+    /**
+     * The list of modules whose controllers are to be registered in the Fastify instance
+     */
     imports?: ModuleMetadata['imports'];
+    /**
+     * Factory function to modify the Fastify instance before it is used to register the controllers
+     */
     fastifyFactory?: (instance: FastifyInstance) => Promisable<FastifyInstance>;
+    /**
+     * The list of controllers to be registered in the Fastify instance
+     */
     controllers?: ModuleMetadata['controllers'];
+    /**
+     * The list of providers to be registered in the Fastify instance
+     */
     providers?: ModuleMetadata['providers'];
+    /**
+     * The list of providers to be exported by the Fastify module
+     */
     exports?: ModuleMetadata['exports'];
 }
 export interface FastifyModuleAsyncOptions extends Pick<FastifyModuleOptions, 'imports' | 'controllers' | 'providers' | 'exports' | 'fastifyFactory'> {
+    /**
+     * Factory function to create the FastifyModuleOptions
+     */
     useFactory: (...args: any[]) => Promisable<FastifyConfig>;
+    /**
+     * The list of providers to be injected into the factory function
+     */
     inject?: FactoryProvider['inject'];
 }

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

@@ -6,6 +6,9 @@ import { HttpMethod } from '../decorators/index.js';
 import { HttpRequest, HttpResponse, ServerMetadata } from '../interfaces/index.js';
 import { ContextService } from '../services/index.js';
 import { type FastifyConfig } from './fastify-module.interface.js';
+/**
+ * Defining types
+ */
 declare module 'fastify' {
     interface FastifyRequest {
         rawBody?: Buffer;
@@ -23,7 +26,9 @@ export interface RequestContext {
     body: JsonObject;
 }
 export interface RequestMetadata {
+    /** request id */
     rid?: string;
+    /** Service request id */
     srid?: string;
     method?: string;
     url?: string;
@@ -31,6 +36,7 @@ export interface RequestMetadata {
     reqLen?: string;
     reqIp?: string;
     resLen?: string;
+    /** Time taken to process the request */
     timeTaken?: string;
     body?: any;
     query?: object;
@@ -71,6 +77,11 @@ export declare class FastifyRouter extends Router {
     register(controllers: ControllerRouteMetadata[]): Promise<void>;
     start(): Promise<void>;
     stop(): Promise<void>;
+    /**
+     * Creates a new child context derived from the current one to load route-specific data
+     * during SSR. Automatically reuses middleware results from the parent context to avoid
+     * redundant execution and ensures correct context isolation for nested route data fetching.
+     */
     resolveChildRoute<T extends JsonValue = JsonObject>(url: string): Promise<T>;
     mockRequest(): MockRequestChain;
     mockRequest(options: MockRequestOptions): Promise<MockResponse>;

package/esm/module/fastify-router.js

@@ -10,6 +10,9 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
+/**
+ * Importing npm packages
+ */
 import assert from 'node:assert';
 import { Inject, Injectable, Router } from '@shadow-library/app';
 import { ClassSchema, TransformerFactory } from '@shadow-library/class-schema';
@@ -17,9 +20,15 @@ import { InternalError, Logger, utils } from '@shadow-library/common';
 import merge from 'deepmerge';
 import findMyWay from 'find-my-way';
 import stringify from 'json-stable-stringify';
+/**
+ * Importing user defined packages
+ */
 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';
+/**
+ * Declaring the constants
+ */
 const httpMethods = Object.values(HttpMethod).filter(m => m !== HttpMethod.ALL);
 const DEFAULT_ARTIFACTS = { transforms: {} };
 let FastifyRouter = class FastifyRouter extends Router {
@@ -84,7 +93,7 @@ let FastifyRouter = class FastifyRouter extends Router {
                 metadata.reqIp = req.headers['x-forwarded-for'] || req.socket.remoteAddress;
                 metadata.resLen = res.getHeader('content-length');
                 const resTime = process.hrtime(startTime);
-                metadata.timeTaken = (resTime[0] * 1e3 + resTime[1] * 1e-6).toFixed(3);
+                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;
                 if (req.query)
@@ -146,10 +155,12 @@ let FastifyRouter = class FastifyRouter extends Router {
             const query = request.query;
             const body = request.body;
             const context = { request, response, params, query, body };
+            /** Setting the status code and headers */
             response.status(statusCode);
             for (const [key, value] of Object.entries(metadata.headers ?? {})) {
                 response.header(key, typeof value === 'function' ? value() : value);
             }
+            /** Handling the actual route and serializing the output */
             const args = argsOrder.map(arg => arg && context[arg]);
             const data = await route.handler(...args);
             if (metadata.redirect)
@@ -170,11 +181,13 @@ let FastifyRouter = class FastifyRouter extends Router {
     async getMiddlewareHandler(middleware, metadata) {
         if (!middleware.metadata.generates)
             return middleware.handler.bind(middleware.instance);
+        /** Generating the cache key and getting the cached middleware */
         const genCacheKey = 'cacheKey' in middleware.instance && typeof middleware.instance.cacheKey === 'function' ? middleware.instance.cacheKey : stringify;
         const cacheKey = genCacheKey(metadata);
         const cachedMiddleware = this.cachedDynamicMiddlewares.get(cacheKey);
         if (cachedMiddleware)
             return cachedMiddleware;
+        /** Generating the middleware handler */
         const handler = await middleware.handler.apply(middleware.instance, [metadata]);
         this.cachedDynamicMiddlewares.set(cacheKey, handler);
         return handler;
@@ -200,6 +213,7 @@ let FastifyRouter = class FastifyRouter extends Router {
             routeOptions.url = metadata.path;
             routeOptions.method = metadata.method === HttpMethod.ALL ? httpMethods : [metadata.method];
             routeOptions.handler = this.generateRouteHandler(route);
+            /** Applying middlewares */
             for (const middleware of middlewares) {
                 const name = middleware.metatype.name;
                 const { type } = middleware.metadata;
@@ -260,6 +274,11 @@ let FastifyRouter = class FastifyRouter extends Router {
         await this.instance.close();
         this.logger.info('server stopped');
     }
+    /**
+     * Creates a new child context derived from the current one to load route-specific data
+     * during SSR. Automatically reuses middleware results from the parent context to avoid
+     * redundant execution and ensures correct context isolation for nested route data fetching.
+     */
     async resolveChildRoute(url) {
         if (!this.childRouter)
             throw new InternalError('Child routes are not enabled');

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

@@ -1,5 +1,11 @@
 import { Class } from 'type-fest';
 import { FastifyModuleAsyncOptions, FastifyModuleOptions } from './fastify-module.interface.js';
+/**
+ * Defining types
+ */
+/**
+ * Declaring the constants
+ */
 export declare class FastifyModule {
     private static getDefaultConfig;
     static forRoot(options: FastifyModuleOptions): Class<FastifyModule>;

package/esm/module/fastify.module.js

@@ -1,13 +1,25 @@
+/**
+ * Importing npm packages
+ */
 import { Module, Router } from '@shadow-library/app';
 import { ClassSchema } from '@shadow-library/class-schema';
 import { Config, utils } from '@shadow-library/common';
 import { v4 as uuid } from 'uuid';
+/**
+ * Importing user defined packages
+ */
 import { DefaultErrorHandler } from '../classes/index.js';
 import { FASTIFY_CONFIG, FASTIFY_INSTANCE } from '../constants.js';
 import { ContextService } from '../services/index.js';
 import { ErrorResponseDto } from './error-response.dto.js';
 import { FastifyRouter } from './fastify-router.js';
 import { createFastifyInstance } from './fastify.utils.js';
+/**
+ * Defining types
+ */
+/**
+ * Declaring the constants
+ */
 export class FastifyModule {
     static getDefaultConfig() {
         const errorResponseSchema = ClassSchema.generate(ErrorResponseDto);

package/esm/module/fastify.utils.js

@@ -1,8 +1,20 @@
+/**
+ * Importing npm packages
+ */
 import assert from 'node:assert';
 import { ValidationError, throwError, utils } from '@shadow-library/common';
 import Ajv from 'ajv';
 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 });
@@ -29,12 +41,13 @@ export function compileValidator(routeSchema) {
     return (data) => {
         validate(data);
         for (const error of validate.errors ?? []) {
+            /** Since this schema is for querystring there won't be any nested objects so we are directly accessing the path */
             const path = error.instancePath.substring(1);
             const defaultValue = routeSchema.schema.properties?.[path]?.default;
             if (defaultValue !== undefined)
                 data[path] = defaultValue;
             else
-                delete data[path];
+                delete data[path]; // eslint-disable-line @typescript-eslint/no-dynamic-delete
         }
         return { value: data };
     };

package/esm/server.error.d.ts

@@ -1,3 +1,6 @@
+/**
+ * Importing npm packages
+ */
 import { AppError, ErrorCode, ErrorType } from '@shadow-library/common';
 export declare class ServerError extends AppError<ServerErrorCode> {
     getStatusCode(): number;
@@ -6,13 +9,25 @@ export declare class ServerErrorCode extends ErrorCode {
     private readonly statusCode;
     protected constructor(code: string, type: ErrorType, msg: string, statusCode?: number);
     getStatusCode(): number;
+    /*!
+     * List of all server related errors
+     */
+    /** An unexpected server error occurred while processing the request */
     static readonly S001: ServerErrorCode;
+    /** The requested endpoint does not exist */
     static readonly S002: ServerErrorCode;
+    /** The provided input data is invalid or does not meet validation requirements */
     static readonly S003: ServerErrorCode;
+    /** Authentication credentials are required to access this resource */
     static readonly S004: ServerErrorCode;
+    /** Access denied due to insufficient permissions to perform this operation */
     static readonly S005: ServerErrorCode;
+    /** The request is malformed or contains invalid parameters */
     static readonly S006: ServerErrorCode;
+    /** Rate limit exceeded due to too many requests sent in a given time frame */
     static readonly S007: ServerErrorCode;
+    /** Resource conflict as the requested operation conflicts with existing data */
     static readonly S008: ServerErrorCode;
+    /** The requested resource could not be found */
     static readonly S009: ServerErrorCode;
 }

package/esm/server.error.js

@@ -1,4 +1,16 @@
+/**
+ * Importing npm packages
+ */
 import { AppError, ErrorCode, ErrorType } from '@shadow-library/common';
+/**
+ * Importing user defined packages
+ */
+/**
+ * Defining types
+ */
+/**
+ * Declaring the constants
+ */
 const ERROR_STATUS_CODES = {
     [ErrorType.CLIENT_ERROR]: 400,
     [ErrorType.HTTP_ERROR]: 400,
@@ -23,13 +35,25 @@ export class ServerErrorCode extends ErrorCode {
     getStatusCode() {
         return this.statusCode;
     }
+    /*!
+     * List of all server related errors
+     */
+    /** An unexpected server error occurred while processing the request */
     static S001 = new ServerErrorCode('S001', ErrorType.SERVER_ERROR, 'An unexpected server error occurred while processing the request');
+    /** The requested endpoint does not exist */
     static S002 = new ServerErrorCode('S002', ErrorType.NOT_FOUND, 'The requested endpoint does not exist');
+    /** The provided input data is invalid or does not meet validation requirements */
     static S003 = new ServerErrorCode('S003', ErrorType.VALIDATION_ERROR, 'The provided input data is invalid or does not meet validation requirements');
+    /** Authentication credentials are required to access this resource */
     static S004 = new ServerErrorCode('S004', ErrorType.UNAUTHENTICATED, 'Authentication credentials are required to access this resource');
+    /** Access denied due to insufficient permissions to perform this operation */
     static S005 = new ServerErrorCode('S005', ErrorType.UNAUTHORIZED, 'Access denied due to insufficient permissions to perform this operation');
+    /** The request is malformed or contains invalid parameters */
     static S006 = new ServerErrorCode('S006', ErrorType.CLIENT_ERROR, 'The request is malformed or contains invalid parameters');
+    /** Rate limit exceeded due to too many requests sent in a given time frame */
     static S007 = new ServerErrorCode('S007', ErrorType.CLIENT_ERROR, 'Rate limit exceeded due to too many requests sent in a given time frame', 429);
+    /** Resource conflict as the requested operation conflicts with existing data */
     static S008 = new ServerErrorCode('S008', ErrorType.CONFLICT, 'Resource conflict as the requested operation conflicts with existing data');
+    /** The requested resource could not be found */
     static S009 = new ServerErrorCode('S009', ErrorType.NOT_FOUND, 'The requested resource could not be found');
 }

package/esm/services/context.service.d.ts

@@ -1,7 +1,15 @@
 import { onRequestHookHandler } from 'fastify';
+/**
+ * Importing user defined packages
+ */
 import { HttpRequest, HttpResponse } from '../interfaces/index.js';
+/**
+ * Defining types
+ */
 type Key = string | symbol;
-export declare class ContextService {
+export interface ContextExtension {
+}
+export declare class ContextService implements ContextExtension {
     static readonly name = "ContextService";
     private readonly storage;
     init(): onRequestHookHandler;
@@ -21,5 +29,6 @@ export declare class ContextService {
     getResponse(throwOnMissing: false): HttpResponse | null;
     getRID(): string;
     getRID(throwOnMissing: false): string | null;
+    extend<T extends ContextExtension = ContextExtension>(extension: T & ThisType<this & T>): this;
 }
 export {};

package/esm/services/context.service.js

@@ -4,9 +4,15 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
+/**
+ * Importing npm packages
+ */
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { Injectable } from '@shadow-library/app';
 import { InternalError } from '@shadow-library/common';
+/**
+ * Declaring the constants
+ */
 const REQUEST = Symbol('request');
 const RESPONSE = Symbol('response');
 const RID = Symbol('rid');
@@ -89,6 +95,9 @@ let ContextService = class ContextService {
     getRID(throwOnMissing = true) {
         return this.get(RID, throwOnMissing);
     }
+    extend(extension) {
+        return Object.assign(this, extension);
+    }
 };
 ContextService = __decorate([
     Injectable()

package/package.json

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