kern-db 0.3.0 → 0.5.0

package/dist/{driver-CSfbXOBJ.d.mts → driver-CZCBkque.d.mts}

@@ -24,6 +24,7 @@ interface DriverResult {
  *
  * A driver sends parameters as text without a declared type, so that the statement text alone determines their types, and returns values as text without parsing them.
  * It rejects with `QueryError` a statement or script that PostgreSQL rejected, whose connection stays usable, and with `ConnectionError` any other failure of a statement, a script, or a connection.
+ * The driver sets `unsent` of a `ConnectionError` to `true` when it knows that the statement or script was not sent, such as after a failure to get a connection, and only then.
  */
 interface Driver {
   /**
@@ -40,12 +41,16 @@ interface Driver {
    * Either way, no transaction stays open on the pool.
    */
   executeScript(text: string): Promise<void>;
-  /** Reserves a dedicated connection, such as for a transaction or a session. */
+  /**
+   * Reserves a dedicated connection, such as for a transaction or a session.
+   *
+   * It rejects a failure to get a connection with `ConnectionError` whose `unsent` is `true`.
+   */
   acquire(): Promise<Connection>;
   /**
    * Closes the connections once the statements on the pool and the transactions and sessions on reserved connections end.
    *
-   * From the call, it rejects a new statement or script on the pool and a new connection with `ConnectionError`.
+   * From the call, it rejects a new statement or script on the pool and a new connection with `ConnectionError` whose `unsent` is `true`.
    */
   close(): Promise<void>;
 }

package/dist/{driver-error-26zcdHeU.mjs → driver-error-D8D4UQ4F.mjs}

@@ -42,12 +42,19 @@ var QueryError = class QueryError extends Error {
 /**
 * Error of a statement or connection that failed for another reason than PostgreSQL rejecting a statement, such as a lost connection, a timeout of the client, or a closed driver.
 *
-* The statement may have run or not, and its connection may be lost or in an unknown state of its transaction.
+* Unless `unsent` is `true`, the statement may have run or not, and its connection may be lost or in an unknown state of its transaction.
 */
 var ConnectionError = class ConnectionError extends Error {
 	name = "ConnectionError";
+	/**
+	* Whether the statement was certainly not sent to the server, such as when the driver was closed or could not get a connection.
+	*
+	* `false` means that the statement may have been sent.
+	*/
+	unsent;
 	constructor(message, options) {
 		super(message, options);
+		this.unsent = options?.unsent ?? false;
 		setBrand(this, connectionErrorBrand);
 	}
 	/** Tells whether `value` is an instance of the class, including one of `ConnectionError` of another copy of kern-db. */
@@ -69,16 +76,18 @@ function isSessionEnding(severity, code) {
 * Classifies an error of a client as `QueryError` or `ConnectionError`, by the fields of the PostgreSQL error it carries, for a driver to reject with.
 *
 * An error that kern-db has already classified returns as it is.
-* An error without a severity or a SQLSTATE, such as of a client that lost its connection, is a `ConnectionError`, and so is one of severity `FATAL` or `PANIC`, which ends the session.
+* An error without a severity or a SQLSTATE, such as of a client that lost its connection, is a `ConnectionError`, and so is one of severity `FATAL` or `PANIC`, which ends the session; it gets `unsent` of `fields`.
 * An error of severity `ERROR` is a `QueryError`.
 * With a translated severity, the SQLSTATE tells an error that ends the session, so a few errors of other codes that end it give `QueryError`.
 */
 function toDriverError(error, fields) {
 	if (error instanceof QueryError || error instanceof ConnectionError) return error;
 	const message = error instanceof Error ? error.message : String(error);
-	const { severity, code, constraint } = fields ?? {};
-	if (typeof severity !== "string" || typeof code !== "string" || !sqlState.test(code)) return new ConnectionError(message, { cause: error });
-	if (isSessionEnding(severity, code)) return new ConnectionError(message, { cause: error });
+	const { severity, code, constraint, unsent } = fields ?? {};
+	if (typeof severity !== "string" || typeof code !== "string" || !sqlState.test(code) || isSessionEnding(severity, code)) return new ConnectionError(message, {
+		cause: error,
+		unsent
+	});
 	return new QueryError(message, {
 		code,
 		constraint: typeof constraint === "string" ? constraint : void 0,

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-CSfbXOBJ.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-BrvYBvWC.mjs";
+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-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.
  *
@@ -24,17 +24,24 @@ export declare class QueryError extends Error {
 /**
  * Error of a statement or connection that failed for another reason than PostgreSQL rejecting a statement, such as a lost connection, a timeout of the client, or a closed driver.
  *
- * The statement may have run or not, and its connection may be lost or in an unknown state of its transaction.
+ * Unless `unsent` is `true`, the statement may have run or not, and its connection may be lost or in an unknown state of its transaction.
  */
 export declare class ConnectionError extends Error {
   readonly name: string;
+  /**
+   * Whether the statement was certainly not sent to the server, such as when the driver was closed or could not get a connection.
+   *
+   * `false` means that the statement may have been sent.
+   */
+  readonly unsent: boolean;
   constructor(message: string, options?: {
     cause?: unknown;
+    unsent?: boolean | undefined;
   });
   /** Tells whether `value` is an instance of the class, including one of `ConnectionError` of another copy of kern-db. */
   static [Symbol.hasInstance]<T>(this: abstract new (...args: never) => T, value: unknown): value is T;
 }
-/** Fields of the PostgreSQL error that an error of a client carries, by which `toDriverError` classifies it. */
+/** Fields of the PostgreSQL error that an error of a client carries, by which `toDriverError` classifies it, and whether the driver knows that the statement was not sent. */
 interface DriverErrorFields {
   /**
    * Severity of the error, such as `ERROR` or `FATAL`.
@@ -46,12 +53,18 @@ interface DriverErrorFields {
   readonly code?: unknown;
   /** Name of the constraint that the statement violated. */
   readonly constraint?: unknown;
+  /**
+   * Whether the statement was certainly not sent to the server, such as after a failure to get a connection, which `unsent` of a `ConnectionError` keeps.
+   *
+   * Leave it unset when the statement may have been sent.
+   */
+  readonly unsent?: boolean | undefined;
 }
 /**
  * Classifies an error of a client as `QueryError` or `ConnectionError`, by the fields of the PostgreSQL error it carries, for a driver to reject with.
  *
  * An error that kern-db has already classified returns as it is.
- * An error without a severity or a SQLSTATE, such as of a client that lost its connection, is a `ConnectionError`, and so is one of severity `FATAL` or `PANIC`, which ends the session.
+ * An error without a severity or a SQLSTATE, such as of a client that lost its connection, is a `ConnectionError`, and so is one of severity `FATAL` or `PANIC`, which ends the session; it gets `unsent` of `fields`.
  * An error of severity `ERROR` is a `QueryError`.
  * With a translated severity, the SQLSTATE tells an error that ends the session, so a few errors of other codes that end it give `QueryError`.
  */
@@ -365,10 +378,9 @@ export declare class TransactionConnectionError extends ConnectionError {
  *
  * - `TransactionConnectionError` of phase `commit` gives `true`, since `COMMIT` may have succeeded.
  * - `TransactionConnectionError` of another phase gives `false`, since the transaction was not committed.
+ * - A `ConnectionError` whose `unsent` is `true`, such as after a failure to get a connection or of a closed driver, gives `false`, since the statement was not sent.
  * - Another `ConnectionError` gives `true`, since a statement outside a transaction may have run before its connection failed.
  * - Any other error gives `false`, such as a `QueryError`, or a `ResultDecodeError` of a statement that has run: `false` does not mean that the operation applied nothing.
- *
- * Classification depends only on the error class, so failures before the statement was sent, such as a failure to acquire a connection, also give `true`.
  */
 export declare function isOutcomeUnknown(error: unknown): boolean;
 export { type AcceptedNull, type AcceptedValues, type AnyDerivableType, type AnySqlQuery, type AnyType, type BaseDerivableType, type Connection, type Database, type DatabaseOptions, type DecodedFields, type DerivableType, type DerivableTypeWithParameters, type Driver, type DriverErrorFields, type DriverResult, type FieldTypes, type InitialSqlQueryState, type IsolationLevel, NotFoundError, type OneRow, type OneValueRows, type PollLockOptions, type QueryErrorCode, type QueryErrorCondition, type ResultByRows, ResultDecodeError, type ResultRows, type SessionOptions, type SqlFragment, type SqlQuery, type SqlQueryResult, type SqlQueryState, type SqlStatement, type SqlValue, type TextValue, type TransactionOptions, type Type, type TypeInput, type TypeOptions, type TypeOutput, type TypeTransform, type UntypedValue, type ValueRows, createDatabase, createStatement, defineType, identifier, isDatabase, isDriver, isType, param, sql, type typeValues };

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-26zcdHeU.mjs";
-import { a as TransactionConnectionError, i as isQueryError, o as isOutcomeUnknown, r as isDatabase, t as createDatabase } from "./database-0i2749JZ.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-C3LR3pFV.mjs";
 export { ConnectionError, NotFoundError, QueryError, ResultDecodeError, TransactionConnectionError, createDatabase, createStatement, defineType, identifier, isDatabase, isDriver, isOutcomeUnknown, isQueryError, isType, param, sql, toDriverError };

package/dist/node-postgres.d.mts

@@ -1,4 +1,4 @@
-import { n as Driver } from "./driver-CSfbXOBJ.mjs";
+import { n as Driver } from "./driver-CZCBkque.mjs";
 import { Pool } from "pg";
 /**
  * Creates a kern-db driver over a node-postgres pool; the pool keeps managing its connections.

package/dist/node-postgres.mjs

@@ -1,4 +1,4 @@
-import { a as toDriverError, n as QueryError, t as ConnectionError } from "./driver-error-26zcdHeU.mjs";
+import { a as toDriverError, n as QueryError, t as ConnectionError } from "./driver-error-D8D4UQ4F.mjs";
 // src/drivers/node-postgres.ts
 /** Parsers of a query that keep every value as its text, whatever parsers the client has. */
 const textTypes = { getTypeParser: () => (value) => value };
@@ -89,21 +89,25 @@ function nodePostgresDriver(pool) {
 	function endCheckout() {
 		if (--checkouts === 0) drained?.resolve();
 	}
-	/** Gets a client from the pool for `operation`, which names it in the error once closing starts. */
+	/**
+	* Gets a client from the pool for `operation`, which names it in the error once closing starts.
+	*
+	* Its errors have `unsent`: the statement waits for the client, so nothing is sent before it.
+	*/
 	async function checkOut(operation) {
-		if (closing) throw new ConnectionError(`Cannot ${operation}: the driver is closed`);
+		if (closing) throw new ConnectionError(`Cannot ${operation}: the driver is closed`, { unsent: true });
 		checkouts++;
 		try {
 			const client = await pool.connect();
 			const unsupported = getUnsupportedClientReason(client);
 			if (unsupported) {
 				client.release();
-				throw new ConnectionError(unsupported);
+				throw new ConnectionError(unsupported, { unsent: true });
 			}
 			return client;
 		} catch (error) {
 			endCheckout();
-			throw toDriverError(error);
+			throw toDriverError(error, { unsent: true });
 		}
 	}
 	/** Returns a client to the pool, which closes it with `destroy` or when its connection is lost. */

package/dist/postgres-js.d.mts

@@ -1,4 +1,4 @@
-import { n as Driver } from "./driver-CSfbXOBJ.mjs";
+import { n as Driver } from "./driver-CZCBkque.mjs";
 import { Sql } from "postgres";
 /**
  * Creates a kern-db driver over a postgres.js client; the client keeps managing its pool.

package/dist/postgres-js.mjs

@@ -1,14 +1,40 @@
-import { a as toDriverError, t as ConnectionError } from "./driver-error-26zcdHeU.mjs";
+import { a as toDriverError, t as ConnectionError } from "./driver-error-D8D4UQ4F.mjs";
 // src/drivers/postgres-js.ts
 /** OID of the PostgreSQL `unknown` pseudo-type; postgres.js sends such parameters as they are, and PostgreSQL infers their types. */
 const unknownType = 705;
+/**
+* Codes of the errors that postgres.js 4 gives a statement only before it sends the statement.
+*
+* A statement on the pool waits for a connection that has started, and postgres.js rejects the waiting statements with the error of a failed start.
+* The list has no code that a statement that postgres.js sent can also get:
+*
+* - `CONNECTION_CLOSED` and `CONNECTION_DESTROYED`, which a statement gets when its connection fails;
+* - a SQLSTATE of the server, even of a failed start, such as `3D000` of a missing database: a sent statement gets its own `FATAL` error, and a function can raise one of any code, such as with `plpy.fatal` of PL/Python.
+*/
+const unsentCodes = /* @__PURE__ */ new Set([
+	"QUEUE_TIMEOUT",
+	"CONNECTION_ENDED",
+	"MAX_PARAMETERS_EXCEEDED",
+	"ECONNREFUSED",
+	"ENOTFOUND",
+	"EAI_AGAIN",
+	"CONNECT_TIMEOUT",
+	"SSL_NOT_SUPPORTED",
+	"AUTHENTICATION_INCOMPLETE",
+	"AUTH_TYPE_NOT_IMPLEMENTED",
+	"SASL_MECHANISM_NOT_SUPPORTED",
+	"SASL_NONCE_MISMATCH",
+	"SASL_SIGNATURE_MISMATCH",
+	"CHANNEL_BINDING_REQUIRED"
+]);
 /** Classifies an error of a statement of postgres.js, which gives the severity in English as `severity`, and the constraint as `constraint_name`. */
 function toPostgresJsError(error) {
 	const fields = error ?? {};
 	return toDriverError(error, {
 		severity: fields.severity,
 		code: fields.code,
-		constraint: fields.constraint_name
+		constraint: fields.constraint_name,
+		unsent: unsentCodes.has(fields.code)
 	});
 }
 /**
@@ -52,7 +78,7 @@ function postgresJsDriver(sql) {
 	* `sql.end()` ends the pool only after a few microtasks, and the pool still queues and runs a statement sent before then.
 	*/
 	function assertOpen(operation) {
-		if (closing) throw new ConnectionError(`Cannot ${operation}: the driver is closed`);
+		if (closing) throw new ConnectionError(`Cannot ${operation}: the driver is closed`, { unsent: true });
 	}
 	return {
 		async execute(statement) {
@@ -69,7 +95,7 @@ function postgresJsDriver(sql) {
 			try {
 				connection = await sql.reserve();
 			} catch (error) {
-				throw toDriverError(error);
+				throw toDriverError(error, { unsent: true });
 			}
 			return {
 				execute: (statement) => execute(connection, statement),

package/dist/{query-BrvYBvWC.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-CSfbXOBJ.mjs";
-import { c as Type, d as TypeOutput, i as AnyType } from "./type-CbrtxvDF.mjs";
+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-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-CSfbXOBJ.mjs";
-import { f as IsolationLevel, u as Database } from "./query-BrvYBvWC.mjs";
+import { n as Driver, t as Connection } from "./driver-CZCBkque.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. */
@@ -82,6 +136,8 @@ interface DriverContractOptions {
   }): Driver;
   /** Creates a driver over a new client of the test database whose parsers of result values throw; for a client without parsers, the same as `createDriver`. */
   createDriverWithFailingParsers(): Driver;
+  /** Creates a driver over a new client of an address where no server accepts connections, such as a closed port of the local host, which refuses them at once. */
+  createUnreachableDriver(): Driver;
 }
 /**
  * Functions of a test runner that declare the tests of `describeDriverContract`.
@@ -124,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-26zcdHeU.mjs";
-import { a as TransactionConnectionError, n as getCoordinator, s as pause, t as createDatabase } from "./database-0i2749JZ.mjs";
+import { n as QueryError, t as ConnectionError } from "./driver-error-D8D4UQ4F.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) {
@@ -51,6 +121,14 @@ function createStatementRunners(target) {
 		}
 	};
 }
+/** Asserts that `promise` rejects with a `ConnectionError` of a statement that the driver did not send. */
+async function assertRejectsUnsent(promise) {
+	await assert.rejects(promise, (error) => {
+		assert.ok(error instanceof ConnectionError, `Expected ConnectionError, got ${String(error)}`);
+		assert.equal(error.unsent, true, `Expected unsent ConnectionError, got ${String(error)}`);
+		return true;
+	});
+}
 /** Creates the condition that each column named by a key of `types` equals the value of the key in `values`, as a parameter of its type. */
 function equalsEach(types, values) {
 	let condition = sql`TRUE`;
@@ -63,7 +141,7 @@ function equalsEach(types, values) {
 * They run in the empty database of its clients and leave it unchanged.
 */
 function describeDriverContract(options, runner) {
-	const { createDriver, createDriverWithFailingParsers } = options;
+	const { createDriver, createDriverWithFailingParsers, createUnreachableDriver } = options;
 	const { describe, it, before, after } = runner;
 	describe("driver contract", () => {
 		const driver = createDriver({ max: 2 });
@@ -423,6 +501,26 @@ function describeDriverContract(options, runner) {
 				await own.close();
 			}
 		});
+		it("rejects a statement whose connection is lost while it runs with unsent false", async () => {
+			const own = createDriver({ max: 1 });
+			try {
+				const error = await own.execute(createStatement("SELECT pg_terminate_backend(pg_backend_pid())")).catch((error) => error);
+				assert.ok(error instanceof ConnectionError, `Expected ConnectionError, got ${String(error)}`);
+				assert.equal(error.unsent, false);
+			} finally {
+				await own.close();
+			}
+		});
+		it("rejects a statement, a script, and a connection without a server with unsent ConnectionError", async () => {
+			const unreachable = createUnreachableDriver();
+			try {
+				await assertRejectsUnsent(unreachable.execute(createStatement("SELECT 1")));
+				await assertRejectsUnsent(unreachable.executeScript("SELECT 1"));
+				await assertRejectsUnsent(unreachable.acquire());
+			} finally {
+				await unreachable.close();
+			}
+		});
 		it("replaces an idle connection whose backend exited", async () => {
 			const own = createDriver({ max: 2 });
 			const held = [];
@@ -530,15 +628,15 @@ function describeDriverContract(options, runner) {
 				assert.equal(await query, "slept");
 				assert.deepEqual(settled, ["query", "database"]);
 			});
-			it("rejects a statement, a script, and a connection requested right after it starts with ConnectionError", async () => {
+			it("rejects a statement, a script, and a connection requested right after it starts with unsent ConnectionError", async () => {
 				const driver = createDriver({ max: 1 });
 				const held = await driver.acquire();
 				const closing = driver.close();
 				const acquiring = driver.acquire();
 				const rejections = [
-					assert.rejects(driver.execute(createStatement("SELECT 1")), ConnectionError),
-					assert.rejects(driver.executeScript("SELECT 1"), ConnectionError),
-					assert.rejects(acquiring, ConnectionError)
+					assertRejectsUnsent(driver.execute(createStatement("SELECT 1"))),
+					assertRejectsUnsent(driver.executeScript("SELECT 1")),
+					assertRejectsUnsent(acquiring)
 				];
 				acquiring.then((connection) => connection.release()).catch(() => {});
 				await held.release();
@@ -814,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.3.0",
+  "version": "0.5.0",
   "description": "PostgreSQL database layer with ambient transactions, typed SQL queries, and test transactions",
   "keywords": [
     "database",