Référence d'API — @nodefony/orm-core — racine

stable

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.5 : 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#

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#

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#

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#

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#

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#

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#

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#

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#

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#

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#

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#

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#

function buildOrmGraph(connectorFilter?: string): IOrmGraph

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

buildOrmLeanHealth#

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#

function createOrmAdminApi(): IAdminApi

Construit le producteur IAdminApi du data plane ORM.

defineEntity#

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#

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#

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#

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#

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

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

isUpdateOperators#

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

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

likePatternToRegExp#

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#

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#

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#

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#

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#

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#

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#

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#

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#

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#

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#

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#

const CONNECT_TIMEOUT_MS = 10000

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

LIKE_ESCAPE_CHAR#

const LIKE_ESCAPE_CHAR = "\\"

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

OPERATOR_KEYS#

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#

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#

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#

const connectionMonitor: ConnectionMonitor

Singleton process-wide du moniteur de connexions.

entityRegistry#

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#

const ormRegistry: OrmRegistry

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

queryFlowMonitor#

const queryFlowMonitor: QueryFlowMonitor

Singleton process-wide de la sonde de flux ORM.

Interfaces (5)#

IConnectionDiagnosis#

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#

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#

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#

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#

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#

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

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

OperatorKey#

type OperatorKey = (typeof OPERATOR_KEYS)[number]

Clé d’opérateur riche reconnue.

ServiceWiring#

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#

type UpdateOperatorKey = (typeof UPDATE_OPERATOR_KEYS)[number]

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

← Toutes les références d’API