graphile-realtime-subscriptions 0.2.0

package/LICENSE

@@ -0,0 +1,23 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Dan Lynch <pyramation@gmail.com>
+Copyright (c) 2025 Constructive <developers@constructive.io>
+Copyright (c) 2020-present, Interweb, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,92 @@
+# graphile-realtime-subscriptions
+
+Realtime subscription plugin for PostGraphile v5 — per-table GraphQL subscriptions via LISTEN/NOTIFY.
+
+## Overview
+
+Discovers tables tagged with `@realtime` and generates per-table GraphQL subscription fields (`onXxxChanged`) that use PostgreSQL LISTEN/NOTIFY for real-time event delivery with automatic RLS enforcement.
+
+## Usage
+
+```typescript
+import { RealtimeSubscriptionsPreset } from 'graphile-realtime-subscriptions';
+
+const preset = {
+  extends: [
+    RealtimeSubscriptionsPreset(),
+  ],
+};
+```
+
+## How It Works
+
+1. A row is inserted/updated/deleted on a `@realtime`-tagged table
+2. The `emit_change` trigger fires `pg_notify('realtime:{schema}.{table}', TG_OP)`
+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
+
+## Subscription Modes
+
+### Phase 3a (current)
+
+- **Single record**: `onXxxChanged(id: UUID!)` — subscribe to changes on one row
+- **Full collection**: `onXxxChanged` (no args) — subscribe to any change on the table
+
+---
+
+## Education and Tutorials
+
+ 1. 🚀 [Quickstart: Getting Up and Running](https://constructive.io/learn/quickstart)
+Get started with modular databases in minutes. Install prerequisites and deploy your first module.
+
+ 2. 📦 [Modular PostgreSQL Development with Database Packages](https://constructive.io/learn/modular-postgres)
+Learn to organize PostgreSQL projects with pgpm workspaces and reusable database modules.
+
+ 3. ✏️ [Authoring Database Changes](https://constructive.io/learn/authoring-database-changes)
+Master the workflow for adding, organizing, and managing database changes with pgpm.
+
+ 4. 🧪 [End-to-End PostgreSQL Testing with TypeScript](https://constructive.io/learn/e2e-postgres-testing)
+Master end-to-end PostgreSQL testing with ephemeral databases, RLS testing, and CI/CD automation.
+
+ 5. ⚡ [Supabase Testing](https://constructive.io/learn/supabase)
+Use TypeScript-first tools to test Supabase projects with realistic RLS, policies, and auth contexts.
+
+ 6. 💧 [Drizzle ORM Testing](https://constructive.io/learn/drizzle-testing)
+Run full-stack tests with Drizzle ORM, including database setup, teardown, and RLS enforcement.
+
+ 7. 🔧 [Troubleshooting](https://constructive.io/learn/troubleshooting)
+Common issues and solutions for pgpm, PostgreSQL, and testing.
+
+## Related Constructive Tooling
+
+### 📦 Package Management
+
+* [pgpm](https://github.com/constructive-io/constructive/tree/main/pgpm/pgpm): **🖥️ PostgreSQL Package Manager** for modular Postgres development. Works with database workspaces, scaffolding, migrations, seeding, and installing database packages.
+
+### 🧪 Testing
+
+* [pgsql-test](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-test): **📊 Isolated testing environments** with per-test transaction rollbacks—ideal for integration tests, complex migrations, and RLS simulation.
+* [pgsql-seed](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-seed): **🌱 PostgreSQL seeding utilities** for CSV, JSON, SQL data loading, and pgpm deployment.
+* [supabase-test](https://github.com/constructive-io/constructive/tree/main/postgres/supabase-test): **🧪 Supabase-native test harness** preconfigured for the local Supabase stack—per-test rollbacks, JWT/role context helpers, and CI/GitHub Actions ready.
+* [graphile-test](https://github.com/constructive-io/constructive/tree/main/graphile/graphile-test): **🔐 Authentication mocking** for Graphile-focused test helpers and emulating row-level security contexts.
+* [pg-query-context](https://github.com/constructive-io/constructive/tree/main/postgres/pg-query-context): **🔒 Session context injection** to add session-local context (e.g., `SET LOCAL`) into queries—ideal for setting `role`, `jwt.claims`, and other session settings.
+
+### 🧠 Parsing & AST
+
+* [pgsql-parser](https://www.npmjs.com/package/pgsql-parser): **🔄 SQL conversion engine** that interprets and converts PostgreSQL syntax.
+* [libpg-query-node](https://www.npmjs.com/package/libpg-query): **🌉 Node.js bindings** for `libpg_query`, converting SQL into parse trees.
+* [pg-proto-parser](https://www.npmjs.com/package/pg-proto-parser): **📦 Protobuf parser** for parsing PostgreSQL Protocol Buffers definitions to generate TypeScript interfaces, utility functions, and JSON mappings for enums.
+* [@pgsql/enums](https://www.npmjs.com/package/@pgsql/enums): **🏷️ TypeScript enums** for PostgreSQL AST for safe and ergonomic parsing logic.
+* [@pgsql/types](https://www.npmjs.com/package/@pgsql/types): **📝 Type definitions** for PostgreSQL AST nodes in TypeScript.
+* [@pgsql/utils](https://www.npmjs.com/package/@pgsql/utils): **🛠️ AST utilities** for constructing and transforming PostgreSQL syntax trees.
+
+## Credits
+
+**🛠 Built by the [Constructive](https://constructive.io) team — creators of modular Postgres tooling for secure, composable backends. If you like our work, contribute on [GitHub](https://github.com/constructive-io).**
+
+## Disclaimer
+
+AS DESCRIBED IN THE LICENSES, THE SOFTWARE IS PROVIDED "AS IS", AT YOUR OWN RISK, AND WITHOUT WARRANTIES OF ANY KIND.
+
+No developer or entity involved in creating this software will be liable for any claims or damages whatsoever associated with your use, inability to use, or your interaction with other users of the code, including any direct, indirect, incidental, special, exemplary, punitive or consequential damages, or loss of profits, cryptocurrencies, tokens, or anything else of value.

package/esm/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Realtime Subscriptions Plugin for PostGraphile v5
+ *
+ * Adds per-table GraphQL subscription fields to tables tagged with @realtime.
+ * Uses PostgreSQL LISTEN/NOTIFY for efficient event delivery with automatic
+ * RLS enforcement on re-queries.
+ *
+ * @example
+ * ```typescript
+ * import { RealtimeSubscriptionsPreset } from 'graphile-realtime-subscriptions';
+ *
+ * const preset = {
+ *   extends: [
+ *     RealtimeSubscriptionsPreset(),
+ *   ],
+ * };
+ * ```
+ */
+export { createRealtimeSubscriptionsPlugin, RealtimeSubscriptionsPlugin } from './plugin';
+export { RealtimeSubscriptionsPreset } from './preset';
+export type { RealtimeSubscriptionsPluginOptions } from './types';

package/esm/index.js

@@ -0,0 +1,20 @@
+/**
+ * Realtime Subscriptions Plugin for PostGraphile v5
+ *
+ * Adds per-table GraphQL subscription fields to tables tagged with @realtime.
+ * Uses PostgreSQL LISTEN/NOTIFY for efficient event delivery with automatic
+ * RLS enforcement on re-queries.
+ *
+ * @example
+ * ```typescript
+ * import { RealtimeSubscriptionsPreset } from 'graphile-realtime-subscriptions';
+ *
+ * const preset = {
+ *   extends: [
+ *     RealtimeSubscriptionsPreset(),
+ *   ],
+ * };
+ * ```
+ */
+export { createRealtimeSubscriptionsPlugin, RealtimeSubscriptionsPlugin } from './plugin';
+export { RealtimeSubscriptionsPreset } from './preset';

package/esm/plugin.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Realtime Subscriptions Plugin for PostGraphile v5
+ *
+ * Discovers tables tagged with @realtime and generates per-table
+ * 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
+ *   - Full collection: onXxxChanged (no args) — subscribe to any change on the table
+ *
+ * Event flow:
+ *   1. A row is inserted/updated/deleted
+ *   2. The emit_change trigger fires pg_notify('realtime:{schema}.{table}', TG_OP)
+ *   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
+ *
+ * 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;
+export { createRealtimeSubscriptionsPlugin as RealtimeSubscriptionsPlugin };

package/esm/plugin.js

@@ -0,0 +1,120 @@
+/**
+ * Realtime Subscriptions Plugin for PostGraphile v5
+ *
+ * Discovers tables tagged with @realtime and generates per-table
+ * 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
+ *   - Full collection: onXxxChanged (no args) — subscribe to any change on the table
+ *
+ * Event flow:
+ *   1. A row is inserted/updated/deleted
+ *   2. The emit_change trigger fires pg_notify('realtime:{schema}.{table}', TG_OP)
+ *   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
+ *
+ * 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 { extendSchema } from 'graphile-utils';
+import { Logger } from '@pgpmjs/logger';
+const log = new Logger('graphile-realtime-subscriptions');
+function discoverRealtimeTables(build) {
+    const { pgRegistry } = build.input;
+    const resources = pgRegistry.pgResources;
+    const result = [];
+    for (const [, resource] of Object.entries(resources)) {
+        const r = resource;
+        const codec = r.codec;
+        if (!codec?.attributes)
+            continue;
+        const tags = codec.extensions?.tags;
+        if (!tags?.realtime)
+            continue;
+        const typeName = build.inflection.tableType(codec);
+        const fieldName = `on${typeName}Changed`;
+        const payloadTypeName = `${typeName}SubscriptionPayload`;
+        const rowFieldName = typeName.charAt(0).toLowerCase() + typeName.slice(1);
+        const pgSchema = codec.extensions?.pg?.schemaName ?? 'public';
+        const pgTable = codec.extensions?.pg?.name ?? codec.name;
+        const notifyChannel = `realtime:${pgSchema}.${pgTable}`;
+        result.push({
+            resource: r,
+            typeName,
+            fieldName,
+            payloadTypeName,
+            rowFieldName,
+            notifyChannel,
+            pgSchema,
+            pgTable,
+        });
+        log.info(`Discovered realtime table: ${pgSchema}.${pgTable} -> ${fieldName}`);
+    }
+    return result;
+}
+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}`)
+        .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` +
+        `  event: String!\n` +
+        `  """The current state of the row (null for DELETE or if RLS denies access)."""\n` +
+        `  ${rowFieldName}: ${typeName}\n` +
+        `}`)
+        .join('\n\n');
+    return `extend type Subscription {\n${subscriptionFields}\n}\n\n${payloadTypes}`;
+}
+function buildPlans(tables) {
+    const subscriptionPlans = {};
+    const allPlans = {};
+    for (const { resource, fieldName, payloadTypeName, rowFieldName, notifyChannel } of tables) {
+        subscriptionPlans[fieldName] = {
+            subscribePlan(_$root, args) {
+                const $pgSubscriber = grafastContext().get('pgSubscriber');
+                const $topic = constant(notifyChannel);
+                const $id = args.get('id');
+                return listen($pgSubscriber, $topic, ($payload) => {
+                    return object({
+                        event: $payload,
+                        subscribedId: $id,
+                    });
+                });
+            },
+            plan($event) {
+                return $event;
+            },
+        };
+        allPlans[payloadTypeName] = {
+            event($parent) {
+                return $parent.get('event');
+            },
+            [rowFieldName]($parent) {
+                const $id = $parent.get('subscribedId');
+                return resource.get({ id: $id });
+            },
+        };
+    }
+    allPlans['Subscription'] = subscriptionPlans;
+    return allPlans;
+}
+export function createRealtimeSubscriptionsPlugin(_options = {}) {
+    return extendSchema((build) => {
+        const tables = discoverRealtimeTables(build);
+        if (tables.length === 0) {
+            log.info('No tables with @realtime tag found — skipping subscription generation');
+            return { typeDefs: '', plans: {} };
+        }
+        log.info(`Generating subscription fields for ${tables.length} realtime table(s)`);
+        const typeDefs = buildTypeDefs(tables);
+        const plans = buildPlans(tables);
+        return { typeDefs, plans };
+    }, 'RealtimeSubscriptionsPlugin');
+}
+export { createRealtimeSubscriptionsPlugin as RealtimeSubscriptionsPlugin };

package/esm/preset.d.ts

@@ -0,0 +1,10 @@
+/**
+ * PostGraphile v5 Realtime Subscriptions Preset
+ *
+ * Provides a convenient preset for including realtime subscription support
+ * in PostGraphile. Wraps the RealtimeSubscriptionsPlugin with options.
+ */
+import type { GraphileConfig } from 'graphile-config';
+import type { RealtimeSubscriptionsPluginOptions } from './types';
+export declare function RealtimeSubscriptionsPreset(options?: RealtimeSubscriptionsPluginOptions): GraphileConfig.Preset;
+export default RealtimeSubscriptionsPreset;

package/esm/preset.js

@@ -0,0 +1,13 @@
+/**
+ * PostGraphile v5 Realtime Subscriptions Preset
+ *
+ * Provides a convenient preset for including realtime subscription support
+ * in PostGraphile. Wraps the RealtimeSubscriptionsPlugin with options.
+ */
+import { createRealtimeSubscriptionsPlugin } from './plugin';
+export function RealtimeSubscriptionsPreset(options = {}) {
+    return {
+        plugins: [createRealtimeSubscriptionsPlugin(options)],
+    };
+}
+export default RealtimeSubscriptionsPreset;

package/esm/types.d.ts

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

package/esm/types.js

@@ -0,0 +1 @@
+export {};

package/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Realtime Subscriptions Plugin for PostGraphile v5
+ *
+ * Adds per-table GraphQL subscription fields to tables tagged with @realtime.
+ * Uses PostgreSQL LISTEN/NOTIFY for efficient event delivery with automatic
+ * RLS enforcement on re-queries.
+ *
+ * @example
+ * ```typescript
+ * import { RealtimeSubscriptionsPreset } from 'graphile-realtime-subscriptions';
+ *
+ * const preset = {
+ *   extends: [
+ *     RealtimeSubscriptionsPreset(),
+ *   ],
+ * };
+ * ```
+ */
+export { createRealtimeSubscriptionsPlugin, RealtimeSubscriptionsPlugin } from './plugin';
+export { RealtimeSubscriptionsPreset } from './preset';
+export type { RealtimeSubscriptionsPluginOptions } from './types';

package/index.js

@@ -0,0 +1,26 @@
+"use strict";
+/**
+ * Realtime Subscriptions Plugin for PostGraphile v5
+ *
+ * Adds per-table GraphQL subscription fields to tables tagged with @realtime.
+ * Uses PostgreSQL LISTEN/NOTIFY for efficient event delivery with automatic
+ * RLS enforcement on re-queries.
+ *
+ * @example
+ * ```typescript
+ * import { RealtimeSubscriptionsPreset } from 'graphile-realtime-subscriptions';
+ *
+ * const preset = {
+ *   extends: [
+ *     RealtimeSubscriptionsPreset(),
+ *   ],
+ * };
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+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; } });

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "graphile-realtime-subscriptions",
+  "version": "0.2.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",
+  "license": "MIT",
+  "main": "index.js",
+  "module": "esm/index.js",
+  "types": "index.d.ts",
+  "scripts": {
+    "clean": "makage clean",
+    "prepack": "npm run build",
+    "build": "makage build",
+    "build:dev": "makage build --dev",
+    "lint": "eslint . --fix",
+    "test": "jest --passWithNoTests",
+    "test:watch": "jest --watch"
+  },
+  "publishConfig": {
+    "access": "public",
+    "directory": "dist"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/constructive-io/constructive"
+  },
+  "keywords": [
+    "postgraphile",
+    "graphile",
+    "constructive",
+    "plugin",
+    "postgres",
+    "graphql",
+    "subscriptions",
+    "realtime",
+    "notify"
+  ],
+  "bugs": {
+    "url": "https://github.com/constructive-io/constructive/issues"
+  },
+  "dependencies": {
+    "@pgpmjs/logger": "^2.9.0"
+  },
+  "peerDependencies": {
+    "grafast": "1.0.0",
+    "graphile-build": "5.0.0",
+    "graphile-build-pg": "5.0.0",
+    "graphile-config": "1.0.0",
+    "graphile-utils": "5.0.0",
+    "graphql": "16.13.0",
+    "postgraphile": "5.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.11",
+    "makage": "^0.3.0"
+  },
+  "gitHead": "c87dafec1ccb2c3cc62f2304584104db108a810b"
+}

package/plugin.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Realtime Subscriptions Plugin for PostGraphile v5
+ *
+ * Discovers tables tagged with @realtime and generates per-table
+ * 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
+ *   - Full collection: onXxxChanged (no args) — subscribe to any change on the table
+ *
+ * Event flow:
+ *   1. A row is inserted/updated/deleted
+ *   2. The emit_change trigger fires pg_notify('realtime:{schema}.{table}', TG_OP)
+ *   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
+ *
+ * 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;
+export { createRealtimeSubscriptionsPlugin as RealtimeSubscriptionsPlugin };

package/plugin.js

@@ -0,0 +1,123 @@
+"use strict";
+/**
+ * Realtime Subscriptions Plugin for PostGraphile v5
+ *
+ * Discovers tables tagged with @realtime and generates per-table
+ * 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
+ *   - Full collection: onXxxChanged (no args) — subscribe to any change on the table
+ *
+ * Event flow:
+ *   1. A row is inserted/updated/deleted
+ *   2. The emit_change trigger fires pg_notify('realtime:{schema}.{table}', TG_OP)
+ *   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
+ *
+ * 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.createRealtimeSubscriptionsPlugin = createRealtimeSubscriptionsPlugin;
+exports.RealtimeSubscriptionsPlugin = createRealtimeSubscriptionsPlugin;
+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');
+function discoverRealtimeTables(build) {
+    const { pgRegistry } = build.input;
+    const resources = pgRegistry.pgResources;
+    const result = [];
+    for (const [, resource] of Object.entries(resources)) {
+        const r = resource;
+        const codec = r.codec;
+        if (!codec?.attributes)
+            continue;
+        const tags = codec.extensions?.tags;
+        if (!tags?.realtime)
+            continue;
+        const typeName = build.inflection.tableType(codec);
+        const fieldName = `on${typeName}Changed`;
+        const payloadTypeName = `${typeName}SubscriptionPayload`;
+        const rowFieldName = typeName.charAt(0).toLowerCase() + typeName.slice(1);
+        const pgSchema = codec.extensions?.pg?.schemaName ?? 'public';
+        const pgTable = codec.extensions?.pg?.name ?? codec.name;
+        const notifyChannel = `realtime:${pgSchema}.${pgTable}`;
+        result.push({
+            resource: r,
+            typeName,
+            fieldName,
+            payloadTypeName,
+            rowFieldName,
+            notifyChannel,
+            pgSchema,
+            pgTable,
+        });
+        log.info(`Discovered realtime table: ${pgSchema}.${pgTable} -> ${fieldName}`);
+    }
+    return result;
+}
+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}`)
+        .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` +
+        `  event: String!\n` +
+        `  """The current state of the row (null for DELETE or if RLS denies access)."""\n` +
+        `  ${rowFieldName}: ${typeName}\n` +
+        `}`)
+        .join('\n\n');
+    return `extend type Subscription {\n${subscriptionFields}\n}\n\n${payloadTypes}`;
+}
+function buildPlans(tables) {
+    const subscriptionPlans = {};
+    const allPlans = {};
+    for (const { resource, fieldName, payloadTypeName, rowFieldName, notifyChannel } of tables) {
+        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) => {
+                    return (0, grafast_1.object)({
+                        event: $payload,
+                        subscribedId: $id,
+                    });
+                });
+            },
+            plan($event) {
+                return $event;
+            },
+        };
+        allPlans[payloadTypeName] = {
+            event($parent) {
+                return $parent.get('event');
+            },
+            [rowFieldName]($parent) {
+                const $id = $parent.get('subscribedId');
+                return resource.get({ id: $id });
+            },
+        };
+    }
+    allPlans['Subscription'] = subscriptionPlans;
+    return allPlans;
+}
+function createRealtimeSubscriptionsPlugin(_options = {}) {
+    return (0, graphile_utils_1.extendSchema)((build) => {
+        const tables = discoverRealtimeTables(build);
+        if (tables.length === 0) {
+            log.info('No tables with @realtime tag found — skipping subscription generation');
+            return { typeDefs: '', plans: {} };
+        }
+        log.info(`Generating subscription fields for ${tables.length} realtime table(s)`);
+        const typeDefs = buildTypeDefs(tables);
+        const plans = buildPlans(tables);
+        return { typeDefs, plans };
+    }, 'RealtimeSubscriptionsPlugin');
+}

package/preset.d.ts

@@ -0,0 +1,10 @@
+/**
+ * PostGraphile v5 Realtime Subscriptions Preset
+ *
+ * Provides a convenient preset for including realtime subscription support
+ * in PostGraphile. Wraps the RealtimeSubscriptionsPlugin with options.
+ */
+import type { GraphileConfig } from 'graphile-config';
+import type { RealtimeSubscriptionsPluginOptions } from './types';
+export declare function RealtimeSubscriptionsPreset(options?: RealtimeSubscriptionsPluginOptions): GraphileConfig.Preset;
+export default RealtimeSubscriptionsPreset;

package/preset.js

@@ -0,0 +1,16 @@
+"use strict";
+/**
+ * PostGraphile v5 Realtime Subscriptions Preset
+ *
+ * Provides a convenient preset for including realtime subscription support
+ * in PostGraphile. Wraps the RealtimeSubscriptionsPlugin with options.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RealtimeSubscriptionsPreset = RealtimeSubscriptionsPreset;
+const plugin_1 = require("./plugin");
+function RealtimeSubscriptionsPreset(options = {}) {
+    return {
+        plugins: [(0, plugin_1.createRealtimeSubscriptionsPlugin)(options)],
+    };
+}
+exports.default = RealtimeSubscriptionsPreset;

package/types.d.ts

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

package/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });