@constructive-io/graphql-codegen 2.19.0 → 2.20.0

package/cli/watch/poller.js

@@ -0,0 +1,203 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SchemaPoller = void 0;
+exports.computeSchemaHash = computeSchemaHash;
+const node_events_1 = require("node:events");
+const fetch_meta_1 = require("../introspect/fetch-meta");
+const fetch_schema_1 = require("../introspect/fetch-schema");
+const cache_1 = require("./cache");
+const hash_1 = require("./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.
+ */
+class SchemaPoller extends node_events_1.EventEmitter {
+    options;
+    cache;
+    pollTimer = null;
+    isPolling = false;
+    consecutiveErrors = 0;
+    MAX_CONSECUTIVE_ERRORS = 5;
+    constructor(options) {
+        super();
+        this.options = options;
+        this.cache = new cache_1.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([
+                (0, fetch_meta_1.fetchMeta)({
+                    endpoint: this.options.endpoint,
+                    authorization: this.options.authorization,
+                    headers: this.options.headers,
+                    timeout: 30000,
+                }),
+                (0, fetch_schema_1.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) {
+                    (0, cache_1.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([
+                (0, fetch_meta_1.fetchMeta)({
+                    endpoint: this.options.endpoint,
+                    authorization: this.options.authorization,
+                    headers: this.options.headers,
+                    timeout: 30000,
+                }),
+                (0, fetch_schema_1.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,
+        };
+    }
+}
+exports.SchemaPoller = SchemaPoller;
+/**
+ * Utility to compute schema hash without full poll
+ */
+async function computeSchemaHash(meta, schema) {
+    const metaHash = await (0, hash_1.hashObject)(meta);
+    const schemaHash = await (0, hash_1.hashObject)(schema);
+    return (0, hash_1.combineHashes)(metaHash, schemaHash);
+}

package/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/cli/watch/types.js

@@ -0,0 +1,5 @@
+"use strict";
+/**
+ * Watch mode types
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

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

package/client/error.js

@@ -0,0 +1,255 @@
+"use strict";
+/**
+ * Error handling for GraphQL operations
+ * Provides consistent error types and parsing for PostGraphile responses
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createError = exports.PG_ERROR_CODES = exports.DataError = exports.DataErrorType = void 0;
+exports.parseGraphQLError = parseGraphQLError;
+exports.isDataError = isDataError;
+// ============================================================================
+// Error Types
+// ============================================================================
+exports.DataErrorType = {
+    // Network/Connection errors
+    NETWORK_ERROR: 'NETWORK_ERROR',
+    TIMEOUT_ERROR: 'TIMEOUT_ERROR',
+    // Validation errors
+    VALIDATION_FAILED: 'VALIDATION_FAILED',
+    REQUIRED_FIELD_MISSING: 'REQUIRED_FIELD_MISSING',
+    INVALID_MUTATION_DATA: 'INVALID_MUTATION_DATA',
+    // Query errors
+    QUERY_GENERATION_FAILED: 'QUERY_GENERATION_FAILED',
+    QUERY_EXECUTION_FAILED: 'QUERY_EXECUTION_FAILED',
+    // Permission errors
+    UNAUTHORIZED: 'UNAUTHORIZED',
+    FORBIDDEN: 'FORBIDDEN',
+    // Schema errors
+    TABLE_NOT_FOUND: 'TABLE_NOT_FOUND',
+    // Request errors
+    BAD_REQUEST: 'BAD_REQUEST',
+    NOT_FOUND: 'NOT_FOUND',
+    // GraphQL-specific errors
+    GRAPHQL_ERROR: 'GRAPHQL_ERROR',
+    // PostgreSQL constraint errors (surfaced via PostGraphile)
+    UNIQUE_VIOLATION: 'UNIQUE_VIOLATION',
+    FOREIGN_KEY_VIOLATION: 'FOREIGN_KEY_VIOLATION',
+    NOT_NULL_VIOLATION: 'NOT_NULL_VIOLATION',
+    CHECK_VIOLATION: 'CHECK_VIOLATION',
+    EXCLUSION_VIOLATION: 'EXCLUSION_VIOLATION',
+    // Generic errors
+    UNKNOWN_ERROR: 'UNKNOWN_ERROR',
+};
+/**
+ * Standard error class for data layer operations
+ */
+class DataError extends Error {
+    type;
+    code;
+    originalError;
+    context;
+    tableName;
+    fieldName;
+    constraint;
+    constructor(type, message, options = {}) {
+        super(message);
+        this.name = 'DataError';
+        this.type = type;
+        this.code = options.code;
+        this.originalError = options.originalError;
+        this.context = options.context;
+        this.tableName = options.tableName;
+        this.fieldName = options.fieldName;
+        this.constraint = options.constraint;
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, DataError);
+        }
+    }
+    getUserMessage() {
+        switch (this.type) {
+            case exports.DataErrorType.NETWORK_ERROR:
+                return 'Network error. Please check your connection and try again.';
+            case exports.DataErrorType.TIMEOUT_ERROR:
+                return 'Request timed out. Please try again.';
+            case exports.DataErrorType.UNAUTHORIZED:
+                return 'You are not authorized. Please log in and try again.';
+            case exports.DataErrorType.FORBIDDEN:
+                return 'You do not have permission to access this resource.';
+            case exports.DataErrorType.VALIDATION_FAILED:
+                return 'Validation failed. Please check your input and try again.';
+            case exports.DataErrorType.REQUIRED_FIELD_MISSING:
+                return this.fieldName
+                    ? `The field "${this.fieldName}" is required.`
+                    : 'A required field is missing.';
+            case exports.DataErrorType.UNIQUE_VIOLATION:
+                return this.fieldName
+                    ? `A record with this ${this.fieldName} already exists.`
+                    : 'A record with this value already exists.';
+            case exports.DataErrorType.FOREIGN_KEY_VIOLATION:
+                return 'This record references a record that does not exist.';
+            case exports.DataErrorType.NOT_NULL_VIOLATION:
+                return this.fieldName
+                    ? `The field "${this.fieldName}" cannot be empty.`
+                    : 'A required field cannot be empty.';
+            case exports.DataErrorType.CHECK_VIOLATION:
+                return this.fieldName
+                    ? `The value for "${this.fieldName}" is not valid.`
+                    : 'The value does not meet the required constraints.';
+            default:
+                return this.message || 'An unexpected error occurred.';
+        }
+    }
+    isRetryable() {
+        return (this.type === exports.DataErrorType.NETWORK_ERROR ||
+            this.type === exports.DataErrorType.TIMEOUT_ERROR);
+    }
+}
+exports.DataError = DataError;
+// ============================================================================
+// PostgreSQL Error Codes
+// ============================================================================
+exports.PG_ERROR_CODES = {
+    UNIQUE_VIOLATION: '23505',
+    FOREIGN_KEY_VIOLATION: '23503',
+    NOT_NULL_VIOLATION: '23502',
+    CHECK_VIOLATION: '23514',
+    EXCLUSION_VIOLATION: '23P01',
+    NUMERIC_VALUE_OUT_OF_RANGE: '22003',
+    STRING_DATA_RIGHT_TRUNCATION: '22001',
+    INVALID_TEXT_REPRESENTATION: '22P02',
+    DATETIME_FIELD_OVERFLOW: '22008',
+    UNDEFINED_TABLE: '42P01',
+    UNDEFINED_COLUMN: '42703',
+    INSUFFICIENT_PRIVILEGE: '42501',
+};
+// ============================================================================
+// Error Factory
+// ============================================================================
+exports.createError = {
+    network: (originalError) => new DataError(exports.DataErrorType.NETWORK_ERROR, 'Network error occurred', { originalError }),
+    timeout: (originalError) => new DataError(exports.DataErrorType.TIMEOUT_ERROR, 'Request timed out', { originalError }),
+    unauthorized: (message = 'Authentication required') => new DataError(exports.DataErrorType.UNAUTHORIZED, message),
+    forbidden: (message = 'Access forbidden') => new DataError(exports.DataErrorType.FORBIDDEN, message),
+    badRequest: (message, code) => new DataError(exports.DataErrorType.BAD_REQUEST, message, { code }),
+    notFound: (message = 'Resource not found') => new DataError(exports.DataErrorType.NOT_FOUND, message),
+    graphql: (message, code) => new DataError(exports.DataErrorType.GRAPHQL_ERROR, message, { code }),
+    uniqueViolation: (message, fieldName, constraint) => new DataError(exports.DataErrorType.UNIQUE_VIOLATION, message, { fieldName, constraint, code: '23505' }),
+    foreignKeyViolation: (message, fieldName, constraint) => new DataError(exports.DataErrorType.FOREIGN_KEY_VIOLATION, message, { fieldName, constraint, code: '23503' }),
+    notNullViolation: (message, fieldName, constraint) => new DataError(exports.DataErrorType.NOT_NULL_VIOLATION, message, { fieldName, constraint, code: '23502' }),
+    unknown: (originalError) => new DataError(exports.DataErrorType.UNKNOWN_ERROR, originalError.message, { originalError }),
+};
+function parseGraphQLErrorCode(code) {
+    if (!code)
+        return exports.DataErrorType.UNKNOWN_ERROR;
+    const normalized = code.toUpperCase();
+    // GraphQL standard codes
+    if (normalized === 'UNAUTHENTICATED')
+        return exports.DataErrorType.UNAUTHORIZED;
+    if (normalized === 'FORBIDDEN')
+        return exports.DataErrorType.FORBIDDEN;
+    if (normalized === 'GRAPHQL_VALIDATION_FAILED')
+        return exports.DataErrorType.QUERY_GENERATION_FAILED;
+    // PostgreSQL SQLSTATE codes
+    if (code === exports.PG_ERROR_CODES.UNIQUE_VIOLATION)
+        return exports.DataErrorType.UNIQUE_VIOLATION;
+    if (code === exports.PG_ERROR_CODES.FOREIGN_KEY_VIOLATION)
+        return exports.DataErrorType.FOREIGN_KEY_VIOLATION;
+    if (code === exports.PG_ERROR_CODES.NOT_NULL_VIOLATION)
+        return exports.DataErrorType.NOT_NULL_VIOLATION;
+    if (code === exports.PG_ERROR_CODES.CHECK_VIOLATION)
+        return exports.DataErrorType.CHECK_VIOLATION;
+    if (code === exports.PG_ERROR_CODES.EXCLUSION_VIOLATION)
+        return exports.DataErrorType.EXCLUSION_VIOLATION;
+    return exports.DataErrorType.UNKNOWN_ERROR;
+}
+function classifyByMessage(message) {
+    const lower = message.toLowerCase();
+    if (lower.includes('timeout') || lower.includes('timed out')) {
+        return exports.DataErrorType.TIMEOUT_ERROR;
+    }
+    if (lower.includes('network') || lower.includes('fetch') || lower.includes('failed to fetch')) {
+        return exports.DataErrorType.NETWORK_ERROR;
+    }
+    if (lower.includes('unauthorized') || lower.includes('authentication required')) {
+        return exports.DataErrorType.UNAUTHORIZED;
+    }
+    if (lower.includes('forbidden') || lower.includes('permission')) {
+        return exports.DataErrorType.FORBIDDEN;
+    }
+    if (lower.includes('duplicate key') || lower.includes('already exists')) {
+        return exports.DataErrorType.UNIQUE_VIOLATION;
+    }
+    if (lower.includes('foreign key constraint')) {
+        return exports.DataErrorType.FOREIGN_KEY_VIOLATION;
+    }
+    if (lower.includes('not-null constraint') || lower.includes('null value in column')) {
+        return exports.DataErrorType.NOT_NULL_VIOLATION;
+    }
+    return exports.DataErrorType.UNKNOWN_ERROR;
+}
+function extractFieldFromError(message, constraint, column) {
+    if (column)
+        return column;
+    const columnMatch = message.match(/column\s+"?([a-z_][a-z0-9_]*)"?/i);
+    if (columnMatch)
+        return columnMatch[1];
+    if (constraint) {
+        const constraintMatch = constraint.match(/_([a-z_][a-z0-9_]*)_(?:key|fkey|check|pkey)$/i);
+        if (constraintMatch)
+            return constraintMatch[1];
+    }
+    const keyMatch = message.match(/Key\s+\(([a-z_][a-z0-9_]*)\)/i);
+    if (keyMatch)
+        return keyMatch[1];
+    return undefined;
+}
+/**
+ * Parse any error into a DataError
+ */
+function parseGraphQLError(error) {
+    if (error instanceof DataError) {
+        return error;
+    }
+    // GraphQL error object
+    if (error &&
+        typeof error === 'object' &&
+        'message' in error &&
+        typeof error.message === 'string') {
+        const gqlError = error;
+        const extCode = gqlError.extensions?.code;
+        const mappedType = parseGraphQLErrorCode(extCode);
+        const column = gqlError.extensions?.column;
+        const constraint = gqlError.extensions?.constraint;
+        const fieldName = extractFieldFromError(gqlError.message, constraint, column);
+        if (mappedType !== exports.DataErrorType.UNKNOWN_ERROR) {
+            return new DataError(mappedType, gqlError.message, {
+                code: extCode,
+                fieldName,
+                constraint,
+                context: gqlError.extensions,
+            });
+        }
+        // Fallback: classify by message
+        const fallbackType = classifyByMessage(gqlError.message);
+        return new DataError(fallbackType, gqlError.message, {
+            code: extCode,
+            fieldName,
+            constraint,
+            context: gqlError.extensions,
+        });
+    }
+    // Standard Error
+    if (error instanceof Error) {
+        const type = classifyByMessage(error.message);
+        return new DataError(type, error.message, { originalError: error });
+    }
+    // Unknown
+    const message = typeof error === 'string' ? error : 'Unknown error occurred';
+    return new DataError(exports.DataErrorType.UNKNOWN_ERROR, message);
+}
+/**
+ * Check if value is a DataError
+ */
+function isDataError(error) {
+    return error instanceof DataError;
+}

package/client/execute.d.ts

@@ -0,0 +1,57 @@
+/**
+ * GraphQL execution utilities
+ */
+import type { DocumentNode } from 'graphql';
+import { TypedDocumentString } from './typed-document';
+type ExecutableDocument = TypedDocumentString<unknown, unknown> | DocumentNode | string;
+type ResultOf<TDocument> = TDocument extends TypedDocumentString<infer TResult, unknown> ? TResult : unknown;
+type VariablesOf<TDocument> = TDocument extends TypedDocumentString<unknown, infer TVariables> ? TVariables : Record<string, unknown>;
+export interface ExecuteOptions {
+    /** Custom headers to include */
+    headers?: Record<string, string>;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /** Signal for request cancellation */
+    signal?: AbortSignal;
+}
+export interface GraphQLResponse<T = unknown> {
+    data?: T;
+    errors?: Array<{
+        message: string;
+        extensions?: {
+            code?: string;
+        } & Record<string, unknown>;
+        locations?: Array<{
+            line: number;
+            column: number;
+        }>;
+        path?: Array<string | number>;
+    }>;
+}
+/**
+ * Execute a GraphQL operation against an endpoint
+ */
+export declare function execute<TDocument extends ExecutableDocument>(endpoint: string, document: TDocument, variables?: VariablesOf<TDocument>, options?: ExecuteOptions): Promise<ResultOf<TDocument>>;
+export interface GraphQLClientOptions {
+    /** GraphQL endpoint URL */
+    endpoint: string;
+    /** Default headers to include with every request */
+    headers?: Record<string, string>;
+    /** Default timeout in milliseconds */
+    timeout?: number;
+}
+/**
+ * Create a GraphQL client instance
+ */
+export declare function createGraphQLClient(options: GraphQLClientOptions): {
+    /**
+     * Execute a GraphQL operation
+     */
+    execute<TDocument extends ExecutableDocument>(document: TDocument, variables?: VariablesOf<TDocument>, options?: ExecuteOptions): Promise<ResultOf<TDocument>>;
+    /**
+     * Get the endpoint URL
+     */
+    getEndpoint(): string;
+};
+export type GraphQLClient = ReturnType<typeof createGraphQLClient>;
+export {};