Nodefony 10.0.0-beta.5
Framework Node.js fullstack — HTTP & WebSocket, même contexte

Référence d'API — @nodefony/framework — decorators

stable

Documentation › Référence d’API › @nodefony/framework › decorators

Générée depuis les déclarations de types publiées de @nodefony/framework 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/framework#

import { … } from "@nodefony/framework" — 48 symboles.

Fonctions (20)#

Anonymous#

function Anonymous(): (target: object, propertyKey?: string, descriptor?: PropertyDescriptor) => any

Déclare une action (méthode) ou un contrôleur (classe) publique : skip l’autorisation (override un @IsGranted de classe sur cette méthode) ET skip l’authentification (réutilise le mécanisme @BypassFirewall → pas de 401 en zone protégée). L’alias lisible de « permitAll » (mental model Spring). Pour un login, une sonde de liveness, une page publique d’un contrôleur par ailleurs protégé.

Body#

function Body(keyOrOptions?: string | { stream?: boolean; }): (target: object, propertyKey: string, parameterIndex: number) => void

Décorateur de paramètre @Body : - @Body() → body parsé entier · @Body("field") → un champ du body parsé. - @Body({ stream: true }) → flux brut de la requête (Readable), sans parse en mémoire (P2.9 — gros uploads sans pic RAM ; le pipeline saute le parse busboy/JSON pour cette route).

BypassFirewall#

function BypassFirewall(target: object, propertyKey?: string, descriptor?: PropertyDescriptor): any

Déclare une route (décorateur de méthode) ou tout un contrôleur (décorateur de classe) comme PUBLIQUE : le firewall ne s’exécute pas (Route.bypassFirewall). Pour la liveness (/health, /info — sondes k8s/monitoring NON authentifiées, ping pré-login), les webhooks signés, ou un endpoint d’auth (login). Sucre déclaratif sur l’option RouteOptions.bypassFirewall (les deux coexistent ; l’option l’emporte).

Csp#

function Csp(directives: CspDirectives): (target: object, propertyKey?: string, descriptor?: PropertyDescriptor) => any

@Csp({ "frame-src": [...] }) — déclare des directives CSP additionnelles pour l’action (méthode) ou tout le contrôleur (classe). Distinct de registerCspOrigins (besoins PERMANENTS d’un module, ex. Vite) : ici c’est le besoin ponctuel d’UNE réponse (embarquer une iframe YouTube, autoriser une CDN).

Domain#

function Domain(patterns: string | string[]): (target: object, propertyKey?: string, descriptor?: PropertyDescriptor) => any

Restreint une route (décorateur de méthode) ou tout un contrôleur (décorateur de classe) à un ou plusieurs vhosts. Source de vérité du domaine de routing — le host posé ici alimente Route.host, compilé en RegExp ancrée/wildcard (matcher partagé @nodefony/http). Domaine non servi par la route → 403.

function Header(key: string, value: string): (target: object, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor

Ajoute un en-tête à la réponse d’une action.

HttpCode#

function HttpCode(statusCode: number): (target: object, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor

Fixe le code de statut HTTP de la réponse d’une action.

Idempotent#

function Idempotent(options?: { required?: boolean; }): (target: object, propertyKey?: string, descriptor?: PropertyDescriptor) => any

@Idempotent() — protège une mutation (POST/PUT/PATCH/DELETE) d’un controller userland contre le double-effet d’un rejeu (double-clic, reconnexion socket, retry réseau), via une Idempotency-Key cliente (modèle Stripe, conforme draft-ietf-httpapi-idempotency-key-header). No-op sur les méthodes sûres (GET…).

IsGranted#

function IsGranted(attribute: string | readonly string[], options?: { subject?: string; }): (target: object, propertyKey?: string, descriptor?: PropertyDescriptor) => any

Exige une autorisation pour l’action (décorateur de méthode) ou tout le contrôleur (décorateur de classe).

Redirect#

function Redirect(url: string, statusCode?: number): (target: object, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor

Redirige la réponse d’une action vers une autre URL.

RequireAuthentication#

function RequireAuthentication(options?: IRequireAuthenticationOptions): (target: object, propertyKey?: string, descriptor?: PropertyDescriptor) => any

Exige une connexion RÉCENTE et/ou faite avec certains moyens pour l’action (décorateur de méthode) ou tout le contrôleur (décorateur de classe).

RequireScope#

function RequireScope(scope: string | readonly string[]): (target: object, propertyKey?: string, descriptor?: PropertyDescriptor) => any

Exige un scope (api:action) pour l’action (décorateur de méthode) ou tout le contrôleur (décorateur de classe). Axe d’autorisation distinct des rôles (@IsGranted) : un scope downscope un jeton MACHINE délégué (clé API, JWT d’agent, OAuth) — il est un no-op pour une session humaine, dont les droits sont portés par ses rôles (cf ScopeVoter).

Scope#

function Scope(scope: ControllerScope): (target: { scope?: ControllerScope; }) => void

Déclare la portée d’instanciation d’un contrôleur — pose le statique scope de la classe (hérité de Controller, défaut "singleton"). Lu par le constructeur de Controller (new.target) et par le Resolver : 0 Reflect.

UseSession#

function UseSession(options?: UseSessionOptions): (target: object, propertyKey?: string, descriptor?: PropertyDescriptor) => any

Déclare qu’une route (décorateur de méthode) ou tout un contrôleur (décorateur de classe) a besoin d’une session serveur. C’est l’unique façon d’activer une session (avec la reprise auto d’un cookie existant — L1) : il n’y a plus de sessionAutoStart global « démarre partout » (le moteur du ×23). Lazy par défaut — aucune session pour une route qui n’en déclare pas.

buildContextParamArgs#

function buildContextParamArgs(metas: readonly ParamMeta[], context: IParamArgSource, paramsMap: Record<string, unknown>, queryOverride?: Record<string, unknown>): unknown[]

Résout les paramètres décorés d’une action depuis un Context — la mise en forme UNIQUE, appelée par le Resolver (routes HTTP et WS) comme par les actions @RealtimeAction, pour qu’un décorateur ne puisse pas prendre deux sens selon le transport.

controller#

function controller(prefix: string): <T extends ControllerConstructor & { prefix?: string; }>(mycontroller: T) => T

Declaration Controller

controllers#

function controllers(targets: TypeController<Controller>[] | TypeController<Controller>): <T extends Constructor<Module>>(constructor: T) => T

Rattache un ou plusieurs contrôleurs à un module, dont ils suivent le cycle de vie.

getParamArgsMeta#

function getParamArgsMeta(proto: object, method: string | symbol): readonly ParamMeta[] | null

Les paramètres décorés d’une méthode (@Body, @CurrentUser…), ou null si elle n’en porte aucun. Lecture Reflect : à faire une fois, hors du chemin de chaque requête.

route#

function route(name: string, options: RouteOptions & { schema?: undefined; bodyStream?: false; }): RouteMethodDecorator
function route<S extends IRouteSchema>(name: string, options: RouteOptionsWithSchema<S> & { bodyStream?: false; }): SchemaRouteMethodDecorator<S, false>
function route<S extends IRouteSchema & { readonly body?: undefined; }>(name: string, options: RouteOptionsWithSchema<S> & { bodyStream: true; }): SchemaRouteMethodDecorator<S, true>

Crée une route avec le nom et les options spécifiés.

routeExpectsBodyStream#

function routeExpectsBodyStream(routeDef: { controller?: { prototype: object; } | null; classMethod?: string; bodyStream?: boolean; }): boolean

P2.9 — Indique si l’action d’une route attend le flux brut du body (un paramètre @Body({ stream:true })). Le résultat est mémoïsé sur route.bodyStream : lecture Reflect au 1er appel, O(1) ensuite → 0 coût hot-path. Lu en amont par handleHttp (avant le parse) pour décider de sauter le parse busboy/JSON. Typage structurel (pas d’import Route → 0 cycle).

Constantes (20)#

All#

const All: IHttpMethodDecorator

@All — route sans restriction de méthode : matche toutes les méthodes HTTP (équivalent NestJS @All()). N’émet aucun requirement methods, donc Route.matchRequirements ne lève jamais 405 sur la méthode.

const Cookie: (key?: string) => (target: object, propertyKey: string, parameterIndex: number) => void

CsrfExempt#

const CsrfExempt: () => (target: object, propertyKey?: string, descriptor?: PropertyDescriptor) => any

@CsrfExempt() — opt-OUT de la défense CSRF pour une route, en conservant l’authentification et l’autorisation (≠ @Anonymous/@BypassFirewall qui coupent l’auth). Pour un webhook ou une API recevant un POST cross-origin légitime, dont la requête est authentifiée autrement (signature HMAC du provider, clé API). Classe = toutes les actions. Marqueur seul (0 logique sécu ici).

CsrfProtect#

const CsrfProtect: () => (target: object, propertyKey?: string, descriptor?: PropertyDescriptor) => any

@CsrfProtect() — opt-IN à la défense CSRF synchronizer token (double-submit signé HMAC) EN PLUS de la défense globale Fetch Metadata/Origin (étape 1, toujours active). Pour les mutations à haute valeur (changement de mot de passe, virement) : une requête sûre vers la route SÈME le cookie lisible csrf-token ; la mutation DOIT rejouer ce token dans l’en-tête x-csrf-token (sinon 403). Classe = toutes les actions. N’écrit qu’un marqueur (0 import @nodefony/security, 0 cycle).

CurrentUser#

const CurrentUser: (key?: string) => (target: object, propertyKey: string, parameterIndex: number) => void

@CurrentUser() user: IUser — injecte l’utilisateur de l’ALS (jamais le credential).

Delete#

const Delete: IHttpMethodDecorator

Get#

const Get: IHttpMethodDecorator

const Head: IHttpMethodDecorator

Headers#

const Headers: (key?: string) => (target: object, propertyKey: string, parameterIndex: number) => void

Options#

const Options: IHttpMethodDecorator

Param#

const Param: (key?: string) => (target: object, propertyKey: string, parameterIndex: number) => void

Patch#

const Patch: IHttpMethodDecorator

Post#

const Post: IHttpMethodDecorator

Put#

const Put: IHttpMethodDecorator

Query#

const Query: (key?: string) => (target: object, propertyKey: string, parameterIndex: number) => void

Req#

const Req: (key?: string) => (target: object, propertyKey: string, parameterIndex: number) => void

Res#

const Res: (key?: string) => (target: object, propertyKey: string, parameterIndex: number) => void

Session#

const Session: (key?: string) => (target: object, propertyKey: string, parameterIndex: number) => void

UploadedFile#

const UploadedFile: (key?: string) => (target: object, propertyKey: string, parameterIndex: number) => void

UploadedFiles#

const UploadedFiles: (key?: string) => (target: object, propertyKey: string, parameterIndex: number) => void

Interfaces (7)#

IAuthenticationRequirement#

interface IAuthenticationRequirement

Exigence d’authentification figée d’une action — fusion classe + méthode au plus strict (âge le plus court, moyens réunis), calculée UNE fois par route. Objet partagé entre requêtes : ne jamais muter.

IHttpMethodDecorator#

interface IHttpMethodDecorator

Un décorateur de méthode HTTP (@Get, @Post…). Sans schéma, la signature de l’action est libre (décorateurs de paramètre) ; avec schema, l’action reçoit un argument unique RouteInput<S>, vérifié à la compilation.

IParamArgSource#

interface IParamArgSource

Ce qu’un Context — HTTP comme WebSocket — offre à la résolution des paramètres décorés. Forme structurelle : le framework n’importe pas les classes de contexte pour la lire.

IRequireAuthenticationOptions#

interface IRequireAuthenticationOptions

Options de RequireAuthentication.

ParamMeta#

interface ParamMeta

SecurityClause#

interface SecurityClause

Une clause @IsGranted : un OU plusieurs attributs (OR interne), sujet optionnel. @IsGranted("ROLE_ADMIN") → { anyOf: ["ROLE_ADMIN"] } ; @IsGranted(["A","B"]) → { anyOf: ["A","B"] } (un seul suffit) ; @IsGranted("doc.edit", { subject: "id" }) → le param de route id est passé au voter.

SecurityRequirement#

interface SecurityRequirement

Exigence d’autorisation figée d’une action — calculée UNE fois par route (fusion classe + méthode) puis gelée sur RouteActionMeta.security. Objet PARTAGÉ entre toutes les requêtes : ne jamais muter. null (hors de ce type) = aucune garde → coût nul sur le hot path.

Types (1)#

CspDirectives#

type CspDirectives = Record<string, readonly string[]>

Directives CSP additionnelles déclarées par une action (@Csp) : directive → sources (ex. { "frame-src": ["https://youtube.com"] }). Structurellement compatible avec CspFragment (@nodefony/security) — aucun import cross-module (0 cycle). Mergé additivement dans le CSP de la réponse par le firewall, UNIQUEMENT sur les routes qui en déclarent (cold path).

← Toutes les références d’API