docs: add some basic documentation for the storage plugin api

docs/src/content/docs/reference/migration-types.mdx

@@ -0,0 +1,93 @@
+---
+title: Migration Types
+---
+
+import Link from '@components/Link.astro';
+
+These are common TypeScript types for migration files used by <Link href="/plugins/">plugins</Link>.
+
+## `MigrationMetadata`
+
+```ts
+type MigrationMetadata = {
+  /**
+   * The name of the migration file
+   *
+   * @example 20210901123456000_create_users_table.js
+   */
+  name: string;
+  /**
+   * The directory where the migration file is located, relative to the current working directory
+   *
+   * @example migrations
+   */
+  directory: string;
+  /**
+   * The full absolute path to the migration file
+   *
+   * @example /home/user/project/migrations/20210901123456000_create_users_table.js
+   */
+  filePath: string;
+  /**
+   * The relative path to the migration file, relative to the current working directory
+   *
+   * @example migrations/20210901123456000_create_users_table.js
+   */
+  relativeFilePath: string;
+  /**
+   * The current working directory (the same as process.cwd())
+   */
+  cwd: string;
+  /**
+   * The extension of the migration file, with a leading period
+   *
+   * @example .js
+   */
+  extension: string;
+};
+```
+
+## `MigrationMetadataFinished`
+
+```ts
+type MigrationMetadataFinished = MigrationMetadata & {
+  status: 'done' | 'failed' | 'skipped' | 'pending';
+  /**
+   * The duration of the migration in milliseconds
+   */
+  duration: number;
+  /**
+   * The error that occurred during the migration, if `status` is `"failed"`
+   */
+  error?: Error;
+};
+```
+
+## `MigrationHistoryEntry`
+
+```ts
+type MigrationHistoryEntry = {
+  /**
+   * The name of the migration.
+   * 
+   * @example 20210901123456000_create_users_table.js
+   */
+  name: string;
+  /**
+   * The date when the migration was executed.
+   */
+  date: Date;
+  /**
+   * The status of the migration.
+   * 
+   * As an entry is only added to the history after the migration has finished, this will always be either `"done"` or `"failed"`.
+   */
+  status: 'done' | 'failed';
+  /**
+   * The error that occurred during the migration, if `status` is `"failed"`
+   * 
+   * This should be a plain object, as it is serialized when passed to the storage plugin's `onError` method.
+   */
+  error?: Record<string, unknown>;
+};
+```

docs/src/content/docs/reference/storage-plugin-api.mdx

@@ -0,0 +1,86 @@
+---
+title: Storage Plugin API
+---
+
+import Link from '@components/Link.astro';
+
+When writing a storage plugin, you will need to implement the following interface:
+
+```ts
+type EmigrateStorage = {
+  initializeStorage(): Promise<Storage>;
+};
+```
+
+Where `Storage` is the following interface:
+
+```ts
+type Storage = {
+  /**
+   * Acquire a lock on the given migrations.
+   *
+   * To best support concurrent migrations (e.g. when multiple services are deployed at the same time and want to migrate the same database)
+   * the plugin should try to lock all migrations at once (i.e. in a transaction) and ignore migrations that are already locked (or done).
+   * The successfully locked migrations should be returned and are the migrations that will be executed.
+   *
+   * If one of the migrations to lock is in a failed state, the plugin should throw an error to abort the migration attempt.
+   *
+   * @returns The migrations that were successfully locked.
+   */
+  lock(migrations: MigrationMetadata[]): Promise<MigrationMetadata[]>;
+  /**
+   * The unlock method is called after all migrations have been executed or when the process is interrupted (e.g. by a SIGTERM or SIGINT signal).
+   *
+   * Depending on the plugin implementation, the unlock method is usually a no-op for already succeeded or failed migrations.
+   *
+   * @param migrations The previously successfully locked migrations that should now be unlocked.
+   */
+  unlock(migrations: MigrationMetadata[]): Promise<void>;
+
+  /**
+   * Remove a migration from the history.
+   *
+   * This is used to remove a migration from the history which is needed for failed migrations to be re-executed.
+   *
+   * @param migration The migration that should be removed from the history.
+   */
+  remove(migration: MigrationMetadata): Promise<void>;
+  /**
+   * Get the history of previously executed migrations.
+   *
+   * For failed migrations, the error property should be set.
+   * Emigrate will not sort the history entries, so the plugin should return the entries in the order they were executed.
+   * The order doesn't affect the execution of migrations, but it does affect the order in which the history is displayed in the CLI.
+   * Migrations that have not yet been executed will always be run in alphabetical order.
+   *
+   * The history has two purposes:
+   * 1. To determine which migrations have already been executed.
+   * 2. To list the migration history in the CLI.
+   */
+  getHistory(): AsyncIterable<MigrationHistoryEntry>;
+  /**
+   * Called when a migration has been successfully executed.
+   *
+   * @param migration The name of the migration that should be marked as done.
+   */
+  onSuccess(migration: MigrationMetadataFinished): Promise<void>;
+  /**
+   * Called when a migration has failed.
+   *
+   * The passed error will be serialized so it's easily storable it in the history.
+   * If the original Error instance is needed it's available as the `error` property on the finished migration.
+   *
+   * @param migration The name of the migration that should be marked as failed.
+   * @param error The error that caused the migration to fail. Serialized for easy storage.
+   */
+  onError(migration: MigrationMetadataFinished, error: SerializedError): Promise<void>;
+  /**
+   * Called when the command is finished or aborted (e.g. by a SIGTERM or SIGINT signal).
+   *
+   * Use this to clean up any resources like database connections or file handles.
+   */
+  end(): Promise<void>;
+};
+```
+
+See the <Link href="/reference/migration-types/">Migration Types</Link> page for more information about the `MigrationMetadata`, `MigrationMetadataFinished`, and `MigrationHistoryEntry` types.