@shadow-library/fastify 1.6.4 → 1.7.1

package/README.md

@@ -684,6 +684,45 @@ FastifyModule.forRoot({
 
 > **Note:** When using `forRootAsync`, the defaults are automatically merged with the config returned by your factory function, so you only need to specify the properties you want to override.
 
+### Developer Options
+
+The library registers additional config keys under the `app.dev` namespace for development and debugging convenience. These are controlled via environment variables (or any config source) and require no changes to your module setup.
+
+| Config Key            | Type      | Default                        | Description                                       |
+| --------------------- | --------- | ------------------------------ | ------------------------------------------------- |
+| `app.dev.delay`       | `integer` | — (disabled)                   | Adds an artificial delay (in ms) to every request |
+| `app.dev.stack-trace` | `boolean` | `true` in dev, `false` in prod | Appends the error `stack` to error responses      |
+
+#### `app.dev.stack-trace`
+
+When enabled, the `DefaultErrorHandler` includes the error's `stack` property in the response body alongside the standard error fields. This is automatically enabled in non-production environments and disabled in production.
+
+A warning is logged if stack trace logging is active in a production environment.
+
+The response shape when enabled matches `DevErrorResponseDto`:
+
+```typescript
+import { DevErrorResponseDto } from '@shadow-library/fastify';
+
+// Error response shape with stack trace enabled:
+// {
+//   code: "S001",
+//   message: "An unexpected error has occurred",
+//   stack: "Error: ...\n    at ..."
+// }
+```
+
+#### `app.dev.delay`
+
+Adds an artificial delay in milliseconds to every incoming request via an `onRequest` hook. Useful for simulating slow networks or testing loading states in your frontend without modifying application code.
+
+A warning is logged if a dev delay is active in a production environment.
+
+```bash
+# Add a 500ms delay to every request
+APP_DEV_DELAY=500 node dist/main.js
+```
+
 ### Dynamic Module Configuration
 
 `FastifyModule` is a **dynamic module** that configures itself based on the options you provide. Unlike static modules, dynamic modules return a module configuration object at runtime, allowing for flexible dependency injection and configuration.

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

@@ -13,6 +13,9 @@ export interface ParsedFastifyError {
 }
 export declare class DefaultErrorHandler implements ErrorHandler {
     private readonly logger;
+    private readonly isStackTraceEnabled;
+    constructor();
     protected parseFastifyError(err: FastifyError): ParsedFastifyError;
+    private handleError;
     handle(err: Error, _req: HttpRequest, res: HttpResponse): HttpResponse;
 }

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

@@ -18,27 +18,35 @@ const validationError = new server_error_1.ServerError(server_error_1.ServerErro
 const invalidRequestError = new server_error_1.ServerError(server_error_1.ServerErrorCode.S006);
 class DefaultErrorHandler {
     logger = common_1.Logger.getLogger(constants_1.NAMESPACE, 'DefaultErrorHandler');
+    isStackTraceEnabled = common_1.Config.get('app.dev.stack-trace');
+    constructor() {
+        if (this.isStackTraceEnabled && common_1.Config.isProd())
+            this.logger.warn('Stack trace logging is enabled in production');
+    }
     parseFastifyError(err) {
         if (err.statusCode === 500)
             return { statusCode: 500, error: unexpectedError.toObject() };
         return { statusCode: err.statusCode, error: { ...invalidRequestError.toObject(), message: err.message } };
     }
-    handle(err, _req, res) {
-        this.logger.warn('Handling error', err);
-        if (err.cause)
-            this.logger.warn('Caused by', err.cause);
+    handleError(err) {
         if (err instanceof server_error_1.ServerError)
-            return res.status(err.getStatusCode()).send(err.toObject());
+            return { statusCode: err.getStatusCode(), error: err.toObject() };
         else if (err instanceof common_1.ValidationError)
-            return res.status(validationError.getStatusCode()).send({ ...err.toObject(), ...validationError.toObject() });
+            return { statusCode: validationError.getStatusCode(), error: { ...err.toObject(), ...validationError.toObject() } };
         else if (err instanceof common_1.AppError)
-            return res.status(500).send(err.toObject());
-        else if (err.name === 'FastifyError') {
-            const { statusCode, error } = this.parseFastifyError(err);
-            return res.status(statusCode).send(error);
-        }
+            return { statusCode: 500, error: err.toObject() };
+        else if (err.name === 'FastifyError')
+            return this.parseFastifyError(err);
         this.logger.error('Unhandled error has occurred', err);
-        return res.status(500).send(unexpectedError.toObject());
+        return { statusCode: unexpectedError.getStatusCode(), error: unexpectedError.toObject() };
+    }
+    handle(err, _req, res) {
+        this.logger.warn('Handling error', err);
+        if (err.cause)
+            this.logger.warn('Caused by', err.cause);
+        const { statusCode, error } = this.handleError(err);
+        const payload = this.isStackTraceEnabled ? { ...error, stack: err.stack } : error;
+        return res.status(statusCode).send(payload);
     }
 }
 exports.DefaultErrorHandler = DefaultErrorHandler;

package/cjs/config.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Importing npm packages
+ */
+/**
+ * Importing user defined packages
+ */
+/**
+ * Defining types
+ */
+declare module '@shadow-library/common' {
+    interface ConfigRecords {
+        'app.port': number;
+        'app.host': string;
+        'app.dev.delay': number;
+        'app.dev.stack-trace': boolean;
+    }
+}
+export {};

package/cjs/config.js

@@ -0,0 +1,14 @@
+"use strict";
+/**
+ * Importing npm packages
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const common_1 = require("@shadow-library/common");
+/**
+ * Declaring the constants
+ */
+const isDevValue = String(common_1.Config.isDev());
+common_1.Config.load('app.host', { defaultValue: 'localhost' });
+common_1.Config.load('app.port', { defaultValue: '8080', validateType: 'integer' });
+common_1.Config.load('app.dev.delay', { validateType: 'integer' });
+common_1.Config.load('app.dev.stack-trace', { defaultValue: isDevValue, validateType: 'boolean' });

package/cjs/decorators/api-operation.decorator.d.ts

@@ -5,6 +5,7 @@
  * Defining types
  */
 export interface ApiOperationMetadata {
+    operationId?: string;
     summary?: string;
     description?: string;
     tags?: string[];

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

@@ -34,7 +34,7 @@ function HttpRoute(options) {
         const methodName = propertyKey.toString();
         const summary = methodName.charAt(0).toUpperCase() + methodName.slice(1).replace(/([a-z])([A-Z])|([A-Z]+)([A-Z][a-z])/g, '$1$3 $2$4');
         (0, app_1.Route)(options)(target, propertyKey, descriptor);
-        (0, api_operation_decorator_1.ApiOperation)({ summary })(target, propertyKey, descriptor);
+        (0, api_operation_decorator_1.ApiOperation)({ summary, operationId: methodName })(target, propertyKey, descriptor);
     };
 }
 const Get = (path) => HttpRoute({ method: HttpMethod.GET, path });

package/cjs/index.d.ts

@@ -1,7 +1,8 @@
 /**
- * Importing npm packages
+ * Importing side-effect packages
  */
 import 'reflect-metadata';
+import './config.js';
 /**
  * exporting modules
  */

package/cjs/index.js

@@ -16,9 +16,10 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FASTIFY_INSTANCE = void 0;
 /**
- * Importing npm packages
+ * Importing side-effect packages
  */
 require("reflect-metadata");
+require("./config.js");
 /**
  * exporting modules
  */

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

@@ -17,3 +17,6 @@ export declare class ErrorResponseDto {
     message: string;
     fields?: ErrorFieldDto[];
 }
+export declare class DevErrorResponseDto extends ErrorResponseDto {
+    stack?: string;
+}

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

@@ -9,7 +9,7 @@ var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ErrorResponseDto = exports.ErrorFieldDto = void 0;
+exports.DevErrorResponseDto = exports.ErrorResponseDto = exports.ErrorFieldDto = void 0;
 /**
  * Importing npm packages
  */
@@ -65,3 +65,14 @@ __decorate([
 exports.ErrorResponseDto = ErrorResponseDto = __decorate([
     (0, class_schema_1.Schema)()
 ], ErrorResponseDto);
+let DevErrorResponseDto = class DevErrorResponseDto extends ErrorResponseDto {
+    stack;
+};
+exports.DevErrorResponseDto = DevErrorResponseDto;
+__decorate([
+    (0, class_schema_1.Field)({ optional: true }),
+    __metadata("design:type", String)
+], DevErrorResponseDto.prototype, "stack", void 0);
+exports.DevErrorResponseDto = DevErrorResponseDto = __decorate([
+    (0, class_schema_1.Schema)()
+], DevErrorResponseDto);

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

@@ -14,12 +14,6 @@ import { ContextService } from '../services/index.js';
 /**
  * Defining types
  */
-declare module '@shadow-library/common' {
-    interface ConfigRecords {
-        'app.port': number;
-        'app.host': string;
-    }
-}
 export interface FastifyConfig extends FastifyServerOptions {
     /**
      * The host on which the Fastify instance is to be started

package/cjs/module/fastify-router.js

@@ -291,6 +291,12 @@ let FastifyRouter = class FastifyRouter extends app_1.Router {
         this.instance.addHook('onRequest', this.context.init());
         this.instance.addHook('onRequest', this.getRequestLogger());
         this.logger.info('Registered global middlewares');
+        const delay = common_1.Config.get('app.dev.delay');
+        if (delay) {
+            if (common_1.Config.isProd())
+                this.logger.warn('Dev delay is enabled in production');
+            this.instance.addHook('onRequest', (_req, _res, done) => setTimeout(done, delay));
+        }
         for (const route of routes) {
             const metadata = route.metadata;
             (0, node_assert_1.default)(metadata.path, 'Route path is required');

package/cjs/module/fastify.module.js

@@ -32,9 +32,9 @@ const fastify_utils_1 = require("./fastify.utils.js");
  */
 let FastifyModule = FastifyModule_1 = class FastifyModule {
     static getDefaultConfig() {
-        common_1.Config.load('app.host', { defaultValue: 'localhost' });
-        common_1.Config.load('app.port', { defaultValue: '8080', validateType: 'number' });
-        const errorResponseSchema = class_schema_1.ClassSchema.generate(error_response_dto_1.ErrorResponseDto);
+        const stackTrace = common_1.Config.get('app.dev.stack-trace');
+        const errorResponseClass = stackTrace ? error_response_dto_1.DevErrorResponseDto : error_response_dto_1.ErrorResponseDto;
+        const errorResponseSchema = class_schema_1.ClassSchema.generate(errorResponseClass);
         return {
             host: common_1.Config.get('app.host'),
             port: common_1.Config.get('app.port'),

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

@@ -13,6 +13,9 @@ export interface ParsedFastifyError {
 }
 export declare class DefaultErrorHandler implements ErrorHandler {
     private readonly logger;
+    private readonly isStackTraceEnabled;
+    constructor();
     protected parseFastifyError(err: FastifyError): ParsedFastifyError;
+    private handleError;
     handle(err: Error, _req: HttpRequest, res: HttpResponse): HttpResponse;
 }

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

@@ -1,7 +1,7 @@
 /**
  * Importing npm packages
  */
-import { AppError, Logger, ValidationError } from '@shadow-library/common';
+import { AppError, Config, Logger, ValidationError } from '@shadow-library/common';
 /**
  * Importing user defined packages
  */
@@ -15,26 +15,34 @@ const validationError = new ServerError(ServerErrorCode.S003);
 const invalidRequestError = new ServerError(ServerErrorCode.S006);
 export class DefaultErrorHandler {
     logger = Logger.getLogger(NAMESPACE, 'DefaultErrorHandler');
+    isStackTraceEnabled = Config.get('app.dev.stack-trace');
+    constructor() {
+        if (this.isStackTraceEnabled && Config.isProd())
+            this.logger.warn('Stack trace logging is enabled in production');
+    }
     parseFastifyError(err) {
         if (err.statusCode === 500)
             return { statusCode: 500, error: unexpectedError.toObject() };
         return { statusCode: err.statusCode, error: { ...invalidRequestError.toObject(), message: err.message } };
     }
-    handle(err, _req, res) {
-        this.logger.warn('Handling error', err);
-        if (err.cause)
-            this.logger.warn('Caused by', err.cause);
+    handleError(err) {
         if (err instanceof ServerError)
-            return res.status(err.getStatusCode()).send(err.toObject());
+            return { statusCode: err.getStatusCode(), error: err.toObject() };
         else if (err instanceof ValidationError)
-            return res.status(validationError.getStatusCode()).send({ ...err.toObject(), ...validationError.toObject() });
+            return { statusCode: validationError.getStatusCode(), error: { ...err.toObject(), ...validationError.toObject() } };
         else if (err instanceof AppError)
-            return res.status(500).send(err.toObject());
-        else if (err.name === 'FastifyError') {
-            const { statusCode, error } = this.parseFastifyError(err);
-            return res.status(statusCode).send(error);
-        }
+            return { statusCode: 500, error: err.toObject() };
+        else if (err.name === 'FastifyError')
+            return this.parseFastifyError(err);
         this.logger.error('Unhandled error has occurred', err);
-        return res.status(500).send(unexpectedError.toObject());
+        return { statusCode: unexpectedError.getStatusCode(), error: unexpectedError.toObject() };
+    }
+    handle(err, _req, res) {
+        this.logger.warn('Handling error', err);
+        if (err.cause)
+            this.logger.warn('Caused by', err.cause);
+        const { statusCode, error } = this.handleError(err);
+        const payload = this.isStackTraceEnabled ? { ...error, stack: err.stack } : error;
+        return res.status(statusCode).send(payload);
     }
 }

package/esm/config.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Importing npm packages
+ */
+/**
+ * Importing user defined packages
+ */
+/**
+ * Defining types
+ */
+declare module '@shadow-library/common' {
+    interface ConfigRecords {
+        'app.port': number;
+        'app.host': string;
+        'app.dev.delay': number;
+        'app.dev.stack-trace': boolean;
+    }
+}
+export {};

package/esm/config.js

@@ -0,0 +1,12 @@
+/**
+ * Importing npm packages
+ */
+import { Config } from '@shadow-library/common';
+/**
+ * Declaring the constants
+ */
+const isDevValue = String(Config.isDev());
+Config.load('app.host', { defaultValue: 'localhost' });
+Config.load('app.port', { defaultValue: '8080', validateType: 'integer' });
+Config.load('app.dev.delay', { validateType: 'integer' });
+Config.load('app.dev.stack-trace', { defaultValue: isDevValue, validateType: 'boolean' });

package/esm/decorators/api-operation.decorator.d.ts

@@ -5,6 +5,7 @@
  * Defining types
  */
 export interface ApiOperationMetadata {
+    operationId?: string;
     summary?: string;
     description?: string;
     tags?: string[];

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

@@ -30,7 +30,7 @@ export function HttpRoute(options) {
         const methodName = propertyKey.toString();
         const summary = methodName.charAt(0).toUpperCase() + methodName.slice(1).replace(/([a-z])([A-Z])|([A-Z]+)([A-Z][a-z])/g, '$1$3 $2$4');
         Route(options)(target, propertyKey, descriptor);
-        ApiOperation({ summary })(target, propertyKey, descriptor);
+        ApiOperation({ summary, operationId: methodName })(target, propertyKey, descriptor);
     };
 }
 export const Get = (path) => HttpRoute({ method: HttpMethod.GET, path });

package/esm/index.d.ts

@@ -1,7 +1,8 @@
 /**
- * Importing npm packages
+ * Importing side-effect packages
  */
 import 'reflect-metadata';
+import './config.js';
 /**
  * exporting modules
  */

package/esm/index.js

@@ -1,7 +1,8 @@
 /**
- * Importing npm packages
+ * Importing side-effect packages
  */
 import 'reflect-metadata';
+import './config.js';
 /**
  * exporting modules
  */

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

@@ -17,3 +17,6 @@ export declare class ErrorResponseDto {
     message: string;
     fields?: ErrorFieldDto[];
 }
+export declare class DevErrorResponseDto extends ErrorResponseDto {
+    stack?: string;
+}

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

@@ -62,3 +62,14 @@ ErrorResponseDto = __decorate([
     Schema()
 ], ErrorResponseDto);
 export { ErrorResponseDto };
+let DevErrorResponseDto = class DevErrorResponseDto extends ErrorResponseDto {
+    stack;
+};
+__decorate([
+    Field({ optional: true }),
+    __metadata("design:type", String)
+], DevErrorResponseDto.prototype, "stack", void 0);
+DevErrorResponseDto = __decorate([
+    Schema()
+], DevErrorResponseDto);
+export { DevErrorResponseDto };

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

@@ -14,12 +14,6 @@ import { ContextService } from '../services/index.js';
 /**
  * Defining types
  */
-declare module '@shadow-library/common' {
-    interface ConfigRecords {
-        'app.port': number;
-        'app.host': string;
-    }
-}
 export interface FastifyConfig extends FastifyServerOptions {
     /**
      * The host on which the Fastify instance is to be started

package/esm/module/fastify-router.js

@@ -16,7 +16,7 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 import assert from 'node:assert';
 import { Inject, Injectable, Router } from '@shadow-library/app';
 import { ClassSchema, TransformerFactory } from '@shadow-library/class-schema';
-import { InternalError, Logger, utils } from '@shadow-library/common';
+import { Config, InternalError, Logger, utils } from '@shadow-library/common';
 import { all as deepmerge } from 'deepmerge';
 import findMyWay from 'find-my-way';
 import stringify from 'json-stable-stringify';
@@ -285,6 +285,12 @@ let FastifyRouter = class FastifyRouter extends Router {
         this.instance.addHook('onRequest', this.context.init());
         this.instance.addHook('onRequest', this.getRequestLogger());
         this.logger.info('Registered global middlewares');
+        const delay = Config.get('app.dev.delay');
+        if (delay) {
+            if (Config.isProd())
+                this.logger.warn('Dev delay is enabled in production');
+            this.instance.addHook('onRequest', (_req, _res, done) => setTimeout(done, delay));
+        }
         for (const route of routes) {
             const metadata = route.metadata;
             assert(metadata.path, 'Route path is required');

package/esm/module/fastify.module.js

@@ -18,7 +18,7 @@ import { v4 as uuid } from 'uuid';
 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 { DevErrorResponseDto, ErrorResponseDto } from './error-response.dto.js';
 import { FastifyRouter } from './fastify-router.js';
 import { createFastifyInstance } from './fastify.utils.js';
 /**
@@ -29,9 +29,9 @@ import { createFastifyInstance } from './fastify.utils.js';
  */
 let FastifyModule = FastifyModule_1 = class FastifyModule {
     static getDefaultConfig() {
-        Config.load('app.host', { defaultValue: 'localhost' });
-        Config.load('app.port', { defaultValue: '8080', validateType: 'number' });
-        const errorResponseSchema = ClassSchema.generate(ErrorResponseDto);
+        const stackTrace = Config.get('app.dev.stack-trace');
+        const errorResponseClass = stackTrace ? DevErrorResponseDto : ErrorResponseDto;
+        const errorResponseSchema = ClassSchema.generate(errorResponseClass);
         return {
             host: Config.get('app.host'),
             port: Config.get('app.port'),

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "@shadow-library/fastify",
   "type": "module",
-  "version": "1.6.4",
-  "sideEffects": false,
+  "version": "1.7.1",
+  "sideEffects": [
+    "./esm/config.js",
+    "./cjs/config.js"
+  ],
   "description": "A Fastify wrapper featuring decorator-based routing, middleware and error handling",
   "repository": {
     "type": "git",
@@ -27,9 +30,9 @@
   },
   "peerDependencies": {
     "@fastify/view": "^10.0.0",
-    "@shadow-library/app": "^1.3.1",
-    "@shadow-library/class-schema": "^0.2.0",
-    "@shadow-library/common": "^1.5.2",
+    "@shadow-library/app": "^1.3.2",
+    "@shadow-library/class-schema": "^0.4.2",
+    "@shadow-library/common": "^1.6.0",
     "reflect-metadata": "^0.2.2"
   },
   "peerDependenciesMeta": {