@nodefony/orm-core 10.0.0-alpha.2 → 10.0.0-alpha.3

package/dist/index.js

@@ -11,6 +11,8 @@ import { AbstractCrudService } from "./nodefony/src/AbstractCrudService.js";
 import { queryFlowMonitor } from "./nodefony/src/QueryFlowMonitor.js";
 import { buildConnectionHealth, buildOrmFlow, buildOrmGraph, createOrmAdminApi, registerOrmAdminApi, toDbml, toJsonSchema } from "./nodefony/src/OrmAdminApi.js";
 import { buildOrmLeanHealth } from "./nodefony/src/buildOrmLeanHealth.js";
+import { diagnoseConnectionFailure, parseConnectionTarget } from "./nodefony/src/connectionDiagnosis.js";
+import { CONNECT_TIMEOUT_MS, withConnectDeadline } from "./nodefony/src/connectDeadline.js";
 import { reportOrmBootLines, resolveOrmFlowEnabled, wireOrmAdminPlane } from "./nodefony/src/ormWiring.js";
 import { isMigrationFailure } from "./nodefony/interfaces/IOrmMigrations.js";
 import { getEntityMeta, getRepositoryMeta, hasEntityMeta, hasRepositoryMeta } from "./nodefony/src/decorators/metadataStore.js";
@@ -19,4 +21,4 @@ import { DEFAULT_CONNECTOR, entities } from "./nodefony/src/decorators/entitiesD
 import { repository } from "./nodefony/src/decorators/repositoryDecorator.js";
 import "./nodefony/src/decorators/index.js";
 import { defineEntity } from "./nodefony/src/defineEntity.js";
-export { AbstractCrudService, DEFAULT_CONNECTOR, Entity, EntityRegistry, InvalidOrderOption, LIKE_ESCAPE_CHAR, OPERATOR_KEYS, Orm, OrmRegistry, UPDATE_OPERATOR_KEYS, UnknownCriteriaField, assertOrderOption, buildConnectionHealth, buildOrmFlow, buildOrmGraph, buildOrmLeanHealth, connectionMonitor, createOrmAdminApi, defineEntity, entities, entity, entityRegistry, escapeLikeTerm, getEntityMeta, getRepositoryMeta, hasEntityMeta, hasRepositoryMeta, isFieldOperators, isMigrationFailure, isUpdateOperators, likePatternToRegExp, ormRegistry, paginate, queryFlowMonitor, registerOrmAdminApi, reportOrmBootLines, repository, resolveOrmFlowEnabled, searchCriteria, toDbml, toJsonSchema, wireOrmAdminPlane };
+export { AbstractCrudService, CONNECT_TIMEOUT_MS, DEFAULT_CONNECTOR, Entity, EntityRegistry, InvalidOrderOption, LIKE_ESCAPE_CHAR, OPERATOR_KEYS, Orm, OrmRegistry, UPDATE_OPERATOR_KEYS, UnknownCriteriaField, assertOrderOption, buildConnectionHealth, buildOrmFlow, buildOrmGraph, buildOrmLeanHealth, connectionMonitor, createOrmAdminApi, defineEntity, diagnoseConnectionFailure, entities, entity, entityRegistry, escapeLikeTerm, getEntityMeta, getRepositoryMeta, hasEntityMeta, hasRepositoryMeta, isFieldOperators, isMigrationFailure, isUpdateOperators, likePatternToRegExp, ormRegistry, paginate, parseConnectionTarget, queryFlowMonitor, registerOrmAdminApi, reportOrmBootLines, repository, resolveOrmFlowEnabled, searchCriteria, toDbml, toJsonSchema, wireOrmAdminPlane, withConnectDeadline };

package/dist/nodefony/src/connectDeadline.js

@@ -0,0 +1,67 @@
+//#region nodefony/src/connectDeadline.ts
+/**
+* Le DÉLAI DE GARDE d'une connexion à une base — une commande n'attend jamais
+* sans fin.
+*
+* 🔴 Le cas est vécu, et il ne ressemble pas à une panne : `nodefony inspect
+* config` restait suspendu, sans un mot, sans erreur, sans reprendre la main.
+* Aucun driver ne borne l'établissement par défaut — `pg-pool` traite son
+* `connectionTimeoutMillis` à `0` comme « attendre indéfiniment » — et un
+* serveur qui accepte la connexion TCP sans jamais répondre (conteneur en
+* train de mourir, port relayé vers rien, réseau qui avale les paquets) laisse
+* l'appelant pendu.
+*
+* Une commande de diagnostic qui se bloque est pire qu'une commande qui
+* échoue : l'échec nomme une cause, le blocage n'apprend rien et fait douter
+* de l'outil plutôt que de l'infrastructure.
+*
+* @module
+*/
+/**
+* Le temps qu'on accorde à une base pour ACCEPTER une connexion, en
+* millisecondes.
+*
+* Dix secondes, et ce n'est pas un réglage de performance : c'est la frontière
+* entre « lent » et « ne répondra pas ». Un serveur local répond en quelques
+* millisecondes, un serveur infonuagique qui sort de veille en quelques
+* secondes ; au-delà, ce qui se passe n'est plus une lenteur, et le dire vaut
+* mieux que l'attendre.
+*
+* Volontairement NON configurable : le besoin n'est pas de choisir une durée,
+* c'est de n'attendre jamais sans fin. Une clé de configuration serait une
+* surface publique à porter pour toute une série majeure, au service d'un
+* réglage que personne n'a demandé.
+*/
+const CONNECT_TIMEOUT_MS = 1e4;
+/**
+* Borne l'attente d'une promesse, et rejette avec une cause NOMMÉE au-delà.
+*
+* Le message importe autant que la borne : « délai dépassé » sans sujet
+* envoie chercher partout. Celui-ci dit ce qu'on attendait, de qui, et
+* combien de temps — c'est ce qui distingue un diagnostic d'un abandon.
+*
+* Le minuteur est `unref`é : il ne doit pas, à lui seul, retenir le processus
+* en vie une fois la réponse arrivée.
+*
+* @param work - la promesse à borner (établissement, ping…).
+* @param what - ce qu'on attend, à la première personne du sujet : « la
+*   réponse de postgres 127.0.0.1:5432 ».
+* @param ms - la borne, en millisecondes.
+* @returns la valeur de `work` si elle arrive à temps.
+* @throws Error quand la borne est atteinte — jamais de résolution silencieuse.
+*/
+async function withConnectDeadline(work, what, ms = CONNECT_TIMEOUT_MS) {
+	let timer;
+	try {
+		return await Promise.race([work, new Promise((_, reject) => {
+			timer = setTimeout(() => {
+				reject(/* @__PURE__ */ new Error(`délai dépassé (${ms} ms) en attendant ${what} — le serveur a accepté la connexion sans répondre, ou n'a jamais répondu. Vérifier que le service visé est bien celui qui écoute, et qu'il est en état de servir.`));
+			}, ms);
+			timer.unref?.();
+		})]);
+	} finally {
+		if (timer !== void 0) clearTimeout(timer);
+	}
+}
+//#endregion
+export { CONNECT_TIMEOUT_MS, withConnectDeadline };

package/dist/nodefony/src/connectionDiagnosis.js

@@ -0,0 +1,112 @@
+//#region nodefony/src/connectionDiagnosis.ts
+/**
+* Personne n'écoute : la couche transport a refusé ou n'a trouvé personne.
+* Ces codes viennent du système, pas du serveur de base de données.
+*/
+const UNREACHABLE_CODES = /* @__PURE__ */ new Set([
+	"ECONNREFUSED",
+	"ENOTFOUND",
+	"EHOSTUNREACH",
+	"ENETUNREACH",
+	"EAI_AGAIN"
+]);
+/**
+* Un serveur a répondu ET refusé. Chacun de ces codes est produit par le
+* serveur lui-même — donc il a parlé, donc quelque chose tient le port.
+*
+* PostgreSQL rend des SQLSTATE : classe `28` = autorisation invalide,
+* `3D000` = base inconnue, `53300` = trop de connexions. MySQL et MariaDB
+* rendent des noms `ER_*`. MongoDB nomme ses refus (`AuthenticationFailed`).
+*/
+const ANSWERED_CODES = /* @__PURE__ */ new Set([
+	"28P01",
+	"28000",
+	"3D000",
+	"53300",
+	"ER_ACCESS_DENIED_ERROR",
+	"ER_DBACCESS_DENIED_ERROR",
+	"ER_BAD_DB_ERROR",
+	"ER_NOT_SUPPORTED_AUTH_MODE",
+	"ER_HOST_NOT_PRIVILEGED",
+	"AuthenticationFailed",
+	"Unauthorized"
+]);
+/** Lit le code que le driver a posé sur l'erreur, sans rien supposer de sa forme. */
+function readCode(error) {
+	if (typeof error !== "object" || error === null) return null;
+	const carrier = error;
+	for (const raw of [carrier.code, carrier.codeName]) {
+		if (typeof raw === "string" && raw.length > 0) return raw;
+		if (typeof raw === "number") return String(raw);
+	}
+	return null;
+}
+/**
+* Extrait l'hôte et le port d'une URL de connexion, sans son secret.
+*
+* @param url - URL de connexion (`postgres://…`, `mysql://…`, `mongodb://…`).
+* @returns l'adresse visée ; champs à `null` si l'URL est absente ou illisible.
+*/
+function parseConnectionTarget(url) {
+	if (!url) return {
+		host: null,
+		port: null
+	};
+	try {
+		const parsed = new URL(url);
+		const port = parsed.port ? Number(parsed.port) : null;
+		return {
+			host: parsed.hostname || null,
+			port: Number.isFinite(port) ? port : null
+		};
+	} catch {
+		return {
+			host: null,
+			port: null
+		};
+	}
+}
+/**
+* La commande qui nomme QUI tient un port, sur la plateforme visée.
+*
+* La plateforme est un PARAMÈTRE et non une lecture de `process.platform` : la
+* règle se vérifie alors pour les trois systèmes depuis n'importe lequel, sans
+* machine Windows. `netstat` parce que `lsof` n'existe pas sous Windows, et
+* qu'une commande introuvable est un second mystère à résoudre.
+*/
+function whoHoldsPort(port, platform) {
+	return platform === "win32" ? `netstat -ano | findstr :${port}` : `lsof -nP -iTCP:${port} -sTCP:LISTEN`;
+}
+/**
+* Explique un échec de connexion en distinguant « personne n'écoute » de
+* « quelqu'un a répondu et refuse ».
+*
+* @param error - l'erreur rendue par le driver.
+* @param target - hôte et port visés (cf {@link parseConnectionTarget}).
+* @param platform - plateforme pour laquelle rédiger le geste ; défaut : la courante.
+* @returns le verdict, le code constaté et une explication déjà rédigée.
+*/
+function diagnoseConnectionFailure(error, target = {
+	host: null,
+	port: null
+}, platform = process.platform) {
+	const code = readCode(error);
+	const where = target.host && target.port ? `${target.host}:${target.port}` : target.host ?? "l'adresse configurée";
+	if (code !== null && UNREACHABLE_CODES.has(code)) return {
+		verdict: "unreachable",
+		code,
+		explanation: `personne n'écoute sur ${where} (${code}) — la base n'est pas démarrée, ou l'adresse configurée n'est pas la sienne.`
+	};
+	if (code !== null && ANSWERED_CODES.has(code)) return {
+		verdict: "answered",
+		code,
+		explanation: `un serveur a RÉPONDU sur ${where} puis a refusé (${code}) — donc quelque chose tient bien ce port. Ce peut être la base attendue avec de mauvais identifiants, mais aussi UN AUTRE SERVEUR (le conteneur d'un autre projet, par exemple) : le refus vient alors d'une base qui n'est pas la vôtre, et vérifier les identifiants ne mène nulle part.${target.port !== null ? ` Pour savoir qui tient ce port : « docker ps --filter publish=${target.port} », ou « ${whoHoldsPort(target.port, platform)} ».` : ""}`
+	};
+	return {
+		verdict: "unknown",
+		code,
+		explanation: `échec de connexion à ${where}${code ? ` (${code})` : ""} — vérifier que l'infrastructure déclarée (NF_DATABASE_URL / connectors) désigne bien la base attendue, et qu'elle est démarrée.`
+	};
+}
+//#endregion
+export { diagnoseConnectionFailure, parseConnectionTarget };

package/dist/types/index.d.ts

@@ -25,6 +25,9 @@ export { buildOrmGraph, buildConnectionHealth, buildOrmFlow, toDbml, toJsonSchem
 export { queryFlowMonitor } from "./nodefony/src/QueryFlowMonitor.js";
 export { connectionMonitor } from "./nodefony/src/ConnectionMonitor.js";
 export { buildOrmLeanHealth } from "./nodefony/src/buildOrmLeanHealth.js";
+export { diagnoseConnectionFailure, parseConnectionTarget, } from "./nodefony/src/connectionDiagnosis.js";
+export type { ConnectionVerdict, IConnectionDiagnosis, IConnectionTarget, } from "./nodefony/src/connectionDiagnosis.js";
+export { CONNECT_TIMEOUT_MS, withConnectDeadline, } from "./nodefony/src/connectDeadline.js";
 export { wireOrmAdminPlane, resolveOrmFlowEnabled, reportOrmBootLines, } from "./nodefony/src/ormWiring.js";
 export type { ISlowQuery, IQueryFlow, IOrmFlowReport, } from "./nodefony/interfaces/IOrmFlow.js";
 export type { IColumnInfo, IConnectionInfo, IRelationInfo, IEntityGraphNode, IOrmSummary, IOrmGraph, IConnectionError, IConnectionHealth, } from "./nodefony/interfaces/IOrmGraph.js";

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

@@ -0,0 +1,52 @@
+/**
+ * Le DÉLAI DE GARDE d'une connexion à une base — une commande n'attend jamais
+ * sans fin.
+ *
+ * 🔴 Le cas est vécu, et il ne ressemble pas à une panne : `nodefony inspect
+ * config` restait suspendu, sans un mot, sans erreur, sans reprendre la main.
+ * Aucun driver ne borne l'établissement par défaut — `pg-pool` traite son
+ * `connectionTimeoutMillis` à `0` comme « attendre indéfiniment » — et un
+ * serveur qui accepte la connexion TCP sans jamais répondre (conteneur en
+ * train de mourir, port relayé vers rien, réseau qui avale les paquets) laisse
+ * l'appelant pendu.
+ *
+ * Une commande de diagnostic qui se bloque est pire qu'une commande qui
+ * échoue : l'échec nomme une cause, le blocage n'apprend rien et fait douter
+ * de l'outil plutôt que de l'infrastructure.
+ *
+ * @module
+ */
+/**
+ * Le temps qu'on accorde à une base pour ACCEPTER une connexion, en
+ * millisecondes.
+ *
+ * Dix secondes, et ce n'est pas un réglage de performance : c'est la frontière
+ * entre « lent » et « ne répondra pas ». Un serveur local répond en quelques
+ * millisecondes, un serveur infonuagique qui sort de veille en quelques
+ * secondes ; au-delà, ce qui se passe n'est plus une lenteur, et le dire vaut
+ * mieux que l'attendre.
+ *
+ * Volontairement NON configurable : le besoin n'est pas de choisir une durée,
+ * c'est de n'attendre jamais sans fin. Une clé de configuration serait une
+ * surface publique à porter pour toute une série majeure, au service d'un
+ * réglage que personne n'a demandé.
+ */
+export declare const CONNECT_TIMEOUT_MS = 10000;
+/**
+ * Borne l'attente d'une promesse, et rejette avec une cause NOMMÉE au-delà.
+ *
+ * Le message importe autant que la borne : « délai dépassé » sans sujet
+ * envoie chercher partout. Celui-ci dit ce qu'on attendait, de qui, et
+ * combien de temps — c'est ce qui distingue un diagnostic d'un abandon.
+ *
+ * Le minuteur est `unref`é : il ne doit pas, à lui seul, retenir le processus
+ * en vie une fois la réponse arrivée.
+ *
+ * @param work - la promesse à borner (établissement, ping…).
+ * @param what - ce qu'on attend, à la première personne du sujet : « la
+ *   réponse de postgres 127.0.0.1:5432 ».
+ * @param ms - la borne, en millisecondes.
+ * @returns la valeur de `work` si elle arrive à temps.
+ * @throws Error quand la borne est atteinte — jamais de résolution silencieuse.
+ */
+export declare function withConnectDeadline<T>(work: Promise<T>, what: string, ms?: number): Promise<T>;

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

@@ -0,0 +1,58 @@
+/**
+ * Diagnostic d'un échec de connexion à une base — **ce qui a été CONSTATÉ**,
+ * jamais seulement ce qu'on en déduit.
+ *
+ * Le message d'échec énumérait trois causes (infrastructure déclarée, base
+ * démarrée, entités portées) et aucune n'était la bonne dans un cas fréquent :
+ * **un AUTRE serveur occupe déjà le port**. Vécu sur une application fraîchement
+ * générée — son PostgreSQL n'était pas démarré, mais le conteneur d'un autre
+ * projet écoutait sur `127.0.0.1:5432`. L'application s'y est connectée et a reçu
+ * « password authentication failed ». Le message était EXACT, et c'est ce qui le
+ * rendait trompeur : il est cru, et il envoie vérifier des identifiants justes.
+ *
+ * La distinction qui tranche tient en une question : **quelqu'un a-t-il
+ * répondu ?** `ECONNREFUSED` dit que non — personne n'écoute, la base n'est pas
+ * démarrée. Un refus d'authentification dit que si : un serveur a parlé, donc le
+ * port est tenu, et la question devient « par QUI ? ».
+ *
+ * Vit dans `orm-core` parce que les deux adapters posent la même question : deux
+ * implémentations parallèles diraient deux choses différentes du même symptôme.
+ */
+/** Ce que l'échec permet d'affirmer sur l'autre bout du socket. */
+export type ConnectionVerdict = 
+/** Personne n'a répondu — rien n'écoute à cette adresse. */
+"unreachable"
+/** Un serveur a répondu, et il refuse — le port est bien tenu par quelqu'un. */
+ | "answered"
+/** L'erreur ne permet de trancher ni dans un sens ni dans l'autre. */
+ | "unknown";
+/** Diagnostic rendu à l'appelant, qui compose le message final. */
+export interface IConnectionDiagnosis {
+    verdict: ConnectionVerdict;
+    /** Code CONSTATÉ, tel que le driver l'a rendu (`ECONNREFUSED`, `28P01`, …). */
+    code: string | null;
+    /** Ce qu'on peut affirmer, et le geste qui tranche. Déjà rédigé. */
+    explanation: string;
+}
+/** Adresse visée, telle qu'on peut la dire sans divulguer de secret. */
+export interface IConnectionTarget {
+    host: string | null;
+    port: number | null;
+}
+/**
+ * Extrait l'hôte et le port d'une URL de connexion, sans son secret.
+ *
+ * @param url - URL de connexion (`postgres://…`, `mysql://…`, `mongodb://…`).
+ * @returns l'adresse visée ; champs à `null` si l'URL est absente ou illisible.
+ */
+export declare function parseConnectionTarget(url?: string | null): IConnectionTarget;
+/**
+ * Explique un échec de connexion en distinguant « personne n'écoute » de
+ * « quelqu'un a répondu et refuse ».
+ *
+ * @param error - l'erreur rendue par le driver.
+ * @param target - hôte et port visés (cf {@link parseConnectionTarget}).
+ * @param platform - plateforme pour laquelle rédiger le geste ; défaut : la courante.
+ * @returns le verdict, le code constaté et une explication déjà rédigée.
+ */
+export declare function diagnoseConnectionFailure(error: unknown, target?: IConnectionTarget, platform?: string): IConnectionDiagnosis;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodefony/orm-core",
-  "version": "10.0.0-alpha.2",
+  "version": "10.0.0-alpha.3",
   "description": "Un contrat de dépôt de données pour Nodefony, plusieurs moteurs : interfaces, registre et classes de base pour le support multi-ORM",
   "contributors": [],
   "type": "module",
@@ -36,11 +36,11 @@
     "esm"
   ],
   "peerDependencies": {
-    "nodefony": "^10.0.0-alpha.2"
+    "nodefony": "^10.0.0-alpha.3"
   },
   "devDependencies": {
     "@types/node": "26.4.1",
-    "nodefony": "^10.0.0-alpha.2",
+    "nodefony": "^10.0.0-alpha.3",
     "rimraf": "6.1.3",
     "vitest": "5.0.0"
   },