Mulai Cepat

• Menyuntikkan tipe Paths gaya OpenAPI yang diperoleh dari skema turunan Swagger/OpenAPI / AsyncAPI / kontrak kustom, dll. (secara konvensional disebut paths) untuk memastikan stabilitas tipe permintaan.
• Semua API mengembalikan Observable RxJS.
• Core bersifat independen dari framework (tidak bergantung pada Next.js).
• Fitur khusus Next.js dipisahkan ke titik masuk @byeolnaerim/typed-rx-http/next → hanya diperlukan Next.js saat mengimpor /next.
• Fitur khusus RSocket dipisahkan ke titik masuk @byeolnaerim/typed-rx-http/rsocket → hanya diperlukan paket RSocket saat mengimpor /rsocket.

npm

Core (independen framework)

Adapter Next.js (opsional)

Jangan impor /next di proyek yang tidak menggunakan Next.js.

Adapter RSocket (opsional)

Hanya instal paket peer di proyek yang menggunakan RSocket.

Jangan impor /rsocket di proyek yang tidak menggunakan RSocket.

Paths dari createHttpClient<Paths>() adalah tipe yang menggambarkan "spesifikasi permintaan (route)". Dalam dokumen, biasanya disebut paths, tetapi tidak harus OpenAPI/Swagger, dan tidak harus bernama paths.

Namun, Core menggunakan batasan OpenApiPathsLike secara internal, sehingga Paths harus memiliki bentuk yang mirip dengan paths OpenAPI seperti di bawah ini.

• Kunci teratas: string jalur URL (misalnya "/users/{id}")
• Kunci bawah: metode HTTP (get/post/put/delete/patch …)
• Setiap metode memiliki bidang seperti parameters.query/path/header/cookie, requestBody, responses (atau never)

Core terutama merujuk pada bidang di atas untuk membangun tipe ServiceArguments.

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

Contoh: output openapi-typescript biasanya memiliki spesifikasi seperti di bawah ini (beberapa disingkat).

HeaderStore adalah penyimpanan in-memory sederhana untuk mengelola header dasar di CSR.

• headerStore adalah opsional, tetapi disarankan untuk digunakan jika ingin menggunakan header dasar/otentikasi sesi di CSR.
• headersProvider digunakan ketika perhitungan header diperlukan untuk setiap permintaan seperti di SSR/multi-tenant.

Tipe permintaan (url/metode/pathVariable/queryString/body) ditentukan oleh tipe yang disuntikkan pengguna ke createHttpClient<Paths>() (secara konvensional jalur OpenAPI). Tipe respons dipilih oleh pemanggil di callApi<R>() dengan generik R (inti tidak secara otomatis menyimpulkan dari respons).

Perpustakaan ini tidak memaksa pembungkus respons. Anda dapat memilih bentuk respons secara generik untuk setiap API.

Respons yang dibungkus

Respons tanpa pembungkus

Gunakan callApiStream ketika server mengirimkan NDJSON (satu JSON per baris). Jika tidak ada header Accept, secara default diatur ke application/x-ndjson.

Fungsi yang disediakan oleh createCsrCache<CacheName>():

• callApiCsrCache(callApiFn, serviceArgs, cacheOptions)
• removeCsrCache(cacheName) — mendukung nama cache tipe + string

createSessionAuth memisahkan logika otentikasi sesi dari inti dan menghubungkannya sebagai opsi.

Tindakan:

• Menjaga Authorization di headerStore
• Sinkronisasi token dengan ensureToken$() (/api/auth/token)
• Saat 401 terjadi, coba refresh sekali (/api/auth/token/refresh) lalu coba ulang permintaan asli
• Jika refresh gagal, logout (/api/auth/logout) dan sampaikan kesalahan
• Perubahan status login ditangani dari luar dengan callback onLoginChange

Jika hanya perlu sinkronisasi token tanpa refresh/retry:

Jika bukan 2xx, lempar HttpResponseError (termasuk status, respons, args, data).

Kompatibilitas warisan: jika badan kesalahan berbentuk { resultType: ... }, lempar objek itu langsung.

redirectToUnauthorizedOnServer401

redirectToUnauthorizedOnServer401 adalah implementasi dasar (fungsi utilitas) untuk melakukan redirect ketika 401 terjadi di lingkungan SSR Next.js (App Router).

Aturan tindakan (tetap):

• Target redirect: /unauthorized
• queryString: redirect_uri=<halaman saat ini> + logout=true
• Halaman saat ini dibaca dari header x-page-url (jika tidak ada, gunakan /)

Artinya, gunakan aturan jalur/query di atas hanya jika sesuai dengan proyek. Jika jalurnya berbeda atau aturan query berbeda, Anda dapat mengimplementasikan onServer401 secara langsung dan menyuntikkannya.

callApiSsrCache

Ini adalah pembantu cache SSR berbasis next/cache(unstable_cache) dari Next.

• GET + cacheTime > 0 → force-cache + revalidate
• Selain itu → no-store
• Menyuntikkan Cookie / Authorization per permintaan dengan headersProvider
• Jika 401 terjadi dan ada onServer401, maka akan dieksekusi (biasanya redirect())

Di bawah ini adalah rxjsHttpService.ts yang merupakan adapter HTTP umum proyek yang ditunjuk oleh commonServiceFile dalam contoh generator berikut. Ini bukan file yang dihasilkan oleh pustaka, tetapi dikelola langsung oleh proyek, mengekspor core client + session auth + CSR cache + SSR cache helper di satu tempat. Berikut adalah kode lengkapnya.

createHttpClient<Paths>(options)

Mengembalikan:

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

Opsi:

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

createHeaderStore(initial?)

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

createCsrCache<CacheName>()

• callApiCsrCache(callApiFn, serviceArgs, cacheForService)
• removeCsrCache(cacheName) (tipe + string)

createSessionAuth(options)

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

• Menggunakan fetch / Response API (rxjs/fetch)
• Streaming (NDJSON) memerlukan ReadableStream + TextDecoder
• SSE memerlukan EventSource

Tersedia di sebagian besar browser modern dan runtime Next.js. Runtime Node kustom mungkin memerlukan polyfill.

Paket ini menyediakan skrip Node yang menghasilkan kode tipe/layanan dari JSON OpenAPI/Swagger, terpisah dari klien HTTP runtime. Skrip ini adalah fitur opsional.

Pengguna umum @byeolnaerim/typed-rx-http, /next, /rsocket tidak perlu menjalankan skrip ini dan tidak perlu menginstal openapi-typescript.

Isolasi ketergantungan

Menghasilkan tipe OpenAPI memerlukan openapi-typescript CLI. Namun, paket ini tidak memasukkan openapi-typescript ke dalam dependencies umum.

Pustaka @byeolnaerim/typed-rx-http sendiri menggunakan TypeScript 6.0.3 di devDependencies.typescript. Entry point typed-rx-http, /next, /rsocket dan build pustaka mempertahankan standar TypeScript 6.0.3 ini.

Namun, openapi-typescript mungkin masih memerlukan versi TypeScript 5.x tertentu, sehingga hanya OpenAPI auto node script yang dijalankan dalam lingkungan eksekusi sementara npx terpisah dengan openapi-typescript dan [email protected]. Lingkungan eksekusi sementara ini tidak mengubah devDependencies.typescript 6.0.3 pustaka dan tidak menggunakan versi typescript atau openapi-typescript yang diinstal di proyek pengguna.

Nilai default adalah menghasilkan dan menjalankan perintah di bawah ini hanya pada saat eksekusi skrip otomatis.

Oleh karena itu, cara penggunaannya tidak berubah. Anda dapat memanggil skrip node otomatis seperti biasa, dan hanya lingkungan TypeScript 5.9.3 yang terisolasi yang digunakan pada tahap pembuatan tipe OpenAPI. Pengguna yang tidak menggunakan skrip otomatis tidak terikat pada openapi-typescript atau TypeScript 5.9.3 sama sekali.

Jika perlu, Anda dapat mengunci perintah secara langsung dengan openApiTypescriptCommand.

Atau Anda hanya dapat mengubah versi paket yang mengonfigurasi perintah dasar.

File yang dihasilkan

Pengaturan default menghasilkan file-file di bawah ini.

apiUnionArrays.ts tidak hanya menghasilkan enum skema OpenAPI tetapi juga menghasilkan enum parameter query, path, header, dan cookie sebagai array konstan. Juga memproses items.enum dari parameter query array.

Pemantauan EventStream

Permintaan HTTP satu kali

Dihasilkan dari file lokal

Tulis kode backend seperti biasa. Dalam contoh ini, terima nama sebagai variabel jalur dan pesan sebagai parameter kueri. Monodan balas.

Ambil dari backend. swagger.jsonHasilkan file tipe dan layanan. Tugas ini dapat dipanggil sekali saat menjalankan server pengembangan atau terhubung dengan skrip watch.

Anda dapat mencoba mengubah di bawah ini. Kode Backenddan HasilTekan untuk membuka layar eksekusi di sebelah kanan. Ubah nilai dan tekan tombol permintaan. Bagian yang terlihat di proyek nyata.Kode Front