Merge pull request #469 from lenneTech/DEV-43

11.9.0: Add ErrorCodeModule for centralized error handling with i18n translations and REST API

Author: kaihaase

docs/error-codes.md

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.8.0",
+  "version": "11.9.0",
   "description": "Modern, fast, powerful Node.js web framework in TypeScript based on Nest with a GraphQL API and a connection to MongoDB (or other databases).",
   "keywords": [
     "node",
@@ -21,7 +21,7 @@
     "build:pack": "npm pack && echo 'use file:/ROOT_PATH_TO_TGZ_FILE to integrate the package'",
     "build:dev": "npm run build && yalc push --private",
     "docs": "npm run docs:ci && open http://127.0.0.1:8080/ && open ./public/index.html && compodoc -p tsconfig.json -s ",
-    "docs:bootstrap": "node extras/update-spectaql-version.mjs && npx -y spectaql ./spectaql.yml",
+    "docs:bootstrap": "node extras/update-spectaql-version.mjs && node scripts/run-spectaql.mjs",
     "docs:ci": "ts-node ./scripts/init-server.ts && npm run docs:bootstrap && compodoc -p tsconfig.json",
     "format": "prettier --write 'src/**/*.ts'",
     "format:staged": "pretty-quick --staged",

package-lock.json

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+/**
+ * Wrapper script for spectaql that filters Sass deprecation warnings
+ *
+ * Sass deprecation warnings come from spectaql's internal dependencies
+ * and cannot be silenced through configuration. This script filters them
+ * from the output while preserving the exit code.
+ */
+
+import { spawn } from 'child_process';
+
+const spectaql = spawn('npx', ['-y', 'spectaql', './spectaql.yml'], {
+  stdio: ['inherit', 'pipe', 'pipe'],
+});
+
+// Patterns to filter from output (Sass deprecation warnings)
+const filterPatterns = [
+  'DEPRECATION WARNING',
+  'More info and automated migrator:',
+  'sass-lang.com',
+  '───', // Box drawing characters
+  '│', // Vertical line in Sass output
+  '╵', // Bottom corner
+  '╷', // Top corner
+  '@import', // Import statements in warnings
+  'root stylesheet',
+];
+
+function shouldFilter(line) {
+  return filterPatterns.some((pattern) => line.includes(pattern));
+}
+
+function processOutput(data, stream) {
+  const lines = data.toString().split('\n');
+  const filtered = lines.filter((line) => !shouldFilter(line));
+  const output = filtered.join('\n');
+  if (output.trim()) {
+    stream.write(output + (output.endsWith('\n') ? '' : '\n'));
+  }
+}
+
+spectaql.stdout.on('data', (data) => {
+  processOutput(data, process.stdout);
+});
+
+spectaql.stderr.on('data', (data) => {
+  processOutput(data, process.stderr);
+});
+
+spectaql.on('close', (code) => {
+  process.exit(code);
+});

package.json

@@ -11,7 +11,7 @@ servers:
 info:
   title: lT Nest Server
   description: Modern, fast, powerful Node.js web framework in TypeScript based on Nest with a GraphQL API and a connection to MongoDB (or other databases).
-  version: 11.8.0
+  version: 11.9.0
   contact:
     name: lenne.Tech GmbH
     url: https://lenne.tech

scripts/run-spectaql.mjs

@@ -262,6 +262,10 @@ const config: { [env: string]: IServerOptions } = {
       verificationLink: 'http://localhost:4200/user/verification',
     },
     env: 'local',
+    // Disable auto-registration to allow Server ErrorCodeModule with SRV_* codes
+    errorCode: {
+      autoRegister: false,
+    },
     execAfterInit: 'npm run docs:bootstrap',
     filter: {
       maxLimit: null,

spectaql.yml

@@ -22,6 +22,7 @@ import { TemplateService } from './core/common/services/template.service';
 import { BetterAuthUserMapper } from './core/modules/better-auth/better-auth-user.mapper';
 import { BetterAuthModule } from './core/modules/better-auth/better-auth.module';
 import { BetterAuthService } from './core/modules/better-auth/better-auth.service';
+import { ErrorCodeModule } from './core/modules/error-code/error-code.module';
 import { CoreHealthCheckModule } from './core/modules/health-check/core-health-check.module';
 
 /**
@@ -226,6 +227,21 @@ export class CoreModule implements NestModule {
         Object.assign({ driver: ApolloDriver }, config.graphQl.driver, config.graphQl.options),
       ),
     ];
+
+    // Add ErrorCodeModule based on configuration
+    // autoRegister defaults to true (backward compatible)
+    const errorCodeConfig = config.errorCode;
+    const isErrorCodeAutoRegister = errorCodeConfig?.autoRegister !== false;
+
+    if (isErrorCodeAutoRegister) {
+      // Always use forRoot() - it registers the controller and handles configuration
+      imports.push(
+        ErrorCodeModule.forRoot({
+          additionalErrorRegistry: errorCodeConfig?.additionalErrorRegistry,
+        }),
+      );
+    }
+
     if (config.healthCheck) {
       imports.push(CoreHealthCheckModule);
     }

src/config.env.ts

@@ -589,6 +589,70 @@ export interface IBetterAuthUserField {
   type: BetterAuthFieldType;
 }
 
+/**
+ * Interface for Error Code module configuration
+ *
+ * Controls how the ErrorCodeModule is registered and configured.
+ *
+ * @since 11.9.0
+ */
+export interface IErrorCode {
+  /**
+   * Additional error registry to merge with core LTNS_* errors
+   *
+   * Use this to add project-specific error codes with a custom prefix.
+   *
+   * @example
+   * ```typescript
+   * const ProjectErrors = {
+   *   ORDER_NOT_FOUND: {
+   *     code: 'PROJ_0001',
+   *     message: 'Order not found',
+   *     translations: { de: 'Bestellung nicht gefunden.', en: 'Order not found.' }
+   *   }
+   * } as const satisfies IErrorRegistry;
+   *
+   * errorCode: {
+   *   additionalErrorRegistry: ProjectErrors,
+   * }
+   * ```
+   */
+  additionalErrorRegistry?: Record<
+    string,
+    {
+      code: string;
+      message: string;
+      translations: { [locale: string]: string; de: string; en: string };
+    }
+  >;
+
+  /**
+   * Automatically register the ErrorCodeModule in CoreModule
+   *
+   * Set to `false` to disable auto-registration and provide your own
+   * ErrorCodeModule with custom controller and/or service.
+   *
+   * @default true
+   *
+   * @example
+   * ```typescript
+   * // In config.env.ts - disable auto-registration
+   * errorCode: {
+   *   autoRegister: false,
+   * }
+   *
+   * // In server.module.ts - import your custom module
+   * @Module({
+   *   imports: [
+   *     CoreModule.forRoot(...),
+   *     ErrorCodeModule.forRoot(), // Your custom module
+   *   ],
+   * })
+   * ```
+   */
+  autoRegister?: boolean;
+}
+
 /**
  * Interface for JWT configuration (main and refresh)
  */
@@ -766,6 +830,31 @@ export interface IServerOptions {
    */
   env?: string;
 
+  /**
+   * Configuration for the error code module
+   *
+   * Controls how error codes and translations are handled.
+   *
+   * @since 11.9.0
+   *
+   * @example
+   * ```typescript
+   * // Default: auto-register with core errors only
+   * errorCode: undefined
+   *
+   * // Add project-specific error codes
+   * errorCode: {
+   *   additionalErrorRegistry: ProjectErrors,
+   * }
+   *
+   * // Disable auto-registration to provide your own module
+   * errorCode: {
+   *   autoRegister: false,
+   * }
+   * ```
+   */
+  errorCode?: IErrorCode;
+
   /**
    * Exec a command after server is initialized
    * e.g. 'npm run docs:bootstrap'

src/core.module.ts

@@ -1,4 +1,4 @@
-import { ExecutionContext, Injectable, Logger, Optional, UnauthorizedException } from '@nestjs/common';
+import { ExecutionContext, ForbiddenException, Injectable, Logger, Optional, UnauthorizedException } from '@nestjs/common';
 import { ModuleRef, Reflector } from '@nestjs/core';
 import { GqlExecutionContext } from '@nestjs/graphql';
 import { getConnectionToken } from '@nestjs/mongoose';
@@ -7,6 +7,7 @@ import { firstValueFrom, isObservable } from 'rxjs';
 
 import { RoleEnum } from '../../../common/enums/role.enum';
 import { BetterAuthService } from '../../better-auth/better-auth.service';
+import { ErrorCode } from '../../error-code';
 import { AuthGuardStrategy } from '../auth-guard-strategy.enum';
 import { ExpiredTokenException } from '../exceptions/expired-token.exception';
 import { InvalidTokenException } from '../exceptions/invalid-token.exception';
@@ -331,7 +332,7 @@ export class RolesGuard extends AuthGuard(AuthGuardStrategy.JWT) {
 
     // Check if locked
     if (roles && roles.includes(RoleEnum.S_NO_ONE)) {
-      throw new UnauthorizedException('No access');
+      throw new UnauthorizedException(ErrorCode.UNAUTHORIZED);
     }
 
     // Check roles
@@ -354,11 +355,11 @@ export class RolesGuard extends AuthGuard(AuthGuardStrategy.JWT) {
         if (info?.name === 'TokenExpiredError') {
           throw new ExpiredTokenException();
         }
-        throw new UnauthorizedException('Unauthorized');
+        throw new UnauthorizedException(ErrorCode.UNAUTHORIZED);
       }
 
       // Requester is not authorized
-      throw new UnauthorizedException('Missing role');
+      throw new ForbiddenException(ErrorCode.ACCESS_DENIED);
     }
 
     // Everything is ok

src/core/common/interfaces/server-options.interface.ts

@@ -17,6 +17,7 @@ import { ServiceOptions } from '../../../common/interfaces/service-options.inter
 import { ConfigService } from '../../../common/services/config.service';
 import { BetterAuthUserMapper } from '../../better-auth/better-auth-user.mapper';
 import { BetterAuthService } from '../../better-auth/better-auth.service';
+import { ErrorCode } from '../../error-code';
 import { CoreAuthModel } from '../core-auth.model';
 import { CoreAuthSignInInput } from '../inputs/core-auth-sign-in.input';
 import { CoreAuthSignUpInput } from '../inputs/core-auth-sign-up.input';
@@ -83,13 +84,13 @@ export class CoreAuthService {
     // Check authentication
     const user = serviceOptions.currentUser;
     if (!user || !tokenOrRefreshToken) {
-      throw new UnauthorizedException('Invalid token');
+      throw new UnauthorizedException(ErrorCode.INVALID_TOKEN);
     }
 
     // Check authorization
     const deviceId = this.decodeJwt(tokenOrRefreshToken)?.deviceId;
     if (!deviceId || !user.refreshTokens[deviceId]) {
-      throw new UnauthorizedException('Invalid token');
+      throw new UnauthorizedException(ErrorCode.INVALID_TOKEN);
     }
 
     // Logout from all devices
@@ -374,7 +375,7 @@ export class CoreAuthService {
     if (currentRefreshToken) {
       deviceId = this.decodeJwt(currentRefreshToken)?.deviceId;
       if (!deviceId || !user.refreshTokens?.[deviceId]) {
-        throw new UnauthorizedException('Invalid token');
+        throw new UnauthorizedException(ErrorCode.INVALID_TOKEN);
       }
       if (!this.configService.getFastButReadOnly('jwt.refresh.renewal')) {
         // Return currentToken
@@ -398,7 +399,7 @@ export class CoreAuthService {
     // Set new token
     const payload = this.decodeJwt(newRefreshToken);
     if (!payload) {
-      throw new UnauthorizedException('Invalid token');
+      throw new UnauthorizedException(ErrorCode.INVALID_TOKEN);
     }
     if (!deviceId) {
       deviceId = payload.deviceId;