--- title: "Référence d'API — nodefony — types" source: docs/api/core/types.md url: https://nodefony.github.io/nodefony-core/docs/api/core/types/ --- [Documentation](../../../) › [Référence d'API](../../) › [`nodefony`](../) › types > 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"` — 52 symboles. ### Interfaces (43) #### `DefaultOptionsService` ```ts interface DefaultOptionsService extends EventDefaultInterface ``` - `events?: { nbListeners: number; }` - `syslog?: SyslogDefaultSettings` #### `IAdminApi` ```ts interface IAdminApi ``` Contrat qu'un producteur (module ou kernel) implémente pour exposer sa donnée d'admin à Studio via le data plane `/nodefony//api/*`. - `readonly adminNamespace: string` — Segment de route ET clé d'identification unique. - `adminDescriptor(): IAdminDescriptor` — Métadonnées d'affichage (sidebar Studio). - `adminEndpoints(): IAdminEndpoint[]` — Endpoints exposés par ce producteur. #### `IAdminDescriptor` ```ts interface IAdminDescriptor ``` Métadonnées d'affichage du module dans la sidebar Studio. - `label: string` — Libellé humain, ex `"HTTP"`, `"Sécurité"`, `"Kernel"`. - `icon?: string` — Nom d'icône (jeu Tabler, cohérent avec le frontend Studio). - `order?: number` — Ordre d'affichage croissant dans la sidebar. - `role?: string` — Rôle requis pour voir l'entrée de menu (peut différer par endpoint). #### `IAdminEndpoint` ```ts interface IAdminEndpoint ``` Définition déclarative d'un endpoint, relative au namespace du module. - `path: string` — Chemin RELATIF au namespace, sans `/` initial. - `method?: AdminHttpMethod` — Méthode HTTP, défaut `"GET"`. - `role?: string` — Rôle minimum requis pour appeler l'endpoint (RBAC appliqué par le broker). - `public?: boolean` — Endpoint PUBLIC : le broker n'impose AUCUN rôle (pas de défaut `ROLE_NODEFONY_ADMIN`), la route est atteignable sans authentification. - `summary?: string` — Résumé court pour l'auto-doc Studio et l'introspection. - `page?: IAdminPageCapabilities` — Capacités de pagination publiées dans le catalogue admin — tri possible et vocabulaire de filtre. - `credentials?: boolean` — Le corps porte un SECRET de connexion (mot de passe, code) : en production, la porte qui transporte la requête la refuse en 403 si elle est arrivée en clair (HTTP), AVANT le contrôle de rôle et le han … - `handler: AdminHandler` — Implémentation. #### `IAdminPageCapabilities` ```ts interface IAdminPageCapabilities ``` Ce qu'un endpoint paginé sait faire — **publié**, pour que son client cesse de le deviner. - `sortable?: () => readonly string[]` — Champs triables — **une fonction**, parce que la réponse dépend du store effectivement branché au démarrage, pas d'une constante de compilation. - `filters?: IFilterSpec` — Vocabulaire de filtre de l'endpoint (`IFilterSpec`), sérialisable tel quel : un nom → une nature (`"boolean"`, `"int"`, `"string"`) ou la liste fermée de ses valeurs, qui vaut allowlist. - `search?: () => boolean` — L'endpoint sait-il **chercher** (`?q=`) — même raison d'être que `IAdminPageCapabilities.sortable`, et même piège s'il manque : une console qui affiche une barre de recherche que le serveur ignore pré … - `facets?: Readonly>>>` — Table des **facettes** de cet endpoint — nom → jeu de filtres qui la sélectionne. #### `IAdminRegistry` ```ts interface IAdminRegistry ``` Façade d'enregistrement du data plane admin — vue **minimale** du broker que voit un producteur. - `register(api: IAdminApi): this` — Enregistre un producteur. - `unregister(namespace: string): boolean` — Retire un producteur (et ses routes si déjà montées). - `has(namespace: string): boolean` — `true` si un producteur est enregistré sous ce namespace. - `getApi(namespace: string): IAdminApi` — Producteur enregistré sous ce namespace, ou `undefined`. - `list(): readonly IAdminApi[]` — Liste immuable des producteurs enregistrés. #### `IAdminRequest` ```ts interface IAdminRequest ``` Requête admin normalisée — projection minimale du Context HTTP/WS. - `params: Readonly>` — Variables de route extraites du pattern, ex `{id}` → `params.id`. - `query: Readonly>` — Query string parsée (`?a=1&b=2` → `{ a: "1", b: "2" }`). - `body: unknown` — Corps de requête déjà parsé (JSON), `null` si absent. - `user: unknown` — Utilisateur authentifié injecté par le firewall (P6), `null` tant que l'auth est mock ou la route anonyme. - `roles: readonly string[]` — Rôles résolus de l'utilisateur courant — base du contrôle d'accès. - `requestId?: string` — Corrélation de logs (ALS `RequestContext.getRequestId()`). - `idempotencyKey?: string` — Clé d'idempotence d'une **mutation** (modèle Stripe), si fournie par le client (en-tête HTTP `Idempotency-Key` ou `params.idempotencyKey` du pont WS). #### `IAdminResponse` ```ts interface IAdminResponse ``` Enveloppe de réponse d'un endpoint admin. - `status?: number` — Code HTTP, défaut `200`. - `headers?: Readonly>` — En-têtes additionnels (le broker pose `content-type: application/json`). - `body: T` — Charge utile sérialisable JSON. #### `IContainer` ```ts interface IContainer ``` Contrat public du DI Container nodefony. Container et Scope l'implémentent. - `readonly id: string` - `set(name: string, object: unknown): void` - `get(name: string): T | null` - `remove(name: string): boolean` - `has(name: string): boolean` - `keys(): string[]` - `entries(): [ string, unknown ][]` - `addScope(name: string): object` - `enterScope(name: string): IScope` - `leaveScope(scope: IScope): void` - `removeScope(name: string): void` - `scopeCount(name: string): number` — Nombre d'instances vivantes du scope nommé (introspection/sondes). - `log(pci: Pci, severity?: Severity, msgid?: Msgid, msg?: Message): ReturnType | void` - `clean(): void` - `reset(): void` #### `IErrorSample` ```ts interface IErrorSample ``` Un exemple d'erreur, de quoi la retrouver dans le journal. - `route: string` - `status: number | null` - `error: string | null` - `requestId: string` #### `IIdempotencyKeyEntry` ```ts interface IIdempotencyKeyEntry ``` Une clé d'idempotence telle qu'exposée à l'INTROSPECTION admin. - `readonly key: string` — La clé d'idempotence (telle que composée par l'appelant). - `readonly state: "in-flight" | "done"` — `in-flight` = mutation en cours ; `done` = réponse mémorisée (rejouable). - `readonly expiresAtMs: number` — Échéance de l'entrée (epoch ms) — au-delà, la clé redevient `fresh`. - `readonly hasResponse: boolean` — `true` si une réponse est mémorisée (jamais son contenu). #### `IIdempotencyListQuery` ```ts interface IIdempotencyListQuery extends IPageQuery ``` Requête de listing des clés d'idempotence — `IPageQuery` + le filtre d'exploitation. `q` (hérité) = **préfixe** de clé : les clés sont composées (identité + méthode + chemin), donc le préfixe isole un scope entier. - `state?: "in-flight" | "done"` — Restreint à un état. #### `IIdempotencyStore` ```ts interface IIdempotencyStore ``` Cache d'idempotence borné (modèle Stripe `Idempotency-Key`) — dédoublonne les **mutations** rejouées (reconnexion socket, double-clic) du data plane admin comme des controllers userland décorés `@Idempotent`. - `begin(key: string, fingerprint: string): IdempotencyOutcome | Promise` — Réserve **atomiquement** la clé et renvoie le verdict à suivre. - `complete(key: string, response: IdempotentResponse): void | Promise` — Mémorise la réponse d'une clé *in-flight* (TTL) → rejeux futurs = `replayed`. - `abort(key: string): void | Promise` — Libère une clé *in-flight* dont l'exécution a échoué : rien n'est mémorisé (un échec doit pouvoir être réessayé). - `gc?(now?: number): Promise | number` — Purge les entrées expirées — présente UNIQUEMENT sur les impls SANS expiration native (`drizzle` → `DELETE WHERE expiresAt <= now`). - `listPage(query: IIdempotencyListQuery): Promise>` — Page de clés vivantes — introspection admin (repérer une clé figée *in-flight* qui bloque les rejeux d'un client). - `readonly size: number` — Nombre d'entrées vivantes (observabilité / tests). #### `IKernel` ```ts interface IKernel extends IService ``` Contrat public du Kernel nodefony. Utilisé comme type de IService.kernel pour éviter l'import circulaire Kernel.ts → Service.ts → IService.ts → IKernel.ts → Kernel.ts. - `runProfile: IRunProfile` - `readonly version: string` - `readonly environment: EnvironmentType` - `readonly debug: DebugType` - `readonly projectName: string` - `readonly path: string` - `readonly varDir?: FileClass` — Répertoire des données runtime PERSISTÉES (`/var`) — base commune des stores fichier (passkeys, TOTP, sessions) et bases SQLite. - `readonly isDev: boolean` - `readonly isProd: boolean` - `readonly infra: IInfra` — Infra déclarée (`database`/`cache`/`logs`) résolue depuis l'environnement (URLs `NF_DATABASE_URL`/`NF_REDIS_URL`/…). - `readonly storeResolutions: IStoreResolution[]` — Résolutions EFFECTIVES des stores de persistance, capturées au boot par chaque brique (`registerStoreResolution`) — la vérité vécue (replis inclus), alimente l'écran Studio « Stores ». - `registerStoreResolution(resolution: Omit): void` — Enregistre la résolution effective d'une brique de persistance (idempotent par `brick` — la dernière résolution gagne). - `readonly isTTY: boolean` — L'environnement FOURNIT-il un vrai terminal ? - `readonly pid: number` - `readonly platform: NodeJS.Platform` - `tmpDir?: FileClass` — Répertoire temporaire du projet (`/tmp`), initialisé au boot. - `readonly started: boolean` - `readonly booted: boolean` - `readonly ready: boolean` - `readonly postReady: boolean` - `readonly suppressBootBanners: boolean` — Supprime les bannières serveurs sous l'écran de boot animé (dev). - `readonly Events: Readonly` - `readonly progress: number` - `readonly trunk: TrunkType` - `command: ICommand | null` - `commandArgs: unknown[]` - `domain: string` - `cli: ICliKernel | null` - `readonly modules: Record` - `start(): Promise` - `terminate(code?: number, quiet?: boolean): Promise` — `quiet` muselle l'affichage (log « terminate : N ») — jamais le drain. - `isTrunk(): Promise` - `isModule(subclass: unknown): boolean` - `addModule(Mod: unknown, ...args: unknown[]): Promise` - `loadModule(nameOrPath: string): Promise` - `getModule(name: string): IModule` - `getModules(): Record` - `replaceModuleOptions(mod: IModule, options: Record): void` — Remplace la configuration FIGÉE d'un module (édition à chaud en développement) : `mod.options` et le registre lu par `useConfig`. - `getNetwork(): KernelNetworkResult` - `checkPath(myPath: string): string | null` - `isCommandComplete(progress: number): boolean` - `getBootReport(): IBootReport` — Verdict agrégé du dernier boot (modules, serveurs, santé) — vérité unique. - `reportBootLine(phase: string, line: string): void` — AJOUTE une ligne de détail à afficher sous une phase de boot (canal neutre). - `setBootLines(phase: string, lines: string[]): void` — REMPLACE les lignes de détail d'une phase (producteur idempotent). - `getBootLines(phase: string): string[]` — Lignes de détail déclarées pour une phase de boot. - `reportBootNotice(notice: IBootNotice): void` — Déclare un point d'attention du démarrage (constat + geste), rendu au bilan. - `reportBootLink(link: IBootLinkDeclaration): void` — Déclare une adresse à ouvrir, par son chemin sur l'application. - `readonly readinessBlocked: number` — Nombre de composants qui retiennent la mise en service — `0` = disponible. - `readonly servable: boolean` — Ce processus a-t-il le droit de recevoir du trafic ? - `setReadiness(name: string, ready: boolean, reason?: string, blocking?: boolean, action?: string): void` — Pose le verdict de disponibilité d'un composant nommé (schéma en retard, cache froid…). - `clearReadiness(name: string): void` — Retire un contributeur : sa voix ne retient plus rien. - `readinessReport(): IReadinessContributor[]` — État de chaque contributeur — pour un diagnostic, jamais pour la sonde. #### `IMcpCaller` ```ts interface IMcpCaller ``` Ce que le transport a pu ÉTABLIR de l'appelant — jamais ce qu'il prétend. - `authenticated: boolean` — Une identité a-t-elle été PROUVÉE (jeton validé) ? - `scopes: readonly string[]` — Scopes réellement accordés par le serveur d'autorisation. - `roles: readonly string[]` — Rôles Nodefony de cet appelant — ce sur quoi le plan d'administration tranche. - `subject?: string` — Sujet du jeton (`sub`), pour l'audit et pour filtrer les données rendues. #### `IMcpTool` ```ts interface IMcpTool extends IMcpToolDefinition ``` Un outil exécutable : ce que `tools/list` publie, plus ce qui répond. - `scopes?: readonly string[]` — Scopes OAuth exigés — **tous**, pas au moins un. - `scopesFor?: (args: Readonly>) => readonly string[]` — Scopes que CES arguments exigent, en plus de `IMcpTool.scopes` — un paramètre qui élargit ce que l'outil fait (agir au nom d'un autre compte, écrire) sans conditionner sa visibilité. - `requiresAuth?: boolean` — Exige une identité prouvée, sans scope particulier. - `actsForUser?: boolean` — L'outil agit AU NOM du propriétaire du jeton : son handler s'exécute dans une bulle de requête où `RequestContext.getAuthenticatedUser()`, les services qu'il appelle et l'autorisation (`authorization. … - `handler: (args: Record, caller: IMcpCaller, run?: IMcpToolRun) => IMcpToolResult | Promise` — Implémentation. #### `IMcpToolAnnotations` ```ts interface IMcpToolAnnotations ``` Ce qu'un outil promet de son effet — les indices `ToolAnnotations` de la spec MCP (révision 2026-07-28, `schema.ts`), publiés dans `tools/list`. - `title?: string` — Titre lisible, préféré au nom par les interfaces. - `readOnlyHint?: boolean` — L'outil ne modifie RIEN de son environnement (défaut de la spec : `false`). - `destructiveHint?: boolean` — Une écriture peut détruire (défaut : `true`) — `false` : n'ajoute que. - `idempotentHint?: boolean` — Rappeler l'outil avec les mêmes arguments n'a pas d'effet de plus (défaut : `false`) — vrai d'un remplacement ou d'une suppression, faux d'une création ou d'un envoi. - `openWorldHint?: boolean` — L'outil touche un monde extérieur ouvert — web, API tierce, courriel (défaut : `true`). #### `IMcpToolDefinition` ```ts interface IMcpToolDefinition ``` Un outil tel que `tools/list` le publie — sans son implémentation. - `name: string` — Identifiant d'appel. - `description: string` — ⭐ **Le premier critère de déclenchement de l'outil**, avant toute considération technique. - `inputSchema: Record` — Schéma JSON des arguments attendus. - `annotations?: IMcpToolAnnotations` — Ce que l'outil promet de son effet — à poser sur CHAQUE outil. #### `IMcpToolResult` ```ts interface IMcpToolResult ``` Ce que rend un outil — du contenu, et l'aveu d'un échec métier. - `content: { type: "text"; text: string; }[]` - `isError?: boolean` #### `IMcpToolRun` ```ts interface IMcpToolRun ``` Ce que la porte prête à un outil pendant SON exécution : de quoi savoir que l'agent est parti, et de quoi lui donner signe de vie. - `readonly signal: AbortSignal` — Abattu quand l'agent abandonne l'appel. - `progress(progress: number, total?: number, message?: string): void` — Signale l'avancement (`notifications/progress`). #### `IModule` ```ts interface IModule extends IService ``` Contrat public d'un module nodefony. Module.ts implémente cette interface. - `path: string` - `isApp: boolean` - `package?: PackageJson` - `onKernelRegister?(): Promise` - `onKernelBoot?(): Promise` - `onKernelReady?(): Promise` - `init?(kernel?: IKernel): Promise` - `addService(service: unknown, ...args: unknown[]): Promise` - `loadService(service: string, ...args: unknown[]): Promise` - `getDependencies(): string[]` - `getController(name: string): IControllerConstructor` - `getControllers(): Record>` - `getServiceNames(): string[]` - `getMcpTools?(): IMcpTool[]` — Outils que ce module ajoute à la porte MCP de l'application. - `configSchema(): unknown` - `getPackageJson(cwd?: string): Promise` - `getModuleName(): string` - `getModuleVersion(): string` - `install(force?: boolean): Promise` - `outdated(): Promise` - `loadJson(url: string, cwd?: string): Promise` #### `IModuleManifestEntry` ```ts interface IModuleManifestEntry ``` Entrée détaillée d'un manifeste de modules. - `name: string` — Nom du package/module à charger (résolu par `import()` dynamique). - `policy?: ModulePolicy` — Politique de chargement. - `when?: (config: TypeKernelOptions) => boolean` — Garde de chargement évaluée sur la config fusionnée du kernel. - `config?: Record` — Config colocalisée du module (forme `use(name, config)`). #### `INPlusOne` ```ts interface INPlusOne ``` Un N+1 : la même forme SQL répétée dans une requête. - `route: string` - `controller: string | null` - `action: string | null` - `shape: string` - `maxRepeats: number` — Plus grand nombre de répétitions vu dans une requête. - `requests: number` — Requêtes touchées. - `totalMs: number` — Temps cumulé de ces répétitions. - `sampleRequestId: string` — Une requête touchée, pour aller voir son profil complet. #### `IPage` ```ts interface IPage ``` Une **page** de résultats — la sortie unique de toute pagination Nodefony. - `items: T[]` — Les éléments de la page (au plus `limit`). - `total?: number` — Total exact de la collection filtrée — présent si `IPageQuery.withTotal` n'est pas `false` **et** que le backend sait compter à coût raisonnable. - `limit: number` — Taille de page demandée (écho de `IPageQuery.limit`). - `offset?: number` — Décalage de cette page (mode offset ; absent en mode curseur). - `hasNext: boolean` — `true` s'il existe au moins un élément au-delà de cette page. - `nextCursor?: string | null` — Jeton de la page suivante (mode **curseur**) — à repasser en `IPageQuery.cursor`. #### `IPageQuery` ```ts interface IPageQuery ``` **LE contrat de pagination unique de Nodefony.** Tous les stores, toutes les API (présents et futurs) paginent avec ce type — c'est un standard de développement, jamais une pagination maison au cas par cas. - `limit: number` — Taille de page — obligatoire (jamais « tout »). - `offset?: number` — Décalage depuis le début de la collection filtrée (mode **offset**). - `cursor?: string` — Jeton de page (mode **curseur**) : ne renvoyer que les éléments situés « après » lui dans l'ordre du store. - `order?: Array<[ string, "ASC" | "DESC" ]>` — Tri : couples `[champ, sens]`. - `withTotal?: boolean` — Renvoyer le total exact (`IPage.total`) ou non. - `q?: string` — Recherche plein-texte best-effort — le **champ** ciblé et la sémantique (préfixe / sous-chaîne / casse) sont définis par chaque store et documentés côté store. - `tenantId?: string | null` — **RÉSERVÉ multi-tenant** — slot du contrat pour le scoping par tenant, appliqué **au niveau du store** le jour du chantier tenant. #### `IPhaseTotal` ```ts interface IPhaseTotal ``` Temps cumulé d'une phase sur les requêtes d'une route. - `totalMs: number` - `count: number` — Requêtes où la phase est apparue et s'est terminée. #### `IProfileEntry` ```ts interface IProfileEntry ``` Profil complet d'une requête (HTTP ou frame WS), servi par `/{requestId}`. - `requestId: string` - `seq: number` — Numéro d'ordre de collecte, croissant sur la vie du profileur. - `ts: number` — Horodatage de la collecte (`Date.now()`), pour le tri client. - `kind: "http" | "ws"` - `method: string | null` - `url: string` - `scheme: string` - `status: number | null` - `durationMs: number | null` — Durée de la requête (ms), de son arrivée au dernier octet de la réponse — la même que la ligne d'accès ; `null` si le chronométrage est coupé. - `route: string | null` - `controller: string | null` - `action: string | null` - `remoteAddress: string | null` - `user: string | null` — Identité (username) si le firewall l'a injectée, sinon `null`. - `traceparent: string | null` — `traceparent` W3C Trace Context — corrélation distribuée. - `error: string | null` - `phases: IProfilePhase[]` - `queries?: IProfileQuery[]` — Requêtes ORM mesurées — `undefined` quand aucun adaptateur n'a poussé. - `security?: IProfileSecurity` — Traversée du firewall — `undefined` si la requête n'a croisé aucune zone. #### `IProfilePhase` ```ts interface IProfilePhase ``` Une phase du pipeline, projetée pour le transport (durée résolue). - `name: string` - `startMs: number` — Début relatif `performance.now()` (ms) — sert au calcul du waterfall. - `durationMs: number | null` — Durée en ms, `null` si la phase ne s'est pas terminée (erreur). #### `IProfileQuery` ```ts interface IProfileQuery ``` Une requête SQL/NoSQL exécutée pendant la requête : les adaptateurs ORM la poussent dans le tampon de la requête (`RequestContext.pushQuery`), que le profileur relit au teardown. Absent hors développement, et quand aucun adaptateur n'a rien poussé. - `sql: string` — Requête (SQL ou commande NoSQL), tronquée si volumineuse. - `startMs?: number` — Début relatif (`performance.now()`) — même horloge que les phases. - `durationMs: number` — Durée d'exécution en ms. - `rows?: number` — Lignes affectées/retournées, si connu. - `connector?: string` — Connecteur émetteur (`drizzle`, `mongoose`…). #### `IProfileReport` ```ts interface IProfileReport ``` Le rapport agrégé. - `requests: number` — Requêtes agrégées (hors outillage filtré). - `http: number` - `ws: number` - `filteredTooling: number` — Requêtes de l'outillage écartées (`/nodefony/…`, `/_vite/…`). - `untimed: number` — Requêtes sans durée mesurée. - `routes: IRouteStats[]` — Triées par p95 décroissant. - `nPlusOne: INPlusOne[]` — Triés par temps cumulé décroissant. - `slowQueries: ISqlShapeStats[]` — Les dix formes SQL les plus coûteuses (temps cumulé décroissant). - `sqlShapesDropped: number` — Formes SQL distinctes vues au-delà de la capacité, comptées sans détail. - `errors: IErrorSample[]` #### `IProfileSecurity` ```ts interface IProfileSecurity ``` Traversée du firewall par cette requête — **ce qui était possible** (la zone : son nom, si elle est protégée, quels authenticators elle accepte) croisé avec **ce qui s'est passé** (quel maillon a résolu l'identité, l'issue, le motif d'un refus). Une requête qui PASSE n'émet aucun événement d'audit : sans ce relevé, elle serait invisible côté sécurité. - `zone: string | null` — Nom de la zone traversée. - `protected: boolean` — La zone exige-t-elle une identité (`security: true`) ? - `mode: string | null` — Chaîne d'authenticators : `first` = le premier qui supporte, `all` = MFA. - `candidates: string[]` — Authenticators que la zone accepte (ce qui était POSSIBLE). - `authenticator: string | null` — Authenticator qui a RÉELLEMENT résolu l'identité. - `outcome: string | null` — `granted` · `anonymous` · `denied` · `failure` · `throttled` · `bypass` · `public`. - `reason: string | null` — Motif du refus (`no_credentials`, `invalid_credentials`…). - `roles: string[] | null` — Rôles du token résolu (l'axe autorisation). #### `IProfileSummary` ```ts interface IProfileSummary ``` Résumé léger d'un profil pour la liste `recent` (sans les phases). - `requestId: string` - `ts: number` - `kind: "http" | "ws"` - `method: string | null` - `url: string` - `status: number | null` - `durationMs: number | null` - `route: string | null` - `error: string | null` #### `IRouteStats` ```ts interface IRouteStats ``` Statistiques d'une route sur la fenêtre agrégée. - `route: string` - `kind: "http" | "ws"` - `controller: string | null` - `action: string | null` - `count: number` - `untimed: number` — Requêtes sans durée mesurée (chronométrage coupé : `timing.enabled: false`). - `served: number` — Requêtes SERVIES et chronométrées (statut < 400, sans exception) : la population de tout ce qui se dit « par requête » ci-dessous. - `p50Ms: number | null` — Percentiles et maximum, sur les requêtes servies. - `p95Ms: number | null` - `maxMs: number | null` - `status: IStatusBreakdown` - `errors: number` — Requêtes en erreur : statut ≥ 500 ou exception levée. - `queries: { total: number; perRequestMax: number; totalMs: number; }` — Requêtes SQL/NoSQL des requêtes servies : total, maximum dans une requête, temps CUMULÉ (des requêtes parallèles s'y additionnent). - `phases: Record` — Temps par phase des requêtes servies, `action.self` compris. #### `IScope` ```ts interface IScope extends IContainer ``` Contrat public d'un scope (Container enfant lié à un parent). Étend IContainer et ajoute name, l'état de fermeture et le rattachement d'objets. - `readonly name: string` - `readonly closed: boolean` — `true` une fois le scope refermé par `leaveScope()` : ses services sont libérés, un `get()` y rend `null` et un `set()` lève. - `hasOwn(name: string): boolean` — `true` si `name` est posé SUR ce scope — jamais un service hérité du conteneur parent. - `own(instance: object): void` — Lie la durée de vie d'un objet à celle du scope : son `clean()`, s'il en a un, est appelé à la fermeture du scope, dans l'ordre INVERSE des rattachements (le dernier créé est nettoyé le premier). #### `IServerKernel` ```ts interface IServerKernel ``` - `initServers(): Promise` — Démarre les serveurs HTTP/HTTPS/WS/WSS activés par la configuration. #### `IService` ```ts interface IService ``` Contrat public de tout service nodefony. Kernel, Module, Controller, adapters ORM — tous implémentent IService. - `readonly name: string` - `readonly options: DefaultOptionsService` - `readonly container: IContainer | null` - `readonly kernel: IKernel | null` - `readonly syslog: Syslog | null` - `readonly notificationsCenter: Event` — undefined si notificationsCenter=false passé au constructeur, ou après clean() - `getName(): string` - `initSyslog(environment?: EnvironmentType, debug?: DebugType, options?: conditionsInterface): ReturnType | null` - `clean(syslog?: boolean): void` - `log(pci: Pci, severity?: Severity, msgid?: Msgid, msg?: Message, moduleName?: string): Pdu` - `logger(pci: Pci, ...args: unknown[]): void` - `trace(pci: Pci, ...args: unknown[]): void` - `get(name: string): T | null` - `set(name: string, obj: unknown): void` - `remove(name: string): boolean` - `has(name: string): boolean` - `on(eventName: string | symbol, listener: EventListener): this` - `once(eventName: string | symbol, listener: EventListener): this` - `off(eventName: string | symbol, listener: EventListener): this` - `emit(eventName: string | symbol, ...args: unknown[]): boolean` - `fire(eventName: string | symbol, ...args: unknown[]): boolean` - `emitAsync(eventName: string | symbol, ...args: unknown[]): Promise` - `fireAsync(eventName: string | symbol, ...args: unknown[]): Promise` - `emitAsyncGuarded(eventName: string | symbol, options?: IGuardedEmitOptions, ...args: unknown[]): Promise` — Émet en série en ISOLANT chaque listener (try/catch, timeout optionnel) : un rejet n'empêche pas les suivants. - `addListener(eventName: string | symbol, listener: EventListener): this` - `removeListener(eventName: string | symbol, listener: EventListener): this` - `removeAllListeners(eventName?: string | symbol): this` - `prependListener(eventName: string | symbol, listener: EventListener): this` - `prependOnceListener(eventName: string | symbol, listener: EventListener): this` - `listen(eventName: string | symbol, listener: EventListener): (...args: unknown[]) => boolean` - `settingsToListen(localSettings: EventDefaultInterface, context: object): void` - `eventNames(): (string | symbol)[]` - `listenerCount(eventName: string | symbol, listener?: EventListener): number` - `listeners(eventName: string | symbol): EventListener[]` - `rawListeners(eventName: string | symbol): EventListener[]` - `getMaxListeners(): number` - `setMaxListeners(n: number): this` #### `ISortableSource` ```ts interface ISortableSource ``` **Une capacité de tri se DÉCLARE** — le socle commun à tout ce qui rend des pages triables (stores de sessions, de jetons, d'endpoints, dépôts d'utilisateurs…). - `readonly sortableFields?: readonly string[]` — Champs triables, en **noms publics** (ceux de l'URL), ou absent si ce backend ne sait pas trier. #### `ISqlShapeStats` ```ts interface ISqlShapeStats ``` Une forme SQL et son coût sur la fenêtre. - `shape: string` - `connector: string | null` - `count: number` - `totalMs: number` - `maxMs: number` - `routes: string[]` — Routes qui l'ont émise (au plus cinq). #### `IStartedServer` ```ts interface IStartedServer ``` Ce que le Kernel utilise d'un serveur démarré : afficher son adresse d'écoute. - `showBanner(): void` — Affiche la bannière « Server Listen on… » du serveur. #### `IStatusBreakdown` ```ts interface IStatusBreakdown ``` Répartition des statuts HTTP d'une route. - `s2xx: number` - `s3xx: number` - `s4xx: number` - `s5xx: number` - `unauthorized: number` — Dont 401 : la route exige une authentification que la requête n'avait pas. - `forbidden: number` — Dont 403 : authentifiée, mais refusée. #### `ISyslog` ```ts interface ISyslog ``` - `settings: SyslogDefaultSettings` - `readonly ringStack: Pdu[]` - `readonly bufferCapacity: number` — Capacité MAX du ring buffer (plafond `maxStack`). - `readonly ringEnabled: boolean` — `true` si les Pdu sont stockés dans le ring (relecture mémoire active). - `setRingEnabled(enabled: boolean): boolean` — Active/désactive le stockage mémoire (ring) à chaud — outil avancé. - `readonly streamEnabled: boolean` — `true` si la diffusion temps réel (`nodefony:syslog`) est active. - `setStreamEnabled(enabled: boolean): boolean` — Active/désactive la diffusion temps réel à chaud (onglet Live). - `burstPrinted: number` - `missed: number` - `invalid: number` - `valid: number` - `errorTotal: number` — Cumul monotone des logs de sévérité 0–3 (ERROR/CRITIC/ALERT/EMERGENCY). - `criticTotal: number` — Sous-ensemble CRITIQUE (sévérité 0–2 : CRITIC/ALERT/EMERGENCY). - `start: number` - `async: boolean` - `init(environment: EnvironmentType, debug?: DebugType, options?: conditionsInterface): void` - `clean(): this` - `reset(): this` - `clearLogStack(): void` - `log(payload: Pci, severity?: Severity, msgid?: Msgid, msg?: Message): Pdu` - `error(data: Pci): Pdu` - `warn(data: Pci): Pdu` - `info(data: Pci): Pdu` - `debug(data: Pci): Pdu` - `trace(data: Pci, msgid?: Msgid, msg?: Message): Pdu` - `print(...args: Pci[]): Pdu` - `logMultiple(severity: Severity, ...args: Pci[]): Pdu` - `pushStack(pdu: Pdu): number` - `getLogStack(start?: number, end?: number, condition?: conditionsInterface): Pdu[] | Pdu` - `getLogs(conditions: conditionsInterface, stack?: Pdu[] | null): Pdu[]` - `logToJson(conditions: conditionsInterface, stack?: Pdu[] | null): string` - `loadStack(stack: Pdu[] | string, doEvent?: boolean, beforeConditions?: (pdu: Pdu, stackItem: Pdu) => void | null): Pdu[]` - `filter(conditions: conditionsInterface, callback: CallbackFunction): void` - `listenWithConditions(conditions: conditionsInterface, callback: CallbackFunction): void` - `addTransport(transport: ITransport): this` - `removeTransport(transport: ITransport): this` - `listTransports(): { name: string; enabled: boolean; }[]` — Liste polymorphe des transports d'écriture (axe WRITE) + état `enabled`. - `setTransportEnabled(name: string, enabled: boolean): boolean` — Active/désactive un transport d'écriture à chaud, par nom (dev/diagnostic). #### `ITransport` ```ts interface ITransport ``` - `readonly name: string` - `send(pdu: Pdu): Promise` - `close?(): Promise` — Libère ce que le transport tient ouvert (fichier, socket). #### `IdempotentResponse` ```ts interface IdempotentResponse ``` Réponse mémorisée d'une mutation idempotente — la forme `{status, headers?, body}` produite par un endpoint (data plane admin `AdminApiController.runAdmin`, ou action userland `@Idempotent`), pour la rejouer telle quelle à un rejeu (même statut, même corps, même en-têtes). - `status: number` — Code HTTP de la réponse mémorisée. - `headers?: Readonly>` — En-têtes additionnels éventuels. - `body: unknown` — Charge utile sérialisable JSON. ### Types (9) #### `AdminHandler` ```ts type AdminHandler = (request: IAdminRequest) => T | IAdminResponse | Promise> ``` Handler d'un endpoint admin : fonction pure entrée → sortie. #### `AdminHttpMethod` ```ts type AdminHttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" ``` Méthodes HTTP supportées par le data plane admin. #### `DebugType` ```ts type DebugType = boolean | string | string[] ``` #### `EnvironmentType` ```ts type EnvironmentType = keyof typeof environment ``` #### `EventListener` ```ts type EventListener = (...args: any[]) => unknown ``` Listener d'événement Nodefony : arguments libres, retour libre — une valeur ou une PROMESSE, que `emitAsync`/`fireAsync` attendent et collectent. Un retour `void` ferait passer chaque listener `async` pour une promesse perdue. #### `IModuleManifest` ```ts type IModuleManifest = (string | IModuleManifestEntry)[] ``` Manifeste déclaratif des modules d'une application Nodefony, exposé via `config.modules`. Le Kernel en est le **seul orchestrateur** : il lit cette liste, la filtre (policy + `when` + environnement) et charge les modules en série à `onPreRegister`. #### `IdempotencyOutcome` ```ts type IdempotencyOutcome = { state: "fresh"; } | { state: "in-flight"; } | { state: "replayed"; response: IdempotentResponse; } | { state: "mismatch"; } ``` Verdict de `IIdempotencyStore.begin` pour une clé d'idempotence donnée. Aligné sur `draft-ietf-httpapi-idempotency-key-header-08` §2.6/§2.7. #### `ModulePolicy` ```ts type ModulePolicy = "mandatory" | "optional" | "dev" ``` Politique de chargement d'un module. #### `PartialInput` ```ts type PartialInput = { [K in keyof T]?: T[K]; } ``` Données d'écriture partielles telles qu'elles arrivent d'un schéma de validation : une clé peut manquer OU valoir `undefined`, et les deux disent la même chose — « ne pas toucher à ce champ ». --- [← Toutes les références d'API](../../)