@ftschopp/dynatable-migrations 1.2.4 → 1.2.6

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,cAAc,SAAS,CAAC;AAGxB,OAAO,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AACjE,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAGrD,OAAO,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AAGlE,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,cAAc,SAAS,CAAC;AAGxB,OAAO,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AACjE,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,4BAA4B,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAGrF,OAAO,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AAGlE,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -18,7 +18,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.initProject = exports.showStatus = exports.rollbackMigrations = exports.runMigrations = exports.createMigration = exports.generateMigrationTemplate = exports.createDynamoDBClient = exports.loadConfig = exports.ConfigLoader = exports.MigrationRunner = exports.MigrationLoader = exports.DynamoDBMigrationTracker = void 0;
+exports.initProject = exports.showStatus = exports.rollbackMigrations = exports.runMigrations = exports.createMigration = exports.generateMigrationTemplate = exports.MigrationLockLostError = exports.MigrationAlreadyAppliedError = exports.createDynamoDBClient = exports.loadConfig = exports.ConfigLoader = exports.MigrationRunner = exports.MigrationLoader = exports.DynamoDBMigrationTracker = void 0;
 // Types
 __exportStar(require("./types"), exports);
 // Core
@@ -33,6 +33,9 @@ Object.defineProperty(exports, "ConfigLoader", { enumerable: true, get: function
 Object.defineProperty(exports, "loadConfig", { enumerable: true, get: function () { return config_1.loadConfig; } });
 var client_1 = require("./core/client");
 Object.defineProperty(exports, "createDynamoDBClient", { enumerable: true, get: function () { return client_1.createDynamoDBClient; } });
+var errors_1 = require("./core/errors");
+Object.defineProperty(exports, "MigrationAlreadyAppliedError", { enumerable: true, get: function () { return errors_1.MigrationAlreadyAppliedError; } });
+Object.defineProperty(exports, "MigrationLockLostError", { enumerable: true, get: function () { return errors_1.MigrationLockLostError; } });
 // Template
 var migration_1 = require("./templates/migration");
 Object.defineProperty(exports, "generateMigrationTemplate", { enumerable: true, get: function () { return migration_1.generateMigrationTemplate; } });

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;;;;;;;;;;;;;;;AAEH,QAAQ;AACR,0CAAwB;AAExB,OAAO;AACP,0CAA0D;AAAjD,mHAAA,wBAAwB,OAAA;AACjC,wCAAgD;AAAvC,yGAAA,eAAe,OAAA;AACxB,wCAAiE;AAAxD,yGAAA,eAAe,OAAA;AACxB,wCAAyD;AAAhD,sGAAA,YAAY,OAAA;AAAE,oGAAA,UAAU,OAAA;AACjC,wCAAqD;AAA5C,8GAAA,oBAAoB,OAAA;AAE7B,WAAW;AACX,mDAAkE;AAAzD,sHAAA,yBAAyB,OAAA;AAElC,kCAAkC;AAClC,4CAAoD;AAA3C,yGAAA,eAAe,OAAA;AACxB,oCAA8C;AAArC,mGAAA,aAAa,OAAA;AACtB,wCAAqD;AAA5C,0GAAA,kBAAkB,OAAA;AAC3B,4CAA+C;AAAtC,oGAAA,UAAU,OAAA;AACnB,wCAA8C;AAArC,mGAAA,WAAW,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;;;;;;;;;;;;;;;AAEH,QAAQ;AACR,0CAAwB;AAExB,OAAO;AACP,0CAA0D;AAAjD,mHAAA,wBAAwB,OAAA;AACjC,wCAAgD;AAAvC,yGAAA,eAAe,OAAA;AACxB,wCAAiE;AAAxD,yGAAA,eAAe,OAAA;AACxB,wCAAyD;AAAhD,sGAAA,YAAY,OAAA;AAAE,oGAAA,UAAU,OAAA;AACjC,wCAAqD;AAA5C,8GAAA,oBAAoB,OAAA;AAC7B,wCAAqF;AAA5E,sHAAA,4BAA4B,OAAA;AAAE,gHAAA,sBAAsB,OAAA;AAE7D,WAAW;AACX,mDAAkE;AAAzD,sHAAA,yBAAyB,OAAA;AAElC,kCAAkC;AAClC,4CAAoD;AAA3C,yGAAA,eAAe,OAAA;AACxB,oCAA8C;AAArC,mGAAA,aAAa,OAAA;AACtB,wCAAqD;AAA5C,0GAAA,kBAAkB,OAAA;AAC3B,4CAA+C;AAAtC,oGAAA,UAAU,OAAA;AACnB,wCAA8C;AAArC,mGAAA,WAAW,OAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ftschopp/dynatable-migrations",
-  "version": "1.2.4",
+  "version": "1.2.6",
   "description": "DynamoDB migration tool for single table design with schema versioning",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/cli-utils.test.ts

@@ -0,0 +1,45 @@
+import { parsePositiveInt } from './cli-utils';
+
+describe('parsePositiveInt', () => {
+  const parser = parsePositiveInt('limit');
+
+  test('accepts positive integers', () => {
+    expect(parser('1')).toBe(1);
+    expect(parser('42')).toBe(42);
+    expect(parser('1000')).toBe(1000);
+  });
+
+  test('trims surrounding whitespace before parsing', () => {
+    expect(parser('  5  ')).toBe(5);
+  });
+
+  test('rejects 0', () => {
+    expect(() => parser('0')).toThrow(/--limit must be a positive integer/);
+  });
+
+  test('rejects negative numbers', () => {
+    expect(() => parser('-5')).toThrow(/--limit must be a positive integer/);
+  });
+
+  test('rejects non-numeric input', () => {
+    expect(() => parser('abc')).toThrow(/--limit must be a positive integer/);
+  });
+
+  test('rejects floats (1.5 would parseInt to 1, but the trailing decimals are still wrong)', () => {
+    expect(() => parser('1.5')).toThrow(/--limit must be a positive integer/);
+  });
+
+  test('rejects empty string', () => {
+    expect(() => parser('')).toThrow(/--limit must be a positive integer/);
+  });
+
+  test('rejects strings with trailing junk that parseInt would silently swallow', () => {
+    // parseInt('5abc', 10) === 5, but we should refuse it because the input
+    // is clearly not a positive integer.
+    expect(() => parser('5abc')).toThrow(/--limit must be a positive integer/);
+  });
+
+  test('error mentions the flag name passed to the factory', () => {
+    expect(() => parsePositiveInt('steps')('-1')).toThrow(/--steps/);
+  });
+});

package/src/cli-utils.ts

@@ -0,0 +1,18 @@
+import { InvalidArgumentError } from 'commander';
+
+/**
+ * Commander value parser that accepts only positive integers. Used for
+ * `--limit` and `--steps` so `0`, negative numbers, and non-numeric input
+ * fail at parse time with a clean usage error instead of silently feeding
+ * `Array.prototype.slice` and producing surprising rollbacks.
+ */
+export function parsePositiveInt(name: string): (raw: string) => number {
+  return (raw: string) => {
+    const trimmed = raw.trim();
+    const n = Number.parseInt(trimmed, 10);
+    if (!Number.isInteger(n) || n <= 0 || String(n) !== trimmed) {
+      throw new InvalidArgumentError(`--${name} must be a positive integer (got "${raw}").`);
+    }
+    return n;
+  };
+}

package/src/cli.ts

@@ -7,6 +7,7 @@ import { runMigrations } from './commands/up';
 import { rollbackMigrations } from './commands/down';
 import { showStatus } from './commands/status';
 import { initProject } from './commands/init';
+import { parsePositiveInt } from './cli-utils';
 
 // Read version from package.json
 const packageJson = require('../package.json');
@@ -62,13 +63,12 @@ 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')
+  .option('-l, --limit <number>', 'Limit number of migrations to run', parsePositiveInt('limit'))
   .option('-d, --dry-run', 'Show what would be done without making changes')
   .action(async (options) => {
     try {
       const config = await loadConfig(options.config);
-      const limit = options.limit ? parseInt(options.limit, 10) : undefined;
-      await runMigrations(config, limit, options.dryRun);
+      await runMigrations(config, options.limit, options.dryRun);
     } catch (error: any) {
       console.error(`Error: ${error.message}`);
       process.exit(1);
@@ -80,13 +80,12 @@ program
   .command('down')
   .description('Rollback migrations')
   .option('-c, --config <path>', 'Path to config file')
-  .option('-s, --steps <number>', 'Number of migrations to rollback', '1')
+  .option('-s, --steps <number>', 'Number of migrations to rollback', parsePositiveInt('steps'), 1)
   .option('-d, --dry-run', 'Show what would be done without making changes')
   .action(async (options) => {
     try {
       const config = await loadConfig(options.config);
-      const steps = parseInt(options.steps, 10);
-      await rollbackMigrations(config, steps, options.dryRun);
+      await rollbackMigrations(config, options.steps, options.dryRun);
     } catch (error: any) {
       console.error(`Error: ${error.message}`);
       process.exit(1);

package/src/core/errors.ts

@@ -0,0 +1,55 @@
+/**
+ * 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/runner.test.ts

@@ -0,0 +1,51 @@
+/* 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/);
+  });
+});

package/src/core/runner.ts

@@ -48,6 +48,12 @@ export class MigrationRunner {
   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
@@ -149,6 +155,12 @@ export class MigrationRunner {
    * 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

package/src/core/tracker.test.ts

@@ -148,3 +148,134 @@ describe('DynamoDBMigrationTracker - tracker writes are gated by lock ownership'
     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();
+  });
+});