@lenne.tech/nest-server 11.8.0 → 11.9.0

package/src/server/modules/error-code/README.md

@@ -0,0 +1,131 @@
+# Error Code Module - Reference Implementation
+
+This directory contains the reference implementation for extending the ErrorCodeModule.
+
+## Purpose
+
+Demonstrates **Scenario C: Custom Service + Controller via forRoot()** where a project:
+1. Defines its own error codes with a unique prefix (`SRV_*`)
+2. Creates a custom service extending `CoreErrorCodeService`
+3. Creates a **standalone** controller (not extending CoreErrorCodeController - see below)
+4. Uses `ErrorCodeModule.forRoot({ service, controller })` from Core
+
+**No custom module needed!** The Core ErrorCodeModule handles everything.
+
+## Files
+
+| File | Description |
+|------|-------------|
+| `error-codes.ts` | Server-specific error definitions (`SRV_*` prefix) |
+| `error-code.service.ts` | Custom service registering `ServerErrors` |
+| `error-code.controller.ts` | Custom controller with `/codes` endpoint |
+| `index.ts` | Module exports |
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│               Core ErrorCodeModule.forRoot()                 │
+│                         (@Global)                            │
+├──────────────────────────────────────────────────────────────┤
+│  ┌─────────────────────┐    ┌─────────────────────────────┐  │
+│  │  ErrorCodeService   │    │   ErrorCodeController       │  │
+│  │  extends Core...    │    │   (standalone - see below)  │  │
+│  │                     │    │                             │  │
+│  │  - LTNS_* (core)    │    │   GET /api/i18n/errors/codes│  │
+│  │  - SRV_* (server)   │    │   GET /api/i18n/errors/de   │  │
+│  │                     │    │   GET /api/i18n/errors/en   │  │
+│  └─────────────────────┘    └─────────────────────────────┘  │
+└──────────────────────────────────────────────────────────────┘
+```
+
+## Usage
+
+### In ServerModule
+
+```typescript
+import { ErrorCodeModule } from '@lenne.tech/nest-server';
+import { ErrorCodeController } from './modules/error-code/error-code.controller';
+import { ErrorCodeService } from './modules/error-code/error-code.service';
+
+@Module({
+  imports: [
+    CoreModule.forRoot({
+      // ...config
+      errorCode: {
+        autoRegister: false, // Required! Prevents CoreModule auto-registration
+      },
+    }),
+    // Use Core ErrorCodeModule with custom service and controller
+    ErrorCodeModule.forRoot({
+      controller: ErrorCodeController,
+      service: ErrorCodeService,
+    }),
+  ],
+})
+export class ServerModule {}
+```
+
+### In Code
+
+```typescript
+import { ErrorCode } from './modules/error-code/error-codes';
+import { Errors } from '@lenne.tech/nest-server';
+
+// Access error codes
+console.log(ErrorCode.DEMO_ERROR);  // '#SRV_0001: Demo error for testing'
+
+// Use factory functions
+throw new BadRequestException(Errors.userNotFound({ email: 'test@example.com' }));
+```
+
+## When to Use This Pattern
+
+Use Scenario C when you need:
+- Custom REST endpoints (like `/codes`)
+- Different route paths
+- Complex controller logic
+
+For simpler cases, see:
+- **Scenario A**: `additionalErrorRegistry` in config (simplest)
+- **Scenario B**: Custom service via inheritance
+
+See `src/core/modules/error-code/INTEGRATION-CHECKLIST.md` for all scenarios.
+
+## Important Notes
+
+### Why Standalone Controller Instead of Extending?
+
+The controller is **standalone** (does not extend `CoreErrorCodeController`) because:
+
+**NestJS registers routes from parent classes first**, regardless of method declaration
+order in child classes. This causes parameterized routes (`:locale`) to intercept
+static routes (`/codes`), even if you re-declare the methods.
+
+```typescript
+// DOES NOT WORK - parent route registered first!
+@Controller('api/i18n/errors')
+export class ErrorCodeController extends CoreErrorCodeController {
+  @Get('codes')                    // Registered AFTER parent's :locale
+  getAllCodes(): string[] { }
+
+  @Get(':locale')                  // Parent already registered this
+  override getTranslations() { }
+}
+
+// WORKS - standalone ensures correct order
+@Controller('api/i18n/errors')
+export class ErrorCodeController {
+  @Get('codes')                    // Registered first
+  getAllCodes(): string[] { }
+
+  @Get(':locale')                  // Registered second
+  getTranslations() { }
+}
+```
+
+**Key insight:** NestJS Controller inheritance does NOT work like Service inheritance for route ordering.
+
+### Why is `autoRegister: false` required?
+
+NestJS `@Global()` modules use "first wins" for provider registration. Without `autoRegister: false`, CoreModule registers its ErrorCodeModule first, and your custom service is ignored.

package/src/server/modules/error-code/error-code.controller.ts

@@ -0,0 +1,91 @@
+import { Controller, Get, NotFoundException, Param } from '@nestjs/common';
+
+import { Roles } from '../../../core/common/decorators/roles.decorator';
+import { RoleEnum } from '../../../core/common/enums/role.enum';
+import { IErrorTranslationResponse, SupportedLocale } from '../../../core/modules/error-code/interfaces/error-code.interfaces';
+import { ErrorCodeService } from './error-code.service';
+
+/**
+ * Server Error Code Controller
+ *
+ * Project-specific Error Code controller that provides error translation endpoints.
+ * This is a standalone controller (not extending CoreErrorCodeController) to ensure
+ * correct route registration order.
+ *
+ * Endpoints:
+ * - GET /api/i18n/errors/codes - Get all available error codes (custom)
+ * - GET /api/i18n/errors/:locale - Get translations for a locale
+ *
+ * **WHY standalone instead of extending CoreErrorCodeController?**
+ * NestJS registers routes from parent classes first, regardless of method declaration
+ * order in child classes. This causes parameterized routes (`:locale`) to intercept
+ * static routes (`/codes`). A standalone controller ensures predictable route ordering.
+ *
+ * @example
+ * ```typescript
+ * // In your module
+ * ErrorCodeModule.forRoot({
+ *   controller: ErrorCodeController,
+ *   service: ErrorCodeService,
+ * })
+ * ```
+ */
+@Controller('api/i18n/errors')
+export class ErrorCodeController {
+  constructor(protected readonly errorCodeService: ErrorCodeService) {}
+
+  /**
+   * Get all available error codes
+   *
+   * Returns a list of all registered error codes from all registries.
+   * This endpoint must be defined BEFORE the :locale endpoint to prevent
+   * "codes" being interpreted as a locale parameter.
+   *
+   * @returns Array of error codes
+   *
+   * @example
+   * Response:
+   * ```json
+   * ["LTNS_0001", "LTNS_0002", "SRV_0001", "SRV_0002"]
+   * ```
+   */
+  @Get('codes')
+  @Roles(RoleEnum.S_EVERYONE)
+  getAllCodes(): string[] {
+    return this.errorCodeService.getErrorCodes();
+  }
+
+  /**
+   * Get error translations for a specific locale
+   *
+   * Returns all error codes with their translations in Nuxt i18n compatible format.
+   *
+   * @param locale - Locale code (e.g., 'de', 'en')
+   * @returns Translations object
+   * @throws NotFoundException if locale is not supported
+   *
+   * @example
+   * Response:
+   * ```json
+   * {
+   *   "errors": {
+   *     "LTNS_0001": "Benutzer mit E-Mail {email} wurde nicht gefunden.",
+   *     "LTNS_0002": "Das eingegebene Passwort ist ungültig.",
+   *     "SRV_0001": "Dies ist ein Demo-Fehler zu Testzwecken."
+   *   }
+   * }
+   * ```
+   */
+  @Get(':locale')
+  @Roles(RoleEnum.S_EVERYONE)
+  getTranslations(@Param('locale') locale: string): IErrorTranslationResponse {
+    if (!this.errorCodeService.isLocaleSupported(locale)) {
+      throw new NotFoundException(
+        `Locale "${locale}" is not supported. ` +
+          `Supported locales: ${this.errorCodeService.getSupportedLocales().join(', ')}`,
+      );
+    }
+
+    return this.errorCodeService.getTranslations(locale as SupportedLocale);
+  }
+}

package/src/server/modules/error-code/error-code.service.ts

@@ -0,0 +1,42 @@
+import { Injectable } from '@nestjs/common';
+
+import { CoreErrorCodeService } from '../../../core/modules/error-code/core-error-code.service';
+import { ServerErrors } from './error-codes';
+
+/**
+ * Server Error Code Service
+ *
+ * Extends CoreErrorCodeService with project-specific error codes.
+ * This service is automatically registered when using ErrorCodeModule.forRoot()
+ * with the service option.
+ *
+ * @example
+ * ```typescript
+ * // In your module
+ * ErrorCodeModule.forRoot({
+ *   service: ErrorCodeService,
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Extend with additional locales
+ * @Injectable()
+ * export class ErrorCodeService extends CoreErrorCodeService {
+ *   protected override supportedLocales = ['de', 'en', 'fr', 'es'] as const;
+ *
+ *   constructor() {
+ *     super();
+ *     this.registerErrorRegistry(ProjectErrors);
+ *   }
+ * }
+ * ```
+ */
+@Injectable()
+export class ErrorCodeService extends CoreErrorCodeService {
+  constructor() {
+    super();
+    // Register project-specific errors
+    this.registerErrorRegistry(ServerErrors);
+  }
+}

package/src/server/modules/error-code/error-codes.ts

@@ -0,0 +1,65 @@
+import { IErrorRegistry, mergeErrorCodes } from '../../../core/modules/error-code/error-codes';
+
+/**
+ * Server-specific Error Registry
+ *
+ * Project-specific error codes that extend the core LTNS_* errors.
+ * Use a unique prefix (e.g., SRV_ for Server) to avoid conflicts.
+ *
+ * Error code ranges for this project:
+ * - SRV_0001-SRV_0099: Business logic errors
+ * - SRV_0100-SRV_0199: Integration errors
+ *
+ * @example
+ * ```typescript
+ * import { UnprocessableEntityException } from '@nestjs/common';
+ * import { ErrorCode } from './error-codes';
+ *
+ * throw new UnprocessableEntityException(ErrorCode.DEMO_ERROR);
+ * // Response: { statusCode: 422, message: "#SRV_0001: Demo error for testing" }
+ * ```
+ */
+export const ServerErrors = {
+  // =====================================================
+  // Business Logic Errors (SRV_0001-SRV_0099)
+  // =====================================================
+
+  DEMO_ERROR: {
+    code: 'SRV_0001',
+    message: 'Demo error for testing',
+    translations: {
+      de: 'Dies ist ein Demo-Fehler zu Testzwecken.',
+      en: 'This is a demo error for testing purposes.',
+    },
+  },
+
+  FEATURE_NOT_AVAILABLE: {
+    code: 'SRV_0002',
+    message: 'Feature not available in this environment',
+    translations: {
+      de: 'Diese Funktion ist in dieser Umgebung nicht verfügbar.',
+      en: 'This feature is not available in this environment.',
+    },
+  },
+} as const satisfies IErrorRegistry;
+
+/**
+ * Merged ErrorCode object for use in this project
+ *
+ * Contains both core LTNS_* errors and project-specific SRV_* errors.
+ *
+ * @example
+ * ```typescript
+ * // Core error
+ * throw new UnauthorizedException(ErrorCode.UNAUTHORIZED);
+ *
+ * // Project error
+ * throw new UnprocessableEntityException(ErrorCode.DEMO_ERROR);
+ * ```
+ */
+export const ErrorCode = mergeErrorCodes(ServerErrors);
+
+/**
+ * Type for all available error code keys
+ */
+export type ServerErrorCodeKey = keyof typeof ErrorCode;

package/src/server/modules/error-code/index.ts

@@ -0,0 +1,8 @@
+// Controller
+export * from './error-code.controller';
+
+// Service
+export * from './error-code.service';
+
+// Error Codes
+export * from './error-codes';

package/src/server/server.module.ts

@@ -7,11 +7,14 @@ import { Any } from '../core/common/scalars/any.scalar';
 import { DateScalar } from '../core/common/scalars/date.scalar';
 import { JSON } from '../core/common/scalars/json.scalar';
 import { CoreAuthService } from '../core/modules/auth/services/core-auth.service';
+import { ErrorCodeModule } from '../core/modules/error-code/error-code.module';
 import { TusModule } from '../core/modules/tus';
 import { CronJobs } from './common/services/cron-jobs.service';
 import { AuthController } from './modules/auth/auth.controller';
 import { AuthModule } from './modules/auth/auth.module';
 import { BetterAuthModule } from './modules/better-auth/better-auth.module';
+import { ErrorCodeController } from './modules/error-code/error-code.controller';
+import { ErrorCodeService } from './modules/error-code/error-code.service';
 import { FileModule } from './modules/file/file.module';
 import { ServerController } from './server.controller';
 
@@ -48,6 +51,13 @@ import { ServerController } from './server.controller';
       fallbackSecrets: [envConfig.jwt?.secret, envConfig.jwt?.refresh?.secret],
     }),
 
+    // Include ErrorCodeModule with project-specific error codes
+    // Uses Core ErrorCodeModule.forRoot() with custom service and controller
+    ErrorCodeModule.forRoot({
+      controller: ErrorCodeController,
+      service: ErrorCodeService,
+    }),
+
     // Include FileModule for file handling
     FileModule,