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

stable

Documentation › Référence d’API › nodefony › client-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/client#

import { … } from "nodefony/client" — 14 symboles.

Interfaces (14)#

IErrorSample#

interface IErrorSample

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

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

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.

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

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.

← Toutes les références d’API