@coffre/db 0.1.13 → 0.1.14

package/dist/migrate.d.ts

@@ -8,15 +8,30 @@ export declare function restrictDatabase(client: Pick<PoolClient, 'query'>): Pro
  * in the built package, where the build copies them.
  */
 export declare function migrationsFolder(engine: Engine): string;
-/** A migration run's plan: `applied` of the `total` migrations there before it, the rest applied by it. */
+/**
+ * A migration run's plan: `applied` of the `total` migrations there before
+ * it, and the tags of the rest, which it applies.
+ */
 export type MigrationPlan = {
   applied: number;
   total: number;
+  pending: string[];
 };
+/**
+ * Which of this version's migrations a database has applied, and which it
+ * has not, without changing it or waiting on a migration under way. A
+ * history that is not a prefix of this version's is refused, as
+ * `migrateDatabase` refuses it.
+ */
+export declare function migrationStatus(url: string): Promise<{
+  applied: string[];
+  pending: string[];
+}>;
 /**
  * Apply missing migrations, check their history and reassert database
- * privileges. `onPlan` hears how many there are to apply before they are:
- * all of them go in one call, with no word of each.
+ * privileges. `onPlan` hears what there is to apply before it is, under
+ * the migration lock, and may stop the run by throwing: all of it then goes
+ * in one call, with no word of each.
  */
-export declare function migrateDatabase(url: string, onPlan?: (plan: MigrationPlan) => void): Promise<void>;
+export declare function migrateDatabase(url: string, onPlan?: (plan: MigrationPlan) => void | Promise<void>): Promise<void>;
 //#endregion

package/dist/migrate.js

@@ -105,9 +105,35 @@ async function sqliteMigrator(url) {
 	};
 }
 /**
+* Which of this version's migrations a database has applied, and which it
+* has not, without changing it or waiting on a migration under way. A
+* history that is not a prefix of this version's is refused, as
+* `migrateDatabase` refuses it.
+*/
+async function migrationStatus(url) {
+	const engine = engineOfUrl(url);
+	const expected = await expectedMigrations(engine);
+	const migrator = await {
+		postgres: postgresMigrator,
+		sqlite: sqliteMigrator
+	}[engine](url);
+	try {
+		const history = await migrator.applied();
+		verifyHistory(expected, history, false);
+		const applied = history?.length ?? 0;
+		return {
+			applied: expected.slice(0, applied).map((entry) => entry.tag),
+			pending: expected.slice(applied).map((entry) => entry.tag)
+		};
+	} finally {
+		await migrator.close();
+	}
+}
+/**
 * Apply missing migrations, check their history and reassert database
-* privileges. `onPlan` hears how many there are to apply before they are:
-* all of them go in one call, with no word of each.
+* privileges. `onPlan` hears what there is to apply before it is, under
+* the migration lock, and may stop the run by throwing: all of it then goes
+* in one call, with no word of each.
 */
 async function migrateDatabase(url, onPlan) {
 	const engine = engineOfUrl(url);
@@ -122,9 +148,11 @@ async function migrateDatabase(url, onPlan) {
 		locked = true;
 		const applied = await migrator.applied();
 		verifyHistory(expected, applied, false);
-		onPlan?.({
-			applied: applied?.length ?? 0,
-			total: expected.length
+		const done = applied?.length ?? 0;
+		await onPlan?.({
+			applied: done,
+			total: expected.length,
+			pending: expected.slice(done).map((entry) => entry.tag)
 		});
 		await migrator.migrate(migrationsFolder(engine));
 		verifyHistory(expected, await migrator.applied(), true);
@@ -138,4 +166,4 @@ async function migrateDatabase(url, onPlan) {
 	}
 }
 //#endregion
-export { migrateDatabase, migrationsFolder, restrictDatabase };
+export { migrateDatabase, migrationStatus, migrationsFolder, restrictDatabase };

package/dist/schema-version.d.ts

@@ -10,4 +10,12 @@ import { Engine } from "./dialect.js";
  */
 export declare const REQUIRED_MIGRATIONS: Record<Engine, number>;
 export declare function requiredMigrations(db: Queryable): number;
+/**
+ * Every migration this version ships, oldest first, per engine: read from
+ * the journals at build time, so a Worker, which has no files, knows them
+ * too. A database that has applied fewer is behind this code, whatever
+ * `REQUIRED_MIGRATIONS` lets it run on.
+ */
+export declare const KNOWN_MIGRATIONS: Record<Engine, readonly string[]>;
+export declare function knownMigrations(db: Queryable): readonly string[];
 //#endregion

package/dist/schema-version.js

@@ -1,4 +1,34 @@
 import { engineOf } from "./dialect.js";
+//#region src/migrations/postgres/meta/_journal.json
+var entries$1 = [{
+	"idx": 0,
+	"version": "7",
+	"when": 1790930587507,
+	"tag": "0000_baseline",
+	"breakpoints": true
+}, {
+	"idx": 1,
+	"version": "7",
+	"when": 1791062292678,
+	"tag": "0001_remove_syncs",
+	"breakpoints": true
+}];
+//#endregion
+//#region src/migrations/sqlite/meta/_journal.json
+var entries = [{
+	"idx": 0,
+	"version": "6",
+	"when": 1790874462505,
+	"tag": "0000_baseline",
+	"breakpoints": true
+}, {
+	"idx": 1,
+	"version": "6",
+	"when": 1791062293531,
+	"tag": "0001_remove_syncs",
+	"breakpoints": true
+}];
+//#endregion
 //#region src/schema-version.ts
 /**
 * Minimum migration prefix required by this application image, per engine:
@@ -14,5 +44,18 @@ const REQUIRED_MIGRATIONS = {
 function requiredMigrations(db) {
 	return REQUIRED_MIGRATIONS[engineOf(db)];
 }
+/**
+* Every migration this version ships, oldest first, per engine: read from
+* the journals at build time, so a Worker, which has no files, knows them
+* too. A database that has applied fewer is behind this code, whatever
+* `REQUIRED_MIGRATIONS` lets it run on.
+*/
+const KNOWN_MIGRATIONS = {
+	postgres: entries$1.map((entry) => entry.tag),
+	sqlite: entries.map((entry) => entry.tag)
+};
+function knownMigrations(db) {
+	return KNOWN_MIGRATIONS[engineOf(db)];
+}
 //#endregion
-export { REQUIRED_MIGRATIONS, requiredMigrations };
+export { KNOWN_MIGRATIONS, REQUIRED_MIGRATIONS, knownMigrations, requiredMigrations };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coffre/db",
-  "version": "0.1.13",
+  "version": "0.1.14",
   "description": "coffre's database: the schema, its migrations and the connections, on Postgres or SQLite.",
   "license": "MIT",
   "repository": {
@@ -74,7 +74,7 @@
     "drizzle-orm": "0.45.2",
     "pg": "8.16.3",
     "pg-connection-string": "2.14.0",
-    "@coffre/core": "0.1.13"
+    "@coffre/core": "0.1.14"
   },
   "devDependencies": {
     "@types/node": "26.1.1",

package/src/migrate.ts

@@ -185,15 +185,45 @@ async function sqliteMigrator(url: string): Promise<Migrator> {
   };
 }
 
-/** A migration run's plan: `applied` of the `total` migrations there before it, the rest applied by it. */
-export type MigrationPlan = { applied: number; total: number };
+/**
+ * A migration run's plan: `applied` of the `total` migrations there before
+ * it, and the tags of the rest, which it applies.
+ */
+export type MigrationPlan = { applied: number; total: number; pending: string[] };
+
+/**
+ * Which of this version's migrations a database has applied, and which it
+ * has not, without changing it or waiting on a migration under way. A
+ * history that is not a prefix of this version's is refused, as
+ * `migrateDatabase` refuses it.
+ */
+export async function migrationStatus(url: string): Promise<{ applied: string[]; pending: string[] }> {
+  const engine = engineOfUrl(url);
+  const expected = await expectedMigrations(engine);
+  const migrator = await { postgres: postgresMigrator, sqlite: sqliteMigrator }[engine](url);
+  try {
+    const history = await migrator.applied();
+    verifyHistory(expected, history, false);
+    const applied = history?.length ?? 0;
+    return {
+      applied: expected.slice(0, applied).map((entry) => entry.tag),
+      pending: expected.slice(applied).map((entry) => entry.tag),
+    };
+  } finally {
+    await migrator.close();
+  }
+}
 
 /**
  * Apply missing migrations, check their history and reassert database
- * privileges. `onPlan` hears how many there are to apply before they are:
- * all of them go in one call, with no word of each.
+ * privileges. `onPlan` hears what there is to apply before it is, under
+ * the migration lock, and may stop the run by throwing: all of it then goes
+ * in one call, with no word of each.
  */
-export async function migrateDatabase(url: string, onPlan?: (plan: MigrationPlan) => void): Promise<void> {
+export async function migrateDatabase(
+  url: string,
+  onPlan?: (plan: MigrationPlan) => void | Promise<void>,
+): Promise<void> {
   const engine = engineOfUrl(url);
   const expected = await expectedMigrations(engine);
   const migrator = await { postgres: postgresMigrator, sqlite: sqliteMigrator }[engine](url);
@@ -205,7 +235,8 @@ export async function migrateDatabase(url: string, onPlan?: (plan: MigrationPlan
 
     const applied = await migrator.applied();
     verifyHistory(expected, applied, false);
-    onPlan?.({ applied: applied?.length ?? 0, total: expected.length });
+    const done = applied?.length ?? 0;
+    await onPlan?.({ applied: done, total: expected.length, pending: expected.slice(done).map((entry) => entry.tag) });
     await migrator.migrate(migrationsFolder(engine));
     verifyHistory(expected, await migrator.applied(), true);
     await migrator.restrict();

package/src/schema-version.ts

@@ -1,5 +1,7 @@
 import type { Queryable } from './database.ts';
 import { engineOf, type Engine } from './dialect.ts';
+import postgresJournal from './migrations/postgres/meta/_journal.json' with { type: 'json' };
+import sqliteJournal from './migrations/sqlite/meta/_journal.json' with { type: 'json' };
 
 /**
  * Minimum migration prefix required by this application image, per engine:
@@ -13,3 +15,18 @@ export const REQUIRED_MIGRATIONS: Record<Engine, number> = { postgres: 1, sqlite
 export function requiredMigrations(db: Queryable): number {
   return REQUIRED_MIGRATIONS[engineOf(db)];
 }
+
+/**
+ * Every migration this version ships, oldest first, per engine: read from
+ * the journals at build time, so a Worker, which has no files, knows them
+ * too. A database that has applied fewer is behind this code, whatever
+ * `REQUIRED_MIGRATIONS` lets it run on.
+ */
+export const KNOWN_MIGRATIONS: Record<Engine, readonly string[]> = {
+  postgres: postgresJournal.entries.map((entry) => entry.tag),
+  sqlite: sqliteJournal.entries.map((entry) => entry.tag),
+};
+
+export function knownMigrations(db: Queryable): readonly string[] {
+  return KNOWN_MIGRATIONS[engineOf(db)];
+}