@nodefony/orm-core 10.0.0-alpha.1

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

@@ -0,0 +1,58 @@
+import type { IOrm } from "../interfaces/index.js";
+/**
+ * Registre process-wide des instances ORM enregistrées sous un nom unique.
+ *
+ * Support multi-ORM natif : chaque driver (`@nodefony/mongoose`,
+ * `@nodefony/drizzle`...) s'enregistre à son boot via
+ * {@link OrmRegistry.register} sous une clé logique (`"db_principale"`,
+ * `"db_logs"`...). Les consommateurs (repositories, session storage, security)
+ * résolvent l'ORM voulu par cette clé, jamais par référence directe au driver.
+ *
+ * Pas de coupling à `nodefony` : structure pure et lazy (la `Map` interne n'est
+ * allouée qu'au premier `register`), donc trivialement testable en isolation.
+ */
+export declare class OrmRegistry {
+    #private;
+    /**
+     * Enregistre une instance ORM sous un nom unique.
+     *
+     * @param name - clé logique de l'ORM (ex. `"db_principale"`).
+     * @param orm - instance implémentant {@link IOrm}.
+     * @throws si un ORM du même nom est déjà enregistré (erreur de configuration).
+     */
+    register(name: string, orm: IOrm): void;
+    /**
+     * Résout l'ORM enregistré sous un nom.
+     *
+     * @param name - clé logique de l'ORM.
+     * @returns l'instance {@link IOrm} correspondante.
+     * @throws si aucun ORM n'est enregistré sous ce nom.
+     */
+    get(name: string): IOrm;
+    /**
+     * Indique si un ORM est enregistré sous ce nom.
+     *
+     * @param name - clé logique de l'ORM.
+     */
+    has(name: string): boolean;
+    /**
+     * Liste les noms des ORM enregistrés.
+     *
+     * @returns tableau des clés (vide si aucun ORM enregistré).
+     */
+    list(): string[];
+    /**
+     * Retire un ORM du registre (utile au teardown des tests / hot-reload).
+     *
+     * @param name - clé logique de l'ORM.
+     * @returns `true` si un ORM a été retiré, `false` sinon.
+     */
+    unregister(name: string): boolean;
+}
+/**
+ * Singleton process-wide partagé par tous les drivers et consommateurs ORM.
+ *
+ * Les modules ORM s'enregistrent ici ; la classe {@link OrmRegistry} reste
+ * instanciable séparément pour des registres isolés (tests).
+ */
+export declare const ormRegistry: OrmRegistry;

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

@@ -0,0 +1,53 @@
+import type { IQueryFlow } from "../interfaces/IOrmFlow.js";
+/**
+ * **QueryFlowMonitor** — sonde de **débit ORM** per-instance (process-local),
+ * agrégée et **indépendante de l'ALS** : compte les requêtes, suit leur latence
+ * (moyenne + EWMA) et capture les plus lentes, pour le panneau Supervision
+ * (« contrôle total » des ORM, patron sondes+hub).
+ *
+ * Distinct du **profiler par-requête** (debug bar, buffer de scope ALS, dev-only,
+ * coût nul hors requête tracée) : ce moniteur observe le débit **global** et doit
+ * donc compter en continu → il est **gaté** par {@link enabled} (OFF par défaut)
+ * pour rester **coût nul en production** et ne pas pénaliser les bancs de charge
+ * (qui instancient les adapters hors kernel → `enabled` reste à `false`). Le
+ * module driver l'active au boot en environnement non-prod.
+ *
+ * Perf (règle ABSOLUE) :
+ *  - structure lazy (`Map` allouée au 1ᵉʳ enregistrement, ring `slow` au 1ᵉʳ lent) ;
+ *  - le hot path n'alloue rien hors cas lent et n'appelle **jamais** `toSQL()`
+ *    (l'appelant ne capture le SQL que sur le chemin lent, rare) ;
+ *  - le débit/s n'est pas calculé ici (dérivé du delta de `total` à la lecture)
+ *    → 0 état mutable côté lecture, 0 ring de timestamps sous charge.
+ *
+ * Cloud-native : per-instance ; la vue multi-pod relève de l'agrégation
+ * (Prometheus / fan-out Redis P13), pas de cette classe. Reset au restart.
+ */
+declare class QueryFlowMonitor {
+    #private;
+    /** Sonde active ? OFF par défaut → coût nul tant que le driver ne l'active pas. */
+    enabled: boolean;
+    /** Seuil « lent » (ms) — modifiable par le driver/config. */
+    slowMs: number;
+    /** Active/désactive la sonde (appelé au boot du module driver selon l'env). */
+    setEnabled(on: boolean): void;
+    /**
+     * Enregistre une requête mesurée. À n'appeler **que** si {@link enabled} (le
+     * tap appelant teste le drapeau pour éviter tout coût quand la sonde est OFF).
+     *
+     * @param connector - clé du connecteur ORM (registre).
+     * @param durationMs - durée de la requête (ms).
+     * @param sql - SQL paramétré+redacté, fourni **uniquement** si la requête est
+     *   lente (l'appelant n'extrait le texte que sur le chemin lent — rare).
+     */
+    record(connector: string, durationMs: number, sql?: string): void;
+    /**
+     * Vue figée du flux d'un connecteur (ou flux neutre si jamais observé).
+     *
+     * @param connector - clé du connecteur ORM.
+     * @param vendor - vendor de l'adapter (dérivé par l'appelant).
+     */
+    snapshot(connector: string, vendor: string): IQueryFlow;
+}
+/** Singleton process-wide de la sonde de flux ORM. */
+export declare const queryFlowMonitor: QueryFlowMonitor;
+export {};

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

@@ -0,0 +1,15 @@
+import type { IOrmLeanHealth } from "nodefony";
+/**
+ * **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.
+ *
+ * Perf (règle ABSOLUE) : lecture PURE des singletons déjà alimentés (`queryFlowMonitor` +
+ * `connectionMonitor`) → **0 ping**, **0 `toSQL()`**, O(N connecteurs, N petit). `isConnected()`
+ * est un simple test d'état (pas une requête). `queryTotal` reste à 0 si le flux est OFF
+ * (prod) — c'est voulu : la sonde ne crée aucun coût, elle agrège ce qui existe déjà.
+ *
+ * @returns la santé ORM agrégée du process ({@link IOrmLeanHealth}).
+ */
+export declare function buildOrmLeanHealth(): IOrmLeanHealth;
+export default buildOrmLeanHealth;

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

@@ -0,0 +1,131 @@
+import type { FieldOperators, UpdateOperators } from "../interfaces/IRepository.js";
+/**
+ * Liste figée des opérateurs riches reconnus dans un critère portable.
+ *
+ * Source de vérité unique partagée par tous les adapters : un objet de valeur de
+ * champ n'est traité comme {@link FieldOperators} que si **toutes** ses clés
+ * appartiennent à cette liste (cf {@link isFieldOperators}).
+ */
+export declare const OPERATOR_KEYS: readonly ["$eq", "$ne", "$gt", "$gte", "$lt", "$lte", "$in", "$nin", "$like", "$null"];
+/** Clé d'opérateur riche reconnue. */
+export type OperatorKey = (typeof OPERATOR_KEYS)[number];
+/**
+ * Indique si une valeur de champ est un objet d'{@link FieldOperators}.
+ *
+ * Heuristique : objet simple, non-`null`, non-tableau, dont **toutes** les clés
+ * propres sont des opérateurs reconnus (et au moins une). Une valeur objet
+ * « ordinaire » (colonne JSON, sous-document) n'a pas que des clés `$`-préfixées
+ * reconnues → elle est traitée comme une égalité, jamais comme un filtre riche.
+ *
+ * @param value - valeur de critère associée à un champ.
+ * @returns `true` si `value` doit être interprétée comme des opérateurs.
+ */
+export declare function isFieldOperators(value: unknown): value is FieldOperators<unknown>;
+/**
+ * Liste figée des opérateurs d'**écriture** reconnus dans le `update` d'un
+ * `upsert` (cf {@link UpdateOperators}).
+ *
+ * Source de vérité unique partagée par tous les adapters — pendant, côté
+ * écriture, de {@link OPERATOR_KEYS}.
+ */
+export declare const UPDATE_OPERATOR_KEYS: readonly ["$max", "$min"];
+/** Clé d'opérateur d'écriture reconnue. */
+export type UpdateOperatorKey = (typeof UPDATE_OPERATOR_KEYS)[number];
+/**
+ * Indique si une valeur d'écriture est un objet d'{@link UpdateOperators}.
+ *
+ * Même heuristique que {@link isFieldOperators} : objet simple, non-`null`,
+ * non-tableau, dont **toutes** les clés propres sont des opérateurs d'écriture
+ * reconnus (et au moins une). Une valeur objet « ordinaire » (colonne JSON,
+ * sous-document) est donc écrite telle quelle, jamais interprétée.
+ *
+ * @param value - valeur d'écriture associée à un champ.
+ * @returns `true` si `value` doit être interprétée comme des opérateurs.
+ */
+export declare function isUpdateOperators(value: unknown): value is UpdateOperators<unknown>;
+/**
+ * Le caractère d'échappement des motifs `$like` du contrat portable.
+ *
+ * Il ne se choisit pas librement : **PostgreSQL et MySQL appliquent déjà `\`**
+ * quand aucune clause `ESCAPE` n'est écrite, si bien qu'un motif portant un
+ * antislash se comportait DÉJÀ différemment selon le moteur (SQLite, lui, n'a
+ * aucun échappement par défaut : il cherchait l'antislash littéral). Fixer `\`
+ * et l'émettre explicitement ne change donc pas la sémantique du contrat — cela
+ * la fait exister, en alignant les trois moteurs sur celui des deux
+ * comportements qui était déjà majoritaire.
+ *
+ * @see {@link escapeLikeTerm} pour construire un motif, {@link likePatternToRegExp}
+ *   pour l'interpréter là où il n'y a pas de SQL (Mongo, mémoire).
+ */
+export declare const LIKE_ESCAPE_CHAR = "\\";
+/**
+ * Neutralise les métacaractères d'un **texte** pour l'insérer dans un motif
+ * `$like` — `%`, `_` et l'antislash lui-même.
+ *
+ * À utiliser dès qu'un fragment de motif vient d'un humain ou d'une donnée :
+ * sans elle, chercher `50%` demande « 50 suivi de n'importe quoi », et chercher
+ * `a_b` ramène `axb`. L'utilisateur ne lit pas ça comme une imprécision, il le
+ * lit comme un résultat.
+ *
+ * L'échappement n'a de valeur que si la clause `ESCAPE` correspondante est
+ * ÉMISE : un motif échappé sans elle est cherché littéralement, antislash
+ * compris, et ne rend plus rien — en silence. C'est pourquoi les deux vont
+ * ensemble et vivent ici, et non chez chaque appelant.
+ *
+ * @param text - le fragment littéral à insérer dans un motif.
+ * @returns le même texte, ses métacaractères neutralisés.
+ *
+ * @example
+ * ```ts
+ * { discount: { $like: `${escapeLikeTerm("50%")}%` } }  // → "50\%%"
+ * ```
+ */
+export declare function escapeLikeTerm(text: string): string;
+/**
+ * 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).
+ *
+ * C'est la contrepartie exacte de ce qu'un moteur SQL fait avec
+ * `LIKE … ESCAPE '\'` : `%` vaut « n'importe quelle suite », `_` « un
+ * caractère », et un caractère précédé de {@link LIKE_ESCAPE_CHAR} vaut
+ * lui-même. Sans cette lecture, un adapter documentaire rendrait des résultats
+ * différents d'un adapter SQL pour le même critère portable — la divergence la
+ * plus coûteuse qui soit, puisqu'elle ne se voit qu'en changeant de backend.
+ *
+ * Un antislash final sans caractère à échapper est traité comme un antislash
+ * littéral, comme le font les moteurs SQL.
+ *
+ * @param pattern - le motif du contrat (`préfixe%`, `a\_b`…).
+ * @returns une `RegExp` ancrée aux deux bouts.
+ */
+export declare function likePatternToRegExp(pattern: string): RegExp;
+/**
+ * Traduit un terme de recherche `?q=` en critère portable — **la** règle de
+ * recherche d'orm-core, en un seul exemplaire.
+ *
+ * Elle existe parce qu'elle était écrite plusieurs fois, presque à l'identique,
+ * dans des stores qui n'avaient aucun test dessus.
+ *
+ * **Le motif est ANCRÉ À GAUCHE** (`préfixe%`), donc **indexable**. Une
+ * recherche `%terme%` interdit tout usage d'index et impose un balayage
+ * complet : plus « pratique » sur dix lignes, intenable sur un million. C'est un
+ * choix de conception — un besoin de sous-chaîne relève d'un index plein-texte,
+ * pas de `LIKE`.
+ *
+ * Plusieurs champs deviennent un `$or` ; un seul reste un critère plat (les
+ * deux formes sont équivalentes pour les adapters, la seconde est plus lisible
+ * dans les journaux de requêtes).
+ *
+ * Le terme est **échappé** ({@link escapeLikeTerm}) : chercher `50%` cherche
+ * « 50% », et `a_b` ne ramène pas `axb`. Ça n'a été possible qu'une fois la
+ * clause `ESCAPE` émise par la traduction de `$like` — auparavant un terme
+ * échappé était cherché littéralement, antislash compris, et ne rendait plus
+ * rien du tout, en silence. Les deux gestes sont indissociables : c'est pourquoi
+ * ils vivent dans le même fichier.
+ *
+ * @param q - le terme saisi, déjà trimé par `parsePageQuery`.
+ * @param fields - les champs sur lesquels chercher, en noms de propriétés.
+ * @returns le critère à fusionner, ou `null` si le terme est vide ou qu'aucun
+ *   champ n'est déclaré — l'appelant décide alors quoi faire de `q`.
+ */
+export declare function searchCriteria<T>(q: string | undefined, fields: ReadonlyArray<keyof T & string>): Record<string, unknown> | null;

package/dist/types/nodefony/src/decorators/entitiesDecorator.d.ts

@@ -0,0 +1,48 @@
+import type { Module } from "nodefony";
+import type { IEntityDefinition } from "../defineEntity.js";
+type Constructor<T = object> = new (...args: any[]) => T;
+/** Connecteur retenu quand ni l'entité ni le décorateur n'en nomment un. */
+export declare const DEFAULT_CONNECTOR = "default";
+/** Options du décorateur {@link entities}. */
+export interface EntitiesOptions {
+    /**
+     * Connexion nommée pour toutes les entités de la liste (défaut : `"default"`).
+     * Une entité qui porte son propre `connector` garde le sien — utile pour une base
+     * secondaire (ex. un entrepôt d'analyse) déclarée dans le même module.
+     */
+    connector?: string;
+}
+/**
+ * Déclare les entités qu'un module apporte — l'équivalent de `@controllers([...])`
+ * pour la couche données.
+ *
+ * ```ts
+ * @entities([PostEntity, CommentEntity])
+ * @controllers([PostController])
+ * class Blog extends Module { … }
+ * ```
+ *
+ * **Pourquoi ce décorateur existe** : l'inscription d'une entité est impérative
+ * (`entityRegistry.register()`), et il n'y a aucune découverte automatique. Sans lui,
+ * une application n'a **aucun endroit** où déclarer ses entités : elle dépend d'un
+ * import à effet de bord, où un fichier simplement oublié donne une entité
+ * silencieusement absente — l'erreur n'apparaît qu'au premier `getRepository()`, loin
+ * de sa cause. Une liste, elle, se lit.
+ *
+ * **Phase `onRegister`, jamais `onBoot`** (piège) : les connecteurs se branchent à
+ * `onBoot` et créent les tables à ce moment-là. Enregistrer les entités à `onBoot`,
+ * comme le fait `@controllers`, en ferait une **course** avec le `connect()` : selon
+ * l'ordre des écouteurs, la table n'existerait pas. `onRegister` est strictement
+ * antérieur — sûr par construction.
+ *
+ * **Idempotent** : une entité déjà inscrite pour le même connecteur est ignorée (un
+ * module peut être instancié deux fois dans un même processus — tests, rechargement).
+ * Une **collision réelle** (deux entités différentes, même nom, même connecteur) reste
+ * une erreur levée par le registre : c'est un conflit de modèle, pas un doublon bénin.
+ *
+ * @param list - descripteurs produits par `defineEntity()` (un seul ou un tableau).
+ * @param options - connecteur cible commun.
+ * @returns le décorateur de classe `Module`.
+ */
+export declare function entities(list: IEntityDefinition[] | IEntityDefinition, options?: EntitiesOptions): <T extends Constructor<Module>>(constructor: T) => T;
+export {};

package/dist/types/nodefony/src/decorators/entityDecorator.d.ts

@@ -0,0 +1,49 @@
+import type { IEntityRelation } from "../../interfaces/index.js";
+import { type DecoratedClass } from "./metadataStore.js";
+/**
+ * Options du décorateur {@link entity}.
+ *
+ * @typeParam S - type du schéma natif du driver.
+ */
+export interface EntityOptions<S = unknown> {
+    /** Connexion nommée cible, telle que déclarée en config (ex. `"db_principale"`). */
+    connector: string;
+    /** Nom logique ; par défaut le nom de la classe décorée. */
+    name?: string;
+    /**
+     * Module Nodefony propriétaire (ex. `"user"`, `"test"`) — regroupe l'entité
+     * dans le graphe canonique / ERD Studio. Optionnel.
+     */
+    module?: string;
+    /**
+     * Classification (domaine fonctionnel) — axe de regroupement ERD distinct du
+     * `module`. Optionnel. Voir {@link IEntity.domain}.
+     */
+    domain?: string;
+    /** Schéma natif du driver (schéma Mongoose, schéma Drizzle...). */
+    schema?: S;
+    /** Relations déclaratives vers d'autres entités. */
+    relations?: ReadonlyArray<IEntityRelation>;
+}
+/**
+ * Décore une classe comme entité multi-ORM et l'enregistre au chargement.
+ *
+ * Résout le piège d'ordre d'initialisation TS (le constructeur de base
+ * s'exécute avant les initialiseurs de champs de la sous-classe) : le décorateur
+ * s'exécute sur la **classe** au chargement du module, donc `name`/`connector`
+ * sont connus sans instance. Il construit un **descripteur {@link IEntity} depuis
+ * les options** (aucune instanciation au boot), l'enregistre dans le
+ * `entityRegistry` process-wide, et stocke la métadonnée via un `WeakMap`
+ * (cf. `metadataStore`, sans `reflect-metadata`).
+ *
+ * @param options - connecteur cible + nom/schéma/relations optionnels.
+ * @returns le décorateur de classe (renvoie la classe inchangée).
+ * @throws si une entité de même `name` est déjà enregistrée sur le même `connector`.
+ *
+ * @example
+ * ```ts
+ * \@entity({ connector: "db_principale", schema: { id: { type: "uuid" } } })
+ * class User extends Entity { ... }
+ * ```
+ */
+export declare function entity<S = unknown>(options: EntityOptions<S>): <T extends DecoratedClass>(target: T) => T;

package/dist/types/nodefony/src/decorators/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Barrel des décorateurs orm-core (P5.3).
+ *
+ * `@entity` + `@repository` + helpers d'introspection des métadonnées
+ * (stockées via `WeakMap`, sans `reflect-metadata`).
+ */
+export { entity, type EntityOptions } from "./entityDecorator.js";
+export { entities, DEFAULT_CONNECTOR, type EntitiesOptions, } from "./entitiesDecorator.js";
+export { repository, type RepositoryOptions } from "./repositoryDecorator.js";
+export { getEntityMeta, hasEntityMeta, getRepositoryMeta, hasRepositoryMeta, type EntityMetadata, type RepositoryMetadata, type DecoratedClass, } from "./metadataStore.js";

package/dist/types/nodefony/src/decorators/metadataStore.d.ts

@@ -0,0 +1,54 @@
+import type { IEntityRelation } from "../../interfaces/index.js";
+/**
+ * Constructeur de classe ciblé par un décorateur orm-core (paramètres libres).
+ *
+ * `never[]` en rest accepte n'importe quelle signature de constructeur concrète
+ * tout en restant assignable comme clé `WeakMap`. Évite `any` (règle projet).
+ */
+export type DecoratedClass = new (...args: never[]) => object;
+/**
+ * Métadonnée attachée à une classe par {@link entity}.
+ *
+ * @typeParam S - type du schéma natif du driver.
+ */
+export interface EntityMetadata<S = unknown> {
+    /** Nom logique de l'entité (clé de lookup). */
+    readonly name: string;
+    /** Connexion nommée cible (clé du `ormRegistry`). */
+    readonly connector: string;
+    /** Module Nodefony propriétaire (regroupement graphe/ERD), si fourni. */
+    readonly module?: string;
+    /** Classification (domaine fonctionnel), axe de regroupement distinct du module. */
+    readonly domain?: string;
+    /** Schéma natif du driver (forme libre), si fourni au décorateur. */
+    readonly schema?: S;
+    /** Relations déclaratives vers d'autres entités. */
+    readonly relations?: ReadonlyArray<IEntityRelation>;
+    /** Constructeur décoré (pour introspection / résolution lazy par le driver). */
+    readonly target: DecoratedClass;
+}
+/**
+ * Métadonnée attachée à une classe par {@link repository}.
+ */
+export interface RepositoryMetadata {
+    /** Nom logique du repository (clé DI, ex. `"repository.user"`). */
+    readonly name: string;
+    /** Nom logique de l'entité gérée par ce repository. */
+    readonly entity: string;
+    /** Connecteur cible (lève l'ambiguïté si l'entité existe sur plusieurs connexions). */
+    readonly connector?: string;
+    /** Constructeur décoré. */
+    readonly target: DecoratedClass;
+}
+/** Enregistre la métadonnée `@entity` d'une classe. */
+export declare function setEntityMeta(target: DecoratedClass, meta: EntityMetadata): void;
+/** Récupère la métadonnée `@entity` d'une classe, ou `undefined`. */
+export declare function getEntityMeta(target: DecoratedClass): EntityMetadata | undefined;
+/** Indique si une classe porte une métadonnée `@entity`. */
+export declare function hasEntityMeta(target: DecoratedClass): boolean;
+/** Enregistre la métadonnée `@repository` d'une classe. */
+export declare function setRepositoryMeta(target: DecoratedClass, meta: RepositoryMetadata): void;
+/** Récupère la métadonnée `@repository` d'une classe, ou `undefined`. */
+export declare function getRepositoryMeta(target: DecoratedClass): RepositoryMetadata | undefined;
+/** Indique si une classe porte une métadonnée `@repository`. */
+export declare function hasRepositoryMeta(target: DecoratedClass): boolean;

package/dist/types/nodefony/src/decorators/repositoryDecorator.d.ts

@@ -0,0 +1,30 @@
+import { type DecoratedClass } from "./metadataStore.js";
+/**
+ * Options du décorateur {@link repository}.
+ */
+export interface RepositoryOptions {
+    /** Nom logique de l'entité gérée par ce repository. */
+    entity: string;
+    /** Connecteur cible — lève l'ambiguïté si l'entité existe sur plusieurs connexions. */
+    connector?: string;
+}
+/**
+ * Décore une classe comme repository d'une entité (tag métadonnée pur).
+ *
+ * Stocke le lien repo↔entity dans un `WeakMap` (cf. `metadataStore`, sans
+ * `reflect-metadata`). N'enregistre RIEN dans un registre en P5.3 : le binding
+ * DI (`@Inject('repository.user.db_principale')`) est câblé par l'adapter ORM
+ * concret (P5.4+), qui scanne ces métadonnées. Coût uniquement au chargement
+ * du module — jamais par requête.
+ *
+ * @param name - nom logique du repository (clé DI, ex. `"repository.user"`).
+ * @param options - entité gérée + connecteur cible optionnel.
+ * @returns le décorateur de classe (renvoie la classe inchangée).
+ *
+ * @example
+ * ```ts
+ * \@repository("repository.user", { entity: "User", connector: "db_principale" })
+ * class UserRepository implements IRepository<User> { ... }
+ * ```
+ */
+export declare function repository(name: string, options: RepositoryOptions): <T extends DecoratedClass>(target: T) => T;

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

@@ -0,0 +1,43 @@
+import type { IEntity } from "../interfaces/IEntity.js";
+/**
+ * Descripteur d'entité **sans connecteur figé** — la forme sous laquelle une
+ * application déclare ses entités.
+ *
+ * Pourquoi le connecteur manque : dans {@link IEntity}, `connector` est le **nom
+ * d'une connexion** (`"default"`, `"analytics"`…). C'est une donnée de
+ * **configuration**, pas de code : la même table peut être servie par une connexion
+ * différente selon l'environnement. La figer à l'import interdirait de la réutiliser
+ * — c'est exactement ce qui condamne le décorateur de classe
+ * `@entity({connector, schema})` à n'être jamais employé en production. Ici, le
+ * connecteur est résolu **au boot**, par le décorateur `entities`.
+ */
+export interface IEntityDefinition<S = unknown, M = unknown> extends Omit<IEntity<S, M>, "connector"> {
+    /**
+     * Connecteur cible — à ne renseigner que pour **forcer** une entité sur une
+     * connexion précise (base secondaire). Sinon, c'est `entities(…, { connector })`
+     * qui tranche, et à défaut le connecteur `"default"`.
+     */
+    readonly connector?: string;
+}
+/**
+ * Déclare une entité applicative. Fonction d'**identité typée** : elle ne fait
+ * qu'attacher le type — aucun effet de bord, aucun enregistrement.
+ *
+ * L'enregistrement est le rôle du décorateur `entities([...])` posé sur le Module,
+ * qui s'exécute à la phase `onRegister` (avant que l'ORM ne se connecte). Séparer
+ * les deux permet d'importer une entité (dans un test, un script, un autre module)
+ * sans déclencher son inscription dans un registre global.
+ *
+ * @example
+ * ```ts
+ * export const PostEntity = defineEntity({
+ *   name: "Post",
+ *   module: "blog",
+ *   schema: postTable,     // table Drizzle native (ou SchemaDefinition Mongoose)
+ * });
+ * ```
+ *
+ * @param definition - descripteur (nom logique, schéma natif, module, relations…).
+ * @returns le descripteur, tel quel.
+ */
+export declare function defineEntity<S, M = unknown>(definition: IEntityDefinition<S, M>): IEntityDefinition<S, M>;

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

@@ -0,0 +1,62 @@
+/**
+ * Erreurs typées du socle ORM — **data-level uniquement** (aucun couplage à une
+ * couche API/transport : ces erreurs décrivent des fautes sur les données, pas
+ * sur une requête HTTP/GraphQL). Une surface API qui les rencontre décide
+ * elle-même comment les projeter (400, erreur GraphQL…), l'ORM n'en sait rien.
+ */
+/**
+ * Levée quand un critère de repository référence un **champ inconnu** de l'entité
+ * ciblée.
+ *
+ * Garde-fou « ultra solide » + **portabilité** : sans elle, un champ inconnu est
+ * traité différemment selon l'adapter — Drizzle l'**ignore** (la condition
+ * disparaît → la requête peut renvoyer **toute** la table), Mongoose le **garde**
+ * (→ **0 résultat**). Le même critère mal typé donnerait donc des résultats
+ * opposés selon l'ORM (rupture de la promesse « swap d'ORM ») et une faute de
+ * frappe (`emial`) passerait silencieusement. On échoue **tôt et pareil** sur les
+ * deux drivers.
+ *
+ * Les requêtes natives/calculées (opérateurs logiques `$or`, sous-requêtes…) ne
+ * relèvent **pas** du critère portable : passer par `IOrm.getNativeConnection()`.
+ */
+export declare class UnknownCriteriaField extends Error {
+    /** Champ fautif (clé du critère non résolue sur l'entité). */
+    readonly field: string;
+    /** Nom logique de l'entité ciblée. */
+    readonly entity: string;
+    /** Champs connus de l'entité (aide au diagnostic / faute de frappe). */
+    readonly known: readonly string[];
+    /**
+     * @param field - champ inconnu rencontré dans le critère.
+     * @param entity - entité ciblée (nom logique).
+     * @param known - champs connus de l'entité.
+     */
+    constructor(field: string, entity: string, known: readonly string[]);
+}
+/**
+ * Levée quand l'option de lecture `order` n'est pas un tableau de couples
+ * `[champ, "ASC" | "DESC"]`.
+ *
+ * Symétrique de {@link UnknownCriteriaField}, sous la même règle « jamais un skip
+ * silencieux » : avant cette garde, une forme 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. Le sens est vérifié
+ * en casse exacte : un `"desc"` minuscule aurait produit un tri **ASC**, soit
+ * l'inverse de l'intention.
+ *
+ * TypeScript attrape déjà le cas au typage ; la surface réelle est l'appel non typé
+ * ou construit dynamiquement — exactement là où un tri faux ne se voit pas. La
+ * normalisation d'une entrée utilisateur (casse, `champ:sens`) appartient à la
+ * frontière qui la reçoit (`parsePageQuery`), jamais au repository.
+ */
+export declare class InvalidOrderOption extends Error {
+    /** Nom logique de l'entité ciblée. */
+    readonly entity: string;
+    /** Ce qui a été reçu, décrit par sa FORME (jamais la valeur : pas de fuite de données). */
+    readonly received: string;
+    /**
+     * @param entity - entité ciblée (nom logique).
+     * @param received - description de la forme reçue (ex. `an object`, `pair #0 is not an array`).
+     */
+    constructor(entity: string, received: string);
+}

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

@@ -0,0 +1,48 @@
+import type { IKernel } from "nodefony";
+/**
+ * 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.
+ *
+ * Trois branchements, tous **GLOBAUX** (ils itèrent `ormRegistry`) → couvrent
+ * TOUS les ORM enregistrés, peu importe le driver appelant ; idempotents
+ * (« dernier gagne ») → sûr d'être invoqué par N drivers :
+ *  1. `registerOrmAdminApi` (si un broker admin est présent) — monte les routes
+ *     data plane `/nodefony/orm/api/*` ;
+ *  2. `setOrmHealthProvider` — santé ORM lean dans la sonde cluster (par worker) ;
+ *  3. `setOrmRichProvider` — diagnostic riche (connexion + flux) pour le drill Studio.
+ *
+ * Les seams `setOrm*Provider` matérialisent l'inversion de dépendance : le core
+ * expose la prise, orm-core fournit l'implémentation agnostique
+ * (0 dépendance `framework` → `orm-core`).
+ *
+ * @param kernel - kernel courant (`this.kernel` du module driver), ou nullish.
+ */
+export declare function wireOrmAdminPlane(kernel: IKernel | null | undefined): 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).
+ *
+ * `describeConnection()` ne révèle JAMAIS de credential (redaction côté adapter).
+ * Le libellé « Services & ORM » doit matcher une phase du `BootReporter` (core).
+ *
+ * @param kernel - kernel courant (`this.kernel` du module driver), ou nullish.
+ */
+export declare function reportOrmBootLines(kernel: IKernel | null | undefined): void;
+/**
+ * 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).
+ *
+ * Factorise le calcul recopié à l'identique dans chaque `*Service.onBoot` (le
+ * pendant « flux » de {@link wireOrmAdminPlane}, gardé distinct car il s'exécute
+ * dans le Service, pas le Module, et porte une responsabilité différente).
+ *
+ * @param kernel - kernel courant (pour lire l'environnement d'exécution).
+ * @returns `true` si la sonde de flux doit être activée.
+ */
+export declare function resolveOrmFlowEnabled(kernel: IKernel | null | undefined): boolean;

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

@@ -0,0 +1,43 @@
+import type { IRepository } from "../interfaces/IRepository.js";
+import type { IPage, PageQuery } from "../interfaces/IPage.js";
+/** Réglages d'un `paginate` — ce que ce point d'entrée sait faire en plus de découper. */
+export interface IPaginateOptions<T> {
+    /**
+     * Champs sur lesquels `?q=` cherche. **Absent ou vide ⇒ tout `q` reçu est
+     * REFUSÉ**, jamais ignoré.
+     *
+     * Le défaut est le refus pour la même raison que pour le tri et les filtres :
+     * un `q` accepté puis jeté rend la collection ENTIÈRE à qui croit lire un
+     * résultat de recherche — la façon la plus discrète de mentir, puisque la
+     * réponse est un `200` bien formé. Et c'est exactement ce que ce helper
+     * faisait : `q` traversait son type sans être lu une seule fois.
+     *
+     * Comme le tri, la recherche est une capacité — elle se constate et se
+     * déclare, jamais elle ne se suppose.
+     */
+    searchable?: ReadonlyArray<keyof T & string>;
+}
+/**
+ * Pagine un {@link 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.
+ *
+ * `hasNext` est obtenu **sans `COUNT`** par l'astuce `limit + 1` : on demande une
+ * ligne de plus que la page ; si elle arrive, il y a une suite (on la retire du
+ * résultat). Le `COUNT(*)` — coûteux sur les grosses tables — n'est payé que si
+ * `withTotal` n'est pas `false` (mode « Page » vs « Slice », cf Spring Data).
+ *
+ * La **recherche** `?q=` n'est honorée que si l'appelant déclare où chercher
+ * ({@link IPaginateOptions.searchable}) ; sans cela elle est refusée en `400`.
+ *
+ * @typeParam T - type de l'entité paginée.
+ * @param repo - le repository à paginer.
+ * @param page - la requête de page ({@link PageQuery}).
+ * @param options - capacités de ce point d'entrée (recherche).
+ * @returns une {@link Page} : au plus `limit` items, `hasNext`, et `total` si demandé.
+ * @throws {@link PageQueryError} (`400`) si un `q` est reçu sans champ
+ *   cherchable déclaré, ou si le critère porte déjà un `$or`.
+ */
+export declare function paginate<T>(repo: IRepository<T>, page: PageQuery<T>, options?: IPaginateOptions<T>): Promise<IPage<T>>;