---
title: "Référence d'API — @nodefony/orm-core — racine"
source: docs/api/orm-core/racine.md
url: https://nodefony.github.io/nodefony-core/docs/api/orm-core/racine/
---


[Documentation](../../../) › [Référence d'API](../../) › [`@nodefony/orm-core`](../) › racine

> Générée depuis les déclarations de types publiées de `@nodefony/orm-core` **10.0.0-beta.6** : exactement ce que reçoit une application qui l'installe. Cette page n'existe dans aucun dépôt — pour la corriger, on corrige le TSDoc du code.

## `@nodefony/orm-core`

`import { … } from "@nodefony/orm-core"` — 51 symboles.

### Classes (9)

#### `AbstractCrudService`

```ts
abstract class AbstractCrudService<T, R extends IRepository<T> = IRepository<T>> extends Service
```

Service CRUD **générique** — socle réutilisable au-dessus d'un `IRepository`.

- `protected readonly repository: R`
- `constructor(name: string, repository: R, ...wiring: ServiceWiring)`
- `find(criteria?: Criteria<T>, options?: RepositoryReadOptions): Promise<T[]>` — Liste les entités correspondant au critère (toutes si omis).
- `findOne(criteria: Criteria<T>, options?: RepositoryReadOptions): Promise<T | null>` — Première entité correspondant au critère, ou `null`.
- `findById(id: string, options?: RepositoryReadOptions): Promise<T | null>` — Entité par clé primaire `id`, ou `null`.
- `count(criteria?: Criteria<T>): Promise<number>` — Compte les entités correspondant au critère (toutes si omis).
- `findPage(page: PageQuery<T>): Promise<IPage<T>>` — Liste **une page** d'entités — pagination **native** (jamais matérialiser toute la collection).
- `protected readonly searchableFields: ReadonlyArray<keyof T & string>` — Champs sur lesquels `?q=` cherche — **vide par défaut, donc `q` est refusé**.
- `create(data: PartialInput<T>): Promise<T>` — Crée une entité : `beforeCreate` → persistance → `afterCreate` → `onCreated`.
- `updateOne(criteria: Criteria<T>, data: PartialInput<T>): Promise<T | null>` — Met à jour **au plus une** entité : `beforeUpdate` → persistance atomique → `afterUpdate` → `onUpdated`.
- `delete(criteria: Criteria<T>): Promise<number>` — Supprime : `beforeDelete` → persistance → `afterDelete` → `onDeleted`.
- `protected beforeCreate(data: PartialInput<T>): PartialInput<T> | Promise<PartialInput<T>>` — Transforme/valide les données avant création (ex.
- `protected afterCreate(_entity: T): void | Promise<void>` — Effet de bord après création (ex.
- `protected beforeUpdate(_criteria: Criteria<T>, data: PartialInput<T>): PartialInput<T> | Promise<PartialInput<T>>` — Transforme/valide les données avant mise à jour.
- `protected afterUpdate(_entity: T): void | Promise<void>` — Effet de bord après mise à jour.
- `protected beforeDelete(_criteria: Criteria<T>): void | Promise<void>` — Garde/validation avant suppression (ex.
- `protected afterDelete(_criteria: Criteria<T>, _removed: number): void | Promise<void>` — Effet de bord après suppression (ex.

#### `Entity`

```ts
abstract class Entity<S = unknown, M = unknown> implements IEntity<S, M>
```

Classe de base abstraite d'une entité, indépendante du driver ORM.

- `abstract readonly name: string` — Nom logique de l'entité (clé de lookup, ex.
- `abstract readonly connector: string` — Connexion nommée cible, telle que déclarée en config (clé du `ormRegistry`).
- `model?: M` — Modèle compilé natif, renseigné après connexion de l'ORM.
- `readonly relations?: ReadonlyArray<IEntityRelation>` — Relations déclarées vers d'autres entités (par nom logique).
- `abstract getSchema(): S` — Construit la définition de schéma propre au driver.
- `get schema(): S` — Définition de schéma propre au driver (délègue à `Entity.getSchema`).
- `register(): this` — Enregistre cette entité dans le `entityRegistry` process-wide.

#### `EntityRegistry`

```ts
class EntityRegistry
```

Registre cross-ORM des entités, indexé par nom logique puis par connecteur.

- `register(entity: IEntity): void` — Enregistre une entité pour son connecteur cible.
- `get(name: string, connector?: string): IEntity` — Résout une entité par nom (et connecteur si plusieurs candidats).
- `has(name: string, connector?: string): boolean` — Indique si une entité (optionnellement sur un connecteur précis) est enregistrée.
- `list(): IEntity[]` — Liste toutes les entités enregistrées, tous connecteurs confondus.
- `unregister(name: string, connector?: string): boolean` — Retire une entité du registre (teardown tests / hot-reload).

#### `InvalidOrderOption`

```ts
class InvalidOrderOption extends Error
```

Levée quand l'option de lecture `order` n'est pas un tableau de couples `[champ, "ASC" | "DESC"]`.

- `readonly entity: string` — Nom logique de l'entité ciblée.
- `readonly received: string` — Ce qui a été reçu, décrit par sa FORME (jamais la valeur : pas de fuite de données).
- `constructor(entity: string, received: string)`

#### `Orm`

```ts
abstract class Orm extends Service implements IOrm
```

Classe de base abstraite de tout ORM Nodefony — câble `Service` (DI, Syslog, bus d'événements) et le contrat `IOrm`, et s'auto-enregistre dans le `ormRegistry` process-wide à la construction.

- `protected alive: boolean` — État de vie de la connexion — source UNIQUE de `isConnected()`.
- `get liveness(): "events" | "assumed"` — **Ce que cet adapter sait VRAIMENT de l'état de sa connexion** — déclaré, jamais supposé.
- `constructor(name: string, container?: Container, notificationsCenter?: Event | false | null, options?: DefaultOptionsService)`
- `connect(): Promise<void>` — Connecte le driver puis émet `onOrmReady`.
- `protected connectionLost(reason: string): void` — **Le driver a PERDU la connexion** — à appeler par l'adapter depuis l'événement natif de son driver (`pool.on("error")` côté `pg`, `connection.on("disconnected")` côté Mongoose…).
- `protected connectionRestored(): void` — **Le driver a RÉTABLI la connexion** — à appeler par l'adapter depuis l'événement natif correspondant (`pool.on("connect")`, `reconnected`…).
- `protected heartbeatMs: number` — Période du battement de cœur, en millisecondes.
- `protected heartbeatTimeoutMs: number` — Délai au-delà duquel un battement sans réponse vaut une PERTE.
- `protected startHeartbeat(): void` — Démarre le battement si l'adapter sait répondre à un `ping()` et que la période n'est pas nulle.
- `describeResilience(): IOrmResilience` — Décrit le mécanisme de résilience TEL QU'IL TOURNE — lecture pure, pour le data plane (`connection/health`) : période et montre du battement, battement actif ou non, perte en souffrance.
- `protected stopHeartbeat(): void` — Arrête le battement et libère la minuterie.
- `protected beatNow(): void` — **Bat MAINTENANT**, sans attendre la fin de la période.
- `isConnected(): boolean` — Indique si la connexion est active — **implémentation UNIQUE**, portée par la classe de base et non par chaque adapter.
- `protected abstract onConnect(): Promise<void>` — Établit la connexion native du driver (compilation des entités, pool...).
- `abstract disconnect(): Promise<void>` — Ferme la connexion et libère le pool.
- `abstract getRepository<T = unknown>(name: string): IRepository<T>` — Repository typé d'une entité enregistrée.
- `abstract transaction<R>(work: (tx: ITransaction) => Promise<R>): Promise<R>` — Exécute un travail transactionnel (commit si résolu, rollback si rejeté).
- `abstract getNativeConnection<C = unknown>(): C` — Expose la connexion native du driver (trappe SQL/commandes brutes).
- `describeEntity(_name: string): IColumnInfo[]` — Décrit les colonnes d'une entité pour le graphe canonique.
- `describeConnection(): IConnectionInfo` — Décrit la connexion sous-jacente (driver + cible).

#### `OrmRegistry`

```ts
class OrmRegistry
```

Registre process-wide des instances ORM enregistrées sous un nom unique.

- `register(name: string, orm: IOrm): void` — Enregistre une instance ORM sous un nom unique.
- `get(name: string): IOrm` — Résout l'ORM enregistré sous un nom.
- `has(name: string): boolean` — Indique si un ORM est enregistré sous ce nom.
- `list(): string[]` — Liste les noms des ORM enregistrés.
- `unregister(name: string): boolean` — Retire un ORM du registre (utile au teardown des tests / hot-reload).

#### `ReferencedEntityError`

```ts
class ReferencedEntityError extends Error
```

Levée quand une suppression viserait une entité encore RÉFÉRENCÉE par une relation obligatoire d'une autre entité.

- `readonly entity: string` — Entité dont la suppression est refusée (nom logique).
- `readonly referencedBy: string` — Entité qui la référence encore (nom logique).
- `readonly field: string` — Champ de référence de `ReferencedEntityError.referencedBy`.
- `constructor(entity: string, referencedBy: string, field: string)`

#### `SavepointNotSupportedError`

```ts
class SavepointNotSupportedError extends Error
```

Levée par `ITransaction.savepoint()` / `rollbackTo()` sur un moteur qui ne porte PAS de savepoints (MongoDB).

- `readonly driver: string` — Moteur qui refuse (valeur de `describeConnection().driver`).
- `constructor(driver: string, operation: "savepoint" | "rollbackTo")`

#### `UnknownCriteriaField`

```ts
class UnknownCriteriaField extends Error
```

Levée quand un critère de repository référence un **champ inconnu** de l'entité ciblée.

- `readonly field: string` — Champ fautif (clé du critère non résolue sur l'entité).
- `readonly entity: string` — Nom logique de l'entité ciblée.
- `readonly known: readonly string[]` — Champs connus de l'entité (aide au diagnostic / faute de frappe).
- `constructor(field: string, entity: string, known: readonly string[])`

### Fonctions (24)

#### `assertOrderOption`

```ts
function assertOrderOption(order: unknown, entity: string): void
```

Vérifie que l'option de lecture `order` respecte le contrat portable `Array<[string, "ASC" | "DESC"]>`, ou lève `InvalidOrderOption`.

#### `buildConnectionHealth`

```ts
function buildConnectionHealth(filter?: string): Promise<IConnectionHealth[]>
```

Construit le **diagnostic complet des connexions** (per-instance) : ping live (latence enregistrée dans la fenêtre glissante), sonde profonde driver (`IOrm.probe` — stockage/pool), et compteurs de cycle de vie du `connectionMonitor`. Réutilisé par l'endpoint `connection/health` ET par le ticker hub realtime de Studio (« contrôle total des ORM »).

#### `buildOrmFlow`

```ts
function buildOrmFlow(filter?: string): IOrmFlowReport
```

Construit le rapport de **flux ORM** (per-instance) : débit (via `total`), latence (moyenne + EWMA), pire latence et requêtes lentes récentes, par connecteur enregistré. Lecture pure du `queryFlowMonitor` (aucune requête émise — contrairement à `buildConnectionHealth` qui ping) → bon marché. Réutilisé par l'endpoint `flow` ET le ticker hub realtime de Studio.

#### `buildOrmGraph`

```ts
function buildOrmGraph(connectorFilter?: string): IOrmGraph
```

Construit le graphe canonique complet (optionnellement filtré par connecteur).

#### `buildOrmLeanHealth`

```ts
function buildOrmLeanHealth(): IOrmLeanHealth
```

**Santé ORM lean per-instance** — somme process-wide de tous les connecteurs enregistrés, destinée à voyager dans le report de sonde cluster (« ORM par worker »). C'est la fonction branchée par le driver via `setOrmHealthProvider` (core) ; le framework la lit dans le report.

#### `createOrmAdminApi`

```ts
function createOrmAdminApi(): IAdminApi
```

Construit le producteur `IAdminApi` du data plane ORM.

#### `defineEntity`

```ts
function defineEntity<S, M = unknown>(definition: IEntityDefinition<S, M>): IEntityDefinition<S, M>
```

Déclare une entité applicative. Fonction d'**identité typée** : elle ne fait qu'attacher le type — aucun effet de bord, aucun enregistrement.

#### `describeConnectFailure`

```ts
function describeConnectFailure(subject: string, diagnosis: IConnectionDiagnosis, cause: string, advice?: string): string
```

Compose le message d'échec au démarrage d'un connecteur — UNE rédaction pour tous les adapters.

#### `diagnoseConnectionFailure`

```ts
function diagnoseConnectionFailure(error: unknown, target?: IConnectionTarget, platform?: string): IConnectionDiagnosis
```

Explique un échec de connexion en distinguant « personne n'écoute » de « quelqu'un a répondu et refuse ».

#### `escapeLikeTerm`

```ts
function escapeLikeTerm(text: string): string
```

Neutralise les métacaractères d'un **texte** pour l'insérer dans un motif `$like` — `%`, `_` et l'antislash lui-même.

#### `isFieldOperators`

```ts
function isFieldOperators(value: unknown): value is FieldOperators<unknown>
```

Indique si une valeur de champ est un objet d'`FieldOperators`.

#### `isUpdateOperators`

```ts
function isUpdateOperators(value: unknown): value is UpdateOperators<unknown>
```

Indique si une valeur d'écriture est un objet d'`UpdateOperators`.

#### `likePatternToRegExp`

```ts
function likePatternToRegExp(pattern: string): RegExp
```

Traduit un motif `$like` en expression régulière **ancrée** — pour les stores qui n'ont pas de `LIKE` (MongoDB, implémentations en mémoire).

#### `paginate`

```ts
function paginate<T>(repo: IRepository<T>, page: PageQuery<T>, options?: IPaginateOptions<T>): Promise<IPage<T>>
```

Pagine un `IRepository` de façon **portable** — au-dessus des primitives natives `find(criteria, { limit, offset, order })` et `count(criteria)` que tout adapter implémente déjà (SQL `LIMIT/OFFSET`+`COUNT`, Mongo `skip/limit`+ `countDocuments`…). Aucun adapter n'a à changer : un seul aller vers la page, jamais de matérialisation de toute la collection.

#### `parseConnectionTarget`

```ts
function parseConnectionTarget(url?: string | null): IConnectionTarget
```

Extrait l'hôte, le port, la base et le compte d'une URL de connexion, sans son secret.

#### `registerOrmAdminApi`

```ts
function registerOrmAdminApi(registry: IAdminRegistry): void
```

Enregistre l'`OrmAdminApi` sur le broker admin, **idempotent** (no-op si déjà monté). Appelé par un module driver à son `onKernelBoot` (orm-core est une lib pure et ne peut pas s'auto-monter).

#### `reportOrmBootLines`

```ts
function reportOrmBootLines(kernel: IKernel | null): void
```

Pousse dans le BootReporter une ligne par ORM enregistré (« nom → driver (cible) ») pour que la phase de boot « Services & ORM » RACONTE les connexions mises en place, au lieu d'une phase muette. Idempotent : reconstruit la liste complète depuis le registre et REMPLACE (sûr d'être appelé par N drivers).

#### `reportOrphanEntities`

```ts
function reportOrphanEntities(log: (message: string, severity: "WARNING") => void, owner: object, declared?: readonly string[]): string | null
```

Signale UNE fois par démarrage les entités orphelines, au moment où tous les ORM sont ouverts.

#### `resolveOrmFlowEnabled`

```ts
function resolveOrmFlowEnabled(kernel: IKernel | null): boolean
```

Détermine si la sonde de flux ORM (`queryFlowMonitor`) doit être active : **OFF en production** (coût nul sur le hot path des requêtes), **ON sinon** (observabilité dev / Supervision). Override explicite par la variable d'environnement `NF_ORM_FLOW` (`1`/`true` = forcer ON).

#### `searchCriteria`

```ts
function searchCriteria<T>(q: string, fields: ReadonlyArray<keyof T & string>): Record<string, unknown> | null
```

Traduit un terme de recherche `?q=` en critère portable — **la** règle de recherche d'orm-core, en un seul exemplaire.

#### `toDbml`

```ts
function toDbml(graph: IOrmGraph): string
```

Sérialise un graphe en **DBML** (Database Markup Language) — format pivot lu par dbdiagram.io, les outils IA et convertible en SQL. Les `Ref:` sont dérivés des relations selon la convention FK des adapters (`<source>Id` sur la cible pour 1-N ; `<target>Id` sur la source pour N-1/1-1). Le many-to-many est annoté en commentaire (table de jonction non portable).

#### `toJsonSchema`

```ts
function toJsonSchema(graph: IOrmGraph): { $schema: string; $defs: Record<string, IJsonSchemaObject>; }
```

Sérialise un graphe en **JSON Schema** (draft 2020-12) — un `$defs` par entité. Format « IA-first » : un agent (text-to-SQL, génération de formulaire, validation de payload) consomme directement ce schéma. Les colonnes non-nullables alimentent `required` ; les relations deviennent des `$ref` (N→1/1→1) ou des tableaux de `$ref` (1→N/N→N) vers les autres `$defs`.

#### `wireOrmAdminPlane`

```ts
function wireOrmAdminPlane(kernel: IKernel | null): void
```

Branche le « plan d'administration » ORM dans le kernel — montage **idempotent** appelé par CHAQUE driver à son `onKernelBoot`. Factorise la dette C5 : le bloc était jusqu'ici recopié à l'identique dans chaque module driver (Drizzle, Mongoose), donc voué à diverger ; il vit désormais à un seul endroit.

#### `withConnectDeadline`

```ts
function withConnectDeadline<T>(work: Promise<T>, what: string, ms?: number): Promise<T>
```

Borne l'attente d'une promesse, et rejette avec une cause NOMMÉE au-delà.

### Constantes (9)

#### `CONNECT_TIMEOUT_MS`

```ts
const CONNECT_TIMEOUT_MS = 10000
```

Le temps qu'on accorde à une base pour ACCEPTER une connexion, en millisecondes.

#### `LIKE_ESCAPE_CHAR`

```ts
const LIKE_ESCAPE_CHAR = "\\"
```

Le caractère d'échappement des motifs `$like` du contrat portable.

#### `OPERATOR_KEYS`

```ts
const OPERATOR_KEYS: readonly [ "$eq", "$ne", "$gt", "$gte", "$lt", "$lte", "$in", "$nin", "$like", "$null" ]
```

Liste figée des opérateurs riches reconnus dans un critère portable.

#### `REJECTED_MARKER`

```ts
const REJECTED_MARKER = "s'est connect\u00E9, mais le serveur a refus\u00E9 une instruction \u2014 "
```

Marqueur de la phrase « connecté, puis refusé » — lu par `create app` (`migrationFailureCause`, cœur) pour NE PAS conclure à une base injoignable. Le cœur ne peut pas importer ce paquet : sa copie est éprouvée contre celle-ci par un test de parité.

#### `UPDATE_OPERATOR_KEYS`

```ts
const UPDATE_OPERATOR_KEYS: readonly [ "$max", "$min" ]
```

Liste figée des opérateurs d'**écriture** reconnus dans le `update` d'un `upsert` (cf `UpdateOperators`).

#### `connectionMonitor`

```ts
const connectionMonitor: ConnectionMonitor
```

Singleton process-wide du moniteur de connexions.

#### `entityRegistry`

```ts
const entityRegistry: EntityRegistry
```

Singleton process-wide partagé. Les entités s'y enregistrent (via le décorateur `entities([...])` posé sur le Module, ou `Entity.register`). La classe `EntityRegistry` reste instanciable pour des registres isolés (tests).

#### `ormRegistry`

```ts
const ormRegistry: OrmRegistry
```

Singleton process-wide partagé par tous les drivers et consommateurs ORM.

#### `queryFlowMonitor`

```ts
const queryFlowMonitor: QueryFlowMonitor
```

Singleton process-wide de la sonde de flux ORM.

### Interfaces (5)

#### `IConnectionDiagnosis`

```ts
interface IConnectionDiagnosis
```

Diagnostic rendu à l'appelant, qui compose le message final.

- `verdict: ConnectionVerdict`
- `code: string | null` — Code CONSTATÉ, tel que le driver l'a rendu (`ECONNREFUSED`, `28P01`, …).
- `explanation: string` — Ce qu'on peut affirmer, et le geste qui tranche.

#### `IConnectionTarget`

```ts
interface IConnectionTarget
```

Adresse visée, telle qu'on peut la dire sans divulguer de secret.

- `host: string | null`
- `port: number | null`
- `database?: string | null` — Nom de la base désignée par l'URL — de quoi NOMMER une base absente et écrire la commande qui la crée.
- `user?: string | null` — Compte de connexion (jamais son mot de passe) — propriétaire de la base à créer.

#### `IEntityDefinition`

```ts
interface IEntityDefinition<S = unknown, M = unknown> extends Omit<IEntity<S, M>, "connector">
```

Descripteur d'entité **sans connecteur figé** — la forme sous laquelle une application déclare ses entités.

- `readonly connector?: string` — Connecteur cible — à ne renseigner que pour **forcer** une entité sur une connexion précise (base secondaire).

#### `IPage`

```ts
interface IPage<T>
```

Une **page** de résultats — la sortie unique de toute pagination Nodefony.

- `items: T[]` — Les éléments de la page (au plus `limit`).
- `total?: number` — Total exact de la collection filtrée — présent si `IPageQuery.withTotal` n'est pas `false` **et** que le backend sait compter à coût raisonnable.
- `limit: number` — Taille de page demandée (écho de `IPageQuery.limit`).
- `offset?: number` — Décalage de cette page (mode offset ; absent en mode curseur).
- `hasNext: boolean` — `true` s'il existe au moins un élément au-delà de cette page.
- `nextCursor?: string | null` — Jeton de la page suivante (mode **curseur**) — à repasser en `IPageQuery.cursor`.

#### `IPageQuery`

```ts
interface IPageQuery
```

**LE contrat de pagination unique de Nodefony.** Tous les stores, toutes les API (présents et futurs) paginent avec ce type — c'est un standard de développement, jamais une pagination maison au cas par cas.

- `limit: number` — Taille de page — obligatoire (jamais « tout »).
- `offset?: number` — Décalage depuis le début de la collection filtrée (mode **offset**).
- `cursor?: string` — Jeton de page (mode **curseur**) : ne renvoyer que les éléments situés « après » lui dans l'ordre du store.
- `order?: Array<[ string, "ASC" | "DESC" ]>` — Tri : couples `[champ, sens]`.
- `withTotal?: boolean` — Renvoyer le total exact (`IPage.total`) ou non.
- `q?: string` — Recherche plein-texte best-effort — le **champ** ciblé et la sémantique (préfixe / sous-chaîne / casse) sont définis par chaque store et documentés côté store.
- `tenantId?: string | null` — **RÉSERVÉ multi-tenant** — slot du contrat pour le scoping par tenant, appliqué **au niveau du store** le jour du chantier tenant.

### Types (4)

#### `ConnectionVerdict`

```ts
type ConnectionVerdict = "unreachable" | "answered" | "rejected" | "unknown"
```

Ce que l'échec permet d'affirmer sur l'autre bout du socket.

#### `OperatorKey`

```ts
type OperatorKey = (typeof OPERATOR_KEYS)[number]
```

Clé d'opérateur riche reconnue.

#### `ServiceWiring`

```ts
type ServiceWiring = [ container?: Container, notificationsCenter?: Event | false | null, options?: DefaultOptionsService ]
```

Câblage d'un `Service` (DI / bus d'événements / options) sous forme de **tuple** — évite de redéclarer `container` / `notificationsCenter` / `options` dans le constructeur de chaque service juste pour les tunneler jusqu'à `super`.

#### `UpdateOperatorKey`

```ts
type UpdateOperatorKey = (typeof UPDATE_OPERATOR_KEYS)[number]
```

Clé d'opérateur d'écriture reconnue.

---

[← Toutes les références d'API](../../)