@smartsamurai/krapi-sdk/src/core/error-codes.ts

KRAPI TypeScript SDK - Easy-to-use client SDK for connecting to self-hosted KRAPI servers (like Appwrite SDK)

/**
 * Error Code Constants and Mappings
 *
 * Centralizes error code definitions and provides mappings for consistent
 * error code usage across the KRAPI SDK.
 */

import { ErrorCode } from "./krapi-error";

/**
 * Error code constants for consistent usage
 */
export const ERROR_CODES = {
  // Authentication & Authorization
  UNAUTHORIZED: "UNAUTHORIZED" as ErrorCode,
  FORBIDDEN: "FORBIDDEN" as ErrorCode,

  // Resource errors
  NOT_FOUND: "NOT_FOUND" as ErrorCode,
  CONFLICT: "CONFLICT" as ErrorCode,

  // Validation errors
  VALIDATION_ERROR: "VALIDATION_ERROR" as ErrorCode,
  BAD_REQUEST: "BAD_REQUEST" as ErrorCode,
  UNPROCESSABLE_ENTITY: "UNPROCESSABLE_ENTITY" as ErrorCode,

  // Network & Communication
  NETWORK_ERROR: "NETWORK_ERROR" as ErrorCode,
  TIMEOUT: "TIMEOUT" as ErrorCode,

  // Rate limiting
  RATE_LIMIT_EXCEEDED: "RATE_LIMIT_EXCEEDED" as ErrorCode,

  // Server & Service errors
  INTERNAL_ERROR: "INTERNAL_ERROR" as ErrorCode,
  SERVER_ERROR: "SERVER_ERROR" as ErrorCode,
  SERVICE_UNAVAILABLE: "SERVICE_UNAVAILABLE" as ErrorCode,

  // Request errors
  REQUEST_ERROR: "REQUEST_ERROR" as ErrorCode,
} as const;

/**
 * Map HTTP status codes to ErrorCode
 */
export const HTTP_STATUS_TO_ERROR_CODE: Record<number, ErrorCode> = {
  // 4xx Client Errors
  400: ERROR_CODES.BAD_REQUEST,
  401: ERROR_CODES.UNAUTHORIZED,
  403: ERROR_CODES.FORBIDDEN,
  404: ERROR_CODES.NOT_FOUND,
  409: ERROR_CODES.CONFLICT,
  422: ERROR_CODES.UNPROCESSABLE_ENTITY,
  429: ERROR_CODES.RATE_LIMIT_EXCEEDED,

  // 5xx Server Errors
  500: ERROR_CODES.INTERNAL_ERROR,
  502: ERROR_CODES.SERVER_ERROR,
  503: ERROR_CODES.SERVICE_UNAVAILABLE,
  504: ERROR_CODES.TIMEOUT,
};

/**
 * Map database error patterns to ErrorCode
 */
export const DATABASE_ERROR_PATTERNS: Array<{
  pattern: RegExp;
  code: ErrorCode;
}> = [
  { pattern: /unique.*constraint.*violated/i, code: ERROR_CODES.CONFLICT },
  { pattern: /foreign.*key.*constraint.*violated/i, code: ERROR_CODES.BAD_REQUEST },
  { pattern: /check.*constraint.*violated/i, code: ERROR_CODES.VALIDATION_ERROR },
  { pattern: /not.*null.*constraint.*violated/i, code: ERROR_CODES.VALIDATION_ERROR },
  { pattern: /connection.*timeout/i, code: ERROR_CODES.TIMEOUT },
  { pattern: /connection.*refused/i, code: ERROR_CODES.SERVICE_UNAVAILABLE },
  { pattern: /query.*timeout/i, code: ERROR_CODES.TIMEOUT },
];

/**
 * Map validation error types to ErrorCode
 */
export const VALIDATION_ERROR_TYPES: Record<string, ErrorCode> = {
  required: ERROR_CODES.VALIDATION_ERROR,
  type: ERROR_CODES.VALIDATION_ERROR,
  format: ERROR_CODES.VALIDATION_ERROR,
  enum: ERROR_CODES.VALIDATION_ERROR,
  minimum: ERROR_CODES.VALIDATION_ERROR,
  maximum: ERROR_CODES.VALIDATION_ERROR,
  minLength: ERROR_CODES.VALIDATION_ERROR,
  maxLength: ERROR_CODES.VALIDATION_ERROR,
  pattern: ERROR_CODES.VALIDATION_ERROR,
  unique: ERROR_CODES.CONFLICT,
};

/**
 * Get ErrorCode from HTTP status code
 *
 * @param status - HTTP status code
 * @returns Corresponding ErrorCode or undefined if not mapped
 */
export function getErrorCodeFromHttpStatus(status: number): ErrorCode | undefined {
  return HTTP_STATUS_TO_ERROR_CODE[status];
}

/**
 * Get ErrorCode from database error message
 *
 * @param message - Database error message
 * @returns Corresponding ErrorCode or undefined if not matched
 */
export function getErrorCodeFromDatabaseError(message: string): ErrorCode | undefined {
  for (const { pattern, code } of DATABASE_ERROR_PATTERNS) {
    if (pattern.test(message)) {
      return code;
    }
  }
  return undefined;
}

/**
 * Get ErrorCode from validation error type
 *
 * @param errorType - Validation error type
 * @returns Corresponding ErrorCode or undefined if not mapped
 */
export function getErrorCodeFromValidationType(errorType: string): ErrorCode | undefined {
  return VALIDATION_ERROR_TYPES[errorType];
}

/**
 * Error code descriptions for documentation
 */
export const ERROR_CODE_DESCRIPTIONS: Record<ErrorCode, string> = {
  UNAUTHORIZED: "Authentication is required or credentials are invalid",
  FORBIDDEN: "Access to the requested resource is forbidden",
  NOT_FOUND: "The requested resource was not found",
  CONFLICT: "The request conflicts with the current state of the resource",
  VALIDATION_ERROR: "The request data failed validation",
  BAD_REQUEST: "The request is malformed or contains invalid parameters",
  UNPROCESSABLE_ENTITY: "The request data is syntactically correct but semantically invalid",
  NETWORK_ERROR: "A network error occurred while processing the request",
  TIMEOUT: "The request timed out",
  RATE_LIMIT_EXCEEDED: "Too many requests have been made in a short period",
  INTERNAL_ERROR: "An internal server error occurred",
  SERVER_ERROR: "An external server error occurred",
  SERVICE_UNAVAILABLE: "The service is temporarily unavailable",
  REQUEST_ERROR: "An error occurred while processing the request",
};