graphile-realtime-test 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,160 @@
+# graphile-realtime-test
+
+<p align="center" width="100%">
+  <img height="250" src="https://raw.githubusercontent.com/constructive-io/constructive/refs/heads/main/assets/outline-logo.svg" />
+</p>
+
+<p align="center" width="100%">
+  <a href="https://github.com/constructive-io/constructive/actions/workflows/run-tests.yaml">
+    <img height="20" src="https://github.com/constructive-io/constructive/actions/workflows/run-tests.yaml/badge.svg" />
+  </a>
+  <a href="https://github.com/constructive-io/constructive/blob/main/LICENSE">
+    <img height="20" src="https://img.shields.io/badge/license-MIT-blue.svg"/>
+  </a>
+  <a href="https://www.npmjs.com/package/graphile-realtime-test">
+    <img height="20" src="https://img.shields.io/github/package-json/v/constructive-io/constructive?filename=graphile%2Fgraphile-realtime-test%2Fpackage.json"/>
+  </a>
+</p>
+
+Subscription testing utilities for `graphile-realtime-subscriptions`.
+
+Provides smart tag injection, `grafast.subscribe()` helpers, and `pg_notify` simulation for integration testing realtime GraphQL subscriptions against a real PostgreSQL database.
+
+## Usage
+
+```typescript
+import { createRealtimeTestContext, waitForEvent } from 'graphile-realtime-test';
+import { seed } from 'pgsql-test';
+
+const ctx = await createRealtimeTestContext(
+  {
+    schemas: ['my_schema'],
+    realtimeTables: ['items'],
+    useRoot: true,
+    authRole: 'postgres',
+  },
+  [seed.sqlfile(['./seed.sql'])]
+);
+
+// Start a subscription
+const iterator = await ctx.subscribe(`
+  subscription {
+    onItemChanged {
+      event
+      rowId
+      overflow
+    }
+  }
+`);
+
+// Fire a NOTIFY
+await ctx.notifyChange('items', 'INSERT', ['some-uuid']);
+
+// Assert the event
+const event = await waitForEvent(iterator);
+expect(event.data.onItemChanged.event).toBe('INSERT');
+
+// Clean up
+await iterator.return?.();
+await ctx.teardown();
+```
+
+## API
+
+### `createRealtimeTestContext(input, seedAdapters?)`
+
+Creates a fully wired test context with schema, subscriptions, and NOTIFY helpers.
+
+### `makeRealtimeSmartTagsPlugin(tagsByTable)`
+
+Creates a Graphile plugin that injects smart tags on table codecs during schema build.
+
+### `subscribe(opts)`
+
+Calls `grafast.subscribe()` and returns the raw async iterator.
+
+### `waitForEvent(iterator, timeoutMs?)`
+
+Waits for the next event from a subscription iterator with a timeout.
+
+### `collectEvents(iterator, count, timeoutMs?)`
+
+Collects multiple events from a subscription iterator.
+
+### `notify(client, schema, table, payload)`
+
+Fires a raw `pg_notify` on a realtime channel.
+
+### `notifyChange(client, schema, table, operation, rowIds)`
+
+Fires a DML NOTIFY with the standard payload format.
+
+### `notifyInvalidate(client, schema, table)`
+
+Fires an INVALIDATE (overflow) NOTIFY.
+
+### `buildPayload(operation, rowIds)`
+
+Builds a standard DML payload string.
+
+### `buildInvalidatePayload()`
+
+Returns the `"INVALIDATE"` payload string.
+
+---
+
+## 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/context.d.ts

@@ -0,0 +1,85 @@
+import type { GraphQLSchema, ExecutionResult } from 'graphql';
+import type { GraphileConfig } from 'graphile-config';
+import type { PgTestClient } from 'pgsql-test/test-client';
+import type { GetConnectionOpts } from 'pgsql-test';
+import type { SeedAdapter } from 'pgsql-test/seed/types';
+import type { GetConnectionsInput } from 'graphile-test';
+/**
+ * Input for creating a realtime test context.
+ */
+export interface RealtimeTestInput extends GetConnectionsInput, GetConnectionOpts {
+    /**
+     * Map of table names to smart tags to inject.
+     * The `@realtime` tag is injected automatically for tables listed here.
+     *
+     * Example: `{ items: { realtime: true } }`
+     *
+     * If you only pass table names without tags, use `realtimeTables` instead.
+     */
+    smartTags?: Record<string, Record<string, unknown>>;
+    /**
+     * Shorthand: list of table names that should get `{ realtime: true }`.
+     * Merged with `smartTags` if both are provided.
+     */
+    realtimeTables?: string[];
+    /**
+     * Options for the realtime subscriptions plugin (e.g. overflowThreshold).
+     */
+    realtimeOptions?: {
+        overflowThreshold?: number;
+    };
+}
+/**
+ * The context returned by `createRealtimeTestContext()`.
+ */
+export interface RealtimeTestContext {
+    /** Root pg test client (superuser) */
+    pg: PgTestClient;
+    /** Database-scoped test client */
+    db: PgTestClient;
+    /** The built GraphQL schema (includes subscription fields) */
+    schema: GraphQLSchema;
+    /** The resolved Graphile preset */
+    resolvedPreset: GraphileConfig.ResolvedPreset;
+    /**
+     * Start a GraphQL subscription and return the async iterator.
+     *
+     * The returned iterator yields `ExecutionResult` events. Call `.return()`
+     * on it when done to clean up.
+     */
+    subscribe(query: string, variables?: Record<string, unknown>, contextOverrides?: Record<string, unknown>): Promise<AsyncIterableIterator<ExecutionResult> | ExecutionResult>;
+    /**
+     * Fire a pg_notify on a realtime channel.
+     *
+     * @param table - Table name (unqualified)
+     * @param operation - DML operation
+     * @param rowIds - Affected row IDs
+     * @param schema - Schema name (default: the first schema from input)
+     */
+    notifyChange(table: string, operation: 'INSERT' | 'UPDATE' | 'DELETE', rowIds: string[], schema?: string): Promise<void>;
+    /**
+     * Fire an INVALIDATE (overflow) NOTIFY.
+     */
+    notifyInvalidate(table: string, schema?: string): Promise<void>;
+    /**
+     * Fire a raw pg_notify on a realtime channel.
+     */
+    notify(table: string, payload: string, schema?: string): Promise<void>;
+    /** Tear down the test context and close connections */
+    teardown(): Promise<void>;
+}
+/**
+ * Create a fully wired realtime test context.
+ *
+ * This sets up:
+ *   - A PostgreSQL test database with the given seed
+ *   - Smart tag injection via `makeRealtimeSmartTagsPlugin`
+ *   - The `RealtimeSubscriptionsPlugin` for subscription field generation
+ *   - A built GraphQL schema with subscription support
+ *   - Helper functions for subscribing, notifying, and asserting
+ *
+ * @param input - Configuration including schemas, tables, and options
+ * @param seedAdapters - Optional SQL seed adapters (from `pgsql-test`)
+ * @returns A `RealtimeTestContext` with all the helpers
+ */
+export declare function createRealtimeTestContext(input: RealtimeTestInput, seedAdapters?: SeedAdapter[]): Promise<RealtimeTestContext>;

package/context.js

@@ -0,0 +1,124 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRealtimeTestContext = createRealtimeTestContext;
+const pgsql_test_1 = require("pgsql-test");
+const graphile_build_1 = require("graphile-build");
+const graphile_build_2 = require("graphile-build");
+const graphile_build_pg_1 = require("graphile-build-pg");
+const pg_1 = require("postgraphile/adaptors/pg");
+const graphile_realtime_subscriptions_1 = require("graphile-realtime-subscriptions");
+const subscribe_js_1 = require("./subscribe.js");
+const notify_js_1 = require("./notify.js");
+const smart_tags_js_1 = require("./smart-tags.js");
+/**
+ * Minimal preset matching graphile-test's MinimalPreset.
+ */
+const MinimalPreset = {
+    extends: [graphile_build_2.defaultPreset, graphile_build_pg_1.defaultPreset],
+    disablePlugins: ['NodePlugin'],
+};
+/**
+ * Create a fully wired realtime test context.
+ *
+ * This sets up:
+ *   - A PostgreSQL test database with the given seed
+ *   - Smart tag injection via `makeRealtimeSmartTagsPlugin`
+ *   - The `RealtimeSubscriptionsPlugin` for subscription field generation
+ *   - A built GraphQL schema with subscription support
+ *   - Helper functions for subscribing, notifying, and asserting
+ *
+ * @param input - Configuration including schemas, tables, and options
+ * @param seedAdapters - Optional SQL seed adapters (from `pgsql-test`)
+ * @returns A `RealtimeTestContext` with all the helpers
+ */
+async function createRealtimeTestContext(input, seedAdapters) {
+    const { schemas, preset: userPreset, realtimeOptions } = input;
+    // Build smart tags map
+    const smartTagsMap = {
+        ...(input.smartTags ?? {}),
+    };
+    for (const table of input.realtimeTables ?? []) {
+        if (!smartTagsMap[table]) {
+            smartTagsMap[table] = {};
+        }
+        smartTagsMap[table].realtime = true;
+    }
+    // Get database connections
+    const conn = await (0, pgsql_test_1.getConnections)(input, seedAdapters);
+    const { pg, db, teardown: dbTeardown } = conn;
+    const pgPool = conn.manager.getPool(conn.pg.config);
+    // Build the schema with realtime plugins
+    const smartTagsPlugin = (0, smart_tags_js_1.makeRealtimeSmartTagsPlugin)(smartTagsMap);
+    const realtimePlugin = (0, graphile_realtime_subscriptions_1.createRealtimeSubscriptionsPlugin)(realtimeOptions);
+    // Create pgService — this also creates the PgSubscriber that
+    // listens for NOTIFY events on a dedicated PostgreSQL connection
+    const pgService = (0, pg_1.makePgService)({
+        pool: pgPool,
+        schemas,
+    });
+    const completePreset = {
+        extends: [
+            MinimalPreset,
+            ...(userPreset?.extends ?? []),
+        ],
+        ...(userPreset?.disablePlugins && { disablePlugins: userPreset.disablePlugins }),
+        plugins: [
+            ...(userPreset?.plugins ?? []),
+            smartTagsPlugin,
+            realtimePlugin,
+        ],
+        ...(userPreset?.schema && { schema: userPreset.schema }),
+        ...(userPreset?.grafast && { grafast: userPreset.grafast }),
+        pgServices: [pgService],
+    };
+    const result = await (0, graphile_build_1.makeSchema)(completePreset);
+    const schema = result.schema;
+    const resolvedPreset = result.resolvedPreset;
+    const defaultSchema = schemas[0] ?? 'public';
+    // Use root pg client for NOTIFY so it's visible outside the test transaction
+    const notifyClient = pg.client;
+    // Extract the pgSubscriber from the pgService — subscriptions need it
+    // in the grafast context to receive LISTEN/NOTIFY events
+    const pgSubscriber = pgService.pgSubscriber;
+    const pgSubscriberKey = pgService.pgSubscriberKey ?? 'pgSubscriber';
+    const teardown = async () => {
+        if (pgSubscriber && typeof pgSubscriber.release === 'function') {
+            await pgSubscriber.release();
+        }
+        if (pgService && typeof pgService.release === 'function') {
+            await pgService.release();
+        }
+        await dbTeardown();
+    };
+    return {
+        pg,
+        db,
+        schema,
+        resolvedPreset,
+        async subscribe(query, variables, contextOverrides) {
+            // Build the context that grafast.subscribe needs.
+            // The subscription plan accesses pgSubscriber via grafastContext().get('pgSubscriber')
+            const contextValue = {
+                [pgSubscriberKey]: pgSubscriber,
+                ...contextOverrides,
+            };
+            return (0, subscribe_js_1.subscribe)({
+                schema,
+                resolvedPreset,
+                query,
+                variables,
+                contextValue,
+            });
+        },
+        async notifyChange(table, operation, rowIds, tableSchema) {
+            await (0, notify_js_1.notifyChange)(notifyClient, tableSchema ?? defaultSchema, table, operation, rowIds);
+        },
+        async notifyInvalidate(table, tableSchema) {
+            await (0, notify_js_1.notifyInvalidate)(notifyClient, tableSchema ?? defaultSchema, table);
+        },
+        async notify(table, payload, tableSchema) {
+            await (0, notify_js_1.notify)(notifyClient, tableSchema ?? defaultSchema, table, payload);
+        },
+        teardown,
+    };
+}

package/esm/context.js

@@ -0,0 +1,121 @@
+import { getConnections as getPgConnections } from 'pgsql-test';
+import { makeSchema } from 'graphile-build';
+import { defaultPreset as graphileBuildDefaultPreset } from 'graphile-build';
+import { defaultPreset as graphileBuildPgDefaultPreset } from 'graphile-build-pg';
+import { makePgService } from 'postgraphile/adaptors/pg';
+import { createRealtimeSubscriptionsPlugin } from 'graphile-realtime-subscriptions';
+import { subscribe as subscribeHelper } from './subscribe.js';
+import { notify, notifyChange, notifyInvalidate } from './notify.js';
+import { makeRealtimeSmartTagsPlugin } from './smart-tags.js';
+/**
+ * Minimal preset matching graphile-test's MinimalPreset.
+ */
+const MinimalPreset = {
+    extends: [graphileBuildDefaultPreset, graphileBuildPgDefaultPreset],
+    disablePlugins: ['NodePlugin'],
+};
+/**
+ * Create a fully wired realtime test context.
+ *
+ * This sets up:
+ *   - A PostgreSQL test database with the given seed
+ *   - Smart tag injection via `makeRealtimeSmartTagsPlugin`
+ *   - The `RealtimeSubscriptionsPlugin` for subscription field generation
+ *   - A built GraphQL schema with subscription support
+ *   - Helper functions for subscribing, notifying, and asserting
+ *
+ * @param input - Configuration including schemas, tables, and options
+ * @param seedAdapters - Optional SQL seed adapters (from `pgsql-test`)
+ * @returns A `RealtimeTestContext` with all the helpers
+ */
+export async function createRealtimeTestContext(input, seedAdapters) {
+    const { schemas, preset: userPreset, realtimeOptions } = input;
+    // Build smart tags map
+    const smartTagsMap = {
+        ...(input.smartTags ?? {}),
+    };
+    for (const table of input.realtimeTables ?? []) {
+        if (!smartTagsMap[table]) {
+            smartTagsMap[table] = {};
+        }
+        smartTagsMap[table].realtime = true;
+    }
+    // Get database connections
+    const conn = await getPgConnections(input, seedAdapters);
+    const { pg, db, teardown: dbTeardown } = conn;
+    const pgPool = conn.manager.getPool(conn.pg.config);
+    // Build the schema with realtime plugins
+    const smartTagsPlugin = makeRealtimeSmartTagsPlugin(smartTagsMap);
+    const realtimePlugin = createRealtimeSubscriptionsPlugin(realtimeOptions);
+    // Create pgService — this also creates the PgSubscriber that
+    // listens for NOTIFY events on a dedicated PostgreSQL connection
+    const pgService = makePgService({
+        pool: pgPool,
+        schemas,
+    });
+    const completePreset = {
+        extends: [
+            MinimalPreset,
+            ...(userPreset?.extends ?? []),
+        ],
+        ...(userPreset?.disablePlugins && { disablePlugins: userPreset.disablePlugins }),
+        plugins: [
+            ...(userPreset?.plugins ?? []),
+            smartTagsPlugin,
+            realtimePlugin,
+        ],
+        ...(userPreset?.schema && { schema: userPreset.schema }),
+        ...(userPreset?.grafast && { grafast: userPreset.grafast }),
+        pgServices: [pgService],
+    };
+    const result = await makeSchema(completePreset);
+    const schema = result.schema;
+    const resolvedPreset = result.resolvedPreset;
+    const defaultSchema = schemas[0] ?? 'public';
+    // Use root pg client for NOTIFY so it's visible outside the test transaction
+    const notifyClient = pg.client;
+    // Extract the pgSubscriber from the pgService — subscriptions need it
+    // in the grafast context to receive LISTEN/NOTIFY events
+    const pgSubscriber = pgService.pgSubscriber;
+    const pgSubscriberKey = pgService.pgSubscriberKey ?? 'pgSubscriber';
+    const teardown = async () => {
+        if (pgSubscriber && typeof pgSubscriber.release === 'function') {
+            await pgSubscriber.release();
+        }
+        if (pgService && typeof pgService.release === 'function') {
+            await pgService.release();
+        }
+        await dbTeardown();
+    };
+    return {
+        pg,
+        db,
+        schema,
+        resolvedPreset,
+        async subscribe(query, variables, contextOverrides) {
+            // Build the context that grafast.subscribe needs.
+            // The subscription plan accesses pgSubscriber via grafastContext().get('pgSubscriber')
+            const contextValue = {
+                [pgSubscriberKey]: pgSubscriber,
+                ...contextOverrides,
+            };
+            return subscribeHelper({
+                schema,
+                resolvedPreset,
+                query,
+                variables,
+                contextValue,
+            });
+        },
+        async notifyChange(table, operation, rowIds, tableSchema) {
+            await notifyChange(notifyClient, tableSchema ?? defaultSchema, table, operation, rowIds);
+        },
+        async notifyInvalidate(table, tableSchema) {
+            await notifyInvalidate(notifyClient, tableSchema ?? defaultSchema, table);
+        },
+        async notify(table, payload, tableSchema) {
+            await notify(notifyClient, tableSchema ?? defaultSchema, table, payload);
+        },
+        teardown,
+    };
+}

package/esm/index.js

@@ -0,0 +1,4 @@
+export { createRealtimeTestContext } from './context.js';
+export { makeRealtimeSmartTagsPlugin } from './smart-tags.js';
+export { subscribe, waitForEvent, collectEvents, } from './subscribe.js';
+export { notify, notifyChange, notifyInvalidate, buildPayload, buildInvalidatePayload, } from './notify.js';

package/esm/notify.js

@@ -0,0 +1,52 @@
+/**
+ * Fire a pg_notify on the realtime channel for a given schema.table.
+ *
+ * The channel format matches what emit_change uses:
+ *   `realtime:<schema>.<table>`
+ *
+ * @param client - A pg Client (or PoolClient) to run the NOTIFY on
+ * @param schema - The PostgreSQL schema name (e.g. 'public')
+ * @param table - The table name (e.g. 'items')
+ * @param payload - The NOTIFY payload string
+ */
+export async function notify(client, schema, table, payload) {
+    const channel = `realtime:${schema}.${table}`;
+    await client.query(`SELECT pg_notify($1, $2)`, [channel, payload]);
+}
+/**
+ * Build a standard DML payload string in the format emit_change uses.
+ *
+ * @param operation - The DML operation: 'INSERT', 'UPDATE', or 'DELETE'
+ * @param rowIds - Array of affected row IDs (UUIDs)
+ * @returns Formatted payload string (e.g. "INSERT:uuid1,uuid2")
+ */
+export function buildPayload(operation, rowIds) {
+    if (rowIds.length === 0) {
+        return operation;
+    }
+    return `${operation}:${rowIds.join(',')}`;
+}
+/**
+ * Build an INVALIDATE (overflow) payload.
+ */
+export function buildInvalidatePayload() {
+    return 'INVALIDATE';
+}
+/**
+ * Convenience: fire a DML NOTIFY for a table.
+ *
+ * @param client - A pg Client to run the NOTIFY on
+ * @param schema - The PostgreSQL schema name
+ * @param table - The table name
+ * @param operation - The DML operation
+ * @param rowIds - Array of affected row IDs
+ */
+export async function notifyChange(client, schema, table, operation, rowIds) {
+    await notify(client, schema, table, buildPayload(operation, rowIds));
+}
+/**
+ * Convenience: fire an INVALIDATE NOTIFY for a table.
+ */
+export async function notifyInvalidate(client, schema, table) {
+    await notify(client, schema, table, buildInvalidatePayload());
+}

package/esm/smart-tags.js

@@ -0,0 +1,38 @@
+/**
+ * Creates a Graphile plugin that injects smart tags on table codecs during
+ * the schema build phase. This runs early (before RealtimeSubscriptionsPlugin)
+ * so that @realtime and other tags are visible when the subscription plugin
+ * discovers tables.
+ *
+ * @param tagsByTable - Map of table name to tags to inject.
+ *   Example: `{ items: { realtime: true } }`
+ */
+export function makeRealtimeSmartTagsPlugin(tagsByTable) {
+    return {
+        name: 'RealtimeTestSmartTagsPlugin',
+        version: '1.0.0',
+        schema: {
+            hooks: {
+                init: {
+                    before: ['RealtimeSubscriptionsPlugin'],
+                    callback(_, build) {
+                        for (const codec of Object.values(build.input.pgRegistry.pgCodecs)) {
+                            const c = codec;
+                            if (!c.attributes || !c.name)
+                                continue;
+                            const tags = tagsByTable[c.name];
+                            if (!tags)
+                                continue;
+                            if (!c.extensions)
+                                c.extensions = {};
+                            if (!c.extensions.tags)
+                                c.extensions.tags = {};
+                            Object.assign(c.extensions.tags, tags);
+                        }
+                        return _;
+                    },
+                },
+            },
+        },
+    };
+}

package/esm/subscribe.js

@@ -0,0 +1,73 @@
+import { subscribe as grafastSubscribe } from 'grafast';
+import { parse } from 'graphql';
+/**
+ * Call grafast.subscribe() and return the raw async iterator.
+ *
+ * The caller is responsible for iterating the result and calling `.return()`
+ * when done.
+ *
+ * @returns An AsyncIterableIterator that yields ExecutionResult events,
+ *          or an ExecutionResult if subscription setup failed.
+ */
+export async function subscribe(opts) {
+    const document = typeof opts.query === 'string' ? parse(opts.query) : opts.query;
+    const result = await grafastSubscribe({
+        schema: opts.schema,
+        document,
+        variableValues: opts.variables ?? undefined,
+        contextValue: opts.contextValue ?? {},
+        resolvedPreset: opts.resolvedPreset,
+    });
+    return result;
+}
+/**
+ * Wait for the next event from a subscription iterator, with a timeout.
+ *
+ * @param iterator - The async iterator returned by `subscribe()`
+ * @param timeoutMs - Maximum time to wait (default: 5000ms)
+ * @returns The next subscription event
+ * @throws If the timeout is exceeded or the iterator completes without a value
+ */
+export async function waitForEvent(iterator, timeoutMs = 5000) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            reject(new Error(`waitForEvent timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+        iterator
+            .next()
+            .then((result) => {
+            clearTimeout(timer);
+            if (result.done) {
+                reject(new Error('Subscription iterator completed without yielding a value'));
+            }
+            else {
+                resolve(result.value);
+            }
+        })
+            .catch((err) => {
+            clearTimeout(timer);
+            reject(err);
+        });
+    });
+}
+/**
+ * Collect multiple events from a subscription iterator.
+ *
+ * @param iterator - The async iterator returned by `subscribe()`
+ * @param count - Number of events to collect
+ * @param timeoutMs - Maximum time to wait for all events (default: 10000ms)
+ * @returns Array of collected events
+ */
+export async function collectEvents(iterator, count, timeoutMs = 10000) {
+    const events = [];
+    const deadline = Date.now() + timeoutMs;
+    for (let i = 0; i < count; i++) {
+        const remaining = deadline - Date.now();
+        if (remaining <= 0) {
+            throw new Error(`collectEvents timed out after ${timeoutMs}ms (collected ${events.length}/${count})`);
+        }
+        const event = await waitForEvent(iterator, remaining);
+        events.push(event);
+    }
+    return events;
+}

package/index.d.ts

@@ -0,0 +1,6 @@
+export { createRealtimeTestContext } from './context.js';
+export type { RealtimeTestContext, RealtimeTestInput } from './context.js';
+export { makeRealtimeSmartTagsPlugin } from './smart-tags.js';
+export { subscribe, waitForEvent, collectEvents, } from './subscribe.js';
+export type { SubscriptionEvent, SubscribeOptions } from './subscribe.js';
+export { notify, notifyChange, notifyInvalidate, buildPayload, buildInvalidatePayload, } from './notify.js';

package/index.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildInvalidatePayload = exports.buildPayload = exports.notifyInvalidate = exports.notifyChange = exports.notify = exports.collectEvents = exports.waitForEvent = exports.subscribe = exports.makeRealtimeSmartTagsPlugin = exports.createRealtimeTestContext = void 0;
+var context_js_1 = require("./context.js");
+Object.defineProperty(exports, "createRealtimeTestContext", { enumerable: true, get: function () { return context_js_1.createRealtimeTestContext; } });
+var smart_tags_js_1 = require("./smart-tags.js");
+Object.defineProperty(exports, "makeRealtimeSmartTagsPlugin", { enumerable: true, get: function () { return smart_tags_js_1.makeRealtimeSmartTagsPlugin; } });
+var subscribe_js_1 = require("./subscribe.js");
+Object.defineProperty(exports, "subscribe", { enumerable: true, get: function () { return subscribe_js_1.subscribe; } });
+Object.defineProperty(exports, "waitForEvent", { enumerable: true, get: function () { return subscribe_js_1.waitForEvent; } });
+Object.defineProperty(exports, "collectEvents", { enumerable: true, get: function () { return subscribe_js_1.collectEvents; } });
+var notify_js_1 = require("./notify.js");
+Object.defineProperty(exports, "notify", { enumerable: true, get: function () { return notify_js_1.notify; } });
+Object.defineProperty(exports, "notifyChange", { enumerable: true, get: function () { return notify_js_1.notifyChange; } });
+Object.defineProperty(exports, "notifyInvalidate", { enumerable: true, get: function () { return notify_js_1.notifyInvalidate; } });
+Object.defineProperty(exports, "buildPayload", { enumerable: true, get: function () { return notify_js_1.buildPayload; } });
+Object.defineProperty(exports, "buildInvalidatePayload", { enumerable: true, get: function () { return notify_js_1.buildInvalidatePayload; } });

package/notify.d.ts

@@ -0,0 +1,39 @@
+import type { Client } from 'pg';
+/**
+ * Fire a pg_notify on the realtime channel for a given schema.table.
+ *
+ * The channel format matches what emit_change uses:
+ *   `realtime:<schema>.<table>`
+ *
+ * @param client - A pg Client (or PoolClient) to run the NOTIFY on
+ * @param schema - The PostgreSQL schema name (e.g. 'public')
+ * @param table - The table name (e.g. 'items')
+ * @param payload - The NOTIFY payload string
+ */
+export declare function notify(client: Client, schema: string, table: string, payload: string): Promise<void>;
+/**
+ * Build a standard DML payload string in the format emit_change uses.
+ *
+ * @param operation - The DML operation: 'INSERT', 'UPDATE', or 'DELETE'
+ * @param rowIds - Array of affected row IDs (UUIDs)
+ * @returns Formatted payload string (e.g. "INSERT:uuid1,uuid2")
+ */
+export declare function buildPayload(operation: 'INSERT' | 'UPDATE' | 'DELETE', rowIds: string[]): string;
+/**
+ * Build an INVALIDATE (overflow) payload.
+ */
+export declare function buildInvalidatePayload(): string;
+/**
+ * Convenience: fire a DML NOTIFY for a table.
+ *
+ * @param client - A pg Client to run the NOTIFY on
+ * @param schema - The PostgreSQL schema name
+ * @param table - The table name
+ * @param operation - The DML operation
+ * @param rowIds - Array of affected row IDs
+ */
+export declare function notifyChange(client: Client, schema: string, table: string, operation: 'INSERT' | 'UPDATE' | 'DELETE', rowIds: string[]): Promise<void>;
+/**
+ * Convenience: fire an INVALIDATE NOTIFY for a table.
+ */
+export declare function notifyInvalidate(client: Client, schema: string, table: string): Promise<void>;

package/notify.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.notify = notify;
+exports.buildPayload = buildPayload;
+exports.buildInvalidatePayload = buildInvalidatePayload;
+exports.notifyChange = notifyChange;
+exports.notifyInvalidate = notifyInvalidate;
+/**
+ * Fire a pg_notify on the realtime channel for a given schema.table.
+ *
+ * The channel format matches what emit_change uses:
+ *   `realtime:<schema>.<table>`
+ *
+ * @param client - A pg Client (or PoolClient) to run the NOTIFY on
+ * @param schema - The PostgreSQL schema name (e.g. 'public')
+ * @param table - The table name (e.g. 'items')
+ * @param payload - The NOTIFY payload string
+ */
+async function notify(client, schema, table, payload) {
+    const channel = `realtime:${schema}.${table}`;
+    await client.query(`SELECT pg_notify($1, $2)`, [channel, payload]);
+}
+/**
+ * Build a standard DML payload string in the format emit_change uses.
+ *
+ * @param operation - The DML operation: 'INSERT', 'UPDATE', or 'DELETE'
+ * @param rowIds - Array of affected row IDs (UUIDs)
+ * @returns Formatted payload string (e.g. "INSERT:uuid1,uuid2")
+ */
+function buildPayload(operation, rowIds) {
+    if (rowIds.length === 0) {
+        return operation;
+    }
+    return `${operation}:${rowIds.join(',')}`;
+}
+/**
+ * Build an INVALIDATE (overflow) payload.
+ */
+function buildInvalidatePayload() {
+    return 'INVALIDATE';
+}
+/**
+ * Convenience: fire a DML NOTIFY for a table.
+ *
+ * @param client - A pg Client to run the NOTIFY on
+ * @param schema - The PostgreSQL schema name
+ * @param table - The table name
+ * @param operation - The DML operation
+ * @param rowIds - Array of affected row IDs
+ */
+async function notifyChange(client, schema, table, operation, rowIds) {
+    await notify(client, schema, table, buildPayload(operation, rowIds));
+}
+/**
+ * Convenience: fire an INVALIDATE NOTIFY for a table.
+ */
+async function notifyInvalidate(client, schema, table) {
+    await notify(client, schema, table, buildInvalidatePayload());
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "graphile-realtime-test",
+  "version": "0.2.0",
+  "description": "Subscription testing utilities for graphile-realtime-subscriptions — smart tag injection, grafast.subscribe() helpers, and pg_notify simulation",
+  "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": [
+    "testing",
+    "graphql",
+    "graphile",
+    "constructive",
+    "subscriptions",
+    "realtime",
+    "notify",
+    "test"
+  ],
+  "bugs": {
+    "url": "https://github.com/constructive-io/constructive/issues"
+  },
+  "dependencies": {
+    "graphile-realtime-subscriptions": "^0.5.2",
+    "graphile-test": "^4.14.2"
+  },
+  "peerDependencies": {
+    "grafast": "1.0.0",
+    "graphile-build": "5.0.0",
+    "graphile-build-pg": "5.0.0",
+    "graphile-config": "1.0.0",
+    "graphql": "16.13.0",
+    "pg": "^8.20.0",
+    "postgraphile": "5.0.0"
+  },
+  "devDependencies": {
+    "@types/pg": "^8.18.0",
+    "makage": "^0.3.0",
+    "pgsql-test": "^4.13.2"
+  },
+  "gitHead": "ea590e1b9e1ee38c267f8dbbb37aa3f83a5d3fb7"
+}

package/smart-tags.d.ts

@@ -0,0 +1,11 @@
+import type { GraphileConfig } from 'graphile-config';
+/**
+ * Creates a Graphile plugin that injects smart tags on table codecs during
+ * the schema build phase. This runs early (before RealtimeSubscriptionsPlugin)
+ * so that @realtime and other tags are visible when the subscription plugin
+ * discovers tables.
+ *
+ * @param tagsByTable - Map of table name to tags to inject.
+ *   Example: `{ items: { realtime: true } }`
+ */
+export declare function makeRealtimeSmartTagsPlugin(tagsByTable: Record<string, Record<string, unknown>>): GraphileConfig.Plugin;

package/smart-tags.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.makeRealtimeSmartTagsPlugin = makeRealtimeSmartTagsPlugin;
+/**
+ * Creates a Graphile plugin that injects smart tags on table codecs during
+ * the schema build phase. This runs early (before RealtimeSubscriptionsPlugin)
+ * so that @realtime and other tags are visible when the subscription plugin
+ * discovers tables.
+ *
+ * @param tagsByTable - Map of table name to tags to inject.
+ *   Example: `{ items: { realtime: true } }`
+ */
+function makeRealtimeSmartTagsPlugin(tagsByTable) {
+    return {
+        name: 'RealtimeTestSmartTagsPlugin',
+        version: '1.0.0',
+        schema: {
+            hooks: {
+                init: {
+                    before: ['RealtimeSubscriptionsPlugin'],
+                    callback(_, build) {
+                        for (const codec of Object.values(build.input.pgRegistry.pgCodecs)) {
+                            const c = codec;
+                            if (!c.attributes || !c.name)
+                                continue;
+                            const tags = tagsByTable[c.name];
+                            if (!tags)
+                                continue;
+                            if (!c.extensions)
+                                c.extensions = {};
+                            if (!c.extensions.tags)
+                                c.extensions.tags = {};
+                            Object.assign(c.extensions.tags, tags);
+                        }
+                        return _;
+                    },
+                },
+            },
+        },
+    };
+}

package/subscribe.d.ts

@@ -0,0 +1,49 @@
+import type { GraphQLSchema, DocumentNode, ExecutionResult } from 'graphql';
+import type { GraphileConfig } from 'graphile-config';
+/**
+ * A single event yielded by a subscription iterator.
+ */
+export interface SubscriptionEvent<TData = Record<string, unknown>> {
+    data?: TData | null;
+    errors?: readonly {
+        message: string;
+    }[];
+}
+/**
+ * Options for `subscribe()`.
+ */
+export interface SubscribeOptions {
+    schema: GraphQLSchema;
+    resolvedPreset: GraphileConfig.ResolvedPreset;
+    query: string | DocumentNode;
+    variables?: Record<string, unknown>;
+    contextValue?: Record<string, unknown>;
+}
+/**
+ * Call grafast.subscribe() and return the raw async iterator.
+ *
+ * The caller is responsible for iterating the result and calling `.return()`
+ * when done.
+ *
+ * @returns An AsyncIterableIterator that yields ExecutionResult events,
+ *          or an ExecutionResult if subscription setup failed.
+ */
+export declare function subscribe(opts: SubscribeOptions): Promise<AsyncIterableIterator<ExecutionResult> | ExecutionResult>;
+/**
+ * Wait for the next event from a subscription iterator, with a timeout.
+ *
+ * @param iterator - The async iterator returned by `subscribe()`
+ * @param timeoutMs - Maximum time to wait (default: 5000ms)
+ * @returns The next subscription event
+ * @throws If the timeout is exceeded or the iterator completes without a value
+ */
+export declare function waitForEvent<TData = Record<string, unknown>>(iterator: AsyncIterableIterator<ExecutionResult>, timeoutMs?: number): Promise<SubscriptionEvent<TData>>;
+/**
+ * Collect multiple events from a subscription iterator.
+ *
+ * @param iterator - The async iterator returned by `subscribe()`
+ * @param count - Number of events to collect
+ * @param timeoutMs - Maximum time to wait for all events (default: 10000ms)
+ * @returns Array of collected events
+ */
+export declare function collectEvents<TData = Record<string, unknown>>(iterator: AsyncIterableIterator<ExecutionResult>, count: number, timeoutMs?: number): Promise<SubscriptionEvent<TData>[]>;

package/subscribe.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.subscribe = subscribe;
+exports.waitForEvent = waitForEvent;
+exports.collectEvents = collectEvents;
+const grafast_1 = require("grafast");
+const graphql_1 = require("graphql");
+/**
+ * Call grafast.subscribe() and return the raw async iterator.
+ *
+ * The caller is responsible for iterating the result and calling `.return()`
+ * when done.
+ *
+ * @returns An AsyncIterableIterator that yields ExecutionResult events,
+ *          or an ExecutionResult if subscription setup failed.
+ */
+async function subscribe(opts) {
+    const document = typeof opts.query === 'string' ? (0, graphql_1.parse)(opts.query) : opts.query;
+    const result = await (0, grafast_1.subscribe)({
+        schema: opts.schema,
+        document,
+        variableValues: opts.variables ?? undefined,
+        contextValue: opts.contextValue ?? {},
+        resolvedPreset: opts.resolvedPreset,
+    });
+    return result;
+}
+/**
+ * Wait for the next event from a subscription iterator, with a timeout.
+ *
+ * @param iterator - The async iterator returned by `subscribe()`
+ * @param timeoutMs - Maximum time to wait (default: 5000ms)
+ * @returns The next subscription event
+ * @throws If the timeout is exceeded or the iterator completes without a value
+ */
+async function waitForEvent(iterator, timeoutMs = 5000) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            reject(new Error(`waitForEvent timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+        iterator
+            .next()
+            .then((result) => {
+            clearTimeout(timer);
+            if (result.done) {
+                reject(new Error('Subscription iterator completed without yielding a value'));
+            }
+            else {
+                resolve(result.value);
+            }
+        })
+            .catch((err) => {
+            clearTimeout(timer);
+            reject(err);
+        });
+    });
+}
+/**
+ * Collect multiple events from a subscription iterator.
+ *
+ * @param iterator - The async iterator returned by `subscribe()`
+ * @param count - Number of events to collect
+ * @param timeoutMs - Maximum time to wait for all events (default: 10000ms)
+ * @returns Array of collected events
+ */
+async function collectEvents(iterator, count, timeoutMs = 10000) {
+    const events = [];
+    const deadline = Date.now() + timeoutMs;
+    for (let i = 0; i < count; i++) {
+        const remaining = deadline - Date.now();
+        if (remaining <= 0) {
+            throw new Error(`collectEvents timed out after ${timeoutMs}ms (collected ${events.length}/${count})`);
+        }
+        const event = await waitForEvent(iterator, remaining);
+        events.push(event);
+    }
+    return events;
+}