@constructive-io/graphql-codegen 2.23.3 → 2.24.1

package/cli/codegen/utils.d.ts

@@ -171,6 +171,12 @@ export declare function getPrimaryKeyInfo(table: CleanTable): PrimaryKeyField[];
  * Get primary key field names (convenience wrapper)
  */
 export declare function getPrimaryKeyFields(table: CleanTable): string[];
+/**
+ * Check if table has a valid single-field primary key
+ * Used to determine if a single query hook can be generated
+ * Tables with composite keys return false (handled as custom queries)
+ */
+export declare function hasValidPrimaryKey(table: CleanTable): boolean;
 /**
  * Generate query key prefix for a table
  * e.g., "cars" for list queries, "car" for detail queries

package/cli/codegen/utils.js

@@ -35,6 +35,7 @@ exports.isRelationField = isRelationField;
 exports.getScalarFields = getScalarFields;
 exports.getPrimaryKeyInfo = getPrimaryKeyInfo;
 exports.getPrimaryKeyFields = getPrimaryKeyFields;
+exports.hasValidPrimaryKey = hasValidPrimaryKey;
 exports.getQueryKeyPrefix = getQueryKeyPrefix;
 exports.getGeneratedFileHeader = getGeneratedFileHeader;
 exports.indent = indent;
@@ -331,6 +332,24 @@ function getPrimaryKeyInfo(table) {
 function getPrimaryKeyFields(table) {
     return getPrimaryKeyInfo(table).map((pk) => pk.name);
 }
+/**
+ * Check if table has a valid single-field primary key
+ * Used to determine if a single query hook can be generated
+ * Tables with composite keys return false (handled as custom queries)
+ */
+function hasValidPrimaryKey(table) {
+    // Check for explicit primary key constraint with single field
+    const pk = table.constraints?.primaryKey?.[0];
+    if (pk && pk.fields.length === 1) {
+        return true;
+    }
+    // Check for 'id' field as fallback
+    const idField = table.fields.find((f) => f.name.toLowerCase() === 'id');
+    if (idField) {
+        return true;
+    }
+    return false;
+}
 // ============================================================================
 // Query key generation
 // ============================================================================

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

@@ -0,0 +1,53 @@
+/**
+ * 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;
+/**
+ * Create a call expression with TypeScript type parameters
+ *
+ * This is used to generate typed function calls like:
+ * execute<ResultType, VariablesType>(document, variables)
+ */
+export declare function createTypedCallExpression(callee: t.Expression, args: (t.Expression | t.SpreadElement)[], typeParams: t.TSType[]): t.CallExpression;

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

@@ -0,0 +1,111 @@
+/**
+ * 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;
+}
+/**
+ * Create a call expression with TypeScript type parameters
+ *
+ * This is used to generate typed function calls like:
+ * execute<ResultType, VariablesType>(document, variables)
+ */
+export function createTypedCallExpression(callee, args, typeParams) {
+    const call = t.callExpression(callee, args);
+    if (typeParams.length > 0) {
+        // @ts-ignore - Babel types support typeParameters on CallExpression for TS
+        call.typeParameters = t.tsTypeParameterInstantiation(typeParams);
+    }
+    return call;
+}

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,134 @@
-import { createFileHeader } from './ts-ast';
-import { getListQueryHookName, getSingleQueryHookName, getCreateMutationHookName, getUpdateMutationHookName, getDeleteMutationHookName, } from './utils';
+import * as t from '@babel/types';
+import { generateCode, addJSDocComment } from './babel-ast';
+import { getListQueryHookName, getSingleQueryHookName, getCreateMutationHookName, getUpdateMutationHookName, getDeleteMutationHookName, hasValidPrimaryKey, } 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}`));
+        // Only export single query hook if table has valid primary key
+        if (hasValidPrimaryKey(table)) {
+            const singleHookName = getSingleQueryHookName(table);
+            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 +137,86 @@ ${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 = [];
+    const exportedHooks = new Set();
     // 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}';`);
-    }
-    // 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}';`);
+        if (!exportedHooks.has(listHookName)) {
+            statements.push(exportAllFrom(`./${listHookName}`));
+            exportedHooks.add(listHookName);
+        }
+        // Only export single query hook if table has valid primary key
+        if (hasValidPrimaryKey(table)) {
+            const singleHookName = getSingleQueryHookName(table);
+            if (!exportedHooks.has(singleHookName)) {
+                statements.push(exportAllFrom(`./${singleHookName}`));
+                exportedHooks.add(singleHookName);
+            }
+        }
+    }
+    // Add custom query hooks (skip if already exported from table hooks)
+    for (const name of customQueryNames) {
+        const hookName = getOperationHookName(name, 'query');
+        if (!exportedHooks.has(hookName)) {
+            statements.push(exportAllFrom(`./${hookName}`));
+            exportedHooks.add(hookName);
         }
     }
-    return lines.join('\n') + '\n';
+    // 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 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 = [];
+    const exportedHooks = new Set();
     // 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}';`);
+        if (!exportedHooks.has(createHookName)) {
+            statements.push(exportAllFrom(`./${createHookName}`));
+            exportedHooks.add(createHookName);
+        }
         // Only add update/delete if they exist
         if (table.query?.update !== null) {
-            lines.push(`export * from './${updateHookName}';`);
+            const updateHookName = getUpdateMutationHookName(table);
+            if (!exportedHooks.has(updateHookName)) {
+                statements.push(exportAllFrom(`./${updateHookName}`));
+                exportedHooks.add(updateHookName);
+            }
         }
         if (table.query?.delete !== null) {
-            lines.push(`export * from './${deleteHookName}';`);
+            const deleteHookName = getDeleteMutationHookName(table);
+            if (!exportedHooks.has(deleteHookName)) {
+                statements.push(exportAllFrom(`./${deleteHookName}`));
+                exportedHooks.add(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}';`);
+    // Add custom mutation hooks (skip if already exported from table hooks)
+    for (const name of customMutationNames) {
+        const hookName = getOperationHookName(name, 'mutation');
+        if (!exportedHooks.has(hookName)) {
+            statements.push(exportAllFrom(`./${hookName}`));
+            exportedHooks.add(hookName);
         }
     }
-    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);
 }

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[];