---
title: "Référence d'API — nodefony — realtime-RealtimeEventMap"
source: docs/api/core/realtime-RealtimeEventMap.md
url: https://nodefony.github.io/nodefony-core/docs/api/core/realtime-RealtimeEventMap/
---


[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`

```ts
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`

```ts
interface DefaultActionsMap
```

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

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

#### `DefaultEventsMap`

```ts
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`

```ts
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`

```ts
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`

```ts
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`

```ts
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`

```ts
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`

```ts
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`

```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`).
- `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`

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

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

#### `ActionParams`

```ts
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`

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

Résultat attendu d'une RPC (`out`).

#### `ActionsMap`

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

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

#### `BridgeVerb`

```ts
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`

```ts
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`

```ts
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`

```ts
type ContractClientEmit<C extends IRealtimeContract> = ContractSide<C, "clientToServer", EventsMap>
```

Ce que le client ÉMET : `clientToServer`, tel que déclaré.

#### `ContractClientListen`

```ts
type ContractClientListen<C extends IRealtimeContract> = ReceivedEvents<ContractSide<C, "serverToClient", EventsMap>>
```

Ce que le client REÇOIT : `serverToClient`, lu par `Jsonify`.

#### `ContractClientRoutes`

```ts
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`

```ts
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`

```ts
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`

```ts
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`

```ts
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`

```ts
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`

```ts
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`

```ts
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`

```ts
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`

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

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

#### `ContractServerListen`

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

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

#### `ContractServerMethods`

```ts
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`

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

Nom valide dans une `EventsMap`.

#### `EventPayload`

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

Payload typé d'un canal.

#### `EventsMap`

```ts
type EventsMap = Record<string, unknown>
```

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

#### `Jsonify`

```ts
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`

```ts
type RealtimeClosedReason = "ended" | "evicted"
```

Motif d'un `realtime:closed`. Fermé exprès, comme `RealtimeDeniedReason` : le client doit pouvoir traiter tous les cas.

#### `RealtimeDeniedReason`

```ts
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`

```ts
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`

```ts
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`

```ts
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](../../)