@ftschopp/dynatable-migrations 1.2.6 → 1.3.1

package/src/core/runner.ts

@@ -1,315 +0,0 @@
-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';
-import { compareSemver } from './semver';
-import { startLockHeartbeat } from './lock-heartbeat';
-
-export interface RunOptions {
-  limit?: number;
-  dryRun?: boolean;
-}
-
-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(options: RunOptions = {}): Promise<MigrationFile[]> {
-    const { limit, dryRun = false } = options;
-
-    if (limit !== undefined && (!Number.isInteger(limit) || limit <= 0)) {
-      throw new Error(
-        `runner.up({ limit }) requires a positive integer (got ${JSON.stringify(limit)}).`
-      );
-    }
-
-    await this.initialize();
-
-    // Acquire lock unless dry run
-    let stopHeartbeat: (() => void) | undefined;
-    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.'
-        );
-      }
-      stopHeartbeat = startLockHeartbeat(this.tracker, this.tracker.lockTtlSeconds);
-    }
-
-    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}`
-          );
-        }
-      }
-
-      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 [];
-      }
-
-      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;
-      }
-
-      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,
-            undefined,
-            migrationFile.checksum
-          );
-
-          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;
-    } finally {
-      // Always stop the heartbeat and release the lock — in that order, so
-      // we don't refresh a lock we're about to delete.
-      if (stopHeartbeat) stopHeartbeat();
-      if (!dryRun) {
-        await this.tracker.releaseLock();
-      }
-    }
-  }
-
-  /**
-   * Rollback last migration
-   */
-  async down(steps: number = 1, dryRun: boolean = false): Promise<MigrationFile[]> {
-    if (!Number.isInteger(steps) || steps <= 0) {
-      throw new Error(
-        `runner.down(steps) requires a positive integer (got ${JSON.stringify(steps)}).`
-      );
-    }
-
-    await this.initialize();
-
-    // Acquire lock unless dry run
-    let stopHeartbeat: (() => void) | undefined;
-    if (!dryRun) {
-      const lockAcquired = await this.tracker.acquireLock();
-      if (!lockAcquired) {
-        throw new Error('Could not acquire migration lock. Another migration may be in progress.');
-      }
-      stopHeartbeat = startLockHeartbeat(this.tracker, this.tracker.lockTtlSeconds);
-    }
-
-    try {
-      const appliedMigrations = await this.tracker.getAppliedMigrations();
-      const applied = appliedMigrations
-        .filter((m) => m.status === 'applied')
-        .sort((a, b) => compareSemver(b.version, a.version))
-        .slice(0, steps);
-
-      if (applied.length === 0) {
-        console.log('✅ No migrations to rollback');
-        return [];
-      }
-
-      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(`\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;
-    } finally {
-      if (stopHeartbeat) stopHeartbeat();
-      if (!dryRun) {
-        await this.tracker.releaseLock();
-      }
-    }
-  }
-
-  /**
-   * 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 {
-    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/semver.test.ts

@@ -1,33 +0,0 @@
-import { compareSemver } from './semver';
-
-describe('compareSemver', () => {
-  test('returns -1 when a < b across the minor digit boundary (the original bug)', () => {
-    expect(compareSemver('0.9.0', '0.10.0')).toBe(-1);
-  });
-
-  test('returns 1 when a > b across the minor digit boundary', () => {
-    expect(compareSemver('0.10.0', '0.9.0')).toBe(1);
-  });
-
-  test('returns -1 when a < b across the patch digit boundary', () => {
-    expect(compareSemver('0.1.0', '0.1.10')).toBe(-1);
-  });
-
-  test('handles major beats minor', () => {
-    expect(compareSemver('1.0.0', '0.99.99')).toBe(1);
-  });
-
-  test('returns 0 for equal versions', () => {
-    expect(compareSemver('1.2.3', '1.2.3')).toBe(0);
-  });
-
-  test('sorts a list of versions ascending in the correct order', () => {
-    const sorted = ['0.10.0', '1.0.0', '0.1.0', '0.9.0'].sort(compareSemver);
-    expect(sorted).toEqual(['0.1.0', '0.9.0', '0.10.0', '1.0.0']);
-  });
-
-  test('sorts a list of versions descending when the comparator is inverted', () => {
-    const sorted = ['0.10.0', '1.0.0', '0.1.0', '0.9.0'].sort((a, b) => compareSemver(b, a));
-    expect(sorted).toEqual(['1.0.0', '0.10.0', '0.9.0', '0.1.0']);
-  });
-});

package/src/core/semver.ts

@@ -1,26 +0,0 @@
-/**
- * Compare two semver versions of the form `MAJOR.MINOR.PATCH`.
- *
- * Returns:
- *   -1 if `a < b`
- *    0 if `a === b`
- *    1 if `a > b`
- *
- * Designed for migration filenames (`0.1.0_name.ts`) which the loader
- * already validates as strict three-segment semver — prerelease and build
- * metadata are not handled.
- */
-export function 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/tracker.test.ts

@@ -1,281 +0,0 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
-import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
-import {
-  DynamoDBDocumentClient,
-  GetCommand,
-  PutCommand,
-  UpdateCommand,
-  TransactWriteCommand,
-} from '@aws-sdk/lib-dynamodb';
-import { mockClient } from 'aws-sdk-client-mock';
-import { DynamoDBMigrationTracker, DEFAULT_LOCK_TTL_SECONDS } from './tracker';
-import type { MigrationConfig } from '../types';
-
-const ddbMock = mockClient(DynamoDBDocumentClient);
-
-const baseConfig: MigrationConfig = {
-  tableName: 'TestTable',
-  client: { region: 'us-east-1' },
-};
-
-function makeTracker(config: Partial<MigrationConfig> = {}) {
-  const client = DynamoDBDocumentClient.from(new DynamoDBClient({ region: 'us-east-1' }));
-  return new DynamoDBMigrationTracker(client, { ...baseConfig, ...config });
-}
-
-beforeEach(() => {
-  ddbMock.reset();
-});
-
-describe('DynamoDBMigrationTracker - lock TTL', () => {
-  test('uses the default 5-minute TTL when none is configured', () => {
-    const tracker = makeTracker();
-    expect(tracker.lockTtlSeconds).toBe(DEFAULT_LOCK_TTL_SECONDS);
-  });
-
-  test('honors a custom lockTtlSeconds from config', () => {
-    const tracker = makeTracker({ lockTtlSeconds: 30 });
-    expect(tracker.lockTtlSeconds).toBe(30);
-  });
-});
-
-describe('DynamoDBMigrationTracker - acquireLock', () => {
-  test('uses <= for the expiry boundary so simultaneous-ms expiries are takeable', async () => {
-    ddbMock.on(PutCommand).resolves({});
-    const tracker = makeTracker();
-
-    await tracker.acquireLock();
-
-    const calls = ddbMock.commandCalls(PutCommand);
-    expect(calls).toHaveLength(1);
-    const expr = (calls[0]!.args[0].input as any).ConditionExpression as string;
-    expect(expr).toContain('expiresAt <= :now');
-  });
-
-  test('returns false when the lock row exists and has not expired', async () => {
-    const err = Object.assign(new Error('cond failed'), {
-      name: 'ConditionalCheckFailedException',
-    });
-    ddbMock.on(PutCommand).rejects(err);
-    const tracker = makeTracker();
-
-    await expect(tracker.acquireLock()).resolves.toBe(false);
-  });
-});
-
-describe('DynamoDBMigrationTracker - refreshLock', () => {
-  test('extends the lock with a ConditionExpression on the current lockId', async () => {
-    ddbMock.on(PutCommand).resolves({});
-    ddbMock.on(UpdateCommand).resolves({});
-
-    const tracker = makeTracker({ lockTtlSeconds: 60 });
-    await tracker.acquireLock();
-    await tracker.refreshLock();
-
-    const updates = ddbMock.commandCalls(UpdateCommand);
-    expect(updates).toHaveLength(1);
-    const input = updates[0]!.args[0].input as any;
-    expect(input.ConditionExpression).toBe('lockId = :lockId');
-    expect(typeof input.ExpressionAttributeValues[':lockId']).toBe('string');
-    expect(typeof input.ExpressionAttributeValues[':exp']).toBe('number');
-  });
-
-  test('throws when the lockId no longer matches (lost race)', async () => {
-    ddbMock.on(PutCommand).resolves({});
-    const err = Object.assign(new Error('cond failed'), {
-      name: 'ConditionalCheckFailedException',
-    });
-    ddbMock.on(UpdateCommand).rejects(err);
-
-    const tracker = makeTracker();
-    await tracker.acquireLock();
-
-    await expect(tracker.refreshLock()).rejects.toMatchObject({
-      name: 'ConditionalCheckFailedException',
-    });
-  });
-
-  test('is a silent no-op when no lock has been acquired yet', async () => {
-    const tracker = makeTracker();
-    await expect(tracker.refreshLock()).resolves.toBeUndefined();
-    expect(ddbMock.commandCalls(UpdateCommand)).toHaveLength(0);
-  });
-});
-
-describe('DynamoDBMigrationTracker - tracker writes are gated by lock ownership', () => {
-  test('markAsApplied (new record path) emits a ConditionCheck on the lock row', async () => {
-    ddbMock.on(PutCommand).resolves({}); // acquireLock
-    ddbMock.on(TransactWriteCommand).resolves({});
-    // getMigration returns no existing record → take the Put branch
-    ddbMock.on(GetCommand).resolves({ Item: undefined });
-
-    const tracker = makeTracker();
-    await tracker.acquireLock();
-    await tracker.markAsApplied('0.1.0', 'init');
-
-    const tx = ddbMock.commandCalls(TransactWriteCommand);
-    expect(tx).toHaveLength(1);
-    const items = (tx[0]!.args[0].input as any).TransactItems as any[];
-    // First item should be the lock-row ConditionCheck
-    expect(items[0].ConditionCheck).toBeDefined();
-    expect(items[0].ConditionCheck.ConditionExpression).toBe('lockId = :lockId');
-    expect(items[0].ConditionCheck.Key).toEqual({
-      PK: '_SCHEMA#VERSION#LOCK',
-      SK: '_SCHEMA#VERSION#LOCK',
-    });
-  });
-
-  test('markAsApplied throws when no lock has been acquired', async () => {
-    const tracker = makeTracker();
-    await expect(tracker.markAsApplied('0.1.0', 'init')).rejects.toThrow(
-      /Tracker has no active lock/i
-    );
-  });
-
-  test('markAsApplied (new record path) uses attribute_not_exists(SK), not (PK)', async () => {
-    ddbMock.on(PutCommand).resolves({});
-    ddbMock.on(TransactWriteCommand).resolves({});
-    ddbMock.on(GetCommand).resolves({ Item: undefined });
-
-    const tracker = makeTracker();
-    await tracker.acquireLock();
-    await tracker.markAsApplied('0.1.0', 'init');
-
-    const tx = ddbMock.commandCalls(TransactWriteCommand);
-    const items = (tx[0]!.args[0].input as any).TransactItems as any[];
-    // The Put is the second item (index 1) after the ConditionCheck
-    const put = items.find((i) => i.Put);
-    expect(put.Put.ConditionExpression).toBe('attribute_not_exists(SK)');
-  });
-});
-
-describe('DynamoDBMigrationTracker - markAsApplied idempotency (#10)', () => {
-  function cancelledTransactError(reasons: Array<{ Code?: string }>) {
-    return Object.assign(new Error('Transaction cancelled'), {
-      name: 'TransactionCanceledException',
-      CancellationReasons: reasons,
-    });
-  }
-
-  test('returns silently when the cancellation is because the row is already in status=applied', async () => {
-    ddbMock.on(PutCommand).resolves({}); // acquireLock
-    // First getMigration → no record (so we take the Put branch)
-    // Second getMigration (after cancellation) → already applied
-    ddbMock
-      .on(GetCommand)
-      .resolvesOnce({ Item: undefined })
-      .resolvesOnce({
-        Item: {
-          PK: '_SCHEMA#VERSION',
-          SK: '0.1.0',
-          version: '0.1.0',
-          status: 'applied',
-          name: 'init',
-        },
-      });
-
-    // Migration row condition fails (reasons[1]); lock check passed (reasons[0] = None)
-    ddbMock.on(TransactWriteCommand).rejects(
-      cancelledTransactError([{ Code: 'None' }, { Code: 'ConditionalCheckFailed' }])
-    );
-
-    const tracker = makeTracker();
-    await tracker.acquireLock();
-
-    await expect(tracker.markAsApplied('0.1.0', 'init')).resolves.toBeUndefined();
-  });
-
-  test('throws MigrationAlreadyAppliedError when the row exists in a non-applied state', async () => {
-    ddbMock.on(PutCommand).resolves({});
-    ddbMock
-      .on(GetCommand)
-      .resolvesOnce({ Item: undefined })
-      .resolvesOnce({
-        Item: {
-          PK: '_SCHEMA#VERSION',
-          SK: '0.1.0',
-          version: '0.1.0',
-          status: 'failed',
-          name: 'init',
-        },
-      });
-
-    ddbMock.on(TransactWriteCommand).rejects(
-      cancelledTransactError([{ Code: 'None' }, { Code: 'ConditionalCheckFailed' }])
-    );
-
-    const tracker = makeTracker();
-    await tracker.acquireLock();
-
-    await expect(tracker.markAsApplied('0.1.0', 'init')).rejects.toMatchObject({
-      name: 'MigrationAlreadyAppliedError',
-      version: '0.1.0',
-      currentStatus: 'failed',
-    });
-  });
-
-  test('throws MigrationLockLostError when the lock-row ConditionCheck is what failed', async () => {
-    ddbMock.on(PutCommand).resolves({});
-    ddbMock.on(GetCommand).resolves({ Item: undefined });
-
-    ddbMock.on(TransactWriteCommand).rejects(
-      cancelledTransactError([{ Code: 'ConditionalCheckFailed' }, { Code: 'None' }])
-    );
-
-    const tracker = makeTracker();
-    await tracker.acquireLock();
-
-    await expect(tracker.markAsApplied('0.1.0', 'init')).rejects.toMatchObject({
-      name: 'MigrationLockLostError',
-      version: '0.1.0',
-    });
-  });
-
-  test('re-throws unexpected errors unchanged', async () => {
-    ddbMock.on(PutCommand).resolves({});
-    ddbMock.on(GetCommand).resolves({ Item: undefined });
-
-    const boom = Object.assign(new Error('upstream blew up'), { name: 'InternalServerError' });
-    ddbMock.on(TransactWriteCommand).rejects(boom);
-
-    const tracker = makeTracker();
-    await tracker.acquireLock();
-
-    await expect(tracker.markAsApplied('0.1.0', 'init')).rejects.toBe(boom);
-  });
-
-  test('idempotent path also covers the Update branch (existing record was rolled_back, applied by a racing worker)', async () => {
-    ddbMock.on(PutCommand).resolves({});
-    // First getMigration → existing rolled_back record (so we take the Update branch)
-    // Second getMigration (after cancellation) → already applied (race)
-    ddbMock
-      .on(GetCommand)
-      .resolvesOnce({
-        Item: {
-          PK: '_SCHEMA#VERSION',
-          SK: '0.1.0',
-          version: '0.1.0',
-          status: 'rolled_back',
-          name: 'init',
-        },
-      })
-      .resolvesOnce({
-        Item: {
-          PK: '_SCHEMA#VERSION',
-          SK: '0.1.0',
-          version: '0.1.0',
-          status: 'applied',
-          name: 'init',
-        },
-      });
-
-    ddbMock.on(TransactWriteCommand).rejects(
-      cancelledTransactError([{ Code: 'None' }, { Code: 'ConditionalCheckFailed' }])
-    );
-
-    const tracker = makeTracker();
-    await tracker.acquireLock();
-
-    await expect(tracker.markAsApplied('0.1.0', 'init')).resolves.toBeUndefined();
-  });
-});