Référence d'API — nodefony — types

stable

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#

interface DefaultOptionsService extends EventDefaultInterface

• events?: { nbListeners: number; }
• syslog?: SyslogDefaultSettings

IAdminApi#

interface IAdminApi

Contrat qu’un producteur (module ou kernel) implémente pour exposer sa donnée d’admin à Studio via le data plane /nodefony/<namespace>/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#

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#

interface IAdminEndpoint<T = unknown>

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<T> — Implémentation.

IAdminPageCapabilities#

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<Record<string, Readonly<Record<string, unknown>>>> — Table des facettes de cet endpoint — nom → jeu de filtres qui la sélectionne.

IAdminRegistry#

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#

interface IAdminRequest

Requête admin normalisée — projection minimale du Context HTTP/WS.

• params: Readonly<Record<string, string>> — Variables de route extraites du pattern, ex {id} → params.id.
• query: Readonly<Record<string, string | string[]>> — 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#

interface IAdminResponse<T = unknown>

Enveloppe de réponse d’un endpoint admin.

• status?: number — Code HTTP, défaut 200.
• headers?: Readonly<Record<string, string>> — En-têtes additionnels (le broker pose content-type: application/json).
• body: T — Charge utile sérialisable JSON.

IContainer#

interface IContainer

Contrat public du DI Container nodefony. Container et Scope l’implémentent.

• readonly id: string
• set(name: string, object: unknown): void
• get<T = unknown>(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<Syslog["log"]> | void
• clean(): void
• reset(): void

IErrorSample#

interface IErrorSample

Un exemple d’erreur, de quoi la retrouver dans le journal.

• route: string
• status: number | null
• error: string | null
• requestId: string

IIdempotencyKeyEntry#

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#

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#

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<IdempotencyOutcome> — Réserve atomiquement la clé et renvoie le verdict à suivre.
• complete(key: string, response: IdempotentResponse): void | Promise<void> — Mémorise la réponse d’une clé in-flight (TTL) → rejeux futurs = replayed.
• abort(key: string): void | Promise<void> — 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> | 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<IPage<IIdempotencyKeyEntry>> — 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#

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 (<path>/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<IStoreResolution, "provenance">): 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 (<cwd>/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<EventsType>
• readonly progress: number
• readonly trunk: TrunkType
• command: ICommand | null
• commandArgs: unknown[]
• domain: string
• cli: ICliKernel | null
• readonly modules: Record<string, IModule>
• start(): Promise<this>
• terminate(code?: number, quiet?: boolean): Promise<this> — quiet muselle l’affichage (log « terminate : N ») — jamais le drain.
• isTrunk(): Promise<TrunkType>
• isModule(subclass: unknown): boolean
• addModule(Mod: unknown, ...args: unknown[]): Promise<IModule>
• loadModule(nameOrPath: string): Promise<IModule>
• getModule(name: string): IModule
• getModules(): Record<string, IModule>
• replaceModuleOptions(mod: IModule, options: Record<string, unknown>): 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#

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#

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<Record<string, unknown>>) => 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<string, unknown>, caller: IMcpCaller, run?: IMcpToolRun) => IMcpToolResult | Promise<IMcpToolResult> — Implémentation.

IMcpToolAnnotations#

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#

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<string, unknown> — Schéma JSON des arguments attendus.
• annotations?: IMcpToolAnnotations — Ce que l’outil promet de son effet — à poser sur CHAQUE outil.

IMcpToolResult#

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#

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#

interface IModule extends IService

Contrat public d’un module nodefony. Module.ts implémente cette interface.

• path: string
• isApp: boolean
• package?: PackageJson
• onKernelRegister?(): Promise<this>
• onKernelBoot?(): Promise<this>
• onKernelReady?(): Promise<this>
• init?(kernel?: IKernel): Promise<this>
• addService(service: unknown, ...args: unknown[]): Promise<IService>
• loadService(service: string, ...args: unknown[]): Promise<IService>
• getDependencies(): string[]
• getController<T = unknown>(name: string): IControllerConstructor<T>
• getControllers<T = unknown>(): Record<string, IControllerConstructor<T>>
• getServiceNames(): string[]
• getMcpTools?(): IMcpTool[] — Outils que ce module ajoute à la porte MCP de l’application.
• configSchema(): unknown
• getPackageJson(cwd?: string): Promise<PackageJson>
• getModuleName(): string
• getModuleVersion(): string
• install(force?: boolean): Promise<number | Error>
• outdated(): Promise<number | Error>
• loadJson(url: string, cwd?: string): Promise<JSONObject>

IModuleManifestEntry#

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<string, unknown> — Config colocalisée du module (forme use(name, config)).

INPlusOne#

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#

interface IPage<T>

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#

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#

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#

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#

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#

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#

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#

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#

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#

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<string, IPhaseTotal> — Temps par phase des requêtes servies, action.self compris.

IScope#

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#

interface IServerKernel

• initServers(): Promise<IStartedServer[]> — Démarre les serveurs HTTP/HTTPS/WS/WSS activés par la configuration.

IService#

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<Syslog["init"]> | 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<T>(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<unknown>
• fireAsync(eventName: string | symbol, ...args: unknown[]): Promise<unknown>
• emitAsyncGuarded(eventName: string | symbol, options?: IGuardedEmitOptions, ...args: unknown[]): Promise<IGuardedEmitResult> — É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#

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#

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#

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#

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#

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#

interface ITransport

• readonly name: string
• send(pdu: Pdu): Promise<void>
• close?(): Promise<void> — Libère ce que le transport tient ouvert (fichier, socket).

IdempotentResponse#

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<Record<string, string>> — En-têtes additionnels éventuels.
• body: unknown — Charge utile sérialisable JSON.

Types (9)#

AdminHandler#

type AdminHandler<T = unknown> = (request: IAdminRequest) => T | IAdminResponse<T> | Promise<T | IAdminResponse<T>>

Handler d’un endpoint admin : fonction pure entrée → sortie.

AdminHttpMethod#

type AdminHttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE"

Méthodes HTTP supportées par le data plane admin.

DebugType#

type DebugType = boolean | string | string[]

EnvironmentType#

type EnvironmentType = keyof typeof environment

EventListener#

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#

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#

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#

type ModulePolicy = "mandatory" | "optional" | "dev"

Politique de chargement d’un module.

PartialInput#

type PartialInput<T> = { [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