Início Rápido

• Injetar tipos de Paths estilo OpenAPI obtidos de esquemas derivados de Swagger/OpenAPI / AsyncAPI / contratos personalizados, garantindo a segurança do tipo de rota (requisição).
• Todas as APIs retornam RxJS Observable.
• O core é independente de framework (sem dependência do Next.js).
• Funcionalidades específicas do Next.js são separadas no ponto de entrada @byeolnaerim/typed-rx-http/next → Next.js é necessário apenas ao importar /next.
• Funcionalidades específicas do RSocket são separadas no ponto de entrada @byeolnaerim/typed-rx-http/rsocket → RSocket é necessário apenas ao importar /rsocket.

npm

Core (independente de framework)

Adaptador Next.js (opcional).

Em projetos que não utilizam Next.js, não importe /next.

Adaptador RSocket (opcional).

Instale o pacote peer apenas em projetos que utilizam RSocket.

Em projetos que não utilizam RSocket, não importe /rsocket.

Os Paths em createHttpClient<Paths>() representam o tipo que expressa a "especificação da requisição (rota)". Na documentação, é comumente chamado de paths, mas não precisa ser necessariamente OpenAPI/Swagger, nem ter o nome de paths.

No entanto, o core utiliza internamente a restrição OpenApiPathsLike, portanto, os Paths devem ter uma forma semelhante aos paths do OpenAPI.

• Chave de nível superior: string de caminho da URL (ex: "/users/{id}").
• Chave de nível inferior: método HTTP (get/post/put/delete/patch …).
• Dentro de cada método, existem campos como parameters.query/path/header/cookie, requestBody, responses (ou nunca).

O core refere-se principalmente aos campos abaixo para compor o tipo ServiceArguments.

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

Ex: a saída do openapi-typescript geralmente segue o padrão abaixo (com algumas abreviações).

HeaderStore é um simples armazenamento em memória para gerenciar cabeçalhos padrão no CSR.

• headerStore é opcional, mas é recomendado incluí-lo se você quiser usar cabeçalhos padrão/autenticação de sessão no CSR.
• headersProvider é usado quando é necessário calcular cabeçalhos para cada solicitação, como em SSR/multi-tenant.

O tipo de solicitação (url/método/pathVariable/queryString/corpo) é determinado pelo tipo injetado pelo usuário em createHttpClient<Paths>() (geralmente caminhos OpenAPI). O tipo de resposta é escolhido pelo chamador em callApi<R>() como um genérico R (o núcleo não infere automaticamente das respostas).

Esta biblioteca não força o encapsulamento de resposta. Você pode escolher o formato de resposta genericamente para cada API.

Resposta encapsulada

Resposta sem encapsulamento

Quando o servidor retorna NDJSON (um JSON por linha), use callApiStream. Se não houver cabeçalho Accept, application/x-ndjson será definido como padrão.

Funcionalidade fornecida por createCsrCache<CacheName>:

• callApiCsrCache(callApiFn, serviceArgs, cacheOptions)
• removeCsrCache(cacheName) — suporta tanto nomes de cache de tipo quanto strings.

createSessionAuth separa a lógica de autenticação de sessão do núcleo, permitindo que você a adicione ou remova como uma opção.

Funcionamento:

• Manter Authorization no headerStore
• Sincronizar token com ensureToken$() (/api/auth/token)
• Ao ocorrer 401, tente refresh uma vez (/api/auth/token/refresh) e reenvie a solicitação original.
• Se o refresh falhar, faça logout (/api/auth/logout) e passe o erro.
• Mudanças no estado de login são tratadas externamente pelo callback onLoginChange.

Se apenas a sincronização do token for necessária, sem refresh/retry:

Se não for 2xx, lança HttpResponseError (incluindo status, resposta, args, dados).

Compatibilidade legada: se o corpo do erro estiver no formato { resultType: ... }, lança esse objeto diretamente.

redirectToUnauthorizedOnServer401

redirectToUnauthorizedOnServer401 é a implementação padrão (função de conveniência) que realiza o redirecionamento quando ocorre 401 no ambiente SSR do Next.js (App Router).

Regras de operação (fixas):

• Destino do redirecionamento: /unauthorized
• queryString: redirect_uri=<página atual> + logout=true
• A página atual é lida do cabeçalho x-page-url (se não houver, será /).

Ou seja, use essas regras de caminho/query apenas se elas corresponderem ao seu projeto. Se o caminho for diferente ou as regras de query forem diferentes, você pode implementar onServer401 diretamente e injetá-lo como abaixo.

callApiSsrCache

Este é um assistente de cache SSR baseado em next/cache(unstable_cache) do Next.

• GET + cacheTime > 0 → force-cache + revalidate
• Outros → no-store
• Injeção de Cookie / Autorização por solicitação com headersProvider
• Se ocorrer 401 e houver onServer401, execute (geralmente redirect())

O rxjsHttpService.ts abaixo é o adaptador HTTP comum do projeto que é referenciado pelo commonServiceFile do exemplo do gerador a seguir. Não é um arquivo gerado pela biblioteca, mas gerenciado diretamente pelo projeto, exportando core client + session auth + CSR cache + SSR cache helper em um só lugar. Abaixo está o código completo.

createHttpClient<Paths>(options)

Retorno:

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

Opções:

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

createHeaderStore(initial?)

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

createCsrCache<CacheName>()

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

createSessionAuth(options)

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

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

A maioria dos navegadores modernos e o tempo de execução do Next.js oferecem suporte nativo. Um tempo de execução Node personalizado pode precisar de um polyfill.

Este pacote fornece, além do cliente HTTP em tempo de execução, um script Node que gera código de tipo/serviço a partir de JSON OpenAPI/Swagger. Este script é uma funcionalidade opcional.

Usuários comuns de @byeolnaerim/typed-rx-http, /next, /rsocket não precisam executar este script e não precisam instalar openapi-typescript.

Isolamento de dependências

A geração de tipos OpenAPI requer o CLI openapi-typescript. No entanto, este pacote não inclui openapi-typescript nas dependências gerais.

A biblioteca @byeolnaerim/typed-rx-http em si usa TypeScript 6.0.3 em devDependencies.typescript. Os pontos de entrada e a construção da biblioteca typed-rx-http, /next, /rsocket mantêm esse padrão de TypeScript 6.0.3.

No entanto, openapi-typescript pode exigir uma versão específica do TypeScript 5.x, portanto, o script auto node OpenAPI é executado em um ambiente temporário npx separado com openapi-typescript e [email protected]. Este ambiente temporário não altera o devDependencies.typescript 6.0.3 da biblioteca e não usa a versão do typescript ou openapi-typescript instalada no projeto do usuário.

O padrão é gerar e executar os seguintes comandos apenas no momento da execução do script automático.

Portanto, a forma de uso não muda. Você pode chamar o script auto node como antes, e um ambiente isolado de TypeScript 5.9.3 será usado apenas na etapa de geração de tipos OpenAPI. Usuários que não usam o script automático não ficam vinculados ao openapi-typescript ou TypeScript 5.9.3.

Se necessário, você pode fixar o comando diretamente com openApiTypescriptCommand.

Ou você pode apenas alterar a versão do pacote que configura o comando padrão.

Arquivos gerados

As configurações padrão geram os arquivos abaixo.

apiUnionArrays.ts gera não apenas enums do esquema OpenAPI, mas também enums de parâmetros de query, path, header e cookie como arrays constantes. Também lida com os items.enum de parâmetros de query em array.

Monitoramento de EventStream

Requisição HTTP única

Gerar a partir de arquivo local

O código do backend é escrito como de costume. Neste exemplo, recebemos o nome como variável de caminho e a mensagem como parâmetro de consulta. MonoE respondemos.

Receba o do backend. swagger.jsonGere os arquivos de tipo e serviço. Esta tarefa pode ser chamada uma vez ao executar o servidor de desenvolvimento ou conectada a um script de observação.

Você pode alterar abaixo. Código Backenddo elemento alvo e ResultadoVocê pode clicar para abrir a tela de execução à direita. Altere os valores e pressione o botão de solicitação. Parte visível no projeto real.Código Front