Quick Start

• Swagger/OpenAPI / AsyncAPI 파생 스키마 / 커스텀 계약 등으로부터 얻은 OpenAPI-style Paths 타입(관례상 paths)을 주입해 라우트(요청) 타입 안정성을 확보
• 모든 API는 RxJS Observable 반환
• core는 프레임워크 독립 (Next.js 의존 없음)
• Next.js 전용 기능은 @byeolnaerim/typed-rx-http/next 엔트리포인트로 분리 → /next를 import할 때만 Next.js가 필요
• RSocket 전용 기능은 @byeolnaerim/typed-rx-http/rsocket 엔트리포인트로 분리 → /rsocket을 import할 때만 RSocket 패키지가 필요

npm

Core (프레임워크 독립)

Next.js 어댑터(선택)

Next.js를 사용하지 않는 프로젝트에서는 /next를 import하지 마세요.

RSocket 어댑터(선택)

RSocket을 쓰는 프로젝트에서만 peer 패키지를 설치하세요.

RSocket을 사용하지 않는 프로젝트에서는 /rsocket을 import하지 마세요.

createHttpClient<Paths>()의 Paths는 “요청 스펙(라우트)”을 표현하는 타입입니다. 문서에서는 관례상 paths라고 부르지만, 꼭 OpenAPI/Swagger일 필요도, 이름이 paths일 필요도 없습니다.

다만 코어는 내부적으로 OpenApiPathsLike 제약을 사용하므로, Paths는 아래처럼 OpenAPI paths와 유사한 형태여야 합니다.

• 최상위 키: URL 경로 문자열(예: "/users/{id}")
• 하위 키: HTTP method (get/post/put/delete/patch …)
• 각 method 안에 parameters.query/path/header/cookie, requestBody, responses 같은 필드가 존재(또는 never)

코어는 위 구조에서 주로 아래 필드를 참조해 ServiceArguments의 타입을 구성합니다.

• url: keyof Paths
• method: keyof Paths[url]
• queryString: parameters.query
• pathVariable: parameters.path
• body: requestBody

예: openapi-typescript 출력물은 보통 아래와 같은 규격입니다(일부 축약).

HeaderStore는 CSR에서 기본 헤더를 관리하기 위한 간단한 in-memory store입니다.

• headerStore는 선택이지만, CSR에서 기본 헤더/세션 인증을 사용하려면 넣는 것을 권장합니다.
• headersProvider는 SSR/멀티테넌트처럼 요청마다 헤더 계산이 필요할 때 사용합니다.

요청 타입(url/method/pathVariable/queryString/body)은 사용자가 createHttpClient<Paths>()에 주입한 타입(관례상 OpenAPI paths)으로부터 결정됩니다. 응답 타입은 callApi<R>()에서 호출자가 제너릭 R로 선택합니다(코어가 responses에서 자동 추론하지 않습니다).

이 라이브러리는 응답 래핑을 강제하지 않습니다. API별로 제너릭으로 응답 형태를 선택하면 됩니다.

래핑된 응답

래핑 없는 응답

서버가 NDJSON(한 줄에 JSON 하나)을 내려줄 때 callApiStream을 사용합니다. Accept 헤더가 없으면 기본값으로 application/x-ndjson가 설정됩니다.

createCsrCache<CacheName>()가 제공하는 기능:

• callApiCsrCache(callApiFn, serviceArgs, cacheOptions)
• removeCsrCache(cacheName) — 타입 캐시명 + 문자열 모두 지원

createSessionAuth는 세션 인증 로직을 코어에서 분리해 옵션으로 붙였다 떼는 방식입니다.

동작:

• Authorization을 headerStore에 유지
• ensureToken$()로 토큰 동기화(/api/auth/token)
• 401 발생 시 refresh 1회 시도(/api/auth/token/refresh) 후 원 요청 재시도
• refresh 실패 시 logout(/api/auth/logout) 후 에러 전달
• 로그인 상태 변경은 onLoginChange 콜백으로 외부에서 처리

refresh/retry 없이 토큰 동기화만 필요하면:

2xx가 아니면 HttpResponseError를 throw 합니다(status, response, args, data 포함).

레거시 호환: 에러 바디가 { resultType: ... } 형태면 그 객체를 그대로 throw 합니다.

redirectToUnauthorizedOnServer401

redirectToUnauthorizedOnServer401는 Next.js(App Router) SSR 환경에서 401이 발생했을 때 redirect를 수행하는 기본 구현(편의 함수)입니다.

동작 규칙(고정):

• redirect 대상: /unauthorized
• queryString: redirect_uri=<현재 페이지> + logout=true
• 현재 페이지는 x-page-url 헤더에서 읽습니다(없으면 /)

즉, 위 경로/쿼리 규칙이 프로젝트와 맞을 때만 그대로 사용하세요. 경로가 다르거나 쿼리 규칙이 다르면, 아래처럼 직접 onServer401를 구현해서 주입하면 됩니다.

callApiSsrCache

Next의 next/cache(unstable_cache) 기반 SSR 캐시 도우미입니다.

• GET + cacheTime > 0 → force-cache + revalidate
• 그 외 → no-store
• headersProvider로 요청별 Cookie / Authorization 주입
• 401 발생 시 onServer401가 있으면 실행(보통 redirect())

아래 rxjsHttpService.ts가 이후 generator 예제의 commonServiceFile이 가리키는 프로젝트 공용 HTTP adapter입니다. 라이브러리가 생성하는 파일이 아니라 프로젝트가 직접 관리하며, core client + session auth + CSR cache + SSR cache helper를 한 곳에서 export합니다. 아래는 전체 코드입니다.

createHttpClient<Paths>(options)

반환:

• callApi<R>(args): Observable<R>
• callApiStream<RChunk>(args): Observable<RChunk>
• uploadFile({ file, url, ifNoneMatch?, headers? }): Observable<Response>
• createSSEObservable<R>(args): Observable<R>

옵션:

• baseUrl: string
• headerStore?: HeaderStore
• headersProvider?: () => Record<string, string> | Promise<Record<string, string>>
• dropAuthWhenCacheControl?: boolean (기본값: true)
• onServer401?: () => void | Promise<void>

createHeaderStore(initial?)

get(), set(), merge(), remove(), clear()

createCsrCache<CacheName>()

• callApiCsrCache(callApiFn, serviceArgs, cacheForService)
• removeCsrCache(cacheName) (타입 + 문자열)

createSessionAuth(options)

• withSessionAuth(), withEnsureToken()
• ensureToken$(), refreshToken$(), logout$()

• fetch / Response API 사용(rxjs/fetch)
• 스트리밍(NDJSON)은 ReadableStream + TextDecoder 필요
• SSE는 EventSource 필요

대부분의 최신 브라우저와 Next.js 런타임에서는 기본 제공됩니다. 커스텀 Node 런타임에서는 폴리필이 필요할 수 있습니다.

이 패키지는 런타임 HTTP 클라이언트와 별도로, OpenAPI/Swagger JSON에서 타입/서비스 코드를 생성하는 Node 스크립트를 함께 제공합니다. 이 스크립트는 선택 기능입니다.

일반적인 @byeolnaerim/typed-rx-http, /next, /rsocket 사용자는 이 스크립트를 실행하지 않아도 되며, openapi-typescript를 설치할 필요도 없습니다.

의존성 격리

OpenAPI 타입 생성에는 openapi-typescript CLI가 필요합니다. 하지만 이 패키지는 openapi-typescript를 일반 dependencies에 넣지 않습니다.

@byeolnaerim/typed-rx-http 라이브러리 자체는 devDependencies.typescript로 TypeScript 6.0.3을 사용합니다. typed-rx-http, /next, /rsocket 엔트리포인트와 라이브러리 빌드는 이 TypeScript 6.0.3 기준을 유지합니다.

다만 openapi-typescript는 아직 특정 TypeScript 5.x 버전을 요구할 수 있으므로, OpenAPI auto node script만 별도의 npx 임시 실행 환경에서 openapi-typescript와 [email protected]을 같이 실행합니다. 이 임시 실행 환경은 라이브러리의 devDependencies.typescript 6.0.3을 바꾸지 않고, 사용자의 프로젝트에 설치된 typescript나 openapi-typescript 버전도 사용하지 않습니다.

기본값은 auto script 실행 시점에만 아래 명령을 생성해서 실행하는 것입니다.

따라서 사용법 자체는 바뀌지 않습니다. 기존처럼 auto node script를 호출하면 되고, OpenAPI 타입 생성 단계에서만 격리된 TypeScript 5.9.3 환경이 사용됩니다. auto script를 쓰지 않는 사용자는 openapi-typescript나 TypeScript 5.9.3에 전혀 묶이지 않습니다.

필요하면 openApiTypescriptCommand로 명령을 직접 고정할 수 있습니다.

또는 기본 명령을 구성하는 패키지 버전만 바꿀 수도 있습니다.

생성되는 파일

기본 설정은 아래 파일들을 생성합니다.

apiUnionArrays.ts는 OpenAPI schema enum뿐 아니라 query, path, header, cookie parameter enum도 상수 배열로 생성합니다. 배열 query parameter의 items.enum도 처리합니다.

EventStream 감시

HTTP 1회 요청

로컬 파일에서 생성

백엔드 코드는 평소처럼 작성합니다. 이 예제에서는 path variable로 이름을, query parameter로 메시지를 받아 Mono로 응답합니다.

백엔드의 swagger.json을 받아 타입과 service 파일을 생성합니다. 이 작업은 개발 서버를 실행할 때 한 번 호출하거나 watch script로 연결할 수 있습니다.

아래에서 Front code와 Backend code를 바꿔 볼 수 있습니다. Result를 누르면 오른쪽에 실행 화면이 열립니다. 값을 바꾼 뒤 요청 버튼을 눌러보세요.