@nodefony/framework 10.0.0-alpha.1

package/dist/nodefony/src/Resolver.js

@@ -0,0 +1,416 @@
+import { buildParamArgs, computeActionMeta, resolveActionMeta, resolveSessionIntent } from "../decorators/routerDecorators.js";
+import { computeFingerprint, evaluateIdempotency, isMutationMethod, resolveIdempotencyKey, resolveIdentity } from "./idempotency.js";
+import { RequestContext, isArray, isPlainObject, isPromise, nodefonyError, typeOf } from "nodefony";
+import { Http2Response, HttpResponse, WebsocketResponse } from "@nodefony/http";
+//#region nodefony/src/Resolver.ts
+/**
+* Résout une route vers son couple controller/action et exécute l'action —
+* UN Resolver est alloué par requête HTTP (et par connexion WS, réutilisé
+* par message). **POJO volontaire** (V3.1) : n'étend PAS `Service` — le
+* plumbing Service (Map de listeners trackés, spread d'options, lookups
+* kernel/syslog) coûtait par requête sans aucun consommateur (jamais écouté,
+* jamais loggé, jamais dans le container). Le DI per-request passe par
+* `context.container` (le cache `"controller"` y survit au Resolver : un
+* forward ou un 2ᵉ Resolver WS sur la MÊME connexion retrouve l'instance).
+*/
+var Resolver = class {
+	injector;
+	controller = null;
+	actionName;
+	action;
+	context;
+	route = null;
+	resolve = false;
+	variables = [];
+	exception;
+	acceptedProtocol = null;
+	bypassFirewall = false;
+	/**
+	* Query d'une invocation **par message** (pont WS-RPC `api.request`) — pendant
+	* de `cleanPathOverride` pour le `?…` du path invoqué. Le contexte WS étant
+	* PARTAGÉ par la connexion (sa `queryGet` = celle du handshake), la query
+	* per-invocation vit ici (le Resolver est per-invocation → zéro bleed entre
+	* requêtes concurrentes d'une même socket). `null` (hot path HTTP) = ignoré.
+	* Consommé par `@Query` (`_buildParamArgs`) et copié sur le controller
+	* per-request (`executeAction`).
+	*/
+	queryOverride = null;
+	/**
+	* Méthode HTTP **logique** d'une invocation par le pont WS-RPC `api.request`
+	* quand c'est une MUTATION (POST/PUT/PATCH/DELETE). Posée par
+	* `Router.resolve(ctx, cleanPath, methodOverride)` → consommée par `match()`
+	* pour désambiguïser, sur le transport WEBSOCKET unique, la route logique
+	* visée (cf `Route.matchRequirements`). `null` (GET/HTTP) = match historique
+	* sur `context.method`.
+	*/
+	methodOverride = null;
+	constructor(context) {
+		this.context = context;
+		this.injector = context.container?.get("injector") ?? null;
+	}
+	match(route, context, cleanPath) {
+		const match = route.match(context, cleanPath, this.methodOverride ?? void 0);
+		if (match) {
+			this.variables = match;
+			this.route = route;
+			this.controller = route.controller;
+			this.actionName = route.classMethod;
+			this.resolve = true;
+			this.bypassFirewall = this.route.bypassFirewall;
+			if (route.requirements.protocol) this.acceptedProtocol = route.requirements.protocol.toLowerCase();
+			const actionMeta = resolveActionMeta(route);
+			this.context.sessionIntent = actionMeta.sessionIntent;
+			if (actionMeta.cspDirectives !== null) this.context.cspDirectives = actionMeta.cspDirectives;
+			if (actionMeta.csrfProtect) this.context.csrfProtect = true;
+			if (actionMeta.csrfExempt) this.context.csrfExempt = true;
+		}
+		return match;
+	}
+	/**
+	* Snapshot per-requête des variables de route matchées (`{name}` → valeur,
+	* + wildcard `*` éventuel). Construit depuis les valeurs de CETTE requête
+	* (`this.variables`, posées par `match()`) zippées avec les noms de
+	* `route.variables`. Remplace l'ancien `Route.variablesMap` qui vivait sur
+	* l'instance `Route` partagée (statique) → écrasé par toute requête/connexion
+	* concurrente sur la même route (bleed inter-requêtes). Lu par
+	* `Context.setMetaData()` pour exposer `msg.nodefony.route.variablesMap`.
+	*/
+	getMatchedParams() {
+		const names = this.route?.variables ?? [];
+		const params = {};
+		for (let i = 0; i < names.length; i++) params[names[i]] = this.variables[i];
+		const wildcard = this.variables["*"];
+		if (wildcard !== void 0) params["*"] = wildcard;
+		return params;
+	}
+	parsePathernController(name) {
+		let module;
+		let tab = [];
+		if (typeof name !== "string") throw new Error(`Invalid name parameter: expected a string`);
+		tab = name.split(":");
+		if (tab.length !== 3) throw new Error(`Invalid name format: expected "module:controller:action"`);
+		module = this.context.kernel?.getModule(tab[0]);
+		if (!module) throw new Error(`Module not found: ${tab[0]}`);
+		this.controller = module.getController(tab[1]);
+		if (!this.controller) throw new Error(`Controller not found in module: ${tab[1]}`);
+		this.action = this.getAction(tab[2]);
+		if (!this.action) throw new Error(`Action not found in controller ${tab[1]}: ${tab[2]}`);
+		this.actionName = tab[2];
+		this.resolve = true;
+		if (this.controller) this.context.sessionIntent = resolveSessionIntent(this.controller, this.actionName);
+	}
+	getAction(name) {
+		if (!this.controller) throw new Error(`Controller not set`);
+		const methodNames = Object.getOwnPropertyNames(this.controller.prototype);
+		for (const methodName of methodNames) if (typeof this.controller.prototype[methodName] === "function" && methodName === name) return this.controller.prototype[methodName];
+		return null;
+	}
+	async newController(context) {
+		if (!this.controller) throw new Error(`Route Controller not found`);
+		if (this.controller.scope === "singleton") {
+			const router = this.context.router;
+			const controller = router ? await router.getSingletonController(this.controller, () => this._createController(context)) : await this._createController(context);
+			this.context.container?.set("controller", controller);
+			return controller;
+		}
+		const controller = await this._createController(context);
+		this.context.container?.set("controller", controller);
+		return controller;
+	}
+	/**
+	* Instancie la classe controller résolue (DI) + hooks de création : `module`
+	* (constante de classe, shadow d'instance posé 1× ici — plus de write par
+	* requête dans `executeAction`) puis `initialize()`. Pour un singleton,
+	* `initialize()` n'est donc appelé qu'UNE fois, à la création (sémantique
+	* boot) — le per-request y lit l'ALS s'il a besoin de la requête.
+	*/
+	async _createController(context) {
+		const ctx = context || this.context;
+		ctx.phaseStart("initialize");
+		try {
+			const controller = this.injector?.instantiate(this.controller, ctx);
+			if (!controller) throw new Error(`Route Controller not found`);
+			if (this.controller?.prototype.module) controller.module = this.controller.prototype.module;
+			if ("initialize" in controller && typeof controller.initialize === "function") await controller.initialize();
+			return controller;
+		} finally {
+			ctx.phaseEnd("initialize");
+		}
+	}
+	/**
+	* Exécute l'action résolue et retourne sa **valeur brute**, SANS la rendre sur
+	* le transport (pas de `returnController`/`send`). Découple « exécuter → valeur »
+	* de « rendre la valeur » : un appelant multi-transport (WS-RPC `invoke`, futur
+	* GraphQL) réutilise la MÊME action puis emballe le résultat à sa façon
+	* (`{ id, result }`, champ GraphQL…). Le pipeline HTTP/WS normal passe par
+	* {@link callController} (= `executeAction` + rendu).
+	*
+	* @param data - args supplémentaires (message WS brut legacy) concaténés aux variables de route.
+	* @param reload - force `newController()` (le container peut déjà porter un AUTRE controller).
+	* @returns la valeur retournée par l'action + son `RedirectMeta` éventuel.
+	*/
+	async executeAction(data, reload = false, metaArg) {
+		const meta = metaArg ?? (this.route ? resolveActionMeta(this.route) : computeActionMeta(this.controller, this.actionName));
+		if (meta.security !== null) await this._enforceSecurity(meta.security);
+		let controller = this.context.container?.get("controller");
+		if (!controller || reload || this.controller && !(controller instanceof this.controller)) controller = await this.newController();
+		if (this.controller?.scope !== "singleton") {
+			controller.setRoute(this.route);
+			if (this.queryOverride !== null) {
+				controller.queryGet = this.queryOverride;
+				controller.query = this.queryOverride;
+			}
+		}
+		const methodKey = this.actionName;
+		let args;
+		if (meta.paramsMeta) args = this._buildParamArgs(meta.paramsMeta);
+		else if (data) args = [...this.variables, ...data];
+		else args = [...this.variables];
+		this._applyResponseMeta(meta);
+		const redirectMeta = meta.redirectMeta ?? void 0;
+		if (typeof controller[methodKey] === "function") return {
+			result: controller[methodKey](...args),
+			redirectMeta
+		};
+		if (this.action) return {
+			result: this.action(...args),
+			redirectMeta
+		};
+		throw new Error(`Route Action not found`);
+	}
+	async callController(data, reload = false) {
+		const meta = this.route ? resolveActionMeta(this.route) : computeActionMeta(this.controller, this.actionName);
+		const { result, redirectMeta } = meta.idempotent !== null ? await this._callWithIdempotency(meta, data, reload) : await this.executeAction(data, reload, meta);
+		return this._handleRedirect(result, redirectMeta);
+	}
+	/**
+	* Exécute l'action AVEC la porte d'idempotence mais SANS rendu
+	* (`returnController`) — le chemin du **pont `api.request`** (WS) : la valeur
+	* nue est enveloppée `{id, result}` par le peer, jamais rendue sur le
+	* transport. La méthode HTTP logique d'une mutation du pont voyage dans
+	* {@link methodOverride} ; sans porte ici, un rejeu `socket.mutate` (socket
+	* qui reconnecte) ré-exécuterait la mutation (doublon — vécu au banc duplex).
+	*
+	* @returns `{ result }` — la valeur retournée par l'action (ou la réponse
+	*   mémorisée rejouée pour une clé d'idempotence déjà servie).
+	*/
+	async executeActionGuarded(data, reload = false) {
+		const meta = this.route ? resolveActionMeta(this.route) : computeActionMeta(this.controller, this.actionName);
+		const { result } = meta.idempotent !== null ? await this._callWithIdempotency(meta, data, reload) : await this.executeAction(data, reload, meta);
+		return { result };
+	}
+	/**
+	* Applique la porte d'idempotence d'une action `@Idempotent` (mutations), via le
+	* helper partagé `idempotency.ts` (la MÊME sémantique que le data plane admin) et
+	* le service `idempotencyStore`. Conforme `draft-ietf-httpapi-idempotency-key-header`.
+	*
+	* Cycle (anti double-effet) : `evaluateIdempotency` rend un verdict neutre →
+	*  - `reject` → `nodefonyError` (400 clé requise / 409 concurrent / 422 mismatch) ;
+	*  - `replay` → réponse mémorisée rejouée SANS ré-exécuter l'action ;
+	*  - `execute` → exécution directe (mode souple sans clé / store absent) ;
+	*  - `guarded` → exécuter, puis `complete()` (succès, réponse rejouable) ou
+	*    `abort()` (échec/403 — la clé reste réessayable, un échec ne se mémorise pas).
+	*
+	* No-op sur les méthodes sûres (GET…). La réponse mémorisée est
+	* le **résultat retourné** par l'action (`return data`) + son statut : une action
+	* qui pilote la response manuellement (`this.render`/stream) n'est pas rejouée
+	* fidèlement (le double-effet reste évité, mais le corps rejoué est vide).
+	*
+	* Retourne la forme BRUTE `{ result, redirectMeta }` (comme `executeAction`) :
+	* le rendu appartient à l'appelant — `callController` rend (`_handleRedirect`),
+	* le pont (`executeActionGuarded`) enveloppe la valeur nue.
+	*/
+	async _callWithIdempotency(meta, data, reload = false) {
+		const context = this.context;
+		if (!isMutationMethod(this.methodOverride ?? context.method)) return this.executeAction(data, reload, meta);
+		const als = RequestContext.get();
+		const httpReq = context.request;
+		const names = this.route?.variables ?? [];
+		const params = {};
+		for (let i = 0; i < names.length; i++) params[names[i]] = this.variables[i];
+		const body = als?.body !== void 0 ? als.body : httpReq?.queryPost ?? null;
+		const store = context.container?.get("idempotencyStore");
+		const verdict = await evaluateIdempotency({
+			store,
+			identity: resolveIdentity(als?.user),
+			clientKey: resolveIdempotencyKey(als?.idempotencyKey, httpReq?.headers?.["idempotency-key"]),
+			fingerprint: computeFingerprint([
+				this.route?.name ?? this.actionName,
+				params,
+				body
+			]),
+			isWs: Boolean(context.type?.startsWith("websocket")),
+			required: meta.idempotent?.required ?? true
+		});
+		if (verdict.kind === "reject") throw new nodefonyError(verdict.message, verdict.status);
+		if (verdict.kind === "replay") {
+			const { status, headers, body: memo } = verdict.response;
+			const response = context.response;
+			response?.setStatusCode(status);
+			if (headers) for (const k in headers) response?.setHeader(k, headers[k]);
+			return {
+				result: memo,
+				redirectMeta: void 0
+			};
+		}
+		if (verdict.kind === "execute") return this.executeAction(data, reload, meta);
+		try {
+			const { result, redirectMeta } = await this.executeAction(data, reload, meta);
+			const resolved = await result;
+			const status = context.response?.statusCode ?? 200;
+			try {
+				await store?.complete(verdict.key, {
+					status,
+					body: resolved
+				});
+			} catch {
+				try {
+					context.log(`@Idempotent ${this.route?.name ?? this.actionName}: réponse non mémorisable (corps non sérialisable — retourne le payload brut, pas renderJson) ; dédup conservée avec un corps de rejeu vide`, "WARNING");
+				} catch {}
+				await store?.complete(verdict.key, {
+					status,
+					body: null
+				});
+			}
+			return {
+				result: resolved,
+				redirectMeta
+			};
+		} catch (e) {
+			await store?.abort(verdict.key);
+			throw e;
+		}
+	}
+	/**
+	* Évalue l'exigence d'autorisation (`@IsGranted`) d'une action via le service
+	* `authorization` (par nom, 0 import security). Clauses en **AND**, attributs
+	* d'une clause en **OR**. Refus (ou moteur/identité absents) → 403 (Zero Trust,
+	* fail-closed). Cold path : n'est appelé que sur une route gardée.
+	*
+	* @throws nodefonyError 403 si l'accès est refusé.
+	*/
+	async _enforceSecurity(req) {
+		const authz = this.context.container?.get("authorization");
+		const token = RequestContext.get()?.token;
+		if (!authz || token === void 0) throw new nodefonyError("Access denied", 403);
+		const clauses = req.clauses;
+		for (let i = 0; i < clauses.length; i++) {
+			const clause = clauses[i];
+			const subject = clause.subjectParam !== void 0 ? this._resolveSubject(clause.subjectParam) : void 0;
+			let ok = false;
+			const anyOf = clause.anyOf;
+			for (let j = 0; j < anyOf.length; j++) if (await authz.decide(token, anyOf[j], subject)) {
+				ok = true;
+				break;
+			}
+			if (!ok) throw new nodefonyError("Access denied", 403);
+		}
+	}
+	/**
+	* Résout un paramètre de route NOMMÉ (`@IsGranted(..., { subject: "id" })`) vers
+	* sa valeur, depuis `route.variables` (noms) + `this.variables` (valeurs déjà
+	* parsées). 0 alloc (indexOf + accès tableau).
+	*/
+	_resolveSubject(name) {
+		const idx = (this.route?.variables ?? []).indexOf(name);
+		return idx === -1 ? void 0 : this.variables[idx];
+	}
+	_buildParamArgs(metas) {
+		const httpCtx = this.context;
+		const varNames = this.route?.variables ?? [];
+		const paramsMap = {};
+		for (let i = 0; i < varNames.length; i++) paramsMap[varNames[i]] = this.variables[i];
+		const ctx = this.context;
+		return buildParamArgs(metas, {
+			paramsMap,
+			request: httpCtx?.request,
+			response: httpCtx?.response,
+			session: ctx?.session,
+			queryOverride: this.queryOverride ?? void 0,
+			getRequestCookies: (name) => ctx?.getRequestCookies ? ctx.getRequestCookies(name) : void 0
+		});
+	}
+	/**
+	* Applique `@HttpCode` + `@Header` depuis le snapshot figé de la route
+	* (P5) — plus aucune lecture `Reflect` ni `Object.entries` par requête.
+	* V4.3 : cible la response du CONTEXT (per-request : identique à
+	* `controller.response` ; singleton : la seule source correcte — l'instance
+	* partagée ne porte aucune response).
+	*/
+	_applyResponseMeta(meta) {
+		const response = this.context.response;
+		if (meta.httpCode !== null) response?.setStatusCode(meta.httpCode);
+		const entries = meta.headerEntries;
+		if (entries) for (let i = 0; i < entries.length; i++) response?.setHeader(entries[i][0], entries[i][1]);
+	}
+	async _handleRedirect(actionResult, redirectMeta) {
+		if (!redirectMeta) return this.returnController(actionResult);
+		const resolved = await Promise.resolve(actionResult);
+		if (resolved !== null && resolved !== void 0 && typeof resolved === "object" && "url" in resolved) {
+			const override = resolved;
+			this.context.redirect(override.url, override.statusCode ?? redirectMeta.statusCode);
+			return this.returnController(void 0);
+		}
+		if (resolved === void 0 || resolved === null) {
+			this.context.redirect(redirectMeta.url, redirectMeta.statusCode);
+			return this.returnController(void 0);
+		}
+		return this.returnController(resolved);
+	}
+	async returnController(result) {
+		const type = typeOf(result);
+		switch (true) {
+			case result instanceof Promise:
+			case isPromise(result): return result.then((myresult) => this.returnController(myresult));
+			case type === "string":
+			case result instanceof String: return this.context.send(result);
+			case result instanceof Http2Response:
+			case result instanceof HttpResponse:
+			case result instanceof WebsocketResponse: return result;
+			case type === "buffer":
+				if (this.context.sended) return;
+				return this.context.send(result);
+			case type === "number":
+			case type === "boolean":
+				if (this.context.sended) return;
+				this.context.setContextJson();
+				return this.context.render(result);
+			case type === "array":
+			case type === "object":
+				if (this.context.sended) return;
+				if (isPlainObject(result) || isArray(result)) {
+					this.context.setContextJson();
+					return this.context.render(result);
+				}
+				switch (this.context.type) {
+					case "http":
+					case "http2":
+					case "http3":
+					case "https": this.context.waitAsync = true;
+				}
+				return;
+			default: switch (this.context.type) {
+				case "http":
+				case "http2":
+				case "http3":
+				case "https":
+					if (this.context.sended) return;
+					if (this.context.isRedirect) return this.context.send();
+					if (NO_BODY_STATUS.has(this.getResponseStatus())) return this.context.send();
+					this.context.waitAsync = true;
+			}
+		}
+	}
+	/** Statut courant de la réponse (0 si le transport n'en porte pas). */
+	getResponseStatus() {
+		return this.context.response?.statusCode ?? 0;
+	}
+};
+/** Statuts dont la réponse n'a, par définition, pas de corps (RFC 9110). */
+const NO_BODY_STATUS = /* @__PURE__ */ new Set([
+	204,
+	205,
+	304
+]);
+//#endregion
+export { Resolver as default };

package/dist/nodefony/src/ResourceController.js

@@ -0,0 +1,148 @@
+import Controller from "./Controller.js";
+import { assertPageQuery } from "nodefony";
+import { HttpError } from "@nodefony/http";
+//#region nodefony/src/ResourceController.ts
+/**
+* Controller de ressource **souverain** (V4.2 — POC API souveraine, Phase 2) :
+* la logique métier est écrite UNE fois dans le service de ressource, les
+* actions de la sous-classe ne sont que des portes (REST, WS-RPC `invoke`,
+* GraphQL à venir) qui retournent la **valeur brute** — `returnController`
+* l'auto-JSON en REST, le pont WS l'enveloppe (`{id,result}`), sans réécrire
+* l'action par transport.
+*
+* **Stateless par construction** :
+* - `static scope = "singleton"` : UNE instance partagée (cache Router, V4.3).
+*   L'état per-request n'existe PAS sur `this` — il arrive par les arguments
+*   décorés (`@Param`/`@Body`/`@Query`) et par les helpers hérités qui
+*   retrouvent la requête courante via l'ALS (V4.1).
+* - le seul champ est `resource`, posé 1× au constructor (état de BOOT,
+*   immuable ensuite — sûr en concurrence).
+* - règle absolue pour les sous-classes : **jamais `this.x = …` par requête**
+*   (data race silencieuse). Une sous-classe qui a besoin d'état per-request
+*   sur `this` doit rétrograder : `static scope = "request"`.
+*
+* Sécurité : aucun critère de requête n'est passé AUTOMATIQUEMENT au service
+* (pas de `find(this.queryGet)` implicite) — exposer un filtrage est une
+* décision EXPLICITE de la sous-classe (deny-by-default ; le scope de
+* sécurité des données se branche au niveau service/criteria, P6).
+*
+* @example
+* ```ts
+* \@controller("/api/books")
+* class BookController extends ResourceController<Book> {
+*   constructor(context: Context) {
+*     super("BookController", context, bookService);
+*   }
+*   \@route("books-list", { path: "", requirements: { methods: ["GET", "WEBSOCKET"] } })
+*   list() {
+*     return this.listResource();
+*   }
+*   \@route("books-get", { path: "/{id}", requirements: { methods: ["GET", "WEBSOCKET"] } })
+*   detail(\@Param("id") id: string) {
+*     return this.getResource(id);
+*   }
+* }
+* ```
+*/
+var ResourceController = class extends Controller {
+	/**
+	* Singleton PAR DÉFAUT : la classe est conçue stateless — premier client
+	* du scope V4.3. Une sous-classe peut rétrograder (`static scope =
+	* "request"`) si elle doit porter de l'état per-request sur `this`.
+	*/
+	static scope = "singleton";
+	/**
+	* Service de ressource — état de BOOT (posé 1× ici, jamais réassigné).
+	* `protected` : les actions de la sous-classe y accèdent, les portes non.
+	*/
+	resource = null;
+	constructor(name, context, resource) {
+		super(name, context);
+		if (resource) this.resource = resource;
+	}
+	/**
+	* Service de ressource garanti — 500 explicite si la sous-classe ne l'a
+	* pas fourni (erreur de câblage, pas une erreur client).
+	*/
+	requireResource() {
+		if (!this.resource) throw new HttpError(`${this.name}: no resource service wired (pass it to super(name, context, resource))`, 500, this.context);
+		return this.resource;
+	}
+	/**
+	* Liste la ressource. `criteria` est EXPLICITE (jamais dérivé de la query
+	* string automatiquement — deny-by-default).
+	*/
+	listResource(criteria, options) {
+		return Promise.resolve(this.requireResource().find(criteria, options));
+	}
+	/**
+	* Liste la ressource en rendant une **page** (`{ items, hasNext, total? }`)
+	* plutôt qu'un tableau nu.
+	*
+	* Pourquoi une page et pas un tableau : un tableau ne dit pas s'il en reste.
+	* Le client qui reçoit 25 lignes ne peut pas distinguer « c'est tout » de
+	* « demande la suite » — il redemande indéfiniment, ou s'arrête trop tôt.
+	*
+	* **Mode offset imposé** (`assertPageQuery`) : un client qui enverrait un
+	* `cursor` recevrait sinon la page 1 à chaque appel, en boucle et sans erreur.
+	*
+	* Si le service n'expose pas `findPage`, la page est reconstituée à partir de
+	* `find` en chargeant `limit + 1` lignes (même technique que `paginate`) : le
+	* `hasNext` reste exact, seul `total` manque — et son absence est lisible dans
+	* la réponse, le contrat `IPage` le donnant pour optionnel.
+	*
+	* @param page - bornes, tri et critères de la page demandée.
+	* @returns la page (`items` borné à `limit`).
+	* @throws PaginationModeError si la requête mélange offset et curseur.
+	*/
+	async listPageResource(page) {
+		assertPageQuery(page, "offset");
+		const resource = this.requireResource();
+		if (typeof resource.findPage === "function") return resource.findPage(page);
+		const limit = Math.max(1, Math.floor(page.limit));
+		const offset = Math.max(0, Math.floor(page.offset ?? 0));
+		const rows = await Promise.resolve(resource.find(page.criteria, {
+			limit: limit + 1,
+			offset,
+			order: page.order
+		}));
+		const hasNext = rows.length > limit;
+		return {
+			items: hasNext ? rows.slice(0, limit) : rows,
+			limit,
+			offset,
+			hasNext
+		};
+	}
+	/**
+	* Lit une entité par id — `null` si absente (la porte décide du 404).
+	*
+	* `options.relations` charge les associations dans la foulée. La porte doit
+	* n'y laisser passer que des relations qu'elle a DÉCLARÉES : un `include`
+	* libre laisse le client nommer n'importe quelle association, donc lire des
+	* données qu'aucune route ne lui ouvre.
+	*/
+	getResource(id, options) {
+		return Promise.resolve(this.requireResource().findById(id, options));
+	}
+	/** Crée une entité — 501 si la ressource est read-only. */
+	createResource(data) {
+		const resource = this.requireResource();
+		if (typeof resource.create !== "function") throw new HttpError(`${this.name}: resource is read-only (no create)`, 501, this.context);
+		return Promise.resolve(resource.create(data));
+	}
+	/** Met à jour une entité ciblée par critères — 501 si non supporté. */
+	updateResource(criteria, data) {
+		const resource = this.requireResource();
+		if (typeof resource.updateOne !== "function") throw new HttpError(`${this.name}: resource is read-only (no updateOne)`, 501, this.context);
+		return Promise.resolve(resource.updateOne(criteria, data));
+	}
+	/** Supprime par critères (nombre d'entités touchées) — 501 si non supporté. */
+	removeResource(criteria) {
+		const resource = this.requireResource();
+		if (typeof resource.delete !== "function") throw new HttpError(`${this.name}: resource is read-only (no delete)`, 501, this.context);
+		return Promise.resolve(resource.delete(criteria));
+	}
+};
+//#endregion
+export { ResourceController as default };