--- title: "Référence d'API — nodefony/angular" source: docs/api/core/angular.md url: https://nodefony.github.io/nodefony-core/docs/api/core/angular/ --- [Documentation](../../../) › [Référence d'API](../../) › [`nodefony`](../) › angular > 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/angular` `import { … } from "nodefony/angular"` — 50 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) #### `injectNodefony` ```ts function injectNodefony(): NodefonySocket ``` `injectNodefony()` — la socket brute (canaux, journal, statistiques…). Tête de gondole et échappatoire pour les cas avancés ; pour de l'état réactif, prendre les fonctions dédiées ci-dessous. #### `injectNodefonyAdaptiveChannel` ```ts function injectNodefonyAdaptiveChannel(base: Source, onMessage: (payload: unknown) => void, desiredMs: Source, options?: AdaptiveChannelOptions): Signal ``` `injectNodefonyAdaptiveChannel()` — comme `injectNodefonyChannel`, mais en **cadence adaptative** (AIMD piloté par le client) : la cadence recule sous famine puis remonte quand c'est sain, sans rien changer au serveur. Renvoie la cadence effective, à afficher. #### `injectNodefonyAdaptiveChannelData` ```ts function injectNodefonyAdaptiveChannelData(base: Source, desiredMs: Source, options?: AdaptiveChannelOptions): AdaptiveChannelData ``` `injectNodefonyAdaptiveChannelData()` — comme `injectNodefonyChannelData`, mais en cadence adaptative. Mince surcouche de `injectNodefonyAdaptiveChannel` : garde la dernière valeur et rend la cadence effective. Réservé aux canaux d'ÉTAT. #### `injectNodefonyChannel` ```ts function injectNodefonyChannel(channel: Source, onMessage: (payload: unknown) => void): void ``` `injectNodefonyChannel()` — s'abonne à un canal pub/sub : `onMessage` est appelé à chaque message. Le socle apparie `subscribe`/`unsubscribe` côté serveur (ref-comptés) et rejoue l'abonnement à chaque reconnexion. #### `injectNodefonyChannelData` ```ts function injectNodefonyChannelData(channel: Source, initial?: T | null): Signal ``` `injectNodefonyChannelData()` — la **dernière valeur** reçue sur un canal (le cas le plus courant : la dernière mesure d'un flux d'état). `null` tant que rien n'est arrivé. #### `injectNodefonyChannelStats` ```ts function injectNodefonyChannelStats(channel: Source): Signal ``` `injectNodefonyChannelStats()` — statistiques vivantes d'un canal (débit, série pour un VU-mètre, total). La source est l'échantillonneur du client (1×/s) : aucune horloge n'est posée ici, et aucune trame n'est émise pour mesurer. #### `injectNodefonyIdentity` ```ts function injectNodefonyIdentity(): Signal ``` `injectNodefonyIdentity()` — 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'est arrivé ; une fois reçu, un visiteur anonyme a `authenticated: false`. Brique du gating front : `authenticated: false` → écran de connexion, **sans** appeler `/auth/me`. #### `injectNodefonyKernel` ```ts function injectNodefonyKernel(): INodefonyKernel | null ``` `injectNodefonyKernel()` — le noyau client fourni à `provideNodefony` (`{ kernel }`), ou `null` quand l'application n'en compose pas. Référence brute ; pour l'état réactif, prendre `injectNodefonyKernelState` et `injectNodefonyKernelIdentity`. #### `injectNodefonyKernelIdentity` ```ts function injectNodefonyKernelIdentity(): Signal ``` `injectNodefonyKernelIdentity()` — l'identité DÉCLARÉE au noyau par l'application (`setIdentity`), ou `null` hors session ou sans noyau fourni. Suit les changements de COMPTE — un profil rafraîchi à clé inchangée ne réveille personne (règle d'identité du noyau). #### `injectNodefonyKernelState` ```ts function injectNodefonyKernelState(): Signal ``` `injectNodefonyKernelState()` — l'état du noyau (`created` → `booting` → `ready` → `terminated`), ou `null` sans noyau fourni. #### `injectNodefonyLogin` ```ts function injectNodefonyLogin(options?: NodefonyLoginOptions): NodefonyLoginBinding ``` `injectNodefonyLogin()` — le déroulé de connexion du framework, relayé en signal. Le balisage reste entièrement à l'application ; les règles vivent dans `NodefonyLogin` (`nodefony/client`), jamais ici. #### `injectNodefonyNoticeLog` ```ts function injectNodefonyNoticeLog(options?: Source): Signal ``` `injectNodefonyNoticeLog()` — l'anneau borné des dernières notices, filtrable par source : un historique léger des criticités, distinct des notifications éphémères. La taille de l'anneau et le filtrage viennent du socle (`observeNoticeLog`). #### `injectNodefonyNotifications` ```ts function injectNodefonyNotifications(onNotice: (notice: NodefonyNotice) => void): void ``` `injectNodefonyNotifications()` — le flux des **notices normalisées** du client : criticités qui cassent le temps réel (codes de fermeture RFC 6455 interprétés), erreurs poussées par le serveur, rétablissement de connexion. `onNotice` est appelé pour CHAQUE notice → brancher un centre de notifications. #### `injectNodefonySnapshot` ```ts function injectNodefonySnapshot(): Signal ``` `injectNodefonySnapshot()` — 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. #### `injectNodefonySse` ```ts function injectNodefonySse(url: Source, options?: ObserveSseOptions): Signal ``` `injectNodefonySse()` — ouvre un flux SSE, rend son état (`readyState`, dernier événement, erreur) en signal, et le FERME à la destruction du contexte d'injection (composant ou service). #### `injectNodefonyState` ```ts function injectNodefonyState(): Signal ``` `injectNodefonyState()` — l'état de la connexion (`"connected"`, `"reconnecting"`, …), tenu à jour. Branché sur la porte publique `onState`, jamais sur le nom de l'événement local, qui n'a pas à sortir du client. #### `injectNodefonySyslog` ```ts function injectNodefonySyslog(options?: Source): Signal ``` `injectNodefonySyslog()` — le flux du journal, prêt à afficher : anneau borné et filtre de sévérité. Le format **coalescé** du canal (`{ logs, dropped }`), l'entrée unique, la taille de l'anneau et le canal par défaut viennent du socle (`observeSyslog`) : cette fonction n'en connaît aucun. #### `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. #### `provideNodefony` ```ts function provideNodefony(options: NodefonyAngularOptions): EnvironmentProviders ``` Le fournisseur — à poser une fois, dans les `providers` de l'application. #### `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. ### Constantes (2) #### `NODEFONY_CLIENT` ```ts const NODEFONY_CLIENT: InjectionToken> ``` Le jeton sous lequel `provideNodefony` enregistre la socket. #### `NODEFONY_KERNEL` ```ts const NODEFONY_KERNEL: InjectionToken ``` Le jeton sous lequel `provideNodefony` enregistre le noyau client, quand l'application en compose un. Absent → `injectNodefonyKernel` rend `null`. ### Interfaces (19) #### `AdaptiveChannelData` ```ts interface AdaptiveChannelData ``` Résultat de `injectNodefonyAdaptiveChannelData` : valeur + cadence réelle. - `data: Signal` — Dernière valeur reçue, `null` tant que rien n'est arrivé. - `intervalMs: Signal` — Cadence effective (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. #### `InjectNoticeLogOptions` ```ts interface InjectNoticeLogOptions ``` Réglages de `injectNodefonyNoticeLog`. - `max?: number` — Taille max de l'anneau (les plus anciennes notices sont évincées). - `sources?: NodefonyNotice["source"][]` — Ne garder que ces sources (ex. #### `InjectSyslogOptions` ```ts interface InjectSyslogOptions ``` Réglages de `injectNodefonySyslog`. - `max?: number` — Taille max de l'anneau (les plus anciennes lignes sont évincées). - `severities?: string[]` — Ne garder que ces sévérités (ex. - `channel?: string` — Canal source. #### `NodefonyAngularOptions` ```ts interface NodefonyAngularOptions ``` Réglages de `provideNodefony` — l'un des trois au moins doit être donné. - `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. #### `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 `injectNodefonyLogin` : l'état en signal, et le déroulé qui porte les actions. - `readonly state: Signal` — 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. #### `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 ? ### Types (7) #### `AdaptiveChannelOptions` ```ts type AdaptiveChannelOptions = Omit ``` Réglages adaptatifs (la cadence désirée se passe à part, en argument). #### `ChannelStatsSnapshot` ```ts type ChannelStatsSnapshot = MessageStats ``` Statistiques observées d'un canal, telles que le client les calcule. #### `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" ``` #### `Source` ```ts type Source = T | () => T ``` Une source de valeur : constante, ou fonction qui la lit (un `Signal` en est un cas — un signal EST une fonction sans argument). --- [← Toutes les références d'API](../../)