@ultimat3/testing 27.11.0 → 27.12.0

package/README.md

@@ -305,9 +305,15 @@ its own, so one shared store is enough.
 ## Parallel databases
 
 ```ts
-const db = await acquireWorkerDatabase({ adminUrl, migrate });
+import { acquireWorkerDatabase } from '@ultimat3/testing';
+
+// `migrate: (url) => …` applies the app's schema into the template once; omitted here.
+await using db = await acquireWorkerDatabase({ adminUrl: Bun.env['TEST_DATABASE_URL'] });
 ```
 
+The handle is async-disposable (`As of 2026-10-18`): `await using` drops the worker's database when
+the scope ends, a failed test included; `db.drop()` is the same call spelled by hand.
+
 The first worker creates the template under a Postgres advisory lock and migrates it; every
 worker then clones it copy-on-write, under the same lock — a clone waits only 5 s for a session on
 the template to leave, and the next worker's migration holds one. With no Postgres configured it falls back to PGlite, so

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/testing",
-  "version": "27.11.0",
+  "version": "27.12.0",
   "description": "Test harness: cloned template DBs per worker, frozen clock, sealed network, 6 test types",
   "license": "MIT",
   "type": "module",
@@ -36,20 +36,20 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/action": "27.11.0",
-    "@ultimat3/cache": "27.11.0",
-    "@ultimat3/core": "27.11.0",
-    "@ultimat3/db": "27.11.0",
-    "@ultimat3/entity": "27.11.0",
-    "@ultimat3/http": "27.11.0",
-    "@ultimat3/i18n": "27.11.0",
-    "@ultimat3/jobs": "27.11.0",
-    "@ultimat3/mail": "27.11.0",
-    "@ultimat3/policy": "27.11.0",
-    "@ultimat3/pwa": "27.11.0",
-    "@ultimat3/query": "27.11.0",
-    "@ultimat3/realtime": "27.11.0",
-    "@ultimat3/render": "27.11.0",
-    "@ultimat3/time": "27.11.0"
+    "@ultimat3/action": "27.12.0",
+    "@ultimat3/cache": "27.12.0",
+    "@ultimat3/core": "27.12.0",
+    "@ultimat3/db": "27.12.0",
+    "@ultimat3/entity": "27.12.0",
+    "@ultimat3/http": "27.12.0",
+    "@ultimat3/i18n": "27.12.0",
+    "@ultimat3/jobs": "27.12.0",
+    "@ultimat3/mail": "27.12.0",
+    "@ultimat3/policy": "27.12.0",
+    "@ultimat3/pwa": "27.12.0",
+    "@ultimat3/query": "27.12.0",
+    "@ultimat3/realtime": "27.12.0",
+    "@ultimat3/render": "27.12.0",
+    "@ultimat3/time": "27.12.0"
   }
 }

package/src/index.ts

@@ -340,7 +340,12 @@ export {
 } from './sealed-network';
 export type { SharedExamples } from './shared-examples';
 export { behavesLike, sharedExamples } from './shared-examples';
-export type { SqlRunner, TemplateDbConfig, WorkerDatabase } from './template-db';
+export type {
+  DisposableWorkerDatabase,
+  SqlRunner,
+  TemplateDbConfig,
+  WorkerDatabase,
+} from './template-db';
 export {
   acquireWorkerDatabase,
   cloneSql,

package/src/template-db.ts

@@ -30,6 +30,13 @@ export interface WorkerDatabase {
   drop(): Promise<void>;
 }
 
+/**
+ * What `acquireWorkerDatabase` answers: the handle plus `drop()` as its async disposer, so
+ * `await using db = await acquireWorkerDatabase()` releases it however the scope exits. A separate
+ * type so a hand-built `WorkerDatabase` (a fake `acquire`) owes no disposer.
+ */
+export type DisposableWorkerDatabase = WorkerDatabase & AsyncDisposable;
+
 export const DEFAULT_TEMPLATE = 'ultimate_test_template';
 
 /**
@@ -109,7 +116,7 @@ const defaultConnect = (url: string): SqlRunner => {
 export async function acquireWorkerDatabase(
   config: TemplateDbConfig = {},
   deps: Partial<TemplateDbDeps> = {},
-): Promise<WorkerDatabase> {
+): Promise<DisposableWorkerDatabase> {
   const env = deps.env ?? (Bun.env as Readonly<Record<string, string | undefined>>);
   const connect = deps.connect ?? defaultConnect;
   const template = config.templateName ?? DEFAULT_TEMPLATE;
@@ -118,13 +125,13 @@ export async function acquireWorkerDatabase(
   const adminUrl = config.adminUrl ?? env['TEST_DATABASE_URL'] ?? env['DATABASE_URL'];
 
   if (adminUrl === undefined || adminUrl.length === 0) {
-    return {
+    return disposable({
       kind: 'pglite',
       worker,
       database,
       url: `pglite://memory/${database}`,
       drop: async () => undefined,
-    };
+    });
   }
 
   const admin = connect(adminUrl);
@@ -160,7 +167,7 @@ export async function acquireWorkerDatabase(
   }
   await admin.close();
 
-  return {
+  return disposable({
     kind: 'postgres',
     worker,
     database,
@@ -170,7 +177,12 @@ export async function acquireWorkerDatabase(
       await cleanup.exec(dropSql(database));
       await cleanup.close();
     },
-  };
+  });
+}
+
+/** The handle with its `drop` as the async disposer, so `await using` is the one release spelling. */
+function disposable(db: WorkerDatabase): DisposableWorkerDatabase {
+  return { ...db, [Symbol.asyncDispose]: () => db.drop() };
 }
 
 /**