@constructive-io/graphql-codegen 2.20.1 → 2.22.0

package/README.md

@@ -1,4 +1,16 @@
-# @constructive-io/graphql-sdk
+# @constructive-io/graphql-codegen
+
+<p align="center" width="100%">
+  <img height="250" src="https://raw.githubusercontent.com/constructive-io/constructive/refs/heads/main/assets/outline-logo.svg" />
+</p>
+
+<p align="center" width="100%">
+  <a href="https://github.com/constructive-io/constructive/actions/workflows/run-tests.yaml">
+    <img height="20" src="https://github.com/constructive-io/constructive/actions/workflows/run-tests.yaml/badge.svg" />
+  </a>
+   <a href="https://github.com/constructive-io/constructive/blob/main/LICENSE"><img height="20" src="https://img.shields.io/badge/license-MIT-blue.svg"/></a>
+   <a href="https://www.npmjs.com/package/@constructive-io/graphql-codegen"><img height="20" src="https://img.shields.io/github/package-json/v/constructive-io/constructive?filename=graphql%2Fcodegen%2Fpackage.json"/></a>
+</p>
 
 CLI-based GraphQL SDK generator for PostGraphile endpoints. Generate type-safe React Query hooks or a Prisma-like ORM client from your GraphQL schema.
 
@@ -39,7 +51,7 @@ CLI-based GraphQL SDK generator for PostGraphile endpoints. Generate type-safe R
 ## Installation
 
 ```bash
-pnpm add @constructive-io/graphql-sdk
+pnpm add @constructive-io/graphql-codegen
 ```
 
 ## Quick Start
@@ -53,7 +65,7 @@ npx graphql-sdk init
 Creates a `graphql-sdk.config.ts` file:
 
 ```typescript
-import { defineConfig } from '@constructive-io/graphql-sdk';
+import { defineConfig } from '@constructive-io/graphql-codegen';
 
 export default defineConfig({
   endpoint: 'https://api.example.com/graphql',

package/cli/codegen/barrel.d.ts

@@ -15,8 +15,11 @@ export declare function generateQueriesBarrel(tables: CleanTable[]): string;
 export declare function generateMutationsBarrel(tables: CleanTable[]): string;
 /**
  * Generate the main index.ts barrel file
+ *
+ * @param tables - The tables to include in the SDK
+ * @param hasSchemaTypes - Whether schema-types.ts was generated
  */
-export declare function generateMainBarrel(tables: CleanTable[]): string;
+export declare function generateMainBarrel(tables: CleanTable[], hasSchemaTypes?: boolean): string;
 /**
  * Generate queries barrel including custom query operations
  */

package/cli/codegen/barrel.js

@@ -12,10 +12,7 @@ const type_resolver_1 = require("./type-resolver");
  * Generate the queries/index.ts barrel file
  */
 function generateQueriesBarrel(tables) {
-    const lines = [
-        (0, ts_ast_1.createFileHeader)('Query hooks barrel export'),
-        '',
-    ];
+    const lines = [(0, ts_ast_1.createFileHeader)('Query hooks barrel export'), ''];
     // Export all query hooks
     for (const table of tables) {
         const listHookName = (0, utils_1.getListQueryHookName)(table);
@@ -51,31 +48,40 @@ function generateMutationsBarrel(tables) {
 }
 /**
  * Generate the main index.ts barrel file
+ *
+ * @param tables - The tables to include in the SDK
+ * @param hasSchemaTypes - Whether schema-types.ts was generated
  */
-function generateMainBarrel(tables) {
+function generateMainBarrel(tables, hasSchemaTypes = false) {
     const tableNames = tables.map((t) => t.name).join(', ');
+    const schemaTypesExport = hasSchemaTypes
+        ? `
+// Schema types (input, payload, enum types)
+export * from './schema-types';
+`
+        : '';
     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();
@@ -89,7 +95,7 @@ export * from './client';
 
 // Entity and filter types
 export * from './types';
-
+${schemaTypesExport}
 // Query hooks
 export * from './queries';
 

package/cli/codegen/client.js

@@ -56,6 +56,39 @@ export function getConfig(): GraphQLClientConfig {
   return globalConfig;
 }
 
+/**
+ * Set a single header value
+ * Useful for updating Authorization after login
+ *
+ * @example
+ * \`\`\`ts
+ * setHeader('Authorization', 'Bearer <new-token>');
+ * \`\`\`
+ */
+export function setHeader(key: string, value: string): void {
+  const config = getConfig();
+  globalConfig = {
+    ...config,
+    headers: { ...config.headers, [key]: value },
+  };
+}
+
+/**
+ * Merge multiple headers into the current configuration
+ *
+ * @example
+ * \`\`\`ts
+ * setHeaders({ Authorization: 'Bearer <token>', 'X-Custom': 'value' });
+ * \`\`\`
+ */
+export function setHeaders(headers: Record<string, string>): void {
+  const config = getConfig();
+  globalConfig = {
+    ...config,
+    headers: { ...config.headers, ...headers },
+  };
+}
+
 // ============================================================================
 // Error handling
 // ============================================================================

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

@@ -21,18 +21,28 @@ 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>;
 }
 /**
  * Generate a custom mutation hook file
+ * When reactQueryEnabled is false, returns null since mutations require React Query
  */
-export declare function generateCustomMutationHook(options: GenerateCustomMutationHookOptions): GeneratedCustomMutationFile;
+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>;
 }
 /**
  * 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[];

package/cli/codegen/custom-mutations.js

@@ -7,9 +7,14 @@ const schema_gql_ast_1 = require("./schema-gql-ast");
 const type_resolver_1 = require("./type-resolver");
 /**
  * Generate a custom mutation hook file
+ * When reactQueryEnabled is false, returns null since mutations require React Query
  */
 function generateCustomMutationHook(options) {
-    const { operation } = options;
+    const { operation, reactQueryEnabled = true } = options;
+    // Mutations require React Query - skip generation when disabled
+    if (!reactQueryEnabled) {
+        return null;
+    }
     try {
         return generateCustomMutationHookInternal(options);
     }
@@ -20,13 +25,15 @@ function generateCustomMutationHook(options) {
     }
 }
 function generateCustomMutationHookInternal(options) {
-    const { operation, typeRegistry, maxDepth = 2, skipQueryField = true } = options;
+    const { operation, typeRegistry, maxDepth = 2, skipQueryField = true, tableTypeNames } = options;
     const project = (0, ts_ast_1.createProject)();
     const hookName = (0, type_resolver_1.getOperationHookName)(operation.name, 'mutation');
     const fileName = (0, type_resolver_1.getOperationFileName)(operation.name, 'mutation');
     const variablesTypeName = (0, type_resolver_1.getOperationVariablesTypeName)(operation.name, 'mutation');
     const resultTypeName = (0, type_resolver_1.getOperationResultTypeName)(operation.name, 'mutation');
     const documentConstName = (0, type_resolver_1.getDocumentConstName)(operation.name, 'mutation');
+    // Create type tracker to collect referenced types (with table type awareness)
+    const tracker = (0, type_resolver_1.createTypeTracker)({ tableTypeNames });
     // Generate GraphQL document
     const mutationDocument = (0, schema_gql_ast_1.buildCustomMutationString)({
         operation,
@@ -37,8 +44,21 @@ function generateCustomMutationHookInternal(options) {
     const sourceFile = (0, ts_ast_1.createSourceFile)(project, fileName);
     // Add file header
     sourceFile.insertText(0, (0, ts_ast_1.createFileHeader)(`Custom mutation hook for ${operation.name}`) + '\n\n');
+    // Generate variables interface if there are arguments (with tracking)
+    let variablesProps = [];
+    if (operation.args.length > 0) {
+        variablesProps = generateVariablesProperties(operation.args, tracker);
+    }
+    // Generate result interface (with tracking)
+    const resultType = (0, type_resolver_1.typeRefToTsType)(operation.returnType, tracker);
+    const resultProps = [
+        { name: operation.name, type: resultType },
+    ];
+    // Get importable types from tracker (separated by source)
+    const schemaTypes = tracker.getImportableTypes(); // From schema-types.ts
+    const tableTypes = tracker.getTableTypes(); // From types.ts
     // Add imports
-    sourceFile.addImportDeclarations([
+    const imports = [
         (0, ts_ast_1.createImport)({
             moduleSpecifier: '@tanstack/react-query',
             namedImports: ['useMutation'],
@@ -48,21 +68,31 @@ function generateCustomMutationHookInternal(options) {
             moduleSpecifier: '../client',
             namedImports: ['execute'],
         }),
-    ]);
+    ];
+    // Add types.ts import for table entity types
+    if (tableTypes.length > 0) {
+        imports.push((0, ts_ast_1.createImport)({
+            moduleSpecifier: '../types',
+            typeOnlyNamedImports: tableTypes,
+        }));
+    }
+    // Add schema-types import for Input/Payload/Enum types
+    if (schemaTypes.length > 0) {
+        imports.push((0, ts_ast_1.createImport)({
+            moduleSpecifier: '../schema-types',
+            typeOnlyNamedImports: schemaTypes,
+        }));
+    }
+    sourceFile.addImportDeclarations(imports);
     // Add mutation document constant
     sourceFile.addVariableStatement((0, ts_ast_1.createConst)(documentConstName, '`\n' + mutationDocument + '`', {
         docs: ['GraphQL mutation document'],
     }));
-    // Generate variables interface if there are arguments
+    // Add variables interface
     if (operation.args.length > 0) {
-        const variablesProps = generateVariablesProperties(operation.args);
         sourceFile.addInterface((0, ts_ast_1.createInterface)(variablesTypeName, variablesProps));
     }
-    // Generate result interface
-    const resultType = (0, type_resolver_1.typeRefToTsType)(operation.returnType);
-    const resultProps = [
-        { name: operation.name, type: resultType },
-    ];
+    // Add result interface
     sourceFile.addInterface((0, ts_ast_1.createInterface)(resultTypeName, resultProps));
     // Generate hook function
     const hookParams = generateHookParameters(operation, variablesTypeName, resultTypeName);
@@ -86,10 +116,10 @@ function generateCustomMutationHookInternal(options) {
 /**
  * Generate interface properties from CleanArguments
  */
-function generateVariablesProperties(args) {
+function generateVariablesProperties(args, tracker) {
     return args.map((arg) => ({
         name: arg.name,
-        type: (0, type_resolver_1.typeRefToTsType)(arg.type),
+        type: (0, type_resolver_1.typeRefToTsType)(arg.type, tracker),
         optional: !(0, type_resolver_1.isTypeRequired)(arg.type),
         docs: arg.description ? [arg.description] : undefined,
     }));
@@ -135,9 +165,10 @@ function generateHookBody(operation, documentConstName, variablesTypeName, resul
 }
 /**
  * Generate all custom mutation hook files
+ * When reactQueryEnabled is false, returns empty array since mutations require React Query
  */
 function generateAllCustomMutationHooks(options) {
-    const { operations, typeRegistry, maxDepth = 2, skipQueryField = true } = options;
+    const { operations, typeRegistry, maxDepth = 2, skipQueryField = true, reactQueryEnabled = true, tableTypeNames } = options;
     return operations
         .filter((op) => op.kind === 'mutation')
         .map((operation) => generateCustomMutationHook({
@@ -145,5 +176,8 @@ function generateAllCustomMutationHooks(options) {
         typeRegistry,
         maxDepth,
         skipQueryField,
-    }));
+        reactQueryEnabled,
+        tableTypeNames,
+    }))
+        .filter((result) => result !== null);
 }

package/cli/codegen/custom-queries.d.ts

@@ -21,6 +21,10 @@ export interface GenerateCustomQueryHookOptions {
     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>;
 }
 /**
  * Generate a custom query hook file
@@ -31,6 +35,10 @@ export interface GenerateAllCustomQueryHooksOptions {
     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>;
 }
 /**
  * Generate all custom query hook files

package/cli/codegen/custom-queries.js

@@ -10,7 +10,7 @@ const utils_1 = require("./utils");
  * Generate a custom query hook file
  */
 function generateCustomQueryHook(options) {
-    const { operation, typeRegistry, maxDepth = 2, skipQueryField = true } = options;
+    const { operation, typeRegistry, maxDepth = 2, skipQueryField = true, reactQueryEnabled = true, tableTypeNames } = options;
     const project = (0, ts_ast_1.createProject)();
     const hookName = (0, type_resolver_1.getOperationHookName)(operation.name, 'query');
     const fileName = (0, type_resolver_1.getOperationFileName)(operation.name, 'query');
@@ -18,6 +18,8 @@ function generateCustomQueryHook(options) {
     const resultTypeName = (0, type_resolver_1.getOperationResultTypeName)(operation.name, 'query');
     const documentConstName = (0, type_resolver_1.getDocumentConstName)(operation.name, 'query');
     const queryKeyName = (0, type_resolver_1.getQueryKeyName)(operation.name);
+    // Create type tracker to collect referenced types (with table type awareness)
+    const tracker = (0, type_resolver_1.createTypeTracker)({ tableTypeNames });
     // Generate GraphQL document
     const queryDocument = (0, schema_gql_ast_1.buildCustomQueryString)({
         operation,
@@ -27,34 +29,61 @@ function generateCustomQueryHook(options) {
     });
     const sourceFile = (0, ts_ast_1.createSourceFile)(project, fileName);
     // Add file header
-    sourceFile.insertText(0, (0, ts_ast_1.createFileHeader)(`Custom query hook for ${operation.name}`) + '\n\n');
-    // Add imports
-    sourceFile.addImportDeclarations([
-        (0, ts_ast_1.createImport)({
+    const headerText = reactQueryEnabled
+        ? `Custom query hook for ${operation.name}`
+        : `Custom query functions for ${operation.name}`;
+    sourceFile.insertText(0, (0, ts_ast_1.createFileHeader)(headerText) + '\n\n');
+    // Generate variables interface if there are arguments (with tracking)
+    let variablesProps = [];
+    if (operation.args.length > 0) {
+        variablesProps = generateVariablesProperties(operation.args, tracker);
+    }
+    // Generate result interface (with tracking)
+    const resultType = (0, type_resolver_1.typeRefToTsType)(operation.returnType, tracker);
+    const resultProps = [
+        { name: operation.name, type: resultType },
+    ];
+    // Get importable types from tracker (separated by source)
+    const schemaTypes = tracker.getImportableTypes(); // From schema-types.ts
+    const tableTypes = tracker.getTableTypes(); // From types.ts
+    // Add imports - conditionally include React Query imports
+    const imports = [];
+    if (reactQueryEnabled) {
+        imports.push((0, ts_ast_1.createImport)({
             moduleSpecifier: '@tanstack/react-query',
             namedImports: ['useQuery'],
             typeOnlyNamedImports: ['UseQueryOptions', 'QueryClient'],
-        }),
-        (0, ts_ast_1.createImport)({
-            moduleSpecifier: '../client',
-            namedImports: ['execute'],
-            typeOnlyNamedImports: ['ExecuteOptions'],
-        }),
-    ]);
+        }));
+    }
+    imports.push((0, ts_ast_1.createImport)({
+        moduleSpecifier: '../client',
+        namedImports: ['execute'],
+        typeOnlyNamedImports: ['ExecuteOptions'],
+    }));
+    // Add types.ts import for table entity types
+    if (tableTypes.length > 0) {
+        imports.push((0, ts_ast_1.createImport)({
+            moduleSpecifier: '../types',
+            typeOnlyNamedImports: tableTypes,
+        }));
+    }
+    // Add schema-types import for Input/Payload/Enum types
+    if (schemaTypes.length > 0) {
+        imports.push((0, ts_ast_1.createImport)({
+            moduleSpecifier: '../schema-types',
+            typeOnlyNamedImports: schemaTypes,
+        }));
+    }
+    sourceFile.addImportDeclarations(imports);
     // Add query document constant
     sourceFile.addVariableStatement((0, ts_ast_1.createConst)(documentConstName, '`\n' + queryDocument + '`', {
         docs: ['GraphQL query document'],
     }));
-    // Generate variables interface if there are arguments
+    // Add variables interface
     if (operation.args.length > 0) {
-        const variablesProps = generateVariablesProperties(operation.args);
         sourceFile.addInterface((0, ts_ast_1.createInterface)(variablesTypeName, variablesProps));
     }
-    // Generate result interface
-    const resultType = (0, type_resolver_1.typeRefToTsType)(operation.returnType);
-    const resultProps = [
-        { name: operation.name, type: resultType },
-    ];
+    // Add result interface
     sourceFile.addInterface((0, ts_ast_1.createInterface)(resultTypeName, resultProps));
     // Query key factory
     if (operation.args.length > 0) {
@@ -66,17 +95,19 @@ function generateCustomQueryHook(options) {
             docs: ['Query key factory for caching'],
         }));
     }
-    // Generate hook function
-    const hookParams = generateHookParameters(operation, variablesTypeName, resultTypeName);
-    const hookBody = generateHookBody(operation, documentConstName, queryKeyName, variablesTypeName, resultTypeName);
-    const hookDoc = generateHookDoc(operation, hookName);
-    sourceFile.addFunction({
-        name: hookName,
-        isExported: true,
-        parameters: hookParams,
-        statements: hookBody,
-        docs: [{ description: hookDoc }],
-    });
+    // Generate hook function (only if React Query is enabled)
+    if (reactQueryEnabled) {
+        const hookParams = generateHookParameters(operation, variablesTypeName, resultTypeName);
+        const hookBody = generateHookBody(operation, documentConstName, queryKeyName, variablesTypeName, resultTypeName);
+        const hookDoc = generateHookDoc(operation, hookName);
+        sourceFile.addFunction({
+            name: hookName,
+            isExported: true,
+            parameters: hookParams,
+            statements: hookBody,
+            docs: [{ description: hookDoc }],
+        });
+    }
     // Add standalone functions section
     sourceFile.addStatements('\n// ============================================================================');
     sourceFile.addStatements('// Standalone Functions (non-React)');
@@ -95,20 +126,22 @@ function generateCustomQueryHook(options) {
         statements: fetchBody,
         docs: [{ description: fetchDoc }],
     });
-    // Generate prefetch function
-    const prefetchFnName = `prefetch${(0, utils_1.ucFirst)(operation.name)}Query`;
-    const prefetchParams = generatePrefetchParameters(operation, variablesTypeName);
-    const prefetchBody = generatePrefetchBody(operation, documentConstName, queryKeyName, variablesTypeName, resultTypeName);
-    const prefetchDoc = generatePrefetchDoc(operation, prefetchFnName);
-    sourceFile.addFunction({
-        name: prefetchFnName,
-        isExported: true,
-        isAsync: true,
-        parameters: prefetchParams,
-        returnType: 'Promise<void>',
-        statements: prefetchBody,
-        docs: [{ description: prefetchDoc }],
-    });
+    // Generate prefetch function (only if React Query is enabled)
+    if (reactQueryEnabled) {
+        const prefetchFnName = `prefetch${(0, utils_1.ucFirst)(operation.name)}Query`;
+        const prefetchParams = generatePrefetchParameters(operation, variablesTypeName);
+        const prefetchBody = generatePrefetchBody(operation, documentConstName, queryKeyName, variablesTypeName, resultTypeName);
+        const prefetchDoc = generatePrefetchDoc(operation, prefetchFnName);
+        sourceFile.addFunction({
+            name: prefetchFnName,
+            isExported: true,
+            isAsync: true,
+            parameters: prefetchParams,
+            returnType: 'Promise<void>',
+            statements: prefetchBody,
+            docs: [{ description: prefetchDoc }],
+        });
+    }
     return {
         fileName,
         content: (0, ts_ast_1.getFormattedOutput)(sourceFile),
@@ -121,10 +154,10 @@ function generateCustomQueryHook(options) {
 /**
  * Generate interface properties from CleanArguments
  */
-function generateVariablesProperties(args) {
+function generateVariablesProperties(args, tracker) {
     return args.map((arg) => ({
         name: arg.name,
-        type: (0, type_resolver_1.typeRefToTsType)(arg.type),
+        type: (0, type_resolver_1.typeRefToTsType)(arg.type, tracker),
         optional: !(0, type_resolver_1.isTypeRequired)(arg.type),
         docs: arg.description ? [arg.description] : undefined,
     }));
@@ -346,7 +379,7 @@ await ${fnName}(queryClient);
  * Generate all custom query hook files
  */
 function generateAllCustomQueryHooks(options) {
-    const { operations, typeRegistry, maxDepth = 2, skipQueryField = true } = options;
+    const { operations, typeRegistry, maxDepth = 2, skipQueryField = true, reactQueryEnabled = true, tableTypeNames } = options;
     return operations
         .filter((op) => op.kind === 'query')
         .map((operation) => generateCustomQueryHook({
@@ -354,5 +387,7 @@ function generateAllCustomQueryHooks(options) {
         typeRegistry,
         maxDepth,
         skipQueryField,
+        reactQueryEnabled,
+        tableTypeNames,
     }));
 }

package/cli/codegen/gql-ast.js

@@ -147,16 +147,20 @@ function buildSingleQueryAST(config) {
     const { table } = config;
     const queryName = (0, utils_1.getSingleRowQueryName)(table);
     const scalarFields = (0, utils_1.getScalarFields)(table);
-    // Variable definitions - assume UUID primary key
+    // Get primary key info dynamically from table constraints
+    const pkFields = (0, utils_1.getPrimaryKeyInfo)(table);
+    // For simplicity, use first PK field (most common case)
+    const pkField = pkFields[0];
+    // Variable definitions - use dynamic PK field name and type
     const variableDefinitions = [
         t.variableDefinition({
-            variable: t.variable({ name: 'id' }),
-            type: t.nonNullType({ type: t.namedType({ type: 'UUID' }) }),
+            variable: t.variable({ name: pkField.name }),
+            type: t.nonNullType({ type: t.namedType({ type: pkField.gqlType }) }),
         }),
     ];
-    // Query arguments
+    // Query arguments - use dynamic PK field name
     const args = [
-        t.argument({ name: 'id', value: t.variable({ name: 'id' }) }),
+        t.argument({ name: pkField.name, value: t.variable({ name: pkField.name }) }),
     ];
     // Field selections
     const fieldSelections = createFieldSelections(scalarFields);