feat: gate subscription hook generation on @realtime smart tag

- Add smartTags field to Table interface in both query and codegen packages
- Parse smart tags from PostGraphile @-prefixed description lines in inferTablesFromIntrospection
- Export parseSmartTags utility from @constructive-io/graphql-query
- Gate subscription hook generation: only tables with @realtime smart tag get hooks
- Gate useConnectionState + subscriptions barrel: only emitted when at least one table has @realtime
- Add comprehensive Smart Tag Gating test suite (5 new tests, all passing)
- All 344 codegen tests + 18 query tests passing, typecheck clean

Author: pyramation

graphql/codegen/src/__tests__/codegen/subscription-hooks.test.ts

@@ -7,6 +7,7 @@
  * - Subscription barrel file
  */
 import { generateSubscriptionsBarrel } from '../../core/codegen/barrel';
+import { generate } from '../../core/codegen/index';
 import {
   generateAllSubscriptionHooks,
   generateConnectionStateHook,
@@ -42,6 +43,7 @@ function createTable(partial: Partial<Table> & { name: string }): Table {
     query: partial.query,
     inflection: partial.inflection,
     constraints: partial.constraints,
+    smartTags: partial.smartTags,
   };
 }
 
@@ -63,6 +65,25 @@ const contactTable = createTable({
   },
 });
 
+const contactTableWithRealtime = createTable({
+  name: 'Contact',
+  fields: [
+    { name: 'id', type: fieldTypes.uuid },
+    { name: 'firstName', type: fieldTypes.string },
+    { name: 'lastName', type: fieldTypes.string },
+    { name: 'email', type: fieldTypes.string },
+    { name: 'createdAt', type: fieldTypes.datetime },
+  ],
+  query: {
+    all: 'contacts',
+    one: 'contact',
+    create: 'createContact',
+    update: 'updateContact',
+    delete: 'deleteContact',
+  },
+  smartTags: { '@realtime': true },
+});
+
 const projectTable = createTable({
   name: 'Project',
   fields: [
@@ -80,6 +101,24 @@ const projectTable = createTable({
   },
 });
 
+const projectTableWithRealtime = createTable({
+  name: 'Project',
+  fields: [
+    { name: 'id', type: fieldTypes.uuid },
+    { name: 'name', type: fieldTypes.string },
+    { name: 'active', type: fieldTypes.boolean },
+    { name: 'createdAt', type: fieldTypes.datetime },
+  ],
+  query: {
+    all: 'projects',
+    one: 'project',
+    create: 'createProject',
+    update: 'updateProject',
+    delete: 'deleteProject',
+  },
+  smartTags: { '@realtime': true },
+});
+
 describe('Subscription naming utils', () => {
   it('generates subscription hook name', () => {
     expect(getSubscriptionHookName(contactTable)).toBe(
@@ -243,3 +282,67 @@ describe('Subscription Barrel Generator', () => {
     expect(result).toContain('./useProjectSubscription');
   });
 });
+
+describe('Smart Tag Gating', () => {
+  const minConfig = {
+    tables: { include: [], exclude: [], systemExclude: [] },
+    queries: { include: [], exclude: [], systemExclude: [] },
+    mutations: { include: [], exclude: [], systemExclude: [] },
+    codegen: { skipQueryField: false },
+    reactQuery: true,
+  } as any;
+
+  it('does not generate subscription hooks when no tables have @realtime', () => {
+    const result = generate({
+      tables: [contactTable, projectTable],
+      config: minConfig,
+    });
+    expect(result.stats.subscriptionHooks).toBe(0);
+    const subFiles = result.files.filter((f) => f.path.startsWith('subscriptions/'));
+    expect(subFiles).toHaveLength(0);
+  });
+
+  it('generates subscription hooks only for tables with @realtime', () => {
+    const result = generate({
+      tables: [contactTableWithRealtime, projectTable],
+      config: minConfig,
+    });
+    expect(result.stats.subscriptionHooks).toBe(1);
+    const subFiles = result.files.filter((f) => f.path.startsWith('subscriptions/'));
+    expect(subFiles.some((f) => f.path.includes('useContactSubscription'))).toBe(true);
+    expect(subFiles.some((f) => f.path.includes('useProjectSubscription'))).toBe(false);
+    expect(subFiles.some((f) => f.path.includes('useConnectionState'))).toBe(true);
+    expect(subFiles.some((f) => f.path === 'subscriptions/index.ts')).toBe(true);
+  });
+
+  it('generates subscription hooks for all @realtime tables', () => {
+    const result = generate({
+      tables: [contactTableWithRealtime, projectTableWithRealtime],
+      config: minConfig,
+    });
+    expect(result.stats.subscriptionHooks).toBe(2);
+    const subFiles = result.files.filter((f) => f.path.startsWith('subscriptions/'));
+    expect(subFiles.some((f) => f.path.includes('useContactSubscription'))).toBe(true);
+    expect(subFiles.some((f) => f.path.includes('useProjectSubscription'))).toBe(true);
+  });
+
+  it('does not emit useConnectionState or barrel when no @realtime tables', () => {
+    const result = generate({
+      tables: [contactTable],
+      config: minConfig,
+    });
+    const subFiles = result.files.filter((f) => f.path.startsWith('subscriptions/'));
+    expect(subFiles).toHaveLength(0);
+    const mainBarrel = result.files.find((f) => f.path === 'index.ts');
+    expect(mainBarrel?.content).not.toContain('./subscriptions');
+  });
+
+  it('emits subscriptions barrel in main index when @realtime tables exist', () => {
+    const result = generate({
+      tables: [contactTableWithRealtime],
+      config: minConfig,
+    });
+    const mainBarrel = result.files.find((f) => f.path === 'index.ts');
+    expect(mainBarrel?.content).toContain('./subscriptions');
+  });
+});

graphql/codegen/src/core/codegen/index.ts

@@ -299,27 +299,31 @@ export function generate(options: GenerateOptions): GenerateResult {
   }
 
   // 8b. Generate subscription hooks (subscriptions/*.ts)
-  const subscriptionHooks = generateAllSubscriptionHooks(tables);
+  // Only generate for tables with the @realtime smart tag
+  const realtimeTables = tables.filter(
+    (t) => t.smartTags?.['@realtime'] !== undefined,
+  );
+  const subscriptionHooks = generateAllSubscriptionHooks(realtimeTables);
   for (const hook of subscriptionHooks) {
     files.push({
       path: `subscriptions/${hook.fileName}`,
       content: hook.content,
     });
   }
 
-  // 8c. Generate connection state hook
-  const connectionStateHook = generateConnectionStateHook();
-  files.push({
-    path: `subscriptions/${connectionStateHook.fileName}`,
-    content: connectionStateHook.content,
-  });
-
-  // 8d. Generate subscriptions/index.ts barrel
+  // 8c. Generate connection state hook + barrel only if any table has @realtime
   const hasSubscriptions = subscriptionHooks.length > 0;
   if (hasSubscriptions) {
+    const connectionStateHook = generateConnectionStateHook();
+    files.push({
+      path: `subscriptions/${connectionStateHook.fileName}`,
+      content: connectionStateHook.content,
+    });
+
+    // 8d. Generate subscriptions/index.ts barrel
     files.push({
       path: 'subscriptions/index.ts',
-      content: generateSubscriptionsBarrel(tables),
+      content: generateSubscriptionsBarrel(realtimeTables),
     });
   }
 

graphql/codegen/src/types/schema.ts

@@ -18,6 +18,8 @@ export interface Table {
   query?: TableQueryNames;
   /** Constraint information */
   constraints?: TableConstraints;
+  /** Smart tags parsed from PostGraphile @-prefixed comment directives */
+  smartTags?: Record<string, string | true>;
 }
 
 /**

graphql/query/src/index.ts

@@ -40,4 +40,4 @@ export * from './client';
 export * from './introspect';
 
 // Utility functions
-export { stripSmartComments } from './utils';
+export { parseSmartTags, stripSmartComments } from './utils';

graphql/query/src/introspect/infer-tables.ts

@@ -14,7 +14,7 @@
  */
 import { lcFirst, pluralize, singularize, ucFirst } from 'inflekt';
 
-import { stripSmartComments } from '../utils';
+import { parseSmartTags, stripSmartComments } from '../utils';
 
 import type {
   IntrospectionField,
@@ -324,6 +324,9 @@ function buildCleanTable(
   // Extract description from entity type (PostgreSQL COMMENT), strip smart comments
   const description = commentsEnabled ? stripSmartComments(entityType.description) : undefined;
 
+  // Parse smart tags from raw description before they are stripped
+  const smartTags = parseSmartTags(entityType.description);
+
   return {
     table: {
       name: entityName,
@@ -333,6 +336,7 @@ function buildCleanTable(
       inflection,
       query,
       constraints,
+      ...(smartTags ? { smartTags } : {}),
     },
     hasRealOperation,
   };

graphql/query/src/types/schema.ts

@@ -18,6 +18,8 @@ export interface Table {
   query?: TableQueryNames;
   /** Constraint information */
   constraints?: TableConstraints;
+  /** Smart tags parsed from PostGraphile @-prefixed comment directives */
+  smartTags?: Record<string, string | true>;
 }
 
 /**

graphql/query/src/utils.ts

@@ -73,3 +73,34 @@ export function stripSmartComments(
 
   return result;
 }
+
+/**
+ * Parse PostGraphile smart tags from a description string.
+ *
+ * Smart tags are lines starting with `@` in PostgreSQL COMMENTs.
+ * Each line is parsed as `@tagName` (boolean true) or `@tagName value`.
+ *
+ * Returns undefined if no smart tags are found.
+ */
+export function parseSmartTags(
+  description: string | null | undefined,
+): Record<string, string | true> | undefined {
+  if (!description) return undefined;
+
+  const lines = description.split('\n');
+  let tags: Record<string, string | true> | undefined;
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith('@')) continue;
+
+    const spaceIdx = trimmed.indexOf(' ');
+    const tagName = spaceIdx === -1 ? trimmed : trimmed.slice(0, spaceIdx);
+    const tagValue = spaceIdx === -1 ? true : trimmed.slice(spaceIdx + 1).trim();
+
+    if (!tags) tags = {};
+    tags[tagName] = tagValue || true;
+  }
+
+  return tags;
+}