@ftschopp/dynatable-migrations 1.2.6 → 1.3.0

package/src/core/config.ts

@@ -1,140 +0,0 @@
-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();
-}

package/src/core/errors.ts

@@ -1,55 +0,0 @@
-/**
- * Thrown by `markAsApplied` when the version already has a tracking record
- * in a non-applied state (e.g. `failed`, `rolled_back`) and therefore
- * cannot be silently treated as an idempotent re-apply. Surfaces the
- * existing state so the caller can decide whether to retry, recover, or
- * roll back.
- */
-export class MigrationAlreadyAppliedError extends Error {
-  public readonly version: string;
-  public readonly currentStatus: string | undefined;
-
-  constructor(version: string, currentStatus: string | undefined) {
-    super(
-      `Migration "${version}" already has a tracking record in state ` +
-        `"${currentStatus ?? 'unknown'}" — cannot mark as applied. ` +
-        `If you want to re-apply this version, roll it back first ` +
-        `(or recover the failed run) and try again.`
-    );
-    this.name = 'MigrationAlreadyAppliedError';
-    this.version = version;
-    this.currentStatus = currentStatus;
-    if (typeof (Error as unknown as { captureStackTrace?: unknown }).captureStackTrace === 'function') {
-      (
-        Error as unknown as { captureStackTrace: (target: object, ctor: unknown) => void }
-      ).captureStackTrace(this, MigrationAlreadyAppliedError);
-    }
-  }
-}
-
-/**
- * Thrown when a tracker write is cancelled because the migration lock was
- * taken by another process between `acquireLock()` and the write itself
- * (e.g. the original lock TTL expired and a second worker took over).
- *
- * The transaction was rolled back atomically — no partial state was
- * written. The safe action is to stop the current `up()` / `down()` run.
- */
-export class MigrationLockLostError extends Error {
-  public readonly version: string;
-
-  constructor(version: string) {
-    super(
-      `Migration lock was lost during markAsApplied("${version}"). ` +
-        `Another worker may have taken over. The transaction was rolled ` +
-        `back atomically; no partial state was written.`
-    );
-    this.name = 'MigrationLockLostError';
-    this.version = version;
-    if (typeof (Error as unknown as { captureStackTrace?: unknown }).captureStackTrace === 'function') {
-      (
-        Error as unknown as { captureStackTrace: (target: object, ctor: unknown) => void }
-      ).captureStackTrace(this, MigrationLockLostError);
-    }
-  }
-}

package/src/core/loader.ts

@@ -1,256 +0,0 @@
-import * as fs from 'fs';
-import * as path from 'path';
-import * as crypto from 'crypto';
-import { Migration, MigrationFile } from '../types';
-import { compareSemver } from './semver';
-
-/**
- * Load all migration files from directory
- */
-export class MigrationLoader {
-  private migrationsDir: string;
-
-  constructor(migrationsDir: string) {
-    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
-   */
-  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 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> {
-    // 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);
-      } 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;
-
-    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);
-
-    // Calculate checksum
-    const checksum = this.calculateChecksum(absolutePath);
-
-    return {
-      version,
-      name,
-      filePath,
-      migration,
-      checksum,
-    };
-  }
-
-  /**
-   * 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) {
-      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}`);
-    }
-  }
-
-  /**
-   * 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';
-  }
-
-}

package/src/core/lock-heartbeat.test.ts

@@ -1,78 +0,0 @@
-import { startLockHeartbeat } from './lock-heartbeat';
-import type { MigrationTracker } from '../types';
-
-beforeEach(() => {
-  jest.useFakeTimers();
-});
-
-afterEach(() => {
-  jest.useRealTimers();
-});
-
-function makeTracker(refresh: jest.Mock): MigrationTracker {
-  // Only the methods the heartbeat actually touches need to be present.
-  return {
-    refreshLock: refresh,
-  } as unknown as MigrationTracker;
-}
-
-describe('startLockHeartbeat', () => {
-  test('calls refreshLock every ~ttl/3 seconds', () => {
-    const refresh = jest.fn().mockResolvedValue(undefined);
-    const tracker = makeTracker(refresh);
-    const stop = startLockHeartbeat(tracker, 30); // every 10s
-
-    jest.advanceTimersByTime(10_000);
-    expect(refresh).toHaveBeenCalledTimes(1);
-
-    jest.advanceTimersByTime(10_000);
-    expect(refresh).toHaveBeenCalledTimes(2);
-
-    stop();
-  });
-
-  test('stop() clears the interval and prevents further refreshes', () => {
-    const refresh = jest.fn().mockResolvedValue(undefined);
-    const tracker = makeTracker(refresh);
-    const stop = startLockHeartbeat(tracker, 30);
-
-    jest.advanceTimersByTime(10_000);
-    stop();
-    jest.advanceTimersByTime(60_000);
-
-    expect(refresh).toHaveBeenCalledTimes(1);
-  });
-
-  test('clamps the interval to a 1s minimum even with absurdly small TTLs', () => {
-    const refresh = jest.fn().mockResolvedValue(undefined);
-    const tracker = makeTracker(refresh);
-    const stop = startLockHeartbeat(tracker, 0.5); // would compute < 1s
-
-    jest.advanceTimersByTime(999);
-    expect(refresh).toHaveBeenCalledTimes(0);
-    jest.advanceTimersByTime(1);
-    expect(refresh).toHaveBeenCalledTimes(1);
-
-    stop();
-  });
-
-  test('swallows refresh errors so transient failures do not crash the runner', async () => {
-    const warn = jest.spyOn(console, 'warn').mockImplementation(() => {});
-    const refresh = jest
-      .fn()
-      .mockRejectedValueOnce(Object.assign(new Error('boom'), { name: 'NetworkError' }));
-    const tracker = makeTracker(refresh);
-    const stop = startLockHeartbeat(tracker, 30);
-
-    jest.advanceTimersByTime(10_000);
-    // Let the rejected promise settle
-    await Promise.resolve();
-    await Promise.resolve();
-
-    expect(refresh).toHaveBeenCalledTimes(1);
-    expect(warn).toHaveBeenCalled();
-
-    stop();
-    warn.mockRestore();
-  });
-});

package/src/core/lock-heartbeat.ts

@@ -1,48 +0,0 @@
-import type { MigrationTracker } from '../types';
-
-/**
- * Periodically refreshes the migration lock so that migrations longer than
- * the lock TTL don't have their lock taken by another worker.
- *
- * Returns a stop function. Call it from the same `finally` that releases
- * the lock to make sure the interval doesn't leak.
- *
- * The heartbeat fires every `ttlSeconds / 3` seconds. Errors from the
- * underlying refresh are logged and swallowed: if the lock is genuinely
- * lost, the next tracker mutation will fail its ConditionCheck and the
- * runner will surface a clear `TransactionCanceledException` to the user.
- */
-export function startLockHeartbeat(
-  tracker: MigrationTracker,
-  ttlSeconds: number
-): () => void {
-  // Fire well before expiry so a single missed beat doesn't drop the lock.
-  const intervalMs = Math.max(1_000, Math.floor((ttlSeconds * 1000) / 3));
-  let active = true;
-
-  const handle = setInterval(() => {
-    if (!active) return;
-    void tracker.refreshLock().catch((err: unknown) => {
-      const name = (err as { name?: string } | null)?.name;
-      const message = (err as { message?: string } | null)?.message ?? String(err);
-      if (name === 'ConditionalCheckFailedException') {
-        console.warn(
-          '⚠️  Migration lock was taken by another process. ' +
-            'Subsequent tracker writes will fail.'
-        );
-      } else {
-        console.warn(`⚠️  Failed to refresh migration lock: ${message}`);
-      }
-    });
-  }, intervalMs);
-
-  // Don't keep the Node event loop alive just for the heartbeat.
-  if (typeof handle.unref === 'function') {
-    handle.unref();
-  }
-
-  return () => {
-    active = false;
-    clearInterval(handle);
-  };
-}

package/src/core/runner.test.ts

@@ -1,51 +0,0 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
-import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
-import { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
-import { MigrationRunner } from './runner';
-import type { MigrationConfig } from '../types';
-
-const baseConfig: MigrationConfig = {
-  tableName: 'TestTable',
-  client: { region: 'us-east-1' },
-};
-
-function makeRunner() {
-  const client = DynamoDBDocumentClient.from(new DynamoDBClient({ region: 'us-east-1' }));
-  return new MigrationRunner(client, baseConfig);
-}
-
-describe('MigrationRunner.up - input validation', () => {
-  test('throws when limit is 0', async () => {
-    await expect(makeRunner().up({ limit: 0 })).rejects.toThrow(/positive integer/);
-  });
-
-  test('throws when limit is negative', async () => {
-    await expect(makeRunner().up({ limit: -3 })).rejects.toThrow(/positive integer/);
-  });
-
-  test('throws when limit is NaN', async () => {
-    await expect(makeRunner().up({ limit: NaN })).rejects.toThrow(/positive integer/);
-  });
-
-  test('throws when limit is a non-integer (1.5)', async () => {
-    await expect(makeRunner().up({ limit: 1.5 })).rejects.toThrow(/positive integer/);
-  });
-});
-
-describe('MigrationRunner.down - input validation', () => {
-  test('throws when steps is 0', async () => {
-    await expect(makeRunner().down(0)).rejects.toThrow(/positive integer/);
-  });
-
-  test('throws when steps is negative', async () => {
-    await expect(makeRunner().down(-5)).rejects.toThrow(/positive integer/);
-  });
-
-  test('throws when steps is NaN', async () => {
-    await expect(makeRunner().down(Number.NaN)).rejects.toThrow(/positive integer/);
-  });
-
-  test('throws when steps is a non-integer', async () => {
-    await expect(makeRunner().down(2.5)).rejects.toThrow(/positive integer/);
-  });
-});