Unified Error Handling System

.
├── types/
│   └── errors.ts       # Error-related TypeScript types
├── lib/
│   └── errors.ts       # Core error system implementation
└── locales/
    ├── en/
    │   └── errors.json # English error messages
    └── zh/
        └── errors.json # Chinese error messages

export interface ErrorMetadata {
  /** The ID of the user associated with the error */
  userId?: string;

  /** The ID of the specific resource involved */
  resourceId?: string;

  /** The type of the resource involved */
  resourceType?: string;

  /** Unique identifier for request tracing */
  traceId?: string;

  /** The specific action or operation that failed */
  action?: string;

  /** Timestamp when the error occurred */
  createdAt?: string;
}

import { ErrorMetadata } from "@/types/errors";

// Central Error Dictionary
export const ErrorMap = {
  // 400 Bad Request
  INVALID_INPUT: {
    errorCode: 40001,
    httpStatus: 400,
    category: "BAD_REQUEST",
    message: "The provided input is invalid.",
  },
  // 401 Unauthorized
  TOKEN_EXPIRED: {
    errorCode: 40101,
    httpStatus: 401,
    category: "UNAUTHORIZED",
    message: "Authentication token has expired.",
  },
  INVALID_TOKEN: {
    errorCode: 40102,
    httpStatus: 401,
    category: "UNAUTHORIZED",
    message: "Invalid or tampered authentication token.",
  },
  // 403 Forbidden
  INSUFFICIENT_PERMISSIONS: {
    errorCode: 40301,
    httpStatus: 403,
    category: "FORBIDDEN",
    message: "User lacks required permissions for this action.",
  },
  // 404 Not Found
  RESOURCE_NOT_FOUND: {
    errorCode: 40401,
    httpStatus: 404,
    category: "NOT_FOUND",
    message: "The requested resource could not be found.",
  },
  // 500 Internal Server Error
  DATABASE_CONNECTION_FAILED: {
    errorCode: 50001,
    httpStatus: 500,
    category: "INTERNAL_SERVER_ERROR",
    message: "Failed to establish a connection to the database.",
  },
  // 503 Service Unavailable
  AI_SERVICE_ERROR: {
    errorCode: 50301,
    httpStatus: 503,
    category: "SERVICE_UNAVAILABLE",
    message: "The third-party AI service failed to respond.",
  },
} as const;

export type ReasonCode = keyof typeof ErrorMap;

interface AppErrorOptions {
  metadata?: ErrorMetadata;
  cause?: unknown;
}

// Custom AppError Class
export class AppError extends Error {
  public readonly reason: ReasonCode;
  public readonly errorCode: number;
  public readonly httpStatus: number;
  public readonly category: string;
  public readonly metadata: ErrorMetadata;
  public readonly cause?: unknown;

  constructor(reason: ReasonCode, options: AppErrorOptions = {}) {
    const errorDefinition = ErrorMap[reason];

    super(errorDefinition.message);
    this.name = "AppError";

    // Load static properties from ErrorMap
    this.reason = reason;
    this.errorCode = errorDefinition.errorCode;
    this.httpStatus = errorDefinition.httpStatus;
    this.category = errorDefinition.category;

    // Set dynamic properties
    this.metadata = options.metadata ?? {};
    this.cause = options.cause;
    this.metadata.createdAt = new Date().toISOString();

    // Maintain proper stack trace
    if (Error.captureStackTrace) {
      Error.captureStackTrace(this, AppError);
    }
  }
}