feat(types): move Emigrate types to separate package and improve types (#41)

* feat(types): move Emigrate types to separate package

Also refactor the types to use discriminating unions for easier error handling and such.
Errors passed to storage plugins should now be serialized and storage plugins are expected to return already serialized errors on failed history entries.

* fix(mysql): handle the new type changes

* fix(storage-fs): handle the new type changes

* feat(cli): better error handling and types

Adapt to the new types from the @emigrate/types package, like discriminating union types and serializing and deserializing errors

packages/cli/src/commands/list.ts

@@ -1,6 +1,6 @@
 import process from 'node:process';
 import { getOrLoadReporter, getOrLoadStorage } from '@emigrate/plugin-tools';
-import { BadOptionError, MissingOptionError, StorageInitError } from '../errors.js';
+import { BadOptionError, MissingOptionError, StorageInitError, toError } from '../errors.js';
 import { type Config } from '../types.js';
 import { exec } from '../exec.js';
 import { migrationRunner } from '../migration-runner.js';
@@ -12,20 +12,20 @@ const lazyDefaultReporter = async () => import('../reporters/default.js');
 
 export default async function listCommand({ directory, reporter: reporterConfig, storage: storageConfig }: Config) {
   if (!directory) {
-    throw new MissingOptionError('directory');
+    throw MissingOptionError.fromOption('directory');
   }
 
   const cwd = process.cwd();
   const storagePlugin = await getOrLoadStorage([storageConfig]);
 
   if (!storagePlugin) {
-    throw new BadOptionError('storage', 'No storage found, please specify a storage using the storage option');
+    throw BadOptionError.fromOption('storage', 'No storage found, please specify a storage using the storage option');
   }
 
   const reporter = await getOrLoadReporter([reporterConfig ?? lazyDefaultReporter]);
 
   if (!reporter) {
-    throw new BadOptionError(
+    throw BadOptionError.fromOption(
       'reporter',
       'No reporter found, please specify an existing reporter using the reporter option',
     );
@@ -36,25 +36,33 @@ export default async function listCommand({ directory, reporter: reporterConfig,
   const [storage, storageError] = await exec(async () => storagePlugin.initializeStorage());
 
   if (storageError) {
-    await reporter.onFinished?.([], new StorageInitError('Could not initialize storage', { cause: storageError }));
+    await reporter.onFinished?.([], StorageInitError.fromError(storageError));
 
     return 1;
   }
 
-  const collectedMigrations = collectMigrations(cwd, directory, storage.getHistory());
+  try {
+    const collectedMigrations = collectMigrations(cwd, directory, storage.getHistory());
 
-  const error = await migrationRunner({
-    dry: true,
-    reporter,
-    storage,
-    migrations: await arrayFromAsync(collectedMigrations),
-    async validate() {
-      // No-op
-    },
-    async execute() {
-      throw new Error('Unexpected execute call');
-    },
-  });
+    const error = await migrationRunner({
+      dry: true,
+      reporter,
+      storage,
+      migrations: await arrayFromAsync(collectedMigrations),
+      async validate() {
+        // No-op
+      },
+      async execute() {
+        throw new Error('Unexpected execute call');
+      },
+    });
 
-  return error ? 1 : 0;
+    return error ? 1 : 0;
+  } catch (error) {
+    await reporter.onFinished?.([], toError(error));
+
+    return 1;
+  } finally {
+    await storage.end();
+  }
 }

packages/cli/src/commands/new.ts

@@ -2,11 +2,19 @@ import process from 'node:process';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { getTimestampPrefix, sanitizeMigrationName, getOrLoadPlugin, getOrLoadReporter } from '@emigrate/plugin-tools';
-import { type MigrationMetadata } from '@emigrate/plugin-tools/types';
-import { BadOptionError, MissingArgumentsError, MissingOptionError, UnexpectedError } from '../errors.js';
+import { type MigrationMetadataFinished, type MigrationMetadata, isFailedMigration } from '@emigrate/types';
+import {
+  BadOptionError,
+  EmigrateError,
+  MissingArgumentsError,
+  MissingOptionError,
+  UnexpectedError,
+  toError,
+} from '../errors.js';
 import { type Config } from '../types.js';
 import { withLeadingPeriod } from '../with-leading-period.js';
 import { version } from '../get-package-info.js';
+import { getDuration } from '../get-duration.js';
 
 const lazyDefaultReporter = async () => import('../reporters/default.js');
 
@@ -15,15 +23,15 @@ export default async function newCommand(
   name: string,
 ) {
   if (!directory) {
-    throw new MissingOptionError('directory');
+    throw MissingOptionError.fromOption('directory');
   }
 
   if (!name) {
-    throw new MissingArgumentsError('name');
+    throw MissingArgumentsError.fromArgument('name');
   }
 
   if (!extension && !template && plugins.length === 0) {
-    throw new MissingOptionError(['extension', 'template', 'plugin']);
+    throw MissingOptionError.fromOption(['extension', 'template', 'plugin']);
   }
 
   const cwd = process.cwd();
@@ -31,7 +39,7 @@ export default async function newCommand(
   const reporter = await getOrLoadReporter([reporterConfig ?? lazyDefaultReporter]);
 
   if (!reporter) {
-    throw new BadOptionError(
+    throw BadOptionError.fromOption(
       'reporter',
       'No reporter found, please specify an existing reporter using the reporter option',
     );
@@ -39,6 +47,8 @@ export default async function newCommand(
 
   await reporter.onInit?.({ command: 'new', version, cwd, dry: false, directory });
 
+  const start = process.hrtime();
+
   let filename: string | undefined;
   let content: string | undefined;
 
@@ -82,7 +92,7 @@ export default async function newCommand(
   }
 
   if (!filename || content === undefined) {
-    throw new BadOptionError(
+    throw BadOptionError.fromOption(
       'plugin',
       'No generator plugin found, please specify a generator plugin using the plugin option',
     );
@@ -102,19 +112,31 @@ export default async function newCommand(
 
   await reporter.onNewMigration?.(migration, content);
 
-  let saveError: Error | undefined;
+  const finishedMigrations: MigrationMetadataFinished[] = [];
 
   try {
     await createDirectory(directoryPath);
     await saveFile(filePath, content);
+    const duration = getDuration(start);
+    finishedMigrations.push({ ...migration, status: 'done', duration });
   } catch (error) {
-    saveError = error instanceof Error ? error : new Error(String(error));
+    const duration = getDuration(start);
+    const errorInstance = toError(error);
+    finishedMigrations.push({ ...migration, status: 'failed', duration, error: errorInstance });
   }
 
-  await reporter.onFinished?.(
-    [{ ...migration, status: saveError ? 'failed' : 'done', error: saveError, duration: 0 }],
-    saveError,
-  );
+  // eslint-disable-next-line unicorn/no-array-callback-reference
+  const firstFailed = finishedMigrations.find(isFailedMigration);
+  const firstError =
+    firstFailed?.error instanceof EmigrateError
+      ? firstFailed.error
+      : firstFailed
+        ? new UnexpectedError(`Failed to create migration file: ${firstFailed.relativeFilePath}`, {
+            cause: firstFailed?.error,
+          })
+        : undefined;
+
+  await reporter.onFinished?.(finishedMigrations, firstError);
 }
 
 async function createDirectory(directoryPath: string) {

packages/cli/src/commands/remove.ts

@@ -1,6 +1,6 @@
 import process from 'node:process';
 import { getOrLoadReporter, getOrLoadStorage } from '@emigrate/plugin-tools';
-import { type MigrationHistoryEntry, type MigrationMetadataFinished } from '@emigrate/plugin-tools/types';
+import { type MigrationHistoryEntry, type MigrationMetadataFinished } from '@emigrate/types';
 import {
   BadOptionError,
   MigrationNotRunError,
@@ -26,24 +26,24 @@ export default async function removeCommand(
   name: string,
 ) {
   if (!directory) {
-    throw new MissingOptionError('directory');
+    throw MissingOptionError.fromOption('directory');
   }
 
   if (!name) {
-    throw new MissingArgumentsError('name');
+    throw MissingArgumentsError.fromArgument('name');
   }
 
   const cwd = process.cwd();
   const storagePlugin = await getOrLoadStorage([storageConfig]);
 
   if (!storagePlugin) {
-    throw new BadOptionError('storage', 'No storage found, please specify a storage using the storage option');
+    throw BadOptionError.fromOption('storage', 'No storage found, please specify a storage using the storage option');
   }
 
   const reporter = await getOrLoadReporter([reporterConfig ?? lazyDefaultReporter]);
 
   if (!reporter) {
-    throw new BadOptionError(
+    throw BadOptionError.fromOption(
       'reporter',
       'No reporter found, please specify an existing reporter using the reporter option',
     );
@@ -52,14 +52,22 @@ export default async function removeCommand(
   const [storage, storageError] = await exec(async () => storagePlugin.initializeStorage());
 
   if (storageError) {
-    await reporter.onFinished?.([], new StorageInitError('Could not initialize storage', { cause: storageError }));
+    await reporter.onFinished?.([], StorageInitError.fromError(storageError));
 
     return 1;
   }
 
   await reporter.onInit?.({ command: 'remove', version, cwd, dry: false, directory });
 
-  const migrationFile = await getMigration(cwd, directory, name, !force);
+  const [migrationFile, fileError] = await exec(async () => getMigration(cwd, directory, name, !force));
+
+  if (fileError) {
+    await reporter.onFinished?.([], fileError);
+
+    await storage.end();
+
+    return 1;
+  }
 
   const finishedMigrations: MigrationMetadataFinished[] = [];
   let historyEntry: MigrationHistoryEntry | undefined;
@@ -71,7 +79,7 @@ export default async function removeCommand(
     }
 
     if (migrationHistoryEntry.status === 'done' && !force) {
-      removalError = new OptionNeededError(
+      removalError = OptionNeededError.fromOption(
         'force',
         `The migration "${migrationFile.name}" is not in a failed state. Use the "force" option to force its removal`,
       );
@@ -98,10 +106,7 @@ export default async function removeCommand(
       removalError = error instanceof Error ? error : new Error(String(error));
     }
   } else if (!removalError) {
-    removalError = new MigrationNotRunError(
-      `Migration "${migrationFile.name}" is not in the migration history`,
-      migrationFile,
-    );
+    removalError = MigrationNotRunError.fromMetadata(migrationFile);
   }
 
   if (removalError) {

packages/cli/src/commands/up.test.ts

@@ -1,7 +1,6 @@
 import { describe, it, mock, type Mock } from 'node:test';
 import assert from 'node:assert';
 import path from 'node:path';
-import { serializeError } from '@emigrate/plugin-tools';
 import {
   type EmigrateReporter,
   type MigrationHistoryEntry,
@@ -9,7 +8,10 @@ import {
   type Storage,
   type Plugin,
   type SerializedError,
-} from '@emigrate/plugin-tools/types';
+  type FailedMigrationHistoryEntry,
+  type NonFailedMigrationHistoryEntry,
+} from '@emigrate/types';
+import { deserializeError } from 'serialize-error';
 import { version } from '../get-package-info.js';
 import upCommand from './up.js';
 
@@ -117,7 +119,10 @@ describe('up', () => {
     assert.strictEqual(reporter.onMigrationStart.mock.calls.length, 0);
     assert.strictEqual(reporter.onMigrationSuccess.mock.calls.length, 0);
     assert.strictEqual(reporter.onMigrationError.mock.calls.length, 1);
-    assert.strictEqual(getErrorCause(reporter.onMigrationError.mock.calls[0]?.arguments[1]), failedEntry.error);
+    assert.deepStrictEqual(
+      getErrorCause(reporter.onMigrationError.mock.calls[0]?.arguments[1]),
+      deserializeError(failedEntry.error),
+    );
     assert.strictEqual(reporter.onMigrationSkip.mock.calls.length, 1);
     assert.strictEqual(reporter.onFinished.mock.calls.length, 1);
     const [entries, error] = reporter.onFinished.mock.calls[0]?.arguments ?? [];
@@ -125,7 +130,7 @@ describe('up', () => {
       error?.message,
       `Migration ${failedEntry.name} is in a failed state, it should be fixed and removed`,
     );
-    assert.strictEqual(getErrorCause(error), failedEntry.error);
+    assert.deepStrictEqual(getErrorCause(error), deserializeError(failedEntry.error));
     assert.strictEqual(entries?.length, 2);
     assert.deepStrictEqual(
       entries.map((entry) => `${entry.name} (${entry.status})`),
@@ -155,7 +160,10 @@ describe('up', () => {
     assert.strictEqual(reporter.onMigrationStart.mock.calls.length, 0);
     assert.strictEqual(reporter.onMigrationSuccess.mock.calls.length, 0);
     assert.strictEqual(reporter.onMigrationError.mock.calls.length, 1);
-    assert.strictEqual(getErrorCause(reporter.onMigrationError.mock.calls[0]?.arguments[1]), failedEntry.error);
+    assert.deepStrictEqual(
+      getErrorCause(reporter.onMigrationError.mock.calls[0]?.arguments[1]),
+      deserializeError(failedEntry.error),
+    );
     assert.strictEqual(reporter.onMigrationSkip.mock.calls.length, 1);
     assert.strictEqual(reporter.onFinished.mock.calls.length, 1);
     const [entries, error] = reporter.onFinished.mock.calls[0]?.arguments ?? [];
@@ -163,7 +171,7 @@ describe('up', () => {
       error?.message,
       `Migration ${failedEntry.name} is in a failed state, it should be fixed and removed`,
     );
-    assert.strictEqual(getErrorCause(error), failedEntry.error);
+    assert.deepStrictEqual(getErrorCause(error), deserializeError(failedEntry.error));
     assert.strictEqual(entries?.length, 2);
     assert.deepStrictEqual(
       entries.map((entry) => `${entry.name} (${entry.status})`),
@@ -354,27 +362,38 @@ function toMigrations(cwd: string, directory: string, names: string[]): Migratio
   return names.map((name) => toMigration(cwd, directory, name));
 }
 
-function toEntry(
-  name: string | MigrationHistoryEntry,
-  status: MigrationHistoryEntry['status'] = 'done',
-): MigrationHistoryEntry {
-  if (typeof name === 'string') {
+function toEntry(name: MigrationHistoryEntry): MigrationHistoryEntry;
+function toEntry<S extends MigrationHistoryEntry['status']>(
+  name: string,
+  status?: S,
+): S extends 'failed' ? FailedMigrationHistoryEntry : NonFailedMigrationHistoryEntry;
+
+function toEntry(name: string | MigrationHistoryEntry, status?: 'done' | 'failed'): MigrationHistoryEntry {
+  if (typeof name !== 'string') {
+    return name.status === 'failed' ? name : name;
+  }
+
+  if (status === 'failed') {
     return {
       name,
       status,
       date: new Date(),
-      error: status === 'failed' ? serializeError(new Error('Failed')) : undefined,
+      error: { name: 'Error', message: 'Failed' },
     };
   }
 
-  return name;
+  return {
+    name,
+    status: status ?? 'done',
+    date: new Date(),
+  };
 }
 
 function toEntries(
   names: Array<string | MigrationHistoryEntry>,
-  status: MigrationHistoryEntry['status'] = 'done',
+  status?: MigrationHistoryEntry['status'],
 ): MigrationHistoryEntry[] {
-  return names.map((name) => toEntry(name, status));
+  return names.map((name) => (typeof name === 'string' ? toEntry(name, status) : name));
 }
 
 async function noop() {

packages/cli/src/commands/up.ts

@@ -1,7 +1,7 @@
 import process from 'node:process';
 import { getOrLoadPlugins, getOrLoadReporter, getOrLoadStorage } from '@emigrate/plugin-tools';
-import { isFinishedMigration, type LoaderPlugin } from '@emigrate/plugin-tools/types';
-import { BadOptionError, MigrationLoadError, MissingOptionError, StorageInitError } from '../errors.js';
+import { isFinishedMigration, type LoaderPlugin } from '@emigrate/types';
+import { BadOptionError, MigrationLoadError, MissingOptionError, StorageInitError, toError } from '../errors.js';
 import { type Config } from '../types.js';
 import { withLeadingPeriod } from '../with-leading-period.js';
 import { type GetMigrationsFunction } from '../get-migrations.js';
@@ -31,19 +31,19 @@ export default async function upCommand({
   getMigrations,
 }: Config & ExtraFlags): Promise<number> {
   if (!directory) {
-    throw new MissingOptionError('directory');
+    throw MissingOptionError.fromOption('directory');
   }
 
   const storagePlugin = await getOrLoadStorage([storageConfig]);
 
   if (!storagePlugin) {
-    throw new BadOptionError('storage', 'No storage found, please specify a storage using the storage option');
+    throw BadOptionError.fromOption('storage', 'No storage found, please specify a storage using the storage option');
   }
 
   const reporter = await getOrLoadReporter([reporterConfig ?? lazyDefaultReporter]);
 
   if (!reporter) {
-    throw new BadOptionError(
+    throw BadOptionError.fromOption(
       'reporter',
       'No reporter found, please specify an existing reporter using the reporter option',
     );
@@ -54,57 +54,66 @@ export default async function upCommand({
   const [storage, storageError] = await exec(async () => storagePlugin.initializeStorage());
 
   if (storageError) {
-    await reporter.onFinished?.([], new StorageInitError('Could not initialize storage', { cause: storageError }));
+    await reporter.onFinished?.([], StorageInitError.fromError(storageError));
 
     return 1;
   }
 
-  const collectedMigrations = filterAsync(
-    collectMigrations(cwd, directory, storage.getHistory(), getMigrations),
-    (migration) => !isFinishedMigration(migration) || migration.status === 'failed',
-  );
+  try {
+    const collectedMigrations = filterAsync(
+      collectMigrations(cwd, directory, storage.getHistory(), getMigrations),
+      (migration) => !isFinishedMigration(migration) || migration.status === 'failed',
+    );
 
-  const loaderPlugins = await getOrLoadPlugins('loader', [lazyPluginLoaderJs, ...plugins]);
+    const loaderPlugins = await getOrLoadPlugins('loader', [lazyPluginLoaderJs, ...plugins]);
 
-  const loaderByExtension = new Map<string, LoaderPlugin | undefined>();
+    const loaderByExtension = new Map<string, LoaderPlugin | undefined>();
 
-  const getLoaderByExtension = (extension: string) => {
-    if (!loaderByExtension.has(extension)) {
-      const loader = loaderPlugins.find((plugin) =>
-        plugin.loadableExtensions.some((loadableExtension) => withLeadingPeriod(loadableExtension) === extension),
-      );
+    const getLoaderByExtension = (extension: string) => {
+      if (!loaderByExtension.has(extension)) {
+        const loader = loaderPlugins.find((plugin) =>
+          plugin.loadableExtensions.some((loadableExtension) => withLeadingPeriod(loadableExtension) === extension),
+        );
 
-      loaderByExtension.set(extension, loader);
-    }
-
-    return loaderByExtension.get(extension);
-  };
-
-  const error = await migrationRunner({
-    dry,
-    reporter,
-    storage,
-    migrations: await arrayFromAsync(collectedMigrations),
-    async validate(migration) {
-      const loader = getLoaderByExtension(migration.extension);
-
-      if (!loader) {
-        throw new BadOptionError('plugin', `No loader plugin found for file extension: ${migration.extension}`);
-      }
-    },
-    async execute(migration) {
-      const loader = getLoaderByExtension(migration.extension)!;
-      const [migrationFunction, loadError] = await exec(async () => loader.loadMigration(migration));
-
-      if (loadError) {
-        throw new MigrationLoadError(`Failed to load migration file: ${migration.relativeFilePath}`, migration, {
-          cause: loadError,
-        });
+        loaderByExtension.set(extension, loader);
       }
 
-      await migrationFunction();
-    },
-  });
+      return loaderByExtension.get(extension);
+    };
 
-  return error ? 1 : 0;
+    const error = await migrationRunner({
+      dry,
+      reporter,
+      storage,
+      migrations: await arrayFromAsync(collectedMigrations),
+      async validate(migration) {
+        const loader = getLoaderByExtension(migration.extension);
+
+        if (!loader) {
+          throw BadOptionError.fromOption(
+            'plugin',
+            `No loader plugin found for file extension: ${migration.extension}`,
+          );
+        }
+      },
+      async execute(migration) {
+        const loader = getLoaderByExtension(migration.extension)!;
+        const [migrationFunction, loadError] = await exec(async () => loader.loadMigration(migration));
+
+        if (loadError) {
+          throw MigrationLoadError.fromMetadata(migration, loadError);
+        }
+
+        await migrationFunction();
+      },
+    });
+
+    return error ? 1 : 0;
+  } catch (error) {
+    await reporter.onFinished?.([], toError(error));
+
+    return 1;
+  } finally {
+    await storage.end();
+  }
 }