@shadow-library/fastify 1.0.1 → 1.2.0

package/README.md

@@ -14,6 +14,7 @@ A powerful TypeScript-first Fastify wrapper featuring decorator-based routing, a
 - 📊 **Type Safety**: Full TypeScript support with schema generation
 - 🎨 **Templating Ready**: Built-in support for templating engines
 - ⚡ **Dynamic Module**: Configurable module with `forRoot()` and `forRootAsync()` methods
+- 🔢 **API Versioning**: Built-in support for prefix-based API versioning
 
 ## Installation
 
@@ -129,6 +130,7 @@ bootstrap();
 @Delete(path?: string)     // DELETE requests
 @Options(path?: string)    // OPTIONS requests
 @Head(path?: string)       // HEAD requests
+@Version(version: number)  // Set API version for the route
 ```
 
 #### Parameter Decorators
@@ -183,6 +185,205 @@ export class ProtectedController {
 }
 ```
 
+### API Versioning
+
+The framework provides a powerful versioning system that allows you to version your APIs using URL path prefixes. This is useful for maintaining multiple versions of your API simultaneously.
+
+#### Enabling Versioning
+
+To enable versioning, set `prefixVersioning: true` in your module configuration:
+
+```typescript
+@Module({
+  imports: [
+    FastifyModule.forRoot({
+      controllers: [UserController],
+      port: 3000,
+
+      // Enable prefix-based versioning
+      prefixVersioning: true,
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+#### Using the @Version Decorator
+
+Use the `@Version` decorator on your controllers to specify the API version:
+
+```typescript
+import { HttpController, Get, Post, Version, Body } from '@shadow-library/fastify';
+
+@HttpController('/api/users')
+@Version(1)
+export class UserV1Controller {
+  @Get()
+  async getUsers() {
+    return [{ id: 1, name: 'John Doe' }];
+  }
+}
+
+@HttpController('/api/users')
+@Version(2)
+export class UserV2Controller {
+  @Get()
+  async getUsers() {
+    // v2 with additional fields
+    return [{ id: 1, name: 'John Doe', email: 'john@example.com', createdAt: new Date() }];
+  }
+
+  @Post()
+  async createUser(@Body() userData: CreateUserDto) {
+    // New features in v2
+    return { id: 2, ...userData };
+  }
+}
+```
+
+**Result**:
+
+- v1 endpoints: `GET /v1/api/users`
+- v2 endpoints: `GET /v2/api/users`, `POST /v2/api/users`
+
+#### Default Version
+
+If versioning is enabled but no `@Version` decorator is specified, routes default to `v1`:
+
+```typescript
+@HttpController('/api/products')
+export class ProductController {
+  @Get()
+  async getProducts() {
+    return [];
+  }
+}
+// Results in: GET /v1/api/products
+```
+
+#### Method-Level Versioning
+
+You can also apply versioning at the method level for more granular control:
+
+```typescript
+@HttpController('/api/data')
+export class DataController {
+  @Get('/stats')
+  @Version(1)
+  async getStatsV1() {
+    return { totalUsers: 100 };
+  }
+
+  @Get('/stats')
+  @Version(2)
+  async getStatsV2() {
+    return { totalUsers: 100, activeUsers: 75, newUsers: 10 };
+  }
+
+  @Get('/info')
+  async getInfo() {
+    // This defaults to v1 when versioning is enabled
+    return { version: 'v1' };
+  }
+}
+```
+
+**Result**:
+
+- `GET /v1/api/data/stats` → `getStatsV1()`
+- `GET /v2/api/data/stats` → `getStatsV2()`
+- `GET /v1/api/data/info` → `getInfo()`
+
+#### Versioning Best Practices
+
+1. **Maintain Backward Compatibility**: Keep older versions running while you migrate clients to newer versions
+2. **Version Breaking Changes**: Only increment versions for breaking changes in your API
+3. **Document Version Differences**: Clearly document what changes between versions
+4. **Deprecation Strategy**: Communicate deprecation timelines for older API versions
+5. **Consistent Versioning**: Use consistent version numbers across related endpoints
+
+#### Example: Complete Versioned API
+
+```typescript
+import { Module } from '@shadow-library/app';
+import { FastifyModule, HttpController, Get, Post, Version } from '@shadow-library/fastify';
+
+// Version 1 Controllers
+@HttpController('/api/users')
+@Version(1)
+class UserV1Controller {
+  @Get()
+  async list() {
+    return [{ id: 1, name: 'John' }];
+  }
+}
+
+@HttpController('/api/posts')
+@Version(1)
+class PostV1Controller {
+  @Get()
+  async list() {
+    return [{ id: 1, title: 'Hello' }];
+  }
+}
+
+// Version 2 Controllers - with enhanced features
+@HttpController('/api/users')
+@Version(2)
+class UserV2Controller {
+  @Get()
+  async list() {
+    return [{ id: 1, name: 'John', email: 'john@example.com', role: 'admin' }];
+  }
+
+  @Post('/bulk')
+  async bulkCreate(@Body() users: CreateUserDto[]) {
+    // New feature in v2
+    return { created: users.length };
+  }
+}
+
+@HttpController('/api/posts')
+@Version(2)
+class PostV2Controller {
+  @Get()
+  async list() {
+    return [{ id: 1, title: 'Hello', content: 'World', tags: ['news'] }];
+  }
+}
+
+@Module({
+  imports: [
+    FastifyModule.forRoot({
+      controllers: [UserV1Controller, UserV2Controller, PostV1Controller, PostV2Controller],
+      prefixVersioning: true,
+      port: 3000,
+    }),
+  ],
+})
+export class AppModule {}
+
+// Available endpoints:
+// GET  /v1/api/users
+// GET  /v1/api/posts
+// GET  /v2/api/users
+// POST /v2/api/users/bulk  (new in v2)
+// GET  /v2/api/posts
+```
+
+#### Disabling Versioning
+
+If you don't need versioning, simply omit the `prefixVersioning` option or set it to `false`:
+
+```typescript
+FastifyModule.forRoot({
+  controllers: [UserController],
+  prefixVersioning: false, // or omit entirely
+  port: 3000,
+});
+// Routes will be: GET /api/users (no version prefix)
+```
+
 ### Error Handling
 
 ```typescript
@@ -223,6 +424,89 @@ export class RoutesController {
 }
 ```
 
+#### Child Routes Configuration
+
+Child routes enable server-side route resolution, commonly used for SSR (Server-Side Rendering) and internal API composition. When enabled, you can make internal HTTP requests to your own routes without going through the network layer.
+
+**Basic Setup:**
+
+```typescript
+@Module({
+  imports: [
+    FastifyModule.forRoot({
+      controllers: [UserController, DataController],
+
+      // Enable child routes functionality
+      enableChildRoutes: true,
+
+      // Optional: Provide custom headers for child route requests
+      childRouteHeaders: () => ({
+        'x-correlation-id': '123',
+      }),
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+**Usage in Controllers:**
+
+```typescript
+@HttpController('/api')
+export class DataAggregatorController {
+  constructor(@Inject(Router) private readonly fastifyRouter: FastifyRouter) {}
+
+  @Get('/dashboard')
+  async getDashboardData() {
+    // Make internal requests to other routes
+    const [users, posts, analytics] = await Promise.all([
+      this.fastifyRouter.resolveChildRoute('/api/users'),
+      this.fastifyRouter.resolveChildRoute('/api/posts?limit=10'),
+      this.fastifyRouter.resolveChildRoute('/api/analytics/summary'),
+    ]);
+
+    return {
+      dashboard: {
+        users,
+        posts,
+        analytics,
+        timestamp: new Date().toISOString(),
+      },
+    };
+  }
+}
+```
+
+**Custom Headers Function:**
+
+The `childRouteHeaders` function is called for each child route request, allowing you to:
+
+- Pass authentication context from the parent request
+- Include tenant/user-specific information
+- Add tracing or correlation IDs
+- Set internal service flags
+
+```typescript
+// Dynamic headers based on current request context
+childRouteHeaders: (contextService) => {
+  const request = contextService.getRequest();
+  return {
+    'x-user-id': contextService.get('currentUserId'),
+    'x-request-id': contextService.getRID(),
+    'x-forwarded-from': 'internal-aggregator',
+    'x-correlation-id': request.headers['x-correlation-id'],
+  };
+},
+```
+
+**Important Notes:**
+
+- Child routes always include the header `x-service: 'internal-child-route'`
+- Custom headers are merged with the default service header
+- If you provide an `x-service` header, it will be overridden with the default value
+- Child routes create isolated contexts, preventing middleware conflicts
+- Enable only when needed, as it adds routing overhead
+
 ## Configuration
 
 ### Dynamic Module Configuration
@@ -253,6 +537,9 @@ The module provides two configuration methods:
       // Security
       maskSensitiveData: true,
 
+      // API Versioning
+      prefixVersioning: true,
+
       // Request ID generation
       requestIdLogLabel: 'rid',
       genReqId: () => uuid(),
@@ -269,6 +556,12 @@ The module provides two configuration methods:
         '5xx': ErrorResponseSchema,
       },
 
+      // Child routes configuration (for SSR and internal route resolution)
+      enableChildRoutes: true,
+      childRouteHeaders: contextService => ({
+        'x-correlation-id': contextService.getRequest().headers['x-correlation-id'],
+      }),
+
       // Extend Fastify instance before registering controllers
       fastifyFactory: async fastify => {
         // Register plugins, add hooks, or configure Fastify
@@ -800,7 +1093,7 @@ Check out the [examples](./examples) directory for complete working examples:
 
 - **hello-world**: Basic HTTP controller with GET/POST routes
 - **user-auth**: Advanced example with authentication guards
-- **child-routes**: Route resolution and unified endpoints
+- **child-routes**: Route resolution, unified endpoints, and custom headers for SSR
 
 ## Contributing
 

package/cjs/decorators/index.d.ts

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

package/cjs/decorators/index.js

@@ -20,3 +20,4 @@ __exportStar(require("./http-output.decorator.js"), exports);
 __exportStar(require("./http-route.decorator.js"), exports);
 __exportStar(require("./middleware.decorator.js"), exports);
 __exportStar(require("./sensitive.decorator.js"), exports);
+__exportStar(require("./version.decorator.js"), exports);

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

@@ -0,0 +1,11 @@
+import { Integer } from 'type-fest';
+/**
+ * Importing user defined packages
+ */
+/**
+ * Defining types
+ */
+/**
+ * Declaring the constants
+ */
+export declare function Version<T extends number>(version: Integer<T>): ClassDecorator & MethodDecorator;

package/cjs/decorators/version.decorator.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Version = Version;
+/**
+ * Importing npm packages
+ */
+const app_1 = require("@shadow-library/app");
+/**
+ * Importing user defined packages
+ */
+/**
+ * Defining types
+ */
+/**
+ * Declaring the constants
+ */
+function Version(version) {
+    return (0, app_1.Route)({ version });
+}

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

@@ -16,6 +16,7 @@ declare module '@shadow-library/app' {
     interface RouteMetadata extends Omit<RouteShorthandOptions, 'config'> {
         method?: HttpMethod;
         path?: string;
+        version?: number;
         schemas?: RouteInputSchemas & {
             response?: Record<number | string, JSONSchema>;
         };

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

@@ -9,6 +9,7 @@ import { Promisable } from 'type-fest';
  * Importing user defined packages
  */
 import { ErrorHandler } from '../interfaces/index.js';
+import { ContextService } from '../services/index.js';
 /**
  * Defining types
  */
@@ -39,11 +40,21 @@ export interface FastifyConfig extends FastifyServerOptions {
      * @default false
      */
     enableChildRoutes?: boolean;
+    /**
+     * Function to provide custom headers for internal child route requests.
+     * Useful for passing authentication tokens or other necessary headers.
+     */
+    childRouteHeaders?: (contextService: ContextService) => Record<string, string>;
     /**
      * Masks fields marked as sensitive in API inputs (body, query, and URL params) when written to logs.
      * @default true
      */
     maskSensitiveData?: boolean;
+    /**
+     * Enables prefix-based versioning for all routes in the Fastify instance.
+     * @default false
+     */
+    prefixVersioning?: boolean;
 }
 export interface FastifyModuleOptions extends Partial<FastifyConfig> {
     /**

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

@@ -82,7 +82,7 @@ export declare class FastifyRouter extends Router {
      * 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>;
+    resolveChildRoute<T extends JsonValue = JsonObject>(url: string, headers?: Record<string, string>): Promise<T>;
     mockRequest(): MockRequestChain;
     mockRequest(options: MockRequestOptions): Promise<MockResponse>;
 }

package/cjs/module/fastify-router.js

@@ -119,8 +119,14 @@ let FastifyRouter = class FastifyRouter extends app_1.Router {
                     const { instance, metadata, metatype } = controller;
                     const basePath = metadata.path ?? '/';
                     for (const route of controller.routes) {
+                        /** Prepare path with versioning if enabled */
                         const routePath = route.metadata.path ?? '';
-                        const path = basePath + routePath;
+                        let path = basePath + routePath;
+                        if (this.config.prefixVersioning) {
+                            const version = route.metadata.version ?? 1;
+                            const connector = path.startsWith('/') ? '' : '/';
+                            path = '/v' + version + connector + path;
+                        }
                         const parsedController = { ...route, instance, metatype };
                         parsedController.metadata.path = path;
                         parsedControllers.routes.push(parsedController);
@@ -285,10 +291,12 @@ let FastifyRouter = class FastifyRouter extends app_1.Router {
      * 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) {
+    async resolveChildRoute(url, headers = {}) {
         if (!this.childRouter)
             throw new common_1.InternalError('Child routes are not enabled');
-        const response = await this.instance.inject({ method: 'GET', url, headers: { 'x-service': 'internal-child-route' } });
+        const childHeaders = this.config.childRouteHeaders?.(this.context) ?? {};
+        Object.assign(headers, childHeaders, { 'x-service': 'internal-child-route' });
+        const response = await this.instance.inject({ method: 'GET', url, headers });
         return response.json();
     }
     mockRequest(options) {

package/esm/decorators/index.d.ts

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

package/esm/decorators/index.js

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

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

@@ -0,0 +1,11 @@
+import { Integer } from 'type-fest';
+/**
+ * Importing user defined packages
+ */
+/**
+ * Defining types
+ */
+/**
+ * Declaring the constants
+ */
+export declare function Version<T extends number>(version: Integer<T>): ClassDecorator & MethodDecorator;

package/esm/decorators/version.decorator.js

@@ -0,0 +1,16 @@
+/**
+ * Importing npm packages
+ */
+import { Route } from '@shadow-library/app';
+/**
+ * Importing user defined packages
+ */
+/**
+ * Defining types
+ */
+/**
+ * Declaring the constants
+ */
+export function Version(version) {
+    return Route({ version });
+}

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

@@ -16,6 +16,7 @@ declare module '@shadow-library/app' {
     interface RouteMetadata extends Omit<RouteShorthandOptions, 'config'> {
         method?: HttpMethod;
         path?: string;
+        version?: number;
         schemas?: RouteInputSchemas & {
             response?: Record<number | string, JSONSchema>;
         };

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

@@ -9,6 +9,7 @@ import { Promisable } from 'type-fest';
  * Importing user defined packages
  */
 import { ErrorHandler } from '../interfaces/index.js';
+import { ContextService } from '../services/index.js';
 /**
  * Defining types
  */
@@ -39,11 +40,21 @@ export interface FastifyConfig extends FastifyServerOptions {
      * @default false
      */
     enableChildRoutes?: boolean;
+    /**
+     * Function to provide custom headers for internal child route requests.
+     * Useful for passing authentication tokens or other necessary headers.
+     */
+    childRouteHeaders?: (contextService: ContextService) => Record<string, string>;
     /**
      * Masks fields marked as sensitive in API inputs (body, query, and URL params) when written to logs.
      * @default true
      */
     maskSensitiveData?: boolean;
+    /**
+     * Enables prefix-based versioning for all routes in the Fastify instance.
+     * @default false
+     */
+    prefixVersioning?: boolean;
 }
 export interface FastifyModuleOptions extends Partial<FastifyConfig> {
     /**

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

@@ -82,7 +82,7 @@ export declare class FastifyRouter extends Router {
      * 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>;
+    resolveChildRoute<T extends JsonValue = JsonObject>(url: string, headers?: Record<string, string>): Promise<T>;
     mockRequest(): MockRequestChain;
     mockRequest(options: MockRequestOptions): Promise<MockResponse>;
 }

package/esm/module/fastify-router.js

@@ -113,8 +113,14 @@ let FastifyRouter = class FastifyRouter extends Router {
                     const { instance, metadata, metatype } = controller;
                     const basePath = metadata.path ?? '/';
                     for (const route of controller.routes) {
+                        /** Prepare path with versioning if enabled */
                         const routePath = route.metadata.path ?? '';
-                        const path = basePath + routePath;
+                        let path = basePath + routePath;
+                        if (this.config.prefixVersioning) {
+                            const version = route.metadata.version ?? 1;
+                            const connector = path.startsWith('/') ? '' : '/';
+                            path = '/v' + version + connector + path;
+                        }
                         const parsedController = { ...route, instance, metatype };
                         parsedController.metadata.path = path;
                         parsedControllers.routes.push(parsedController);
@@ -279,10 +285,12 @@ let FastifyRouter = class FastifyRouter extends Router {
      * 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) {
+    async resolveChildRoute(url, headers = {}) {
         if (!this.childRouter)
             throw new InternalError('Child routes are not enabled');
-        const response = await this.instance.inject({ method: 'GET', url, headers: { 'x-service': 'internal-child-route' } });
+        const childHeaders = this.config.childRouteHeaders?.(this.context) ?? {};
+        Object.assign(headers, childHeaders, { 'x-service': 'internal-child-route' });
+        const response = await this.instance.inject({ method: 'GET', url, headers });
         return response.json();
     }
     mockRequest(options) {

package/package.json

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