--- title: "Référence d'API — nodefony/react" source: docs/api/core/react.md url: https://nodefony.github.io/nodefony-core/docs/api/core/react/ --- [Documentation](../../../) › [Référence d'API](../../) › [`nodefony`](../) › react > Générée depuis les déclarations de types publiées de `nodefony` **10.0.0-beta.5** : exactement ce que reçoit une application qui l'installe. Cette page n'existe dans aucun dépôt — pour la corriger, on corrige le TSDoc du code. ## `nodefony/react` `import { … } from "nodefony/react"` — 47 symboles. ### Classes (1) #### `NodefonyLogin` ```ts class NodefonyLogin ``` Le **déroulé de connexion** côté navigateur : une machine à états PURE, sans DOM ni framework d'affichage, branchée sur les routes de session du framework. Le pendant de `NodefonySocket` et de `NodefonySse` pour l'authentification. - `constructor(options?: NodefonyLoginOptions)` - `readonly getState: () => NodefonyLoginState` — État courant — le même objet tant que rien n'a changé. - `readonly subscribe: (listener: (state: NodefonyLoginState) => void) => () => void` — Écoute les changements d'état. - `submitIdentifier(identifier: string): void` — Valide le compte saisi et passe à l'étape `password`. - `submitPassword(password: string): Promise` — Envoie le mot de passe du compte saisi. - `login(identifier: string, password: string): Promise` — Raccourci des formulaires d'un seul écran : compte et mot de passe d'un coup. - `submitMfaCode(code: string): Promise` — Envoie le code du second facteur (TOTP ou code de récupération). - `loginWithPasskey(): Promise` — Connexion par passkey, sans identifiant ni mot de passe. - `loadProviders(): Promise` — Charge la liste des fournisseurs (une requête, rejouée seulement après échec). - `startProvider(name: string, from?: string, back?: string): void` — Part chez un fournisseur, en navigation PLEINE PAGE — jamais par `fetch` : le navigateur doit suivre les redirections et revenir avec le cookie de session posé au retour. - `me(): Promise` — Reprend une session existante ; `null` quand il n'y en a pas. - `logout(): Promise` — Ferme la session et revient à l'étape `identifier`. - `back(): void` — Revient à l'étape `identifier`, en gardant le compte saisi. ### Fonctions (21) #### `NodefonyProvider` ```ts function NodefonyProvider(props: NodefonyProviderProps): React.ReactElement ``` Injecte le client temps réel Nodefony dans le sous-arbre. À monter une fois, au-dessus des composants qui consomment les hooks `useNodefony*`. #### `isRateChannel` ```ts function isRateChannel(channel: string, base: string): boolean ``` Vrai si `channel` est le canal de base nu OU une de ses variantes cadencées `base:`. #### `parseRate` ```ts function parseRate(channel: string, base: string, bounds: RateBounds): number ``` Résout la cadence (ms) d'un canal cadencé connu, côté serveur. Le serveur connaît la `base` qu'il vient de matcher ; ce helper en extrait le suffixe `:`, **borne** dans `bounds` et retombe sur `bounds.default` pour le canal de base nu ou un suffixe invalide. #### `rateChannel` ```ts function rateChannel(base: string, intervalMs?: number, defaultMs?: number): string ``` Construit le nom d'un canal cadencé à partir de sa base et de la cadence demandée. #### `useNodefony` ```ts function useNodefony(): NodefonySocket ``` `useNodefony()` — le client temps réel brut (hub : canaux, syslog, stats…). Tête de gondole + échappatoire pour les cas avancés. Référence stable (pas de re-render) ; pour l'état réactif, utiliser les hooks dédiés ci-dessous. #### `useNodefonyAdaptiveChannel` ```ts function useNodefonyAdaptiveChannel(base: string, onMessage: (payload: unknown) => void, desiredMs: number, opts?: AdaptiveChannelHookOptions, deps?: React.DependencyList): number ``` `useNodefonyAdaptiveChannel()` — équivalent **handler-based** de `useNodefonyChannel` mais en **cadence adaptative** (AIMD client-driven, cf `NodefonySocket.adaptiveChannel`) : la lib recule la cadence sous famine puis la remonte quand c'est sain. `onMessage` reçoit chaque frame (handler riche autorisé) ; **renvoie la cadence effective** (ms) pour un badge. Primitif commun à tous les dashboards d'état (Supervision, ORM…) → **logique live identique**. Réservé aux canaux d'ÉTAT (latest-wins). Réglage `enabled` (off = abonnement fixe). #### `useNodefonyAdaptiveChannelData` ```ts function useNodefonyAdaptiveChannelData(base: string, desiredMs: number, opts?: AdaptiveChannelHookOptions, deps?: React.DependencyList): AdaptiveChannelData ``` `useNodefonyAdaptiveChannelData()` — comme `useNodefonyChannelData` mais en cadence adaptative. Mince surcouche de `useNodefonyAdaptiveChannel` : garde la **dernière valeur** reçue + renvoie la cadence effective (badge UI). Réservé aux canaux d'ÉTAT. #### `useNodefonyChannel` ```ts function useNodefonyChannel(channel: string, onMessage: (payload: unknown) => void, deps?: React.DependencyList): void ``` `useNodefonyChannel()` — s'abonne à un canal pub/sub : `onMessage` est appelé à chaque message. Le socle apparie subscribe/unsubscribe serveur (ref-comptés) et le re-subscribe au reconnect. Le handler peut changer à chaque render sans re-déclencher l'abonnement (capturé via ref) ; passer `deps` si le canal effectif dépend d'autres valeurs. #### `useNodefonyChannelData` ```ts function useNodefonyChannelData(channel: string, initial?: T | null): T | null ``` `useNodefonyChannelData()` — la **dernière valeur** reçue sur un canal (cas le plus courant : dernière mesure d'un flux de stats). `null` tant que rien n'est arrivé. #### `useNodefonyChannelStats` ```ts function useNodefonyChannelStats(channel: string): ChannelStatsSnapshot | null ``` `useNodefonyChannelStats()` — stats live d'un canal (débit, série VU-mètre, total). Source = le client Core (`getChannelStats`, échantillonné 1×/s). Implémenté en `state`+effet (pas `useSyncExternalStore`) car le snapshot est un objet recréé → la stabilité de référence requise par le store externe ne tiendrait pas. #### `useNodefonyIdentity` ```ts function useNodefonyIdentity(): RealtimeIdentity | null ``` `useNodefonyIdentity()` — l'**identité résolue** de la connexion, annoncée par le serveur au `realtime:welcome` (`authenticated`, `roles`, `userIdentifier`, `scopes`). `null` tant qu'aucun welcome n'a été reçu ; une fois reçu, un visiteur anonyme a `authenticated: false`. `useSyncExternalStore` → re-render uniquement quand l'identité change ((re)welcome ou logout). Brique du gating front : `authenticated:false` → écran login, **sans** route `/auth/me`. #### `useNodefonyKernel` ```ts function useNodefonyKernel(): INodefonyKernel | null ``` `useNodefonyKernel()` — le noyau client fourni au ``, ou `null` quand l'application n'en compose pas. Référence stable ; pour l'état réactif, prendre `useNodefonyKernelState` et `useNodefonyKernelIdentity`. #### `useNodefonyKernelIdentity` ```ts function useNodefonyKernelIdentity(): NodefonyKernelIdentity | null ``` `useNodefonyKernelIdentity()` — l'identité DÉCLARÉE au noyau par l'application (`setIdentity`), ou `null` hors session ou sans noyau fourni. Re-render à chaque changement de COMPTE — un profil rafraîchi à clé inchangée ne réveille personne (règle d'identité du noyau). #### `useNodefonyKernelState` ```ts function useNodefonyKernelState(): NodefonyKernelState | null ``` `useNodefonyKernelState()` — l'état du noyau (`created` → `booting` → `ready` → `terminated`), ou `null` sans noyau fourni. Re-render uniquement aux transitions. #### `useNodefonyLogin` ```ts function useNodefonyLogin(options?: NodefonyLoginOptions): NodefonyLoginBinding ``` `useNodefonyLogin()` — le déroulé de connexion du framework, relayé en état React. Le balisage reste entièrement à l'application ; les règles (étapes, second facteur, blocage, fournisseurs, passkey) vivent dans `NodefonyLogin` (`nodefony/client`), jamais ici. #### `useNodefonyNoticeLog` ```ts function useNodefonyNoticeLog(opts?: UseNoticeLogOptions): NodefonyNotice[] ``` `useNodefonyNoticeLog()` — ring buffer borné des dernières notices, filtrable par source. Brique du hub temps réel (« incidents temps réel ») : un historique léger des criticités realtime, distinct des toasts éphémères. La taille de l'anneau et le filtrage viennent du socle (`observeNoticeLog`). #### `useNodefonyNotifications` ```ts function useNodefonyNotifications(onNotice: (notice: NodefonyNotice) => void, deps?: React.DependencyList): void ``` `useNodefonyNotifications()` — s'abonne au flux de **notices normalisées** du client : criticités qui cassent le temps réel (close codes RFC 6455 interprétés), erreurs serveur poussées, rétablissement de connexion. `onNotice` est appelé pour CHAQUE notice → brancher un centre de notifications (snackbar). Le handler peut changer à chaque render sans re-déclencher l'abonnement (capturé via ref). #### `useNodefonySnapshot` ```ts function useNodefonySnapshot(): SocketSnapshot | null ``` `useNodefonySnapshot()` — ce que la socket sait d'ELLE-MÊME : état, canaux tenus, trames reçues, trames perdues, dernière trame. Rafraîchi par l'échantillonneur déjà en place — aucune horloge de plus, aucune trame émise pour mesurer. #### `useNodefonySse` ```ts function useNodefonySse(url: string | null, options?: ObserveSseOptions): SseSnapshot ``` `useNodefonySse()` — ouvre un flux SSE au montage, rend son état (`readyState`, dernier événement, erreur), et le FERME au démontage. #### `useNodefonyState` ```ts function useNodefonyState(): RealtimeState ``` `useNodefonyState()` — état de la connexion (`"connected" | "reconnecting" | …`). `useSyncExternalStore` : re-render UNIQUEMENT au changement d'état (snapshot primitif, sans tearing en mode concurrent). #### `useNodefonySyslog` ```ts function useNodefonySyslog(opts?: UseSyslogOptions): unknown[] ``` `useNodefonySyslog()` — flux syslog prêt à l'emploi : ring buffer borné + filtre de sévérité. Le format **coalescé** du canal (`{ logs: Pdu[], dropped }`), l'entrée unique, la taille de l'anneau et le canal par défaut viennent du socle (`observeSyslog`) : ce hook n'en connaît aucun. Brique de la page Logs — un seul appel remplace l'effet + le buffer manuels. ### Interfaces (19) #### `AdaptiveChannelData` ```ts interface AdaptiveChannelData ``` Résultat de `useNodefonyAdaptiveChannelData` : dernière valeur + cadence réelle. - `data: T | null` — Dernière valeur reçue, `null` tant que rien n'est arrivé. - `intervalMs: number` — Cadence effective courante (ms) — bouge avec l'AIMD, à afficher en badge. #### `INodefonyKernel` ```ts interface INodefonyKernel ``` Contrat du kernel client isomorphe (ADR-0007 D2 — surface v1, volontairement minimale : chaque méthode publiée est une promesse SemVer). - `get(name: K): NodefonyKernelServices[K]` — Récupère un service enregistré (ou `undefined` s'il n'est pas composé). - `set(name: K, svc: NodefonyKernelServices[K]): void` — Enregistre un service sous son nom contractuel. - `has(name: string): boolean` — Teste la présence d'un service (nom libre, y compris hors contrat). - `boot(): Promise` — Compose et connecte les services (idempotent). - `terminate(): Promise` — Flush l'observabilité et déconnecte (best-effort sur `pagehide`). - `readonly state: NodefonyKernelState` — État courant du kernel — jamais régressif. - `setIdentity(identity: NodefonyKernelIdentity | null): void` — Déclare l'identité runtime courante — c'est l'application qui la connaît (login, logout, bascule de compte), le kernel qui en tire les conséquences. - `readonly identity: NodefonyKernelIdentity | null` — Identité runtime courante, telle que l'application l'a déclarée. - `on(event: NodefonyKernelEvent, handler: (...args: unknown[]) => void): this` — Abonne un handler à un événement du kernel (API `Event` du Core, chaînable). - `off(event: NodefonyKernelEvent, handler: (...args: unknown[]) => void): this` — Retire un handler abonné par `on` (chaînable). - `readonly syslog: Syslog` — Journal client de série (`Pdu` isomorphes — corrélables au back par `requestId`). #### `ISseEvent` ```ts interface ISseEvent ``` Un événement reçu, une fois sa ligne vide atteinte (WHATWG §9.2.6). - `readonly type: string` — Le champ `event`, ou `"message"` quand le bloc n'en portait pas. - `readonly data: string` — Les champs `data` du bloc, joints par un saut de ligne. - `readonly lastEventId: string` — L'identifiant courant du flux, après ce bloc — `""` s'il n'y en a jamais eu. #### `NodefonyKernelIdentity` ```ts interface NodefonyKernelIdentity ``` Identité runtime déclarée par l'application au kernel. - `readonly key: string` — Clé stable du compte — l'unique critère du re-handshake (D9). - `readonly data?: unknown` — Charge libre, opaque au kernel. #### `NodefonyLoginBinding` ```ts interface NodefonyLoginBinding ``` Ce que rend `useNodefonyLogin` : l'état, et le déroulé qui porte les actions. - `readonly state: NodefonyLoginState` — Photographie du déroulé, renouvelée à chaque changement. - `readonly flow: NodefonyLogin` — Les actions : `login`, `submitMfaCode`, `startProvider`, `logout`… #### `NodefonyLoginError` ```ts interface NodefonyLoginError ``` Échec classé de la dernière action. - `readonly kind: LoginErrorKind` - `readonly message: string` — Message du serveur, relayé TEL QUEL — en particulier le refus uniforme d'un 401, qui ne doit jamais être reformulé : le préciser côté client dirait à un inconnu si le compte existe. - `readonly status: number | null` — Statut HTTP, `null` quand le serveur n'a pas répondu. - `readonly retryAt: number | null` — Fin du blocage (millisecondes depuis l'époque) — seulement pour `throttled`. #### `NodefonyLoginOptions` ```ts interface NodefonyLoginOptions ``` Réglages de `NodefonyLogin` — tous facultatifs. - `readonly baseUrl?: string` — Origine du serveur ; vide = même origine que la page. - `readonly identifier?: string` — Compte prérempli (le dernier utilisé, mémorisé par l'application). - `readonly fetch?: typeof fetch` — `fetch` à employer ; défaut : celui du navigateur. - `readonly navigate?: (url: string) => void` — Navigation pleine page vers un fournisseur ; défaut : `location.assign`. - `readonly passkey?: NodefonyPasskeyAgent | null` — Signataire de passkey ; défaut : l'API WebAuthn native, si elle est complète. - `readonly now?: () => number` — Horloge (ms) ; défaut : `Date.now`. - `readonly defaultRetryAfterS?: number` — Attente appliquée quand un 429 ne dit pas combien de temps (secondes). #### `NodefonyLoginProvider` ```ts interface NodefonyLoginProvider ``` Fournisseur de connexion, tel que le SERVEUR le présente. - `readonly name: string` - `readonly label: string` #### `NodefonyLoginState` ```ts interface NodefonyLoginState ``` Photographie du déroulé — un objet NEUF à chaque changement, jamais muté. - `readonly step: LoginStep` - `readonly identifier: string` — Compte saisi (ou rendu par le serveur une fois connecté). - `readonly pending: boolean` — Une requête est en vol : l'écran désactive ses boutons. - `readonly user: NodefonyLoginUser | null` — Identité de la session, `null` tant qu'elle n'est pas ouverte. - `readonly mfaMethods: readonly string[]` — Seconds facteurs proposés par le serveur à l'étape `mfa`, réduits à ceux que ce client sait conduire (aujourd'hui `totp`). - `readonly error: NodefonyLoginError | null` - `readonly providers: readonly NodefonyLoginProvider[] | null` — Fournisseurs configurés ; `null` tant que `NodefonyLogin.loadProviders` n'a pas répondu. - `readonly passkeyAvailable: boolean` — Le navigateur sait-il signer avec une passkey ? #### `NodefonyLoginUser` ```ts interface NodefonyLoginUser ``` Identité rendue par le serveur une fois la session ouverte. - `readonly id: number | string` - `readonly identifier: string` — Identifiant de connexion (login, e-mail, sujet fédéré) — le même que `IUser.identifier`. - `readonly email?: string` - `readonly roles: readonly string[]` - `readonly [field: string]: unknown` #### `NodefonyNotice` ```ts interface NodefonyNotice ``` Notice normalisée prête à afficher (snackbar / centre de notifications). - `level: NoticeLevel` — Sévérité d'affichage. - `title?: string` — Titre court (gras), optionnel. - `message: string` — Message lisible (déjà localisé FR). - `source: "realtime" | "api" | "server"` — Origine — `realtime` (transport WS), `api` (data plane HTTP), `server` (push). - `code?: number` — Code corrélé : close code WS, status HTTP ou code d'erreur JSON-RPC. - `ts: number` — Timestamp (ms epoch) de production. #### `NodefonyProviderProps` ```ts interface NodefonyProviderProps ``` - `kernel?: INodefonyKernel` — Le noyau client de l'application — la voie COMPOSÉE. - `url?: string` — Adresse du serveur temps réel — la voie SIMPLE. - `client?: NodefonySocket` — Socket déjà construite — la voie AVANCÉE, quand l'application possède son cycle de connexion (c'est le cas de la console d'administration, qui re-négocie la socket sur changement d'identité). - `children?: React.ReactNode` #### `ObserveSseOptions` ```ts interface ObserveSseOptions extends NodefonySseOptions ``` Réglages de `observeSse` : ceux de `NodefonySse`, plus deux. - `events?: readonly string[]` — Types d'événements écoutés — le champ `event:` du serveur. - `onEvent?: (event: ISseEvent) => void` — Appelé pour CHAQUE événement reçu, avant la mise à jour de l'état. #### `RateBounds` ```ts interface RateBounds ``` Bornes de cadence d'un canal cadencé (toutes en millisecondes). - `readonly default: number` — Cadence par défaut — celle du canal de base nu (sans suffixe). - `readonly min: number` — Borne basse (cadence minimale autorisée, anti-DoS event-loop). - `readonly max: number` — Borne haute (cadence maximale autorisée). #### `RealtimeIdentity` ```ts interface RealtimeIdentity ``` Identité d'une connexion temps réel, telle que **résolue par le serveur au handshake** (token neutre `IRealtimeToken` côté back) et **annoncée au client** dans la notification système `realtime:welcome`. - `type: string` — Type de token résolu (`"anonymous"`, `"session"`, `"jwt"`, …) — discriminator. - `authenticated: boolean` — `false` pour un visiteur anonyme (Zero Trust : toujours présent, jamais `null`). - `userIdentifier: string` — Identifiant logique du porteur (`"anonymous"`, `"user-42"`, …). - `roles: string[]` — Rôles **plats** (RBAC, sans hiérarchie résolue) — `["ROLE_ANONYMOUS"]` si anonyme. - `scopes: string[]` — Scopes accordés (clés API / OAuth) — `[]` en session BFF web. #### `SocketSnapshot` ```ts interface SocketSnapshot ``` Ce que le client sait de sa PROPRE socket, à un instant donné. - `url: string | null` — L'adresse du serveur temps réel — de QUELLE socket cet instantané parle. - `state: RealtimeState` — État de la connexion. - `channels: readonly string[]` — Canaux effectivement tenus par cette connexion. - `frames: number` — Trames reçues depuis l'ouverture. - `unsent: number` — Trames perdues faute de transport ouvert — un silence qui se compte. - `lastFrame: { method: string | null; at: number | null; }` — Méthode et horodatage de la dernière trame reçue (`null` si aucune). - `reconnectAttempts: number` — Tentatives de reconnexion depuis la dernière connexion réussie. - `nextRetryAt: number | null` — Échéance de la prochaine tentative (ms epoch), `null` hors reconnexion. - `identity: RealtimeIdentity | null` — Identité résolue par le serveur, `null` avant le premier welcome. - `serverChannels: readonly string[] | null` — Canaux que le serveur annonce à l'accueil, `null` avant le premier welcome. - `serverMethods: readonly string[] | null` — Actions que le serveur annonce à l'accueil, `null` avant le premier welcome. #### `SseSnapshot` ```ts interface SseSnapshot ``` L'état d'un flux observé — ce qu'une vue affiche. - `readonly readyState: number` — 0 `CONNECTING`, 1 `OPEN`, 2 `CLOSED` — les constantes de `NodefonySse`. - `readonly lastEvent: ISseEvent | null` — Le dernier événement reçu d'un des types écoutés, `null` tant qu'aucun. - `readonly error: boolean` — La dernière transition était-elle une coupure ? #### `UseNoticeLogOptions` ```ts interface UseNoticeLogOptions ``` - `max?: number` — Taille max du ring (anciennes notices évincées). - `sources?: NodefonyNotice["source"][]` — Ne garder que ces sources (ex `["realtime"]`). #### `UseSyslogOptions` ```ts interface UseSyslogOptions ``` - `max?: number` — Taille max du ring buffer (anciennes lignes évincées). - `severities?: string[]` — Ne garder que ces sévérités (ex `["ERROR","CRITIC"]`). - `channel?: string` — Canal source. ### Types (6) #### `AdaptiveChannelHookOptions` ```ts type AdaptiveChannelHookOptions = Omit ``` Réglages adaptatifs du hook (cadence désirée fixée à part par `intervalMs`). #### `ChannelStatsSnapshot` ```ts type ChannelStatsSnapshot = MessageStats ``` Stats observées d'un canal (telles que calculées par le client Core). #### `LoginErrorKind` ```ts type LoginErrorKind = "credentials" | "throttled" | "network" | "server" | "cancelled" | "unsupported" ``` Nature d'un échec, classée pour que l'écran sache QUOI dire. #### `LoginStep` ```ts type LoginStep = "identifier" | "password" | "mfa" | "authenticated" ``` Étape du déroulé de connexion. #### `NodefonyKernelState` ```ts type NodefonyKernelState = "created" | "booting" | "ready" | "terminated" ``` États du kernel client, ordonnés et non régressifs (symétrie nominale avec les lifecycle flags du Kernel serveur — `booted`/`ready`/… — sans en singer la sémantique process). #### `RealtimeState` ```ts type RealtimeState = "disconnected" | "connecting" | "connected" | "reconnecting" | "error" ``` --- [← Toutes les références d'API](../../)