# migration-planner

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

The migration planner produces `MigrationPlan` objects that describe which migrations should be applied or rolled back, without executing them. Separating planning from execution makes dry-run reporting straightforward, enables validation before any database writes, and simplifies unit testing by removing I/O dependencies from the planning step.

## Features

- `sortMigrations(migrations)` — lexicographic sort by `id`, putting numeric prefixes in ascending order.
- `planUp(all, applied)` — returns all pending (not-yet-applied) migrations sorted ascending.
- `planDown(all, applied, steps?)` — returns the last N applied migrations in reverse (rollback) order.
- `checksumForMigration(migration)` — returns the stored checksum or computes one from the up function body.

## Usage: Basic Example

```ts
import { planUp, sortMigrations } from "@suaveplan/migration";

const plan = planUp(allMigrations, []);
// plan.toApply contains all migrations in ascending id order
```

## Usage: Advanced Example

```ts
import { planDown } from "@suaveplan/migration";

// Rollback only the last 2 applied migrations
const plan = planDown(allMigrations, appliedRecords, 2);
// plan.toRollback[0] is the most recently applied migration
```

## API Reference

### `sortMigrations(migrations: Migration[]): Migration[]`

Returns a new array sorted by `id` ascending. Does not mutate the input.

### `planUp(all: Migration[], applied: MigrationRecord[]): MigrationPlan`

Returns `{ toApply: Migration[], toRollback: [] }`. `toApply` contains migrations whose `id` is not in `applied`.

### `planDown(all: Migration[], applied: MigrationRecord[], steps?: number): MigrationPlan`

Returns `{ toApply: [], toRollback: Migration[] }`. `toRollback` is at most `steps` migrations (all if omitted), most-recent first.

### `checksumForMigration(migration: Migration): string`

Returns `migration.checksum` if set, otherwise computes SHA-256 of `migration.up.toString()`.

## Implementation Notes

`planDown` reverses the sorted applied list before slicing, ensuring rollbacks proceed in most-recent-first order (LIFO). `sortMigrations` uses `localeCompare` for reliable multi-character prefix handling.