graphile-realtime-subscriptions 0.2.0 → 0.4.0

package/esm/plugin.js

@@ -5,24 +5,104 @@
  * 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.
  */
-import { context as grafastContext, listen, object, constant } from 'grafast';
+import { context as grafastContext, listen, object, constant, lambda } from 'grafast';
 import { extendSchema } from 'graphile-utils';
 import { Logger } from '@pgpmjs/logger';
 const log = new Logger('graphile-realtime-subscriptions');
+/** Default overflow threshold: events per second per table per subscriber */
+const DEFAULT_OVERFLOW_THRESHOLD = 50;
+/**
+ * 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';
+    }
+}
 function discoverRealtimeTables(build) {
     const { pgRegistry } = build.input;
     const resources = pgRegistry.pgResources;
@@ -58,32 +138,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 = 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, $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 object({
-                        event: $payload,
-                        subscribedId: $id,
+                        parsed: $parsed,
+                        subscribedIds: $ids,
                     });
                 });
             },
@@ -93,18 +200,50 @@ function buildPlans(tables) {
         };
         allPlans[payloadTypeName] = {
             event($parent) {
-                return $parent.get('event');
+                const $parsed = $parent.get('parsed');
+                return lambda($parsed, (p) => p?.event ?? 'UNKNOWN');
+            },
+            rowId($parent) {
+                const $parsed = $parent.get('parsed');
+                const $subscribedIds = $parent.get('subscribedIds');
+                return 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 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 = 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;
 }
-export function createRealtimeSubscriptionsPlugin(_options = {}) {
+export function createRealtimeSubscriptionsPlugin(options = {}) {
+    const overflowThreshold = options.overflowThreshold ?? DEFAULT_OVERFLOW_THRESHOLD;
     return extendSchema((build) => {
         const tables = discoverRealtimeTables(build);
         if (tables.length === 0) {
@@ -112,9 +251,15 @@ export 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');
 }
 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 };

package/esm/realtime-manager.js

@@ -0,0 +1,134 @@
+/**
+ * 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 { Logger } from '@pgpmjs/logger';
+import { CursorTracker } from './cursor-tracker';
+const log = new 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}`;
+}
+export class RealtimeManager {
+    cursorTracker;
+    subscriber;
+    started = false;
+    constructor(options) {
+        const { pgSubscriber, withPgClient, ...cursorOpts } = options;
+        this.subscriber = pgSubscriber;
+        this.cursorTracker = new 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;
+    }
+}
+export { extractRowId, entryToNotifyPayload, entryToChannel };

package/esm/types.d.ts

@@ -1,9 +1,146 @@
 /**
  * Configuration options for the Realtime Subscriptions Plugin.
- *
- * Phase 3a supports single-record and full-collection subscription modes
- * with no additional configuration required. Future phases will add
- * options for poll intervals, batch sizes, and throttling.
  */
 export interface RealtimeSubscriptionsPluginOptions {
+    /**
+     * Maximum number of events per table per second before switching to
+     * overflow (INVALIDATE) mode. When exceeded, the subscription sends
+     * a single { event: 'INVALIDATE', overflow: true } instead of
+     * individual row events, signaling the client to refetch.
+     *
+     * Default: 50
+     */
+    overflowThreshold?: number;
+}
+/**
+ * A minimal PostgreSQL client interface used by CursorTracker.
+ * Compatible with node-postgres (pg) Client or PoolClient.
+ */
+export interface PgClient {
+    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.
+ */
+export interface ChangeLogEntry {
+    id: string;
+    occurred_at: string;
+    source_schema: string;
+    source_table: string;
+    operation: string;
+    payload_after: Record<string, unknown> | null;
+    payload_before: Record<string, unknown> | null;
+    payload_diff: Record<string, unknown> | null;
+    subscriber_ids: string[];
+}
+/**
+ * Configuration for the CursorTracker background poller.
+ */
+export interface CursorTrackerOptions {
+    /**
+     * Unique identifier for this listener node.
+     * Should be stable across restarts if you want cursor continuity.
+     * If not provided, a random ID is generated (ephemeral mode).
+     */
+    nodeId?: string;
+    /**
+     * The realtime_public schema name where drain_changes(),
+     * touch_listener(), and cleanup_ephemeral() live.
+     *
+     * Default: 'realtime_public'
+     */
+    schema?: string;
+    /**
+     * How often to poll drain_changes() for new events (milliseconds).
+     *
+     * Default: 5000 (5 seconds)
+     */
+    pollIntervalMs?: number;
+    /**
+     * How often to send a heartbeat via touch_listener() (milliseconds).
+     *
+     * Default: 30000 (30 seconds)
+     */
+    heartbeatIntervalMs?: number;
+    /**
+     * Maximum number of change_log rows to fetch per drain_changes() call.
+     *
+     * Default: 500
+     */
+    batchLimit?: number;
+    /**
+     * Function to acquire a PgClient for executing queries.
+     * The cursor tracker calls this for every poll and heartbeat cycle.
+     */
+    withPgClient: WithPgClient;
+    /**
+     * Called when drain_changes() returns new change_log entries.
+     * The entries include subscriber_ids for fan-out routing.
+     */
+    onChanges?: (entries: ChangeLogEntry[]) => void;
+    /**
+     * Called when an error occurs during polling, heartbeat, or cleanup.
+     * If not provided, errors are logged to the console.
+     */
+    onError?: (error: Error) => void;
+}
+/**
+ * Configuration for the RealtimeManager, which bridges CursorTracker
+ * events into PostGraphile's PgSubscriber for at-least-once delivery.
+ */
+export interface RealtimeManagerOptions {
+    /**
+     * The PgSubscriber instance from PostGraphile's context.
+     * RealtimeManager emits cursor-tracked events on its internal EventEmitter
+     * so they flow through existing subscription plans.
+     */
+    pgSubscriber: unknown;
+    /**
+     * Function to acquire a PgClient for executing cursor tracking queries.
+     */
+    withPgClient: WithPgClient;
+    /**
+     * Unique identifier for this listener node.
+     * Should be stable across restarts if you want cursor continuity.
+     * If not provided, a random ID is generated (ephemeral mode).
+     */
+    nodeId?: string;
+    /**
+     * The realtime_public schema name where drain_changes(),
+     * touch_listener(), and cleanup_ephemeral() live.
+     *
+     * Default: 'realtime_public'
+     */
+    schema?: string;
+    /**
+     * How often to poll drain_changes() for new events (milliseconds).
+     *
+     * Default: 5000 (5 seconds)
+     */
+    pollIntervalMs?: number;
+    /**
+     * How often to send a heartbeat via touch_listener() (milliseconds).
+     *
+     * Default: 30000 (30 seconds)
+     */
+    heartbeatIntervalMs?: number;
+    /**
+     * Maximum number of change_log rows to fetch per drain_changes() call.
+     *
+     * Default: 500
+     */
+    batchLimit?: number;
+    /**
+     * Called when an error occurs during polling, heartbeat, or cleanup.
+     * If not provided, errors are logged via @pgpmjs/logger.
+     */
+    onError?: (error: Error) => void;
 }

package/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/index.js

@@ -18,9 +18,13 @@
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RealtimeSubscriptionsPreset = exports.RealtimeSubscriptionsPlugin = exports.createRealtimeSubscriptionsPlugin = void 0;
+exports.RealtimeManager = exports.CursorTracker = exports.RealtimeSubscriptionsPreset = exports.RealtimeSubscriptionsPlugin = exports.createRealtimeSubscriptionsPlugin = void 0;
 var plugin_1 = require("./plugin");
 Object.defineProperty(exports, "createRealtimeSubscriptionsPlugin", { enumerable: true, get: function () { return plugin_1.createRealtimeSubscriptionsPlugin; } });
 Object.defineProperty(exports, "RealtimeSubscriptionsPlugin", { enumerable: true, get: function () { return plugin_1.RealtimeSubscriptionsPlugin; } });
 var preset_1 = require("./preset");
 Object.defineProperty(exports, "RealtimeSubscriptionsPreset", { enumerable: true, get: function () { return preset_1.RealtimeSubscriptionsPreset; } });
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphile-realtime-subscriptions",
-  "version": "0.2.0",
+  "version": "0.4.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,8 @@
     "url": "https://github.com/constructive-io/constructive/issues"
   },
   "dependencies": {
-    "@pgpmjs/logger": "^2.9.0"
+    "@pgpmjs/logger": "^2.9.0",
+    "@pgsql/quotes": "^17.1.0"
   },
   "peerDependencies": {
     "grafast": "1.0.0",
@@ -55,5 +56,5 @@
     "@types/node": "^22.19.11",
     "makage": "^0.3.0"
   },
-  "gitHead": "c87dafec1ccb2c3cc62f2304584104db108a810b"
+  "gitHead": "b54aef52c81be35a53e771003939d447aa34ba35"
 }