feat(pg-cache): pluggable pool-factory seam (default = pg.Pool)

Author: pyramation

postgres/pg-cache/src/__tests__/driver.test.ts

@@ -0,0 +1,89 @@
+// Locks the pool-factory seam: getPgPool must use a registered factory when
+// present, and fall back to the default pg.Pool builder otherwise. This is what
+// lets an alternate backend (e.g. PGlite) plug in without any change to pgpm /
+// pgsql-* — and guarantees the default path is untouched when nothing registers.
+
+import { randomUUID } from 'crypto';
+import pg from 'pg';
+
+import {
+  defaultPgPoolFactory,
+  getActivePgPoolFactory,
+  getPgPool,
+  hasPgPoolFactory,
+  PgPoolFactory,
+  registerPgPoolFactory
+} from '../index';
+import { pgCache } from '../lru';
+
+const createMockPool = (): pg.Pool =>
+  ({ query: jest.fn(), connect: jest.fn(), end: jest.fn(async () => {}) } as unknown as pg.Pool);
+
+const freshConfig = () => {
+  const database = `seam_${randomUUID()}`;
+  return { database, host: 'localhost', port: 5432, user: 'postgres', password: 'x' };
+};
+
+describe('pg-cache pool-factory seam', () => {
+  afterEach(() => {
+    registerPgPoolFactory(undefined);
+  });
+
+  it('defaults to no registered factory', () => {
+    expect(hasPgPoolFactory()).toBe(false);
+    expect(getActivePgPoolFactory()).toBeUndefined();
+  });
+
+  it('register/reset toggles the active factory', () => {
+    const factory: PgPoolFactory = () => createMockPool();
+    registerPgPoolFactory(factory);
+    expect(hasPgPoolFactory()).toBe(true);
+    expect(getActivePgPoolFactory()).toBe(factory);
+
+    registerPgPoolFactory(undefined);
+    expect(hasPgPoolFactory()).toBe(false);
+  });
+
+  it('getPgPool builds via the registered factory (no real pg connection)', () => {
+    const cfg = freshConfig();
+    const mock = createMockPool();
+    const factory = jest.fn<pg.Pool, [any]>(() => mock);
+    registerPgPoolFactory(factory);
+
+    const pool = getPgPool(cfg);
+
+    expect(factory).toHaveBeenCalledTimes(1);
+    expect(pool).toBe(mock);
+
+    pgCache.delete(cfg.database);
+  });
+
+  it('caches by database: a second call reuses the pool and does not re-invoke the factory', () => {
+    const cfg = freshConfig();
+    const factory = jest.fn<pg.Pool, [any]>(() => createMockPool());
+    registerPgPoolFactory(factory);
+
+    const first = getPgPool(cfg);
+    const second = getPgPool(cfg);
+
+    expect(first).toBe(second);
+    expect(factory).toHaveBeenCalledTimes(1);
+
+    pgCache.delete(cfg.database);
+  });
+
+  it('falls back to defaultPgPoolFactory when nothing is registered', () => {
+    const cfg = freshConfig();
+    // defaultPgPoolFactory builds a real pg.Pool but does NOT connect until a
+    // query runs, so this is safe without a live server.
+    const pool = getPgPool(cfg);
+    expect(pool).toBeInstanceOf(pg.Pool);
+    pgCache.delete(cfg.database);
+  });
+
+  it('defaultPgPoolFactory returns a pg.Pool', () => {
+    const pool = defaultPgPoolFactory(freshConfig());
+    expect(pool).toBeInstanceOf(pg.Pool);
+    return pool.end();
+  });
+});

postgres/pg-cache/src/driver.ts

@@ -0,0 +1,50 @@
+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 factory returns a `pg.Pool`; the only surface pgpm/pgsql-* actually rely
+ * on is `query()`, `connect()` and `end()`, so an adapter may return an object
+ * that implements that subset. `QueryablePool` documents that contract.
+ */
+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;
+
+let activeFactory: PgPoolFactory | undefined;
+
+/**
+ * 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: PgPoolFactory | undefined): void => {
+  activeFactory = factory;
+};
+
+/** The currently-registered factory, or `undefined` when using the default. */
+export const getActivePgPoolFactory = (): PgPoolFactory | undefined => activeFactory;
+
+/** Whether a non-default pool factory is currently registered. */
+export const hasPgPoolFactory = (): boolean => activeFactory !== undefined;

postgres/pg-cache/src/index.ts

@@ -1,4 +1,9 @@
 // Main exports from pg-cache package
+export {
+  getActivePgPoolFactory,
+  hasPgPoolFactory,
+  registerPgPoolFactory
+} from './driver';
 export { 
   close,
   getPgCacheConfig,
@@ -8,9 +13,11 @@ export {
 } from './lru';
 export {
   buildConnectionString,
+  defaultPgPoolFactory,
   getPgPool,
   getPgPoolConfig
 } from './pg';
 
 // Re-export types
+export type { PgPoolFactory, QueryableClient, QueryablePool } from './driver';
 export type { PgCacheConfig, PoolCleanupCallback } from './lru';

postgres/pg-cache/src/pg.ts

@@ -2,6 +2,7 @@ import pg from 'pg';
 import { getPgEnvOptions, PgConfig, PgPoolConfig } from 'pg-env';
 import { Logger } from '@pgpmjs/logger';
 
+import { getActivePgPoolFactory, PgPoolFactory } from './driver';
 import { pgCache } from './lru';
 
 const log = new Logger('pg-cache');
@@ -38,13 +39,13 @@ export function getPgPoolConfig(overrides?: PgPoolConfig): pg.PoolConfig {
   };
 }
 
-export const getPgPool = (pgConfig: Partial<PgConfig> & { pool?: PgPoolConfig }): pg.Pool => {
+/**
+ * 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: PgPoolFactory = (pgConfig): pg.Pool => {
   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 });
@@ -100,7 +101,22 @@ export const getPgPool = (pgConfig: Partial<PgConfig> & { pool?: PgPoolConfig })
       log.error(`Pool ${database} unexpected idle connection error [${err.code || 'unknown'}]: ${err.message}`);
     }
   });
-  
+
+  return pgPool;
+};
+
+export const getPgPool = (pgConfig: Partial<PgConfig> & { pool?: PgPoolConfig }): pg.Pool => {
+  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).
+  const factory = getActivePgPoolFactory() ?? defaultPgPoolFactory;
+  const pgPool = factory(pgConfig);
+
   pgCache.set(database, pgPool);
   return pgPool;
 };