honopang (1.0.0)

Published 2025-09-15 02:23:45 +09:00 by sldev_token

Setup this registry in your project .npmrc file:

registry=

To install the package using npm, run the following command:

npm install honopang@1.0.0

or add it to the package.json file:

"honopang": "1.0.0"

For more information on the npm registry, see the documentation.

Honopang 🚀

Railway Bun Function을 위한 Hono.js 헬퍼 스크립트 라이브러리

Honopang은 Railway에서 Bun Function을 개발할 때 자주 사용되는 유틸리티들을 모아놓은 헬퍼 라이브러리입니다. Hono.js 기반 API 개발을 더욱 쉽고 효율적으로 만들어줍니다.

🎯 주요 기능

1. Race Logger - NocoDB 실행 로그 기록

API 실행 과정을 자동으로 추적하고 NocoDB에 로그를 기록합니다.

2. 에러 처리 - StatusError & Response Handler

HTTP 상태 코드를 포함한 에러 처리와 표준화된 응답 생성

3. 요청 파싱 - Context Parser

다양한 Content-Type의 요청 데이터를 자동으로 파싱하고 검증

4. 인증 미들웨어 - Authorization Handler

Bearer 토큰 기반 인증 미들웨어 생성

📦 설치

bun install

🚀 시작하기

bun run index.ts

Import

import { StatusError, responseOfError } from "/opt/honopang" // 도커 프로덕션
import { StatusError, responseOfError } from "honopang" // 또는 npm 패키지로

📖 API 문서

Race Logger

실행 로그를 NocoDB에 자동으로 기록하는 레이스 로거입니다.

import { createRaceLoggerOnNocoDB } from "honopang";

// 기본 로거 생성
const logger = createRaceLoggerOnNocoDB({
  baseUrl: "https://nocodb.example.com",
  tableId: "table_123",
  topic: "user-api",
  timezone: "Asia/Seoul" // 선택적, 기본값: "Asia/Seoul"
});

// 사용법
app.get("/users", async (c) => {
  return logger(async (utils) => {
    utils.stdout("사용자 목록 조회 시작", utils.ms);
    const users = await getUserList();
    utils.assignDetail({ userCount: users.length });
    utils.stdout("조회 완료", utils.formatMs("ms"));
    return c.json(users);
  });
});

// 설정 복제
const adminLogger = logger.clone({ topic: "admin-api" });

NocoDB 테이블 구조

Race Logger를 사용하기 위해 다음과 같은 필드 구조로 NocoDB 테이블을 생성하세요:

필드명	데이터 타입	필수 여부	설명	예시 값
`topic`	SingleLineText	권장	로그 주제/태그 (인덱스 생성 권장)	`"user-api"`, `"admin-operations"`
`begin_at`	DateTime	필수	실행 시작 시간	`yyyy-MM-dd HH:mm:ss`
`duration`	Number	선택	실행 소요 시간 (밀리초)	`1250`
`detail`	JSON	선택	상세 정보 객체	`{"userCount": 42, "status": "success"}`
`stdout`	LongText	선택	표준 출력 로그 (줄바꿈으로 구분)	`"Starting process...\nProcessing data...\nCompleted"`
`stderr`	LongText	선택	오류 로그 (줄바꿈으로 구분)	`"Warning: deprecated API\nError: connection timeout"`

에러 처리

HTTP 상태 코드를 포함한 커스텀 에러 클래스와 응답 헬퍼입니다.

import { StatusError, responseOfError } from "honopang";

// StatusError 사용법
throw new StatusError("Not Found", 404);
throw new StatusError(404); // 자동으로 "Not Found" 메시지 생성

// 에러 응답 처리
app.get("/user/:id", async (c) => {
  try {
    // 비즈니스 로직
    throw new StatusError("User not found", 404);
  } catch (error) {
    return responseOfError(c, error);
  }
});

요청 파싱

다양한 Content-Type의 요청을 자동으로 파싱하고 검증합니다.

import { parseParams } from "honopang";

app.post("/users", async (c) => {
  // 모든 파라미터 파싱
  const params = await parseParams(c);
  
  // 필수 필드 검증
  const params = await parseParams(c, {
    requires: ["name", "email"]
  });
  
  // 특정 필드만 선택
  const params = await parseParams(c, {
    selects: ["name", "email", "age"],
    requires: ["name", "email"]
  });
  
  return c.json({ success: true, data: params });
});

인증 미들웨어

Bearer 토큰 기반 인증 미들웨어를 생성합니다.

import { createNextHandlerIfAuthorization } from "honopang";

const authHandler = createNextHandlerIfAuthorization(
  async function (token: string) {
    const url = new URL(`/v1/auth/verify/${token}`, AUTH_SERVER_URL);
    const response = await fetch(url);
    
    if (response.status === 200) {
      return true;
    } else {
      return new StatusError("Invalid token", 401);
    }
  }
);

// 인증이 필요한 라우트에 적용
app.get("/protected", authHandler, (c) => {
  return c.json({ message: "Protected content" });
});

🏗️ 프로젝트 구조

src/
├── common.ts           # StatusError 클래스와 공통 타입
├── createHook.ts       # Race Logger (NocoDB 로깅)
├── contextParser.ts    # 요청 파라미터 파싱
├── contextResponse.ts  # 에러 응답 헬퍼
└── createHandler.ts    # 인증 미들웨어 생성기

🌍 배포

이 라이브러리는 Railway Function에서 /opt/honopang 경로에 설치될 예정입니다.

// Railway 배포 시 사용법
import { StatusError, responseOfError } from "/opt/honopang";

🛠️ 개발 환경

Runtime: Bun v1.2.8+
Framework: Hono.js
Language: TypeScript
Target: Railway Bun Functions

📝 라이선스

이 프로젝트는 Railway Bun Function 개발을 위한 헬퍼 라이브러리입니다.

Built with ❤️ for Railway Bun Functions

Development dependencies

ID	Version
@types/bun	latest
@types/luxon	^3.7.1
hono	^4.9.7
luxon	^3.7.2

Peer dependencies

ID	Version
typescript	^5

Details

npm

2025-09-15 02:23:45 +09:00

latest

44 KiB

Assets (1)

honopang-1.0.0.tgz 44 KiB

Versions (1) View all

1.0.0

2025-09-15