@asapjs/error 1.0.0-alpha.0

package/README.md

@@ -0,0 +1,229 @@
+# @asapjs/error
+
+TypeScript 기반 ASAP.js 프레임워크를 위한 Effect 통합 에러 처리 패키지
+
+## 주요 기능
+
+- **TypeIs 기반 에러 정의**: 간단하고 타입 안전한 에러 생성
+- **자동 Swagger 문서화**: TypeIs 스키마로부터 OpenAPI 스펙 자동 생성
+- **Effect 라이브러리 통합**: stack-safe 로깅 및 구조화된 에러 처리
+- **레거시 호환성**: 기존 `HttpException` 지원
+
+## 설치
+
+```bash
+yarn add @asapjs/error effect
+```
+
+## 기본 사용법
+
+### 1. 에러 정의 (새로운 방식)
+
+```typescript
+import { error, TypeIs } from '@asapjs/error';
+
+export class UserErrors {
+  static NOT_FOUND = error(404, "USER_NOT_FOUND", "사용자를 찾을 수 없습니다. ID: {userId}", {
+    userId: TypeIs.INT({ comment: "사용자 ID" }),
+  });
+
+  static EMAIL_DUPLICATE = error(409, "USER_EMAIL_DUPLICATE", "이미 사용 중인 이메일입니다: {email}", {
+    email: TypeIs.STRING({ comment: "중복된 이메일" }),
+    existingUserId: TypeIs.INT({ comment: "기존 사용자 ID", optional: true }),
+  });
+
+  static INVALID_DATA = error(400, "USER_INVALID_DATA", "잘못된 사용자 데이터입니다", {
+    invalidFields: TypeIs.ARRAY({ 
+      type: () => TypeIs.STRING(), 
+      comment: "유효하지 않은 필드 목록" 
+    }),
+    details: TypeIs.JSON({ 
+      comment: "상세 오류 정보", 
+      optional: true 
+    }),
+  });
+}
+```
+
+### 2. 컨트롤러에서 사용
+
+```typescript
+import { Get, Post, RouterController } from '@asapjs/router';
+import { wrapWithEffect } from '@asapjs/error';
+import { UserErrors } from './errors/UserErrors';
+
+export default class UserController extends RouterController {
+  @Get('/:id', {
+    title: '사용자 조회',
+    errors: [UserErrors.NOT_FOUND], // Swagger에 자동으로 문서화
+  })
+  public getUser = wrapWithEffect(async ({ path }) => {
+    const user = await findUser(path.id);
+    if (!user) {
+      throw UserErrors.NOT_FOUND({ userId: path.id });
+    }
+    return { result: user };
+  });
+
+  @Post('/', {
+    title: '사용자 생성',
+    body: CreateUserDto,
+    errors: [UserErrors.EMAIL_DUPLICATE, UserErrors.INVALID_DATA],
+  })
+  public createUser = wrapWithEffect(async ({ body }) => {
+    // 이메일 검증
+    if (!isValidEmail(body.email)) {
+      throw UserErrors.INVALID_DATA({
+        invalidFields: ['email'],
+        details: { email: 'Invalid email format' }
+      });
+    }
+    
+    // 중복 체크
+    const existing = await findUserByEmail(body.email);
+    if (existing) {
+      throw UserErrors.EMAIL_DUPLICATE({ 
+        email: body.email,
+        existingUserId: existing.id 
+      });
+    }
+    
+    const user = await createUser(body);
+    return { result: user };
+  });
+}
+```
+
+### 3. Express 앱에 미들웨어 적용
+
+```typescript
+import { effectErrorHandler } from '@asapjs/error';
+
+app.use(effectErrorHandler);
+```
+
+## HTTP 에러 응답 포맷
+
+모든 에러는 다음과 같은 통일된 포맷으로 응답됩니다:
+
+```json
+{
+  "status": 404,
+  "errorCode": "USER_NOT_FOUND",
+  "message": "사용자를 찾을 수 없습니다. ID: 123",
+  "data": {
+    "userId": 123
+  }
+}
+```
+
+## 주요 특징
+
+### 1. TypeIs를 활용한 타입 안전성
+
+```typescript
+// 컴파일 타임에 타입 체크
+throw UserErrors.NOT_FOUND({ userId: "123" }); // ❌ Error: userId must be number
+throw UserErrors.NOT_FOUND({ userId: 123 });   // ✅ OK
+```
+
+### 2. 메시지 템플릿
+
+에러 메시지에 `{fieldName}` 형식으로 데이터를 삽입할 수 있습니다:
+
+```typescript
+static NOT_FOUND = error(404, "USER_NOT_FOUND", "사용자 {userId}를 찾을 수 없습니다", {
+  userId: TypeIs.INT(),
+});
+
+// 사용 시: "사용자 123를 찾을 수 없습니다"
+throw UserErrors.NOT_FOUND({ userId: 123 });
+```
+
+### 3. 자동 Swagger 문서화
+
+TypeIs 스키마가 자동으로 OpenAPI 스펙으로 변환됩니다:
+
+```yaml
+components:
+  schemas:
+    USER_NOT_FOUND:
+      type: object
+      properties:
+        status:
+          type: number
+          example: 404
+        errorCode:
+          type: string
+          example: USER_NOT_FOUND
+        message:
+          type: string
+        data:
+          type: object
+          properties:
+            userId:
+              type: integer
+              description: 사용자 ID
+```
+
+## TypeIs 지원 타입
+
+```typescript
+TypeIs.INT()           // 정수
+TypeIs.STRING()        // 문자열
+TypeIs.BOOLEAN()       // 불린
+TypeIs.FLOAT()         // 실수
+TypeIs.JSON()          // JSON 객체
+TypeIs.ARRAY()         // 배열
+TypeIs.DATETIME()      // 날짜/시간
+TypeIs.ENUM()          // 열거형
+```
+
+모든 타입은 `optional: true` 옵션을 지원합니다.
+
+## 고급 기능
+
+### Effect 래핑
+
+`wrapWithEffect`는 다음 기능을 제공합니다:
+
+- 자동 스팬 트레이싱
+- 구조화된 로깅 (요청 ID, 파일, 라인, 함수명 포함)
+- Effect Exit 처리
+
+### 레거시 호환성
+
+기존 `HttpException`을 사용하는 코드도 자동으로 처리됩니다:
+
+```typescript
+throw new HttpException(400, '잘못된 요청입니다');
+// 자동으로 { status: 400, errorCode: 'LEGACY_HTTP_EXCEPTION', message: '...' } 로 변환
+```
+
+## 마이그레이션 가이드
+
+### 기존 방식
+
+```typescript
+export class UserNotFoundError extends NotFoundError {
+  constructor(userId: number) {
+    super('USER_NOT_FOUND', `사용자를 찾을 수 없습니다. ID: ${userId}`, { userId });
+  }
+}
+
+throw new UserNotFoundError(123);
+```
+
+### 새로운 방식
+
+```typescript
+export class UserErrors {
+  static NOT_FOUND = error(404, "USER_NOT_FOUND", "사용자를 찾을 수 없습니다. ID: {userId}", {
+    userId: TypeIs.INT(),
+  });
+}
+
+throw UserErrors.NOT_FOUND({ userId: 123 });
+```
+
+새로운 방식은 더 간결하고, 타입 안전하며, 자동 문서화를 지원합니다.

package/dist/factory.d.ts

@@ -0,0 +1,15 @@
+import { HttpError } from './types';
+export interface ErrorCreator<T = any> {
+    (data: T): HttpError;
+    _status: number;
+    _code: string;
+    _message: string;
+    _schema: Record<string, any>;
+}
+export declare function error<T extends Record<string, any>>(status: number, code: string, message: string, schema: T): ErrorCreator<InferTypeFromSchema<T>>;
+export declare function setAddSchemeFunction(func: any): void;
+export declare function markSwaggerAsReady(): void;
+type InferTypeFromSchema<T extends Record<string, any>> = {
+    [K in keyof T]: any;
+};
+export {};

package/dist/factory.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.error = error;
+exports.setAddSchemeFunction = setAddSchemeFunction;
+exports.markSwaggerAsReady = markSwaggerAsReady;
+// addScheme will be injected at runtime
+let addSchemeFunc = () => { };
+const types_1 = require("./types");
+const schema_1 = require("./schema");
+// 지연 등록을 위한 큐
+const pendingSchemas = [];
+let isSwaggerReady = false;
+function error(status, code, message, schema) {
+    // Swagger 스키마 등록 (지연 실행)
+    const registerSchema = () => registerErrorSwaggerSchema(code, status, message, schema);
+    if (isSwaggerReady) {
+        registerSchema();
+    }
+    else {
+        pendingSchemas.push(registerSchema);
+    }
+    // 에러 생성 함수
+    const creator = ((data) => {
+        // 스키마 등록 확인 (첫 사용 시)
+        ensureSchemaRegistered(code, status, message, schema);
+        // 데이터 유효성 검사
+        (0, schema_1.validateDataWithSchema)(data, schema);
+        // 메시지 템플릿 처리 (예: "사용자 {userId}를 찾을 수 없습니다")
+        const finalMessage = interpolateMessage(message, data);
+        return new types_1.HttpError(status, code, finalMessage, data);
+    });
+    // 메타데이터 저장 (Swagger 문서화용)
+    creator._status = status;
+    creator._code = code;
+    creator._message = message;
+    // 원본 schema를 그대로 저장 (함수 호출 결과가 아닌 원본)
+    creator._schema = schema;
+    return creator;
+}
+// addScheme 함수 주입
+function setAddSchemeFunction(func) {
+    addSchemeFunc = func;
+}
+// Swagger가 준비되면 호출
+function markSwaggerAsReady() {
+    isSwaggerReady = true;
+    // 대기 중인 스키마 모두 등록
+    while (pendingSchemas.length > 0) {
+        const register = pendingSchemas.shift();
+        if (register)
+            register();
+    }
+}
+// 스키마가 등록되었는지 확인하고 필요시 등록
+const registeredSchemas = new Set();
+function ensureSchemaRegistered(code, status, message, schema) {
+    if (!registeredSchemas.has(code)) {
+        registerErrorSwaggerSchema(code, status, message, schema);
+        registeredSchemas.add(code);
+    }
+}
+function registerErrorSwaggerSchema(code, status, message, schema) {
+    const swaggerSchema = {
+        type: 'object',
+        properties: {
+            status: { type: 'number', example: status },
+            errorCode: { type: 'string', example: code },
+            message: { type: 'string', example: message },
+            data: {
+                type: 'object',
+                properties: Object.entries(schema).reduce((acc, [key, typeIs]) => {
+                    acc[key] = (0, schema_1.typeIsToSwaggerSchema)(typeIs);
+                    return acc;
+                }, {}),
+            },
+        },
+        required: ['status', 'errorCode', 'message'],
+    };
+    addSchemeFunc({
+        name: code,
+        data: swaggerSchema,
+    });
+}
+function interpolateMessage(template, data) {
+    return template.replace(/\{(\w+)\}/g, (match, key) => {
+        return data[key] !== undefined ? String(data[key]) : match;
+    });
+}

package/dist/helpers.d.ts

@@ -0,0 +1,7 @@
+import { Effect, Cause } from 'effect';
+import { Response } from 'express';
+import { HttpErrorBody } from './types';
+export declare function makeHttpError(status: number, errorCode: string, message: string, data?: Record<string, any>): HttpErrorBody;
+export declare function errorToResponse(error: unknown, res: Response): void;
+export declare function causeToError(cause: Cause.Cause<unknown>): unknown;
+export declare function runEffectAsPromise<A, E>(effect: Effect.Effect<A, E, never>): Promise<A>;

package/dist/helpers.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.makeHttpError = makeHttpError;
+exports.errorToResponse = errorToResponse;
+exports.causeToError = causeToError;
+exports.runEffectAsPromise = runEffectAsPromise;
+const effect_1 = require("effect");
+const types_1 = require("./types");
+function makeHttpError(status, errorCode, message, data) {
+    return {
+        status,
+        errorCode,
+        message,
+        data,
+    };
+}
+function errorToResponse(error, res) {
+    let errorBody;
+    if (error instanceof types_1.HttpError) {
+        errorBody = error.toJSON();
+    }
+    else if (error && typeof error === 'object' && 'status' in error && 'message' in error && !('errorCode' in error)) {
+        // Legacy HttpException 지원
+        errorBody = {
+            status: error.status,
+            errorCode: 'LEGACY_HTTP_EXCEPTION',
+            message: error.message,
+        };
+    }
+    else if (error && typeof error === 'object' && 'status' in error && 'errorCode' in error && 'message' in error) {
+        errorBody = error;
+    }
+    else {
+        errorBody = new types_1.HttpError(500, 'INTERNAL_SERVER_ERROR', error instanceof Error ? error.message : '알 수 없는 서버 오류가 발생했습니다.').toJSON();
+    }
+    res.status(errorBody.status).json(errorBody);
+}
+function causeToError(cause) {
+    const failureOption = effect_1.Cause.failureOption(cause);
+    const dieOption = effect_1.Cause.dieOption(cause);
+    if (failureOption._tag === 'Some') {
+        return failureOption.value;
+    }
+    else if (dieOption._tag === 'Some') {
+        return dieOption.value;
+    }
+    else if (effect_1.Cause.isInterrupted(cause)) {
+        return new Error('Operation interrupted');
+    }
+    else {
+        const failures = effect_1.Cause.failures(cause);
+        if (effect_1.Chunk.size(failures) > 0) {
+            return effect_1.Chunk.unsafeGet(failures, 0);
+        }
+        return new Error('Unknown error');
+    }
+}
+async function runEffectAsPromise(effect) {
+    const exit = await effect_1.Effect.runPromiseExit(effect);
+    if (effect_1.Exit.isSuccess(exit)) {
+        return exit.value;
+    }
+    else {
+        const error = causeToError(exit.cause);
+        throw error;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from './types';
+export * from './helpers';
+export * from './middleware';
+export * from './factory';
+export * from './schema';

package/dist/index.js

@@ -0,0 +1,22 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types"), exports);
+__exportStar(require("./helpers"), exports);
+__exportStar(require("./middleware"), exports);
+__exportStar(require("./factory"), exports);
+__exportStar(require("./schema"), exports);
+// HttpException은 router 패키지에서 직접 import 해야 함 (순환 의존성 방지)

package/dist/middleware.d.ts

@@ -0,0 +1,7 @@
+import { NextFunction, Request, Response } from 'express';
+interface RequestWithId extends Request {
+    id?: string;
+}
+export declare const effectErrorHandler: (error: unknown, req: RequestWithId, res: Response, next: NextFunction) => void;
+export declare function wrapWithEffect<T extends (...args: any[]) => any>(handler: T): (...args: any[]) => Promise<any>;
+export {};

package/dist/middleware.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.effectErrorHandler = void 0;
+exports.wrapWithEffect = wrapWithEffect;
+const effect_1 = require("effect");
+const common_1 = require("@asapjs/common");
+const helpers_1 = require("./helpers");
+function getStackInfo(error) {
+    const stack = error.stack || '';
+    const stackLines = stack.split('\n');
+    for (const line of stackLines) {
+        const match = line.match(/at\s+(.+?)\s+\((.+?):(\d+):(\d+)\)/);
+        if (match) {
+            const [, functionName, file, line, column] = match;
+            return { functionName, file, line: parseInt(line), column: parseInt(column) };
+        }
+        const simpleMatch = line.match(/at\s+(.+?):(\d+):(\d+)/);
+        if (simpleMatch) {
+            const [, file, line, column] = simpleMatch;
+            return { functionName: 'anonymous', file, line: parseInt(line), column: parseInt(column) };
+        }
+    }
+    return null;
+}
+const effectErrorHandler = (error, req, res, next) => {
+    const config = (0, common_1.getConfig)();
+    const requestId = req.id || 'unknown';
+    const stackInfo = error instanceof Error ? getStackInfo(error) : null;
+    const logContext = {
+        requestId,
+        method: req.method,
+        url: req.url,
+        ip: req.ip,
+        userAgent: req.get('user-agent'),
+        ...(stackInfo && {
+            file: stackInfo.file,
+            line: stackInfo.line,
+            function: stackInfo.functionName,
+        }),
+    };
+    if (error instanceof Error) {
+        common_1.logger.error(`Error: ${error.message}`, {
+            ...logContext,
+            stack: error.stack,
+            errorName: error.name,
+        });
+    }
+    else {
+        common_1.logger.error('Non-Error thrown', {
+            ...logContext,
+            error: String(error),
+        });
+    }
+    (0, helpers_1.errorToResponse)(error, res);
+};
+exports.effectErrorHandler = effectErrorHandler;
+function wrapWithEffect(handler) {
+    return async (...args) => {
+        const [req, res, next] = args;
+        try {
+            const effect = effect_1.Effect.promise(() => handler(...args));
+            const traced = effect_1.Effect.withSpan(effect, `${req.method} ${req.path}`, {
+                attributes: {
+                    'http.method': req.method,
+                    'http.path': req.path,
+                    'http.request_id': req.id || 'unknown',
+                },
+            });
+            const result = await effect_1.Effect.runPromise(traced);
+            return result;
+        }
+        catch (error) {
+            if (next) {
+                next(error);
+            }
+            else {
+                throw error;
+            }
+        }
+    };
+}

package/dist/schema.d.ts

@@ -0,0 +1,3 @@
+import { SchemaType } from '@asapjs/schema';
+export declare function typeIsToSwaggerSchema(typeIs: SchemaType): any;
+export declare function validateDataWithSchema(data: any, schema: Record<string, any>): void;

package/dist/schema.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.typeIsToSwaggerSchema = typeIsToSwaggerSchema;
+exports.validateDataWithSchema = validateDataWithSchema;
+function typeIsToSwaggerSchema(typeIs) {
+    // @asapjs/schema의 toSwagger 메서드 사용
+    if (typeIs.toSwagger) {
+        return typeIs.toSwagger();
+    }
+    // fallback
+    return { type: 'string' };
+}
+function validateDataWithSchema(data, schema) {
+    if (!data || typeof data !== 'object') {
+        throw new Error('Invalid data: must be an object');
+    }
+    for (const [key, typeIs] of Object.entries(schema)) {
+        const value = data[key];
+        // TypeIs가 함수로 전달된 경우 실행
+        const schemaType = typeof typeIs === 'function' ? typeIs() : typeIs;
+        // optional 여부 확인
+        const isOptional = schemaType.__options.optional || false;
+        // 필수 필드 체크
+        if (value === undefined && !isOptional) {
+            throw new Error(`Missing required field: ${key}`);
+        }
+        // 값이 있을 때만 타입 체크
+        if (value !== undefined) {
+            validateFieldType(key, value, schemaType);
+        }
+    }
+}
+function validateFieldType(fieldName, value, schemaType) {
+    // @asapjs/schema의 validate 메서드 사용
+    if (!schemaType.validate(value)) {
+        throw new Error(`Field '${fieldName}' has invalid type for ${schemaType.__name}`);
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,14 @@
+export interface HttpErrorBody {
+    status: number;
+    errorCode: string;
+    message: string;
+    data?: Record<string, any>;
+}
+export declare class HttpError extends Error implements HttpErrorBody {
+    readonly status: number;
+    readonly errorCode: string;
+    readonly message: string;
+    readonly data?: Record<string, any>;
+    constructor(status: number, errorCode: string, message: string, data?: Record<string, any>);
+    toJSON(): HttpErrorBody;
+}

package/dist/types.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpError = void 0;
+class HttpError extends Error {
+    constructor(status, errorCode, message, data) {
+        super(message);
+        this.name = 'HttpError';
+        this.status = status;
+        this.errorCode = errorCode;
+        this.message = message;
+        this.data = data;
+        // Maintains proper stack trace for where our error was thrown (only available on V8)
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, HttpError);
+        }
+    }
+    toJSON() {
+        return {
+            status: this.status,
+            errorCode: this.errorCode,
+            message: this.message,
+            data: this.data,
+        };
+    }
+}
+exports.HttpError = HttpError;

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@asapjs/error",
+  "version": "1.0.0-alpha.0",
+  "description": "Error handling utilities for ASAP.js with Effect integration",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  },
+  "dependencies": {
+    "@asapjs/common": "1.0.0-alpha.0",
+    "@asapjs/schema": "1.0.0-alpha.0",
+    "@asapjs/types": "1.0.0-alpha.0",
+    "effect": "^3.11.11",
+    "express": "^4.17.3"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.13",
+    "@types/node": "^17.0.21",
+    "typescript": "^5.8.3"
+  },
+  "author": "",
+  "license": "ISC",
+  "publishConfig": {
+    "access": "public"
+  },
+  "gitHead": "79561e3604dc505813035558d1bfcc6cda0b088a"
+}