@constructive-io/graphql-codegen 4.38.1 → 4.39.0

package/core/codegen/barrel.d.ts

@@ -15,6 +15,8 @@ export declare function generateMutationsBarrel(tables: Table[]): string;
  */
 export interface MainBarrelOptions {
     hasMutations?: boolean;
+    /** Whether subscriptions/ directory was generated */
+    hasSubscriptions?: boolean;
     /** Whether query-keys.ts was generated */
     hasQueryKeys?: boolean;
     /** Whether mutation-keys.ts was generated */
@@ -44,6 +46,10 @@ export declare function generateRootBarrel(options?: RootBarrelOptions): string;
  *   export * as public_ from './public';
  */
 export declare function generateMultiTargetBarrel(targetNames: string[]): string;
+/**
+ * Generate the subscriptions/index.ts barrel file
+ */
+export declare function generateSubscriptionsBarrel(tables: Table[]): string;
 /**
  * Generate queries barrel including custom query operations
  */

package/core/codegen/barrel.js

@@ -38,6 +38,7 @@ exports.generateMutationsBarrel = generateMutationsBarrel;
 exports.generateMainBarrel = generateMainBarrel;
 exports.generateRootBarrel = generateRootBarrel;
 exports.generateMultiTargetBarrel = generateMultiTargetBarrel;
+exports.generateSubscriptionsBarrel = generateSubscriptionsBarrel;
 exports.generateCustomQueriesBarrel = generateCustomQueriesBarrel;
 exports.generateCustomMutationsBarrel = generateCustomMutationsBarrel;
 /**
@@ -111,7 +112,7 @@ function generateMutationsBarrel(tables) {
 }
 function generateMainBarrel(tables, options = {}) {
     const opts = options;
-    const { hasMutations = true, hasQueryKeys = false, hasMutationKeys = false, hasInvalidation = false, } = opts;
+    const { hasMutations = true, hasSubscriptions = false, hasQueryKeys = false, hasMutationKeys = false, hasInvalidation = false, } = opts;
     const tableNames = tables.map((tbl) => tbl.name).join(', ');
     const statements = [];
     // Client configuration (ORM wrapper with configure/getClient)
@@ -134,6 +135,10 @@ function generateMainBarrel(tables, options = {}) {
     if (hasMutations) {
         statements.push(exportAllFrom('./mutations'));
     }
+    // Subscription hooks
+    if (hasSubscriptions) {
+        statements.push(exportAllFrom('./subscriptions'));
+    }
     // Add file header as leading comment on first statement
     if (statements.length > 0) {
         (0, babel_ast_1.addJSDocComment)(statements[0], [
@@ -243,6 +248,26 @@ function generateMultiTargetBarrel(targetNames) {
     }
     return (0, babel_ast_1.generateCode)(statements);
 }
+/**
+ * Generate the subscriptions/index.ts barrel file
+ */
+function generateSubscriptionsBarrel(tables) {
+    const statements = [];
+    for (const table of tables) {
+        const hookName = (0, utils_1.getSubscriptionHookName)(table);
+        statements.push(exportAllFrom(`./${hookName}`));
+    }
+    // Connection state hook
+    statements.push(exportAllFrom('./useConnectionState'));
+    if (statements.length > 0) {
+        (0, babel_ast_1.addJSDocComment)(statements[0], [
+            'Subscription hooks barrel export',
+            '@generated by @constructive-io/graphql-codegen',
+            'DO NOT EDIT - changes will be overwritten',
+        ]);
+    }
+    return (0, babel_ast_1.generateCode)(statements);
+}
 // ============================================================================
 // Custom operation barrels (includes both table and custom hooks)
 // ============================================================================

package/core/codegen/index.d.ts

@@ -36,6 +36,7 @@ export interface GenerateResult {
         tables: number;
         queryHooks: number;
         mutationHooks: number;
+        subscriptionHooks: number;
         customQueryHooks: number;
         customMutationHooks: number;
         totalFiles: number;
@@ -71,7 +72,7 @@ export declare function generateAllFiles(tables: Table[], config: GraphQLSDKConf
  * (they're expected to exist in the shared types directory).
  */
 export declare function generate(options: GenerateOptions): GenerateResult;
-export { generateCustomMutationsBarrel, generateCustomQueriesBarrel, generateMainBarrel, generateMutationsBarrel, generateQueriesBarrel, } from './barrel';
+export { generateCustomMutationsBarrel, generateCustomQueriesBarrel, generateMainBarrel, generateMutationsBarrel, generateQueriesBarrel, generateSubscriptionsBarrel, } from './barrel';
 export { generateClientFile } from './client';
 export { generateAllCustomMutationHooks, generateCustomMutationHook, } from './custom-mutations';
 export { generateAllCustomQueryHooks, generateCustomQueryHook, } from './custom-queries';
@@ -80,3 +81,4 @@ export { generateMutationKeysFile } from './mutation-keys';
 export { generateAllMutationHooks, generateCreateMutationHook, generateDeleteMutationHook, generateUpdateMutationHook, } from './mutations';
 export { generateAllQueryHooks, generateListQueryHook, generateSingleQueryHook, } from './queries';
 export { generateQueryKeysFile } from './query-keys';
+export { generateAllSubscriptionHooks, generateConnectionStateHook, generateSubscriptionHook, } from './subscriptions';

package/core/codegen/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.generateQueryKeysFile = exports.generateSingleQueryHook = exports.generateListQueryHook = exports.generateAllQueryHooks = exports.generateUpdateMutationHook = exports.generateDeleteMutationHook = exports.generateCreateMutationHook = exports.generateAllMutationHooks = exports.generateMutationKeysFile = exports.generateInvalidationFile = exports.generateCustomQueryHook = exports.generateAllCustomQueryHooks = exports.generateCustomMutationHook = exports.generateAllCustomMutationHooks = exports.generateClientFile = exports.generateQueriesBarrel = exports.generateMutationsBarrel = exports.generateMainBarrel = exports.generateCustomQueriesBarrel = exports.generateCustomMutationsBarrel = void 0;
+exports.generateSubscriptionHook = exports.generateConnectionStateHook = exports.generateAllSubscriptionHooks = exports.generateQueryKeysFile = exports.generateSingleQueryHook = exports.generateListQueryHook = exports.generateAllQueryHooks = exports.generateUpdateMutationHook = exports.generateDeleteMutationHook = exports.generateCreateMutationHook = exports.generateAllMutationHooks = exports.generateMutationKeysFile = exports.generateInvalidationFile = exports.generateCustomQueryHook = exports.generateAllCustomQueryHooks = exports.generateCustomMutationHook = exports.generateAllCustomMutationHooks = exports.generateClientFile = exports.generateSubscriptionsBarrel = exports.generateQueriesBarrel = exports.generateMutationsBarrel = exports.generateMainBarrel = exports.generateCustomQueriesBarrel = exports.generateCustomMutationsBarrel = void 0;
 exports.generateAllFiles = generateAllFiles;
 exports.generate = generate;
 const config_1 = require("../../types/config");
@@ -13,6 +13,7 @@ const mutation_keys_1 = require("./mutation-keys");
 const mutations_1 = require("./mutations");
 const queries_1 = require("./queries");
 const query_keys_1 = require("./query-keys");
+const subscriptions_1 = require("./subscriptions");
 const selection_1 = require("./selection");
 const utils_1 = require("./utils");
 // ============================================================================
@@ -173,12 +174,37 @@ function generate(options) {
                 : (0, barrel_1.generateMutationsBarrel)(tables),
         });
     }
+    // 8b. Generate subscription hooks (subscriptions/*.ts)
+    // Only generate for tables with the @realtime smart tag
+    const realtimeTables = tables.filter((t) => t.smartTags?.['@realtime'] !== undefined);
+    const subscriptionHooks = (0, subscriptions_1.generateAllSubscriptionHooks)(realtimeTables);
+    for (const hook of subscriptionHooks) {
+        files.push({
+            path: `subscriptions/${hook.fileName}`,
+            content: hook.content,
+        });
+    }
+    // 8c. Generate connection state hook + barrel only if any table has @realtime
+    const hasSubscriptions = subscriptionHooks.length > 0;
+    if (hasSubscriptions) {
+        const connectionStateHook = (0, subscriptions_1.generateConnectionStateHook)();
+        files.push({
+            path: `subscriptions/${connectionStateHook.fileName}`,
+            content: connectionStateHook.content,
+        });
+        // 8d. Generate subscriptions/index.ts barrel
+        files.push({
+            path: 'subscriptions/index.ts',
+            content: (0, barrel_1.generateSubscriptionsBarrel)(realtimeTables),
+        });
+    }
     // 9. Generate main index.ts barrel
     // No longer includes types.ts or schema-types.ts - hooks import from ORM directly
     files.push({
         path: 'index.ts',
         content: (0, barrel_1.generateMainBarrel)(tables, {
             hasMutations,
+            hasSubscriptions,
             hasQueryKeys,
             hasMutationKeys,
             hasInvalidation,
@@ -190,6 +216,7 @@ function generate(options) {
             tables: tables.length,
             queryHooks: queryHooks.length,
             mutationHooks: mutationHooks.length,
+            subscriptionHooks: subscriptionHooks.length,
             customQueryHooks: customQueryHooks.length,
             customMutationHooks: customMutationHooks.length,
             totalFiles: files.length,
@@ -205,6 +232,7 @@ Object.defineProperty(exports, "generateCustomQueriesBarrel", { enumerable: true
 Object.defineProperty(exports, "generateMainBarrel", { enumerable: true, get: function () { return barrel_2.generateMainBarrel; } });
 Object.defineProperty(exports, "generateMutationsBarrel", { enumerable: true, get: function () { return barrel_2.generateMutationsBarrel; } });
 Object.defineProperty(exports, "generateQueriesBarrel", { enumerable: true, get: function () { return barrel_2.generateQueriesBarrel; } });
+Object.defineProperty(exports, "generateSubscriptionsBarrel", { enumerable: true, get: function () { return barrel_2.generateSubscriptionsBarrel; } });
 var client_2 = require("./client");
 Object.defineProperty(exports, "generateClientFile", { enumerable: true, get: function () { return client_2.generateClientFile; } });
 var custom_mutations_2 = require("./custom-mutations");
@@ -228,3 +256,7 @@ Object.defineProperty(exports, "generateListQueryHook", { enumerable: true, get:
 Object.defineProperty(exports, "generateSingleQueryHook", { enumerable: true, get: function () { return queries_2.generateSingleQueryHook; } });
 var query_keys_2 = require("./query-keys");
 Object.defineProperty(exports, "generateQueryKeysFile", { enumerable: true, get: function () { return query_keys_2.generateQueryKeysFile; } });
+var subscriptions_2 = require("./subscriptions");
+Object.defineProperty(exports, "generateAllSubscriptionHooks", { enumerable: true, get: function () { return subscriptions_2.generateAllSubscriptionHooks; } });
+Object.defineProperty(exports, "generateConnectionStateHook", { enumerable: true, get: function () { return subscriptions_2.generateConnectionStateHook; } });
+Object.defineProperty(exports, "generateSubscriptionHook", { enumerable: true, get: function () { return subscriptions_2.generateSubscriptionHook; } });

package/core/codegen/orm/client-generator.d.ts

@@ -10,6 +10,12 @@ export interface GeneratedClientFile {
  * Reads from the templates directory for proper type checking.
  */
 export declare function generateOrmClientFile(): GeneratedClientFile;
+/**
+ * Generate the realtime.ts file (RealtimeManager + subscription types)
+ *
+ * Reads from the templates directory for proper type checking.
+ */
+export declare function generateRealtimeFile(): GeneratedClientFile;
 /**
  * Generate the query-builder.ts file (runtime query builder)
  *

package/core/codegen/orm/client-generator.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.generateOrmClientFile = generateOrmClientFile;
+exports.generateRealtimeFile = generateRealtimeFile;
 exports.generateQueryBuilderFile = generateQueryBuilderFile;
 exports.generateSelectTypesFile = generateSelectTypesFile;
 exports.generateCreateClientFile = generateCreateClientFile;
@@ -83,6 +84,17 @@ function generateOrmClientFile() {
         content: readTemplateFile('orm-client.ts', 'ORM Client - Runtime GraphQL executor'),
     };
 }
+/**
+ * Generate the realtime.ts file (RealtimeManager + subscription types)
+ *
+ * Reads from the templates directory for proper type checking.
+ */
+function generateRealtimeFile() {
+    return {
+        fileName: 'realtime.ts',
+        content: readTemplateFile('orm-realtime.ts', 'Realtime Manager - WebSocket subscription support'),
+    };
+}
 /**
  * Generate the query-builder.ts file (runtime query builder)
  *

package/core/codegen/orm/client.d.ts

@@ -45,6 +45,37 @@ export declare class FetchAdapter implements GraphQLAdapter {
     setHeaders(headers: Record<string, string>): void;
     getEndpoint(): string;
 }
+export type SubscriptionOperation = 'INSERT' | 'UPDATE' | 'DELETE';
+export type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting';
+export type ConnectionStateListener = (state: ConnectionState) => void;
+export type Unsubscribe = () => void;
+export interface SubscriptionEvent<T> {
+    operation: SubscriptionOperation;
+    data: T | null;
+    previousValues?: Partial<T>;
+    timestamp: string;
+}
+export interface SubscriptionFieldMeta {
+    fieldName: string;
+    tableName: string;
+    dataFieldName: string;
+}
+export interface SubscribeOptions<T, TFilter = Record<string, unknown>> {
+    filter?: TFilter;
+    onEvent: (event: SubscriptionEvent<T>) => void;
+    onError?: (error: Error) => void;
+    onComplete?: () => void;
+}
+export interface RealtimeConfig {
+    url: string;
+    getToken?: () => string | Promise<string>;
+    connectionParams?: Record<string, unknown>;
+    lazy?: boolean;
+    retryAttempts?: number;
+    retryWait?: number | ((retryCount: number) => number | Promise<number>);
+    onConnected?: () => void;
+    onDisconnected?: (reason?: unknown) => void;
+}
 /**
  * Configuration for creating an ORM client.
  */
@@ -55,6 +86,8 @@ export interface OrmClientConfig {
     headers?: Record<string, string>;
     /** Custom adapter for GraphQL execution (overrides endpoint/headers) */
     adapter?: GraphQLAdapter;
+    /** Optional realtime (WebSocket) configuration */
+    realtime?: RealtimeConfig;
 }
 export declare class GraphQLRequestError extends Error {
     readonly errors: GraphQLError[];
@@ -65,6 +98,16 @@ export declare class OrmClient {
     private adapter;
     constructor(config: OrmClientConfig);
     execute<T>(document: string, variables?: Record<string, unknown>): Promise<QueryResult<T>>;
+    subscribe<T>(meta: SubscriptionFieldMeta, document: string, variables: Record<string, unknown>, options: {
+        onEvent: (event: SubscriptionEvent<T>) => void;
+        onError?: (error: Error) => void;
+        onComplete?: () => void;
+    }): Unsubscribe;
     setHeaders(headers: Record<string, string>): void;
     getEndpoint(): string;
+    getConnectionState(): ConnectionState;
+    onConnectionStateChange(listener: ConnectionStateListener): Unsubscribe;
+    getActiveSubscriptionCount(): number;
+    get isRealtimeEnabled(): boolean;
+    dispose(): void;
 }

package/core/codegen/orm/client.js

@@ -92,6 +92,9 @@ class OrmClient {
     async execute(document, variables) {
         return this.adapter.execute(document, variables);
     }
+    subscribe(meta, document, variables, options) {
+        throw new Error('Realtime not configured');
+    }
     setHeaders(headers) {
         if (this.adapter.setHeaders) {
             this.adapter.setHeaders(headers);
@@ -100,5 +103,18 @@ class OrmClient {
     getEndpoint() {
         return this.adapter.getEndpoint?.() ?? '';
     }
+    getConnectionState() {
+        return 'disconnected';
+    }
+    onConnectionStateChange(listener) {
+        return () => { };
+    }
+    getActiveSubscriptionCount() {
+        return 0;
+    }
+    get isRealtimeEnabled() {
+        return false;
+    }
+    dispose() { }
 }
 exports.OrmClient = OrmClient;

package/core/codegen/orm/index.d.ts

@@ -40,6 +40,6 @@ export interface GenerateOrmResult {
  */
 export declare function generateOrm(options: GenerateOrmOptions): GenerateOrmResult;
 export { generateModelsBarrel, generateTypesBarrel } from './barrel';
-export { generateOrmClientFile, generateQueryBuilderFile, generateSelectTypesFile, } from './client-generator';
+export { generateOrmClientFile, generateQueryBuilderFile, generateRealtimeFile, generateSelectTypesFile, } from './client-generator';
 export { generateCustomMutationOpsFile, generateCustomQueryOpsFile, } from './custom-ops-generator';
 export { generateAllModelFiles, generateModelFile } from './model-generator';

package/core/codegen/orm/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.generateModelFile = exports.generateAllModelFiles = exports.generateCustomQueryOpsFile = exports.generateCustomMutationOpsFile = exports.generateSelectTypesFile = exports.generateQueryBuilderFile = exports.generateOrmClientFile = exports.generateTypesBarrel = exports.generateModelsBarrel = void 0;
+exports.generateModelFile = exports.generateAllModelFiles = exports.generateCustomQueryOpsFile = exports.generateCustomMutationOpsFile = exports.generateSelectTypesFile = exports.generateRealtimeFile = exports.generateQueryBuilderFile = exports.generateOrmClientFile = exports.generateTypesBarrel = exports.generateModelsBarrel = void 0;
 exports.generateOrm = generateOrm;
 const barrel_1 = require("./barrel");
 const client_generator_1 = require("./client-generator");
@@ -19,9 +19,11 @@ function generateOrm(options) {
     const hasCustomQueries = (customOperations?.queries.length ?? 0) > 0;
     const hasCustomMutations = (customOperations?.mutations.length ?? 0) > 0;
     const typeRegistry = customOperations?.typeRegistry;
-    // 1. Generate runtime files (client, query-builder, select-types)
+    // 1. Generate runtime files (client, query-builder, select-types, realtime)
     const clientFile = (0, client_generator_1.generateOrmClientFile)();
     files.push({ path: clientFile.fileName, content: clientFile.content });
+    const realtimeFile = (0, client_generator_1.generateRealtimeFile)();
+    files.push({ path: realtimeFile.fileName, content: realtimeFile.content });
     const queryBuilderFile = (0, client_generator_1.generateQueryBuilderFile)();
     files.push({
         path: queryBuilderFile.fileName,
@@ -111,6 +113,7 @@ Object.defineProperty(exports, "generateTypesBarrel", { enumerable: true, get: f
 var client_generator_2 = require("./client-generator");
 Object.defineProperty(exports, "generateOrmClientFile", { enumerable: true, get: function () { return client_generator_2.generateOrmClientFile; } });
 Object.defineProperty(exports, "generateQueryBuilderFile", { enumerable: true, get: function () { return client_generator_2.generateQueryBuilderFile; } });
+Object.defineProperty(exports, "generateRealtimeFile", { enumerable: true, get: function () { return client_generator_2.generateRealtimeFile; } });
 Object.defineProperty(exports, "generateSelectTypesFile", { enumerable: true, get: function () { return client_generator_2.generateSelectTypesFile; } });
 var custom_ops_generator_2 = require("./custom-ops-generator");
 Object.defineProperty(exports, "generateCustomMutationOpsFile", { enumerable: true, get: function () { return custom_ops_generator_2.generateCustomMutationOpsFile; } });

package/core/codegen/subscriptions.d.ts

@@ -0,0 +1,30 @@
+import type { Table } from '../../types/schema';
+export interface GeneratedSubscriptionFile {
+    fileName: string;
+    content: string;
+}
+/**
+ * Generate a subscription hook for a table.
+ *
+ * Produces a React hook that calls `getClient().subscribe()` with the
+ * correct subscription document, field metadata, and typed callbacks.
+ *
+ * Example generated output:
+ * ```ts
+ * export function useContactSubscription(options: ContactSubscriptionOptions): Unsubscribe {
+ *   ...
+ * }
+ * ```
+ */
+export declare function generateSubscriptionHook(table: Table): GeneratedSubscriptionFile;
+/**
+ * Generate the useConnectionState hook file.
+ *
+ * This hook exposes the WebSocket connection state from the ORM client
+ * so UI components can show connection indicators.
+ */
+export declare function generateConnectionStateHook(): GeneratedSubscriptionFile;
+/**
+ * Generate subscription hooks for all tables
+ */
+export declare function generateAllSubscriptionHooks(tables: Table[]): GeneratedSubscriptionFile[];

package/core/codegen/subscriptions.js

@@ -0,0 +1,270 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateSubscriptionHook = generateSubscriptionHook;
+exports.generateConnectionStateHook = generateConnectionStateHook;
+exports.generateAllSubscriptionHooks = generateAllSubscriptionHooks;
+/**
+ * Subscription hook generators - delegates to ORM client subscribe (Babel AST-based)
+ *
+ * Output structure:
+ * subscriptions/
+ *   useContactSubscription.ts  - Subscription hook -> ORM client.subscribe()
+ *   useConnectionState.ts      - Connection state hook
+ */
+const t = __importStar(require("@babel/types"));
+const hooks_ast_1 = require("./hooks-ast");
+const utils_1 = require("./utils");
+/**
+ * Generate a subscription hook for a table.
+ *
+ * Produces a React hook that calls `getClient().subscribe()` with the
+ * correct subscription document, field metadata, and typed callbacks.
+ *
+ * Example generated output:
+ * ```ts
+ * export function useContactSubscription(options: ContactSubscriptionOptions): Unsubscribe {
+ *   ...
+ * }
+ * ```
+ */
+function generateSubscriptionHook(table) {
+    const { typeName, singularName } = (0, utils_1.getTableNames)(table);
+    const hookName = (0, utils_1.getSubscriptionHookName)(table);
+    const subscriptionFieldName = (0, utils_1.getSubscriptionFieldName)(table);
+    const keysName = `${(0, utils_1.lcFirst)(typeName)}Keys`;
+    const statements = [];
+    // Imports
+    statements.push((0, hooks_ast_1.createImportDeclaration)('react', ['useEffect', 'useRef', 'useCallback']));
+    statements.push((0, hooks_ast_1.createImportDeclaration)('@tanstack/react-query', ['useQueryClient']));
+    statements.push((0, hooks_ast_1.createImportDeclaration)('@tanstack/react-query', ['QueryClient'], true));
+    statements.push((0, hooks_ast_1.createImportDeclaration)('../client', ['getClient']));
+    statements.push((0, hooks_ast_1.createImportDeclaration)('../../orm/client', [
+        'SubscriptionEvent',
+        'SubscriptionFieldMeta',
+        'Unsubscribe',
+    ], true));
+    statements.push((0, hooks_ast_1.createImportDeclaration)('../../orm/input-types', [typeName], true));
+    statements.push((0, hooks_ast_1.createImportDeclaration)('../query-keys', [keysName]));
+    // Re-export SubscriptionEvent for consumer convenience
+    statements.push((0, hooks_ast_1.createTypeReExport)(['SubscriptionEvent', 'Unsubscribe'], '../../orm/client'));
+    // Subscription document constant
+    const subscriptionDoc = `subscription On${typeName}Changed {
+  ${subscriptionFieldName} {
+    event
+    ${singularName} { __typename }
+    timestamp
+  }
+}`;
+    const docDecl = (0, hooks_ast_1.constDecl)('SUBSCRIPTION_DOCUMENT', t.stringLiteral(subscriptionDoc));
+    statements.push(docDecl);
+    // Field metadata constant
+    const metaDecl = t.variableDeclaration('const', [
+        t.variableDeclarator(t.identifier('FIELD_META'), t.objectExpression([
+            (0, hooks_ast_1.objectProp)('fieldName', t.stringLiteral(subscriptionFieldName)),
+            (0, hooks_ast_1.objectProp)('tableName', t.stringLiteral(singularName)),
+            (0, hooks_ast_1.objectProp)('dataFieldName', t.stringLiteral(singularName)),
+        ])),
+    ]);
+    // Add type annotation: SubscriptionFieldMeta
+    const metaId = metaDecl.declarations[0].id;
+    metaId.typeAnnotation = t.tsTypeAnnotation((0, hooks_ast_1.typeRef)('SubscriptionFieldMeta'));
+    statements.push(metaDecl);
+    // Options interface
+    const optionsTypeName = `${typeName}SubscriptionOptions`;
+    const optionsInterface = t.tsInterfaceDeclaration(t.identifier(optionsTypeName), null, null, t.tsInterfaceBody([
+        (() => {
+            const p = t.tsPropertySignature(t.identifier('onEvent'), t.tsTypeAnnotation(t.tsFunctionType(null, [
+                (0, hooks_ast_1.createFunctionParam)('event', (0, hooks_ast_1.typeRef)('SubscriptionEvent', [(0, hooks_ast_1.typeRef)(typeName)])),
+            ], t.tsTypeAnnotation(t.tsVoidKeyword()))));
+            return p;
+        })(),
+        (() => {
+            const p = t.tsPropertySignature(t.identifier('onError'), t.tsTypeAnnotation(t.tsFunctionType(null, [(0, hooks_ast_1.createFunctionParam)('error', (0, hooks_ast_1.typeRef)('Error'))], t.tsTypeAnnotation(t.tsVoidKeyword()))));
+            p.optional = true;
+            return p;
+        })(),
+        (() => {
+            const p = t.tsPropertySignature(t.identifier('enabled'), t.tsTypeAnnotation(t.tsBooleanKeyword()));
+            p.optional = true;
+            return p;
+        })(),
+        (() => {
+            const p = t.tsPropertySignature(t.identifier('invalidateQueries'), t.tsTypeAnnotation(t.tsBooleanKeyword()));
+            p.optional = true;
+            return p;
+        })(),
+    ]));
+    statements.push(t.exportNamedDeclaration(optionsInterface));
+    // Hook implementation
+    const hookBody = [];
+    // const queryClient = useQueryClient();
+    hookBody.push((0, hooks_ast_1.constDecl)('queryClient', (0, hooks_ast_1.callExpr)('useQueryClient', [])));
+    // const optionsRef = useRef(options);
+    hookBody.push((0, hooks_ast_1.constDecl)('optionsRef', (0, hooks_ast_1.callExpr)('useRef', [t.identifier('options')])));
+    // optionsRef.current = options;
+    hookBody.push(t.expressionStatement(t.assignmentExpression('=', t.memberExpression(t.identifier('optionsRef'), t.identifier('current')), t.identifier('options'))));
+    // useEffect with subscribe
+    const effectBody = [];
+    // if (options.enabled === false) return;
+    effectBody.push(t.ifStatement(t.binaryExpression('===', t.memberExpression(t.identifier('options'), t.identifier('enabled')), t.booleanLiteral(false)), t.returnStatement(null)));
+    // const client = getClient();
+    effectBody.push((0, hooks_ast_1.constDecl)('client', (0, hooks_ast_1.callExpr)('getClient', [])));
+    // if (!client.isRealtimeEnabled) return;
+    effectBody.push(t.ifStatement(t.unaryExpression('!', t.memberExpression(t.identifier('client'), t.identifier('isRealtimeEnabled'))), t.returnStatement(null)));
+    // const unsubscribe = client.subscribe(FIELD_META, SUBSCRIPTION_DOCUMENT, {}, { onEvent, onError, onComplete });
+    const subscribeCall = t.callExpression(t.memberExpression(t.identifier('client'), t.identifier('subscribe')), [
+        t.identifier('FIELD_META'),
+        t.identifier('SUBSCRIPTION_DOCUMENT'),
+        t.objectExpression([]),
+        t.objectExpression([
+            (0, hooks_ast_1.objectProp)('onEvent', t.arrowFunctionExpression([t.identifier('event')], t.blockStatement([
+                // optionsRef.current.onEvent(event);
+                t.expressionStatement((0, hooks_ast_1.callExpr)(t.memberExpression(t.memberExpression(t.identifier('optionsRef'), t.identifier('current')), t.identifier('onEvent')), [t.identifier('event')])),
+                // if (optionsRef.current.invalidateQueries !== false) { queryClient.invalidateQueries({ queryKey: keysName.all }); }
+                t.ifStatement(t.binaryExpression('!==', t.memberExpression(t.memberExpression(t.identifier('optionsRef'), t.identifier('current')), t.identifier('invalidateQueries')), t.booleanLiteral(false)), t.expressionStatement((0, hooks_ast_1.callExpr)(t.memberExpression(t.identifier('queryClient'), t.identifier('invalidateQueries')), [
+                    t.objectExpression([
+                        (0, hooks_ast_1.objectProp)('queryKey', t.memberExpression(t.identifier(keysName), t.identifier('all'))),
+                    ]),
+                ]))),
+            ]))),
+            (0, hooks_ast_1.objectProp)('onError', t.arrowFunctionExpression([t.identifier('err')], t.blockStatement([
+                t.expressionStatement(t.optionalCallExpression(t.optionalMemberExpression(t.memberExpression(t.identifier('optionsRef'), t.identifier('current')), t.identifier('onError'), false, true), [t.identifier('err')], false)),
+            ]))),
+        ]),
+    ]);
+    effectBody.push((0, hooks_ast_1.constDecl)('unsubscribe', subscribeCall));
+    // return () => unsubscribe();
+    effectBody.push(t.returnStatement(t.arrowFunctionExpression([], t.callExpression(t.identifier('unsubscribe'), []))));
+    // useEffect(() => { ... }, [options.enabled]);
+    const effectFn = t.arrowFunctionExpression([], t.blockStatement(effectBody));
+    hookBody.push(t.expressionStatement((0, hooks_ast_1.callExpr)('useEffect', [
+        effectFn,
+        t.arrayExpression([
+            t.memberExpression(t.identifier('options'), t.identifier('enabled')),
+            t.identifier('queryClient'),
+        ]),
+    ])));
+    // Hook declaration
+    const hookParam = (0, hooks_ast_1.createFunctionParam)('options', (0, hooks_ast_1.typeRef)(optionsTypeName));
+    const hookDecl = (0, hooks_ast_1.exportFunction)(hookName, null, [hookParam], hookBody, t.tsVoidKeyword());
+    (0, hooks_ast_1.addJSDocComment)(hookDecl, [
+        `Subscription hook for ${typeName} realtime events`,
+        '',
+        'Subscribes to realtime changes on the server and automatically',
+        'invalidates React Query cache when events are received.',
+        '',
+        '@example',
+        '```tsx',
+        `${hookName}({`,
+        '  onEvent: (event) => {',
+        `    console.log(event.operation, event.data);`,
+        '  },',
+        '});',
+        '```',
+    ]);
+    statements.push(hookDecl);
+    return {
+        fileName: (0, utils_1.getSubscriptionFileName)(table),
+        content: (0, hooks_ast_1.generateHookFileCode)(`Subscription hook for ${typeName}`, statements),
+    };
+}
+/**
+ * Generate the useConnectionState hook file.
+ *
+ * This hook exposes the WebSocket connection state from the ORM client
+ * so UI components can show connection indicators.
+ */
+function generateConnectionStateHook() {
+    const statements = [];
+    // Imports
+    statements.push((0, hooks_ast_1.createImportDeclaration)('react', ['useState', 'useEffect']));
+    statements.push((0, hooks_ast_1.createImportDeclaration)('../client', ['getClient']));
+    statements.push((0, hooks_ast_1.createImportDeclaration)('../../orm/client', ['ConnectionState'], true));
+    // Re-export ConnectionState
+    statements.push((0, hooks_ast_1.createTypeReExport)(['ConnectionState'], '../../orm/client'));
+    // Hook body
+    const hookBody = [];
+    // const [state, setState] = useState<ConnectionState>(() => getClient().getConnectionState());
+    const initFn = t.arrowFunctionExpression([], (0, hooks_ast_1.callExpr)(t.memberExpression((0, hooks_ast_1.callExpr)('getClient', []), t.identifier('getConnectionState')), []));
+    const useStateCall = (0, hooks_ast_1.callExpr)('useState', [initFn]);
+    // @ts-ignore - typeParameters on CallExpression for TS
+    useStateCall.typeParameters = t.tsTypeParameterInstantiation([
+        (0, hooks_ast_1.typeRef)('ConnectionState'),
+    ]);
+    hookBody.push(t.variableDeclaration('const', [
+        t.variableDeclarator(t.arrayPattern([t.identifier('state'), t.identifier('setState')]), useStateCall),
+    ]));
+    // useEffect
+    const effectBody = [];
+    effectBody.push((0, hooks_ast_1.constDecl)('client', (0, hooks_ast_1.callExpr)('getClient', [])));
+    // if (!client.isRealtimeEnabled) return;
+    effectBody.push(t.ifStatement(t.unaryExpression('!', t.memberExpression(t.identifier('client'), t.identifier('isRealtimeEnabled'))), t.returnStatement(null)));
+    // const unsubscribe = client.onConnectionStateChange(setState);
+    effectBody.push((0, hooks_ast_1.constDecl)('unsubscribe', (0, hooks_ast_1.callExpr)(t.memberExpression(t.identifier('client'), t.identifier('onConnectionStateChange')), [t.identifier('setState')])));
+    // return () => unsubscribe();
+    effectBody.push(t.returnStatement(t.arrowFunctionExpression([], t.callExpression(t.identifier('unsubscribe'), []))));
+    hookBody.push(t.expressionStatement((0, hooks_ast_1.callExpr)('useEffect', [
+        t.arrowFunctionExpression([], t.blockStatement(effectBody)),
+        t.arrayExpression([]),
+    ])));
+    // return state;
+    hookBody.push(t.returnStatement(t.identifier('state')));
+    // Hook declaration
+    const hookDecl = (0, hooks_ast_1.exportFunction)('useConnectionState', null, [], hookBody, (0, hooks_ast_1.typeRef)('ConnectionState'));
+    (0, hooks_ast_1.addJSDocComment)(hookDecl, [
+        'Hook to observe the WebSocket connection state.',
+        '',
+        'Returns the current connection state of the realtime WebSocket.',
+        "Returns 'disconnected' if realtime is not configured.",
+        '',
+        '@example',
+        '```tsx',
+        'const state = useConnectionState();',
+        "// state: 'disconnected' | 'connecting' | 'connected' | 'reconnecting'",
+        '```',
+    ]);
+    statements.push(hookDecl);
+    return {
+        fileName: 'useConnectionState.ts',
+        content: (0, hooks_ast_1.generateHookFileCode)('WebSocket connection state hook', statements),
+    };
+}
+/**
+ * Generate subscription hooks for all tables
+ */
+function generateAllSubscriptionHooks(tables) {
+    return tables.map((table) => generateSubscriptionHook(table));
+}