Funztic: Hono 기반 함수형 API 개발 라이브러리

Funztic는 Hono 웹 프레임워크를 기반으로 한 함수형 API 개발 라이브러리입니다.

모나드 패턴을 활용하여 타입 안전하고 선언적인 API 개발을 지원합니다.

📦 설치

npm i funztic
# 또는
yarn add funztic

🚀 시작하기

기본 사용법

import { Funztic, Result } from 'funztic';
import { z } from '@hono/zod-openapi'; // zod를 사용할 수도 있습니다.

new Funztic({
  title: 'My API',
  version: '1.0.0'
}).get(
  '/hello', {
    summary: '인사말을 반환합니다',
    responses: {
      200: {
        description: '성공',
        schema: z.object({ message: z.string() })
      }
    }
  },
  () => Result.ok({ message: '안녕하세요!' })
).serve(3000, { description: 'API 서버' });

📚 API 문서

Funztic 클래스

생성자

new Funztic(options?: {
  title?: string;
  version?: string;
  description?: string;
})

메서드

defineSecurity

보안 스키마를 정의합니다.

defineSecurity(type: SecuritySchemeKey, schema: SecurityScheme): this

register

의존성을 등록합니다.

register<T extends AnyClass>(instance: InstanceType<T>): this

enter

라우트 그룹의 접두사를 설정합니다.

enter(prefix: string): this

exit

라우트 그룹의 접두사를 제거합니다.

exit(): this

guard

미들웨어를 등록합니다.

guard(middleware: MiddlewareHandler | MiddlewareHandler[]): this

unguard

마지막으로 등록된 미들웨어를 제거합니다.

unguard(): this

HTTP 메서드

다음 HTTP 메서드를 지원합니다:

• get
• post
• put
• delete
• patch

get<Params, Query, Headers, Res>(
  path: string,
  config: RouteConfig<never, Params, Query, Headers, Res>,
  handler: RouteHandlerFn<never, Params, Query, Headers, Res>
): this

use

전역 미들웨어를 등록합니다.

use(pathOrMiddleware: string | MiddlewareHandler, ...handlers: MiddlewareHandler[]): this

serve

서버를 시작합니다.

serve(port: number = 3000, options?: {
  swaggerUrl?: string;
  description?: string;
}): any

HttpResult 클래스

정적 메서드

ok

성공 결과를 생성합니다.

static ok<T>(value: T): HttpResult<T>

okAsync

비동기 성공 결과를 생성합니다.

static okAsync<T>(valuePromise: Promise<T>): Promise<HttpResult<T>>

fail

실패 결과를 생성합니다.

static fail<E>(status: number, errorBody: E): HttpResult<E>

of

사용자 정의 상태 코드로 결과를 생성합니다.

static of<T>(status: number, value: T, headers?: Record<string, string>): HttpResult<T>

fromNullable

null 또는 undefined를 처리합니다.

static fromNullable<T, E = string>(
  value: T | null | undefined,
  errorStatus?: number,
  errorMsg?: E
): HttpResult<T | E>

인스턴스 메서드

map

성공 결과를 변환합니다.

map<U>(fn: (value: T) => U): HttpResult<U>

flatMap

중첩된 결과를 평탄화합니다.

flatMap<U>(fn: (value: T) => HttpResult<U>): HttpResult<U>

filter

결과를 필터링합니다.

filter<E = string>(
  predicate: (value: T) => boolean,
  errorStatus?: number,
  errorMsg?: E
): HttpResult<T | E>

withHeader

헤더를 추가합니다.

withHeader(name: string, value: string): HttpResult<T>

toResponse

Response 객체로 변환합니다.

toResponse(): Response

🔐 보안 스키마

다음 보안 스키마를 지원합니다:

SecuritySchemes.basic()      // Basic 인증
SecuritySchemes.bearer()     // Bearer 토큰
SecuritySchemes.digest()     // Digest 인증
SecuritySchemes.apiKey()     // API 키
SecuritySchemes.oauth2()     // OAuth2
SecuritySchemes.openIdConnect() // OpenID Connect

📝 예제

보안이 적용된 API

new Funztic().defineSecurity(
  'apiKey',
  SecuritySchemes.apiKey('X-Secure-Key')
).get(
  '/secure', {
    security: ['apiKey'],
    responses: {
      200: {
        description: '성공',
        schema: z.object({ message: z.string() })
      },
      401: {
        description: '실패',
        schema: z.object({ message: z.string() })
      }
    }
  },
  ({ origin }) => {
    if (JwtUtil.verify(origin)) { // 미들웨어를 적용할 수도 있습니다.
      return Result.ok({ message: '보안이 적용된 엔드포인트입니다' });
    } else {
      return Result.fail(401, { message: '유효하지 않은 토큰입니다' });
    }
  }
).serve();

의존성 주입

class UserService {
  async getUsers() {
    return [{ id: 1, name: '홍길동' }];
  }
}

new Funztic().register(
  new UserService()
).get(
  '/users', {
    responses: {
      200: {
        description: '성공',
        schema: z.array(z.object({
          id: z.number(),
          name: z.string()
        }))
      }
    }
  }, async (_, resolver) => {
    const userService = resolver(UserService);
    const users = await userService.getUsers();
    return Result.ok(users);
  }
).serve();

📄 라이센스

ISC