...

Author: igalklebanov

src/migration/migrator.ts

@@ -189,10 +189,35 @@ export class Migrator {
    *
    * await migrator.migrateTo(NO_MIGRATIONS)
    * ```
+   *
+   * By default, this method migrates up or down depending on which side of the
+   * current migration state the target migration is on. Pass
+   * {@link MigrateToOptions.direction} to enforce a direction — if reaching the
+   * target would require migrating the other way, nothing is executed and
+   * {@link MigrationResultSet.error} holds an error:
+   *
+   * ```ts
+   * import { promises as fs } from 'node:fs'
+   * import path from 'node:path'
+   * import { FileMigrationProvider, Migrator } from 'kysely/migration'
+   *
+   * const migrator = new Migrator({
+   *   db,
+   *   provider: new FileMigrationProvider({
+   *     fs,
+   *     // Path to the folder that contains all your migrations.
+   *     migrationFolder: 'some/path/to/migrations',
+   *     path,
+   *   })
+   * })
+   *
+   * // Errors if `some_migration` is already executed.
+   * await migrator.migrateTo('some_migration', { direction: 'Up' })
+   * ```
    */
   async migrateTo(
     targetMigrationName: string | NoMigrations,
-    options?: MigrateOptions,
+    options?: MigrateToOptions,
   ): Promise<MigrationResultSet> {
     return this.#migrate(
       ({
@@ -204,6 +229,10 @@ export class Migrator {
           isObject(targetMigrationName) &&
           targetMigrationName.__noMigrations__ === true
         ) {
+          if (options?.direction === 'Up') {
+            throw new Error(`can't migrate up to NO_MIGRATIONS`)
+          }
+
           return { direction: 'Down', step: Infinity }
         }
 
@@ -222,13 +251,25 @@ export class Migrator {
         )
 
         if (executedIndex !== -1) {
+          if (options?.direction === 'Up') {
+            throw new Error(
+              `migration "${targetMigrationName}" is already executed; can't migrate up to it`,
+            )
+          }
+
           return {
             direction: 'Down',
             step: executedMigrations.length - executedIndex - 1,
           }
         }
 
         if (pendingIndex !== -1) {
+          if (options?.direction === 'Down') {
+            throw new Error(
+              `migration "${targetMigrationName}" isn't executed; can't migrate down to it`,
+            )
+          }
+
           return { direction: 'Up', step: pendingIndex + 1 }
         }
 
@@ -933,6 +974,22 @@ export interface MigrateOptions {
 
 export type MigratorTransactionMode = 'per-run' | 'per-migration' | 'none'
 
+export interface MigrateToOptions extends MigrateOptions {
+  /**
+   * Enforces a migration direction.
+   *
+   * When provided and reaching the target migration would require migrating
+   * the other way, nothing is executed and {@link MigrationResultSet.error}
+   * holds an error. For example, `direction: 'Up'` errors when the target
+   * migration is already executed.
+   *
+   * By default, {@link Migrator.migrateTo | migrateTo} migrates up or down
+   * depending on which side of the current migration state the target
+   * migration is on.
+   */
+  readonly direction?: MigrationDirection
+}
+
 export interface MigratorProps extends MigrateOptions {
   readonly db: Kysely<any>
   readonly provider: MigrationProvider
@@ -1043,7 +1100,7 @@ export interface MigrationResultSet {
   readonly results?: MigrationResult[]
 }
 
-type MigrationDirection = 'Up' | 'Down'
+export type MigrationDirection = 'Up' | 'Down'
 
 export interface MigrationResult {
   readonly migrationName: string

test/node/src/migration.test.ts

@@ -488,6 +488,123 @@ for (const dialect of DIALECTS) {
         expect(executedDownMethods2).to.eql(['migration4', 'migration3'])
       })
 
+      it('should migrate up to a specific migration with direction enforced', async () => {
+        const { migrator, executedUpMethods } = createMigrations([
+          'migration1',
+          'migration2',
+          'migration3',
+        ])
+
+        const { results } = await migrator.migrateTo('migration2', {
+          direction: 'Up',
+        })
+
+        expect(results).to.eql([
+          { migrationName: 'migration1', direction: 'Up', status: 'Success' },
+          { migrationName: 'migration2', direction: 'Up', status: 'Success' },
+        ])
+
+        expect(executedUpMethods).to.eql(['migration1', 'migration2'])
+      })
+
+      it('should return an error when migrating up to an already executed migration', async () => {
+        const { migrator, executedUpMethods, executedDownMethods } =
+          createMigrations(['migration1', 'migration2', 'migration3'])
+
+        await migrator.migrateToLatest()
+
+        const { error } = await migrator.migrateTo('migration2', {
+          direction: 'Up',
+        })
+
+        expect(error).to.be.an.instanceOf(Error)
+        expect(getMessage(error)).to.eql(
+          `migration "migration2" is already executed; can't migrate up to it`,
+        )
+
+        expect(executedUpMethods).to.eql([
+          'migration1',
+          'migration2',
+          'migration3',
+        ])
+        expect(executedDownMethods).to.eql([])
+      })
+
+      it('should migrate down to a specific migration with direction enforced', async () => {
+        const { migrator, executedDownMethods } = createMigrations([
+          'migration1',
+          'migration2',
+          'migration3',
+        ])
+
+        await migrator.migrateToLatest()
+
+        const { results } = await migrator.migrateTo('migration1', {
+          direction: 'Down',
+        })
+
+        expect(results).to.eql([
+          { migrationName: 'migration3', direction: 'Down', status: 'Success' },
+          { migrationName: 'migration2', direction: 'Down', status: 'Success' },
+        ])
+
+        expect(executedDownMethods).to.eql(['migration3', 'migration2'])
+      })
+
+      it('should return an error when migrating down to a pending migration', async () => {
+        const { migrator, executedUpMethods, executedDownMethods } =
+          createMigrations(['migration1', 'migration2', 'migration3'])
+
+        const { error } = await migrator.migrateTo('migration2', {
+          direction: 'Down',
+        })
+
+        expect(error).to.be.an.instanceOf(Error)
+        expect(getMessage(error)).to.eql(
+          `migration "migration2" isn't executed; can't migrate down to it`,
+        )
+
+        expect(executedUpMethods).to.eql([])
+        expect(executedDownMethods).to.eql([])
+      })
+
+      it('should migrate all the way down with direction enforced', async () => {
+        const { migrator, executedDownMethods } = createMigrations([
+          'migration1',
+          'migration2',
+        ])
+
+        await migrator.migrateToLatest()
+
+        const { results } = await migrator.migrateTo(NO_MIGRATIONS, {
+          direction: 'Down',
+        })
+
+        expect(results).to.eql([
+          { migrationName: 'migration2', direction: 'Down', status: 'Success' },
+          { migrationName: 'migration1', direction: 'Down', status: 'Success' },
+        ])
+
+        expect(executedDownMethods).to.eql(['migration2', 'migration1'])
+      })
+
+      it('should return an error when migrating up to NO_MIGRATIONS', async () => {
+        const { migrator, executedUpMethods, executedDownMethods } =
+          createMigrations(['migration1', 'migration2'])
+
+        await migrator.migrateToLatest()
+
+        const { error } = await migrator.migrateTo(NO_MIGRATIONS, {
+          direction: 'Up',
+        })
+
+        expect(error).to.be.an.instanceOf(Error)
+        expect(getMessage(error)).to.eql(`can't migrate up to NO_MIGRATIONS`)
+
+        expect(executedUpMethods).to.eql(['migration1', 'migration2'])
+        expect(executedDownMethods).to.eql([])
+      })
+
       describe('with allowUnorderedMigrations enabled', () => {
         it('should migrate up to a specific migration', async () => {
           const { migrator: migrator1, executedUpMethods: executedUpMethods1 } =