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

stable

Documentation › Référence d’API › nodefony › runtime

Générée depuis les déclarations de types publiées de nodefony 10.0.0-beta.5 : 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" — 112 symboles.

Classes (8)#

CursorOrderError#

class CursorOrderError extends nodefonyError

Erreur levée quand un store paginant par curseur reçoit un IPageQuery.order : il ne peut pas l’honorer, et l’avaler mentirait.

• constructor(fields: readonly string[])

GcScheduler#

class GcScheduler

Timer de maintenance déterministe, jittéré et désarmable. Voir la doc du module pour le rationnel complet.

• constructor(opts: IGcSchedulerOptions)
• get armed(): boolean — true si l’ordonnanceur est armé (délai initial en cours OU timer récurrent).
• start(): boolean — Arme l’ordonnanceur.
• runNow(): Promise<void> — Exécute une passe immédiatement — point d’entrée public (le timer l’appelle ; un worker cron / une commande batch peut l’appeler à sa place).
• stop(): void — Désarme les timers (idempotent) — à appeler au shutdown.

PageQueryError#

class PageQueryError extends nodefonyError

Erreur d’une requête de page mal formée ou non honorable par le point d’entrée : order sur un endpoint qui ne trie pas, champ hors allowlist, sens de tri inconnu.

• constructor(message: string)

PaginationModeError#

class PaginationModeError extends nodefonyError

Erreur levée quand un listPage reçoit le champ de pagination du mode que son store ne sait pas honorer — un cursor pour un store offset, ou un offset de navigation pour un store curseur.

• constructor(received: PaginationMode, supported: PaginationMode)

RequestContext#

class RequestContext

AsyncLocalStorage facade — single shared instance per process. Lazily constructed so importing this module has zero cost if run() is never called (the ALS allocation is the only cost).

• static run<T>(payload: RequestContextPayload, fn: () => T): T — Enter a new request scope.
• static get(): RequestContextPayload — Returns the current payload, or undefined outside any request scope.
• static getRequestId(): string — Shortcut — returns the current requestId or undefined.
• static getUser(): unknown — Rend l’utilisateur posé par le pare-feu, BRUT — y compris l’utilisateur anonyme d’une zone qui accepte l’anonymat.
• static getAuthenticatedUser(): IRequestUser | null — Rend l’utilisateur AUTHENTIFIÉ de la requête, ou null : hors zone du pare-feu, ou anonyme (jeton non authentifié).
• static isAnonymous(): boolean — Dit si la requête est servie à un ANONYME par le pare-feu : jeton non authentifié d’une zone qui accepte l’anonymat.
• static getContext<T = unknown>(): T — Shortcut — returns the current transport context (V4.1) or undefined.
• static getUserId(): string | null — Rend l’id de l’utilisateur AUTHENTIFIÉ de l’unité de travail, ou null.
• static getScope(): IScope — Rend le scope DI de la requête en cours : le conteneur propre à CETTE requête, ou undefined s’il n’y en a pas d’ouvert.
• static requireScope(): IScope — Comme getScope, mais lève quand aucun scope ouvert n’est disponible — pour le code qui n’a pas de sens hors d’une requête.
• static release(store: RequestContextPayload): void — Vide un magasin dont l’unité de travail est finie : requête HTTP, connexion WebSocket, appel api.request, action temps réel décorée.
• static set<K extends keyof RequestContextPayload>(key: K, value: RequestContextPayload[K]): void — Mutate the current payload in place.
• static isProfiling(): boolean — true si un buffer de profiling de requêtes ORM est actif sur le scope courant (dev + HttpKernel profiler activé).
• static pushQuery(query: IProfilerQuery): void — Pousse une requête ORM dans le buffer de profiling du scope courant.

RevocationWatch#

class RevocationWatch<T>

Registre des connexions longues à identité révocable, re-validées périodiquement — la SEULE implémentation, partagée par le hub WebSocket et les flux SSE : une garde que l’un des transports n’aurait pas serait le chemin qu’un attaquant prendrait.

• constructor(policy: IRevocationPolicy<T>)
• get size(): number — Nombre d’entrées inscrites.
• register(entry: T): void — Inscrit une entrée ; démarre le tick à la première.
• unregister(entry: T): void — Retire une entrée (idempotent) ; arrête le tick quand le registre se vide.
• revalidate(): Promise<void> — Re-valide toutes les entrées et ferme celles dont l’identité est morte.
• refreshIdentity(identifier: string): number — Ferme, tout de suite, les entrées qui ont figé cette identité — ses droits ont changé (IDENTITY_CHANGED_EVENT).

SchemaValidationError#

class SchemaValidationError extends Error

Erreur levée quand une entrée ne satisfait pas son schéma — l’unique erreur de validation des routes à schéma.

• readonly code = 422 — Statut HTTP équivalent.
• readonly issues: readonly ISchemaValidationIssue[] — Les anomalies, toutes parties confondues.
• constructor(issues: readonly ISchemaValidationIssue[])

TimeoutError#

class TimeoutError extends Error

Erreur levée par withTimeout quand le délai est dépassé — distincte d’un rejet métier pour que l’appelant puisse différencier « lent/figé » de « a échoué » (ex. politique de boot : timeout d’un module critique en prod).

• readonly timeoutMs: number — Délai (ms) qui a été dépassé.
• constructor(timeoutMs: number, label?: string)

Fonctions (31)#

assertPageQuery#

function assertPageQuery(query: IPageQuery, mode: PaginationMode): void

Fait respecter le contrat « un store expose UN seul mode » au point d’entrée d’un listPage, sur la requête brute reçue de l’appelant (avant qu’elle ne soit normalisée) : rejette explicitement le champ du mode non supporté plutôt que de l’ignorer sans un mot.

bearerToken#

function bearerToken(header: unknown): string | null

Rend le jeton porté par un en-tête Authorization, ou null.

compareByOrder#

function compareByOrder<T>(order: NonNullable<IPageQuery["order"]>, read: FieldReader<T>): (a: T, b: T) => number

Fabrique le comparateur d’un order du contrat de page — le tri en mémoire de Nodefony, partagé par tous les stores qui n’ont pas de moteur pour le faire à leur place.

countFacets#

function countFacets<S extends Readonly<Record<string, object>>>(facets: S, count: (query: S[keyof S]) => number | Promise<number>): Promise<FacetCounts<S>>

Compte plusieurs facettes d’une même collection en un seul geste.

facetDimensions#

function facetDimensions(facets: Readonly<Record<string, object>>): string[]

Les champs qu’une table de facettes décompose — donc ceux qu’un client ne peut pas filtrer sur l’endpoint qui les rend.

findLegacyEnvFiles#

function findLegacyEnvFiles(opts?: ILoadEnvOptions): string[]

Les fichiers de l’ANCIENNE convention (Vite / Next.js) présents dans une application : .env.local, .env.<mode>, .env.<mode>.local.

frameIndexOf#

function frameIndexOf(id: string, connection: string): number | null

Le rang de la frame si id en est une de connection, sinon null — un identifiant qui ne fait que COMMENCER comme la connexion n’en est pas une.

frameRequestId#

function frameRequestId(connection: string, n: number): string

L’identifiant de la n-ième frame d’une connexion.

identityHint#

function identityHint(kernel: IKernel | null): string | null

Le geste qui donne une IDENTITÉ dans cette application — ou null.

isDocVisible#

function isDocVisible(scope: DocScope | null, frameworkRepository: boolean): boolean

Une page de cette portée se montre-t-elle dans ce décor ?

isFrameworkRepository#

function isFrameworkRepository(projectRoot: string): boolean

Cette racine est-elle le dépôt du framework lui-même ?

isLoginPageSkin#

function isLoginPageSkin(value: unknown): value is LoginPageSkin

Dit si une valeur nomme un habillage connu.

isStandardSchema#

function isStandardSchema(value: unknown): value is IStandardSchemaV1

Indique si une valeur implémente Standard Schema v1. Sert aux contrôles de démarrage : un appelant JavaScript peut passer n’importe quoi.

legacyEnvMessage#

function legacyEnvMessage(files: readonly string[]): string

Le message qui accompagne le refus de findLegacyEnvFiles : ce qu’il faut faire de chaque fichier, sans avoir à ouvrir la documentation.

loadEnv#

function loadEnv(opts?: ILoadEnvOptions): number

Charge .env dans process.env, SANS jamais écraser une variable déjà présente : le shell et l’orchestrateur gagnent toujours.

loginPagePath#

function loginPagePath(from?: string, page?: string): string

Adresse de la page de connexion qui ramène à from une fois connecté — le lien « Se connecter » d’une page applicative.

loginPageSkinFile#

function loginPageSkinFile(skin: LoginPageSkin): string | null

Fichier de la feuille d’un habillage, relatif à LOGIN_PAGE_ASSETS_BASE.

oauth2AuthorizePath#

function oauth2AuthorizePath(provider: string, from?: string, back?: string): string

Adresse qui démarre la connexion par un fournisseur : à ouvrir en navigation PLEINE PAGE, jamais par fetch — le navigateur doit suivre les redirections vers le fournisseur et revenir avec le cookie de session posé au retour.

parseFilters#

function parseFilters<const S extends IFilterSpec>(source: PageQuerySource, spec: S, options?: IParseFiltersOptions): FilterValues<S>

Le lecteur de filtres : transforme une source clé→valeur en filtres validés, selon la spec déclarée par la ressource. Fonction pure.

parsePageQuery#

function parsePageQuery(source: PageQuerySource, options?: IParsePageQueryOptions): IPageQuery

Le traducteur d’une requête de page : transforme une source clé→valeur en IPageQuery borné et validé. Fonction pure — aucun accès au kernel, à l’ALS ni à la requête HTTP.

pickOrder#

function pickOrder(order: IPageQuery["order"], allowed: readonly string[], fallback: NonNullable<IPageQuery["order"]>): NonNullable<IPageQuery["order"]>

Retient d’un order demandé les seuls couples dont le champ est déclaré triable, et retombe sur l’ordre par défaut s’il n’en reste aucun.

readBearerHeader#

function readBearerHeader(header: unknown): BearerHeader

Lit un en-tête Authorization et dit ce qu’il porte.

readDocScope#

function readDocScope(publish: unknown): DocScope | null

Lit la clé de frontmatter publish d’une page de documentation.

readSessionAuthentication#

function readSessionAuthentication(session: IMetaBagReader | null): ISessionAuthentication | null

Lit quand et comment une session a été ouverte.

redactSecrets#

function redactSecrets(line: string): string

Renvoie line avec les secrets connus masqués par ***.

redactUrlCredentials#

function redactUrlCredentials(text: string): string

Masque le mot de passe de toute URL contenue dans text (user:***@hôte).

renameOrderFields#

function renameOrderFields(order: NonNullable<IPageQuery["order"]>, aliases: Readonly<Record<string, string>>): NonNullable<IPageQuery["order"]>

Réécrit les noms de champs d’un order selon une table d’alias — le pont entre le vocabulaire public (celui de l’URL) et le schéma d’un backend.

safeRedirectPath#

function safeRedirectPath(value: unknown, fallback?: string): string

Rend value si c’est un chemin LOCAL sûr, sinon fallback.

standardJsonSchemaOf#

function standardJsonSchemaOf(schema: IStandardSchemaV1): IStandardJsonSchemaConverter | null

Le convertisseur JSON Schema d’un schéma, s’il en expose un.

toSchemaValidationIssues#

function toSchemaValidationIssues(issues: ReadonlyArray<IStandardSchemaIssue>, part?: string): ISchemaValidationIssue[]

Normalise les anomalies d’un schéma : segments objet { key } dépliés, clés converties en texte (un Symbol ferait lever Array.join), partie de l’entrée rattachée.

withTimeout#

function withTimeout<T>(promise: PromiseLike<T>, timeoutMs: number, label?: string): Promise<T>

Résout avec la valeur de promise si elle se règle avant timeoutMs, sinon rejette avec une TimeoutError.

Constantes (32)#

AUTH_API_BASE#

const AUTH_API_BASE = "/nodefony/security/api/auth"

Base des routes de session : connexion, second facteur, déconnexion, identité.

AUTH_LOGIN_PATH#

const AUTH_LOGIN_PATH = "/nodefony/security/api/auth/login"

Route de connexion par session : POST avec {username, password}.

AUTH_LOGIN_TOTP_PATH#

const AUTH_LOGIN_TOTP_PATH = "/nodefony/security/api/auth/login/totp"

Second facteur après un 202 mfaRequired : POST avec {code} (TOTP ou code de récupération).

AUTH_LOGOUT_PATH#

const AUTH_LOGOUT_PATH = "/nodefony/security/api/auth/logout"

Déconnexion : POST, idempotente ; rend logoutUrl quand la session venait d’un fournisseur.

AUTH_ME_PATH#

const AUTH_ME_PATH = "/nodefony/security/api/auth/me"

Identité de la session courante : GET, toujours 200 — { user }, ou { user: null } sans session.

DEFAULT_LOGIN_PAGE_SKIN#

const DEFAULT_LOGIN_PAGE_SKIN: LoginPageSkin

Habillage servi quand la configuration n’en choisit aucun.

ENV_FILE#

const ENV_FILE = ".env"

Le SEUL fichier d’environnement que Nodefony charge : les valeurs du POSTE (secrets de développement compris), jamais commité.

IDENTITY_CHANGED_EVENT#

const IDENTITY_CHANGED_EVENT = "onIdentityChanged"

Événement kernel — les droits d’une identité ont changé (ses rôles, par exemple), sans qu’elle soit morte. Une connexion longue a FIGÉ cette identité à l’ouverture : elle doit se fermer pour que le client se reconnecte avec l’identité à jour. Re-lire la base à chaque tick pour le détecter coûterait une lecture par connexion ; l’événement ne coûte rien tant que rien ne change. Charge utile : IIdentityChangedEvent.

INSECURE_TRANSPORT_MESSAGE#

const INSECURE_TRANSPORT_MESSAGE = "Credentials must be sent over HTTPS"

Refus d’un secret de connexion reçu en clair (HTTP) en production — corps error d’une réponse 403 des routes de connexion.

LOGIN_PAGE_ASSETS_BASE#

const LOGIN_PAGE_ASSETS_BASE = "/nodefony/security/login"

Base des fichiers de la page de connexion par défaut (script, feuille de style). Distincte de la page elle-même, dont le chemin se règle (loginPage.path) : ces fichiers ne changent pas d’adresse quand la page en change.

LOGIN_PAGE_LAYOUTS#

const LOGIN_PAGE_LAYOUTS: readonly [ "card", "split", "bare" ]

Modes de mise en page de la page de connexion par défaut.

LOGIN_PAGE_PATH#

const LOGIN_PAGE_PATH = "/login"

Chemin par défaut de la page de connexion servie par le framework.

LOGIN_PAGE_SCRIPT_PATH#

const LOGIN_PAGE_SCRIPT_PATH = "/nodefony/security/login/login.js"

Script de la page de connexion par défaut (bundle nodefony/login.js).

LOGIN_PAGE_SKINS#

const LOGIN_PAGE_SKINS: readonly [ "frontispiece", "ledger", "horizon", "console", "blueprint", "dots", "minimal", "enterprise", "photo-card" ]

Habillages de la page de connexion par défaut (loginPage.skin).

LOGIN_PAGE_SKIN_SPECS#

const LOGIN_PAGE_SKIN_SPECS: Readonly<Record<LoginPageSkin, ILoginPageSkinSpec>>

Mise en page et fond de chaque habillage — le Record exige les neuf.

LOGIN_PAGE_STYLE_PATH#

const LOGIN_PAGE_STYLE_PATH = "/nodefony/security/login/login.css"

Feuille de style de la page de connexion par défaut.

LOGIN_PAGE_THEME_KEY#

const LOGIN_PAGE_THEME_KEY = "nf-login-theme"

Clé du stockage local où la page de connexion par défaut retient le thème choisi (light ou dark). Le gabarit la lit avant le premier rendu, le script de la page l’écrit à la bascule.

MFA_METHOD_TOTP#

const MFA_METHOD_TOTP = "totp"

Méthode de second facteur « code à usage unique » : un code TOTP, ou un code de récupération, présenté à AUTH_LOGIN_TOTP_PATH.

OAUTH2_API_BASE#

const OAUTH2_API_BASE = "/nodefony/security/api/oauth2"

Base de la connexion par un fournisseur externe (OAuth 2.0 / OpenID Connect).

OAUTH2_CANCELLED_REASON#

const OAUTH2_CANCELLED_REASON = "access_denied"

Code OAuth 2.0 d’une annulation par l’utilisateur (RFC 6749 §4.1.2.1).

OAUTH2_FAILED_REASON#

const OAUTH2_FAILED_REASON = "failed"

Valeur de reason que le callback OAuth pose sur l’écran d’échec quand la cause n’est pas un code normalisé du fournisseur (state invalide, échange du code refusé, compte non provisionné). Seule access_denied dit une ANNULATION ; toute autre valeur est un échec à annoncer.

OAUTH2_PROVIDERS_PATH#

const OAUTH2_PROVIDERS_PATH = "/nodefony/security/api/oauth2/providers"

Fournisseurs de connexion configurés : GET → { providers: {name, label}[] }.

PAGE_QUERY_KEYS#

const PAGE_QUERY_KEYS: ReadonlySet<string>

Les clés que le contrat de page revendique sur le fil — source unique.

REVOCATION_REVALIDATE_MS#

const REVOCATION_REVALIDATE_MS = 30000

Période de re-validation des connexions à identité RÉVOCABLE, en ms.

SESSION_AMR_KEY#

const SESSION_AMR_KEY = "amr"

Clé de métadonnée : méthodes d’authentification utilisées (RFC 8176).

SESSION_AUTH_AT_KEY#

const SESSION_AUTH_AT_KEY = "authAt"

Clé de métadonnée : heure de l’authentification (millisecondes epoch).

UNKNOWN_COUNT#

const UNKNOWN_COUNT = -1

Ce qu’un store rend quand il ne PEUT pas compter — convention de tous les backends du dépôt (countSessions, countTokens, countEndpoints).

WEBAUTHN_API_BASE#

const WEBAUTHN_API_BASE = "/nodefony/security/api/webauthn"

Base des cérémonies WebAuthn (passkeys).

WEBAUTHN_LOGIN_OPTIONS_PATH#

const WEBAUTHN_LOGIN_OPTIONS_PATH = "/nodefony/security/api/webauthn/login/options"

Défi de connexion par passkey : POST (corps vide) → options WebAuthn en JSON.

WEBAUTHN_LOGIN_VERIFY_PATH#

const WEBAUTHN_LOGIN_VERIFY_PATH = "/nodefony/security/api/webauthn/login/verify"

Vérification de la passkey : POST avec {response} → ouvre la session.

WEBAUTHN_STATUS_PATH#

const WEBAUTHN_STATUS_PATH = "/nodefony/security/api/webauthn/status"

État de la connexion par passkey : GET → { enabled: boolean }, toujours 200 quand le service existe. Les cérémonies répondent 503 quand les passkeys sont coupées ; cette route permet à un écran de connexion de ne pas proposer un bouton voué à cet échec.

isPlainObject#

const isPlainObject: (obj: unknown) => obj is Record<string, unknown>

Vérifie qu’un objet est un “plain object” — {} ou Object.create(null).

Interfaces (23)#

IGcSchedulerOptions#

interface IGcSchedulerOptions

Options de construction d’un GcScheduler.

• intervalS: number — Intervalle entre deux passes, en secondes.
• run: () => unknown — La passe de maintenance (typiquement () => store.gc()).
• jitter?: boolean — Étale le départ d’un délai aléatoire borné (anti thundering herd en cluster).
• onError?: (error: unknown) => void — Reçoit l’erreur d’une passe qui a levé (sinon l’échec est silencieux).
• initialDelayMs?: number — Délai fixe avant la première passe (ms, défaut 30_000) — laisse finir le boot avant de scanner.
• jitterCapMs?: number — Plafond du jitter (ms, défaut 60_000) — borne le retard de la 1ʳᵉ passe.

IIdentityChangedEvent#

interface IIdentityChangedEvent

Charge utile de IDENTITY_CHANGED_EVENT.

• readonly identifier: string — Identifiant de connexion de l’identité dont les droits ont changé.

ILoadEnvOptions#

interface ILoadEnvOptions

Options de loadEnv — où lire, et quels noms de l’ancienne convention signaler.

• runtimeEnv?: string — Mode RUNTIME ("development" | "production") = NODE_ENV.
• appEnv?: string — Environnement de DÉPLOIEMENT (string libre : staging / canary…) = APP_ENV / NF_ENV.
• cwd?: string — Racine du projet où chercher les fichiers (défaut process.cwd()).

ILoginPageDescription#

interface ILoginPageDescription

Ce que la page de connexion par défaut doit afficher, décrit par la sécurité et lu par le contrôleur qui la sert.

• readonly path: string — Chemin où la page est servie (loginPage.path).
• readonly title: string | null — Titre de la page, ou null pour le titre par défaut.
• readonly logo: string | null — Adresse du logo, ou null pour celui de Nodefony.
• readonly template: string | null — Gabarit .eta de l’application qui remplace celui du framework, ou null.
• readonly heading: string | null — Titre de la carte et de l’onglet, ou null pour « Se connecter ».
• readonly subtitle: string | null — Ligne sous le titre, ou null pour la phrase déduite des moyens proposés.
• readonly stylesheet: string | null — Feuille de l’application chargée APRÈS celle du framework, ou null.
• readonly providersFirst: boolean — Les fournisseurs passent-ils avant le formulaire (quand il y en a) ?
• readonly hero: ILoginPageHero | false | null — Panneau d’illustration : null = vitrine Nodefony, false = marque seule, sinon le contenu qui la remplace.
• readonly footer: boolean — Pied de page : protections de la session et mention du framework.
• readonly skin: LoginPageSkin — Habillage : feuille chargée entre celle du framework et celle de l’application.
• readonly layout: LoginPageLayout — Mode de mise en page (loginPage.layout, sinon celui de l’habillage).
• readonly password: boolean — Le formulaire identifiant et mot de passe est-il proposé ?
• readonly passkey: boolean — La connexion par passkey est-elle proposée ?
• readonly previewPicker: boolean — Sélecteur d’aperçu demandé (loginPage.previewPicker) ; la page ne l’affiche qu’en développement.
• readonly previewHook?: string | null — Chemin de l’application appelé en POST ({ skin, layout }) avant chaque rechargement de l’aperçu (loginPage.previewHook), ou null/absent.
• readonly providers: readonly ILoginPageProvider[] — Fournisseurs à proposer, dans l’ordre de la configuration.

ILoginPageHero#

interface ILoginPageHero

Contenu du panneau d’illustration qui REMPLACE la vitrine Nodefony. Texte seul, échappé au rendu : l’image du panneau passe par la feuille de l’application (--nf-login-hero-image), jamais par une adresse injectée dans le balisage.

• readonly heading: string — Accroche du panneau.
• readonly text: string | null — Phrase sous l’accroche, ou null.

ILoginPageProvider#

interface ILoginPageProvider

Fournisseur d’identité proposé sur la page de connexion.

• readonly name: string — Nom du fournisseur, tel qu’il figure dans l’adresse d’autorisation.
• readonly label: string — Libellé affiché sur le bouton.
• readonly icon: string | null — Image du bouton (chemin servi par l’application ou URL), ou null pour l’icône du framework (marque GitHub, sinon une clé).

ILoginPageSkinSpec#

interface ILoginPageSkinSpec

Ce qu’un habillage impose au gabarit, au-delà de sa feuille.

• readonly layout: LoginPageLayout — Mise en page pour laquelle l’habillage est dessiné, sauf layout explicite.
• readonly backdrop: boolean — Fond de page décoré (motif, image) : le pied passe alors sur une pastille pleine pour rester lisible (<body data-backdrop>).

IParseFiltersOptions#

interface IParseFiltersOptions

Réglages de lecture d’un point d’entrée qui porte plus que des filtres.

• accepts?: readonly string[] — Paramètres que ce point d’entrée lit lui-même, hors filtres — une projection (?include=author), un format de sortie, une clé propre au transport.

IParsePageQueryOptions#

interface IParsePageQueryOptions

Réglages d’un point d’entrée paginé : ses bornes et ce qu’il accepte de trier.

• defaultLimit?: number — Taille de page quand le client n’en demande pas.
• maxLimit?: number — Cap dur : une demande supérieure est ramenée à ce plafond (jamais refusée — un client qui demande trop ne mérite pas une erreur, il mérite une page).
• sortable?: readonly string[] — Champs sur lesquels ce point d’entrée sait trier — l’allowlist qui rend order exploitable.
• searchable?: boolean — Ce point d’entrée sait-il chercher (?q=) — c’est-à-dire relayer q jusqu’à un store qui l’honore.

IProfilerQuery#

interface IProfilerQuery

Une requête ORM (SQL/NoSQL) capturée pendant le scope de requête, pour le profiler dev-only. Shape canonique partagée par tous les adapters ORM et le Profiler @nodefony/http (structurellement identique à ProfileQuery).

• sql: string — Requête (SQL ou commande NoSQL), tronquée si volumineuse.
• startMs?: number — Début relatif (performance.now(), ms) — même horloge que PhaseTiming.startMs du Context, donc la requête se PLACE dans le waterfall des phases (le SQL apparaît DANS la barre action), au lieu de …
• durationMs: number — Durée d’exécution en ms.
• rows?: number — Lignes affectées/retournées, si connu.
• connector?: string — Connecteur émetteur (drizzle, mongoose…).

IRequestUser#

interface IRequestUser

L’utilisateur AUTHENTIFIÉ d’une requête, tel que le lit un contrôleur (this.user). Contrat minimal du cœur, que l’IUser de @nodefony/user satisfait : le framework le type sans dépendre du paquet des comptes.

• readonly id: string — Identifiant interne (UUID).
• readonly identifier: string — Identifiant de connexion (login, e-mail).
• readonly roles: readonly string[] — Rôles accordés, sans hiérarchie résolue.

IRevocationPolicy#

interface IRevocationPolicy<T>

Ce que le registre sait faire d’une entrée — fourni par son propriétaire.

• isValid(entry: T): Promise<boolean> | boolean — L’identité de l’entrée est-elle toujours valable ?
• revoke(entry: T): void — Ferme la connexion de l’entrée — appelée une fois, l’entrée déjà retirée.
• identityOf?(entry: T): string — Identifiant de connexion de l’identité figée par l’entrée — undefined si elle n’en porte pas.
• refresh?(entry: T): void — Ferme l’entrée pour que son client se RECONNECTE avec une identité à jour — à distinguer de revoke, qui signifie « identité morte ».
• periodMs?: number — Période du tick, en ms.

ISchemaValidationIssue#

interface ISchemaValidationIssue

Une anomalie de validation, normalisée : chemin en clés textuelles, et partie de l’entrée qui l’a portée.

• readonly message: string — Message lisible.
• readonly path: readonly string[] — Chemin de la valeur fautive DANS sa partie (["author", "email"]).
• readonly in?: string — La partie de l’entrée : body, query, params, headers…

ISessionAuthentication#

interface ISessionAuthentication

Comment une session a été authentifiée.

• readonly at: number — Heure de l’authentification, en millisecondes epoch.
• readonly amr: readonly string[] — Méthodes utilisées (RFC 8176) ; vide quand un fournisseur a authentifié.

IStandardJsonSchemaConverter#

interface IStandardJsonSchemaConverter

Convertisseur JSON Schema optionnel (Standard JSON Schema v1), exposé par certaines bibliothèques sous ~standard.jsonSchema (Zod 4 le fait). Sert à DÉCRIRE un schéma — console d’administration, documentation —, jamais à valider.

• readonly input: (options: { readonly target: string; }) => Record<string, unknown> — JSON Schema du type d’entrée ; peut lever si la conversion est impossible.

IStandardSchemaFailure#

interface IStandardSchemaFailure

Résultat d’une validation en échec.

• readonly issues: ReadonlyArray<IStandardSchemaIssue> — Les anomalies relevées.

IStandardSchemaIssue#

interface IStandardSchemaIssue

Une anomalie rendue par un schéma en échec.

• readonly message: string — Message lisible de l’anomalie.
• readonly path?: ReadonlyArray<PropertyKey | IStandardSchemaPathSegment> — Chemin de la valeur fautive, s’il y en a un.

IStandardSchemaPathSegment#

interface IStandardSchemaPathSegment

Un segment de chemin d’anomalie, sous sa forme objet.

• readonly key: PropertyKey — La clé du segment.

IStandardSchemaProps#

interface IStandardSchemaProps<Input = unknown, Output = Input>

Les propriétés ~standard d’un schéma.

• readonly version: 1 — Version de la spécification.
• readonly vendor: string — Bibliothèque qui implémente le schéma (zod, valibot…).
• readonly validate: (value: unknown, options?: { readonly libraryOptions?: Record<string, unknown>; }) => StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>> — Valide une valeur inconnue ; synchrone, sauf si le schéma est asynchrone.
• readonly types?: IStandardSchemaTypes<Input, Output> — Types inférés, pour la compilation.

IStandardSchemaSuccess#

interface IStandardSchemaSuccess<Output>

Résultat d’une validation réussie.

• readonly value: Output — La valeur validée, éventuellement transformée par le schéma.
• readonly issues?: undefined — Absent en cas de succès.

IStandardSchemaTypes#

interface IStandardSchemaTypes<Input = unknown, Output = Input>

Types portés par un schéma (présents à la compilation seulement).

• readonly input: Input — Le type accepté en entrée.
• readonly output: Output — Le type rendu après validation.

IStandardSchemaV1#

interface IStandardSchemaV1<Input = unknown, Output = Input>

Un schéma conforme à Standard Schema v1 — Zod 4, Valibot, ArkType…

• readonly "~standard": IStandardSchemaProps<Input, Output> — Les propriétés de la spécification.

RequestContextPayload#

interface RequestContextPayload

• requestId: string
• scheme?: string
• user?: unknown — Set by the security firewall after afterAuth (P6).
• traceparent?: string — W3C traceparent header for OpenTelemetry compatibility (P2.7).
• queries?: IProfilerQuery[] — Buffer de requêtes ORM du profiler — présent uniquement en dev quand le HttpKernel l’alloue (profiler actif).
• context?: unknown — Contexte transport courant (HttpContext / WebsocketContext), posé par HttpKernel à l’entrée du scope (V4.1).
• scope?: IScope — Scope DI de la requête — le même objet que context.container.
• body?: unknown — Corps de la requête posé par le pont WS-RPC api.request (mutations) : en WebSocket il n’existe aucun corps HTTP parsé, donc le pont transporte la charge utile de la frame ici (per-invocation via …
• idempotencyKey?: string — Clé d’idempotence (modèle Stripe) portée par une mutation du data plane admin : posée par le pont WS (params.idempotencyKey) ou lue de l’en-tête HTTP Idempotency-Key.
• renderSink?: { body?: string | Buffer; status?: number; } — Puits de CAPTURE du rendu, posé par le pont WS-RPC api.request : une action user peut répondre par un RENDU (renderJson/renderView) au lieu d’une valeur nue.
• invocation?: unknown — Profil de l’invocation en cours (FrameProfile de @nodefony/http), posé par le pont WS-RPC.
• resolver?: unknown — Résolution de l’appel en cours quand elle n’est pas celle du contexte : le pont WS-RPC api.request crée un résolveur PAR APPEL, sans le ranger sur context.resolver — qui reste celui de la conn …
• token?: unknown — Jeton d’authentification posé par le pare-feu après afterAuth (rôles, périmètres, attributs).

Types (18)#

BearerHeader#

type BearerHeader = { kind: "absent"; } | { kind: "empty"; } | { kind: "other"; } | { kind: "token"; token: string; }

Ce que porte un en-tête Authorization — et surtout ce qu’il NE porte pas.

DocScope#

type DocScope = "user" | "core" | "none"

À qui une page de documentation s’adresse : user (qui se sert de Nodefony), core (qui développe le framework, dans son dépôt), none (personne — elle reste dans git, nulle part ailleurs).

FacetCount#

type FacetCount = number | null

Valeur d’un compteur tel qu’il traverse HTTP : un nombre, ou null quand le backend branché ne sait pas répondre.

FacetCounts#

type FacetCounts<S> = { [K in keyof S]: FacetCount; }

Les compteurs rendus, une clé par facette déclarée.

FieldReader#

type FieldReader<T> = (item: T, field: string) => unknown

Lit la valeur d’un champ triable sur un élément. Chaque store fournit la sienne : le nom du champ est public (celui de l’URL), la façon de l’atteindre est interne.

FilterDef#

type FilterDef = FilterKind | readonly string[] | FilterEach

Définition d’UN filtre : sa nature, la liste fermée de ses valeurs, ou l’une des deux répétée (FilterEach).

FilterKind#

type FilterKind = "string" | "boolean" | "int" | "uuid" | "objectId"

Nature d’un filtre — ce qui suffit à le lire depuis une source clé→valeur.

FilterValue#

type FilterValue<D extends FilterDef> = D extends { each: infer E; } ? ScalarFilterValue<E>[] : ScalarFilterValue<D>

Le type JavaScript qu’une définition de filtre produit une fois lue — un tableau pour un filtre { each }, la valeur seule sinon.

FilterValues#

type FilterValues<S extends IFilterSpec> = { -readonly [K in keyof S]?: FilterValue<S[K]>; }

Les filtres lus, typés depuis la spec : une énumération rend son union de littéraux, boolean rend un booléen, int un nombre.

IFacetSpec#

type IFacetSpec<Q> = Readonly<Record<string, Partial<Q>>>

Déclaration des facettes d’une ressource : nom public → filtre de sa requête de liste.

IFilterSpec#

type IFilterSpec = Readonly<Record<string, FilterDef>>

Ce qu’un point d’entrée sait filtrer : nom public → définition.

InferSchemaInput#

type InferSchemaInput<S extends IStandardSchemaV1> = NonNullable<S["~standard"]["types"]>["input"]

Le type qu’accepte un schéma.

InferSchemaOutput#

type InferSchemaOutput<S extends IStandardSchemaV1> = NonNullable<S["~standard"]["types"]>["output"]

Le type que rend un schéma validé.

LoginPageLayout#

type LoginPageLayout = (typeof LOGIN_PAGE_LAYOUTS)[number]

Un mode de mise en page de la page de connexion (loginPage.layout).

LoginPageSkin#

type LoginPageSkin = (typeof LOGIN_PAGE_SKINS)[number]

Un habillage de la page de connexion (loginPage.skin).

PageQuerySource#

type PageQuerySource = Readonly<Record<string, unknown>>

Source d’où extraire une requête de page, agnostique de sa provenance : une query string déjà parsée (?limit=20&offset=40), le corps JSON d’une requête QUERY (RFC 10008), ou tout autre porteur clé→valeur.

PaginationMode#

type PaginationMode = "offset" | "cursor"

Les deux modes de pagination du contrat IPageQuery, mutuellement exclusifs : un backend n’expose que l’un (IPageQuery.offset navigation directe, ou IPageQuery.cursor navigation « après ce jeton »). Cf le TSDoc d’IPageQuery : « un backend n’expose qu’un mode ; le store le déclare ».

StandardSchemaResult#

type StandardSchemaResult<Output> = IStandardSchemaSuccess<Output> | IStandardSchemaFailure

Résultat de ~standard.validate.

← Toutes les références d’API