pg-cache 3.13.1 → 3.14.1

package/driver.d.ts

@@ -0,0 +1,41 @@
+import type pg from 'pg';
+import type { PgConfig, PgPoolConfig } from 'pg-env';
+/**
+ * Minimal connection-factory seam for pg-cache.
+ *
+ * `getPgPool` funnels every pooled connection in the stack through a single
+ * factory. By default that factory builds a real `pg.Pool` (see
+ * `defaultPgPoolFactory`). Registering an alternate factory lets a different
+ * backend (e.g. an in-process PGlite instance) supply the pool WITHOUT any
+ * backend-specific dependency leaking into pg-cache or its consumers.
+ *
+ * The only surface pgpm/pgsql-* actually rely on is `query()`, `connect()` and
+ * `end()` (plus an `ended` flag for disposal), so a factory may return anything
+ * implementing that subset — `QueryablePool`. A real `pg.Pool` structurally
+ * satisfies it, so the default path is unchanged and fully backward-compatible.
+ */
+export interface QueryableClient {
+    query(text: string, values?: any[]): Promise<any>;
+    release(...args: any[]): void;
+}
+export interface QueryablePool {
+    query(text: string, values?: any[]): Promise<any>;
+    connect(): Promise<QueryableClient>;
+    end(): Promise<void>;
+}
+export type PgPoolFactory = (config: Partial<PgConfig> & {
+    pool?: PgPoolConfig;
+}) => pg.Pool | QueryablePool;
+/**
+ * Register the factory `getPgPool` uses to build new pools. Pass `undefined`
+ * to restore the default (`pg.Pool`) behavior.
+ *
+ * Note: only affects pools created after registration; already-cached pools are
+ * unchanged. Callers that need a clean slate should tear down existing pools
+ * first (see `teardownPgPools`).
+ */
+export declare const registerPgPoolFactory: (factory: PgPoolFactory | undefined) => void;
+/** The currently-registered factory, or `undefined` when using the default. */
+export declare const getActivePgPoolFactory: () => PgPoolFactory | undefined;
+/** Whether a non-default pool factory is currently registered. */
+export declare const hasPgPoolFactory: () => boolean;

package/driver.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasPgPoolFactory = exports.getActivePgPoolFactory = exports.registerPgPoolFactory = void 0;
+let activeFactory;
+/**
+ * Register the factory `getPgPool` uses to build new pools. Pass `undefined`
+ * to restore the default (`pg.Pool`) behavior.
+ *
+ * Note: only affects pools created after registration; already-cached pools are
+ * unchanged. Callers that need a clean slate should tear down existing pools
+ * first (see `teardownPgPools`).
+ */
+const registerPgPoolFactory = (factory) => {
+    activeFactory = factory;
+};
+exports.registerPgPoolFactory = registerPgPoolFactory;
+/** The currently-registered factory, or `undefined` when using the default. */
+const getActivePgPoolFactory = () => activeFactory;
+exports.getActivePgPoolFactory = getActivePgPoolFactory;
+/** Whether a non-default pool factory is currently registered. */
+const hasPgPoolFactory = () => activeFactory !== undefined;
+exports.hasPgPoolFactory = hasPgPoolFactory;

package/esm/driver.js

@@ -0,0 +1,16 @@
+let activeFactory;
+/**
+ * Register the factory `getPgPool` uses to build new pools. Pass `undefined`
+ * to restore the default (`pg.Pool`) behavior.
+ *
+ * Note: only affects pools created after registration; already-cached pools are
+ * unchanged. Callers that need a clean slate should tear down existing pools
+ * first (see `teardownPgPools`).
+ */
+export const registerPgPoolFactory = (factory) => {
+    activeFactory = factory;
+};
+/** The currently-registered factory, or `undefined` when using the default. */
+export const getActivePgPoolFactory = () => activeFactory;
+/** Whether a non-default pool factory is currently registered. */
+export const hasPgPoolFactory = () => activeFactory !== undefined;

package/esm/index.js

@@ -1,3 +1,4 @@
 // Main exports from pg-cache package
+export { getActivePgPoolFactory, hasPgPoolFactory, registerPgPoolFactory } from './driver';
 export { close, getPgCacheConfig, pgCache, PgPoolCacheManager, teardownPgPools } from './lru';
-export { buildConnectionString, getPgPool, getPgPoolConfig } from './pg';
+export { buildConnectionString, defaultPgPoolFactory, getPgPool, getPgPoolConfig } from './pg';

package/esm/pg.js

@@ -1,6 +1,7 @@
 import pg from 'pg';
 import { getPgEnvOptions } from 'pg-env';
 import { Logger } from '@pgpmjs/logger';
+import { getActivePgPoolFactory } from './driver';
 import { pgCache } from './lru';
 const log = new Logger('pg-cache');
 export const buildConnectionString = (user, password, host, port, database) => `postgres://${user}:${password}@${host}:${port}/${database}`;
@@ -26,14 +27,13 @@ export function getPgPoolConfig(overrides) {
         ...(overrides?.allowExitOnIdle !== undefined && { allowExitOnIdle: overrides.allowExitOnIdle }),
     };
 }
-export const getPgPool = (pgConfig) => {
+/**
+ * Default pool factory: builds a real `pg.Pool` over TCP. This is the behavior
+ * used whenever no alternate driver is registered (see `./driver`).
+ */
+export const defaultPgPoolFactory = (pgConfig) => {
     const config = getPgEnvOptions(pgConfig);
-    const { user, password, host, port, database, } = config;
-    if (pgCache.has(database)) {
-        const cached = pgCache.get(database);
-        if (cached)
-            return cached;
-    }
+    const { user, password, host, port, database } = config;
     const connectionString = buildConnectionString(user, password, host, port, database);
     const poolConfig = getPgPoolConfig(pgConfig.pool);
     const pgPool = new pg.Pool({ connectionString, ...poolConfig });
@@ -89,6 +89,21 @@ export const getPgPool = (pgConfig) => {
             log.error(`Pool ${database} unexpected idle connection error [${err.code || 'unknown'}]: ${err.message}`);
         }
     });
+    return pgPool;
+};
+export const getPgPool = (pgConfig) => {
+    const config = getPgEnvOptions(pgConfig);
+    const { database } = config;
+    if (pgCache.has(database)) {
+        const cached = pgCache.get(database);
+        if (cached)
+            return cached;
+    }
+    // Route through the registered driver (default = pg.Pool over TCP). A custom
+    // factory may return any QueryablePool (e.g. an in-process PGlite pool); it is
+    // treated as a pg.Pool since that is the only surface consumers use.
+    const factory = getActivePgPoolFactory() ?? defaultPgPoolFactory;
+    const pgPool = factory(pgConfig);
     pgCache.set(database, pgPool);
     return pgPool;
 };

package/index.d.ts

@@ -1,3 +1,5 @@
+export { getActivePgPoolFactory, hasPgPoolFactory, registerPgPoolFactory } from './driver';
 export { close, getPgCacheConfig, pgCache, PgPoolCacheManager, teardownPgPools } from './lru';
-export { buildConnectionString, getPgPool, getPgPoolConfig } from './pg';
+export { buildConnectionString, defaultPgPoolFactory, getPgPool, getPgPoolConfig } from './pg';
+export type { PgPoolFactory, QueryableClient, QueryablePool } from './driver';
 export type { PgCacheConfig, PoolCleanupCallback } from './lru';

package/index.js

@@ -1,7 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getPgPoolConfig = exports.getPgPool = exports.buildConnectionString = exports.teardownPgPools = exports.PgPoolCacheManager = exports.pgCache = exports.getPgCacheConfig = void 0;
+exports.getPgPoolConfig = exports.getPgPool = exports.defaultPgPoolFactory = exports.buildConnectionString = exports.teardownPgPools = exports.PgPoolCacheManager = exports.pgCache = exports.getPgCacheConfig = exports.registerPgPoolFactory = exports.hasPgPoolFactory = exports.getActivePgPoolFactory = void 0;
 // Main exports from pg-cache package
+var driver_1 = require("./driver");
+Object.defineProperty(exports, "getActivePgPoolFactory", { enumerable: true, get: function () { return driver_1.getActivePgPoolFactory; } });
+Object.defineProperty(exports, "hasPgPoolFactory", { enumerable: true, get: function () { return driver_1.hasPgPoolFactory; } });
+Object.defineProperty(exports, "registerPgPoolFactory", { enumerable: true, get: function () { return driver_1.registerPgPoolFactory; } });
 var lru_1 = require("./lru");
 Object.defineProperty(exports, "close", { enumerable: true, get: function () { return lru_1.close; } });
 Object.defineProperty(exports, "getPgCacheConfig", { enumerable: true, get: function () { return lru_1.getPgCacheConfig; } });
@@ -10,5 +14,6 @@ Object.defineProperty(exports, "PgPoolCacheManager", { enumerable: true, get: fu
 Object.defineProperty(exports, "teardownPgPools", { enumerable: true, get: function () { return lru_1.teardownPgPools; } });
 var pg_1 = require("./pg");
 Object.defineProperty(exports, "buildConnectionString", { enumerable: true, get: function () { return pg_1.buildConnectionString; } });
+Object.defineProperty(exports, "defaultPgPoolFactory", { enumerable: true, get: function () { return pg_1.defaultPgPoolFactory; } });
 Object.defineProperty(exports, "getPgPool", { enumerable: true, get: function () { return pg_1.getPgPool; } });
 Object.defineProperty(exports, "getPgPoolConfig", { enumerable: true, get: function () { return pg_1.getPgPoolConfig; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pg-cache",
-  "version": "3.13.1",
+  "version": "3.14.1",
   "author": "Constructive <developers@constructive.io>",
   "description": "PostgreSQL connection pool LRU cache manager",
   "main": "index.js",
@@ -30,7 +30,7 @@
   },
   "dependencies": {
     "@pgpmjs/logger": "^2.13.0",
-    "@pgpmjs/types": "^2.31.0",
+    "@pgpmjs/types": "^2.32.0",
     "lru-cache": "^11.2.7",
     "pg": "^8.21.0",
     "pg-env": "^1.17.0"
@@ -48,5 +48,5 @@
     "connection",
     "constructive"
   ],
-  "gitHead": "5a7e92e9849aa715367a33fa78a23c5f9adaefa0"
+  "gitHead": "87e65cd31d4e23c367ca4d398416b19ac863c7de"
 }

package/pg.d.ts

@@ -1,5 +1,6 @@
 import pg from 'pg';
 import { PgConfig, PgPoolConfig } from 'pg-env';
+import { PgPoolFactory } from './driver';
 export declare const buildConnectionString: (user: string, password: string, host: string, port: string | number, database: string) => string;
 /**
  * Read per-pool configuration from environment variables.
@@ -10,6 +11,11 @@ export declare const buildConnectionString: (user: string, password: string, hos
  * - PG_POOL_CONNECTION_TIMEOUT_MS: Fail connect() after ms (default: 5000)
  */
 export declare function getPgPoolConfig(overrides?: PgPoolConfig): pg.PoolConfig;
+/**
+ * Default pool factory: builds a real `pg.Pool` over TCP. This is the behavior
+ * used whenever no alternate driver is registered (see `./driver`).
+ */
+export declare const defaultPgPoolFactory: PgPoolFactory;
 export declare const getPgPool: (pgConfig: Partial<PgConfig> & {
     pool?: PgPoolConfig;
 }) => pg.Pool;

package/pg.js

@@ -3,11 +3,12 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getPgPool = exports.buildConnectionString = void 0;
+exports.getPgPool = exports.defaultPgPoolFactory = exports.buildConnectionString = void 0;
 exports.getPgPoolConfig = getPgPoolConfig;
 const pg_1 = __importDefault(require("pg"));
 const pg_env_1 = require("pg-env");
 const logger_1 = require("@pgpmjs/logger");
+const driver_1 = require("./driver");
 const lru_1 = require("./lru");
 const log = new logger_1.Logger('pg-cache');
 const buildConnectionString = (user, password, host, port, database) => `postgres://${user}:${password}@${host}:${port}/${database}`;
@@ -34,14 +35,13 @@ function getPgPoolConfig(overrides) {
         ...(overrides?.allowExitOnIdle !== undefined && { allowExitOnIdle: overrides.allowExitOnIdle }),
     };
 }
-const getPgPool = (pgConfig) => {
+/**
+ * Default pool factory: builds a real `pg.Pool` over TCP. This is the behavior
+ * used whenever no alternate driver is registered (see `./driver`).
+ */
+const defaultPgPoolFactory = (pgConfig) => {
     const config = (0, pg_env_1.getPgEnvOptions)(pgConfig);
-    const { user, password, host, port, database, } = config;
-    if (lru_1.pgCache.has(database)) {
-        const cached = lru_1.pgCache.get(database);
-        if (cached)
-            return cached;
-    }
+    const { user, password, host, port, database } = config;
     const connectionString = (0, exports.buildConnectionString)(user, password, host, port, database);
     const poolConfig = getPgPoolConfig(pgConfig.pool);
     const pgPool = new pg_1.default.Pool({ connectionString, ...poolConfig });
@@ -97,6 +97,22 @@ const getPgPool = (pgConfig) => {
             log.error(`Pool ${database} unexpected idle connection error [${err.code || 'unknown'}]: ${err.message}`);
         }
     });
+    return pgPool;
+};
+exports.defaultPgPoolFactory = defaultPgPoolFactory;
+const getPgPool = (pgConfig) => {
+    const config = (0, pg_env_1.getPgEnvOptions)(pgConfig);
+    const { database } = config;
+    if (lru_1.pgCache.has(database)) {
+        const cached = lru_1.pgCache.get(database);
+        if (cached)
+            return cached;
+    }
+    // Route through the registered driver (default = pg.Pool over TCP). A custom
+    // factory may return any QueryablePool (e.g. an in-process PGlite pool); it is
+    // treated as a pg.Pool since that is the only surface consumers use.
+    const factory = (0, driver_1.getActivePgPoolFactory)() ?? exports.defaultPgPoolFactory;
+    const pgPool = factory(pgConfig);
     lru_1.pgCache.set(database, pgPool);
     return pgPool;
 };