クイックスタート

• Swagger/OpenAPI / AsyncAPI派生スキーマ / カスタム契約などから得たOpenAPIスタイルのPathsタイプ（慣例的にpaths）を注入してルート（リクエスト）タイプの安定性を確保
• すべてのAPIはRxJS Observableを返す
• coreはフレームワークに依存しない（Next.js依存なし）
• Next.js専用機能は@byeolnaerim/typed-rx-http/nextエントリーポイントに分離 → /nextをインポートする時のみNext.jsが必要
• RSocket専用機能は@byeolnaerim/typed-rx-http/rsocketエントリーポイントに分離 → /rsocketをインポートする時のみRSocketパッケージが必要

npm

Core（フレームワーク非依存）

Next.jsアダプター（オプション）

Next.jsを使用しないプロジェクトでは/nextをインポートしないでください。

RSocketアダプター（オプション）

RSocketを使用するプロジェクトでのみpeerパッケージをインストールしてください。

RSocketを使用しないプロジェクトでは/rsocketをインポートしないでください。

createHttpClient<Paths>()のPathsは「リクエスト仕様（ルート）」を表すタイプです。ドキュメントでは慣例的にpathsと呼ばれますが、必ずしもOpenAPI/Swaggerである必要はなく、名前がpathsである必要もありません。

ただし、coreは内部的にOpenApiPathsLike制約を使用するため、Pathsは以下のようにOpenAPI pathsに類似した形である必要があります。

• 最上位キー: URLパス文字列（例: "/users/{id}"）
• 下位キー: HTTPメソッド（get/post/put/delete/patch …）
• 各メソッド内にparameters.query/path/header/cookie、requestBody、responsesなどのフィールドが存在（またはnever）

coreは上記構造から主に以下のフィールドを参照してServiceArgumentsのタイプを構成します。

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

例: openapi-typescriptの出力は通常以下のような形式です（若干の省略あり）。

HeaderStoreはCSRで基本ヘッダーを管理するためのシンプルなインメモリストアです。

• headerStoreは任意ですが、CSRで基本ヘッダー/セッション認証を使用するには追加することを推奨します。
• headersProviderはSSR/マルチテナントのようにリクエストごとにヘッダー計算が必要な場合に使用します。

リクエストタイプ（url/method/pathVariable/queryString/body）は、ユーザーがcreateHttpClient<Paths>()に注入したタイプ（慣例的にOpenAPI paths）から決定されます。応答タイプはcallApi<R>()で呼び出し元がジェネリックRで選択します（コアはresponsesから自動推論しません）。

このライブラリは応答ラッピングを強制しません。APIごとにジェネリックで応答形式を選択できます。

ラッピングされた応答

ラッピングなしの応答

サーバーがNDJSON（1行にJSON1つ）を返すときは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をスローします（status, response, args, dataを含む）。

レガシー互換: エラーボディが{ resultType: ... }形式の場合、そのオブジェクトをそのままスローします。

redirectToUnauthorizedOnServer401

redirectToUnauthorizedOnServer401はNext.js（App Router）SSR環境で401が発生した際にリダイレクトを行う基本実装（便利関数）です。

動作ルール（固定）:

• リダイレクト先: /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アダプターです。ライブラリが生成するファイルではなく、プロジェクトが直接管理し、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を一般的な依存関係に含めていません。

@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 スキーマの enum だけでなく、query、path、header、cookie パラメータの enum も定数配列として生成します。配列の query パラメータの items.enum も処理します。

EventStream 監視

HTTP 1 回のリクエスト

ローカルファイルから生成

バックエンドコードは普段通りに記述します。この例では、パス変数で名前を、クエリパラメータでメッセージを受け取ります。 Monoと応答します。

バックエンドの swagger.jsonを受け取り、タイプとサービスファイルを生成します。この作業は開発サーバーを実行する際に一度呼び出すか、watchスクリプトで接続できます。

以下で フロントコードと バックエンドコードを変更できます。 結果を押すと右側に実行画面が開きます。値を変更した後、リクエストボタンを押してみてください。