graphile-realtime-subscriptions 0.3.0 → 0.5.0

package/cursor-tracker.d.ts

@@ -0,0 +1,42 @@
+/**
+ * CursorTracker — manages the listener_node lifecycle and periodic
+ * drain_changes() polling for at-least-once event delivery.
+ *
+ * Lifecycle:
+ *   1. start() → calls touch_listener() to register/heartbeat the node
+ *   2. Periodically polls drain_changes() for new change_log entries
+ *   3. Periodically heartbeats via touch_listener()
+ *   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.
+ */
+import type { CursorTrackerOptions, ChangeLogEntry } from './types';
+declare const DEFAULT_POLL_INTERVAL_MS = 5000;
+declare const DEFAULT_HEARTBEAT_INTERVAL_MS = 30000;
+declare const DEFAULT_BATCH_LIMIT = 500;
+declare const DEFAULT_SCHEMA = "realtime_public";
+export declare class CursorTracker {
+    readonly nodeId: string;
+    private readonly schema;
+    private readonly pollIntervalMs;
+    private readonly heartbeatIntervalMs;
+    private readonly batchLimit;
+    private readonly withPgClient;
+    private readonly onChanges;
+    private readonly onError;
+    private pollTimer;
+    private heartbeatTimer;
+    private running;
+    private draining;
+    constructor(options: CursorTrackerOptions);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    drain(): Promise<ChangeLogEntry[]>;
+    touchListener(): Promise<void>;
+    cleanupEphemeral(): Promise<void>;
+    get isRunning(): boolean;
+    private quoteIdent;
+}
+export { DEFAULT_POLL_INTERVAL_MS, DEFAULT_HEARTBEAT_INTERVAL_MS, DEFAULT_BATCH_LIMIT, DEFAULT_SCHEMA, };

package/cursor-tracker.js

@@ -0,0 +1,139 @@
+"use strict";
+/**
+ * CursorTracker — manages the listener_node lifecycle and periodic
+ * drain_changes() polling for at-least-once event delivery.
+ *
+ * Lifecycle:
+ *   1. start() → calls touch_listener() to register/heartbeat the node
+ *   2. Periodically polls drain_changes() for new change_log entries
+ *   3. Periodically heartbeats via touch_listener()
+ *   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.
+ */
+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;
+const crypto_1 = require("crypto");
+const logger_1 = require("@pgpmjs/logger");
+const quotes_1 = require("@pgsql/quotes");
+const log = new logger_1.Logger('cursor-tracker');
+const DEFAULT_POLL_INTERVAL_MS = 5000;
+exports.DEFAULT_POLL_INTERVAL_MS = DEFAULT_POLL_INTERVAL_MS;
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 30000;
+exports.DEFAULT_HEARTBEAT_INTERVAL_MS = DEFAULT_HEARTBEAT_INTERVAL_MS;
+const DEFAULT_BATCH_LIMIT = 500;
+exports.DEFAULT_BATCH_LIMIT = DEFAULT_BATCH_LIMIT;
+const DEFAULT_SCHEMA = 'realtime_public';
+exports.DEFAULT_SCHEMA = DEFAULT_SCHEMA;
+class CursorTracker {
+    nodeId;
+    schema;
+    pollIntervalMs;
+    heartbeatIntervalMs;
+    batchLimit;
+    withPgClient;
+    onChanges;
+    onError;
+    pollTimer = null;
+    heartbeatTimer = null;
+    running = false;
+    draining = false;
+    constructor(options) {
+        this.nodeId = options.nodeId ?? (0, crypto_1.randomUUID)();
+        this.schema = options.schema ?? DEFAULT_SCHEMA;
+        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.onChanges = options.onChanges ?? (() => { });
+        this.onError = options.onError ?? ((err) => {
+            log.error(`CursorTracker error: ${err.message}`);
+        });
+    }
+    async start() {
+        if (this.running)
+            return;
+        this.running = true;
+        log.info(`Starting cursor tracker: node=${this.nodeId}, schema=${this.schema}`);
+        await this.touchListener();
+        // Initial drain immediately after registration
+        await this.drain();
+        this.pollTimer = setInterval(() => {
+            void this.drain();
+        }, this.pollIntervalMs);
+        this.heartbeatTimer = setInterval(() => {
+            void this.touchListener();
+        }, this.heartbeatIntervalMs);
+    }
+    async stop() {
+        if (!this.running)
+            return;
+        this.running = false;
+        log.info(`Stopping cursor tracker: node=${this.nodeId}`);
+        if (this.pollTimer) {
+            clearInterval(this.pollTimer);
+            this.pollTimer = null;
+        }
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+        await this.cleanupEphemeral();
+    }
+    async drain() {
+        if (this.draining)
+            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);
+            });
+            if (entries.length > 0) {
+                log.info(`Drained ${entries.length} change(s) for node=${this.nodeId}`);
+                this.onChanges(entries);
+            }
+            return entries;
+        }
+        catch (err) {
+            this.onError(err instanceof Error ? err : new Error(String(err)));
+            return [];
+        }
+        finally {
+            this.draining = false;
+        }
+    }
+    async touchListener() {
+        try {
+            await this.withPgClient(async (client) => {
+                const sql = `SELECT ${this.quoteIdent(this.schema)}.touch_listener($1)`;
+                await client.query(sql, [this.nodeId]);
+            });
+        }
+        catch (err) {
+            this.onError(err instanceof Error ? err : new Error(String(err)));
+        }
+    }
+    async cleanupEphemeral() {
+        try {
+            await this.withPgClient(async (client) => {
+                const sql = `SELECT ${this.quoteIdent(this.schema)}.cleanup_ephemeral($1)`;
+                await client.query(sql, [this.nodeId]);
+            });
+            log.info(`Cleaned up ephemeral subscriptions for node=${this.nodeId}`);
+        }
+        catch (err) {
+            this.onError(err instanceof Error ? err : new Error(String(err)));
+        }
+    }
+    get isRunning() {
+        return this.running;
+    }
+    quoteIdent(identifier) {
+        return quotes_1.QuoteUtils.quoteIdentifier(identifier);
+    }
+}
+exports.CursorTracker = CursorTracker;

package/esm/cursor-tracker.d.ts

@@ -0,0 +1,42 @@
+/**
+ * CursorTracker — manages the listener_node lifecycle and periodic
+ * drain_changes() polling for at-least-once event delivery.
+ *
+ * Lifecycle:
+ *   1. start() → calls touch_listener() to register/heartbeat the node
+ *   2. Periodically polls drain_changes() for new change_log entries
+ *   3. Periodically heartbeats via touch_listener()
+ *   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.
+ */
+import type { CursorTrackerOptions, ChangeLogEntry } from './types';
+declare const DEFAULT_POLL_INTERVAL_MS = 5000;
+declare const DEFAULT_HEARTBEAT_INTERVAL_MS = 30000;
+declare const DEFAULT_BATCH_LIMIT = 500;
+declare const DEFAULT_SCHEMA = "realtime_public";
+export declare class CursorTracker {
+    readonly nodeId: string;
+    private readonly schema;
+    private readonly pollIntervalMs;
+    private readonly heartbeatIntervalMs;
+    private readonly batchLimit;
+    private readonly withPgClient;
+    private readonly onChanges;
+    private readonly onError;
+    private pollTimer;
+    private heartbeatTimer;
+    private running;
+    private draining;
+    constructor(options: CursorTrackerOptions);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    drain(): Promise<ChangeLogEntry[]>;
+    touchListener(): Promise<void>;
+    cleanupEphemeral(): Promise<void>;
+    get isRunning(): boolean;
+    private quoteIdent;
+}
+export { DEFAULT_POLL_INTERVAL_MS, DEFAULT_HEARTBEAT_INTERVAL_MS, DEFAULT_BATCH_LIMIT, DEFAULT_SCHEMA, };

package/esm/cursor-tracker.js

@@ -0,0 +1,132 @@
+/**
+ * CursorTracker — manages the listener_node lifecycle and periodic
+ * drain_changes() polling for at-least-once event delivery.
+ *
+ * Lifecycle:
+ *   1. start() → calls touch_listener() to register/heartbeat the node
+ *   2. Periodically polls drain_changes() for new change_log entries
+ *   3. Periodically heartbeats via touch_listener()
+ *   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.
+ */
+import { randomUUID } from 'crypto';
+import { Logger } from '@pgpmjs/logger';
+import { QuoteUtils } from '@pgsql/quotes';
+const log = new Logger('cursor-tracker');
+const DEFAULT_POLL_INTERVAL_MS = 5000;
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 30000;
+const DEFAULT_BATCH_LIMIT = 500;
+const DEFAULT_SCHEMA = 'realtime_public';
+export class CursorTracker {
+    nodeId;
+    schema;
+    pollIntervalMs;
+    heartbeatIntervalMs;
+    batchLimit;
+    withPgClient;
+    onChanges;
+    onError;
+    pollTimer = null;
+    heartbeatTimer = null;
+    running = false;
+    draining = false;
+    constructor(options) {
+        this.nodeId = options.nodeId ?? randomUUID();
+        this.schema = options.schema ?? DEFAULT_SCHEMA;
+        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.onChanges = options.onChanges ?? (() => { });
+        this.onError = options.onError ?? ((err) => {
+            log.error(`CursorTracker error: ${err.message}`);
+        });
+    }
+    async start() {
+        if (this.running)
+            return;
+        this.running = true;
+        log.info(`Starting cursor tracker: node=${this.nodeId}, schema=${this.schema}`);
+        await this.touchListener();
+        // Initial drain immediately after registration
+        await this.drain();
+        this.pollTimer = setInterval(() => {
+            void this.drain();
+        }, this.pollIntervalMs);
+        this.heartbeatTimer = setInterval(() => {
+            void this.touchListener();
+        }, this.heartbeatIntervalMs);
+    }
+    async stop() {
+        if (!this.running)
+            return;
+        this.running = false;
+        log.info(`Stopping cursor tracker: node=${this.nodeId}`);
+        if (this.pollTimer) {
+            clearInterval(this.pollTimer);
+            this.pollTimer = null;
+        }
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+        await this.cleanupEphemeral();
+    }
+    async drain() {
+        if (this.draining)
+            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);
+            });
+            if (entries.length > 0) {
+                log.info(`Drained ${entries.length} change(s) for node=${this.nodeId}`);
+                this.onChanges(entries);
+            }
+            return entries;
+        }
+        catch (err) {
+            this.onError(err instanceof Error ? err : new Error(String(err)));
+            return [];
+        }
+        finally {
+            this.draining = false;
+        }
+    }
+    async touchListener() {
+        try {
+            await this.withPgClient(async (client) => {
+                const sql = `SELECT ${this.quoteIdent(this.schema)}.touch_listener($1)`;
+                await client.query(sql, [this.nodeId]);
+            });
+        }
+        catch (err) {
+            this.onError(err instanceof Error ? err : new Error(String(err)));
+        }
+    }
+    async cleanupEphemeral() {
+        try {
+            await this.withPgClient(async (client) => {
+                const sql = `SELECT ${this.quoteIdent(this.schema)}.cleanup_ephemeral($1)`;
+                await client.query(sql, [this.nodeId]);
+            });
+            log.info(`Cleaned up ephemeral subscriptions for node=${this.nodeId}`);
+        }
+        catch (err) {
+            this.onError(err instanceof Error ? err : new Error(String(err)));
+        }
+    }
+    get isRunning() {
+        return this.running;
+    }
+    quoteIdent(identifier) {
+        return QuoteUtils.quoteIdentifier(identifier);
+    }
+}
+export { DEFAULT_POLL_INTERVAL_MS, DEFAULT_HEARTBEAT_INTERVAL_MS, DEFAULT_BATCH_LIMIT, DEFAULT_SCHEMA, };

package/esm/index.d.ts

@@ -18,4 +18,7 @@
  */
 export { createRealtimeSubscriptionsPlugin, RealtimeSubscriptionsPlugin } from './plugin';
 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';

package/esm/index.js

@@ -18,3 +18,5 @@
  */
 export { createRealtimeSubscriptionsPlugin, RealtimeSubscriptionsPlugin } from './plugin';
 export { RealtimeSubscriptionsPreset } from './preset';
+export { CursorTracker } from './cursor-tracker';
+export { RealtimeManager } from './realtime-manager';

package/esm/plugin.d.ts

@@ -6,7 +6,7 @@
  * for real-time event delivery.
  *
  * Subscription modes:
- *   - Single record: onXxxChanged(id: UUID!) — subscribe to changes on one row
+ *   - 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):
@@ -20,13 +20,30 @@
  *   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.
  */
 import type { GraphileConfig } from 'graphile-config';
 import type { RealtimeSubscriptionsPluginOptions } from './types';
@@ -61,4 +78,7 @@ declare class EventThrottle {
 }
 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/esm/plugin.js

@@ -6,7 +6,7 @@
  * for real-time event delivery.
  *
  * Subscription modes:
- *   - Single record: onXxxChanged(id: UUID!) — subscribe to changes on one row
+ *   - 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):
@@ -20,13 +20,30 @@
  *   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.
  */
 import { context as grafastContext, listen, object, constant, lambda } from 'grafast';
 import { extendSchema } from 'graphile-utils';
@@ -121,7 +138,7 @@ 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` +
@@ -130,7 +147,7 @@ function buildTypeDefs(tables) {
         `  event: String!\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)."""\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` +
@@ -147,9 +164,10 @@ function buildPlans(tables, overflowThreshold) {
             subscribePlan(_$root, args) {
                 const $pgSubscriber = grafastContext().get('pgSubscriber');
                 const $topic = constant(notifyChannel);
-                const $id = args.get('id');
+                const $ids = args.get('ids');
                 return listen($pgSubscriber, $topic, ($payload) => {
-                    const $parsed = lambda($payload, (raw) => {
+                    const $parsed = lambda([$payload, $ids], (pair) => {
+                        const [raw, subscribedIds] = pair;
                         const parsed = parseNotifyPayload(String(raw));
                         const action = parsed.overflow ? 'deliver' : throttle.check();
                         if (action === 'drop') {
@@ -162,11 +180,17 @@ function buildPlans(tables, overflowThreshold) {
                                 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 object({
                         parsed: $parsed,
-                        subscribedId: $id,
+                        subscribedIds: $ids,
                     });
                 });
             },
@@ -181,11 +205,16 @@ function buildPlans(tables, overflowThreshold) {
             },
             rowId($parent) {
                 const $parsed = $parent.get('parsed');
-                return lambda($parsed, (p) => {
-                    const parsed = p;
-                    if (!parsed || parsed.overflow || parsed.rowIds.length === 0)
+                const $subscribedIds = $parent.get('subscribedIds');
+                return lambda([$parsed, $subscribedIds], (pair) => {
+                    const [p, subscribedIds] = pair;
+                    if (!p || p.overflow || p.rowIds.length === 0)
                         return null;
-                    return parsed.rowIds[0];
+                    // 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) {
@@ -194,13 +223,16 @@ function buildPlans(tables, overflowThreshold) {
             },
             [rowFieldName]($parent) {
                 const $parsed = $parent.get('parsed');
-                const $subscribedId = $parent.get('subscribedId');
-                const $rowId = lambda([$parsed, $subscribedId], (pair) => {
-                    const [p, subscribedId] = pair;
-                    if (subscribedId)
-                        return subscribedId;
+                const $subscribedIds = $parent.get('subscribedIds');
+                const $rowId = 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 });
@@ -226,5 +258,8 @@ export function createRealtimeSubscriptionsPlugin(options = {}) {
     }, 'RealtimeSubscriptionsPlugin');
 }
 export { createRealtimeSubscriptionsPlugin as RealtimeSubscriptionsPlugin };
+// Re-export CursorTracker and RealtimeManager for convenience
+export { CursorTracker } from './cursor-tracker';
+export { RealtimeManager } from './realtime-manager';
 // Exported for testing
 export { parseNotifyPayload, EventThrottle, DEFAULT_OVERFLOW_THRESHOLD };

package/esm/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 };