kern-db 0.2.0 → 0.3.0

package/dist/{database-BkWPkXG5.mjs → database-0i2749JZ.mjs}

@@ -210,6 +210,23 @@ var TransactionConnectionError = class TransactionConnectionError extends Connec
 	}
 };
 /**
+* Tells whether the outcome of an operation that rejected with `error` is unknown, since its connection failed.
+*
+* Pass it the error that a whole operation rejected with: `execute` or `query` of a database outside a transaction, a statement in a session, or a whole `transaction`.
+* A `ConnectionError` of a statement caught in the callback of a transaction is not such an error: the transaction rolls back anyway, and its own error tells its outcome.
+*
+* - `TransactionConnectionError` of phase `commit` gives `true`, since `COMMIT` may have succeeded.
+* - `TransactionConnectionError` of another phase gives `false`, since the transaction was not committed.
+* - 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`.
+*/
+function isOutcomeUnknown(error) {
+	if (error instanceof TransactionConnectionError) return error.phase === "commit";
+	return error instanceof ConnectionError;
+}
+/**
 * Reserved connection of a transaction of `transaction` that records the first `ConnectionError` of its statements and scripts, including those of its nested levels.
 *
 * A failure before `COMMIT` is sent makes the transaction roll back rather than commit, since the statement may not have run.
@@ -1467,4 +1484,4 @@ function createDatabase({ driver, ...options }) {
 	coordinators.set(database, coordinator);
 	return database;
 }
-export { TransactionConnectionError as a, isQueryError as i, getCoordinator as n, isDatabase as r, createDatabase as t };
+export { TransactionConnectionError as a, isQueryError as i, getCoordinator as n, isOutcomeUnknown as o, isDatabase as r, pause as s, createDatabase as t };

package/dist/index.d.mts

@@ -357,4 +357,18 @@ export declare class TransactionConnectionError extends ConnectionError {
   /** Tells whether `value` is an instance of the class, including one of `TransactionConnectionError` of another copy of kern-db. */
   static [Symbol.hasInstance]<T>(this: abstract new (...args: never) => T, value: unknown): value is T;
 }
+/**
+ * Tells whether the outcome of an operation that rejected with `error` is unknown, since its connection failed.
+ *
+ * Pass it the error that a whole operation rejected with: `execute` or `query` of a database outside a transaction, a statement in a session, or a whole `transaction`.
+ * A `ConnectionError` of a statement caught in the callback of a transaction is not such an error: the transaction rolls back anyway, and its own error tells its outcome.
+ *
+ * - `TransactionConnectionError` of phase `commit` gives `true`, since `COMMIT` may have succeeded.
+ * - `TransactionConnectionError` of another phase gives `false`, since the transaction was not committed.
+ * - 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, r as isDatabase, t as createDatabase } from "./database-BkWPkXG5.mjs";
-export { ConnectionError, NotFoundError, QueryError, ResultDecodeError, TransactionConnectionError, createDatabase, createStatement, defineType, identifier, isDatabase, isDriver, isQueryError, isType, param, sql, toDriverError };
+import { a as TransactionConnectionError, i as isQueryError, o as isOutcomeUnknown, r as isDatabase, t as createDatabase } from "./database-0i2749JZ.mjs";
+export { ConnectionError, NotFoundError, QueryError, ResultDecodeError, TransactionConnectionError, createDatabase, createStatement, defineType, identifier, isDatabase, isDriver, isOutcomeUnknown, isQueryError, isType, param, sql, toDriverError };

package/dist/testing.d.mts

@@ -1,4 +1,4 @@
-import { n as Driver } from "./driver-CSfbXOBJ.mjs";
+import { n as Driver, t as Connection } from "./driver-CSfbXOBJ.mjs";
 import { f as IsolationLevel, u as Database } from "./query-BrvYBvWC.mjs";
 /** Test fixture of `useTestFixture`, open while the tests of its `describe` block or test file run. */
 interface TestFixture<T = unknown> {
@@ -98,4 +98,30 @@ interface DriverContractRunner extends TestHooks {
  * They run in the empty database of its clients and leave it unchanged.
  */
 export declare function describeDriverContract(options: DriverContractOptions, runner: DriverContractRunner): void;
-export type { DriverContractOptions, DriverContractRunner, OpenedTestFixture, PendingTestFixture, TestFixture, TestFixtureOptions, TestHelpers, TestHooks, TestTransactionOptions };
+/** Options of `waitForLock` and `waitForLockedStatement`. */
+interface LockWaitOptions {
+  /** Milliseconds to wait before rejecting; 2000 by default, shorter than the default timeout of a test, so that the helper rejects with its own error. */
+  timeout?: number;
+}
+/**
+ * Resolves to the process ID of the backend of PostgreSQL that runs the statements of `target`, `pg_backend_pid()`.
+ *
+ * Call it on the connection that will wait for a lock, such as inside its transaction or session: on the pool of a database or a driver, it gives the backend of whichever connection runs the statement.
+ */
+export declare function getBackendPid(target: Pick<Connection, "execute">): Promise<number>;
+/**
+ * Waits until the backend `pid` waits for a lock, such as of a row or an advisory lock that another transaction holds, and rejects when it does not in time.
+ *
+ * `observer` runs the checks: a database, a driver, or a connection other than the one that waits.
+ * It reads the locks with `pg_blocking_pids`, which reads the current lock state even inside a transaction.
+ */
+export declare function waitForLock(observer: Pick<Connection, "execute">, pid: number, options?: LockWaitOptions): Promise<void>;
+/**
+ * Waits until a backend of the current database other than that of `observer` waits for a lock in a statement whose text contains `fragment`, and resolves to its backend PID.
+ *
+ * It finds a backend that the test does not know, such as one of the pool of the code under test.
+ * `observer` runs the checks: a database, a driver, or a connection other than the one that waits.
+ * 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 };

package/dist/testing.mjs

@@ -1,7 +1,7 @@
 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, t as createDatabase } from "./database-BkWPkXG5.mjs";
+import { a as TransactionConnectionError, n as getCoordinator, s as pause, t as createDatabase } from "./database-0i2749JZ.mjs";
 import { t as array } from "./array-BLt8ZNR5.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";
@@ -738,4 +738,80 @@ function describeDriverContract(options, runner) {
 		});
 	});
 }
-export { createTestHelpers, describeDriverContract };
+// src/lock-wait.ts
+/** Time that the helpers wait by default, in milliseconds. */
+const defaultTimeout = 2e3;
+/** Pause between two checks in milliseconds, so that waiting does not keep the observer busy. */
+const pollInterval = 5;
+/**
+* Resolves to the process ID of the backend of PostgreSQL that runs the statements of `target`, `pg_backend_pid()`.
+*
+* Call it on the connection that will wait for a lock, such as inside its transaction or session: on the pool of a database or a driver, it gives the backend of whichever connection runs the statement.
+*/
+async function getBackendPid(target) {
+	const { rows } = await target.execute(createStatement("SELECT pg_backend_pid()"));
+	return Number(rows[0][0]);
+}
+/**
+* Waits until the backend `pid` waits for a lock, such as of a row or an advisory lock that another transaction holds, and rejects when it does not in time.
+*
+* `observer` runs the checks: a database, a driver, or a connection other than the one that waits.
+* It reads the locks with `pg_blocking_pids`, which reads the current lock state even inside a transaction.
+*/
+async function waitForLock(observer, pid, options = {}) {
+	const timeout = options.timeout ?? defaultTimeout;
+	const statement = createStatement("SELECT cardinality(pg_blocking_pids($1::integer)) > 0", [String(pid)]);
+	await poll(timeout, `Backend ${pid} did not wait for a lock within ${timeout} ms`, async () => {
+		const { rows } = await observer.execute(statement);
+		return rows[0][0] === "t" ? true : void 0;
+	});
+}
+/**
+* Waits until a backend of the current database other than that of `observer` waits for a lock in a statement whose text contains `fragment`, and resolves to its backend PID.
+*
+* It finds a backend that the test does not know, such as one of the pool of the code under test.
+* `observer` runs the checks: a database, a driver, or a connection other than the one that waits.
+* It rejects when no such backend waits in time.
+*/
+async function waitForLockedStatement(observer, fragment, options = {}) {
+	const timeout = options.timeout ?? defaultTimeout;
+	const clearSnapshot = createStatement("SELECT pg_stat_clear_snapshot()");
+	const statement = createStatement(`SELECT pid FROM pg_stat_activity
+    WHERE datname = current_database() AND pid <> pg_backend_pid()
+      AND position($1::text IN query) > 0 AND cardinality(pg_blocking_pids(pid)) > 0
+    ORDER BY pid LIMIT 1`, [fragment]);
+	return await poll(timeout, `No statement with "${fragment}" waited for a lock within ${timeout} ms`, async (isWaiting) => {
+		await observer.execute(clearSnapshot);
+		if (!isWaiting()) return;
+		const { rows } = await observer.execute(statement);
+		return rows.length > 0 ? Number(rows[0][0]) : void 0;
+	});
+}
+/**
+* Calls `check` until it resolves to a value other than `undefined`, pausing between the calls, and resolves to that value.
+*
+* It rejects with `message` once `timeout` passes, also while a check still runs, such as on a pool that has no free connection; such a check settles without the helper.
+* A check must send no further statement once `isWaiting` returns `false`.
+*/
+async function poll(timeout, message, check) {
+	let waiting = true;
+	const isWaiting = () => waiting;
+	let timer;
+	const expired = new Promise((_, reject) => {
+		timer = setTimeout(() => {
+			waiting = false;
+			reject(new Error(message));
+		}, timeout);
+	});
+	try {
+		for (;;) {
+			const value = await Promise.race([check(isWaiting), expired]);
+			if (value !== void 0) return value;
+			await Promise.race([pause(pollInterval, void 0), expired]);
+		}
+	} finally {
+		waiting = false;
+		clearTimeout(timer);
+	}
+}
+export { createTestHelpers, describeDriverContract, getBackendPid, waitForLock, waitForLockedStatement };

package/package.json

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