@nodefony/framework 10.0.0-alpha.9 → 10.0.0-beta.2

package/dist/nodefony/src/docsReader.js

@@ -1,5 +1,5 @@
 import { basename, dirname, extname, join } from "node:path";
-import { findProjectRoot, resolveSymbolsFile } from "nodefony";
+import { findProjectRoot, packageManagerCommandLines, packageManagerExecArgs, portableSpawn, resolvePackageManager, resolveSymbolsFile } from "nodefony";
 import { existsSync } from "node:fs";
 import { promisify } from "node:util";
 import { readFile, readdir, stat } from "node:fs/promises";
@@ -70,8 +70,8 @@ function parseFrontmatter(raw) {
 }
 /** Premier titre `# H1` du corps markdown, ou `null`. */
 function firstHeading(body) {
-	const m = body.match(/^#\s+(.+)$/m);
-	return m ? m[1].trim() : null;
+	const title = body.match(/^#\s+(.+)$/m)?.[1];
+	return title === void 0 ? null : title.trim();
 }
 /**
 * Date ISO du dernier commit git d'un fichier (détecte la dérive doc↔code).
@@ -297,19 +297,22 @@ async function searchModuleDocs(targets, query, options = {}) {
 			}
 			score += occurrences / Math.max(1, foldedBody.length / DOC_LENGTH_PIVOT);
 			const candidates = [];
-			for (let i = 0; i < lines.length; i += 1) {
-				const carried = terms.filter((t) => foldedLines[i].includes(t));
-				if (carried.length === 0) continue;
+			for (const [i, folded] of foldedLines.entries()) {
+				const carried = terms.filter((t) => folded.includes(t));
+				const [matchedTerm] = carried;
+				if (matchedTerm === void 0) continue;
 				candidates.push({
 					lineNumber: i,
+					line: lines[i] ?? "",
+					folded,
 					coverage: carried.length,
-					matchedTerm: carried[0]
+					matchedTerm
 				});
 			}
 			candidates.sort((a, b) => b.coverage - a.coverage || a.lineNumber - b.lineNumber);
 			const matches = candidates.slice(0, perDoc).sort((a, b) => a.lineNumber - b.lineNumber).map((c) => ({
 				line: c.lineNumber + 1,
-				text: snippet(lines[c.lineNumber], foldedLines[c.lineNumber], c.matchedTerm)
+				text: snippet(c.line, c.folded, c.matchedTerm)
 			}));
 			hits.push({
 				module: target.key,
@@ -414,10 +417,10 @@ async function typeFiles(modulePath) {
 */
 function declarationStart(lines, at) {
 	let start = at;
-	if (start > 0 && lines[start - 1].trim().endsWith("*/")) {
+	if (lines[start - 1]?.trim().endsWith("*/")) {
 		let i = start - 1;
-		while (i > 0 && !lines[i].trim().startsWith("/**")) i -= 1;
-		if (lines[i].trim().startsWith("/**")) start = i;
+		while (i > 0 && !lines[i]?.trim().startsWith("/**")) i -= 1;
+		if (lines[i]?.trim().startsWith("/**")) start = i;
 	}
 	return start;
 }
@@ -457,14 +460,15 @@ async function readSymbolDeclaration(modulePath, symbolName) {
 		let depth = 0;
 		let opened = false;
 		let end = at;
-		for (let i = at; i < lines.length; i += 1) {
-			for (const ch of lines[i]) if (ch === "{") {
+		for (const [offset, line] of lines.slice(at).entries()) {
+			const i = at + offset;
+			for (const ch of line) if (ch === "{") {
 				depth += 1;
 				opened = true;
 			} else if (ch === "}") depth -= 1;
 			end = i;
 			if (opened && depth <= 0) break;
-			if (!opened && lines[i].trimEnd().endsWith(";")) break;
+			if (!opened && line.trimEnd().endsWith(";")) break;
 		}
 		const declaration = lines.slice(start, end + 1).join("\n");
 		return declaration.length > DECLARATION_MAX_CHARS ? {
@@ -649,50 +653,54 @@ async function listTestGroups(modulePath) {
 *   config du module (la liste `reporter` dupliquée par module divergeait).
 * - sinon (cœur : monocart, pas de `vitest.config.ts`) → `npm run coverage`.
 *
+* Le binaire et le script passent par le gestionnaire de paquets du PROJET :
+* `npx` n'existe pas chez bun, et sous pnpm il chercherait hors de l'arbre que
+* le verrou décrit.
+*
 * @param modulePath - racine du module (où vit `vitest.config.ts`)
 * @param file - chemin relatif d'UN fichier de test, déjà validé par l'appelant
+* @param manager - gestionnaire du projet ; défaut : résolu depuis la racine
+*   de l'application qui contient le module
 * @returns commande, arguments en tableau (spawn sans shell) et libellé du mode
 */
-function testRunCommand(modulePath, file) {
+function testRunCommand(modulePath, file, manager = resolvePackageManager({ dir: findProjectRoot(modulePath) ?? modulePath }).name) {
 	const hasVitest = existsSync(join(modulePath, "vitest.config.ts"));
 	if (file && hasVitest) return {
-		cmd: "npx",
-		args: [
-			"vitest",
-			"run",
-			file
-		],
+		cmd: manager,
+		args: packageManagerExecArgs(manager, "vitest", ["run", file]),
 		mode: `vitest run ${file}`
 	};
 	if (hasVitest) return {
-		cmd: "npx",
-		args: [
-			"vitest",
+		cmd: manager,
+		args: packageManagerExecArgs(manager, "vitest", [
 			"run",
 			"--coverage",
 			"--coverage.reporter=text-summary",
 			"--coverage.reporter=json-summary",
 			"--coverage.reporter=lcov",
 			"--coverage.reportsDirectory=.coverage"
-		],
+		]),
 		mode: "vitest run --coverage (reporters forcés)"
 	};
 	return {
-		cmd: "npm",
+		cmd: manager,
 		args: ["run", "coverage"],
-		mode: "npm run coverage (suite complète)"
+		mode: `${packageManagerCommandLines(manager).run("coverage")} (suite complète)`
 	};
 }
 /**
 * Lance les tests d'un module et renvoie un résumé (pass/fail/durée + tail).
 *
-* - 1 fichier (module vitest) → `npx vitest run <file>` (rapide, pass/fail).
-* - sinon → `npm run coverage` (suite complète + refresh coverage ; marche
-*   pour vitest comme pour monocart/core).
+* - 1 fichier (module vitest) → `vitest run <file>` (rapide, pass/fail).
+* - sinon → le script `coverage` (suite complète + refresh coverage ; marche
+*   pour vitest comme pour le cœur).
+* Les deux par le gestionnaire du projet (cf {@link testRunCommand}).
 *
 * ⚠️ EXÉCUTE un process — appelé UNIQUEMENT derrière le garde dev-only de
-* l'endpoint (cf KernelAdminApi). spawn sans shell + args en tableau (pas
-* d'injection shell). `file` validé en amont (suffixe .test.ts, pas de `..`).
+* l'endpoint (cf KernelAdminApi). `portableSpawn` : jamais de `shell`, args
+* en tableau (pas d'injection), et le `.cmd` du gestionnaire se lance sous
+* Windows — un `spawn("npx")` nu y rendait `ENOENT`. `file` validé en amont
+* (suffixe .test.ts, pas de `..`).
 */
 function runModuleTests(modulePath, file) {
 	const { cmd, args, mode } = testRunCommand(modulePath, file);
@@ -705,9 +713,11 @@ function runModuleTests(modulePath, file) {
 		};
 		let child;
 		try {
-			child = spawn(cmd, args, {
+			const run = portableSpawn(cmd, args);
+			child = spawn(run.file, run.args, {
 				cwd: modulePath,
-				env: process.env
+				env: process.env,
+				windowsVerbatimArguments: run.windowsVerbatimArguments
 			});
 		} catch (e) {
 			return resolve({
@@ -720,16 +730,16 @@ function runModuleTests(modulePath, file) {
 				mode
 			});
 		}
-		child.stdout?.on("data", cap);
-		child.stderr?.on("data", cap);
+		child.stdout.on("data", cap);
+		child.stderr.on("data", cap);
 		const timer = setTimeout(() => child.kill("SIGKILL"), 18e4);
 		let settled = false;
 		const settle = (result) => {
 			if (settled) return;
 			settled = true;
 			clearTimeout(timer);
-			child.stdout?.off("data", cap);
-			child.stderr?.off("data", cap);
+			child.stdout.off("data", cap);
+			child.stderr.off("data", cap);
 			resolve(result);
 		};
 		child.on("error", (e) => {
@@ -894,7 +904,7 @@ async function readCoverage(modulePath) {
 		} catch {}
 	}
 	if (!report) return { available: false };
-	report.files.sort((a, b) => a.file.localeCompare(b.file));
+	report.files?.sort((a, b) => a.file.localeCompare(b.file));
 	try {
 		report.generated = usedFile ? (await stat(usedFile)).mtime.toISOString() : null;
 	} catch {

package/dist/nodefony/src/scopeCatalog.js

@@ -33,7 +33,7 @@ function collectDeclaredApiScopes() {
 	}
 	return [...byApi.keys()].sort().map((api) => ({
 		api,
-		scopes: [...byApi.get(api)].sort()
+		scopes: [...byApi.get(api) ?? []].sort()
 	}));
 }
 //#endregion

package/dist/nodefony/src/singletonGuard.js

@@ -0,0 +1,76 @@
+//#region nodefony/src/singletonGuard.ts
+/**
+* Filets d'un contrôleur **singleton** — le défaut : UNE instance par classe,
+* partagée par toutes les requêtes, concurrentes comprises.
+*
+* Un singleton ne peut porter aucun état de requête sur `this` : la valeur
+* écrite par une requête serait lue par la suivante — une fuite de données
+* entre utilisateurs, sans la moindre erreur. Deux filets la rendent visible :
+*
+* - les accesseurs d'état par requête de `Controller` (`query`, `request`,
+*   `context`…) refusent l'écriture sur un singleton, dans tous les
+*   environnements (coût nul : ils ne sont jamais écrits sur le chemin chaud) ;
+* - en développement seulement, {@link guardSingletonState} fait lever toute
+*   écriture sur un champ de l'instance, une fois sa construction et son
+*   `initialize()` terminés.
+*
+* @module
+*/
+/**
+* `true` si l'environnement du kernel est celui du développement.
+*
+* Une seule définition pour tout le paquet : la sonde CSP de `Controller` et le
+* filet des singletons s'allument sur le même critère.
+*
+* @param environment - `kernel.environment`, tel quel.
+* @returns `true` en développement (`"development"` ou son alias `"dev"`).
+*/
+function isDevelopment(environment) {
+	return environment === "development" || environment === "dev";
+}
+/**
+* Message d'une écriture refusée sur un contrôleur singleton : il nomme la
+* classe, le membre, la raison du refus et les deux remèdes.
+*
+* @param controller - nom de la classe du contrôleur.
+* @param member - membre écrit (`count`, `query`…).
+* @returns le message, en une phrase par idée.
+*/
+function singletonWriteMessage(controller, member) {
+	return `Contrôleur « ${controller} » : écriture de « this.${member} » refusée. Ce contrôleur est un singleton (le défaut) : une seule instance sert toutes les requêtes, concurrentes comprises, et cette valeur fuirait de l'une à l'autre. Remèdes : déclarer la classe @Scope("request") — une instance par requête, une par connexion en WebSocket — ou porter cet état par la requête : un argument décoré (@Param, @Query, @Body…), un service de portée request, ou le contexte.`;
+}
+/**
+* En développement, fait lever toute écriture sur un champ d'un contrôleur
+* singleton, avec un message qui nomme le contrôleur, le champ et le remède.
+*
+* Chaque propriété PROPRE inscriptible devient un accesseur : la lecture rend
+* la valeur posée à la construction ou dans `initialize()`, l'écriture lève.
+* L'instance est ensuite rendue non extensible, pour qu'un champ non déclaré
+* ne puisse pas être ajouté en cours de requête.
+*
+* Ce que le filet n'attrape PAS, et que seule la relecture garde : les champs
+* `#privés` (ce ne sont pas des propriétés), et les mutations internes d'un
+* objet tenu par un champ (`this.cache.set(…)`, `this.list.push(…)`).
+*
+* @param controller - l'instance, construite et initialisée.
+* @param name - nom de sa classe, pour le message.
+*/
+function guardSingletonState(controller, name) {
+	for (const key of Reflect.ownKeys(controller)) {
+		const descriptor = Object.getOwnPropertyDescriptor(controller, key);
+		if (descriptor?.writable !== true) continue;
+		const value = descriptor.value;
+		const member = String(key);
+		Object.defineProperty(controller, key, {
+			configurable: false,
+			enumerable: descriptor.enumerable ?? false,
+			get: () => value,
+			set: () => {
+				throw new TypeError(singletonWriteMessage(name, member));
+			}
+		});
+	}
+	Object.preventExtensions(controller);
+}
+//#endregion
+export { guardSingletonState, isDevelopment, singletonWriteMessage };

package/dist/types/nodefony/controller/ApiKeyController.d.ts

@@ -16,7 +16,8 @@ import Controller from "../src/Controller.js";
  * zone data plane `^/nodefony/[^/]+/api(/|$)` → **session BFF requise**. Le porteur
  * est TOUJOURS l'utilisateur courant (`authFlow.me`), jamais un paramètre — on ne
  * crée/révoque jamais une clé pour autrui. Montés seulement si le service `apiKeys`
- * existe (security chargé + clés activées) → 404, zéro surface, sinon.
+ * existe (security chargé) — sans security, 404 et zéro surface ; clés
+ * désactivées, les routes répondent 503.
  *
  * Erreurs mappées par DUCK-TYPING sur `code` (400/409/503) — framework ne peut pas
  * importer les classes d'erreur de security.

package/dist/types/nodefony/controller/BenchController.d.ts

@@ -26,7 +26,7 @@ import Controller from "../src/Controller.js";
 declare class BenchController extends Controller {
     constructor(context: ContextType);
     /** Rend le corps figé. Aucune lecture de kernel, aucun I/O, aucune allocation. */
-    index(): Promise<import("@nodefony/http").Http2Response | import("@nodefony/http").HttpResponse | import("@nodefony/http").WebsocketResponse>;
+    index(): import("nodefony").MaybePromise<import("@nodefony/http").Http2Response | import("@nodefony/http").HttpResponse | import("@nodefony/http").WebsocketResponse>;
     /**
      * Dump de la sonde perf in-situ du http-kernel (`NF_PERF_PROBE=1`) : µs
      * moyens par requête des postes enterScope / new HttpContext / leaveScope.
@@ -35,7 +35,7 @@ declare class BenchController extends Controller {
      * pas. `?reset=1` remet les compteurs à zéro (à faire après le warmup, pour
      * ne pas diluer la mesure avec le code froid).
      */
-    probe(): Promise<import("@nodefony/http").Http2Response | import("@nodefony/http").HttpResponse | import("@nodefony/http").WebsocketResponse>;
+    probe(): import("nodefony").MaybePromise<import("@nodefony/http").Http2Response | import("@nodefony/http").HttpResponse | import("@nodefony/http").WebsocketResponse>;
 }
 /**
  * Monte la route de banc — appelée par le module framework, uniquement si

package/dist/types/nodefony/controller/OAuth2Controller.d.ts

@@ -82,11 +82,11 @@ declare class OAuth2Controller extends Controller {
      * fournisseur déclaré `hidden` n'y figure pas, mais reste autorisable :
      * masquer n'est pas désactiver. Aucun secret n'est exposé.
      */
-    providers(): Promise<import("@nodefony/http").Http2Response | import("@nodefony/http").HttpResponse | import("@nodefony/http").WebsocketResponse>;
+    providers(): import("nodefony").MaybePromise<import("@nodefony/http").Http2Response | import("@nodefony/http").HttpResponse | import("@nodefony/http").WebsocketResponse>;
     /** Démarre le flux : URL d'autorisation + état anti-replay en session, 302. */
-    authorize(provider: string): Promise<void | import("@nodefony/http").HttpResponse | import("@nodefony/http").WebsocketResponse>;
+    authorize(provider: string): Promise<import("@nodefony/http").HttpResponse | import("@nodefony/http").WebsocketResponse | undefined>;
     /** Valide `state`, échange le `code`, ouvre la session BFF (302). */
-    callback(provider: string): Promise<void | import("@nodefony/http").HttpResponse | import("@nodefony/http").WebsocketResponse>;
+    callback(provider: string): Promise<import("@nodefony/http").HttpResponse | import("@nodefony/http").WebsocketResponse | undefined>;
 }
 /**
  * Monte les routes du social login OAuth — appelé par le module framework à

package/dist/types/nodefony/controller/ProtectedResourceMetadataController.d.ts

@@ -89,7 +89,7 @@ declare class ProtectedResourceMetadataController extends Controller {
  */
 export interface IServiceScan {
     keys(): string[];
-    get<T = unknown>(name: string): T | null;
+    get(name: string): unknown;
 }
 /**
  * Rassemble ce que TOUS les services du conteneur déclarent protéger.

package/dist/types/nodefony/controller/SessionAuthController.d.ts

@@ -20,7 +20,8 @@ export interface ISessionAuthFlow {
     login(context: ContextType, identifier: unknown, password: unknown): Promise<ILoginOutcome>;
     completeMfaLogin(context: ContextType, code: unknown): Promise<unknown>;
     logout(context: ContextType): Promise<boolean>;
-    me(context: ContextType): Promise<unknown | null>;
+    /** Identité courante, ou `null` sans session authentifiée. */
+    me(context: ContextType): Promise<unknown>;
 }
 /**
  * Endpoints HTTP du flux de session BFF — adaptateurs MINCES au-dessus du

package/dist/types/nodefony/controller/TokenAuthController.d.ts

@@ -23,8 +23,8 @@ export interface ITokenIssuer {
  *  - `POST /nodefony/security/api/token/refresh` — body `{refresh_token}` → rotation
  *
  * Montés par le module framework UNIQUEMENT si le service `tokenService` existe
- * (module security chargé + JWT activé) — sans lui, les routes n'existent pas
- * (404, zéro surface).
+ * (module security chargé) — sans lui, les routes n'existent pas (404, zéro
+ * surface). JWT désactivé ou store indisponible : les routes répondent 503.
  *
  * Le JWT part en **réponse JSON** (Bearer), JAMAIS en cookie ni en URL (anti
  * fuite / non-révocable). Erreurs mappées par DUCK-TYPING sur `code` (401/429) —

package/dist/types/nodefony/controller/TotpController.d.ts

@@ -16,7 +16,8 @@ import Controller from "../src/Controller.js";
  * plane `^/nodefony/[^/]+/api(/|$)` → **session BFF requise**. Le sujet est
  * TOUJOURS l'utilisateur courant (`authFlow.me`), jamais un paramètre — on n'active
  * /ne désactive jamais le 2FA d'autrui (anti-IDOR). Montés seulement si le service
- * `totp` existe (security chargé + 2FA activé) → 404, zéro surface, sinon.
+ * `totp` existe (security chargé) — sans security, 404 et zéro surface ; 2FA
+ * désactivé, les routes répondent 503.
  */
 declare class TotpController extends Controller {
     #private;

package/dist/types/nodefony/decorators/routerDecorators.d.ts

@@ -80,7 +80,7 @@ export declare const USE_SESSION_METHOD_METADATA = "session:useMethod";
 export type ParamSource = "param" | "body" | "query" | "headers" | "cookie" | "session" | "req" | "res" | "file" | "files" | "user";
 export interface ParamMeta {
     source: ParamSource;
-    key?: string;
+    key?: string | undefined;
     index: number;
     /**
      * P2.9 — `@Body({ stream: true })` : injecte le **flux brut** de la requête
@@ -89,7 +89,7 @@ export interface ParamMeta {
      * pipeline saute le parse busboy/JSON pour la route concernée (cf
      * `routeExpectsBodyStream` + `handleHttp`).
      */
-    stream?: boolean;
+    stream?: boolean | undefined;
 }
 export interface RedirectMeta {
     url: string;
@@ -106,7 +106,7 @@ export interface SecurityClause {
     /** Attributs en OR — un seul accordé suffit pour valider la clause. */
     readonly anyOf: readonly string[];
     /** Nom du paramètre de route passé comme `subject` au voter (optionnel). */
-    readonly subjectParam?: string;
+    readonly subjectParam?: string | undefined;
 }
 /**
  * Exigence d'autorisation **figée** d'une action — calculée UNE fois par route
@@ -258,7 +258,7 @@ declare function Redirect(url: string, statusCode?: number): (target: object, pr
  *   \@Get("/") home() {} // marseille.fr/ → OK ; nodefony.com/ → 403
  * }
  */
-declare function Domain(patterns: string | string[]): (target: any, propertyKey?: string, descriptor?: PropertyDescriptor) => any;
+declare function Domain(patterns: string | string[]): (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
@@ -288,31 +288,37 @@ declare function Domain(patterns: string | string[]): (target: any, propertyKey?
  *   \@Get("/studio/api/stats") stats() {}    // gaté par l'aire data plane
  * }
  */
-declare function BypassFirewall(target: any, propertyKey?: string, descriptor?: PropertyDescriptor): any;
+declare function BypassFirewall(target: object, propertyKey?: string, descriptor?: PropertyDescriptor): any;
 /**
- * Déclare le scope d'instanciation d'un controller (V4.3) — pose le statique
- * `scope` de la classe (hérité de `Controller`, défaut `"request"`). Lu par le
- * constructor de `Controller` (`new.target`) et par le `Resolver` : 0 Reflect.
- *
- * `@Scope("singleton")` : UNE instance partagée par toutes les requêtes
- * (cache kernel-scoped sur le Router, `initialize()` appelé 1× à la création).
- * **Contrat stateless strict** : l'action ne lit/n'écrit AUCUN état par requête
- * sur `this` — tout passe par les arguments décorés (`@Param`/`@Body`…) et les
- * helpers, qui retrouvent la requête courante via l'ALS (V4.1). Un champ muté
- * par requête sur un singleton = data race silencieuse entre deux requêtes
- * concurrentes. Le défaut per-request reste inchangé (0 breaking legacy).
+ * 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.
+ *
+ * `@Scope("request")` : une instance par requête — par CONNEXION en
+ * WebSocket. À déclarer quand le contrôleur injecte un service de portée
+ * `request` à son constructeur (un singleton qui le tente est refusé au
+ * démarrage), prépare chaque requête dans `initialize()`, ou garde un état
+ * sur `this`.
+ *
+ * `@Scope("singleton")` redit le défaut : UNE instance partagée par toutes les
+ * requêtes (cache du Router, `initialize()` appelé une fois, à la création).
+ * **Contrat sans état** : l'action ne lit ni n'écrit aucun état de requête sur
+ * `this` — tout passe par les arguments décorés (`@Param`/`@Body`…) et les
+ * helpers, qui retrouvent la requête courante dans l'ALS. Les accesseurs
+ * d'état refusent l'écriture, et le développement refuse toute écriture sur
+ * un champ.
  *
  * ⚠️ Homonyme : le core `nodefony` exporte aussi `Scope` (le scope DI du
  * `Container`) — celui-ci s'importe depuis `@nodefony/framework`.
  *
  * @example
- * \@Scope("singleton")
- * \@controller("/api/books")
- * class BookController extends ResourceController { ... }
+ * \@Scope("request")
+ * \@controller("/me")
+ * class MeController extends Controller { ... }
  */
-declare function Scope(scope: ControllerScope): <T extends {
+declare function Scope(scope: ControllerScope): (target: {
     scope?: ControllerScope;
-}>(target: T) => void;
+}) => void;
 /** Options déclaratives de `@UseSession` (= forme de l'intent runtime). */
 export type UseSessionOptions = SessionIntent;
 /**
@@ -336,7 +342,7 @@ export type UseSessionOptions = SessionIntent;
  *   \@Get("/me") @UseSession({ readOnly: true }) me() {} // lecture seule → 0 write
  * }
  */
-declare function UseSession(options?: UseSessionOptions): (target: any, propertyKey?: string, descriptor?: PropertyDescriptor) => any;
+declare function UseSession(options?: UseSessionOptions): (target: object, propertyKey?: string, descriptor?: PropertyDescriptor) => any;
 /**
  * Résout l'intent de session effectif d'une action — lu par le `Resolver` au
  * match, posé sur `context.sessionIntent`, consommé au point d'activation unique
@@ -364,7 +370,7 @@ declare function resolveSessionIntent(ctor: ControllerConstructor, actionName: s
  */
 declare function IsGranted(attribute: string | readonly string[], options?: {
     subject?: string;
-}): (target: any, propertyKey?: string, descriptor?: PropertyDescriptor) => any;
+}): (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
@@ -373,7 +379,7 @@ declare function IsGranted(attribute: string | readonly string[], options?: {
  * login, une sonde de liveness, une page publique d'un contrôleur par ailleurs
  * protégé.
  */
-declare function Anonymous(): (target: any, propertyKey?: string, descriptor?: PropertyDescriptor) => any;
+declare function Anonymous(): (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
@@ -395,7 +401,7 @@ declare function Anonymous(): (target: any, propertyKey?: string, descriptor?: P
  * metadata est **dédiée** (≠ `@IsGranted`) pour que la découverte au boot puisse
  * lister les scopes déclarés par route sans les confondre avec les rôles.
  */
-declare function RequireScope(scope: string | readonly string[]): (target: any, propertyKey?: string, descriptor?: PropertyDescriptor) => any;
+declare function RequireScope(scope: string | readonly string[]): (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
@@ -407,7 +413,7 @@ declare function RequireScope(scope: string | readonly string[]): (target: any,
  * dans le CSP de la réponse est fait par le firewall, hors hot-path, UNIQUEMENT
  * sur les routes décorées. Calque `@IsGranted` (0 import `@nodefony/security`).
  */
-declare function Csp(directives: CspDirectives): (target: any, propertyKey?: string, descriptor?: PropertyDescriptor) => any;
+declare function Csp(directives: CspDirectives): (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
@@ -416,7 +422,7 @@ declare function Csp(directives: CspDirectives): (target: any, propertyKey?: str
  * 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).
  */
-declare const CsrfProtect: () => (target: any, propertyKey?: string, descriptor?: PropertyDescriptor) => any;
+declare const CsrfProtect: () => (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
@@ -424,7 +430,7 @@ declare const CsrfProtect: () => (target: any, propertyKey?: string, descriptor?
  * 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).
  */
-declare const CsrfExempt: () => (target: any, propertyKey?: string, descriptor?: PropertyDescriptor) => any;
+declare const CsrfExempt: () => (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
@@ -452,7 +458,7 @@ declare const CsrfExempt: () => (target: any, propertyKey?: string, descriptor?:
  */
 declare function Idempotent(options?: {
     required?: boolean;
-}): (target: any, propertyKey?: string, descriptor?: PropertyDescriptor) => any;
+}): (target: object, propertyKey?: string, descriptor?: PropertyDescriptor) => any;
 declare const Param: (key?: string) => (target: object, propertyKey: string, parameterIndex: number) => void;
 declare const Query: (key?: string) => (target: object, propertyKey: string, parameterIndex: number) => void;
 /**
@@ -520,23 +526,23 @@ export interface IParamArgContext {
      * transport — pont WS-RPC `api.request` (`Resolver.queryOverride`). Prime
      * sur `request.queryGet` pour `@Query` uniquement (`@Req` reste le brut).
      */
-    queryOverride?: Record<string, unknown>;
+    queryOverride?: Record<string, unknown> | undefined;
     request?: {
-        queryGet?: Record<string, unknown>;
-        queryPost?: Record<string, unknown>;
-        queryFile?: unknown[];
-        headers?: Record<string, unknown>;
+        queryGet?: Record<string, unknown> | undefined;
+        queryPost?: Record<string, unknown> | undefined;
+        queryFile?: unknown[] | undefined;
+        headers?: Record<string, unknown> | undefined;
         /**
          * P2.9 — `IncomingMessage` brut (un `Readable`) sous-jacent au wrapper
          * `HttpRequest`. Injecté tel quel par `@Body({ stream: true })` (le pipeline
          * n'a pas consommé/parsé ce flux). `undefined` pour les contextes WS.
          */
-        request?: NodeJS.ReadableStream;
-    } | null;
+        request?: NodeJS.ReadableStream | undefined;
+    } | null | undefined;
     response?: unknown;
     session?: {
         get(key: string): unknown;
-    } | null;
+    } | null | undefined;
     getRequestCookies(name?: string): unknown;
 }
 /**
@@ -570,9 +576,9 @@ declare function buildParamArgs(metas: ParamMeta[], ctx: IParamArgContext): unkn
 declare function routeExpectsBodyStream(routeDef: {
     controller?: {
         prototype: object;
-    } | null;
-    classMethod?: string;
-    bodyStream?: boolean;
+    } | null | undefined;
+    classMethod?: string | undefined;
+    bodyStream?: boolean | undefined;
 }): boolean;
 /**
  * Snapshot des métadonnées d'action d'une route (`@HttpCode`/`@Header`/
@@ -639,8 +645,8 @@ declare function computeActionMeta(ctor?: {
 declare function resolveActionMeta(routeDef: {
     controller?: {
         prototype: object;
-    } | null;
-    classMethod?: string;
-    actionMeta?: RouteActionMeta;
+    } | null | undefined;
+    classMethod?: string | undefined;
+    actionMeta?: RouteActionMeta | undefined;
 }): RouteActionMeta;
 export { route, controller, controllers, Get, Post, Put, Delete, Patch, Options, Head, All, Domain, BypassFirewall, IsGranted, RequireScope, Anonymous, Csp, CsrfProtect, CsrfExempt, Idempotent, CurrentUser, Scope, UseSession, resolveSessionIntent, HttpCode, Header, Redirect, Param, Body, Query, Headers, Cookie, Session, Req, Res, UploadedFile, UploadedFiles, resolveParamArg, buildParamArgs, routeExpectsBodyStream, computeActionMeta, resolveActionMeta, extractActionScopes, };

package/dist/types/nodefony/interfaces/IController.d.ts

@@ -1,5 +1,5 @@
 import type { contextRequest, HTTPMethod, HttpResponse, Http2Response, WebsocketResponse, Session, ContextType } from "@nodefony/http";
-import type { Module, FileClass } from "nodefony";
+import type { Module, FileClass, MaybePromise } from "nodefony";
 import type { OutgoingHttpHeaders } from "node:http";
 import type { ReadStream } from "node:fs";
 import type { IRoute } from "./IRoute.js";
@@ -7,21 +7,23 @@ export interface IController {
     readonly route?: IRoute | null;
     request: contextRequest;
     response: HttpResponse | Http2Response | WebsocketResponse | null;
-    context?: ContextType;
+    context?: ContextType | undefined;
     session?: Session | null;
-    method?: HTTPMethod;
+    method?: HTTPMethod | undefined;
     queryGet: Record<string, unknown>;
     query: Record<string, unknown>;
     queryFile: unknown[];
     queryPost: Record<string, unknown>;
-    module?: Module;
+    module?: Module | undefined;
     setContext(context: ContextType): void;
     setContextJson(encoding?: BufferEncoding): unknown;
     setContextHtml(encoding?: BufferEncoding): unknown;
-    render(data: unknown, encoding?: BufferEncoding, status?: string | number, headers?: Record<string, string | number>): Promise<unknown>;
-    renderResponse(data: unknown, encoding?: BufferEncoding, status?: string | number, headers?: OutgoingHttpHeaders): Promise<HttpResponse | Http2Response | WebsocketResponse>;
+    /** Rend une donnée — la réponse, ou sa promesse quand l'envoi attend. */
+    render(data: unknown, encoding?: BufferEncoding, status?: string | number, headers?: Record<string, string | number>): MaybePromise<unknown>;
+    /** Envoie une donnée sérialisée — la réponse, ou sa promesse quand l'envoi attend. */
+    renderResponse(data: unknown, encoding?: BufferEncoding, status?: string | number, headers?: OutgoingHttpHeaders): MaybePromise<HttpResponse | Http2Response | WebsocketResponse>;
     renderView(path: string, param?: Record<string, unknown>, status?: string | number, headers?: Record<string, string | number>): Promise<HttpResponse | Http2Response | WebsocketResponse>;
-    renderJson(obj: unknown, status?: string | number, headers?: OutgoingHttpHeaders): Promise<unknown>;
+    renderJson(obj: unknown, status?: string | number, headers?: OutgoingHttpHeaders): MaybePromise<unknown>;
     setRoute(route: IRoute): IRoute;
     getSession(): Session | undefined | null;
     redirect(url: string, status?: string | number, headers?: Record<string, string | number>): void;