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


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

```ts
interface IErrorSample
```

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

- `route: string`
- `status: number | null`
- `error: string | null`
- `requestId: string`

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

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

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

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

---

[← Toutes les références d'API](../../)