@constructive-io/graphql-codegen 4.38.1 → 4.39.0

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

@@ -44,6 +44,17 @@ export 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.
+ */
+export 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/esm/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/esm/core/codegen/orm/client.js

@@ -87,6 +87,9 @@ export 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);
@@ -95,4 +98,17 @@ export class OrmClient {
     getEndpoint() {
         return this.adapter.getEndpoint?.() ?? '';
     }
+    getConnectionState() {
+        return 'disconnected';
+    }
+    onConnectionStateChange(listener) {
+        return () => { };
+    }
+    getActiveSubscriptionCount() {
+        return 0;
+    }
+    get isRealtimeEnabled() {
+        return false;
+    }
+    dispose() { }
 }

package/esm/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/esm/core/codegen/orm/index.js

@@ -1,5 +1,5 @@
 import { generateModelsBarrel, generateTypesBarrel } from './barrel';
-import { generateCreateClientFile, generateOrmClientFile, generateQueryBuilderFile, generateSelectTypesFile, } from './client-generator';
+import { generateCreateClientFile, generateOrmClientFile, generateQueryBuilderFile, generateRealtimeFile, generateSelectTypesFile, } from './client-generator';
 import { generateCustomMutationOpsFile, generateCustomQueryOpsFile, } from './custom-ops-generator';
 import { collectInputTypeNames, collectPayloadTypeNames, generateInputTypesFile, } from './input-types-generator';
 import { generateAllModelFiles } from './model-generator';
@@ -15,9 +15,11 @@ export 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 = generateOrmClientFile();
     files.push({ path: clientFile.fileName, content: clientFile.content });
+    const realtimeFile = generateRealtimeFile();
+    files.push({ path: realtimeFile.fileName, content: realtimeFile.content });
     const queryBuilderFile = generateQueryBuilderFile();
     files.push({
         path: queryBuilderFile.fileName,
@@ -102,6 +104,6 @@ export function generateOrm(options) {
 }
 // Re-export generators for direct use
 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/esm/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/esm/core/codegen/subscriptions.js

@@ -0,0 +1,232 @@
+/**
+ * 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
+ */
+import * as t from '@babel/types';
+import { addJSDocComment, callExpr, constDecl, createFunctionParam, createImportDeclaration, createTypeReExport, exportFunction, generateHookFileCode, objectProp, typeRef, } from './hooks-ast';
+import { getSubscriptionFieldName, getSubscriptionFileName, getSubscriptionHookName, getTableNames, lcFirst, } from './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 {
+ *   ...
+ * }
+ * ```
+ */
+export function generateSubscriptionHook(table) {
+    const { typeName, singularName } = getTableNames(table);
+    const hookName = getSubscriptionHookName(table);
+    const subscriptionFieldName = getSubscriptionFieldName(table);
+    const keysName = `${lcFirst(typeName)}Keys`;
+    const statements = [];
+    // Imports
+    statements.push(createImportDeclaration('react', ['useEffect', 'useRef', 'useCallback']));
+    statements.push(createImportDeclaration('@tanstack/react-query', ['useQueryClient']));
+    statements.push(createImportDeclaration('@tanstack/react-query', ['QueryClient'], true));
+    statements.push(createImportDeclaration('../client', ['getClient']));
+    statements.push(createImportDeclaration('../../orm/client', [
+        'SubscriptionEvent',
+        'SubscriptionFieldMeta',
+        'Unsubscribe',
+    ], true));
+    statements.push(createImportDeclaration('../../orm/input-types', [typeName], true));
+    statements.push(createImportDeclaration('../query-keys', [keysName]));
+    // Re-export SubscriptionEvent for consumer convenience
+    statements.push(createTypeReExport(['SubscriptionEvent', 'Unsubscribe'], '../../orm/client'));
+    // Subscription document constant
+    const subscriptionDoc = `subscription On${typeName}Changed {
+  ${subscriptionFieldName} {
+    event
+    ${singularName} { __typename }
+    timestamp
+  }
+}`;
+    const docDecl = 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([
+            objectProp('fieldName', t.stringLiteral(subscriptionFieldName)),
+            objectProp('tableName', t.stringLiteral(singularName)),
+            objectProp('dataFieldName', t.stringLiteral(singularName)),
+        ])),
+    ]);
+    // Add type annotation: SubscriptionFieldMeta
+    const metaId = metaDecl.declarations[0].id;
+    metaId.typeAnnotation = t.tsTypeAnnotation(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, [
+                createFunctionParam('event', typeRef('SubscriptionEvent', [typeRef(typeName)])),
+            ], t.tsTypeAnnotation(t.tsVoidKeyword()))));
+            return p;
+        })(),
+        (() => {
+            const p = t.tsPropertySignature(t.identifier('onError'), t.tsTypeAnnotation(t.tsFunctionType(null, [createFunctionParam('error', 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(constDecl('queryClient', callExpr('useQueryClient', [])));
+    // const optionsRef = useRef(options);
+    hookBody.push(constDecl('optionsRef', 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(constDecl('client', 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([
+            objectProp('onEvent', t.arrowFunctionExpression([t.identifier('event')], t.blockStatement([
+                // optionsRef.current.onEvent(event);
+                t.expressionStatement(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(callExpr(t.memberExpression(t.identifier('queryClient'), t.identifier('invalidateQueries')), [
+                    t.objectExpression([
+                        objectProp('queryKey', t.memberExpression(t.identifier(keysName), t.identifier('all'))),
+                    ]),
+                ]))),
+            ]))),
+            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(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(callExpr('useEffect', [
+        effectFn,
+        t.arrayExpression([
+            t.memberExpression(t.identifier('options'), t.identifier('enabled')),
+            t.identifier('queryClient'),
+        ]),
+    ])));
+    // Hook declaration
+    const hookParam = createFunctionParam('options', typeRef(optionsTypeName));
+    const hookDecl = exportFunction(hookName, null, [hookParam], hookBody, t.tsVoidKeyword());
+    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: getSubscriptionFileName(table),
+        content: 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.
+ */
+export function generateConnectionStateHook() {
+    const statements = [];
+    // Imports
+    statements.push(createImportDeclaration('react', ['useState', 'useEffect']));
+    statements.push(createImportDeclaration('../client', ['getClient']));
+    statements.push(createImportDeclaration('../../orm/client', ['ConnectionState'], true));
+    // Re-export ConnectionState
+    statements.push(createTypeReExport(['ConnectionState'], '../../orm/client'));
+    // Hook body
+    const hookBody = [];
+    // const [state, setState] = useState<ConnectionState>(() => getClient().getConnectionState());
+    const initFn = t.arrowFunctionExpression([], callExpr(t.memberExpression(callExpr('getClient', []), t.identifier('getConnectionState')), []));
+    const useStateCall = callExpr('useState', [initFn]);
+    // @ts-ignore - typeParameters on CallExpression for TS
+    useStateCall.typeParameters = t.tsTypeParameterInstantiation([
+        typeRef('ConnectionState'),
+    ]);
+    hookBody.push(t.variableDeclaration('const', [
+        t.variableDeclarator(t.arrayPattern([t.identifier('state'), t.identifier('setState')]), useStateCall),
+    ]));
+    // useEffect
+    const effectBody = [];
+    effectBody.push(constDecl('client', 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(constDecl('unsubscribe', 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(callExpr('useEffect', [
+        t.arrowFunctionExpression([], t.blockStatement(effectBody)),
+        t.arrayExpression([]),
+    ])));
+    // return state;
+    hookBody.push(t.returnStatement(t.identifier('state')));
+    // Hook declaration
+    const hookDecl = exportFunction('useConnectionState', null, [], hookBody, typeRef('ConnectionState'));
+    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: generateHookFileCode('WebSocket connection state hook', statements),
+    };
+}
+/**
+ * Generate subscription hooks for all tables
+ */
+export function generateAllSubscriptionHooks(tables) {
+    return tables.map((table) => generateSubscriptionHook(table));
+}

package/esm/core/codegen/utils.d.ts

@@ -65,6 +65,21 @@ export declare function getUpdateMutationFileName(table: Table): string;
  * Generate file name for delete mutation hook
  */
 export declare function getDeleteMutationFileName(table: Table): string;
+/**
+ * Generate hook function name for subscription
+ * e.g., "useContactSubscription"
+ */
+export declare function getSubscriptionHookName(table: Table): string;
+/**
+ * Generate file name for subscription hook
+ * e.g., "useContactSubscription.ts"
+ */
+export declare function getSubscriptionFileName(table: Table): string;
+/**
+ * Generate the GraphQL subscription field name
+ * e.g., "onContactChanged"
+ */
+export declare function getSubscriptionFieldName(table: Table): string;
 /**
  * Get the GraphQL query name for fetching all rows
  * Uses inflection from introspection, falls back to convention

package/esm/core/codegen/utils.js

@@ -94,6 +94,29 @@ export function getUpdateMutationFileName(table) {
 export function getDeleteMutationFileName(table) {
     return `${getDeleteMutationHookName(table)}.ts`;
 }
+/**
+ * Generate hook function name for subscription
+ * e.g., "useContactSubscription"
+ */
+export function getSubscriptionHookName(table) {
+    const { singularName } = getTableNames(table);
+    return `use${ucFirst(singularName)}Subscription`;
+}
+/**
+ * Generate file name for subscription hook
+ * e.g., "useContactSubscription.ts"
+ */
+export function getSubscriptionFileName(table) {
+    return `${getSubscriptionHookName(table)}.ts`;
+}
+/**
+ * Generate the GraphQL subscription field name
+ * e.g., "onContactChanged"
+ */
+export function getSubscriptionFieldName(table) {
+    const { singularName } = getTableNames(table);
+    return `on${ucFirst(singularName)}Changed`;
+}
 // ============================================================================
 // GraphQL operation names
 // ============================================================================

package/esm/types/schema.d.ts

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constructive-io/graphql-codegen",
-  "version": "4.38.1",
+  "version": "4.39.0",
   "description": "GraphQL SDK generator for Constructive databases with React Query hooks",
   "keywords": [
     "graphql",
@@ -56,7 +56,7 @@
     "@0no-co/graphql.web": "^1.1.2",
     "@babel/generator": "^7.29.1",
     "@babel/types": "^7.29.0",
-    "@constructive-io/graphql-query": "^3.21.1",
+    "@constructive-io/graphql-query": "^3.22.0",
     "@constructive-io/graphql-types": "^3.8.0",
     "@inquirerer/utils": "^3.3.5",
     "@pgpmjs/core": "^6.16.1",
@@ -64,7 +64,7 @@
     "deepmerge": "^4.3.1",
     "find-and-require-package-json": "^0.9.1",
     "gql-ast": "^3.8.0",
-    "graphile-schema": "^1.18.4",
+    "graphile-schema": "^1.18.6",
     "graphql": "16.13.0",
     "inflekt": "^0.7.1",
     "inquirerer": "^4.7.0",
@@ -100,5 +100,5 @@
     "tsx": "^4.21.0",
     "typescript": "^5.9.3"
   },
-  "gitHead": "0fcb26c8f3379de5c2bf486e7ad78bb61a76e497"
+  "gitHead": "90016935b53d6fb84e0b83879377f0c2eb9abce6"
 }

package/types/schema.d.ts

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