Explicit Resource Management for pg pool client

docs/pages/apis/pool.mdx

@@ -187,6 +187,35 @@ assert(pool.idleCount === 0)
 assert(pool.totalCount === 0)
 ```
 
+`client.destroyOnDispose: boolean`
+
+`client[Symbol.dispose]() => void`
+
+Alternatively, pool clients support [Explicit Resource Management](https://tc39.es/proposal-explicit-resource-management/), which means you can use the `using` syntax to release them if your runtime supports it.
+
+```js
+
+import { Pool } from 'pg'
+
+const pool = new Pool()
+{
+  // check out a single client
+  using client = await pool.connect()
+
+  // client.release() implicitly called at the end of scope
+}
+
+{
+  // check out a single client
+  using client = await pool.connnect()
+  client.destroyOnDispose = true;
+
+  // client.release(true) implicitly called at the end of scope
+}
+```
+
+If you want the client to be destroyed instead of being returned to the pool at the end of the scope, (i.e. calling `client.release(true)` at the end of the scope), set the `destroyOnRelease` property to `true`.
+
 <Alert>
   <div>
     You <strong>must</strong> release a client when you are finished with it.

eslint.config.mjs

@@ -0,0 +1,66 @@
+import { defineConfig, globalIgnores } from "eslint/config";
+import typescriptEslint from "@typescript-eslint/eslint-plugin";
+import prettier from "eslint-plugin-prettier";
+import globals from "globals";
+import tsParser from "@typescript-eslint/parser";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import js from "@eslint/js";
+import { FlatCompat } from "@eslint/eslintrc";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const compat = new FlatCompat({
+    baseDirectory: __dirname,
+    recommendedConfig: js.configs.recommended,
+    allConfig: js.configs.all
+});
+
+export default defineConfig([globalIgnores([
+    "**/node_modules",
+    "**/coverage",
+    "packages/*/dist",
+    "packages/pg-protocol/dist/**/*",
+    "packages/pg-query-stream/dist/**/*",
+]), {
+    extends: compat.extends("eslint:recommended", "plugin:prettier/recommended", "prettier"),
+
+    plugins: {
+        "@typescript-eslint": typescriptEslint,
+        prettier,
+    },
+
+    languageOptions: {
+        globals: {
+            ...globals.node,
+            ...globals.mocha,
+        },
+
+        parser: tsParser,
+        ecmaVersion: 2017,
+        sourceType: "module",
+    },
+
+    rules: {
+        "@typescript-eslint/no-unused-vars": ["error", {
+            args: "none",
+            caughtErrors: "none",
+            varsIgnorePattern: "^_$",
+        }],
+
+        // handled by @typescript-eslint/no-unused-vars
+        "no-unused-vars": "off",
+
+        "no-var": "error",
+        "prefer-const": "error",
+        "no-constant-condition": ["error", {
+            checkLoops: "all"
+        }]
+    },
+}, {
+    files: ["**/*.ts", "**/*.mts", "**/*.cts", "**/*.tsx"],
+
+    rules: {
+        "no-undef": "off",
+    },
+}]);

package.json

@@ -20,15 +20,18 @@
     "lint": "eslint --cache 'packages/**/*.{js,ts,tsx}'"
   },
   "devDependencies": {
-    "@typescript-eslint/eslint-plugin": "^7.0.0",
-    "@typescript-eslint/parser": "^6.17.0",
-    "eslint": "^8.56.0",
+    "@eslint/eslintrc": "^3.3.5",
+    "@eslint/js": "^10.0.1",
+    "@typescript-eslint/eslint-plugin": "^8.58.0",
+    "@typescript-eslint/parser": "^8.58.0",
+    "eslint": "^10.2.1",
     "eslint-config-prettier": "^10.1.2",
     "eslint-plugin-node": "^11.1.0",
     "eslint-plugin-prettier": "^5.1.2",
     "lerna": "^3.19.0",
     "prettier": "3.0.3",
-    "typescript": "^4.0.3"
+    "typescript": "^6.0.3",
+    "@types/node": "^16"
   },
   "prettier": {
     "semi": false,

packages/pg-cloudflare/package.json

@@ -7,7 +7,7 @@
   "license": "MIT",
   "devDependencies": {
     "ts-node": "^8.5.4",
-    "typescript": "^4.0.3"
+    "typescript": "^6.0.3"
   },
   "exports": {
     ".": {

packages/pg-cloudflare/src/index.ts

@@ -1,4 +1,4 @@
-import { SocketOptions, Socket, TlsOptions } from 'cloudflare:sockets' // eslint-disable-line
+import { SocketOptions, Socket, TlsOptions } from 'cloudflare:sockets'
 import { EventEmitter } from 'events'
 
 /**
@@ -153,7 +153,10 @@ const debug = false
 
 function dump(data: unknown) {
   if (data instanceof Uint8Array || data instanceof ArrayBuffer) {
-    const hex = Buffer.from(data).toString('hex')
+    // workaround https://github.com/microsoft/TypeScript/issues/63447
+    const buf = data instanceof Uint8Array ? Buffer.from(data) : Buffer.from(data)
+
+    const hex = buf.toString('hex')
     const str = new TextDecoder().decode(data)
     return `\n>>> STR: "${str.replace(/\n/g, '\\n')}"\n>>> HEX: ${hex}\n`
   } else {

packages/pg-cloudflare/tsconfig.json

@@ -9,15 +9,16 @@
     "moduleResolution": "node16",
     "sourceMap": true,
     "outDir": "dist",
+    "rootDir": "./src",
     "incremental": true,
-    "baseUrl": ".",
     "declaration": true,
     "paths": {
       "*": [
-        "node_modules/*",
-        "src/types/*"
+        "./node_modules/*",
+        "./src/types/*"
       ]
-    }
+    },
+    "types": ["node"]
   },
   "include": [
     "src/**/*"

packages/pg-connection-string/package.json

@@ -41,7 +41,7 @@
     "mocha": "^11.7.5",
     "nyc": "^15",
     "tsx": "^4.19.4",
-    "typescript": "^4.0.3"
+    "typescript": "^6.0.3"
   },
   "files": [
     "index.js",

packages/pg-pool/index.js

@@ -341,6 +341,13 @@ class Pool extends EventEmitter {
 
     client.release = this._releaseOnce(client, idleListener)
 
+    if (Symbol.dispose) {
+      client.destroyOnDispose = false
+      client[Symbol.dispose] = function () {
+        this.release(this.destroyOnDispose)
+      }
+    }
+
     client.removeListener('error', idleListener)
 
     if (!pendingItem.timedOut) {

packages/pg-pool/test/disposable-clients.js

@@ -0,0 +1,25 @@
+const Pool = require('../')
+
+const expect = require('expect.js')
+
+describe('disposable clients', () => {
+  it('defines a callable [Symbol.dispose]() when symbol is present', async () => {
+    const pool = new Pool({ max: 1 })
+    const client = await pool.connect()
+
+    if (Symbol?.dispose) {
+      expect(client[Symbol.dispose]).to.be.a('function')
+    }
+
+    // ensure we don't define an `undefined` function when Symbol.dispose
+    // doesn't exist
+    expect(client).not.to.have.property('undefined')
+
+    client.release()
+    await pool.end()
+  })
+
+  if (process.version.slice(1).split('.')[0] >= 24) {
+    require('./disposable-clients/using.js')
+  }
+})

packages/pg-pool/test/disposable-clients/using.js

@@ -0,0 +1,38 @@
+const Pool = require('../..')
+
+const expect = require('expect.js')
+
+it('supports releasing clients via `using`', async () => {
+  const pool = new Pool({ max: 1 })
+  expect(pool.totalCount).to.eql(0)
+
+  {
+    using client = await pool.connect()
+    expect(pool.totalCount).to.eql(1)
+    expect(pool.idleCount).to.eql(0)
+    await client.query('SELECT NOW()')
+  }
+
+  expect(pool.totalCount).to.eql(1)
+  expect(pool.idleCount).to.eql(1)
+
+  await pool.end()
+})
+
+it('supports destroying clients via `using`', async () => {
+  const pool = new Pool({ max: 1 })
+  expect(pool.totalCount).to.eql(0)
+
+  {
+    using client = await pool.connect()
+    client.destroyOnDispose = true
+    expect(pool.totalCount).to.eql(1)
+    expect(pool.idleCount).to.eql(0)
+    await client.query('SELECT NOW()')
+  }
+
+  expect(pool.totalCount).to.eql(0)
+  expect(pool.idleCount).to.eql(0)
+
+  await pool.end()
+})

packages/pg-protocol/package.json

@@ -17,12 +17,12 @@
   "devDependencies": {
     "@types/chai": "^4.2.7",
     "@types/mocha": "^10.0.10",
-    "@types/node": "^12.12.21",
+    "@types/node": "^16",
     "chai": "^4.2.0",
     "chunky": "^0.0.0",
     "mocha": "^11.7.5",
     "ts-node": "^8.5.4",
-    "typescript": "^4.0.3"
+    "typescript": "^6.0.3"
   },
   "scripts": {
     "test": "mocha dist/**/*.test.js",

packages/pg-protocol/src/buffer-reader.ts

@@ -2,7 +2,7 @@ export class BufferReader {
   private buffer: Buffer = Buffer.allocUnsafe(0)
 
   // TODO(bmc): support non-utf8 encoding?
-  private encoding: string = 'utf-8'
+  private encoding: BufferEncoding = 'utf-8'
 
   constructor(private offset: number = 0) {}
 

packages/pg-protocol/tsconfig.json

@@ -9,15 +9,19 @@
     "moduleResolution": "node16",
     "sourceMap": true,
     "outDir": "dist",
+    "rootDir": "./src",
     "incremental": true,
-    "baseUrl": ".",
     "declaration": true,
     "paths": {
       "*": [
-        "node_modules/*",
-        "src/types/*"
+        "./node_modules/*",
+        "./src/types/*"
       ]
-    }
+    },
+    "types": [
+      "node",
+      "mocha"
+    ]
   },
   "include": [
     "src/**/*"

packages/pg-query-stream/package.json

@@ -39,16 +39,16 @@
   "devDependencies": {
     "@types/chai": "^4.2.13",
     "@types/mocha": "^10.0.10",
-    "@types/node": "^14.0.0",
+    "@types/node": "^16.0.0",
     "@types/pg": "^7.14.5",
     "JSONStream": "~1.3.5",
     "concat-stream": "~1.0.1",
-    "eslint-plugin-promise": "^7.2.1",
+    "eslint-plugin-promise": "^7.3.0",
     "mocha": "^11.7.5",
     "pg": "^8.20.0",
     "stream-spec": "~0.3.5",
     "ts-node": "^8.5.4",
-    "typescript": "^4.0.3"
+    "typescript": "^6.0.3"
   },
   "peerDependencies": {
     "pg": "^8"

packages/pg-query-stream/tsconfig.json

@@ -10,8 +10,8 @@
     "sourceMap": true,
     "pretty": true,
     "outDir": "dist",
+    "rootDir": "./src",
     "incremental": true,
-    "baseUrl": ".",
     "declaration": true,
     "types": [
       "node",

packages/pg/package.json

@@ -45,7 +45,7 @@
     "bluebird": "3.7.2",
     "co": "4.6.0",
     "pg-copy-streams": "0.3.0",
-    "typescript": "^4.0.3",
+    "typescript": "^6.0.3",
     "vitest": "~3.0.9",
     "wrangler": "^3.x"
   },