@nodefony/mongoose 10.0.0-alpha.1

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

@@ -0,0 +1,40 @@
+import type { IPageQuery } from "nodefony";
+/**
+ * **La** table d'alias du dialecte Mongo — `id` public → `_id` au repos.
+ *
+ * Elle vit ici, chez l'adapter qui possède la convention, et non dans le
+ * vocabulaire de chaque ressource : ce n'est pas une propriété des jetons ni des
+ * endpoints, c'est une propriété de **Mongo**, où la clé primaire s'appelle
+ * `_id` et où aucun champ `id` n'existe au repos (`id` n'est qu'un virtuel de
+ * lecture). Trois copies de cette même règle vivaient auparavant dans trois
+ * fichiers de vocabulaire, une par ressource.
+ *
+ * Ce que la traduction évite : Mongo ne se plaint **pas** d'un tri sur un champ
+ * absent — il rend les documents dans un ordre arbitraire. Sans elle, un
+ * `?order=id` serait donc silencieusement inerte sur Mongo et correct partout
+ * ailleurs, et l'écart ne se verrait qu'en production, chez un tiers.
+ */
+export declare const MONGO_ORDER_ALIASES: Readonly<Record<string, string>>;
+/**
+ * Borne un `order` reçu à ce que le store DÉCLARE savoir trier, puis l'exprime
+ * dans le schéma Mongo — les deux gestes que tout store Mongo doit faire, dans
+ * cet ordre, avant de descendre le tri au driver.
+ *
+ * L'ordre compte : filtrer d'abord (sur le vocabulaire **public**, celui que le
+ * store annonce), traduire ensuite. L'inverse comparerait des noms de colonnes à
+ * une liste de noms publics, et laisserait passer ce qu'elle est censée refuser.
+ *
+ * @param order - l'ordre demandé, en vocabulaire public.
+ * @param sortable - ce que le store déclare ({@link ISortableSource}).
+ * @param fallback - l'ordre contractuel appliqué à défaut, en vocabulaire public.
+ * @returns l'ordre prêt pour `.sort()` / `paginate()`, en noms de champs Mongo.
+ */
+export declare function mongoOrder(order: IPageQuery["order"], sortable: readonly string[] | undefined, fallback: NonNullable<IPageQuery["order"]>): NonNullable<IPageQuery["order"]>;
+/**
+ * Forme `{ champ: 1 | -1 }` attendue par `Model.sort()` — le dernier maillon,
+ * pour les stores qui parlent au driver Mongo directement plutôt que par
+ * `paginate()`.
+ *
+ * @param order - un ordre déjà borné et traduit (sortie de {@link mongoOrder}).
+ */
+export declare function toMongoSort(order: NonNullable<IPageQuery["order"]>): Record<string, 1 | -1>;

package/dist/types/nodefony/src/orm-core/MongooseOrm.d.ts

@@ -0,0 +1,132 @@
+import type { ConnectOptions } from "mongoose";
+import { Orm } from "@nodefony/orm-core";
+import type { IColumnInfo, IConnectionInfo, IOrmProbe, IRepository, ITransaction } from "@nodefony/orm-core";
+/**
+ * Verdict d'index d'une entité — l'écart entre ce que le schéma DÉCLARE et ce
+ * que la base PORTE réellement.
+ *
+ * C'est le pendant documentaire de l'écart de schéma SQL : MongoDB n'a pas de
+ * DDL, mais un index unique qui n'existe pas est exactement une contrainte
+ * absente. Le verdict est rendu structuré parce qu'il a deux publics — le
+ * journal pour l'exploitant, et l'appelant (banc, sonde d'administration) qui
+ * doit pouvoir en décider.
+ */
+export interface IIndexAudit {
+    /** Nom de l'entité (clé du `entityRegistry`). */
+    entity: string;
+    /** Collection MongoDB sous-jacente. */
+    collection: string;
+    /** Index déclarés au schéma et ABSENTS de la base — la vraie alerte. */
+    missing: string[];
+    /** Index présents en base et non déclarés — informatif, jamais supprimé. */
+    extra: string[];
+    /** Motif d'un échec de construction, quand la base l'a refusée. */
+    error?: string;
+}
+/**
+ * Adapter Mongoose **branché sur `@nodefony/orm-core`** (P5.4).
+ *
+ * 2ᵉ adapter, **hétérogène** au SQL : valide que le contrat enrichi
+ * (`relations`/`withTransaction`) est réellement portable sur un store
+ * documentaire. Distinct du service legacy `nodefony/service/orm.ts`.
+ *
+ * Spécificités MongoDB exposées par l'implémentation :
+ * - **connexion isolée** via `mongoose.createConnection` (pas le singleton global)
+ *   → indispensable au multi-ORM (plusieurs connexions logiques) ;
+ * - relations sans clé étrangère SQL : `one-to-many` = **virtual populate**
+ *   (réf ObjectId injectée sur l'enfant + virtuel sur le parent), `many-to-one`/
+ *   `one-to-one` = champ réf sur la source. `many-to-many` → natif ;
+ * - transactions = **sessions** (requièrent un replica set).
+ */
+export declare class MongooseOrm extends Orm {
+    #private;
+    /**
+     * Mongoose traduit les signaux de topologie du driver MongoDB (SDAM) : il
+     * SAIT qu'un serveur est tombé, même sans le moindre trafic — d'où
+     * `"events"`. C'est la seule des trois familles d'adapters du dépôt qui
+     * dispose d'une surveillance de serveur indépendante des requêtes.
+     */
+    get liveness(): "events" | "assumed";
+    /**
+     * @param name - clé unique de l'ORM dans le `ormRegistry`.
+     * @param uri - URI de connexion MongoDB (replica set requis pour les tx).
+     * @param options - options de connexion Mongoose (auth, pool, timeouts).
+     */
+    constructor(name: string, uri: string, options?: ConnectOptions);
+    protected onConnect(): Promise<void>;
+    /** Constat d'index de la connexion courante, ou `null` hors connexion. */
+    get pendingIndexAudit(): Promise<IIndexAudit[]> | null;
+    /**
+     * Constate l'écart entre les index DÉCLARÉS par les schémas et ceux que la
+     * base porte réellement, et journalise tout manque en `CRITIC`.
+     *
+     * **Pourquoi c'est nécessaire.** Mongoose construit les index en tâche de
+     * fond à la compilation des modèles, et l'issue de cette construction n'était
+     * écoutée par personne. Or plusieurs de ces index portent des contraintes
+     * d'unicité dont dépend l'authentification. Reproduit sur un serveur réel :
+     * une collection portant déjà des doublons fait échouer la construction de
+     * l'index unique — et le process continue, code de sortie 0, **sans un seul
+     * message**, avec pour seul index `_id_`. La contrainte n'existe pas, et rien
+     * ne le dit : c'est la dégradation silencieuse que la doctrine interdit.
+     *
+     * **Pourquoi APRÈS `init()`.** Un `diffIndexes()` lancé aussitôt après la
+     * compilation annonce comme manquants des index dont la construction est
+     * simplement en cours — mesuré. `init()` est le point où la construction est
+     * terminée, en succès comme en échec ; c'est donc là, et pas avant, que
+     * l'écart veut dire quelque chose.
+     *
+     * **Pourquoi ce n'est pas attendu au démarrage.** Construire un index sur une
+     * grosse collection prend des minutes ; faire patienter le pod changerait son
+     * comportement bien au-delà de ce défaut. Le constat court donc en tâche de
+     * fond et parle dès qu'il sait — {@link MongooseOrm.pendingIndexAudit} permet
+     * de l'attendre quand il le faut.
+     *
+     * **Ce que cette méthode ne fait PAS** : réparer. `syncIndexes()` de mongoose
+     * SUPPRIME les index non déclarés — irréversible, et catastrophique sur une
+     * base qu'un exploitant a indexée à la main. Réparer reste un geste explicite.
+     *
+     * @returns un verdict par entité (vide si la connexion est déjà close).
+     */
+    verifyIndexes(): Promise<IIndexAudit[]>;
+    disconnect(): Promise<void>;
+    getRepository<T = unknown>(name: string): IRepository<T>;
+    transaction<R>(work: (tx: ITransaction) => Promise<R>): Promise<R>;
+    getNativeConnection<C = unknown>(): C;
+    /**
+     * Ping bas-coût : commande `{ ping: 1 }` sur la base native (`admin().command`)
+     * — round-trip réel vers MongoDB pour le diagnostic du data plane.
+     *
+     * @throws si la connexion (ou sa base native) n'est pas prête, ou si la base
+     *   ne répond pas.
+     */
+    ping(): Promise<void>;
+    /**
+     * Sonde Mongo (best-effort) : connexions du serveur (`serverStatus`) → pool.
+     * Round-trip réseau → uniquement pendant un abonnement actif. `{}` si indispo.
+     *
+     * @returns sonde `pool` + `extra`, ou `{}`.
+     */
+    probe(): Promise<IOrmProbe>;
+    /**
+     * Colonnes normalisées d'une entité depuis les `paths` du schéma Mongoose —
+     * alimente le graphe canonique / ERD / contexte IA. Pas de PK SQL : `_id` est
+     * la clé primaire implicite de tout document.
+     *
+     * @param name - nom logique de l'entité.
+     * @returns colonnes (`[]` si l'entité n'est pas connue de cet ORM).
+     */
+    describeEntity(name: string): IColumnInfo[];
+    /**
+     * Décrit la connexion : driver `mongodb` + cible (hôte:port/base, **sans
+     * credentials**) + version de la lib `mongoose`. Aucun secret n'est exposé
+     * dans le data plane (l'URI est nettoyée de tout `user:pass@`).
+     *
+     * @returns driver + cible nettoyée + version de l'ORM.
+     */
+    describeConnection(): IConnectionInfo;
+    /**
+     * Cible affichable de l'URI, **sans credentials** : `hôte:port/base`. Jamais
+     * de `user:pass@` (anti info-leak dans le data plane / les logs).
+     */
+    safeTarget(): string;
+}

package/dist/types/nodefony/src/orm-core/MongooseRepository.d.ts

@@ -0,0 +1,51 @@
+import type { ClientSession, Model } from "mongoose";
+import type { Criteria, UpdateData, IRepository, ITransaction, RepositoryReadOptions } from "@nodefony/orm-core";
+/** Modèle Mongoose à document libre (boundary — typé finement côté repo). */
+type LooseModel = Model<Record<string, unknown>>;
+/**
+ * Repository portable (contrat {@link IRepository}) au-dessus d'un modèle Mongoose.
+ *
+ * Démontre la portabilité du contrat sur un **store documentaire hétérogène** :
+ * - `options.relations` → `populate()` (virtuels/refs déclarés), pas `include` ;
+ * - **clé primaire `_id`** (MongoDB) ↔ `id` (contrat) : le critère `{ id }` est
+ *   traduit en `{ _id }`, et la sortie (`toObject({ virtuals: true })`) porte le
+ *   virtuel `id` (string hex de l'ObjectId) → contrat `id: string` respecté ;
+ * - liaison transactionnelle via {@link MongooseRepository.withTransaction}
+ *   (`{ session }` sur toutes les ops ; requiert un replica set).
+ *
+ * @typeParam T - forme plate de l'entité gérée.
+ */
+export declare class MongooseRepository<T = unknown> implements IRepository<T> {
+    #private;
+    /**
+     * @param model - modèle Mongoose compilé.
+     * @param connector - nom de la connexion (clé du registre) — défaut `"nodefony"`.
+     * @param session - session transactionnelle à laquelle lier les ops (ou `null`).
+     */
+    constructor(model: LooseModel, connector?: string, session?: ClientSession | null);
+    find(criteria?: Criteria<T>, options?: RepositoryReadOptions): Promise<T[]>;
+    findOne(criteria: Criteria<T>, options?: RepositoryReadOptions): Promise<T | null>;
+    create(data: Partial<T>): Promise<T>;
+    createMany(data: Partial<T>[]): Promise<T[]>;
+    updateOne(criteria: Criteria<T>, data: Partial<T>): Promise<T | null>;
+    upsert(criteria: Criteria<T>, update: UpdateData<T>, insertOnly?: Partial<T>): Promise<T>;
+    updateMany(criteria: Criteria<T>, data: Partial<T>): Promise<number>;
+    increment(criteria: Criteria<T>, changes: Partial<Record<keyof T, number>>): Promise<T | null>;
+    delete(criteria: Criteria<T>): Promise<number>;
+    deleteOne(criteria: Criteria<T>): Promise<boolean>;
+    findOneAndDelete(criteria: Criteria<T>): Promise<T | null>;
+    count(criteria?: Criteria<T>): Promise<number>;
+    /**
+     * `COUNT(DISTINCT …)` en agrégation — `$group` puis `$count`, donc la
+     * déduplication reste dans le serveur. `Model.distinct()` aurait rapatrié
+     * toutes les valeurs pour n'en mesurer que la longueur.
+     *
+     * `{$ne: null}` écarte à la fois la valeur nulle et le champ absent, ce qui
+     * aligne le résultat sur le `COUNT(DISTINCT col)` SQL — sans lui, les
+     * documents sans valeur formeraient un groupe `null` compté comme une valeur.
+     */
+    countDistinct(field: keyof T & string, criteria?: Criteria<T>): Promise<number>;
+    exists(criteria: Criteria<T>): Promise<boolean>;
+    withTransaction(tx: ITransaction): IRepository<T>;
+}
+export {};

package/dist/types/nodefony/src/orm-core/MongooseTransaction.d.ts

@@ -0,0 +1,37 @@
+import type { ClientSession } from "mongoose";
+import type { ITransaction } from "@nodefony/orm-core";
+/**
+ * Adapte une `ClientSession` MongoDB au contrat portable {@link ITransaction}.
+ *
+ * Obtenue dans le callback de `MongooseOrm.transaction()`, qui gère le
+ * commit/abort automatique via `session.withTransaction()`. Les transactions
+ * MongoDB **exigent un replica set** (un standalone ne les supporte pas).
+ *
+ * MongoDB n'a **pas de savepoints** : {@link MongooseTransaction.savepoint} /
+ * {@link MongooseTransaction.rollbackTo} sont des no-op documentés (limite du
+ * driver, prévue par le contrat).
+ */
+export declare class MongooseTransaction implements ITransaction {
+    #private;
+    /**
+     * @param session - session MongoDB transactionnelle sous-jacente.
+     */
+    constructor(session: ClientSession);
+    /** Indique si la transaction est déjà terminée (commit ou rollback). */
+    isDone(): boolean;
+    /**
+     * Valide la transaction (no-op si déjà terminée — idempotent, parité avec
+     * `DrizzleTransaction`). En mode managé (défaut via `IOrm.transaction`), le
+     * commit/abort est piloté par `session.withTransaction` : un appel manuel est
+     * inutile, et l'idempotence évite un double-commit accidentel.
+     */
+    commit(): Promise<void>;
+    /** Annule la transaction (no-op si déjà terminée — idempotent). */
+    rollback(): Promise<void>;
+    /** No-op : MongoDB ne gère pas les savepoints. */
+    savepoint(_name: string): Promise<void>;
+    /** No-op : MongoDB ne gère pas les savepoints. */
+    rollbackTo(_name: string): Promise<void>;
+    /** Expose la `ClientSession` native (trappe bas niveau). */
+    getNative<C = unknown>(): C;
+}

package/dist/types/nodefony/src/orm-core/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Adapter Mongoose sur `@nodefony/orm-core` (P5.4).
+ *
+ * 2ᵉ adapter (store documentaire hétérogène), distinct du service legacy.
+ */
+export { MongooseOrm } from "./MongooseOrm.js";
+export type { IIndexAudit } from "./MongooseOrm.js";
+export { MongooseRepository } from "./MongooseRepository.js";
+export { MongooseTransaction } from "./MongooseTransaction.js";