@constructive-io/graphql-codegen 2.32.0 → 3.0.0

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

@@ -1,37 +1,86 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.fetchSchema = fetchSchema;
 /**
  * Fetch GraphQL schema introspection from an endpoint
  */
+const node_dns_1 = __importDefault(require("node:dns"));
+const undici_1 = require("undici");
 const schema_query_1 = require("./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 undici_1.Agent({
+        connect: {
+            lookup(hostname, opts, cb) {
+                if (isLocalhostHostname(hostname)) {
+                    cb(null, '127.0.0.1', 4);
+                    return;
+                }
+                node_dns_1.default.lookup(hostname, opts, cb);
+            },
+        },
+    });
+}
+let localhostAgent = null;
+function getLocalhostAgent() {
+    if (!localhostAgent) {
+        localhostAgent = createLocalhostAgent();
+    }
+    return localhostAgent;
+}
 /**
  * Fetch the full schema introspection from a GraphQL endpoint
  */
 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_query_1.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_query_1.SCHEMA_INTROSPECTION_QUERY,
-                variables: {},
-            }),
-            signal: controller.signal,
-        });
+        const response = await fetch(endpoint, fetchOptions);
         clearTimeout(timeoutId);
         if (!response.ok) {
             return {

package/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;

package/core/introspect/source/api-schemas.js

@@ -0,0 +1,122 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateServicesSchemas = validateServicesSchemas;
+exports.resolveApiSchemas = resolveApiSchemas;
+exports.createDatabasePool = createDatabasePool;
+const pg_cache_1 = require("pg-cache");
+const pg_env_1 = require("pg-env");
+/**
+ * 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
+ */
+async function validateServicesSchemas(pool) {
+    try {
+        // Check for services_public.apis table
+        const apisCheck = await pool.query(`
+      SELECT 1 FROM information_schema.tables 
+      WHERE table_schema = 'services_public' 
+      AND table_name = 'apis'
+    `);
+        if (apisCheck.rows.length === 0) {
+            return {
+                valid: false,
+                error: 'services_public.apis table not found. The database must have the services schema deployed.',
+            };
+        }
+        // Check for services_public.api_schemas table
+        const apiSchemasCheck = await pool.query(`
+      SELECT 1 FROM information_schema.tables 
+      WHERE table_schema = 'services_public' 
+      AND table_name = 'api_schemas'
+    `);
+        if (apiSchemasCheck.rows.length === 0) {
+            return {
+                valid: false,
+                error: 'services_public.api_schemas table not found. The database must have the services schema deployed.',
+            };
+        }
+        // Check for metaschema_public.schema table
+        const metaschemaCheck = await pool.query(`
+      SELECT 1 FROM information_schema.tables 
+      WHERE table_schema = 'metaschema_public' 
+      AND table_name = 'schema'
+    `);
+        if (metaschemaCheck.rows.length === 0) {
+            return {
+                valid: false,
+                error: 'metaschema_public.schema table not found. The database must have the metaschema deployed.',
+            };
+        }
+        return { valid: true };
+    }
+    catch (err) {
+        return {
+            valid: false,
+            error: `Failed to validate services schemas: ${err instanceof Error ? err.message : 'Unknown error'}`,
+        };
+    }
+}
+/**
+ * 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
+ */
+async function resolveApiSchemas(pool, apiNames) {
+    // First validate that the required schemas exist
+    const validation = await validateServicesSchemas(pool);
+    if (!validation.valid) {
+        throw new Error(validation.error);
+    }
+    // Query to get schema names for the given API names
+    const result = await pool.query(`
+    SELECT DISTINCT ms.schema_name
+    FROM services_public.api_schemas as_tbl
+    JOIN services_public.apis api ON api.id = as_tbl.api_id
+    JOIN metaschema_public.schema ms ON ms.id = as_tbl.schema_id
+    WHERE api.name = ANY($1)
+    ORDER BY ms.schema_name
+    `, [apiNames]);
+    if (result.rows.length === 0) {
+        throw new Error(`No schemas found for API names: ${apiNames.join(', ')}. ` +
+            'Ensure the APIs exist and have schemas assigned in services_public.api_schemas.');
+    }
+    return result.rows.map((row) => row.schema_name);
+}
+/**
+ * Create a database pool for the given database name or connection string
+ *
+ * @param database - Database name or connection string
+ * @returns Database connection pool
+ */
+function createDatabasePool(database) {
+    // Check if it's a connection string or just a database name
+    const isConnectionString = database.startsWith('postgres://') || database.startsWith('postgresql://');
+    if (isConnectionString) {
+        // Parse connection string and extract database name
+        // Format: postgres://user:password@host:port/database
+        const url = new URL(database);
+        const dbName = url.pathname.slice(1); // Remove leading slash
+        return (0, pg_cache_1.getPgPool)({
+            host: url.hostname,
+            port: parseInt(url.port || '5432', 10),
+            user: url.username,
+            password: url.password,
+            database: dbName,
+        });
+    }
+    // Use environment variables for connection, just override database name
+    const config = (0, pg_env_1.getPgEnvOptions)({ database });
+    return (0, pg_cache_1.getPgPool)(config);
+}

package/core/introspect/source/database.d.ts

@@ -0,0 +1,32 @@
+import type { SchemaSource, SchemaSourceResult } from './types';
+export interface DatabaseSchemaSourceOptions {
+    /**
+     * Database name or connection string
+     * Can be a simple database name (uses PGHOST, PGPORT, PGUSER, PGPASSWORD env vars)
+     * or a full connection string (postgres://user:pass@host:port/dbname)
+     */
+    database: string;
+    /**
+     * PostgreSQL schemas to include in introspection
+     * Mutually exclusive with apiNames
+     */
+    schemas?: string[];
+    /**
+     * API names to resolve schemas from
+     * Queries services_public.api_schemas to get schema names
+     * Mutually exclusive with schemas
+     */
+    apiNames?: string[];
+}
+/**
+ * Schema source that loads from a PostgreSQL database
+ *
+ * Uses PostGraphile to introspect the database and generate a GraphQL schema.
+ * The schema is built in-memory without writing to disk.
+ */
+export declare class DatabaseSchemaSource implements SchemaSource {
+    private readonly options;
+    constructor(options: DatabaseSchemaSourceOptions);
+    fetch(): Promise<SchemaSourceResult>;
+    describe(): string;
+}

package/core/introspect/source/database.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DatabaseSchemaSource = void 0;
+/**
+ * Database Schema Source
+ *
+ * Loads GraphQL schema directly from a PostgreSQL database using PostGraphile
+ * introspection and converts it to introspection format.
+ */
+const graphql_1 = require("graphql");
+const types_1 = require("./types");
+const database_1 = require("../../database");
+const api_schemas_1 = require("./api-schemas");
+/**
+ * Schema source that loads from a PostgreSQL database
+ *
+ * Uses PostGraphile to introspect the database and generate a GraphQL schema.
+ * The schema is built in-memory without writing to disk.
+ */
+class DatabaseSchemaSource {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async fetch() {
+        const { database, apiNames } = this.options;
+        // Resolve schemas - either from explicit schemas option or from apiNames
+        let schemas;
+        if (apiNames && apiNames.length > 0) {
+            // Validate services schemas exist at the beginning for database mode
+            const pool = (0, api_schemas_1.createDatabasePool)(database);
+            try {
+                const validation = await (0, api_schemas_1.validateServicesSchemas)(pool);
+                if (!validation.valid) {
+                    throw new types_1.SchemaSourceError(validation.error, this.describe());
+                }
+                schemas = await (0, api_schemas_1.resolveApiSchemas)(pool, apiNames);
+            }
+            catch (err) {
+                if (err instanceof types_1.SchemaSourceError)
+                    throw err;
+                throw new types_1.SchemaSourceError(`Failed to resolve API schemas: ${err instanceof Error ? err.message : 'Unknown error'}`, this.describe(), err instanceof Error ? err : undefined);
+            }
+        }
+        else {
+            schemas = this.options.schemas ?? ['public'];
+        }
+        // Build SDL from database
+        let sdl;
+        try {
+            sdl = await (0, database_1.buildSchemaSDLFromDatabase)({
+                database,
+                schemas,
+            });
+        }
+        catch (err) {
+            throw new types_1.SchemaSourceError(`Failed to introspect database: ${err instanceof Error ? err.message : 'Unknown error'}`, this.describe(), err instanceof Error ? err : undefined);
+        }
+        // Validate non-empty
+        if (!sdl.trim()) {
+            throw new types_1.SchemaSourceError('Database introspection returned empty schema', this.describe());
+        }
+        // Parse SDL to GraphQL schema
+        let schema;
+        try {
+            schema = (0, graphql_1.buildSchema)(sdl);
+        }
+        catch (err) {
+            throw new types_1.SchemaSourceError(`Invalid GraphQL SDL from database: ${err instanceof Error ? err.message : 'Unknown error'}`, this.describe(), err instanceof Error ? err : undefined);
+        }
+        // Convert to introspection format
+        let introspectionResult;
+        try {
+            introspectionResult = (0, graphql_1.introspectionFromSchema)(schema);
+        }
+        catch (err) {
+            throw new types_1.SchemaSourceError(`Failed to generate introspection: ${err instanceof Error ? err.message : 'Unknown error'}`, this.describe(), err instanceof Error ? err : undefined);
+        }
+        // Convert graphql-js introspection result to our mutable type
+        const introspection = JSON.parse(JSON.stringify(introspectionResult));
+        return { introspection };
+    }
+    describe() {
+        const { database, schemas, apiNames } = this.options;
+        if (apiNames && apiNames.length > 0) {
+            return `database: ${database} (apiNames: ${apiNames.join(', ')})`;
+        }
+        return `database: ${database} (schemas: ${(schemas ?? ['public']).join(', ')})`;
+    }
+}
+exports.DatabaseSchemaSource = DatabaseSchemaSource;

package/core/introspect/source/index.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Schema Source Module
+ *
+ * Provides a unified interface for loading GraphQL schemas from different sources:
+ * - Live GraphQL endpoints (via introspection)
+ * - Static .graphql schema files
+ * - PostgreSQL databases (via PostGraphile introspection)
+ * - PGPM modules (via ephemeral database deployment)
+ */
+export * from './types';
+export * from './endpoint';
+export * from './file';
+export * from './database';
+export * from './pgpm-module';
+export * from './api-schemas';
+import type { SchemaSource } from './types';
+import type { DbConfig } from '../../../types/config';
+/**
+ * Options for endpoint-based schema source
+ */
+export interface EndpointSourceOptions {
+    endpoint: string;
+    authorization?: string;
+    headers?: Record<string, string>;
+    timeout?: number;
+}
+/**
+ * Options for file-based schema source
+ */
+export interface FileSourceOptions {
+    schemaFile: string;
+}
+/**
+ * Options for database-based schema source
+ */
+export interface DatabaseSourceOptions {
+    database: string;
+    schemas?: string[];
+    apiNames?: string[];
+}
+/**
+ * Options for PGPM module-based schema source (direct path)
+ */
+export interface PgpmModulePathSourceOptions {
+    pgpmModulePath: string;
+    schemas?: string[];
+    apiNames?: string[];
+    keepDb?: boolean;
+}
+/**
+ * Options for PGPM module-based schema source (workspace + module name)
+ */
+export interface PgpmWorkspaceSourceOptions {
+    pgpmWorkspacePath: string;
+    pgpmModuleName: string;
+    schemas?: string[];
+    apiNames?: string[];
+    keepDb?: boolean;
+}
+export interface CreateSchemaSourceOptions {
+    /**
+     * GraphQL endpoint URL (for live introspection)
+     */
+    endpoint?: string;
+    /**
+     * Path to GraphQL schema file (.graphql)
+     */
+    schemaFile?: string;
+    /**
+     * Database configuration for direct database introspection or PGPM module
+     */
+    db?: DbConfig;
+    /**
+     * Optional authorization header for endpoint requests
+     */
+    authorization?: string;
+    /**
+     * Optional additional headers for endpoint requests
+     */
+    headers?: Record<string, string>;
+    /**
+     * Request timeout in milliseconds (for endpoint requests)
+     */
+    timeout?: number;
+}
+/**
+ * Detect which source mode is being used based on options
+ */
+export type SourceMode = 'endpoint' | 'schemaFile' | 'database' | 'pgpm-module' | 'pgpm-workspace';
+export declare function detectSourceMode(options: CreateSchemaSourceOptions): SourceMode | null;
+/**
+ * Create a schema source based on configuration
+ *
+ * Supports five modes:
+ * - endpoint: Introspect from a live GraphQL endpoint
+ * - schemaFile: Load from a local .graphql file
+ * - database: Introspect directly from a PostgreSQL database
+ * - pgpm-module: Deploy a PGPM module to an ephemeral database and introspect
+ * - pgpm-workspace: Deploy a module from a PGPM workspace to an ephemeral database and introspect
+ *
+ * @param options - Source configuration
+ * @returns Appropriate SchemaSource implementation
+ * @throws Error if no valid source is provided
+ */
+export declare function createSchemaSource(options: CreateSchemaSourceOptions): SchemaSource;
+/**
+ * Validate that source options are valid (exactly one source specified)
+ */
+export declare function validateSourceOptions(options: CreateSchemaSourceOptions): {
+    valid: boolean;
+    error?: string;
+};

package/core/introspect/source/index.js

@@ -0,0 +1,173 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectSourceMode = detectSourceMode;
+exports.createSchemaSource = createSchemaSource;
+exports.validateSourceOptions = validateSourceOptions;
+/**
+ * Schema Source Module
+ *
+ * Provides a unified interface for loading GraphQL schemas from different sources:
+ * - Live GraphQL endpoints (via introspection)
+ * - Static .graphql schema files
+ * - PostgreSQL databases (via PostGraphile introspection)
+ * - PGPM modules (via ephemeral database deployment)
+ */
+__exportStar(require("./types"), exports);
+__exportStar(require("./endpoint"), exports);
+__exportStar(require("./file"), exports);
+__exportStar(require("./database"), exports);
+__exportStar(require("./pgpm-module"), exports);
+__exportStar(require("./api-schemas"), exports);
+const endpoint_1 = require("./endpoint");
+const file_1 = require("./file");
+const database_1 = require("./database");
+const pgpm_module_1 = require("./pgpm-module");
+function detectSourceMode(options) {
+    if (options.endpoint)
+        return 'endpoint';
+    if (options.schemaFile)
+        return 'schemaFile';
+    if (options.db) {
+        // Check for PGPM modes first
+        if (options.db.pgpm?.modulePath)
+            return 'pgpm-module';
+        if (options.db.pgpm?.workspacePath && options.db.pgpm?.moduleName)
+            return 'pgpm-workspace';
+        // Default to database mode if db is specified without pgpm
+        return 'database';
+    }
+    return null;
+}
+/**
+ * Create a schema source based on configuration
+ *
+ * Supports five modes:
+ * - endpoint: Introspect from a live GraphQL endpoint
+ * - schemaFile: Load from a local .graphql file
+ * - database: Introspect directly from a PostgreSQL database
+ * - pgpm-module: Deploy a PGPM module to an ephemeral database and introspect
+ * - pgpm-workspace: Deploy a module from a PGPM workspace to an ephemeral database and introspect
+ *
+ * @param options - Source configuration
+ * @returns Appropriate SchemaSource implementation
+ * @throws Error if no valid source is provided
+ */
+function createSchemaSource(options) {
+    const mode = detectSourceMode(options);
+    switch (mode) {
+        case 'schemaFile':
+            return new file_1.FileSchemaSource({
+                schemaPath: options.schemaFile,
+            });
+        case 'endpoint':
+            return new endpoint_1.EndpointSchemaSource({
+                endpoint: options.endpoint,
+                authorization: options.authorization,
+                headers: options.headers,
+                timeout: options.timeout,
+            });
+        case 'database':
+            // Database mode uses db.config for connection (falls back to env vars)
+            // and db.schemas or db.apiNames for schema selection
+            return new database_1.DatabaseSchemaSource({
+                database: options.db?.config?.database ?? '',
+                schemas: options.db?.schemas,
+                apiNames: options.db?.apiNames,
+            });
+        case 'pgpm-module':
+            return new pgpm_module_1.PgpmModuleSchemaSource({
+                pgpmModulePath: options.db.pgpm.modulePath,
+                schemas: options.db?.schemas,
+                apiNames: options.db?.apiNames,
+                keepDb: options.db?.keepDb,
+            });
+        case 'pgpm-workspace':
+            return new pgpm_module_1.PgpmModuleSchemaSource({
+                pgpmWorkspacePath: options.db.pgpm.workspacePath,
+                pgpmModuleName: options.db.pgpm.moduleName,
+                schemas: options.db?.schemas,
+                apiNames: options.db?.apiNames,
+                keepDb: options.db?.keepDb,
+            });
+        default:
+            throw new Error('No source specified. Use one of: endpoint, schemaFile, or db (with optional pgpm for module deployment).');
+    }
+}
+/**
+ * Validate that source options are valid (exactly one source specified)
+ */
+function validateSourceOptions(options) {
+    // Count primary sources
+    const sources = [
+        options.endpoint,
+        options.schemaFile,
+        options.db,
+    ].filter(Boolean);
+    if (sources.length === 0) {
+        return {
+            valid: false,
+            error: 'No source specified. Use one of: endpoint, schemaFile, or db.',
+        };
+    }
+    if (sources.length > 1) {
+        return {
+            valid: false,
+            error: 'Multiple sources specified. Use only one of: endpoint, schemaFile, or db.',
+        };
+    }
+    // Validate pgpm workspace mode has both required fields
+    if (options.db?.pgpm) {
+        const pgpm = options.db.pgpm;
+        if (pgpm.workspacePath && !pgpm.moduleName) {
+            return {
+                valid: false,
+                error: 'db.pgpm.workspacePath requires db.pgpm.moduleName to be specified.',
+            };
+        }
+        if (pgpm.moduleName && !pgpm.workspacePath) {
+            return {
+                valid: false,
+                error: 'db.pgpm.moduleName requires db.pgpm.workspacePath to be specified.',
+            };
+        }
+        // Must have either modulePath or workspacePath+moduleName
+        if (!pgpm.modulePath && !(pgpm.workspacePath && pgpm.moduleName)) {
+            return {
+                valid: false,
+                error: 'db.pgpm requires either modulePath or both workspacePath and moduleName.',
+            };
+        }
+    }
+    // For database mode, validate schemas/apiNames mutual exclusivity
+    if (options.db) {
+        const hasSchemas = options.db.schemas && options.db.schemas.length > 0;
+        const hasApiNames = options.db.apiNames && options.db.apiNames.length > 0;
+        if (hasSchemas && hasApiNames) {
+            return {
+                valid: false,
+                error: 'Cannot specify both db.schemas and db.apiNames. Use one or the other.',
+            };
+        }
+        if (!hasSchemas && !hasApiNames) {
+            return {
+                valid: false,
+                error: 'Must specify either db.schemas or db.apiNames for database mode.',
+            };
+        }
+    }
+    return { valid: true };
+}