@ftschopp/dynatable-migrations 1.0.0

package/src/core/loader.ts

@@ -0,0 +1,233 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { Migration, MigrationFile } from '../types';
+
+/**
+ * Load all migration files from directory
+ */
+export class MigrationLoader {
+  private migrationsDir: string;
+
+  constructor(migrationsDir: string) {
+    this.migrationsDir = migrationsDir;
+  }
+
+  /**
+   * Load all migration files
+   */
+  async loadMigrations(): Promise<MigrationFile[]> {
+    if (!fs.existsSync(this.migrationsDir)) {
+      throw new Error(`Migrations directory not found: ${this.migrationsDir}`);
+    }
+
+    const files = fs
+      .readdirSync(this.migrationsDir)
+      .filter(
+        (f) =>
+          (f.endsWith('.ts') || f.endsWith('.js')) &&
+          !f.endsWith('.d.ts') &&
+          this.isValidMigrationFileName(f)
+      )
+      .sort((a, b) => {
+        // Sort by semver
+        const versionA = a.match(/^(\d+\.\d+\.\d+)/)?.[1] || '0.0.0';
+        const versionB = b.match(/^(\d+\.\d+\.\d+)/)?.[1] || '0.0.0';
+        return this.compareSemver(versionA, versionB);
+      });
+
+    const migrations: MigrationFile[] = [];
+
+    for (const file of files) {
+      const filePath = path.join(this.migrationsDir, file);
+      const migration = await this.loadMigration(filePath);
+
+      if (migration) {
+        migrations.push(migration);
+      }
+    }
+
+    return migrations;
+  }
+
+  /**
+   * 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];
+
+        module = require(absolutePath);
+      } else {
+        // For JavaScript files, use dynamic import
+        const fileUrl = `file://${absolutePath}`;
+        module = await import(fileUrl);
+      }
+
+      const migration: Migration = module.migration || module.default;
+
+      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);
+
+      return {
+        version,
+        name,
+        filePath,
+        migration,
+      };
+    } catch (error: any) {
+      throw new Error(`Failed to load migration ${filePath}: ${error.message}`);
+    }
+  }
+
+  /**
+   * Validate migration file name format
+   * Expected: 1.0.0_migration_name.ts (semver format)
+   */
+  private isValidMigrationFileName(fileName: string): boolean {
+    // Match semver: 1.0.0_name.ts or 1.2.3_name.ts
+    return /^\d+\.\d+\.\d+_[\w-]+\.(ts|js)$/.test(fileName);
+  }
+
+  /**
+   * Parse version and name from file name
+   */
+  private parseMigrationFileName(fileName: string): {
+    version: string;
+    name: string;
+  } {
+    const match = fileName.match(/^(\d+\.\d+\.\d+)_([\w-]+)\.(ts|js)$/);
+
+    if (!match || !match[1] || !match[2]) {
+      throw new Error(
+        `Invalid migration file name format: ${fileName}. Expected: X.Y.Z_name.ts (semver)`
+      );
+    }
+
+    const version = match[1];
+    const name = match[2];
+
+    return { version, name };
+  }
+
+  /**
+   * Validate migration structure
+   */
+  private validateMigration(migration: Migration, filePath: string): void {
+    if (!migration.version) {
+      throw new Error(`Migration ${filePath} is missing 'version' property`);
+    }
+
+    if (!migration.name) {
+      throw new Error(`Migration ${filePath} is missing 'name' property`);
+    }
+
+    if (typeof migration.up !== 'function') {
+      throw new Error(`Migration ${filePath} is missing 'up' function or it's not a function`);
+    }
+
+    if (typeof migration.down !== 'function') {
+      throw new Error(`Migration ${filePath} is missing 'down' function or it's not a function`);
+    }
+  }
+
+  /**
+   * Get pending migrations (not yet applied)
+   */
+  async getPendingMigrations(appliedVersions: string[]): Promise<MigrationFile[]> {
+    const allMigrations = await this.loadMigrations();
+    return allMigrations.filter((m) => !appliedVersions.includes(m.version));
+  }
+
+  /**
+   * Get migration by version
+   */
+  async getMigration(version: string): Promise<MigrationFile | null> {
+    const migrations = await this.loadMigrations();
+    return migrations.find((m) => m.version === version) || null;
+  }
+
+  /**
+   * Generate next version number (increments patch by default)
+   */
+  async getNextVersion(): Promise<string> {
+    const migrations = await this.loadMigrations();
+
+    if (migrations.length === 0) {
+      return '0.1.0';
+    }
+
+    // Get last version
+    const lastMigration = migrations[migrations.length - 1];
+    if (!lastMigration) {
+      return '0.1.0';
+    }
+
+    const lastVersion = lastMigration.version;
+
+    // Parse semver and increment patch
+    const parts = lastVersion.split('.');
+    if (parts.length === 3 && parts[0] && parts[1] && parts[2]) {
+      const major = parseInt(parts[0], 10);
+      const minor = parseInt(parts[1], 10);
+      const patch = parseInt(parts[2], 10);
+
+      // Increment patch version
+      return `${major}.${minor}.${patch + 1}`;
+    }
+
+    return '0.1.0';
+  }
+
+  /**
+   * Compare semver versions
+   * Returns: -1 if a < b, 0 if a === b, 1 if a > b
+   */
+  private compareSemver(a: string, b: string): number {
+    const partsA = a.split('.').map((n) => parseInt(n, 10));
+    const partsB = b.split('.').map((n) => parseInt(n, 10));
+
+    for (let i = 0; i < 3; i++) {
+      const numA = partsA[i] || 0;
+      const numB = partsB[i] || 0;
+
+      if (numA > numB) return 1;
+      if (numA < numB) return -1;
+    }
+
+    return 0;
+  }
+}

package/src/core/runner.ts

@@ -0,0 +1,223 @@
+import { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
+import { MigrationConfig, MigrationContext, MigrationFile, MigrationStatus } from '../types';
+import { DynamoDBMigrationTracker } from './tracker';
+import { MigrationLoader } from './loader';
+
+export class MigrationRunner {
+  private client: DynamoDBDocumentClient;
+  private config: MigrationConfig;
+  private tracker: DynamoDBMigrationTracker;
+  private loader: MigrationLoader;
+
+  constructor(client: DynamoDBDocumentClient, config: MigrationConfig) {
+    this.client = client;
+    this.config = config;
+    this.tracker = new DynamoDBMigrationTracker(client, config);
+    this.loader = new MigrationLoader(config.migrationsDir || './migrations');
+  }
+
+  /**
+   * Initialize migration system
+   */
+  async initialize(): Promise<void> {
+    await this.tracker.initialize();
+  }
+
+  /**
+   * Run all pending migrations
+   */
+  async up(limit?: number): Promise<MigrationFile[]> {
+    await this.initialize();
+
+    const appliedMigrations = await this.tracker.getAppliedMigrations();
+    const appliedVersions = appliedMigrations
+      .filter((m) => m.status === 'applied')
+      .map((m) => m.version);
+
+    let pendingMigrations = await this.loader.getPendingMigrations(appliedVersions);
+
+    // Apply limit if specified
+    if (limit) {
+      pendingMigrations = pendingMigrations.slice(0, limit);
+    }
+
+    if (pendingMigrations.length === 0) {
+      console.log('✅ No pending migrations');
+      return [];
+    }
+
+    console.log(`\n📦 Found ${pendingMigrations.length} pending migration(s)\n`);
+
+    const executed: MigrationFile[] = [];
+
+    for (const migrationFile of pendingMigrations) {
+      try {
+        console.log(`⬆️  Applying ${migrationFile.version}: ${migrationFile.name}`);
+
+        const context = this.createContext();
+        await migrationFile.migration.up(context);
+
+        await this.tracker.markAsApplied(
+          migrationFile.version,
+          migrationFile.name,
+          migrationFile.migration.schema
+        );
+
+        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.markAsFailed(migrationFile.version, error.message);
+
+        throw new Error(`Migration ${migrationFile.version} failed: ${error.message}`);
+      }
+    }
+
+    return executed;
+  }
+
+  /**
+   * Rollback last migration
+   */
+  async down(steps: number = 1): 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 [];
+    }
+
+    console.log(`\n📦 Rolling back ${applied.length} migration(s)\n`);
+
+    const rolledBack: MigrationFile[] = [];
+
+    for (const record of applied) {
+      try {
+        const migrationFile = await this.loader.getMigration(record.version);
+
+        if (!migrationFile) {
+          throw new Error(`Migration file not found for version ${record.version}`);
+        }
+
+        console.log(`⬇️  Rolling back ${migrationFile.version}: ${migrationFile.name}`);
+
+        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;
+  }
+
+  /**
+   * Get migration status
+   */
+  async status(): Promise<MigrationStatus[]> {
+    await this.initialize();
+
+    const allMigrations = await this.loader.loadMigrations();
+    const appliedMigrations = await this.tracker.getAppliedMigrations();
+
+    const appliedMap = new Map(appliedMigrations.map((m) => [m.version, m]));
+
+    return allMigrations.map((migrationFile) => {
+      const record = appliedMap.get(migrationFile.version);
+
+      if (!record) {
+        return {
+          version: migrationFile.version,
+          name: migrationFile.name,
+          status: 'pending' as const,
+        };
+      }
+
+      return {
+        version: record.version,
+        name: record.name,
+        status: record.status,
+        appliedAt: record.appliedAt,
+        error: record.error,
+      };
+    });
+  }
+
+  /**
+   * Get current version
+   */
+  async getCurrentVersion(): Promise<string | null> {
+    await this.initialize();
+    return this.tracker.getCurrentVersion();
+  }
+
+  /**
+   * Reset all migrations (rollback everything)
+   */
+  async reset(): Promise<void> {
+    const appliedMigrations = await this.tracker.getAppliedMigrations();
+    const appliedCount = appliedMigrations.filter((m) => m.status === 'applied').length;
+
+    if (appliedCount === 0) {
+      console.log('✅ No migrations to reset');
+      return;
+    }
+
+    console.log(`\n⚠️  Resetting ${appliedCount} migration(s)\n`);
+    await this.down(appliedCount);
+  }
+
+  /**
+   * 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,
+      tracker: this.tracker,
+      config: this.config,
+      dynamodb: {
+        ScanCommand,
+        QueryCommand,
+        GetCommand,
+        PutCommand,
+        UpdateCommand,
+        DeleteCommand,
+        BatchGetCommand,
+        BatchWriteCommand,
+        TransactWriteCommand,
+        TransactGetCommand,
+      },
+    };
+  }
+}

package/src/core/tracker.ts

@@ -0,0 +1,219 @@
+import { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
+import { PutCommand, GetCommand, QueryCommand, UpdateCommand } from '@aws-sdk/lib-dynamodb';
+import { MigrationTracker, MigrationRecord, SchemaChange, MigrationConfig } from '../types';
+
+export class DynamoDBMigrationTracker implements MigrationTracker {
+  private client: DynamoDBDocumentClient;
+  private tableName: string;
+  private trackingPrefix: string;
+  private gsi1Name: string;
+
+  constructor(client: DynamoDBDocumentClient, config: MigrationConfig) {
+    this.client = client;
+    this.tableName = config.tableName;
+    this.trackingPrefix = config.trackingPrefix || '_SCHEMA#VERSION';
+    this.gsi1Name = config.gsi1Name || 'GSI1';
+  }
+
+  async initialize(): Promise<void> {
+    // Check if current version pointer exists, if not create it
+    const current = await this.getCurrentVersion();
+    if (!current) {
+      // Create initial version pointer
+      await this.client.send(
+        new PutCommand({
+          TableName: this.tableName,
+          Item: {
+            PK: `${this.trackingPrefix}#CURRENT`,
+            SK: `${this.trackingPrefix}#CURRENT`,
+            GSI1PK: 'SCHEMA#CURRENT',
+            GSI1SK: 'v0000',
+            currentVersion: 'v0000',
+            updatedAt: new Date().toISOString(),
+          },
+        })
+      );
+    }
+  }
+
+  async getAppliedMigrations(): Promise<MigrationRecord[]> {
+    const result = await this.client.send(
+      new QueryCommand({
+        TableName: this.tableName,
+        KeyConditionExpression: 'PK = :pk',
+        ExpressionAttributeValues: {
+          ':pk': this.trackingPrefix,
+        },
+      })
+    );
+
+    return (result.Items || []) as MigrationRecord[];
+  }
+
+  async getCurrentVersion(): Promise<string | null> {
+    const result = await this.client.send(
+      new GetCommand({
+        TableName: this.tableName,
+        Key: {
+          PK: `${this.trackingPrefix}#CURRENT`,
+          SK: `${this.trackingPrefix}#CURRENT`,
+        },
+      })
+    );
+
+    return result.Item?.currentVersion || null;
+  }
+
+  async markAsApplied(
+    version: string,
+    name: string,
+    schemaDefinition?: Record<string, any>,
+    schemaChanges?: SchemaChange[]
+  ): Promise<void> {
+    const now = new Date().toISOString();
+
+    // Create migration record
+    await this.client.send(
+      new PutCommand({
+        TableName: this.tableName,
+        Item: {
+          PK: this.trackingPrefix,
+          SK: version,
+          version,
+          name,
+          timestamp: now,
+          appliedAt: now,
+          status: 'applied',
+          schemaDefinition,
+          schemaChanges,
+        } as MigrationRecord,
+      })
+    );
+
+    // Update current version pointer
+    await this.client.send(
+      new UpdateCommand({
+        TableName: this.tableName,
+        Key: {
+          PK: `${this.trackingPrefix}#CURRENT`,
+          SK: `${this.trackingPrefix}#CURRENT`,
+        },
+        UpdateExpression: 'SET currentVersion = :version, updatedAt = :updatedAt, GSI1SK = :gsi1sk',
+        ExpressionAttributeValues: {
+          ':version': version,
+          ':updatedAt': now,
+          ':gsi1sk': version,
+        },
+      })
+    );
+  }
+
+  async markAsRolledBack(version: string): Promise<void> {
+    await this.client.send(
+      new UpdateCommand({
+        TableName: this.tableName,
+        Key: {
+          PK: this.trackingPrefix,
+          SK: version,
+        },
+        UpdateExpression: 'SET #status = :status, rolledBackAt = :timestamp',
+        ExpressionAttributeNames: {
+          '#status': 'status',
+        },
+        ExpressionAttributeValues: {
+          ':status': 'rolled_back',
+          ':timestamp': new Date().toISOString(),
+        },
+      })
+    );
+
+    // Find previous version and update current pointer
+    const migrations = await this.getAppliedMigrations();
+    const appliedMigrations = migrations
+      .filter((m) => m.status === 'applied' && m.version !== version)
+      .sort((a, b) => b.version.localeCompare(a.version));
+
+    const previousVersion = appliedMigrations[0]?.version || 'v0000';
+
+    await this.client.send(
+      new UpdateCommand({
+        TableName: this.tableName,
+        Key: {
+          PK: `${this.trackingPrefix}#CURRENT`,
+          SK: `${this.trackingPrefix}#CURRENT`,
+        },
+        UpdateExpression: 'SET currentVersion = :version, updatedAt = :updatedAt, GSI1SK = :gsi1sk',
+        ExpressionAttributeValues: {
+          ':version': previousVersion,
+          ':updatedAt': new Date().toISOString(),
+          ':gsi1sk': previousVersion,
+        },
+      })
+    );
+  }
+
+  async markAsFailed(version: string, error: string): Promise<void> {
+    await this.client.send(
+      new UpdateCommand({
+        TableName: this.tableName,
+        Key: {
+          PK: this.trackingPrefix,
+          SK: version,
+        },
+        UpdateExpression: 'SET #status = :status, #error = :error, failedAt = :timestamp',
+        ExpressionAttributeNames: {
+          '#status': 'status',
+          '#error': 'error',
+        },
+        ExpressionAttributeValues: {
+          ':status': 'failed',
+          ':error': error,
+          ':timestamp': new Date().toISOString(),
+        },
+      })
+    );
+  }
+
+  async recordSchemaChange(change: SchemaChange): Promise<void> {
+    const currentVersion = await this.getCurrentVersion();
+    if (!currentVersion || currentVersion === 'v0000') {
+      throw new Error('Cannot record schema change: No migration has been applied yet');
+    }
+
+    // Append to schemaChanges array
+    await this.client.send(
+      new UpdateCommand({
+        TableName: this.tableName,
+        Key: {
+          PK: this.trackingPrefix,
+          SK: currentVersion,
+        },
+        UpdateExpression:
+          'SET schemaChanges = list_append(if_not_exists(schemaChanges, :empty_list), :change)',
+        ExpressionAttributeValues: {
+          ':empty_list': [],
+          ':change': [change],
+        },
+      })
+    );
+  }
+
+  async getMigration(version: string): Promise<MigrationRecord | null> {
+    const result = await this.client.send(
+      new GetCommand({
+        TableName: this.tableName,
+        Key: {
+          PK: this.trackingPrefix,
+          SK: version,
+        },
+      })
+    );
+
+    return (result.Item as MigrationRecord) || null;
+  }
+
+  async isApplied(version: string): Promise<boolean> {
+    const migration = await this.getMigration(version);
+    return migration?.status === 'applied';
+  }
+}

package/src/index.ts

@@ -0,0 +1,23 @@
+/**
+ * @ftschopp/dynatable-migrations
+ * DynamoDB migration tool for single table design with schema versioning
+ */
+
+// Types
+export * from './types';
+
+// Core
+export { DynamoDBMigrationTracker } from './core/tracker';
+export { MigrationLoader } from './core/loader';
+export { MigrationRunner } from './core/runner';
+export { ConfigLoader, loadConfig } from './core/config';
+
+// Template
+export { generateMigrationTemplate } from './templates/migration';
+
+// Commands (for programmatic use)
+export { createMigration } from './commands/create';
+export { runMigrations } from './commands/up';
+export { rollbackMigrations } from './commands/down';
+export { showStatus } from './commands/status';
+export { initProject } from './commands/init';