feat(errors): Introduce ClientError and ServerError classes

- Added ClientError class for handling 4xx client errors with enhanced toString method for better error reporting in production and development environments.
- Introduced ServerError class for managing 5xx server errors, including detailed response body handling for non-production environments.
- Deprecated ApiError in favor of ClientError for improved clarity and consistency.
- Updated defaultFetcher and effectErrorHandler to utilize new error classes, ensuring better error management across the application.

This update enhances error handling capabilities and improves the overall robustness of the application.

Author: Palbahngmiyine

src/errors/defaultError.ts

@@ -82,13 +82,41 @@ export class NetworkError extends Data.TaggedError('NetworkError')<{
   }
 }
 
-export class ApiError extends Data.TaggedError('ApiError')<{
+// 4xx 클라이언트 에러용
+export class ClientError extends Data.TaggedError('ClientError')<{
   readonly errorCode: string;
   readonly errorMessage: string;
   readonly httpStatus: number;
   readonly url?: string;
 }> {
   toString(): string {
-    return `${this.errorCode}: ${this.errorMessage}`;
+    if (process.env.NODE_ENV === 'production') {
+      return `${this.errorCode}: ${this.errorMessage}`;
+    }
+    return `ClientError(${this.httpStatus}): ${this.errorCode} - ${this.errorMessage}\nURL: ${this.url}`;
+  }
+}
+
+/** @deprecated Use ClientError instead */
+export const ApiError = ClientError;
+/** @deprecated Use ClientError instead */
+export type ApiError = ClientError;
+
+// 5xx 서버 에러용
+export class ServerError extends Data.TaggedError('ServerError')<{
+  readonly errorCode: string;
+  readonly errorMessage: string;
+  readonly httpStatus: number;
+  readonly url?: string;
+  readonly responseBody?: string;
+}> {
+  toString(): string {
+    const isProduction = process.env.NODE_ENV === 'production';
+    if (isProduction) {
+      return `ServerError(${this.httpStatus}): ${this.errorCode} - ${this.errorMessage}`;
+    }
+    return `ServerError(${this.httpStatus}): ${this.errorCode} - ${this.errorMessage}
+URL: ${this.url}
+Response: ${this.responseBody?.substring(0, 500) ?? '(empty)'}`;
   }
 }

src/lib/defaultFetcher.ts

@@ -1,9 +1,10 @@
 import {Data, Effect, Match, pipe, Schedule} from 'effect';
 import {
-  ApiError,
+  ClientError,
   DefaultError,
   ErrorResponse,
   NetworkError,
+  ServerError,
 } from '../errors/defaultError';
 import getAuthInfo, {AuthenticationParameter} from './authenticator';
 import {runSafePromise} from './effectErrorHandler';
@@ -51,7 +52,7 @@ const handleClientErrorResponse = (res: Response) =>
     }),
     Effect.flatMap(error =>
       Effect.fail(
-        new ApiError({
+        new ClientError({
           errorCode: error.errorCode,
           errorMessage: error.errorMessage,
           httpStatus: res.status,
@@ -75,18 +76,38 @@ const handleServerErrorResponse = (res: Response) =>
           },
         }),
     }),
-    Effect.flatMap(text =>
-      Effect.fail(
-        new DefaultError({
-          errorCode: 'UnknownError',
-          errorMessage: text,
-          context: {
-            responseStatus: res.status,
-            responseUrl: res.url,
-          },
+    Effect.flatMap(text => {
+      const isProduction = process.env.NODE_ENV === 'production';
+
+      // JSON 파싱 시도
+      try {
+        const json = JSON.parse(text) as Partial<ErrorResponse>;
+        if (json.errorCode && json.errorMessage) {
+          return Effect.fail(
+            new ServerError({
+              errorCode: json.errorCode,
+              errorMessage: json.errorMessage,
+              httpStatus: res.status,
+              url: res.url,
+              responseBody: isProduction ? undefined : text,
+            }),
+          );
+        }
+      } catch {
+        // JSON 파싱 실패 시 무시하고 fallback
+      }
+
+      // JSON이 아니거나 필드가 없는 경우
+      return Effect.fail(
+        new ServerError({
+          errorCode: `HTTP_${res.status}`,
+          errorMessage: text.substring(0, 200) || 'Server error occurred',
+          httpStatus: res.status,
+          url: res.url,
+          responseBody: isProduction ? undefined : text,
         }),
-      ),
-    ),
+      );
+    }),
   );
 
 /**

src/lib/effectErrorHandler.ts

@@ -23,7 +23,10 @@ export const formatError = (error: unknown): string => {
   if (error instanceof EffectError.NetworkError) {
     return error.toString();
   }
-  if (error instanceof EffectError.ApiError) {
+  if (error instanceof EffectError.ClientError) {
+    return error.toString();
+  }
+  if (error instanceof EffectError.ServerError) {
     return error.toString();
   }
   if (error instanceof VariableValidationError) {
@@ -65,7 +68,11 @@ export const runSafeSync = <E, A>(effect: Effect.Effect<A, E>): A => {
         if (firstDefect instanceof Error) {
           throw firstDefect;
         }
-        throw new Error(`Uncaught defect: ${String(firstDefect)}`);
+        const isProduction = process.env.NODE_ENV === 'production';
+        const message = isProduction
+          ? `Unexpected error: ${String(firstDefect)}`
+          : `Unexpected error: ${String(firstDefect)}\nCause: ${Cause.pretty(cause)}`;
+        throw new Error(message);
       }
       throw new Error(`Unhandled Exit: ${Cause.pretty(cause)}`);
     },
@@ -94,10 +101,12 @@ export const runSafePromise = <E, A>(
             // 원본 Error 객체를 그대로 반환
             return Promise.reject(firstDefect);
           }
-          // Error 객체가 아니면 새로 생성
-          return Promise.reject(
-            new Error(`Uncaught defect: ${String(firstDefect)}`),
-          );
+          // Error 객체가 아니면 환경에 따라 상세 정보 포함
+          const isProduction = process.env.NODE_ENV === 'production';
+          const message = isProduction
+            ? `Unexpected error: ${String(firstDefect)}`
+            : `Unexpected error: ${String(firstDefect)}\nCause: ${Cause.pretty(cause)}`;
+          return Promise.reject(new Error(message));
         }
 
         // 3. 그 외 (예: 중단)의 경우, Cause를 문자열로 변환하여 반환
@@ -147,10 +156,10 @@ export const toCompatibleError = (effectError: unknown): Error => {
     return error;
   }
 
-  // ApiError 보존
-  if (effectError instanceof EffectError.ApiError) {
+  // ClientError 보존 (하위 호환성을 위해 error.name은 'ApiError' 유지)
+  if (effectError instanceof EffectError.ClientError) {
     const error = new Error(effectError.toString());
-    error.name = 'ApiError';
+    error.name = 'ApiError'; // 하위 호환성
     Object.defineProperties(error, {
       errorCode: {
         value: effectError.errorCode,
@@ -175,6 +184,43 @@ export const toCompatibleError = (effectError: unknown): Error => {
     return error;
   }
 
+  // ServerError 보존
+  if (effectError instanceof EffectError.ServerError) {
+    const error = new Error(effectError.toString());
+    error.name = 'ServerError';
+    const props: PropertyDescriptorMap = {
+      errorCode: {
+        value: effectError.errorCode,
+        writable: false,
+        enumerable: true,
+      },
+      errorMessage: {
+        value: effectError.errorMessage,
+        writable: false,
+        enumerable: true,
+      },
+      httpStatus: {
+        value: effectError.httpStatus,
+        writable: false,
+        enumerable: true,
+      },
+      url: {value: effectError.url, writable: false, enumerable: true},
+    };
+    // 개발환경에서만 responseBody 포함
+    if (!isProduction && effectError.responseBody) {
+      props.responseBody = {
+        value: effectError.responseBody,
+        writable: false,
+        enumerable: true,
+      };
+    }
+    Object.defineProperties(error, props);
+    if (isProduction) {
+      delete (error as Error).stack;
+    }
+    return error;
+  }
+
   // DefaultError 보존
   if (effectError instanceof EffectError.DefaultError) {
     const error = new Error(effectError.toString());