kysely 0.14.0 → 0.15.2

package/dist/cjs/migration/{migration.d.ts → migrator.d.ts}

@@ -1,101 +1,86 @@
 import { Kysely } from '../kysely.js';
-import { DialectAdapter } from '../dialect/dialect-adapter.js';
 export declare const MIGRATION_TABLE = "kysely_migration";
 export declare const MIGRATION_LOCK_TABLE = "kysely_migration_lock";
 export declare const MIGRATION_LOCK_ID = "migration_lock";
 export declare const NO_MIGRATIONS: NoMigrations;
-export declare type MigrationsOrFolderPath = Record<string, Migration> | string;
 export interface Migration {
     up(db: Kysely<any>): Promise<void>;
-    down?(db: Kysely<any>): Promise<void>;
-}
-/**
- * Type for the NO_MIGRATIONS constant. Never create one of these.
- */
-export interface NoMigrations {
-    readonly __noMigrations__: true;
-}
-/**
- * All migration methods ({@link MigrationModule.migrateTo | migrateTo},
- * {@link MigrationModule.migrateToLatest | migrateToLatest} etc.) never
- * throw but return this object instead.
- */
-export interface MigrationResultSet {
     /**
-     * This is defined if something went wrong.
+     * An optional down method.
      *
-     * An error may have occurred in one of the migrations in which case the
-     * {@link results} list contains an item with `status === 'Error'` to
-     * indicate which migration failed.
-     *
-     * An error may also have occurred before Kysely was able to figure out
-     * which migrations should be executed, in which case the {@link results}
-     * list is undefined.
-     */
-    readonly error?: unknown;
-    /**
-     * {@link MigrationResult} for each individual migration that was supposed
-     * to be executed by the operation.
-     *
-     * If all went well, each result's `status` is `Success`. If some migration
-     * failed, the failed migration's result's `status` is `Error` and all
-     * results after that one have `status` ´NotExecuted`.
-     *
-     * This property can be undefined if an error occurred before Kysely was
-     * able to figure out which migrations should be executed.
-     *
-     * If this list is empty, there were no migrations to execute.
+     * If you don't provide a down method, the migration is skipped when
+     * migrating down.
      */
-    readonly results?: MigrationResult[];
-}
-export interface MigrationResult {
-    readonly migrationName: string;
-    /**
-     * The direction in which this migration was executed.
-     */
-    readonly direction: 'Up' | 'Down';
-    /**
-     * The execution status.
-     *
-     *  - `Success` means the migration was successfully executed. Note that
-     *    if any of the later migrations in the {@link MigrationResult.results}
-     *    list failed (have status `Error`) AND the dialect supports transactional
-     *    DDL, even the successfull migrations were rolled back.
-     *
-     *  - `Error` means the migration failed. In this case the
-     *    {@link MigrationResult.error} contains the error.
-     *
-     *  - `NotExecuted` means that the migration was supposed to be executed
-     *    but wasn't because an earlier migration failed.
-     */
-    readonly status: 'Success' | 'Error' | 'NotExecuted';
+    down?(db: Kysely<any>): Promise<void>;
 }
-export declare class MigrationModule {
+/**
+ * A class for running migrations.
+ *
+ * ### Example
+ *
+ * This example uses the {@link FileMigrationProvider} that reads migrations
+ * files from a single folder. You can easily implement your own
+ * {@link MigrationProvider} if you want to provide migrations some
+ * other way.
+ *
+ * ```ts
+ * const migrator = new Migrator({
+ *   db,
+ *   // The constructor signature of FileMigrationProvider is a
+ *   // bit weird to keep Kysely independent of node.js or any
+ *   // other environment.
+ *   provider: new FileMigrationProvider(
+ *     fs.readdir,
+ *     path.join,
+ *     // Path to the folder that contains all your migrations.
+ *     'migrations'
+ *   )
+ * })
+ * ```
+ */
+export declare class Migrator {
     #private;
-    constructor(db: Kysely<any>, adapter: DialectAdapter);
+    constructor(props: MigratorProps);
     /**
      * Runs all migrations that have not yet been run.
      *
-     * The only argument must either be a file path to the folder that contains all migrations
-     * OR an object that contains all migrations (not just the ones that need to be executed).
-     * The keys in the object must be the unique migration names.
-     *
      * This method returns a {@link MigrationResultSet} instance and _never_ throws.
      * {@link MigrationResultSet.error} holds the error if something went wrong.
      * {@link MigrationResultSet.results} contains information about which migrations
      * were executed and which failed. See the examples below.
      *
-     * This method goes through all possible migrations (passed as the argument) and runs the
-     * ones whose names are alphabetically after the last migration that has been run. If the
+     * This method goes through all possible migrations provided by the provider and runs the
+     * ones whose names come alphabetically after the last migration that has been run. If the
      * list of executed migrations doesn't match the beginning of the list of possible migrations
      * an error is thrown.
      *
      * ### Examples
      *
      * ```ts
-     * const { error, results } = await db.migration.migrateToLatest(
-     *   path.join(__dirname, 'migrations')
-     * )
+     * import * as path from 'path'
+     * import * as fs from 'fs/promises'
+     *
+     * const db = new Kysely<Database>({
+     *   dialect: new PostgresDialect({
+     *     host: 'localhost',
+     *     database: 'kysely_test',
+     *   }),
+     * })
+     *
+     * const migrator = new Migrator({
+     *   db,
+     *   // The constructor signature of FileMigrationProvider is a
+     *   // bit weird to keep Kysely independent of node.js or any
+     *   // other environment.
+     *   provider: new FileMigrationProvider(
+     *     fs.readdir,
+     *     path.join,
+     *     // Path to the folder that contains all your migrations.
+     *     'migrations'
+     *   )
+     * })
+     *
+     * const { error, results } = await migrator.migrateToLatest()
      *
      * results?.forEach((it) => {
      *   if (it.status === 'Success') {
@@ -110,100 +95,140 @@ export declare class MigrationModule {
      *   console.error(error)
      * }
      * ```
-     *
-     * In the next example, we use a record of migration objects instead of file folder path.
-     * The keys in the object are migration names that can be anything you want. The order of
-     * the migrations is determined based on the alphabetical order of the keys in the record.
-     * This version of the `migrateToLatest` method can be useful if you are using a bundler
-     * like webpack or esbuild.
-     *
-     * ```ts
-     * await db.migration.migrateToLatest({
-     *   migration1: {
-     *     async up(db: Kysely<any>): Promise<void> {
-     *       ...
-     *     },
-     *
-     *     async down(db: Kysely<any>): Promise<void> {
-     *       ...
-     *     }
-     *   },
-     *
-     *   migration2: {
-     *     async up(db: Kysely<any>): Promise<void> {
-     *       ...
-     *     },
-     *
-     *     async down(db: Kysely<any>): Promise<void> {
-     *       ...
-     *     }
-     *   },
-     *
-     *  ...
-     * })
-     * ```
      */
-    migrateToLatest(migrationsFolderPath: string): Promise<MigrationResultSet>;
-    migrateToLatest(allMigrations: Record<string, Migration>): Promise<MigrationResultSet>;
+    migrateToLatest(): Promise<MigrationResultSet>;
     /**
      * Migrate up/down to a specific migration.
      *
-     * Otherwise works just like {@link migrateToLatest}. The first argument
-     * behaves the same, the output is the same etc.
+     * This method returns a {@link MigrationResultSet} instance and _never_ throws.
+     * {@link MigrationResultSet.error} holds the error if something went wrong.
+     * {@link MigrationResultSet.results} contains information about which migrations
+     * were executed and which failed.
      *
      * ### Examples
      *
      * ```ts
-     * await db.migration.migrateTo(
-     *   path.join(__dirname, 'migrations'),
-     *   'some_migration'
-     * )
+     * await migrator.migrateTo('some_migration')
      * ```
      *
      * If you specify the name of the first migration, this method migrates
-     * down to the first migration, but doesn't run the `down` migration for
-     * the first migration. In case you want to migrate down ALL migrations
+     * down to the first migration, but doesn't run the `down` method of
+     * the first migration. In case you want to migrate all the way down,
      * you can use a special constant `NO_MIGRATIONS`:
      *
      * ```ts
-     * await db.migration.migrateTo(
-     *   path.join(__dirname, 'migrations'),
-     *   NO_MIGRATIONS,
-     * )
+     * await migrator.migrateTo(NO_MIGRATIONS)
      * ```
      */
-    migrateTo(migrationsFolderPath: string, targetMigrationName: string | NoMigrations): Promise<MigrationResultSet>;
-    migrateTo(allMigrations: Record<string, Migration>, targetMigrationName: string | NoMigrations): Promise<MigrationResultSet>;
+    migrateTo(targetMigrationName: string | NoMigrations): Promise<MigrationResultSet>;
     /**
      * Migrate one step up.
      *
-     * Otherwise works just like {@link migrateToLatest}. The only argument
-     * behaves the same, the output is the same etc.
+     * This method returns a {@link MigrationResultSet} instance and _never_ throws.
+     * {@link MigrationResultSet.error} holds the error if something went wrong.
+     * {@link MigrationResultSet.results} contains information about which migrations
+     * were executed and which failed.
      *
      * ### Examples
      *
      * ```ts
-     * await db.migration.migrateUp(
-     *   path.join(__dirname, 'migrations'),
-     * )
+     * await migrator.migrateUp()
      * ```
      */
-    migrateUp(migrationsFolderPath: string): Promise<MigrationResultSet>;
-    migrateUp(allMigrations: Record<string, Migration>): Promise<MigrationResultSet>;
+    migrateUp(): Promise<MigrationResultSet>;
     /**
      * Migrate one step down.
      *
-     * Otherwise works just like {@link migrateToLatest}. The only argument
-     * behaves the same, the output is the same etc.
+     * This method returns a {@link MigrationResultSet} instance and _never_ throws.
+     * {@link MigrationResultSet.error} holds the error if something went wrong.
+     * {@link MigrationResultSet.results} contains information about which migrations
+     * were executed and which failed.
      *
      * ### Examples
      *
      * ```ts
-     * await db.migration.migrateDown(
-     *   path.join(__dirname, 'migrations'),
-     * )
+     * await migrator.migrateDown()
      * ```
      */
-    migrateDown(migrationsFolderPath: string): Promise<MigrationResultSet>;
-    migrateDown(allMigrations: Record<string, Migration>): Promise<MigrationResultSet>;
+    migrateDown(): Promise<MigrationResultSet>;
+}
+export interface MigratorProps {
+    readonly db: Kysely<any>;
+    readonly provider: MigrationProvider;
+}
+/**
+ * All migration methods ({@link MigrationModule.migrateTo | migrateTo},
+ * {@link MigrationModule.migrateToLatest | migrateToLatest} etc.) never
+ * throw but return this object instead.
+ */
+export interface MigrationResultSet {
+    /**
+     * This is defined if something went wrong.
+     *
+     * An error may have occurred in one of the migrations in which case the
+     * {@link results} list contains an item with `status === 'Error'` to
+     * indicate which migration failed.
+     *
+     * An error may also have occurred before Kysely was able to figure out
+     * which migrations should be executed, in which case the {@link results}
+     * list is undefined.
+     */
+    readonly error?: unknown;
+    /**
+     * {@link MigrationResult} for each individual migration that was supposed
+     * to be executed by the operation.
+     *
+     * If all went well, each result's `status` is `Success`. If some migration
+     * failed, the failed migration's result's `status` is `Error` and all
+     * results after that one have `status` ´NotExecuted`.
+     *
+     * This property can be undefined if an error occurred before Kysely was
+     * able to figure out which migrations should be executed.
+     *
+     * If this list is empty, there were no migrations to execute.
+     */
+    readonly results?: MigrationResult[];
+}
+export interface MigrationResult {
+    readonly migrationName: string;
+    /**
+     * The direction in which this migration was executed.
+     */
+    readonly direction: 'Up' | 'Down';
+    /**
+     * The execution status.
+     *
+     *  - `Success` means the migration was successfully executed. Note that
+     *    if any of the later migrations in the {@link MigrationResult.results}
+     *    list failed (have status `Error`) AND the dialect supports transactional
+     *    DDL, even the successfull migrations were rolled back.
+     *
+     *  - `Error` means the migration failed. In this case the
+     *    {@link MigrationResult.error} contains the error.
+     *
+     *  - `NotExecuted` means that the migration was supposed to be executed
+     *    but wasn't because an earlier migration failed.
+     */
+    readonly status: 'Success' | 'Error' | 'NotExecuted';
+}
+export interface MigrationProvider {
+    /**
+     * Returns all migrations, old and new.
+     *
+     * For example if you have your migrations in a folder as separate files,
+     * you can use the {@link FileMigrationProvider} that implements this
+     * method to return all migrations in a folder.
+     *
+     * The keys of the returned object are migration names and values are the
+     * migrations. The order of the migrations is determined by the alphabetical
+     * order of the migration names. The items in the object don't need to be
+     * sorted, they are sorted by Kysely.
+     */
+    getMigrations(): Promise<Record<string, Migration>>;
+}
+/**
+ * Type for the {@link NO_MIGRATIONS} constant. Never create one of these.
+ */
+export interface NoMigrations {
+    readonly __noMigrations__: true;
 }