@lenne.tech/nest-server 11.7.3 → 11.9.0

package/src/core/modules/tus/tus.module.ts

@@ -0,0 +1,187 @@
+import { DynamicModule, Global, Logger, Module, OnModuleInit, Type } from '@nestjs/common';
+import { getConnectionToken } from '@nestjs/mongoose';
+import { Connection } from 'mongoose';
+
+import { ITusConfig } from '../../common/interfaces/server-options.interface';
+import { CoreTusController } from './core-tus.controller';
+import { CoreTusService } from './core-tus.service';
+import { normalizeTusConfig } from './interfaces/tus-config.interface';
+
+/**
+ * Token for injecting the TUS configuration
+ */
+export const TUS_CONFIG = 'TUS_CONFIG';
+
+/**
+ * Options for TusModule.forRoot()
+ */
+export interface TusModuleOptions {
+  /**
+   * TUS configuration.
+   * Accepts:
+   * - `true` or `undefined`: Enable with defaults (enabled by default)
+   * - `false`: Disable TUS uploads
+   * - `{ ... }`: Enable with custom configuration
+   */
+  config?: boolean | ITusConfig;
+
+  /**
+   * Custom controller class to use instead of CoreTusController.
+   * The class must extend CoreTusController.
+   *
+   * @example
+   * ```typescript
+   * @Controller('tus')
+   * @Roles(RoleEnum.S_USER) // Require authentication
+   * export class TusController extends CoreTusController {
+   *   override async handleTus(...) {
+   *     // Custom logic
+   *     return super.handleTus(...);
+   *   }
+   * }
+   *
+   * TusModule.forRoot({
+   *   controller: TusController,
+   * })
+   * ```
+   */
+  controller?: Type<CoreTusController>;
+}
+
+/**
+ * TUS Module for resumable file uploads
+ *
+ * This module provides integration with the tus.io protocol via @tus/server.
+ * It is enabled by default with sensible defaults - no configuration required.
+ *
+ * Features:
+ * - Resumable uploads via tus.io protocol
+ * - Automatic migration to GridFS after upload completion
+ * - Configurable extensions (creation, termination, expiration, etc.)
+ * - Module Inheritance Pattern for customization
+ *
+ * @example
+ * ```typescript
+ * // Default usage - enabled with all defaults
+ * @Module({
+ *   imports: [
+ *     CoreModule.forRoot(envConfig),
+ *     TusModule.forRoot(), // No config needed
+ *   ],
+ * })
+ * export class AppModule {}
+ *
+ * // Custom configuration
+ * TusModule.forRoot({
+ *   config: {
+ *     maxSize: 100 * 1024 * 1024, // 100 MB
+ *     path: '/uploads',
+ *   },
+ * })
+ *
+ * // Disable TUS
+ * TusModule.forRoot({ config: false })
+ * ```
+ */
+@Global()
+@Module({})
+export class TusModule implements OnModuleInit {
+  private static logger = new Logger(TusModule.name);
+  private static tusEnabled = false;
+  private static currentConfig: ITusConfig | null = null;
+  private static customController: null | Type<CoreTusController> = null;
+
+  constructor(private readonly tusService?: CoreTusService) {}
+
+  async onModuleInit(): Promise<void> {
+    if (TusModule.tusEnabled && this.tusService?.isEnabled()) {
+      TusModule.logger.log('TusModule ready');
+    }
+  }
+
+  /**
+   * Gets the controller class to use (custom or default)
+   */
+  private static getControllerClass(): Type<CoreTusController> {
+    return this.customController || CoreTusController;
+  }
+
+  /**
+   * Creates a dynamic module for TUS uploads
+   *
+   * @param options - Configuration options (optional)
+   * @returns Dynamic module configuration
+   */
+  static forRoot(options: TusModuleOptions = {}): DynamicModule {
+    const { config: rawConfig, controller } = options;
+
+    // Normalize config: undefined/true → enabled with defaults, false → disabled
+    const config = normalizeTusConfig(rawConfig);
+
+    // Store config for service configuration
+    this.currentConfig = config;
+    // Store custom controller if provided
+    this.customController = controller || null;
+
+    // If TUS is disabled, return minimal module
+    if (config === null) {
+      this.logger.debug('TUS uploads disabled');
+      this.tusEnabled = false;
+      return {
+        exports: [TUS_CONFIG, CoreTusService],
+        module: TusModule,
+        providers: [
+          {
+            provide: TUS_CONFIG,
+            useValue: null,
+          },
+          {
+            inject: [getConnectionToken()],
+            provide: CoreTusService,
+            useFactory: (connection: Connection) => {
+              const service = new CoreTusService(connection);
+              service.configure(false);
+              return service;
+            },
+          },
+        ],
+      };
+    }
+
+    // Enable TUS
+    this.tusEnabled = true;
+
+    return {
+      controllers: [this.getControllerClass()],
+      exports: [TUS_CONFIG, CoreTusService],
+      module: TusModule,
+      providers: [
+        {
+          provide: TUS_CONFIG,
+          useValue: config,
+        },
+        {
+          inject: [getConnectionToken(), TUS_CONFIG],
+          provide: CoreTusService,
+          useFactory: async (connection: Connection, tusConfig: ITusConfig) => {
+            const service = new CoreTusService(connection);
+            service.configure(tusConfig);
+            // Manually call onModuleInit since useFactory bypasses lifecycle hooks
+            await service.onModuleInit();
+            return service;
+          },
+        },
+      ],
+    };
+  }
+
+  /**
+   * Resets the static state of TusModule
+   * Useful for testing
+   */
+  static reset(): void {
+    this.tusEnabled = false;
+    this.currentConfig = null;
+    this.customController = null;
+  }
+}

package/src/core.module.ts

@@ -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);
     }

package/src/index.ts

@@ -131,6 +131,12 @@ export * from './core/modules/auth/tokens.decorator';
 
 export * from './core/modules/better-auth';
 
+// =====================================================================================================================
+// Core - Modules - ErrorCode
+// =====================================================================================================================
+
+export * from './core/modules/error-code';
+
 // =====================================================================================================================
 // Core - Modules - File
 // =====================================================================================================================
@@ -158,6 +164,12 @@ export * from './core/modules/health-check/core-health-check.service';
 
 export * from './core/modules/migrate';
 
+// =====================================================================================================================
+// Core - Modules - Tus
+// =====================================================================================================================
+
+export * from './core/modules/tus';
+
 // =====================================================================================================================
 // Core - Modules - User
 // =====================================================================================================================

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/modules/file/file.controller.ts

@@ -3,33 +3,41 @@ import {
   Controller,
   Delete,
   Get,
-  NotFoundException,
   Param,
   Post,
-  Res,
   UploadedFile,
   UseInterceptors,
 } from '@nestjs/common';
 import { FileInterceptor } from '@nestjs/platform-express';
-import { Response } from 'express';
 import { Readable } from 'stream';
 
 import { Roles } from '../../../core/common/decorators/roles.decorator';
 import { RoleEnum } from '../../../core/common/enums/role.enum';
-import { CoreFileInfo } from '../../../core/modules/file/core-file-info.model';
+import { CoreFileController } from '../../../core/modules/file/core-file.controller';
 import { FileUpload } from '../../../core/modules/file/interfaces/file-upload.interface';
 import { FileService } from './file.service';
 
 /**
  * File controller
+ *
+ * Extends CoreFileController to provide public download endpoints:
+ * - GET /files/id/:id - Download file by ID (public)
+ * - GET /files/:filename - Download file by filename (public)
+ *
+ * Adds admin-only endpoints:
+ * - POST /files/upload - Upload file (admin)
+ * - GET /files/info/:id - Get file info (admin)
+ * - DELETE /files/:id - Delete file (admin)
  */
 @Controller('files')
 @Roles(RoleEnum.ADMIN)
-export class FileController {
+export class FileController extends CoreFileController {
   /**
    * Import services
    */
-  constructor(private readonly fileService: FileService) {}
+  constructor(protected override readonly fileService: FileService) {
+    super(fileService);
+  }
 
   /**
    * Upload file via HTTP
@@ -54,34 +62,6 @@ export class FileController {
     return await this.fileService.createFile(fileUpload);
   }
 
-  /**
-   * Download file
-   */
-  @Get(':id')
-  @Roles(RoleEnum.ADMIN)
-  async getFile(@Param('id') id: string, @Res() res: Response) {
-    if (!id) {
-      throw new BadRequestException('Missing ID');
-    }
-
-    let file: CoreFileInfo | null;
-    try {
-      file = await this.fileService.getFileInfo(id);
-    } catch (e) {
-      console.error(e);
-      file = null;
-    }
-
-    if (!file) {
-      throw new NotFoundException('File not found');
-    }
-    const filestream = await this.fileService.getFileStream(id);
-    res.header('Content-Type', file.contentType || 'application/octet-stream');
-    res.header('Content-Disposition', `attachment; filename=${file.filename}`);
-    res.header('Cache-Control', 'max-age=31536000');
-    return filestream.pipe(res);
-  }
-
   /**
    * Get file information
    */