Référence d'API — nodefony — realtime-RealtimeEventMap

stable

Documentation › Référence d’API › nodefony › realtime-RealtimeEventMap

Générée depuis les déclarations de types publiées de nodefony 10.0.0-beta.6 : 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#

import { … } from "nodefony" — 40 symboles.

Fonctions (1)#

expectType#

function expectType<T>(_value: T): void

Assertion type compile-time : expectType<T>(value) échoue à la compilation si value n’est pas assignable à T. 0 coût runtime (fonction vide).

Interfaces (9)#

DefaultActionsMap#

interface DefaultActionsMap

Défaut permissif pour ActionsMap (rétro-compat).

• [method: string]: { in?: unknown; out: unknown; }

DefaultEventsMap#

interface DefaultEventsMap

Défaut permissif pour EventsMap — toute clé string, payload unknown. Code instancié sans paramétrage (new JsonRpcPeer(opts)) → comportement pré-types-partagés inchangé. Sécurité rétro-compat 100%.

• [event: string]: unknown

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.

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 (cf RealtimeClosedReason) — 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 pont api.request : "<VERBE> <chemin>" → schéma du corps et de la query (typeof du 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 (cf RealtimeDeniedReason) — 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 avec reason: "unavailable", quand le serveur sait combien de temps il restera indisponible (coupe-circuit ouvert).

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 — true quand c’est le SERVEUR qui a abonné la connexion (abonnement imposé, ADR-0022 §6 décision 2) — absent pour la réponse à un subscribe du 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 (cf RealtimeIdentity).
• env?: string — Mode d’exécution du serveur — posé UNIQUEMENT hors production.
• subscriptionAcks?: boolean — Le serveur ACQUITTE chaque abonnement accepté (realtime:subscribed, cf IRealtimeSubscribed).
• 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, cf IFrameCodec).
• 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 — false pour un visiteur anonyme (Zero Trust : toujours présent, jamais null).
• id: string | null — Identifiant STABLE et OPAQUE du compte — la clé des canaux personnels (user:${id}) ; null pour 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 (30)#

ActionNames#

type ActionNames<M extends ActionsMap> = [ LiteralKeys<M> ] extends [ never ] ? string : LiteralKeys<M>

Nom valide dans une ActionsMap — même règle que EventNames.

ActionParams#

type ActionParams<M extends ActionsMap, K extends keyof M> = "in" extends keyof M[K] ? M[K] extends { in?: infer I; } ? I : undefined : undefined

Paramètres entrants d’une RPC, lus sur le in de la déclaration.

ActionResult#

type ActionResult<M extends ActionsMap, K extends keyof M> = M[K]["out"]

Résultat attendu d’une RPC (out).

ActionsMap#

type ActionsMap = Record<string, { in?: unknown; out: unknown; }>

Map des RPC — nom de méthode → { in: paramètres, out: résultat }.

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.

ContractActionNames#

type ContractActionNames<M extends ActionsMap> = LiteralKeys<M>

Noms d’actions RÉELLEMENT déclarés par le contrat — never quand la map n’en déclare aucune (DefaultActionsMap).

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.

ContractParams#

type ContractParams<M extends ActionsMap, K> = K extends ContractActionNames<M> ? ActionParams<M, K & keyof M> : unknown

params d’une RPC : dictés par le contrat quand K lui appartient, libres sinon. Règle UNIQUE — IRealtimeSocket, NodefonySocket et ServerRealtimeSocket la partagent au lieu de la recopier.

ContractResult#

type ContractResult<M extends ActionsMap, K, T> = K extends ContractActionNames<M> ? ActionResult<M, K & keyof M> : T

Résultat d’une RPC : dicté par le contrat quand K lui appartient, sinon le T que l’appelant demande. Pendant de ContractParams.

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.

ContractRouteSchemas#

type ContractRouteSchemas<C extends IRealtimeContract> = { [K in LiteralKeys<ContractClientRoutes<C>>]: { [P in keyof ContractClientRoutes<C>[K] & ("body" | "query" | "params")]: ContractClientRoutes<C>[K][P]; }; }

Table de VALEURS qu’un contrôleur de contrat déclare pour que le démarrage vérifie ses serverRoutes : une entrée par route du contrat, portant le schéma même que la route valide (body, query, params). Écrite côté serveur seulement — le navigateur ne la voit jamais, donc n’embarque aucun schéma.

ContractServerActions#

type ContractServerActions<C extends IRealtimeContract> = MethodsSeenBy<ContractSide<C, "clientMethods", ActionsMap>, "out">

Les méthodes que le serveur APPELLE (requestClient) : clientMethods, le résultat lu par Jsonify.

ContractServerEmit#

type ContractServerEmit<C extends IRealtimeContract> = ContractSide<C, "serverToClient", EventsMap>

Ce que le serveur ÉMET : serverToClient, tel que déclaré.

ContractServerListen#

type ContractServerListen<C extends IRealtimeContract> = ReceivedEvents<ContractSide<C, "clientToServer", EventsMap>>

Ce que le serveur REÇOIT : clientToServer, lu par Jsonify.

ContractServerMethods#

type ContractServerMethods<C extends IRealtimeContract> = MethodsSeenBy<ContractSide<C, "serverMethods", ActionsMap>, "in">

Les méthodes que le serveur IMPLÉMENTE : serverMethods, les paramètres lus par Jsonify, le résultat tel que déclaré.

EventNames#

type EventNames<M extends EventsMap> = [ LiteralKeys<M> ] extends [ never ] ? string : LiteralKeys<M>

Nom valide dans une EventsMap.

EventPayload#

type EventPayload<M extends EventsMap, K extends keyof M> = M[K]

Payload typé d’un canal.

EventsMap#

type EventsMap = Record<string, unknown>

Map des canaux pub/sub — nom de canal → forme du payload.

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.

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.

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.

TypedRpcActionHandler#

type TypedRpcActionHandler<M extends ActionsMap, K extends keyof M & string> = (params: ActionParams<M, K>) => ActionResult<M, K> | Promise<ActionResult<M, K>>

Handler typé pour une RPC entrante (côté qui expose via register). Sync ou async — JSON-RPC 2.0 §5.1 : throw → réponse -32603 internal_error.

← Toutes les références d’API