kern-db 0.0.0-stage → 0.2.0

package/dist/node-postgres.mjs

@@ -0,0 +1,177 @@
+import { a as toDriverError, n as QueryError, t as ConnectionError } from "./driver-error-26zcdHeU.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 };
+/**
+* Returns why the driver cannot read the values of a client as text, if it cannot.
+*
+* `pg` sets `native` and `binary` on a client, though its types omit them.
+*/
+function getUnsupportedClientReason(client) {
+	if (client.native) return "nodePostgresDriver requires the JavaScript client: create the pool with pg, not pg.native";
+	if (client.binary) return "nodePostgresDriver requires text results: disable binary in the options of the pool and in pg.defaults";
+}
+/** Listener of the `error` event of a pool or a client, for a connection whose loss needs no handling at the event; an `EventEmitter` throws an `error` event without a listener, which terminates the process. */
+function ignoreConnectionError() {}
+/** Transaction status that `getTransactionStatus` of `pg` gives for a connection outside a transaction block. */
+const idleStatus = "I";
+/** Query that runs no statement, also in a failed transaction, and completes after the statements sent before it. */
+const emptyQuery = { text: "" };
+/**
+* Tells whether a client is outside a transaction block after its last statement.
+*
+* `pg` rejects a statement at the ErrorResponse of PostgreSQL, before the ReadyForQuery that reports the status of the transaction, so after a statement that PostgreSQL rejected, which `rejected` tells, an empty query waits for that report.
+* It returns `false` when the empty query fails, since the status cannot be trusted then.
+*/
+async function isIdle(client, rejected) {
+	if (rejected) try {
+		await client.query(emptyQuery);
+	} catch {
+		return false;
+	}
+	return client.getTransactionStatus() === idleStatus;
+}
+/**
+* Classifies an error of a statement of `pg`, which gives the severity only in the language of the server.
+*
+* With translated messages, `toDriverError` tells an error that ends the session by its SQLSTATE.
+*/
+function toNodePostgresError(error) {
+	return toDriverError(error, error ?? {});
+}
+async function execute(client, statement) {
+	const config = {
+		text: statement.text,
+		values: statement.parameters,
+		rowMode: "array",
+		types: textTypes,
+		queryMode: "extended"
+	};
+	let result;
+	try {
+		result = await client.query(config);
+	} catch (error) {
+		throw toNodePostgresError(error);
+	}
+	const { fields } = result;
+	const columns = [];
+	for (let index = 0; index < fields.length; index++) columns.push(fields[index].name);
+	return {
+		command: result.command,
+		count: result.rowCount ?? 0,
+		columns,
+		rows: result.rows
+	};
+}
+async function executeScript(client, text) {
+	try {
+		await client.query({
+			text,
+			rowMode: "array",
+			types: textTypes
+		});
+	} catch (error) {
+		throw toNodePostgresError(error);
+	}
+}
+/**
+* Creates a kern-db driver over a node-postgres pool; the pool keeps managing its connections.
+*
+* Closing the driver ends the supplied pool.
+*/
+function nodePostgresDriver(pool) {
+	let checkouts = 0;
+	let drained;
+	let closing;
+	pool.on("error", ignoreConnectionError);
+	pool.on("acquire", (client) => client.on("error", ignoreConnectionError));
+	pool.on("release", (_error, client) => client.off("error", ignoreConnectionError));
+	function endCheckout() {
+		if (--checkouts === 0) drained?.resolve();
+	}
+	/** Gets a client from the pool for `operation`, which names it in the error once closing starts. */
+	async function checkOut(operation) {
+		if (closing) throw new ConnectionError(`Cannot ${operation}: the driver is closed`);
+		checkouts++;
+		try {
+			const client = await pool.connect();
+			const unsupported = getUnsupportedClientReason(client);
+			if (unsupported) {
+				client.release();
+				throw new ConnectionError(unsupported);
+			}
+			return client;
+		} catch (error) {
+			endCheckout();
+			throw toDriverError(error);
+		}
+	}
+	/** Returns a client to the pool, which closes it with `destroy` or when its connection is lost. */
+	function checkIn(client, destroy) {
+		client.release(destroy);
+		endCheckout();
+	}
+	/**
+	* Runs a statement or a `script` on a client of its own, unlike `pool.query`, which closes the connection of any failed statement.
+	*
+	* `pg` returns a client to the pool whatever its transaction, so the driver closes a connection that is not idle after it, and rejects a statement or script that leaves a transaction open.
+	*/
+	async function runOnPool(operation, script, run) {
+		const client = await checkOut(operation);
+		let result;
+		try {
+			result = await run(client);
+		} catch (error) {
+			checkIn(client, !(error instanceof QueryError && (!script || await isIdle(client, true))));
+			throw error;
+		}
+		if (client.getTransactionStatus() !== idleStatus) {
+			checkIn(client, true);
+			throw new ConnectionError(`Cannot ${operation} that leaves a transaction open on a pooled connection: the driver closed the connection to roll the transaction back; use $transaction of a Db or transaction of the database instead`);
+		}
+		checkIn(client, false);
+		return result;
+	}
+	async function endPool() {
+		if (checkouts > 0) {
+			drained = Promise.withResolvers();
+			await drained.promise;
+		}
+		await pool.end();
+	}
+	return {
+		execute: (statement) => runOnPool("execute a statement", false, (client) => execute(client, statement)),
+		executeScript: (text) => runOnPool("execute a script", true, (client) => executeScript(client, text)),
+		async acquire() {
+			const client = await checkOut("acquire a connection");
+			let last = Promise.resolve();
+			let broken = false;
+			let rejected = false;
+			const onCompleted = () => {
+				rejected = false;
+			};
+			const onFailed = (error) => {
+				if (error instanceof QueryError) rejected = true;
+				else broken = true;
+			};
+			function enqueue(run) {
+				const result = last.then(run);
+				last = result.then(onCompleted, onFailed);
+				return result;
+			}
+			return {
+				execute: (statement) => enqueue(() => execute(client, statement)),
+				executeScript: (text) => enqueue(() => executeScript(client, text)),
+				async release() {
+					await last;
+					checkIn(client, broken || !await isIdle(client, rejected));
+				}
+			};
+		},
+		close() {
+			closing ??= endPool();
+			return closing;
+		}
+	};
+}
+export { nodePostgresDriver };

package/dist/postgres-js.d.mts

@@ -0,0 +1,9 @@
+import { n as Driver } from "./driver-CSfbXOBJ.mjs";
+import { Sql } from "postgres";
+/**
+ * Creates a kern-db driver over a postgres.js client; the client keeps managing its pool.
+ *
+ * It throws a `TypeError` for a client that transforms the column names or rows of results, such as with `postgres.camel`.
+ * Closing the driver ends the supplied client.
+ */
+export declare function postgresJsDriver(sql: Sql): Driver;

package/dist/postgres-js.mjs

@@ -0,0 +1,86 @@
+import { a as toDriverError, t as ConnectionError } from "./driver-error-26zcdHeU.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;
+/** 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
+	});
+}
+/**
+* Creates a kern-db driver over a postgres.js client; the client keeps managing its pool.
+*
+* It throws a `TypeError` for a client that transforms the column names or rows of results, such as with `postgres.camel`.
+* Closing the driver ends the supplied client.
+*/
+function postgresJsDriver(sql) {
+	const { column, row } = sql.options.transform;
+	if (column.from !== void 0 || row.from !== void 0) throw new TypeError("Cannot create a driver of a postgres.js client that transforms the column names or rows of results, such as with postgres.camel: kern-db reads results as PostgreSQL returns them");
+	let closing;
+	async function execute(client, statement) {
+		const parameters = statement.parameters.map((value) => sql.typed(value, unknownType));
+		let rows;
+		try {
+			rows = await client.unsafe(statement.text, parameters, { simple: false }).raw();
+		} catch (error) {
+			throw toPostgresJsError(error);
+		}
+		const { columns } = rows;
+		const names = [];
+		for (let index = 0; index < columns.length; index++) names.push(columns[index].name);
+		return {
+			command: rows.command,
+			count: rows.count ?? 0,
+			columns: names,
+			rows: rows.map((row) => row.map((value) => value === null ? null : value.toString("utf8")))
+		};
+	}
+	async function executeScript(client, text) {
+		try {
+			await client.unsafe(text).simple().raw();
+		} catch (error) {
+			throw toPostgresJsError(error);
+		}
+	}
+	/**
+	* Throws once closing starts.
+	*
+	* `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`);
+	}
+	return {
+		async execute(statement) {
+			assertOpen("execute a statement");
+			return execute(sql, statement);
+		},
+		async executeScript(text) {
+			assertOpen("execute a script");
+			return executeScript(sql, text);
+		},
+		async acquire() {
+			assertOpen("acquire a connection");
+			let connection;
+			try {
+				connection = await sql.reserve();
+			} catch (error) {
+				throw toDriverError(error);
+			}
+			return {
+				execute: (statement) => execute(connection, statement),
+				executeScript: (text) => executeScript(connection, text),
+				release: () => connection.release()
+			};
+		},
+		close() {
+			closing ??= sql.end();
+			return closing;
+		}
+	};
+}
+export { postgresJsDriver };