@constructive-io/graphql-codegen 2.23.2 → 2.24.0

package/cli/commands/generate.js

@@ -195,6 +195,7 @@ async function loadConfig(options) {
         hooks: baseConfig.hooks,
         postgraphile: baseConfig.postgraphile,
         codegen: baseConfig.codegen,
+        reactQuery: baseConfig.reactQuery,
     };
     // Validate at least one source is provided
     if (!mergedConfig.endpoint && !mergedConfig.schema) {

package/cli/index.js

@@ -74,6 +74,7 @@ async function loadWatchConfig(options) {
         postgraphile: baseConfig.postgraphile,
         codegen: baseConfig.codegen,
         orm: baseConfig.orm,
+        reactQuery: baseConfig.reactQuery,
         watch: {
             ...baseConfig.watch,
             // CLI options override config

package/esm/cli/codegen/babel-ast.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Babel AST utilities for code generation
+ *
+ * Provides minimal helper functions for building TypeScript AST nodes.
+ * Use raw t.* calls for most operations - only helpers that provide
+ * real value beyond simple wrapping are included here.
+ */
+import generate from '@babel/generator';
+import * as t from '@babel/types';
+export { t, generate };
+/**
+ * Generate code from an array of statements
+ */
+export declare function generateCode(statements: t.Statement[]): string;
+/**
+ * Create a block comment
+ */
+export declare const commentBlock: (value: string) => t.CommentBlock;
+/**
+ * Create a line comment
+ */
+export declare const commentLine: (value: string) => t.CommentLine;
+/**
+ * Add a leading JSDoc comment to a node
+ */
+export declare function addJSDocComment<T extends t.Node>(node: T, lines: string[]): T;
+/**
+ * Add a leading single-line comment to a node
+ */
+export declare function addLineComment<T extends t.Node>(node: T, text: string): T;
+/**
+ * Create an 'as const' assertion - common pattern worth abstracting
+ */
+export declare function asConst(expression: t.Expression): t.TSAsExpression;
+/**
+ * Create an array expression with 'as const' - very common pattern
+ */
+export declare function constArray(elements: (t.Expression | t.SpreadElement)[]): t.TSAsExpression;
+/**
+ * Create a typed parameter - saves boilerplate for type annotations
+ */
+export declare function typedParam(name: string, typeAnnotation: t.TSType, optional?: boolean): t.Identifier;
+/**
+ * Create keyof typeof expression - complex nested type operators
+ */
+export declare function keyofTypeof(name: string): t.TSTypeOperator;

package/esm/cli/codegen/babel-ast.js

@@ -0,0 +1,97 @@
+/**
+ * Babel AST utilities for code generation
+ *
+ * Provides minimal helper functions for building TypeScript AST nodes.
+ * Use raw t.* calls for most operations - only helpers that provide
+ * real value beyond simple wrapping are included here.
+ */
+import generate from '@babel/generator';
+import * as t from '@babel/types';
+// Re-export for convenience
+export { t, generate };
+/**
+ * Generate code from an array of statements
+ */
+export function generateCode(statements) {
+    const program = t.program(statements);
+    // @ts-ignore - Babel types mismatch
+    return generate(program).code;
+}
+/**
+ * Create a block comment
+ */
+export const commentBlock = (value) => {
+    return {
+        type: 'CommentBlock',
+        value,
+        start: null,
+        end: null,
+        loc: null,
+    };
+};
+/**
+ * Create a line comment
+ */
+export const commentLine = (value) => {
+    return {
+        type: 'CommentLine',
+        value,
+        start: null,
+        end: null,
+        loc: null,
+    };
+};
+/**
+ * Add a leading JSDoc comment to a node
+ */
+export function addJSDocComment(node, lines) {
+    const commentText = lines.length === 1
+        ? `* ${lines[0]} `
+        : `*\n${lines.map(line => ` * ${line}`).join('\n')}\n `;
+    if (!node.leadingComments) {
+        node.leadingComments = [];
+    }
+    node.leadingComments.push(commentBlock(commentText));
+    return node;
+}
+/**
+ * Add a leading single-line comment to a node
+ */
+export function addLineComment(node, text) {
+    if (!node.leadingComments) {
+        node.leadingComments = [];
+    }
+    node.leadingComments.push(commentLine(` ${text}`));
+    return node;
+}
+/**
+ * Create an 'as const' assertion - common pattern worth abstracting
+ */
+export function asConst(expression) {
+    return t.tsAsExpression(expression, t.tsTypeReference(t.identifier('const')));
+}
+/**
+ * Create an array expression with 'as const' - very common pattern
+ */
+export function constArray(elements) {
+    return asConst(t.arrayExpression(elements));
+}
+/**
+ * Create a typed parameter - saves boilerplate for type annotations
+ */
+export function typedParam(name, typeAnnotation, optional = false) {
+    const param = t.identifier(name);
+    param.typeAnnotation = t.tsTypeAnnotation(typeAnnotation);
+    param.optional = optional;
+    return param;
+}
+/**
+ * Create keyof typeof expression - complex nested type operators
+ */
+export function keyofTypeof(name) {
+    const typeofOp = t.tsTypeOperator(t.tsTypeReference(t.identifier(name)));
+    typeofOp.operator = 'typeof';
+    const keyofOp = t.tsTypeOperator(typeofOp);
+    keyofOp.operator = 'keyof';
+    return keyofOp;
+}

package/esm/cli/codegen/barrel.d.ts

@@ -1,8 +1,7 @@
 /**
  * Barrel file generators - creates index.ts files for exports
  *
- * Using simple string generation for barrel files since they're straightforward
- * and ts-morph has issues with insertText + addStatements combination.
+ * Using Babel AST for generating barrel (index.ts) files with re-exports.
  */
 import type { CleanTable } from '../../types/schema';
 /**
@@ -22,6 +21,12 @@ export declare function generateMutationsBarrel(tables: CleanTable[]): string;
 export interface MainBarrelOptions {
     hasSchemaTypes?: boolean;
     hasMutations?: boolean;
+    /** Whether query-keys.ts was generated */
+    hasQueryKeys?: boolean;
+    /** Whether mutation-keys.ts was generated */
+    hasMutationKeys?: boolean;
+    /** Whether invalidation.ts was generated */
+    hasInvalidation?: boolean;
 }
 export declare function generateMainBarrel(tables: CleanTable[], options?: MainBarrelOptions | boolean): string;
 /**

package/esm/cli/codegen/barrel.js

@@ -1,102 +1,131 @@
-import { createFileHeader } from './ts-ast';
+import * as t from '@babel/types';
+import { generateCode, addJSDocComment } from './babel-ast';
 import { getListQueryHookName, getSingleQueryHookName, getCreateMutationHookName, getUpdateMutationHookName, getDeleteMutationHookName, } from './utils';
 import { getOperationHookName } from './type-resolver';
+/**
+ * Helper to create export * from './module' statement
+ */
+function exportAllFrom(modulePath) {
+    return t.exportAllDeclaration(t.stringLiteral(modulePath));
+}
 /**
  * Generate the queries/index.ts barrel file
  */
 export function generateQueriesBarrel(tables) {
-    const lines = [createFileHeader('Query hooks barrel export'), ''];
+    const statements = [];
     // Export all query hooks
     for (const table of tables) {
         const listHookName = getListQueryHookName(table);
         const singleHookName = getSingleQueryHookName(table);
-        lines.push(`export * from './${listHookName}';`);
-        lines.push(`export * from './${singleHookName}';`);
+        statements.push(exportAllFrom(`./${listHookName}`));
+        statements.push(exportAllFrom(`./${singleHookName}`));
+    }
+    // Add file header as leading comment on first statement
+    if (statements.length > 0) {
+        addJSDocComment(statements[0], [
+            'Query hooks barrel export',
+            '@generated by @constructive-io/graphql-codegen',
+            'DO NOT EDIT - changes will be overwritten',
+        ]);
     }
-    return lines.join('\n') + '\n';
+    return generateCode(statements);
 }
 /**
  * Generate the mutations/index.ts barrel file
  */
 export function generateMutationsBarrel(tables) {
-    const lines = [
-        createFileHeader('Mutation hooks barrel export'),
-        '',
-    ];
+    const statements = [];
     // Export all mutation hooks
     for (const table of tables) {
         const createHookName = getCreateMutationHookName(table);
         const updateHookName = getUpdateMutationHookName(table);
         const deleteHookName = getDeleteMutationHookName(table);
-        lines.push(`export * from './${createHookName}';`);
+        statements.push(exportAllFrom(`./${createHookName}`));
         // Only add update/delete if they exist
         if (table.query?.update !== null) {
-            lines.push(`export * from './${updateHookName}';`);
+            statements.push(exportAllFrom(`./${updateHookName}`));
         }
         if (table.query?.delete !== null) {
-            lines.push(`export * from './${deleteHookName}';`);
+            statements.push(exportAllFrom(`./${deleteHookName}`));
         }
     }
-    return lines.join('\n') + '\n';
+    // Add file header as leading comment on first statement
+    if (statements.length > 0) {
+        addJSDocComment(statements[0], [
+            'Mutation hooks barrel export',
+            '@generated by @constructive-io/graphql-codegen',
+            'DO NOT EDIT - changes will be overwritten',
+        ]);
+    }
+    return generateCode(statements);
 }
 export function generateMainBarrel(tables, options = {}) {
     // Support legacy signature where second arg was just hasSchemaTypes boolean
     const opts = typeof options === 'boolean'
         ? { hasSchemaTypes: options, hasMutations: true }
         : options;
-    const { hasSchemaTypes = false, hasMutations = true } = opts;
-    const tableNames = tables.map((t) => t.name).join(', ');
-    const schemaTypesExport = hasSchemaTypes
-        ? `
-// Schema types (input, payload, enum types)
-export * from './schema-types';
-`
-        : '';
-    const mutationsExport = hasMutations
-        ? `
-// Mutation hooks
-export * from './mutations';
-`
-        : '';
-    return `/**
- * Auto-generated GraphQL SDK
- * @generated by @constructive-io/graphql-codegen
- *
- * Tables: ${tableNames}
- *
- * Usage:
- *
- * 1. Configure the client:
- * \`\`\`ts
- * import { configure } from './generated';
- *
- * configure({
- *   endpoint: 'https://api.example.com/graphql',
- *   headers: { Authorization: 'Bearer <token>' },
- * });
- * \`\`\`
- *
- * 2. Use the hooks:
- * \`\`\`tsx
- * import { useCarsQuery, useCreateCarMutation } from './generated';
- *
- * function MyComponent() {
- *   const { data, isLoading } = useCarsQuery({ first: 10 });
- *   const { mutate } = useCreateCarMutation();
- *   // ...
- * }
- * \`\`\`
- */
-
-// Client configuration
-export * from './client';
-
-// Entity and filter types
-export * from './types';
-${schemaTypesExport}
-// Query hooks
-export * from './queries';
-${mutationsExport}`;
+    const { hasSchemaTypes = false, hasMutations = true, hasQueryKeys = false, hasMutationKeys = false, hasInvalidation = false, } = opts;
+    const tableNames = tables.map((tbl) => tbl.name).join(', ');
+    const statements = [];
+    // Client configuration
+    statements.push(exportAllFrom('./client'));
+    // Entity and filter types
+    statements.push(exportAllFrom('./types'));
+    // Schema types (input, payload, enum types)
+    if (hasSchemaTypes) {
+        statements.push(exportAllFrom('./schema-types'));
+    }
+    // Centralized query keys (for cache management)
+    if (hasQueryKeys) {
+        statements.push(exportAllFrom('./query-keys'));
+    }
+    // Centralized mutation keys (for tracking in-flight mutations)
+    if (hasMutationKeys) {
+        statements.push(exportAllFrom('./mutation-keys'));
+    }
+    // Cache invalidation helpers
+    if (hasInvalidation) {
+        statements.push(exportAllFrom('./invalidation'));
+    }
+    // Query hooks
+    statements.push(exportAllFrom('./queries'));
+    // Mutation hooks
+    if (hasMutations) {
+        statements.push(exportAllFrom('./mutations'));
+    }
+    // Add file header as leading comment on first statement
+    if (statements.length > 0) {
+        addJSDocComment(statements[0], [
+            'Auto-generated GraphQL SDK',
+            '@generated by @constructive-io/graphql-codegen',
+            '',
+            `Tables: ${tableNames}`,
+            '',
+            'Usage:',
+            '',
+            '1. Configure the client:',
+            '```ts',
+            "import { configure } from './generated';",
+            '',
+            'configure({',
+            "  endpoint: 'https://api.example.com/graphql',",
+            "  headers: { Authorization: 'Bearer <token>' },",
+            '});',
+            '```',
+            '',
+            '2. Use the hooks:',
+            '```tsx',
+            "import { useCarsQuery, useCreateCarMutation } from './generated';",
+            '',
+            'function MyComponent() {',
+            '  const { data, isLoading } = useCarsQuery({ first: 10 });',
+            '  const { mutate } = useCreateCarMutation();',
+            '  // ...',
+            '}',
+            '```',
+        ]);
+    }
+    return generateCode(statements);
 }
 // ============================================================================
 // Custom operation barrels (includes both table and custom hooks)
@@ -105,60 +134,60 @@ ${mutationsExport}`;
  * Generate queries barrel including custom query operations
  */
 export function generateCustomQueriesBarrel(tables, customQueryNames) {
-    const lines = [
-        createFileHeader('Query hooks barrel export'),
-        '',
-        '// Table-based query hooks',
-    ];
+    const statements = [];
     // Export all table query hooks
     for (const table of tables) {
         const listHookName = getListQueryHookName(table);
         const singleHookName = getSingleQueryHookName(table);
-        lines.push(`export * from './${listHookName}';`);
-        lines.push(`export * from './${singleHookName}';`);
+        statements.push(exportAllFrom(`./${listHookName}`));
+        statements.push(exportAllFrom(`./${singleHookName}`));
     }
     // Add custom query hooks
-    if (customQueryNames.length > 0) {
-        lines.push('');
-        lines.push('// Custom query hooks');
-        for (const name of customQueryNames) {
-            const hookName = getOperationHookName(name, 'query');
-            lines.push(`export * from './${hookName}';`);
-        }
+    for (const name of customQueryNames) {
+        const hookName = getOperationHookName(name, 'query');
+        statements.push(exportAllFrom(`./${hookName}`));
+    }
+    // Add file header as leading comment on first statement
+    if (statements.length > 0) {
+        addJSDocComment(statements[0], [
+            'Query hooks barrel export',
+            '@generated by @constructive-io/graphql-codegen',
+            'DO NOT EDIT - changes will be overwritten',
+        ]);
     }
-    return lines.join('\n') + '\n';
+    return generateCode(statements);
 }
 /**
  * Generate mutations barrel including custom mutation operations
  */
 export function generateCustomMutationsBarrel(tables, customMutationNames) {
-    const lines = [
-        createFileHeader('Mutation hooks barrel export'),
-        '',
-        '// Table-based mutation hooks',
-    ];
+    const statements = [];
     // Export all table mutation hooks
     for (const table of tables) {
         const createHookName = getCreateMutationHookName(table);
         const updateHookName = getUpdateMutationHookName(table);
         const deleteHookName = getDeleteMutationHookName(table);
-        lines.push(`export * from './${createHookName}';`);
+        statements.push(exportAllFrom(`./${createHookName}`));
         // Only add update/delete if they exist
         if (table.query?.update !== null) {
-            lines.push(`export * from './${updateHookName}';`);
+            statements.push(exportAllFrom(`./${updateHookName}`));
         }
         if (table.query?.delete !== null) {
-            lines.push(`export * from './${deleteHookName}';`);
+            statements.push(exportAllFrom(`./${deleteHookName}`));
         }
     }
     // Add custom mutation hooks
-    if (customMutationNames.length > 0) {
-        lines.push('');
-        lines.push('// Custom mutation hooks');
-        for (const name of customMutationNames) {
-            const hookName = getOperationHookName(name, 'mutation');
-            lines.push(`export * from './${hookName}';`);
-        }
+    for (const name of customMutationNames) {
+        const hookName = getOperationHookName(name, 'mutation');
+        statements.push(exportAllFrom(`./${hookName}`));
+    }
+    // Add file header as leading comment on first statement
+    if (statements.length > 0) {
+        addJSDocComment(statements[0], [
+            'Mutation hooks barrel export',
+            '@generated by @constructive-io/graphql-codegen',
+            'DO NOT EDIT - changes will be overwritten',
+        ]);
     }
-    return lines.join('\n') + '\n';
+    return generateCode(statements);
 }

package/esm/cli/codegen/client.js

@@ -196,5 +196,66 @@ export async function executeWithErrors<TData = unknown, TVariables = Record<str
     errors: json.errors ?? null,
   };
 }
+
+// ============================================================================
+// QueryClient Factory
+// ============================================================================
+
+/**
+ * Default QueryClient configuration optimized for GraphQL
+ *
+ * These defaults provide a good balance between freshness and performance:
+ * - staleTime: 1 minute - data considered fresh, won't refetch
+ * - gcTime: 5 minutes - unused data kept in cache
+ * - refetchOnWindowFocus: false - don't refetch when tab becomes active
+ * - retry: 1 - retry failed requests once
+ */
+export const defaultQueryClientOptions = {
+  defaultOptions: {
+    queries: {
+      staleTime: 1000 * 60, // 1 minute
+      gcTime: 1000 * 60 * 5, // 5 minutes
+      refetchOnWindowFocus: false,
+      retry: 1,
+    },
+  },
+};
+
+/**
+ * QueryClient options type for createQueryClient
+ */
+export interface CreateQueryClientOptions {
+  defaultOptions?: {
+    queries?: {
+      staleTime?: number;
+      gcTime?: number;
+      refetchOnWindowFocus?: boolean;
+      retry?: number | boolean;
+      retryDelay?: number | ((attemptIndex: number) => number);
+    };
+    mutations?: {
+      retry?: number | boolean;
+      retryDelay?: number | ((attemptIndex: number) => number);
+    };
+  };
+}
+
+// Note: createQueryClient is available when using with @tanstack/react-query
+// Import QueryClient from '@tanstack/react-query' and use these options:
+//
+// import { QueryClient } from '@tanstack/react-query';
+// const queryClient = new QueryClient(defaultQueryClientOptions);
+//
+// Or merge with your own options:
+// const queryClient = new QueryClient({
+//   ...defaultQueryClientOptions,
+//   defaultOptions: {
+//     ...defaultQueryClientOptions.defaultOptions,
+//     queries: {
+//       ...defaultQueryClientOptions.defaultOptions.queries,
+//       staleTime: 30000, // Override specific options
+//     },
+//   },
+// });
 `;
 }

package/esm/cli/codegen/custom-mutations.d.ts

@@ -21,28 +21,18 @@ export interface GenerateCustomMutationHookOptions {
     typeRegistry: TypeRegistry;
     maxDepth?: number;
     skipQueryField?: boolean;
-    /** Whether to generate React Query hooks (default: true for backwards compatibility) */
     reactQueryEnabled?: boolean;
-    /** Table entity type names (for import path resolution) */
     tableTypeNames?: Set<string>;
+    useCentralizedKeys?: boolean;
 }
-/**
- * Generate a custom mutation hook file
- * When reactQueryEnabled is false, returns null since mutations require React Query
- */
 export declare function generateCustomMutationHook(options: GenerateCustomMutationHookOptions): GeneratedCustomMutationFile | null;
 export interface GenerateAllCustomMutationHooksOptions {
     operations: CleanOperation[];
     typeRegistry: TypeRegistry;
     maxDepth?: number;
     skipQueryField?: boolean;
-    /** Whether to generate React Query hooks (default: true for backwards compatibility) */
     reactQueryEnabled?: boolean;
-    /** Table entity type names (for import path resolution) */
     tableTypeNames?: Set<string>;
+    useCentralizedKeys?: boolean;
 }
-/**
- * Generate all custom mutation hook files
- * When reactQueryEnabled is false, returns empty array since mutations require React Query
- */
 export declare function generateAllCustomMutationHooks(options: GenerateAllCustomMutationHooksOptions): GeneratedCustomMutationFile[];