graphile-realtime-subscriptions 0.5.0 → 0.6.0

package/cursor-tracker.d.ts

@@ -9,8 +9,8 @@
  *   4. stop() → calls cleanup_ephemeral() to remove ephemeral subscriptions
  *              and delete the listener_node row
  *
- * The caller provides a withPgClient callback that acquires a PgClient
- * for each operation. This keeps connection management external.
+ * The caller provides a Queryable (typically a pg.Pool from pg-cache)
+ * and this class calls pool.query() directly for each operation.
  */
 import type { CursorTrackerOptions, ChangeLogEntry } from './types';
 declare const DEFAULT_POLL_INTERVAL_MS = 5000;
@@ -23,7 +23,7 @@ export declare class CursorTracker {
     private readonly pollIntervalMs;
     private readonly heartbeatIntervalMs;
     private readonly batchLimit;
-    private readonly withPgClient;
+    private readonly pool;
     private readonly onChanges;
     private readonly onError;
     private pollTimer;

package/cursor-tracker.js

@@ -10,8 +10,8 @@
  *   4. stop() → calls cleanup_ephemeral() to remove ephemeral subscriptions
  *              and delete the listener_node row
  *
- * The caller provides a withPgClient callback that acquires a PgClient
- * for each operation. This keeps connection management external.
+ * The caller provides a Queryable (typically a pg.Pool from pg-cache)
+ * and this class calls pool.query() directly for each operation.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_SCHEMA = exports.DEFAULT_BATCH_LIMIT = exports.DEFAULT_HEARTBEAT_INTERVAL_MS = exports.DEFAULT_POLL_INTERVAL_MS = exports.CursorTracker = void 0;
@@ -33,7 +33,7 @@ class CursorTracker {
     pollIntervalMs;
     heartbeatIntervalMs;
     batchLimit;
-    withPgClient;
+    pool;
     onChanges;
     onError;
     pollTimer = null;
@@ -46,7 +46,7 @@ class CursorTracker {
         this.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
         this.heartbeatIntervalMs = options.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
         this.batchLimit = options.batchLimit ?? DEFAULT_BATCH_LIMIT;
-        this.withPgClient = options.withPgClient;
+        this.pool = options.pool;
         this.onChanges = options.onChanges ?? (() => { });
         this.onError = options.onError ?? ((err) => {
             log.error(`CursorTracker error: ${err.message}`);
@@ -87,11 +87,9 @@ class CursorTracker {
             return [];
         this.draining = true;
         try {
-            const entries = await this.withPgClient(async (client) => {
-                const sql = `SELECT * FROM ${this.quoteIdent(this.schema)}.drain_changes($1, $2)`;
-                const result = await client.query(sql, [this.nodeId, this.batchLimit]);
-                return result.rows.map((row) => row.drain_changes);
-            });
+            const sql = `SELECT * FROM ${this.quoteIdent(this.schema)}.drain_changes($1, $2)`;
+            const result = await this.pool.query(sql, [this.nodeId, this.batchLimit]);
+            const entries = result.rows.map((row) => row.drain_changes);
             if (entries.length > 0) {
                 log.info(`Drained ${entries.length} change(s) for node=${this.nodeId}`);
                 this.onChanges(entries);
@@ -108,10 +106,8 @@ class CursorTracker {
     }
     async touchListener() {
         try {
-            await this.withPgClient(async (client) => {
-                const sql = `SELECT ${this.quoteIdent(this.schema)}.touch_listener($1)`;
-                await client.query(sql, [this.nodeId]);
-            });
+            const sql = `SELECT ${this.quoteIdent(this.schema)}.touch_listener($1)`;
+            await this.pool.query(sql, [this.nodeId]);
         }
         catch (err) {
             this.onError(err instanceof Error ? err : new Error(String(err)));
@@ -119,10 +115,8 @@ class CursorTracker {
     }
     async cleanupEphemeral() {
         try {
-            await this.withPgClient(async (client) => {
-                const sql = `SELECT ${this.quoteIdent(this.schema)}.cleanup_ephemeral($1)`;
-                await client.query(sql, [this.nodeId]);
-            });
+            const sql = `SELECT ${this.quoteIdent(this.schema)}.cleanup_ephemeral($1)`;
+            await this.pool.query(sql, [this.nodeId]);
             log.info(`Cleaned up ephemeral subscriptions for node=${this.nodeId}`);
         }
         catch (err) {

package/esm/cursor-tracker.d.ts

@@ -9,8 +9,8 @@
  *   4. stop() → calls cleanup_ephemeral() to remove ephemeral subscriptions
  *              and delete the listener_node row
  *
- * The caller provides a withPgClient callback that acquires a PgClient
- * for each operation. This keeps connection management external.
+ * The caller provides a Queryable (typically a pg.Pool from pg-cache)
+ * and this class calls pool.query() directly for each operation.
  */
 import type { CursorTrackerOptions, ChangeLogEntry } from './types';
 declare const DEFAULT_POLL_INTERVAL_MS = 5000;
@@ -23,7 +23,7 @@ export declare class CursorTracker {
     private readonly pollIntervalMs;
     private readonly heartbeatIntervalMs;
     private readonly batchLimit;
-    private readonly withPgClient;
+    private readonly pool;
     private readonly onChanges;
     private readonly onError;
     private pollTimer;

package/esm/cursor-tracker.js

@@ -9,8 +9,8 @@
  *   4. stop() → calls cleanup_ephemeral() to remove ephemeral subscriptions
  *              and delete the listener_node row
  *
- * The caller provides a withPgClient callback that acquires a PgClient
- * for each operation. This keeps connection management external.
+ * The caller provides a Queryable (typically a pg.Pool from pg-cache)
+ * and this class calls pool.query() directly for each operation.
  */
 import { randomUUID } from 'crypto';
 import { Logger } from '@pgpmjs/logger';
@@ -26,7 +26,7 @@ export class CursorTracker {
     pollIntervalMs;
     heartbeatIntervalMs;
     batchLimit;
-    withPgClient;
+    pool;
     onChanges;
     onError;
     pollTimer = null;
@@ -39,7 +39,7 @@ export class CursorTracker {
         this.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
         this.heartbeatIntervalMs = options.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
         this.batchLimit = options.batchLimit ?? DEFAULT_BATCH_LIMIT;
-        this.withPgClient = options.withPgClient;
+        this.pool = options.pool;
         this.onChanges = options.onChanges ?? (() => { });
         this.onError = options.onError ?? ((err) => {
             log.error(`CursorTracker error: ${err.message}`);
@@ -80,11 +80,9 @@ export class CursorTracker {
             return [];
         this.draining = true;
         try {
-            const entries = await this.withPgClient(async (client) => {
-                const sql = `SELECT * FROM ${this.quoteIdent(this.schema)}.drain_changes($1, $2)`;
-                const result = await client.query(sql, [this.nodeId, this.batchLimit]);
-                return result.rows.map((row) => row.drain_changes);
-            });
+            const sql = `SELECT * FROM ${this.quoteIdent(this.schema)}.drain_changes($1, $2)`;
+            const result = await this.pool.query(sql, [this.nodeId, this.batchLimit]);
+            const entries = result.rows.map((row) => row.drain_changes);
             if (entries.length > 0) {
                 log.info(`Drained ${entries.length} change(s) for node=${this.nodeId}`);
                 this.onChanges(entries);
@@ -101,10 +99,8 @@ export class CursorTracker {
     }
     async touchListener() {
         try {
-            await this.withPgClient(async (client) => {
-                const sql = `SELECT ${this.quoteIdent(this.schema)}.touch_listener($1)`;
-                await client.query(sql, [this.nodeId]);
-            });
+            const sql = `SELECT ${this.quoteIdent(this.schema)}.touch_listener($1)`;
+            await this.pool.query(sql, [this.nodeId]);
         }
         catch (err) {
             this.onError(err instanceof Error ? err : new Error(String(err)));
@@ -112,10 +108,8 @@ export class CursorTracker {
     }
     async cleanupEphemeral() {
         try {
-            await this.withPgClient(async (client) => {
-                const sql = `SELECT ${this.quoteIdent(this.schema)}.cleanup_ephemeral($1)`;
-                await client.query(sql, [this.nodeId]);
-            });
+            const sql = `SELECT ${this.quoteIdent(this.schema)}.cleanup_ephemeral($1)`;
+            await this.pool.query(sql, [this.nodeId]);
             log.info(`Cleaned up ephemeral subscriptions for node=${this.nodeId}`);
         }
         catch (err) {

package/esm/index.d.ts

@@ -21,4 +21,4 @@ export { RealtimeSubscriptionsPreset } from './preset';
 export { CursorTracker } from './cursor-tracker';
 export { RealtimeManager } from './realtime-manager';
 export type { RealtimeSubscriptionsPluginOptions } from './types';
-export type { CursorTrackerOptions, ChangeLogEntry, PgClient, WithPgClient, RealtimeManagerOptions, } from './types';
+export type { CursorTrackerOptions, ChangeLogEntry, Queryable, RealtimeManagerOptions, } from './types';

package/esm/plugin.d.ts

@@ -80,5 +80,5 @@ export declare function createRealtimeSubscriptionsPlugin(options?: RealtimeSubs
 export { createRealtimeSubscriptionsPlugin as RealtimeSubscriptionsPlugin };
 export { CursorTracker } from './cursor-tracker';
 export { RealtimeManager } from './realtime-manager';
-export type { CursorTrackerOptions, ChangeLogEntry, WithPgClient, PgClient, RealtimeManagerOptions } from './types';
+export type { CursorTrackerOptions, ChangeLogEntry, Queryable, RealtimeManagerOptions } from './types';
 export { parseNotifyPayload, EventThrottle, DEFAULT_OVERFLOW_THRESHOLD };

package/esm/realtime-manager.js

@@ -61,7 +61,7 @@ export class RealtimeManager {
     subscriber;
     started = false;
     constructor(options) {
-        const { pgSubscriber, withPgClient, ...cursorOpts } = options;
+        const { pgSubscriber, pool, ...cursorOpts } = options;
         this.subscriber = pgSubscriber;
         this.cursorTracker = new CursorTracker({
             nodeId: cursorOpts.nodeId,
@@ -69,7 +69,7 @@ export class RealtimeManager {
             pollIntervalMs: cursorOpts.pollIntervalMs,
             heartbeatIntervalMs: cursorOpts.heartbeatIntervalMs,
             batchLimit: cursorOpts.batchLimit,
-            withPgClient,
+            pool,
             onChanges: (entries) => this.dispatchEntries(entries),
             onError: cursorOpts.onError ?? ((err) => {
                 log.error(`RealtimeManager error: ${err.message}`);

package/esm/types.d.ts

@@ -13,19 +13,18 @@ export interface RealtimeSubscriptionsPluginOptions {
     overflowThreshold?: number;
 }
 /**
- * A minimal PostgreSQL client interface used by CursorTracker.
- * Compatible with node-postgres (pg) Client or PoolClient.
+ * A minimal query-capable interface — satisfied by pg.Pool, pg.Client,
+ * pg.PoolClient, or any object with a compatible `query` method.
+ *
+ * CursorTracker and RealtimeManager use only one-shot queries, so
+ * `pool.query()` (which internally borrows a client, runs the query,
+ * and releases the client) is all that's needed — no callback wrapper.
  */
-export interface PgClient {
+export interface Queryable {
     query<R = Record<string, unknown>>(text: string, values?: unknown[]): Promise<{
         rows: R[];
     }>;
 }
-/**
- * Callback that provides a PgClient for executing queries.
- * The client is released after the callback returns.
- */
-export type WithPgClient = <T>(callback: (client: PgClient) => Promise<T>) => Promise<T>;
 /**
  * A single entry from drain_changes(), representing a change_log row
  * matched against subscriber tables.
@@ -77,10 +76,12 @@ export interface CursorTrackerOptions {
      */
     batchLimit?: number;
     /**
-     * Function to acquire a PgClient for executing queries.
-     * The cursor tracker calls this for every poll and heartbeat cycle.
+     * A query-capable object (typically a pg.Pool from pg-cache) used to
+     * run drain_changes(), touch_listener(), and cleanup_ephemeral() queries.
+     * pool.query() internally borrows a connection and releases it after
+     * each call — no manual connection management needed.
      */
-    withPgClient: WithPgClient;
+    pool: Queryable;
     /**
      * Called when drain_changes() returns new change_log entries.
      * The entries include subscriber_ids for fan-out routing.
@@ -104,9 +105,10 @@ export interface RealtimeManagerOptions {
      */
     pgSubscriber: unknown;
     /**
-     * Function to acquire a PgClient for executing cursor tracking queries.
+     * A query-capable object (typically a pg.Pool from pg-cache) used by
+     * the underlying CursorTracker for drain_changes() polling.
      */
-    withPgClient: WithPgClient;
+    pool: Queryable;
     /**
      * Unique identifier for this listener node.
      * Should be stable across restarts if you want cursor continuity.

package/index.d.ts

@@ -21,4 +21,4 @@ export { RealtimeSubscriptionsPreset } from './preset';
 export { CursorTracker } from './cursor-tracker';
 export { RealtimeManager } from './realtime-manager';
 export type { RealtimeSubscriptionsPluginOptions } from './types';
-export type { CursorTrackerOptions, ChangeLogEntry, PgClient, WithPgClient, RealtimeManagerOptions, } from './types';
+export type { CursorTrackerOptions, ChangeLogEntry, Queryable, RealtimeManagerOptions, } from './types';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphile-realtime-subscriptions",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Realtime subscription plugin for PostGraphile v5 — per-table GraphQL subscriptions via LISTEN/NOTIFY",
   "author": "Constructive <developers@constructive.io>",
   "homepage": "https://github.com/constructive-io/constructive",
@@ -40,7 +40,7 @@
     "url": "https://github.com/constructive-io/constructive/issues"
   },
   "dependencies": {
-    "@pgpmjs/logger": "^2.10.0",
+    "@pgpmjs/logger": "^2.11.0",
     "@pgsql/quotes": "^17.1.0"
   },
   "peerDependencies": {
@@ -56,5 +56,5 @@
     "@types/node": "^22.19.11",
     "makage": "^0.3.0"
   },
-  "gitHead": "c665e2443ec98da61e9f372cf663cb9973afef4b"
+  "gitHead": "50dc1d69049c207b46c237eba1e1b1cb7a5f928f"
 }

package/plugin.d.ts

@@ -80,5 +80,5 @@ export declare function createRealtimeSubscriptionsPlugin(options?: RealtimeSubs
 export { createRealtimeSubscriptionsPlugin as RealtimeSubscriptionsPlugin };
 export { CursorTracker } from './cursor-tracker';
 export { RealtimeManager } from './realtime-manager';
-export type { CursorTrackerOptions, ChangeLogEntry, WithPgClient, PgClient, RealtimeManagerOptions } from './types';
+export type { CursorTrackerOptions, ChangeLogEntry, Queryable, RealtimeManagerOptions } from './types';
 export { parseNotifyPayload, EventThrottle, DEFAULT_OVERFLOW_THRESHOLD };

package/realtime-manager.js

@@ -67,7 +67,7 @@ class RealtimeManager {
     subscriber;
     started = false;
     constructor(options) {
-        const { pgSubscriber, withPgClient, ...cursorOpts } = options;
+        const { pgSubscriber, pool, ...cursorOpts } = options;
         this.subscriber = pgSubscriber;
         this.cursorTracker = new cursor_tracker_1.CursorTracker({
             nodeId: cursorOpts.nodeId,
@@ -75,7 +75,7 @@ class RealtimeManager {
             pollIntervalMs: cursorOpts.pollIntervalMs,
             heartbeatIntervalMs: cursorOpts.heartbeatIntervalMs,
             batchLimit: cursorOpts.batchLimit,
-            withPgClient,
+            pool,
             onChanges: (entries) => this.dispatchEntries(entries),
             onError: cursorOpts.onError ?? ((err) => {
                 log.error(`RealtimeManager error: ${err.message}`);

package/types.d.ts

@@ -13,19 +13,18 @@ export interface RealtimeSubscriptionsPluginOptions {
     overflowThreshold?: number;
 }
 /**
- * A minimal PostgreSQL client interface used by CursorTracker.
- * Compatible with node-postgres (pg) Client or PoolClient.
+ * A minimal query-capable interface — satisfied by pg.Pool, pg.Client,
+ * pg.PoolClient, or any object with a compatible `query` method.
+ *
+ * CursorTracker and RealtimeManager use only one-shot queries, so
+ * `pool.query()` (which internally borrows a client, runs the query,
+ * and releases the client) is all that's needed — no callback wrapper.
  */
-export interface PgClient {
+export interface Queryable {
     query<R = Record<string, unknown>>(text: string, values?: unknown[]): Promise<{
         rows: R[];
     }>;
 }
-/**
- * Callback that provides a PgClient for executing queries.
- * The client is released after the callback returns.
- */
-export type WithPgClient = <T>(callback: (client: PgClient) => Promise<T>) => Promise<T>;
 /**
  * A single entry from drain_changes(), representing a change_log row
  * matched against subscriber tables.
@@ -77,10 +76,12 @@ export interface CursorTrackerOptions {
      */
     batchLimit?: number;
     /**
-     * Function to acquire a PgClient for executing queries.
-     * The cursor tracker calls this for every poll and heartbeat cycle.
+     * A query-capable object (typically a pg.Pool from pg-cache) used to
+     * run drain_changes(), touch_listener(), and cleanup_ephemeral() queries.
+     * pool.query() internally borrows a connection and releases it after
+     * each call — no manual connection management needed.
      */
-    withPgClient: WithPgClient;
+    pool: Queryable;
     /**
      * Called when drain_changes() returns new change_log entries.
      * The entries include subscriber_ids for fan-out routing.
@@ -104,9 +105,10 @@ export interface RealtimeManagerOptions {
      */
     pgSubscriber: unknown;
     /**
-     * Function to acquire a PgClient for executing cursor tracking queries.
+     * A query-capable object (typically a pg.Pool from pg-cache) used by
+     * the underlying CursorTracker for drain_changes() polling.
      */
-    withPgClient: WithPgClient;
+    pool: Queryable;
     /**
      * Unique identifier for this listener node.
      * Should be stable across restarts if you want cursor continuity.