@nodefony/orm-core — le contrat de persistance

stable@nodefony/orm-coremis à jour 2026-07-19

La prise de courant de la couche données : ton code métier branche IRepository, et derrière la prise il y a Drizzle (SQL) ou Mongoose (MongoDB) — sans que le métier le sache. orm-core ne contient aucun driver : il définit les contrats (IOrm, IRepository, IEntity, ITransaction), les registres qui les relient, les critères de recherche portables, la pagination et le socle CRUD. Promesse tenue : changer d’ORM sans réécrire le métier.

📍 Documentation › ORM — le socle

🧠 Schéma général#

Une lecture en une phrase : le métier ne parle qu’aux contrats du milieu ; les drivers du bas sont interchangeables, et les registres savent quel driver sert quelle entité.

🧭 Par où commencer#

Trois parcours selon ce que tu viens faire. L’ordre compte — chaque étape suppose la précédente.

Je persiste ma première table — je n’ai encore rien en base.

1. Créer une entité, de zéro à find() — le pas-à-pas complet, sans rien supposer connu. Commence là si tu débutes.
2. La section 🚀 Démarrage rapide de cette page — la même chose en condensé, copiable telle quelle.
3. @nodefony/drizzle — le driver SQL par défaut : où se déclare le connecteur, quels dialectes, comment se crée la table.

J’écris des requêtes qui tiennent — je sais persister, je veux interroger correctement.

1. 🔎 Les critères de recherche — l’égalité, les opérateurs $, et le piège du null en SQL.
2. 📄 Pagination portable — pourquoi paginate() évite le COUNT(*).
3. ⚙️ Le socle CRUD — mettre la logique dans un service, pas dans un controller.
4. 🧰 Les contrats — la liste complète des verbes, et lequel choisir (updateOne vs updateMany vs upsert).

Je choisis mon backend / j’en branche un nouveau — décision d’architecture.

1. 🗄️ Backends pris en charge — ce que couvre chaque driver, et ce qu’il ne couvre pas (choix assumé, pas un manque).
2. 🧩 Extension — le contrat minimal d’un adapter.
3. ADR-0003 — les risques de l’abstraction, écrits avant qu’elle ne soit validée.
4. Guide persistance — déclarer l’infra d’une app complète (base, stores de session, migrations).

🗂️ Le catalogue#

Choisir en cinq secondes avec le tableau, puis lire la card correspondante.

<!-- prettier-ignore -->

📖 Lexique#

Qu’est-ce que c’est ?#

Une prise normalisée entre ton code métier et la base de données.

Sans elle, ton service appelle directement Drizzle : db.select().from(users).where(eq(users.id, x)). Ça marche — jusqu’au jour où l’application doit passer sur MongoDB, ou simplement changer de version majeure d’ORM. Alors chaque service, chaque controller, chaque commande CLI est à réécrire, parce que la syntaxe du moteur a fui partout dans le métier.

orm-core interpose un contrat : le métier écrit articles.find({ views: { $gte: 100 } }), et c’est le driver qui traduit — en gte() Drizzle, en $gte Mongo. Le vocabulaire du moteur ne franchit jamais la frontière.

C’est le patron Repository (une collection d’entités qu’on interroge), monté en ports & adapters : orm-core publie les ports, les drivers fournissent les adapters. Conséquence structurante — orm-core n’importe aucun driver, et ne peut pas en importer : c’est ce qui garantit que la dépendance va bien du concret vers l’abstrait, et jamais l’inverse.

ℹ️ 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.

La vision Nodefony#

Trois partis pris expliquent la forme exacte de l’API, et ils méritent d’être connus avant de l’utiliser.

1. La portabilité visée est celle du TEMPS, pas de l’espace. L’objectif officiel est de pouvoir changer d’ORM au fil des années sans réécrire le métier — pas de faire tourner quatre ORM simultanément. Le multi-connecteur reste possible (analytics à côté de default), mais ce n’est pas ce qui justifie l’API. C’est écrit noir sur blanc dans l’ADR-0003, risque n°2 — sur-dimensionner pour ce cas serait une erreur.

2. L’abstraction assume de ne pas tout couvrir — et fournit la trappe. Une jointure arbitraire, une CTE, une fonction fenêtre : ça ne se porte pas d’un moteur SQL à MongoDB. Plutôt que d’inventer un langage de requête maison, IOrm.getNativeConnection() (^IOrm.ts:51) rend la connexion brute du driver. Le contrat est honnête : plus tu recours à la trappe, moins ton code est portable — et tu le sais en l’écrivant, parce que l’appel est visible.

3. Une erreur doit se produire à l’identique sur tous les drivers. C’est le point le plus subtil. Un critère qui référence un champ inexistant ({ emial: "…" }) serait ignoré par Drizzle — la condition disparaît, la requête rend toute la table — et conservé par Mongoose, qui rend zéro résultat. Le même code, deux comportements opposés, aucune erreur : la promesse de portabilité s’effondre en silence. D’où UnknownCriteriaField (^errors.ts:23), levée par les deux drivers : on échoue tôt, et pareil.

La même règle vaut pour les options : une forme de tri voisine mais fausse — { age: "asc" } au lieu de [["age", "ASC"]] — faisait partir la requête sans ORDER BY, et l’appelant recevait des lignes non triées qu’il croyait triées. assertOrderOption() (^{readOptions.ts:39}) est appelée par chaque adapter en amont de sa requête et lève InvalidOrderOption (^errors.ts:65) ; le sens est vérifié en casse exacte, parce qu’un "desc" minuscule aurait trié à l’envers. Normaliser une entrée utilisateur (casse, champ:sens) appartient à la frontière qui la reçoit — parsePageQuery le fait —, jamais au repository.

4. Le contrat va plus loin que le CRUD scolaire. IRepository (^{IRepository.ts:197}) porte quinze verbes, pas cinq : les opérations atomiques (upsert, increment, updateOne, findOneAndDelete) sont dans le contrat parce qu’un SELECT suivi d’un UPDATE est une course, et qu’une course en base ne se rattrape pas côté application.

🚀 Démarrage rapide#

Vu d’une application générée par nodefony create app. Trois fichiers, et une base qui répond.

1. Déclarer la connexion#

Le driver et la cible physique vivent dans la config, jamais dans l’entité — c’est ce qui rend le changement de moteur indolore.

// nodefony.config.ts — un seul connecteur, en SQLite : zéro installation.
export default defineConfig(() => ({
  modules: [
    "@nodefony/framework",
    use("@nodefony/drizzle", {
      connectors: {
        // "default" est le NOM de la connexion, pas celui du moteur.
        default: { dialect: "sqlite", filename: "nodefony/databases/app.db" },
      },
    }),
  ],
}));

2. Décrire l’entité, et la déclarer au module#

defineEntity() (^{defineEntity.ts:48}) n’a aucun effet de bord : importer ce fichier n’inscrit rien. C’est le décorateur entities() (^{entitiesDecorator.ts:56}) posé sur le module qui inscrit la liste, à la phase onRegister — avant que le connecteur n’ouvre et ne crée les tables.

// src/modules/blog/index.ts
import { randomUUID } from "node:crypto";
import { integer, sqliteTable, text } from "drizzle-orm/sqlite-core";
import { Module } from "nodefony";
import { defineEntity, entities } from "@nodefony/orm-core";

// Le schéma est du Drizzle NATIF : tous les types du moteur restent disponibles.
export const articleTable = sqliteTable("Article", {
  id: text("id")
    .primaryKey()
    .$defaultFn(() => randomUUID()),
  title: text("title").notNull(),
  // Défaut posé côté JS : le DDL dérivé n'émet pas les DEFAULT SQL.
  views: integer("views")
    .notNull()
    .$defaultFn(() => 0),
  publishedAt: integer("publishedAt"), // null = brouillon
});

/** Une ligne d'`Article`, telle que la rend le repository. */
export interface ArticleRow {
  id: string;
  title: string;
  views: number;
  publishedAt: number | null;
}

// Pas de `connector` ici : il est résolu au boot (défaut `"default"`).
export const ArticleEntity = defineEntity({
  name: "Article",
  module: "blog",
  schema: articleTable,
});

@entities([ArticleEntity])
class Blog extends Module {}

export default Blog;

3. Lire et écrire#

Le repository s’obtient par le registre (ou par injection dans un controller). À partir de là, plus une ligne de code ne nomme Drizzle.

// nodefony/service/ArticleService.ts
import { AbstractCrudService, ormRegistry, paginate } from "@nodefony/orm-core";
import type { IRepository } from "@nodefony/orm-core";

/** Le type de ligne exporté à côté de l'entité (rappelé ici pour l'extrait). */
interface ArticleRow {
  id: string;
  title: string;
  views: number;
  publishedAt: number | null;
}

/** Le métier vit dans le service — REST, WebSocket et CLI l'appellent tous. */
export class ArticleService extends AbstractCrudService<ArticleRow> {
  constructor(repository: IRepository<ArticleRow>) {
    super("articleService", repository);
  }
}

export async function demo(): Promise<void> {
  const articles = ormRegistry
    .get("default")
    .getRepository<ArticleRow>("Article");

  await articles.create({ title: "Bonjour" });

  // `$null: true` → IS NULL. Une égalité `= NULL` serait toujours fausse en SQL.
  const brouillons = await articles.find({ publishedAt: { $null: true } });

  // Compteur atomique : jamais de lecture-modification-écriture, donc jamais de course.
  await articles.increment({ title: "Bonjour" }, { views: 1 });

  // Une page, sans jamais matérialiser toute la table.
  const page = await paginate(articles, {
    limit: 20,
    order: [["views", "DESC"]],
  });

  console.log(brouillons.length, page.total, page.hasNext);
}

Ce qu’on observe#

Au démarrage, le driver crée la table et le récap de boot annonce la connexion (reportOrmBootLines(), ^{ormWiring.ts:60}). Le data plane confirme depuis l’extérieur :

# Les connecteurs enregistrés et leur état
curl -s http://localhost:5151/nodefony/orm/api/orms
# [{"name":"default","default":true,"connected":true,"entityCount":1}]

# Le modèle canonique : colonnes + relations, tel que l'ERD Studio le consomme
curl -s http://localhost:5151/nodefony/orm/api/entity/Article

# Le nombre de lignes par entité (un COUNT(*) par table, à la demande)
curl -s http://localhost:5151/nodefony/orm/api/counts
# {"Article":1}

🏗️ Architecture interne#

Deux registres, un cycle de vie. Tout le reste en découle.

entityRegistry (^{EntityRegistry.ts:147}) 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 de nom lève (OrmRegistry.register(), ^{OrmRegistry.ts:26}) : deux connexions homonymes seraient un bug silencieux, jamais une intention.

La phase d’inscription est le piège n°1. Les connecteurs se branchent à onBoot et créent les tables à ce moment. Inscrire une entité à onBoot la met donc en course avec connect() : selon l’ordre des écouteurs, la table existe ou non. entities() s’accroche à onRegister (^{entitiesDecorator.ts:66}), strictement antérieur — sûr par construction. C’est la différence de comportement avec @controllers, qui lui reste à onBoot.

Orm.connect() (^Orm.ts:54) est une template method : elle mesure la latence, alimente le moniteur de connexion, puis émet onOrmReady. Un adapter surcharge onConnect() (^Orm.ts:74), et jamais connect() — sinon l’événement et l’instrumentation disparaissent.

🧰 Les contrats — la surface publique#

Quatre interfaces. Les signatures exactes vivent dans le graphe généré (jq '.symbols.IRepository' .ai/symbols.json) — elles ne sont pas recopiées ici, elles divergeraient.

IOrm — une connexion logique#

IOrm (^IOrm.ts:12) représente une connexion nommée. Il ouvre et ferme (connect/disconnect), rend les repositories (IOrm.getRepository(), ^IOrm.ts:33), ouvre une transaction (IOrm.transaction(), ^IOrm.ts:41) et expose la trappe native (IOrm.getNativeConnection(), ^IOrm.ts:51).

Quatre méthodes sont optionnelles — un adapter qui ne les implémente pas dégrade proprement au lieu d’échouer : describeEntity() (^IOrm.ts:78, colonnes pour l’ERD), describeConnection() (^IOrm.ts:71, driver et cible sans credential), ping() (^IOrm.ts:82, aller-retour réel) et probe() (^IOrm.ts:92, métriques driver, qui ne doit jamais lever).

IRepository — les quinze verbes#

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.

❗ Important

updateOne est atomique par construction : une seule requête (UPDATE … RETURNING en SQL, findOneAndUpdate en Mongo), jamais un UPDATE suivi d’une relecture. La différence n’est pas cosmétique : la relecture rendrait null à tort dès que le critère porte sur un champ qu’on vient de modifier — updateOne({ status: "pending" }, { status: "done" }) ne retrouve plus rien après coup (^{IRepository.ts:221}).

Quelques usages, un par garantie :

// Insertion par lots : une seule requête, l'ordre est conservé.
await articles.createMany([{ title: "A" }, { title: "B" }]);

// Existence sans charger la ligne (ni compter la table).
if (await articles.exists({ title: "A" })) {
  /* … */
}

// Claim-and-remove : on prend le job ET on le retire, sans que deux workers l'obtiennent.
const job = await jobs.findOneAndDelete({ status: "queued" });

// Upsert : le seuil ne recule jamais, même sur deux appels simultanés.
await quotas.upsert(
  { userId },
  { seuil: { $max: Date.now() } },
  { createdAt: Date.now() },
);

L’upsert mérite une note. Son DO UPDATE est inconditionnel — MySQL n’accepte pas de WHERE sur ON DUPLICATE KEY UPDATE. Une valeur qui ne doit jamais régresser porte donc sa condition dans la valeur écrite, via UpdateOperators (^{IRepository.ts:94}) : $max/$min se traduisent en MAX() (sqlite), GREATEST() (postgres, mysql) ou $max natif (Mongo) — une instruction atomique sur les quatre backends.

IEntity — la description d’une table#

IEntity (^{IEntity.ts:37}) porte un nom logique, un connector (le nom d’une connexion, jamais d’un moteur), un schema natif du driver, et des relations déclaratives (IEntityRelation, ^IEntity.ts:4). Deux champs facultatifs servent la lisibilité d’un gros modèle : module (qui apporte l’entité) et domain (^{IEntity.ts:58}, la classification métier — l’axe qui rend navigable une base de plusieurs centaines de tables).

Dans une application, on ne construit pas un IEntity à la main : on écrit un IEntityDefinition (^{defineEntity.ts:15}) — le même objet sans connector, justement parce que le connecteur est une donnée de configuration, résolue au boot.

ITransaction — tout ou rien#

ITransaction (^{ITransaction.ts:8}) expose commit, rollback, savepoint (^{ITransaction.ts:20}), rollbackTo et la trappe getNative. En pratique on ne l’appelle presque jamais directement : on passe par IOrm.transaction(), qui valide si le travail se résout et annule s’il lève.

await orm.transaction(async (tx) => {
  const auteur = await users.withTransaction(tx).create({ email: "x@y.z" });
  await articles
    .withTransaction(tx)
    .create({ title: "Hello", userId: auteur.id });
  // une exception ici ⇒ rollback des DEUX écritures ; sinon commit automatique
});

withTransaction(tx) rend une vue du repository, pas un état global : rien n’est stocké dans un contexte implicite, donc deux transactions concurrentes ne peuvent pas se mélanger.

⚠️ Attention

Une transaction porte sur un seul connecteur. Les transactions réparties (2PC) ne sont pas garanties : écrire dans default et analytics dans un même transaction() ne donne aucune atomicité entre les deux (^{ITransaction.ts:5}).

🔎 Les critères de recherche#

Un critère est un objet. Chaque clé est un champ ; chaque valeur est soit une égalité, soit un objet d’opérateurs.

await articles.find({ title: "Hello" }); // égalité
await articles.find({ views: { $gte: 100, $lt: 1000 } }); // deux opérateurs = ET
await articles.find({ id: { $in: ids } }); // appartenance
await articles.find({ title: { $like: "Hel%" } }); // motif SQL
await articles.find({ publishedAt: { $null: false } }); // IS NOT NULL

Les dix opérateurs reconnus sont figés dans OPERATOR_KEYS (^{criteria.ts:13}) — source unique partagée par tous les adapters : $eq $ne $gt $gte $lt $lte $in $nin $like $null. Plusieurs opérateurs sur un même champ se combinent en ET.

Le null est le piège que le contrat désamorce. En SQL, colonne = NULL est toujours faux : un filtre « la colonne est vide » écrit naïvement ne matcherait jamais rien, sans erreur. Deux formes équivalentes le résolvent — la valeur nue { publishedAt: null } et l’opérateur { publishedAt: { $null: true } } (^{IRepository.ts:65}), qui produisent tous deux un IS NULL. La valeur nue n’est d’ailleurs ouverte par le typage que si le champ est nullable (FieldCriteria, ^{IRepository.ts:128}) : chercher IS NULL sur une colonne non-nullable est une erreur de raisonnement, et le compilateur la refuse.

Comment un objet est reconnu comme filtre plutôt que comme valeur : isFieldOperators() (^{criteria.ts:42}) ne l’interprète que si toutes ses clés sont des opérateurs connus. Une colonne 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 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).

📄 Pagination portable#

paginate() (^{paginate.ts:47}) construit une page au-dessus des primitives que tout adapter implémente déjà (find avec limit/offset/order, et count). Aucun driver n’a eu à changer.

Deux décisions le rendent utilisable sur une grosse table :

1. hasNext sans COUNT — on demande limit + 1 lignes ; si la ligne supplémentaire arrive, il y a une suite, et on la retire du résultat.
2. total optionnel — le COUNT(*) est coûteux, il n’est payé que si withTotal n’est pas false. C’est la distinction « Page » (avec total) et « Slice » (sans), reprise de Spring Data.

Les bornes sont normalisées plutôt que propagées : un limit de 0 ou un offset négatif est ramené dans le domaine valide (^{paginate.ts:28}) — un find({ limit: 0 }) a un comportement qui dépend du dialecte, donc on ne le laisse pas sortir.

Le contrat de page lui-même (IPage, IPageQuery) vit dans le cœur (^{src/nodefony/src/types/IPage.ts:22}), pas ici : il est partagé par tous les stores paginés du framework (sessions HTTP, jetons, audit…). orm-core ne fait que l’enrichir du criteria typé, sous le nom PageQuery (^IPage.ts:18).

⚙️ Le socle CRUD — AbstractCrudService#

Une classe à étendre pour que chaque entité expose son CRUD de la même manière, et qu’il n’y ait qu’un seul endroit à modifier quand la règle métier change.

export class ArticleService extends AbstractCrudService<ArticleRow> {
  constructor(repository: IRepository<ArticleRow>) {
    super("articleService", repository);
  }

  /** Valide avant insertion : un rejet devient un 422, quel que soit le transport. */
  protected override beforeCreate(
    data: Partial<ArticleRow>,
  ): Partial<ArticleRow> {
    return createArticleSchema.parse(data) as Partial<ArticleRow>;
  }
}

AbstractCrudService (^{AbstractCrudService.ts:37}) sépare volontairement deux régimes :

• Lectures (find, findOne, findById, count, findPage) — délégation pure. Aucun hook, aucun événement : c’est le chemin chaud, il ne doit rien payer.
• Mutations (create, updateOne, delete) — encadrées par des hooks template method (beforeCreate, ^{AbstractCrudService.ts:185}, et ses six frères) puis un événement de cycle de vie onCreated / onUpdated / onDeleted, émis seulement si la mutation a eu lieu (^{AbstractCrudService.ts:167}). L’audit, l’invalidation de cache ou une notification Studio s’y abonnent sans toucher au service.

findPage() (^{AbstractCrudService.ts:110}) est la primitive à utiliser pour toute liste d’administration : elle ne charge qu’une page, quelle que soit la taille de la table.

⚠️ Attention

Ce service est un singleton partagé (il étend Service, donc l’injection l’instancie une fois). C’est légitime parce qu’il est sans état : ne jamais écrire this.currentUser = … pendant une requête. L’utilisateur courant, le tenant, la transaction voyagent dans le contexte — jamais sur l’instance.

🗄️ Backends pris en charge#

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:868}) et MongooseRepository.upsert() (^{MongooseRepository.ts:343}).

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 :

ℹ️ 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.

🧩 Extension — brancher son propre driver#

Le contrat minimal tient en peu de choses, parce que orm-core fournit déjà la plomberie.

1. Étendre Orm (^Orm.ts:29) : implémenter onConnect(), disconnect(), isConnected(), getRepository(), transaction(), getNativeConnection(). L’enregistrement dans ormRegistry est fait par le constructeur de base — il n’y a rien à écrire. Ne jamais surcharger connect() : c’est la template method qui émet onOrmReady et instrumente la latence.
2. Implémenter IRepository<T> en traduisant les critères. isFieldOperators() (^{criteria.ts:42}) et isUpdateOperators() (^{criteria.ts:87}) sont fournis pour que la détection soit identique partout — les réécrire, c’est fabriquer une divergence.
3. Lever UnknownCriteriaField (^errors.ts:23) sur un champ inconnu, et appeler assertOrderOption() (^{readOptions.ts:39}) une fois, en amont, sur options.order. C’est le prix de la promesse de portabilité : un adapter qui retesterait la forme lui-même finirait par diverger de l’autre.
4. Câbler le data plane en une ligne à onKernelBoot : wireOrmAdminPlane(this.kernel) (^{ormWiring.ts:31}) monte les routes admin, la santé et le diagnostic riche. Et resolveOrmFlowEnabled(kernel) (^{ormWiring.ts:96}) décide si la sonde de flux s’allume — hors production par défaut, NF_ORM_FLOW=1 force.
5. Déclarer les capacités dans package.json (nodefony.storeKind, nodefony.stores) : c’est ainsi que le framework sait ce que ton adapter sait faire.

Les méthodes optionnelles d’IOrm (describeEntity, describeConnection, ping, probe) s’ajoutent ensuite : sans elles l’adapter fonctionne, il est simplement moins observable.

📡 Observabilité — Studio#

Deux sondes indépendantes, et un data plane qui les expose. La séparation est délibérée : mesurer la santé ne doit pas coûter le débit, et observer le débit ne doit pas réveiller la base.

connectionMonitor (^{ConnectionMonitor.ts:197}) suit le cycle de vie d’une connexion : première connexion, reconnexions, erreurs récentes, et une fenêtre de latence de ping (ConnectionMonitor.recordPing(), ^{ConnectionMonitor.ts:106}). 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 moyenne et EWMA, pire latence, et un anneau borné à vingt requêtes lentes. Trois propriétés le rendent sûr en production :

• éteint par défaut — enabled = false : coût nul tant qu’on ne l’allume pas ;
• lazy — la table de statistiques n’est allouée qu’au premier enregistrement ;
• le SQL n’est capté que sur le chemin lent (QueryFlowMonitor.record(), ^{QueryFlowMonitor.ts:101}) : jamais de sérialisation de requête au cas nominal ;
• aucune persistance — tout est en mémoire vive. Une sonde n’écrit jamais dans la base qu’elle 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:421}) expose huit points d’entrée, tous filtrables par ?connector= :

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 (text-to-SQL, RAG). Le dessin n’en est qu’une projection.

Côté Studio, trois écrans le consomment : /nodefony/orm (vue d’ensemble), /nodefony/orm/:pid (le détail d’un worker, en cluster) et /nodefony/orm-entity (le détail d’une entité).

⚡ Performance & mémoire#

Le socle est conçu pour ne rien coûter quand il ne sert pas.

Deux conséquences pratiques pour ton code : préférer exists() à findOne() !== null (aucune colonne n’est chargée), et increment() à une lecture suivie d’une écriture (une requête au lieu de deux, et pas de course).

⚠️ Pièges#

🧪 Tests & couverture#

Les compteurs de cette page sont recomptés à chaque génération — jamais figés dans le texte. Ils portent sur les tests unitaires du socle : tests/unit/** couvre les deux registres, les critères, la pagination, le service CRUD, les décorateurs, les deux moniteurs, le câblage et le data plane.

Ce que ces tests prouvent : la logique pure du socle, sans base de données. C’est cohérent — orm-core ne contient aucun driver, donc rien à connecter.

Ce qu’ils ne prouvent pas, et où c’est prouvé. Le contrat IRepository n’a de sens qu’exécuté sur une vraie base. Cette preuve vit chez les drivers, sous forme de bancs de contrat — une même suite rejouée par dialecte :

• @nodefony/drizzle — tests/integration/repository-contract.ts est le banc commun, rejoué par repository-contract-sqlite.test.ts (toujours exécuté, base en mémoire), repository-contract-postgres.e2e.test.ts et repository-contract-mysql.e2e.test.ts ;
• @nodefony/mongoose — tests/integration/orm-core-mongoose.test.ts exerce le même contrat côté documentaire.

⚠️ Attention

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 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 ».

Ce qui manque aujourd’hui, dit franchement : pas de banc de charge ni de test mémoire dédié au socle (le coût réel se mesure chez les drivers, sur une vraie base) — voir le skill nodefony-load-test pour monter un banc, et nodefony-check-memory-health pour la gate mémoire du pipeline. Couverture de lignes : npm run coverage dans le module (le pourcentage vit dans le rapport vitest, jamais dans cette page — il vieillirait).

🔗 Pour aller plus loin#

• ⬆️ Retour : Toute la documentation · Par où démarrer
• 🧭 Les drivers : @nodefony/drizzle (SQL, par défaut) · @nodefony/mongoose (MongoDB) et sa configuration
• 🚀 Débuter : Créer une entité, de zéro à find()
• 🏛️ Transverse : guide persistance · stockage de session · configuration d’une application
• 📐 Décisions : ADR-0003 — abstraction Repository multi-ORM
• 📖 Lexique général du framework.