@nodefony/orm-core 10.0.0-beta.4 → 10.0.0-beta.6

package/README.md

@@ -99,20 +99,35 @@ du module**, sur la classe et non sur une instance : il connaît donc son nom et
 instancier, et enregistre l'entité directement.
 
 ```typescript
+import { randomUUID } from "node:crypto";
 import { entity, repository } from "@nodefony/orm-core";
 import type { IRepository } from "@nodefony/orm-core";
+import { defineTable } from "@nodefony/drizzle";
+
+// Le `schema` est la forme de l'ADAPTATEUR : ici la description portable du kit
+// Drizzle, qui suit le dialecte du connecteur.
+const memberTable = defineTable({
+  name: "Member",
+  columns: {
+    id: { kind: "uuid", primaryKey: true, defaultFn: () => randomUUID() },
+    email: { kind: "string", length: 255, notNull: true },
+  },
+});
 
-// `name` vaut par défaut le nom de la classe ; ici forcé à "User".
+// `name` vaut par défaut le nom de la classe ; ici forcé à "Member".
 @entity({
   connector: "db_principale",
-  name: "User",
-  schema: { id: { type: "uuid", primaryKey: true }, email: { type: "string" } },
+  name: "Member",
+  schema: memberTable,
   relations: [{ type: "one-to-many", target: "Room", field: "rooms" }],
 })
-class UserEntity {}
+class MemberEntity {}
 
-@repository("repository.user", { entity: "User", connector: "db_principale" })
-class UserRepository implements IRepository<UserEntity> {
+@repository("repository.member", {
+  entity: "Member",
+  connector: "db_principale",
+})
+class MemberRepository implements IRepository<MemberEntity> {
   /* find, findOne, create… sont fournis par l'adaptateur ORM */
 }
 ```

package/dist/index.js

@@ -4,13 +4,13 @@ import { assertOrderOption } from "./nodefony/src/readOptions.js";
 import { OrmRegistry, ormRegistry } from "./nodefony/src/OrmRegistry.js";
 import { EntityRegistry, entityRegistry } from "./nodefony/src/EntityRegistry.js";
 import { reportOrphanEntities } from "./nodefony/src/orphanEntities.js";
-import { connectionMonitor } from "./nodefony/src/ConnectionMonitor.js";
 import { Orm } from "./nodefony/src/Orm.js";
 import { Entity } from "./nodefony/src/Entity.js";
-import { paginate } from "./nodefony/src/paginate.js";
 import { AbstractCrudService } from "./nodefony/src/AbstractCrudService.js";
-import { queryFlowMonitor } from "./nodefony/src/QueryFlowMonitor.js";
+import { paginate } from "./nodefony/src/paginate.js";
 import { buildConnectionHealth, buildOrmFlow, buildOrmGraph, createOrmAdminApi, registerOrmAdminApi, toDbml, toJsonSchema } from "./nodefony/src/OrmAdminApi.js";
+import { queryFlowMonitor } from "./nodefony/src/QueryFlowMonitor.js";
+import { connectionMonitor } from "./nodefony/src/ConnectionMonitor.js";
 import { buildOrmLeanHealth } from "./nodefony/src/buildOrmLeanHealth.js";
 import { REJECTED_MARKER, describeConnectFailure, diagnoseConnectionFailure, parseConnectionTarget } from "./nodefony/src/connectionDiagnosis.js";
 import { CONNECT_TIMEOUT_MS, withConnectDeadline } from "./nodefony/src/connectDeadline.js";

package/dist/nodefony/src/OrmAdminApi.js

@@ -131,8 +131,51 @@ function buildOrmSummaries() {
 	});
 }
 /**
-* Construit un nœud de graphe pour une entité : relations (toujours) + colonnes
-* (via `orm.describeEntity` si l'adapter l'implémente et si l'ORM est connecté).
+* Clé étrangère d'une relation qui n'en nomme aucune : `<entité>Id`, l'entité
+* en minuscule initiale — la convention des adapters.
+*
+* @param entity - nom logique de l'entité qui donne son nom à la clé.
+* @returns le nom de colonne conventionnel.
+*/
+function conventionalForeignKey(entity) {
+	return `${entity.charAt(0).toLowerCase()}${entity.slice(1)}Id`;
+}
+/**
+* Relations d'un nœud : celles que l'entité DÉCLARE, puis une « plusieurs vers
+* un » par clé étrangère que la base porte et qu'aucune déclaration ne couvre.
+*
+* Sans la seconde moitié, une entité qui référence par ses colonnes (`ref` du
+* kit, table écrite à la main) sans répéter le lien dans `relations` n'avait
+* AUCUNE arête dans le graphe, alors que la contrainte existe en base.
+* Une déclaration couvre une colonne quand sa clé — explicite, ou
+* conventionnelle — est cette colonne.
+*/
+function nodeRelations(declared, columns) {
+	const relations = declared.map((r) => ({
+		type: r.type,
+		target: r.target,
+		field: r.field,
+		foreignKey: r.foreignKey
+	}));
+	let covered = null;
+	for (const col of columns) {
+		if (col.references === void 0) continue;
+		covered ??= new Set(declared.filter((r) => r.type === "many-to-one" || r.type === "one-to-one").map((r) => r.foreignKey ?? conventionalForeignKey(r.target)));
+		if (covered.has(col.name)) continue;
+		relations.push({
+			type: "many-to-one",
+			target: col.references.entity,
+			field: col.name,
+			foreignKey: col.name,
+			targetKey: col.references.column
+		});
+	}
+	return relations;
+}
+/**
+* Construit un nœud de graphe pour une entité : colonnes (via
+* `orm.describeEntity` si l'adapter l'implémente et si l'ORM est connecté) et
+* relations, déclarées puis imposées par les clés étrangères.
 */
 function buildEntityNode(connector, name) {
 	const entity = entityRegistry.get(name, connector);
@@ -148,12 +191,7 @@ function buildEntityNode(connector, name) {
 		module: entity.module ?? "",
 		domain: entity.domain ?? "",
 		columns,
-		relations: (entity.relations ?? []).map((r) => ({
-			type: r.type,
-			target: r.target,
-			field: r.field,
-			foreignKey: r.foreignKey
-		}))
+		relations: nodeRelations(entity.relations ?? [], columns)
 	};
 }
 /** Construit le graphe canonique complet (optionnellement filtré par connecteur). */
@@ -327,13 +365,13 @@ function toDbml(graph) {
 			refs.add(`// many-to-many ${node.name}.${rel.field} <> ${rel.target} (table de jonction)`);
 			continue;
 		}
-		const camel = (n) => `${n.charAt(0).toLowerCase()}${n.slice(1)}Id`;
+		const key = dbmlId(rel.targetKey ?? "id");
 		if (rel.type === "one-to-many") {
-			const fk = rel.foreignKey ?? camel(node.name);
-			refs.add(`Ref: ${dbmlId(rel.target)}.${dbmlId(fk)} > ${dbmlId(node.name)}.id`);
+			const fk = rel.foreignKey ?? conventionalForeignKey(node.name);
+			refs.add(`Ref: ${dbmlId(rel.target)}.${dbmlId(fk)} > ${dbmlId(node.name)}.${key}`);
 		} else {
-			const fk = rel.foreignKey ?? camel(rel.target);
-			refs.add(`Ref: ${dbmlId(node.name)}.${dbmlId(fk)} > ${dbmlId(rel.target)}.id`);
+			const fk = rel.foreignKey ?? conventionalForeignKey(rel.target);
+			refs.add(`Ref: ${dbmlId(node.name)}.${dbmlId(fk)} > ${dbmlId(rel.target)}.${key}`);
 		}
 	}
 	lines.push(...refs);
@@ -529,4 +567,4 @@ function registerOrmAdminApi(registry) {
 	if (registry.has("orm")) return;
 	registry.register(createOrmAdminApi());
 }
-export { buildConnectionHealth, buildOrmFlow, buildOrmGraph, createOrmAdminApi, registerOrmAdminApi, storeCarrier, toDbml, toJsonSchema };
+export { buildConnectionHealth, buildOrmFlow, buildOrmGraph, conventionalForeignKey, createOrmAdminApi, registerOrmAdminApi, storeCarrier, toDbml, toJsonSchema };

package/dist/nodefony/src/decorators/index.js

@@ -1,5 +1,5 @@
-import { getEntityMeta, getRepositoryMeta, hasEntityMeta, hasRepositoryMeta } from "./metadataStore.js";
 import { entity } from "./entityDecorator.js";
 import { DEFAULT_CONNECTOR, entities } from "./entitiesDecorator.js";
 import { repository } from "./repositoryDecorator.js";
+import { getEntityMeta, getRepositoryMeta, hasEntityMeta, hasRepositoryMeta } from "./metadataStore.js";
 export { DEFAULT_CONNECTOR, entities, entity, getEntityMeta, getRepositoryMeta, hasEntityMeta, hasRepositoryMeta, repository };

package/dist/nodefony/src/ormWiring.js

@@ -1,6 +1,6 @@
-import { ormRegistry } from "./OrmRegistry.js";
 import { buildConnectionHealth, buildOrmFlow, registerOrmAdminApi } from "./OrmAdminApi.js";
 import { buildOrmLeanHealth } from "./buildOrmLeanHealth.js";
+import { ormRegistry } from "./OrmRegistry.js";
 import { setOrmHealthProvider, setOrmRichProvider } from "nodefony";
 // nodefony/src/ormWiring.ts
 /**

package/dist/nodefony/src/orphanEntities.js

@@ -1,5 +1,5 @@
-import { ormRegistry } from "./OrmRegistry.js";
 import { entityRegistry } from "./EntityRegistry.js";
+import { ormRegistry } from "./OrmRegistry.js";
 // nodefony/src/orphanEntities.ts
 /**
 * Entités inscrites sur un connecteur qu'aucun ORM n'a ouvert.

package/dist/types/index.d.ts

@@ -31,7 +31,7 @@ export type { ConnectionVerdict, IConnectionDiagnosis, IConnectionTarget, } from
 export { CONNECT_TIMEOUT_MS, withConnectDeadline, } from "./nodefony/src/connectDeadline.js";
 export { wireOrmAdminPlane, resolveOrmFlowEnabled, reportOrmBootLines, } from "./nodefony/src/ormWiring.js";
 export type { ISlowQuery, IQueryFlow, IOrmFlowReport, } from "./nodefony/interfaces/IOrmFlow.js";
-export type { IColumnInfo, IConnectionInfo, IRelationInfo, IEntityGraphNode, IOrmSummary, IOrmGraph, IConnectionError, IConnectionEvent, IOrmResilience, IConnectionHealth, } from "./nodefony/interfaces/IOrmGraph.js";
+export type { IColumnInfo, IColumnReference, IConnectionInfo, IRelationInfo, IEntityGraphNode, IOrmSummary, IOrmGraph, IConnectionError, IConnectionEvent, IOrmResilience, IConnectionHealth, } from "./nodefony/interfaces/IOrmGraph.js";
 export type { ILatencyWindow, IOrmStorageProbe, IOrmPoolProbe, IOrmProbe, } from "./nodefony/interfaces/IOrmProbe.js";
 export type { IOrmMigrationAction, IOrmMigrationEntry, IOrmMigrationSource, IOrmMigrationStatus, IOrmMigrationFailure, IOrmMigrationReply, IOrmPendingMigration, IOrmMigrationPlan, IOrmMigrationPlanReply, IOrmMigrationApplied, IOrmMigrationApplyReply, } from "./nodefony/interfaces/IOrmMigrations.js";
 export { isMigrationFailure } from "./nodefony/interfaces/IOrmMigrations.js";

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

@@ -81,4 +81,16 @@ export interface IEntity<S = unknown, M = unknown> {
      * dans leur table → ce champ y est sans effet. **Optionnel**.
      */
     readonly indexes?: ReadonlyArray<IEntityIndex> | undefined;
+    /**
+     * Champs qui ne sortent JAMAIS par une relation : quand une autre entité
+     * charge celle-ci (`relations: ["owner"]`, `?include=owner`), l'adapter ne les
+     * lit pas. Le dépôt de l'entité elle-même les rend toujours — c'est la porte
+     * de qui en a besoin (l'authentification lit `password` par là).
+     *
+     * Sans cette déclaration, référencer un `User` exposait son empreinte de mot
+     * de passe à quiconque lisait la ressource qui le référence. Un nom qui ne
+     * désigne aucun champ fait échouer la connexion en le nommant : une faute de
+     * frappe ici rouvrirait la fuite sans un mot. **Optionnel**.
+     */
+    readonly privateFields?: ReadonlyArray<string> | undefined;
 }

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

@@ -22,6 +22,20 @@ export interface IColumnInfo {
     nullable: boolean;
     /** `true` si contrainte d'unicité. */
     unique: boolean;
+    /**
+     * Cible de la clé étrangère que la BASE porte sur cette colonne — absente si
+     * la colonne n'en porte pas, ou si l'adapter ne sait pas la lire. Le graphe
+     * en dérive une relation « plusieurs vers un » quand aucune relation déclarée
+     * ne couvre déjà la colonne.
+     */
+    references?: IColumnReference | undefined;
+}
+/** Cible d'une clé étrangère : l'entité visée et la colonne qu'elle y désigne. */
+export interface IColumnReference {
+    /** Nom logique de l'entité visée (nom de table si aucune entité ne la porte). */
+    entity: string;
+    /** Colonne visée (en général la clé primaire). */
+    column: string;
 }
 /** Relation projetée pour le graphe (sous-ensemble sérialisable de `IEntityRelation`). */
 export interface IRelationInfo {
@@ -33,6 +47,8 @@ export interface IRelationInfo {
     field: string;
     /** Clé étrangère (explicite ou dérivée déterministe). */
     foreignKey?: string | undefined;
+    /** Colonne visée sur la cible — `id` par convention quand elle est absente. */
+    targetKey?: string | undefined;
 }
 /** Nœud du graphe : une entité avec ses colonnes et ses relations. */
 export interface IEntityGraphNode {
@@ -51,7 +67,10 @@ export interface IEntityGraphNode {
     domain: string;
     /** Colonnes normalisées (vide si l'adapter n'implémente pas `describeEntity`). */
     columns: IColumnInfo[];
-    /** Relations déclarées. */
+    /**
+     * Relations : celles que l'entité DÉCLARE, puis celles que ses clés
+     * étrangères imposent et qu'aucune déclaration ne couvre.
+     */
     relations: IRelationInfo[];
 }
 /** Connexion sous-jacente d'un ORM (extrait via {@link IOrm.describeConnection}). */

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

@@ -3,5 +3,5 @@ export type { IEntity, IEntityIndex, IEntityRelation } from "./IEntity.js";
 export type { IRepository, OrmCriteria, Criteria, FieldCriteria, FieldOperators, UpdateData, UpdateOperators, RepositoryReadOptions, } from "./IRepository.js";
 export type { ITransaction } from "./ITransaction.js";
 export type { IPage, IPageQuery, PageQuery } from "./IPage.js";
-export type { IColumnInfo, IConnectionInfo, IRelationInfo, IEntityGraphNode, IOrmSummary, IOrmGraph, IConnectionError, IConnectionEvent, IOrmResilience, IConnectionHealth, } from "./IOrmGraph.js";
+export type { IColumnInfo, IColumnReference, IConnectionInfo, IRelationInfo, IEntityGraphNode, IOrmSummary, IOrmGraph, IConnectionError, IConnectionEvent, IOrmResilience, IConnectionHealth, } from "./IOrmGraph.js";
 export type { ILatencyWindow, IOrmStorageProbe, IOrmPoolProbe, IOrmProbe, } from "./IOrmProbe.js";

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

@@ -17,6 +17,14 @@ import type { IOrmFlowReport } from "../interfaces/IOrmFlow.js";
  *   un ORM (le repli sur le nom `default` s'applique alors).
  */
 export declare function storeCarrier(resolutions: readonly IStoreResolution[], names: readonly string[]): string | null;
+/**
+ * Clé étrangère d'une relation qui n'en nomme aucune : `<entité>Id`, l'entité
+ * en minuscule initiale — la convention des adapters.
+ *
+ * @param entity - nom logique de l'entité qui donne son nom à la clé.
+ * @returns le nom de colonne conventionnel.
+ */
+export declare function conventionalForeignKey(entity: string): string;
 /** Construit le graphe canonique complet (optionnellement filtré par connecteur). */
 export declare function buildOrmGraph(connectorFilter?: string): IOrmGraph;
 /**

package/docs/index.md

@@ -478,7 +478,11 @@ atomique sur les quatre backends.
 d'un moteur), un `schema` natif du driver, et des `relations` déclaratives (`IEntityRelation`,
 `IEntity.ts#IEntityRelation`). Deux champs facultatifs servent la lisibilité d'un gros modèle : `module` (qui
 apporte l'entité) et `domain` (`IEntity.ts#IEntity.domain`, la classification métier — l'axe qui rend navigable
-une base de plusieurs centaines de tables). Un troisième, `indexes` (`IEntityIndex`), déclare les
+une base de plusieurs centaines de tables ; `create entity --domain` le pose). Le graphe d'entités ne
+se limite pas aux `relations` déclarées : une colonne qui porte une clé étrangère en base en rend la
+cible (`IOrmGraph.ts#IColumnReference`, lue par `describeEntity`), et le graphe en tire une
+relation « plusieurs vers un » quand aucune déclaration ne couvre déjà la colonne
+(`OrmAdminApi.ts#conventionalForeignKey` dit quelle colonne une déclaration couvre). Un troisième, `indexes` (`IEntityIndex`), déclare les
 index COMPOSITES qu'un adaptateur ne sait pas exprimer dans son schéma : Mongoose les applique
 (`schema.index()`), Drizzle les ignore, puisqu'il les déclare dans sa table.
 
@@ -734,19 +738,20 @@ deux, et pas de course).
 
 ## ⚠️ Pièges
 
-| Symptôme                                                      | Cause                                                                                              | Correction                                                                                                  |
-| ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
-| « no entity registered under "X" » au premier appel           | l'entité n'a jamais été inscrite (fichier importé mais `defineEntity` est sans effet de bord)      | l'ajouter à `@entities([...])` sur le module (`entitiesDecorator.ts#entities`)                              |
-| La table n'existe pas alors que l'entité est déclarée         | inscription faite à `onBoot` → course avec `connect()`                                             | inscrire à `onRegister` — c'est ce que fait `entities()` (`entitiesDecorator.ts#entities`)                  |
-| « entity "User" exists on multiple connectors … specify one » | la même entité vit sur plusieurs connecteurs                                                       | préciser le connecteur : `entityRegistry.get("User", "analytics")` (`EntityRegistry.ts#EntityRegistry.get`) |
-| 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#FieldOperators.$null`)     |
-| `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()`                  |
-| `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#IRepository.updateOne`)                    |
-| 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#UpdateOperators`)         |
-| 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#isFieldOperators`)                 |
-| `onOrmReady` ne part plus après un ajout dans l'adapter       | `connect()` a été surchargé                                                                        | surcharger `onConnect()` (`Orm.ts#Orm.onConnect`), 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#resolveOrmFlowEnabled`) ; les deux drivers officiels ont un tap              |
+| Symptôme                                                              | Cause                                                                                                                                         | Correction                                                                                                                                                 |
+| --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| « no entity registered under "X" » au premier appel                   | l'entité n'a jamais été inscrite (fichier importé mais `defineEntity` est sans effet de bord)                                                 | l'ajouter à `@entities([...])` sur le module (`entitiesDecorator.ts#entities`)                                                                             |
+| La table n'existe pas alors que l'entité est déclarée                 | inscription faite à `onBoot` → course avec `connect()`                                                                                        | inscrire à `onRegister` — c'est ce que fait `entities()` (`entitiesDecorator.ts#entities`)                                                                 |
+| « entity "User" exists on multiple connectors … specify one »         | la même entité vit sur plusieurs connecteurs                                                                                                  | préciser le connecteur : `entityRegistry.get("User", "analytics")` (`EntityRegistry.ts#EntityRegistry.get`)                                                |
+| 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#FieldOperators.$null`)                                                    |
+| `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()`                                                                 |
+| `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#IRepository.updateOne`)                                                                   |
+| 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#UpdateOperators`)                                                        |
+| 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#isFieldOperators`)                                                                |
+| `onOrmReady` ne part plus après un ajout dans l'adapter               | `connect()` a été surchargé                                                                                                                   | surcharger `onConnect()` (`Orm.ts#Orm.onConnect`), 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#resolveOrmFlowEnabled`) ; les deux drivers officiels ont un tap                                                             |
+| Un champ vaut `null` dans la réponse alors que la colonne est remplie | repository maison : la fonction qui transforme une ligne en entité ne recopie pas cette colonne — rien ne lève, le champ optionnel reste vide | faire porter au mapping **chaque** champ exposé, et un test qui écrit une ligne complète puis compare tous les champs relus (`IRepository.ts#IRepository`) |
 
 ## 🧪 Tests & couverture
 

package/docs/tutorial-entity.md

@@ -23,6 +23,26 @@ source: "src/packages/@nodefony/orm-core/docs/tutorial-entity.md"
 
 📍 [Documentation](../../../../../docs/index.md) › [ORM — le socle](index.md) › **Créer une entité**
 
+## ⚡ Le geste — une commande
+
+Dans une application, une entité ne s'écrit pas à la main : `create entity` pose tout ce que cette
+page construit pas à pas, câblé et testé.
+
+```bash
+npx nodefony create entity Post title:string content:text views:int --route /api/posts
+```
+
+Elle écrit la table (`nodefony/entity/Post.ts`), ses schémas de validation, un service CRUD, un
+contrôleur REST dont les lectures répondent aussi par la socket, un test unitaire et un test e2e,
+puis inscrit l'entité et le contrôleur dans `index.ts`. Si l'application versionne ses migrations
+(toute application complète), elle écrit puis applique celle de la table à la base de
+développement ; sinon, la table naît au prochain démarrage. Si la base ne répond pas, sa sortie donne la commande à
+relancer (`npx nodefony orm:generate --name posts --apply`). Les options :
+[le raccourci](#le-raccourci--nodefony-create-entity).
+
+La suite de la page construit la même entité à la main : c'est ce qui permet de comprendre ce que
+la commande écrit, et de le retoucher.
+
 ## 🧠 Schéma général
 
 Trois objets s'emboîtent, toujours dans le même ordre. Le tutoriel les parcourt de gauche à
@@ -337,11 +357,14 @@ champs se déclarent en positionnels, façon Rails :
 nodefony create entity Post title:string content:text views:int
 # --id uuid7|uuid4|serial   --soft-delete   --no-timestamps
 # --module <nom>            --no-controller --connector <nom>
+# --no-migrate              (n'écrit pas la migration : la sortie la conseille)
 ```
 
 Elle écrit le fichier d'entité (`nodefony/entity/Post.ts`), les schémas de validation, un service
 CRUD, un controller REST + WebSocket et les tests — puis **câble elle-même** `@entities([...])` et
-`@controllers([...])`. Le schéma vit alors dans son propre fichier, et le point d'entrée ne garde
+`@controllers([...])`, et migre la table neuve quand l'application versionne son schéma — mais seulement si la migration ne touche
+qu'elle : une autre entité modifiée en attente laisse le fichier écrit, NON appliqué, et la sortie
+nomme les tables en trop. Le schéma vit alors dans son propre fichier, et le point d'entrée ne garde
 que l'import plus la ligne du décorateur.
 
 > [!WARNING]
@@ -379,6 +402,12 @@ apportent, jamais sur leur nom.
 > **nombre** de lignes touchées. Un verbe unique masquerait cette différence de garantie, qui est
 > précisément ce qu'on veut choisir en connaissance de cause.
 
+**Une clé qui vaut `undefined` vaut une clé absente.** Les écritures du service CRUD acceptent
+`PartialInput<T>` (`types/PartialInput.ts#PartialInput`) et retirent ces clés avant la persistance
+(`AbstractCrudService.updateOne()`, `AbstractCrudService.ts#AbstractCrudService.updateOne`) : un champ
+facultatif d'un schéma Zod (`.optional()`, `.partial()`) qui arrive `undefined` ne touche pas la
+colonne. Pour la **vider**, écrire `null`.
+
 Quelques usages, un par garantie :
 
 ```ts ignore

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodefony/orm-core",
-  "version": "10.0.0-beta.4",
+  "version": "10.0.0-beta.6",
   "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-beta.4"
+    "nodefony": "^10.0.0-beta.6"
   },
   "devDependencies": {
-    "@types/node": "26.6.5",
-    "nodefony": "^10.0.0-beta.4",
-    "vitest": "5.0.5"
+    "@types/node": "26.6.6",
+    "nodefony": "^10.0.0-beta.6",
+    "vitest": "5.1.0"
   },
   "repository": {
     "type": "git",