@lenne.tech/nest-server 11.8.0 → 11.10.0

package/src/core/modules/error-code/INTEGRATION-CHECKLIST.md

@@ -0,0 +1,291 @@
+# ErrorCode Integration Checklist
+
+**For integrating custom error codes into projects using `@lenne.tech/nest-server`.**
+
+> **Estimated time:** 5-10 minutes
+
+---
+
+## Choose Your Scenario
+
+| Scenario | Use When | Configuration | Complexity |
+|----------|----------|---------------|------------|
+| **A. additionalErrorRegistry** | Simple error code addition | Config in `config.env.ts` | Minimal |
+| **B. Custom Service** | Need custom locales or logic | Service inheritance | Low |
+| **C. Custom Controller** | Need custom controller/routes | Service + Controller | Medium |
+
+**Recommendation:** Start with **Scenario A**. Only use B or C if you need customization beyond adding error codes.
+
+---
+
+## Reference Implementation
+
+All files are available as reference in the package:
+
+**Local (in your node_modules):**
+```
+node_modules/@lenne.tech/nest-server/src/server/modules/error-code/
+```
+
+**GitHub:**
+https://github.com/lenneTech/nest-server/tree/develop/src/server/modules/error-code
+
+---
+
+## Scenario A: additionalErrorRegistry (Simplest)
+
+Use this when you just want to add project-specific error codes.
+
+### 1. Define Error Codes
+
+**Create:** `src/server/common/errors/project-errors.ts`
+
+```typescript
+import { IErrorRegistry, mergeErrorCodes } from '@lenne.tech/nest-server';
+
+/**
+ * Project-specific error codes
+ *
+ * Format: PREFIX_XXXX (e.g., PROJ_0001, APP_0001)
+ * Use a unique prefix to avoid collisions with LTNS_* core errors.
+ */
+export const ProjectErrors = {
+  ORDER_NOT_FOUND: {
+    code: 'PROJ_0001',
+    message: 'Order not found',
+    translations: {
+      de: 'Bestellung mit ID {orderId} wurde nicht gefunden.',
+      en: 'Order with ID {orderId} was not found.',
+    },
+  },
+  PAYMENT_FAILED: {
+    code: 'PROJ_0002',
+    message: 'Payment processing failed',
+    translations: {
+      de: 'Die Zahlung konnte nicht verarbeitet werden: {reason}',
+      en: 'Payment processing failed: {reason}',
+    },
+  },
+} as const satisfies IErrorRegistry;
+
+// Merged error codes for type-safe factory functions
+export const ErrorCode = mergeErrorCodes(ProjectErrors);
+```
+
+### 2. Add to config.env.ts
+
+```typescript
+import { ProjectErrors } from './server/common/errors/project-errors';
+
+const config = {
+  // ... other config ...
+  errorCode: {
+    additionalErrorRegistry: ProjectErrors,
+  },
+};
+```
+
+**Done!** Your project errors are now available via `/api/i18n/errors/:locale`.
+
+---
+
+## Scenario B: Custom Service (For Custom Locales)
+
+Use this when you need:
+- Additional locales (e.g., French, Spanish)
+- Custom logic in the service
+
+### 1. Define Error Codes
+
+Same as Scenario A, Step 1.
+
+### 2. Create Custom Service
+
+**Create:** `src/server/modules/error-code/error-code.service.ts`
+**Copy from:** `node_modules/@lenne.tech/nest-server/src/server/modules/error-code/error-code.service.ts`
+
+**Optional customization - add locales:**
+```typescript
+@Injectable()
+export class ErrorCodeService extends CoreErrorCodeService {
+  // Override to add more locales
+  protected override supportedLocales = ['de', 'en', 'fr', 'es'] as const;
+
+  constructor() {
+    super();
+    this.registerErrorRegistry(ProjectErrors);
+  }
+}
+```
+
+### 3. Disable Auto-Registration
+
+**Update:** `src/config.env.ts`
+
+```typescript
+const config = {
+  // ... other config ...
+  errorCode: {
+    autoRegister: false, // Required! Prevents CoreModule from registering its own
+  },
+};
+```
+
+**WHY is `autoRegister: false` required?**
+NestJS @Global() modules use "first wins" for provider registration. Without this, CoreModule's ErrorCodeModule loads first and your custom service is ignored.
+
+### 4. Register in ServerModule
+
+**Update:** `src/server/server.module.ts`
+
+```typescript
+import { ErrorCodeModule as CoreErrorCodeModule } from '@lenne.tech/nest-server';
+import { ErrorCodeService } from './modules/error-code/error-code.service';
+
+@Module({
+  imports: [
+    CoreModule.forRoot(...),
+    // Register with custom service
+    CoreErrorCodeModule.forRoot({
+      service: ErrorCodeService,
+    }),
+    // ... other modules
+  ],
+})
+export class ServerModule {}
+```
+
+---
+
+## Scenario C: Custom Controller (For Custom Routes)
+
+Use this when you need:
+- Custom controller endpoints (e.g., `/codes` listing)
+- Different route paths
+- Additional REST endpoints
+
+**No custom module needed!** Use Core `ErrorCodeModule.forRoot()` with your custom controller and service.
+
+### 1. Create Files
+
+**Copy from:** `node_modules/@lenne.tech/nest-server/src/server/modules/error-code/`
+
+Files needed:
+- `error-codes.ts` - Your error definitions
+- `error-code.service.ts` - Service extending CoreErrorCodeService
+- `error-code.controller.ts` - Controller (**standalone**, not extending)
+- `index.ts` - Exports
+
+**No `error-code.module.ts` needed!**
+
+### 2. Disable Auto-Registration
+
+Same as Scenario B, Step 3.
+
+### 3. Register via Core ErrorCodeModule
+
+**Update:** `src/server/server.module.ts`
+
+```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(...),
+    // Use Core ErrorCodeModule with custom service and controller
+    ErrorCodeModule.forRoot({
+      controller: ErrorCodeController,
+      service: ErrorCodeService,
+    }),
+    // ... other modules
+  ],
+})
+export class ServerModule {}
+```
+
+**WHY standalone controller instead of extending?**
+NestJS registers routes from parent classes first, regardless of method order in child classes. This causes `:locale` to intercept `/codes`. A standalone controller ensures correct route order: static routes (`/codes`) first, then parameterized routes (`:locale`).
+
+---
+
+## Verification Checklist
+
+After integration, verify:
+
+- [ ] `npm run build` succeeds without errors
+- [ ] `npm test` passes
+- [ ] `GET /api/i18n/errors/de` returns your project error codes
+- [ ] `GET /api/i18n/errors/en` returns English translations
+- [ ] Error codes follow format `PREFIX_XXXX` (e.g., `PROJ_0001`)
+- [ ] Translations include placeholders where needed (`{param}`)
+
+### For Scenario C only:
+- [ ] `GET /api/i18n/errors/codes` returns all error codes (if implemented)
+
+---
+
+## Common Mistakes
+
+| Mistake | Symptom | Fix |
+|---------|---------|-----|
+| Forgot `autoRegister: false` | Project errors not appearing | Add `errorCode: { autoRegister: false }` to config |
+| Wrong error code format | Validation errors | Use `PREFIX_XXXX` format (4 digits) |
+| Missing translations | Runtime errors | Ensure all locales have translations |
+| Controller extends CoreErrorCodeController | `/codes` returns 404 | Use standalone controller |
+| Duplicate error codes | Unpredictable behavior | Ensure unique codes across all registries |
+| Forgot to import module | No error translations | Import ErrorCodeModule in ServerModule |
+
+---
+
+## Using Error Codes in Code
+
+```typescript
+import { ErrorCode, Errors } from '@lenne.tech/nest-server';
+
+// Type-safe error code access
+const code = ErrorCode.userNotFound;  // Returns '#LTNS_0001: User not found'
+
+// Factory functions with parameters
+throw new BadRequestException(Errors.userNotFound({ email: 'test@example.com' }));
+// Throws: '#LTNS_0001: User with email test@example.com was not found.'
+
+// Project-specific errors (after registration)
+import { ErrorCode as ProjectErrorCode } from './common/errors/project-errors';
+
+const orderCode = ProjectErrorCode.ORDER_NOT_FOUND;  // '#PROJ_0001: Order not found'
+```
+
+---
+
+## API Reference
+
+### REST Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/i18n/errors/:locale` | GET | Get translations for locale (de, en, ...) |
+| `/api/i18n/errors/codes` | GET | Get all error codes (Scenario C only) |
+
+### Response Format (Nuxt i18n compatible)
+
+```json
+{
+  "errors": {
+    "LTNS_0001": "Benutzer wurde nicht gefunden.",
+    "LTNS_0100": "Sie sind nicht angemeldet.",
+    "PROJ_0001": "Bestellung mit ID {orderId} wurde nicht gefunden."
+  }
+}
+```
+
+> **Note:** Core LTNS_* translations are user-friendly messages without placeholders. Project-specific errors (PROJ_*) may include placeholders like `{orderId}` if defined in your `ProjectErrors` registry.
+
+---
+
+## Detailed Documentation
+
+For complete API reference and advanced topics:
+- **Core Error Codes:** `node_modules/@lenne.tech/nest-server/src/core/modules/error-code/error-codes.ts`
+- **Interfaces:** `node_modules/@lenne.tech/nest-server/src/core/modules/error-code/interfaces/error-code.interfaces.ts`

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

@@ -0,0 +1,55 @@
+import { Controller, Get, NotFoundException, Param } from '@nestjs/common';
+
+import { Roles } from '../../common/decorators/roles.decorator';
+import { RoleEnum } from '../../common/enums/role.enum';
+import { CoreErrorCodeService } from './core-error-code.service';
+import { IErrorTranslationResponse, SupportedLocale } from './interfaces/error-code.interfaces';
+
+/**
+ * Core Error Code Controller
+ *
+ * Provides REST endpoints for error translations.
+ * This controller is publicly accessible (no authentication required).
+ *
+ * @example
+ * GET /api/i18n/errors/de - Get German translations
+ * GET /api/i18n/errors/en - Get English translations
+ */
+@Controller('api/i18n/errors')
+export class CoreErrorCodeController {
+  constructor(protected readonly errorCodeService: CoreErrorCodeService) {}
+
+  /**
+   * 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 wurde nicht gefunden.",
+   *     "LTNS_0002": "Das eingegebene Passwort ist ungültig.",
+   *     "LTNS_0100": "Sie sind nicht angemeldet."
+   *   }
+   * }
+   * ```
+   */
+  @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/core/modules/error-code/core-error-code.service.ts

@@ -0,0 +1,135 @@
+import { Injectable } from '@nestjs/common';
+
+import { getAllErrorDefinitions, IErrorRegistry } from './error-codes';
+import { SupportedLocale } from './interfaces/error-code.interfaces';
+
+/**
+ * Core Error Code Service
+ *
+ * Serves error code translations from the structured ErrorRegistry.
+ * Translations are defined in error-codes.ts as Single Source of Truth.
+ *
+ * Projects can extend this service to add custom error registries.
+ *
+ * @example
+ * ```typescript
+ * // In consuming project:
+ * import { CoreErrorCodeService, IErrorRegistry } from '@lenne.tech/nest-server';
+ *
+ * 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;
+ *
+ * @Injectable()
+ * export class ErrorCodeService extends CoreErrorCodeService {
+ *   constructor() {
+ *     super();
+ *     this.registerErrorRegistry(ProjectErrors);
+ *   }
+ * }
+ * ```
+ */
+@Injectable()
+export class CoreErrorCodeService {
+  /**
+   * Supported locales
+   */
+  protected supportedLocales: SupportedLocale[] = ['de', 'en'];
+
+  /**
+   * Cached translations per locale
+   */
+  protected translations: Map<SupportedLocale, Record<string, string>> = new Map();
+
+  /**
+   * Registered error registries
+   */
+  protected registries: IErrorRegistry[] = [];
+
+  constructor() {
+    // Initialize with core errors
+    this.registerErrorRegistry(getAllErrorDefinitions());
+  }
+
+  /**
+   * Register an error registry and generate translations
+   *
+   * @param registry - Error registry to register
+   */
+  registerErrorRegistry(registry: IErrorRegistry): void {
+    this.registries.push(registry);
+    this.generateTranslationsFromRegistry(registry);
+  }
+
+  /**
+   * Generate translations from error registry
+   *
+   * @param registry - Error registry to extract translations from
+   */
+  protected generateTranslationsFromRegistry(registry: IErrorRegistry): void {
+    for (const [, definition] of Object.entries(registry)) {
+      const { code, translations: defTranslations } = definition;
+
+      for (const locale of this.supportedLocales) {
+        const translation = defTranslations[locale];
+        if (translation) {
+          const existing = this.translations.get(locale) || {};
+          this.translations.set(locale, { ...existing, [code]: translation });
+        }
+      }
+    }
+  }
+
+  /**
+   * Check if a locale is supported
+   *
+   * @param locale - Locale to check
+   * @returns True if locale is supported
+   */
+  isLocaleSupported(locale: string): locale is SupportedLocale {
+    return this.supportedLocales.includes(locale as SupportedLocale);
+  }
+
+  /**
+   * Get supported locales
+   *
+   * @returns Array of supported locales
+   */
+  getSupportedLocales(): SupportedLocale[] {
+    return [...this.supportedLocales];
+  }
+
+  /**
+   * Get all translations for a locale
+   *
+   * @param locale - Locale code (e.g., 'de', 'en')
+   * @returns Translations object wrapped in { errors: ... } for Nuxt i18n compatibility
+   * @throws Error if locale is not supported
+   */
+  getTranslations(locale: SupportedLocale): { errors: Record<string, string> } {
+    if (!this.isLocaleSupported(locale)) {
+      throw new Error(`Locale "${locale}" is not supported. Supported: ${this.supportedLocales.join(', ')}`);
+    }
+
+    return { errors: this.translations.get(locale) || {} };
+  }
+
+  /**
+   * Get all error codes
+   *
+   * @returns Array of error codes from all registries
+   */
+  getErrorCodes(): string[] {
+    const codes = new Set<string>();
+    for (const translations of this.translations.values()) {
+      for (const code of Object.keys(translations)) {
+        codes.add(code);
+      }
+    }
+    return Array.from(codes).sort();
+  }
+}

package/src/core/modules/error-code/error-code.module.ts

@@ -0,0 +1,119 @@
+import { DynamicModule, Global, Module, Type } from '@nestjs/common';
+
+import { CoreErrorCodeController } from './core-error-code.controller';
+import { CoreErrorCodeService } from './core-error-code.service';
+import { IErrorCodeModuleConfig } from './interfaces/error-code.interfaces';
+
+/**
+ * Error Code Module
+ *
+ * Provides error code translations via REST endpoint.
+ * Translations are defined in the error registry (Single Source of Truth).
+ *
+ * @example
+ * ```typescript
+ * // Basic usage (auto-register in CoreModule)
+ * // No explicit import needed - included in CoreModule
+ *
+ * // Extended usage (with custom error registry - RECOMMENDED)
+ * 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;
+ *
+ * ErrorCodeModule.forRoot({ additionalErrorRegistry: ProjectErrors })
+ *
+ * // Extended usage (with custom controller and service)
+ * ErrorCodeModule.forRoot({
+ *   additionalErrorRegistry: ProjectErrors,
+ *   controller: ErrorCodeController,
+ *   service: ErrorCodeService,
+ * })
+ * ```
+ */
+@Global()
+@Module({
+  // IMPORTANT: Controllers are NOT registered here - they are registered via forRoot()
+  // This prevents duplicate controller registration when using custom controllers,
+  // which would cause route conflicts (e.g., :locale intercepting /codes)
+  exports: [CoreErrorCodeService],
+  providers: [CoreErrorCodeService],
+})
+export class ErrorCodeModule {
+  /**
+   * Gets the controller class to use (custom or default)
+   */
+  private static getControllerClass(config?: IErrorCodeModuleConfig): Type<any> {
+    return config?.controller || CoreErrorCodeController;
+  }
+
+  /**
+   * Gets the service class to use (custom or default)
+   */
+  private static getServiceClass(config?: IErrorCodeModuleConfig): Type<CoreErrorCodeService> {
+    return config?.service || CoreErrorCodeService;
+  }
+
+  /**
+   * Register the module with configuration
+   *
+   * Supports the following patterns:
+   * 1. **No config**: Uses CoreErrorCodeService and CoreErrorCodeController with core errors only
+   * 2. **additionalErrorRegistry only**: Adds project errors to core errors
+   * 3. **service only**: Uses custom service class (should register its own errors in constructor)
+   * 4. **controller only**: Uses custom controller class with CoreErrorCodeService
+   * 5. **Full config**: Uses custom service and controller
+   *
+   * @param config - Module configuration
+   * @returns Dynamic module
+   */
+  static forRoot(config?: IErrorCodeModuleConfig): DynamicModule {
+    const ControllerClass = this.getControllerClass(config);
+    const ServiceClass = this.getServiceClass(config);
+
+    // Build providers array
+    const providers: any[] = [];
+
+    if (config?.service) {
+      // If a custom service is provided, register it under both tokens:
+      // 1. Its own class (for direct injection in custom controllers)
+      // 2. CoreErrorCodeService (for backward compatibility)
+      providers.push(ServiceClass);
+      providers.push({
+        provide: CoreErrorCodeService,
+        useExisting: ServiceClass,
+      });
+    } else {
+      // Use factory to register additional errors
+      providers.push({
+        provide: CoreErrorCodeService,
+        useFactory: () => {
+          const service = new CoreErrorCodeService();
+
+          // Add additional error registry
+          if (config?.additionalErrorRegistry) {
+            service.registerErrorRegistry(config.additionalErrorRegistry);
+          }
+
+          return service;
+        },
+      });
+    }
+
+    // Export both the base class and custom service class (if provided)
+    const exports: any[] = [CoreErrorCodeService];
+    if (config?.service && ServiceClass !== CoreErrorCodeService) {
+      exports.push(ServiceClass);
+    }
+
+    return {
+      controllers: [ControllerClass],
+      exports,
+      module: ErrorCodeModule,
+      providers,
+    };
+  }
+}