@nodefony/orm-core 10.0.0-alpha.9 → 10.0.0-beta.2

package/README.md

@@ -5,8 +5,8 @@ plusieurs ORM dans le même processus — par exemple Drizzle pour SQL et Mongoo
 derrière une API portable, avec une trappe vers le driver natif pour les cas que l'abstraction ne
 couvre pas.
 
-> Bibliothèque pure : ce module n'expose pas de classe `Module` et n'est pas listé dans
-> `@modules()`. Ce sont les **drivers** (`@nodefony/drizzle`, `@nodefony/mongoose`…) qui sont des
+> Bibliothèque pure : ce module n'expose pas de classe `Module` et n'est pas listé dans le
+> manifeste `modules` de `nodefony.config.ts`. Ce sont les **drivers** (`@nodefony/drizzle`, `@nodefony/mongoose`…) qui sont des
 > modules Nodefony et qui s'enregistrent eux-mêmes dans l'`OrmRegistry`.
 
 ## Quel ORM par défaut ?
@@ -36,13 +36,13 @@ d'imposer plusieurs ORM simultanés.
 
 ## Contrats exposés
 
-| Interface        | Rôle                                                                      |
-| ---------------- | ------------------------------------------------------------------------- |
-| `IOrm`           | Instance ORM (connexion logique) : `connect`, `repository`, `transaction` |
-| `IEntity<S,M>`   | Entité enregistrée : nom logique, connecteur cible, schéma, modèle natif  |
-| `IRepository<T>` | CRUD portable : `find`/`findOne`/`create`/`update`/`delete`/`count`       |
-| `ITransaction`   | Unité de travail : `commit`/`rollback`/`savepoint`/`rollbackTo`           |
-| `Criteria<T>`    | Filtre typé par champ et opérateurs riches ; `OrmCriteria` = échappatoire |
+| Interface        | Rôle                                                                                                      |
+| ---------------- | --------------------------------------------------------------------------------------------------------- |
+| `IOrm`           | Instance ORM (connexion logique) : `connect`, `getRepository`, `transaction`                              |
+| `IEntity<S,M>`   | Entité enregistrée : nom logique, connecteur cible, schéma, modèle natif                                  |
+| `IRepository<T>` | CRUD portable (15 verbes) : `find`/`findOne`/`create`/`updateOne`/`updateMany`/`upsert`/`delete`/`count`… |
+| `ITransaction`   | Unité de travail : `commit`/`rollback`/`savepoint`/`rollbackTo`                                           |
+| `Criteria<T>`    | Filtre typé par champ et opérateurs riches ; `OrmCriteria` = échappatoire                                 |
 
 ### Critères riches (opérateurs typés)
 
@@ -70,7 +70,7 @@ fenêtrage. C'est le garde-fou qui empêche l'abstraction de devenir un plafond.
 ## Exemple
 
 ```typescript
-import { OrmRegistry } from "@nodefony/orm-core";
+import { ormRegistry } from "@nodefony/orm-core";
 import type { IRepository } from "@nodefony/orm-core";
 
 interface User {
@@ -78,14 +78,16 @@ interface User {
   email: string;
 }
 
-const orm = OrmRegistry.get("db_principale");
+const orm = ormRegistry.get("db_principale");
 const users: IRepository<User> = orm.getRepository<User>("User");
 
 const created = await users.create({ email: "a@b.c" });
 const found = await users.findOne({ email: "a@b.c" });
 
 await orm.transaction(async (tx) => {
-  await users.update({ id: created.id }, { email: "x@y.z" });
+  await users
+    .withTransaction(tx)
+    .updateOne({ id: created.id }, { email: "x@y.z" });
   // validation automatique si la fonction résout, annulation si elle rejette
 });
 ```

package/dist/nodefony/src/AbstractCrudService.js

@@ -1,3 +1,4 @@
+import { omitUndefined } from "./omitUndefined.js";
 import { paginate } from "./paginate.js";
 import { Service } from "nodefony";
 //#region nodefony/src/AbstractCrudService.ts
@@ -115,12 +116,15 @@ var AbstractCrudService = class extends Service {
 	/**
 	* Crée une entité : `beforeCreate` → persistance → `afterCreate` → `onCreated`.
 	*
+	* Une clé qui vaut `undefined` vaut clé absente : elle est retirée avant la
+	* persistance (cf `omitUndefined`), quel que soit l'adaptateur.
+	*
 	* @param data - champs de l'entité à créer.
 	* @returns l'entité persistée. Émet `onCreated`.
 	*/
 	async create(data) {
 		const prepared = await this.beforeCreate(data);
-		const entity = await this.repository.create(prepared);
+		const entity = await this.repository.create(omitUndefined(prepared));
 		await this.afterCreate(entity);
 		this.fire("onCreated", entity);
 		return entity;
@@ -139,12 +143,12 @@ var AbstractCrudService = class extends Service {
 	* on la remontera dans un service le jour où un usage métier la réclame.
 	*
 	* @param criteria - filtre de sélection (champ inconnu → `UnknownCriteriaField`).
-	* @param data - champs à modifier.
+	* @param data - champs à modifier ; une clé `undefined` n'est pas touchée.
 	* @returns l'entité mise à jour, ou `null` si aucune ne correspond (pas d'event).
 	*/
 	async updateOne(criteria, data) {
 		const prepared = await this.beforeUpdate(criteria, data);
-		const updated = await this.repository.updateOne(criteria, prepared);
+		const updated = await this.repository.updateOne(criteria, omitUndefined(prepared));
 		if (updated !== null) {
 			await this.afterUpdate(updated);
 			this.fire("onUpdated", updated);

package/dist/nodefony/src/ConnectionMonitor.js

@@ -51,7 +51,7 @@ var ConnectionMonitor = class {
 	#stats = null;
 	/** Crée/retourne les stats mutables d'un connecteur (alloue à la demande). */
 	#ensure(name) {
-		if (this.#stats === null) this.#stats = /* @__PURE__ */ new Map();
+		this.#stats ??= /* @__PURE__ */ new Map();
 		let s = this.#stats.get(name);
 		if (s === void 0) {
 			s = {
@@ -80,7 +80,7 @@ var ConnectionMonitor = class {
 	*/
 	recordPing(name, ms) {
 		const s = this.#ensure(name);
-		if (s.latencies === null) s.latencies = [];
+		s.latencies ??= [];
 		s.latencies.push(ms);
 		if (s.latencies.length > MAX_LATENCY_SAMPLES) s.latencies.shift();
 	}
@@ -139,7 +139,7 @@ var ConnectionMonitor = class {
 	}
 	/** Ajoute un événement en tête de la chronologie (allouée au 1ᵉʳ, bornée). */
 	#pushEvent(s, e) {
-		if (s.events === null) s.events = [];
+		s.events ??= [];
 		s.events.unshift(e);
 		if (s.events.length > MAX_EVENTS) s.events.length = MAX_EVENTS;
 	}
@@ -157,7 +157,7 @@ var ConnectionMonitor = class {
 			ts: Date.now()
 		};
 		s.lastError = err;
-		if (s.recentErrors === null) s.recentErrors = [];
+		s.recentErrors ??= [];
 		s.recentErrors.unshift(err);
 		if (s.recentErrors.length > MAX_RECENT_ERRORS) s.recentErrors.length = MAX_RECENT_ERRORS;
 	}
@@ -172,9 +172,10 @@ var ConnectionMonitor = class {
 		if (s === void 0) return EMPTY_CORE;
 		const lat = s.latencies;
 		let latency = EMPTY_LATENCY;
-		if (lat && lat.length) {
-			let min = lat[0];
-			let max = lat[0];
+		const last = lat?.at(-1);
+		if (lat && last !== void 0) {
+			let min = last;
+			let max = last;
 			let sum = 0;
 			for (const v of lat) {
 				if (v < min) min = v;
@@ -182,7 +183,7 @@ var ConnectionMonitor = class {
 				sum += v;
 			}
 			latency = {
-				last: lat[lat.length - 1],
+				last,
 				min: Math.round(min * 100) / 100,
 				avg: Math.round(sum / lat.length * 100) / 100,
 				max: Math.round(max * 100) / 100,

package/dist/nodefony/src/EntityRegistry.js

@@ -20,7 +20,7 @@ var EntityRegistry = class {
 	* @throws si cette entité est déjà enregistrée sur le même connecteur.
 	*/
 	register(entity) {
-		if (this.#entities === null) this.#entities = Object.create(null);
+		this.#entities ??= Object.create(null);
 		const store = this.#entities;
 		let bucket = store[entity.name];
 		if (bucket === void 0) {
@@ -49,7 +49,10 @@ var EntityRegistry = class {
 		}
 		const connectors = Object.keys(bucket);
 		if (connectors.length > 1) throw new Error(`EntityRegistry: entity "${name}" exists on multiple connectors (${connectors.join(", ")}); specify one.`);
-		return bucket[connectors[0]];
+		const only = connectors[0];
+		const entity = only === void 0 ? void 0 : bucket[only];
+		if (entity === void 0) throw new Error(`EntityRegistry: no entity registered under "${name}".`);
+		return entity;
 	}
 	/**
 	* Indique si une entité (optionnellement sur un connecteur précis) est enregistrée.
@@ -72,7 +75,10 @@ var EntityRegistry = class {
 		const out = [];
 		for (const name in this.#entities) {
 			const bucket = this.#entities[name];
-			for (const connector in bucket) out.push(bucket[connector]);
+			for (const connector in bucket) {
+				const entity = bucket[connector];
+				if (entity !== void 0) out.push(entity);
+			}
 		}
 		return out;
 	}

package/dist/nodefony/src/Orm.js

@@ -194,7 +194,7 @@ var Orm = class extends Service {
 		const timer = setInterval(() => {
 			this.#beat();
 		}, this.heartbeatMs);
-		timer.unref?.();
+		timer.unref();
 		this.#heartbeat = timer;
 	}
 	/**
@@ -264,7 +264,7 @@ var Orm = class extends Service {
 				watchdog = setTimeout(() => {
 					rejeter(/* @__PURE__ */ new Error(`aucune réponse en ${this.heartbeatTimeoutMs} ms`));
 				}, this.heartbeatTimeoutMs);
-				watchdog.unref?.();
+				watchdog.unref();
 			})]);
 			this.connectionRestored();
 		} catch (e) {

package/dist/nodefony/src/OrmAdminApi.js

@@ -349,8 +349,8 @@ function jsonSchemaType(nativeType) {
 	const t = nativeType.toLowerCase();
 	if (/\b(serial|bigint|smallint|tinyint|mediumint|int|integer)\b/.test(t)) return { type: "integer" };
 	if (/(real|float|double|decimal|numeric|number)/.test(t)) return { type: "number" };
-	if (/bool/.test(t)) return { type: "boolean" };
-	if (/json/.test(t)) return { type: "object" };
+	if (t.includes("bool")) return { type: "boolean" };
+	if (t.includes("json")) return { type: "object" };
 	if (/(date|time|timestamp)/.test(t)) return {
 		type: "string",
 		format: "date-time"
@@ -422,7 +422,7 @@ function createOrmAdminApi() {
 			path: "entity/{name}",
 			summary: "Une entité (colonnes + relations) — ?connector= si homonymes",
 			handler: (request) => {
-				const name = request.params.name ?? "";
+				const name = request.params.name;
 				const connector = oneParam(request, "connector");
 				try {
 					const found = entityRegistry.list().find((e) => e.name === name && (!connector || e.connector === connector));

package/dist/nodefony/src/OrmRegistry.js

@@ -22,7 +22,7 @@ var OrmRegistry = class {
 	* @throws si un ORM du même nom est déjà enregistré (erreur de configuration).
 	*/
 	register(name, orm) {
-		if (this.#orms === null) this.#orms = /* @__PURE__ */ new Map();
+		this.#orms ??= /* @__PURE__ */ new Map();
 		if (this.#orms.has(name)) throw new Error(`OrmRegistry: an ORM named "${name}" is already registered.`);
 		this.#orms.set(name, orm);
 	}

package/dist/nodefony/src/QueryFlowMonitor.js

@@ -51,7 +51,7 @@ var QueryFlowMonitor = class {
 	}
 	/** Crée/retourne les stats mutables d'un connecteur (alloue à la demande). */
 	#ensure(connector) {
-		if (this.#stats === null) this.#stats = /* @__PURE__ */ new Map();
+		this.#stats ??= /* @__PURE__ */ new Map();
 		let s = this.#stats.get(connector);
 		if (s === void 0) {
 			s = {
@@ -85,7 +85,7 @@ var QueryFlowMonitor = class {
 		s.ewmaMs = s.ewmaMs === null ? durationMs : EWMA_ALPHA * durationMs + .8 * s.ewmaMs;
 		if (durationMs >= this.slowMs) {
 			s.slowTotal += 1;
-			if (s.slow === null) s.slow = [];
+			s.slow ??= [];
 			s.slow.unshift({
 				ts: Date.now(),
 				durationMs,

package/dist/nodefony/src/connectDeadline.js

@@ -57,7 +57,7 @@ async function withConnectDeadline(work, what, ms = CONNECT_TIMEOUT_MS) {
 			timer = setTimeout(() => {
 				reject(/* @__PURE__ */ new Error(`délai dépassé (${ms} ms) en attendant ${what} — le serveur a accepté la connexion sans répondre, ou n'a jamais répondu. Vérifier que le service visé est bien celui qui écoute, et qu'il est en état de servir.`));
 			}, ms);
-			timer.unref?.();
+			timer.unref();
 		})]);
 	} finally {
 		if (timer !== void 0) clearTimeout(timer);

package/dist/nodefony/src/criteria.js

@@ -124,8 +124,8 @@ function escapeLikeTerm(text) {
 function likePatternToRegExp(pattern) {
 	let source = "";
 	for (let i = 0; i < pattern.length; i++) {
-		const c = pattern[i];
-		if (c === "\\" && i + 1 < pattern.length) source += escapeRegExpChar(pattern[++i]);
+		const c = pattern.charAt(i);
+		if (c === "\\" && i + 1 < pattern.length) source += escapeRegExpChar(pattern.charAt(++i));
 		else if (c === "%") source += ".*";
 		else if (c === "_") source += ".";
 		else source += escapeRegExpChar(c);
@@ -169,7 +169,8 @@ function searchCriteria(q, fields) {
 	const term = q?.trim();
 	if (!term || fields.length === 0) return null;
 	const likePattern = `${escapeLikeTerm(term)}%`;
-	if (fields.length === 1) return { [fields[0]]: { $like: likePattern } };
+	const only = fields.length === 1 ? fields[0] : void 0;
+	if (only !== void 0) return { [only]: { $like: likePattern } };
 	return { $or: fields.map((f) => ({ [f]: { $like: likePattern } })) };
 }
 //#endregion

package/dist/nodefony/src/omitUndefined.js

@@ -0,0 +1,30 @@
+//#region nodefony/src/omitUndefined.ts
+/**
+* Retire les clés qui valent `undefined` d'une donnée d'écriture partielle.
+*
+* `undefined` et clé absente veulent dire « ne pas toucher » : Drizzle ignore
+* déjà une valeur `undefined`, Mongoose (≥ 6) la retire d'une mise à jour. La
+* règle est posée ICI, une fois, au seuil de la persistance, au lieu d'être
+* un comportement propre à chaque adaptateur.
+*
+* Rend l'objet reçu TEL QUEL quand aucune clé ne vaut `undefined` — le cas
+* courant d'un corps JSON, qui ne peut pas en porter : aucune allocation.
+*
+* @param data - données d'écriture, clés `undefined` admises
+* @returns les mêmes données, sans aucune clé `undefined`
+*/
+function omitUndefined(data) {
+	const source = data;
+	for (const key of Object.keys(source)) {
+		if (source[key] !== void 0) continue;
+		const out = {};
+		for (const k of Object.keys(source)) {
+			const value = source[k];
+			if (value !== void 0) out[k] = value;
+		}
+		return out;
+	}
+	return data;
+}
+//#endregion
+export { omitUndefined };

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

@@ -53,7 +53,7 @@ export interface IEntity<S = unknown, M = unknown> {
      * **Optionnel** : sert au regroupement dans le graphe canonique / ERD Studio.
      * Non renseigné → entité non rattachée (groupe « — » côté UI).
      */
-    readonly module?: string;
+    readonly module?: string | undefined;
     /**
      * **Classification** de l'entité (ex. domaine fonctionnel `"facturation"`,
      * `"comptabilité"`) — axe de regroupement **distinct** du `module`
@@ -61,7 +61,7 @@ export interface IEntity<S = unknown, M = unknown> {
      * base** (centaines de tables d'un même module) : l'ERD groupe/filtre par
      * `domain`. **Optionnel** ; non renseigné → retombe sur `module`.
      */
-    readonly domain?: string;
+    readonly domain?: string | undefined;
     /** Définition de schéma propre au driver (forme libre). */
     readonly schema: S;
     /** Modèle compilé natif, renseigné après connexion de l'ORM. */
@@ -72,13 +72,13 @@ export interface IEntity<S = unknown, M = unknown> {
      * schema-as-code (Drizzle) les expriment en colonnes → ce flag y est sans effet.
      * **Optionnel**, défaut `false`.
      */
-    readonly timestamps?: boolean;
+    readonly timestamps?: boolean | undefined;
     /** Relations déclarées vers d'autres entités (par nom logique). */
-    readonly relations?: ReadonlyArray<IEntityRelation>;
+    readonly relations?: ReadonlyArray<IEntityRelation> | undefined;
     /**
      * Index composites, appliqués par l'adapter qui les exprime hors schéma
      * (Mongoose `schema.index()`). Les ORM schema-as-code (Drizzle) les déclarent
      * dans leur table → ce champ y est sans effet. **Optionnel**.
      */
-    readonly indexes?: ReadonlyArray<IEntityIndex>;
+    readonly indexes?: ReadonlyArray<IEntityIndex> | undefined;
 }

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

@@ -26,7 +26,7 @@ export interface ISlowQuery {
     /** Connecteur ORM (clé du registre). */
     connector: string;
     /** SQL paramétré et redacté (absent si l'adapter ne sait pas l'extraire). */
-    sql?: string;
+    sql?: string | undefined;
 }
 /**
  * Compteurs de flux d'UN connecteur ORM. Cumuls depuis le boot (le débit/s se

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

@@ -32,7 +32,7 @@ export interface IRelationInfo {
     /** Champ portant la relation côté entité courante. */
     field: string;
     /** Clé étrangère (explicite ou dérivée déterministe). */
-    foreignKey?: string;
+    foreignKey?: string | undefined;
 }
 /** Nœud du graphe : une entité avec ses colonnes et ses relations. */
 export interface IEntityGraphNode {
@@ -66,11 +66,11 @@ export interface IConnectionInfo {
      * `host:port/base` (serveur) ou URI redactée. **Jamais de credential** (mot de
      * passe retiré côté adapter).
      */
-    target?: string;
+    target?: string | undefined;
     /** Version du moteur/base (ex. SQLite `3.45.1`), si l'adapter peut l'obtenir. */
-    version?: string;
+    version?: string | undefined;
     /** Version de la lib ORM elle-même (ex. drizzle-orm `0.44.x`), si connue. */
-    ormVersion?: string;
+    ormVersion?: string | undefined;
 }
 /** Résumé d'un ORM/connecteur enregistré. */
 export interface IOrmSummary {
@@ -93,7 +93,7 @@ export interface IOrmSummary {
     /** Nombre d'entités rattachées à cet ORM. */
     entityCount: number;
     /** Connexion sous-jacente (driver + cible), si l'adapter l'expose. */
-    connection?: IConnectionInfo;
+    connection?: IConnectionInfo | undefined;
 }
 /** Erreur de connexion horodatée (message **redacté** — jamais de credential). */
 export interface IConnectionError {
@@ -112,7 +112,7 @@ export interface IConnectionEvent {
     /** Horodatage epoch ms. */
     ts: number;
     /** Cause de la perte (credential déjà retiré) — absente pour une reprise. */
-    reason?: string;
+    reason?: string | undefined;
 }
 /**
  * Le mécanisme de résilience d'un connecteur, TEL QU'IL TOURNE dans ce process.
@@ -153,11 +153,11 @@ export interface IConnectionHealth {
     /** Base/driver (`sqlite`, `mongodb`…). */
     driver: string;
     /** Cible lisible (chemin relatif / host:port), jamais de credential. */
-    target?: string;
+    target?: string | undefined;
     /** Version moteur. */
-    version?: string;
+    version?: string | undefined;
     /** Version lib ORM. */
-    ormVersion?: string;
+    ormVersion?: string | undefined;
     /** État courant (`isConnected`). */
     connected: boolean;
     /** Connecté depuis (epoch ms), `null` si jamais connecté. */
@@ -177,7 +177,7 @@ export interface IConnectionHealth {
     /** Pertes et reprises récentes (ring borné, plus récentes d'abord). */
     events: IConnectionEvent[];
     /** Mécanisme de détection et de reprise, si l'ORM le décrit. */
-    resilience?: IOrmResilience;
+    resilience?: IOrmResilience | undefined;
     /** Nombre total d'erreurs enregistrées (connexion + ping). */
     errorCount: number;
     /** Dernière erreur, `null` si aucune. */
@@ -195,11 +195,11 @@ export interface IConnectionHealth {
     /** Fenêtre glissante de latence (min/moy/max sur les N derniers pings). */
     latency: ILatencyWindow;
     /** Sonde de stockage (driver), si l'adapter l'expose. */
-    storage?: IOrmStorageProbe;
+    storage?: IOrmStorageProbe | undefined;
     /** Sonde de pool de connexions (driver), si l'adapter l'expose. */
-    pool?: IOrmPoolProbe;
+    pool?: IOrmPoolProbe | undefined;
     /** Métriques driver libres (clé→valeur). */
-    extra?: Record<string, string | number | boolean>;
+    extra?: Record<string, string | number | boolean> | undefined;
 }
 /** Graphe complet du modèle de données — réponse de `/nodefony/orm/api/graph`. */
 export interface IOrmGraph {

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

@@ -32,15 +32,15 @@ export interface ILatencyWindow {
  */
 export interface IOrmStorageProbe {
     /** Taille de la base (octets) — `pages × pageSize` (SQLite). */
-    sizeBytes?: number;
+    sizeBytes?: number | undefined;
     /** Nombre de pages allouées. */
-    pages?: number;
+    pages?: number | undefined;
     /** Taille d'une page (octets). */
-    pageSize?: number;
+    pageSize?: number | undefined;
     /** Mode de journalisation (SQLite : `wal`, `delete`, `memory`…). */
-    journalMode?: string;
+    journalMode?: string | undefined;
     /** Pages libres (fragmentation / espace récupérable au VACUUM). */
-    freePages?: number;
+    freePages?: number | undefined;
 }
 /**
  * Sonde de pool de connexions — pertinente pour les bases serveur (Mongo,
@@ -48,13 +48,13 @@ export interface IOrmStorageProbe {
  */
 export interface IOrmPoolProbe {
     /** Taille max configurée du pool. */
-    size?: number;
+    size?: number | undefined;
     /** Connexions disponibles (idle). */
-    available?: number;
+    available?: number | undefined;
     /** Connexions en cours d'utilisation. */
-    borrowed?: number;
+    borrowed?: number | undefined;
     /** Demandes en attente d'une connexion. */
-    pending?: number;
+    pending?: number | undefined;
 }
 /**
  * Sonde profonde driver-spécifique retournée par {@link IOrm.probe}. Tous les

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

@@ -20,5 +20,5 @@ export type { IPage, IPageQuery } from "nodefony";
  */
 export interface PageQuery<T = unknown> extends IPageQuery {
     /** Filtre typé optionnel appliqué avant la pagination (toutes les lignes si omis). */
-    criteria?: Criteria<T>;
+    criteria?: Criteria<T> | undefined;
 }

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

@@ -23,23 +23,23 @@ export type OrmCriteria = Record<string, unknown>;
  */
 export interface FieldOperators<V> {
     /** Égalité stricte (équivalent à passer la valeur nue). */
-    $eq?: V;
+    $eq?: V | undefined;
     /** Différent de. */
-    $ne?: V;
+    $ne?: V | undefined;
     /** Strictement supérieur à. */
-    $gt?: V;
+    $gt?: V | undefined;
     /** Supérieur ou égal à. */
-    $gte?: V;
+    $gte?: V | undefined;
     /** Strictement inférieur à. */
-    $lt?: V;
+    $lt?: V | undefined;
     /** Inférieur ou égal à. */
-    $lte?: V;
+    $lte?: V | undefined;
     /** Appartient à l'ensemble. */
-    $in?: readonly V[];
+    $in?: readonly V[] | undefined;
     /** N'appartient pas à l'ensemble. */
-    $nin?: readonly V[];
+    $nin?: readonly V[] | undefined;
     /** Motif SQL `LIKE` (`%`/`_`) — pertinent pour les champs texte uniquement. */
-    $like?: string;
+    $like?: string | undefined;
     /**
      * Teste l'**absence de valeur** : `true` → `IS NULL`, `false` → `IS NOT NULL`
      * (Mongo : `$eq`/`$ne null`, qui couvre aussi le champ absent).
@@ -60,7 +60,7 @@ export interface FieldOperators<V> {
      * // les PAT qui ont une expiration
      * repo.find({ expiresAt: { $null: false } });
      */
-    $null?: boolean;
+    $null?: boolean | undefined;
 }
 /**
  * Opérateurs d'**écriture** applicables à un champ dans le `update` d'un
@@ -154,7 +154,7 @@ export type Criteria<T> = {
      * // les clés encore utilisables
      * repo.count({ revokedAt: null, $or: [{ expiresAt: null }, { expiresAt: { $gt: now } }] });
      */
-    $or?: ReadonlyArray<Criteria<T>>;
+    $or?: ReadonlyArray<Criteria<T>> | undefined;
 } & OrmCriteria;
 /**
  * Options de lecture (`find`/`findOne`) portables cross-ORM.
@@ -181,7 +181,7 @@ export interface RepositoryReadOptions {
      * la frontière qui la reçoit (`parsePageQuery` accepte `champ:sens` en casse
      * libre), jamais au repository.
      */
-    order?: Array<[string, "ASC" | "DESC"]>;
+    order?: Array<[string, "ASC" | "DESC"]> | undefined;
 }
 /**
  * Contrat CRUD minimal exposé par un repository, indépendant de l'ORM sous-jacent.

package/dist/types/nodefony/src/AbstractCrudService.d.ts

@@ -1,4 +1,5 @@
 import { Service } from "nodefony";
+import type { PartialInput } from "nodefony";
 import type { IRepository, Criteria, RepositoryReadOptions, IPage, PageQuery } from "../interfaces/index.js";
 import type { ServiceWiring } from "./serviceWiring.js";
 /**
@@ -102,10 +103,13 @@ export declare abstract class AbstractCrudService<T, R extends IRepository<T> =
     /**
      * Crée une entité : `beforeCreate` → persistance → `afterCreate` → `onCreated`.
      *
+     * Une clé qui vaut `undefined` vaut clé absente : elle est retirée avant la
+     * persistance (cf `omitUndefined`), quel que soit l'adaptateur.
+     *
      * @param data - champs de l'entité à créer.
      * @returns l'entité persistée. Émet `onCreated`.
      */
-    create(data: Partial<T>): Promise<T>;
+    create(data: PartialInput<T>): Promise<T>;
     /**
      * Met à jour **au plus une** entité : `beforeUpdate` → persistance atomique
      * → `afterUpdate` → `onUpdated`.
@@ -120,10 +124,10 @@ export declare abstract class AbstractCrudService<T, R extends IRepository<T> =
      * on la remontera dans un service le jour où un usage métier la réclame.
      *
      * @param criteria - filtre de sélection (champ inconnu → `UnknownCriteriaField`).
-     * @param data - champs à modifier.
+     * @param data - champs à modifier ; une clé `undefined` n'est pas touchée.
      * @returns l'entité mise à jour, ou `null` si aucune ne correspond (pas d'event).
      */
-    updateOne(criteria: Criteria<T>, data: Partial<T>): Promise<T | null>;
+    updateOne(criteria: Criteria<T>, data: PartialInput<T>): Promise<T | null>;
     /**
      * Supprime : `beforeDelete` → persistance → `afterDelete` → `onDeleted`.
      *
@@ -138,7 +142,7 @@ export declare abstract class AbstractCrudService<T, R extends IRepository<T> =
      * @param data - données entrantes.
      * @returns les données préparées à persister.
      */
-    protected beforeCreate(data: Partial<T>): Partial<T> | Promise<Partial<T>>;
+    protected beforeCreate(data: PartialInput<T>): PartialInput<T> | Promise<PartialInput<T>>;
     /** Effet de bord après création (ex. provisionner une ressource liée). */
     protected afterCreate(_entity: T): void | Promise<void>;
     /**
@@ -148,7 +152,7 @@ export declare abstract class AbstractCrudService<T, R extends IRepository<T> =
      * @param data - données entrantes.
      * @returns les données préparées à persister.
      */
-    protected beforeUpdate(_criteria: Criteria<T>, data: Partial<T>): Partial<T> | Promise<Partial<T>>;
+    protected beforeUpdate(_criteria: Criteria<T>, data: PartialInput<T>): PartialInput<T> | Promise<PartialInput<T>>;
     /** Effet de bord après mise à jour. */
     protected afterUpdate(_entity: T): void | Promise<void>;
     /** Garde/validation avant suppression (ex. interdire la suppression du dernier admin). */

package/dist/types/nodefony/src/Entity.d.ts

@@ -25,7 +25,7 @@ export declare abstract class Entity<S = unknown, M = unknown> implements IEntit
     /** Modèle compilé natif, renseigné après connexion de l'ORM. */
     model?: M;
     /** Relations déclarées vers d'autres entités (par nom logique). */
-    readonly relations?: ReadonlyArray<IEntityRelation>;
+    readonly relations?: ReadonlyArray<IEntityRelation> | undefined;
     /**
      * Construit la définition de schéma propre au driver.
      *

package/dist/types/nodefony/src/decorators/entityDecorator.d.ts

@@ -21,7 +21,7 @@ export interface EntityOptions<S = unknown> {
      */
     domain?: string;
     /** Schéma natif du driver (schéma Mongoose, schéma Drizzle...). */
-    schema?: S;
+    schema?: S | undefined;
     /** Relations déclaratives vers d'autres entités. */
     relations?: ReadonlyArray<IEntityRelation>;
 }

package/dist/types/nodefony/src/decorators/metadataStore.d.ts

@@ -17,13 +17,13 @@ export interface EntityMetadata<S = unknown> {
     /** Connexion nommée cible (clé du `ormRegistry`). */
     readonly connector: string;
     /** Module Nodefony propriétaire (regroupement graphe/ERD), si fourni. */
-    readonly module?: string;
+    readonly module?: string | undefined;
     /** Classification (domaine fonctionnel), axe de regroupement distinct du module. */
-    readonly domain?: string;
+    readonly domain?: string | undefined;
     /** Schéma natif du driver (forme libre), si fourni au décorateur. */
-    readonly schema?: S;
+    readonly schema?: S | undefined;
     /** Relations déclaratives vers d'autres entités. */
-    readonly relations?: ReadonlyArray<IEntityRelation>;
+    readonly relations?: ReadonlyArray<IEntityRelation> | undefined;
     /** Constructeur décoré (pour introspection / résolution lazy par le driver). */
     readonly target: DecoratedClass;
 }
@@ -36,7 +36,7 @@ export interface RepositoryMetadata {
     /** Nom logique de l'entité gérée par ce repository. */
     readonly entity: string;
     /** Connecteur cible (lève l'ambiguïté si l'entité existe sur plusieurs connexions). */
-    readonly connector?: string;
+    readonly connector?: string | undefined;
     /** Constructeur décoré. */
     readonly target: DecoratedClass;
 }

package/dist/types/nodefony/src/omitUndefined.d.ts

@@ -0,0 +1,16 @@
+import type { PartialInput } from "nodefony";
+/**
+ * Retire les clés qui valent `undefined` d'une donnée d'écriture partielle.
+ *
+ * `undefined` et clé absente veulent dire « ne pas toucher » : Drizzle ignore
+ * déjà une valeur `undefined`, Mongoose (≥ 6) la retire d'une mise à jour. La
+ * règle est posée ICI, une fois, au seuil de la persistance, au lieu d'être
+ * un comportement propre à chaque adaptateur.
+ *
+ * Rend l'objet reçu TEL QUEL quand aucune clé ne vaut `undefined` — le cas
+ * courant d'un corps JSON, qui ne peut pas en porter : aucune allocation.
+ *
+ * @param data - données d'écriture, clés `undefined` admises
+ * @returns les mêmes données, sans aucune clé `undefined`
+ */
+export declare function omitUndefined<T>(data: PartialInput<T>): Partial<T>;

package/docs/index.md

@@ -177,7 +177,7 @@ garantit que la dépendance va bien du concret vers l'abstrait, et jamais l'inve
 > [!NOTE]
 > `orm-core` n'est **pas un module bootable** : pas de classe `Module`, rien à mettre dans
 > `modules: [...]`. C'est une bibliothèque pure. Les modules, ce sont les **drivers** — ce sont eux
-> qui s'enregistrent dans `ormRegistry` (`OrmRegistry.ts:88`) à leur démarrage.
+> qui s'enregistrent dans `ormRegistry` (`OrmRegistry.ts:86`) à leur démarrage.
 
 ## La vision Nodefony
 
@@ -377,13 +377,13 @@ sequenceDiagram
   Note over K: onServersReady → récap de boot
 ```
 
-**`entityRegistry`** (`EntityRegistry.ts:147`) indexe les entités à **deux** niveaux — nom puis
+**`entityRegistry`** (`EntityRegistry.ts:145`) indexe les entités à **deux** niveaux — nom puis
 connecteur — parce qu'une même entité logique (`User`) peut vivre sur plusieurs connexions. Demander
 `get("User")` sans préciser le connecteur alors que deux le portent **lève** plutôt que de deviner
 (`EntityRegistry.get()`, `EntityRegistry.ts:54`). Le stockage est un `Object.create(null)` alloué
 **au premier enregistrement** : une application sans base ne paie rien.
 
-**`ormRegistry`** (`OrmRegistry.ts:88`) associe un nom de connexion à son instance `IOrm`. Un doublon
+**`ormRegistry`** (`OrmRegistry.ts:86`) associe un nom de connexion à son instance `IOrm`. Un doublon
 de nom **lève** (`OrmRegistry.register()`, `OrmRegistry.ts:26`) : deux connexions homonymes seraient
 un bug silencieux, jamais une intention.
 
@@ -394,7 +394,7 @@ l'ordre des écouteurs, la table existe ou non. `entities()` s'accroche à `onRe
 comportement avec `@controllers`, qui lui reste à `onBoot`.
 
 **`Orm.connect()`** (`Orm.ts:118`) est une **template method** : elle mesure la latence, alimente le
-moniteur de connexion, puis émet `onOrmReady`. Un adapter surcharge `onConnect()` (`Orm.ts:74`), et
+moniteur de connexion, puis émet `onOrmReady`. Un adapter surcharge `onConnect()` (`Orm.ts:363`), et
 **jamais** `connect()` — sinon l'événement et l'instrumentation disparaissent.
 
 ## 🧰 Les contrats — la surface publique
@@ -420,20 +420,22 @@ lieu d'échouer : `describeEntity()` (`IOrm.ts:78`, colonnes pour l'ERD), `descr
 `IRepository<T>` (`IRepository.ts:197`) est la seule surface que ton métier devrait connaître. Les
 verbes se choisissent sur **la garantie** qu'ils apportent, pas sur leur nom.
 
-| Verbe                 | Ce qu'il garantit                                                    | Ancre                        |
-| --------------------- | -------------------------------------------------------------------- | ---------------------------- |
-| `find` / `findOne`    | lecture filtrée + eager-load + tri + bornes                          | `IRepository.ts:230`         |
-| `count` / `exists`    | compter, ou juste savoir s'il y en a un (sans charger de colonne)    | `IRepository.ts:395`, `:335` |
-| `create`              | insertion d'une ligne, rend la version persistée (id, défauts)       | `IRepository.ts:240`         |
-| `createMany`          | N lignes en **une** requête — seed, import, ingestion par lots       | `IRepository.ts:252`         |
-| `updateOne`           | met à jour **au plus une** ligne, **atomiquement**, et la rend       | `IRepository.ts:269`         |
-| `updateMany`          | met à jour toutes les lignes du critère, rend le **nombre**          | `IRepository.ts:312`         |
-| `upsert`              | insère **ou** met à jour sur conflit de clé, en **une** instruction  | `IRepository.ts:296`         |
-| `increment`           | `SET f = f + ?` atomique — compteurs, quotas, rate-limit             | `IRepository.ts:287`         |
-| `delete`              | supprime tout ce qui matche, rend le nombre                          | `IRepository.ts:336`         |
-| `deleteOne`           | supprime **au plus une** ligne, rend un booléen                      | `IRepository.ts:345`         |
-| `findOneAndDelete`    | supprime **et rend** la ligne — file de jobs, outbox, `pop` atomique | `IRepository.ts:355`         |
-| `withTransaction(tx)` | une **vue** du repository liée à une transaction                     | `IRepository.ts:406`         |
+| Verbe                 | Ce qu'il garantit                                                         | Ancre                |
+| --------------------- | ------------------------------------------------------------------------- | -------------------- |
+| `find` / `findOne`    | lecture filtrée + eager-load + tri + bornes                               | `IRepository.ts:230` |
+| `count`               | compter les entités qui correspondent au critère                          | `IRepository.ts:362` |
+| `exists`              | savoir s'il y en a au moins un, sans charger de colonne                   | `IRepository.ts:395` |
+| `countDistinct`       | compter les valeurs DISTINCTES et non nulles d'un champ, sans les charger | `IRepository.ts:381` |
+| `create`              | insertion d'une ligne, rend la version persistée (id, défauts)            | `IRepository.ts:240` |
+| `createMany`          | N lignes en **une** requête — seed, import, ingestion par lots            | `IRepository.ts:252` |
+| `updateOne`           | met à jour **au plus une** ligne, **atomiquement**, et la rend            | `IRepository.ts:269` |
+| `updateMany`          | met à jour toutes les lignes du critère, rend le **nombre**               | `IRepository.ts:312` |
+| `upsert`              | insère **ou** met à jour sur conflit de clé, en **une** instruction       | `IRepository.ts:296` |
+| `increment`           | `SET f = f + ?` atomique — compteurs, quotas, rate-limit                  | `IRepository.ts:287` |
+| `delete`              | supprime tout ce qui matche, rend le nombre                               | `IRepository.ts:336` |
+| `deleteOne`           | supprime **au plus une** ligne, rend un booléen                           | `IRepository.ts:345` |
+| `findOneAndDelete`    | supprime **et rend** la ligne — file de jobs, outbox, `pop` atomique      | `IRepository.ts:355` |
+| `withTransaction(tx)` | une **vue** du repository liée à une transaction                          | `IRepository.ts:406` |
 
 > [!IMPORTANT]
 > `updateOne` est atomique **par construction** : une seule requête (`UPDATE … RETURNING` en SQL,
@@ -538,8 +540,8 @@ raisonnement, et le compilateur la refuse.
 JSON ou un sous-document (`{ meta: { auteur: "…" } }`) reste donc une égalité — c'est ce qui évite
 qu'une donnée métier soit prise pour une requête.
 
-**Ce que le critère ne couvre pas** : les `OR` logiques, les sous-requêtes, les agrégats, les
-jointures arbitraires. Ce n'est pas un oubli — c'est la limite du portable, et la sortie est
+**Ce que le critère ne couvre pas** : les sous-requêtes, les agrégats, les jointures arbitraires
+(la disjonction, elle, s'exprime par `$or: [...]`, portable). Ce n'est pas un oubli — c'est la limite du portable, et la sortie est
 `getNativeConnection()`. L'erreur `UnknownCriteriaField` (`errors.ts:23`) le dit d'ailleurs
 explicitement dans son message, avec la liste des champs connus de l'entité (diagnostic d'une faute
 de frappe).
@@ -608,8 +610,8 @@ d'administration : elle ne charge qu'une page, quelle que soit la taille de la t
 
 Deux drivers implémentent les contrats. Le contrat `IRepository` est tenu **en entier** par les
 deux : les quinze verbes existent des deux côtés — par exemple l'upsert, avec
-`DrizzleRepository.upsert()` (`DrizzleRepository.ts:879`) et `MongooseRepository.upsert()`
-(`MongooseRepository.ts:405`).
+`DrizzleRepository.upsert()` (`DrizzleRepository.ts:986`) et `MongooseRepository.upsert()`
+(`MongooseRepository.ts:422`).
 
 | Capacité                               | `@nodefony/drizzle`                 | `@nodefony/mongoose`                         |
 | -------------------------------------- | ----------------------------------- | -------------------------------------------- |
@@ -618,12 +620,12 @@ deux : les quinze verbes existent des deux côtés — par exemple l'upsert, ave
 | Eager-load `{ relations }`             | oui                                 | oui (`populate`)                             |
 | Transactions                           | oui                                 | oui (replica set requis par Mongo)           |
 | Savepoints (rollback partiel)          | oui                                 | non — refusés (`SavepointNotSupportedError`) |
-| Colonnes pour l'ERD (`describeEntity`) | oui (`DrizzleOrm.ts:1933`)          | oui (`MongooseOrm.ts:649`)                   |
-| Sonde de flux (requêtes/s, lentes)     | oui — alimente `queryFlowMonitor`   | non câblée                                   |
-| Sonde profonde (`probe`)               | oui (`DrizzleOrm.ts:1835`)          | oui (`MongooseOrm.ts:617`)                   |
+| Colonnes pour l'ERD (`describeEntity`) | oui (`DrizzleOrm.ts:1982`)          | oui (`MongooseOrm.ts:649`)                   |
+| Sonde de flux (requêtes/s, lentes)     | oui — alimente `queryFlowMonitor`   | oui — alimente `queryFlowMonitor`            |
+| Sonde profonde (`probe`)               | oui (`DrizzleOrm.ts:1873`)          | oui (`MongooseOrm.ts:617`)                   |
 
-**Les « stores » du framework, eux, ne sont pas alignés — et c'est un choix.** Un adapter déclare ce
-qu'il porte dans son `package.json`, clé `nodefony.stores` :
+**Les « stores » du framework** : chaque adapter déclare ce qu'il porte dans son `package.json`, clé
+`nodefony.stores`. Les deux backends durables portent les huit :
 
 | Store         | drizzle | mongoose |
 | ------------- | ------- | -------- |
@@ -632,16 +634,15 @@ qu'il porte dans son `package.json`, clé `nodefony.stores` :
 | `tokens`      | ✅      | ✅       |
 | `passkeys`    | ✅      | ✅       |
 | `webhooks`    | ✅      | ✅       |
-| `totp`        | ✅      | —        |
-| `audit`       | ✅      | —        |
-| `idempotency` | ✅      | —        |
+| `totp`        | ✅      | ✅       |
+| `audit`       | ✅      | ✅       |
+| `idempotency` | ✅      | ✅       |
 
 > [!NOTE]
-> La couverture est **adaptée à la nature de chaque backend**, ce n'est pas une parité SQL × NoSQL à
-> atteindre. Un store d'idempotence veut une contrainte d'unicité et un `ON CONFLICT` — le terrain du
-> SQL. Lire ce tableau comme « mongoose est incomplet » serait un contresens : il porte exactement ce
-> qu'un déploiement Mongo attend de lui. La liste fait autorité côté code
-> (`@nodefony/drizzle/package.json`, clé `nodefony.stores`) — elle n'est pas un commentaire.
+> La couverture est **adaptée à la nature de chaque backend** : c'est `@nodefony/redis`, un cache,
+> qui s'arrête à quatre stores (`session`, `tokens`, `passkeys`, `idempotency`) — il ne garde ni
+> comptes ni journal. La liste fait autorité côté code (`nodefony.stores` du `package.json` de chaque
+> adapter) — elle n'est pas un commentaire.
 
 ## 🧩 Extension — brancher son propre driver
 
@@ -678,7 +679,7 @@ première connexion, reconnexions, erreurs récentes, et une fenêtre de latence
 (`ConnectionMonitor.recordPing()`, `ConnectionMonitor.ts:136`). Il est alimenté par `Orm.connect()`
 sans que l'adapter ait à y penser.
 
-**`queryFlowMonitor`** (`QueryFlowMonitor.ts:146`) suit le **débit** : total de requêtes, latence
+**`queryFlowMonitor`** (`QueryFlowMonitor.ts:144`) suit le **débit** : total de requêtes, latence
 moyenne et EWMA, pire latence, et un anneau borné à vingt requêtes lentes. Trois propriétés le
 rendent sûr en production :
 
@@ -690,19 +691,22 @@ rendent sûr en production :
   observe, et le débit par seconde est **dérivé côté lecteur** (delta entre deux relevés), donc rien
   n'est muté à la lecture.
 
-Le data plane `/nodefony/orm/api/*` (`createOrmAdminApi()`, `OrmAdminApi.ts:541`) expose huit points
+Le data plane `/nodefony/orm/api/*` (`createOrmAdminApi()`, `OrmAdminApi.ts:541`) expose onze points
 d'entrée, tous filtrables par `?connector=` :
 
-| Point d'entrée      | Ce qu'il rend                                                     |
-| ------------------- | ----------------------------------------------------------------- |
-| `orms`              | les connecteurs, leur état, leur nombre d'entités                 |
-| `entities`          | le modèle complet : colonnes + relations                          |
-| `entity/{name}`     | une entité (404 si inconnue)                                      |
-| `graph`             | le graphe canonique (`buildOrmGraph()`, `OrmAdminApi.ts:227`)     |
-| `counts`            | le nombre de lignes par entité — un `COUNT(*)` par table          |
-| `connection/health` | état, latence, erreurs, reconnexions, sondes                      |
-| `flow`              | débit et requêtes lentes (`buildOrmFlow()`, `OrmAdminApi.ts:360`) |
-| `export/{format}`   | `dbml` (`toDbml()`, `OrmAdminApi.ts:395`) ou `jsonschema`         |
+| Point d'entrée      | Ce qu'il rend                                                      |
+| ------------------- | ------------------------------------------------------------------ |
+| `orms`              | les connecteurs, leur état, leur nombre d'entités                  |
+| `entities`          | le modèle complet : colonnes + relations                           |
+| `entity/{name}`     | une entité (404 si inconnue)                                       |
+| `graph`             | le graphe canonique (`buildOrmGraph()`, `OrmAdminApi.ts:227`)      |
+| `counts`            | le nombre de lignes par entité — un `COUNT(*)` par table           |
+| `connection/health` | état, latence, erreurs, reconnexions, sondes                       |
+| `flow`              | débit et requêtes lentes (`buildOrmFlow()`, `OrmAdminApi.ts:360`)  |
+| `export/{format}`   | `dbml` (`toDbml()`, `OrmAdminApi.ts:395`) ou `jsonschema`          |
+| `migrations`        | l'état des migrations (même objet que `orm:migrate:status --json`) |
+| `migrations/plan`   | le SQL en attente                                                  |
+| `migrations/apply`  | applique les migrations (développement seulement)                  |
 
 Ce graphe canonique est **la pièce maîtresse**, pas le diagramme : c'est une donnée sérialisable qui
 sert à la fois l'ERD de Studio, un export vers un outil tiers, et le contexte d'un agent IA
@@ -740,9 +744,9 @@ deux, et pas de course).
 | `updateOne` rend `null` alors que la ligne a bien changé      | ancien réflexe `UPDATE` + relecture (le critère porte sur le champ modifié)                        | utiliser `updateOne`, atomique par construction (`IRepository.ts:269`)                      |
 | Un `upsert` écrase une valeur qui devait progresser           | le `DO UPDATE` est inconditionnel (contrainte MySQL)                                               | poser la condition **dans** la valeur : `{ seuil: { $max: v } }` (`IRepository.ts:94`)      |
 | Un objet de critère est pris pour une égalité (colonne JSON)  | comportement **voulu** : une valeur n'est un filtre que si **toutes** ses clés sont des opérateurs | c'est la protection ; pour filtrer dedans, passer au natif (`criteria.ts:42`)               |
-| `onOrmReady` ne part plus après un ajout dans l'adapter       | `connect()` a été surchargé                                                                        | surcharger `onConnect()` (`Orm.ts:74`), jamais `connect()`                                  |
+| `onOrmReady` ne part plus après un ajout dans l'adapter       | `connect()` a été surchargé                                                                        | surcharger `onConnect()` (`Orm.ts:363`), jamais `connect()`                                 |
 | Une entité déclarée dans un module reste invisible            | le module embarque sa **propre copie** du registre (singleton dédoublé)                            | externaliser `@nodefony/orm-core` dans le `rolldown.config.ts` du module                    |
-| Rien dans `flow` alors que la base travaille                  | la sonde est éteinte hors développement, ou le driver n'a pas de tap                               | `NF_ORM_FLOW=1` (`ormWiring.ts:96`) ; le tap n'est câblé que côté Drizzle                   |
+| Rien dans `flow` alors que la base travaille                  | la sonde est éteinte hors développement, ou le driver n'a pas de tap                               | `NF_ORM_FLOW=1` (`ormWiring.ts:96`) ; les deux drivers officiels ont un tap                 |
 
 ## 🧪 Tests & couverture
 

package/docs/tutorial-entity.md

@@ -285,14 +285,15 @@ fichier, sans rien contourner.
 
 Deux conséquences du DDL dérivé au boot, à connaître dès maintenant :
 
-- la table est créée par un `CREATE TABLE IF NOT EXISTS` — **modifier le schéma n'altère pas une
-  table déjà créée** (aucun `ALTER` n'est émis) ;
-- les **index** déclarés et les `DEFAULT` **SQL** ne sont pas émis. D'où les défauts posés côté
-  JavaScript (`$defaultFn`), qui s'appliquent quoi qu'il arrive.
+- la table est créée par un `CREATE TABLE IF NOT EXISTS`, avec ses index et ses clés étrangères ;
+  au démarrage suivant, seule une colonne ajoutée qui **accepte le vide** est rattrapée — une colonne
+  obligatoire ne l'est jamais ;
+- les `DEFAULT` **SQL** ne sont pas émis. D'où les défauts posés côté JavaScript (`$defaultFn`), qui
+  s'appliquent quoi qu'il arrive.
 
 > [!TIP]
-> En développement, la façon la plus rapide de prendre en compte une colonne ajoutée est de
-> supprimer le fichier SQLite et de redémarrer. En production, cela relève d'une migration.
+> En développement, une colonne obligatoire ajoutée se prend en compte par `nodefony orm:reset`. En
+> production, cela relève d'une migration (`orm:generate`, puis `orm:migrate`).
 
 ### Étape 3 — déclarer l'entité
 
@@ -347,20 +348,22 @@ que l'import plus la ligne du décorateur.
 Le repository porte **quinze verbes**, pas cinq. Ils se choisissent sur la **garantie** qu'ils
 apportent, jamais sur leur nom.
 
-| Verbe                 | Ce qu'il garantit                                                  | Ancre                        |
-| --------------------- | ------------------------------------------------------------------ | ---------------------------- |
-| `find` / `findOne`    | lecture filtrée, avec tri, bornes et eager-load                    | `IRepository.ts:230`, `:192` |
-| `create`              | insère une ligne et rend sa version persistée (id, défauts)        | `IRepository.ts:240`         |
-| `createMany`          | N lignes en **une** requête — seed, import, ingestion par lots     | `IRepository.ts:252`         |
-| `updateOne`           | modifie **au plus une** ligne, **atomiquement**, et la rend        | `IRepository.ts:269`         |
-| `updateMany`          | modifie toutes les lignes du critère, rend le **nombre**           | `IRepository.ts:312`         |
-| `upsert`              | insère **ou** met à jour sur conflit de clé, en une instruction    | `IRepository.ts:296`         |
-| `increment`           | `SET f = f + ?` atomique — compteurs, quotas, limitation de débit  | `IRepository.ts:287`         |
-| `delete`              | supprime tout ce qui matche, rend le nombre                        | `IRepository.ts:336`         |
-| `deleteOne`           | supprime **au plus une** ligne, rend un booléen                    | `IRepository.ts:345`         |
-| `findOneAndDelete`    | supprime **et rend** la ligne — file de jobs, `pop` atomique       | `IRepository.ts:355`         |
-| `count` / `exists`    | compter, ou juste savoir s'il y en a une (sans charger de colonne) | `IRepository.ts:395`, `:335` |
-| `withTransaction(tx)` | une **vue** du repository liée à une transaction                   | `IRepository.ts:406`         |
+| Verbe                 | Ce qu'il garantit                                                         | Ancre                        |
+| --------------------- | ------------------------------------------------------------------------- | ---------------------------- |
+| `find` / `findOne`    | lecture filtrée, avec tri, bornes et eager-load                           | `IRepository.ts:230`, `:192` |
+| `create`              | insère une ligne et rend sa version persistée (id, défauts)               | `IRepository.ts:240`         |
+| `createMany`          | N lignes en **une** requête — seed, import, ingestion par lots            | `IRepository.ts:252`         |
+| `updateOne`           | modifie **au plus une** ligne, **atomiquement**, et la rend               | `IRepository.ts:269`         |
+| `updateMany`          | modifie toutes les lignes du critère, rend le **nombre**                  | `IRepository.ts:312`         |
+| `upsert`              | insère **ou** met à jour sur conflit de clé, en une instruction           | `IRepository.ts:296`         |
+| `increment`           | `SET f = f + ?` atomique — compteurs, quotas, limitation de débit         | `IRepository.ts:287`         |
+| `delete`              | supprime tout ce qui matche, rend le nombre                               | `IRepository.ts:336`         |
+| `deleteOne`           | supprime **au plus une** ligne, rend un booléen                           | `IRepository.ts:345`         |
+| `findOneAndDelete`    | supprime **et rend** la ligne — file de jobs, `pop` atomique              | `IRepository.ts:355`         |
+| `count`               | compter les entités qui correspondent au critère                          | `IRepository.ts:362`         |
+| `exists`              | savoir s'il y en a au moins une, sans charger de colonne                  | `IRepository.ts:395`         |
+| `countDistinct`       | compter les valeurs DISTINCTES et non nulles d'un champ, sans les charger | `IRepository.ts:381`         |
+| `withTransaction(tx)` | une **vue** du repository liée à une transaction                          | `IRepository.ts:406`         |
 
 > [!IMPORTANT]
 > **Il n'existe pas de méthode `update()`.** Le choix est explicite et il est intentionnel :
@@ -463,8 +466,8 @@ Sur une ligne dont on sait qu'elle **existe**, ils sont inutiles :
 
 ### Ce que le critère ne couvre pas
 
-Les `OR` logiques, les sous-requêtes, les agrégats et les jointures arbitraires n'en font pas
-partie. Ce n'est pas un oubli : c'est la limite de ce qui se porte d'un moteur SQL à MongoDB. La
+Les sous-requêtes, les agrégats et les jointures arbitraires n'en font pas partie (la disjonction,
+elle, s'exprime par `$or: [...]`). Ce n'est pas un oubli : c'est la limite de ce qui se porte d'un moteur SQL à MongoDB. La
 sortie est `IOrm.getNativeConnection()` (`IOrm.ts:51`), qui rend la connexion brute du driver.
 
 Un champ absent de l'entité lève `UnknownCriteriaField` (`errors.ts:23`), et le message liste les
@@ -528,8 +531,8 @@ d'administration, la primitive est `AbstractCrudService.findPage()` (`AbstractCr
 | `posts.update is not a function`                              | la méthode `update()` n'existe pas dans le contrat                                               | `updateOne` pour une ligne (`IRepository.ts:269`), `updateMany` pour un lot (`IRepository.ts:312`)       |
 | « no entity registered under "Post" » au premier appel        | le fichier d'entité est importé, mais `defineEntity()` est **sans effet de bord**                | ajouter l'entité à `@entities([...])` sur le module (`entitiesDecorator.ts:56`)                          |
 | La table n'existe pas alors que l'entité est déclarée         | inscription faite à `onBoot` → course avec l'ouverture du connecteur                             | inscrire à `onRegister` — c'est ce que fait `entities()` (`entitiesDecorator.ts:56`)                     |
-| Une colonne ajoutée au schéma reste absente de la table       | le DDL du boot est un `CREATE TABLE IF NOT EXISTS` : aucun `ALTER` n'est émis                    | supprimer la base de développement et redémarrer, ou passer par une migration                            |
-| Un `DEFAULT` SQL ou un index déclaré n'apparaît pas           | le DDL dérivé ne les émet pas                                                                    | poser le défaut côté JavaScript (`$defaultFn`) ; créer l'index par migration                             |
+| Une colonne ajoutée au schéma reste absente de la table       | colonne **obligatoire** : le rattrapage de développement n'ajoute que les colonnes facultatives  | `nodefony orm:reset` en développement, ou `orm:generate` puis `orm:migrate`                              |
+| Un `DEFAULT` SQL déclaré n'apparaît pas                       | le DDL dérivé ne l'émet pas                                                                      | poser le défaut côté JavaScript (`$defaultFn`)                                                           |
 | Un filtre « champ vide » ne remonte jamais rien               | `colonne = NULL` est toujours faux en SQL                                                        | `{ champ: { $null: true } }` ou la valeur nue `{ champ: null }` (`IRepository.ts:65`)                    |
 | `UnknownCriteriaField` sur un champ qui « existe pourtant »   | faute de frappe, ou champ calculé absent du schéma                                               | lire les champs connus dans le message ; pour du natif, passer par `getNativeConnection()`               |
 | `connector: "sqlite"` ne trouve aucune connexion              | `connector` nomme une **connexion**, pas un moteur                                               | mettre la clé de `connectors` (`"default"`) ; le moteur est le `dialect` de la config                    |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodefony/orm-core",
-  "version": "10.0.0-alpha.9",
+  "version": "10.0.0-beta.2",
   "description": "Un contrat de dépôt de données pour Nodefony, plusieurs moteurs : interfaces, registre et classes de base pour le support multi-ORM",
   "contributors": [],
   "type": "module",
@@ -37,12 +37,12 @@
     "esm"
   ],
   "peerDependencies": {
-    "nodefony": "^10.0.0-alpha.9"
+    "nodefony": "^10.0.0-beta.2"
   },
   "devDependencies": {
-    "@types/node": "26.6.2",
-    "nodefony": "^10.0.0-alpha.9",
-    "vitest": "5.0.1"
+    "@types/node": "26.6.3",
+    "nodefony": "^10.0.0-beta.2",
+    "vitest": "5.0.3"
   },
   "repository": {
     "type": "git",