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

stable

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#

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)#

injectNodefony#

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#

function injectNodefonyAdaptiveChannel(base: Source<string>, onMessage: (payload: unknown) => void, desiredMs: Source<number>, options?: AdaptiveChannelOptions): Signal<number>

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#

function injectNodefonyAdaptiveChannelData<T = unknown>(base: Source<string>, desiredMs: Source<number>, options?: AdaptiveChannelOptions): AdaptiveChannelData<T>

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#

function injectNodefonyChannel(channel: Source<string>, 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#

function injectNodefonyChannelData<T = unknown>(channel: Source<string>, initial?: T | null): Signal<T | null>

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#

function injectNodefonyChannelStats(channel: Source<string>): Signal<ChannelStatsSnapshot | null>

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#

function injectNodefonyIdentity(): Signal<RealtimeIdentity | null>

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#

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#

function injectNodefonyKernelIdentity(): Signal<NodefonyKernelIdentity | null>

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#

function injectNodefonyKernelState(): Signal<NodefonyKernelState | null>

injectNodefonyKernelState() — l’état du noyau (created → booting → ready → terminated), ou null sans noyau fourni.

injectNodefonyLogin#

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#

function injectNodefonyNoticeLog(options?: Source<InjectNoticeLogOptions>): Signal<NodefonyNotice[]>

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#

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#

function injectNodefonySnapshot(): Signal<SocketSnapshot | null>

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#

function injectNodefonySse(url: Source<string | null>, options?: ObserveSseOptions): Signal<SseSnapshot>

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#

function injectNodefonyState(): Signal<RealtimeState>

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#

function injectNodefonySyslog(options?: Source<InjectSyslogOptions>): Signal<unknown[]>

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#

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.

provideNodefony#

function provideNodefony(options: NodefonyAngularOptions): EnvironmentProviders

Le fournisseur — à poser une fois, dans les providers de l’application.

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.

Constantes (2)#

NODEFONY_CLIENT#

const NODEFONY_CLIENT: InjectionToken<NodefonySocket<import("../../realtime/RealtimeEventMap").DefaultEventsMap, import("../../realtime/RealtimeEventMap").DefaultEventsMap, import("../../realtime/RealtimeEventMap").DefaultActionsMap>>

Le jeton sous lequel provideNodefony enregistre la socket.

NODEFONY_KERNEL#

const NODEFONY_KERNEL: InjectionToken<INodefonyKernel>

Le jeton sous lequel provideNodefony enregistre le noyau client, quand l’application en compose un. Absent → injectNodefonyKernel rend null.

Interfaces (19)#

AdaptiveChannelData#

interface AdaptiveChannelData<T>

Résultat de injectNodefonyAdaptiveChannelData : valeur + cadence réelle.

• data: Signal<T | null> — Dernière valeur reçue, null tant que rien n’est arrivé.
• intervalMs: Signal<number> — Cadence effective (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.

InjectNoticeLogOptions#

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#

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#

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#

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 injectNodefonyLogin : l’état en signal, et le déroulé qui porte les actions.

• readonly state: Signal<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.

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 ?

Types (7)#

AdaptiveChannelOptions#

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

Réglages adaptatifs (la cadence désirée se passe à part, en argument).

ChannelStatsSnapshot#

type ChannelStatsSnapshot = MessageStats

Statistiques observées d’un canal, telles que le client les calcule.

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"

Source#

type Source<T> = 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