@lenne.tech/nest-server 11.27.5 → 11.27.7

package/src/core/modules/better-auth/core-better-auth.module.ts

@@ -28,15 +28,34 @@ import { CoreBetterAuthRateLimitMiddleware } from './core-better-auth-rate-limit
 import { CoreBetterAuthRateLimiter } from './core-better-auth-rate-limiter.service';
 import { CoreBetterAuthSignUpValidatorService } from './core-better-auth-signup-validator.service';
 import { CoreBetterAuthUserMapper } from './core-better-auth-user.mapper';
+import { BETTER_AUTH_CONFIG, BETTER_AUTH_COOKIE_DOMAIN, BETTER_AUTH_INSTANCE } from './core-better-auth.constants';
 import { CoreBetterAuthController } from './core-better-auth.controller';
 import { CoreBetterAuthMiddleware } from './core-better-auth.middleware';
+import {
+  getBetterAuthTokenService,
+  resetBetterAuthRegistry,
+  setBetterAuthTokenService,
+} from './core-better-auth.registry';
 import { CoreBetterAuthResolver } from './core-better-auth.resolver';
-import { BETTER_AUTH_CONFIG, BETTER_AUTH_COOKIE_DOMAIN, CoreBetterAuthService } from './core-better-auth.service';
+import { CoreBetterAuthService } from './core-better-auth.service';
 
 /**
- * Token for injecting the better-auth instance
+ * @deprecated Import from `./core-better-auth.constants` instead. Re-exported only
+ * so existing deep imports keep working; it will be dropped in a future MINOR.
+ *
+ * Do NOT import this token from here inside the better-auth module itself — the
+ * token must come from the constants leaf, or module and service start importing
+ * each other again and SWC builds crash with a temporal-dead-zone ReferenceError
+ * (see core-better-auth.constants.ts).
+ *
+ * NOTE: the `@deprecated` tag above is documentation only — TypeScript does not
+ * honor JSDoc on an `export … from` declaration. Do NOT try to "fix" that by
+ * re-declaring the token as a local `const`: that would give the barrel two
+ * distinct declarations of the same name and turn its `export *` into a TS2308
+ * ambiguity error. The mechanical guards are `pnpm run check:swc-tdz` and
+ * `tests/unit/better-auth-di-tokens.spec.ts`.
  */
-export const BETTER_AUTH_INSTANCE = 'BETTER_AUTH_INSTANCE';
+export { BETTER_AUTH_INSTANCE } from './core-better-auth.constants';
 
 /**
  * Options for CoreBetterAuthModule.forRoot()
@@ -239,10 +258,11 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
   // Safety Net: Track if forRoot() has already been called to detect duplicate registration
   private static forRootCalled = false;
   private static cachedDynamicModule: DynamicModule | null = null;
-  // Static references for lazy GraphQL driver (autoRegister: false) and BetterAuthRolesGuard
+  // Static references for lazy GraphQL driver (autoRegister: false).
+  // The BetterAuthTokenService reference lives in core-better-auth.registry.ts instead,
+  // so BetterAuthRolesGuard can read it without importing this module (cycle-free).
   private static serviceInstance: CoreBetterAuthService | null = null;
   private static userMapperInstance: CoreBetterAuthUserMapper | null = null;
-  private static tokenServiceInstance: BetterAuthTokenService | null = null;
   private static resolvedCookieDomain: string | undefined = undefined;
 
   /**
@@ -279,11 +299,14 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
 
   /**
    * Gets the static BetterAuthTokenService instance.
-   * Used by BetterAuthRolesGuard for token verification when user isn't already on request.
    * Safe because guards are invoked only after module initialization.
+   *
+   * Delegates to the core-better-auth.registry leaf module, which is the single
+   * source of truth. BetterAuthRolesGuard reads the registry directly instead of
+   * calling this method, so that guard and module never import each other.
    */
   static getTokenServiceInstance(): BetterAuthTokenService | null {
-    return this.tokenServiceInstance;
+    return getBetterAuthTokenService();
   }
 
   /**
@@ -315,7 +338,7 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
       CoreBetterAuthModule.userMapperInstance = this.userMapper;
     }
     if (this.tokenService) {
-      CoreBetterAuthModule.tokenServiceInstance = this.tokenService;
+      setBetterAuthTokenService(this.tokenService);
     }
 
     // Configure rate limiter with stored config
@@ -747,6 +770,9 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
     this.serviceInstance = null;
     this.userMapperInstance = null;
     this.resolvedCookieDomain = undefined;
+    // Reset the BetterAuthTokenService reference used by BetterAuthRolesGuard.
+    // Without this a token service from a previous testing module leaks into the next one.
+    resetBetterAuthRegistry();
     // Reset shared RolesGuard registry (shared with CoreAuthModule)
     RolesGuardRegistry.reset();
   }

package/src/core/modules/better-auth/core-better-auth.registry.ts

@@ -0,0 +1,53 @@
+/**
+ * Runtime registry for better-auth singletons that must be reachable from files
+ * which cannot import core-better-auth.module.ts.
+ *
+ * `BetterAuthRolesGuard` deliberately has no constructor dependencies (see
+ * .claude/rules/better-auth.md §5), so it cannot receive `BetterAuthTokenService`
+ * through DI and has to look it up statically. Reading it from
+ * `CoreBetterAuthModule` would make guard and module import each other — the same
+ * cycle shape that crashed SWC builds when the DI tokens still lived in the module
+ * and the service (see core-better-auth.constants.ts).
+ *
+ * This file therefore holds the reference instead. It uses only `import type`,
+ * which both tsc and SWC erase entirely, so it emits no `require()` at all and is
+ * a true leaf: it can never be mid-evaluation when someone imports it, in any
+ * module system, under any compiler.
+ *
+ * @internal Populated by CoreBetterAuthModule.onModuleInit(). Read it through the
+ * public `CoreBetterAuthModule.getTokenServiceInstance()` unless you are in a file
+ * that the module itself imports — importing the module from there would re-create
+ * the cycle.
+ */
+
+import type { BetterAuthTokenService } from './better-auth-token.service';
+
+let tokenServiceInstance: BetterAuthTokenService | null = null;
+
+/**
+ * Stores the BetterAuthTokenService singleton.
+ * Called by CoreBetterAuthModule during module initialization.
+ * @internal
+ */
+export function setBetterAuthTokenService(service: BetterAuthTokenService | null): void {
+  tokenServiceInstance = service;
+}
+
+/**
+ * Returns the BetterAuthTokenService singleton, or null when better-auth is
+ * disabled or the module has not initialized yet.
+ *
+ * Safe to call from guards: they run only after module initialization.
+ */
+export function getBetterAuthTokenService(): BetterAuthTokenService | null {
+  return tokenServiceInstance;
+}
+
+/**
+ * Clears the registry. Called by CoreBetterAuthModule.reset() so tests do not
+ * leak a token service from a previous testing module into the next one.
+ * @internal
+ */
+export function resetBetterAuthRegistry(): void {
+  tokenServiceInstance = null;
+}

package/src/core/modules/better-auth/core-better-auth.service.ts

@@ -13,7 +13,7 @@ import { resolveBetterAuthCookiePrefix } from './better-auth-cookie-prefix.helpe
 import { BetterAuthInstance } from './better-auth.config';
 import { BetterAuthSessionUser } from './core-better-auth-user.mapper';
 import { convertExpressHeaders, parseCookieHeader, signCookieValueIfNeeded } from './core-better-auth-web.helper';
-import { BETTER_AUTH_INSTANCE } from './core-better-auth.module';
+import { BETTER_AUTH_CONFIG, BETTER_AUTH_COOKIE_DOMAIN, BETTER_AUTH_INSTANCE } from './core-better-auth.constants';
 
 /**
  * Result of a session validation
@@ -28,6 +28,24 @@ export interface SessionResult {
   user: BetterAuthSessionUser | null;
 }
 
+/**
+ * @deprecated Import from `./core-better-auth.constants` instead. Re-exported only
+ * so existing deep imports keep working; it will be dropped in a future MINOR.
+ *
+ * Do NOT import these tokens from here inside the better-auth module itself — they
+ * must come from the constants leaf, or module and service start importing each
+ * other again and SWC builds crash with a temporal-dead-zone ReferenceError
+ * (see core-better-auth.constants.ts).
+ *
+ * NOTE: the `@deprecated` tag above is documentation only — TypeScript does not
+ * honor JSDoc on an `export … from` declaration. Do NOT try to "fix" that by
+ * re-declaring the tokens as local `const`s: that would give the barrel two
+ * distinct declarations of the same name and turn its `export *` into a TS2308
+ * ambiguity error. The mechanical guards are `pnpm run check:swc-tdz` and
+ * `tests/unit/better-auth-di-tokens.spec.ts`.
+ */
+export { BETTER_AUTH_CONFIG, BETTER_AUTH_COOKIE_DOMAIN } from './core-better-auth.constants';
+
 /**
  * CoreBetterAuthService provides a NestJS-friendly wrapper around the better-auth instance.
  *
@@ -51,17 +69,6 @@ export interface SessionResult {
  * }
  * ```
  */
-/**
- * Injection token for resolved BetterAuth configuration
- */
-export const BETTER_AUTH_CONFIG = 'BETTER_AUTH_CONFIG';
-
-/**
- * Injection token for resolved cross-subdomain cookie domain.
- * Set during Better-Auth instance creation, undefined if disabled.
- */
-export const BETTER_AUTH_COOKIE_DOMAIN = 'BETTER_AUTH_COOKIE_DOMAIN';
-
 @Injectable()
 export class CoreBetterAuthService implements OnModuleInit {
   private readonly logger = new Logger(CoreBetterAuthService.name);

package/src/core/modules/better-auth/index.ts

@@ -39,8 +39,17 @@ export * from './core-better-auth-signup-validator.service';
 export * from './core-better-auth-token.helper';
 export * from './core-better-auth-user.mapper';
 export * from './core-better-auth-web.helper';
+export * from './core-better-auth.constants';
 export * from './core-better-auth.controller';
 export * from './core-better-auth.middleware';
 export * from './core-better-auth.module';
+// NOT exported: './core-better-auth.registry'.
+//
+// It is module-internal plumbing that only exists so BetterAuthRolesGuard can reach
+// BetterAuthTokenService without importing CoreBetterAuthModule (see .claude/rules/better-auth.md
+// §6). Re-exporting it would put `setBetterAuthTokenService()` on the public API — letting a
+// consumer swap or null the very token service the guard makes its authorization decisions with.
+// Consumers that need the instance already have the public, read-only
+// `CoreBetterAuthModule.getTokenServiceInstance()`.
 export * from './core-better-auth.resolver';
 export * from './core-better-auth.service';

package/src/core/modules/migrate/migration-runner.ts

@@ -19,13 +19,27 @@ export interface MigrationFile {
   up: () => Promise<void>;
 }
 
+/**
+ * Default file pattern for migration files: `*.ts` and `*.js`, but never `*.d.ts`.
+ *
+ * A compiled migration ships `foo.js` next to `foo.d.ts` (whenever the project
+ * builds with `declaration: true`). A plain `/\.(ts|js)$/` matches the
+ * declaration file too, so the runner would load it as a *second* migration and
+ * throw — `export declare …` is not valid CommonJS.
+ *
+ * The lookbehind guards the `.ts` branch only. Writing it as `(?<!\.d)\.(ts|js)$`
+ * would also reject a perfectly valid `foo.d.js`, since `.d` precedes `.js` there
+ * as well.
+ */
+export const DEFAULT_MIGRATION_FILE_PATTERN = /(?:(?<!\.d)\.ts|\.js)$/;
+
 /**
  * Migration runner configuration
  */
 export interface MigrationRunnerOptions {
   /** Directory containing migration files */
   migrationsDirectory: string;
-  /** Pattern to match migration files (default: *.ts, *.js) */
+  /** Pattern to match migration files (default: {@link DEFAULT_MIGRATION_FILE_PATTERN}) */
   pattern?: RegExp;
   /** State store for tracking migrations */
   stateStore: MongoStateStore;
@@ -59,7 +73,7 @@ export class MigrationRunner {
 
   constructor(options: MigrationRunnerOptions) {
     this.options = options;
-    this.pattern = options.pattern || /\.(ts|js)$/;
+    this.pattern = options.pattern || DEFAULT_MIGRATION_FILE_PATTERN;
   }
 
   /**

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

@@ -0,0 +1,25 @@
+/**
+ * Dependency-injection tokens of the TUS module.
+ *
+ * They live in a dedicated, import-free leaf file — never in `tus.module.ts` or a service — so that
+ * no file needing a token has to import the module (or vice versa) and close an import cycle.
+ *
+ * On a cycle, a token read at MODULE-EVALUATION time — inside an `@Inject()` decorator argument, in
+ * `design:paramtypes` metadata, or in a static field initializer — reads a `const` still in its
+ * temporal dead zone, and SWC-compiled builds (`nest start -b swc`) die at startup with:
+ *
+ *   ReferenceError: Cannot access 'TUS_CONFIG' before initialization
+ *
+ * A file that imports nothing can never be mid-evaluation when someone imports it, in any module
+ * system, under any compiler. That is the whole point — keep it import-free.
+ *
+ * `tsc`, `pnpm test` and `oxlint` are all blind to a regression here; only `pnpm run check:swc-tdz`
+ * sees it. See .claude/rules/architecture.md → "DI Token Placement (SWC-Safe)".
+ */
+
+/**
+ * Token for injecting the resolved TUS configuration.
+ *
+ * Injected type: `Required<ITusConfig>`.
+ */
+export const TUS_CONFIG = 'TUS_CONFIG';

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

@@ -5,12 +5,17 @@ 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 { TUS_CONFIG } from './tus.constants';
 import { normalizeTusConfig } from './interfaces/tus-config.interface';
 
 /**
- * Token for injecting the TUS configuration
+ * @deprecated Import from `./tus.constants` instead. Re-exported only so existing deep imports keep
+ * working; the token is declared in an import-free leaf so module and services stay acyclic
+ * (SWC-safe — see tus.constants.ts).
+ *
+ * Do NOT import it from here inside the TUS module itself — that is what re-creates the cycle.
  */
-export const TUS_CONFIG = 'TUS_CONFIG';
+export { TUS_CONFIG } from './tus.constants';
 
 /**
  * Options for TusModule.forRoot()