@ftschopp/dynatable-migrations 1.0.0 → 1.2.0

package/src/commands/status.ts

@@ -1,26 +1,9 @@
-import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
-import { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
 import { MigrationRunner } from '../core/runner';
+import { createDynamoDBClient } from '../core/client';
 import { MigrationConfig } from '../types';
 
 export async function showStatus(config: MigrationConfig): Promise<void> {
-  // Create DynamoDB client
-  const ddbClient = new DynamoDBClient({
-    region: config.client.region,
-    endpoint: config.client.endpoint,
-    credentials: config.client.credentials,
-  });
-
-  const client = DynamoDBDocumentClient.from(ddbClient, {
-    marshallOptions: {
-      removeUndefinedValues: true,
-      convertClassInstanceToMap: true,
-    },
-    unmarshallOptions: {
-      wrapNumbers: false,
-    },
-  });
-
+  const client = createDynamoDBClient(config);
   const runner = new MigrationRunner(client, config);
 
   try {

package/src/commands/up.ts

@@ -1,32 +1,19 @@
-import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
-import { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
 import { MigrationRunner } from '../core/runner';
+import { createDynamoDBClient } from '../core/client';
 import { MigrationConfig } from '../types';
 
-export async function runMigrations(config: MigrationConfig, limit?: number): Promise<void> {
-  // Create DynamoDB client
-  const ddbClient = new DynamoDBClient({
-    region: config.client.region,
-    endpoint: config.client.endpoint,
-    credentials: config.client.credentials,
-  });
-
-  const client = DynamoDBDocumentClient.from(ddbClient, {
-    marshallOptions: {
-      removeUndefinedValues: true,
-      convertClassInstanceToMap: true,
-    },
-    unmarshallOptions: {
-      wrapNumbers: false,
-    },
-  });
-
+export async function runMigrations(
+  config: MigrationConfig,
+  limit?: number,
+  dryRun: boolean = false
+): Promise<void> {
+  const client = createDynamoDBClient(config);
   const runner = new MigrationRunner(client, config);
 
   try {
-    const executed = await runner.up(limit);
+    const executed = await runner.up({ limit, dryRun });
 
-    if (executed.length > 0) {
+    if (!dryRun && executed.length > 0) {
       console.log(`\n🎉 Successfully applied ${executed.length} migration(s)`);
 
       const currentVersion = await runner.getCurrentVersion();

package/src/core/client.ts

@@ -0,0 +1,24 @@
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+import { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
+import { MigrationConfig } from '../types';
+
+/**
+ * Create a DynamoDB Document Client from config
+ */
+export function createDynamoDBClient(config: MigrationConfig): DynamoDBDocumentClient {
+  const ddbClient = new DynamoDBClient({
+    region: config.client.region,
+    endpoint: config.client.endpoint,
+    credentials: config.client.credentials,
+  });
+
+  return DynamoDBDocumentClient.from(ddbClient, {
+    marshallOptions: {
+      removeUndefinedValues: true,
+      convertClassInstanceToMap: true,
+    },
+    unmarshallOptions: {
+      wrapNumbers: false,
+    },
+  });
+}

package/src/core/loader.ts

@@ -1,5 +1,6 @@
 import * as fs from 'fs';
 import * as path from 'path';
+import * as crypto from 'crypto';
 import { Migration, MigrationFile } from '../types';
 
 /**
@@ -12,6 +13,14 @@ export class MigrationLoader {
     this.migrationsDir = migrationsDir;
   }
 
+  /**
+   * Calculate checksum of a file
+   */
+  calculateChecksum(filePath: string): string {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    return crypto.createHash('md5').update(content).digest('hex');
+  }
+
   /**
    * Load all migration files
    */
@@ -53,63 +62,96 @@ export class MigrationLoader {
    * Load single migration file
    */
   private async loadMigration(filePath: string): Promise<MigrationFile | null> {
-    try {
-      // Convert to absolute path
-      const absolutePath = path.isAbsolute(filePath)
-        ? filePath
-        : path.resolve(process.cwd(), filePath);
-
-      let module: any;
-
-      // For TypeScript files, use require (ts-node must be registered)
-      if (absolutePath.endsWith('.ts')) {
-        // Register ts-node if not already registered
-        try {
-          require('ts-node').register({
-            transpileOnly: true,
-            skipProject: true, // Don't use project tsconfig
-            compilerOptions: {
-              module: 'commonjs',
-              target: 'ES2020',
-              esModuleInterop: true,
-              moduleResolution: 'node',
-            },
-          });
-        } catch {
-          // ts-node might already be registered
-        }
-
-        // Clear require cache to reload file
-        delete require.cache[absolutePath];
+    // Convert to absolute path
+    const absolutePath = path.isAbsolute(filePath)
+      ? filePath
+      : path.resolve(process.cwd(), filePath);
+
+    let module: any;
 
+    // For TypeScript files, use require (ts-node must be registered)
+    if (absolutePath.endsWith('.ts')) {
+      // Register ts-node if not already registered
+      this.registerTsNode();
+
+      // Clear require cache to reload file
+      delete require.cache[absolutePath];
+
+      try {
         module = require(absolutePath);
-      } else {
-        // For JavaScript files, use dynamic import
+      } catch (error: any) {
+        throw new Error(
+          `Failed to load TypeScript migration ${filePath}: ${error.message}. ` +
+            `Ensure ts-node is installed and the file has valid TypeScript syntax.`
+        );
+      }
+    } else {
+      // For JavaScript files, use dynamic import
+      try {
         const fileUrl = `file://${absolutePath}`;
         module = await import(fileUrl);
+      } catch (error: any) {
+        throw new Error(
+          `Failed to load JavaScript migration ${filePath}: ${error.message}`
+        );
       }
+    }
 
-      const migration: Migration = module.migration || module.default;
+    const migration: Migration = module.migration || module.default;
 
-      if (!migration) {
-        console.warn(`Warning: No migration export found in ${filePath}`);
-        return null;
-      }
+    if (!migration) {
+      console.warn(`Warning: No migration export found in ${filePath}`);
+      return null;
+    }
+
+    // Validate migration structure
+    this.validateMigration(migration, filePath);
+
+    const fileName = path.basename(filePath);
+    const { version, name } = this.parseMigrationFileName(fileName);
 
-      // Validate migration structure
-      this.validateMigration(migration, filePath);
+    // Calculate checksum
+    const checksum = this.calculateChecksum(absolutePath);
 
-      const fileName = path.basename(filePath);
-      const { version, name } = this.parseMigrationFileName(fileName);
+    return {
+      version,
+      name,
+      filePath,
+      migration,
+      checksum,
+    };
+  }
 
-      return {
-        version,
-        name,
-        filePath,
-        migration,
-      };
+  /**
+   * Register ts-node for TypeScript file loading
+   */
+  private registerTsNode(): void {
+    try {
+      // Check if ts-node is already registered
+      const tsNodeSymbol = Symbol.for('ts-node.register.instance');
+      if ((process as any)[tsNodeSymbol]) {
+        return; // Already registered
+      }
+
+      require('ts-node').register({
+        transpileOnly: true,
+        skipProject: true, // Don't use project tsconfig
+        compilerOptions: {
+          module: 'commonjs',
+          target: 'ES2020',
+          esModuleInterop: true,
+          moduleResolution: 'node',
+        },
+      });
     } catch (error: any) {
-      throw new Error(`Failed to load migration ${filePath}: ${error.message}`);
+      if (error.code === 'MODULE_NOT_FOUND') {
+        throw new Error(
+          'ts-node is required to load TypeScript migrations. ' +
+            'Install it with: npm install ts-node'
+        );
+      }
+      // Other errors might mean ts-node is already registered differently
+      console.warn(`Warning: Could not register ts-node: ${error.message}`);
     }
   }
 

package/src/core/runner.ts

@@ -1,8 +1,25 @@
 import { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
+import {
+  ScanCommand,
+  QueryCommand,
+  GetCommand,
+  PutCommand,
+  UpdateCommand,
+  DeleteCommand,
+  BatchGetCommand,
+  BatchWriteCommand,
+  TransactWriteCommand,
+  TransactGetCommand,
+} from '@aws-sdk/lib-dynamodb';
 import { MigrationConfig, MigrationContext, MigrationFile, MigrationStatus } from '../types';
 import { DynamoDBMigrationTracker } from './tracker';
 import { MigrationLoader } from './loader';
 
+export interface RunOptions {
+  limit?: number;
+  dryRun?: boolean;
+}
+
 export class MigrationRunner {
   private client: DynamoDBDocumentClient;
   private config: MigrationConfig;
@@ -26,105 +43,175 @@ export class MigrationRunner {
   /**
    * Run all pending migrations
    */
-  async up(limit?: number): Promise<MigrationFile[]> {
+  async up(options: RunOptions = {}): Promise<MigrationFile[]> {
+    const { limit, dryRun = false } = options;
+
     await this.initialize();
 
-    const appliedMigrations = await this.tracker.getAppliedMigrations();
-    const appliedVersions = appliedMigrations
-      .filter((m) => m.status === 'applied')
-      .map((m) => m.version);
+    // Acquire lock unless dry run
+    if (!dryRun) {
+      const lockAcquired = await this.tracker.acquireLock();
+      if (!lockAcquired) {
+        throw new Error(
+          'Could not acquire migration lock. Another migration may be in progress. ' +
+            'If you believe this is an error, wait a few minutes and try again.'
+        );
+      }
+    }
 
-    let pendingMigrations = await this.loader.getPendingMigrations(appliedVersions);
+    try {
+      const appliedMigrations = await this.tracker.getAppliedMigrations();
+      const appliedVersions = appliedMigrations
+        .filter((m) => m.status === 'applied')
+        .map((m) => m.version);
+
+      // Check for checksum mismatches on applied migrations
+      for (const applied of appliedMigrations.filter((m) => m.status === 'applied')) {
+        const file = await this.loader.getMigration(applied.version);
+        if (file && applied.checksum && file.checksum !== applied.checksum) {
+          console.warn(
+            `⚠️  Warning: Migration ${applied.version} has been modified since it was applied. ` +
+              `Original checksum: ${applied.checksum}, Current: ${file.checksum}`
+          );
+        }
+      }
 
-    // Apply limit if specified
-    if (limit) {
-      pendingMigrations = pendingMigrations.slice(0, limit);
-    }
+      let pendingMigrations = await this.loader.getPendingMigrations(appliedVersions);
 
-    if (pendingMigrations.length === 0) {
-      console.log('✅ No pending migrations');
-      return [];
-    }
+      // Apply limit if specified
+      if (limit) {
+        pendingMigrations = pendingMigrations.slice(0, limit);
+      }
 
-    console.log(`\n📦 Found ${pendingMigrations.length} pending migration(s)\n`);
+      if (pendingMigrations.length === 0) {
+        console.log('✅ No pending migrations');
+        return [];
+      }
 
-    const executed: MigrationFile[] = [];
+      if (dryRun) {
+        console.log(`\n🔍 DRY RUN - Would apply ${pendingMigrations.length} migration(s):\n`);
+        for (const migrationFile of pendingMigrations) {
+          console.log(`   ${migrationFile.version}: ${migrationFile.name}`);
+          if (migrationFile.migration.description) {
+            console.log(`      ${migrationFile.migration.description}`);
+          }
+        }
+        console.log('\nNo changes were made.\n');
+        return pendingMigrations;
+      }
 
-    for (const migrationFile of pendingMigrations) {
-      try {
-        console.log(`⬆️  Applying ${migrationFile.version}: ${migrationFile.name}`);
+      console.log(`\n📦 Found ${pendingMigrations.length} pending migration(s)\n`);
 
-        const context = this.createContext();
-        await migrationFile.migration.up(context);
+      const executed: MigrationFile[] = [];
 
-        await this.tracker.markAsApplied(
-          migrationFile.version,
-          migrationFile.name,
-          migrationFile.migration.schema
-        );
+      for (const migrationFile of pendingMigrations) {
+        try {
+          console.log(`⬆️  Applying ${migrationFile.version}: ${migrationFile.name}`);
+
+          const context = this.createContext();
+          await migrationFile.migration.up(context);
 
-        console.log(`✅ Applied ${migrationFile.version}: ${migrationFile.name}\n`);
-        executed.push(migrationFile);
-      } catch (error: any) {
-        console.error(`❌ Failed to apply ${migrationFile.version}: ${error.message}\n`);
+          await this.tracker.markAsApplied(
+            migrationFile.version,
+            migrationFile.name,
+            migrationFile.migration.schema,
+            undefined,
+            migrationFile.checksum
+          );
 
-        await this.tracker.markAsFailed(migrationFile.version, error.message);
+          console.log(`✅ Applied ${migrationFile.version}: ${migrationFile.name}\n`);
+          executed.push(migrationFile);
+        } catch (error: any) {
+          console.error(`❌ Failed to apply ${migrationFile.version}: ${error.message}\n`);
 
-        throw new Error(`Migration ${migrationFile.version} failed: ${error.message}`);
+          await this.tracker.markAsFailed(migrationFile.version, error.message);
+
+          throw new Error(`Migration ${migrationFile.version} failed: ${error.message}`);
+        }
       }
-    }
 
-    return executed;
+      return executed;
+    } finally {
+      // Always release lock
+      if (!dryRun) {
+        await this.tracker.releaseLock();
+      }
+    }
   }
 
   /**
    * Rollback last migration
    */
-  async down(steps: number = 1): Promise<MigrationFile[]> {
+  async down(steps: number = 1, dryRun: boolean = false): Promise<MigrationFile[]> {
     await this.initialize();
 
-    const appliedMigrations = await this.tracker.getAppliedMigrations();
-    const applied = appliedMigrations
-      .filter((m) => m.status === 'applied')
-      .sort((a, b) => b.version.localeCompare(a.version))
-      .slice(0, steps);
-
-    if (applied.length === 0) {
-      console.log('✅ No migrations to rollback');
-      return [];
+    // Acquire lock unless dry run
+    if (!dryRun) {
+      const lockAcquired = await this.tracker.acquireLock();
+      if (!lockAcquired) {
+        throw new Error(
+          'Could not acquire migration lock. Another migration may be in progress.'
+        );
+      }
     }
 
-    console.log(`\n📦 Rolling back ${applied.length} migration(s)\n`);
-
-    const rolledBack: MigrationFile[] = [];
+    try {
+      const appliedMigrations = await this.tracker.getAppliedMigrations();
+      const applied = appliedMigrations
+        .filter((m) => m.status === 'applied')
+        .sort((a, b) => b.version.localeCompare(a.version))
+        .slice(0, steps);
 
-    for (const record of applied) {
-      try {
-        const migrationFile = await this.loader.getMigration(record.version);
+      if (applied.length === 0) {
+        console.log('✅ No migrations to rollback');
+        return [];
+      }
 
-        if (!migrationFile) {
-          throw new Error(`Migration file not found for version ${record.version}`);
+      if (dryRun) {
+        console.log(`\n🔍 DRY RUN - Would rollback ${applied.length} migration(s):\n`);
+        for (const record of applied) {
+          console.log(`   ${record.version}: ${record.name}`);
         }
+        console.log('\nNo changes were made.\n');
+        return [];
+      }
 
-        console.log(`⬇️  Rolling back ${migrationFile.version}: ${migrationFile.name}`);
+      console.log(`\n📦 Rolling back ${applied.length} migration(s)\n`);
 
-        const context = this.createContext();
-        await migrationFile.migration.down(context);
+      const rolledBack: MigrationFile[] = [];
 
-        await this.tracker.markAsRolledBack(migrationFile.version);
+      for (const record of applied) {
+        try {
+          const migrationFile = await this.loader.getMigration(record.version);
 
-        console.log(`✅ Rolled back ${migrationFile.version}: ${migrationFile.name}\n`);
-        rolledBack.push(migrationFile);
-      } catch (error: any) {
-        console.error(`❌ Failed to rollback ${record.version}: ${error.message}\n`);
+          if (!migrationFile) {
+            throw new Error(`Migration file not found for version ${record.version}`);
+          }
 
-        await this.tracker.markAsFailed(record.version, error.message);
+          console.log(`⬇️  Rolling back ${migrationFile.version}: ${migrationFile.name}`);
 
-        throw new Error(`Rollback of ${record.version} failed: ${error.message}`);
+          const context = this.createContext();
+          await migrationFile.migration.down(context);
+
+          await this.tracker.markAsRolledBack(migrationFile.version);
+
+          console.log(`✅ Rolled back ${migrationFile.version}: ${migrationFile.name}\n`);
+          rolledBack.push(migrationFile);
+        } catch (error: any) {
+          console.error(`❌ Failed to rollback ${record.version}: ${error.message}\n`);
+
+          await this.tracker.markAsFailed(record.version, error.message);
+
+          throw new Error(`Rollback of ${record.version} failed: ${error.message}`);
+        }
       }
-    }
 
-    return rolledBack;
+      return rolledBack;
+    } finally {
+      if (!dryRun) {
+        await this.tracker.releaseLock();
+      }
+    }
   }
 
   /**
@@ -187,20 +274,6 @@ export class MigrationRunner {
    * Create migration context
    */
   private createContext(): MigrationContext {
-    // Import DynamoDB commands
-    const {
-      ScanCommand,
-      QueryCommand,
-      GetCommand,
-      PutCommand,
-      UpdateCommand,
-      DeleteCommand,
-      BatchGetCommand,
-      BatchWriteCommand,
-      TransactWriteCommand,
-      TransactGetCommand,
-    } = require('@aws-sdk/lib-dynamodb');
-
     return {
       client: this.client,
       tableName: this.config.tableName,