# migration-runner

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->
## Purpose

`MigrationRunner` is the top-level orchestrator for the migration package. It wires together the planner, executor, store, lock, and event bus into a single high-level API. Consumers create a runner with their migration list and store adapter, then call `up()` to apply pending migrations, `down()` to roll back, `status()` to inspect the current state, and `validate()` to verify migration metadata consistency before running.

## Features

- `up(options?)` — plans and applies all pending migrations; respects advisory locks, AbortSignal, and dry-run mode.
- `down(options?)` — plans and rolls back the last N applied migrations.
- `status()` — returns combined status of all registered migrations.
- `validate()` — checks for duplicate IDs and returns structured validation errors.
- Injectable `Clock`, `LoggerLike`, `EventBus`, and `MigrationLockAdapter`.
- `createMigrationRunner` factory function for ergonomic construction.

## Usage: Basic Example

```ts
import { MigrationRunner, MemoryMigrationStore } from "@suaveplan/migration";

const store = new MemoryMigrationStore();
const runner = new MigrationRunner({ migrations, store });
const result = await runner.up();
// result.applied lists migration IDs that were applied
```

## Usage: Advanced Example

```ts
import { MigrationRunner, MemoryMigrationStore, MemoryMigrationLock } from "@suaveplan/migration";
import { EventBus } from "@suaveplan/events";

const store = new MemoryMigrationStore();
const lock = new MemoryMigrationLock();
const events = new EventBus<MigrationEventMap>();

events.on("migration:after", ({ migration, durationMs }) => {
  console.log(`Applied ${migration.id} in ${durationMs}ms`);
});

const runner = new MigrationRunner({ migrations, store, lock, events, checksumValidation: true });
await runner.up({ signal: abortController.signal });
```

## API Reference

### `class MigrationRunner`

**Constructor**: `(config: MigrationRunnerConfig, clock?: Clock)`

- `config.migrations` — array of `Migration` objects.
- `config.store` — `MigrationStoreAdapter` for ledger persistence.
- `config.lock?` — optional `MigrationLockAdapter`.
- `config.logger?` — optional `LoggerLike` for structured log output.
- `config.events?` — optional `EventBus<MigrationEventMap>`.
- `config.dryRun?` — default `false`.
- `config.checksumValidation?` — default `true`.

### `up(options?: RunOptions): Promise<MigrationResult>`

Returns `{ applied, skipped, failed, direction: "up", dryRun }`.

### `down(options?: RunOptions & { steps?: number }): Promise<MigrationResult>`

Returns `{ applied, skipped, failed, direction: "down", dryRun }`.

### `status(): Promise<MigrationStatusEntry[]>`

Returns status for every registered migration sorted by id.

### `validate(): Promise<ValidationResult>`

Returns `{ valid, errors }`.

### `createMigrationRunner(config, clock?): MigrationRunner`

Factory function — equivalent to `new MigrationRunner(config, clock)`.

## Implementation Notes

The `buildContext()` method provides a no-op `execute`/`query` implementation suitable for runners that do not need direct database access in migration functions (e.g. when the migration functions close over an external adapter). Consumers requiring SQL execution in migration functions should provide a custom context via a subclass.