@nodefony/orm-core 10.0.0-beta.5 → 10.0.0-beta.6

package/README.md

@@ -99,20 +99,35 @@ du module**, sur la classe et non sur une instance : il connaît donc son nom et
 instancier, et enregistre l'entité directement.
 
 ```typescript
+import { randomUUID } from "node:crypto";
 import { entity, repository } from "@nodefony/orm-core";
 import type { IRepository } from "@nodefony/orm-core";
+import { defineTable } from "@nodefony/drizzle";
+
+// Le `schema` est la forme de l'ADAPTATEUR : ici la description portable du kit
+// Drizzle, qui suit le dialecte du connecteur.
+const memberTable = defineTable({
+  name: "Member",
+  columns: {
+    id: { kind: "uuid", primaryKey: true, defaultFn: () => randomUUID() },
+    email: { kind: "string", length: 255, notNull: true },
+  },
+});
 
-// `name` vaut par défaut le nom de la classe ; ici forcé à "User".
+// `name` vaut par défaut le nom de la classe ; ici forcé à "Member".
 @entity({
   connector: "db_principale",
-  name: "User",
-  schema: { id: { type: "uuid", primaryKey: true }, email: { type: "string" } },
+  name: "Member",
+  schema: memberTable,
   relations: [{ type: "one-to-many", target: "Room", field: "rooms" }],
 })
-class UserEntity {}
+class MemberEntity {}
 
-@repository("repository.user", { entity: "User", connector: "db_principale" })
-class UserRepository implements IRepository<UserEntity> {
+@repository("repository.member", {
+  entity: "Member",
+  connector: "db_principale",
+})
+class MemberRepository implements IRepository<MemberEntity> {
   /* find, findOne, create… sont fournis par l'adaptateur ORM */
 }
 ```

package/dist/index.js

@@ -4,13 +4,13 @@ import { assertOrderOption } from "./nodefony/src/readOptions.js";
 import { OrmRegistry, ormRegistry } from "./nodefony/src/OrmRegistry.js";
 import { EntityRegistry, entityRegistry } from "./nodefony/src/EntityRegistry.js";
 import { reportOrphanEntities } from "./nodefony/src/orphanEntities.js";
-import { connectionMonitor } from "./nodefony/src/ConnectionMonitor.js";
 import { Orm } from "./nodefony/src/Orm.js";
 import { Entity } from "./nodefony/src/Entity.js";
-import { paginate } from "./nodefony/src/paginate.js";
 import { AbstractCrudService } from "./nodefony/src/AbstractCrudService.js";
-import { queryFlowMonitor } from "./nodefony/src/QueryFlowMonitor.js";
+import { paginate } from "./nodefony/src/paginate.js";
 import { buildConnectionHealth, buildOrmFlow, buildOrmGraph, createOrmAdminApi, registerOrmAdminApi, toDbml, toJsonSchema } from "./nodefony/src/OrmAdminApi.js";
+import { queryFlowMonitor } from "./nodefony/src/QueryFlowMonitor.js";
+import { connectionMonitor } from "./nodefony/src/ConnectionMonitor.js";
 import { buildOrmLeanHealth } from "./nodefony/src/buildOrmLeanHealth.js";
 import { REJECTED_MARKER, describeConnectFailure, diagnoseConnectionFailure, parseConnectionTarget } from "./nodefony/src/connectionDiagnosis.js";
 import { CONNECT_TIMEOUT_MS, withConnectDeadline } from "./nodefony/src/connectDeadline.js";

package/dist/nodefony/src/OrmAdminApi.js

@@ -131,8 +131,51 @@ function buildOrmSummaries() {
 	});
 }
 /**
-* Construit un nœud de graphe pour une entité : relations (toujours) + colonnes
-* (via `orm.describeEntity` si l'adapter l'implémente et si l'ORM est connecté).
+* Clé étrangère d'une relation qui n'en nomme aucune : `<entité>Id`, l'entité
+* en minuscule initiale — la convention des adapters.
+*
+* @param entity - nom logique de l'entité qui donne son nom à la clé.
+* @returns le nom de colonne conventionnel.
+*/
+function conventionalForeignKey(entity) {
+	return `${entity.charAt(0).toLowerCase()}${entity.slice(1)}Id`;
+}
+/**
+* Relations d'un nœud : celles que l'entité DÉCLARE, puis une « plusieurs vers
+* un » par clé étrangère que la base porte et qu'aucune déclaration ne couvre.
+*
+* Sans la seconde moitié, une entité qui référence par ses colonnes (`ref` du
+* kit, table écrite à la main) sans répéter le lien dans `relations` n'avait
+* AUCUNE arête dans le graphe, alors que la contrainte existe en base.
+* Une déclaration couvre une colonne quand sa clé — explicite, ou
+* conventionnelle — est cette colonne.
+*/
+function nodeRelations(declared, columns) {
+	const relations = declared.map((r) => ({
+		type: r.type,
+		target: r.target,
+		field: r.field,
+		foreignKey: r.foreignKey
+	}));
+	let covered = null;
+	for (const col of columns) {
+		if (col.references === void 0) continue;
+		covered ??= new Set(declared.filter((r) => r.type === "many-to-one" || r.type === "one-to-one").map((r) => r.foreignKey ?? conventionalForeignKey(r.target)));
+		if (covered.has(col.name)) continue;
+		relations.push({
+			type: "many-to-one",
+			target: col.references.entity,
+			field: col.name,
+			foreignKey: col.name,
+			targetKey: col.references.column
+		});
+	}
+	return relations;
+}
+/**
+* Construit un nœud de graphe pour une entité : colonnes (via
+* `orm.describeEntity` si l'adapter l'implémente et si l'ORM est connecté) et
+* relations, déclarées puis imposées par les clés étrangères.
 */
 function buildEntityNode(connector, name) {
 	const entity = entityRegistry.get(name, connector);
@@ -148,12 +191,7 @@ function buildEntityNode(connector, name) {
 		module: entity.module ?? "",
 		domain: entity.domain ?? "",
 		columns,
-		relations: (entity.relations ?? []).map((r) => ({
-			type: r.type,
-			target: r.target,
-			field: r.field,
-			foreignKey: r.foreignKey
-		}))
+		relations: nodeRelations(entity.relations ?? [], columns)
 	};
 }
 /** Construit le graphe canonique complet (optionnellement filtré par connecteur). */
@@ -327,13 +365,13 @@ function toDbml(graph) {
 			refs.add(`// many-to-many ${node.name}.${rel.field} <> ${rel.target} (table de jonction)`);
 			continue;
 		}
-		const camel = (n) => `${n.charAt(0).toLowerCase()}${n.slice(1)}Id`;
+		const key = dbmlId(rel.targetKey ?? "id");
 		if (rel.type === "one-to-many") {
-			const fk = rel.foreignKey ?? camel(node.name);
-			refs.add(`Ref: ${dbmlId(rel.target)}.${dbmlId(fk)} > ${dbmlId(node.name)}.id`);
+			const fk = rel.foreignKey ?? conventionalForeignKey(node.name);
+			refs.add(`Ref: ${dbmlId(rel.target)}.${dbmlId(fk)} > ${dbmlId(node.name)}.${key}`);
 		} else {
-			const fk = rel.foreignKey ?? camel(rel.target);
-			refs.add(`Ref: ${dbmlId(node.name)}.${dbmlId(fk)} > ${dbmlId(rel.target)}.id`);
+			const fk = rel.foreignKey ?? conventionalForeignKey(rel.target);
+			refs.add(`Ref: ${dbmlId(node.name)}.${dbmlId(fk)} > ${dbmlId(rel.target)}.${key}`);
 		}
 	}
 	lines.push(...refs);
@@ -529,4 +567,4 @@ function registerOrmAdminApi(registry) {
 	if (registry.has("orm")) return;
 	registry.register(createOrmAdminApi());
 }
-export { buildConnectionHealth, buildOrmFlow, buildOrmGraph, createOrmAdminApi, registerOrmAdminApi, storeCarrier, toDbml, toJsonSchema };
+export { buildConnectionHealth, buildOrmFlow, buildOrmGraph, conventionalForeignKey, createOrmAdminApi, registerOrmAdminApi, storeCarrier, toDbml, toJsonSchema };

package/dist/nodefony/src/decorators/index.js

@@ -1,5 +1,5 @@
-import { getEntityMeta, getRepositoryMeta, hasEntityMeta, hasRepositoryMeta } from "./metadataStore.js";
 import { entity } from "./entityDecorator.js";
 import { DEFAULT_CONNECTOR, entities } from "./entitiesDecorator.js";
 import { repository } from "./repositoryDecorator.js";
+import { getEntityMeta, getRepositoryMeta, hasEntityMeta, hasRepositoryMeta } from "./metadataStore.js";
 export { DEFAULT_CONNECTOR, entities, entity, getEntityMeta, getRepositoryMeta, hasEntityMeta, hasRepositoryMeta, repository };

package/dist/nodefony/src/ormWiring.js

@@ -1,6 +1,6 @@
-import { ormRegistry } from "./OrmRegistry.js";
 import { buildConnectionHealth, buildOrmFlow, registerOrmAdminApi } from "./OrmAdminApi.js";
 import { buildOrmLeanHealth } from "./buildOrmLeanHealth.js";
+import { ormRegistry } from "./OrmRegistry.js";
 import { setOrmHealthProvider, setOrmRichProvider } from "nodefony";
 // nodefony/src/ormWiring.ts
 /**

package/dist/nodefony/src/orphanEntities.js

@@ -1,5 +1,5 @@
-import { ormRegistry } from "./OrmRegistry.js";
 import { entityRegistry } from "./EntityRegistry.js";
+import { ormRegistry } from "./OrmRegistry.js";
 // nodefony/src/orphanEntities.ts
 /**
 * Entités inscrites sur un connecteur qu'aucun ORM n'a ouvert.

package/dist/types/index.d.ts

@@ -31,7 +31,7 @@ export type { ConnectionVerdict, IConnectionDiagnosis, IConnectionTarget, } from
 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, IConnectionEvent, IOrmResilience, IConnectionHealth, } from "./nodefony/interfaces/IOrmGraph.js";
+export type { IColumnInfo, IColumnReference, IConnectionInfo, IRelationInfo, IEntityGraphNode, IOrmSummary, IOrmGraph, IConnectionError, IConnectionEvent, IOrmResilience, IConnectionHealth, } from "./nodefony/interfaces/IOrmGraph.js";
 export type { ILatencyWindow, IOrmStorageProbe, IOrmPoolProbe, IOrmProbe, } from "./nodefony/interfaces/IOrmProbe.js";
 export type { IOrmMigrationAction, IOrmMigrationEntry, IOrmMigrationSource, IOrmMigrationStatus, IOrmMigrationFailure, IOrmMigrationReply, IOrmPendingMigration, IOrmMigrationPlan, IOrmMigrationPlanReply, IOrmMigrationApplied, IOrmMigrationApplyReply, } from "./nodefony/interfaces/IOrmMigrations.js";
 export { isMigrationFailure } from "./nodefony/interfaces/IOrmMigrations.js";

package/dist/types/nodefony/interfaces/IEntity.d.ts

@@ -81,4 +81,16 @@ export interface IEntity<S = unknown, M = unknown> {
      * dans leur table → ce champ y est sans effet. **Optionnel**.
      */
     readonly indexes?: ReadonlyArray<IEntityIndex> | undefined;
+    /**
+     * Champs qui ne sortent JAMAIS par une relation : quand une autre entité
+     * charge celle-ci (`relations: ["owner"]`, `?include=owner`), l'adapter ne les
+     * lit pas. Le dépôt de l'entité elle-même les rend toujours — c'est la porte
+     * de qui en a besoin (l'authentification lit `password` par là).
+     *
+     * Sans cette déclaration, référencer un `User` exposait son empreinte de mot
+     * de passe à quiconque lisait la ressource qui le référence. Un nom qui ne
+     * désigne aucun champ fait échouer la connexion en le nommant : une faute de
+     * frappe ici rouvrirait la fuite sans un mot. **Optionnel**.
+     */
+    readonly privateFields?: ReadonlyArray<string> | undefined;
 }

package/dist/types/nodefony/interfaces/IOrmGraph.d.ts

@@ -22,6 +22,20 @@ export interface IColumnInfo {
     nullable: boolean;
     /** `true` si contrainte d'unicité. */
     unique: boolean;
+    /**
+     * Cible de la clé étrangère que la BASE porte sur cette colonne — absente si
+     * la colonne n'en porte pas, ou si l'adapter ne sait pas la lire. Le graphe
+     * en dérive une relation « plusieurs vers un » quand aucune relation déclarée
+     * ne couvre déjà la colonne.
+     */
+    references?: IColumnReference | undefined;
+}
+/** Cible d'une clé étrangère : l'entité visée et la colonne qu'elle y désigne. */
+export interface IColumnReference {
+    /** Nom logique de l'entité visée (nom de table si aucune entité ne la porte). */
+    entity: string;
+    /** Colonne visée (en général la clé primaire). */
+    column: string;
 }
 /** Relation projetée pour le graphe (sous-ensemble sérialisable de `IEntityRelation`). */
 export interface IRelationInfo {
@@ -33,6 +47,8 @@ export interface IRelationInfo {
     field: string;
     /** Clé étrangère (explicite ou dérivée déterministe). */
     foreignKey?: string | undefined;
+    /** Colonne visée sur la cible — `id` par convention quand elle est absente. */
+    targetKey?: string | undefined;
 }
 /** Nœud du graphe : une entité avec ses colonnes et ses relations. */
 export interface IEntityGraphNode {
@@ -51,7 +67,10 @@ export interface IEntityGraphNode {
     domain: string;
     /** Colonnes normalisées (vide si l'adapter n'implémente pas `describeEntity`). */
     columns: IColumnInfo[];
-    /** Relations déclarées. */
+    /**
+     * Relations : celles que l'entité DÉCLARE, puis celles que ses clés
+     * étrangères imposent et qu'aucune déclaration ne couvre.
+     */
     relations: IRelationInfo[];
 }
 /** Connexion sous-jacente d'un ORM (extrait via {@link IOrm.describeConnection}). */

package/dist/types/nodefony/interfaces/index.d.ts

@@ -3,5 +3,5 @@ export type { IEntity, IEntityIndex, IEntityRelation } from "./IEntity.js";
 export type { IRepository, OrmCriteria, Criteria, FieldCriteria, FieldOperators, UpdateData, UpdateOperators, RepositoryReadOptions, } from "./IRepository.js";
 export type { ITransaction } from "./ITransaction.js";
 export type { IPage, IPageQuery, PageQuery } from "./IPage.js";
-export type { IColumnInfo, IConnectionInfo, IRelationInfo, IEntityGraphNode, IOrmSummary, IOrmGraph, IConnectionError, IConnectionEvent, IOrmResilience, IConnectionHealth, } from "./IOrmGraph.js";
+export type { IColumnInfo, IColumnReference, IConnectionInfo, IRelationInfo, IEntityGraphNode, IOrmSummary, IOrmGraph, IConnectionError, IConnectionEvent, IOrmResilience, IConnectionHealth, } from "./IOrmGraph.js";
 export type { ILatencyWindow, IOrmStorageProbe, IOrmPoolProbe, IOrmProbe, } from "./IOrmProbe.js";

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

@@ -17,6 +17,14 @@ import type { IOrmFlowReport } from "../interfaces/IOrmFlow.js";
  *   un ORM (le repli sur le nom `default` s'applique alors).
  */
 export declare function storeCarrier(resolutions: readonly IStoreResolution[], names: readonly string[]): string | null;
+/**
+ * Clé étrangère d'une relation qui n'en nomme aucune : `<entité>Id`, l'entité
+ * en minuscule initiale — la convention des adapters.
+ *
+ * @param entity - nom logique de l'entité qui donne son nom à la clé.
+ * @returns le nom de colonne conventionnel.
+ */
+export declare function conventionalForeignKey(entity: string): string;
 /** Construit le graphe canonique complet (optionnellement filtré par connecteur). */
 export declare function buildOrmGraph(connectorFilter?: string): IOrmGraph;
 /**

package/docs/index.md

@@ -478,7 +478,11 @@ atomique sur les quatre backends.
 d'un moteur), un `schema` natif du driver, et des `relations` déclaratives (`IEntityRelation`,
 `IEntity.ts#IEntityRelation`). Deux champs facultatifs servent la lisibilité d'un gros modèle : `module` (qui
 apporte l'entité) et `domain` (`IEntity.ts#IEntity.domain`, la classification métier — l'axe qui rend navigable
-une base de plusieurs centaines de tables). Un troisième, `indexes` (`IEntityIndex`), déclare les
+une base de plusieurs centaines de tables ; `create entity --domain` le pose). Le graphe d'entités ne
+se limite pas aux `relations` déclarées : une colonne qui porte une clé étrangère en base en rend la
+cible (`IOrmGraph.ts#IColumnReference`, lue par `describeEntity`), et le graphe en tire une
+relation « plusieurs vers un » quand aucune déclaration ne couvre déjà la colonne
+(`OrmAdminApi.ts#conventionalForeignKey` dit quelle colonne une déclaration couvre). Un troisième, `indexes` (`IEntityIndex`), déclare les
 index COMPOSITES qu'un adaptateur ne sait pas exprimer dans son schéma : Mongoose les applique
 (`schema.index()`), Drizzle les ignore, puisqu'il les déclare dans sa table.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodefony/orm-core",
-  "version": "10.0.0-beta.5",
+  "version": "10.0.0-beta.6",
   "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",
@@ -37,12 +37,12 @@
     "esm"
   ],
   "peerDependencies": {
-    "nodefony": "^10.0.0-beta.5"
+    "nodefony": "^10.0.0-beta.6"
   },
   "devDependencies": {
-    "@types/node": "26.6.5",
-    "nodefony": "^10.0.0-beta.5",
-    "vitest": "5.0.5"
+    "@types/node": "26.6.6",
+    "nodefony": "^10.0.0-beta.6",
+    "vitest": "5.1.0"
   },
   "repository": {
     "type": "git",