graphile-realtime-subscriptions 0.2.0 → 0.4.0

package/plugin.d.ts

@@ -5,21 +5,80 @@
  * subscription fields (onXxxChanged) that use PostgreSQL LISTEN/NOTIFY
  * for real-time event delivery.
  *
- * Subscription modes (Phase 3a):
- *   - Single record: onXxxChanged(id: UUID!) — subscribe to changes on one row
+ * Subscription modes:
+ *   - Specific rows: onXxxChanged(ids: [UUID!]) — subscribe to changes on specific rows
  *   - Full collection: onXxxChanged (no args) — subscribe to any change on the table
  *
+ * NOTIFY payload format (from emit_change trigger):
+ *   - Normal: "INSERT:uuid1,uuid2,..."  or "UPDATE:uuid1" or "DELETE:uuid1"
+ *   - Overflow: "INVALIDATE" (when a single statement affects > 50 rows)
+ *
  * Event flow:
  *   1. A row is inserted/updated/deleted
- *   2. The emit_change trigger fires pg_notify('realtime:{schema}.{table}', TG_OP)
+ *   2. The emit_change trigger fires pg_notify with TG_OP:row_ids or INVALIDATE
  *   3. PostGraphile's pgSubscriber receives the NOTIFY
- *   4. The subscription re-queries the source table with RLS enforced
- *   5. The client receives { event, row } where row reflects the current state
+ *   4. The plugin parses the payload and fetches the specific changed row(s)
+ *   5. The client receives { event, row, rowId, overflow }
+ *
+ * Cursor tracking (at-least-once delivery):
+ *   The CursorTracker class provides a complementary polling-based delivery
+ *   path via drain_changes(). It manages the listener_node lifecycle:
+ *   - start() registers the node via touch_listener()
+ *   - Periodic polling via drain_changes() fetches change_log entries
+ *   - Periodic heartbeat via touch_listener() keeps the node alive
+ *   - stop() calls cleanup_ephemeral() to remove ephemeral subscriptions
+ *   This enables at-least-once semantics by tracking cursor position.
  *
- * RLS enforcement is automatic — resource.get() queries through the
- * authenticated user's connection with their JWT role applied.
+ * Overflow protection:
+ *   - Database-side: statements affecting > 50 rows send INVALIDATE
+ *   - Plugin-side: per-subscriber throttle (default 50 events/second/table)
+ *     drops individual events and sends a single INVALIDATE when exceeded
+ *
+ * Security / RLS enforcement:
+ *   - Row data is always fetched via resource.get() which runs through the
+ *     authenticated user's connection with their JWT role and pgSettings applied.
+ *   - For INSERT/UPDATE events, if RLS denies access (resource.get returns null),
+ *     the rowId is masked (set to null) to prevent metadata leaks.
+ *   - For DELETE events, row is naturally null (the row no longer exists).
+ *   - For INVALIDATE (overflow), the client should refetch via a normal query
+ *     which is also RLS-gated.
+ *   - When ids are provided, only events for those specific rows are delivered,
+ *     preventing cross-tenant event leaks.
  */
 import type { GraphileConfig } from 'graphile-config';
 import type { RealtimeSubscriptionsPluginOptions } from './types';
-export declare function createRealtimeSubscriptionsPlugin(_options?: RealtimeSubscriptionsPluginOptions): GraphileConfig.Plugin;
+/** Default overflow threshold: events per second per table per subscriber */
+declare const DEFAULT_OVERFLOW_THRESHOLD = 50;
+interface ParsedPayload {
+    event: string;
+    rowIds: string[];
+    overflow: boolean;
+}
+/**
+ * Parse the NOTIFY payload from emit_change.
+ * Format: "TG_OP:id1,id2,..." or "INVALIDATE"
+ */
+declare function parseNotifyPayload(raw: string): ParsedPayload;
+/**
+ * Per-subscriber, per-table event rate tracker.
+ * Counts events in a sliding 1-second window.
+ */
+declare class EventThrottle {
+    private readonly threshold;
+    private windowStart;
+    private eventCount;
+    private overflowSent;
+    constructor(threshold: number);
+    /**
+     * Record an event and return whether it should be delivered.
+     * Returns 'deliver' for normal events, 'overflow' when the threshold
+     * is first exceeded, or 'drop' for subsequent events in the same window.
+     */
+    check(): 'deliver' | 'overflow' | 'drop';
+}
+export declare function createRealtimeSubscriptionsPlugin(options?: RealtimeSubscriptionsPluginOptions): GraphileConfig.Plugin;
 export { createRealtimeSubscriptionsPlugin as RealtimeSubscriptionsPlugin };
+export { CursorTracker } from './cursor-tracker';
+export { RealtimeManager } from './realtime-manager';
+export type { CursorTrackerOptions, ChangeLogEntry, WithPgClient, PgClient, RealtimeManagerOptions } from './types';
+export { parseNotifyPayload, EventThrottle, DEFAULT_OVERFLOW_THRESHOLD };

package/plugin.js

@@ -6,27 +6,111 @@
  * subscription fields (onXxxChanged) that use PostgreSQL LISTEN/NOTIFY
  * for real-time event delivery.
  *
- * Subscription modes (Phase 3a):
- *   - Single record: onXxxChanged(id: UUID!) — subscribe to changes on one row
+ * Subscription modes:
+ *   - Specific rows: onXxxChanged(ids: [UUID!]) — subscribe to changes on specific rows
  *   - Full collection: onXxxChanged (no args) — subscribe to any change on the table
  *
+ * NOTIFY payload format (from emit_change trigger):
+ *   - Normal: "INSERT:uuid1,uuid2,..."  or "UPDATE:uuid1" or "DELETE:uuid1"
+ *   - Overflow: "INVALIDATE" (when a single statement affects > 50 rows)
+ *
  * Event flow:
  *   1. A row is inserted/updated/deleted
- *   2. The emit_change trigger fires pg_notify('realtime:{schema}.{table}', TG_OP)
+ *   2. The emit_change trigger fires pg_notify with TG_OP:row_ids or INVALIDATE
  *   3. PostGraphile's pgSubscriber receives the NOTIFY
- *   4. The subscription re-queries the source table with RLS enforced
- *   5. The client receives { event, row } where row reflects the current state
+ *   4. The plugin parses the payload and fetches the specific changed row(s)
+ *   5. The client receives { event, row, rowId, overflow }
+ *
+ * Cursor tracking (at-least-once delivery):
+ *   The CursorTracker class provides a complementary polling-based delivery
+ *   path via drain_changes(). It manages the listener_node lifecycle:
+ *   - start() registers the node via touch_listener()
+ *   - Periodic polling via drain_changes() fetches change_log entries
+ *   - Periodic heartbeat via touch_listener() keeps the node alive
+ *   - stop() calls cleanup_ephemeral() to remove ephemeral subscriptions
+ *   This enables at-least-once semantics by tracking cursor position.
+ *
+ * Overflow protection:
+ *   - Database-side: statements affecting > 50 rows send INVALIDATE
+ *   - Plugin-side: per-subscriber throttle (default 50 events/second/table)
+ *     drops individual events and sends a single INVALIDATE when exceeded
  *
- * RLS enforcement is automatic — resource.get() queries through the
- * authenticated user's connection with their JWT role applied.
+ * Security / RLS enforcement:
+ *   - Row data is always fetched via resource.get() which runs through the
+ *     authenticated user's connection with their JWT role and pgSettings applied.
+ *   - For INSERT/UPDATE events, if RLS denies access (resource.get returns null),
+ *     the rowId is masked (set to null) to prevent metadata leaks.
+ *   - For DELETE events, row is naturally null (the row no longer exists).
+ *   - For INVALIDATE (overflow), the client should refetch via a normal query
+ *     which is also RLS-gated.
+ *   - When ids are provided, only events for those specific rows are delivered,
+ *     preventing cross-tenant event leaks.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_OVERFLOW_THRESHOLD = exports.EventThrottle = exports.RealtimeManager = exports.CursorTracker = void 0;
 exports.createRealtimeSubscriptionsPlugin = createRealtimeSubscriptionsPlugin;
 exports.RealtimeSubscriptionsPlugin = createRealtimeSubscriptionsPlugin;
+exports.parseNotifyPayload = parseNotifyPayload;
 const grafast_1 = require("grafast");
 const graphile_utils_1 = require("graphile-utils");
 const logger_1 = require("@pgpmjs/logger");
 const log = new logger_1.Logger('graphile-realtime-subscriptions');
+/** Default overflow threshold: events per second per table per subscriber */
+const DEFAULT_OVERFLOW_THRESHOLD = 50;
+exports.DEFAULT_OVERFLOW_THRESHOLD = DEFAULT_OVERFLOW_THRESHOLD;
+/**
+ * Parse the NOTIFY payload from emit_change.
+ * Format: "TG_OP:id1,id2,..." or "INVALIDATE"
+ */
+function parseNotifyPayload(raw) {
+    if (raw === 'INVALIDATE') {
+        return { event: 'INVALIDATE', rowIds: [], overflow: true };
+    }
+    const colonIdx = raw.indexOf(':');
+    if (colonIdx === -1) {
+        return { event: raw || 'UNKNOWN', rowIds: [], overflow: false };
+    }
+    const event = raw.substring(0, colonIdx);
+    const idsPart = raw.substring(colonIdx + 1);
+    const rowIds = idsPart.length > 0 ? idsPart.split(',') : [];
+    return { event, rowIds, overflow: false };
+}
+/**
+ * Per-subscriber, per-table event rate tracker.
+ * Counts events in a sliding 1-second window.
+ */
+class EventThrottle {
+    threshold;
+    windowStart = 0;
+    eventCount = 0;
+    overflowSent = false;
+    constructor(threshold) {
+        this.threshold = threshold;
+    }
+    /**
+     * Record an event and return whether it should be delivered.
+     * Returns 'deliver' for normal events, 'overflow' when the threshold
+     * is first exceeded, or 'drop' for subsequent events in the same window.
+     */
+    check() {
+        const now = Date.now();
+        if (now - this.windowStart >= 1000) {
+            this.windowStart = now;
+            this.eventCount = 0;
+            this.overflowSent = false;
+        }
+        this.eventCount++;
+        if (this.eventCount <= this.threshold) {
+            return 'deliver';
+        }
+        if (!this.overflowSent) {
+            this.overflowSent = true;
+            return 'overflow';
+        }
+        return 'drop';
+    }
+}
+exports.EventThrottle = EventThrottle;
 function discoverRealtimeTables(build) {
     const { pgRegistry } = build.input;
     const resources = pgRegistry.pgResources;
@@ -62,32 +146,59 @@ function discoverRealtimeTables(build) {
 }
 function buildTypeDefs(tables) {
     const subscriptionFields = tables
-        .map(({ fieldName, payloadTypeName }) => `  """Subscribe to changes on this table. Pass an id to watch a specific record."""\n  ${fieldName}(id: UUID): ${payloadTypeName}`)
+        .map(({ fieldName, payloadTypeName }) => `  """Subscribe to changes on this table. Pass ids to watch specific rows, or no args for the full collection."""\n  ${fieldName}(ids: [UUID!]): ${payloadTypeName}`)
         .join('\n');
     const payloadTypes = tables
         .map(({ payloadTypeName, typeName, rowFieldName }) => `"""Payload delivered when a ${typeName} row changes."""\n` +
         `type ${payloadTypeName} {\n` +
-        `  """The DML operation: INSERT, UPDATE, or DELETE."""\n` +
+        `  """The DML operation: INSERT, UPDATE, DELETE, or INVALIDATE."""\n` +
         `  event: String!\n` +
-        `  """The current state of the row (null for DELETE or if RLS denies access)."""\n` +
+        `  """The current state of the row (null for DELETE, INVALIDATE, or if RLS denies access)."""\n` +
         `  ${rowFieldName}: ${typeName}\n` +
+        `  """The ID of the changed row (null for INVALIDATE, or masked when RLS denies access)."""\n` +
+        `  rowId: UUID\n` +
+        `  """True when too many changes occurred and the client should refetch."""\n` +
+        `  overflow: Boolean!\n` +
         `}`)
         .join('\n\n');
     return `extend type Subscription {\n${subscriptionFields}\n}\n\n${payloadTypes}`;
 }
-function buildPlans(tables) {
+function buildPlans(tables, overflowThreshold) {
     const subscriptionPlans = {};
     const allPlans = {};
     for (const { resource, fieldName, payloadTypeName, rowFieldName, notifyChannel } of tables) {
+        const throttle = new EventThrottle(overflowThreshold);
         subscriptionPlans[fieldName] = {
             subscribePlan(_$root, args) {
                 const $pgSubscriber = (0, grafast_1.context)().get('pgSubscriber');
                 const $topic = (0, grafast_1.constant)(notifyChannel);
-                const $id = args.get('id');
+                const $ids = args.get('ids');
                 return (0, grafast_1.listen)($pgSubscriber, $topic, ($payload) => {
+                    const $parsed = (0, grafast_1.lambda)([$payload, $ids], (pair) => {
+                        const [raw, subscribedIds] = pair;
+                        const parsed = parseNotifyPayload(String(raw));
+                        const action = parsed.overflow ? 'deliver' : throttle.check();
+                        if (action === 'drop') {
+                            return null;
+                        }
+                        if (action === 'overflow') {
+                            return {
+                                event: 'INVALIDATE',
+                                rowIds: [],
+                                overflow: true,
+                            };
+                        }
+                        // Sparse set filtering: only deliver events for subscribed row IDs
+                        if (subscribedIds && subscribedIds.length > 0) {
+                            const hasMatch = parsed.rowIds.some((rid) => subscribedIds.includes(rid));
+                            if (!hasMatch)
+                                return null;
+                        }
+                        return parsed;
+                    });
                     return (0, grafast_1.object)({
-                        event: $payload,
-                        subscribedId: $id,
+                        parsed: $parsed,
+                        subscribedIds: $ids,
                     });
                 });
             },
@@ -97,18 +208,50 @@ function buildPlans(tables) {
         };
         allPlans[payloadTypeName] = {
             event($parent) {
-                return $parent.get('event');
+                const $parsed = $parent.get('parsed');
+                return (0, grafast_1.lambda)($parsed, (p) => p?.event ?? 'UNKNOWN');
+            },
+            rowId($parent) {
+                const $parsed = $parent.get('parsed');
+                const $subscribedIds = $parent.get('subscribedIds');
+                return (0, grafast_1.lambda)([$parsed, $subscribedIds], (pair) => {
+                    const [p, subscribedIds] = pair;
+                    if (!p || p.overflow || p.rowIds.length === 0)
+                        return null;
+                    // When ids are provided, return the first matching row ID
+                    if (subscribedIds && subscribedIds.length > 0) {
+                        return p.rowIds.find((rid) => subscribedIds.includes(rid)) ?? null;
+                    }
+                    return p.rowIds[0];
+                });
+            },
+            overflow($parent) {
+                const $parsed = $parent.get('parsed');
+                return (0, grafast_1.lambda)($parsed, (p) => p?.overflow ?? false);
             },
             [rowFieldName]($parent) {
-                const $id = $parent.get('subscribedId');
-                return resource.get({ id: $id });
+                const $parsed = $parent.get('parsed');
+                const $subscribedIds = $parent.get('subscribedIds');
+                const $rowId = (0, grafast_1.lambda)([$parsed, $subscribedIds], (tuple) => {
+                    const [p, subscribedIds] = tuple;
+                    if (!p || p.overflow || p.rowIds.length === 0)
+                        return null;
+                    // When ids are provided, return first matching row ID
+                    if (subscribedIds && subscribedIds.length > 0) {
+                        return p.rowIds.find((rid) => subscribedIds.includes(rid)) ?? null;
+                    }
+                    // Full collection mode: return first row ID
+                    return p.rowIds[0];
+                });
+                return resource.get({ id: $rowId });
             },
         };
     }
     allPlans['Subscription'] = subscriptionPlans;
     return allPlans;
 }
-function createRealtimeSubscriptionsPlugin(_options = {}) {
+function createRealtimeSubscriptionsPlugin(options = {}) {
+    const overflowThreshold = options.overflowThreshold ?? DEFAULT_OVERFLOW_THRESHOLD;
     return (0, graphile_utils_1.extendSchema)((build) => {
         const tables = discoverRealtimeTables(build);
         if (tables.length === 0) {
@@ -116,8 +259,14 @@ function createRealtimeSubscriptionsPlugin(_options = {}) {
             return { typeDefs: '', plans: {} };
         }
         log.info(`Generating subscription fields for ${tables.length} realtime table(s)`);
+        log.info(`Overflow threshold: ${overflowThreshold} events/second/table`);
         const typeDefs = buildTypeDefs(tables);
-        const plans = buildPlans(tables);
+        const plans = buildPlans(tables, overflowThreshold);
         return { typeDefs, plans };
     }, 'RealtimeSubscriptionsPlugin');
 }
+// Re-export CursorTracker and RealtimeManager for convenience
+var cursor_tracker_1 = require("./cursor-tracker");
+Object.defineProperty(exports, "CursorTracker", { enumerable: true, get: function () { return cursor_tracker_1.CursorTracker; } });
+var realtime_manager_1 = require("./realtime-manager");
+Object.defineProperty(exports, "RealtimeManager", { enumerable: true, get: function () { return realtime_manager_1.RealtimeManager; } });

package/realtime-manager.d.ts

@@ -0,0 +1,67 @@
+/**
+ * RealtimeManager — bridges CursorTracker (polling drain_changes) into
+ * PostGraphile's PgSubscriber so cursor-tracked events flow through the
+ * same subscription plans as NOTIFY events.
+ *
+ * Architecture:
+ *   PgSubscriber uses an internal EventEmitter. NOTIFY payloads arrive via
+ *   pg's `notification` event and are emitted as `eventEmitter.emit(channel, payload)`.
+ *   The `listen()` step in grafast subscribes to the same EventEmitter.
+ *
+ *   RealtimeManager converts ChangeLogEntry objects from drain_changes() into
+ *   the same NOTIFY payload format ("OP:rowId1,rowId2,...") and emits them on
+ *   the PgSubscriber's EventEmitter, so existing subscription plans handle
+ *   them identically to real NOTIFY events.
+ *
+ *   This provides at-least-once delivery: NOTIFY is instant but best-effort;
+ *   cursor polling catches up on anything missed (disconnects, restarts).
+ *   Duplicates are expected and acceptable — clients should be idempotent.
+ *
+ * Lifecycle:
+ *   1. start() → registers listener node, begins polling + heartbeat
+ *   2. drain_changes() results are converted and emitted on PgSubscriber
+ *   3. stop() → cleans up ephemeral subscriptions, removes listener node
+ */
+import type { ChangeLogEntry, RealtimeManagerOptions } from './types';
+/**
+ * Extract row IDs from a ChangeLogEntry.
+ *
+ * For INSERT/UPDATE the row ID lives in payload_after.id;
+ * for DELETE it lives in payload_before.id.
+ * Falls back to the change_log entry's own id if payloads are missing.
+ */
+declare function extractRowId(entry: ChangeLogEntry): string | null;
+/**
+ * Convert a ChangeLogEntry into the NOTIFY payload format used by emit_change.
+ * Format: "OPERATION:rowId" (e.g. "INSERT:550e8400-...")
+ */
+declare function entryToNotifyPayload(entry: ChangeLogEntry): string;
+/**
+ * Build the NOTIFY channel name for a change_log entry.
+ * Matches the channel format used by emit_change: "realtime:{schema}.{table}"
+ */
+declare function entryToChannel(entry: ChangeLogEntry): string;
+export declare class RealtimeManager {
+    private readonly cursorTracker;
+    private readonly subscriber;
+    private started;
+    constructor(options: RealtimeManagerOptions);
+    get nodeId(): string;
+    get isRunning(): boolean;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /**
+     * Convert ChangeLogEntry objects to NOTIFY-format payloads and emit
+     * them on the PgSubscriber's internal EventEmitter.
+     */
+    private dispatchEntries;
+    /**
+     * Access PgSubscriber's internal EventEmitter.
+     *
+     * PgSubscriber from @dataplan/pg stores an EventEmitter3 instance as
+     * `this.eventEmitter`. It is private but stable across v1.x releases.
+     * This is the same emitter that NOTIFY events are dispatched through.
+     */
+    private getEventEmitter;
+}
+export { extractRowId, entryToNotifyPayload, entryToChannel };

package/realtime-manager.js

@@ -0,0 +1,140 @@
+"use strict";
+/**
+ * RealtimeManager — bridges CursorTracker (polling drain_changes) into
+ * PostGraphile's PgSubscriber so cursor-tracked events flow through the
+ * same subscription plans as NOTIFY events.
+ *
+ * Architecture:
+ *   PgSubscriber uses an internal EventEmitter. NOTIFY payloads arrive via
+ *   pg's `notification` event and are emitted as `eventEmitter.emit(channel, payload)`.
+ *   The `listen()` step in grafast subscribes to the same EventEmitter.
+ *
+ *   RealtimeManager converts ChangeLogEntry objects from drain_changes() into
+ *   the same NOTIFY payload format ("OP:rowId1,rowId2,...") and emits them on
+ *   the PgSubscriber's EventEmitter, so existing subscription plans handle
+ *   them identically to real NOTIFY events.
+ *
+ *   This provides at-least-once delivery: NOTIFY is instant but best-effort;
+ *   cursor polling catches up on anything missed (disconnects, restarts).
+ *   Duplicates are expected and acceptable — clients should be idempotent.
+ *
+ * Lifecycle:
+ *   1. start() → registers listener node, begins polling + heartbeat
+ *   2. drain_changes() results are converted and emitted on PgSubscriber
+ *   3. stop() → cleans up ephemeral subscriptions, removes listener node
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RealtimeManager = void 0;
+exports.extractRowId = extractRowId;
+exports.entryToNotifyPayload = entryToNotifyPayload;
+exports.entryToChannel = entryToChannel;
+const logger_1 = require("@pgpmjs/logger");
+const cursor_tracker_1 = require("./cursor-tracker");
+const log = new logger_1.Logger('realtime-manager');
+/**
+ * Extract row IDs from a ChangeLogEntry.
+ *
+ * For INSERT/UPDATE the row ID lives in payload_after.id;
+ * for DELETE it lives in payload_before.id.
+ * Falls back to the change_log entry's own id if payloads are missing.
+ */
+function extractRowId(entry) {
+    if (entry.operation === 'DELETE') {
+        return entry.payload_before?.id ?? null;
+    }
+    return entry.payload_after?.id ?? null;
+}
+/**
+ * Convert a ChangeLogEntry into the NOTIFY payload format used by emit_change.
+ * Format: "OPERATION:rowId" (e.g. "INSERT:550e8400-...")
+ */
+function entryToNotifyPayload(entry) {
+    const rowId = extractRowId(entry);
+    if (!rowId) {
+        return entry.operation;
+    }
+    return `${entry.operation}:${rowId}`;
+}
+/**
+ * Build the NOTIFY channel name for a change_log entry.
+ * Matches the channel format used by emit_change: "realtime:{schema}.{table}"
+ */
+function entryToChannel(entry) {
+    return `realtime:${entry.source_schema}.${entry.source_table}`;
+}
+class RealtimeManager {
+    cursorTracker;
+    subscriber;
+    started = false;
+    constructor(options) {
+        const { pgSubscriber, withPgClient, ...cursorOpts } = options;
+        this.subscriber = pgSubscriber;
+        this.cursorTracker = new cursor_tracker_1.CursorTracker({
+            nodeId: cursorOpts.nodeId,
+            schema: cursorOpts.schema,
+            pollIntervalMs: cursorOpts.pollIntervalMs,
+            heartbeatIntervalMs: cursorOpts.heartbeatIntervalMs,
+            batchLimit: cursorOpts.batchLimit,
+            withPgClient,
+            onChanges: (entries) => this.dispatchEntries(entries),
+            onError: cursorOpts.onError ?? ((err) => {
+                log.error(`RealtimeManager error: ${err.message}`);
+            }),
+        });
+    }
+    get nodeId() {
+        return this.cursorTracker.nodeId;
+    }
+    get isRunning() {
+        return this.started && this.cursorTracker.isRunning;
+    }
+    async start() {
+        if (this.started)
+            return;
+        this.started = true;
+        log.info(`Starting RealtimeManager: node=${this.nodeId}`);
+        await this.cursorTracker.start();
+    }
+    async stop() {
+        if (!this.started)
+            return;
+        this.started = false;
+        log.info(`Stopping RealtimeManager: node=${this.nodeId}`);
+        await this.cursorTracker.stop();
+    }
+    /**
+     * Convert ChangeLogEntry objects to NOTIFY-format payloads and emit
+     * them on the PgSubscriber's internal EventEmitter.
+     */
+    dispatchEntries(entries) {
+        const emitter = this.getEventEmitter();
+        if (!emitter) {
+            log.warn('PgSubscriber has no eventEmitter; cursor events cannot be dispatched');
+            return;
+        }
+        for (const entry of entries) {
+            const channel = entryToChannel(entry);
+            const payload = entryToNotifyPayload(entry);
+            emitter.emit(channel, payload);
+        }
+        log.info(`Dispatched ${entries.length} cursor-tracked event(s) to PgSubscriber`);
+    }
+    /**
+     * Access PgSubscriber's internal EventEmitter.
+     *
+     * PgSubscriber from @dataplan/pg stores an EventEmitter3 instance as
+     * `this.eventEmitter`. It is private but stable across v1.x releases.
+     * This is the same emitter that NOTIFY events are dispatched through.
+     */
+    getEventEmitter() {
+        const sub = this.subscriber;
+        if (sub && typeof sub === 'object' && 'eventEmitter' in sub) {
+            const ee = sub.eventEmitter;
+            if (typeof ee?.emit === 'function') {
+                return ee;
+            }
+        }
+        return null;
+    }
+}
+exports.RealtimeManager = RealtimeManager;