@lenne.tech/nest-server 11.21.3 → 11.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.21.3",
+  "version": "11.22.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",
@@ -168,7 +168,11 @@
   "files": [
     "dist/**/*",
     "src/**/*",
-    "bin/**/*"
+    "bin/**/*",
+    "CLAUDE.md",
+    ".claude/rules/**/*",
+    "docs/**/*",
+    "migration-guides/**/*"
   ],
   "watch": {
     "build:dev": "src"
@@ -191,7 +195,8 @@
       "picomatch@>=4.0.0 <4.0.4": "4.0.4",
       "path-to-regexp@>=8.0.0 <8.4.0": "8.4.1",
       "kysely@>=0.26.0 <0.28.15": "0.28.15",
-      "lodash@>=4.0.0 <4.18.0": "4.18.1"
+      "lodash@>=4.0.0 <4.18.0": "4.18.1",
+      "defu@<=6.1.4": "6.1.6"
     },
     "onlyBuiltDependencies": [
       "bcrypt",

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

@@ -2117,16 +2117,12 @@ interface IBetterAuthBase {
    * Custom controller class to use instead of the default CoreBetterAuthController.
    * The class should extend CoreBetterAuthController.
    *
-   * This allows projects to customize REST endpoints via config instead of creating
-   * a separate module. Use this with CoreModule.forRoot(envConfig) (IAM-only mode).
-   *
-   * @example
+   * @deprecated Since 11.22.0 — Use the `overrides` parameter on `CoreModule.forRoot()` instead:
    * ```typescript
-   * // config.env.ts
-   * betterAuth: {
-   *   controller: IamController,
-   * }
+   * CoreModule.forRoot(envConfig, { betterAuth: { controller: IamController } })
    * ```
+   * This separates class references from environment configuration. The config field
+   * still works for backward compatibility but `overrides` takes precedence.
    *
    * @since 11.14.0
    */
@@ -2342,16 +2338,12 @@ interface IBetterAuthBase {
    * Custom resolver class to use instead of the default DefaultBetterAuthResolver.
    * The class should extend CoreBetterAuthResolver.
    *
-   * This allows projects to customize GraphQL operations via config instead of creating
-   * a separate module. Use this with CoreModule.forRoot(envConfig) (IAM-only mode).
-   *
-   * @example
+   * @deprecated Since 11.22.0 — Use the `overrides` parameter on `CoreModule.forRoot()` instead:
    * ```typescript
-   * // config.env.ts
-   * betterAuth: {
-   *   resolver: IamResolver,
-   * }
+   * CoreModule.forRoot(envConfig, { betterAuth: { resolver: IamResolver } })
    * ```
+   * This separates class references from environment configuration. The config field
+   * still works for backward compatibility but `overrides` takes precedence.
    *
    * @since 11.14.0
    */
@@ -2663,3 +2655,78 @@ interface IBetterAuthWithPasskey extends IBetterAuthBase {
    */
   trustedOrigins: string[];
 }
+
+/**
+ * Override default implementations of core module components.
+ *
+ * Use this as the second parameter of `CoreModule.forRoot()` to replace
+ * default controllers, resolvers, or services with project-specific implementations.
+ *
+ * This keeps class references (code) separate from environment configuration (strings/numbers)
+ * and ensures each module's `forRoot()` is called exactly once — preventing duplicate
+ * controller registration.
+ *
+ * Each core module that supports customization has a typed entry here.
+ * Only specified components are overridden — unset fields use defaults.
+ *
+ * @example
+ * ```typescript
+ * // IAM-only mode with overrides
+ * CoreModule.forRoot(envConfig, {
+ *   errorCode: { controller: ErrorCodeController, service: ErrorCodeService },
+ *   betterAuth: { resolver: BetterAuthResolver },
+ * })
+ *
+ * // Legacy mode with overrides
+ * CoreModule.forRoot(CoreAuthService, AuthModule.forRoot(envConfig.jwt), envConfig, {
+ *   errorCode: { controller: ErrorCodeController, service: ErrorCodeService },
+ *   betterAuth: { controller: BetterAuthController, resolver: BetterAuthResolver },
+ * })
+ * ```
+ *
+ * @since 11.22.0
+ */
+export interface ICoreModuleOverrides {
+  /**
+   * Override BetterAuth controller and/or resolver.
+   *
+   * The custom controller must extend `CoreBetterAuthController`.
+   * The custom resolver must extend `CoreBetterAuthResolver` and re-declare
+   * all GraphQL decorators (`@Mutation`, `@Query`, `@Roles`).
+   *
+   * @example
+   * ```typescript
+   * {
+   *   betterAuth: {
+   *     controller: BetterAuthController,
+   *     resolver: BetterAuthResolver,
+   *   },
+   * }
+   * ```
+   */
+  betterAuth?: {
+    controller?: Type<any>;
+    resolver?: Type<any>;
+  };
+
+  /**
+   * Override ErrorCode controller and/or service.
+   *
+   * The custom controller can be standalone (recommended) or extend `CoreErrorCodeController`.
+   * The custom service must extend `CoreErrorCodeService`.
+   *
+   * @example
+   * ```typescript
+   * {
+   *   errorCode: {
+   *     controller: ErrorCodeController,
+   *     service: ErrorCodeService,
+   *   },
+   * }
+   * ```
+   */
+  errorCode?: {
+    controller?: Type<any>;
+    service?: Type<any>;
+  };
+}

package/src/core/modules/better-auth/CUSTOMIZATION.md

@@ -41,29 +41,23 @@ export class ServerModule {}
 - Default `CoreBetterAuthController` and `DefaultBetterAuthResolver` are registered
 - No additional configuration needed
 
-### Pattern 2: Config-based Controller/Resolver (Recommended for Customization)
+### Pattern 2: Overrides Parameter (Recommended for Customization)
 
 **Use when:** Need custom Controller or Resolver, but don't need a separate module.
 
-```typescript
-// config.env.ts
-import { IamController } from './server/modules/iam/iam.controller';
-import { IamResolver } from './server/modules/iam/iam.resolver';
-
-const config = {
-  betterAuth: {
-    controller: IamController, // Custom controller class
-    resolver: IamResolver, // Custom resolver class
-    // ... other betterAuth config
-  },
-};
-```
-
 ```typescript
 // server.module.ts
+import { IamController } from './modules/iam/iam.controller';
+import { IamResolver } from './modules/iam/iam.resolver';
+
 @Module({
   imports: [
-    CoreModule.forRoot(envConfig), // Uses custom controller/resolver from config
+    CoreModule.forRoot(envConfig, {
+      betterAuth: {
+        controller: IamController,
+        resolver: IamResolver,
+      },
+    }),
   ],
 })
 export class ServerModule {}
@@ -71,9 +65,22 @@ export class ServerModule {}
 
 **What happens:**
 
-- CoreModule passes `controller`/`resolver` to `CoreBetterAuthModule.forRoot()`
+- CoreModule passes overrides to `CoreBetterAuthModule.forRoot()`
 - Your custom classes are registered instead of defaults
 - Single registration point, no duplicate imports
+- Class references stay separate from environment config
+
+**Alternative:** Set `controller`/`resolver` directly in config (backward compatible):
+
+```typescript
+// config.env.ts — still works but overrides parameter is preferred
+const config = {
+  betterAuth: {
+    controller: IamController,
+    resolver: IamResolver,
+  },
+};
+```
 
 ### Pattern 3: Separate Module (autoRegister: false)
 

package/src/core/modules/better-auth/INTEGRATION-CHECKLIST.md

@@ -23,11 +23,11 @@
 
 ### Registration Patterns (Quick Reference)
 
-| Pattern             | Use When                           | Configuration                                      |
-| ------------------- | ---------------------------------- | -------------------------------------------------- |
-| **Zero-Config**     | No customization needed            | Just use `CoreModule.forRoot(envConfig)`           |
-| **Config-based**    | Custom Controller/Resolver         | Add `controller`/`resolver` to `betterAuth` config |
-| **Separate Module** | Full control, additional providers | Set `autoRegister: false` in config                |
+| Pattern                     | Use When                           | Configuration                                                                                 |
+| --------------------------- | ---------------------------------- | --------------------------------------------------------------------------------------------- |
+| **Zero-Config**             | No customization needed            | Just use `CoreModule.forRoot(envConfig)`                                                      |
+| **Overrides** (recommended) | Custom Controller/Resolver         | Pass `overrides` to `CoreModule.forRoot(envConfig, { betterAuth: { controller, resolver } })` |
+| **Separate Module**         | Full control, additional providers | Set `autoRegister: false` in config                                                           |
 
 **Details:** See [CUSTOMIZATION.md](./CUSTOMIZATION.md#module-registration-patterns)
 

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

@@ -141,16 +141,15 @@ NestJS @Global() modules use "first wins" for provider registration. Without thi
 
 **Update:** `src/server/server.module.ts`
 
+Use the `overrides` parameter of `CoreModule.forRoot()` (recommended since v11.22.0):
+
 ```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,
+    CoreModule.forRoot(envConfig, {
+      errorCode: { service: ErrorCodeService },
     }),
     // ... other modules
   ],
@@ -158,6 +157,22 @@ import { ErrorCodeService } from './modules/error-code/error-code.service';
 export class ServerModule {}
 ```
 
+**Alternative** (for complex setups): disable auto-registration and import separately:
+
+```typescript
+import { ErrorCodeModule as CoreErrorCodeModule } from '@lenne.tech/nest-server';
+import { ErrorCodeService } from './modules/error-code/error-code.service';
+
+@Module({
+  imports: [
+    CoreModule.forRoot({ ...envConfig, errorCode: { autoRegister: false } }),
+    CoreErrorCodeModule.forRoot({ service: ErrorCodeService }),
+    // ... other modules
+  ],
+})
+export class ServerModule {}
+```
+
 ---
 
 ## Scenario C: Custom Controller (For Custom Routes)
@@ -168,7 +183,7 @@ Use this when you need:
 - Different route paths
 - Additional REST endpoints
 
-**No custom module needed!** Use Core `ErrorCodeModule.forRoot()` with your custom controller and service.
+**No custom module needed!** Use the `overrides` parameter of `CoreModule.forRoot()`.
 
 ### 1. Create Files
 
@@ -183,13 +198,29 @@ Files needed:
 
 **No `error-code.module.ts` needed!**
 
-### 2. Disable Auto-Registration
+### 2. Register via CoreModule.forRoot() Overrides (Recommended)
 
-Same as Scenario B, Step 3.
+**Update:** `src/server/server.module.ts`
 
-### 3. Register via Core ErrorCodeModule
+```typescript
+import { ErrorCodeController } from './modules/error-code/error-code.controller';
+import { ErrorCodeService } from './modules/error-code/error-code.service';
 
-**Update:** `src/server/server.module.ts`
+@Module({
+  imports: [
+    CoreModule.forRoot(envConfig, {
+      errorCode: {
+        controller: ErrorCodeController,
+        service: ErrorCodeService,
+      },
+    }),
+    // ... other modules
+  ],
+})
+export class ServerModule {}
+```
+
+**Alternative** (for complex setups): disable auto-registration and import separately:
 
 ```typescript
 import { ErrorCodeModule } from '@lenne.tech/nest-server';
@@ -198,8 +229,7 @@ import { ErrorCodeService } from './modules/error-code/error-code.service';
 
 @Module({
   imports: [
-    CoreModule.forRoot(...),
-    // Use Core ErrorCodeModule with custom service and controller
+    CoreModule.forRoot({ ...envConfig, errorCode: { autoRegister: false } }),
     ErrorCodeModule.forRoot({
       controller: ErrorCodeController,
       service: ErrorCodeService,

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

@@ -12,8 +12,10 @@ import { IErrorCodeModuleConfig } from './interfaces/error-code.interfaces';
  *
  * @example
  * ```typescript
- * // Basic usage (auto-register in CoreModule)
- * // No explicit import needed - included in CoreModule
+ * // Basic usage (auto-register in CoreModule via overrides)
+ * CoreModule.forRoot(envConfig, {
+ *   errorCode: { controller: ErrorCodeController, service: ErrorCodeService },
+ * })
  *
  * // Extended usage (with custom error registry - RECOMMENDED)
  * const ProjectErrors = {
@@ -25,13 +27,6 @@ import { IErrorCodeModuleConfig } from './interfaces/error-code.interfaces';
  * } as const satisfies IErrorRegistry;
  *
  * ErrorCodeModule.forRoot({ additionalErrorRegistry: ProjectErrors })
- *
- * // Extended usage (with custom controller and service)
- * ErrorCodeModule.forRoot({
- *   additionalErrorRegistry: ProjectErrors,
- *   controller: ErrorCodeController,
- *   service: ErrorCodeService,
- * })
  * ```
  */
 @Global()

package/src/core.module.ts

@@ -12,7 +12,7 @@ import { CheckResponseInterceptor } from './core/common/interceptors/check-respo
 import { CheckSecurityInterceptor } from './core/common/interceptors/check-security.interceptor';
 import { ResponseModelInterceptor } from './core/common/interceptors/response-model.interceptor';
 import { TranslateResponseInterceptor } from './core/common/interceptors/translate-response.interceptor';
-import { IServerOptions } from './core/common/interfaces/server-options.interface';
+import { ICoreModuleOverrides, IServerOptions } from './core/common/interfaces/server-options.interface';
 import { RequestContextMiddleware } from './core/common/middleware/request-context.middleware';
 import { MapAndValidatePipe } from './core/common/pipes/map-and-validate.pipe';
 import { ComplexityPlugin } from './core/common/plugins/complexity.plugin';
@@ -95,6 +95,12 @@ export class CoreModule implements NestModule {
    *
    * ```typescript
    * CoreModule.forRoot(envConfig)
+   *
+   * // With module overrides (custom controllers/resolvers/services)
+   * CoreModule.forRoot(envConfig, {
+   *   errorCode: { controller: ErrorCodeController, service: ErrorCodeService },
+   *   betterAuth: { resolver: BetterAuthResolver },
+   * })
    * ```
    *
    * Use this for new projects that only use BetterAuth (IAM) for authentication.
@@ -109,6 +115,11 @@ export class CoreModule implements NestModule {
    *
    * ```typescript
    * CoreModule.forRoot(CoreAuthService, AuthModule.forRoot(envConfig.jwt), envConfig)
+   *
+   * // With module overrides
+   * CoreModule.forRoot(CoreAuthService, AuthModule.forRoot(envConfig.jwt), envConfig, {
+   *   errorCode: { controller: ErrorCodeController, service: ErrorCodeService },
+   * })
    * ```
    *
    * @deprecated This 3-parameter signature is deprecated for new projects.
@@ -127,22 +138,36 @@ export class CoreModule implements NestModule {
    *
    * @see https://github.com/lenneTech/nest-server/blob/develop/.claude/rules/module-deprecation.md
    */
-  static forRoot(options: Partial<IServerOptions>): DynamicModule;
+  static forRoot(options: Partial<IServerOptions>, overrides?: ICoreModuleOverrides): DynamicModule;
   /**
    * @deprecated Use the single-parameter signature `CoreModule.forRoot(envConfig)` for new projects.
    * This 3-parameter signature is for existing projects during migration to IAM.
    */
-  static forRoot(AuthService: any, AuthModule: any, options: Partial<IServerOptions>): DynamicModule;
+  static forRoot(
+    AuthService: any,
+    AuthModule: any,
+    options: Partial<IServerOptions>,
+    overrides?: ICoreModuleOverrides,
+  ): DynamicModule;
   static forRoot(
     authServiceOrOptions: any,
     authModuleOrUndefined?: any,
     optionsOrUndefined?: Partial<IServerOptions>,
+    overridesOrUndefined?: ICoreModuleOverrides,
   ): DynamicModule {
-    // Detect which signature was used
-    const isIamOnlyMode = authModuleOrUndefined === undefined && optionsOrUndefined === undefined;
+    // Detect which signature was used:
+    // IAM-only: forRoot(config, overrides?) — first arg is a plain object (config)
+    // Legacy:   forRoot(AuthService, AuthModule, config, overrides?) — first arg is a class (function)
+    const isIamOnlyMode = typeof authServiceOrOptions !== 'function';
     const AuthService = isIamOnlyMode ? null : authServiceOrOptions;
     const AuthModule = isIamOnlyMode ? null : authModuleOrUndefined;
     const options: Partial<IServerOptions> = isIamOnlyMode ? authServiceOrOptions : optionsOrUndefined;
+    // For IAM-only mode: overrides is the 2nd param; for legacy mode: it's the 4th param.
+    // The cast is safe: the public overloads guarantee the 2nd arg is ICoreModuleOverrides | undefined
+    // in IAM-only mode (typeof first arg !== 'function'), never a DynamicModule (AuthModule).
+    const overrides: ICoreModuleOverrides | undefined = isIamOnlyMode
+      ? (authModuleOrUndefined as ICoreModuleOverrides | undefined)
+      : overridesOrUndefined;
 
     // Process config
     let cors = {};
@@ -316,11 +341,21 @@ export class CoreModule implements NestModule {
     const errorCodeConfig = config.errorCode;
     const isErrorCodeAutoRegister = errorCodeConfig?.autoRegister !== false;
 
+    if (!isErrorCodeAutoRegister && (overrides?.errorCode?.controller || overrides?.errorCode?.service)) {
+      console.warn(
+        'CoreModule: errorCode overrides are ignored because errorCode.autoRegister is false. ' +
+          'Either remove autoRegister: false or pass controller/service to your own ErrorCodeModule.forRoot() call.',
+      );
+    }
+
     if (isErrorCodeAutoRegister) {
       // Always use forRoot() - it registers the controller and handles configuration
+      // Overrides take precedence over config for controller/service
       imports.push(
         ErrorCodeModule.forRoot({
           additionalErrorRegistry: errorCodeConfig?.additionalErrorRegistry,
+          controller: overrides?.errorCode?.controller,
+          service: overrides?.errorCode?.service,
         }),
       );
     }
@@ -357,24 +392,31 @@ export class CoreModule implements NestModule {
     // autoRegister: false means the project imports its own BetterAuthModule separately
     const isAutoRegisterDisabled = typeof betterAuthConfig === 'object' && betterAuthConfig?.autoRegister === false;
 
-    // Extract custom controller/resolver from config (Pattern 2: Config-based)
+    // Extract custom controller/resolver: overrides take precedence over config fields
     const configController = typeof betterAuthConfig === 'object' ? betterAuthConfig?.controller : undefined;
     const configResolver = typeof betterAuthConfig === 'object' ? betterAuthConfig?.resolver : undefined;
 
+    if (isAutoRegisterDisabled && (overrides?.betterAuth?.controller || overrides?.betterAuth?.resolver)) {
+      console.warn(
+        'CoreModule: betterAuth overrides are ignored because betterAuth.autoRegister is false. ' +
+          'Either remove autoRegister: false or pass controller/resolver to your own BetterAuthModule.forRoot() call.',
+      );
+    }
+
     if (isBetterAuthEnabled) {
       if ((isIamOnlyMode && !isAutoRegisterDisabled) || isAutoRegister) {
         imports.push(
           CoreBetterAuthModule.forRoot({
             config: betterAuthConfig === true ? {} : betterAuthConfig || {},
-            // Pass custom controller/resolver from config (Pattern 2)
-            controller: configController,
+            // Overrides take precedence over config fields (backward compatible)
+            controller: overrides?.betterAuth?.controller || configController,
             // Pass JWT secrets for backwards compatibility fallback
             fallbackSecrets: [config.jwt?.secret, config.jwt?.refresh?.secret],
             // In IAM-only mode, register RolesGuard globally to enforce @Roles() decorators
             // In Legacy mode (autoRegister), RolesGuard is already registered via CoreAuthModule
             registerRolesGuardGlobally: isIamOnlyMode,
-            // Pass custom resolver from config (Pattern 2)
-            resolver: configResolver,
+            // Overrides take precedence over config fields (backward compatible)
+            resolver: overrides?.betterAuth?.resolver || configResolver,
             // Pass server-level URLs for Passkey auto-detection
             // When env: 'local', defaults are: baseUrl=localhost:3000, appUrl=localhost:3001
             serverAppUrl: config.appUrl,

package/src/server/server.module.ts

@@ -7,7 +7,6 @@ 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';
@@ -35,7 +34,13 @@ import { ServerController } from './server.controller';
   imports: [
     // Include CoreModule for standard processes
     // Note: BetterAuthModule is imported manually below (autoRegister defaults to false)
-    CoreModule.forRoot(CoreAuthService, AuthModule.forRoot(envConfig.jwt), envConfig),
+    // ErrorCodeModule is auto-registered by CoreModule with overrides for custom controller/service
+    CoreModule.forRoot(CoreAuthService, AuthModule.forRoot(envConfig.jwt), envConfig, {
+      errorCode: {
+        controller: ErrorCodeController,
+        service: ErrorCodeService,
+      },
+    }),
 
     // Include cron job handling
     ScheduleModule.forRoot(),
@@ -49,13 +54,6 @@ import { ServerController } from './server.controller';
     // This allows project-specific customization via BetterAuthResolver
     BetterAuthModule.forRoot({}),
 
-    // 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,