@refpool/pg 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Atul Singh
+
+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

@@ -0,0 +1,54 @@
+# @refpool/pg
+
+Multi-tenant **node-postgres (`pg`) `Pool` pooling** built on
+[`@refpool/core`](../core)'s reference-counted, bounded LRU pool.
+
+A pool of `pg.Pool` instances keyed by tenant: at most `max` live pools, shared
+between concurrent requests for the same tenant, with idle ones reclaimed and
+`.end()`ed automatically — so you never accumulate one live connection pool per
+tenant forever.
+
+## Install
+
+```bash
+npm install @refpool/pg pg
+```
+
+`pg` (`^8.0.0`) is a **required** peer dependency — this package statically
+imports it, so you must install `pg` alongside `@refpool/pg`.
+
+## Usage
+
+```ts
+import { createPgPool, withResource } from '@refpool/pg';
+
+const pool = createPgPool({
+  max: 25,
+  idleTtlMs: 60_000,
+  config: (tenantId) => ({
+    connectionString: `postgres://localhost:5432/tenant_${tenantId}`,
+    max: 5, // inner node-postgres pool size, per tenant
+  }),
+});
+pool.start();
+
+const { rows } = await withResource(pool, tenantId, (pg) =>
+  pg.query('select now()'),
+);
+
+await pool.stop(); // on shutdown: ends every live pg.Pool
+```
+
+The factory builds a `pg.Pool` from `config(key)`; `dispose` calls `.end()` on
+eviction/drain. All other [`PoolOptions`](../core#pooloptionst) pass through.
+
+## API
+
+- `createPgPool(options)` → `RefCountedLruPool<Pool>` —
+  `options` is `PoolOptions` minus `factory`/`dispose`, plus
+  `config: (key) => PoolConfig | Promise<PoolConfig>`.
+- `withResource(pool, key, fn)` — acquire `key`, run `fn(pgPool)`, release in `finally`.
+
+## License
+
+MIT © Atul Singh

package/dist/index.cjs

@@ -0,0 +1,52 @@
+"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);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  createPgPool: () => createPgPool,
+  withResource: () => withResource
+});
+module.exports = __toCommonJS(index_exports);
+var import_core = require("@refpool/core");
+var import_pg = require("pg");
+function createPgPool(options) {
+  const { config, ...rest } = options;
+  return new import_core.RefCountedLruPool({
+    ...rest,
+    factory: async (key) => new import_pg.Pool(await config(key)),
+    dispose: async (pool) => {
+      await pool.end();
+    }
+  });
+}
+async function withResource(pool, key, fn) {
+  const handle = await pool.acquire(key);
+  try {
+    return await fn(handle.resource);
+  } finally {
+    handle.release();
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createPgPool,
+  withResource
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import { RefCountedLruPool } from '@refpool/core';\nimport type { AcquireHandle, PoolOptions } from '@refpool/core';\nimport { Pool } from 'pg';\nimport type { PoolConfig } from 'pg';\n\n/** Options for a per-key node-postgres `Pool` pool. */\nexport type PgPoolOptions = Omit<PoolOptions<Pool>, 'factory' | 'dispose'> & {\n  /** Build the node-postgres `PoolConfig` for a tenant key. */\n  config: (key: string) => PoolConfig | Promise<PoolConfig>;\n};\n\n/**\n * Create a reference-counted, bounded LRU pool of node-postgres `Pool`\n * instances keyed by tenant. The factory builds a `Pool`; dispose `.end()`s\n * it on eviction/drain.\n */\nexport function createPgPool(options: PgPoolOptions): RefCountedLruPool<Pool> {\n  const { config, ...rest } = options;\n  return new RefCountedLruPool<Pool>({\n    ...rest,\n    factory: async (key) => new Pool(await config(key)),\n    dispose: async (pool) => {\n      await pool.end();\n    },\n  });\n}\n\n/** Acquire `key`, run `fn`, and release the holder in `finally`. */\nexport async function withResource<R>(\n  pool: RefCountedLruPool<Pool>,\n  key: string,\n  fn: (pgPool: Pool) => Promise<R> | R,\n): Promise<R> {\n  const handle: AcquireHandle<Pool> = await pool.acquire(key);\n  try {\n    return await fn(handle.resource);\n  } finally {\n    handle.release();\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,kBAAkC;AAElC,gBAAqB;AAcd,SAAS,aAAa,SAAiD;AAC5E,QAAM,EAAE,QAAQ,GAAG,KAAK,IAAI;AAC5B,SAAO,IAAI,8BAAwB;AAAA,IACjC,GAAG;AAAA,IACH,SAAS,OAAO,QAAQ,IAAI,eAAK,MAAM,OAAO,GAAG,CAAC;AAAA,IAClD,SAAS,OAAO,SAAS;AACvB,YAAM,KAAK,IAAI;AAAA,IACjB;AAAA,EACF,CAAC;AACH;AAGA,eAAsB,aACpB,MACA,KACA,IACY;AACZ,QAAM,SAA8B,MAAM,KAAK,QAAQ,GAAG;AAC1D,MAAI;AACF,WAAO,MAAM,GAAG,OAAO,QAAQ;AAAA,EACjC,UAAE;AACA,WAAO,QAAQ;AAAA,EACjB;AACF;","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,18 @@
+import { PoolOptions, RefCountedLruPool } from '@refpool/core';
+import { Pool, PoolConfig } from 'pg';
+
+/** Options for a per-key node-postgres `Pool` pool. */
+type PgPoolOptions = Omit<PoolOptions<Pool>, 'factory' | 'dispose'> & {
+    /** Build the node-postgres `PoolConfig` for a tenant key. */
+    config: (key: string) => PoolConfig | Promise<PoolConfig>;
+};
+/**
+ * Create a reference-counted, bounded LRU pool of node-postgres `Pool`
+ * instances keyed by tenant. The factory builds a `Pool`; dispose `.end()`s
+ * it on eviction/drain.
+ */
+declare function createPgPool(options: PgPoolOptions): RefCountedLruPool<Pool>;
+/** Acquire `key`, run `fn`, and release the holder in `finally`. */
+declare function withResource<R>(pool: RefCountedLruPool<Pool>, key: string, fn: (pgPool: Pool) => Promise<R> | R): Promise<R>;
+
+export { type PgPoolOptions, createPgPool, withResource };

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+import { PoolOptions, RefCountedLruPool } from '@refpool/core';
+import { Pool, PoolConfig } from 'pg';
+
+/** Options for a per-key node-postgres `Pool` pool. */
+type PgPoolOptions = Omit<PoolOptions<Pool>, 'factory' | 'dispose'> & {
+    /** Build the node-postgres `PoolConfig` for a tenant key. */
+    config: (key: string) => PoolConfig | Promise<PoolConfig>;
+};
+/**
+ * Create a reference-counted, bounded LRU pool of node-postgres `Pool`
+ * instances keyed by tenant. The factory builds a `Pool`; dispose `.end()`s
+ * it on eviction/drain.
+ */
+declare function createPgPool(options: PgPoolOptions): RefCountedLruPool<Pool>;
+/** Acquire `key`, run `fn`, and release the holder in `finally`. */
+declare function withResource<R>(pool: RefCountedLruPool<Pool>, key: string, fn: (pgPool: Pool) => Promise<R> | R): Promise<R>;
+
+export { type PgPoolOptions, createPgPool, withResource };

package/dist/index.js

@@ -0,0 +1,26 @@
+// src/index.ts
+import { RefCountedLruPool } from "@refpool/core";
+import { Pool } from "pg";
+function createPgPool(options) {
+  const { config, ...rest } = options;
+  return new RefCountedLruPool({
+    ...rest,
+    factory: async (key) => new Pool(await config(key)),
+    dispose: async (pool) => {
+      await pool.end();
+    }
+  });
+}
+async function withResource(pool, key, fn) {
+  const handle = await pool.acquire(key);
+  try {
+    return await fn(handle.resource);
+  } finally {
+    handle.release();
+  }
+}
+export {
+  createPgPool,
+  withResource
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import { RefCountedLruPool } from '@refpool/core';\nimport type { AcquireHandle, PoolOptions } from '@refpool/core';\nimport { Pool } from 'pg';\nimport type { PoolConfig } from 'pg';\n\n/** Options for a per-key node-postgres `Pool` pool. */\nexport type PgPoolOptions = Omit<PoolOptions<Pool>, 'factory' | 'dispose'> & {\n  /** Build the node-postgres `PoolConfig` for a tenant key. */\n  config: (key: string) => PoolConfig | Promise<PoolConfig>;\n};\n\n/**\n * Create a reference-counted, bounded LRU pool of node-postgres `Pool`\n * instances keyed by tenant. The factory builds a `Pool`; dispose `.end()`s\n * it on eviction/drain.\n */\nexport function createPgPool(options: PgPoolOptions): RefCountedLruPool<Pool> {\n  const { config, ...rest } = options;\n  return new RefCountedLruPool<Pool>({\n    ...rest,\n    factory: async (key) => new Pool(await config(key)),\n    dispose: async (pool) => {\n      await pool.end();\n    },\n  });\n}\n\n/** Acquire `key`, run `fn`, and release the holder in `finally`. */\nexport async function withResource<R>(\n  pool: RefCountedLruPool<Pool>,\n  key: string,\n  fn: (pgPool: Pool) => Promise<R> | R,\n): Promise<R> {\n  const handle: AcquireHandle<Pool> = await pool.acquire(key);\n  try {\n    return await fn(handle.resource);\n  } finally {\n    handle.release();\n  }\n}\n"],"mappings":";AAAA,SAAS,yBAAyB;AAElC,SAAS,YAAY;AAcd,SAAS,aAAa,SAAiD;AAC5E,QAAM,EAAE,QAAQ,GAAG,KAAK,IAAI;AAC5B,SAAO,IAAI,kBAAwB;AAAA,IACjC,GAAG;AAAA,IACH,SAAS,OAAO,QAAQ,IAAI,KAAK,MAAM,OAAO,GAAG,CAAC;AAAA,IAClD,SAAS,OAAO,SAAS;AACvB,YAAM,KAAK,IAAI;AAAA,IACjB;AAAA,EACF,CAAC;AACH;AAGA,eAAsB,aACpB,MACA,KACA,IACY;AACZ,QAAM,SAA8B,MAAM,KAAK,QAAQ,GAAG;AAC1D,MAAI;AACF,WAAO,MAAM,GAAG,OAAO,QAAQ;AAAA,EACjC,UAAE;AACA,WAAO,QAAQ;AAAA,EACjB;AACF;","names":[]}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@refpool/pg",
+  "version": "0.1.0",
+  "description": "Multi-tenant node-postgres (pg) Pool pooling built on @refpool/core's reference-counted, bounded LRU pool.",
+  "license": "MIT",
+  "author": "Atul Singh <atulsingh.harsh@gmail.com> (https://atulsingh.io)",
+  "type": "module",
+  "sideEffects": false,
+  "keywords": [
+    "pg",
+    "node-postgres",
+    "postgres",
+    "pool",
+    "multi-tenant",
+    "connection-pool",
+    "refpool"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/expedite-atul/refpool.git",
+    "directory": "packages/node-postgres"
+  },
+  "homepage": "https://github.com/expedite-atul/refpool/tree/main/packages/node-postgres#readme",
+  "bugs": {
+    "url": "https://github.com/expedite-atul/refpool/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@refpool/core": "0.1.0"
+  },
+  "peerDependencies": {
+    "pg": "^8.0.0"
+  },
+  "devDependencies": {
+    "@testcontainers/postgresql": "^10.16.0",
+    "@types/node": "^22.10.2",
+    "@types/pg": "^8.11.10",
+    "pg": "^8.13.1",
+    "tsup": "^8.3.5",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.8"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}