@constructive-io/graphql-codegen 2.18.0 → 2.20.0

package/esm/cli/watch/orchestrator.js

@@ -0,0 +1,223 @@
+/**
+ * Watch mode orchestrator
+ *
+ * Coordinates schema polling, change detection, and code regeneration
+ */
+import { SchemaPoller } from './poller';
+import { debounce } from './debounce';
+import { generateCommand } from '../commands/generate';
+import { generateOrmCommand } from '../commands/generate-orm';
+/**
+ * Main watch orchestrator class
+ */
+export class WatchOrchestrator {
+    options;
+    watchOptions;
+    poller;
+    status;
+    debouncedRegenerate;
+    isShuttingDown = false;
+    constructor(options) {
+        this.options = options;
+        this.watchOptions = this.buildWatchOptions();
+        this.poller = new SchemaPoller(this.watchOptions);
+        this.status = {
+            isRunning: false,
+            pollCount: 0,
+            regenerateCount: 0,
+            lastPollTime: null,
+            lastRegenTime: null,
+            lastError: null,
+            currentHash: null,
+        };
+        // Create debounced regenerate function
+        this.debouncedRegenerate = debounce(() => this.regenerate(), options.config.watch.debounce);
+        // Set up event handlers
+        this.setupEventHandlers();
+    }
+    buildWatchOptions() {
+        const { config, verbose, authorization } = this.options;
+        return {
+            endpoint: config.endpoint,
+            authorization,
+            headers: config.headers,
+            pollInterval: config.watch.pollInterval,
+            debounce: config.watch.debounce,
+            touchFile: config.watch.touchFile,
+            clearScreen: config.watch.clearScreen,
+            verbose,
+        };
+    }
+    setupEventHandlers() {
+        this.poller.on('poll-start', () => {
+            this.status.pollCount++;
+            if (this.watchOptions.verbose) {
+                this.log('Polling endpoint...');
+            }
+        });
+        this.poller.on('poll-success', (event) => {
+            this.status.lastPollTime = event.timestamp;
+            this.status.lastError = null;
+            if (this.watchOptions.verbose) {
+                this.log(`Poll complete (${event.duration}ms)`);
+            }
+        });
+        this.poller.on('poll-error', (event) => {
+            this.status.lastError = event.error ?? 'Unknown error';
+            this.logError(`Poll failed: ${event.error}`);
+        });
+        this.poller.on('schema-changed', (event) => {
+            this.status.currentHash = event.hash ?? null;
+            this.log(`Schema changed! (${event.duration}ms)`);
+            this.debouncedRegenerate();
+        });
+        this.poller.on('schema-unchanged', () => {
+            if (this.watchOptions.verbose) {
+                this.log('Schema unchanged');
+            }
+        });
+    }
+    /**
+     * Start watch mode
+     */
+    async start() {
+        if (this.status.isRunning) {
+            return;
+        }
+        this.status.isRunning = true;
+        this.setupSignalHandlers();
+        // Clear screen on start if configured
+        if (this.watchOptions.clearScreen) {
+            this.clearScreen();
+        }
+        this.logHeader();
+        // Do initial generation (always generate on start, regardless of cache)
+        this.log('Running initial generation...');
+        await this.regenerate();
+        // Seed the in-memory cache with current schema hash (silent, no events)
+        // This prevents the first poll from triggering another regeneration
+        await this.poller.seedCache();
+        // Start polling loop
+        this.poller.start();
+        this.log(`Watching for schema changes (poll interval: ${this.watchOptions.pollInterval}ms)`);
+    }
+    /**
+     * Stop watch mode
+     */
+    async stop() {
+        if (!this.status.isRunning) {
+            return;
+        }
+        this.isShuttingDown = true;
+        this.debouncedRegenerate.cancel();
+        this.poller.stop();
+        this.status.isRunning = false;
+        this.log('Watch mode stopped');
+    }
+    /**
+     * Get current watch status
+     */
+    getStatus() {
+        return { ...this.status };
+    }
+    async regenerate() {
+        if (this.isShuttingDown) {
+            return;
+        }
+        const startTime = Date.now();
+        if (this.watchOptions.clearScreen) {
+            this.clearScreen();
+            this.logHeader();
+        }
+        this.log('Regenerating...');
+        try {
+            let result;
+            if (this.options.generatorType === 'generate') {
+                result = await generateCommand({
+                    endpoint: this.options.config.endpoint,
+                    output: this.options.outputDir ?? this.options.config.output,
+                    authorization: this.options.authorization,
+                    verbose: this.watchOptions.verbose,
+                    skipCustomOperations: this.options.skipCustomOperations,
+                });
+            }
+            else {
+                result = await generateOrmCommand({
+                    endpoint: this.options.config.endpoint,
+                    output: this.options.outputDir ?? this.options.config.orm?.output,
+                    authorization: this.options.authorization,
+                    verbose: this.watchOptions.verbose,
+                    skipCustomOperations: this.options.skipCustomOperations,
+                });
+            }
+            const duration = Date.now() - startTime;
+            if (result.success) {
+                this.status.regenerateCount++;
+                this.status.lastRegenTime = Date.now();
+                this.logSuccess(`Generated in ${duration}ms`);
+                if (result.tables && result.tables.length > 0) {
+                    this.log(`  Tables: ${result.tables.length}`);
+                }
+                if (result.filesWritten && result.filesWritten.length > 0) {
+                    this.log(`  Files: ${result.filesWritten.length}`);
+                }
+            }
+            else {
+                this.logError(`Generation failed: ${result.message}`);
+                if (result.errors) {
+                    result.errors.forEach((e) => this.logError(`  ${e}`));
+                }
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : 'Unknown error';
+            this.logError(`Generation error: ${message}`);
+        }
+        this.log(`\nWatching for changes...`);
+    }
+    setupSignalHandlers() {
+        const shutdown = async (signal) => {
+            this.log(`\nReceived ${signal}, shutting down...`);
+            await this.stop();
+            process.exit(0);
+        };
+        process.on('SIGINT', () => shutdown('SIGINT'));
+        process.on('SIGTERM', () => shutdown('SIGTERM'));
+    }
+    clearScreen() {
+        // ANSI escape codes for clearing screen
+        process.stdout.write('\x1B[2J\x1B[0f');
+    }
+    logHeader() {
+        const generatorName = this.options.generatorType === 'generate'
+            ? 'React Query hooks'
+            : 'ORM client';
+        console.log(`\n${'─'.repeat(50)}`);
+        console.log(`graphql-codegen watch mode (${generatorName})`);
+        console.log(`Endpoint: ${this.options.config.endpoint}`);
+        console.log(`${'─'.repeat(50)}\n`);
+    }
+    log(message) {
+        const timestamp = new Date().toLocaleTimeString();
+        console.log(`[${timestamp}] ${message}`);
+    }
+    logSuccess(message) {
+        const timestamp = new Date().toLocaleTimeString();
+        console.log(`[${timestamp}] ✓ ${message}`);
+    }
+    logError(message) {
+        const timestamp = new Date().toLocaleTimeString();
+        console.error(`[${timestamp}] ✗ ${message}`);
+    }
+}
+/**
+ * Start watch mode for a generator
+ */
+export async function startWatch(options) {
+    const orchestrator = new WatchOrchestrator(options);
+    await orchestrator.start();
+    // Keep the process alive
+    await new Promise(() => {
+        // This promise never resolves - the process will exit via signal handlers
+    });
+}

package/esm/cli/watch/poller.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Schema polling logic with EventEmitter pattern
+ *
+ * Uses in-memory hash comparison for efficiency.
+ * No file I/O during normal polling - only touchFile is optional file write.
+ */
+import { EventEmitter } from 'node:events';
+import type { MetaQueryResponse } from '../introspect/meta-query';
+import type { IntrospectionQueryResponse } from '../../types/introspection';
+import { SchemaCache } from './cache';
+import type { PollResult, WatchOptions } from './types';
+/**
+ * Schema poller that periodically introspects a GraphQL endpoint
+ * and emits events when the schema changes.
+ *
+ * Uses in-memory caching for hash comparison - no file I/O overhead.
+ */
+export declare class SchemaPoller extends EventEmitter {
+    private options;
+    private cache;
+    private pollTimer;
+    private isPolling;
+    private consecutiveErrors;
+    private readonly MAX_CONSECUTIVE_ERRORS;
+    constructor(options: WatchOptions);
+    /**
+     * Start the polling loop
+     */
+    start(): void;
+    /**
+     * Stop the polling loop
+     */
+    stop(): void;
+    /**
+     * Perform a single poll operation
+     */
+    poll(): Promise<PollResult>;
+    /**
+     * Perform a single poll without starting the loop (for initial generation)
+     */
+    pollOnce(): Promise<PollResult>;
+    /**
+     * Seed the cache with current schema hash without emitting events.
+     * Call this after initial generation to prevent first poll from triggering regeneration.
+     */
+    seedCache(): Promise<void>;
+    /**
+     * Get the current cached schema hash
+     */
+    getCurrentHash(): string | null;
+    /**
+     * Get the cache instance for direct access
+     */
+    getCache(): SchemaCache;
+    /**
+     * Check if the poller is currently running
+     */
+    isRunning(): boolean;
+    private handleError;
+    private createEvent;
+}
+/**
+ * Utility to compute schema hash without full poll
+ */
+export declare function computeSchemaHash(meta: MetaQueryResponse, schema: IntrospectionQueryResponse): Promise<string>;

package/esm/cli/watch/poller.js

@@ -0,0 +1,198 @@
+/**
+ * Schema polling logic with EventEmitter pattern
+ *
+ * Uses in-memory hash comparison for efficiency.
+ * No file I/O during normal polling - only touchFile is optional file write.
+ */
+import { EventEmitter } from 'node:events';
+import { fetchMeta } from '../introspect/fetch-meta';
+import { fetchSchema } from '../introspect/fetch-schema';
+import { SchemaCache, touchFile } from './cache';
+import { hashObject, combineHashes } from './hash';
+/**
+ * Schema poller that periodically introspects a GraphQL endpoint
+ * and emits events when the schema changes.
+ *
+ * Uses in-memory caching for hash comparison - no file I/O overhead.
+ */
+export class SchemaPoller extends EventEmitter {
+    options;
+    cache;
+    pollTimer = null;
+    isPolling = false;
+    consecutiveErrors = 0;
+    MAX_CONSECUTIVE_ERRORS = 5;
+    constructor(options) {
+        super();
+        this.options = options;
+        this.cache = new SchemaCache();
+    }
+    /**
+     * Start the polling loop
+     */
+    start() {
+        if (this.pollTimer) {
+            return; // Already running
+        }
+        // Do an immediate poll
+        this.poll();
+        // Set up interval
+        this.pollTimer = setInterval(() => {
+            this.poll();
+        }, this.options.pollInterval);
+    }
+    /**
+     * Stop the polling loop
+     */
+    stop() {
+        if (this.pollTimer) {
+            clearInterval(this.pollTimer);
+            this.pollTimer = null;
+        }
+    }
+    /**
+     * Perform a single poll operation
+     */
+    async poll() {
+        // Prevent concurrent polls
+        if (this.isPolling) {
+            return { success: false, changed: false, error: 'Poll already in progress' };
+        }
+        this.isPolling = true;
+        const startTime = Date.now();
+        this.emit('poll-start', this.createEvent('poll-start'));
+        try {
+            // Fetch both _meta and __schema
+            const [metaResult, schemaResult] = await Promise.all([
+                fetchMeta({
+                    endpoint: this.options.endpoint,
+                    authorization: this.options.authorization,
+                    headers: this.options.headers,
+                    timeout: 30000,
+                }),
+                fetchSchema({
+                    endpoint: this.options.endpoint,
+                    authorization: this.options.authorization,
+                    headers: this.options.headers,
+                    timeout: 30000,
+                }),
+            ]);
+            const duration = Date.now() - startTime;
+            // Check for errors
+            if (!metaResult.success) {
+                return this.handleError(`_meta fetch failed: ${metaResult.error}`, duration);
+            }
+            if (!schemaResult.success) {
+                return this.handleError(`__schema fetch failed: ${schemaResult.error}`, duration);
+            }
+            const meta = metaResult.data;
+            const schema = schemaResult.data;
+            // Check if schema changed
+            const { changed, newHash } = await this.cache.hasChanged(meta, schema);
+            // Reset error counter on success
+            this.consecutiveErrors = 0;
+            if (changed) {
+                // Update in-memory hash
+                this.cache.updateHash(newHash);
+                // Touch trigger file if configured (only file I/O in watch mode)
+                if (this.options.touchFile) {
+                    touchFile(this.options.touchFile);
+                }
+                this.emit('schema-changed', this.createEvent('schema-changed', { hash: newHash, duration }));
+                return { success: true, changed: true, hash: newHash, meta, schema };
+            }
+            this.emit('schema-unchanged', this.createEvent('schema-unchanged', { duration }));
+            this.emit('poll-success', this.createEvent('poll-success', { duration }));
+            return { success: true, changed: false, hash: newHash, meta, schema };
+        }
+        catch (err) {
+            const duration = Date.now() - startTime;
+            const error = err instanceof Error ? err.message : 'Unknown error';
+            return this.handleError(error, duration);
+        }
+        finally {
+            this.isPolling = false;
+        }
+    }
+    /**
+     * Perform a single poll without starting the loop (for initial generation)
+     */
+    async pollOnce() {
+        return this.poll();
+    }
+    /**
+     * Seed the cache with current schema hash without emitting events.
+     * Call this after initial generation to prevent first poll from triggering regeneration.
+     */
+    async seedCache() {
+        try {
+            const [metaResult, schemaResult] = await Promise.all([
+                fetchMeta({
+                    endpoint: this.options.endpoint,
+                    authorization: this.options.authorization,
+                    headers: this.options.headers,
+                    timeout: 30000,
+                }),
+                fetchSchema({
+                    endpoint: this.options.endpoint,
+                    authorization: this.options.authorization,
+                    headers: this.options.headers,
+                    timeout: 30000,
+                }),
+            ]);
+            if (metaResult.success && schemaResult.success) {
+                const { newHash } = await this.cache.hasChanged(metaResult.data, schemaResult.data);
+                this.cache.updateHash(newHash);
+            }
+        }
+        catch {
+            // Silently fail - cache will be seeded on first successful poll
+        }
+    }
+    /**
+     * Get the current cached schema hash
+     */
+    getCurrentHash() {
+        return this.cache.getHash();
+    }
+    /**
+     * Get the cache instance for direct access
+     */
+    getCache() {
+        return this.cache;
+    }
+    /**
+     * Check if the poller is currently running
+     */
+    isRunning() {
+        return this.pollTimer !== null;
+    }
+    handleError(error, duration) {
+        this.consecutiveErrors++;
+        this.emit('poll-error', this.createEvent('poll-error', { error, duration }));
+        // Slow down polling after multiple consecutive errors
+        if (this.consecutiveErrors >= this.MAX_CONSECUTIVE_ERRORS && this.pollTimer) {
+            this.stop();
+            const newInterval = this.options.pollInterval * 2;
+            this.pollTimer = setInterval(() => {
+                this.poll();
+            }, newInterval);
+        }
+        return { success: false, changed: false, error };
+    }
+    createEvent(type, extra) {
+        return {
+            type,
+            timestamp: Date.now(),
+            ...extra,
+        };
+    }
+}
+/**
+ * Utility to compute schema hash without full poll
+ */
+export async function computeSchemaHash(meta, schema) {
+    const metaHash = await hashObject(meta);
+    const schemaHash = await hashObject(schema);
+    return combineHashes(metaHash, schemaHash);
+}

package/esm/cli/watch/types.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Watch mode types
+ */
+import type { MetaQueryResponse } from '../introspect/meta-query';
+import type { IntrospectionQueryResponse } from '../../types/introspection';
+/**
+ * Result of a schema poll operation
+ */
+export interface PollResult {
+    success: boolean;
+    /** Whether the schema changed since last poll */
+    changed: boolean;
+    /** Error message if poll failed */
+    error?: string;
+    /** The new hash if successful */
+    hash?: string;
+    /** Meta response if successful */
+    meta?: MetaQueryResponse;
+    /** Schema response if successful */
+    schema?: IntrospectionQueryResponse;
+}
+/**
+ * Watch mode options passed to the watch orchestrator
+ */
+export interface WatchOptions {
+    /** GraphQL endpoint URL */
+    endpoint: string;
+    /** Authorization header value */
+    authorization?: string;
+    /** Additional headers */
+    headers?: Record<string, string>;
+    /** Polling interval in ms */
+    pollInterval: number;
+    /** Debounce delay in ms */
+    debounce: number;
+    /** File to touch on schema change (optional) */
+    touchFile: string | null;
+    /** Clear terminal on regeneration */
+    clearScreen: boolean;
+    /** Verbose output */
+    verbose: boolean;
+}
+/**
+ * Events emitted by the SchemaPoller
+ */
+export type PollEventType = 'poll-start' | 'poll-success' | 'poll-error' | 'schema-changed' | 'schema-unchanged';
+/**
+ * Event handler signature for poll events
+ */
+export type PollEventHandler = (event: PollEvent) => void;
+/**
+ * Poll event payload
+ */
+export interface PollEvent {
+    type: PollEventType;
+    timestamp: number;
+    /** Error message if type is 'poll-error' */
+    error?: string;
+    /** New hash if schema changed */
+    hash?: string;
+    /** Duration of the poll in ms */
+    duration?: number;
+}
+/**
+ * Generator type for watch mode
+ */
+export type GeneratorType = 'generate' | 'generate-orm';

package/esm/cli/watch/types.js

@@ -0,0 +1,4 @@
+/**
+ * Watch mode types
+ */
+export {};

package/esm/client/error.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Error handling for GraphQL operations
+ * Provides consistent error types and parsing for PostGraphile responses
+ */
+export declare const DataErrorType: {
+    readonly NETWORK_ERROR: "NETWORK_ERROR";
+    readonly TIMEOUT_ERROR: "TIMEOUT_ERROR";
+    readonly VALIDATION_FAILED: "VALIDATION_FAILED";
+    readonly REQUIRED_FIELD_MISSING: "REQUIRED_FIELD_MISSING";
+    readonly INVALID_MUTATION_DATA: "INVALID_MUTATION_DATA";
+    readonly QUERY_GENERATION_FAILED: "QUERY_GENERATION_FAILED";
+    readonly QUERY_EXECUTION_FAILED: "QUERY_EXECUTION_FAILED";
+    readonly UNAUTHORIZED: "UNAUTHORIZED";
+    readonly FORBIDDEN: "FORBIDDEN";
+    readonly TABLE_NOT_FOUND: "TABLE_NOT_FOUND";
+    readonly BAD_REQUEST: "BAD_REQUEST";
+    readonly NOT_FOUND: "NOT_FOUND";
+    readonly GRAPHQL_ERROR: "GRAPHQL_ERROR";
+    readonly UNIQUE_VIOLATION: "UNIQUE_VIOLATION";
+    readonly FOREIGN_KEY_VIOLATION: "FOREIGN_KEY_VIOLATION";
+    readonly NOT_NULL_VIOLATION: "NOT_NULL_VIOLATION";
+    readonly CHECK_VIOLATION: "CHECK_VIOLATION";
+    readonly EXCLUSION_VIOLATION: "EXCLUSION_VIOLATION";
+    readonly UNKNOWN_ERROR: "UNKNOWN_ERROR";
+};
+export type DataErrorType = (typeof DataErrorType)[keyof typeof DataErrorType];
+export interface DataErrorOptions {
+    tableName?: string;
+    fieldName?: string;
+    constraint?: string;
+    originalError?: Error;
+    code?: string;
+    context?: Record<string, unknown>;
+}
+/**
+ * Standard error class for data layer operations
+ */
+export declare class DataError extends Error {
+    readonly type: DataErrorType;
+    readonly code?: string;
+    readonly originalError?: Error;
+    readonly context?: Record<string, unknown>;
+    readonly tableName?: string;
+    readonly fieldName?: string;
+    readonly constraint?: string;
+    constructor(type: DataErrorType, message: string, options?: DataErrorOptions);
+    getUserMessage(): string;
+    isRetryable(): boolean;
+}
+export declare const PG_ERROR_CODES: {
+    readonly UNIQUE_VIOLATION: "23505";
+    readonly FOREIGN_KEY_VIOLATION: "23503";
+    readonly NOT_NULL_VIOLATION: "23502";
+    readonly CHECK_VIOLATION: "23514";
+    readonly EXCLUSION_VIOLATION: "23P01";
+    readonly NUMERIC_VALUE_OUT_OF_RANGE: "22003";
+    readonly STRING_DATA_RIGHT_TRUNCATION: "22001";
+    readonly INVALID_TEXT_REPRESENTATION: "22P02";
+    readonly DATETIME_FIELD_OVERFLOW: "22008";
+    readonly UNDEFINED_TABLE: "42P01";
+    readonly UNDEFINED_COLUMN: "42703";
+    readonly INSUFFICIENT_PRIVILEGE: "42501";
+};
+export declare const createError: {
+    network: (originalError?: Error) => DataError;
+    timeout: (originalError?: Error) => DataError;
+    unauthorized: (message?: string) => DataError;
+    forbidden: (message?: string) => DataError;
+    badRequest: (message: string, code?: string) => DataError;
+    notFound: (message?: string) => DataError;
+    graphql: (message: string, code?: string) => DataError;
+    uniqueViolation: (message: string, fieldName?: string, constraint?: string) => DataError;
+    foreignKeyViolation: (message: string, fieldName?: string, constraint?: string) => DataError;
+    notNullViolation: (message: string, fieldName?: string, constraint?: string) => DataError;
+    unknown: (originalError: Error) => DataError;
+};
+export interface GraphQLError {
+    message: string;
+    extensions?: {
+        code?: string;
+    } & Record<string, unknown>;
+    locations?: Array<{
+        line: number;
+        column: number;
+    }>;
+    path?: Array<string | number>;
+}
+/**
+ * Parse any error into a DataError
+ */
+export declare function parseGraphQLError(error: unknown): DataError;
+/**
+ * Check if value is a DataError
+ */
+export declare function isDataError(error: unknown): error is DataError;