Référence d'API — nodefony/client — realtime-RealtimeEventMap
stable
Documentation › Référence d’API › nodefony › client-realtime-RealtimeEventMap
Générée depuis les déclarations de types publiées de
nodefony10.0.0-beta.7 : 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/client#
import { … } from "nodefony/client" — 31 symboles.
Constantes (1)#
REALTIME_PRESENCE_METHOD#
const REALTIME_PRESENCE_METHOD = "realtime:presence"
Nom de la notification du protocole qui porte la présence d’un canal (ADR-0025 P2 bis) — une source pour le serveur qui l’émet et le navigateur qui la lit.
Interfaces (13)#
IContractRoute#
interface IContractRoute
Une route servie par le pont, vue par le contrat : le schéma de son corps et de sa query — la VALEUR que la route valide, référencée par typeof, jamais recopiée —, et ce qu’elle rend.
body?: IStandardSchemaV1— Schéma du corps (schema: { body }de la route).query?: IStandardSchemaV1— Schéma de la query (schema: { query }de la route).params?: IStandardSchemaV1— Schéma des paramètres de chemin (schema: { params }de la route) ; absent, leurs noms sont lus dans le gabarit de la clé ({id}).result: unknown— Ce que l’action rend.
IPresenceEntry#
interface IPresenceEntry<TState = unknown>
Ce que porte une identité présente sur un canal (ADR-0025 P4) — l’entrée de la VUE (ReadonlyMap du hook, hub.presence()). Sur le fil, entre pods comme vers le navigateur, elle voyage à plat (PresencePairs, PresenceStates).
tabs: number— Connexions (onglets) de cette identité sur le canal, tous pods confondus — entier ≥ 1.states?: Readonly<Record<string, TState>>— États par onglet ; clé = référence d’onglet OPAQUE (elle ne dit rien de la topologie des pods), présente seulement avec un état (RFC 3863 §4.1.2,idde chaque tuple).
IRealtimeClosed#
interface IRealtimeClosed
Payload de la notification système realtime:closed — poussée par le serveur quand il met fin, de lui-même, à un abonnement en cours (ADR-0021 S4, ADR-0022 §6 décision 3).
channel: string— Canal dont l’abonnement vient de prendre fin.reason: RealtimeClosedReason— Pourquoi (cfRealtimeClosedReason) — jamais le détail de la décision.
IRealtimeContract#
interface IRealtimeContract
Le moule du contrat temps réel d’une application — déclaré UNE fois, dans un fichier partagé par ses deux côtés, et lu par chacun dans SA direction.
serverToClient?: EventsMap— Événements poussés par le serveur (socket, flux SSE, webhook).clientToServer?: EventsMap— Événements envoyés par le client.serverMethods?: ActionsMap— Méthodes du serveur : le client appelle, le serveur répond.clientMethods?: ActionsMap— Méthodes du client : le serveur appelle, le client répond.serverRoutes?: RoutesMap— Routes servies par le pontapi.request:"<VERBE> <chemin>"→ schéma du corps et de la query (typeofdu schéma que la route VALIDE — une seule source) et résultat.
IRealtimeDenied#
interface IRealtimeDenied
Payload de la notification système realtime:denied — poussée par le serveur quand une frame subscribe/inbound est REFUSÉE par le verrou d’autorisation (P6). Rend le refus OBSERVABLE côté client (une notification, contrairement à une requête, serait sinon droppée en silence → le client resterait aveugle).
channel: string— Canal (ou méthode inbound) refusé(e).reason: RealtimeDeniedReason— Motif générique (cfRealtimeDeniedReason) — jamais le détail de la policy.detail?: string— Ce qui s’est passé, en clair — hors production UNIQUEMENT.retryAfterMs?: number— Délai minimal, en millisecondes, avant de réessayer — posé seulement avecreason: "unavailable", quand le serveur sait combien de temps il restera indisponible (coupe-circuit ouvert).
IRealtimePresenceChanges#
interface IRealtimePresenceChanges<TState = unknown>
Changements appliqués à la vue (trame IRealtimePresenceDelta).
set?: PresencePairs— Identités arrivées ou modifiées, avec leur nombre d’onglets (remplace l’ancien).states?: PresenceStates<TState>— États des identités desetqui en portent un.gone?: readonly string[]— Identités parties.
IRealtimePresenceCount#
interface IRealtimePresenceCount extends IRealtimePresenceHead
Nombres seuls : au-delà du seuil de membres nommés (défaut 1 000 ; seuil 0 = jamais nommés), aucune identité ne voyage. Complète comme une liste — elle porte la version courante, remplace la vue (vide d’identités) et réinitialise la référence.
members?: neverchanges?: neverstates?: never
IRealtimePresenceDelta#
interface IRealtimePresenceDelta<TState = unknown> extends IRealtimePresenceHead
Changements numérotés : s’appliquent à la vue seulement si la règle classifyNumberedChange(référence, version) rend applied ; gap → le client réémet subscribe, stale → jetée.
changes: IRealtimePresenceChanges<TState>members?: neverstates?: never
IRealtimePresenceHead#
interface IRealtimePresenceHead
En-tête commun des trames realtime:presence (ADR-0025 P2 bis) — champs figés.
channel: string— Nom EXACT du canal décrit (un canal cadencébase:<ms>en est un autre).version: number— Version de la vue, entière, propre au canal SUR le pod qui sert la connexion.count: number— Identités NOMMÉES distinctes présentes (comptes seulement).unnamed: number— Connexions comptées sans être nommées (anonymes, appelants machine sans compte).partial?: true— Présent seulement àtrue: la vue est connue incomplète ou figée (liste locale avant la réponse des pairs, bus perdu, trou en cours sur un pod).
IRealtimePresenceList#
interface IRealtimePresenceList<TState = unknown> extends IRealtimePresenceHead
Liste complète : REMPLACE la vue et RÉINITIALISE sa référence de version. Servie à chaque (re-)subscribe, et à tout moment quand elle pèse moins que les changements (RFC 5262 §4) — le client l’accepte sans l’avoir demandée.
members: PresencePairs— Tous les présents NOMMÉS, à plat (cfPresencePairs).states?: PresenceStates<TState>— États des présents qui en portent un.changes?: never
IRealtimeSubscribed#
interface IRealtimeSubscribed
Payload de la notification système realtime:subscribed — poussée par le serveur quand un subscribe est ACCEPTÉ, y compris pour un canal que la connexion suivait déjà (sans quoi un subscribe réémis attendrait un acquittement qui ne vient jamais).
channel: string— Canal dont l’abonnement est désormais effectif sur cette connexion.imposed?: true—truequand c’est le SERVEUR qui a abonné la connexion (abonnement imposé, ADR-0022 §6 décision 2) — absent pour la réponse à unsubscribedu client.
IRealtimeWelcome#
interface IRealtimeWelcome
Payload de la notification système realtime:welcome — 1ʳᵉ frame poussée par le serveur juste après le handshake. Annonce le protocole, les canaux/actions découvrables de l’endpoint et l’RealtimeIdentity résolue de la connexion. Cold path (1×/connexion).
ts: number— Timestamp serveur (ms epoch).protocol: string— Étiquette de protocole ("jsonrpc-2.0").channels: string[]— Canaux pub/sub annoncés par l’endpoint (découverte).methods: string[]— Actions RPC exposées par l’endpoint (découverte).identity: RealtimeIdentity— Identité résolue de CETTE connexion (cfRealtimeIdentity).env?: string— Mode d’exécution du serveur — posé UNIQUEMENT hors production.subscriptionAcks?: boolean— Le serveur ACQUITTE chaque abonnement accepté (realtime:subscribed, cfIRealtimeSubscribed).codec?: string— Sous-protocole du codec retenu pour les frames qui SUIVENT cet accueil — l’un de ceux que le client a offerts au handshake (ADR-0022 §2, cfIFrameCodec).bytes?: string— Marqueur de la convention d’octets ($bytes) que le serveur émet sur cette connexion TEXTE — posé quand il a activé un codec binaire que le client n’a pas pris (ADR-0022 §2).
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—falsepour un visiteur anonyme (Zero Trust : toujours présent, jamaisnull).id: string | null— Identifiant STABLE et OPAQUE du compte — la clé des canaux personnels (user:${id}) ;nullpour l’anonyme, et pour un authentificateur qui ne produit pas d’identité d’admission (`IRealtimeToken.get …userIdentifier: string— Identifiant logique du porteur ("anonymous","user-42", …) — affichage et audit, jamais une clé de canal.roles: readonly string[]— Rôles plats (RBAC, sans hiérarchie résolue) —["ROLE_ANONYMOUS"]si anonyme.scopes: readonly string[]— Scopes accordés (clés API / OAuth) —[]en session BFF web.
Types (17)#
BridgeVerb#
type BridgeVerb = "GET" | "POST" | "PUT" | "PATCH" | "DELETE"
Verbe HTTP d’une action servie par le pont api.request — le pont n’en sert pas d’autre.
ContractClientActions#
type ContractClientActions<C extends IRealtimeContract> = MethodsSeenBy<ContractSide<C, "serverMethods", ActionsMap>, "out"> & MethodsSeenBy<ContractSide<C, "clientMethods", ActionsMap>, "in">
Les méthodes du client vues par NodefonySocket : serverMethods qu’il appelle (request, résultat lu par Jsonify) et clientMethods qu’il implémente (register, paramètres lus par Jsonify). La socket range les deux sous un seul générique Actions : une méthode déclarée des deux côtés sous le même nom n’a pas de sens, le contrat ne la sépare pas.
ContractClientEmit#
type ContractClientEmit<C extends IRealtimeContract> = ContractSide<C, "clientToServer", EventsMap>
Ce que le client ÉMET : clientToServer, tel que déclaré.
ContractClientListen#
type ContractClientListen<C extends IRealtimeContract> = ReceivedEvents<ContractSide<C, "serverToClient", EventsMap>>
Ce que le client REÇOIT : serverToClient, lu par Jsonify.
ContractClientRoutes#
type ContractClientRoutes<C extends IRealtimeContract> = ContractSide<C, "serverRoutes", RoutesMap>
Les routes du pont qu’un client appelle — serverRoutes du contrat, ou la carte permissive si le contrat n’en déclare pas.
ContractRouteBody#
type ContractRouteBody<R extends RoutesMap, K extends string> = K extends DeclaredRouteKeys<R> ? RoutePart<R, K, "body"> : unknown
Le corps qu’accepte une route du pont : l’entrée de son schéma quand la clé K ("<VERBE> <chemin>") appartient au contrat, undefined si la route déclarée n’a pas de corps, libre (unknown) hors contrat.
ContractRouteParams#
type ContractRouteParams<R extends RoutesMap, K extends string, P extends string> = K extends DeclaredRouteKeys<R> ? "params" extends keyof R[K & keyof R] ? RoutePart<R, K & keyof R, "params"> : TemplateParams<P> : TemplateParams<P>
Les paramètres de chemin qu’accepte une route du pont : l’entrée de son schéma params quand la route déclarée en a un, sinon une valeur par {nom} du gabarit P — sous contrat comme hors contrat.
ContractRouteQuery#
type ContractRouteQuery<R extends RoutesMap, K extends string> = K extends DeclaredRouteKeys<R> ? RoutePart<R, K, "query"> : unknown
La query qu’accepte une route du pont — pendant de ContractRouteBody.
ContractRouteResult#
type ContractRouteResult<R extends RoutesMap, K extends string, T> = K extends DeclaredRouteKeys<R> ? R[K & keyof R] extends { result: infer X; } ? Jsonify<X> : unknown : T
Ce que rend une route du pont, lu par Jsonify (il a traversé le fil) quand K appartient au contrat ; sinon le T que l’appelant demande.
Jsonify#
type Jsonify<T, D extends number = 10> = unknown extends T ? T : [ D ] extends [ never ] ? unknown : T extends Uint8Array ? T : T extends { toJSON(...args: never[]): infer R; } ? Jsonify<R, JsonifyDepth[D]> : T extends JsonPrimitive | void ? T : T extends bigint | symbol | (...args: never[]) => unknown ? never : T extends readonly unknown[] ? { [I in keyof T]: JsonifyItem<T[I], JsonifyDepth[D]>; } …
Le type qu’un pair REÇOIT quand l’autre a envoyé un T : ce que JSON en fait.
PresencePairs#
type PresencePairs = readonly (string | number)[]
Identités et nombre d’onglets À PLAT : [identité, onglets, identité, onglets, …] — la forme sur le fil de IPresenceEntry (sans ses états).
PresenceStates#
type PresenceStates<TState = unknown> = Readonly<Record<string, Readonly<Record<string, TState>>>>
États par identité puis par onglet (référence opaque → état) — champ FACULTATIF voisin des paires, présent seulement pour les identités qui ont un état. Un lecteur qui ne le connaît pas l’ignore ; jamais posé en 10.0 (ADR-0025 P4).
RealtimeClosedReason#
type RealtimeClosedReason = "ended" | "evicted"
Motif d’un realtime:closed. Fermé exprès, comme RealtimeDeniedReason : le client doit pouvoir traiter tous les cas.
RealtimeDeniedReason#
type RealtimeDeniedReason = "forbidden" | "limit" | "unknown" | "unavailable"
Motif d’un realtime:denied. Fermé exprès : le client doit pouvoir traiter TOUS les cas (le compilateur le lui rappelle), et un motif inventé côté serveur ne doit pas atteindre un écran qui ne sait pas le dire.
RealtimePresenceFrame#
type RealtimePresenceFrame<TState = unknown> = IRealtimePresenceList<TState> | IRealtimePresenceDelta<TState> | IRealtimePresenceCount
Payload de la notification du protocole realtime:presence (ADR-0025 P2 bis) : qui est présent sur un canal à présence. Exactement une des trois formes — la discriminer par changes !== undefined, puis members !== undefined, sinon nombres seuls.
RoutePathParamNames#
type RoutePathParamNames<P extends string> = P extends `${string}{${infer Name}}${infer Rest}` ? Name | RoutePathParamNames<Rest> : never
Noms des variables d’un gabarit de chemin — "/a/{id}/b/{slug}" → "id" | "slug" ; never sans variable. Même lecture que routePathParams (runtime/routePath.ts).
RoutesMap#
type RoutesMap = Record<`${BridgeVerb} /${string}`, IContractRoute>
Carte des routes du pont : "<VERBE> <chemin>" → IContractRoute. Le chemin est celui de la route montée, préfixe du contrôleur compris.