@nodefony/drizzle 10.0.0-alpha.1

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

@@ -0,0 +1,610 @@
+import { likeCond } from "../likeSql.js";
+import { RequestContext, redactSecrets } from "nodefony";
+import { UnknownCriteriaField, assertOrderOption, isFieldOperators, isUpdateOperators, queryFlowMonitor } from "@nodefony/orm-core";
+import { and, asc, count, countDistinct, desc, eq, getTableColumns, getTableName, gt, gte, inArray, isNotNull, isNull, lt, lte, ne, notInArray, or, sql } from "drizzle-orm";
+import { getTableConfig } from "drizzle-orm/sqlite-core";
+import { getTableConfig as getTableConfig$1 } from "drizzle-orm/pg-core";
+import { getTableConfig as getTableConfig$2 } from "drizzle-orm/mysql-core";
+//#region nodefony/src/orm-core/DrizzleRepository.ts
+/**
+* Vue d'exécution canonique (typage sqlite) d'une table multi-dialecte —
+* **LE point unique** de conversion vers les builders (cf {@link DrizzleDb} :
+* la surface builder est structurellement identique sqlite/pg, prouvée e2e).
+* Consommé aussi par les stores à requêtes builder (`DrizzleAuditStore`).
+*/
+function execTable(table) {
+	return table;
+}
+/**
+* Borne du cache de formes préparées d'un repository — au-delà, les formes
+* excédentaires s'exécutent par le chemin non préparé (repli, jamais d'éviction :
+* une entrée retient un statement natif, l'éviction re-préparerait en boucle).
+*/
+const PREPARED_CACHE_MAX = 128;
+/** Séquence des noms de prepared statements (PG les exige uniques par process). */
+let preparedNameSeq = 0;
+/**
+* Repository portable (contrat {@link IRepository}) au-dessus d'une table Drizzle
+* + driver `better-sqlite3`.
+*
+* 3ᵉ adapter du banc orm-core (ADR-0003) : valide le contrat sur un ORM
+* **type-safe-first** dont le `WHERE` est un *builder* d'expressions (pas un objet
+* plat). Spécificités traduites ici :
+* - critère portable → expressions Drizzle (`eq`/`and`/`gt`/`inArray`/`like`...),
+*   opérateurs riches inclus (résolution ADR-0003 risque #3) ;
+* - **eager-load manuel** (`options.relations`) : une requête `IN (...)` par
+*   relation déclarée, puis regroupement en mémoire — portable sans déclarer la
+*   couche `relations()` de Drizzle ;
+* - liaison transactionnelle via {@link DrizzleRepository.withTransaction} (le
+*   handle de transaction *est* un db Drizzle → réutilisé tel quel).
+*
+* @typeParam T - forme plate de l'entité gérée.
+*/
+var DrizzleRepository = class DrizzleRepository {
+	#db;
+	#table;
+	#relations;
+	/** Connecteur ORM (clé du registre) — tag des métriques de flux. */
+	#connector;
+	/** Dialecte SQL du connecteur — route les rares divergences syntaxiques
+	*  (OFFSET-sans-LIMIT, introspection PK composite). */
+	#dialect;
+	/**
+	* Colonnes de la clé primaire (lazy — résolu au premier `*One`) : `null` =
+	* aucune PK déclarée (fallback `rowid`, SQLite-only) ; `undefined` = pas
+	* encore résolu. Rien d'alloué au constructeur (règle perf).
+	*/
+	#pk;
+	/**
+	* Cache des `SELECT` préparés, indexé par FORME de requête (lazy — alloué au
+	* premier `find` mémoïsable, règle perf). Vit aussi longtemps que le
+	* repository — que `DrizzleOrm.getRepository` mémoïse et jette au
+	* `disconnect()` avec les statements qu'il retient.
+	*/
+	#preparedSelects = null;
+	/** `true` = repository lié à une transaction : mémoïsation coupée (cf ctor). */
+	#transactional;
+	/**
+	* @param db - handle Drizzle (instance racine ou transaction).
+	* @param table - table Drizzle de l'entité (variante du dialecte).
+	* @param relations - relations résolues (eager-load), indexées par champ.
+	* @param connector - nom de la connexion (clé du registre) — défaut `"default"`.
+	* @param dialect - dialecte SQL du connecteur — défaut `"sqlite"`.
+	* @param transactional - `true` quand `db` est un handle de transaction :
+	*   l'instance est jetable (une par `withTransaction`) et, en pg, sa connexion
+	*   dédiée est rendue au commit — préparer dessus coûterait sans jamais
+	*   s'amortir. Les transactions gardent le chemin non préparé.
+	*/
+	constructor(db, table, relations, connector = "default", dialect = "sqlite", transactional = false) {
+		this.#db = db;
+		this.#table = table;
+		this.#relations = relations;
+		this.#connector = connector;
+		this.#dialect = dialect;
+		this.#transactional = transactional;
+	}
+	/** Colonne Drizzle d'une table par nom logique. */
+	#col(table, name) {
+		return table[name];
+	}
+	/**
+	* Colonnes de la PK de la table (mémoïsées) : colonnes inline `.primaryKey()`
+	* d'abord (introspection core, valide sur tous les dialectes — couvre toutes
+	* les entités framework), sinon PK composite déclarée via `primaryKey({
+	* columns })` (extraConfig du dialecte, best-effort), sinon `null`.
+	*/
+	#pkColumns() {
+		if (this.#pk !== void 0) return this.#pk;
+		let cols = Object.values(getTableColumns(this.#table)).filter((col) => col.primary);
+		if (cols.length === 0) try {
+			cols = this.#dialect === "postgres" ? [...getTableConfig$1(this.#table).primaryKeys[0]?.columns ?? []] : this.#dialect === "mysql" ? [...getTableConfig$2(this.#table).primaryKeys[0]?.columns ?? []] : [...getTableConfig(this.#table).primaryKeys[0]?.columns ?? []];
+		} catch {
+			cols = [];
+		}
+		this.#pk = cols.length > 0 ? cols : null;
+		return this.#pk;
+	}
+	/**
+	* Prédicat `WHERE` qui borne un UPDATE/DELETE à **au plus une** ligne :
+	* `pk IN (SELECT pk FROM (SELECT pk FROM t WHERE … LIMIT 1) AS picked)`.
+	*
+	* POURQUOI cette forme (et pas `rowid` / `LIMIT` direct) :
+	* - `rowid` est SQLite-only — c'était le SQL dialect-spécifique n°1 du
+	*   repository (audit comparatif ORM 2026-07, garde-fou G3) ;
+	* - `UPDATE … LIMIT 1` n'est pas du SQL standard (PG le rejette) ;
+	* - la **table dérivée** intermédiaire est requise par MySQL, qui interdit à
+	*   la fois `LIMIT` dans une sous-requête `IN` directe ET la re-lecture de
+	*   la table cible d'un UPDATE/DELETE en sous-requête (ERROR 1093) — la
+	*   dérivée force la matérialisation. SQLite et PG l'acceptent telle quelle
+	*   → une seule forme pour les trois dialectes ;
+	* - PK composite : row-values `(a, b) IN (…)` (SQLite ≥ 3.15 / PG / MySQL).
+	*
+	* Fallback sans PK déclarée : `rowid` (SQLite-only — toutes les entités
+	* framework ont une PK ; une table d'app sans PK est un cas sqlite assumé).
+	*/
+	#pickOne(where) {
+		const pk = this.#pkColumns();
+		if (!pk) return where ? sql`rowid in (select rowid from ${this.#table} where ${where} limit 1)` : sql`rowid in (select rowid from ${this.#table} limit 1)`;
+		const qualified = sql.join(pk, sql.raw(", "));
+		const inner = where ? sql`select ${qualified} from ${this.#table} where ${where} limit 1` : sql`select ${qualified} from ${this.#table} limit 1`;
+		const output = sql.join(pk.map((col) => sql.identifier(col.name)), sql.raw(", "));
+		const first = pk[0];
+		const target = pk.length === 1 && first ? sql`${first}` : sql`(${qualified})`;
+		return sql`${target} in (select ${output} from (${inner}) as picked)`;
+	}
+	/**
+	* Lignes affectées, normalisé par driver : better-sqlite3 `{changes}` /
+	* pg `{rowCount}` / mysql2 tuple `[ResultSetHeader{affectedRows}, fields]`.
+	*/
+	#affected(result) {
+		if (Array.isArray(result)) return result[0]?.affectedRows ?? 0;
+		const r = result;
+		return r.changes ?? r.rowCount ?? 0;
+	}
+	/** Tronque + redacte un SQL paramétré pour l'affichage (jamais de valeur). */
+	#safeSql(builder) {
+		let statement;
+		try {
+			statement = builder.toSQL().sql;
+		} catch {
+			statement = "<drizzle query>";
+		}
+		return redactSecrets(statement.length > 2e3 ? `${statement.slice(0, 2e3)}…` : statement);
+	}
+	/**
+	* Tap dev-only : exécute le builder en mesurant la durée, alimente **deux**
+	* sondes complémentaires (sans surcoût quand les deux sont inactives) :
+	*  1. **profiler par-requête** (buffer de scope ALS, debug bar) — capture le
+	*     SQL paramétré de CHAQUE requête tracée ;
+	*  2. **flux ORM agrégé** ({@link queryFlowMonitor}, process-wide) — compte le
+	*     débit + la latence ; n'extrait le SQL que sur le chemin **lent** (rare).
+	*
+	* POURQUOI lecture directe de l'ALS (≠ tap par-requête d'un autre ORM) :
+	* `better-sqlite3` est **synchrone**, sans pool → l'ALS reste valide pendant
+	* `await builder`. Les deux drapeaux sont lus **avant toute allocation** →
+	* coût nul quand rien n'observe (prod, bancs de charge hors kernel).
+	*
+	* Sécurité : `toSQL()` renvoie le SQL **paramétré** (placeholders `?`, jamais
+	* les valeurs) → credentials hors texte ; `redactSecrets` en défense en profondeur.
+	*
+	* @param builder - requête Drizzle (thenable + `toSQL()`).
+	* @returns le résultat de la requête.
+	*/
+	async #prof(builder) {
+		if (!RequestContext.get()?.queries && !queryFlowMonitor.enabled) return builder;
+		return this.#measure(() => builder, () => this.#safeSql(builder));
+	}
+	/**
+	* Tap des `SELECT` préparés — même contrat que {@link DrizzleRepository.#prof}
+	* (mêmes deux sondes, mêmes drapeaux), le SQL redacté étant ici précalculé à
+	* la construction de l'entrée (zéro `toSQL()` par requête).
+	*/
+	async #profPrepared(entry, params) {
+		if (!RequestContext.get()?.queries && !queryFlowMonitor.enabled) return entry.prepared.execute(params);
+		return this.#measure(() => entry.prepared.execute(params), () => entry.sqlSafe);
+	}
+	/**
+	* Cœur de mesure partagé des deux taps : exécute, chronomètre, alimente le
+	* flux agrégé ({@link queryFlowMonitor} — texte SQL sur le chemin lent
+	* seulement) et le buffer par-requête (ALS, debug bar). N'est appelé QUE
+	* quand une sonde est active — il peut donc relire les deux drapeaux sans
+	* coût pour le chemin nominal.
+	*/
+	async #measure(run, sqlSafe) {
+		const buf = RequestContext.get()?.queries;
+		const flow = queryFlowMonitor.enabled;
+		const start = performance.now();
+		const result = await run();
+		const durationMs = performance.now() - start;
+		if (flow) {
+			const statement = durationMs >= queryFlowMonitor.slowMs ? sqlSafe() : void 0;
+			queryFlowMonitor.record(this.#connector, durationMs, statement);
+		}
+		if (buf) buf.push({
+			sql: sqlSafe(),
+			startMs: start,
+			durationMs,
+			rows: Array.isArray(result) ? result.length : void 0,
+			connector: "drizzle"
+		});
+		return result;
+	}
+	/** Empile les conditions d'un objet d'opérateurs riches sur une colonne. */
+	#pushOperators(conds, col, ops) {
+		if (ops.$eq !== void 0) conds.push(eq(col, ops.$eq));
+		if (ops.$ne !== void 0) conds.push(ne(col, ops.$ne));
+		if (ops.$gt !== void 0) conds.push(gt(col, ops.$gt));
+		if (ops.$gte !== void 0) conds.push(gte(col, ops.$gte));
+		if (ops.$lt !== void 0) conds.push(lt(col, ops.$lt));
+		if (ops.$lte !== void 0) conds.push(lte(col, ops.$lte));
+		if (ops.$in !== void 0) conds.push(inArray(col, [...ops.$in]));
+		if (ops.$nin !== void 0) conds.push(notInArray(col, [...ops.$nin]));
+		if (ops.$like !== void 0) conds.push(likeCond(this.#dialect, sql`${col}`, ops.$like));
+		if (ops.$null !== void 0) conds.push(ops.$null ? isNull(col) : isNotNull(col));
+	}
+	/** Traduit un critère portable en expression `WHERE` Drizzle (ou `undefined`). */
+	#where(criteria) {
+		if (!criteria) return;
+		const conds = [];
+		for (const [field, value] of Object.entries(criteria)) {
+			if (field === "$or") {
+				if (!Array.isArray(value)) throw new Error(`DrizzleRepository(${getTableName(this.#table)}): $or attend un tableau de critères.`);
+				const branches = value.map((branch) => this.#where(branch)).filter((branch) => branch !== void 0);
+				if (branches.length > 0) conds.push(branches.length === 1 ? branches[0] : or(...branches));
+				continue;
+			}
+			const col = this.#col(this.#table, field);
+			if (!col) throw new UnknownCriteriaField(field, getTableName(this.#table), Object.keys(getTableColumns(this.#table)));
+			if (isFieldOperators(value)) this.#pushOperators(conds, col, value);
+			else if (value === null) conds.push(isNull(col));
+			else conds.push(eq(col, value));
+		}
+		if (conds.length === 0) return;
+		return conds.length === 1 ? conds[0] : and(...conds);
+	}
+	/**
+	* FORME d'un `SELECT` mémoïsable + valeurs à binder, ou `null` si la requête
+	* doit rester sur le chemin non préparé.
+	*
+	* La forme = ce qui décide du TEXTE SQL : champs du critère dans l'ordre
+	* (un `null` y est marqué à part — `IS NULL` n'est pas paramétrable), tri,
+	* présence de limit/offset. Les VALEURS n'en font jamais partie : elles
+	* deviennent des placeholders (`p<i>`, `lim`, `off`) bindés à l'exécution.
+	*
+	* Repli (`null`) par construction : `$or` et opérateurs riches (le SQL varie
+	* avec la cardinalité — `$in` — ou la combinaison d'opérateurs), valeur
+	* `undefined` (le chemin actuel la rejette, même contrat), transaction
+	* (cf ctor), cache plein ({@link PREPARED_CACHE_MAX}).
+	*/
+	#selectShape(criteria, options) {
+		let key = "";
+		const params = {};
+		if (criteria) {
+			let i = 0;
+			for (const [field, value] of Object.entries(criteria)) {
+				if (field === "$or" || value === void 0 || isFieldOperators(value)) return null;
+				if (value === null) key += `${field}\x01\x00`;
+				else {
+					key += `${field}\x00`;
+					params[`p${i}`] = value;
+				}
+				i++;
+			}
+		}
+		if (options?.order?.length) {
+			key += "";
+			for (const [field, dir] of options.order) key += `${field}\x03${dir}\x00`;
+		}
+		if (options?.limit !== void 0) {
+			key += "L";
+			params["lim"] = options.limit;
+		}
+		if (options?.offset !== void 0) {
+			key += "O";
+			params["off"] = options.offset;
+		}
+		return {
+			key,
+			params
+		};
+	}
+	/**
+	* Construit puis PRÉPARE le `SELECT` d'une forme — même composition que le
+	* chemin non préparé de {@link DrizzleRepository.#runSelect}, les valeurs
+	* remplacées par `sql.placeholder()`. Payé UNE fois par forme :
+	* - sqlite : le statement natif better-sqlite3 est compilé ici et réutilisé
+	*   (`client.prepare` dans le `prepareQuery` du driver) ;
+	* - postgres : requête NOMMÉE node-postgres → plan caché par connexion du
+	*   pool (le nom, unique par process, est exigé par `prepare(name)`) ;
+	* - mysql : drizzle passe par `client.query()` (jamais de prepare protocole)
+	*   → le gain se limite à ne plus refaire `sqlToQuery` à chaque requête.
+	*/
+	#buildPreparedSelect(criteria, options) {
+		let query = this.#db.select().from(execTable(this.#table)).$dynamic();
+		if (criteria) {
+			const conds = [];
+			let i = 0;
+			for (const [field, value] of Object.entries(criteria)) {
+				const col = this.#col(this.#table, field);
+				if (!col) throw new UnknownCriteriaField(field, getTableName(this.#table), Object.keys(getTableColumns(this.#table)));
+				conds.push(value === null ? isNull(col) : eq(col, sql.param(sql.placeholder(`p${i}`), col)));
+				i++;
+			}
+			if (conds.length > 0) query = query.where(conds.length === 1 ? conds[0] : and(...conds));
+		}
+		if (options?.order?.length) query = query.orderBy(...options.order.map(([field, dir]) => dir === "DESC" ? desc(this.#col(this.#table, field)) : asc(this.#col(this.#table, field))));
+		if (options?.limit !== void 0) query = query.limit(sql.placeholder("lim"));
+		else if (options?.offset !== void 0 && this.#dialect === "sqlite") query = query.limit(sql`-1`);
+		else if (options?.offset !== void 0 && this.#dialect === "mysql") query = query.limit(Number.MAX_SAFE_INTEGER);
+		if (options?.offset !== void 0) query = query.offset(sql.placeholder("off"));
+		const sqlSafe = this.#safeSql(query);
+		return {
+			prepared: query.prepare(`nf_ps_${++preparedNameSeq}`),
+			sqlSafe
+		};
+	}
+	/**
+	* Entrée préparée d'un `SELECT` + valeurs à binder, ou `null` (repli chemin
+	* non préparé). C'est LE remède au goulot mesuré du cycle ORM : drizzle
+	* refabriquait (`build` ~39 % du CPU du chemin read) et re-préparait (~9 %)
+	* la MÊME requête à chaque requête HTTP — la forme ne changeait jamais, seules
+	* les valeurs bindées changeaient.
+	*/
+	#preparedSelect(criteria, options) {
+		if (this.#transactional) return null;
+		const shape = this.#selectShape(criteria, options);
+		if (shape === null) return null;
+		let cache = this.#preparedSelects;
+		if (cache === null) cache = this.#preparedSelects = /* @__PURE__ */ new Map();
+		let entry = cache.get(shape.key);
+		if (entry === void 0) {
+			if (cache.size >= PREPARED_CACHE_MAX) return null;
+			entry = this.#buildPreparedSelect(criteria, options);
+			cache.set(shape.key, entry);
+		}
+		return {
+			entry,
+			params: shape.params
+		};
+	}
+	/**
+	* Exécute le `SELECT` (critère + pagination + tri), retourne des objets plats.
+	*
+	* Point de passage UNIQUE des options de lecture pour cet adapter (`find` y mène,
+	* `findOne` passe par `find`) : la garde sur `order` s'y pose donc une seule fois,
+	* en amont des trois endroits qui construisent un `ORDER BY` — chemin préparé,
+	* forme mémoïsée et chemin direct.
+	*
+	* @throws InvalidOrderOption si `options.order` n'est pas un tableau de couples.
+	*/
+	async #runSelect(criteria, options) {
+		assertOrderOption(options?.order, getTableName(this.#table));
+		const memo = this.#preparedSelect(criteria, options);
+		if (memo !== null) return this.#profPrepared(memo.entry, memo.params);
+		let query = this.#db.select().from(execTable(this.#table)).$dynamic();
+		const where = this.#where(criteria);
+		if (where) query = query.where(where);
+		if (options?.order?.length) query = query.orderBy(...options.order.map(([field, dir]) => dir === "DESC" ? desc(this.#col(this.#table, field)) : asc(this.#col(this.#table, field))));
+		if (options?.limit !== void 0) query = query.limit(options.limit);
+		else if (options?.offset !== void 0 && this.#dialect === "sqlite") query = query.limit(sql`-1`);
+		else if (options?.offset !== void 0 && this.#dialect === "mysql") query = query.limit(Number.MAX_SAFE_INTEGER);
+		if (options?.offset !== void 0) query = query.offset(options.offset);
+		return await this.#prof(query);
+	}
+	/** Eager-load manuel des relations déclarées (1 requête `IN (...)` par relation). */
+	async #populate(rows, relations) {
+		if (rows.length === 0) return;
+		for (const name of relations) {
+			const rel = this.#relations[name];
+			if (!rel) throw new Error(`DrizzleRepository(${name}): relation "${name}" non déclarée.`);
+			if (rel.type === "one-to-many") {
+				const parentIds = rows.map((row) => row[rel.localKey]);
+				const fkCol = this.#col(rel.targetTable, rel.foreignKey);
+				const children = await this.#prof(this.#db.select().from(execTable(rel.targetTable)).where(inArray(fkCol, parentIds)));
+				const byParent = /* @__PURE__ */ new Map();
+				for (const child of children) {
+					const key = child[rel.foreignKey];
+					const bucket = byParent.get(key);
+					if (bucket) bucket.push(child);
+					else byParent.set(key, [child]);
+				}
+				for (const row of rows) row[name] = byParent.get(row[rel.localKey]) ?? [];
+			} else {
+				const fkValues = rows.map((row) => row[rel.foreignKey]).filter((value) => value !== null && value !== void 0);
+				const idCol = this.#col(rel.targetTable, rel.targetKey);
+				const parents = fkValues.length > 0 ? await this.#prof(this.#db.select().from(execTable(rel.targetTable)).where(inArray(idCol, fkValues))) : [];
+				const byId = new Map(parents.map((p) => [p[rel.targetKey], p]));
+				for (const row of rows) row[name] = byId.get(row[rel.foreignKey]) ?? null;
+			}
+		}
+	}
+	async find(criteria, options) {
+		const rows = await this.#runSelect(criteria, options);
+		if (options?.relations?.length) await this.#populate(rows, options.relations);
+		return rows;
+	}
+	async findOne(criteria, options) {
+		return (await this.find(criteria, {
+			...options,
+			limit: 1
+		}))[0] ?? null;
+	}
+	async create(data) {
+		if (this.#dialect === "mysql") return (await this.#mysqlInsertReturning([data]))[0];
+		return (await this.#prof(this.#db.insert(execTable(this.#table)).values(data).returning()))[0];
+	}
+	async createMany(data) {
+		if (data.length === 0) return [];
+		if (this.#dialect === "mysql") return await this.#mysqlInsertReturning(data);
+		return await this.#prof(this.#db.insert(execTable(this.#table)).values(data).returning());
+	}
+	async updateOne(criteria, data) {
+		if (this.#dialect === "mysql") return this.#mysqlUpdateOneReturning(data, criteria);
+		const pick = this.#pickOne(this.#where(criteria));
+		return (await this.#prof(this.#db.update(execTable(this.#table)).set(data).where(pick).returning()))[0] ?? null;
+	}
+	/**
+	* Traduit le `update` d'un upsert en deux vues : ce qu'on ÉCRIT à l'insertion
+	* (valeurs brutes) et ce qu'on ré-applique au conflit (`SET`), où les
+	* {@link UpdateOperators} deviennent une expression du dialecte.
+	*
+	* `$max`/`$min` → `MAX(col, ?)` en sqlite, `GREATEST/LEAST(col, ?)` en
+	* postgres/mysql : `col` y désigne la valeur EXISTANTE, et la valeur proposée
+	* est bindée. À l'insertion il n'y a rien à comparer → valeur brute.
+	*/
+	#writeSet(update) {
+		const set = {};
+		const values = {};
+		for (const [field, value] of Object.entries(update)) {
+			if (!isUpdateOperators(value)) {
+				set[field] = value;
+				values[field] = value;
+				continue;
+			}
+			const col = this.#col(this.#table, field);
+			if (!col) throw new UnknownCriteriaField(field, getTableName(this.#table), Object.keys(getTableColumns(this.#table)));
+			const apply = (fn, v) => {
+				set[field] = sql`${sql.raw(fn)}(${col}, ${v})`;
+				values[field] = v;
+			};
+			if (value.$max !== void 0) apply(this.#dialect === "sqlite" ? "MAX" : "GREATEST", value.$max);
+			if (value.$min !== void 0) apply(this.#dialect === "sqlite" ? "MIN" : "LEAST", value.$min);
+		}
+		return {
+			set,
+			values
+		};
+	}
+	async upsert(criteria, update, insertOnly) {
+		const target = Object.keys(criteria).map((field) => {
+			const col = this.#col(this.#table, field);
+			if (!col) throw new UnknownCriteriaField(field, getTableName(this.#table), Object.keys(getTableColumns(this.#table)));
+			return col;
+		});
+		const write = this.#writeSet(update);
+		const values = {
+			...criteria,
+			...insertOnly ?? {},
+			...write.values
+		};
+		if (this.#dialect === "mysql") {
+			await this.#prof(this.#db.insert(execTable(this.#table)).values(values).onDuplicateKeyUpdate({ set: write.set }));
+			const conds = target.map((col) => eq(col, values[col.name]));
+			return (await this.#prof(this.#db.select().from(execTable(this.#table)).where(conds.length === 1 ? conds[0] : and(...conds)).limit(1)))[0];
+		}
+		return (await this.#prof(this.#db.insert(execTable(this.#table)).values(values).onConflictDoUpdate({
+			target,
+			set: write.set
+		}).returning()))[0];
+	}
+	async updateMany(criteria, data) {
+		const where = this.#where(criteria);
+		const builder = this.#db.update(execTable(this.#table)).set(data);
+		const result = await this.#prof(where ? builder.where(where) : builder);
+		return this.#affected(result);
+	}
+	async increment(criteria, changes) {
+		const setObj = {};
+		for (const [field, delta] of Object.entries(changes)) {
+			const col = this.#col(this.#table, field);
+			if (!col) throw new UnknownCriteriaField(field, getTableName(this.#table), Object.keys(getTableColumns(this.#table)));
+			setObj[field] = sql`${col} + ${delta}`;
+		}
+		if (this.#dialect === "mysql") return this.#mysqlUpdateOneReturning(setObj, criteria);
+		const pick = this.#pickOne(this.#where(criteria));
+		return (await this.#prof(this.#db.update(execTable(this.#table)).set(setObj).where(pick).returning()))[0] ?? null;
+	}
+	async delete(criteria) {
+		const where = this.#where(criteria);
+		const builder = this.#db.delete(execTable(this.#table));
+		const result = await this.#prof(where ? builder.where(where) : builder);
+		return this.#affected(result);
+	}
+	async deleteOne(criteria) {
+		if (this.#dialect === "mysql") return await this.#mysqlDeleteOneReturning(criteria) !== null;
+		return (await this.#deleteOneReturning(criteria)).length > 0;
+	}
+	async findOneAndDelete(criteria) {
+		if (this.#dialect === "mysql") return this.#mysqlDeleteOneReturning(criteria);
+		return (await this.#deleteOneReturning(criteria))[0] ?? null;
+	}
+	/** DELETE atomique d'AU PLUS une ligne (PK via `#pickOne`), RETURNING la ligne. */
+	async #deleteOneReturning(criteria) {
+		const pick = this.#pickOne(this.#where(criteria));
+		return await this.#prof(this.#db.delete(execTable(this.#table)).where(pick).returning());
+	}
+	/** PK obligatoire en mysql (les verbes re-SELECTent par PK). Fail-loud sinon. */
+	#requirePk(verb) {
+		const pk = this.#pkColumns();
+		if (!pk) throw new Error(`DrizzleRepository(${getTableName(this.#table)}): "${verb}" on mysql requires a declared primary key (no RETURNING → rows are re-read by PK).`);
+		return pk;
+	}
+	/** WHERE d'égalité sur la PK (valeurs plates lues par nom de colonne). */
+	#pkWhere(pk, values) {
+		const conds = pk.map((col) => eq(col, values[col.name]));
+		return conds.length === 1 ? conds[0] : and(...conds);
+	}
+	/** SELECT d'UNE ligne par valeurs de PK (relecture post-mutation mysql). */
+	async #selectByPk(pk, values) {
+		return (await this.#prof(this.#db.select().from(execTable(this.#table)).where(this.#pkWhere(pk, values)).limit(1)))[0] ?? null;
+	}
+	/** Valeurs de PK d'une ligne cible, après application d'un `set` éventuel
+	*  (un set qui réécrit une colonne PK avec une VALEUR plate est honoré ;
+	*  les fragments SQL — increment — retombent sur la valeur d'origine). */
+	#finalPkValues(pk, target, set) {
+		const out = {};
+		for (const col of pk) {
+			const v = set?.[col.name];
+			out[col.name] = v !== void 0 && (typeof v !== "object" || v === null) ? v : target[col.name];
+		}
+		return out;
+	}
+	/** UPDATE mysql « au plus une, ligne rendue » : cible par critère → UPDATE
+	*  borné PK + critère re-vérifié → relecture par PK. */
+	async #mysqlUpdateOneReturning(set, criteria) {
+		const pk = this.#requirePk("updateOne");
+		const where = this.#where(criteria);
+		const target = (await this.#runSelect(criteria, { limit: 1 }))[0];
+		if (!target) return null;
+		const pkCond = this.#pkWhere(pk, target);
+		const result = await this.#prof(this.#db.update(execTable(this.#table)).set(set).where(where ? and(pkCond, where) : pkCond));
+		if (this.#affected(result) === 0) return null;
+		return await this.#selectByPk(pk, this.#finalPkValues(pk, target, set));
+	}
+	/** DELETE mysql « au plus une, ligne rendue » : cible par critère → DELETE
+	*  borné PK + critère re-vérifié → ligne lue rendue. */
+	async #mysqlDeleteOneReturning(criteria) {
+		const pk = this.#requirePk("deleteOne");
+		const where = this.#where(criteria);
+		const target = (await this.#runSelect(criteria, { limit: 1 }))[0];
+		if (!target) return null;
+		const pkCond = this.#pkWhere(pk, target);
+		const result = await this.#prof(this.#db.delete(execTable(this.#table)).where(where ? and(pkCond, where) : pkCond));
+		return this.#affected(result) > 0 ? target : null;
+	}
+	/** INSERT mysql, ligne(s) rendue(s) : `$returningId()` (PK générées côté JS
+	*  par `$defaultFn` ou auto-increment) complété par les PK passées dans les
+	*  données, puis relecture par PK (ordre d'insertion préservé). */
+	async #mysqlInsertReturning(data) {
+		const pk = this.#requirePk("create");
+		const ids = await this.#prof(this.#db.insert(execTable(this.#table)).values(data).$returningId());
+		const out = [];
+		for (let i = 0; i < data.length; i++) {
+			const values = {};
+			for (const col of pk) values[col.name] = data[i]?.[col.name] ?? ids[i]?.[col.name];
+			const row = await this.#selectByPk(pk, values);
+			if (!row) throw new Error(`DrizzleRepository(${getTableName(this.#table)}): mysql insert succeeded but the row could not be re-read by primary key.`);
+			out.push(row);
+		}
+		return out;
+	}
+	async count(criteria) {
+		const where = this.#where(criteria);
+		const builder = this.#db.select({ value: count() }).from(execTable(this.#table)).$dynamic();
+		const rows = await this.#prof(where ? builder.where(where) : builder);
+		return Number(rows[0]?.value ?? 0);
+	}
+	/**
+	* `COUNT(DISTINCT col)` natif — la déduplication reste dans le moteur, aucune
+	* ligne n'est rapatriée. `COUNT(DISTINCT …)` ignore les `NULL` sur les trois
+	* dialectes, ce qui donne au contrat sa sémantique sans clause supplémentaire.
+	*/
+	async countDistinct(field, criteria) {
+		const where = this.#where(criteria);
+		const builder = this.#db.select({ value: countDistinct(this.#col(this.#table, field)) }).from(execTable(this.#table)).$dynamic();
+		const rows = await this.#prof(where ? builder.where(where) : builder);
+		return Number(rows[0]?.value ?? 0);
+	}
+	async exists(criteria) {
+		const where = this.#where(criteria);
+		let query = this.#db.select({ one: sql`1` }).from(execTable(this.#table)).$dynamic();
+		if (where) query = query.where(where);
+		query = query.limit(1);
+		return (await this.#prof(query)).length > 0;
+	}
+	withTransaction(tx) {
+		return new DrizzleRepository(tx.getNative(), this.#table, this.#relations, this.#connector, this.#dialect, true);
+	}
+};
+//#endregion
+export { DrizzleRepository, execTable };