kern-db 0.4.0 → 0.5.0

package/dist/builder.d.mts

@@ -1,4 +1,4 @@
-import { B as takeOnlyRow, C as renderFragment, D as bindParameter, E as assertUntypedValue, H as toValueRows, L as createFieldDecodeError, O as encodeParameter, P as ResultMode, R as createResultDecodeError, V as toMissingResult, a as SqlQuery, c as StatementSource, l as startSqlQuery, v as ParameterBinder, y as SqlFragment, z as isRecordKey } from "./query-Dxiy1HJD.mjs";
+import { B as takeOnlyRow, C as renderFragment, D as bindParameter, E as assertUntypedValue, H as toValueRows, L as createFieldDecodeError, O as encodeParameter, P as ResultMode, R as createResultDecodeError, V as toMissingResult, a as SqlQuery, c as StatementSource, l as startSqlQuery, v as ParameterBinder, y as SqlFragment, z as isRecordKey } from "./query-DpxSVheu.mjs";
 /** Quotes `name` as a PostgreSQL identifier, which keeps its case and any characters in it. */
 export declare function quoteIdentifier(name: string): string;
 export { type ParameterBinder, type ResultMode, SqlFragment, SqlQuery, type StatementSource, assertUntypedValue, bindParameter, createFieldDecodeError, createResultDecodeError, encodeParameter, isRecordKey, renderFragment, startSqlQuery, takeOnlyRow, toMissingResult, toValueRows };

package/dist/{database-D4ql2RZ0.mjs → database-C3LR3pFV.mjs}

@@ -3,88 +3,6 @@ import { S as createStatement, _ as sql, f as compileFragment, n as startSqlQuer
 import { i as setBrand, n as QueryError, r as isInstance, t as ConnectionError } from "./driver-error-D8D4UQ4F.mjs";
 import { n as formatArray } from "./array-BLt8ZNR5.mjs";
 import { AsyncLocalStorage } from "node:async_hooks";
-// src/transaction/release.ts
-/**
-* Returns a connection to the driver and passes a failed release to `onReleaseError`, or to `console.error` without one.
-*
-* The result or error of the transaction is decided before its release, so a failed release must not change it: a committed transaction that rejected would be retried.
-* Reporting the failure cannot change it either.
-* The error of a handler that throws or rejects goes to `console.error` with the failure of the release, and a `console.error` that throws is ignored.
-*/
-async function releaseConnection(connection, onReleaseError) {
-	try {
-		await connection.release();
-	} catch (error) {
-		reportReleaseError(error, onReleaseError);
-	}
-}
-/** Passes a failed release to `onReleaseError`, or to `console.error` without one, without throwing. */
-function reportReleaseError(error, onReleaseError) {
-	if (!onReleaseError) {
-		logReleaseError(error);
-		return;
-	}
-	try {
-		Promise.resolve(onReleaseError(error)).catch((handlerError) => logReleaseError(error, { error: handlerError }));
-	} catch (handlerError) {
-		logReleaseError(error, { error: handlerError });
-	}
-}
-/**
-* Writes a failed release to `console.error`, preceded by the error of `onReleaseError` when the handler failed.
-*
-* A console that throws, such as one redirected to a failing logger, leaves nowhere to report to, so its error is ignored.
-*/
-function logReleaseError(error, handlerFailure) {
-	try {
-		if (handlerFailure) console.error("kern-db: onReleaseError failed", handlerFailure.error);
-		console.error("kern-db: releasing a connection failed", error);
-	} catch {}
-}
-// src/transaction/abort.ts
-/**
-* Runs `start` and settles as its promise, or rejects with the reason of `signal` when it aborts first and `abort`, called on the abort, returns `true`.
-*
-* It listens from before `start`, which may abort the signal before it returns, and stops once the promise of `start` settles, such as for the signal that `node:test` aborts after every test.
-* A later rejection of that promise stays handled, and a value it resolves with after the rejection goes to `discard`, which handles its own failures.
-*/
-function settleUnlessAborted(start, signal, abort, discard) {
-	const settled = Promise.withResolvers();
-	let abandoned = false;
-	const onAbort = () => {
-		if (abort()) {
-			abandoned = true;
-			settled.reject(signal.reason);
-		}
-	};
-	signal.addEventListener("abort", onAbort, { once: true });
-	let running;
-	try {
-		running = start();
-	} catch (error) {
-		signal.removeEventListener("abort", onAbort);
-		settled.reject(error);
-		return settled.promise;
-	}
-	running.then((value) => {
-		signal.removeEventListener("abort", onAbort);
-		if (abandoned) discard?.(value);
-		else settled.resolve(value);
-	}, (error) => {
-		signal.removeEventListener("abort", onAbort);
-		settled.reject(error);
-	});
-	return settled.promise;
-}
-/**
-* Acquires a connection for a test transaction, rejecting with the reason of `signal` when it aborts first.
-*
-* A connection acquired after the abort returns to the pool as best-effort cleanup: the test transaction has already rejected, so nothing awaits the release, and its failure goes to `onReleaseError`.
-*/
-function acquireUnlessAborted(driver, signal, onReleaseError) {
-	if (signal.aborted) return Promise.reject(signal.reason);
-	return settleUnlessAborted(() => driver.acquire(), signal, () => true, (connection) => void releaseConnection(connection, onReleaseError));
-}
 // src/transaction/advisory-lock.ts
 /** Pause of `pollLock` in milliseconds after its first attempt, which doubles after each attempt up to `maxPollDelay`. */
 const firstPollDelay = 50;
@@ -300,6 +218,88 @@ function createSettingStatement(settings, local) {
 	}
 	return createStatement(text, parameters);
 }
+// src/transaction/release.ts
+/**
+* Returns a connection to the driver and passes a failed release to `onReleaseError`, or to `console.error` without one.
+*
+* The result or error of the transaction is decided before its release, so a failed release must not change it: a committed transaction that rejected would be retried.
+* Reporting the failure cannot change it either.
+* The error of a handler that throws or rejects goes to `console.error` with the failure of the release, and a `console.error` that throws is ignored.
+*/
+async function releaseConnection(connection, onReleaseError) {
+	try {
+		await connection.release();
+	} catch (error) {
+		reportReleaseError(error, onReleaseError);
+	}
+}
+/** Passes a failed release to `onReleaseError`, or to `console.error` without one, without throwing. */
+function reportReleaseError(error, onReleaseError) {
+	if (!onReleaseError) {
+		logReleaseError(error);
+		return;
+	}
+	try {
+		Promise.resolve(onReleaseError(error)).catch((handlerError) => logReleaseError(error, { error: handlerError }));
+	} catch (handlerError) {
+		logReleaseError(error, { error: handlerError });
+	}
+}
+/**
+* Writes a failed release to `console.error`, preceded by the error of `onReleaseError` when the handler failed.
+*
+* A console that throws, such as one redirected to a failing logger, leaves nowhere to report to, so its error is ignored.
+*/
+function logReleaseError(error, handlerFailure) {
+	try {
+		if (handlerFailure) console.error("kern-db: onReleaseError failed", handlerFailure.error);
+		console.error("kern-db: releasing a connection failed", error);
+	} catch {}
+}
+// src/transaction/test-levels/abort.ts
+/**
+* Runs `start` and settles as its promise, or rejects with the reason of `signal` when it aborts first and `abort`, called on the abort, returns `true`.
+*
+* It listens from before `start`, which may abort the signal before it returns, and stops once the promise of `start` settles, such as for the signal that `node:test` aborts after every test.
+* A later rejection of that promise stays handled, and a value it resolves with after the rejection goes to `discard`, which handles its own failures.
+*/
+function settleUnlessAborted(start, signal, abort, discard) {
+	const settled = Promise.withResolvers();
+	let abandoned = false;
+	const onAbort = () => {
+		if (abort()) {
+			abandoned = true;
+			settled.reject(signal.reason);
+		}
+	};
+	signal.addEventListener("abort", onAbort, { once: true });
+	let running;
+	try {
+		running = start();
+	} catch (error) {
+		signal.removeEventListener("abort", onAbort);
+		settled.reject(error);
+		return settled.promise;
+	}
+	running.then((value) => {
+		signal.removeEventListener("abort", onAbort);
+		if (abandoned) discard?.(value);
+		else settled.resolve(value);
+	}, (error) => {
+		signal.removeEventListener("abort", onAbort);
+		settled.reject(error);
+	});
+	return settled.promise;
+}
+/**
+* Acquires a connection for a test transaction, rejecting with the reason of `signal` when it aborts first.
+*
+* A connection acquired after the abort returns to the pool as best-effort cleanup: the test transaction has already rejected, so nothing awaits the release, and its failure goes to `onReleaseError`.
+*/
+function acquireUnlessAborted(driver, signal, onReleaseError) {
+	if (signal.aborted) return Promise.reject(signal.reason);
+	return settleUnlessAborted(() => driver.acquire(), signal, () => true, (connection) => void releaseConnection(connection, onReleaseError));
+}
 // src/transaction/level.ts
 /** Options of a level started without options, shared so that such a start allocates none. */
 const noLevelOptions = {};
@@ -346,7 +346,8 @@ function createLevel(connection, parent, transaction, isolation) {
 		endedBy: void 0,
 		restore: void 0,
 		isolation: enclosing ? enclosing.isolation : isolation,
-		locks: void 0
+		locks: void 0,
+		turns: void 0
 	};
 }
 /**
@@ -433,6 +434,11 @@ async function runLevel(storage, level, callback, commits, signal) {
 			rejection = { error };
 		}
 	}
+	if (!rejection && level.turns && !level.cleanup && !level.turns.tryTake()) try {
+		await level.turns.take(signal);
+	} catch {
+		endLevel(level, false, "abort");
+	}
 	if (level.cleanup) return getEndedOutcome(level.cleanup, level.endedBy === "abort" ? signal?.reason : createClosedError(level, rejection));
 	if (!rejection && level.child) rejection = { error: /* @__PURE__ */ new Error(level.session ? "Session ended with an error: a transaction of it was still running when its callback finished" : "Transaction was rolled back: a nested transaction was still running when its callback finished") };
 	if (!rejection && level.rollbackOnly) rejection = { error: new Error("Transaction was rolled back: a nested transaction failed to end", { cause: level.rollbackOnly.error }) };
@@ -442,6 +448,12 @@ async function runLevel(storage, level, callback, commits, signal) {
 		rejection: combineRejections(rejection, cleanup)
 	};
 }
+/** Runs `callback` in a started `level` in `storage` with `runLevel`, returning its result or throwing its rejection. */
+async function runStarted(storage, level, callback, commits, signal) {
+	const { result, rejection } = await runLevel(storage, level, callback, commits, signal);
+	if (rejection) throw rejection.error;
+	return result;
+}
 /**
 * Ends `level` once, whoever ends it: later calls return the cleanup already started.
 *
@@ -456,6 +468,7 @@ function endLevel(level, commit, endedBy) {
 		return level.cleanup;
 	}
 	level.state = "closing";
+	level.turns?.close();
 	level.cleanup = cleanUpLevel(level, commit, level.child && endLevel(level.child, false, "enclosing level"));
 	return level.cleanup;
 }
@@ -556,223 +569,6 @@ function combineRejections(earlier, cleanup) {
 function suppress(error, earlier, message) {
 	return { error: earlier ? new SuppressedError(error, earlier.error, message) : error };
 }
-// src/transaction/fixture-stack.ts
-/** Open test fixtures of a transaction coordinator and the queue of the changes of their stack. */
-var TestFixtureStack = class {
-	#driver;
-	#onReleaseError;
-	/** Async context of the levels of the coordinator, which tells whether a call runs inside a level. */
-	#storage;
-	/** Open test fixtures, the innermost last. */
-	#fixtures = [];
-	/** Changes of the fixture stack, run one after another so that each one sees the stack the previous one left. */
-	#transitions = Promise.resolve();
-	/**
-	* The `close` functions of the test fixtures that are still opening, from the call that starts the opening until the fixture enters the stack or the opening ends otherwise.
-	*
-	* An opening holds the queue of the fixture stack while its seed runs, so a closing of the stack queued behind it would wait for a seed that may never settle.
-	* Closing the stack therefore calls these first: each one tells its opening to stop waiting for the seed.
-	*/
-	#openings = /* @__PURE__ */ new Set();
-	/**
-	* Outermost fixture in the stack whose closing is queued but has not finished.
-	*
-	* Openings that start after that closing is requested nest outside of the fixture once it closes, so a repeated closing of it, or a closing of a fixture nested in it, must not close them.
-	*/
-	#closing;
-	constructor(driver, storage, onReleaseError) {
-		this.#driver = driver;
-		this.#storage = storage;
-		this.#onReleaseError = onReleaseError;
-	}
-	/**
-	* Starts opening a test fixture with `options`, see `startTestFixture` of the coordinator, or, given `refusal`, returns a fixture that rejects with it.
-	*
-	* The `close` of a refused fixture resolves once the earlier changes of the stack end.
-	*/
-	start(seed, refusal, options) {
-		let level;
-		let closeRequested = false;
-		const closing = Promise.withResolvers();
-		let closedRejection;
-		const close = () => {
-			if (this.#storage.getStore()) return Promise.reject(/* @__PURE__ */ new Error("Cannot close a test fixture inside a transaction"));
-			closeRequested = true;
-			closing.resolve();
-			if (level && this.#fixtures.includes(level)) {
-				const opened = level;
-				if (this.#closing && this.#closing.depth <= opened.depth) return this.#enqueue(() => this.#closeFixture(opened));
-				this.#closing = opened;
-				return this.#closeAfterOpenings(() => this.#enqueue(async () => {
-					try {
-						await this.#closeFixture(opened);
-					} finally {
-						if (this.#closing === opened) this.#closing = void 0;
-					}
-				}));
-			}
-			return this.#enqueue(() => {
-				const rejection = closedRejection;
-				closedRejection = void 0;
-				if (rejection) throw rejection.error;
-			});
-		};
-		if (refusal) return {
-			fixture: Promise.reject(refusal),
-			close
-		};
-		/**
-		* Runs stages 2 and 3 of the fixture and puts it in the stack, returning `undefined` when closing was requested and the fixture rolled back cleanly.
-		*
-		* It rejects with a failure to start the fixture, with the rejection of `seed`, or with a failure to roll back, which suppresses the rejection of `seed`.
-		*/
-		const open = async () => {
-			if (closeRequested) return;
-			const parent = this.#fixtures.at(-1);
-			const started = parent ? await this.#startInFixture(parent, options) : await this.#beginFixture(options?.isolation);
-			started.state = "open";
-			const outcome = closeRequested ? void 0 : await Promise.race([this.#seedFixture(started, seed), closing.promise]);
-			if (outcome && !outcome.rejection && !closeRequested) {
-				this.#fixtures.push(started);
-				level = started;
-				this.#openings.delete(close);
-				const { result } = outcome;
-				return {
-					get data() {
-						if (started.state !== "open") throw new Error("Test fixture is closed");
-						return result;
-					},
-					close,
-					[Symbol.asyncDispose]: close
-				};
-			}
-			const rejection = combineRejections(outcome?.rejection, { rejection: await this.#endFixture(started) });
-			if (rejection) throw rejection.error;
-		};
-		this.#openings.add(close);
-		return {
-			fixture: this.#enqueue(async () => {
-				let opened;
-				try {
-					opened = await open();
-				} catch (error) {
-					if (!closeRequested) throw error;
-					closedRejection = { error };
-				} finally {
-					this.#openings.delete(close);
-				}
-				if (!opened) throw new Error("Test fixture was closed before it opened");
-				return opened;
-			}),
-			close
-		};
-	}
-	/**
-	* Starts the level of a test transaction in the innermost test fixture as a change of the fixture stack, resolving to `undefined` when no fixture is open.
-	*
-	* Aborted while it waits for its turn, it rejects at once and its change starts nothing, so that a test that has already ended never preempts the active level of the fixture.
-	* From its turn on, it settles with its change.
-	*/
-	startTestLevel(options) {
-		const signal = options?.signal;
-		let waiting = true;
-		const start = () => this.#enqueue(() => {
-			if (signal?.aborted) return;
-			waiting = false;
-			const fixture = this.#fixtures.at(-1);
-			return fixture && this.#startInFixture(fixture, options);
-		});
-		return signal ? settleUnlessAborted(start, signal, () => waiting) : start();
-	}
-	/**
-	* Closes every fixture, including those still opening, rejecting with the failures of all of them.
-	*
-	* Unlike closing a fixture, it closes every opening, including one started after a closing of the stack was requested, since nothing may stay open.
-	*/
-	close() {
-		return this.#closeAfterOpenings(() => this.#enqueue(() => {
-			const root = this.#fixtures[0];
-			return root && this.#closeFixture(root);
-		}));
-	}
-	/**
-	* Closes the fixtures still opening and runs `closeStack`, rejecting with the failures of all of them.
-	*
-	* A seed that never settles holds the queue of the fixture stack, so closing is requested for every opening before `closeStack` queues its change, and the rollback does not wait for the seeds.
-	*/
-	async #closeAfterOpenings(closeStack) {
-		const closings = [];
-		for (const closeOpening of this.#openings) closings.push(closeOpening());
-		closings.push(closeStack());
-		let rejection;
-		for (const closing of await Promise.allSettled(closings)) if (closing.status === "rejected") rejection = suppress(closing.reason, rejection, "Closing a test fixture failed");
-		if (rejection) throw rejection.error;
-	}
-	/**
-	* Runs `seed` in a savepoint of a fixture that is released when it resolves, returning its result or rejection.
-	*
-	* The savepoint has its own context, so late code of `seed` cannot reach the fixture after it ends.
-	*/
-	async #seedFixture(fixture, seed) {
-		try {
-			return await runLevel(this.#storage, await startNestedLevel(fixture, false), seed, true);
-		} catch (error) {
-			return { rejection: { error } };
-		}
-	}
-	/** Closes an opened fixture as a change of the fixture stack. */
-	async #closeFixture(fixture) {
-		const index = this.#fixtures.indexOf(fixture);
-		if (index < 0) return;
-		let rejection;
-		try {
-			rejection = await this.#endFixture(fixture);
-		} finally {
-			this.#fixtures.length = index;
-		}
-		if (rejection) throw rejection.error;
-	}
-	/** Rolls back a fixture and releases the connection of the first one, returning the error to reject with. */
-	async #endFixture(fixture) {
-		const { rejection } = await endLevel(fixture, false);
-		if (!fixture.parent) await releaseConnection(fixture.connection, this.#onReleaseError);
-		return rejection;
-	}
-	/** Runs a change of the fixture stack after the earlier ones. */
-	#enqueue(transition) {
-		const result = this.#transitions.then(transition);
-		this.#transitions = result.catch(() => {});
-		return result;
-	}
-	/** Starts the first test fixture: a transaction at `isolation` on a reserved connection. */
-	async #beginFixture(isolation) {
-		const connection = await this.#driver.acquire();
-		try {
-			await connection.execute(getBeginStatement(isolation));
-		} catch (error) {
-			await releaseConnection(connection, this.#onReleaseError);
-			throw error;
-		}
-		return createLevel(connection, void 0, false, isolation);
-	}
-	/**
-	* Starts a nested level of a test fixture with `options`, preempting its active one.
-	*
-	* A fixture runs one nested level at a time, so a new one ends the previous one, such as a test that timed out.
-	* A level whose `signal` aborts while it preempts rejects with its reason instead of starting, and a failure to start after the abort suppresses the reason.
-	*/
-	async #startInFixture(fixture, options) {
-		const signal = options?.signal;
-		if (fixture.child) {
-			const cleanup = await endLevel(fixture.child, false, "preemption");
-			if (cleanup.rejection) throw suppressAbortReason(new Error("Cannot start a level of the test fixture: ending its active level failed", { cause: cleanup.rejection.error }), signal);
-		}
-		const unavailable = createUnavailableError(fixture, "start a level of the test fixture");
-		if (unavailable) throw suppressAbortReason(unavailable, signal);
-		signal?.throwIfAborted();
-		return startNestedLevel(fixture, false, options);
-	}
-};
 // src/error-condition-codes.ts
 /**
 * Condition names of the SQLSTATE codes of PostgreSQL errors, by code: the codes of type `E` with a condition name, which PL/pgSQL takes in `EXCEPTION WHEN`, under the headings of their classes.
@@ -1068,7 +864,8 @@ function createSessionLevel(connection) {
 		endedBy: void 0,
 		restore: void 0,
 		isolation: void 0,
-		locks: void 0
+		locks: void 0,
+		turns: void 0
 	};
 }
 /**
@@ -1120,6 +917,436 @@ async function leaveInTransaction(connection) {
 		if (!(error instanceof QueryError) || isQueryError(error, "in_failed_sql_transaction")) return;
 	}
 }
+// src/transaction/test-levels/turns.ts
+/**
+* Queue of the units of work that share the connection of a level of the test helpers, which run one at a time in the order they ask for a turn.
+*
+* The holder of the turn passes it to the next waiter with `release`.
+* Once closed, it grants every turn at once, so that its waiters see that the level is closed and reject.
+*/
+var TurnQueue = class {
+	#held = false;
+	#closed = false;
+	/** Waiters in the order they asked for a turn; each one, called, takes the turn. */
+	#waiters = [];
+	/**
+	* Resolves once the caller holds the turn, or at once after `close`.
+	*
+	* Aborted by `signal` while it waits, it leaves the queue and rejects with the reason of the signal; given an aborted signal, it rejects without taking the turn.
+	*/
+	take(signal) {
+		if (signal?.aborted) return Promise.reject(signal.reason);
+		if (this.#closed) return Promise.resolve();
+		if (!this.#held) {
+			this.#held = true;
+			return Promise.resolve();
+		}
+		const { promise, resolve, reject } = Promise.withResolvers();
+		const onAbort = () => {
+			this.#waiters.splice(this.#waiters.indexOf(grant), 1);
+			reject(signal.reason);
+		};
+		const grant = () => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		};
+		signal?.addEventListener("abort", onAbort, { once: true });
+		this.#waiters.push(grant);
+		return promise;
+	}
+	/** Takes the turn at once when it is free or the queue is closed, and tells whether it did. */
+	tryTake() {
+		if (this.#closed) return true;
+		if (this.#held) return false;
+		this.#held = true;
+		return true;
+	}
+	/** Passes the turn of the caller to the next waiter, or frees it. */
+	release() {
+		if (this.#closed) return;
+		const next = this.#waiters.shift();
+		if (next) next();
+		else this.#held = false;
+	}
+	/** Grants the turn to every waiter and to every later caller. */
+	close() {
+		this.#closed = true;
+		for (const grant of this.#waiters.splice(0)) grant();
+	}
+};
+/**
+* Runs `start` on its turn on the connection of a level of the test helpers `level`, and passes the turn on once it settles, after the level it started has ended.
+*
+* The code of the level runs statements and transactions at once on its connection, such as the requests of an open test transaction, where PostgreSQL would run a statement inside a nested transaction of other code, so they take turns rather than reject as in a transaction of `transaction`.
+* It rejects without calling `start` when the level accepts no statements on its turn, and with the reason of `signal` when it aborts first.
+*/
+async function runInTurn(level, operation, start, signal) {
+	const turns = level.turns;
+	if (!turns.tryTake()) await turns.take(signal);
+	try {
+		signal?.throwIfAborted();
+		const unavailable = createUnavailableError(level, operation);
+		if (unavailable) throw unavailable;
+		return await start();
+	} finally {
+		turns.release();
+	}
+}
+/**
+* Runs a statement of `run` on its turn in a savepoint of its own in a level of the test helpers `level`, released when it succeeds and rolled back when it fails.
+*
+* A statement outside a transaction commits or fails alone in production, so its failure must not abort the transaction of the test.
+* A statement sent before the level ends settles with its own result, as on the connection of a transaction: the rollback of the level undoes it, and reports the failures of that rollback.
+*/
+function runStatementInTurn(level, operation, run) {
+	return runInTurn(level, operation, async () => {
+		const unit = createLevel(level.connection, level, false);
+		level.child = unit;
+		const { connection } = unit;
+		const savepoint = connection.execute(createStatement(`SAVEPOINT ${getSavepointName(unit)}`));
+		unit.state = "open";
+		const running = run(connection);
+		try {
+			await savepoint;
+		} catch (error) {
+			await running.catch(() => {});
+			if (unit.cleanup) throw combineRejections({ error }, await unit.cleanup).error;
+			level.rollbackOnly ??= { error };
+			closeStarting(unit);
+			throw error;
+		}
+		let result;
+		try {
+			result = await running;
+		} catch (error) {
+			const cleanup = await endLevel(unit, false);
+			throw unit.endedBy ? error : combineRejections({ error }, cleanup).error;
+		}
+		const cleanup = await endLevel(unit, true);
+		if (cleanup.rejection && !unit.endedBy) throw cleanup.rejection.error;
+		return result;
+	});
+}
+// src/transaction/test-levels/fixture-stack.ts
+/** Open test fixtures of a transaction coordinator and the queue of the changes of their stack. */
+var TestFixtureStack = class {
+	#driver;
+	#onReleaseError;
+	/** Async context of the levels of the coordinator, which tells whether a call runs inside a level. */
+	#storage;
+	/** Open test fixtures, the innermost last. */
+	#fixtures = [];
+	/** Changes of the fixture stack, run one after another so that each one sees the stack the previous one left. */
+	#transitions = Promise.resolve();
+	/**
+	* The `close` functions of the test fixtures that are still opening, from the call that starts the opening until the fixture enters the stack or the opening ends otherwise.
+	*
+	* An opening holds the queue of the fixture stack while its seed runs, so a closing of the stack queued behind it would wait for a seed that may never settle.
+	* Closing the stack therefore calls these first: each one tells its opening to stop waiting for the seed.
+	*/
+	#openings = /* @__PURE__ */ new Set();
+	/**
+	* Outermost fixture in the stack whose closing is queued but has not finished.
+	*
+	* Openings that start after that closing is requested nest outside of the fixture once it closes, so a repeated closing of it, or a closing of a fixture nested in it, must not close them.
+	*/
+	#closing;
+	constructor(driver, storage, onReleaseError) {
+		this.#driver = driver;
+		this.#storage = storage;
+		this.#onReleaseError = onReleaseError;
+	}
+	/**
+	* Starts opening a test fixture with `options`, see `startTestFixture` of the coordinator, or, given `refusal`, returns a fixture that rejects with it.
+	*
+	* The `close` of a refused fixture resolves once the earlier changes of the stack end.
+	*/
+	start(seed, refusal, options) {
+		let level;
+		let closeRequested = false;
+		const closing = Promise.withResolvers();
+		let closedRejection;
+		const close = () => {
+			if (this.#storage.getStore()) return Promise.reject(/* @__PURE__ */ new Error("Cannot close a test fixture inside a transaction"));
+			closeRequested = true;
+			closing.resolve();
+			if (level && this.#fixtures.includes(level)) {
+				const opened = level;
+				if (this.#closing && this.#closing.depth <= opened.depth) return this.#enqueue(() => this.#closeFixture(opened));
+				this.#closing = opened;
+				return this.#closeAfterOpenings(() => this.#enqueue(async () => {
+					try {
+						await this.#closeFixture(opened);
+					} finally {
+						if (this.#closing === opened) this.#closing = void 0;
+					}
+				}));
+			}
+			return this.#enqueue(() => {
+				const rejection = closedRejection;
+				closedRejection = void 0;
+				if (rejection) throw rejection.error;
+			});
+		};
+		if (refusal) return {
+			fixture: Promise.reject(refusal),
+			close
+		};
+		/**
+		* Runs stages 2 and 3 of the fixture and puts it in the stack, returning `undefined` when closing was requested and the fixture rolled back cleanly.
+		*
+		* It rejects with a failure to start the fixture, with the rejection of `seed`, or with a failure to roll back, which suppresses the rejection of `seed`.
+		*/
+		const open = async () => {
+			if (closeRequested) return;
+			const parent = this.#fixtures.at(-1);
+			const started = parent ? await this.#startInFixture(parent, options) : await this.#beginFixture(options?.isolation);
+			started.state = "open";
+			const outcome = closeRequested ? void 0 : await Promise.race([this.#seedFixture(started, seed), closing.promise]);
+			if (outcome && !outcome.rejection && !closeRequested) {
+				this.#fixtures.push(started);
+				level = started;
+				this.#openings.delete(close);
+				const { result } = outcome;
+				return {
+					get data() {
+						if (started.state !== "open") throw new Error("Test fixture is closed");
+						return result;
+					},
+					close,
+					[Symbol.asyncDispose]: close
+				};
+			}
+			const rejection = combineRejections(outcome?.rejection, { rejection: await this.#endFixture(started) });
+			if (rejection) throw rejection.error;
+		};
+		this.#openings.add(close);
+		return {
+			fixture: this.#enqueue(async () => {
+				let opened;
+				try {
+					opened = await open();
+				} catch (error) {
+					if (!closeRequested) throw error;
+					closedRejection = { error };
+				} finally {
+					this.#openings.delete(close);
+				}
+				if (!opened) throw new Error("Test fixture was closed before it opened");
+				return opened;
+			}),
+			close
+		};
+	}
+	/**
+	* Starts the level of a test transaction in the innermost test fixture as a change of the fixture stack, resolving to `undefined` when no fixture is open.
+	*
+	* Aborted while it waits for its turn, it rejects at once and its change starts nothing, so that a test that has already ended never preempts the active level of the fixture.
+	* From its turn on, it settles with its change.
+	*/
+	startTestLevel(options) {
+		const signal = options?.signal;
+		let waiting = true;
+		const start = () => this.#enqueue(() => {
+			if (signal?.aborted) return;
+			waiting = false;
+			const fixture = this.#fixtures.at(-1);
+			return fixture && this.#startInFixture(fixture, options);
+		});
+		return signal ? settleUnlessAborted(start, signal, () => waiting) : start();
+	}
+	/**
+	* Closes every fixture, including those still opening, rejecting with the failures of all of them.
+	*
+	* Unlike closing a fixture, it closes every opening, including one started after a closing of the stack was requested, since nothing may stay open.
+	*/
+	close() {
+		return this.#closeAfterOpenings(() => this.#enqueue(() => {
+			const root = this.#fixtures[0];
+			return root && this.#closeFixture(root);
+		}));
+	}
+	/**
+	* Closes the fixtures still opening and runs `closeStack`, rejecting with the failures of all of them.
+	*
+	* A seed that never settles holds the queue of the fixture stack, so closing is requested for every opening before `closeStack` queues its change, and the rollback does not wait for the seeds.
+	*/
+	async #closeAfterOpenings(closeStack) {
+		const closings = [];
+		for (const closeOpening of this.#openings) closings.push(closeOpening());
+		closings.push(closeStack());
+		let rejection;
+		for (const closing of await Promise.allSettled(closings)) if (closing.status === "rejected") rejection = suppress(closing.reason, rejection, "Closing a test fixture failed");
+		if (rejection) throw rejection.error;
+	}
+	/**
+	* Runs `seed` in a savepoint of a fixture that is released when it resolves, returning its result or rejection.
+	*
+	* The savepoint has its own context, so late code of `seed` cannot reach the fixture after it ends.
+	* Its statements and transactions take turns, as in a test transaction.
+	*/
+	async #seedFixture(fixture, seed) {
+		try {
+			const level = await startNestedLevel(fixture, false);
+			level.turns = new TurnQueue();
+			return await runLevel(this.#storage, level, seed, true);
+		} catch (error) {
+			return { rejection: { error } };
+		}
+	}
+	/** Closes an opened fixture as a change of the fixture stack. */
+	async #closeFixture(fixture) {
+		const index = this.#fixtures.indexOf(fixture);
+		if (index < 0) return;
+		let rejection;
+		try {
+			rejection = await this.#endFixture(fixture);
+		} finally {
+			this.#fixtures.length = index;
+		}
+		if (rejection) throw rejection.error;
+	}
+	/** Rolls back a fixture and releases the connection of the first one, returning the error to reject with. */
+	async #endFixture(fixture) {
+		const { rejection } = await endLevel(fixture, false);
+		if (!fixture.parent) await releaseConnection(fixture.connection, this.#onReleaseError);
+		return rejection;
+	}
+	/** Runs a change of the fixture stack after the earlier ones. */
+	#enqueue(transition) {
+		const result = this.#transitions.then(transition);
+		this.#transitions = result.catch(() => {});
+		return result;
+	}
+	/** Starts the first test fixture: a transaction at `isolation` on a reserved connection. */
+	async #beginFixture(isolation) {
+		const connection = await this.#driver.acquire();
+		try {
+			await connection.execute(getBeginStatement(isolation));
+		} catch (error) {
+			await releaseConnection(connection, this.#onReleaseError);
+			throw error;
+		}
+		return createLevel(connection, void 0, false, isolation);
+	}
+	/**
+	* Starts a nested level of a test fixture with `options`, preempting its active one.
+	*
+	* A fixture runs one nested level at a time, so a new one ends the previous one, such as a test that timed out.
+	* A level whose `signal` aborts while it preempts rejects with its reason instead of starting, and a failure to start after the abort suppresses the reason.
+	*/
+	async #startInFixture(fixture, options) {
+		const signal = options?.signal;
+		if (fixture.child) {
+			const cleanup = await endLevel(fixture.child, false, "preemption");
+			if (cleanup.rejection) throw suppressAbortReason(new Error("Cannot start a level of the test fixture: ending its active level failed", { cause: cleanup.rejection.error }), signal);
+		}
+		const unavailable = createUnavailableError(fixture, "start a level of the test fixture");
+		if (unavailable) throw suppressAbortReason(unavailable, signal);
+		signal?.throwIfAborted();
+		return startNestedLevel(fixture, false, options);
+	}
+};
+// src/transaction/test-levels/open-test-transaction.ts
+/** Opens the test transactions of a transaction coordinator, and closes those on connections of their own when the database closes. */
+var OpenTestTransactions = class {
+	#driver;
+	#storage;
+	#fixtures;
+	#onReleaseError;
+	/** The `close` functions of the open test transactions on connections of their own; those in a fixture close with it. */
+	#roots = /* @__PURE__ */ new Set();
+	constructor(driver, storage, fixtures, onReleaseError) {
+		this.#driver = driver;
+		this.#storage = storage;
+		this.#fixtures = fixtures;
+		this.#onReleaseError = onReleaseError;
+	}
+	/**
+	* Opens a test transaction: a savepoint in the innermost open fixture, which preempts its active level, or a transaction on a connection of its own.
+	*
+	* Its statements outside a transaction and its nested levels take turns on its connection, see `runInTurn`.
+	* `getClosedError` returns the error of an opening once closing the database is requested; an opening on a connection of its own that the closing overtakes rolls back and rejects with it, since the closing no longer sees it.
+	*/
+	async open(options, getClosedError) {
+		const nested = await this.#fixtures.startTestLevel(options);
+		const level = nested ?? await this.#begin(options?.isolation, getClosedError);
+		if (nested?.cleanup) {
+			const { rejection } = await getEndedOutcome(nested.cleanup, /* @__PURE__ */ new Error("Cannot open a test transaction: its test fixture ended it before it opened"));
+			throw rejection.error;
+		}
+		level.state = "open";
+		level.turns = new TurnQueue();
+		let closing;
+		const close = () => {
+			closing ??= (async () => {
+				const { rejection } = await endLevel(level, false);
+				if (!nested) {
+					this.#roots.delete(close);
+					await releaseConnection(level.connection, this.#onReleaseError);
+				}
+				if (rejection) throw rejection.error;
+			})();
+			return closing;
+		};
+		if (!nested) {
+			const closedError = getClosedError();
+			if (closedError) {
+				let rejection = { error: closedError };
+				try {
+					await close();
+				} catch (error) {
+					rejection = suppress(error, rejection, "Transaction rollback failed");
+				}
+				throw rejection.error;
+			}
+			this.#roots.add(close);
+		}
+		return {
+			run: async (callback) => {
+				if (level.state !== "open") throw new Error("Cannot run a callback in the test transaction: it is already closed");
+				const current = this.#storage.getStore();
+				if (current === level) return callback();
+				if (current) throw new Error("Cannot run a callback in an open test transaction inside a transaction");
+				return this.#storage.run(level, callback);
+			},
+			close,
+			[Symbol.asyncDispose]: close
+		};
+	}
+	/** Rolls back the open test transactions on connections of their own, rejecting with the failures of all of them. */
+	async close() {
+		const closings = [];
+		for (const close of this.#roots) closings.push(close());
+		let rejection;
+		for (const closing of await Promise.allSettled(closings)) if (closing.status === "rejected") rejection = suppress(closing.reason, rejection, "Closing a test transaction failed");
+		if (rejection) throw rejection.error;
+	}
+	/**
+	* Begins an open test transaction outside a fixture at `isolation` on a connection of its own.
+	*
+	* Once closing the database is requested, it releases the connection instead of sending `BEGIN`, and rejects with the error of `getClosedError`.
+	*/
+	async #begin(isolation, getClosedError) {
+		const closedError = getClosedError();
+		if (closedError) throw closedError;
+		const connection = await this.#driver.acquire();
+		const lateError = getClosedError();
+		if (lateError) {
+			await releaseConnection(connection, this.#onReleaseError);
+			throw lateError;
+		}
+		const level = createLevel(connection, void 0, false, isolation);
+		try {
+			await connection.execute(getBeginStatement(isolation));
+		} catch (error) {
+			closeStarting(level);
+			await releaseConnection(connection, this.#onReleaseError);
+			throw error;
+		}
+		return level;
+	}
+};
 // src/transaction/coordinator.ts
 /**
 * Routes statements and scripts to the ambient transaction or session of the current async context or to the pool.
@@ -1133,6 +1360,7 @@ var TransactionCoordinator = class {
 	#onReleaseError;
 	/** Closing of the database, set by the first `close`; from then on, operations outside a transaction reject. */
 	#closed;
+	#openTestTransactions;
 	/** Rejects statements and transactions outside a test transaction or the seed of a test fixture instead of running them on the pool. */
 	test;
 	constructor(driver, { test = false, onReleaseError } = {}) {
@@ -1140,19 +1368,23 @@ var TransactionCoordinator = class {
 		this.test = test;
 		this.#onReleaseError = onReleaseError;
 		this.#fixtures = new TestFixtureStack(driver, this.#storage, onReleaseError);
+		this.#openTestTransactions = new OpenTestTransactions(driver, this.#storage, this.#fixtures, onReleaseError);
 	}
 	execute(statement) {
-		const target = this.#route("execute a query");
+		const level = this.#storage.getStore();
+		if (level?.turns) return runStatementInTurn(level, "execute a query", (connection) => connection.execute(statement));
+		const target = this.#route(level, "execute a query");
 		return target instanceof Error ? Promise.reject(target) : target.execute(statement);
 	}
 	/** Executes a script of statements without parameters where `execute` executes a statement. */
 	executeScript(text) {
-		const target = this.#route("execute a script");
+		const level = this.#storage.getStore();
+		if (level?.turns) return runStatementInTurn(level, "execute a script", (connection) => connection.executeScript(text));
+		const target = this.#route(level, "execute a script");
 		return target instanceof Error ? Promise.reject(target) : target.executeScript(text);
 	}
-	/** Returns the connection of the ambient transaction or session, or the driver of the pool, that runs `operation`, or the error that rejects it. */
-	#route(operation) {
-		const level = this.#storage.getStore();
+	/** Returns the connection of the ambient transaction or session `level`, or the driver of the pool, that runs `operation`, or the error that rejects it. */
+	#route(level, operation) {
 		if (!level) {
 			if (this.#closed) return createDatabaseClosedError(operation);
 			return this.test ? new Error(describeOutsideTest(operation)) : this.driver;
@@ -1261,6 +1493,7 @@ var TransactionCoordinator = class {
 	* Runs `callback` in a transaction that always rolls back, on a coordinator created for tests.
 	*
 	* Inside a transaction, it runs `callback` in a savepoint nested in it that always rolls back.
+	* Outside a transaction of `transaction`, the statements and nested levels of `callback` take turns on its connection, each statement in a savepoint of its own, see `runInTurn`; when `callback` resolves, the level ends after the statements and nested levels it started.
 	* When `signal` aborts, the level stops accepting statements at once and ends without waiting for `callback`.
 	* Once the level ends, the transaction rejects with the reason of the signal.
 	* A failure to start or end the level after the abort suppresses the reason in a `SuppressedError`.
@@ -1273,7 +1506,24 @@ var TransactionCoordinator = class {
 		const parent = this.#storage.getStore();
 		if (parent) return this.#runNested(parent, callback, false, options);
 		if (this.#closed) return Promise.reject(createDatabaseClosedError("start a test transaction"));
-		return this.#fixtures.startTestLevel(options).then((level) => level ? this.#runStarted(level, callback, false, signal) : this.#runRoot(callback, false, options));
+		return this.#fixtures.startTestLevel(options).then((level) => {
+			if (!level) return this.#runRoot(callback, false, options);
+			level.turns = new TurnQueue();
+			return runStarted(this.#storage, level, callback, false, signal);
+		});
+	}
+	/**
+	* Opens a test transaction that the callbacks of `run` share until it closes, see `OpenTestTransactions`.
+	*
+	* It rejects inside a transaction, and once closing the database is requested.
+	*/
+	async openTestTransaction(options) {
+		if (!this.test) throw new Error("openTestTransaction requires a database created with test: true");
+		if (this.#storage.getStore()) throw new Error("Cannot open a test transaction inside a transaction");
+		const getClosedError = () => this.#closed ? createDatabaseClosedError("open a test transaction") : void 0;
+		const closedError = getClosedError();
+		if (closedError) throw closedError;
+		return this.#openTestTransactions.open(options, getClosedError);
 	}
 	/**
 	* Opens a test fixture: a transaction on a reserved connection, or a savepoint in the innermost open fixture, and runs `seed` in it.
@@ -1295,15 +1545,15 @@ var TransactionCoordinator = class {
 	}
 	/** Returns the error that rejects a test fixture created now, or `undefined` when it can open. */
 	#getFixtureRefusal() {
-		if (!this.test) return /* @__PURE__ */ new Error("createTestFixture requires a database created with test: true");
+		if (!this.test) return /* @__PURE__ */ new Error("openTestFixture requires a database created with test: true");
 		if (this.#storage.getStore()) return /* @__PURE__ */ new Error("Cannot create a test fixture inside a transaction");
 		if (this.#closed) return createDatabaseClosedError("create a test fixture");
 	}
 	/**
-	* Closes the test fixtures, including those still opening, and then the driver, which waits for the running transactions and sessions to end.
+	* Closes the test fixtures, including those still opening, and the open test transactions on connections of their own, and then the driver, which waits for the running transactions and sessions to end.
 	*
-	* A driver waits for every reserved connection, so closing it under an open fixture would wait forever.
-	* A failed closing of the driver suppresses the failures of closing the fixtures.
+	* A driver waits for every reserved connection, so closing it under an open fixture or test transaction would wait forever.
+	* A failed closing of the driver suppresses the failures of closing the fixtures and test transactions.
 	* From the first call, statements, transactions, sessions, and fixtures started outside a transaction and a session reject, while the levels already running can still end; a repeated call returns the same closing.
 	*/
 	close() {
@@ -1312,14 +1562,10 @@ var TransactionCoordinator = class {
 		this.#closed ??= this.#close();
 		return this.#closed;
 	}
-	/** Closes the test fixtures and then the driver, see `close`. */
+	/** Closes the test fixtures and the open test transactions on connections of their own, and then the driver, see `close`. */
 	async #close() {
 		let rejection;
-		try {
-			await this.#fixtures.close();
-		} catch (error) {
-			rejection = { error };
-		}
+		for (const closing of await Promise.allSettled([this.#fixtures.close(), this.#openTestTransactions.close()])) if (closing.status === "rejected") rejection = suppress(closing.reason, rejection, "Closing a test fixture or transaction failed");
 		try {
 			await this.driver.close();
 		} catch (error) {
@@ -1345,6 +1591,7 @@ var TransactionCoordinator = class {
 			throw signal.reason;
 		}
 		const level = createLevel(connection, void 0, commits, options.isolation);
+		if (!commits) level.turns = new TurnQueue();
 		const outcome = await this.#runTransaction(level, callback, commits, options);
 		await releaseConnection(connection, this.#onReleaseError);
 		return settleTransaction(level, outcome);
@@ -1402,15 +1649,15 @@ var TransactionCoordinator = class {
 		return outcome.result;
 	}
 	async #runNested(parent, callback, commits, options) {
+		const start = async () => {
+			const level = await startNestedLevel(parent, commits, options);
+			if (!level.inTransaction) level.turns = new TurnQueue();
+			return runStarted(this.#storage, level, callback, commits, options?.signal);
+		};
+		if (parent.turns) return runInTurn(parent, "start a nested transaction", start, options?.signal);
 		const unavailable = createUnavailableError(parent, "start a nested transaction");
 		if (unavailable) throw unavailable;
-		return this.#runStarted(await startNestedLevel(parent, commits, options), callback, commits, options?.signal);
-	}
-	/** Runs `callback` in a started level, returning its result or throwing its rejection. */
-	async #runStarted(level, callback, commits, signal) {
-		const { result, rejection } = await runLevel(this.#storage, level, callback, commits, signal);
-		if (rejection) throw rejection.error;
-		return result;
+		return start();
 	}
 };
 /**

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import { a as TextValue, i as SqlStatement, n as Driver, o as createStatement, r as DriverResult, s as isDriver, t as Connection } from "./driver-CZCBkque.mjs";
-import { a as BaseDerivableType, c as Type, d as TypeOutput, f as TypeTransform, h as typeValues, i as AnyType, l as TypeInput, m as isType, n as AcceptedValues, o as DerivableType, p as defineType, r as AnyDerivableType, s as DerivableTypeWithParameters, t as AcceptedNull, u as TypeOptions } from "./type-CbrtxvDF.mjs";
-import { A as OneRow, F as ResultRows, I as ValueRows, M as ResultByRows, N as ResultDecodeError, S as param, T as UntypedValue, _ as isDatabase, a as SqlQuery, b as SqlValue, d as DatabaseOptions, f as IsolationLevel, g as createDatabase, h as TransactionOptions, i as InitialSqlQueryState, j as OneValueRows, k as NotFoundError, m as SessionOptions, n as DecodedFields, o as SqlQueryResult, p as PollLockOptions, r as FieldTypes, s as SqlQueryState, t as AnySqlQuery, u as Database, w as sql, x as identifier, y as SqlFragment } from "./query-Dxiy1HJD.mjs";
+import { a as BaseDerivableType, c as Type, d as TypeOutput, f as TypeTransform, h as typeValues, i as AnyType, l as TypeInput, m as isType, n as AcceptedValues, o as DerivableType, p as defineType, r as AnyDerivableType, s as DerivableTypeWithParameters, t as AcceptedNull, u as TypeOptions } from "./type-DU5oJfh_.mjs";
+import { A as OneRow, F as ResultRows, I as ValueRows, M as ResultByRows, N as ResultDecodeError, S as param, T as UntypedValue, _ as isDatabase, a as SqlQuery, b as SqlValue, d as DatabaseOptions, f as IsolationLevel, g as createDatabase, h as TransactionOptions, i as InitialSqlQueryState, j as OneValueRows, k as NotFoundError, m as SessionOptions, n as DecodedFields, o as SqlQueryResult, p as PollLockOptions, r as FieldTypes, s as SqlQueryState, t as AnySqlQuery, u as Database, w as sql, x as identifier, y as SqlFragment } from "./query-DpxSVheu.mjs";
 /**
  * Error of a statement that PostgreSQL rejected, such as for a violated constraint; the connection of the statement stays usable.
  *

package/dist/index.mjs

@@ -1,5 +1,5 @@
 import { o as defineType, s as isType } from "./bytea-DNZ_ftio.mjs";
 import { C as isDriver, S as createStatement, _ as sql, h as param, i as ResultDecodeError, m as identifier, r as NotFoundError } from "./query-FKBN7BMY.mjs";
 import { a as toDriverError, n as QueryError, t as ConnectionError } from "./driver-error-D8D4UQ4F.mjs";
-import { a as TransactionConnectionError, i as isQueryError, o as isOutcomeUnknown, r as isDatabase, t as createDatabase } from "./database-D4ql2RZ0.mjs";
+import { a as TransactionConnectionError, i as isQueryError, o as isOutcomeUnknown, r as isDatabase, t as createDatabase } from "./database-C3LR3pFV.mjs";
 export { ConnectionError, NotFoundError, QueryError, ResultDecodeError, TransactionConnectionError, createDatabase, createStatement, defineType, identifier, isDatabase, isDriver, isOutcomeUnknown, isQueryError, isType, param, sql, toDriverError };

package/dist/{query-Dxiy1HJD.d.mts → query-DpxSVheu.d.mts}

@@ -1,5 +1,5 @@
 import { a as TextValue, i as SqlStatement, n as Driver, r as DriverResult } from "./driver-CZCBkque.mjs";
-import { c as Type, d as TypeOutput, i as AnyType } from "./type-CbrtxvDF.mjs";
+import { c as Type, d as TypeOutput, i as AnyType } from "./type-DU5oJfh_.mjs";
 /**
  * How a query returns its rows: `many` as an array; `one` as one row, rejecting without it; `nullable` as one row or `null` without it; `optional` as one row or `undefined` without it.
  *

package/dist/testing.d.mts

@@ -1,17 +1,39 @@
 import { n as Driver, t as Connection } from "./driver-CZCBkque.mjs";
-import { f as IsolationLevel, u as Database } from "./query-Dxiy1HJD.mjs";
+import { f as IsolationLevel, u as Database } from "./query-DpxSVheu.mjs";
 /** Test fixture of `useTestFixture`, open while the tests of its `describe` block or test file run. */
 interface TestFixture<T = unknown> {
   /** Result of the seed of the fixture; reading it while the fixture is not open throws. */
   readonly data: T;
 }
-/** Test fixture opened by the transaction coordinator: an outer transaction of a database created for tests, which always rolls back when it closes. */
+/** Open test fixture of `openTestFixture`: an outer transaction of a database created for tests, which always rolls back when it closes. */
 interface OpenedTestFixture<T = unknown> extends AsyncDisposable {
   /** Result of the seed of the fixture, such as the records it created; reading it after the fixture closes throws. */
   readonly data: T;
   /** Rolls back the fixture and the fixtures opened inside it; closing a closed fixture does nothing. */
   close(): Promise<void>;
 }
+/** Open test transaction of `openTestTransaction`, which the callbacks of `run`, such as the requests of one browser test to a server, share until it closes. */
+interface OpenedTestTransaction extends AsyncDisposable {
+  /**
+   * Runs `callback` in the test transaction, so that its queries run there.
+   *
+   * Each query of the callback outside a transaction runs as a nested transaction of its own, so that a failed query undoes only itself, as in production.
+   * A transaction of a callback runs as a nested transaction that the queries and transactions of the other callbacks wait for.
+   * It rejects without calling `callback` once the test transaction is closed, and inside a transaction.
+   */
+  run<T>(callback: () => Promise<T>): Promise<T>;
+  /** Rolls back the test transaction; the later queries of its callbacks fail, and closing it again returns the same closing. */
+  close(): Promise<void>;
+}
+/** Options of `openTestTransaction`. */
+interface OpenTestTransactionOptions {
+  /**
+   * Isolation level of the test transaction, such as `serializable`, for code under test that starts a transaction at that level.
+   *
+   * Inside a test fixture, the test transaction runs at the level of the fixture: given another level, it rejects.
+   */
+  isolation?: IsolationLevel;
+}
 /** Test fixture that is being opened, with a `close` that can be called before it opens. */
 interface PendingTestFixture<T = unknown> {
   readonly fixture: Promise<OpenedTestFixture<T>>;
@@ -25,6 +47,12 @@ interface PendingTestFixture<T = unknown> {
 interface TestHooks {
   before(hook: () => Promise<void>): unknown;
   after(hook: () => Promise<void>): unknown;
+  /**
+   * Hook of a test runner that runs a function once the current test finishes, also when it times out, such as `onTestFinished` of `bun:test`.
+   *
+   * With it, a test that `wrapTest` declares rolls back its test transaction as soon as the runner gives up on the test, as with the abort signal of `testTransaction`.
+   */
+  onTestFinished?(hook: () => void): unknown;
 }
 /** Options of `testTransaction`. */
 interface TestTransactionOptions {
@@ -44,7 +72,7 @@ interface TestTransactionOptions {
    */
   isolation?: IsolationLevel;
 }
-/** Options of `useTestFixture`. */
+/** Options of `useTestFixture` and `openTestFixture`. */
 interface TestFixtureOptions {
   /**
    * Isolation level of the transaction of the fixture, such as `serializable`, at which the test transactions and fixtures nested in it run.
@@ -59,6 +87,7 @@ interface TestHelpers {
    * Runs `callback` in a transaction that always rolls back.
    *
    * Wrap the body of every test in it, so that every run of the test gets its own transaction.
+   * A query of the callback outside a transaction runs in a nested transaction of its own, so that a failed query undoes only itself, as in production.
    * Inside an existing transaction, it starts a nested transaction that always rolls back.
    */
   testTransaction<T>(callback: () => Promise<T>, options?: TestTransactionOptions): Promise<T>;
@@ -71,9 +100,34 @@ interface TestHelpers {
    * A fixture whose `seed` rejects rolls back and closes.
    */
   useTestFixture<T>(seed: () => Promise<T>, options?: TestFixtureOptions): TestFixture<T>;
+  /**
+   * Wraps the `test` function of `node:test` or `bun:test` so that every test it declares runs in a test transaction.
+   *
+   * The wrapped function keeps the modifiers of the original, such as `test.skip`, `test.only`, and `test.each(table)`, and its options, such as a timeout.
+   * Without `onTestFinished` in the hooks, the test transaction takes the abort signal of the test context, such as `t.signal` of `node:test`.
+   * Hooks of the test, such as `beforeEach`, run outside of its test transaction.
+   * A test function must return a promise or a value rather than take a `done` callback.
+   * With Vitest, run tests in test transactions with `aroundEach` instead, which also covers their hooks: the wrapper hides the parameters of a test function from the fixtures of `test.extend`.
+   */
+  wrapTest<T extends (...args: never[]) => unknown>(test: T): T;
 }
 /** Creates the test helpers of a database created with `test: true`, registering fixtures with the hooks of a test runner. */
 export declare function createTestHelpers(database: Database, hooks: TestHooks): TestHelpers;
+/**
+ * Opens a test fixture of a database created with `test: true` without the hooks of a test runner, such as in a server that runs browser tests, and runs `seed` in it.
+ *
+ * It resolves once `seed` resolves, with the fixture whose `close` rolls it back; a fixture whose `seed` rejects rolls back and closes.
+ * Closing the database closes the fixture too.
+ * Fixtures nest as with `useTestFixture`: a new one opens inside the innermost open one, and test transactions run in the innermost one.
+ */
+export declare function openTestFixture<T>(database: Database, seed: () => Promise<T>, options?: TestFixtureOptions): Promise<OpenedTestFixture<T>>;
+/**
+ * Opens a test transaction of a database created with `test: true` that callbacks share through `run` until it closes, such as the requests of one browser test to a server.
+ *
+ * Inside an open test fixture, it opens as a nested transaction of the innermost one, and rolls back a test transaction or another open test transaction running there; without a fixture, it opens on a connection of its own.
+ * Closing the database closes it too.
+ */
+export declare function openTestTransaction(database: Database, options?: OpenTestTransactionOptions): Promise<OpenedTestTransaction>;
 /** Options of `describeDriverContract`: how to create the driver under test. */
 interface DriverContractOptions {
   /** Creates a driver over a new client of the test database with `max` connections. */
@@ -126,4 +180,4 @@ export declare function waitForLock(observer: Pick<Connection, "execute">, pid:
  * It rejects when no such backend waits in time.
  */
 export declare function waitForLockedStatement(observer: Pick<Connection, "execute">, fragment: string, options?: LockWaitOptions): Promise<number>;
-export type { DriverContractOptions, DriverContractRunner, LockWaitOptions, OpenedTestFixture, PendingTestFixture, TestFixture, TestFixtureOptions, TestHelpers, TestHooks, TestTransactionOptions };
+export type { DriverContractOptions, DriverContractRunner, LockWaitOptions, OpenTestTransactionOptions, OpenedTestFixture, OpenedTestTransaction, PendingTestFixture, TestFixture, TestFixtureOptions, TestHelpers, TestHooks, TestTransactionOptions };

package/dist/testing.mjs

@@ -1,8 +1,8 @@
 import { r as boolean, t as bytea } from "./bytea-DNZ_ftio.mjs";
 import { S as createStatement, _ as sql, h as param, m as identifier } from "./query-FKBN7BMY.mjs";
 import { n as QueryError, t as ConnectionError } from "./driver-error-D8D4UQ4F.mjs";
-import { a as TransactionConnectionError, n as getCoordinator, s as pause, t as createDatabase } from "./database-D4ql2RZ0.mjs";
 import { t as array } from "./array-BLt8ZNR5.mjs";
+import { a as TransactionConnectionError, n as getCoordinator, s as pause, t as createDatabase } from "./database-C3LR3pFV.mjs";
 import { _ as interval, a as bigint, b as timestamptz, c as numeric, f as inet, g as date, h as enumOf, m as jsonb, n as char, o as doublePrecision, r as text, s as integer, t as uuid, v as time, y as timestamp } from "./types-Dl2oicjV.mjs";
 import assert from "node:assert/strict";
 // src/test-helpers.ts
@@ -10,8 +10,32 @@ import assert from "node:assert/strict";
 function createTestHelpers(database, hooks) {
 	const coordinator = getCoordinator(database);
 	if (!coordinator.test) throw new Error("createTestHelpers requires a database created with test: true");
+	/**
+	* Runs a test function in a test transaction, which `onTestFinished`, or else the signal of the test context, aborts once the runner finishes the test.
+	*
+	* The arguments of a test of `test.each` are a row of its table rather than a context, so its `signal` belongs to the data of the test.
+	*/
+	function runTestInTransaction(callback, parameterized) {
+		return function(...args) {
+			const run = async () => callback.apply(this, args);
+			if (!hooks.onTestFinished) {
+				const signal = parameterized ? void 0 : readTestSignal(args[0]);
+				return coordinator.testTransaction(run, { signal });
+			}
+			const controller = new AbortController();
+			let finished = false;
+			hooks.onTestFinished(() => {
+				finished = true;
+				controller.abort(/* @__PURE__ */ new Error("The test finished before its test transaction ended"));
+			});
+			return coordinator.testTransaction(run, { signal: controller.signal }).catch((error) => {
+				if (!finished) throw error;
+			});
+		};
+	}
 	return {
 		testTransaction: (callback, options) => coordinator.testTransaction(callback, options),
+		wrapTest: (test) => wrapTestFunction(test, void 0, false, runTestInTransaction),
 		useTestFixture(seed, options) {
 			let pending;
 			let fixture;
@@ -38,6 +62,52 @@ function createTestHelpers(database, hooks) {
 		}
 	};
 }
+/**
+* Opens a test fixture of a database created with `test: true` without the hooks of a test runner, such as in a server that runs browser tests, and runs `seed` in it.
+*
+* It resolves once `seed` resolves, with the fixture whose `close` rolls it back; a fixture whose `seed` rejects rolls back and closes.
+* Closing the database closes the fixture too.
+* Fixtures nest as with `useTestFixture`: a new one opens inside the innermost open one, and test transactions run in the innermost one.
+*/
+function openTestFixture(database, seed, options) {
+	return getCoordinator(database).createTestFixture(seed, options);
+}
+/**
+* Opens a test transaction of a database created with `test: true` that callbacks share through `run` until it closes, such as the requests of one browser test to a server.
+*
+* Inside an open test fixture, it opens as a nested transaction of the innermost one, and rolls back a test transaction or another open test transaction running there; without a fixture, it opens on a connection of its own.
+* Closing the database closes it too.
+*/
+function openTestTransaction(database, options) {
+	return getCoordinator(database).openTestTransaction(options);
+}
+/** Reads the abort signal of a test from the first argument of its function, the test context of `node:test`. */
+function readTestSignal(context) {
+	if (typeof context === "object" && context !== null && "signal" in context) {
+		const { signal } = context;
+		return signal instanceof AbortSignal ? signal : void 0;
+	}
+}
+/**
+* Wraps a `test` function of a test runner and the functions that its properties and calls return, such as `test.skip` and `test.each(table)`, replacing every function argument with `wrapCallback` of it.
+*
+* Calls a modifier with the object it was read from, since modifiers of `bun:test` reject another `this`.
+* Marks the callbacks of functions reached through `each` as parameterized.
+*/
+function wrapTestFunction(target, owner, parameterized, wrapCallback) {
+	return new Proxy(target, {
+		apply(callee, self, args) {
+			const wrappedArgs = [];
+			for (const arg of args) wrappedArgs.push(typeof arg === "function" ? wrapCallback(arg, parameterized) : arg);
+			const result = Reflect.apply(callee, owner ?? self, wrappedArgs);
+			return typeof result === "function" ? wrapTestFunction(result, void 0, parameterized, wrapCallback) : result;
+		},
+		get(object, key) {
+			const value = Reflect.get(object, key);
+			return typeof value === "function" ? wrapTestFunction(value, object, parameterized || key === "each", wrapCallback) : value;
+		}
+	});
+}
 // src/driver-contract.ts
 /** Creates helpers that run raw statements on `target`: a database, a driver, or a reserved connection. */
 function createStatementRunners(target) {
@@ -842,4 +912,4 @@ async function poll(timeout, message, check) {
 		clearTimeout(timer);
 	}
 }
-export { createTestHelpers, describeDriverContract, getBackendPid, waitForLock, waitForLockedStatement };
+export { createTestHelpers, describeDriverContract, getBackendPid, openTestFixture, openTestTransaction, waitForLock, waitForLockedStatement };

package/dist/{type-CbrtxvDF.d.mts → type-DU5oJfh_.d.mts}

@@ -61,7 +61,8 @@ interface BaseDerivableType<Output, Input, Parameters extends unknown[] | undefi
   /**
    * Narrows the values of this type to `T` in TypeScript, such as to a union of strings that a `CHECK` constraint allows, or to the shape of JSON values.
    *
-   * The values are not validated at runtime. `T` must be among the values that this type both returns and accepts, and `nullable` keeps `null` apart from it.
+   * The values are not validated at runtime.
+   * `T` must be among the values that this type both returns and accepts, and `nullable` keeps `null` apart from it.
    */
   of<T extends AcceptedValues<Exclude<Output, null>, Exclude<Input, null>>>(): DerivableType<T | AcceptedNull<Input>, T | AcceptedNull<Input>, Parameters>;
 }

package/dist/types.d.mts

@@ -1,4 +1,4 @@
-import { a as BaseDerivableType, c as Type, o as DerivableType, s as DerivableTypeWithParameters } from "./type-CbrtxvDF.mjs";
+import { a as BaseDerivableType, c as Type, o as DerivableType, s as DerivableTypeWithParameters } from "./type-DU5oJfh_.mjs";
 /**
  * Creates a type of one-dimensional arrays of `element` values.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kern-db",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "PostgreSQL database layer with ambient transactions, typed SQL queries, and test transactions",
   "keywords": [
     "database",