Démarrage rapide

• Injection de types de chemins de style OpenAPI obtenus à partir de schémas dérivés Swagger/OpenAPI / AsyncAPI / contrats personnalisés, etc. pour assurer la stabilité des types de requêtes.
• Toutes les API retournent des Observables RxJS.
• core est indépendant du framework (pas de dépendance à Next.js).
• Les fonctionnalités spécifiques à Next.js sont séparées dans le point d'entrée @byeolnaerim/typed-rx-http/next → Next.js n'est nécessaire que lors de l'importation de /next.
• Les fonctionnalités spécifiques à RSocket sont séparées dans le point d'entrée @byeolnaerim/typed-rx-http/rsocket → le package RSocket n'est nécessaire que lors de l'importation de /rsocket.

npm

Core (indépendant du framework)

Adaptateur Next.js (optionnel).

Ne pas importer /next dans les projets qui n'utilisent pas Next.js.

Adaptateur RSocket (optionnel).

Installez le package peer uniquement dans les projets utilisant RSocket.

Ne pas importer /rsocket dans les projets qui n'utilisent pas RSocket.

Le type Paths de createHttpClient<Paths>() représente la spécification de la requête (route). Dans la documentation, il est généralement appelé paths, mais il n'est pas nécessaire que ce soit OpenAPI/Swagger, ni que son nom soit paths.

Cependant, le core utilise en interne la contrainte OpenApiPathsLike, donc Paths doit avoir une forme similaire aux chemins OpenAPI comme ci-dessous.

• Clé principale : chaîne de chemin d'URL (ex : "/users/{id}")
• Clé secondaire : méthode HTTP (get/post/put/delete/patch …)
• Chaque méthode contient des champs comme parameters.query/path/header/cookie, requestBody, responses (ou jamais).

Le core se réfère principalement aux champs ci-dessus pour construire le type des ServiceArguments.

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

Exemple : la sortie openapi-typescript est généralement conforme aux spécifications ci-dessous (avec quelques abréviations).

HeaderStore est un simple store en mémoire pour gérer les en-têtes par défaut dans le CSR.

• headerStore est optionnel, mais il est recommandé de l'utiliser pour les en-têtes par défaut/authentification de session dans le CSR.
• headersProvider est utilisé lorsque le calcul des en-têtes est nécessaire pour chaque requête, comme dans SSR/multi-tenant.

Le type de requête (url/méthode/pathVariable/queryString/body) est déterminé par le type injecté par l'utilisateur dans createHttpClient<Paths>() (par convention, les chemins OpenAPI). Le type de réponse est choisi par l'appelant dans callApi<R>() avec le générique R (le cœur ne l'infère pas automatiquement à partir des réponses).

Cette bibliothèque ne force pas l'enveloppement des réponses. Vous pouvez choisir le format de réponse générique par API.

Réponse enveloppée

Réponse sans enveloppe

Utilisez callApiStream lorsque le serveur renvoie NDJSON (un JSON par ligne). Si l'en-tête Accept est absent, application/x-ndjson est défini par défaut.

Fonctionnalités fournies par createCsrCache<CacheName>() :

• callApiCsrCache(callApiFn, serviceArgs, cacheOptions)
• removeCsrCache(cacheName) — prend en charge le nom du cache de type + chaîne.

createSessionAuth sépare la logique d'authentification de session du cœur, permettant de l'ajouter ou de la retirer en option.

Fonctionnement :

• Maintenir l'Authorization dans headerStore
• Synchronisation du token avec ensureToken$() (/api/auth/token)
• En cas de 401, tentez un rafraîchissement une fois (/api/auth/token/refresh) puis réessayez la demande d'origine.
• En cas d'échec du rafraîchissement, déconnexion (/api/auth/logout) et transmission de l'erreur.
• Les changements d'état de connexion sont gérés de l'extérieur via le callback onLoginChange.

Si seule la synchronisation du token est nécessaire sans rafraîchissement/réessai :

Si ce n'est pas un 2xx, une HttpResponseError est levée (incluant status, response, args, data).

Compatibilité héritée : si le corps d'erreur est sous la forme { resultType: ... }, cet objet est levé tel quel.

redirectToUnauthorizedOnServer401

redirectToUnauthorizedOnServer401 est l'implémentation par défaut (fonction utilitaire) qui effectue une redirection lorsque 401 se produit dans l'environnement SSR de Next.js (App Router).

Règles de fonctionnement (fixes) :

• Cible de redirection : /unauthorized
• queryString : redirect_uri=<page actuelle> + logout=true
• La page actuelle est lue dans l'en-tête x-page-url (ou / si absent).

C'est-à-dire, n'utilisez ces règles de chemin/query que si elles correspondent au projet. Si le chemin est différent ou si les règles de query diffèrent, vous pouvez implémenter onServer401 directement comme ci-dessous et l'injecter.

callApiSsrCache

C'est un assistant de cache SSR basé sur next/cache(unstable_cache) de Next.

• GET + cacheTime > 0 → force-cache + revalidate
• Autres → no-store
• Injection de Cookie / Authorization par requête via headersProvider
• En cas de 401, exécute onServer401 s'il existe (généralement redirect())

Le fichier rxjsHttpService.ts ci-dessous est l'adaptateur HTTP commun du projet désigné par commonServiceFile dans l'exemple de générateur suivant. Ce n'est pas un fichier généré par la bibliothèque, mais géré directement par le projet, exportant le client de base + l'authentification de session + le cache CSR + l'assistant de cache SSR en un seul endroit. Voici le code complet.

createHttpClient<Paths>(options)

Retourne :

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

Options :

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

createHeaderStore(initial?)

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

createCsrCache<CacheName>()

• callApiCsrCache(callApiFn, serviceArgs, cacheForService)
• removeCsrCache(cacheName) (type + chaîne)

createSessionAuth(options)

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

• Utilisation de l'API fetch / Response (rxjs/fetch)
• Le streaming (NDJSON) nécessite ReadableStream + TextDecoder
• SSE nécessite EventSource

La plupart des navigateurs modernes et l'exécution Next.js le prennent en charge par défaut. Un polyfill peut être nécessaire pour un runtime Node personnalisé.

Ce package fournit également un script Node qui génère du code de type/service à partir de JSON OpenAPI/Swagger, séparément du client HTTP d'exécution. Ce script est une fonctionnalité optionnelle.

Les utilisateurs de @byeolnaerim/typed-rx-http, /next, /rsocket n'ont pas besoin d'exécuter ce script et n'ont pas besoin d'installer openapi-typescript.

Isolation des dépendances

La génération de types OpenAPI nécessite openapi-typescript CLI. Cependant, ce package ne met pas openapi-typescript dans les dépendances générales.

La bibliothèque @byeolnaerim/typed-rx-http utilise TypeScript 6.0.3 dans devDependencies.typescript. Les points d'entrée et la construction de la bibliothèque typed-rx-http, /next, /rsocket maintiennent cette norme TypeScript 6.0.3.

Cependant, openapi-typescript peut encore nécessiter une version spécifique de TypeScript 5.x, donc le script auto node OpenAPI s'exécute séparément dans un environnement d'exécution temporaire avec openapi-typescript et [email protected]. Cet environnement d'exécution temporaire ne modifie pas le devDependencies.typescript 6.0.3 de la bibliothèque et n'utilise pas la version de typescript ou openapi-typescript installée dans le projet de l'utilisateur.

La valeur par défaut est de générer et d'exécuter les commandes ci-dessous uniquement au moment de l'exécution du script auto.

Ainsi, l'utilisation elle-même ne change pas. Il suffit d'appeler le script auto node comme auparavant, et un environnement TypeScript 5.9.3 isolé est utilisé uniquement lors de la génération des types OpenAPI. Les utilisateurs qui n'utilisent pas le script auto ne sont pas du tout liés à openapi-typescript ou TypeScript 5.9.3.

Si nécessaire, vous pouvez fixer les commandes directement avec openApiTypescriptCommand.

Ou vous pouvez simplement changer la version du package qui configure la commande par défaut.

Fichiers générés

Les paramètres par défaut génèrent les fichiers ci-dessous.

apiUnionArrays.ts génère des tableaux constants non seulement pour les énumérations du schéma OpenAPI, mais aussi pour les énumérations des paramètres de requête, de chemin, d'en-tête et de cookie. Il traite également les items.enum des paramètres de requête sous forme de tableau.

Surveillance de l'EventStream

Requête HTTP unique

Généré à partir d'un fichier local

Le code backend est écrit comme d'habitude. Dans cet exemple, il reçoit un nom en tant que variable de chemin et un message en tant que paramètre de requête. Monoet répond.

Recevez le fichier de type et de service du backend. swagger.jsonCette opération peut être appelée une fois lors de l'exécution du serveur de développement ou connectée via un script de surveillance.

Vous pouvez essayer de modifier ci-dessous. Code Backendde l'élément cible et RésultatEn cliquant, l'écran d'exécution s'ouvrira à droite. Modifiez les valeurs puis appuyez sur le bouton de demande. Partie visible dans le projet réel.Code Front