@constructive-io/graphql-codegen 2.31.0 → 3.0.0

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

@@ -0,0 +1,117 @@
+import { getPgPool } from 'pg-cache';
+import { getPgEnvOptions } from '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
+ */
+export 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
+ */
+export 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
+ */
+export 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 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 = getPgEnvOptions({ database });
+    return getPgPool(config);
+}

package/esm/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/esm/core/introspect/source/database.js

@@ -0,0 +1,87 @@
+/**
+ * Database Schema Source
+ *
+ * Loads GraphQL schema directly from a PostgreSQL database using PostGraphile
+ * introspection and converts it to introspection format.
+ */
+import { buildSchema, introspectionFromSchema } from 'graphql';
+import { SchemaSourceError } from './types';
+import { buildSchemaSDLFromDatabase } from '../../database';
+import { createDatabasePool, resolveApiSchemas, validateServicesSchemas } from './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.
+ */
+export 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 = createDatabasePool(database);
+            try {
+                const validation = await validateServicesSchemas(pool);
+                if (!validation.valid) {
+                    throw new SchemaSourceError(validation.error, this.describe());
+                }
+                schemas = await resolveApiSchemas(pool, apiNames);
+            }
+            catch (err) {
+                if (err instanceof SchemaSourceError)
+                    throw err;
+                throw new 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 buildSchemaSDLFromDatabase({
+                database,
+                schemas,
+            });
+        }
+        catch (err) {
+            throw new 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 SchemaSourceError('Database introspection returned empty schema', this.describe());
+        }
+        // Parse SDL to GraphQL schema
+        let schema;
+        try {
+            schema = buildSchema(sdl);
+        }
+        catch (err) {
+            throw new 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 = introspectionFromSchema(schema);
+        }
+        catch (err) {
+            throw new 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(', ')})`;
+    }
+}

package/esm/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/esm/core/introspect/source/index.js

@@ -0,0 +1,154 @@
+/**
+ * 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 { EndpointSchemaSource } from './endpoint';
+import { FileSchemaSource } from './file';
+import { DatabaseSchemaSource } from './database';
+import { PgpmModuleSchemaSource, } from './pgpm-module';
+export 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
+ */
+export function createSchemaSource(options) {
+    const mode = detectSourceMode(options);
+    switch (mode) {
+        case 'schemaFile':
+            return new FileSchemaSource({
+                schemaPath: options.schemaFile,
+            });
+        case 'endpoint':
+            return new 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 DatabaseSchemaSource({
+                database: options.db?.config?.database ?? '',
+                schemas: options.db?.schemas,
+                apiNames: options.db?.apiNames,
+            });
+        case 'pgpm-module':
+            return new PgpmModuleSchemaSource({
+                pgpmModulePath: options.db.pgpm.modulePath,
+                schemas: options.db?.schemas,
+                apiNames: options.db?.apiNames,
+                keepDb: options.db?.keepDb,
+            });
+        case 'pgpm-workspace':
+            return new 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)
+ */
+export 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 };
+}

package/esm/core/introspect/source/pgpm-module.d.ts

@@ -0,0 +1,83 @@
+import type { SchemaSource, SchemaSourceResult } from './types';
+/**
+ * Options for PGPM module schema source using direct module path
+ */
+export interface PgpmModulePathOptions {
+    /**
+     * Path to the PGPM module directory
+     * The directory should contain a pgpm.plan file and .control file
+     */
+    pgpmModulePath: 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[];
+    /**
+     * If true, keeps the ephemeral database after introspection (useful for debugging)
+     * @default false
+     */
+    keepDb?: boolean;
+}
+/**
+ * Options for PGPM module schema source using workspace + module name
+ */
+export interface PgpmWorkspaceOptions {
+    /**
+     * Path to the PGPM workspace directory
+     * The directory should contain a pgpm.config.yaml or similar workspace config
+     */
+    pgpmWorkspacePath: string;
+    /**
+     * Name of the module within the workspace
+     */
+    pgpmModuleName: 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[];
+    /**
+     * If true, keeps the ephemeral database after introspection (useful for debugging)
+     * @default false
+     */
+    keepDb?: boolean;
+}
+export type PgpmModuleSchemaSourceOptions = PgpmModulePathOptions | PgpmWorkspaceOptions;
+/**
+ * Type guard to check if options use direct module path
+ */
+export declare function isPgpmModulePathOptions(options: PgpmModuleSchemaSourceOptions): options is PgpmModulePathOptions;
+/**
+ * Type guard to check if options use workspace + module name
+ */
+export declare function isPgpmWorkspaceOptions(options: PgpmModuleSchemaSourceOptions): options is PgpmWorkspaceOptions;
+/**
+ * Schema source that loads from a PGPM module
+ *
+ * Creates an ephemeral database, deploys the module, introspects the schema,
+ * and cleans up. Supports both direct module path and workspace + module name modes.
+ */
+export declare class PgpmModuleSchemaSource implements SchemaSource {
+    private readonly options;
+    private ephemeralDb;
+    constructor(options: PgpmModuleSchemaSourceOptions);
+    fetch(): Promise<SchemaSourceResult>;
+    describe(): string;
+    private resolveModulePath;
+    private getSchemas;
+    private getApiNames;
+    private getKeepDb;
+}