@lenne.tech/nest-server 11.31.0 → 11.31.2

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

@@ -33,6 +33,59 @@ export interface MigrationFile {
  */
 export const DEFAULT_MIGRATION_FILE_PATTERN = /(?:(?<!\.d)\.ts|\.js)$/;
 
+/**
+ * Matches the trailing `.ts`/`.js` extension stripped by {@link migrationId}.
+ * Hoisted to module level so `migrationId` allocates no per-call RegExp wrapper.
+ */
+const MIGRATION_EXTENSION_PATTERN = /\.(ts|js)$/;
+
+/**
+ * Migration identity = the timestamped file stem WITHOUT its `.ts`/`.js` extension.
+ *
+ * A migration keeps its identity when a project switches its production image from
+ * ts-node (`1699-foo.ts`) to compiled JavaScript (`1699-foo.js`) — the recommended
+ * prod setup, since the image prunes ts-node. Comparing raw filenames would make
+ * every compiled `.js` migration look "pending" against a state recorded under `.ts`
+ * names and re-run already-applied migrations (data corruption on existing DBs).
+ * Normalising both sides makes the transition safe with no state rewrite.
+ *
+ * @param title Migration title, usually the filename (e.g. `1699000000000-foo.ts`)
+ * @returns The extension-agnostic identity (e.g. `1699000000000-foo`)
+ * @example
+ * migrationId('1699000000000-foo.ts'); // '1699000000000-foo'
+ * migrationId('1699000000000-foo.js'); // '1699000000000-foo'
+ * migrationId('1699000000000-foo');    // '1699000000000-foo' (already extensionless)
+ */
+export function migrationId(title: string): string {
+  return title.replace(MIGRATION_EXTENSION_PATTERN, '');
+}
+
+/**
+ * Parse the `NSC__MIGRATE__STRICT` environment variable into a boolean.
+ *
+ * Truthy values: `1`, `true`, `yes` (case-insensitive, surrounding whitespace ignored —
+ * a real risk with Docker/compose env files). Every other value means `false` (tolerate,
+ * the safe default); non-empty unrecognized values additionally emit a warning so a typo
+ * like `NSC__MIGRATE__STRICT=on` does not silently disable the control the operator
+ * intended to enable.
+ *
+ * Shared by the CLI (`migrate-cli.ts`) and the {@link MigrationRunner} constructor, so
+ * the env var behaves identically for CLI and programmatic runners.
+ */
+export function parseStrictEnv(value: string | undefined = process.env.NSC__MIGRATE__STRICT): boolean {
+  if (value === undefined) {
+    return false;
+  }
+  const normalized = value.trim().toLowerCase();
+  if (['1', 'true', 'yes'].includes(normalized)) {
+    return true;
+  }
+  if (normalized !== '' && !['0', 'false', 'no'].includes(normalized)) {
+    console.warn(`[migrate] Unrecognized NSC__MIGRATE__STRICT value "${value}" — treating as false (tolerate).`);
+  }
+  return false;
+}
+
 /**
  * Migration runner configuration
  */
@@ -43,6 +96,23 @@ export interface MigrationRunnerOptions {
   pattern?: RegExp;
   /** State store for tracking migrations */
   stateStore: MongoStateStore;
+  /**
+   * Fail hard when a migration recorded in the state has no file on disk.
+   *
+   * Default: resolved from the `NSC__MIGRATE__STRICT` environment variable (see
+   * {@link parseStrictEnv}), falling back to `false` (tolerate) — recorded migrations
+   * whose files were deleted are ignored: `up()` skips them (with a warning) and the
+   * server still starts. Migrations are tracked in git and can be restored, so old
+   * migration files can be pruned without blocking boot. Set `true` to enforce
+   * state/disk integrity (missing file → error in `up()` and `migrate list`).
+   *
+   * Applies to `up()` and `status()`/`migrate list` only — `down()` ALWAYS fails hard
+   * on a missing rollback file, because rollback is an explicit operator action and
+   * never a boot path (an exit 0 with no rollback performed would mislead scripts).
+   *
+   * @see `--strict` CLI flag and `NSC__MIGRATE__STRICT` env var in `cli/migrate-cli.ts`
+   */
+  strict?: boolean;
 }
 
 /**
@@ -72,12 +142,21 @@ export class MigrationRunner {
   private pattern: RegExp;
 
   constructor(options: MigrationRunnerOptions) {
-    this.options = options;
+    // Resolve the strict default from the environment so NSC__MIGRATE__STRICT works
+    // identically for programmatic runners and the CLI (which parses it itself).
+    this.options = { ...options, strict: options.strict ?? parseStrictEnv() };
     this.pattern = options.pattern || DEFAULT_MIGRATION_FILE_PATTERN;
   }
 
   /**
    * Load all migration files from the migrations directory
+   *
+   * Files are deduplicated by {@link migrationId}: when both `foo.ts` and `foo.js`
+   * are present (overlapping `outDir`, source + build output copied into one image),
+   * they are ONE migration — loading both would execute it twice in a single `up()`
+   * run (the exact double-execution the identity concept exists to prevent). The
+   * `.js` file wins deterministically (`.js` sorts before `.ts`), matching the
+   * compiled-production intent; the duplicate is skipped with a warning.
    */
   private async loadMigrationFiles(): Promise<MigrationFile[]> {
     const files = fs
@@ -86,8 +165,17 @@ export class MigrationRunner {
       .sort(); // Sort alphabetically (timestamp-based filenames will be in order)
 
     const migrations: MigrationFile[] = [];
+    const seenIds = new Set<string>();
 
     for (const file of files) {
+      const id = migrationId(file);
+      if (seenIds.has(id)) {
+        console.warn(
+          `[migrate] duplicate files for migration "${id}" — skipping ${file} (a same-named file was already loaded)`,
+        );
+        continue;
+      }
+
       const filePath = path.join(this.options.migrationsDirectory, file);
 
       const module = require(filePath);
@@ -101,6 +189,7 @@ export class MigrationRunner {
       const timestampMatch = file.match(/^(\d+)-/);
       const timestamp = timestampMatch ? parseInt(timestampMatch[1], 10) : Date.now();
 
+      seenIds.add(id);
       migrations.push({
         down: module.down,
         filePath,
@@ -121,9 +210,24 @@ export class MigrationRunner {
 
     const allMigrations = await this.loadMigrationFiles();
     const state = await this.options.stateStore.loadAsync();
-    const completedMigrations = (state.migrations || []).map((m) => m.title);
+    const recorded = state.migrations || [];
+    const presentIds = new Set(allMigrations.map((m) => migrationId(m.title)));
+
+    // Recorded migrations whose file is gone. Tolerated by default (git-tracked and
+    // restorable); in strict mode this is a hard error so integrity drift is caught.
+    const missing = recorded.filter((m) => !presentIds.has(migrationId(m.title)));
+    if (missing.length > 0) {
+      const list = missing.map((m) => m.title).join(', ');
+      if (this.options.strict) {
+        throw new Error(`Strict mode: ${missing.length} recorded migration file(s) missing: ${list}`);
+      }
+      console.warn(
+        `[migrate] ${missing.length} recorded migration file(s) missing — tolerated (strict=false): ${list}`,
+      );
+    }
 
-    const pendingMigrations = allMigrations.filter((m) => !completedMigrations.includes(m.title));
+    const completedIds = new Set(recorded.map((m) => migrationId(m.title)));
+    const pendingMigrations = allMigrations.filter((m) => !completedIds.has(migrationId(m.title)));
 
     if (pendingMigrations.length === 0) {
       console.log('No pending migrations');
@@ -181,10 +285,14 @@ export class MigrationRunner {
 
     const lastMigration = completedMigrations[completedMigrations.length - 1];
     const allMigrations = await this.loadMigrationFiles();
-    const migrationToRollback = allMigrations.find((m) => m.title === lastMigration.title);
+    const rollbackId = migrationId(lastMigration.title);
+    const migrationToRollback = allMigrations.find((m) => migrationId(m.title) === rollbackId);
 
     if (!migrationToRollback) {
-      throw new Error(`Migration file not found: ${lastMigration.title}`);
+      // Always a hard error, independent of `strict`: down() is an explicit operator
+      // action and never a boot path — the boot-tolerance rationale does not apply,
+      // and an exit 0 with no rollback performed would mislead scripted rollbacks.
+      throw new Error(`Migration file not found: ${lastMigration.title} — restore the file from git to roll back.`);
     }
 
     if (!migrationToRollback.down) {
@@ -216,18 +324,27 @@ export class MigrationRunner {
 
   /**
    * Get migration status
+   *
+   * `missing` lists recorded migrations whose file is gone from disk (identity-based,
+   * so a `.ts`-recorded migration with a compiled `.js` on disk is NOT missing) — the
+   * same integrity drift `up()` warns about, surfaced here so `migrate list` can show
+   * it before a deploy or file pruning.
    */
   async status(): Promise<{
     completed: string[];
+    missing: string[];
     pending: string[];
   }> {
     const allMigrations = await this.loadMigrationFiles();
     const state = await this.options.stateStore.loadAsync();
     const completedMigrations = (state.migrations || []).map((m) => m.title);
+    const completedIds = new Set(completedMigrations.map(migrationId));
+    const presentIds = new Set(allMigrations.map((m) => migrationId(m.title)));
 
     return {
       completed: completedMigrations,
-      pending: allMigrations.filter((m) => !completedMigrations.includes(m.title)).map((m) => m.title),
+      missing: completedMigrations.filter((title) => !presentIds.has(migrationId(title))),
+      pending: allMigrations.filter((m) => !completedIds.has(migrationId(m.title))).map((m) => m.title),
     };
   }