@constructive-io/graphql-codegen 2.32.0 → 3.0.1

package/esm/core/config/resolver.js

@@ -0,0 +1,100 @@
+import { mergeConfig, getConfigOptions } from '../../types/config';
+import { findConfigFile, loadConfigFile } from './loader';
+/**
+ * Load and resolve configuration from file and/or options
+ *
+ * This is the main entry point for configuration loading. It:
+ * 1. Finds and loads the config file (if any)
+ * 2. Applies CLI option overrides
+ * 3. Returns fully resolved configuration ready for use
+ */
+export async function loadAndResolveConfig(options) {
+    // Destructure CLI-only fields, rest is config overrides
+    const { config: configPath, ...overrides } = options;
+    // Validate that at most one source is specified
+    const sources = [
+        overrides.endpoint,
+        overrides.schemaFile,
+        overrides.db,
+    ].filter(Boolean);
+    if (sources.length > 1) {
+        return {
+            success: false,
+            error: 'Multiple sources specified. Use only one of: endpoint, schemaFile, or db.',
+        };
+    }
+    // Find config file
+    let resolvedConfigPath = configPath;
+    if (!resolvedConfigPath) {
+        resolvedConfigPath = findConfigFile() ?? undefined;
+    }
+    let baseConfig = {};
+    if (resolvedConfigPath) {
+        const loadResult = await loadConfigFile(resolvedConfigPath);
+        if (!loadResult.success) {
+            return { success: false, error: loadResult.error };
+        }
+        baseConfig = loadResult.config;
+    }
+    const mergedConfig = mergeConfig(baseConfig, overrides);
+    // Check if we have a source (endpoint, schemaFile, or db)
+    const hasSource = mergedConfig.endpoint ||
+        mergedConfig.schemaFile ||
+        mergedConfig.db;
+    if (!hasSource) {
+        return {
+            success: false,
+            error: 'No source specified. Use --endpoint, --schema-file, or --db, or create a config file with "graphql-codegen init".',
+        };
+    }
+    return {
+        success: true,
+        config: getConfigOptions(mergedConfig),
+    };
+}
+/**
+ * Build watch configuration from options
+ *
+ * Used by watch mode to resolve configuration with watch-specific overrides.
+ */
+export async function loadWatchConfig(options) {
+    let configPath = options.config;
+    if (!configPath) {
+        configPath = findConfigFile() ?? undefined;
+    }
+    let baseConfig = {};
+    if (configPath) {
+        const loadResult = await loadConfigFile(configPath);
+        if (!loadResult.success) {
+            console.error('x', loadResult.error);
+            return null;
+        }
+        baseConfig = loadResult.config;
+    }
+    const sourceOverrides = {};
+    if (options.endpoint) {
+        sourceOverrides.endpoint = options.endpoint;
+        sourceOverrides.schemaFile = undefined;
+    }
+    const watchOverrides = {
+        watch: {
+            ...(options.pollInterval !== undefined && {
+                pollInterval: options.pollInterval,
+            }),
+            ...(options.debounce !== undefined && { debounce: options.debounce }),
+            ...(options.touch !== undefined && { touchFile: options.touch }),
+            ...(options.clear !== undefined && { clearScreen: options.clear }),
+        },
+    };
+    let mergedConfig = mergeConfig(baseConfig, sourceOverrides);
+    mergedConfig = mergeConfig(mergedConfig, watchOverrides);
+    if (!mergedConfig.endpoint) {
+        console.error('x No endpoint specified. Watch mode only supports live endpoints.');
+        return null;
+    }
+    if (mergedConfig.schemaFile) {
+        console.error('x Watch mode is only supported with an endpoint, not schemaFile.');
+        return null;
+    }
+    return getConfigOptions(mergedConfig);
+}

package/esm/core/database/index.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Database schema utilities
+ *
+ * Provides functions for building GraphQL schemas directly from PostgreSQL databases.
+ */
+export interface BuildSchemaFromDatabaseOptions {
+    /** Database name */
+    database: string;
+    /** PostgreSQL schemas to include */
+    schemas: string[];
+    /** Output directory for the schema file */
+    outDir: string;
+    /** Optional filename (default: schema.graphql) */
+    filename?: string;
+}
+export interface BuildSchemaFromDatabaseResult {
+    /** Path to the generated schema file */
+    schemaPath: string;
+    /** The SDL content */
+    sdl: string;
+}
+/**
+ * Build a GraphQL schema from a PostgreSQL database and write it to a file.
+ *
+ * This function introspects the database using PostGraphile and generates
+ * a GraphQL SDL file that can be used for code generation.
+ *
+ * @param options - Configuration options
+ * @returns The path to the generated schema file and the SDL content
+ */
+export declare function buildSchemaFromDatabase(options: BuildSchemaFromDatabaseOptions): Promise<BuildSchemaFromDatabaseResult>;
+/**
+ * Build a GraphQL schema SDL string from a PostgreSQL database without writing to file.
+ *
+ * This is a convenience wrapper around buildSchemaSDL from graphql-server.
+ *
+ * @param options - Configuration options
+ * @returns The SDL content as a string
+ */
+export declare function buildSchemaSDLFromDatabase(options: {
+    database: string;
+    schemas: string[];
+}): Promise<string>;

package/esm/core/database/index.js

@@ -0,0 +1,48 @@
+/**
+ * Database schema utilities
+ *
+ * Provides functions for building GraphQL schemas directly from PostgreSQL databases.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { buildSchemaSDL } from '@constructive-io/graphql-server';
+/**
+ * Build a GraphQL schema from a PostgreSQL database and write it to a file.
+ *
+ * This function introspects the database using PostGraphile and generates
+ * a GraphQL SDL file that can be used for code generation.
+ *
+ * @param options - Configuration options
+ * @returns The path to the generated schema file and the SDL content
+ */
+export async function buildSchemaFromDatabase(options) {
+    const { database, schemas, outDir, filename = 'schema.graphql' } = options;
+    // Ensure output directory exists
+    await fs.promises.mkdir(outDir, { recursive: true });
+    // Build schema SDL from database
+    const sdl = await buildSchemaSDL({
+        database,
+        schemas,
+        graphile: { pgSettings: async () => ({ role: 'administrator' }) },
+    });
+    // Write schema to file
+    const schemaPath = path.join(outDir, filename);
+    await fs.promises.writeFile(schemaPath, sdl, 'utf-8');
+    return { schemaPath, sdl };
+}
+/**
+ * Build a GraphQL schema SDL string from a PostgreSQL database without writing to file.
+ *
+ * This is a convenience wrapper around buildSchemaSDL from graphql-server.
+ *
+ * @param options - Configuration options
+ * @returns The SDL content as a string
+ */
+export async function buildSchemaSDLFromDatabase(options) {
+    const { database, schemas } = options;
+    return buildSchemaSDL({
+        database,
+        schemas,
+        graphile: { pgSettings: async () => ({ role: 'administrator' }) },
+    });
+}

package/esm/core/generate.d.ts

@@ -0,0 +1,22 @@
+import type { GraphQLSDKConfigTarget } from '../types/config';
+export interface GenerateOptions extends GraphQLSDKConfigTarget {
+    authorization?: string;
+    verbose?: boolean;
+    dryRun?: boolean;
+    skipCustomOperations?: boolean;
+}
+export interface GenerateResult {
+    success: boolean;
+    message: string;
+    output?: string;
+    tables?: string[];
+    filesWritten?: string[];
+    errors?: string[];
+}
+/**
+ * Main generate function - takes a single config and generates code
+ *
+ * This is the primary entry point for programmatic usage.
+ * For multiple configs, call this function in a loop.
+ */
+export declare function generate(options?: GenerateOptions): Promise<GenerateResult>;

package/esm/core/generate.js

@@ -0,0 +1,186 @@
+/**
+ * Main generate function - orchestrates the entire codegen pipeline
+ *
+ * This is the primary entry point for programmatic usage.
+ * The CLI is a thin wrapper around this function.
+ */
+import path from 'path';
+import { createSchemaSource, validateSourceOptions } from './introspect';
+import { runCodegenPipeline, validateTablesFound } from './pipeline';
+import { generate as generateReactQueryFiles } from './codegen';
+import { generateOrm as generateOrmFiles } from './codegen/orm';
+import { generateSharedTypes } from './codegen/shared';
+import { writeGeneratedFiles } from './output';
+import { getConfigOptions } from '../types/config';
+/**
+ * Main generate function - takes a single config and generates code
+ *
+ * This is the primary entry point for programmatic usage.
+ * For multiple configs, call this function in a loop.
+ */
+export async function generate(options = {}) {
+    // Apply defaults to get resolved config
+    const config = getConfigOptions(options);
+    const outputRoot = config.output;
+    // Determine which generators to run
+    const runReactQuery = config.reactQuery ?? false;
+    const runOrm = config.orm ?? false;
+    if (!runReactQuery && !runOrm) {
+        return {
+            success: false,
+            message: 'No generators enabled. Use reactQuery: true or orm: true in your config.',
+            output: outputRoot,
+        };
+    }
+    // Validate source
+    const sourceValidation = validateSourceOptions({
+        endpoint: config.endpoint || undefined,
+        schemaFile: config.schemaFile || undefined,
+        db: config.db,
+    });
+    if (!sourceValidation.valid) {
+        return {
+            success: false,
+            message: sourceValidation.error,
+            output: outputRoot,
+        };
+    }
+    const source = createSchemaSource({
+        endpoint: config.endpoint || undefined,
+        schemaFile: config.schemaFile || undefined,
+        db: config.db,
+        authorization: options.authorization || config.headers?.['Authorization'],
+        headers: config.headers,
+    });
+    // Run pipeline
+    let pipelineResult;
+    try {
+        console.log(`Fetching schema from ${source.describe()}...`);
+        pipelineResult = await runCodegenPipeline({
+            source,
+            config,
+            verbose: options.verbose,
+            skipCustomOperations: options.skipCustomOperations,
+        });
+    }
+    catch (err) {
+        return {
+            success: false,
+            message: `Failed to fetch schema: ${err instanceof Error ? err.message : 'Unknown error'}`,
+            output: outputRoot,
+        };
+    }
+    const { tables, customOperations } = pipelineResult;
+    // Validate tables
+    const tablesValidation = validateTablesFound(tables);
+    if (!tablesValidation.valid) {
+        return {
+            success: false,
+            message: tablesValidation.error,
+            output: outputRoot,
+        };
+    }
+    const allFilesWritten = [];
+    const bothEnabled = runReactQuery && runOrm;
+    // Generate shared types when both are enabled
+    if (bothEnabled) {
+        console.log('Generating shared types...');
+        const sharedResult = generateSharedTypes({
+            tables,
+            customOperations: {
+                queries: customOperations.queries,
+                mutations: customOperations.mutations,
+                typeRegistry: customOperations.typeRegistry,
+            },
+            config,
+        });
+        if (!options.dryRun) {
+            const writeResult = await writeGeneratedFiles(sharedResult.files, outputRoot, []);
+            if (!writeResult.success) {
+                return {
+                    success: false,
+                    message: `Failed to write shared types: ${writeResult.errors?.join(', ')}`,
+                    output: outputRoot,
+                    errors: writeResult.errors,
+                };
+            }
+            allFilesWritten.push(...(writeResult.filesWritten ?? []));
+        }
+    }
+    // Generate React Query hooks
+    if (runReactQuery) {
+        const hooksDir = path.join(outputRoot, 'hooks');
+        console.log('Generating React Query hooks...');
+        const { files } = generateReactQueryFiles({
+            tables,
+            customOperations: {
+                queries: customOperations.queries,
+                mutations: customOperations.mutations,
+                typeRegistry: customOperations.typeRegistry,
+            },
+            config,
+            sharedTypesPath: bothEnabled ? '..' : undefined,
+        });
+        if (!options.dryRun) {
+            const writeResult = await writeGeneratedFiles(files, hooksDir, ['queries', 'mutations']);
+            if (!writeResult.success) {
+                return {
+                    success: false,
+                    message: `Failed to write React Query hooks: ${writeResult.errors?.join(', ')}`,
+                    output: outputRoot,
+                    errors: writeResult.errors,
+                };
+            }
+            allFilesWritten.push(...(writeResult.filesWritten ?? []));
+        }
+    }
+    // Generate ORM client
+    if (runOrm) {
+        const ormDir = path.join(outputRoot, 'orm');
+        console.log('Generating ORM client...');
+        const { files } = generateOrmFiles({
+            tables,
+            customOperations: {
+                queries: customOperations.queries,
+                mutations: customOperations.mutations,
+                typeRegistry: customOperations.typeRegistry,
+            },
+            config,
+            sharedTypesPath: bothEnabled ? '..' : undefined,
+        });
+        if (!options.dryRun) {
+            const writeResult = await writeGeneratedFiles(files, ormDir, ['models', 'query', 'mutation']);
+            if (!writeResult.success) {
+                return {
+                    success: false,
+                    message: `Failed to write ORM client: ${writeResult.errors?.join(', ')}`,
+                    output: outputRoot,
+                    errors: writeResult.errors,
+                };
+            }
+            allFilesWritten.push(...(writeResult.filesWritten ?? []));
+        }
+    }
+    // Generate unified barrel when both are enabled
+    if (bothEnabled && !options.dryRun) {
+        const barrelContent = `/**
+ * Generated SDK - auto-generated, do not edit
+ * @generated by @constructive-io/graphql-codegen
+ */
+export * from './types';
+export * from './hooks';
+export * from './orm';
+`;
+        await writeGeneratedFiles([{ path: 'index.ts', content: barrelContent }], outputRoot, []);
+    }
+    const generators = [runReactQuery && 'React Query', runOrm && 'ORM'].filter(Boolean).join(' and ');
+    return {
+        success: true,
+        message: options.dryRun
+            ? `Dry run complete. Would generate ${generators} for ${tables.length} tables.`
+            : `Generated ${generators} for ${tables.length} tables. Files written to ${outputRoot}`,
+        output: outputRoot,
+        tables: tables.map((t) => t.name),
+        filesWritten: allFilesWritten,
+    };
+}

package/esm/core/index.d.ts

@@ -1,8 +1,20 @@
 /**
- * Core query building exports
+ * Core module exports
+ *
+ * This module contains all the core business logic for graphql-codegen.
+ * The CLI is a thin wrapper around these core functions.
  */
+export { generate } from './generate';
+export type { GenerateOptions, GenerateResult } from './generate';
 export * from './types';
 export * from './ast';
 export * from './custom-ast';
 export { QueryBuilder, MetaObject } from './query-builder';
 export { validateMetaObject, convertFromMetaSchema } from './meta-object';
+export * from './config';
+export * from './codegen';
+export * from './introspect';
+export * from './pipeline';
+export * from './output';
+export * from './watch';
+export * from './database';

package/esm/core/index.js

@@ -1,6 +1,11 @@
 /**
- * Core query building exports
+ * Core module exports
+ *
+ * This module contains all the core business logic for graphql-codegen.
+ * The CLI is a thin wrapper around these core functions.
  */
+// Main generate function (orchestrates the entire pipeline)
+export { generate } from './generate';
 // Types
 export * from './types';
 // AST generation
@@ -10,3 +15,17 @@ export * from './custom-ast';
 export { QueryBuilder, MetaObject } from './query-builder';
 // Meta object utilities
 export { validateMetaObject, convertFromMetaSchema } from './meta-object';
+// Configuration loading and resolution
+export * from './config';
+// Code generation
+export * from './codegen';
+// Schema introspection
+export * from './introspect';
+// Codegen pipeline
+export * from './pipeline';
+// File output
+export * from './output';
+// Watch mode
+export * from './watch';
+// Database schema utilities
+export * from './database';

package/esm/{cli → core}/introspect/fetch-schema.js

@@ -1,34 +1,80 @@
 /**
  * Fetch GraphQL schema introspection from an endpoint
  */
+import dns from 'node:dns';
+import { Agent } from 'undici';
 import { SCHEMA_INTROSPECTION_QUERY } from './schema-query';
+/**
+ * Check if a hostname is localhost or a localhost subdomain
+ */
+function isLocalhostHostname(hostname) {
+    return hostname === 'localhost' || hostname.endsWith('.localhost');
+}
+/**
+ * Create an undici Agent that resolves *.localhost to 127.0.0.1
+ * This fixes DNS resolution issues on macOS where subdomains like api.localhost
+ * don't resolve automatically (unlike browsers which handle *.localhost).
+ */
+function createLocalhostAgent() {
+    return new Agent({
+        connect: {
+            lookup(hostname, opts, cb) {
+                if (isLocalhostHostname(hostname)) {
+                    cb(null, '127.0.0.1', 4);
+                    return;
+                }
+                dns.lookup(hostname, opts, cb);
+            },
+        },
+    });
+}
+let localhostAgent = null;
+function getLocalhostAgent() {
+    if (!localhostAgent) {
+        localhostAgent = createLocalhostAgent();
+    }
+    return localhostAgent;
+}
 /**
  * Fetch the full schema introspection from a GraphQL endpoint
  */
 export async function fetchSchema(options) {
     const { endpoint, authorization, headers = {}, timeout = 30000 } = options;
+    // Parse the endpoint URL to check for localhost
+    const url = new URL(endpoint);
+    const useLocalhostAgent = isLocalhostHostname(url.hostname);
     // Build headers
     const requestHeaders = {
         'Content-Type': 'application/json',
         Accept: 'application/json',
         ...headers,
     };
+    // Set Host header for localhost subdomains to preserve routing
+    if (useLocalhostAgent && url.hostname !== 'localhost') {
+        requestHeaders['Host'] = url.hostname;
+    }
     if (authorization) {
         requestHeaders['Authorization'] = authorization;
     }
     // Create abort controller for timeout
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), timeout);
+    // Build fetch options
+    const fetchOptions = {
+        method: 'POST',
+        headers: requestHeaders,
+        body: JSON.stringify({
+            query: SCHEMA_INTROSPECTION_QUERY,
+            variables: {},
+        }),
+        signal: controller.signal,
+    };
+    // Use custom agent for localhost to fix DNS resolution on macOS
+    if (useLocalhostAgent) {
+        fetchOptions.dispatcher = getLocalhostAgent();
+    }
     try {
-        const response = await fetch(endpoint, {
-            method: 'POST',
-            headers: requestHeaders,
-            body: JSON.stringify({
-                query: SCHEMA_INTROSPECTION_QUERY,
-                variables: {},
-            }),
-            signal: controller.signal,
-        });
+        const response = await fetch(endpoint, fetchOptions);
         clearTimeout(timeoutId);
         if (!response.ok) {
             return {

package/esm/core/introspect/source/api-schemas.d.ts

@@ -0,0 +1,44 @@
+/**
+ * API Schemas Resolution
+ *
+ * Utilities for resolving PostgreSQL schema names from API names
+ * by querying the services_public.api_schemas table.
+ */
+import { Pool } from 'pg';
+/**
+ * Result of validating services schema requirements
+ */
+export interface ServicesSchemaValidation {
+    valid: boolean;
+    error?: string;
+}
+/**
+ * Validate that the required services schemas exist in the database
+ *
+ * Checks for:
+ * - services_public schema with apis and api_schemas tables
+ * - metaschema_public schema with schema table
+ *
+ * @param pool - Database connection pool
+ * @returns Validation result
+ */
+export declare function validateServicesSchemas(pool: Pool): Promise<ServicesSchemaValidation>;
+/**
+ * Resolve schema names from API names by querying services_public.api_schemas
+ *
+ * Joins services_public.apis, services_public.api_schemas, and metaschema_public.schema
+ * to get the actual PostgreSQL schema names for the given API names.
+ *
+ * @param pool - Database connection pool
+ * @param apiNames - Array of API names to resolve
+ * @returns Array of PostgreSQL schema names
+ * @throws Error if validation fails or no schemas found
+ */
+export declare function resolveApiSchemas(pool: Pool, apiNames: string[]): Promise<string[]>;
+/**
+ * Create a database pool for the given database name or connection string
+ *
+ * @param database - Database name or connection string
+ * @returns Database connection pool
+ */
+export declare function createDatabasePool(database: string): Pool;