import type { PrismaClient } from "@prisma/client";
import type { Pool } from "mysql2/promise";

export interface MigrationContext {
  prisma: PrismaClient;
  mysql: Pool;
  dryRun: boolean;
  reset?: boolean;
  environment?: string; // 'uat' or 'prod'
  verbose?: boolean; // Show detailed output for media migrations
  onlyCourse?: string; // Filter media migrations to specific course code
}

export interface MigrationDefinition<Row = unknown, Data = unknown> {
  /**
   * Unique name for logging and filtering (used with --only).
   */
  name: string;
  /**
   * Either a static SQL string or a factory that will be invoked for every batch.
   * When `batchSize` is provided and a plain string is used, `LIMIT/OFFSET` are appended automatically.
   */
  sourceQuery: string | ((params: { offset: number; batchSize: number }) => string | Promise<string>);
  /**
   * Optional batch size for paginating legacy rows. When omitted, the query is executed once.
   */
  batchSize?: number;
  /**
   * Allow short-circuiting specific rows by returning `null`.
   * Can return a single payload or an array of payloads (for quizzes that map to multiple courses).
   */
  transform: (row: Row, context: MigrationContext) => Promise<Data | Data[] | null> | Data | Data[] | null;
  /**
   * Persist the transformed payload using Prisma.
   */
  upsert: (payload: Data, context: MigrationContext) => Promise<void>;
}