@hm-soft/api-response

백엔드마다 제각각인 API 응답 형식을 하나의 표준 봉투로 통일하는 의존성 없는 유틸 + 타입.

type ApiResponse<T> =
  | { success: true;  data: T; meta?: Record<string, unknown> }
  | { success: false; error: { code: string; message: string; details?: unknown } };

설치

npm install @hm-soft/api-response

사용

import { ok, okList, fail, unwrap, isOk, httpStatus } from "@hm-soft/api-response";

// 라우트 핸들러
export async function GET() {
  const user = await db.user.find(id);
  if (!user) return Response.json(fail("NOT_FOUND", "사용자를 찾을 수 없습니다"), { status: 404 });
  return Response.json(ok(user));
}

// 목록 + 페이지네이션
return Response.json(okList(items, { page: 1, pageSize: 20, total: 137 }));
// → meta: { page:1, pageSize:20, total:137, totalPages:7 }

// 상태코드 자동 매핑
const res = fail("UNAUTHORIZED", "로그인 필요");
return Response.json(res, { status: httpStatus(res) }); // 401

// 클라이언트
const res = await api.get("/user");
if (isOk(res)) console.log(res.data);
const user = unwrap(res); // err면 ApiError throw

API

| 함수 | 설명 | |------|------| | ok(data, meta?) | 성공 응답 | | okList(items, {page,pageSize,total}) | 목록 + totalPages 자동 계산 | | fail(code, message, details?) | 실패 응답 | | fromError(err, code?) | 예외 → 실패 응답 | | isOk(res) / isErr(res) | 타입가드 | | unwrap(res) | ok면 data, err면 ApiError throw | | mapData(res, fn) | ok의 data 변환(err 통과) | | httpStatus(res, {fallback?, statusMap?}) | 응답 → HTTP 상태코드 |

기본 코드→상태 매핑: VALIDATION_ERROR/BAD_REQUEST→400, UNAUTHORIZED→401, FORBIDDEN→403, NOT_FOUND→404, CONFLICT→409, RATE_LIMITED→429, INTERNAL_ERROR→500.

License

Apache-2.0