@nodefony/orm-core 10.0.0-beta.1 → 10.0.0-beta.3

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/docs/index.md

@@ -540,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).
@@ -610,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:866`) et `MongooseRepository.upsert()`
-(`MongooseRepository.ts:422`).
+`DrizzleRepository.upsert()` (`DrizzleRepository.ts:1091`) et `MongooseRepository.upsert()`
+(`MongooseRepository.ts:439`).
 
 | Capacité                               | `@nodefony/drizzle`                 | `@nodefony/mongoose`                         |
 | -------------------------------------- | ----------------------------------- | -------------------------------------------- |
@@ -620,8 +620,8 @@ 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:1971`)          | oui (`MongooseOrm.ts:649`)                   |
-| Sonde de flux (requêtes/s, lentes)     | oui — alimente `queryFlowMonitor`   | non câblée                                   |
+| 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** : chaque adapter déclare ce qu'il porte dans son `package.json`, clé
@@ -691,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
@@ -743,7 +746,7 @@ deux, et pas de course).
 | 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: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
 
@@ -769,7 +772,7 @@ suite rejouée par dialecte :
 > **Un compteur vert ne prouve pas qu'une base a été touchée.** Les bancs sur serveur réel se
 > **skippent** quand leur variable d'infra est absente — et un test skippé compte comme vert.
 > PostgreSQL exige `NF_PG_URL`, MySQL/MariaDB `NF_MYSQL_URL`, MongoDB `NF_MONGO_TEST_URI`. La source
-> unique de ces variables et des commandes Docker correspondantes est `vitest.gates.ts` à la racine
+> unique de ces variables et des commandes Docker correspondantes est `scripts/test/vitest/gates.ts` à la racine
 > du dépôt ; les suites concernées affichent un récapitulatif de couverture en fin d'exécution
 > (`gateReporter`). **Lire ce bloc avant de conclure « vert ».**
 

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é
 
@@ -465,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
@@ -530,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                    |
@@ -559,7 +560,7 @@ dialecte — `@nodefony/drizzle` (sqlite en mémoire, PostgreSQL et MySQL en end
 > [!WARNING]
 > Un compteur vert ne prouve pas qu'une base a été touchée : les bancs sur serveur réel se
 > **skippent** faute de leur variable d'infra, et un test skippé compte comme vert. La source
-> unique de ces variables et des commandes Docker correspondantes est `vitest.gates.ts` à la
+> unique de ces variables et des commandes Docker correspondantes est `scripts/test/vitest/gates.ts` à la
 > racine du dépôt ; les suites concernées affichent leur récapitulatif en fin d'exécution.
 
 ## 🔗 Pour aller plus loin

package/package.json

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