@nodefony/mongoose 10.0.0-alpha.1

package/dist/nodefony/src/orm-core/MongooseOrm.js

@@ -0,0 +1,440 @@
+import { MongooseRepository } from "./MongooseRepository.js";
+import { MongooseTransaction } from "./MongooseTransaction.js";
+import { createRequire } from "node:module";
+import mongoose from "mongoose";
+import { Orm, entityRegistry } from "@nodefony/orm-core";
+import path from "node:path";
+import fs from "node:fs";
+//#region nodefony/src/orm-core/MongooseOrm.ts
+/**
+* Nom canonique d'un index à partir de sa définition (`{ identifier: 1 }` →
+* `identifier_1`) — la convention de nommage de MongoDB lui-même, pour que le
+* journal désigne l'index sous le nom qu'un exploitant lira dans la base.
+*/
+function indexName(definition) {
+	if (!definition || typeof definition !== "object") return String(definition);
+	return Object.entries(definition).map(([field, direction]) => `${field}_${String(direction)}`).join("_");
+}
+/**
+* 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).
+*/
+var MongooseOrm = class MongooseOrm extends Orm {
+	#connection = null;
+	/**
+	* Listeners de cycle de vie attachés à la connexion Mongoose — gardés pour
+	* pouvoir les DÉTACHER : `disconnect()` puis `connect()` sur le même ORM
+	* empilerait sinon un jeu de listeners par cycle (règle « pas de listener
+	* sans cleanup »). `null` tant qu'aucune connexion n'est ouverte.
+	*/
+	#lifecycle = null;
+	/**
+	* 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() {
+		return "events";
+	}
+	#models = null;
+	#repositories = null;
+	#uri;
+	#options;
+	/**
+	* @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, uri, options) {
+		super(name);
+		this.#uri = uri;
+		this.#options = options;
+	}
+	/** Entités enregistrées ciblant cet ORM. */
+	#ownEntities() {
+		return entityRegistry.list().filter((entity) => entity.connector === this.name);
+	}
+	/** FK déterministe camelCase `<entité>Id` (réf ObjectId côté enfant). */
+	#foreignKey(entityName) {
+		return `${entityName.charAt(0).toLowerCase()}${entityName.slice(1)}Id`;
+	}
+	async onConnect() {
+		if (this.#connection) {
+			this.#unwireLifecycle();
+			await this.#connection.close().catch(() => void 0);
+			this.#connection = null;
+		}
+		const connection = mongoose.createConnection(this.#uri, this.#healthyTimeouts());
+		await connection.asPromise();
+		this.#connection = connection;
+		this.#wireLifecycle(connection);
+		this.#models = Object.create(null);
+		const entities = this.#ownEntities();
+		const schemas = /* @__PURE__ */ new Map();
+		for (const entity of entities) schemas.set(entity.name, new mongoose.Schema(entity.schema, {
+			toObject: { virtuals: true },
+			toJSON: { virtuals: true },
+			timestamps: entity.timestamps ?? false
+		}));
+		for (const entity of entities) {
+			if (!entity.relations) continue;
+			const sourceSchema = schemas.get(entity.name);
+			for (const relation of entity.relations) {
+				const targetSchema = schemas.get(relation.target);
+				if (!sourceSchema || !targetSchema) throw new Error(`MongooseOrm "${this.name}": relation target "${relation.target}" (from "${entity.name}.${relation.field}") not registered for this ORM.`);
+				switch (relation.type) {
+					case "one-to-many": {
+						const fk = relation.foreignKey ?? this.#foreignKey(entity.name);
+						if (!targetSchema.path(fk)) targetSchema.add({ [fk]: {
+							type: mongoose.Schema.Types.ObjectId,
+							ref: entity.name
+						} });
+						sourceSchema.virtual(relation.field, {
+							ref: relation.target,
+							localField: "_id",
+							foreignField: fk
+						});
+						break;
+					}
+					case "many-to-one":
+					case "one-to-one": {
+						const fk = relation.foreignKey ?? relation.field;
+						if (!sourceSchema.path(fk)) sourceSchema.add({ [fk]: {
+							type: mongoose.Schema.Types.ObjectId,
+							ref: relation.target
+						} });
+						break;
+					}
+					case "many-to-many": throw new Error(`MongooseOrm "${this.name}": many-to-many ("${entity.name}.${relation.field}") non portable — déclarer via getNativeConnection().`);
+				}
+			}
+		}
+		for (const entity of entities) {
+			const model = connection.model(entity.name, schemas.get(entity.name));
+			this.#models[entity.name] = model;
+			entity.model = model;
+		}
+		const audit = this.verifyIndexes();
+		this.#indexAudit = audit;
+		audit.catch(() => void 0);
+	}
+	/**
+	* Constat d'index en cours — la promesse de la passe lancée au `connect()`.
+	*
+	* Exposée pour que ce qui doit SAVOIR puisse attendre (un banc, une sonde
+	* d'administration, un futur point de disponibilité) sans que le démarrage,
+	* lui, ait à le faire.
+	*/
+	#indexAudit = null;
+	/** Constat d'index de la connexion courante, ou `null` hors connexion. */
+	get pendingIndexAudit() {
+		return this.#indexAudit;
+	}
+	/**
+	* 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).
+	*/
+	async verifyIndexes() {
+		const models = this.#models;
+		if (!models) return [];
+		const audits = [];
+		for (const [name, model] of Object.entries(models)) {
+			const audit = {
+				entity: name,
+				collection: model.collection?.name ?? name,
+				missing: [],
+				extra: []
+			};
+			try {
+				await model.init();
+			} catch (error) {
+				audit.error = error instanceof Error ? error.message : String(error);
+			}
+			try {
+				const diff = await model.diffIndexes();
+				audit.missing = diff.toCreate.map(indexName);
+				audit.extra = diff.toDrop.map(indexName);
+			} catch (error) {
+				if (this.isConnected()) audit.error ??= error instanceof Error ? error.message : String(error);
+				else return audits;
+			}
+			this.#reportIndexAudit(audit);
+			audits.push(audit);
+		}
+		return audits;
+	}
+	/**
+	* Porte un verdict d'index au journal, à la hauteur de ce qu'il signifie.
+	*
+	* Un index manquant est un `CRITIC` : la contrainte que le code croit tenir
+	* n'est pas tenue. Un index en trop n'est qu'une information — il vient
+	* souvent d'un exploitant qui savait ce qu'il faisait, et rien ici ne le
+	* supprimera.
+	*/
+	#reportIndexAudit(audit) {
+		if (audit.error) this.log(`index de "${audit.entity}" (collection "${audit.collection}") : la base a refusé la construction — ${audit.error}`, "CRITIC");
+		if (audit.missing.length > 0) this.log(`index DÉCLARÉS mais ABSENTS de la collection "${audit.collection}" (entité "${audit.entity}") : ${audit.missing.join(", ")} — toute contrainte d'unicité qu'ils portent n'est PAS appliquée`, "CRITIC");
+		if (audit.extra.length > 0) this.log(`index présents en base et non déclarés sur "${audit.collection}" : ${audit.extra.join(", ")} — laissés en place`, "INFO");
+	}
+	/**
+	* Délais d'attente **par défaut**, plus courts que ceux du driver.
+	*
+	* Le driver MongoDB attend **30 s** pour trouver un serveur utilisable
+	* (`serverSelectionTimeoutMS`) et autant pour établir une connexion
+	* (`connectTimeoutMS`) — vérifié au source, `connection_string.js`. Mesuré
+	* sur une base arrêtée : une requête PEND 30 s avant d'échouer. Pour une
+	* requête HTTP c'est absurde : le client a abandonné depuis longtemps, et
+	* le worker reste bloqué à attendre une base dont on sait déjà qu'elle ne
+	* répond pas.
+	*
+	* **5 s** est tenable parce que `retryReads`/`retryWrites` valent `true`
+	* par défaut : une opération qui échoue en sélection est RETENTÉE, ce qui
+	* porte la fenêtre effective à une dizaine de secondes — de quoi absorber
+	* l'élection d'un nouveau primaire sans faire attendre le client deux fois
+	* plus longtemps que nécessaire.
+	*
+	* `socketTimeoutMS` n'est délibérément PAS touché (le driver le laisse
+	* infini) : le borner ici tuerait les agrégations longues légitimes. Ce
+	* rôle revient à `timeoutMS` (CSOT), que seule l'application peut fixer en
+	* connaissance de ses opérations.
+	*
+	* 🔴 **Un choix EXPLICITE gagne toujours** — qu'il vienne des options ou de
+	* la chaîne de connexion. Poser un défaut n'autorise pas à écraser une
+	* intention : une URI qui porte `?serverSelectionTimeoutMS=20000` dit ce
+	* qu'elle veut, et l'objet d'options primerait silencieusement sur elle.
+	*/
+	#healthyTimeouts() {
+		const provided = this.#options ?? {};
+		const inUri = (key) => new RegExp(`[?&]${key}=`, "iu").test(this.#uri);
+		const defaults = {};
+		if (provided.serverSelectionTimeoutMS === void 0 && !inUri("serverSelectionTimeoutMS")) defaults.serverSelectionTimeoutMS = 5e3;
+		if (provided.connectTimeoutMS === void 0 && !inUri("connectTimeoutMS")) defaults.connectTimeoutMS = 5e3;
+		return {
+			...defaults,
+			...provided
+		};
+	}
+	/**
+	* Traduit les événements du driver en signaux du contrat `orm-core`.
+	*
+	* Mongoose SAIT quand le serveur tombe — le setter de `readyState` émet
+	* l'état, et le driver câble `serverDescriptionChanged` (topologie simple)
+	* ou `topologyDescriptionChanged` (replica set : perte du primaire). Rien
+	* n'écoutait, d'où une santé ORM qui affirmait « connecté » pendant toute
+	* une coupure. `error` est écouté AUSSI parce qu'une `Connection` est un
+	* `EventEmitter` : sans auditeur, une erreur émise ferait tomber le process.
+	*/
+	#wireLifecycle(connection) {
+		const lost = (why) => () => this.connectionLost(why);
+		const listeners = [
+			["disconnected", lost("mongoose: disconnected")],
+			["close", lost("mongoose: close")],
+			["error", ((e) => this.connectionLost(`mongoose: ${e?.message ?? String(e)}`))],
+			["reconnected", () => this.connectionRestored()],
+			["connected", () => this.connectionRestored()]
+		];
+		for (const [event, handler] of listeners) connection.on(event, handler);
+		this.#lifecycle = listeners;
+	}
+	/** Détache les listeners de cycle de vie (anti-fuite, anti-empilement). */
+	#unwireLifecycle() {
+		const connection = this.#connection;
+		if (connection && this.#lifecycle) for (const [event, handler] of this.#lifecycle) connection.removeListener(event, handler);
+		this.#lifecycle = null;
+	}
+	async disconnect() {
+		this.alive = false;
+		this.stopHeartbeat();
+		this.#unwireLifecycle();
+		const connection = this.#connection;
+		if (connection) {
+			const sink = () => void 0;
+			connection.on("error", sink);
+			await connection.close();
+		}
+		this.#connection = null;
+		this.#models = null;
+		this.#repositories = null;
+		this.#indexAudit = null;
+	}
+	getRepository(name) {
+		const model = this.#models?.[name];
+		if (!model) throw new Error(`MongooseOrm "${this.name}": no entity model registered under "${name}".`);
+		if (this.#repositories === null) this.#repositories = Object.create(null);
+		let repository = this.#repositories[name];
+		if (repository === void 0) {
+			repository = new MongooseRepository(model, this.name);
+			this.#repositories[name] = repository;
+		}
+		return repository;
+	}
+	async transaction(work) {
+		const connection = this.#connection;
+		if (!connection) throw new Error(`MongooseOrm "${this.name}": not connected.`);
+		const session = await connection.startSession();
+		let result;
+		try {
+			await session.withTransaction(async () => {
+				result = await work(new MongooseTransaction(session));
+			});
+		} finally {
+			await session.endSession();
+		}
+		return result;
+	}
+	getNativeConnection() {
+		if (!this.#connection) throw new Error(`MongooseOrm "${this.name}": not connected.`);
+		return this.#connection;
+	}
+	/**
+	* 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.
+	*/
+	async ping() {
+		const db = this.#connection?.db;
+		if (!db) throw new Error(`MongooseOrm "${this.name}": not connected.`);
+		await db.admin().command({ ping: 1 });
+	}
+	/**
+	* 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 `{}`.
+	*/
+	async probe() {
+		const db = this.#connection?.db;
+		if (!db) return {};
+		try {
+			const status = await db.admin().serverStatus();
+			const conn = status.connections;
+			return {
+				pool: {
+					borrowed: conn?.current,
+					available: conn?.available
+				},
+				extra: status.version ? { serverVersion: status.version } : {}
+			};
+		} catch {
+			return {};
+		}
+	}
+	/**
+	* 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) {
+		const model = this.#models?.[name];
+		if (!model) return [];
+		const paths = model.schema.paths;
+		return Object.entries(paths).map(([field, schemaType]) => ({
+			name: field,
+			type: schemaType.instance || "Mixed",
+			primaryKey: field === "_id",
+			nullable: field === "_id" ? false : schemaType.isRequired !== true,
+			unique: schemaType.options.unique === true
+		}));
+	}
+	/**
+	* 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() {
+		return {
+			driver: "mongodb",
+			target: this.safeTarget(),
+			ormVersion: MongooseOrm.#ormVersion()
+		};
+	}
+	/**
+	* 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() {
+		try {
+			const url = new URL(this.#uri);
+			url.username = "";
+			url.password = "";
+			return `${url.host}${url.pathname}`;
+		} catch {
+			return this.#uri.replace(/^mongodb(\+srv)?:\/\//, "").replace(/^[^@/]*@/, "").replace(/\?.*$/, "");
+		}
+	}
+	/** Version de la lib `mongoose` (résolue + cachée une seule fois). */
+	static #cachedOrmVersion;
+	static #ormVersion() {
+		if (MongooseOrm.#cachedOrmVersion === void 0) MongooseOrm.#cachedOrmVersion = MongooseOrm.#resolvePkgVersion("mongoose") ?? null;
+		return MongooseOrm.#cachedOrmVersion ?? void 0;
+	}
+	/**
+	* Version d'un package npm via son `package.json` (`createRequire` + remontée
+	* FS). `require("<pkg>/package.json")` direct échoue souvent : `exports` ne
+	* publie pas toujours `./package.json`.
+	*/
+	static #resolvePkgVersion(name) {
+		try {
+			const req = createRequire(import.meta.url);
+			let dir = path.dirname(req.resolve(name));
+			for (let i = 0; i < 8; i++) {
+				const pkgPath = path.join(dir, "package.json");
+				if (fs.existsSync(pkgPath)) {
+					const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+					if (pkg.name === name) return pkg.version;
+				}
+				const parent = path.dirname(dir);
+				if (parent === dir) break;
+				dir = parent;
+			}
+		} catch {}
+	}
+};
+//#endregion
+export { MongooseOrm };