@ftschopp/dynatable-migrations 1.0.0

package/src/cli.ts

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import { loadConfig } from './core/config';
+import { createMigration } from './commands/create';
+import { runMigrations } from './commands/up';
+import { rollbackMigrations } from './commands/down';
+import { showStatus } from './commands/status';
+import { initProject } from './commands/init';
+
+const program = new Command();
+
+program
+  .name('dynatable-migrate')
+  .description('DynamoDB migration tool for single table design')
+  .version('0.1.0');
+
+// Init command
+program
+  .command('init')
+  .description('Initialize migrations in current project')
+  .action(async () => {
+    try {
+      await initProject();
+    } catch (error: any) {
+      console.error(`Error: ${error.message}`);
+      process.exit(1);
+    }
+  });
+
+// Create command
+program
+  .command('create <name>')
+  .description('Create a new migration file')
+  .option('-c, --config <path>', 'Path to config file')
+  .option('-t, --type <type>', 'Version bump type: major, minor, or patch (default: patch)')
+  .option('-e, --explicit <version>', 'Explicit version (e.g., 2.0.0)')
+  .action(async (name: string, options) => {
+    try {
+      let migrationsDir = './migrations';
+
+      // Try to load config to get migrations directory
+      try {
+        const config = await loadConfig(options.config);
+        migrationsDir = config.migrationsDir || './migrations';
+      } catch {
+        // If config doesn't exist, use default
+      }
+
+      await createMigration(name, migrationsDir, options.type, options.explicit);
+    } catch (error: any) {
+      console.error(`Error: ${error.message}`);
+      process.exit(1);
+    }
+  });
+
+// Up command
+program
+  .command('up')
+  .description('Run pending migrations')
+  .option('-c, --config <path>', 'Path to config file')
+  .option('-l, --limit <number>', 'Limit number of migrations to run')
+  .action(async (options) => {
+    try {
+      const config = await loadConfig(options.config);
+      const limit = options.limit ? parseInt(options.limit, 10) : undefined;
+      await runMigrations(config, limit);
+    } catch (error: any) {
+      console.error(`Error: ${error.message}`);
+      process.exit(1);
+    }
+  });
+
+// Down command
+program
+  .command('down')
+  .description('Rollback migrations')
+  .option('-c, --config <path>', 'Path to config file')
+  .option('-s, --steps <number>', 'Number of migrations to rollback', '1')
+  .action(async (options) => {
+    try {
+      const config = await loadConfig(options.config);
+      const steps = parseInt(options.steps, 10);
+      await rollbackMigrations(config, steps);
+    } catch (error: any) {
+      console.error(`Error: ${error.message}`);
+      process.exit(1);
+    }
+  });
+
+// Status command
+program
+  .command('status')
+  .description('Show migration status')
+  .option('-c, --config <path>', 'Path to config file')
+  .action(async (options) => {
+    try {
+      const config = await loadConfig(options.config);
+      await showStatus(config);
+    } catch (error: any) {
+      console.error(`Error: ${error.message}`);
+      process.exit(1);
+    }
+  });
+
+program.parse(process.argv);

package/src/commands/create.ts

@@ -0,0 +1,110 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { MigrationLoader } from '../core/loader';
+import { generateMigrationTemplate } from '../templates/migration';
+
+type VersionBumpType = 'major' | 'minor' | 'patch';
+
+/**
+ * Get next version based on bump type
+ */
+async function getNextVersion(loader: MigrationLoader, bumpType: VersionBumpType): Promise<string> {
+  const migrations = await loader['loadMigrations']();
+
+  if (migrations.length === 0) {
+    return '0.1.0';
+  }
+
+  const lastMigration = migrations[migrations.length - 1];
+  if (!lastMigration) {
+    return '0.1.0';
+  }
+
+  const lastVersion = lastMigration.version;
+  const parts = lastVersion.split('.');
+
+  if (parts.length !== 3 || !parts[0] || !parts[1] || !parts[2]) {
+    return '0.1.0';
+  }
+
+  const major = parseInt(parts[0], 10);
+  const minor = parseInt(parts[1], 10);
+  const patch = parseInt(parts[2], 10);
+
+  switch (bumpType) {
+    case 'major':
+      return `${major + 1}.0.0`;
+    case 'minor':
+      return `${major}.${minor + 1}.0`;
+    case 'patch':
+      return `${major}.${minor}.${patch + 1}`;
+    default:
+      return `${major}.${minor}.${patch + 1}`;
+  }
+}
+
+export async function createMigration(
+  name: string,
+  migrationsDir: string = './migrations',
+  bumpType?: string,
+  explicitVersion?: string
+): Promise<void> {
+  // Ensure migrations directory exists
+  if (!fs.existsSync(migrationsDir)) {
+    fs.mkdirSync(migrationsDir, { recursive: true });
+    console.log(`📁 Created migrations directory: ${migrationsDir}`);
+  }
+
+  // Generate version
+  const loader = new MigrationLoader(migrationsDir);
+  let version: string;
+
+  if (explicitVersion) {
+    // Validate explicit version is semver
+    if (!/^\d+\.\d+\.\d+$/.test(explicitVersion)) {
+      throw new Error(
+        `Invalid version format: ${explicitVersion}. Expected semver format (e.g., 1.0.0)`
+      );
+    }
+    version = explicitVersion;
+  } else if (bumpType) {
+    // Validate bump type
+    const validTypes: VersionBumpType[] = ['major', 'minor', 'patch'];
+    if (!validTypes.includes(bumpType as VersionBumpType)) {
+      throw new Error(`Invalid bump type: ${bumpType}. Expected: major, minor, or patch`);
+    }
+    version = await getNextVersion(loader, bumpType as VersionBumpType);
+  } else {
+    // Default: increment patch
+    version = await getNextVersion(loader, 'patch');
+  }
+
+  // Sanitize name (replace spaces and special chars with underscores)
+  const sanitizedName = name.replace(/[^a-zA-Z0-9]/g, '_').toLowerCase();
+
+  // Generate file name
+  const fileName = `${version}_${sanitizedName}.ts`;
+  const filePath = path.join(migrationsDir, fileName);
+
+  // Check if file already exists
+  if (fs.existsSync(filePath)) {
+    throw new Error(`Migration file already exists: ${filePath}`);
+  }
+
+  // Generate migration content
+  const content = generateMigrationTemplate(version, sanitizedName);
+
+  // Write file
+  fs.writeFileSync(filePath, content, 'utf-8');
+
+  // Determine version type for informational message
+  const versionType = bumpType ? bumpType.toUpperCase() : explicitVersion ? 'EXPLICIT' : 'PATCH';
+
+  console.log(`\n✅ Created migration: ${fileName}`);
+  console.log(`   Path: ${filePath}`);
+  console.log(`   Version: ${version} (${versionType})\n`);
+  console.log(`Next steps:`);
+  console.log(`  1. Edit ${fileName}`);
+  console.log(`  2. Implement up() and down() functions`);
+  console.log(`  3. Run: dynatable-migrate up\n`);
+}

package/src/commands/down.ts

@@ -0,0 +1,42 @@
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+import { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
+import { MigrationRunner } from '../core/runner';
+import { MigrationConfig } from '../types';
+
+export async function rollbackMigrations(
+  config: MigrationConfig,
+  steps: number = 1
+): 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 runner = new MigrationRunner(client, config);
+
+  try {
+    const rolledBack = await runner.down(steps);
+
+    if (rolledBack.length > 0) {
+      console.log(`\n🎉 Successfully rolled back ${rolledBack.length} migration(s)`);
+
+      const currentVersion = await runner.getCurrentVersion();
+      console.log(`📌 Current version: ${currentVersion}\n`);
+    }
+  } catch (error: any) {
+    console.error(`\n❌ Rollback failed: ${error.message}\n`);
+    process.exit(1);
+  }
+}

package/src/commands/init.ts

@@ -0,0 +1,37 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { ConfigLoader } from '../core/config';
+
+export async function initProject(): Promise<void> {
+  const cwd = process.cwd();
+
+  console.log('\n🚀 Initializing DynamoDB migrations\n');
+
+  // Create migrations directory
+  const migrationsDir = path.join(cwd, 'migrations');
+  if (!fs.existsSync(migrationsDir)) {
+    fs.mkdirSync(migrationsDir, { recursive: true });
+    console.log(`✅ Created: ${migrationsDir}/`);
+
+    // Create .gitkeep
+    fs.writeFileSync(path.join(migrationsDir, '.gitkeep'), '');
+  } else {
+    console.log(`⚠️  Directory already exists: ${migrationsDir}/`);
+  }
+
+  // Create config file
+  const configPath = path.join(cwd, 'dynatable.config.js');
+  if (!fs.existsSync(configPath)) {
+    ConfigLoader.createDefaultConfig(configPath);
+  } else {
+    console.log(`⚠️  Config already exists: ${configPath}`);
+  }
+
+  console.log('\n✅ Initialization complete!\n');
+  console.log('Next steps:');
+  console.log('  1. Edit dynatable.config.js with your DynamoDB settings');
+  console.log('  2. Create your first migration:');
+  console.log('     dynatable-migrate create add_user_email');
+  console.log('  3. Run migrations:');
+  console.log('     dynatable-migrate up\n');
+}

package/src/commands/status.ts

@@ -0,0 +1,92 @@
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+import { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
+import { MigrationRunner } from '../core/runner';
+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 runner = new MigrationRunner(client, config);
+
+  try {
+    const statuses = await runner.status();
+    const currentVersion = await runner.getCurrentVersion();
+
+    console.log(`\n📊 Migration Status\n`);
+    console.log(`Table: ${config.tableName}`);
+    console.log(`Current version: ${currentVersion || 'v0000 (no migrations)'}`);
+    console.log(`Migrations directory: ${config.migrationsDir || './migrations'}\n`);
+
+    if (statuses.length === 0) {
+      console.log('No migrations found.\n');
+      return;
+    }
+
+    // Group by status
+    const pending = statuses.filter((s) => s.status === 'pending');
+    const applied = statuses.filter((s) => s.status === 'applied');
+    const failed = statuses.filter((s) => s.status === 'failed');
+    const rolledBack = statuses.filter((s) => s.status === 'rolled_back');
+
+    // Show applied migrations
+    if (applied.length > 0) {
+      console.log(`✅ Applied (${applied.length}):`);
+      for (const status of applied) {
+        const date = status.appliedAt ? new Date(status.appliedAt).toLocaleString() : '';
+        console.log(`   ${status.version} - ${status.name} (${date})`);
+      }
+      console.log();
+    }
+
+    // Show pending migrations
+    if (pending.length > 0) {
+      console.log(`⏳ Pending (${pending.length}):`);
+      for (const status of pending) {
+        console.log(`   ${status.version} - ${status.name}`);
+      }
+      console.log();
+    }
+
+    // Show rolled back migrations
+    if (rolledBack.length > 0) {
+      console.log(`⬅️  Rolled Back (${rolledBack.length}):`);
+      for (const status of rolledBack) {
+        console.log(`   ${status.version} - ${status.name}`);
+      }
+      console.log();
+    }
+
+    // Show failed migrations
+    if (failed.length > 0) {
+      console.log(`❌ Failed (${failed.length}):`);
+      for (const status of failed) {
+        console.log(`   ${status.version} - ${status.name}`);
+        if (status.error) {
+          console.log(`      Error: ${status.error}`);
+        }
+      }
+      console.log();
+    }
+
+    // Summary
+    console.log(`Total: ${statuses.length} migration(s)\n`);
+  } catch (error: any) {
+    console.error(`\n❌ Failed to get status: ${error.message}\n`);
+    process.exit(1);
+  }
+}

package/src/commands/up.ts

@@ -0,0 +1,39 @@
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+import { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
+import { MigrationRunner } from '../core/runner';
+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,
+    },
+  });
+
+  const runner = new MigrationRunner(client, config);
+
+  try {
+    const executed = await runner.up(limit);
+
+    if (executed.length > 0) {
+      console.log(`\n🎉 Successfully applied ${executed.length} migration(s)`);
+
+      const currentVersion = await runner.getCurrentVersion();
+      console.log(`📌 Current version: ${currentVersion}\n`);
+    }
+  } catch (error: any) {
+    console.error(`\n❌ Migration failed: ${error.message}\n`);
+    process.exit(1);
+  }
+}

package/src/core/config.ts

@@ -0,0 +1,140 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { MigrationConfig } from '../types';
+
+/**
+ * Load migration configuration
+ */
+export class ConfigLoader {
+  private configPath: string;
+
+  constructor(configPath?: string) {
+    this.configPath = configPath || this.findConfigFile() || 'dynatable.config.js';
+  }
+
+  /**
+   * Find config file in current directory or parent directories
+   */
+  private findConfigFile(): string | null {
+    const configFileNames = [
+      'dynatable.config.js',
+      'dynatable.config.json',
+      '.dynatablerc.js',
+      '.dynatablerc.json',
+    ];
+
+    let currentDir = process.cwd();
+    const root = path.parse(currentDir).root;
+
+    while (currentDir !== root) {
+      for (const fileName of configFileNames) {
+        const filePath = path.join(currentDir, fileName);
+        if (fs.existsSync(filePath)) {
+          return filePath;
+        }
+      }
+
+      currentDir = path.dirname(currentDir);
+    }
+
+    return null;
+  }
+
+  /**
+   * Load configuration from file
+   */
+  async load(): Promise<MigrationConfig> {
+    if (!fs.existsSync(this.configPath)) {
+      throw new Error(
+        `Configuration file not found: ${this.configPath}\n\nPlease create a dynatable.config.js file in your project root.`
+      );
+    }
+
+    try {
+      let config: MigrationConfig;
+
+      if (this.configPath.endsWith('.json')) {
+        const content = fs.readFileSync(this.configPath, 'utf-8');
+        config = JSON.parse(content);
+      } else {
+        // JavaScript config file
+        const module = await import(this.configPath);
+        config = module.default || module;
+      }
+
+      return this.validateAndNormalizeConfig(config);
+    } catch (error: any) {
+      throw new Error(`Failed to load configuration: ${error.message}`);
+    }
+  }
+
+  /**
+   * Validate and normalize configuration
+   */
+  private validateAndNormalizeConfig(config: Partial<MigrationConfig>): MigrationConfig {
+    if (!config.tableName) {
+      throw new Error("Configuration error: 'tableName' is required");
+    }
+
+    if (!config.client?.region) {
+      throw new Error("Configuration error: 'client.region' is required");
+    }
+
+    return {
+      tableName: config.tableName,
+      client: {
+        region: config.client.region,
+        endpoint: config.client.endpoint,
+        credentials: config.client.credentials,
+      },
+      migrationsDir: config.migrationsDir || './migrations',
+      trackingPrefix: config.trackingPrefix || '_SCHEMA#VERSION',
+      gsi1Name: config.gsi1Name || 'GSI1',
+    };
+  }
+
+  /**
+   * Create default config file
+   */
+  static createDefaultConfig(targetPath: string): void {
+    const defaultConfig = `module.exports = {
+  // DynamoDB table name
+  tableName: "MyTable",
+
+  // DynamoDB client configuration
+  client: {
+    region: "us-east-1",
+
+    // Optional: For local DynamoDB
+    endpoint: "http://localhost:8000",
+
+    // Optional: Credentials (use AWS_PROFILE or IAM role in production)
+    credentials: {
+      accessKeyId: "local",
+      secretAccessKey: "local",
+    },
+  },
+
+  // Optional: Migrations directory (default: ./migrations)
+  migrationsDir: "./migrations",
+
+  // Optional: Tracking prefix in single table (default: _SCHEMA#VERSION)
+  trackingPrefix: "_SCHEMA#VERSION",
+
+  // Optional: GSI name for tracking (default: GSI1)
+  gsi1Name: "GSI1",
+};
+`;
+
+    fs.writeFileSync(targetPath, defaultConfig, 'utf-8');
+    console.log(`✅ Created config file: ${targetPath}`);
+  }
+}
+
+/**
+ * Get config from environment or file
+ */
+export async function loadConfig(configPath?: string): Promise<MigrationConfig> {
+  const loader = new ConfigLoader(configPath);
+  return loader.load();
+}