@shadow-library/fastify 0.0.9 → 0.0.11

package/README.md

@@ -695,6 +695,64 @@ export class DataController {
 }
 ```
 
+### Extending Context Service
+
+The `ContextService` can be extended with custom methods to add application-specific functionality while maintaining type safety and method chaining capabilities.
+
+```typescript
+import { contextService } from '@shadow-library/fastify';
+
+declare module '@shadow-library/fastify' {
+  export interface ContextExtension {
+    setUserRole(role: string): ContextService;
+    getUserRole(): string;
+    setCurrentUserId(userId: string): ContextService;
+    getCurrentUserId(): string;
+  }
+}
+
+// Extend the context service with custom methods
+contextService.extend({
+  setUserRole(role: string) {
+    return this.set('user-role', role);
+  },
+  getUserRole() {
+    return this.get<string>('user-role', false);
+  },
+  setCurrentUserId(userId: string) {
+    return this.set('current-user-id', userId);
+  },
+  getCurrentUserId() {
+    return this.get<string>('current-user-id', false);
+  },
+});
+
+// Use in controllers with method chaining
+@HttpController('/api')
+export class UserController {
+  constructor(private readonly contextService: ContextService) {}
+
+  @Post('/login')
+  async login(@Body() loginDto: LoginDto) {
+    const user = await this.authService.validateUser(loginDto);
+
+    // Chain extended methods
+    this.contextService.setCurrentUserId(user.id).setUserRole(user.role);
+
+    return { message: 'Login successful' };
+  }
+
+  @Get('/profile')
+  getProfile() {
+    return {
+      userId: this.contextService.getCurrentUserId(),
+      role: this.contextService.getUserRole(),
+      requestId: this.contextService.getRID(),
+    };
+  }
+}
+```
+
 ## Examples
 
 Check out the [examples](./examples) directory for complete working examples:

package/cjs/classes/default-error-handler.d.ts

@@ -1,6 +1,12 @@
+/**
+ * Importing npm packages
+ */
 import { AppErrorObject } from '@shadow-library/common';
 import { FastifyError } from 'fastify';
 import { ErrorHandler, HttpRequest, HttpResponse } from '../interfaces/index.js';
+/**
+ * Defining types
+ */
 export interface ParsedFastifyError {
     statusCode: number;
     error: AppErrorObject;

package/cjs/classes/default-error-handler.js

@@ -1,9 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DefaultErrorHandler = void 0;
+/**
+ * Importing npm packages
+ */
 const common_1 = require("@shadow-library/common");
+/**
+ * Importing user defined packages
+ */
 const constants_1 = require("../constants.js");
 const server_error_1 = require("../server.error.js");
+/**
+ * Declaring the constants
+ */
 const unexpectedError = new server_error_1.ServerError(server_error_1.ServerErrorCode.S001);
 const validationError = new server_error_1.ServerError(server_error_1.ServerErrorCode.S003);
 const invalidRequestError = new server_error_1.ServerError(server_error_1.ServerErrorCode.S006);

package/cjs/constants.d.ts

@@ -1,3 +1,15 @@
+/**
+ * Importing npm packages
+ */
+/**
+ * Importing user defined packages
+ */
+/**
+ * Defining types
+ */
+/**
+ * Declaring the constants
+ */
 export declare const NAMESPACE = "@shadow-library/fastify";
 export declare const PARAMTYPES_METADATA = "design:paramtypes";
 export declare const FASTIFY_CONFIG: unique symbol;

package/cjs/constants.js

@@ -1,6 +1,18 @@
 "use strict";
+/**
+ * Importing npm packages
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HTTP_CONTROLLER_INPUTS = exports.HTTP_CONTROLLER_TYPE = exports.FASTIFY_INSTANCE = exports.FASTIFY_CONFIG = exports.PARAMTYPES_METADATA = exports.NAMESPACE = void 0;
+/**
+ * Importing user defined packages
+ */
+/**
+ * Defining types
+ */
+/**
+ * Declaring the constants
+ */
 exports.NAMESPACE = '@shadow-library/fastify';
 exports.PARAMTYPES_METADATA = 'design:paramtypes';
 exports.FASTIFY_CONFIG = Symbol('fastify-config');

package/cjs/decorators/http-controller.decorator.d.ts

@@ -1 +1,7 @@
+/**
+ * Defining types
+ */
+/**
+ * Declaring the constants
+ */
 export declare function HttpController(path?: string): ClassDecorator;

package/cjs/decorators/http-controller.decorator.js

@@ -1,8 +1,20 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HttpController = HttpController;
+/**
+ * Importing npm packages
+ */
 const app_1 = require("@shadow-library/app");
+/**
+ * Importing user defined packages
+ */
 const constants_1 = require("../constants.js");
+/**
+ * Defining types
+ */
+/**
+ * Declaring the constants
+ */
 function HttpController(path = '') {
     if (path.charAt(0) !== '/')
         path = `/${path}`;

package/cjs/decorators/http-input.decorator.d.ts

@@ -1,5 +1,8 @@
 import { JSONSchema } from '@shadow-library/class-schema';
 import { Class } from 'type-fest';
+/**
+ * Defining types
+ */
 export declare enum RouteInputType {
     BODY = "body",
     PARAMS = "params",
@@ -8,6 +11,9 @@ export declare enum RouteInputType {
     RESPONSE = "response"
 }
 export type RouteInputSchemas = Partial<Record<'body' | 'params' | 'query', JSONSchema | Class<unknown>>>;
+/**
+ * Declaring the constants
+ */
 export declare function HttpInput(type: RouteInputType, schema?: JSONSchema): ParameterDecorator;
 export declare const Body: (schema?: JSONSchema) => ParameterDecorator;
 export declare const Params: (schema?: JSONSchema) => ParameterDecorator;

package/cjs/decorators/http-input.decorator.js

@@ -5,9 +5,18 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Res = exports.Response = exports.Req = exports.Request = exports.Query = exports.Params = exports.Body = exports.RouteInputType = void 0;
 exports.HttpInput = HttpInput;
+/**
+ * Importing npm packages
+ */
 const node_assert_1 = __importDefault(require("node:assert"));
 const app_1 = require("@shadow-library/app");
+/**
+ * Importing user defined packages
+ */
 const constants_1 = require("../constants.js");
+/**
+ * Defining types
+ */
 var RouteInputType;
 (function (RouteInputType) {
     RouteInputType["BODY"] = "body";
@@ -16,6 +25,9 @@ var RouteInputType;
     RouteInputType["REQUEST"] = "request";
     RouteInputType["RESPONSE"] = "response";
 })(RouteInputType || (exports.RouteInputType = RouteInputType = {}));
+/**
+ * Declaring the constants
+ */
 function HttpInput(type, schema) {
     return (target, propertyKey, index) => {
         (0, node_assert_1.default)(propertyKey, 'Cannot apply decorator to a constructor parameter');

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

@@ -1,5 +1,14 @@
+/**
+ * Importing npm packages
+ */
 import { JSONSchema, SchemaClass } from '@shadow-library/class-schema';
 import { JsonObject } from 'type-fest';
+/**
+ * Importing user defined packages
+ */
+/**
+ * Defining types
+ */
 export interface DynamicRender<T extends JsonObject> {
     template: string;
     data: T;

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

@@ -1,9 +1,15 @@
 "use strict";
+/**
+ * Importing npm packages
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Render = exports.Redirect = exports.Header = exports.HttpStatus = void 0;
 exports.RespondFor = RespondFor;
 const app_1 = require("@shadow-library/app");
 const class_schema_1 = require("@shadow-library/class-schema");
+/**
+ * Declaring the constants
+ */
 const isClass = (schema) => schema.toString().startsWith('class ');
 const HttpStatus = (status) => (0, app_1.Route)({ status });
 exports.HttpStatus = HttpStatus;

package/cjs/decorators/http-route.decorator.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Importing user defined packages
+ */
+/**
+ * Defining types
+ */
 export declare enum HttpMethod {
     GET = "GET",
     POST = "POST",
@@ -12,6 +18,9 @@ export interface RouteOptions {
     method: HttpMethod;
     path?: string;
 }
+/**
+ * Declaring the constants
+ */
 export declare function HttpRoute(options: RouteOptions): MethodDecorator;
 export declare const Get: (path?: string) => MethodDecorator;
 export declare const Post: (path?: string) => MethodDecorator;

package/cjs/decorators/http-route.decorator.js

@@ -2,7 +2,16 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.All = exports.Head = exports.Options = exports.Patch = exports.Delete = exports.Put = exports.Post = exports.Get = exports.HttpMethod = void 0;
 exports.HttpRoute = HttpRoute;
+/**
+ * Importing npm packages
+ */
 const app_1 = require("@shadow-library/app");
+/**
+ * Importing user defined packages
+ */
+/**
+ * Defining types
+ */
 var HttpMethod;
 (function (HttpMethod) {
     HttpMethod["GET"] = "GET";
@@ -14,6 +23,9 @@ var HttpMethod;
     HttpMethod["HEAD"] = "HEAD";
     HttpMethod["ALL"] = "ALL";
 })(HttpMethod || (exports.HttpMethod = HttpMethod = {}));
+/**
+ * Declaring the constants
+ */
 function HttpRoute(options) {
     if (options.path && options.path.charAt(0) !== '/')
         options.path = `/${options.path}`;

package/cjs/decorators/middleware.decorator.d.ts

@@ -1,7 +1,18 @@
+/**
+ * Importing user defined packages
+ */
 import { HTTP_CONTROLLER_TYPE } from '../constants.js';
+/**
+ * Defining types
+ */
 export type MiddlewareType = 'onRequest' | 'preParsing' | 'preValidation' | 'preHandler' | 'preSerialization' | 'onSend' | 'onResponse' | 'onError';
 export interface MiddlewareOptions {
+    /**
+     * Denotes when to execute the middleware. default value is `preHandler`.
+     * see https://fastify.dev/docs/latest/Reference/Lifecycle for more information
+     */
     type: MiddlewareType;
+    /** Denotes the execution order, the higher value gets executed first */
     weight: number;
 }
 export interface MiddlewareMetadata extends MiddlewareOptions {

package/cjs/decorators/middleware.decorator.js

@@ -4,9 +4,18 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Middleware = Middleware;
+/**
+ * Importing npm packages
+ */
 const node_assert_1 = __importDefault(require("node:assert"));
 const app_1 = require("@shadow-library/app");
+/**
+ * Importing user defined packages
+ */
 const constants_1 = require("../constants.js");
+/**
+ * Declaring the constants
+ */
 const propertyKeys = ['generate', 'use'];
 function Middleware(options = {}) {
     if (!options.type)

package/cjs/decorators/sensitive.decorator.d.ts

@@ -1,4 +1,13 @@
 import { MaskOptions } from '@shadow-library/common';
+/**
+ * Importing user defined packages
+ */
+/**
+ * Defining types
+ */
 export type SensitiveDataType = 'secret' | 'email' | 'number' | 'words';
+/**
+ * Declaring the constants
+ */
 export declare function Sensitive(type?: SensitiveDataType): PropertyDecorator;
 export declare function Sensitive(maskOptions: MaskOptions): PropertyDecorator;

package/cjs/decorators/sensitive.decorator.js

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Sensitive = Sensitive;
+/**
+ * Importing npm packages
+ */
 const class_schema_1 = require("@shadow-library/class-schema");
 function Sensitive(typeOrMaskOptions = 'secret') {
     return (target, propertyKey) => {

package/cjs/index.d.ts

@@ -1,4 +1,10 @@
+/**
+ * Importing npm packages
+ */
 import 'reflect-metadata';
+/**
+ * exporting modules
+ */
 export * from './classes/index.js';
 export * from './decorators/index.js';
 export * from './interfaces/index.js';

package/cjs/index.js

@@ -14,7 +14,13 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Importing npm packages
+ */
 require("reflect-metadata");
+/**
+ * exporting modules
+ */
 __exportStar(require("./classes/index.js"), exports);
 __exportStar(require("./decorators/index.js"), exports);
 __exportStar(require("./interfaces/index.js"), exports);

package/cjs/interfaces/error-handler.interface.d.ts

@@ -1,4 +1,16 @@
+/**
+ * Importing npm packages
+ */
+/**
+ * Importing user defined packages
+ */
 import { HttpRequest, HttpResponse } from './route-handler.interface.js';
+/**
+ * Defining types
+ */
+/**
+ * Declaring the constants
+ */
 export interface ErrorHandler {
     handle(err: Error, req: HttpRequest, res: HttpResponse): any | Promise<any>;
 }

package/cjs/interfaces/error-handler.interface.js

@@ -1,2 +1,5 @@
 "use strict";
+/**
+ * Importing npm packages
+ */
 Object.defineProperty(exports, "__esModule", { value: true });

package/cjs/interfaces/middleware.interface.d.ts

@@ -1,5 +1,14 @@
+/**
+ * Importing npm packages
+ */
 import { RouteMetadata } from '@shadow-library/app';
+/**
+ * Importing user defined packages
+ */
 import { HttpCallback, HttpRequest, HttpResponse, RouteHandler } from './route-handler.interface.js';
+/**
+ * Defining types
+ */
 export interface MiddlewareGenerator {
     cacheKey?: (metadata: RouteMetadata) => string;
     generate(metadata: RouteMetadata): RouteHandler | undefined | Promise<RouteHandler | undefined>;

package/cjs/interfaces/route-handler.interface.d.ts

@@ -1,5 +1,17 @@
+/**
+ * Importing npm packages
+ */
 import { SyncValue } from '@shadow-library/common';
 import { DoneFuncWithErrOrRes, FastifyReply, FastifyRequest } from 'fastify';
+/**
+ * Importing user defined packages
+ */
+/**
+ * Defining types
+ */
+/**
+ * Declaring the constants
+ */
 export type HttpRequest = FastifyRequest;
 export type HttpResponse = FastifyReply;
 export type HttpCallback = DoneFuncWithErrOrRes;

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

@@ -1,8 +1,17 @@
+/**
+ * Importing npm packages
+ */
 import { RouteMetadata } from '@shadow-library/app';
 import { JSONSchema } from '@shadow-library/class-schema';
 import { RouteShorthandOptions } from 'fastify';
+/**
+ * Importing user defined packages
+ */
 import { HTTP_CONTROLLER_TYPE } from '../constants.js';
 import { HttpMethod, RouteInputSchemas } from '../decorators/index.js';
+/**
+ * Defining types
+ */
 declare module '@shadow-library/app' {
     interface RouteMetadata extends Omit<RouteShorthandOptions, 'config'> {
         method?: HttpMethod;

package/cjs/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/cjs/module/error-response.dto.js

@@ -10,7 +10,19 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ErrorResponseDto = exports.ErrorFieldDto = void 0;
+/**
+ * Importing npm packages
+ */
 const class_schema_1 = require("@shadow-library/class-schema");
+/**
+ * Importing user defined packages
+ */
+/**
+ * Defining types
+ */
+/**
+ * Declaring the constants
+ */
 let ErrorFieldDto = class ErrorFieldDto {
     field;
     msg;

package/cjs/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/cjs/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>;