@kern-orm/node-postgres 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ilya Semenov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,22 @@
-# Temporary Holding Version
+# @kern-orm/node-postgres
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[node-postgres](https://node-postgres.com/) driver for [kern-orm](https://github.com/IlyaSemenov/kern-orm).
+
+## Install
+
+```sh
+npm install kern-orm @kern-orm/node-postgres pg
+npm install --save-dev @types/pg
+```
+
+## Usage
+
+```ts
+import { nodePostgresDriver } from "@kern-orm/node-postgres"
+import { createDatabase } from "kern-orm"
+import { Pool } from "pg"
+
+const database = createDatabase({
+  driver: nodePostgresDriver(new Pool({ connectionString: process.env.DATABASE_URL })),
+})
+```

package/dist/index.d.mts

@@ -0,0 +1,8 @@
+import { Driver } from "kern-orm";
+import { Pool } from "pg";
+/**
+ * Creates a kern-orm driver over a node-postgres pool; the pool keeps managing its connections.
+ *
+ * Closing the driver ends the supplied pool.
+ */
+export declare function nodePostgresDriver(pool: Pool): Driver;

package/dist/index.mjs

@@ -0,0 +1,131 @@
+// src/driver.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() {}
+/** Handler of the outcome of a statement that the queue of a connection waits for without reading it. */
+function ignoreOutcome() {}
+/**
+* Tells whether PostgreSQL rejected a statement and keeps its connection, such as for a violated constraint.
+*
+* After other failures, such as `query_timeout`, the statement may still run, or the connection is closing.
+* A server with translated messages reports a translated severity, so its connection closes, which only costs a reconnect.
+*/
+function isRejectedStatement(error) {
+	return error.severity === "ERROR";
+}
+async function execute(client, statement) {
+	const config = {
+		text: statement.text,
+		values: statement.parameters,
+		rowMode: "array",
+		types: textTypes,
+		queryMode: "extended"
+	};
+	const result = await client.query(config);
+	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) {
+	await client.query({
+		text,
+		rowMode: "array",
+		types: textTypes
+	});
+}
+/**
+* Creates a kern-orm 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();
+	}
+	async function checkOut() {
+		if (closing) throw new Error("Cannot acquire a connection: the driver is closed");
+		checkouts++;
+		try {
+			const client = await pool.connect();
+			const unsupported = getUnsupportedClientReason(client);
+			if (unsupported) {
+				client.release();
+				throw new Error(unsupported);
+			}
+			return client;
+		} catch (error) {
+			endCheckout();
+			throw 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. */
+	async function runOnPool(run) {
+		const client = await checkOut();
+		let destroy = false;
+		try {
+			return await run(client);
+		} catch (error) {
+			destroy = !isRejectedStatement(error);
+			throw error;
+		} finally {
+			checkIn(client, destroy);
+		}
+	}
+	async function endPool() {
+		if (checkouts > 0) {
+			drained = Promise.withResolvers();
+			await drained.promise;
+		}
+		await pool.end();
+	}
+	return {
+		execute: (statement) => runOnPool((client) => execute(client, statement)),
+		executeScript: (text) => runOnPool((client) => executeScript(client, text)),
+		async acquire() {
+			const client = await checkOut();
+			let last = Promise.resolve();
+			function enqueue(run) {
+				const result = last.then(run);
+				last = result.then(ignoreOutcome, ignoreOutcome);
+				return result;
+			}
+			return {
+				execute: (statement) => enqueue(() => execute(client, statement)),
+				executeScript: (text) => enqueue(() => executeScript(client, text)),
+				release: (failure) => checkIn(client, failure !== void 0)
+			};
+		},
+		close() {
+			closing ??= endPool();
+			return closing;
+		}
+	};
+}
+export { nodePostgresDriver };

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@kern-orm/node-postgres",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "node-postgres driver for kern-orm",
+  "keywords": [
+    "driver",
+    "kern-orm",
+    "node-postgres",
+    "pg",
+    "postgres",
+    "postgresql"
+  ],
+  "homepage": "https://ilyasemenov.github.io/kern-orm/",
+  "bugs": "https://github.com/IlyaSemenov/kern-orm/issues",
+  "license": "MIT",
+  "author": "Ilya Semenov",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/IlyaSemenov/kern-orm.git",
+    "directory": "packages/node-postgres"
+  },
+  "files": [
+    "README.md",
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "prepublishOnly": "bun run build"
+  },
+  "devDependencies": {
+    "@types/pg": "^8.23.1",
+    "kern-orm": "workspace:*",
+    "pg": "^8.23.1"
+  },
+  "peerDependencies": {
+    "@types/pg": "^8.0.0",
+    "kern-orm": ">=0.2.0 <1",
+    "pg": "^8.23.1"
+  },
+  "peerDependenciesMeta": {
+    "@types/pg": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "bun": ">=1.4",
+    "node": ">=24"
+  }
+}