@ballistix.digital/exception-mapper 0.0.1 → 0.2.0

package/CHANGELOG.md

@@ -5,3 +5,19 @@ All notable changes to this package are recorded here. The format follows
 follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## Unreleased
+
+## 0.1.0 - 2026-09-07
+
+### Added
+
+- `ExceptionModule`, a global NestJS module with `forRoot` and `forRootAsync`.
+- `ExceptionMapperRegistry`, which holds the mappers in order and turns any
+  thrown value into a coded `BaseException` or into the `ExceptionDto`
+  envelope.
+- `ExceptionDtoMapper`, which builds the envelope from one exception and never
+  throws.
+- The four mappers: `BaseExceptionMapper`, `ValidationExceptionMapper`,
+  `DatabaseExceptionMapper` and `GenericExceptionMapper`, plus the
+  `ExceptionMapper` interface a further mapper implements.
+- `ExceptionModuleOptions.exposeErrorDetails`, which adds the raw database
+  driver message as a second detail of `DATABASE_ERROR`.

package/README.md

@@ -1,6 +1,242 @@
 # @ballistix.digital/exception-mapper
 
 A NestJS module that maps any thrown value to a coded `BaseException` and to
-the `ExceptionDto` envelope, for HTTP filters and task processors.
+the `ExceptionDto` envelope, for HTTP filters and task processors. A **mapper**
+turns one kind of thrown value into an exception, and the **registry** holds
+the mappers in order. The exception classes, the codes and the envelope live
+in [`@ballistix.digital/exception-types`](../exception-types/README.md).
 
-The consumer guide follows with the first release.
+This file is the consumer guide. [docs/](../docs/index.md) describes how the
+package is built.
+
+## Install
+
+```bash
+npm install @ballistix.digital/exception-mapper @ballistix.digital/exception-types
+```
+
+The package needs Node 22.12 or later. Install these peer dependencies in the
+application.
+
+| Peer | Range |
+| --- | --- |
+| `@ballistix.digital/exception-types` | the release each published manifest pins |
+| `@nestjs/common` | `^11` |
+| `class-validator` | `^0.15.1` |
+| `typeorm` | `>=0.3.0 <2.0.0` |
+| `reflect-metadata` | `^0.2.2` |
+
+The application throws the exception classes of the types package, and this
+package maps to the same classes. A publish of `exception-mapper` pins the
+`exception-types` version of the same build.
+
+## Register the module
+
+Register the module once, at the root of the application. It is global, so a
+service in any feature module injects `ExceptionMapperRegistry` without an
+import.
+
+```ts
+import { Module } from '@nestjs/common';
+import { ExceptionModule } from '@ballistix.digital/exception-mapper';
+
+@Module({
+	imports: [ExceptionModule.forRoot()],
+})
+export class AppModule {}
+```
+
+`forRootAsync` takes the options from a factory, so a `ConfigService` can
+decide them:
+
+```ts
+import { Module } from '@nestjs/common';
+import { ConfigModule, ConfigService } from '@nestjs/config';
+import { ExceptionModule } from '@ballistix.digital/exception-mapper';
+
+@Module({
+	imports: [
+		ExceptionModule.forRootAsync({
+			imports: [ConfigModule],
+			inject: [ConfigService],
+			useFactory: (config: ConfigService) => ({
+				exposeErrorDetails: config.get('EXPOSE_ERROR_DETAILS') === 'true',
+			}),
+		}),
+	],
+})
+export class AppModule {}
+```
+
+The raw driver message of a `QueryFailedError` can carry SQL text and
+constraint names. With `exposeErrorDetails` on, the database mapper adds that
+message as a second entry of `errors`, and the `title` stays the generic
+message. CAUTION: If an untrusted client reads the response, keep
+`exposeErrorDetails` off. The option is off by default.
+
+## From a thrown value to the envelope
+
+The registry asks each mapper in one order, and the first match wins.
+
+```mermaid
+flowchart TD
+    thrown["a thrown value"] --> base{"BaseExceptionMapper<br/>supports?"}
+    base -- yes --> same["the same BaseException"]
+    base -- no --> validation{"ValidationExceptionMapper<br/>supports?"}
+    validation -- yes --> failed["ValidationFailedException<br/>400"]
+    validation -- no --> database{"DatabaseExceptionMapper<br/>supports?"}
+    database -- yes --> dbError["DatabaseErrorException<br/>400 for SQLSTATE class 22, 23, P0<br/>500 for the rest"]
+    database -- no --> generic["GenericExceptionMapper<br/>GenericErrorException<br/>the status of the value, else 500"]
+    same --> dtoMapper["ExceptionDtoMapper"]
+    failed --> dtoMapper
+    dbError --> dtoMapper
+    generic --> dtoMapper
+    dtoMapper --> envelope["the ExceptionDto envelope"]
+    envelope --> retry{"status >= 500?"}
+    retry -- yes --> again["a task processor repeats the attempt"]
+    retry -- no --> stop["a task processor fails the task"]
+```
+
+Look at the last branch: the status the mappers give is also the retry rule a
+task processor reads.
+
+The database mapper reads the first two characters of the Postgres SQLSTATE,
+its class. Class 22 is a data exception, such as a malformed uuid. Class 23 is
+an integrity constraint violation, such as a unique or foreign key breach.
+Class P0 is a `RAISE EXCEPTION` from PL/pgSQL. All three mean the statement
+itself was wrong, which is the fault of the request, so they give 400. A
+deadlock or a connection failure gives 500.
+
+`ValidationExceptionMapper` matches the `ValidationException` that
+`convertAndValidate` throws, and gives one detail for each field and rule that
+failed. `GenericExceptionMapper` is the fallback the registry uses when no mapper in
+the list supports the value, so `map()` never returns `undefined`.
+
+## Write your HTTP filter
+
+The package ships no `@Catch()` filter. Write one in the application:
+
+```ts
+import { ArgumentsHost, Catch, ExceptionFilter } from '@nestjs/common';
+import { ExceptionMapperRegistry } from '@ballistix.digital/exception-mapper';
+import { Response } from 'express';
+
+@Catch()
+export class HttpExceptionFilter implements ExceptionFilter {
+	constructor(private readonly registry: ExceptionMapperRegistry) {}
+
+	public catch(exception: unknown, host: ArgumentsHost): void {
+		const response = host.switchToHttp().getResponse<Response>();
+		const envelope = this.registry.toExceptionDto(exception);
+
+		response.status(envelope.status).json(envelope);
+	}
+}
+```
+
+The filter stays in the application, so a breakpoint on the raw thrown value
+sits in application code. What the filter logs, and what request context it
+adds, is the decision of the application. See
+[ADR 0002](../docs/decisions/0002-filter-stays-in-the-app.md).
+
+Register it as the global filter:
+
+```ts
+import { APP_FILTER } from '@nestjs/core';
+
+@Module({
+	imports: [ExceptionModule.forRoot()],
+	providers: [{ provide: APP_FILTER, useClass: HttpExceptionFilter }],
+})
+export class AppModule {}
+```
+
+## Use it in a task processor
+
+A task processor has no response to write. It stores the envelope on the row,
+and the status decides whether another attempt can succeed:
+
+```ts
+@Injectable()
+export class ReportTaskProcessor {
+	constructor(
+		private readonly registry: ExceptionMapperRegistry,
+		private readonly repository: Repository<ReportTask>,
+	) {}
+
+	public async run(task: ReportTask): Promise<void> {
+		try {
+			await this.build(task);
+		} catch (error) {
+			const envelope = this.registry.toExceptionDto(error);
+
+			// A 5xx is a server fault, so the attempt can be repeated. A 4xx is the
+			// input's fault and repeats with the same result.
+			task.processingError = envelope;
+			task.status = envelope.status >= 500 ? TaskStatus.PENDING : TaskStatus.FAILED;
+
+			await this.repository.save(task);
+		}
+	}
+}
+```
+
+The retry rule belongs to the application. This package only says which status
+the thrown value earns.
+
+## Test with the registry
+
+The registry is a plain class. A unit test builds it by hand, with no NestJS
+bootstrap:
+
+```ts
+const registry = new ExceptionMapperRegistry(
+	new BaseExceptionMapper(),
+	new ValidationExceptionMapper(),
+	new DatabaseExceptionMapper({ exposeErrorDetails: false }),
+	new GenericExceptionMapper(),
+	new ExceptionDtoMapper(),
+);
+
+expect(registry.toExceptionDto(new Error('boom'))).toMatchObject({
+	code: ExceptionCodeEnum.GENERIC_ERROR,
+	status: 500,
+});
+```
+
+`DatabaseExceptionMapper` is the only mapper with a constructor argument. Pass
+`{}` when the test does not care about the driver message.
+
+## API reference
+
+Everything below comes from the package root.
+
+| Export | What it does |
+| --- | --- |
+| `ExceptionModule.forRoot(options?)` | Registers the module with options that are already known |
+| `ExceptionModule.forRootAsync(options)` | The same, with `imports`, `inject` and a `useFactory` |
+| `ExceptionModuleOptions` | `{ exposeErrorDetails?: boolean }` |
+| `ExceptionModuleAsyncOptions` | `{ imports?, inject?, useFactory }` |
+| `EXCEPTION_MODULE_OPTIONS` | The injection token of the resolved options |
+| `ExceptionMapperRegistry` | Holds the mappers in order. `map(error)` gives the exception, `toExceptionDto(error)` gives the envelope |
+| `ExceptionDtoMapper` | `map(exception)` turns one `BaseException` into the envelope |
+| `ExceptionMapper<TError>` | The interface a mapper implements: `supports(error)` and `map(error)` |
+| `BaseExceptionMapper` | Maps a `BaseException` to itself |
+| `ValidationExceptionMapper` | Maps a `ValidationException` to `ValidationFailedException` |
+| `DatabaseExceptionMapper` | Maps a TypeORM `QueryFailedError` to `DatabaseErrorException` |
+| `GenericExceptionMapper` | Maps anything else to `GenericErrorException` |
+
+## Guarantees
+
+- `toExceptionDto()` never throws. A detail that fails its own validation
+  travels raw into the envelope instead of replacing the error the caller
+  handles.
+- First match wins. The order of the mappers is a constructor argument, not a
+  search.
+- The generic mapper is the fallback for a value no mapper in the list
+  supports, so `map()` always returns a `BaseException`.
+- A validation rule with no `ValidationRuleEnum` member becomes `UNKNOWN`, so
+  a new class-validator rule cannot break the mapping.
+- The same thrown value gives the same envelope on every path. An HTTP
+  response and a stored task error read alike.
+- The package ships no filter, no logger and no HTTP dependency.

package/dist/index.d.ts

@@ -1 +1,9 @@
-export {};
+export { ExceptionModule } from './module/exception/exception.module';
+export { EXCEPTION_MODULE_OPTIONS, ExceptionModuleAsyncOptions, ExceptionModuleOptions, } from './module/exception/domain/model/exceptionModuleOptions';
+export { ExceptionMapperRegistry } from './module/exception/service/exceptionMapperRegistry.service';
+export { ExceptionDtoMapper } from './module/exception/mapper/exceptionDto.mapper';
+export { ExceptionMapper } from './module/exception/mapper/exceptionMapper.interface';
+export { BaseExceptionMapper } from './module/exception/mapper/baseException.mapper';
+export { ValidationExceptionMapper } from './module/exception/mapper/validationException.mapper';
+export { DatabaseExceptionMapper } from './module/exception/mapper/databaseException.mapper';
+export { GenericExceptionMapper } from './module/exception/mapper/genericException.mapper';

package/dist/index.js

@@ -1,2 +1,19 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.GenericExceptionMapper = exports.DatabaseExceptionMapper = exports.ValidationExceptionMapper = exports.BaseExceptionMapper = exports.ExceptionDtoMapper = exports.ExceptionMapperRegistry = exports.EXCEPTION_MODULE_OPTIONS = exports.ExceptionModule = void 0;
+var exception_module_1 = require("./module/exception/exception.module");
+Object.defineProperty(exports, "ExceptionModule", { enumerable: true, get: function () { return exception_module_1.ExceptionModule; } });
+var exceptionModuleOptions_1 = require("./module/exception/domain/model/exceptionModuleOptions");
+Object.defineProperty(exports, "EXCEPTION_MODULE_OPTIONS", { enumerable: true, get: function () { return exceptionModuleOptions_1.EXCEPTION_MODULE_OPTIONS; } });
+var exceptionMapperRegistry_service_1 = require("./module/exception/service/exceptionMapperRegistry.service");
+Object.defineProperty(exports, "ExceptionMapperRegistry", { enumerable: true, get: function () { return exceptionMapperRegistry_service_1.ExceptionMapperRegistry; } });
+var exceptionDto_mapper_1 = require("./module/exception/mapper/exceptionDto.mapper");
+Object.defineProperty(exports, "ExceptionDtoMapper", { enumerable: true, get: function () { return exceptionDto_mapper_1.ExceptionDtoMapper; } });
+var baseException_mapper_1 = require("./module/exception/mapper/baseException.mapper");
+Object.defineProperty(exports, "BaseExceptionMapper", { enumerable: true, get: function () { return baseException_mapper_1.BaseExceptionMapper; } });
+var validationException_mapper_1 = require("./module/exception/mapper/validationException.mapper");
+Object.defineProperty(exports, "ValidationExceptionMapper", { enumerable: true, get: function () { return validationException_mapper_1.ValidationExceptionMapper; } });
+var databaseException_mapper_1 = require("./module/exception/mapper/databaseException.mapper");
+Object.defineProperty(exports, "DatabaseExceptionMapper", { enumerable: true, get: function () { return databaseException_mapper_1.DatabaseExceptionMapper; } });
+var genericException_mapper_1 = require("./module/exception/mapper/genericException.mapper");
+Object.defineProperty(exports, "GenericExceptionMapper", { enumerable: true, get: function () { return genericException_mapper_1.GenericExceptionMapper; } });

package/dist/module/exception/domain/model/exceptionModuleOptions.d.ts

@@ -0,0 +1,10 @@
+import { ModuleMetadata } from '@nestjs/common';
+export interface ExceptionModuleOptions {
+    exposeErrorDetails?: boolean;
+}
+export interface ExceptionModuleAsyncOptions {
+    imports?: ModuleMetadata['imports'];
+    inject?: any[];
+    useFactory: (...args: any[]) => ExceptionModuleOptions | Promise<ExceptionModuleOptions>;
+}
+export declare const EXCEPTION_MODULE_OPTIONS: unique symbol;

package/dist/module/exception/domain/model/exceptionModuleOptions.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXCEPTION_MODULE_OPTIONS = void 0;
+exports.EXCEPTION_MODULE_OPTIONS = Symbol('EXCEPTION_MODULE_OPTIONS');

package/dist/module/exception/exception.module.d.ts

@@ -0,0 +1,7 @@
+import { DynamicModule } from '@nestjs/common';
+import { ExceptionModuleAsyncOptions, ExceptionModuleOptions } from './domain/model/exceptionModuleOptions';
+export declare class ExceptionModule {
+    static forRoot(options?: ExceptionModuleOptions): DynamicModule;
+    static forRootAsync(options: ExceptionModuleAsyncOptions): DynamicModule;
+    private static createMapperProviders;
+}

package/dist/module/exception/exception.module.js

@@ -0,0 +1,57 @@
+"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 ExceptionModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExceptionModule = void 0;
+const common_1 = require("@nestjs/common");
+const exceptionModuleOptions_1 = require("./domain/model/exceptionModuleOptions");
+const baseException_mapper_1 = require("./mapper/baseException.mapper");
+const validationException_mapper_1 = require("./mapper/validationException.mapper");
+const databaseException_mapper_1 = require("./mapper/databaseException.mapper");
+const genericException_mapper_1 = require("./mapper/genericException.mapper");
+const exceptionDto_mapper_1 = require("./mapper/exceptionDto.mapper");
+const exceptionMapperRegistry_service_1 = require("./service/exceptionMapperRegistry.service");
+let ExceptionModule = ExceptionModule_1 = class ExceptionModule {
+    static forRoot(options = {}) {
+        return {
+            module: ExceptionModule_1,
+            providers: [{ provide: exceptionModuleOptions_1.EXCEPTION_MODULE_OPTIONS, useValue: options }, ...this.createMapperProviders()],
+            exports: [exceptionMapperRegistry_service_1.ExceptionMapperRegistry, exceptionDto_mapper_1.ExceptionDtoMapper],
+        };
+    }
+    static forRootAsync(options) {
+        return {
+            module: ExceptionModule_1,
+            imports: options.imports ?? [],
+            providers: [
+                {
+                    provide: exceptionModuleOptions_1.EXCEPTION_MODULE_OPTIONS,
+                    useFactory: options.useFactory,
+                    inject: options.inject ?? [],
+                },
+                ...this.createMapperProviders(),
+            ],
+            exports: [exceptionMapperRegistry_service_1.ExceptionMapperRegistry, exceptionDto_mapper_1.ExceptionDtoMapper],
+        };
+    }
+    static createMapperProviders() {
+        return [
+            baseException_mapper_1.BaseExceptionMapper,
+            validationException_mapper_1.ValidationExceptionMapper,
+            databaseException_mapper_1.DatabaseExceptionMapper,
+            genericException_mapper_1.GenericExceptionMapper,
+            exceptionDto_mapper_1.ExceptionDtoMapper,
+            exceptionMapperRegistry_service_1.ExceptionMapperRegistry,
+        ];
+    }
+};
+exports.ExceptionModule = ExceptionModule;
+exports.ExceptionModule = ExceptionModule = ExceptionModule_1 = __decorate([
+    (0, common_1.Global)(),
+    (0, common_1.Module)({})
+], ExceptionModule);

package/dist/module/exception/mapper/baseException.mapper.d.ts

@@ -0,0 +1,6 @@
+import { BaseException } from '@ballistix.digital/exception-types';
+import { ExceptionMapper } from './exceptionMapper.interface';
+export declare class BaseExceptionMapper implements ExceptionMapper<BaseException<unknown>> {
+    supports(error: unknown): error is BaseException<unknown>;
+    map(error: BaseException<unknown>): BaseException<unknown>;
+}

package/dist/module/exception/mapper/baseException.mapper.js

@@ -0,0 +1,23 @@
+"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;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseExceptionMapper = void 0;
+const common_1 = require("@nestjs/common");
+const exception_types_1 = require("@ballistix.digital/exception-types");
+let BaseExceptionMapper = class BaseExceptionMapper {
+    supports(error) {
+        return error instanceof exception_types_1.BaseException;
+    }
+    map(error) {
+        return error;
+    }
+};
+exports.BaseExceptionMapper = BaseExceptionMapper;
+exports.BaseExceptionMapper = BaseExceptionMapper = __decorate([
+    (0, common_1.Injectable)()
+], BaseExceptionMapper);

package/dist/module/exception/mapper/databaseException.mapper.d.ts

@@ -0,0 +1,10 @@
+import { QueryFailedError } from 'typeorm';
+import { DatabaseErrorException } from '@ballistix.digital/exception-types';
+import { ExceptionModuleOptions } from '../domain/model/exceptionModuleOptions';
+import { ExceptionMapper } from './exceptionMapper.interface';
+export declare class DatabaseExceptionMapper implements ExceptionMapper<QueryFailedError> {
+    private readonly options;
+    constructor(options: ExceptionModuleOptions);
+    supports(error: unknown): error is QueryFailedError;
+    map(error: QueryFailedError): DatabaseErrorException;
+}

package/dist/module/exception/mapper/databaseException.mapper.js

@@ -0,0 +1,45 @@
+"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 __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DatabaseExceptionMapper = void 0;
+const common_1 = require("@nestjs/common");
+const typeorm_1 = require("typeorm");
+const exception_types_1 = require("@ballistix.digital/exception-types");
+const exceptionModuleOptions_1 = require("../domain/model/exceptionModuleOptions");
+let DatabaseExceptionMapper = class DatabaseExceptionMapper {
+    constructor(options) {
+        this.options = options;
+    }
+    supports(error) {
+        return error instanceof typeorm_1.QueryFailedError;
+    }
+    map(error) {
+        const driverMessage = this.options.exposeErrorDetails ? error.message : undefined;
+        const sqlStateClass = String(error['code'] ?? '').slice(0, 2);
+        switch (sqlStateClass) {
+            case '22':
+            case '23':
+            case 'P0':
+                return new exception_types_1.DatabaseErrorException(undefined, 400, driverMessage);
+            default:
+                return new exception_types_1.DatabaseErrorException(undefined, 500, driverMessage);
+        }
+    }
+};
+exports.DatabaseExceptionMapper = DatabaseExceptionMapper;
+exports.DatabaseExceptionMapper = DatabaseExceptionMapper = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)(exceptionModuleOptions_1.EXCEPTION_MODULE_OPTIONS)),
+    __metadata("design:paramtypes", [Object])
+], DatabaseExceptionMapper);

package/dist/module/exception/mapper/exceptionDto.mapper.d.ts

@@ -0,0 +1,4 @@
+import { BaseException, ExceptionDto } from '@ballistix.digital/exception-types';
+export declare class ExceptionDtoMapper {
+    map(exception: BaseException<unknown>): ExceptionDto;
+}

package/dist/module/exception/mapper/exceptionDto.mapper.js

@@ -0,0 +1,31 @@
+"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;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExceptionDtoMapper = void 0;
+const common_1 = require("@nestjs/common");
+const exception_types_1 = require("@ballistix.digital/exception-types");
+let ExceptionDtoMapper = class ExceptionDtoMapper {
+    map(exception) {
+        const plain = {
+            title: exception.message,
+            status: exception.status,
+            code: exception.code,
+            errors: exception.errors,
+        };
+        try {
+            return (0, exception_types_1.convertAndValidate)(exception_types_1.ExceptionDto, plain, true);
+        }
+        catch {
+            return plain;
+        }
+    }
+};
+exports.ExceptionDtoMapper = ExceptionDtoMapper;
+exports.ExceptionDtoMapper = ExceptionDtoMapper = __decorate([
+    (0, common_1.Injectable)()
+], ExceptionDtoMapper);

package/dist/module/exception/mapper/exceptionMapper.interface.d.ts

@@ -0,0 +1,5 @@
+import { BaseException } from '@ballistix.digital/exception-types';
+export interface ExceptionMapper<TError = unknown> {
+    supports(error: unknown): error is TError;
+    map(error: TError): BaseException<unknown>;
+}

package/dist/module/exception/mapper/exceptionMapper.interface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/module/exception/mapper/genericException.mapper.d.ts

@@ -0,0 +1,6 @@
+import { GenericErrorException } from '@ballistix.digital/exception-types';
+import { ExceptionMapper } from './exceptionMapper.interface';
+export declare class GenericExceptionMapper implements ExceptionMapper<unknown> {
+    supports(_error: unknown): _error is unknown;
+    map(error: unknown): GenericErrorException;
+}

package/dist/module/exception/mapper/genericException.mapper.js

@@ -0,0 +1,25 @@
+"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;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GenericExceptionMapper = void 0;
+const common_1 = require("@nestjs/common");
+const exception_types_1 = require("@ballistix.digital/exception-types");
+let GenericExceptionMapper = class GenericExceptionMapper {
+    supports(_error) {
+        return true;
+    }
+    map(error) {
+        const message = String(error?.message ?? error);
+        const status = Number(error?.status) || 500;
+        return new exception_types_1.GenericErrorException(message, status);
+    }
+};
+exports.GenericExceptionMapper = GenericExceptionMapper;
+exports.GenericExceptionMapper = GenericExceptionMapper = __decorate([
+    (0, common_1.Injectable)()
+], GenericExceptionMapper);

package/dist/module/exception/mapper/validationException.mapper.d.ts

@@ -0,0 +1,6 @@
+import { ValidationException, ValidationFailedException } from '@ballistix.digital/exception-types';
+import { ExceptionMapper } from './exceptionMapper.interface';
+export declare class ValidationExceptionMapper implements ExceptionMapper<ValidationException> {
+    supports(error: unknown): error is ValidationException;
+    map(error: ValidationException): ValidationFailedException;
+}

package/dist/module/exception/mapper/validationException.mapper.js

@@ -0,0 +1,31 @@
+"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;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ValidationExceptionMapper = void 0;
+const common_1 = require("@nestjs/common");
+const exception_types_1 = require("@ballistix.digital/exception-types");
+const collectValidationDetails = (error) => {
+    const ownDetails = Object.keys(error.constraints ?? {}).map((ruleName) => ({
+        inputField: error.property,
+        rule: exception_types_1.validationRuleByName[ruleName] ?? exception_types_1.ValidationRuleEnum.UNKNOWN,
+        args: error.contexts?.[ruleName],
+    }));
+    return ownDetails.concat((error.children ?? []).flatMap(collectValidationDetails));
+};
+let ValidationExceptionMapper = class ValidationExceptionMapper {
+    supports(error) {
+        return error instanceof exception_types_1.ValidationException;
+    }
+    map(error) {
+        return new exception_types_1.ValidationFailedException(error.getValidationErrors().flatMap(collectValidationDetails));
+    }
+};
+exports.ValidationExceptionMapper = ValidationExceptionMapper;
+exports.ValidationExceptionMapper = ValidationExceptionMapper = __decorate([
+    (0, common_1.Injectable)()
+], ValidationExceptionMapper);

package/dist/module/exception/service/exceptionMapperRegistry.service.d.ts

@@ -0,0 +1,14 @@
+import { BaseException, ExceptionDto } from '@ballistix.digital/exception-types';
+import { BaseExceptionMapper } from '../mapper/baseException.mapper';
+import { ValidationExceptionMapper } from '../mapper/validationException.mapper';
+import { DatabaseExceptionMapper } from '../mapper/databaseException.mapper';
+import { GenericExceptionMapper } from '../mapper/genericException.mapper';
+import { ExceptionDtoMapper } from '../mapper/exceptionDto.mapper';
+export declare class ExceptionMapperRegistry {
+    private readonly genericExceptionMapper;
+    private readonly exceptionDtoMapper;
+    private readonly mappers;
+    constructor(baseExceptionMapper: BaseExceptionMapper, validationExceptionMapper: ValidationExceptionMapper, databaseExceptionMapper: DatabaseExceptionMapper, genericExceptionMapper: GenericExceptionMapper, exceptionDtoMapper: ExceptionDtoMapper);
+    map(error: unknown): BaseException<unknown>;
+    toExceptionDto(error: unknown): ExceptionDto;
+}

package/dist/module/exception/service/exceptionMapperRegistry.service.js

@@ -0,0 +1,41 @@
+"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 __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.ExceptionMapperRegistry = void 0;
+const common_1 = require("@nestjs/common");
+const baseException_mapper_1 = require("../mapper/baseException.mapper");
+const validationException_mapper_1 = require("../mapper/validationException.mapper");
+const databaseException_mapper_1 = require("../mapper/databaseException.mapper");
+const genericException_mapper_1 = require("../mapper/genericException.mapper");
+const exceptionDto_mapper_1 = require("../mapper/exceptionDto.mapper");
+let ExceptionMapperRegistry = class ExceptionMapperRegistry {
+    constructor(baseExceptionMapper, validationExceptionMapper, databaseExceptionMapper, genericExceptionMapper, exceptionDtoMapper) {
+        this.genericExceptionMapper = genericExceptionMapper;
+        this.exceptionDtoMapper = exceptionDtoMapper;
+        this.mappers = [baseExceptionMapper, validationExceptionMapper, databaseExceptionMapper];
+    }
+    map(error) {
+        const mapper = this.mappers.find((candidate) => candidate.supports(error));
+        return (mapper ?? this.genericExceptionMapper).map(error);
+    }
+    toExceptionDto(error) {
+        return this.exceptionDtoMapper.map(this.map(error));
+    }
+};
+exports.ExceptionMapperRegistry = ExceptionMapperRegistry;
+exports.ExceptionMapperRegistry = ExceptionMapperRegistry = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [baseException_mapper_1.BaseExceptionMapper,
+        validationException_mapper_1.ValidationExceptionMapper,
+        databaseException_mapper_1.DatabaseExceptionMapper,
+        genericException_mapper_1.GenericExceptionMapper,
+        exceptionDto_mapper_1.ExceptionDtoMapper])
+], ExceptionMapperRegistry);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ballistix.digital/exception-mapper",
-	"version": "0.0.1",
+	"version": "0.2.0",
 	"description": "A NestJS module that maps any thrown value to a coded BaseException and to the ExceptionDto envelope, for HTTP filters and task processors.",
 	"license": "MIT",
 	"repository": {
@@ -30,8 +30,8 @@
 		"build": "rm -rf dist && tsc -p tsconfig.build.json"
 	},
 	"peerDependencies": {
-		"@ballistix.digital/exception-types": "^0.1.0",
-		"@nestjs/common": "^11",
+		"@ballistix.digital/exception-types": "^0.2.0",
+		"@nestjs/common": "^11 || ^12",
 		"class-validator": "^0.15.1",
 		"reflect-metadata": "^0.2.2",
 		"typeorm": ">=0.3.0 <2.0.0"