@constructive-io/graphql-query 4.5.4 → 4.7.0

package/README.md

@@ -28,7 +28,7 @@ This package is the **canonical source** for PostGraphile query generation logic
 - **Mutation generators** — `buildPostGraphileCreate`, `buildPostGraphileUpdate`, `buildPostGraphileDelete`
 - **Introspection pipeline** — `inferTablesFromIntrospection` to convert a GraphQL schema into `CleanTable` metadata
 - **AST builders** — low-level `getAll`, `getMany`, `getOne`, `createOne`, `patchOne`, `deleteOne`
-- **Client utilities** — `TypedDocumentString`, `execute`, `DataError` for type-safe execution and error handling
+- **Client utilities** — `TypedDocumentString`, `execute`, and `@constructive-io/errors` re-exports (`ConstructiveError`, `parseGraphQLError`) for type-safe execution and error handling
 - **Naming helpers** — server-aware inflection functions that respect PostGraphile's schema naming
 
 All modules are **browser-safe** (no Node.js APIs). `@constructive-io/graphql-codegen` depends on this package for the core logic and adds Node.js-only features (CLI, file output, watch mode).
@@ -329,20 +329,36 @@ const { data, errors } = await client.execute(query, {
 
 ## Error Handling
 
+Error handling is backed by [`@constructive-io/errors`](../../packages/errors), the
+single source of truth for error codes, their public/internal class, message
+copy (i18n), and cross-source parsing. There is no separate client-side error
+catalog or message string-matching — the client re-exports the canonical
+`ConstructiveError`, `parse`, `format`, and helpers.
+
 ```ts
-import { DataError, parseGraphQLError, DataErrorType } from '@constructive-io/graphql-query';
+import {
+  ConstructiveError,
+  parseGraphQLError,
+  format,
+  isRetryable,
+} from '@constructive-io/graphql-query';
 
 try {
   const result = await client.execute(createQuery, { input: { user: { name: 'Alice' } } });
   if (result.errors) {
+    // Normalize any error into a ConstructiveError (machine code + context + class).
     const error = parseGraphQLError(result.errors[0]);
-    if (error.type === DataErrorType.UNIQUE_VIOLATION) {
-      console.log('Duplicate entry:', error.constraintName);
+    if (error.code === 'UNIQUE_VIOLATION') {
+      console.log('Duplicate entry:', error.context.constraint);
     }
   }
 } catch (err) {
-  if (err instanceof DataError) {
-    console.log(err.type, err.message);
+  if (err instanceof ConstructiveError) {
+    // Localized, user-facing copy for public codes; retry hint for transport errors.
+    console.log(err.code, format(err.code, err.context));
+    if (isRetryable(err)) {
+      // network/timeout/rate-limit — safe to retry
+    }
   }
 }
 ```
@@ -441,8 +457,8 @@ GraphQL Schema (introspection or _meta)
 | `TypedDocumentString` | Type-safe GraphQL document wrapper (compatible with codegen client) |
 | `createGraphQLClient(options)` | Create a typed GraphQL client |
 | `execute(url, query, variables, options?)` | Execute a GraphQL query |
-| `DataError` | Structured error class with PG SQLSTATE classification |
-| `parseGraphQLError(error)` | Parse raw GraphQL error into `DataError` |
+| `ConstructiveError` | Canonical error class (`code`, `context`, `class`, `http`) from `@constructive-io/errors` |
+| `parseGraphQLError(error)` | Parse any error (pg / GraphQL / message / SQLSTATE) into a `ConstructiveError` |
 
 ### Naming Helpers
 
@@ -504,6 +520,7 @@ Common issues and solutions for pgpm, PostgreSQL, and testing.
 ### 🧪 Testing
 
 * [pgsql-test](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-test): **📊 Isolated testing environments** with per-test transaction rollbacks—ideal for integration tests, complex migrations, and RLS simulation.
+* [pglite-test](https://github.com/constructive-io/constructive/tree/main/postgres/pglite-test): **🪶 Drop-in pgsql-test replacement backed by PGlite** — in-process Postgres, no server required, instance-per-suite isolation.
 * [pgsql-seed](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-seed): **🌱 PostgreSQL seeding utilities** for CSV, JSON, SQL data loading, and pgpm deployment.
 * [supabase-test](https://github.com/constructive-io/constructive/tree/main/postgres/supabase-test): **🧪 Supabase-native test harness** preconfigured for the local Supabase stack—per-test rollbacks, JWT/role context helpers, and CI/GitHub Actions ready.
 * [graphile-test](https://github.com/constructive-io/constructive/tree/main/graphile/graphile-test): **🔐 Authentication mocking** for Graphile-focused test helpers and emulating row-level security contexts.

package/client/error.d.ts

@@ -1,83 +1,21 @@
 /**
- * Error handling for GraphQL operations
- * Provides consistent error types and parsing for PostGraphile responses
+ * Error handling for GraphQL operations.
+ *
+ * This is a thin client-side adapter over the canonical `@constructive-io/errors`
+ * package. The package owns the single source of truth for error codes, their
+ * public/internal class, message copy (i18n), and cross-source parsing (pg
+ * `DatabaseError`, GraphQL `extensions`, structured `DETAIL`, message tokens,
+ * and native SQLSTATE). There is no separate client-side error catalog or
+ * message string-matching anymore.
  */
-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;
-};
+import { ConstructiveError } from '@constructive-io/errors';
+export { ConstructiveError, classify, format, isPublicCode, parse, type ErrorClass, type ErrorContext, type ParsedError, toError, } from '@constructive-io/errors';
+/** Shape of a single GraphQL error entry in a response `errors[]` array. */
 export interface GraphQLError {
     message: string;
     extensions?: {
         code?: string;
+        class?: string;
     } & Record<string, unknown>;
     locations?: Array<{
         line: number;
@@ -86,10 +24,28 @@ export interface GraphQLError {
     path?: Array<string | number>;
 }
 /**
- * Parse any error into a DataError
+ * Parse any error (pg error, GraphQL error/response, `ConstructiveError`, plain
+ * `Error`, or string) into a throwable {@link ConstructiveError}.
  */
-export declare function parseGraphQLError(error: unknown): DataError;
+export declare function parseGraphQLError(error: unknown, locale?: string): ConstructiveError;
+/** True when the value is a {@link ConstructiveError}. */
+export declare function isConstructiveError(error: unknown): error is ConstructiveError;
+/** Whether an error is safe to retry (network/timeout/rate-limit). */
+export declare function isRetryable(error: unknown): boolean;
 /**
- * Check if value is a DataError
+ * Factory for the transport/HTTP-level errors the client synthesizes itself
+ * (before any server/DB response is parsed). All produce a
+ * {@link ConstructiveError} from the canonical registry.
  */
-export declare function isDataError(error: unknown): error is DataError;
+export declare const createError: {
+    network: (originalError?: Error) => ConstructiveError;
+    timeout: () => ConstructiveError;
+    unauthorized: (message?: string) => ConstructiveError;
+    forbidden: (message?: string) => ConstructiveError;
+    notFound: (message?: string) => ConstructiveError;
+    badRequest: (message: string) => ConstructiveError;
+    graphql: (error: unknown) => ConstructiveError;
+    unknown: (originalError: Error) => ConstructiveError;
+};
+/** Whether an error is safe to surface to end users (public class). */
+export declare function isPublicError(error: unknown): boolean;

package/client/error.js

@@ -1,277 +1,67 @@
 "use strict";
 /**
- * Error handling for GraphQL operations
- * Provides consistent error types and parsing for PostGraphile responses
+ * Error handling for GraphQL operations.
+ *
+ * This is a thin client-side adapter over the canonical `@constructive-io/errors`
+ * package. The package owns the single source of truth for error codes, their
+ * public/internal class, message copy (i18n), and cross-source parsing (pg
+ * `DatabaseError`, GraphQL `extensions`, structured `DETAIL`, message tokens,
+ * and native SQLSTATE). There is no separate client-side error catalog or
+ * message string-matching anymore.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createError = exports.PG_ERROR_CODES = exports.DataError = exports.DataErrorType = void 0;
+exports.createError = exports.toError = exports.parse = exports.isPublicCode = exports.format = exports.classify = exports.ConstructiveError = 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',
-};
+exports.isConstructiveError = isConstructiveError;
+exports.isRetryable = isRetryable;
+exports.isPublicError = isPublicError;
+const errors_1 = require("@constructive-io/errors");
+var errors_2 = require("@constructive-io/errors");
+Object.defineProperty(exports, "ConstructiveError", { enumerable: true, get: function () { return errors_2.ConstructiveError; } });
+Object.defineProperty(exports, "classify", { enumerable: true, get: function () { return errors_2.classify; } });
+Object.defineProperty(exports, "format", { enumerable: true, get: function () { return errors_2.format; } });
+Object.defineProperty(exports, "isPublicCode", { enumerable: true, get: function () { return errors_2.isPublicCode; } });
+Object.defineProperty(exports, "parse", { enumerable: true, get: function () { return errors_2.parse; } });
+Object.defineProperty(exports, "toError", { enumerable: true, get: function () { return errors_2.toError; } });
 /**
- * Standard error class for data layer operations
+ * Parse any error (pg error, GraphQL error/response, `ConstructiveError`, plain
+ * `Error`, or string) into a throwable {@link ConstructiveError}.
  */
-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 parseGraphQLError(error, locale) {
+    return (0, errors_1.toError)(error, locale);
 }
-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;
+/** True when the value is a {@link ConstructiveError}. */
+function isConstructiveError(error) {
+    return error instanceof errors_1.ConstructiveError;
 }
-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;
+/** Codes worth automatically retrying (transient transport/rate failures). */
+const RETRYABLE_CODES = new Set([
+    'NETWORK_ERROR',
+    'TIMEOUT_ERROR',
+    'RATE_LIMITED',
+    'TOO_MANY_REQUESTS',
+]);
+/** Whether an error is safe to retry (network/timeout/rate-limit). */
+function isRetryable(error) {
+    const { code } = (0, errors_1.parse)(error);
+    return Boolean(code && RETRYABLE_CODES.has(code));
 }
 /**
- * Parse any error into a DataError
+ * Factory for the transport/HTTP-level errors the client synthesizes itself
+ * (before any server/DB response is parsed). All produce a
+ * {@link ConstructiveError} from the canonical registry.
  */
-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;
+exports.createError = {
+    network: (originalError) => errors_1.errors.NETWORK_ERROR({}, originalError?.message),
+    timeout: () => errors_1.errors.TIMEOUT_ERROR(),
+    unauthorized: (message = 'Authentication required') => errors_1.errors.UNAUTHENTICATED({}, message),
+    forbidden: (message = 'Access forbidden') => errors_1.errors.FORBIDDEN({}, message),
+    notFound: (message = 'Resource not found') => errors_1.errors.NOT_FOUND({}, message),
+    badRequest: (message) => errors_1.errors.BAD_USER_INPUT({}, message),
+    graphql: (error) => (0, errors_1.toError)(error),
+    unknown: (originalError) => (0, errors_1.toError)(originalError),
+};
+/** Whether an error is safe to surface to end users (public class). */
+function isPublicError(error) {
+    return (0, errors_1.isPublicCode)((0, errors_1.parse)(error).code);
 }

package/client/index.d.ts

@@ -4,5 +4,5 @@
  * Re-exports client utilities for GraphQL execution and error handling.
  */
 export { TypedDocumentString, type DocumentTypeDecoration, } from './typed-document';
-export { DataError, DataErrorType, PG_ERROR_CODES, createError, parseGraphQLError, isDataError, type DataErrorOptions, type GraphQLError, } from './error';
+export { ConstructiveError, classify, createError, format, isConstructiveError, isPublicCode, isPublicError, isRetryable, parse, parseGraphQLError, toError, type ErrorClass, type ErrorContext, type GraphQLError, type ParsedError, } from './error';
 export { execute, createGraphQLClient, type ExecuteOptions, type GraphQLResponse, type GraphQLClientOptions, type GraphQLClient, } from './execute';

package/client/index.js

@@ -5,16 +5,21 @@
  * Re-exports client utilities for GraphQL execution and error handling.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createGraphQLClient = exports.execute = exports.isDataError = exports.parseGraphQLError = exports.createError = exports.PG_ERROR_CODES = exports.DataErrorType = exports.DataError = exports.TypedDocumentString = void 0;
+exports.createGraphQLClient = exports.execute = exports.toError = exports.parseGraphQLError = exports.parse = exports.isRetryable = exports.isPublicError = exports.isPublicCode = exports.isConstructiveError = exports.format = exports.createError = exports.classify = exports.ConstructiveError = exports.TypedDocumentString = void 0;
 var typed_document_1 = require("./typed-document");
 Object.defineProperty(exports, "TypedDocumentString", { enumerable: true, get: function () { return typed_document_1.TypedDocumentString; } });
 var error_1 = require("./error");
-Object.defineProperty(exports, "DataError", { enumerable: true, get: function () { return error_1.DataError; } });
-Object.defineProperty(exports, "DataErrorType", { enumerable: true, get: function () { return error_1.DataErrorType; } });
-Object.defineProperty(exports, "PG_ERROR_CODES", { enumerable: true, get: function () { return error_1.PG_ERROR_CODES; } });
+Object.defineProperty(exports, "ConstructiveError", { enumerable: true, get: function () { return error_1.ConstructiveError; } });
+Object.defineProperty(exports, "classify", { enumerable: true, get: function () { return error_1.classify; } });
 Object.defineProperty(exports, "createError", { enumerable: true, get: function () { return error_1.createError; } });
+Object.defineProperty(exports, "format", { enumerable: true, get: function () { return error_1.format; } });
+Object.defineProperty(exports, "isConstructiveError", { enumerable: true, get: function () { return error_1.isConstructiveError; } });
+Object.defineProperty(exports, "isPublicCode", { enumerable: true, get: function () { return error_1.isPublicCode; } });
+Object.defineProperty(exports, "isPublicError", { enumerable: true, get: function () { return error_1.isPublicError; } });
+Object.defineProperty(exports, "isRetryable", { enumerable: true, get: function () { return error_1.isRetryable; } });
+Object.defineProperty(exports, "parse", { enumerable: true, get: function () { return error_1.parse; } });
 Object.defineProperty(exports, "parseGraphQLError", { enumerable: true, get: function () { return error_1.parseGraphQLError; } });
-Object.defineProperty(exports, "isDataError", { enumerable: true, get: function () { return error_1.isDataError; } });
+Object.defineProperty(exports, "toError", { enumerable: true, get: function () { return error_1.toError; } });
 var execute_1 = require("./execute");
 Object.defineProperty(exports, "execute", { enumerable: true, get: function () { return execute_1.execute; } });
 Object.defineProperty(exports, "createGraphQLClient", { enumerable: true, get: function () { return execute_1.createGraphQLClient; } });

package/esm/client/error.js

@@ -1,271 +1,54 @@
 /**
- * Error handling for GraphQL operations
- * Provides consistent error types and parsing for PostGraphile responses
+ * Error handling for GraphQL operations.
+ *
+ * This is a thin client-side adapter over the canonical `@constructive-io/errors`
+ * package. The package owns the single source of truth for error codes, their
+ * public/internal class, message copy (i18n), and cross-source parsing (pg
+ * `DatabaseError`, GraphQL `extensions`, structured `DETAIL`, message tokens,
+ * and native SQLSTATE). There is no separate client-side error catalog or
+ * message string-matching anymore.
  */
-// ============================================================================
-// 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',
-};
+import { ConstructiveError, errors, isPublicCode, parse, toError, } from '@constructive-io/errors';
+export { ConstructiveError, classify, format, isPublicCode, parse, toError, } from '@constructive-io/errors';
 /**
- * Standard error class for data layer operations
+ * Parse any error (pg error, GraphQL error/response, `ConstructiveError`, plain
+ * `Error`, or string) into a throwable {@link ConstructiveError}.
  */
-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;
+export function parseGraphQLError(error, locale) {
+    return toError(error, locale);
 }
-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;
+/** True when the value is a {@link ConstructiveError}. */
+export function isConstructiveError(error) {
+    return error instanceof ConstructiveError;
 }
-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;
+/** Codes worth automatically retrying (transient transport/rate failures). */
+const RETRYABLE_CODES = new Set([
+    'NETWORK_ERROR',
+    'TIMEOUT_ERROR',
+    'RATE_LIMITED',
+    'TOO_MANY_REQUESTS',
+]);
+/** Whether an error is safe to retry (network/timeout/rate-limit). */
+export function isRetryable(error) {
+    const { code } = parse(error);
+    return Boolean(code && RETRYABLE_CODES.has(code));
 }
 /**
- * Parse any error into a DataError
+ * Factory for the transport/HTTP-level errors the client synthesizes itself
+ * (before any server/DB response is parsed). All produce a
+ * {@link ConstructiveError} from the canonical registry.
  */
-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;
+export const createError = {
+    network: (originalError) => errors.NETWORK_ERROR({}, originalError?.message),
+    timeout: () => errors.TIMEOUT_ERROR(),
+    unauthorized: (message = 'Authentication required') => errors.UNAUTHENTICATED({}, message),
+    forbidden: (message = 'Access forbidden') => errors.FORBIDDEN({}, message),
+    notFound: (message = 'Resource not found') => errors.NOT_FOUND({}, message),
+    badRequest: (message) => errors.BAD_USER_INPUT({}, message),
+    graphql: (error) => toError(error),
+    unknown: (originalError) => toError(originalError),
+};
+/** Whether an error is safe to surface to end users (public class). */
+export function isPublicError(error) {
+    return isPublicCode(parse(error).code);
 }

package/esm/client/index.js

@@ -4,5 +4,5 @@
  * 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 { ConstructiveError, classify, createError, format, isConstructiveError, isPublicCode, isPublicError, isRetryable, parse, parseGraphQLError, toError, } from './error';
 export { execute, createGraphQLClient, } from './execute';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constructive-io/graphql-query",
-  "version": "4.5.4",
+  "version": "4.7.0",
   "description": "Constructive GraphQL Query",
   "author": "Constructive <developers@constructive.io>",
   "main": "index.js",
@@ -30,14 +30,15 @@
   },
   "dependencies": {
     "@0no-co/graphql.web": "^1.1.2",
+    "@constructive-io/errors": "^0.3.0",
     "@constructive-io/fetch": "^1.1.1",
-    "@constructive-io/graphql-types": "^3.22.0",
+    "@constructive-io/graphql-types": "^3.23.0",
     "ajv": "^8.20.0",
-    "gql-ast": "^3.17.0",
+    "gql-ast": "^3.18.0",
     "grafast": "1.0.2",
     "graphile-build-pg": "5.0.2",
     "graphile-config": "1.0.1",
-    "graphile-settings": "^6.5.4",
+    "graphile-settings": "^6.6.0",
     "graphql": "16.13.0",
     "inflection": "^3.0.0",
     "inflekt": "^0.7.1",
@@ -54,5 +55,5 @@
   "devDependencies": {
     "makage": "^0.3.0"
   },
-  "gitHead": "31f7cd3d3cc28cf069056eae5b2a0d4198d154a1"
+  "gitHead": "bb3269d48cdf2bc8f361bdd79b4833c921c13ec3"
 }