@juit/pgproxy-client 1.2.1 → 1.3.0

package/README.md

@@ -86,7 +86,23 @@ const result = await client.query('SELECT * FROM test WHERE value = $1', [ 'theV
 ```
 
 More complex queries (e.g. transactions) can be performed using the
-`connect(...)` method:
+_connection_ returned by the `connect()` method:
+
+```ts
+const client = new PGClient()
+
+await using connection = await client.connect() // the "connection" is AsyncDisposable
+
+await connection.begin() // ... begin transaction
+await connection.query(...) // ... all transaction queries
+await connection.commit() // ... commit transaction, or "rollback()"
+
+// if not declaring with "async using" connections can be closed manually:
+//
+// await connection.close()
+```
+
+Or using a _connection consumer_:
 
 ```ts
 const client = new PGClient()
@@ -109,7 +125,8 @@ A second form of the `query(...)` function accepts an object with two keys:
 * `query`: the SQL query to execute optionally containing placeholders
 * `params`: any parameter replacement for `$x` placeholders
 
-The object passed to the `connect(...)` callback provides the following methods:
+When used with callbacks, the object passed to the `connect(...)` callback
+provides the following methods:
 
 * `query(...)`: as above
 * `begin()`: issues the `BEGIN` SQL statement (starts a transaction)
@@ -118,6 +135,10 @@ The object passed to the `connect(...)` callback provides the following methods:
 
 Uncommitted transactions will always be rolled back by the connection pool code.
 
+Otherwise, when using `connect()` without callbacks, the returned _connection_
+will be `AsyncDisposable`, and (if not using `async using`) can be manually
+disposed of calling the `close()` function.
+
 ### Result
 
 The result returned by the `query(...)` method is a simple object containing:

package/dist/client.cjs

@@ -3,6 +3,10 @@ var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __knownSymbol = (name, symbol) => (symbol = Symbol[name]) ? symbol : Symbol.for("Symbol." + name);
+var __typeError = (msg) => {
+  throw TypeError(msg);
+};
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
@@ -16,6 +20,47 @@ var __copyProps = (to, from, except, desc) => {
   return to;
 };
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var __using = (stack, value, async) => {
+  if (value != null) {
+    if (typeof value !== "object" && typeof value !== "function") __typeError("Object expected");
+    var dispose, inner;
+    if (async) dispose = value[__knownSymbol("asyncDispose")];
+    if (dispose === void 0) {
+      dispose = value[__knownSymbol("dispose")];
+      if (async) inner = dispose;
+    }
+    if (typeof dispose !== "function") __typeError("Object not disposable");
+    if (inner) dispose = function() {
+      try {
+        inner.call(this);
+      } catch (e) {
+        return Promise.reject(e);
+      }
+    };
+    stack.push([async, dispose, value]);
+  } else if (async) {
+    stack.push([async]);
+  }
+  return value;
+};
+var __callDispose = (stack, error, hasError) => {
+  var E = typeof SuppressedError === "function" ? SuppressedError : function(e, s, m, _) {
+    return _ = Error(m), _.name = "SuppressedError", _.error = e, _.suppressed = s, _;
+  };
+  var fail = (e) => error = hasError ? new E(e, error, "An error was suppressed during disposal") : (hasError = true, e);
+  var next = (it) => {
+    while (it = stack.pop()) {
+      try {
+        var result = it[1] && it[1].call(it[2]);
+        if (it[0]) return Promise.resolve(result).then(next, (e) => (fail(e), next()));
+      } catch (e) {
+        fail(e);
+      }
+    }
+    if (hasError) throw error;
+  };
+  return next();
+};
 
 // client.ts
 var client_exports = {};
@@ -36,62 +81,115 @@ function serializeParams(params) {
   return result;
 }
 var PGClient = class PGClientImpl {
-  registry = new import_pgproxy_types.Registry();
+  _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)) {
+  constructor(arg) {
+    arg = arg || globalThis?.process?.env?.PGURL;
+    (0, import_assert.assert)(arg, "No URL to connect to (PGURL environment variable missing?)");
+    if (typeof arg === "string") arg = new URL(arg, "psql:///");
+    (0, import_assert.assert)(arg, "Missing URL or provider for client");
+    if ("href" in arg) {
+      if (!(arg.username || arg.password)) {
         const username = globalThis?.process?.env?.PGUSER || "";
         const password = globalThis?.process?.env?.PGPASSWORD || "";
-        urlOrProvider.username = encodeURIComponent(username);
-        urlOrProvider.password = encodeURIComponent(password);
+        arg.username = encodeURIComponent(username);
+        arg.password = encodeURIComponent(password);
+      }
+      this._provider = (0, import_provider.createProvider)(arg);
+    } else if ("query" in arg && "acquire" in arg && "release" in arg) {
+      this._provider = arg;
+    } else {
+      const {
+        protocol = "psql",
+        database = "",
+        username = globalThis?.process?.env?.PGUSER,
+        password = globalThis?.process?.env?.PGPASSWORD,
+        host = "localhost",
+        port,
+        parameters = {}
+      } = arg;
+      const url = new URL(`${protocol}://`);
+      if (host) url.hostname = host;
+      if (port) url.port = String(port);
+      if (username) url.username = encodeURIComponent(username);
+      if (password) url.password = encodeURIComponent(password);
+      url.pathname = `/${database}`;
+      for (const [key, value] of Object.entries(parameters)) {
+        url.searchParams.set(key, String(value));
       }
+      this._provider = (0, import_provider.createProvider)(url);
     }
-    this._provider = urlOrProvider instanceof URL ? (0, import_provider.createProvider)(urlOrProvider) : urlOrProvider;
+  }
+  get registry() {
+    return this._registry;
+  }
+  get url() {
+    return this._provider.url;
   }
   async query(textOrQuery, maybeParams = []) {
     const [text, params = []] = typeof textOrQuery === "string" ? [textOrQuery, maybeParams] : [textOrQuery.query, textOrQuery.params];
     const result = await this._provider.query(text, serializeParams(params));
-    return new import_result.PGResult(result, this.registry);
+    return new import_result.PGResult(result, this._registry);
   }
   async connect(consumer) {
     const connection = await this._provider.acquire();
-    let transaction = false;
-    try {
-      const registry = this.registry;
-      const consumable = {
-        async query(textOrQuery, maybeParams = []) {
-          const [text, params = []] = typeof textOrQuery === "string" ? [textOrQuery, maybeParams] : [textOrQuery.query, textOrQuery.params];
-          const result = await connection.query(text, serializeParams(params));
-          return new import_result.PGResult(result, registry);
-        },
-        async begin() {
-          if (transaction) return false;
-          await connection.query("BEGIN");
-          return transaction = true;
-        },
-        async commit() {
-          await connection.query("COMMIT");
-          transaction = false;
-        },
-        async rollback() {
-          await connection.query("ROLLBACK");
-          transaction = false;
-        }
-      };
-      return await consumer(consumable);
-    } finally {
-      if (transaction) await connection.query("ROLLBACK");
-      await this._provider.release(connection);
+    if (!consumer) {
+      return new PGConnectionImpl(connection, this._provider, this._registry);
+    } else {
+      var _stack = [];
+      try {
+        const conn = __using(_stack, new PGConnectionImpl(connection, this._provider, this._registry), true);
+        return await consumer(conn);
+      } catch (_) {
+        var _error = _, _hasError = true;
+      } finally {
+        var _promise = __callDispose(_stack, _error, _hasError);
+        _promise && await _promise;
+      }
     }
   }
   async destroy() {
     return await this._provider.destroy();
   }
+  async [Symbol.asyncDispose]() {
+    await this.destroy();
+  }
+};
+var PGConnectionImpl = class {
+  _transaction = false;
+  _connection;
+  _provider;
+  _registry;
+  constructor(connection, provider, registry) {
+    this._connection = connection;
+    this._provider = provider;
+    this._registry = registry;
+  }
+  async query(textOrQuery, maybeParams = []) {
+    const [text, params = []] = typeof textOrQuery === "string" ? [textOrQuery, maybeParams] : [textOrQuery.query, textOrQuery.params];
+    const result = await this._connection.query(text, serializeParams(params));
+    return new import_result.PGResult(result, this._registry);
+  }
+  async begin() {
+    if (this._transaction) return false;
+    await this._connection.query("BEGIN");
+    return this._transaction = true;
+  }
+  async commit() {
+    await this._connection.query("COMMIT");
+    this._transaction = false;
+  }
+  async rollback() {
+    await this._connection.query("ROLLBACK");
+    this._transaction = false;
+  }
+  async close() {
+    if (this._transaction) await this._connection.query("ROLLBACK");
+    await this._provider.release(this._connection);
+  }
+  [Symbol.asyncDispose]() {
+    return this.close();
+  }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/client.cjs.map

@@ -1,6 +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,QAA2C;AAClE,MAAI,OAAO,UAAU,EAAG,QAAO,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;AAsHO,IAAM,WAAgC,MAAM,aAAiC;AAAA,EACzE,WAAqB,IAAI,8BAAS;AAAA,EAEnC;AAAA,EAIR,YAAY,eAAyD;AACnE,oBAAgB,iBAAmB,YAAoB,SAAS,KAAK;AACrE,8BAAO,eAAe,4DAA4D;AAClF,QAAI,OAAO,kBAAkB,SAAU,iBAAgB,IAAI,IAAI,eAAe,UAAU;AACxF,8BAAO,eAAe,oCAAoC;AAE1D,QAAI,yBAAyB,KAAK;AAChC,UAAI,EAAE,cAAc,YAAY,cAAc,WAAW;AACvD,cAAM,WAAa,YAAoB,SAAS,KAAK,UAAiC;AACtF,cAAM,WAAa,YAAoB,SAAS,KAAK,cAAqC;AAC1F,sBAAc,WAAW,mBAAmB,QAAQ;AACpD,sBAAc,WAAW,mBAAmB,QAAQ;AAAA,MACtD;AAAA,IACF;AAEA,SAAK,YAAY,yBAAyB,UACxC,gCAAe,aAAa,IAC5B;AAAA,EACJ;AAAA,EAaA,MAAM,MAGJ,aAA+B,cAA8B,CAAC,GAAkC;AAChG,UAAM,CAAE,MAAM,SAAS,CAAC,CAAE,IAAI,OAAO,gBAAgB,WACnD,CAAE,aAAa,WAAY,IAAI,CAAE,YAAY,OAAO,YAAY,MAAO;AAGzE,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;AAChD,QAAI,cAAc;AAElB,QAAI;AACF,YAAM,WAAW,KAAK;AAEtB,YAAM,aAAgC;AAAA,QACpC,MAAM,MAGJ,aAA+B,cAA8B,CAAC,GAAkC;AAChG,gBAAM,CAAE,MAAM,SAAS,CAAC,CAAE,IAAI,OAAO,gBAAgB,WACnD,CAAE,aAAa,WAAY,IAAI,CAAE,YAAY,OAAO,YAAY,MAAO;AAEzE,gBAAM,SAAS,MAAM,WAAW,MAAM,MAAM,gBAAgB,MAAM,CAAC;AACnE,iBAAO,IAAI,uBAAS,QAAQ,QAAQ;AAAA,QACtC;AAAA,QACA,MAAM,QAA0B;AAC9B,cAAI,YAAa,QAAO;AACxB,gBAAM,WAAW,MAAM,OAAO;AAC9B,iBAAO,cAAc;AAAA,QACvB;AAAA,QACA,MAAM,SAAwB;AAC5B,gBAAM,WAAW,MAAM,QAAQ;AAC/B,wBAAc;AAAA,QAChB;AAAA,QACA,MAAM,WAA0B;AAC9B,gBAAM,WAAW,MAAM,UAAU;AACjC,wBAAc;AAAA,QAChB;AAAA,MACF;AAEA,aAAO,MAAM,SAAS,UAAU;AAAA,IAClC,UAAE;AACA,UAAI,YAAa,OAAM,WAAW,MAAM,UAAU;AAClD,YAAM,KAAK,UAAU,QAAQ,UAAU;AAAA,IACzC;AAAA,EACF;AAAA,EAEA,MAAM,UAAyB;AAC7B,WAAO,MAAM,KAAK,UAAU,QAAQ;AAAA,EACtC;AACF;",
+  "mappings": "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",
   "names": []
 }

package/dist/client.d.ts

@@ -1,6 +1,28 @@
 import { Registry } from '@juit/pgproxy-types';
 import { PGResult } from './result';
-import type { PGConnection, PGProvider } from './provider';
+import type { PGProvider } from './provider';
+/**
+ * Options to create a `PGClient`
+ *
+ * As an alternative to using URLs, a `PGClient` can be instantiated with
+ * options passed in this object.
+ */
+export interface PGClientOptions {
+    /** The protocol used to connect to the database (defaults to "psql") */
+    readonly protocol?: string;
+    /** The PostgreSQL database to connect to */
+    readonly database?: string;
+    /** The user to authenticate as */
+    readonly username?: string;
+    /** The password to use for authentication */
+    readonly password?: string;
+    /** The host to connect to */
+    readonly host?: string;
+    /** The port to connect to */
+    readonly port?: number;
+    /** Any additional options to pass to the provider */
+    readonly parameters?: Record<string, string | number | boolean>;
+}
 /** An interface representing a SQL query to a database */
 export interface PGQuery {
     /** The SQL query to execute optionally containing placeholders. */
@@ -27,7 +49,8 @@ export interface PGQueryable {
 }
 /**
  * An interface for an object that can execute queries _and transactions_
- * on a database */
+ * on a database
+ */
 export interface PGTransactionable extends PGQueryable {
     /**
      * Start a transaction by issuing a `BEGIN` statement
@@ -41,12 +64,21 @@ export interface PGTransactionable extends PGQueryable {
     /** Cancel a transaction by issuing a `ROLLBACK` statement */
     rollback(): Promise<void>;
 }
+/**
+ * A connection to a database that can be asynchronously disposed of.
+ */
+export interface PGConnection extends PGTransactionable, AsyncDisposable {
+    /** Forcedly close the underlying connection to the database */
+    close(): Promise<void>;
+}
 /** A consumer for a {@link PGTransactionable} connection */
 export type PGConsumer<T> = (connection: PGTransactionable) => T | PromiseLike<T>;
 /** The PostgreSQL client */
-export interface PGClient extends PGQueryable {
+export interface PGClient extends PGQueryable, AsyncDisposable {
     /** The {@link @juit/pgproxy-types#Registry} used to parse results from PostgreSQL */
     readonly registry: Registry;
+    /** The URL used to create this provider, devoid of any credentials */
+    readonly url: Readonly<URL>;
     /**
      * Execute a _single_ query on the database.
      *
@@ -69,6 +101,11 @@ export interface PGClient extends PGQueryable {
      *                related parameters) to execute
      */
     query<Row extends Record<string, any> = Record<string, any>, Tuple extends readonly any[] = readonly any[]>(query: PGQuery): Promise<PGResult<Row, Tuple>>;
+    /**
+     * Connect to the database and return an _async disposable_
+     * {@link PGConnection}.
+     */
+    connect(): Promise<PGConnection>;
     /**
      * Connect to the database to execute a number of different queries.
      *
@@ -86,11 +123,10 @@ export interface PGClient extends PGQueryable {
 /** A constructor for {@link (PGClient:interface)} instances */
 export interface PGClientConstructor {
     new (url?: string | URL): PGClient;
-    new (provider: PGProvider<PGConnection>): PGClient;
+    new (provider: PGProvider): PGClient;
+    new (options: PGClientOptions): PGClient;
 }
 /**
  * The PostgreSQL client
- *
- * @constructor
  */
 export declare const PGClient: PGClientConstructor;

package/dist/client.mjs

@@ -1,3 +1,49 @@
+var __knownSymbol = (name, symbol) => (symbol = Symbol[name]) ? symbol : Symbol.for("Symbol." + name);
+var __typeError = (msg) => {
+  throw TypeError(msg);
+};
+var __using = (stack, value, async) => {
+  if (value != null) {
+    if (typeof value !== "object" && typeof value !== "function") __typeError("Object expected");
+    var dispose, inner;
+    if (async) dispose = value[__knownSymbol("asyncDispose")];
+    if (dispose === void 0) {
+      dispose = value[__knownSymbol("dispose")];
+      if (async) inner = dispose;
+    }
+    if (typeof dispose !== "function") __typeError("Object not disposable");
+    if (inner) dispose = function() {
+      try {
+        inner.call(this);
+      } catch (e) {
+        return Promise.reject(e);
+      }
+    };
+    stack.push([async, dispose, value]);
+  } else if (async) {
+    stack.push([async]);
+  }
+  return value;
+};
+var __callDispose = (stack, error, hasError) => {
+  var E = typeof SuppressedError === "function" ? SuppressedError : function(e, s, m, _) {
+    return _ = Error(m), _.name = "SuppressedError", _.error = e, _.suppressed = s, _;
+  };
+  var fail = (e) => error = hasError ? new E(e, error, "An error was suppressed during disposal") : (hasError = true, e);
+  var next = (it) => {
+    while (it = stack.pop()) {
+      try {
+        var result = it[1] && it[1].call(it[2]);
+        if (it[0]) return Promise.resolve(result).then(next, (e) => (fail(e), next()));
+      } catch (e) {
+        fail(e);
+      }
+    }
+    if (hasError) throw error;
+  };
+  return next();
+};
+
 // client.ts
 import { Registry, serialize } from "@juit/pgproxy-types";
 import { assert } from "./assert.mjs";
@@ -12,62 +58,115 @@ function serializeParams(params) {
   return result;
 }
 var PGClient = class PGClientImpl {
-  registry = new Registry();
+  _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)) {
+  constructor(arg) {
+    arg = arg || globalThis?.process?.env?.PGURL;
+    assert(arg, "No URL to connect to (PGURL environment variable missing?)");
+    if (typeof arg === "string") arg = new URL(arg, "psql:///");
+    assert(arg, "Missing URL or provider for client");
+    if ("href" in arg) {
+      if (!(arg.username || arg.password)) {
         const username = globalThis?.process?.env?.PGUSER || "";
         const password = globalThis?.process?.env?.PGPASSWORD || "";
-        urlOrProvider.username = encodeURIComponent(username);
-        urlOrProvider.password = encodeURIComponent(password);
+        arg.username = encodeURIComponent(username);
+        arg.password = encodeURIComponent(password);
+      }
+      this._provider = createProvider(arg);
+    } else if ("query" in arg && "acquire" in arg && "release" in arg) {
+      this._provider = arg;
+    } else {
+      const {
+        protocol = "psql",
+        database = "",
+        username = globalThis?.process?.env?.PGUSER,
+        password = globalThis?.process?.env?.PGPASSWORD,
+        host = "localhost",
+        port,
+        parameters = {}
+      } = arg;
+      const url = new URL(`${protocol}://`);
+      if (host) url.hostname = host;
+      if (port) url.port = String(port);
+      if (username) url.username = encodeURIComponent(username);
+      if (password) url.password = encodeURIComponent(password);
+      url.pathname = `/${database}`;
+      for (const [key, value] of Object.entries(parameters)) {
+        url.searchParams.set(key, String(value));
       }
+      this._provider = createProvider(url);
     }
-    this._provider = urlOrProvider instanceof URL ? createProvider(urlOrProvider) : urlOrProvider;
+  }
+  get registry() {
+    return this._registry;
+  }
+  get url() {
+    return this._provider.url;
   }
   async query(textOrQuery, maybeParams = []) {
     const [text, params = []] = typeof textOrQuery === "string" ? [textOrQuery, maybeParams] : [textOrQuery.query, textOrQuery.params];
     const result = await this._provider.query(text, serializeParams(params));
-    return new PGResult(result, this.registry);
+    return new PGResult(result, this._registry);
   }
   async connect(consumer) {
     const connection = await this._provider.acquire();
-    let transaction = false;
-    try {
-      const registry = this.registry;
-      const consumable = {
-        async query(textOrQuery, maybeParams = []) {
-          const [text, params = []] = typeof textOrQuery === "string" ? [textOrQuery, maybeParams] : [textOrQuery.query, textOrQuery.params];
-          const result = await connection.query(text, serializeParams(params));
-          return new PGResult(result, registry);
-        },
-        async begin() {
-          if (transaction) return false;
-          await connection.query("BEGIN");
-          return transaction = true;
-        },
-        async commit() {
-          await connection.query("COMMIT");
-          transaction = false;
-        },
-        async rollback() {
-          await connection.query("ROLLBACK");
-          transaction = false;
-        }
-      };
-      return await consumer(consumable);
-    } finally {
-      if (transaction) await connection.query("ROLLBACK");
-      await this._provider.release(connection);
+    if (!consumer) {
+      return new PGConnectionImpl(connection, this._provider, this._registry);
+    } else {
+      var _stack = [];
+      try {
+        const conn = __using(_stack, new PGConnectionImpl(connection, this._provider, this._registry), true);
+        return await consumer(conn);
+      } catch (_) {
+        var _error = _, _hasError = true;
+      } finally {
+        var _promise = __callDispose(_stack, _error, _hasError);
+        _promise && await _promise;
+      }
     }
   }
   async destroy() {
     return await this._provider.destroy();
   }
+  async [Symbol.asyncDispose]() {
+    await this.destroy();
+  }
+};
+var PGConnectionImpl = class {
+  _transaction = false;
+  _connection;
+  _provider;
+  _registry;
+  constructor(connection, provider, registry) {
+    this._connection = connection;
+    this._provider = provider;
+    this._registry = registry;
+  }
+  async query(textOrQuery, maybeParams = []) {
+    const [text, params = []] = typeof textOrQuery === "string" ? [textOrQuery, maybeParams] : [textOrQuery.query, textOrQuery.params];
+    const result = await this._connection.query(text, serializeParams(params));
+    return new PGResult(result, this._registry);
+  }
+  async begin() {
+    if (this._transaction) return false;
+    await this._connection.query("BEGIN");
+    return this._transaction = true;
+  }
+  async commit() {
+    await this._connection.query("COMMIT");
+    this._transaction = false;
+  }
+  async rollback() {
+    await this._connection.query("ROLLBACK");
+    this._transaction = false;
+  }
+  async close() {
+    if (this._transaction) await this._connection.query("ROLLBACK");
+    await this._provider.release(this._connection);
+  }
+  [Symbol.asyncDispose]() {
+    return this.close();
+  }
 };
 export {
   PGClient

package/dist/client.mjs.map

@@ -1,6 +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,QAA2C;AAClE,MAAI,OAAO,UAAU,EAAG,QAAO,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;AAsHO,IAAM,WAAgC,MAAM,aAAiC;AAAA,EACzE,WAAqB,IAAI,SAAS;AAAA,EAEnC;AAAA,EAIR,YAAY,eAAyD;AACnE,oBAAgB,iBAAmB,YAAoB,SAAS,KAAK;AACrE,WAAO,eAAe,4DAA4D;AAClF,QAAI,OAAO,kBAAkB,SAAU,iBAAgB,IAAI,IAAI,eAAe,UAAU;AACxF,WAAO,eAAe,oCAAoC;AAE1D,QAAI,yBAAyB,KAAK;AAChC,UAAI,EAAE,cAAc,YAAY,cAAc,WAAW;AACvD,cAAM,WAAa,YAAoB,SAAS,KAAK,UAAiC;AACtF,cAAM,WAAa,YAAoB,SAAS,KAAK,cAAqC;AAC1F,sBAAc,WAAW,mBAAmB,QAAQ;AACpD,sBAAc,WAAW,mBAAmB,QAAQ;AAAA,MACtD;AAAA,IACF;AAEA,SAAK,YAAY,yBAAyB,MACxC,eAAe,aAAa,IAC5B;AAAA,EACJ;AAAA,EAaA,MAAM,MAGJ,aAA+B,cAA8B,CAAC,GAAkC;AAChG,UAAM,CAAE,MAAM,SAAS,CAAC,CAAE,IAAI,OAAO,gBAAgB,WACnD,CAAE,aAAa,WAAY,IAAI,CAAE,YAAY,OAAO,YAAY,MAAO;AAGzE,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;AAChD,QAAI,cAAc;AAElB,QAAI;AACF,YAAM,WAAW,KAAK;AAEtB,YAAM,aAAgC;AAAA,QACpC,MAAM,MAGJ,aAA+B,cAA8B,CAAC,GAAkC;AAChG,gBAAM,CAAE,MAAM,SAAS,CAAC,CAAE,IAAI,OAAO,gBAAgB,WACnD,CAAE,aAAa,WAAY,IAAI,CAAE,YAAY,OAAO,YAAY,MAAO;AAEzE,gBAAM,SAAS,MAAM,WAAW,MAAM,MAAM,gBAAgB,MAAM,CAAC;AACnE,iBAAO,IAAI,SAAS,QAAQ,QAAQ;AAAA,QACtC;AAAA,QACA,MAAM,QAA0B;AAC9B,cAAI,YAAa,QAAO;AACxB,gBAAM,WAAW,MAAM,OAAO;AAC9B,iBAAO,cAAc;AAAA,QACvB;AAAA,QACA,MAAM,SAAwB;AAC5B,gBAAM,WAAW,MAAM,QAAQ;AAC/B,wBAAc;AAAA,QAChB;AAAA,QACA,MAAM,WAA0B;AAC9B,gBAAM,WAAW,MAAM,UAAU;AACjC,wBAAc;AAAA,QAChB;AAAA,MACF;AAEA,aAAO,MAAM,SAAS,UAAU;AAAA,IAClC,UAAE;AACA,UAAI,YAAa,OAAM,WAAW,MAAM,UAAU;AAClD,YAAM,KAAK,UAAU,QAAQ,UAAU;AAAA,IACzC;AAAA,EACF;AAAA,EAEA,MAAM,UAAyB;AAC7B,WAAO,MAAM,KAAK,UAAU,QAAQ;AAAA,EACtC;AACF;",
+  "mappings": "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",
   "names": []
 }

package/dist/provider.cjs

@@ -26,7 +26,19 @@ __export(provider_exports, {
 });
 module.exports = __toCommonJS(provider_exports);
 var import_assert = require("./assert.cjs");
+var providerUrls = /* @__PURE__ */ new WeakMap();
 var AbstractPGProvider = class {
+  constructor(url) {
+    providerUrls.set(this, new URL(url));
+  }
+  get url() {
+    const url = providerUrls.get(this);
+    (0, import_assert.assert)(url, "Internal error: missing provider URL");
+    const sanitizedUrl = new URL(url);
+    sanitizedUrl.username = "";
+    sanitizedUrl.password = "";
+    return sanitizedUrl;
+  }
   async query(text, params = []) {
     const connection = await this.acquire();
     try {

package/dist/provider.cjs.map

@@ -1,6 +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,SAA4B,CAAC,GAAgC;AACrF,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;",
+  "mappings": ";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,oBAAuB;AAyCvB,IAAM,eAAe,oBAAI,QAAiC;AAEnD,IAAe,qBAAf,MAC2B;AAAA,EAChC,YAAY,KAAmB;AAC7B,iBAAa,IAAI,MAAM,IAAI,IAAI,GAAG,CAAC;AAAA,EACrC;AAAA,EAEA,IAAI,MAAqB;AACvB,UAAM,MAAM,aAAa,IAAI,IAAI;AACjC,8BAAO,KAAK,sCAAsC;AAClD,UAAM,eAAe,IAAI,IAAI,GAAG;AAChC,iBAAa,WAAW;AACxB,iBAAa,WAAW;AACxB,WAAO;AAAA,EACT;AAAA,EAKA,MAAM,MAAM,MAAc,SAA4B,CAAC,GAA8B;AACnF,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;AAQA,IAAM,YAAY,oBAAI,IAAmC;AAGlD,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,KAAsB;AACnD,QAAM,WAAW,UAAU,IAAI,IAAI,QAAQ;AAC3C,4BAAO,UAAU,0CAA0C,IAAI,QAAQ,MAAM;AAC7E,SAAO,IAAI,SAAS,GAAG;AACzB;",
   "names": []
 }