@juit/pgproxy-client 1.0.0

package/README.md

@@ -0,0 +1,136 @@
+# PostgreSQL Proxy Client (Base Package)
+
+This package provides the main entry point for clients to work with PGProxy
+Servers. It acts both as an abstraction layer over the various client
+implementations _and_ as a registry for them.
+
+* [Connecting](#connecting)
+* [Client](#client)
+* [PGProxy](https://github.com/juitnow/juit-pgproxy/blob/main/README.md)
+* [Copyright Notice](https://github.com/juitnow/juit-pgproxy/blob/main/NOTICE.md)
+* [License](https://github.com/juitnow/juit-pgproxy/blob/main/NOTICE.md)
+
+### Connecting
+
+In the code, you can simply depend on the `PGClient` class:
+
+```ts
+import { PGClient } from '@juit/pgproxy-client'
+
+const client = new PGClient()
+```
+
+The client can be constructed with a `url` as a parameter, indicating the
+endpoint of the connection _and_ the specific client to be used. If no such
+parameter is specified, the value of the `PGURL` environment variable will be
+used.
+
+Additionally if the URL specified at construction (or in the `PGURL` environment
+variable) does not provide ANY authentication information, the `PGUSER` and
+`PGPASSWORD` environment variables will be used to fill in those details.
+
+Specific implementations are registered by simply importing their library:
+
+* `@juit/pgproxy-client-node`: The HTTP client for NodeJS \
+  handles URLs like: `http(s)://secret@host:port/`
+* `@juit/pgproxy-client-whatwg`: The HTTP client for WhatWG + WebCrypto \
+  handles URLs like: `http(s)://secret@host:port/`
+* `@juit/pgproxy-client-psql`: The direct LibPQ-based client \
+  handles URLs like: `psql://usrname:password@host:port/database`
+
+The ability to abstract client and connection details allows the code to be
+as portable as possible. For example in an AWS Lambda Function:
+
+```ts
+// Entry point for AWS Lambda functions
+
+// Import the _node_ client, the PGURL environment variable comes from the
+// Lambda definitions and can be specified via the AWS console, it will have
+// a format like: https://my-secret@my-ec2-instance:54321/
+import '@pgproxy/client-node'
+
+export const handler = async (event: LambdaEvent) => {
+  // ... use code that connects to the database using `new PGClient()`
+}
+```
+
+Similarly, when running a test requiring a connection to a _local_ database
+(no need to spin up a whole PGProxy Server to test):
+
+```ts
+// Entry point for tests
+
+// Import the _psql_ client, which will be registered as a handler for the
+// "psql" protocol in PGClient
+import '@pgproxy/client-psql'
+
+beforeAll(() => {
+  process.env.PGURL = "psql://username:password@localhost:5432/my-database"
+})
+
+it('should run tests connecting to the database', async () => {
+  // ... test the code using `new PGCLient()`
+})
+```
+
+### Client
+
+Simple queries can be executed on the database via the `query(...)` method:
+
+```ts
+const client = new PGClient()
+const result = await client.query('SELECT * FROM test WHERE value = $1', [ 'theValue' ])
+```
+
+More complex queries (e.g. transactions) can be performed using the
+`connect(...)` method:
+
+```ts
+const client = new PGClient()
+// here "result" will be the value returned by the callback passed to "connect"
+const result = await client.connect(async (connection) => {
+  await connection.begin()
+
+  await connection.query(...) // ... all transaction queries
+
+  await connection.commit()
+  return result // returned to whatever is awaiting on "connect"
+})
+```
+
+The `query(...)` method requires one parameter, the SQL query to run, and allows
+parameters (as an array) to be declared as a second, optional parameter.
+
+The object passed to the `connect(...)` callback provides the following methods:
+
+* `query(...)`: as above
+* `begin()`: issues the `BEGIN` SQL statement (starts a transaction)
+* `commit()`: issues the `COMMIT` SQL statement (commits a transaction)
+* `rollback()`: issues the `ROLLBACK` SQL statement (rolls back a transaction)
+
+Uncommitted transactions will always be rolled back by the connection pool code.
+
+### Result
+
+The result returned by the `query(...)` method is a simple object containing:
+
+* `command` (_string_): The SQL command that generated this result (e.g.
+  `SELECT`, `INSERT`, ...)
+* `rowCount` (_number_): The number of rows affected by the query. \
+  This can be the number of lines returned in `rows` (for `SELECT`
+  statements, for example) or the number of lines _affected_ by the query
+  (the number of records inserted by an `INSERT` query).
+* `rows` (_Record<string, any>[]_): The rows returned by the database query,
+  keyed by the column name.
+* `tuples` (_any[][]_): The tuples returned by the database query, keyed by
+  the column index. */
+
+
+### Types
+
+Each client exposes its own _types registry_ in the `registry` field.
+
+By manipulating the registry, one can tweak the conversion of PostgreSQL types
+to JavaScript types.
+
+For more informations see the `@juit/pgproxy-types` package.

package/dist/assert.cjs

@@ -0,0 +1,34 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// assert.ts
+var assert_exports = {};
+__export(assert_exports, {
+  assert: () => assert
+});
+module.exports = __toCommonJS(assert_exports);
+function assert(what, message) {
+  if (!what)
+    throw new Error(message);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  assert
+});
+//# sourceMappingURL=assert.cjs.map

package/dist/assert.cjs.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../src/assert.ts"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AACO,SAAS,OAAO,MAAe,SAA+B;AACnE,MAAI,CAAE;AAAM,UAAM,IAAI,MAAM,OAAO;AACrC;",
+  "names": []
+}

package/dist/assert.d.ts

@@ -0,0 +1,2 @@
+/** The easiest assertion function in the world */
+export declare function assert(what: unknown, message: string): asserts what;

package/dist/assert.mjs

@@ -0,0 +1,9 @@
+// assert.ts
+function assert(what, message) {
+  if (!what)
+    throw new Error(message);
+}
+export {
+  assert
+};
+//# sourceMappingURL=assert.mjs.map

package/dist/assert.mjs.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../src/assert.ts"],
+  "mappings": ";AACO,SAAS,OAAO,MAAe,SAA+B;AACnE,MAAI,CAAE;AAAM,UAAM,IAAI,MAAM,OAAO;AACrC;",
+  "names": []
+}

package/dist/client.cjs

@@ -0,0 +1,97 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// client.ts
+var client_exports = {};
+__export(client_exports, {
+  PGClient: () => PGClient
+});
+module.exports = __toCommonJS(client_exports);
+var import_pgproxy_types = require("@juit/pgproxy-types");
+var import_assert = require("./assert.cjs");
+var import_provider = require("./provider.cjs");
+var import_result = require("./result.cjs");
+function serializeParams(params) {
+  if (params.length == 0)
+    return [];
+  const result = new Array(params.length);
+  for (let i = 0; i < params.length; i++) {
+    result[i] = params[i] === void 0 ? null : params[i] === null ? null : (0, import_pgproxy_types.serialize)(params[i]);
+  }
+  return result;
+}
+var PGClient = class PGClientImpl {
+  registry = new import_pgproxy_types.Registry();
+  _provider;
+  constructor(urlOrProvider) {
+    urlOrProvider = urlOrProvider || globalThis?.process?.env?.PGURL;
+    (0, import_assert.assert)(urlOrProvider, "No URL to connect to (PGURL environment variable missing?)");
+    if (typeof urlOrProvider === "string")
+      urlOrProvider = new URL(urlOrProvider, "psql:///");
+    (0, import_assert.assert)(urlOrProvider, "Missing URL or provider for client");
+    if (urlOrProvider instanceof URL) {
+      if (!(urlOrProvider.username || urlOrProvider.password)) {
+        const username = globalThis?.process?.env?.PGUSER || "";
+        const password = globalThis?.process?.env?.PGPASSWORD || "";
+        urlOrProvider.username = encodeURIComponent(username);
+        urlOrProvider.password = encodeURIComponent(password);
+      }
+    }
+    this._provider = urlOrProvider instanceof URL ? (0, import_provider.createProvider)(urlOrProvider) : urlOrProvider;
+  }
+  async query(text, params = []) {
+    const result = await this._provider.query(text, serializeParams(params));
+    return new import_result.PGResult(result, this.registry);
+  }
+  async connect(consumer) {
+    const connection = await this._provider.acquire();
+    try {
+      const registry = this.registry;
+      const consumable = {
+        async query(text, params = []) {
+          const result = await connection.query(text, serializeParams(params));
+          return new import_result.PGResult(result, registry);
+        },
+        async begin() {
+          await this.query("BEGIN");
+          return this;
+        },
+        async commit() {
+          await this.query("COMMIT");
+          return this;
+        },
+        async rollback() {
+          await this.query("ROLLBACK");
+          return this;
+        }
+      };
+      return await consumer(consumable);
+    } finally {
+      await this._provider.release(connection);
+    }
+  }
+  async destroy() {
+    return await this._provider.destroy();
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PGClient
+});
+//# sourceMappingURL=client.cjs.map

package/dist/client.cjs.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../src/client.ts"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,2BAAoC;AAEpC,oBAAuB;AACvB,sBAA+B;AAC/B,oBAAyB;AAIzB,SAAS,gBAAgB,QAAkC;AACzD,MAAI,OAAO,UAAU;AAAG,WAAO,CAAC;AAEhC,QAAM,SAA4B,IAAI,MAAM,OAAO,MAAM;AACzD,WAAS,IAAI,GAAG,IAAI,OAAO,QAAQ,KAAM;AACvC,WAAO,CAAC,IACN,OAAO,CAAC,MAAM,SAAY,OAC1B,OAAO,CAAC,MAAM,OAAO,WACrB,gCAAU,OAAO,CAAC,CAAC;AAAA,EACvB;AAEA,SAAO;AACT;AA+EO,IAAM,WAAgC,MAAM,aAAiC;AAAA,EACzE,WAAqB,IAAI,8BAAS;AAAA,EAEnC;AAAA,EAIR,YAAY,eAAyD;AACnE,oBAAgB,iBAAiB,YAAY,SAAS,KAAK;AAC3D,8BAAO,eAAe,4DAA4D;AAClF,QAAI,OAAO,kBAAkB;AAAU,sBAAgB,IAAI,IAAI,eAAe,UAAU;AACxF,8BAAO,eAAe,oCAAoC;AAE1D,QAAI,yBAAyB,KAAK;AAChC,UAAI,EAAE,cAAc,YAAY,cAAc,WAAW;AACvD,cAAM,WAAW,YAAY,SAAS,KAAK,UAAU;AACrD,cAAM,WAAW,YAAY,SAAS,KAAK,cAAc;AACzD,sBAAc,WAAW,mBAAmB,QAAQ;AACpD,sBAAc,WAAW,mBAAmB,QAAQ;AAAA,MACtD;AAAA,IACF;AAEA,SAAK,YAAY,yBAAyB,UACtC,gCAAe,aAAa,IAC5B;AAAA,EACN;AAAA,EAEA,MAAM,MAGJ,MAAc,SAAgB,CAAC,GAAkC;AACjE,UAAM,SAAS,MAAM,KAAK,UAAU,MAAM,MAAM,gBAAgB,MAAM,CAAC;AACvE,WAAO,IAAI,uBAAqB,QAAQ,KAAK,QAAQ;AAAA,EACvD;AAAA,EAEA,MAAM,QAAW,UAAqC;AACpD,UAAM,aAAa,MAAM,KAAK,UAAU,QAAQ;AAEhD,QAAI;AACF,YAAM,WAAW,KAAK;AAEtB,YAAM,aAAgC;AAAA,QACpC,MAAM,MAGJ,MAAc,SAAgB,CAAC,GAAkC;AACjE,gBAAM,SAAS,MAAM,WAAW,MAAM,MAAM,gBAAgB,MAAM,CAAC;AACnE,iBAAO,IAAI,uBAAS,QAAQ,QAAQ;AAAA,QACtC;AAAA,QACA,MAAM,QAAoC;AACxC,gBAAM,KAAK,MAAM,OAAO;AACxB,iBAAO;AAAA,QACT;AAAA,QACA,MAAM,SAAqC;AACzC,gBAAM,KAAK,MAAM,QAAQ;AACzB,iBAAO;AAAA,QACT;AAAA,QACA,MAAM,WAAuC;AAC3C,gBAAM,KAAK,MAAM,UAAU;AAC3B,iBAAO;AAAA,QACT;AAAA,MACF;AAEA,aAAO,MAAM,SAAS,UAAU;AAAA,IAClC,UAAE;AACA,YAAM,KAAK,UAAU,QAAQ,UAAU;AAAA,IACzC;AAAA,EACF;AAAA,EAEA,MAAM,UAAyB;AAC7B,WAAO,MAAM,KAAK,UAAU,QAAQ;AAAA,EACtC;AACF;",
+  "names": []
+}

package/dist/client.d.ts

@@ -0,0 +1,67 @@
+/// <reference types="node" />
+import { Registry } from '@juit/pgproxy-types';
+import { PGResult } from './result';
+import type { PGConnection, PGProvider } from './provider';
+/** An interface for an object that can execute queries on a database */
+export interface PGQueryable {
+    /**
+     * Execute a query on the database
+     *
+     * @param text - The SQL query to execute optionally containing placeholders.
+     * @param params - Any parameter replacement for `$x` placeholders.
+     */
+    query<Row extends Record<string, any> = Record<string, any>, Tuple extends readonly any[] = readonly any[]>(text: string, params?: any[]): Promise<PGResult<Row, Tuple>>;
+}
+/**
+ * An interface for an object that can execute queries _and transactions_
+ * on a database */
+export interface PGTransactionable extends PGQueryable {
+    /** Start a transaction by issuing a `BEGIN` statement */
+    begin(): Promise<this>;
+    /** Commit a transaction by issuing a `COMMIT` statement */
+    commit(): Promise<this>;
+    /** Cancel a transaction by issuing a `ROLLBACK` statement */
+    rollback(): Promise<this>;
+}
+/** A consumer for a {@link PGTransactionable} connection */
+export type PGConsumer<T> = (connection: PGTransactionable) => T | PromiseLike<T>;
+/** The PostgreSQL client */
+export interface PGClient extends PGQueryable {
+    /** The {@link @juit/pgproxy-types#Registry} used to parse results from PostgreSQL */
+    readonly registry: Registry;
+    /**
+     * Execute a _single_ query on the database.
+     *
+     * Invoking the `query` method on a {@link (PGClient:interface)} does NOT guarantee that
+     * the query will be executed on the same connection, therefore things like
+     * _transactions_ will be immediately rolled back after the query.
+     *
+     * @param text - The SQL query to execute optionally containing placeholders.
+     * @param params - Any parameter replacement for `$x` placeholders.
+     */
+    query<Row extends Record<string, any> = Record<string, any>, Tuple extends readonly any[] = readonly any[]>(text: string, params?: any[]): Promise<PGResult<Row, Tuple>>;
+    /**
+     * Connect to the database to execute a number of different queries.
+     *
+     * The `consumer` will be passed a {@link PGTransactionable} instance backed
+     * by the _same_ connection to the database, therefore transactions can be
+     * safely executed in the context of the consumer function itself.
+     */
+    connect<T>(consumer: PGConsumer<T>): Promise<T>;
+    /**
+     * Destroy any resource and underlying connection associated with this
+     * instance's {@link PGProvider}.
+     */
+    destroy(): Promise<void>;
+}
+/** A constructor for {@link (PGClient:interface)} instances */
+export interface PGClientConstructor {
+    new (url?: string | URL): PGClient;
+    new (provider: PGProvider<PGConnection>): PGClient;
+}
+/**
+ * The PostgreSQL client
+ *
+ * @constructor
+ */
+export declare const PGClient: PGClientConstructor;

package/dist/client.mjs

@@ -0,0 +1,72 @@
+// client.ts
+import { Registry, serialize } from "@juit/pgproxy-types";
+import { assert } from "./assert.mjs";
+import { createProvider } from "./provider.mjs";
+import { PGResult } from "./result.mjs";
+function serializeParams(params) {
+  if (params.length == 0)
+    return [];
+  const result = new Array(params.length);
+  for (let i = 0; i < params.length; i++) {
+    result[i] = params[i] === void 0 ? null : params[i] === null ? null : serialize(params[i]);
+  }
+  return result;
+}
+var PGClient = class PGClientImpl {
+  registry = new Registry();
+  _provider;
+  constructor(urlOrProvider) {
+    urlOrProvider = urlOrProvider || globalThis?.process?.env?.PGURL;
+    assert(urlOrProvider, "No URL to connect to (PGURL environment variable missing?)");
+    if (typeof urlOrProvider === "string")
+      urlOrProvider = new URL(urlOrProvider, "psql:///");
+    assert(urlOrProvider, "Missing URL or provider for client");
+    if (urlOrProvider instanceof URL) {
+      if (!(urlOrProvider.username || urlOrProvider.password)) {
+        const username = globalThis?.process?.env?.PGUSER || "";
+        const password = globalThis?.process?.env?.PGPASSWORD || "";
+        urlOrProvider.username = encodeURIComponent(username);
+        urlOrProvider.password = encodeURIComponent(password);
+      }
+    }
+    this._provider = urlOrProvider instanceof URL ? createProvider(urlOrProvider) : urlOrProvider;
+  }
+  async query(text, params = []) {
+    const result = await this._provider.query(text, serializeParams(params));
+    return new PGResult(result, this.registry);
+  }
+  async connect(consumer) {
+    const connection = await this._provider.acquire();
+    try {
+      const registry = this.registry;
+      const consumable = {
+        async query(text, params = []) {
+          const result = await connection.query(text, serializeParams(params));
+          return new PGResult(result, registry);
+        },
+        async begin() {
+          await this.query("BEGIN");
+          return this;
+        },
+        async commit() {
+          await this.query("COMMIT");
+          return this;
+        },
+        async rollback() {
+          await this.query("ROLLBACK");
+          return this;
+        }
+      };
+      return await consumer(consumable);
+    } finally {
+      await this._provider.release(connection);
+    }
+  }
+  async destroy() {
+    return await this._provider.destroy();
+  }
+};
+export {
+  PGClient
+};
+//# sourceMappingURL=client.mjs.map

package/dist/client.mjs.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../src/client.ts"],
+  "mappings": ";AAAA,SAAS,UAAU,iBAAiB;AAEpC,SAAS,cAAc;AACvB,SAAS,sBAAsB;AAC/B,SAAS,gBAAgB;AAIzB,SAAS,gBAAgB,QAAkC;AACzD,MAAI,OAAO,UAAU;AAAG,WAAO,CAAC;AAEhC,QAAM,SAA4B,IAAI,MAAM,OAAO,MAAM;AACzD,WAAS,IAAI,GAAG,IAAI,OAAO,QAAQ,KAAM;AACvC,WAAO,CAAC,IACN,OAAO,CAAC,MAAM,SAAY,OAC1B,OAAO,CAAC,MAAM,OAAO,OACrB,UAAU,OAAO,CAAC,CAAC;AAAA,EACvB;AAEA,SAAO;AACT;AA+EO,IAAM,WAAgC,MAAM,aAAiC;AAAA,EACzE,WAAqB,IAAI,SAAS;AAAA,EAEnC;AAAA,EAIR,YAAY,eAAyD;AACnE,oBAAgB,iBAAiB,YAAY,SAAS,KAAK;AAC3D,WAAO,eAAe,4DAA4D;AAClF,QAAI,OAAO,kBAAkB;AAAU,sBAAgB,IAAI,IAAI,eAAe,UAAU;AACxF,WAAO,eAAe,oCAAoC;AAE1D,QAAI,yBAAyB,KAAK;AAChC,UAAI,EAAE,cAAc,YAAY,cAAc,WAAW;AACvD,cAAM,WAAW,YAAY,SAAS,KAAK,UAAU;AACrD,cAAM,WAAW,YAAY,SAAS,KAAK,cAAc;AACzD,sBAAc,WAAW,mBAAmB,QAAQ;AACpD,sBAAc,WAAW,mBAAmB,QAAQ;AAAA,MACtD;AAAA,IACF;AAEA,SAAK,YAAY,yBAAyB,MACtC,eAAe,aAAa,IAC5B;AAAA,EACN;AAAA,EAEA,MAAM,MAGJ,MAAc,SAAgB,CAAC,GAAkC;AACjE,UAAM,SAAS,MAAM,KAAK,UAAU,MAAM,MAAM,gBAAgB,MAAM,CAAC;AACvE,WAAO,IAAI,SAAqB,QAAQ,KAAK,QAAQ;AAAA,EACvD;AAAA,EAEA,MAAM,QAAW,UAAqC;AACpD,UAAM,aAAa,MAAM,KAAK,UAAU,QAAQ;AAEhD,QAAI;AACF,YAAM,WAAW,KAAK;AAEtB,YAAM,aAAgC;AAAA,QACpC,MAAM,MAGJ,MAAc,SAAgB,CAAC,GAAkC;AACjE,gBAAM,SAAS,MAAM,WAAW,MAAM,MAAM,gBAAgB,MAAM,CAAC;AACnE,iBAAO,IAAI,SAAS,QAAQ,QAAQ;AAAA,QACtC;AAAA,QACA,MAAM,QAAoC;AACxC,gBAAM,KAAK,MAAM,OAAO;AACxB,iBAAO;AAAA,QACT;AAAA,QACA,MAAM,SAAqC;AACzC,gBAAM,KAAK,MAAM,QAAQ;AACzB,iBAAO;AAAA,QACT;AAAA,QACA,MAAM,WAAuC;AAC3C,gBAAM,KAAK,MAAM,UAAU;AAC3B,iBAAO;AAAA,QACT;AAAA,MACF;AAEA,aAAO,MAAM,SAAS,UAAU;AAAA,IAClC,UAAE;AACA,YAAM,KAAK,UAAU,QAAQ,UAAU;AAAA,IACzC;AAAA,EACF;AAAA,EAEA,MAAM,UAAyB;AAC7B,WAAO,MAAM,KAAK,UAAU,QAAQ;AAAA,EACtC;AACF;",
+  "names": []
+}

package/dist/index.cjs

@@ -0,0 +1,33 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// index.ts
+var src_exports = {};
+module.exports = __toCommonJS(src_exports);
+__reExport(src_exports, require("./assert.cjs"), module.exports);
+__reExport(src_exports, require("./client.cjs"), module.exports);
+__reExport(src_exports, require("./provider.cjs"), module.exports);
+__reExport(src_exports, require("./result.cjs"), module.exports);
+__reExport(src_exports, require("./websocket.cjs"), module.exports);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ...require("./assert.cjs"),
+  ...require("./client.cjs"),
+  ...require("./provider.cjs"),
+  ...require("./result.cjs"),
+  ...require("./websocket.cjs")
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../src/index.ts"],
+  "mappings": ";;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA,wBAAc,yBAAd;AACA,wBAAc,yBADd;AAEA,wBAAc,2BAFd;AAGA,wBAAc,yBAHd;AAIA,wBAAc,4BAJd;",
+  "names": []
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from './assert';
+export * from './client';
+export * from './provider';
+export * from './result';
+export * from './websocket';

package/dist/index.mjs

@@ -0,0 +1,7 @@
+// index.ts
+export * from "./assert.mjs";
+export * from "./client.mjs";
+export * from "./provider.mjs";
+export * from "./result.mjs";
+export * from "./websocket.mjs";
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../src/index.ts"],
+  "mappings": ";AAAA,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;",
+  "names": []
+}

package/dist/provider.cjs

@@ -0,0 +1,59 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// provider.ts
+var provider_exports = {};
+__export(provider_exports, {
+  AbstractPGProvider: () => AbstractPGProvider,
+  createProvider: () => createProvider,
+  registerProvider: () => registerProvider
+});
+module.exports = __toCommonJS(provider_exports);
+var import_assert = require("./assert.cjs");
+var AbstractPGProvider = class {
+  async query(text, params) {
+    const connection = await this.acquire();
+    try {
+      return await connection.query(text, params);
+    } finally {
+      await this.release(connection);
+    }
+  }
+  async destroy() {
+  }
+};
+var providers = /* @__PURE__ */ new Map();
+function registerProvider(protocol, constructor) {
+  protocol = `${protocol}:`;
+  (0, import_assert.assert)(!providers.has(protocol), `Connection provider for "${protocol}..." already registered`);
+  providers.set(protocol, constructor);
+  providers.set(protocol, constructor);
+}
+function createProvider(url) {
+  const Provider = providers.get(url.protocol);
+  (0, import_assert.assert)(Provider, `No connection provider registered for "${url.protocol}..."`);
+  return new Provider(url);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AbstractPGProvider,
+  createProvider,
+  registerProvider
+});
+//# sourceMappingURL=provider.cjs.map

package/dist/provider.cjs.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../src/provider.ts"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,oBAAuB;AAqChB,IAAe,qBAAf,MAC2B;AAAA,EAIhC,MAAM,MAAM,MAAc,QAA+C;AACvE,UAAM,aAAa,MAAM,KAAK,QAAQ;AACtC,QAAI;AACF,aAAO,MAAM,WAAW,MAAM,MAAM,MAAM;AAAA,IAC5C,UAAE;AACA,YAAM,KAAK,QAAQ,UAAU;AAAA,IAC/B;AAAA,EACF;AAAA,EAEA,MAAM,UAAyB;AAAA,EAE/B;AACF;AAOA,IAAM,YAAY,oBAAI,IAAiD;AAGhE,SAAS,iBACZ,UACA,aACI;AACN,aAAW,GAAG,QAAQ;AACtB,4BAAO,CAAE,UAAU,IAAI,QAAQ,GAAG,4BAA4B,QAAQ,yBAAyB;AAC/F,YAAU,IAAI,UAAU,WAAW;AACnC,YAAU,IAAI,UAAU,WAAW;AACrC;AAGO,SAAS,eAAe,KAAoC;AACjE,QAAM,WAAW,UAAU,IAAI,IAAI,QAAQ;AAC3C,4BAAO,UAAU,0CAA0C,IAAI,QAAQ,MAAM;AAC7E,SAAO,IAAI,SAAS,GAAG;AACzB;",
+  "names": []
+}

package/dist/provider.d.ts

@@ -0,0 +1,33 @@
+/// <reference types="node" />
+/** Describes the result of a query from a {@link PGProvider} */
+export interface PGConnectionResult {
+    /** The SQL command that generated this result (`SELECT`, `INSERT`, ...) */
+    command: string;
+    /** Number of rows affected by this query (e.g. added rows in `INSERT`) */
+    rowCount: number;
+    /** Fields description with `name` (column name) and `oid` (type) */
+    fields: [name: string, oid: number][];
+    /** Result rows, as an array of unparsed `string` results from `libpq` */
+    rows: (string | null)[][];
+}
+export interface PGConnection {
+    query(text: string, params: (string | null)[]): Promise<PGConnectionResult>;
+}
+export interface PGProviderConstructor<Connection extends PGConnection> {
+    new (url: URL): PGProvider<Connection>;
+}
+export interface PGProvider<Connection extends PGConnection> extends PGConnection {
+    acquire(): Promise<Connection>;
+    release(connection: Connection): Promise<void>;
+    destroy(): Promise<void>;
+}
+export declare abstract class AbstractPGProvider<Connection extends PGConnection> implements PGProvider<Connection> {
+    abstract acquire(): Promise<Connection>;
+    abstract release(connection: PGConnection): Promise<void>;
+    query(text: string, params: string[]): Promise<PGConnectionResult>;
+    destroy(): Promise<void>;
+}
+/** Register a provider, associating it with the specified protocol */
+export declare function registerProvider(protocol: string, constructor: PGProviderConstructor<PGConnection>): void;
+/** Create a new {@link PGProvider} instance for the specified URL */
+export declare function createProvider(url: URL): PGProvider<PGConnection>;

package/dist/provider.mjs

@@ -0,0 +1,32 @@
+// provider.ts
+import { assert } from "./assert.mjs";
+var AbstractPGProvider = class {
+  async query(text, params) {
+    const connection = await this.acquire();
+    try {
+      return await connection.query(text, params);
+    } finally {
+      await this.release(connection);
+    }
+  }
+  async destroy() {
+  }
+};
+var providers = /* @__PURE__ */ new Map();
+function registerProvider(protocol, constructor) {
+  protocol = `${protocol}:`;
+  assert(!providers.has(protocol), `Connection provider for "${protocol}..." already registered`);
+  providers.set(protocol, constructor);
+  providers.set(protocol, constructor);
+}
+function createProvider(url) {
+  const Provider = providers.get(url.protocol);
+  assert(Provider, `No connection provider registered for "${url.protocol}..."`);
+  return new Provider(url);
+}
+export {
+  AbstractPGProvider,
+  createProvider,
+  registerProvider
+};
+//# sourceMappingURL=provider.mjs.map

package/dist/provider.mjs.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../src/provider.ts"],
+  "mappings": ";AAAA,SAAS,cAAc;AAqChB,IAAe,qBAAf,MAC2B;AAAA,EAIhC,MAAM,MAAM,MAAc,QAA+C;AACvE,UAAM,aAAa,MAAM,KAAK,QAAQ;AACtC,QAAI;AACF,aAAO,MAAM,WAAW,MAAM,MAAM,MAAM;AAAA,IAC5C,UAAE;AACA,YAAM,KAAK,QAAQ,UAAU;AAAA,IAC/B;AAAA,EACF;AAAA,EAEA,MAAM,UAAyB;AAAA,EAE/B;AACF;AAOA,IAAM,YAAY,oBAAI,IAAiD;AAGhE,SAAS,iBACZ,UACA,aACI;AACN,aAAW,GAAG,QAAQ;AACtB,SAAO,CAAE,UAAU,IAAI,QAAQ,GAAG,4BAA4B,QAAQ,yBAAyB;AAC/F,YAAU,IAAI,UAAU,WAAW;AACnC,YAAU,IAAI,UAAU,WAAW;AACrC;AAGO,SAAS,eAAe,KAAoC;AACjE,QAAM,WAAW,UAAU,IAAI,IAAI,QAAQ;AAC3C,SAAO,UAAU,0CAA0C,IAAI,QAAQ,MAAM;AAC7E,SAAO,IAAI,SAAS,GAAG;AACzB;",
+  "names": []
+}