@coffre/db 0.1.1 → 0.1.3

package/dist/log.d.ts

@@ -68,5 +68,11 @@ export declare function lockLogHead(tx: Transaction): Promise<{
   nextSeq: bigint;
   headHash: Buffer;
 }>;
-export declare function appendEntries(tx: Transaction, key: LogKey, entries: readonly NewEntry[]): Promise<Appended>;
+/**
+ * Append `entries` under `key`. `check`, when given, runs once the head is
+ * locked and before anything is written: a writer's own condition on the
+ * log as it stands, which no other append can change until this one
+ * commits. It throws to refuse.
+ */
+export declare function appendEntries(tx: Transaction, key: LogKey, entries: readonly NewEntry[], check?: (tx: Transaction) => Promise<void>): Promise<Appended>;
 //#endregion

package/dist/log.js

@@ -60,10 +60,17 @@ async function lockLogHead(tx) {
 	if (head === void 0) throw new Error("audit_chain_head is missing; refusing to write an unchained entry");
 	return head;
 }
-async function appendEntries(tx, key, entries) {
+/**
+* Append `entries` under `key`. `check`, when given, runs once the head is
+* locked and before anything is written: a writer's own condition on the
+* log as it stands, which no other append can change until this one
+* commits. It throws to refuse.
+*/
+async function appendEntries(tx, key, entries, check) {
 	if (entries.length === 0) throw new Error("appendEntries called with no entries");
 	const { auditChainHead, auditLog } = tablesOf(tx);
 	const head = await lockLogHead(tx);
+	await check?.(tx);
 	const [{ now }] = await tx.select({ now: clockMillis(tx) }).from(auditChainHead);
 	const [last] = await tx.select({
 		seq: auditLog.seq,

package/dist/migrate.d.ts

@@ -5,6 +5,15 @@ import { Engine } from "./dialect.js";
  * in the built package, where the build copies them.
  */
 export declare function migrationsFolder(engine: Engine): string;
-/** Apply missing migrations, check their history and reassert database privileges. */
-export declare function migrateDatabase(url: string): Promise<void>;
+/** 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;
+};
+/**
+ * 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.
+ */
+export declare function migrateDatabase(url: string, onPlan?: (plan: MigrationPlan) => void): Promise<void>;
 //#endregion

package/dist/migrate.js

@@ -102,8 +102,12 @@ async function sqliteMigrator(url) {
 		close
 	};
 }
-/** Apply missing migrations, check their history and reassert database privileges. */
-async function migrateDatabase(url) {
+/**
+* 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.
+*/
+async function migrateDatabase(url, onPlan) {
 	const engine = engineOfUrl(url);
 	const expected = await expectedMigrations(engine);
 	const migrator = await {
@@ -114,7 +118,12 @@ async function migrateDatabase(url) {
 	try {
 		await migrator.lock();
 		locked = true;
-		verifyHistory(expected, await migrator.applied(), false);
+		const applied = await migrator.applied();
+		verifyHistory(expected, applied, false);
+		onPlan?.({
+			applied: applied?.length ?? 0,
+			total: expected.length
+		});
 		await migrator.migrate(migrationsFolder(engine));
 		verifyHistory(expected, await migrator.applied(), true);
 		await migrator.restrict();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coffre/db",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "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.1"
+    "@coffre/core": "0.1.3"
   },
   "devDependencies": {
     "@types/node": "26.1.1",

package/src/log.ts

@@ -111,12 +111,24 @@ export async function lockLogHead(tx: Transaction): Promise<{ nextSeq: bigint; h
   return head;
 }
 
-export async function appendEntries(tx: Transaction, key: LogKey, entries: readonly NewEntry[]): Promise<Appended> {
+/**
+ * Append `entries` under `key`. `check`, when given, runs once the head is
+ * locked and before anything is written: a writer's own condition on the
+ * log as it stands, which no other append can change until this one
+ * commits. It throws to refuse.
+ */
+export async function appendEntries(
+  tx: Transaction,
+  key: LogKey,
+  entries: readonly NewEntry[],
+  check?: (tx: Transaction) => Promise<void>,
+): Promise<Appended> {
   if (entries.length === 0) throw new Error('appendEntries called with no entries');
   const { auditChainHead, auditLog } = tablesOf(tx);
 
   // Every append queues here, if its transaction has not already.
   const head = await lockLogHead(tx);
+  await check?.(tx);
   const [{ now }] = await tx.select({ now: clockMillis(tx) }).from(auditChainHead);
   const [last] = await tx
     .select({ seq: auditLog.seq, hash: auditLog.hash })

package/src/migrate.ts

@@ -182,8 +182,15 @@ async function sqliteMigrator(url: string): Promise<Migrator> {
   };
 }
 
-/** Apply missing migrations, check their history and reassert database privileges. */
-export async function migrateDatabase(url: string): Promise<void> {
+/** 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 };
+
+/**
+ * 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.
+ */
+export async function migrateDatabase(url: string, onPlan?: (plan: MigrationPlan) => void): Promise<void> {
   const engine = engineOfUrl(url);
   const expected = await expectedMigrations(engine);
   const migrator = await { postgres: postgresMigrator, sqlite: sqliteMigrator }[engine](url);
@@ -193,7 +200,9 @@ export async function migrateDatabase(url: string): Promise<void> {
     await migrator.lock();
     locked = true;
 
-    verifyHistory(expected, await migrator.applied(), false);
+    const applied = await migrator.applied();
+    verifyHistory(expected, applied, false);
+    onPlan?.({ applied: applied?.length ?? 0, total: expected.length });
     await migrator.migrate(migrationsFolder(engine));
     verifyHistory(expected, await migrator.applied(), true);
     await migrator.restrict();