nestjs-api-forge 1.0.1

package/README.md

@@ -0,0 +1,221 @@
+# nestjs-api-forge
+
+Standardized API response formatting, structured error handling, and exception filters for [NestJS](https://nestjs.com/) applications.
+
+## Features
+
+- **Uniform success response** envelope wrapping all handler return values
+- **Structured error responses** with `code`, `message`, and optional `details` array
+- **Global exception filter** that handles `HttpException`, `ValidationPipe` errors, and unexpected exceptions
+- **Built-in typed exceptions** (`NotFoundException`, `UnauthorizedException`, `ValidationException`, etc.)
+- **`@ForgeMessage`** decorator to override per-route success messages
+- **`@ForgeRawResponse`** decorator to opt a route out of wrapping
+- **`ApiForgeModule.forRoot()`** for one-line global registration
+- **`ApiForgeModule.forRootAsync()`** for config-service-driven options
+
+---
+
+## Installation
+
+```bash
+npm install nestjs-api-forge
+```
+
+---
+
+## Quick Start
+
+### 1. Register globally (`app.module.ts`)
+
+```typescript
+import { Module } from '@nestjs/common';
+import { ApiForgeModule } from 'nestjs-api-forge';
+
+@Module({
+  imports: [
+    ApiForgeModule.forRoot({
+      version: '1.0',
+      defaultSuccessMessage: 'OK',
+      includePath: true,
+      includeTimestamp: true,
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+Every route in your application will now return a standardized response automatically.
+
+---
+
+## Response Formats
+
+### Success
+
+```json
+{
+  "success": true,
+  "statusCode": 200,
+  "message": "Request successful",
+  "data": { "id": 1, "name": "Alice" },
+  "meta": {
+    "timestamp": "2026-05-02T10:00:00.000Z",
+    "path": "/api/users/1",
+    "version": "1.0"
+  }
+}
+```
+
+### Error
+
+```json
+{
+  "success": false,
+  "statusCode": 404,
+  "message": "User not found",
+  "error": {
+    "code": "NOT_FOUND"
+  },
+  "meta": {
+    "timestamp": "2026-05-02T10:00:00.000Z",
+    "path": "/api/users/99",
+    "version": "1.0"
+  }
+}
+```
+
+### Validation Error (from `ValidationPipe`)
+
+```json
+{
+  "success": false,
+  "statusCode": 400,
+  "message": "Validation failed",
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "details": [
+      { "field": "email", "message": "must be an email" },
+      { "field": "password", "message": "must be longer than 8 characters" }
+    ]
+  },
+  "meta": {
+    "timestamp": "2026-05-02T10:00:00.000Z",
+    "path": "/api/auth/register"
+  }
+}
+```
+
+---
+
+## API Reference
+
+### `ApiForgeModule.forRoot(options?)`
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `includePath` | `boolean` | `true` | Include request path in `meta` |
+| `includeTimestamp` | `boolean` | `true` | Include ISO timestamp in `meta` |
+| `version` | `string` | `undefined` | API version string added to `meta` |
+| `defaultSuccessMessage` | `string` | `'Request successful'` | Default success message |
+
+### Decorators
+
+| Decorator | Scope | Description |
+|---|---|---|
+| `@ApiForge(options?)` | Controller / Method | Apply filter + interceptor to a single controller or method |
+| `@ForgeMessage(msg)` | Controller / Method | Override the success message for that route |
+| `@ForgeRawResponse()` | Controller / Method | Skip response wrapping; return handler value as-is |
+
+### Built-in Exceptions
+
+All exceptions extend `ApiException` which extends NestJS's `HttpException`.
+
+| Class | Status | Code |
+|---|---|---|
+| `BadRequestException` | 400 | `BAD_REQUEST` |
+| `UnauthorizedException` | 401 | `UNAUTHORIZED` |
+| `ForbiddenException` | 403 | `FORBIDDEN` |
+| `NotFoundException` | 404 | `NOT_FOUND` |
+| `ConflictException` | 409 | `CONFLICT` |
+| `UnprocessableEntityException` | 422 | `UNPROCESSABLE_ENTITY` |
+| `TooManyRequestsException` | 429 | `TOO_MANY_REQUESTS` |
+| `InternalServerException` | 500 | `INTERNAL_SERVER_ERROR` |
+| `ServiceUnavailableException` | 503 | `SERVICE_UNAVAILABLE` |
+| `ValidationException` | 400 | `VALIDATION_ERROR` |
+
+### `ApiResponseDto` (manual usage)
+
+```typescript
+import { ApiResponseDto } from 'nestjs-api-forge';
+
+ApiResponseDto.success(data, 'User fetched', 200, { path: '/users/1' });
+ApiResponseDto.created(data, 'User created');
+ApiResponseDto.noContent('Deleted');
+ApiResponseDto.error('Not found', 404, { code: 'NOT_FOUND' });
+```
+
+---
+
+## Usage Examples
+
+### Controller with custom message
+
+```typescript
+import { Controller, Get, Param } from '@nestjs/common';
+import { ForgeMessage, NotFoundException } from 'nestjs-api-forge';
+
+@Controller('users')
+export class UsersController {
+  @Get(':id')
+  @ForgeMessage('User fetched successfully')
+  findOne(@Param('id') id: string) {
+    const user = this.usersService.findById(+id);
+    if (!user) throw new NotFoundException('User');
+    return user;
+  }
+}
+```
+
+### Skip wrapping for a specific route
+
+```typescript
+@Get('health')
+@ForgeRawResponse()
+healthCheck() {
+  return { status: 'ok' };
+}
+```
+
+### Async module registration (with ConfigService)
+
+```typescript
+ApiForgeModule.forRootAsync({
+  imports: [ConfigModule],
+  inject: [ConfigService],
+  useFactory: (config: ConfigService) => ({
+    version: config.get('API_VERSION'),
+    defaultSuccessMessage: config.get('DEFAULT_SUCCESS_MSG'),
+  }),
+})
+```
+
+### Use with `ValidationPipe`
+
+```typescript
+// main.ts
+app.useGlobalPipes(
+  new ValidationPipe({
+    whitelist: true,
+    forbidNonWhitelisted: true,
+    transform: true,
+  }),
+);
+```
+
+The exception filter automatically parses `ValidationPipe` error arrays and formats them into `error.details`.
+
+---
+
+## License
+
+MIT

package/dist/api-forge.module.d.ts

@@ -0,0 +1,11 @@
+import { DynamicModule } from '@nestjs/common';
+import { ForgeOptions } from './interfaces/api-response.interface';
+export declare const FORGE_OPTIONS = "FORGE_OPTIONS";
+export declare class ApiForgeModule {
+    static forRoot(options?: ForgeOptions): DynamicModule;
+    static forRootAsync(asyncOptions: {
+        useFactory: (...args: any[]) => ForgeOptions | Promise<ForgeOptions>;
+        inject?: any[];
+        imports?: any[];
+    }): DynamicModule;
+}

package/dist/api-forge.module.js

@@ -0,0 +1,70 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    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;
+};
+var ApiForgeModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiForgeModule = exports.FORGE_OPTIONS = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+const global_exception_filter_1 = require("./filters/global-exception.filter");
+const response_interceptor_1 = require("./interceptors/response.interceptor");
+exports.FORGE_OPTIONS = 'FORGE_OPTIONS';
+let ApiForgeModule = ApiForgeModule_1 = class ApiForgeModule {
+    static forRoot(options = {}) {
+        const optionsProvider = {
+            provide: exports.FORGE_OPTIONS,
+            useValue: options,
+        };
+        const exceptionFilterProvider = {
+            provide: core_1.APP_FILTER,
+            useFactory: () => new global_exception_filter_1.ForgeExceptionFilter(options),
+        };
+        const responseInterceptorProvider = {
+            provide: core_1.APP_INTERCEPTOR,
+            useFactory: (reflector) => new response_interceptor_1.ForgeResponseInterceptor(reflector, options),
+            inject: [core_1.Reflector],
+        };
+        return {
+            module: ApiForgeModule_1,
+            providers: [
+                optionsProvider,
+                exceptionFilterProvider,
+                responseInterceptorProvider,
+            ],
+            exports: [exports.FORGE_OPTIONS],
+        };
+    }
+    static forRootAsync(asyncOptions) {
+        const exceptionFilterProvider = {
+            provide: core_1.APP_FILTER,
+            useFactory: async (...args) => {
+                const options = await asyncOptions.useFactory(...args);
+                return new global_exception_filter_1.ForgeExceptionFilter(options);
+            },
+            inject: asyncOptions.inject ?? [],
+        };
+        const responseInterceptorProvider = {
+            provide: core_1.APP_INTERCEPTOR,
+            useFactory: async (reflector, ...args) => {
+                const options = await asyncOptions.useFactory(...args);
+                return new response_interceptor_1.ForgeResponseInterceptor(reflector, options);
+            },
+            inject: [core_1.Reflector, ...(asyncOptions.inject ?? [])],
+        };
+        return {
+            module: ApiForgeModule_1,
+            imports: asyncOptions.imports ?? [],
+            providers: [exceptionFilterProvider, responseInterceptorProvider],
+        };
+    }
+};
+exports.ApiForgeModule = ApiForgeModule;
+exports.ApiForgeModule = ApiForgeModule = ApiForgeModule_1 = __decorate([
+    (0, common_1.Global)(),
+    (0, common_1.Module)({})
+], ApiForgeModule);
+//# sourceMappingURL=api-forge.module.js.map

package/dist/api-forge.module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-forge.module.js","sourceRoot":"","sources":["../src/api-forge.module.ts"],"names":[],"mappings":";;;;;;;;;;AAAA,2CAAyE;AACzE,uCAAsE;AACtE,+EAAyE;AACzE,8EAA+E;AAGlE,QAAA,aAAa,GAAG,eAAe,CAAC;AAItC,IAAM,cAAc,sBAApB,MAAM,cAAc;IAKzB,MAAM,CAAC,OAAO,CAAC,UAAwB,EAAE;QACvC,MAAM,eAAe,GAAa;YAChC,OAAO,EAAE,qBAAa;YACtB,QAAQ,EAAE,OAAO;SAClB,CAAC;QAEF,MAAM,uBAAuB,GAAa;YACxC,OAAO,EAAE,iBAAU;YACnB,UAAU,EAAE,GAAG,EAAE,CAAC,IAAI,8CAAoB,CAAC,OAAO,CAAC;SACpD,CAAC;QAEF,MAAM,2BAA2B,GAAa;YAC5C,OAAO,EAAE,sBAAe;YACxB,UAAU,EAAE,CAAC,SAAoB,EAAE,EAAE,CACnC,IAAI,+CAAwB,CAAC,SAAS,EAAE,OAAO,CAAC;YAClD,MAAM,EAAE,CAAC,gBAAS,CAAC;SACpB,CAAC;QAEF,OAAO;YACL,MAAM,EAAE,gBAAc;YACtB,SAAS,EAAE;gBACT,eAAe;gBACf,uBAAuB;gBACvB,2BAA2B;aAC5B;YACD,OAAO,EAAE,CAAC,qBAAa,CAAC;SACzB,CAAC;IACJ,CAAC;IAKD,MAAM,CAAC,YAAY,CAAC,YAInB;QACC,MAAM,uBAAuB,GAAa;YACxC,OAAO,EAAE,iBAAU;YACnB,UAAU,EAAE,KAAK,EAAE,GAAG,IAAW,EAAE,EAAE;gBACnC,MAAM,OAAO,GAAG,MAAM,YAAY,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC,CAAC;gBACvD,OAAO,IAAI,8CAAoB,CAAC,OAAO,CAAC,CAAC;YAC3C,CAAC;YACD,MAAM,EAAE,YAAY,CAAC,MAAM,IAAI,EAAE;SAClC,CAAC;QAEF,MAAM,2BAA2B,GAAa;YAC5C,OAAO,EAAE,sBAAe;YACxB,UAAU,EAAE,KAAK,EAAE,SAAoB,EAAE,GAAG,IAAW,EAAE,EAAE;gBACzD,MAAM,OAAO,GAAG,MAAM,YAAY,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC,CAAC;gBACvD,OAAO,IAAI,+CAAwB,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;YAC1D,CAAC;YACD,MAAM,EAAE,CAAC,gBAAS,EAAE,GAAG,CAAC,YAAY,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC;SACpD,CAAC;QAEF,OAAO;YACL,MAAM,EAAE,gBAAc;YACtB,OAAO,EAAE,YAAY,CAAC,OAAO,IAAI,EAAE;YACnC,SAAS,EAAE,CAAC,uBAAuB,EAAE,2BAA2B,CAAC;SAClE,CAAC;IACJ,CAAC;CACF,CAAA;AAlEY,wCAAc;yBAAd,cAAc;IAF1B,IAAA,eAAM,GAAE;IACR,IAAA,eAAM,EAAC,EAAE,CAAC;GACE,cAAc,CAkE1B"}

package/dist/decorators/api-response.decorator.d.ts

@@ -0,0 +1,6 @@
+import { ForgeOptions } from '../interfaces/api-response.interface';
+export declare const FORGE_MESSAGE_KEY = "forge:response_message";
+export declare const FORGE_RAW_RESPONSE_KEY = "forge:raw_response";
+export declare const ForgeMessage: (message: string) => import("@nestjs/common").CustomDecorator<string>;
+export declare const ForgeRawResponse: () => import("@nestjs/common").CustomDecorator<string>;
+export declare function ApiForge(options?: ForgeOptions): <TFunction extends Function, Y>(target: TFunction | object, propertyKey?: string | symbol, descriptor?: TypedPropertyDescriptor<Y>) => void;

package/dist/decorators/api-response.decorator.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ForgeRawResponse = exports.ForgeMessage = exports.FORGE_RAW_RESPONSE_KEY = exports.FORGE_MESSAGE_KEY = void 0;
+exports.ApiForge = ApiForge;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+const response_interceptor_1 = require("../interceptors/response.interceptor");
+const global_exception_filter_1 = require("../filters/global-exception.filter");
+exports.FORGE_MESSAGE_KEY = 'forge:response_message';
+exports.FORGE_RAW_RESPONSE_KEY = 'forge:raw_response';
+const ForgeMessage = (message) => (0, common_1.SetMetadata)(exports.FORGE_MESSAGE_KEY, message);
+exports.ForgeMessage = ForgeMessage;
+const ForgeRawResponse = () => (0, common_1.SetMetadata)(exports.FORGE_RAW_RESPONSE_KEY, true);
+exports.ForgeRawResponse = ForgeRawResponse;
+function ApiForge(options = {}) {
+    const reflector = new core_1.Reflector();
+    return (0, common_1.applyDecorators)((0, common_1.UseInterceptors)(new response_interceptor_1.ForgeResponseInterceptor(reflector, options)), (0, common_1.UseFilters)(new global_exception_filter_1.ForgeExceptionFilter(options)));
+}
+//# sourceMappingURL=api-response.decorator.js.map

package/dist/decorators/api-response.decorator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-response.decorator.js","sourceRoot":"","sources":["../../src/decorators/api-response.decorator.ts"],"names":[],"mappings":";;;AAoBA,4BAMC;AA1BD,2CAA2F;AAC3F,uCAAyC;AACzC,+EAAgF;AAChF,gFAA0E;AAG7D,QAAA,iBAAiB,GAAG,wBAAwB,CAAC;AAC7C,QAAA,sBAAsB,GAAG,oBAAoB,CAAC;AAGpD,MAAM,YAAY,GAAG,CAAC,OAAe,EAAE,EAAE,CAC9C,IAAA,oBAAW,EAAC,yBAAiB,EAAE,OAAO,CAAC,CAAC;AAD7B,QAAA,YAAY,gBACiB;AAGnC,MAAM,gBAAgB,GAAG,GAAG,EAAE,CAAC,IAAA,oBAAW,EAAC,8BAAsB,EAAE,IAAI,CAAC,CAAC;AAAnE,QAAA,gBAAgB,oBAAmD;AAMhF,SAAgB,QAAQ,CAAC,UAAwB,EAAE;IACjD,MAAM,SAAS,GAAG,IAAI,gBAAS,EAAE,CAAC;IAClC,OAAO,IAAA,wBAAe,EACpB,IAAA,wBAAe,EAAC,IAAI,+CAAwB,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC,EACjE,IAAA,mBAAU,EAAC,IAAI,8CAAoB,CAAC,OAAO,CAAC,CAAC,CAC9C,CAAC;AACJ,CAAC"}

package/dist/decorators/index.d.ts

@@ -0,0 +1 @@
+export * from './api-response.decorator';

package/dist/decorators/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+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 });
+__exportStar(require("./api-response.decorator"), exports);
+//# sourceMappingURL=index.js.map

package/dist/decorators/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/decorators/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,2DAAyC"}

package/dist/dto/api-response.dto.d.ts

@@ -0,0 +1,7 @@
+import { ApiErrorPayload, ApiMeta, ApiSuccessResponse, ApiErrorResponse } from '../interfaces/api-response.interface';
+export declare class ApiResponseDto {
+    static success<T>(data: T, message?: string, statusCode?: number, meta?: Partial<ApiMeta>): ApiSuccessResponse<T>;
+    static created<T>(data: T, message?: string, meta?: Partial<ApiMeta>): ApiSuccessResponse<T>;
+    static noContent(message?: string, meta?: Partial<ApiMeta>): ApiSuccessResponse<null>;
+    static error(message: string, statusCode: number, error: ApiErrorPayload, meta?: Partial<ApiMeta>): ApiErrorResponse;
+}

package/dist/dto/api-response.dto.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiResponseDto = void 0;
+class ApiResponseDto {
+    static success(data, message = 'Request successful', statusCode = 200, meta = {}) {
+        return {
+            success: true,
+            statusCode,
+            message,
+            data,
+            meta: {
+                timestamp: new Date().toISOString(),
+                ...meta,
+            },
+        };
+    }
+    static created(data, message = 'Resource created successfully', meta = {}) {
+        return ApiResponseDto.success(data, message, 201, meta);
+    }
+    static noContent(message = 'No content', meta = {}) {
+        return ApiResponseDto.success(null, message, 204, meta);
+    }
+    static error(message, statusCode, error, meta = {}) {
+        return {
+            success: false,
+            statusCode,
+            message,
+            error,
+            meta: {
+                timestamp: new Date().toISOString(),
+                ...meta,
+            },
+        };
+    }
+}
+exports.ApiResponseDto = ApiResponseDto;
+//# sourceMappingURL=api-response.dto.js.map

package/dist/dto/api-response.dto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-response.dto.js","sourceRoot":"","sources":["../../src/dto/api-response.dto.ts"],"names":[],"mappings":";;;AAOA,MAAa,cAAc;IACzB,MAAM,CAAC,OAAO,CACZ,IAAO,EACP,OAAO,GAAG,oBAAoB,EAC9B,UAAU,GAAG,GAAG,EAChB,OAAyB,EAAE;QAE3B,OAAO;YACL,OAAO,EAAE,IAAI;YACb,UAAU;YACV,OAAO;YACP,IAAI;YACJ,IAAI,EAAE;gBACJ,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;gBACnC,GAAG,IAAI;aACR;SACF,CAAC;IACJ,CAAC;IAED,MAAM,CAAC,OAAO,CACZ,IAAO,EACP,OAAO,GAAG,+BAA+B,EACzC,OAAyB,EAAE;QAE3B,OAAO,cAAc,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;IAC1D,CAAC;IAED,MAAM,CAAC,SAAS,CACd,OAAO,GAAG,YAAY,EACtB,OAAyB,EAAE;QAE3B,OAAO,cAAc,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;IAC1D,CAAC;IAED,MAAM,CAAC,KAAK,CACV,OAAe,EACf,UAAkB,EAClB,KAAsB,EACtB,OAAyB,EAAE;QAE3B,OAAO;YACL,OAAO,EAAE,KAAK;YACd,UAAU;YACV,OAAO;YACP,KAAK;YACL,IAAI,EAAE;gBACJ,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;gBACnC,GAAG,IAAI;aACR;SACF,CAAC;IACJ,CAAC;CACF;AAnDD,wCAmDC"}

package/dist/dto/index.d.ts

@@ -0,0 +1 @@
+export * from './api-response.dto';

package/dist/dto/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+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 });
+__exportStar(require("./api-response.dto"), exports);
+//# sourceMappingURL=index.js.map

package/dist/dto/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/dto/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,qDAAmC"}

package/dist/exceptions/api.exception.d.ts

@@ -0,0 +1,34 @@
+import { HttpException, HttpStatus } from '@nestjs/common';
+import { ApiErrorDetail } from '../interfaces/api-response.interface';
+export declare class ApiException extends HttpException {
+    readonly code: string;
+    readonly details?: ApiErrorDetail[] | undefined;
+    constructor(message: string, statusCode: HttpStatus, code: string, details?: ApiErrorDetail[] | undefined);
+}
+export declare class BadRequestException extends ApiException {
+    constructor(message?: string, details?: ApiErrorDetail[]);
+}
+export declare class UnauthorizedException extends ApiException {
+    constructor(message?: string);
+}
+export declare class ForbiddenException extends ApiException {
+    constructor(message?: string);
+}
+export declare class NotFoundException extends ApiException {
+    constructor(resource?: string);
+}
+export declare class ConflictException extends ApiException {
+    constructor(message?: string);
+}
+export declare class UnprocessableEntityException extends ApiException {
+    constructor(message?: string, details?: ApiErrorDetail[]);
+}
+export declare class TooManyRequestsException extends ApiException {
+    constructor(message?: string);
+}
+export declare class InternalServerException extends ApiException {
+    constructor(message?: string);
+}
+export declare class ServiceUnavailableException extends ApiException {
+    constructor(message?: string);
+}

package/dist/exceptions/api.exception.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServiceUnavailableException = exports.InternalServerException = exports.TooManyRequestsException = exports.UnprocessableEntityException = exports.ConflictException = exports.NotFoundException = exports.ForbiddenException = exports.UnauthorizedException = exports.BadRequestException = exports.ApiException = void 0;
+const common_1 = require("@nestjs/common");
+class ApiException extends common_1.HttpException {
+    constructor(message, statusCode, code, details) {
+        super({ message, code, details }, statusCode);
+        this.code = code;
+        this.details = details;
+    }
+}
+exports.ApiException = ApiException;
+class BadRequestException extends ApiException {
+    constructor(message = 'Bad request', details) {
+        super(message, common_1.HttpStatus.BAD_REQUEST, 'BAD_REQUEST', details);
+    }
+}
+exports.BadRequestException = BadRequestException;
+class UnauthorizedException extends ApiException {
+    constructor(message = 'Unauthorized') {
+        super(message, common_1.HttpStatus.UNAUTHORIZED, 'UNAUTHORIZED');
+    }
+}
+exports.UnauthorizedException = UnauthorizedException;
+class ForbiddenException extends ApiException {
+    constructor(message = 'Forbidden resource') {
+        super(message, common_1.HttpStatus.FORBIDDEN, 'FORBIDDEN');
+    }
+}
+exports.ForbiddenException = ForbiddenException;
+class NotFoundException extends ApiException {
+    constructor(resource = 'Resource') {
+        super(`${resource} not found`, common_1.HttpStatus.NOT_FOUND, 'NOT_FOUND');
+    }
+}
+exports.NotFoundException = NotFoundException;
+class ConflictException extends ApiException {
+    constructor(message = 'Resource already exists') {
+        super(message, common_1.HttpStatus.CONFLICT, 'CONFLICT');
+    }
+}
+exports.ConflictException = ConflictException;
+class UnprocessableEntityException extends ApiException {
+    constructor(message = 'Unprocessable entity', details) {
+        super(message, common_1.HttpStatus.UNPROCESSABLE_ENTITY, 'UNPROCESSABLE_ENTITY', details);
+    }
+}
+exports.UnprocessableEntityException = UnprocessableEntityException;
+class TooManyRequestsException extends ApiException {
+    constructor(message = 'Too many requests') {
+        super(message, common_1.HttpStatus.TOO_MANY_REQUESTS, 'TOO_MANY_REQUESTS');
+    }
+}
+exports.TooManyRequestsException = TooManyRequestsException;
+class InternalServerException extends ApiException {
+    constructor(message = 'Internal server error') {
+        super(message, common_1.HttpStatus.INTERNAL_SERVER_ERROR, 'INTERNAL_SERVER_ERROR');
+    }
+}
+exports.InternalServerException = InternalServerException;
+class ServiceUnavailableException extends ApiException {
+    constructor(message = 'Service unavailable') {
+        super(message, common_1.HttpStatus.SERVICE_UNAVAILABLE, 'SERVICE_UNAVAILABLE');
+    }
+}
+exports.ServiceUnavailableException = ServiceUnavailableException;
+//# sourceMappingURL=api.exception.js.map

package/dist/exceptions/api.exception.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.exception.js","sourceRoot":"","sources":["../../src/exceptions/api.exception.ts"],"names":[],"mappings":";;;AAAA,2CAA2D;AAG3D,MAAa,YAAa,SAAQ,sBAAa;IAC7C,YACE,OAAe,EACf,UAAsB,EACN,IAAY,EACZ,OAA0B;QAE1C,KAAK,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,UAAU,CAAC,CAAC;QAH9B,SAAI,GAAJ,IAAI,CAAQ;QACZ,YAAO,GAAP,OAAO,CAAmB;IAG5C,CAAC;CACF;AATD,oCASC;AAED,MAAa,mBAAoB,SAAQ,YAAY;IACnD,YAAY,OAAO,GAAG,aAAa,EAAE,OAA0B;QAC7D,KAAK,CAAC,OAAO,EAAE,mBAAU,CAAC,WAAW,EAAE,aAAa,EAAE,OAAO,CAAC,CAAC;IACjE,CAAC;CACF;AAJD,kDAIC;AAED,MAAa,qBAAsB,SAAQ,YAAY;IACrD,YAAY,OAAO,GAAG,cAAc;QAClC,KAAK,CAAC,OAAO,EAAE,mBAAU,CAAC,YAAY,EAAE,cAAc,CAAC,CAAC;IAC1D,CAAC;CACF;AAJD,sDAIC;AAED,MAAa,kBAAmB,SAAQ,YAAY;IAClD,YAAY,OAAO,GAAG,oBAAoB;QACxC,KAAK,CAAC,OAAO,EAAE,mBAAU,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;IACpD,CAAC;CACF;AAJD,gDAIC;AAED,MAAa,iBAAkB,SAAQ,YAAY;IACjD,YAAY,QAAQ,GAAG,UAAU;QAC/B,KAAK,CAAC,GAAG,QAAQ,YAAY,EAAE,mBAAU,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;IACpE,CAAC;CACF;AAJD,8CAIC;AAED,MAAa,iBAAkB,SAAQ,YAAY;IACjD,YAAY,OAAO,GAAG,yBAAyB;QAC7C,KAAK,CAAC,OAAO,EAAE,mBAAU,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;IAClD,CAAC;CACF;AAJD,8CAIC;AAED,MAAa,4BAA6B,SAAQ,YAAY;IAC5D,YAAY,OAAO,GAAG,sBAAsB,EAAE,OAA0B;QACtE,KAAK,CACH,OAAO,EACP,mBAAU,CAAC,oBAAoB,EAC/B,sBAAsB,EACtB,OAAO,CACR,CAAC;IACJ,CAAC;CACF;AATD,oEASC;AAED,MAAa,wBAAyB,SAAQ,YAAY;IACxD,YAAY,OAAO,GAAG,mBAAmB;QACvC,KAAK,CAAC,OAAO,EAAE,mBAAU,CAAC,iBAAiB,EAAE,mBAAmB,CAAC,CAAC;IACpE,CAAC;CACF;AAJD,4DAIC;AAED,MAAa,uBAAwB,SAAQ,YAAY;IACvD,YAAY,OAAO,GAAG,uBAAuB;QAC3C,KAAK,CAAC,OAAO,EAAE,mBAAU,CAAC,qBAAqB,EAAE,uBAAuB,CAAC,CAAC;IAC5E,CAAC;CACF;AAJD,0DAIC;AAED,MAAa,2BAA4B,SAAQ,YAAY;IAC3D,YAAY,OAAO,GAAG,qBAAqB;QACzC,KAAK,CAAC,OAAO,EAAE,mBAAU,CAAC,mBAAmB,EAAE,qBAAqB,CAAC,CAAC;IACxE,CAAC;CACF;AAJD,kEAIC"}

package/dist/exceptions/index.d.ts

@@ -0,0 +1,2 @@
+export * from './api.exception';
+export * from './validation.exception';

package/dist/exceptions/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+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 });
+__exportStar(require("./api.exception"), exports);
+__exportStar(require("./validation.exception"), exports);
+//# sourceMappingURL=index.js.map

package/dist/exceptions/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/exceptions/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,kDAAgC;AAChC,yDAAuC"}

package/dist/exceptions/validation.exception.d.ts

@@ -0,0 +1,6 @@
+import { ApiException } from './api.exception';
+import { ApiErrorDetail } from '../interfaces/api-response.interface';
+export declare class ValidationException extends ApiException {
+    constructor(details: ApiErrorDetail[]);
+    static fromConstraints(constraints: Record<string, Record<string, string>>): ValidationException;
+}

package/dist/exceptions/validation.exception.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ValidationException = void 0;
+const common_1 = require("@nestjs/common");
+const api_exception_1 = require("./api.exception");
+class ValidationException extends api_exception_1.ApiException {
+    constructor(details) {
+        super('Validation failed', common_1.HttpStatus.BAD_REQUEST, 'VALIDATION_ERROR', details);
+    }
+    static fromConstraints(constraints) {
+        const details = Object.entries(constraints).map(([field, messages]) => ({
+            field,
+            message: Object.values(messages).join(', '),
+        }));
+        return new ValidationException(details);
+    }
+}
+exports.ValidationException = ValidationException;
+//# sourceMappingURL=validation.exception.js.map

package/dist/exceptions/validation.exception.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.exception.js","sourceRoot":"","sources":["../../src/exceptions/validation.exception.ts"],"names":[],"mappings":";;;AAAA,2CAA4C;AAC5C,mDAA+C;AAG/C,MAAa,mBAAoB,SAAQ,4BAAY;IACnD,YAAY,OAAyB;QACnC,KAAK,CAAC,mBAAmB,EAAE,mBAAU,CAAC,WAAW,EAAE,kBAAkB,EAAE,OAAO,CAAC,CAAC;IAClF,CAAC;IAED,MAAM,CAAC,eAAe,CACpB,WAAmD;QAEnD,MAAM,OAAO,GAAqB,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,GAAG,CAC/D,CAAC,CAAC,KAAK,EAAE,QAAQ,CAAC,EAAE,EAAE,CAAC,CAAC;YACtB,KAAK;YACL,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;SAC5C,CAAC,CACH,CAAC;QACF,OAAO,IAAI,mBAAmB,CAAC,OAAO,CAAC,CAAC;IAC1C,CAAC;CACF;AAhBD,kDAgBC"}

package/dist/filters/global-exception.filter.d.ts

@@ -0,0 +1,12 @@
+import { ArgumentsHost, ExceptionFilter } from '@nestjs/common';
+import { ForgeOptions } from '../interfaces/api-response.interface';
+export declare class ForgeExceptionFilter implements ExceptionFilter {
+    private readonly options;
+    private readonly logger;
+    constructor(options?: ForgeOptions);
+    catch(exception: unknown, host: ArgumentsHost): void;
+    private buildMeta;
+    private buildErrorResponse;
+    private extractHttpExceptionMessage;
+    private extractValidationDetails;
+}