Référence d'API — nodefony/react

stable

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#

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<NodefonyLoginState> — Envoie le mot de passe du compte saisi.
• login(identifier: string, password: string): Promise<NodefonyLoginState> — Raccourci des formulaires d’un seul écran : compte et mot de passe d’un coup.
• submitMfaCode(code: string): Promise<NodefonyLoginState> — Envoie le code du second facteur (TOTP ou code de récupération).
• loginWithPasskey(): Promise<NodefonyLoginState> — Connexion par passkey, sans identifiant ni mot de passe.
• loadProviders(): Promise<readonly NodefonyLoginProvider[]> — 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<NodefonyLoginUser | null> — Reprend une session existante ; null quand il n’y en a pas.
• logout(): Promise<string | null> — Ferme la session et revient à l’étape identifier.
• back(): void — Revient à l’étape identifier, en gardant le compte saisi.

Fonctions (21)#

NodefonyProvider#

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#

function isRateChannel(channel: string, base: string): boolean

Vrai si channel est le canal de base nu OU une de ses variantes cadencées base:<ms>.

parseRate#

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 :<ms>, borne dans bounds et retombe sur bounds.default pour le canal de base nu ou un suffixe invalide.

rateChannel#

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#

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#

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#

function useNodefonyAdaptiveChannelData<T = unknown>(base: string, desiredMs: number, opts?: AdaptiveChannelHookOptions, deps?: React.DependencyList): AdaptiveChannelData<T>

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#

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#

function useNodefonyChannelData<T = unknown>(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#

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#

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#

function useNodefonyKernel(): INodefonyKernel | null

useNodefonyKernel() — le noyau client fourni au <NodefonyProvider kernel>, ou null quand l’application n’en compose pas. Référence stable ; pour l’état réactif, prendre useNodefonyKernelState et useNodefonyKernelIdentity.

useNodefonyKernelIdentity#

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#

function useNodefonyKernelState(): NodefonyKernelState | null

useNodefonyKernelState() — l’état du noyau (created → booting → ready → terminated), ou null sans noyau fourni. Re-render uniquement aux transitions.

useNodefonyLogin#

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#

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#

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#

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#

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#

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#

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#

interface AdaptiveChannelData<T>

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#

interface INodefonyKernel

Contrat du kernel client isomorphe (ADR-0007 D2 — surface v1, volontairement minimale : chaque méthode publiée est une promesse SemVer).

• get<K extends keyof NodefonyKernelServices>(name: K): NodefonyKernelServices[K] — Récupère un service enregistré (ou undefined s’il n’est pas composé).
• set<K extends keyof NodefonyKernelServices>(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<void> — Compose et connecte les services (idempotent).
• terminate(): Promise<void> — 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#

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#

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#

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#

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#

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#

interface NodefonyLoginProvider

Fournisseur de connexion, tel que le SERVEUR le présente.

• readonly name: string
• readonly label: string

NodefonyLoginState#

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#

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#

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#

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#

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#

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#

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#

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#

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#

interface UseNoticeLogOptions

• max?: number — Taille max du ring (anciennes notices évincées).
• sources?: NodefonyNotice["source"][] — Ne garder que ces sources (ex ["realtime"]).

UseSyslogOptions#

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#

type AdaptiveChannelHookOptions = Omit<BindAdaptiveOptions, "intervalMs" | "onRate">

Réglages adaptatifs du hook (cadence désirée fixée à part par intervalMs).

ChannelStatsSnapshot#

type ChannelStatsSnapshot = MessageStats

Stats observées d’un canal (telles que calculées par le client Core).

LoginErrorKind#

type LoginErrorKind = "credentials" | "throttled" | "network" | "server" | "cancelled" | "unsupported"

Nature d’un échec, classée pour que l’écran sache QUOI dire.

LoginStep#

type LoginStep = "identifier" | "password" | "mfa" | "authenticated"

Étape du déroulé de connexion.

NodefonyKernelState#

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#

type RealtimeState = "disconnected" | "connecting" | "connected" | "reconnecting" | "error"

← Toutes les références d’API