@constructive-io/graphql-codegen 2.19.0 → 2.20.1

package/esm/client/error.js

@@ -0,0 +1,249 @@
+/**
+ * Error handling for GraphQL operations
+ * Provides consistent error types and parsing for PostGraphile responses
+ */
+// ============================================================================
+// Error Types
+// ============================================================================
+export const 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
+ */
+export 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 DataErrorType.NETWORK_ERROR:
+                return 'Network error. Please check your connection and try again.';
+            case DataErrorType.TIMEOUT_ERROR:
+                return 'Request timed out. Please try again.';
+            case DataErrorType.UNAUTHORIZED:
+                return 'You are not authorized. Please log in and try again.';
+            case DataErrorType.FORBIDDEN:
+                return 'You do not have permission to access this resource.';
+            case DataErrorType.VALIDATION_FAILED:
+                return 'Validation failed. Please check your input and try again.';
+            case DataErrorType.REQUIRED_FIELD_MISSING:
+                return this.fieldName
+                    ? `The field "${this.fieldName}" is required.`
+                    : 'A required field is missing.';
+            case DataErrorType.UNIQUE_VIOLATION:
+                return this.fieldName
+                    ? `A record with this ${this.fieldName} already exists.`
+                    : 'A record with this value already exists.';
+            case DataErrorType.FOREIGN_KEY_VIOLATION:
+                return 'This record references a record that does not exist.';
+            case DataErrorType.NOT_NULL_VIOLATION:
+                return this.fieldName
+                    ? `The field "${this.fieldName}" cannot be empty.`
+                    : 'A required field cannot be empty.';
+            case 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 === DataErrorType.NETWORK_ERROR ||
+            this.type === DataErrorType.TIMEOUT_ERROR);
+    }
+}
+// ============================================================================
+// PostgreSQL Error Codes
+// ============================================================================
+export const 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
+// ============================================================================
+export const createError = {
+    network: (originalError) => new DataError(DataErrorType.NETWORK_ERROR, 'Network error occurred', { originalError }),
+    timeout: (originalError) => new DataError(DataErrorType.TIMEOUT_ERROR, 'Request timed out', { originalError }),
+    unauthorized: (message = 'Authentication required') => new DataError(DataErrorType.UNAUTHORIZED, message),
+    forbidden: (message = 'Access forbidden') => new DataError(DataErrorType.FORBIDDEN, message),
+    badRequest: (message, code) => new DataError(DataErrorType.BAD_REQUEST, message, { code }),
+    notFound: (message = 'Resource not found') => new DataError(DataErrorType.NOT_FOUND, message),
+    graphql: (message, code) => new DataError(DataErrorType.GRAPHQL_ERROR, message, { code }),
+    uniqueViolation: (message, fieldName, constraint) => new DataError(DataErrorType.UNIQUE_VIOLATION, message, { fieldName, constraint, code: '23505' }),
+    foreignKeyViolation: (message, fieldName, constraint) => new DataError(DataErrorType.FOREIGN_KEY_VIOLATION, message, { fieldName, constraint, code: '23503' }),
+    notNullViolation: (message, fieldName, constraint) => new DataError(DataErrorType.NOT_NULL_VIOLATION, message, { fieldName, constraint, code: '23502' }),
+    unknown: (originalError) => new DataError(DataErrorType.UNKNOWN_ERROR, originalError.message, { originalError }),
+};
+function parseGraphQLErrorCode(code) {
+    if (!code)
+        return DataErrorType.UNKNOWN_ERROR;
+    const normalized = code.toUpperCase();
+    // GraphQL standard codes
+    if (normalized === 'UNAUTHENTICATED')
+        return DataErrorType.UNAUTHORIZED;
+    if (normalized === 'FORBIDDEN')
+        return DataErrorType.FORBIDDEN;
+    if (normalized === 'GRAPHQL_VALIDATION_FAILED')
+        return DataErrorType.QUERY_GENERATION_FAILED;
+    // PostgreSQL SQLSTATE codes
+    if (code === PG_ERROR_CODES.UNIQUE_VIOLATION)
+        return DataErrorType.UNIQUE_VIOLATION;
+    if (code === PG_ERROR_CODES.FOREIGN_KEY_VIOLATION)
+        return DataErrorType.FOREIGN_KEY_VIOLATION;
+    if (code === PG_ERROR_CODES.NOT_NULL_VIOLATION)
+        return DataErrorType.NOT_NULL_VIOLATION;
+    if (code === PG_ERROR_CODES.CHECK_VIOLATION)
+        return DataErrorType.CHECK_VIOLATION;
+    if (code === PG_ERROR_CODES.EXCLUSION_VIOLATION)
+        return DataErrorType.EXCLUSION_VIOLATION;
+    return DataErrorType.UNKNOWN_ERROR;
+}
+function classifyByMessage(message) {
+    const lower = message.toLowerCase();
+    if (lower.includes('timeout') || lower.includes('timed out')) {
+        return DataErrorType.TIMEOUT_ERROR;
+    }
+    if (lower.includes('network') || lower.includes('fetch') || lower.includes('failed to fetch')) {
+        return DataErrorType.NETWORK_ERROR;
+    }
+    if (lower.includes('unauthorized') || lower.includes('authentication required')) {
+        return DataErrorType.UNAUTHORIZED;
+    }
+    if (lower.includes('forbidden') || lower.includes('permission')) {
+        return DataErrorType.FORBIDDEN;
+    }
+    if (lower.includes('duplicate key') || lower.includes('already exists')) {
+        return DataErrorType.UNIQUE_VIOLATION;
+    }
+    if (lower.includes('foreign key constraint')) {
+        return DataErrorType.FOREIGN_KEY_VIOLATION;
+    }
+    if (lower.includes('not-null constraint') || lower.includes('null value in column')) {
+        return DataErrorType.NOT_NULL_VIOLATION;
+    }
+    return 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
+ */
+export 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 !== 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(DataErrorType.UNKNOWN_ERROR, message);
+}
+/**
+ * Check if value is a DataError
+ */
+export function isDataError(error) {
+    return error instanceof DataError;
+}

package/esm/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 {};

package/esm/client/execute.js

@@ -0,0 +1,120 @@
+/**
+ * GraphQL execution utilities
+ */
+import { print } from 'graphql';
+import { TypedDocumentString } from './typed-document';
+import { createError, parseGraphQLError } from './error';
+// ============================================================================
+// Helpers
+// ============================================================================
+function documentToString(document) {
+    if (typeof document === 'string')
+        return document;
+    if (document instanceof TypedDocumentString)
+        return document.toString();
+    // DocumentNode
+    if (document && typeof document === 'object' && 'kind' in document) {
+        return print(document);
+    }
+    throw createError.badRequest('Invalid GraphQL document');
+}
+// ============================================================================
+// Execute Function
+// ============================================================================
+/**
+ * Execute a GraphQL operation against an endpoint
+ */
+export async function execute(endpoint, document, variables, options = {}) {
+    const { headers = {}, timeout = 30000, signal } = options;
+    // Create timeout controller
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+    // Combine signals if provided
+    const combinedSignal = signal
+        ? AbortSignal.any([signal, controller.signal])
+        : controller.signal;
+    try {
+        const response = await fetch(endpoint, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Accept: 'application/graphql-response+json, application/json',
+                ...headers,
+            },
+            body: JSON.stringify({
+                query: documentToString(document),
+                ...(variables !== undefined && { variables }),
+            }),
+            signal: combinedSignal,
+        });
+        clearTimeout(timeoutId);
+        if (!response.ok) {
+            throw await handleHttpError(response);
+        }
+        const result = await response.json();
+        if (result.errors?.length) {
+            throw parseGraphQLError(result.errors[0]);
+        }
+        return result.data;
+    }
+    catch (error) {
+        clearTimeout(timeoutId);
+        if (error instanceof Error && error.name === 'AbortError') {
+            throw createError.timeout();
+        }
+        if (error instanceof Error && error.message.includes('fetch')) {
+            throw createError.network(error);
+        }
+        throw parseGraphQLError(error);
+    }
+}
+async function handleHttpError(response) {
+    const { status, statusText } = response;
+    if (status === 401) {
+        return createError.unauthorized('Authentication required');
+    }
+    if (status === 403) {
+        return createError.forbidden('Access forbidden');
+    }
+    if (status === 404) {
+        return createError.notFound('GraphQL endpoint not found');
+    }
+    // Try to extract error from response body
+    try {
+        const body = await response.json();
+        if (body.errors?.length) {
+            return parseGraphQLError(body.errors[0]);
+        }
+        if (body.message) {
+            return createError.badRequest(body.message);
+        }
+    }
+    catch {
+        // Couldn't parse response
+    }
+    return createError.badRequest(`Request failed: ${status} ${statusText}`);
+}
+/**
+ * Create a GraphQL client instance
+ */
+export function createGraphQLClient(options) {
+    const { endpoint, headers: defaultHeaders = {}, timeout: defaultTimeout = 30000 } = options;
+    return {
+        /**
+         * Execute a GraphQL operation
+         */
+        async execute(document, variables, options = {}) {
+            return execute(endpoint, document, variables, {
+                headers: { ...defaultHeaders, ...options.headers },
+                timeout: options.timeout ?? defaultTimeout,
+                signal: options.signal,
+            });
+        },
+        /**
+         * Get the endpoint URL
+         */
+        getEndpoint() {
+            return endpoint;
+        },
+    };
+}

package/esm/client/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Client exports
+ */
+export { TypedDocumentString, type DocumentTypeDecoration } from './typed-document';
+export { DataError, DataErrorType, createError, parseGraphQLError, isDataError, PG_ERROR_CODES, type DataErrorOptions, type GraphQLError, } from './error';
+export { execute, createGraphQLClient, type ExecuteOptions, type GraphQLClientOptions, type GraphQLClient, type GraphQLResponse, } from './execute';

package/esm/client/index.js

@@ -0,0 +1,6 @@
+/**
+ * Client exports
+ */
+export { TypedDocumentString } from './typed-document';
+export { DataError, DataErrorType, createError, parseGraphQLError, isDataError, PG_ERROR_CODES, } from './error';
+export { execute, createGraphQLClient, } from './execute';

package/esm/client/typed-document.d.ts

@@ -0,0 +1,31 @@
+/**
+ * TypedDocumentString - Type-safe wrapper for GraphQL documents
+ * Compatible with GraphQL codegen client preset
+ */
+/**
+ * Document type decoration interface (from @graphql-typed-document-node/core)
+ */
+export interface DocumentTypeDecoration<TResult, TVariables> {
+    /**
+     * This type is used to ensure that the variables you pass in to the query are assignable to Variables
+     * and that the Result is assignable to whatever you pass your result to.
+     */
+    __apiType?: (variables: TVariables) => TResult;
+}
+/**
+ * Enhanced TypedDocumentString with type inference capabilities
+ * Compatible with GraphQL codegen client preset
+ */
+export declare class TypedDocumentString<TResult = unknown, TVariables = unknown> extends String implements DocumentTypeDecoration<TResult, TVariables> {
+    /** Same shape as the codegen implementation for structural typing */
+    __apiType?: (variables: TVariables) => TResult;
+    __meta__?: Record<string, unknown>;
+    private value;
+    constructor(value: string, meta?: Record<string, unknown>);
+    private generateHash;
+    toString(): string;
+    /**
+     * Get the hash for caching purposes
+     */
+    getHash(): string;
+}

package/esm/client/typed-document.js

@@ -0,0 +1,40 @@
+/**
+ * TypedDocumentString - Type-safe wrapper for GraphQL documents
+ * Compatible with GraphQL codegen client preset
+ */
+/**
+ * Enhanced TypedDocumentString with type inference capabilities
+ * Compatible with GraphQL codegen client preset
+ */
+export class TypedDocumentString extends String {
+    /** Same shape as the codegen implementation for structural typing */
+    __apiType;
+    __meta__;
+    value;
+    constructor(value, meta) {
+        super(value);
+        this.value = value;
+        this.__meta__ = {
+            hash: this.generateHash(value),
+            ...meta,
+        };
+    }
+    generateHash(value) {
+        let hash = 0;
+        for (let i = 0; i < value.length; i++) {
+            const char = value.charCodeAt(i);
+            hash = (hash << 5) - hash + char;
+            hash = hash & hash; // Convert to 32-bit integer
+        }
+        return Math.abs(hash).toString(36);
+    }
+    toString() {
+        return this.value;
+    }
+    /**
+     * Get the hash for caching purposes
+     */
+    getHash() {
+        return this.__meta__?.hash;
+    }
+}

package/esm/core/ast.d.ts

@@ -0,0 +1,10 @@
+import type { DocumentNode, FieldNode } from 'graphql';
+import type { ASTFunctionParams, QueryFieldSelection, MutationASTParams } from './types';
+export declare const getAll: ({ queryName, operationName, selection, }: ASTFunctionParams) => DocumentNode;
+export declare const getCount: ({ queryName, operationName, query, }: Omit<ASTFunctionParams, "selection">) => DocumentNode;
+export declare const getMany: ({ builder, queryName, operationName, query, selection, }: ASTFunctionParams) => DocumentNode;
+export declare const getOne: ({ queryName, operationName, query, selection, }: ASTFunctionParams) => DocumentNode;
+export declare const createOne: ({ mutationName, operationName, mutation, selection, }: MutationASTParams) => DocumentNode;
+export declare const patchOne: ({ mutationName, operationName, mutation, selection, }: MutationASTParams) => DocumentNode;
+export declare const deleteOne: ({ mutationName, operationName, mutation, }: Omit<MutationASTParams, "selection">) => DocumentNode;
+export declare function getSelections(selection?: QueryFieldSelection[]): FieldNode[];