@dotdo/postgres 0.1.0

package/src/migrations/do-migrations.types.ts

@@ -0,0 +1,715 @@
+/**
+ * DO Migration System Types
+ *
+ * Type definitions for the Durable Object-specific migration system.
+ * Designed for the unique requirements of Cloudflare Durable Objects:
+ *
+ * - Fast, idempotent migrations (called on every request)
+ * - Memory-efficient for Workers environment
+ * - Support for schema snapshots for fast bootstrapping
+ * - Integration with existing MigrationRunner system
+ *
+ * @module migrations/do-migrations.types
+ */
+
+import type { PGlite } from '@dotdo/pglite'
+
+// =============================================================================
+// Core Migration Types
+// =============================================================================
+
+/**
+ * Migration execution function type
+ *
+ * Migrations can be defined as:
+ * - SQL string
+ * - Sync function returning SQL string
+ * - Async function returning SQL string
+ * - Function that executes directly against PGlite
+ */
+export type MigrationExecutor =
+  | string
+  | (() => string)
+  | (() => Promise<string>)
+  | ((db: PGlite) => Promise<void>)
+
+/**
+ * DO Migration definition
+ *
+ * A migration specifically designed for Durable Object databases.
+ * Supports both SQL strings and programmatic migrations.
+ *
+ * @example SQL string migration
+ * ```typescript
+ * const migration: DOMigration = {
+ *   version: 1,
+ *   name: 'create_users',
+ *   up: `
+ *     CREATE TABLE users (
+ *       id SERIAL PRIMARY KEY,
+ *       email TEXT NOT NULL UNIQUE
+ *     );
+ *   `,
+ *   down: 'DROP TABLE users;',
+ * }
+ * ```
+ *
+ * @example Programmatic migration
+ * ```typescript
+ * const migration: DOMigration = {
+ *   version: 2,
+ *   name: 'seed_data',
+ *   up: async (db) => {
+ *     await db.exec(`INSERT INTO users (email) VALUES ('admin@example.com');`)
+ *   },
+ *   isReversible: false,
+ * }
+ * ```
+ */
+export interface DOMigration {
+  /**
+   * Migration version number
+   *
+   * Must be a positive integer. Migrations are executed in version order.
+   * Version numbers should be monotonically increasing.
+   */
+  version: number
+
+  /**
+   * Human-readable migration name
+   *
+   * Used for logging and status displays.
+   * Convention: snake_case description (e.g., 'create_users', 'add_email_index')
+   */
+  name: string
+
+  /**
+   * Forward migration executor
+   *
+   * Can be:
+   * - SQL string
+   * - Function returning SQL string
+   * - Async function returning SQL string
+   * - Function that executes directly against the database
+   */
+  up: MigrationExecutor
+
+  /**
+   * Rollback migration executor (optional)
+   *
+   * Same types as `up`. If not provided, migration cannot be rolled back.
+   */
+  down?: MigrationExecutor
+
+  /**
+   * Whether this migration can be safely rolled back
+   *
+   * Defaults to true if down is provided.
+   * Set to false for data migrations that cannot be safely reversed.
+   */
+  isReversible?: boolean
+
+  /**
+   * Whether to run outside a transaction
+   *
+   * Required for operations like CREATE INDEX CONCURRENTLY.
+   * Default: false (run in transaction)
+   */
+  transactional?: boolean
+
+  /**
+   * Custom timeout for this migration in milliseconds
+   *
+   * Overrides the global migration timeout.
+   */
+  timeoutMs?: number
+
+  /**
+   * Migration tags for categorization
+   *
+   * Examples: ['schema', 'data', 'index', 'seed']
+   */
+  tags?: string[]
+
+  /**
+   * Migration description
+   *
+   * Longer description of what this migration does.
+   */
+  description?: string
+}
+
+// =============================================================================
+// Migration Result Types
+// =============================================================================
+
+/**
+ * Result of a single migration execution
+ */
+export interface DOMigrationResult {
+  /** Whether the migration succeeded */
+  success: boolean
+
+  /** Migration version */
+  version: number
+
+  /** Migration name */
+  name: string
+
+  /** Execution time in milliseconds */
+  executionTimeMs: number
+
+  /** Error message if failed */
+  error?: string
+
+  /** Whether this migration was skipped (already applied) */
+  skipped?: boolean
+
+  /** Checksum of the applied migration */
+  checksum?: string
+}
+
+/**
+ * Result of a batch migration operation
+ */
+export interface DOMigrationBatchResult {
+  /** Whether all migrations succeeded */
+  success: boolean
+
+  /** Schema version before migration */
+  fromVersion: number
+
+  /** Schema version after migration */
+  toVersion: number
+
+  /** Total execution time in milliseconds */
+  totalTimeMs: number
+
+  /** Individual migration results */
+  results: DOMigrationResult[]
+
+  /** Number of migrations executed */
+  migrationsRun: number
+
+  /** Number of migrations skipped */
+  migrationsSkipped: number
+
+  /** Error message if batch failed */
+  error?: string
+}
+
+// =============================================================================
+// Runner State Types
+// =============================================================================
+
+/**
+ * Current state of the DO migration system
+ */
+export type DOMigrationState =
+  | 'uninitialized'
+  | 'initializing'
+  | 'ready'
+  | 'migrating'
+  | 'error'
+
+/**
+ * Schema version info from the meta table
+ */
+export interface DOSchemaVersion {
+  /** Current schema version (highest applied migration) */
+  currentVersion: number
+
+  /** Number of applied migrations */
+  appliedCount: number
+
+  /** Timestamp of last migration */
+  lastMigrationAt: Date | null
+
+  /** Checksum of all applied migrations */
+  schemaChecksum: string | null
+}
+
+/**
+ * Migration record stored in the meta table
+ */
+export interface DOMigrationRecord {
+  /** Migration version */
+  version: number
+
+  /** Migration name */
+  name: string
+
+  /** Checksum of migration content */
+  checksum: string
+
+  /** When migration was applied */
+  appliedAt: Date
+
+  /** Execution time in milliseconds */
+  executionTimeMs: number
+}
+
+// =============================================================================
+// Schema Snapshot Types
+// =============================================================================
+
+/**
+ * Pre-computed schema snapshot for fast bootstrapping
+ *
+ * Instead of running migrations incrementally, a new DO can apply
+ * a pre-computed snapshot containing the final schema state.
+ */
+export interface DOSchemaSnapshot {
+  /**
+   * Target schema version this snapshot represents
+   */
+  targetVersion: number
+
+  /**
+   * Combined DDL SQL to create the full schema
+   *
+   * This is the result of applying all migrations up to targetVersion.
+   */
+  schemaDDL: string
+
+  /**
+   * Checksum of all source migrations
+   *
+   * Used to validate the snapshot matches the current migrations.
+   */
+  migrationsChecksum: string
+
+  /**
+   * List of migration versions included in this snapshot
+   */
+  includedVersions: number[]
+
+  /**
+   * When this snapshot was generated
+   */
+  generatedAt: Date
+
+  /**
+   * Optional seed data SQL
+   */
+  seedDataDDL?: string
+}
+
+// =============================================================================
+// Configuration Types
+// =============================================================================
+
+/**
+ * Configuration options for the DO migration runner
+ */
+export interface DOMigrationConfig {
+  /**
+   * Name of the meta table for tracking migrations
+   *
+   * Default: '_do_migrations'
+   */
+  metaTableName?: string
+
+  /**
+   * Whether to use advisory locking
+   *
+   * Prevents concurrent migration execution.
+   * Default: true
+   */
+  useLocking?: boolean
+
+  /**
+   * Lock timeout in milliseconds
+   *
+   * How long to wait to acquire the migration lock.
+   * Default: 5000 (5 seconds)
+   */
+  lockTimeoutMs?: number
+
+  /**
+   * Default migration timeout in milliseconds
+   *
+   * Can be overridden per-migration.
+   * Default: 30000 (30 seconds)
+   */
+  migrationTimeoutMs?: number
+
+  /**
+   * Enable schema snapshot mode
+   *
+   * When enabled and a snapshot is available, new DOs will use
+   * the snapshot instead of running incremental migrations.
+   * Default: false
+   */
+  useSnapshot?: boolean
+
+  /**
+   * Pre-computed schema snapshot
+   *
+   * Only used if useSnapshot is true.
+   */
+  snapshot?: DOSchemaSnapshot
+
+  /**
+   * Allow gaps in version numbers
+   *
+   * Default: false
+   */
+  allowVersionGaps?: boolean
+
+  /**
+   * Enable debug logging
+   *
+   * Default: false
+   */
+  debug?: boolean
+
+  /**
+   * Event handler for migration events
+   */
+  onEvent?: DOMigrationEventHandler
+
+  /**
+   * Dry-run mode - validate migrations without executing
+   *
+   * Default: false
+   */
+  dryRun?: boolean
+}
+
+// =============================================================================
+// Event Types
+// =============================================================================
+
+/**
+ * Migration event types
+ */
+export type DOMigrationEventType =
+  | 'initialized'
+  | 'migration:start'
+  | 'migration:complete'
+  | 'migration:error'
+  | 'migration:skip'
+  | 'batch:start'
+  | 'batch:complete'
+  | 'batch:error'
+  | 'lock:acquired'
+  | 'lock:released'
+  | 'lock:timeout'
+  | 'snapshot:applied'
+
+/**
+ * Migration event payload
+ */
+export interface DOMigrationEvent {
+  /** Event type */
+  type: DOMigrationEventType
+
+  /** Timestamp of the event */
+  timestamp: Date
+
+  /** Migration version (for migration events) */
+  version?: number
+
+  /** Migration name (for migration events) */
+  name?: string
+
+  /** Execution time in milliseconds */
+  durationMs?: number
+
+  /** Error if applicable */
+  error?: Error
+
+  /** Additional metadata */
+  metadata?: Record<string, unknown>
+}
+
+/**
+ * Event handler function type
+ */
+export type DOMigrationEventHandler = (event: DOMigrationEvent) => void | Promise<void>
+
+// =============================================================================
+// Runner Interface
+// =============================================================================
+
+/**
+ * DO Migration Runner Interface
+ *
+ * The main interface for running migrations in a Durable Object.
+ * Designed for fast, idempotent operation on every request.
+ *
+ * @example
+ * ```typescript
+ * const runner = createDOMigrationRunner(pglite, migrations, {
+ *   debug: true,
+ * })
+ *
+ * // Called on every request - fast if already migrated
+ * await runner.ensureMigrated()
+ *
+ * // Get current version
+ * const version = await runner.getCurrentVersion()
+ * ```
+ */
+export interface DOMigrationRunner {
+  /**
+   * Current state of the runner
+   */
+  readonly state: DOMigrationState
+
+  /**
+   * Initialize the migration system
+   *
+   * Creates the meta table if it doesn't exist.
+   * Idempotent - safe to call multiple times.
+   */
+  initialize(): Promise<void>
+
+  /**
+   * Run all pending migrations
+   *
+   * Idempotent - calling when already at latest version is a fast no-op.
+   *
+   * @example
+   * ```typescript
+   * const result = await runner.migrate()
+   *
+   * if (result.success) {
+   *   console.log(`Migrated from v${result.fromVersion} to v${result.toVersion}`)
+   *   console.log(`Applied ${result.migrationsRun} migrations in ${result.totalTimeMs}ms`)
+   * } else {
+   *   console.error(`Migration failed: ${result.error}`)
+   * }
+   * ```
+   */
+  migrate(): Promise<DOMigrationBatchResult>
+
+  /**
+   * Ensure the database is migrated to the latest version
+   *
+   * Convenience method that initializes and migrates in one call.
+   * Optimized for calling on every request.
+   *
+   * @example
+   * ```typescript
+   * // In your Durable Object's fetch handler
+   * async fetch(request: Request): Promise<Response> {
+   *   // Fast no-op if already at latest version
+   *   await this.migrationRunner.ensureMigrated()
+   *
+   *   // Process request...
+   * }
+   * ```
+   */
+  ensureMigrated(): Promise<DOMigrationBatchResult>
+
+  /**
+   * Get the current schema version
+   */
+  getCurrentVersion(): Promise<number>
+
+  /**
+   * Get full schema version info
+   */
+  getSchemaVersion(): Promise<DOSchemaVersion>
+
+  /**
+   * Get pending migrations that need to be applied
+   */
+  getPendingMigrations(): Promise<DOMigration[]>
+
+  /**
+   * Check if any migrations are pending
+   */
+  hasPendingMigrations(): Promise<boolean>
+
+  /**
+   * Rollback to a specific version
+   *
+   * @param targetVersion - Version to rollback to (exclusive)
+   * @param options - Rollback options
+   *
+   * @example
+   * ```typescript
+   * // Rollback to version 5 (versions 6+ will be rolled back)
+   * const result = await runner.rollbackTo(5, { dryRun: false })
+   *
+   * if (result.success) {
+   *   console.log(`Rolled back to v${result.toVersion}`)
+   * }
+   * ```
+   */
+  rollbackTo(
+    targetVersion: number,
+    options?: DORollbackOptions
+  ): Promise<DOMigrationBatchResult>
+
+  /**
+   * Rollback the last N migrations
+   *
+   * @param count - Number of migrations to rollback
+   * @param options - Rollback options
+   */
+  rollbackLast(
+    count?: number,
+    options?: DORollbackOptions
+  ): Promise<DOMigrationBatchResult>
+
+  /**
+   * Reset the migration state (drop meta table)
+   *
+   * WARNING: This does not undo schema changes!
+   */
+  reset(): Promise<void>
+
+  /**
+   * Validate migrations without executing
+   *
+   * @returns Validation result with any issues found
+   */
+  validate(): Promise<DOMigrationValidationResult>
+
+  /**
+   * Get the list of all migrations
+   */
+  getMigrations(): DOMigration[]
+
+  /**
+   * Get the latest version from the migration list
+   */
+  getLatestVersion(): number
+
+  /**
+   * Get applied migration records from the meta table
+   */
+  getAppliedMigrations(): Promise<DOMigrationRecord[]>
+
+  /**
+   * Add event listener
+   *
+   * @returns Unsubscribe function
+   */
+  onEvent(handler: DOMigrationEventHandler): () => void
+}
+
+// =============================================================================
+// Rollback Types
+// =============================================================================
+
+/**
+ * Options for rollback operations
+ */
+export interface DORollbackOptions {
+  /**
+   * Preview changes without executing
+   *
+   * Default: false
+   */
+  dryRun?: boolean
+
+  /**
+   * Force rollback of non-reversible migrations
+   *
+   * Default: false
+   */
+  force?: boolean
+
+  /**
+   * Progress callback
+   */
+  onProgress?: (event: DOMigrationEvent) => void
+}
+
+// =============================================================================
+// Validation Types
+// =============================================================================
+
+/**
+ * Validation issue severity
+ */
+export type DOMigrationValidationSeverity = 'error' | 'warning' | 'info'
+
+/**
+ * Validation issue
+ */
+export interface DOMigrationValidationIssue {
+  /** Issue severity */
+  severity: DOMigrationValidationSeverity
+
+  /** Migration version (if applicable) */
+  version?: number
+
+  /** Issue message */
+  message: string
+
+  /** Suggested fix */
+  suggestion?: string
+}
+
+/**
+ * Validation result
+ */
+export interface DOMigrationValidationResult {
+  /** Whether validation passed (no errors) */
+  valid: boolean
+
+  /** List of issues found */
+  issues: DOMigrationValidationIssue[]
+
+  /** Number of errors */
+  errorCount: number
+
+  /** Number of warnings */
+  warningCount: number
+}
+
+// =============================================================================
+// Factory Function Types
+// =============================================================================
+
+/**
+ * Create a DO migration runner
+ *
+ * @param db - PGlite database instance
+ * @param migrations - Array of migrations to manage
+ * @param config - Optional configuration
+ * @returns DOMigrationRunner instance
+ */
+export type CreateDOMigrationRunner = (
+  db: PGlite,
+  migrations: DOMigration[],
+  config?: DOMigrationConfig
+) => DOMigrationRunner
+
+/**
+ * Generate a schema snapshot from migrations
+ *
+ * @param migrations - Array of migrations
+ * @param options - Snapshot generation options
+ * @returns Schema snapshot
+ */
+export type GenerateDOSchemaSnapshot = (
+  migrations: DOMigration[],
+  options?: {
+    includeSeedData?: boolean
+  }
+) => Promise<DOSchemaSnapshot>
+
+/**
+ * Convert standard Migration to DOMigration
+ *
+ * @param migration - Standard migration from MigrationRegistry
+ * @returns DOMigration
+ */
+export type ConvertToDOMigration = (migration: {
+  id: string
+  name: string
+  version: number
+  up: string
+  down?: string
+  isReversible?: boolean
+  transactional?: boolean
+  timeoutMs?: number
+  tags?: string[]
+}) => DOMigration