@shadow-library/fastify 1.2.0 → 1.4.0

package/README.md

@@ -384,6 +384,160 @@ FastifyModule.forRoot({
 // Routes will be: GET /api/users (no version prefix)
 ```
 
+### Global Route Prefix
+
+The `routePrefix` configuration option allows you to add a global prefix to all routes in your application. This is useful for:
+
+- **API Namespacing**: Prefix all routes with `/api` to clearly distinguish API endpoints from other routes
+- **Multi-tenant Applications**: Add tenant-specific prefixes
+- **Microservices**: Namespace your service routes (e.g., `/user-service`, `/payment-service`)
+- **API Gateways**: Organize routes by domain or service boundaries
+
+#### Basic Usage
+
+```typescript
+@Module({
+  imports: [
+    FastifyModule.forRoot({
+      controllers: [UserController, ProductController],
+      routePrefix: 'api',
+      port: 3000,
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+**Example Controllers:**
+
+```typescript
+@HttpController('/users')
+export class UserController {
+  @Get()
+  async getUsers() {
+    return [];
+  }
+
+  @Get('/:id')
+  async getUser(@Params() params: { id: string }) {
+    return { id: params.id };
+  }
+}
+
+@HttpController('/products')
+export class ProductController {
+  @Get()
+  async getProducts() {
+    return [];
+  }
+}
+```
+
+**Result**:
+
+- `GET /api/users`
+- `GET /api/users/:id`
+- `GET /api/products`
+
+#### Combining with Versioning
+
+You can use `routePrefix` together with `prefixVersioning` for a well-organized API structure:
+
+```typescript
+@Module({
+  imports: [
+    FastifyModule.forRoot({
+      controllers: [UserV1Controller, UserV2Controller],
+      routePrefix: 'api',
+      prefixVersioning: true,
+      port: 3000,
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+**Result**:
+
+- `GET /api/v1/users`
+- `GET /api/v2/users`
+
+The order is always: `/{routePrefix}/{version}/{controller-path}/{route-path}`
+
+#### Multi-Service Example
+
+```typescript
+// User Service Module
+@Module({
+  imports: [
+    FastifyModule.forRoot({
+      controllers: [UserController, AuthController],
+      routePrefix: 'user-service',
+      port: 3001,
+    }),
+  ],
+})
+export class UserServiceModule {}
+
+// Payment Service Module
+@Module({
+  imports: [
+    FastifyModule.forRoot({
+      controllers: [PaymentController, InvoiceController],
+      routePrefix: 'payment-service',
+      port: 3002,
+    }),
+  ],
+})
+export class PaymentServiceModule {}
+```
+
+**Result**:
+
+- User Service: `POST /user-service/auth/login`, `GET /user-service/users`
+- Payment Service: `POST /payment-service/payments`, `GET /payment-service/invoices`
+
+#### Dynamic Route Prefix
+
+You can also set the prefix dynamically using `forRootAsync`:
+
+```typescript
+@Module({
+  imports: [
+    FastifyModule.forRootAsync({
+      useFactory: (configService: ConfigService) => ({
+        controllers: [UserController],
+        routePrefix: configService.get('API_PREFIX'), // e.g., 'api/v1'
+        port: configService.get('PORT'),
+      }),
+      inject: [ConfigService],
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+#### Best Practices
+
+1. **Use Consistent Prefixes**: Keep your route prefix consistent across your application
+2. **Avoid Deep Nesting**: Keep prefixes shallow for better readability (prefer `/api` over `/api/v1/public`)
+3. **Combine with Versioning**: Use `routePrefix` for namespace and `prefixVersioning` for versions
+4. **Document Your Routes**: Clearly document the prefix structure for API consumers
+5. **Environment-based Prefixes**: Consider different prefixes for different environments if needed
+
+#### Without Route Prefix
+
+If you don't need a global prefix, simply omit the `routePrefix` option:
+
+```typescript
+FastifyModule.forRoot({
+  controllers: [UserController],
+  // No routePrefix specified
+  port: 3000,
+});
+// Routes will be: GET /users (no prefix)
+```
+
 ### Error Handling
 
 ```typescript
@@ -537,6 +691,9 @@ The module provides two configuration methods:
       // Security
       maskSensitiveData: true,
 
+      // Global route prefix
+      routePrefix: 'api',
+
       // API Versioning
       prefixVersioning: true,
 
@@ -693,6 +850,55 @@ export class AppModule {}
 - **Database**: Add database connection decorators
 - **Caching**: Configure caching plugins
 
+### Customizing AJV Validation
+
+The module uses [AJV](https://ajv.js.org/) for JSON Schema validation. You can customize the AJV instance by providing custom options or plugins through the `ajv` configuration:
+
+```typescript
+import { Module } from '@shadow-library/app';
+import { FastifyModule } from '@shadow-library/fastify';
+import ajvFormats from 'ajv-formats';
+import ajvKeywords from 'ajv-keywords';
+
+@Module({
+  imports: [
+    FastifyModule.forRoot({
+      controllers: [UserController],
+      ajv: {
+        // Custom AJV options
+        customOptions: {
+          removeAdditional: 'all',
+          coerceTypes: 'array',
+          useDefaults: true,
+        },
+        // AJV plugins - supports both formats:
+        // 1. Just the plugin function (uses empty options)
+        // 2. Tuple of [plugin, options]
+        plugins: [
+          ajvFormats, // Plugin without options
+          [ajvKeywords, { keywords: ['typeof', 'instanceof'] }], // Plugin with options
+        ],
+      },
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+#### AJV Configuration Options
+
+| Option          | Type                                       | Description                                           |
+| --------------- | ------------------------------------------ | ----------------------------------------------------- |
+| `customOptions` | `object`                                   | Custom AJV options to merge with the default settings |
+| `plugins`       | `Array<Plugin \| [Plugin, PluginOptions]>` | Array of AJV plugins to register with both validators |
+
+#### Common Use Cases for AJV Customization:
+
+- **Format Validation**: Add `ajv-formats` for email, uri, date-time validation
+- **Custom Keywords**: Use `ajv-keywords` for additional validation keywords
+- **Strict Mode**: Configure strict schema validation settings
+- **Type Coercion**: Customize how types are coerced during validation
+
 ## Middleware
 
 Create custom middleware by implementing the `Middleware` decorator:

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

@@ -16,7 +16,5 @@ const constants_1 = require("../constants.js");
  * Declaring the constants
  */
 function HttpController(path = '') {
-    if (path.charAt(0) !== '/')
-        path = `/${path}`;
     return target => (0, app_1.Controller)({ [constants_1.HTTP_CONTROLLER_TYPE]: 'router', path })(target);
 }

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

@@ -55,6 +55,10 @@ export interface FastifyConfig extends FastifyServerOptions {
      * @default false
      */
     prefixVersioning?: boolean;
+    /**
+     * The global route prefix for all routes in the Fastify instance
+     */
+    routePrefix?: string;
 }
 export interface FastifyModuleOptions extends Partial<FastifyConfig> {
     /**

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

@@ -67,6 +67,7 @@ export declare class FastifyRouter extends Router {
     private readonly sensitiveTransformer;
     constructor(config: FastifyConfig, instance: FastifyInstance, context: ContextService);
     getInstance(): FastifyInstance;
+    private joinPaths;
     private registerRawBody;
     private maskField;
     private getRequestLogger;

package/cjs/module/fastify-router.js

@@ -59,6 +59,14 @@ let FastifyRouter = class FastifyRouter extends app_1.Router {
     getInstance() {
         return this.instance;
     }
+    joinPaths(...parts) {
+        const path = parts
+            .filter(p => typeof p === 'string')
+            .map(p => p.replace(/^\/+|\/+$/g, ''))
+            .filter(Boolean)
+            .join('/');
+        return `/${path}`;
+    }
     registerRawBody() {
         const opts = { parseAs: 'buffer' };
         const parser = this.instance.getDefaultJsonParser('error', 'error');
@@ -117,16 +125,10 @@ let FastifyRouter = class FastifyRouter extends app_1.Router {
             switch (controller.metadata[constants_1.HTTP_CONTROLLER_TYPE]) {
                 case '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 ?? '';
-                        let path = basePath + routePath;
-                        if (this.config.prefixVersioning) {
-                            const version = route.metadata.version ?? 1;
-                            const connector = path.startsWith('/') ? '' : '/';
-                            path = '/v' + version + connector + path;
-                        }
+                        const version = route.metadata.version ?? 1;
+                        const versionPrefix = this.config.prefixVersioning ? `/v${version}` : '';
+                        const path = this.joinPaths(this.config.routePrefix, versionPrefix, metadata.path, route.metadata.path);
                         const parsedController = { ...route, instance, metatype };
                         parsedController.metadata.path = path;
                         parsedControllers.routes.push(parsedController);

package/cjs/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/cjs/module/fastify.utils.js

@@ -18,17 +18,13 @@ const fastify_1 = require("fastify");
  * Importing user defined packages
  */
 const server_error_1 = require("../server.error.js");
-/**
- * Defining types
- */
 /**
  * Declaring the constants
  */
 const keywords = ['x-fastify'];
 const allowedHttpParts = ['body', 'params', 'querystring'];
-const strictValidator = new ajv_1.default({ allErrors: true, useDefaults: true, removeAdditional: true, strict: true, keywords });
-const lenientValidator = new ajv_1.default({ allErrors: true, coerceTypes: true, useDefaults: true, removeAdditional: true, strict: true, keywords });
 const notFoundError = new server_error_1.ServerError(server_error_1.ServerErrorCode.S002);
+const defaultAjvOptions = { allErrors: true, useDefaults: true, removeAdditional: true, strict: true, keywords };
 const notFoundHandler = () => (0, common_1.throwError)(notFoundError);
 exports.notFoundHandler = notFoundHandler;
 function compileSchema(ajv, schema) {
@@ -41,13 +37,13 @@ function compileSchema(ajv, schema) {
     }
     return ajv.getSchema(schema.$id);
 }
-function compileValidator(routeSchema) {
+function compileValidator(routeSchema, validators) {
     (0, node_assert_1.default)(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 ?? []) {
@@ -78,10 +74,19 @@ function formatSchemaErrors(errors, dataVar) {
 async function createFastifyInstance(config, fastifyFactory) {
     const options = common_1.utils.object.omitKeys(config, ['port', 'host', 'errorHandler', 'responseSchema']);
     const { errorHandler } = config;
+    const strictValidator = new ajv_1.default({ ...defaultAjvOptions, ...config.ajv?.customOptions });
+    const lenientValidator = new ajv_1.default({ ...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 = (0, fastify_1.fastify)(options);
     instance.setSchemaErrorFormatter(formatSchemaErrors);
     instance.setNotFoundHandler(exports.notFoundHandler);
     instance.setErrorHandler(errorHandler.handle.bind(errorHandler));
-    instance.setValidatorCompiler(compileValidator);
+    instance.setValidatorCompiler(routeSchema => compileValidator(routeSchema, { strictValidator, lenientValidator }));
     return fastifyFactory ? await fastifyFactory(instance) : instance;
 }

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

@@ -13,7 +13,5 @@ import { HTTP_CONTROLLER_TYPE } from '../constants.js';
  * Declaring the constants
  */
 export function HttpController(path = '') {
-    if (path.charAt(0) !== '/')
-        path = `/${path}`;
     return target => Controller({ [HTTP_CONTROLLER_TYPE]: 'router', path })(target);
 }

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

@@ -55,6 +55,10 @@ export interface FastifyConfig extends FastifyServerOptions {
      * @default false
      */
     prefixVersioning?: boolean;
+    /**
+     * The global route prefix for all routes in the Fastify instance
+     */
+    routePrefix?: string;
 }
 export interface FastifyModuleOptions extends Partial<FastifyConfig> {
     /**

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

@@ -67,6 +67,7 @@ export declare class FastifyRouter extends Router {
     private readonly sensitiveTransformer;
     constructor(config: FastifyConfig, instance: FastifyInstance, context: ContextService);
     getInstance(): FastifyInstance;
+    private joinPaths;
     private registerRawBody;
     private maskField;
     private getRequestLogger;

package/esm/module/fastify-router.js

@@ -53,6 +53,14 @@ let FastifyRouter = class FastifyRouter extends Router {
     getInstance() {
         return this.instance;
     }
+    joinPaths(...parts) {
+        const path = parts
+            .filter(p => typeof p === 'string')
+            .map(p => p.replace(/^\/+|\/+$/g, ''))
+            .filter(Boolean)
+            .join('/');
+        return `/${path}`;
+    }
     registerRawBody() {
         const opts = { parseAs: 'buffer' };
         const parser = this.instance.getDefaultJsonParser('error', 'error');
@@ -111,16 +119,10 @@ let FastifyRouter = class FastifyRouter extends Router {
             switch (controller.metadata[HTTP_CONTROLLER_TYPE]) {
                 case '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 ?? '';
-                        let path = basePath + routePath;
-                        if (this.config.prefixVersioning) {
-                            const version = route.metadata.version ?? 1;
-                            const connector = path.startsWith('/') ? '' : '/';
-                            path = '/v' + version + connector + path;
-                        }
+                        const version = route.metadata.version ?? 1;
+                        const versionPrefix = this.config.prefixVersioning ? `/v${version}` : '';
+                        const path = this.joinPaths(this.config.routePrefix, versionPrefix, metadata.path, route.metadata.path);
                         const parsedController = { ...route, instance, metatype };
                         parsedController.metadata.path = path;
                         parsedControllers.routes.push(parsedController);

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.2.0",
+  "version": "1.4.0",
   "sideEffects": false,
   "description": "A Fastify wrapper featuring decorator-based routing, middleware and error handling",
   "repository": {