@dungarees/datasource 0.11.4

package/migration/inmemory-migrator.js

@@ -0,0 +1,126 @@
+import { getMigrationProvider } from './provider.js';
+import { NO_MIGRATIONS, } from 'kysely/migration';
+const byName = (a, b) => a.localeCompare(b, undefined, { numeric: true, sensitivity: 'base' });
+// The applied list is kept in memory because an in-process database has nowhere to persist
+// migration bookkeeping between instances.
+export const createInMemoryMigrator = ({ datasource, ...source }) => {
+    const provider = getMigrationProvider(source);
+    const applied = [];
+    // Per migrator rather than module wide, so two migrators in one test file cannot hand out
+    // interleaved timestamps. Only the ordering matters, never the actual instant.
+    let executionCounter = 0;
+    const getSortedMigrations = async () => Object.entries(await provider.getMigrations())
+        .map(([name, migration]) => ({ ...migration, name }))
+        .sort((a, b) => byName(a.name, b.name));
+    const runMigration = async ({ migration, direction, isSkipped, }) => {
+        if (isSkipped) {
+            return { migrationName: migration.name, direction, error: undefined, isSkipped };
+        }
+        try {
+            if (direction === 'Up') {
+                await migration.up(datasource);
+                applied.push({ name: migration.name, executedAt: new Date(executionCounter++) });
+            }
+            else {
+                await migration.down?.(datasource);
+                applied.pop();
+            }
+            return { migrationName: migration.name, direction, error: undefined, isSkipped };
+        }
+        catch (error) {
+            return { migrationName: migration.name, direction, error, isSkipped };
+        }
+    };
+    // Sequential on purpose: a migration may depend on the one before it, so running the steps
+    // concurrently would apply them in an order the author never wrote.
+    const runSteps = async (steps) => {
+        const outcomes = [];
+        for (const step of steps) {
+            outcomes.push(await runMigration(step));
+        }
+        return toResultSet(outcomes);
+    };
+    const toResultSet = (outcomes) => ({
+        error: outcomes.find(({ error }) => error !== undefined)?.error,
+        results: outcomes
+            .slice()
+            .sort((a, b) => byName(a.migrationName, b.migrationName))
+            .map(({ migrationName, direction, error, isSkipped }) => ({
+            migrationName,
+            status: getStatus({ isSkipped, error }),
+            direction,
+        })),
+    });
+    const getStatus = ({ isSkipped, error, }) => {
+        if (isSkipped) {
+            return 'NotExecuted';
+        }
+        return error !== undefined ? 'Error' : 'Success';
+    };
+    const isNoMigrations = (target) => target === NO_MIGRATIONS || typeof target !== 'string';
+    return {
+        migrateToLatest: async () => {
+            const migrations = await getSortedMigrations();
+            return await runSteps(migrations
+                .slice(applied.length)
+                .map((migration) => ({ migration, direction: 'Up', isSkipped: false })));
+        },
+        migrateUp: async () => {
+            const migrations = await getSortedMigrations();
+            const next = migrations[applied.length];
+            return next === undefined
+                ? { error: undefined, results: [] }
+                : await runSteps([{ migration: next, direction: 'Up', isSkipped: false }]);
+        },
+        migrateDown: async () => {
+            const migrations = await getSortedMigrations();
+            const last = migrations[applied.length - 1];
+            return last === undefined
+                ? { error: undefined, results: [] }
+                : await runSteps([{ migration: last, direction: 'Down', isSkipped: false }]);
+        },
+        migrateTo: async (target) => {
+            const migrations = await getSortedMigrations();
+            // NO_MIGRATIONS has no index of its own, and -1 makes every applied migration fall into the
+            // "after the target" slice below, which is exactly migrating back to empty.
+            const targetIndex = isNoMigrations(target)
+                ? -1
+                : migrations.findIndex(({ name }) => name === target);
+            if (targetIndex === -1 && !isNoMigrations(target)) {
+                throw new Error(`Migration ${typeof target === 'string' ? target : 'NO_MIGRATIONS'} not found`);
+            }
+            const currentIndex = applied.length;
+            const direction = currentIndex < targetIndex ? 'Up' : 'Down';
+            const toRun = direction === 'Up'
+                ? migrations.slice(currentIndex, targetIndex + 1)
+                : migrations.slice(targetIndex + 1, currentIndex).reverse();
+            const runSet = new Set(toRun);
+            return await runSteps([
+                ...toRun.map((migration) => ({ migration, direction, isSkipped: false })),
+                ...migrations
+                    .filter((migration) => !runSet.has(migration))
+                    .map((migration) => ({ migration, direction, isSkipped: true })),
+            ]);
+        },
+        getMigrations: async () => {
+            const migrations = await getSortedMigrations();
+            return migrations.map((named) => {
+                const executed = applied.find((entry) => entry.name === named.name);
+                return {
+                    name: named.name,
+                    ...(executed !== undefined && { executedAt: executed.executedAt }),
+                    // Wrapped rather than handed over directly, so `up` and `down` stay attached to the
+                    // migration they came from instead of being called detached from it.
+                    migration: {
+                        up: async (db) => {
+                            await named.up(db);
+                        },
+                        down: async (db) => {
+                            await named.down?.(db);
+                        },
+                    },
+                };
+            });
+        },
+    };
+};

package/migration/kysely-migrator.d.ts

@@ -0,0 +1,2 @@
+import type { MigrationRunner, MigratorConfig } from './type.ts';
+export declare const createKyselyMigrator: ({ datasource, ...source }: MigratorConfig) => MigrationRunner;

package/migration/kysely-migrator.js

@@ -0,0 +1,6 @@
+import { getMigrationProvider } from './provider.js';
+import { Migrator as KyselyMigrator } from 'kysely/migration';
+export const createKyselyMigrator = ({ datasource, ...source }) => new KyselyMigrator({
+    db: datasource,
+    provider: getMigrationProvider(source),
+});

package/migration/migration.d.ts

@@ -0,0 +1,4 @@
+import type { IgnoreForTests, MigrationScripts } from './type.ts';
+import type { Migration } from 'kysely/migration';
+export declare const createMigration: ({ up, down }: MigrationScripts) => Migration;
+export declare const ignoreForTests: IgnoreForTests;

package/migration/migration.js

@@ -0,0 +1,5 @@
+export const createMigration = ({ up, down }) => ({ up, down });
+// Set by the test environment so a migration that would be slow or destructive against a fixture
+// can be skipped, while still running for real against a real database.
+const TEST_ENV_VAR = 'TEST';
+export const ignoreForTests = async (action, fallbackValue) => (process.env[TEST_ENV_VAR] !== 'true' ? await action() : fallbackValue);

package/migration/provider.d.ts

@@ -0,0 +1,5 @@
+import type { MigrationSource } from './type.ts';
+import type { Migration, MigrationProvider } from 'kysely/migration';
+export declare const createRecordMigrationProvider: (migrations: Record<string, Migration>) => MigrationProvider;
+export declare const createFolderMigrationProvider: (migrationsFolder: string) => MigrationProvider;
+export declare const getMigrationProvider: (source: MigrationSource) => MigrationProvider;

package/migration/provider.js

@@ -0,0 +1,39 @@
+import { readdir } from 'node:fs/promises';
+import { basename, extname, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+const MIGRATION_EXTENSIONS = ['.ts', '.js', '.mjs'];
+export const createRecordMigrationProvider = (migrations) => ({
+    getMigrations: async () => await Promise.resolve(migrations),
+});
+// Imported by file url rather than by path: a bare path is resolved relative to this module, and a
+// Windows path is not a valid module specifier at all.
+export const createFolderMigrationProvider = (migrationsFolder) => ({
+    getMigrations: async () => {
+        const files = await readdir(migrationsFolder);
+        const migrationFiles = files
+            .filter((name) => MIGRATION_EXTENSIONS.includes(extname(name)) && !name.endsWith('.d.ts'))
+            .sort();
+        return Object.fromEntries(await Promise.all(migrationFiles.map(async (fileName) => [
+            basename(fileName, extname(fileName)),
+            await importMigration(join(migrationsFolder, fileName)),
+        ])));
+    },
+});
+const importMigration = async (filePath) => {
+    const imported = await import(pathToFileURL(filePath).href);
+    // A migration module may default-export the migration or be the migration itself.
+    const migration = typeof imported === 'object' && imported !== null && 'default' in imported
+        ? Reflect.get(imported, 'default')
+        : imported;
+    if (!isMigration(migration)) {
+        throw new Error(`${filePath} does not export a migration with an up function`);
+    }
+    return migration;
+};
+const isMigration = (value) => typeof value === 'object' &&
+    value !== null &&
+    'up' in value &&
+    typeof Reflect.get(value, 'up') === 'function';
+export const getMigrationProvider = (source) => 'migrations' in source
+    ? createRecordMigrationProvider(source.migrations)
+    : createFolderMigrationProvider(source.migrationsFolder);

package/migration/service.d.ts

@@ -0,0 +1,2 @@
+import type { MigrationRunner, Migrator } from './type.ts';
+export declare const createMigrator: (runner: MigrationRunner) => Migrator;

package/migration/service.js

@@ -0,0 +1,24 @@
+import { NO_MIGRATIONS } from 'kysely/migration';
+export const createMigrator = (runner) => ({
+    migrateToLatest: async () => toResultList(await runner.migrateToLatest()),
+    migrateToEmpty: async () => toResultList(await runner.migrateTo(NO_MIGRATIONS)),
+    migrateTo: async (migrationName) => toResultList(await runner.migrateTo(migrationName)),
+    migrateUpStep: async () => toResultList(await runner.migrateUp()),
+    migrateDownStep: async () => toResultList(await runner.migrateDown()),
+    getMigrations: async () => (await runner.getMigrations()).map(toMigrationDetails),
+});
+// kysely types the failure as unknown, because a migration can throw anything at all.
+const toError = (error) => {
+    if (error === undefined) {
+        return undefined;
+    }
+    return error instanceof Error ? error : new Error(JSON.stringify(error));
+};
+const toResultList = ({ error, results }) => ({
+    error: toError(error),
+    results: results ?? [],
+});
+const toMigrationDetails = ({ name, executedAt }) => ({
+    name,
+    executedAt,
+});

package/migration/type.d.ts

@@ -0,0 +1,48 @@
+import type { AnySchema, Datasource } from '../type.ts';
+import type { Migration, MigrationInfo, MigrationResultSet, NoMigrations } from 'kysely/migration';
+export type MigrationScripts = {
+    up: (db: Datasource<AnySchema>) => Promise<void>;
+    down: (db: Datasource<AnySchema>) => Promise<void>;
+};
+export type MigrationSource = {
+    migrationsFolder: string;
+} | {
+    migrations: Record<string, Migration>;
+};
+export type MigratorConfig = {
+    datasource: Datasource<AnySchema>;
+} & MigrationSource;
+export type MigrationRunner = {
+    migrateToLatest: () => Promise<MigrationResultSet>;
+    migrateTo: (target: string | NoMigrations) => Promise<MigrationResultSet>;
+    migrateUp: () => Promise<MigrationResultSet>;
+    migrateDown: () => Promise<MigrationResultSet>;
+    getMigrations: () => Promise<ReadonlyArray<MigrationInfo>>;
+};
+export type Migrator = {
+    migrateUpStep: () => Promise<MigrationResultList>;
+    migrateDownStep: () => Promise<MigrationResultList>;
+    migrateTo: (migrationName: string) => Promise<MigrationResultList>;
+    migrateToLatest: () => Promise<MigrationResultList>;
+    migrateToEmpty: () => Promise<MigrationResultList>;
+    getMigrations: () => Promise<MigrationDetails[]>;
+};
+export type MigrationDetails = {
+    name: string;
+    executedAt: Date | undefined;
+};
+export type MigrationDirection = 'Up' | 'Down';
+export type MigrationStatus = 'Success' | 'Error' | 'NotExecuted';
+export type MigrationResult = {
+    migrationName: string;
+    status: MigrationStatus;
+    direction: MigrationDirection;
+};
+export type MigrationResultList = {
+    error: Error | undefined;
+    results: MigrationResult[];
+};
+export type IgnoreForTests = {
+    <T>(action: () => Promise<T>): Promise<T | undefined>;
+    <T>(action: () => Promise<T>, fallbackValue: T): Promise<T>;
+};

package/migration/type.js

@@ -0,0 +1 @@
+export {};