@constructive-io/graphql-query 3.2.5 → 3.3.0

package/custom-ast.d.ts

@@ -1,9 +1,14 @@
-import type { CleanField, MetaField } from './types';
-export declare function getCustomAst(fieldDefn?: MetaField): any;
+import type { FieldNode } from 'graphql';
+import type { CleanField } from './types/schema';
+import type { MetaField } from './types';
+/**
+ * Get custom AST for MetaField type - handles PostgreSQL types that need subfield selections
+ */
+export declare function getCustomAst(fieldDefn?: MetaField): FieldNode | null;
 /**
  * Generate custom AST for CleanField type - handles GraphQL types that need subfield selections
  */
-export declare function getCustomAstForCleanField(field: CleanField): any;
+export declare function getCustomAstForCleanField(field: CleanField): FieldNode;
 /**
  * Check if a CleanField requires subfield selection based on its GraphQL type
  */
@@ -11,11 +16,20 @@ export declare function requiresSubfieldSelection(field: CleanField): boolean;
 /**
  * Generate AST for GeometryPoint type
  */
-export declare function geometryPointAst(name: string): any;
+export declare function geometryPointAst(name: string): FieldNode;
 /**
  * Generate AST for GeometryGeometryCollection type
  */
-export declare function geometryCollectionAst(name: string): any;
-export declare function geometryAst(name: string): any;
-export declare function intervalAst(name: string): any;
-export declare function isIntervalType(obj: any): boolean;
+export declare function geometryCollectionAst(name: string): FieldNode;
+/**
+ * Generate AST for generic geometry type (returns geojson)
+ */
+export declare function geometryAst(name: string): FieldNode;
+/**
+ * Generate AST for interval type
+ */
+export declare function intervalAst(name: string): FieldNode;
+/**
+ * Check if an object has interval type shape
+ */
+export declare function isIntervalType(obj: unknown): boolean;

package/custom-ast.js

@@ -43,6 +43,9 @@ exports.intervalAst = intervalAst;
 exports.isIntervalType = isIntervalType;
 const t = __importStar(require("gql-ast"));
 const graphql_1 = require("graphql");
+/**
+ * Get custom AST for MetaField type - handles PostgreSQL types that need subfield selections
+ */
 function getCustomAst(fieldDefn) {
     if (!fieldDefn) {
         return null;
@@ -152,6 +155,7 @@ function geometryCollectionAst(name) {
                 t.field({
                     name: 'geometries',
                     selectionSet: t.selectionSet({
+                        // eslint-disable-next-line @typescript-eslint/no-explicit-any
                         selections: [inlineFragment], // gql-ast limitation with inline fragments
                     }),
                 }),
@@ -159,6 +163,9 @@ function geometryCollectionAst(name) {
         }),
     });
 }
+/**
+ * Generate AST for generic geometry type (returns geojson)
+ */
 function geometryAst(name) {
     return t.field({
         name,
@@ -167,6 +174,9 @@ function geometryAst(name) {
         }),
     });
 }
+/**
+ * Generate AST for interval type
+ */
 function intervalAst(name) {
     return t.field({
         name,
@@ -185,6 +195,11 @@ function intervalAst(name) {
 function toFieldArray(strArr) {
     return strArr.map((fieldName) => t.field({ name: fieldName }));
 }
+/**
+ * Check if an object has interval type shape
+ */
 function isIntervalType(obj) {
-    return ['days', 'hours', 'minutes', 'months', 'seconds', 'years'].every((key) => obj.hasOwnProperty(key));
+    if (!obj || typeof obj !== 'object')
+        return false;
+    return ['days', 'hours', 'minutes', 'months', 'seconds', 'years'].every((key) => Object.prototype.hasOwnProperty.call(obj, key));
 }

package/esm/ast.js

@@ -1,6 +1,6 @@
 import * as t from 'gql-ast';
-import { OperationTypeNode, } from 'graphql';
-import { camelize, singularize } from 'inflection';
+import { OperationTypeNode } from 'graphql';
+import { camelize, singularize } from 'inflekt';
 import { getCustomAst } from './custom-ast';
 const NON_MUTABLE_PROPS = ['createdAt', 'createdBy', 'updatedAt', 'updatedBy'];
 const objectToArray = (obj) => Object.keys(obj).map((k) => ({
@@ -48,7 +48,7 @@ const createGqlMutation = ({ operationName, mutationName, selectArgs, selections
         ],
     });
 };
-export const getAll = ({ queryName, operationName, query: _query, selection, }) => {
+export const getAll = ({ queryName, operationName, selection, }) => {
     const selections = getSelections(selection);
     const opSel = [
         t.field({
@@ -170,7 +170,10 @@ export const getMany = ({ builder, queryName, operationName, query, selection, }
         t.argument({ name: 'offset', value: t.variable({ name: 'offset' }) }),
         t.argument({ name: 'after', value: t.variable({ name: 'after' }) }),
         t.argument({ name: 'before', value: t.variable({ name: 'before' }) }),
-        t.argument({ name: 'condition', value: t.variable({ name: 'condition' }) }),
+        t.argument({
+            name: 'condition',
+            value: t.variable({ name: 'condition' }),
+        }),
         t.argument({ name: 'filter', value: t.variable({ name: 'filter' }) }),
         t.argument({ name: 'orderBy', value: t.variable({ name: 'orderBy' }) }),
     ];
@@ -419,9 +422,21 @@ export const deleteOne = ({ mutationName, operationName, mutation, }) => {
 };
 export function getSelections(selection = []) {
     const selectionAst = (field) => {
-        return typeof field === 'string'
-            ? t.field({ name: field })
-            : getCustomAst(field.fieldDefn) || t.field({ name: field.name });
+        if (typeof field === 'string') {
+            return t.field({ name: field });
+        }
+        // Check if fieldDefn has MetaField shape (has type.pgType)
+        const fieldDefn = field.fieldDefn;
+        if (fieldDefn &&
+            'type' in fieldDefn &&
+            fieldDefn.type &&
+            typeof fieldDefn.type === 'object' &&
+            'pgType' in fieldDefn.type) {
+            const customAst = getCustomAst(fieldDefn);
+            if (customAst)
+                return customAst;
+        }
+        return t.field({ name: field.name });
     };
     return selection
         .map((selectionDefn) => {

package/esm/client/error.js

@@ -0,0 +1,271 @@
+/**
+ * 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.js

@@ -0,0 +1,120 @@
+/**
+ * GraphQL execution utilities
+ */
+import { print } from 'graphql';
+import { createError, parseGraphQLError } from './error';
+import { TypedDocumentString } from './typed-document';
+// ============================================================================
+// 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.js

@@ -0,0 +1,8 @@
+/**
+ * Client barrel export
+ *
+ * Re-exports client utilities for GraphQL execution and error handling.
+ */
+export { TypedDocumentString, } from './typed-document';
+export { DataError, DataErrorType, PG_ERROR_CODES, createError, parseGraphQLError, isDataError, } from './error';
+export { execute, createGraphQLClient, } from './execute';

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/custom-ast.js

@@ -1,5 +1,8 @@
 import * as t from 'gql-ast';
 import { Kind } from 'graphql';
+/**
+ * Get custom AST for MetaField type - handles PostgreSQL types that need subfield selections
+ */
 export function getCustomAst(fieldDefn) {
     if (!fieldDefn) {
         return null;
@@ -109,6 +112,7 @@ export function geometryCollectionAst(name) {
                 t.field({
                     name: 'geometries',
                     selectionSet: t.selectionSet({
+                        // eslint-disable-next-line @typescript-eslint/no-explicit-any
                         selections: [inlineFragment], // gql-ast limitation with inline fragments
                     }),
                 }),
@@ -116,6 +120,9 @@ export function geometryCollectionAst(name) {
         }),
     });
 }
+/**
+ * Generate AST for generic geometry type (returns geojson)
+ */
 export function geometryAst(name) {
     return t.field({
         name,
@@ -124,6 +131,9 @@ export function geometryAst(name) {
         }),
     });
 }
+/**
+ * Generate AST for interval type
+ */
 export function intervalAst(name) {
     return t.field({
         name,
@@ -142,6 +152,11 @@ export function intervalAst(name) {
 function toFieldArray(strArr) {
     return strArr.map((fieldName) => t.field({ name: fieldName }));
 }
+/**
+ * Check if an object has interval type shape
+ */
 export function isIntervalType(obj) {
-    return ['days', 'hours', 'minutes', 'months', 'seconds', 'years'].every((key) => obj.hasOwnProperty(key));
+    if (!obj || typeof obj !== 'object')
+        return false;
+    return ['days', 'hours', 'minutes', 'months', 'seconds', 'years'].every((key) => Object.prototype.hasOwnProperty.call(obj, key));
 }