Inicio Rápido

• Inyección de tipos de rutas estilo OpenAPI obtenidos de esquemas derivados de Swagger/OpenAPI / AsyncAPI / contratos personalizados, etc. (por convención, paths) para asegurar la estabilidad del tipo de solicitud.
• Todas las API devuelven RxJS Observable.
• El núcleo es independiente del marco (no depende de Next.js).
• Las funciones específicas de Next.js se separan en el punto de entrada @byeolnaerim/typed-rx-http/next → Next.js solo es necesario al importar /next.
• Las funciones específicas de RSocket se separan en el punto de entrada @byeolnaerim/typed-rx-http/rsocket → RSocket solo es necesario al importar /rsocket.

npm

Core (independiente del framework)

Adaptador de Next.js (opcional).

En proyectos que no utilizan Next.js, no importe /next.

Adaptador de RSocket (opcional).

Instale el paquete peer solo en proyectos que utilizan RSocket.

En proyectos que no utilizan RSocket, no importe /rsocket.

Paths de createHttpClient<Paths>() representan el tipo que expresa la "especificación de solicitud (ruta)". En la documentación, se llama convencionalmente paths, pero no es necesario que sea OpenAPI/Swagger, ni que se llame paths.

Sin embargo, el núcleo utiliza internamente la restricción OpenApiPathsLike, por lo que Paths debe tener una forma similar a los paths de OpenAPI como se muestra a continuación.

• Clave superior: cadena de ruta URL (por ejemplo, "/users/{id}").
• Clave inferior: método HTTP (get/post/put/delete/patch …).
• Dentro de cada método, existen campos como parameters.query/path/header/cookie, requestBody, responses (o nunca).

El núcleo se refiere principalmente a los siguientes campos en esta estructura para construir el tipo de ServiceArguments.

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

Ej: la salida de openapi-typescript suele tener el siguiente formato (con algunas abreviaciones).

HeaderStore es un simple almacén en memoria para gestionar los encabezados básicos en CSR.

• headerStore es opcional, pero se recomienda incluirlo si se utilizan encabezados básicos/autenticación de sesión en CSR.
• headersProvider se utiliza cuando se necesita calcular encabezados por solicitud, como en SSR/multitenencia.

El tipo de solicitud (url/método/pathVariable/queryString/cuerpo) se determina a partir del tipo inyectado por el usuario en createHttpClient<Paths>() (por convención, rutas de OpenAPI). El tipo de respuesta es elegido por el llamador como genérico R en callApi<R>() (el núcleo no infiere automáticamente de responses).

Esta biblioteca no obliga a la envoltura de respuestas. Se puede elegir el formato de respuesta genérico por API.

Respuesta envuelta

Respuesta sin envolver

Cuando el servidor envía NDJSON (un JSON por línea), se utiliza callApiStream. Si no hay encabezado Accept, se establece application/x-ndjson como valor predeterminado.

Funciones proporcionadas por createCsrCache<CacheName>:

• callApiCsrCache(callApiFn, serviceArgs, cacheOptions)
• removeCsrCache(cacheName) — admite tanto el nombre del cache como cadenas.

createSessionAuth separa la lógica de autenticación de sesión del núcleo, permitiendo agregarla o quitarla como opción.

Funcionamiento:

• Mantener Authorization en headerStore
• Sincronizar token con ensureToken$() (/api/auth/token)
• Al ocurrir un 401, intenta refrescar una vez (/api/auth/token/refresh) y luego reintenta la solicitud original.
• Si el refresh falla, realiza logout (/api/auth/logout) y pasa el error.
• Los cambios en el estado de inicio de sesión se manejan externamente con el callback onLoginChange.

Si solo se necesita sincronizar el token sin refresh/retry:

Si no es 2xx, se lanza HttpResponseError (incluyendo status, response, args, data).

Compatibilidad heredada: si el cuerpo de error tiene la forma { resultType: ... }, se lanza ese objeto tal cual.

redirectToUnauthorizedOnServer401

redirectToUnauthorizedOnServer401 es la implementación básica (función de conveniencia) que realiza un redireccionamiento cuando ocurre un 401 en el entorno SSR de Next.js (App Router).

Reglas de funcionamiento (fijas):

• Destino de redirección: /unauthorized
• queryString: redirect_uri=<página actual> + logout=true
• La página actual se lee del encabezado x-page-url (si no existe, se usa /).

Es decir, use estas reglas de ruta/query solo si coinciden con su proyecto. Si la ruta es diferente o las reglas de query son distintas, implemente onServer401 directamente como se muestra a continuación y inyecte.

callApiSsrCache

Este es un asistente de caché SSR basado en next/cache(unstable_cache) de Next.

• GET + cacheTime > 0 → caché forzada + revalidar
• De lo contrario → no-store
• Inyección de Cookie / Authorization por solicitud a través de headersProvider
• Si ocurre 401 y hay onServer401, se ejecuta (normalmente redirect())

El siguiente rxjsHttpService.ts es el adaptador HTTP común del proyecto que se refiere al commonServiceFile del ejemplo de generador posterior. No es un archivo generado por la biblioteca, sino que es gestionado directamente por el proyecto, exportando el cliente central + autenticación de sesión + caché CSR + asistente de caché SSR en un solo lugar. A continuación se muestra el código completo.

createHttpClient<Paths>(opciones)

Retorna:

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

Opciones:

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

createHeaderStore(initial?)

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

createCsrCache<CacheName>()

• callApiCsrCache(callApiFn, serviceArgs, cacheForService)
• removeCsrCache(cacheName) (tipo + cadena)

createSessionAuth(options)

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

• Uso de fetch / Response API (rxjs/fetch)
• Streaming (NDJSON) requiere ReadableStream + TextDecoder
• SSE requiere EventSource

Está disponible en la mayoría de los navegadores modernos y en el tiempo de ejecución de Next.js. Puede requerir un polyfill en un tiempo de ejecución de Node personalizado.

Este paquete proporciona, además del cliente HTTP en tiempo de ejecución, un script de Node que genera código de tipo/servicio a partir de JSON de OpenAPI/Swagger. Este script es una función opcional.

Los usuarios de @byeolnaerim/typed-rx-http, /next, /rsocket no necesitan ejecutar este script ni instalar openapi-typescript.

Aislamiento de dependencias

La generación de tipos OpenAPI requiere el CLI de openapi-typescript. Sin embargo, este paquete no incluye openapi-typescript en las dependencias generales.

La biblioteca @byeolnaerim/typed-rx-http utiliza TypeScript 6.0.3 en devDependencies.typescript. Los puntos de entrada de typed-rx-http, /next, /rsocket y la construcción de la biblioteca mantienen este estándar de TypeScript 6.0.3.

Sin embargo, openapi-typescript puede requerir una versión específica de TypeScript 5.x, por lo que el script de auto nodo de OpenAPI se ejecuta en un entorno temporal separado con openapi-typescript y [email protected]. Este entorno temporal no cambia el devDependencies.typescript 6.0.3 de la biblioteca y no utiliza la versión de typescript o openapi-typescript instalada en el proyecto del usuario.

El valor por defecto es generar y ejecutar el siguiente comando solo en el momento de la ejecución del script automático.

Por lo tanto, la forma de uso no cambia. Se puede llamar al script de nodo automático como antes, y solo se utiliza un entorno aislado de TypeScript 5.9.3 en la etapa de generación de tipos de OpenAPI. Los usuarios que no utilizan el script automático no están atados a openapi-typescript ni a TypeScript 5.9.3.

Si es necesario, puedes fijar el comando directamente con openApiTypescriptCommand.

O puedes cambiar solo la versión del paquete que configura el comando por defecto.

Archivos generados

La configuración predeterminada genera los siguientes archivos.

apiUnionArrays.ts genera no solo enums del esquema OpenAPI, sino también enums de parámetros de consulta, ruta, encabezado y cookie como arreglos constantes. También maneja los items.enum de los parámetros de consulta en arreglo.

Monitoreo de EventStream

Solicitud HTTP única

Generar desde un archivo local

El código del backend se escribe como de costumbre. En este ejemplo, se recibe el nombre como variable de ruta y el mensaje como parámetro de consulta. Monoy se responde.

Recibe el del backend. swagger.jsony genera los archivos de tipo y servicio. Esta tarea se puede llamar una vez al ejecutar el servidor de desarrollo o conectarse con un script de vigilancia.

Puede cambiar a continuación. Código del Backenddel elemento objetivo y ResultadoPuede hacer clic para abrir la pantalla de ejecución a la derecha. Cambie los valores y presione el botón de solicitud. Parte visible en el proyecto real.Código del Front