graphile-realtime-subscriptions 0.2.0 → 0.3.0

package/esm/plugin.d.ts

@@ -5,21 +5,60 @@
  * subscription fields (onXxxChanged) that use PostgreSQL LISTEN/NOTIFY
  * for real-time event delivery.
  *
- * Subscription modes (Phase 3a):
+ * Subscription modes:
  *   - Single record: onXxxChanged(id: UUID!) — subscribe to changes on one row
  *   - 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 }
+ *
+ * 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.
  */
 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 { parseNotifyPayload, EventThrottle, DEFAULT_OVERFLOW_THRESHOLD };

package/esm/plugin.js

@@ -5,24 +5,87 @@
  * subscription fields (onXxxChanged) that use PostgreSQL LISTEN/NOTIFY
  * for real-time event delivery.
  *
- * Subscription modes (Phase 3a):
+ * Subscription modes:
  *   - Single record: onXxxChanged(id: UUID!) — subscribe to changes on one row
  *   - 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 }
+ *
+ * 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.
  */
-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;
@@ -63,26 +126,46 @@ function buildTypeDefs(tables) {
     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)."""\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');
                 return listen($pgSubscriber, $topic, ($payload) => {
+                    const $parsed = lambda($payload, (raw) => {
+                        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,
+                            };
+                        }
+                        return parsed;
+                    });
                     return object({
-                        event: $payload,
+                        parsed: $parsed,
                         subscribedId: $id,
                     });
                 });
@@ -93,18 +176,42 @@ 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');
+                return lambda($parsed, (p) => {
+                    const parsed = p;
+                    if (!parsed || parsed.overflow || parsed.rowIds.length === 0)
+                        return null;
+                    return parsed.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 $subscribedId = $parent.get('subscribedId');
+                const $rowId = lambda([$parsed, $subscribedId], (pair) => {
+                    const [p, subscribedId] = pair;
+                    if (subscribedId)
+                        return subscribedId;
+                    if (!p || p.overflow || p.rowIds.length === 0)
+                        return null;
+                    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 +219,12 @@ 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 };
+// Exported for testing
+export { parseNotifyPayload, EventThrottle, DEFAULT_OVERFLOW_THRESHOLD };

package/esm/types.d.ts

@@ -1,9 +1,14 @@
 /**
  * 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;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphile-realtime-subscriptions",
-  "version": "0.2.0",
+  "version": "0.3.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",
@@ -55,5 +55,5 @@
     "@types/node": "^22.19.11",
     "makage": "^0.3.0"
   },
-  "gitHead": "c87dafec1ccb2c3cc62f2304584104db108a810b"
+  "gitHead": "4a575e3e29827e96979cb6aac2c88eb7a07f7fd0"
 }

package/plugin.d.ts

@@ -5,21 +5,60 @@
  * subscription fields (onXxxChanged) that use PostgreSQL LISTEN/NOTIFY
  * for real-time event delivery.
  *
- * Subscription modes (Phase 3a):
+ * Subscription modes:
  *   - Single record: onXxxChanged(id: UUID!) — subscribe to changes on one row
  *   - 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 }
+ *
+ * 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.
  */
 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 { parseNotifyPayload, EventThrottle, DEFAULT_OVERFLOW_THRESHOLD };

package/plugin.js

@@ -6,27 +6,94 @@
  * subscription fields (onXxxChanged) that use PostgreSQL LISTEN/NOTIFY
  * for real-time event delivery.
  *
- * Subscription modes (Phase 3a):
+ * Subscription modes:
  *   - Single record: onXxxChanged(id: UUID!) — subscribe to changes on one row
  *   - 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 }
+ *
+ * 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.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_OVERFLOW_THRESHOLD = exports.EventThrottle = 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;
@@ -67,26 +134,46 @@ function buildTypeDefs(tables) {
     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)."""\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');
                 return (0, grafast_1.listen)($pgSubscriber, $topic, ($payload) => {
+                    const $parsed = (0, grafast_1.lambda)($payload, (raw) => {
+                        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,
+                            };
+                        }
+                        return parsed;
+                    });
                     return (0, grafast_1.object)({
-                        event: $payload,
+                        parsed: $parsed,
                         subscribedId: $id,
                     });
                 });
@@ -97,18 +184,42 @@ 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');
+                return (0, grafast_1.lambda)($parsed, (p) => {
+                    const parsed = p;
+                    if (!parsed || parsed.overflow || parsed.rowIds.length === 0)
+                        return null;
+                    return parsed.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 $subscribedId = $parent.get('subscribedId');
+                const $rowId = (0, grafast_1.lambda)([$parsed, $subscribedId], (pair) => {
+                    const [p, subscribedId] = pair;
+                    if (subscribedId)
+                        return subscribedId;
+                    if (!p || p.overflow || p.rowIds.length === 0)
+                        return null;
+                    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 +227,9 @@ 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');
 }

package/types.d.ts

@@ -1,9 +1,14 @@
 /**
  * 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;
 }