diff --git a/.changeset/brown-cheetahs-notice.md b/.changeset/brown-cheetahs-notice.md new file mode 100644 index 0000000..2f09a3e --- /dev/null +++ b/.changeset/brown-cheetahs-notice.md @@ -0,0 +1,5 @@ +--- +'@emigrate/plugin-tools': minor +--- + +Pass the current command to the reporter diff --git a/packages/plugin-tools/src/index.ts b/packages/plugin-tools/src/index.ts index b0726ea..0ba58fe 100644 --- a/packages/plugin-tools/src/index.ts +++ b/packages/plugin-tools/src/index.ts @@ -42,6 +42,7 @@ export const isEmigrateReporter = (plugin: any): plugin is EmigrateReporter => { 'onInit', 'onCollectedMigrations', 'onLockedMigrations', + 'onNewMigration', 'onMigrationStart', 'onMigrationSuccess', 'onMigrationError', diff --git a/packages/plugin-tools/src/types.ts b/packages/plugin-tools/src/types.ts index f344f85..cb1d061 100644 --- a/packages/plugin-tools/src/types.ts +++ b/packages/plugin-tools/src/types.ts @@ -150,7 +150,11 @@ export type LoaderPlugin = { loadMigration(migration: MigrationMetadata): Awaitable; }; -type InitParameters = { +export type ReporterInitParameters = { + /** + * The command that is being executed + */ + command: 'up' | 'new' | 'list'; /** * The directory where the migration files are located */ @@ -161,15 +165,17 @@ type InitParameters = { cwd: string; /** * Specifies whether the migration process is a dry run or not. + * + * Will only be true when the command is 'up' and the --dry option is specified. */ dry: boolean; }; export type EmigrateReporter = Partial<{ /** - * Called when the plugin is initialized, which happens before the migrations are collected. + * Called when the reporter is initialized, which is the first method that is called when a command is executed. */ - onInit(parameters: InitParameters): Awaitable; + onInit(parameters: ReporterInitParameters): Awaitable; /** * Called when all pending migrations that should be executed have been collected. * @@ -185,37 +191,57 @@ export type EmigrateReporter = Partial<{ * @param migrations The migrations that have been successfully locked so they can be executed. */ onLockedMigrations(migrations: MigrationMetadata[]): Awaitable; + /** + * Called when a new migration file has been generated. + * + * This is only called when the command is 'new'. + */ + onNewMigration(migration: MigrationMetadata, content: string): Awaitable; /** * Called when a migration is about to be executed. * + * Will only be called for each migration when the command is "up". + * * @param migration Information about the migration that is about to be executed. */ onMigrationStart(migration: MigrationMetadata): Awaitable; /** * Called when a migration has been successfully executed. * + * Will be called after a successful migration when the command is "up" + * or for each successful migration from the history when the command is "list". + * * @param migration Information about the migration that was executed. */ onMigrationSuccess(migration: MigrationMetadataFinished): Awaitable; /** * Called when a migration has failed. * + * Will be called after a failed migration when the command is "up" + * or for each failed migration from the history when the command is "list" (will be at most one in this case). + * * @param migration Information about the migration that failed. * @param error The error that caused the migration to fail. */ onMigrationError(migration: MigrationMetadataFinished, error: Error): Awaitable; /** - * Called when a migration has been skipped because a previous migration failed, it couldn't be successfully locked, or in case of a dry run. + * Called when a migration is skipped + * + * Will be called when a migration is skipped because a previous migration failed, + * it couldn't be successfully locked, or in case of a dry run when the command is "up". + * When the command is "list" this will be called for each pending migration (i.e. those that have not run yet). * * @param migration Information about the migration that was skipped. */ onMigrationSkip(migration: MigrationMetadataFinished): Awaitable; /** - * Called when the migration process has finished. + * Called as a final step after all migrations have been executed or listed. * - * This is called either after all migrations have been executed successfully, at the end of a dry run, or when a migration has failed. + * This is called either after all migrations have been listed successfully for the "list" command + * or for the "up" command when they are executed successfully, at the end of a dry run, or when a migration has failed. + * It is also called after a migration file has been generated with the "new" command. * - * @param migrations Information about all migrations that were executed, their status and any error that occurred. + * @param migrations Information about all migrations that were executed or listed, their status and any error that occurred. * @param error If the migration process failed, this will be the error that caused the failure. */ onFinished(migrations: MigrationMetadataFinished[], error?: Error): Awaitable;