@nodefony/drizzle 10.0.0-alpha.9 → 10.0.0-beta.2

package/dist/nodefony/src/migrator/sources.js

@@ -71,7 +71,8 @@ async function readJournal(dir, source) {
 	}
 	let journal;
 	try {
-		journal = JSON.parse(raw);
+		const parsed = JSON.parse(raw);
+		journal = typeof parsed === "object" && parsed !== null ? parsed : {};
 	} catch (e) {
 		throw new MigrationVerdictError({
 			code: "NF_MIGRATE_UNKNOWN_FORMAT",
@@ -91,21 +92,25 @@ async function readJournal(dir, source) {
 		facts: { file },
 		nextActions: []
 	}, `Le journal des migrations « ${file} » ne porte pas de liste « entries » : ce n'est pas un journal que ce format sait lire.`);
-	if (!SUPPORTED_JOURNAL_VERSIONS.includes(String(journal.version))) throw new MigrationVerdictError({
+	const version = String(journal.version);
+	if (!SUPPORTED_JOURNAL_VERSIONS.includes(version)) throw new MigrationVerdictError({
 		code: "NF_MIGRATE_UNKNOWN_FORMAT",
 		connector: "",
 		source,
 		facts: {
 			file,
-			journalVersion: String(journal.version),
+			journalVersion: version,
 			supported: SUPPORTED_JOURNAL_VERSIONS
 		},
 		nextActions: [{
 			command: "npm update @nodefony/drizzle",
 			args: ["update", "@nodefony/drizzle"]
 		}]
-	}, `Le journal de migrations de la source « ${source} » est en version ${String(journal.version)}, que cette version du framework ne sait pas lire (reconnue : ${SUPPORTED_JOURNAL_VERSIONS.join(", ")}).`);
-	return journal;
+	}, `Le journal de migrations de la source « ${source} » est en version ${version}, que cette version du framework ne sait pas lire (reconnue : ${SUPPORTED_JOURNAL_VERSIONS.join(", ")}).`);
+	return {
+		version,
+		entries: journal.entries
+	};
 }
 /**
 * Lit un fichier de migration, valide son format et découpe ses statements.
@@ -370,8 +375,8 @@ function scanLine(line, needle, grammar, curseur) {
 */
 function delimiteurDollar(line, debut) {
 	let i = debut + 1;
-	while (i < line.length && /[A-Za-z0-9_]/.test(line[i])) {
-		if (i === debut + 1 && /[0-9]/.test(line[i])) return null;
+	while (i < line.length && /[A-Za-z0-9_]/.test(line.charAt(i))) {
+		if (i === debut + 1 && /[0-9]/.test(line.charAt(i))) return null;
 		i += 1;
 	}
 	return line[i] === "$" ? line.slice(debut, i + 1) : null;
@@ -390,7 +395,7 @@ function delimiteurDollar(line, debut) {
 function createdTables(files) {
 	const found = /* @__PURE__ */ new Set();
 	const pattern = /CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?[`"']?([A-Za-z0-9_$]+)[`"']?/gi;
-	for (const file of files) for (const statement of file.statements) for (const match of statement.matchAll(pattern)) found.add(match[1]);
+	for (const file of files) for (const statement of file.statements) for (const [, table] of statement.matchAll(pattern)) if (table !== void 0) found.add(table);
 	return [...found];
 }
 /**

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

@@ -1,5 +1,6 @@
 import { schemaReader, toDollarParams } from "../migrator/catalog.js";
 import "../memoryDatabase.js";
+import { enableWriteAheadLog } from "../sqliteJournal.js";
 import { notConfigured } from "../migrator/refusals.js";
 import { additiveSql, compareSchema, hasGap } from "../migrator/schemaDiff.js";
 import { describeTargetSafely } from "../safeTarget.js";
@@ -431,17 +432,18 @@ var DrizzleOrm = class DrizzleOrm extends Orm {
 	}
 	async onConnect() {
 		await this.#releasePrevious();
-		this.#tables = Object.create(null);
+		const tables = Object.create(null);
+		this.#tables = tables;
 		this.#relations = Object.create(null);
 		const entities = this.#ownEntities();
 		switch (this.#dialect) {
 			case "sqlite":
-				await this.#connectSqlite(entities);
+				await this.#connectSqlite(entities, tables);
 				break;
 			case "postgres":
-				await this.#connectPostgres(entities);
+				await this.#connectPostgres(entities, tables);
 				break;
-			case "mysql": await this.#connectMysql(entities);
+			case "mysql": await this.#connectMysql(entities, tables);
 		}
 		if (this.#deriveSchema) {
 			await this.#reconcileSchema();
@@ -461,7 +463,7 @@ var DrizzleOrm = class DrizzleOrm extends Orm {
 	* La méthode devient asynchrone pour cette seule raison ; le pilote, lui,
 	* reste synchrone une fois chargé (`client.exec`, `client.pragma`).
 	*/
-	async #connectSqlite(entities) {
+	async #connectSqlite(entities, tables) {
 		let Sqlite;
 		let sqliteDrizzle;
 		try {
@@ -471,12 +473,14 @@ var DrizzleOrm = class DrizzleOrm extends Orm {
 			Sqlite = resolved;
 			sqliteDrizzle = (await import("drizzle-orm/better-sqlite3")).drizzle;
 		} catch (e) {
-			throw new Error(`DrizzleOrm "${this.name}": the sqlite dialect needs the optional driver \`better-sqlite3\` (run \`npm i better-sqlite3\`). ${e.message}`, { cause: e });
+			throw new Error(`DrizzleOrm "${this.name}": the sqlite dialect needs the optional driver \`better-sqlite3\` (run \`npm i better-sqlite3\`). ` + e.message, { cause: e });
 		}
 		const client = new Sqlite(this.#filename);
-		if (this.#filename !== ":memory:") {
-			client.pragma("journal_mode = WAL");
-			client.pragma("synchronous = NORMAL");
+		if (this.#filename !== ":memory:") try {
+			await enableWriteAheadLog(client);
+		} catch (e) {
+			client.close();
+			throw e;
 		}
 		client.pragma("foreign_keys = ON");
 		this.#client = client;
@@ -506,7 +510,7 @@ var DrizzleOrm = class DrizzleOrm extends Orm {
 		for (const entity of entities) {
 			this.#assertDialectTable(entity, SQLiteTable, "sqlite");
 			const table = entity.schema;
-			this.#tables[entity.name] = table;
+			tables[entity.name] = table;
 			entity.model = table;
 		}
 		if (!this.#deriveSchema) return;
@@ -537,12 +541,12 @@ var DrizzleOrm = class DrizzleOrm extends Orm {
 	#rawQuery = async (sql, params = []) => {
 		switch (this.#dialect) {
 			case "sqlite": {
-				const statement = this.#client.prepare(sql);
+				const statement = this.#sqliteClient().prepare(sql);
 				return statement.reader ? statement.all(...params) : [];
 			}
-			case "postgres": return (await this.#pgPool.query(toDollarParams(sql), params)).rows;
+			case "postgres": return (await this.#pgClient().query(toDollarParams(sql), params)).rows;
 			case "mysql": {
-				const [rows] = await this.#mysqlPool.query(sql, params);
+				const [rows] = await this.#mysqlClient().query(sql, params);
 				return Array.isArray(rows) ? rows : [];
 			}
 		}
@@ -555,13 +559,13 @@ var DrizzleOrm = class DrizzleOrm extends Orm {
 	async #rawExec(sql) {
 		switch (this.#dialect) {
 			case "sqlite":
-				this.#client.exec(sql);
+				this.#sqliteClient().exec(sql);
 				return;
 			case "postgres":
-				await this.#pgPool.query(sql);
+				await this.#pgClient().query(sql);
 				return;
 			case "mysql":
-				await this.#mysqlPool.query(sql);
+				await this.#mysqlClient().query(sql);
 				return;
 		}
 	}
@@ -640,20 +644,20 @@ var DrizzleOrm = class DrizzleOrm extends Orm {
 				case "sqlite": {
 					const t = table;
 					if (empechees.has(getTableConfig(t).name)) continue;
-					for (const statement of this.#createIndexesSQL(t)) this.#client.exec(statement);
+					for (const statement of this.#createIndexesSQL(t)) this.#sqliteClient().exec(statement);
 					break;
 				}
 				case "postgres": {
 					const t = table;
 					if (empechees.has(getTableConfig$1(t).name)) continue;
-					for (const statement of this.#createIndexesPgSQL(t)) await this.#pgPool.query(statement);
+					for (const statement of this.#createIndexesPgSQL(t)) await this.#pgClient().query(statement);
 					break;
 				}
 				case "mysql": {
 					const t = table;
 					if (empechees.has(getTableConfig$2(t).name)) continue;
 					for (const statement of this.#createIndexesMysqlSQL(t)) try {
-						await this.#mysqlPool.query(statement);
+						await this.#mysqlClient().query(statement);
 					} catch (error) {
 						if (error.code !== "ER_DUP_KEYNAME") throw error;
 					}
@@ -677,7 +681,7 @@ var DrizzleOrm = class DrizzleOrm extends Orm {
 	* déploiement SQLite ne les tire jamais. Pool partagé ; DDL dérivé pour dev/test
 	* (prod = drizzle-kit). Échec d'import → message actionnable (`npm i pg`).
 	*/
-	async #connectPostgres(entities) {
+	async #connectPostgres(entities, tables) {
 		if (!this.#url) throw new Error(`DrizzleOrm "${this.name}": dialect "postgres" requires a connection \`url\`.`);
 		let PoolCtor;
 		let pgDrizzle;
@@ -708,7 +712,7 @@ var DrizzleOrm = class DrizzleOrm extends Orm {
 		this.#pgPool = pool;
 		this.#db = pgDrizzle(pool);
 		try {
-			await this.#finishPostgres(entities, pool, pgDrizzle);
+			await this.#finishPostgres(entities, tables, pool, pgDrizzle);
 		} catch (e) {
 			this.#unwireAll();
 			await pool.end().catch(() => void 0);
@@ -719,11 +723,11 @@ var DrizzleOrm = class DrizzleOrm extends Orm {
 		}
 	}
 	/** Suite de la connexion postgres — isolée pour rendre `connect()` atomique. */
-	async #finishPostgres(entities, pool, pgDrizzle) {
+	async #finishPostgres(entities, tables, pool, pgDrizzle) {
 		this.#beginTx = async () => {
 			const cx = await pool.connect();
 			const puitsTx = (err) => {
-				this.connectionLost(`pg (transaction) : ${err?.message ?? String(err)}`);
+				this.connectionLost(`pg (transaction) : ${err instanceof Error ? err.message : String(err)}`);
 			};
 			cx.on("error", puitsTx);
 			/** Rend la connexion, en retirant d'abord NOTRE puits. */
@@ -748,7 +752,7 @@ var DrizzleOrm = class DrizzleOrm extends Orm {
 		for (const entity of entities) {
 			this.#assertDialectTable(entity, PgTable, "postgres");
 			const table = entity.schema;
-			this.#tables[entity.name] = table;
+			tables[entity.name] = table;
 			entity.model = table;
 		}
 		if (!this.#deriveSchema) return;
@@ -809,7 +813,7 @@ var DrizzleOrm = class DrizzleOrm extends Orm {
 	*/
 	#wirePgLifecycle(pool) {
 		const onError = (err) => {
-			this.connectionLost(`pg: ${err?.message ?? String(err)}`);
+			this.connectionLost(`pg: ${err instanceof Error ? err.message : String(err)}`);
 		};
 		const onConnect = () => {
 			this.connectionRestored();
@@ -853,7 +857,7 @@ var DrizzleOrm = class DrizzleOrm extends Orm {
 			this.connectionRestored();
 			cx.on("error", (err) => {
 				if (this.#mysqlPool !== pool) return;
-				this.connectionLost(`mysql: ${err?.message ?? String(err)}`);
+				this.connectionLost(`mysql: ${err instanceof Error ? err.message : String(err)}`);
 			});
 			cx.stream?.once("close", () => {
 				if (this.#mysqlPool !== pool) return;
@@ -873,7 +877,7 @@ var DrizzleOrm = class DrizzleOrm extends Orm {
 	* `datetime(3)` (kind `dateMs` du colKit) sont écrites/relues en UTC — mêmes
 	* instants que `timestamptz` PG, sans dépendre de la timezone du serveur.
 	*/
-	async #connectMysql(entities) {
+	async #connectMysql(entities, tables) {
 		if (!this.#url) throw new Error(`DrizzleOrm "${this.name}": dialect "mysql" requires a connection \`url\`.`);
 		let pool;
 		let mysqlDrizzle;
@@ -903,7 +907,7 @@ var DrizzleOrm = class DrizzleOrm extends Orm {
 		this.#mysqlPool = pool;
 		this.#db = mysqlDrizzle(pool);
 		try {
-			await this.#finishMysql(entities, pool, mysqlDrizzle);
+			await this.#finishMysql(entities, tables, pool, mysqlDrizzle);
 		} catch (e) {
 			this.#unwireAll();
 			await pool.end().catch(() => void 0);
@@ -914,7 +918,7 @@ var DrizzleOrm = class DrizzleOrm extends Orm {
 		}
 	}
 	/** Suite de la connexion mysql — isolée pour rendre `connect()` atomique. */
-	async #finishMysql(entities, pool, mysqlDrizzle) {
+	async #finishMysql(entities, tables, pool, mysqlDrizzle) {
 		this.#beginTx = async () => {
 			const cx = await pool.getConnection();
 			try {
@@ -937,7 +941,7 @@ var DrizzleOrm = class DrizzleOrm extends Orm {
 		for (const entity of entities) {
 			this.#assertDialectTable(entity, MySqlTable, "mysql");
 			const table = entity.schema;
-			this.#tables[entity.name] = table;
+			tables[entity.name] = table;
 			entity.model = table;
 		}
 		if (!this.#deriveSchema) return;
@@ -977,7 +981,7 @@ var DrizzleOrm = class DrizzleOrm extends Orm {
 		const table = this.#tables?.[name];
 		if (!this.#db) throw new Error(`DrizzleOrm "${this.name}": non connecté — impossible de rendre un dépôt pour "${name}". Les tables ne sont résolues qu'à la connexion. Si ce run est une commande en ligne, elle n'a pas déclaré \`externalServices\` (CONSOLE_DATA_RUN_PROFILE).`);
 		if (!table) throw new Error(`DrizzleOrm "${this.name}": no entity table registered under "${name}".`);
-		if (this.#repositories === null) this.#repositories = Object.create(null);
+		this.#repositories ??= Object.create(null);
 		let repository = this.#repositories[name];
 		if (repository === void 0) {
 			repository = new DrizzleRepository(this.#db, table, this.#relations?.[name] ?? {}, this.name, this.#dialect);
@@ -1010,6 +1014,25 @@ var DrizzleOrm = class DrizzleOrm extends Orm {
 			throw error;
 		}
 	}
+	/**
+	* Connexion SQLite courante — lève si le connecteur n'est pas ouvert. Les
+	* appelants ne passent ici qu'une fois `onConnect` engagé : la levée ne sert
+	* qu'à typer, et à dire la cause si l'ordre était un jour rompu.
+	*/
+	#sqliteClient() {
+		if (this.#client === null) throw new Error(`DrizzleOrm "${this.name}": not connected.`);
+		return this.#client;
+	}
+	/** Pool PostgreSQL courant — même contrat que {@link #sqliteClient}. */
+	#pgClient() {
+		if (this.#pgPool === null) throw new Error(`DrizzleOrm "${this.name}": not connected.`);
+		return this.#pgPool;
+	}
+	/** Pool MySQL courant — même contrat que {@link #sqliteClient}. */
+	#mysqlClient() {
+		if (this.#mysqlPool === null) throw new Error(`DrizzleOrm "${this.name}": not connected.`);
+		return this.#mysqlPool;
+	}
 	getNativeConnection() {
 		if (!this.#db) throw new Error(`DrizzleOrm "${this.name}": not connected.`);
 		return this.#db;
@@ -1123,7 +1146,7 @@ var DrizzleOrm = class DrizzleOrm extends Orm {
 	* @returns sonde `pool` (taille max, idle, empruntées, en attente).
 	*/
 	#probePgPool(pool) {
-		const max = pool.options?.max;
+		const max = pool.options.max;
 		return { pool: {
 			size: typeof max === "number" ? max : 10,
 			available: pool.idleCount,

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

@@ -24,6 +24,25 @@ const PREPARED_CACHE_MAX = 128;
 /** Séquence des noms de prepared statements (PG les exige uniques par process). */
 let preparedNameSeq = 0;
 /**
+* Les comparaisons scalaires, dans l'ordre où elles entrent dans le `WHERE`.
+*
+* UNE table pour le chemin direct (`#pushOperators`) ET le chemin préparé
+* (`#buildPreparedSelect`) : deux listes recopiées finiraient par traduire le
+* même critère en deux SQL différents, selon que la forme est en cache ou non.
+* Leur texte SQL ne dépend que de l'opérateur, jamais de la valeur — c'est ce
+* qui les rend préparables (≠ `$in`/`$nin`, dont le SQL suit la cardinalité).
+*/
+const COMPARISONS = [
+	["$eq", eq],
+	["$ne", ne],
+	["$gt", gt],
+	["$gte", gte],
+	["$lt", lt],
+	["$lte", lte]
+];
+/** Opérateurs qu'une forme préparée sait rendre : les comparaisons et `$null`. */
+const PREPARABLE_OPERATORS = /* @__PURE__ */ new Set([...COMPARISONS.map(([op]) => op), "$null"]);
+/**
 * Repository portable (contrat {@link IRepository}) au-dessus d'une table Drizzle
 * + driver `better-sqlite3`.
 *
@@ -83,9 +102,35 @@ var DrizzleRepository = class DrizzleRepository {
 		this.#dialect = dialect;
 		this.#transactional = transactional;
 	}
-	/** Colonne Drizzle d'une table par nom logique. */
+	/**
+	* Colonne Drizzle d'une table par nom logique ; `undefined` si elle n'existe pas.
+	*
+	* 🔴 `Object.hasOwn` sur l'objet des COLONNES, jamais `table[name]` : le nom
+	* vient souvent de la requête (`?sort=`), et une clé héritée du prototype
+	* (`constructor`, `__proto__`, `toString`) ne vaut pas `undefined` — elle
+	* franchissait la liste blanche et cassait plus loin dans le pilote.
+	* `getTableColumns` rend l'objet tel quel, sans copie.
+	*/
 	#col(table, name) {
-		return table[name];
+		const columns = getTableColumns(table);
+		return Object.hasOwn(columns, name) ? columns[name] : void 0;
+	}
+	/**
+	* Colonne EXIGÉE : un nom inconnu lève au lieu de partir dans le SQL.
+	*
+	* Strict (B2) : champ inconnu = erreur, pas un skip silencieux (qui ferait
+	* disparaître la condition → fuite « renvoie tout »), ni un `undefined` glissé
+	* dans un `ORDER BY` (rendu `no such column: asc`). Même contrat que Mongoose.
+	* Requêtes natives → `getNativeConnection()`.
+	*
+	* @param name - nom logique du champ (critère, tri, clé étrangère).
+	* @param table - table qui doit le porter (défaut : celle du repository).
+	* @throws UnknownCriteriaField si la table ne porte pas ce champ.
+	*/
+	#requireCol(name, table = this.#table) {
+		const col = this.#col(table, name);
+		if (col === void 0) throw new UnknownCriteriaField(name, getTableName(table), Object.keys(getTableColumns(table)));
+		return col;
 	}
 	/**
 	* Colonnes de la PK de la table (mémoïsées) : colonnes inline `.primaryKey()`
@@ -121,18 +166,49 @@ var DrizzleRepository = class DrizzleRepository {
 	*
 	* 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é).
+	*
+	* Court-circuit : un critère qui fixe TOUTES les colonnes de la PK par une
+	* égalité désigne déjà au plus une ligne — le `WHERE` nu suffit, et la
+	* sous-requête n'est plus payée. Elle coûtait ~60 µs par UPDATE en SQLite
+	* (recompilation d'un SQL plus long + table dérivée matérialisée, mesuré par
+	* `scripts/micro/micro-update-pick.mjs` du skill `nodefony-load-test`), soit
+	* l'essentiel de l'écart du banc ORM face à NestJS (#510).
+	*
+	* @param criteria - critère portable de la mutation.
+	* @returns le prédicat qui borne la mutation à au plus une ligne.
 	*/
-	#pickOne(where) {
+	#pickOne(criteria) {
+		const where = this.#where(criteria);
 		const pk = this.#pkColumns();
+		if (where && pk && this.#pinsPrimaryKey(pk, criteria)) return where;
 		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 first = pk.at(0);
 		const target = pk.length === 1 && first ? sql`${first}` : sql`(${qualified})`;
 		return sql`${target} in (select ${output} from (${inner}) as picked)`;
 	}
 	/**
+	* Vrai si le critère fixe chaque colonne de la PK par une égalité à une
+	* valeur (ni `null`, ni opérateur, ni branche de `$or`) — l'unicité de la
+	* PK garantit alors « au plus une ligne » sans sous-requête.
+	*
+	* @param pk - colonnes de la PK (au plus 31 : masque de bits).
+	* @param criteria - critère portable de la mutation.
+	*/
+	#pinsPrimaryKey(pk, criteria) {
+		if (criteria === void 0 || pk.length > 31) return false;
+		let pinned = 0;
+		for (const [field, value] of Object.entries(criteria)) {
+			if (field === "$or" || value === null || value === void 0 || isFieldOperators(value)) continue;
+			const col = this.#col(this.#table, field);
+			const i = col === void 0 ? -1 : pk.indexOf(col);
+			if (i !== -1) pinned |= 1 << i;
+		}
+		return pinned === (1 << pk.length) - 1;
+	}
+	/**
 	* Lignes affectées, normalisé par driver : better-sqlite3 `{changes}` /
 	* pg `{rowCount}` / mysql2 tuple `[ResultSetHeader{affectedRows}, fields]`.
 	*/
@@ -211,12 +287,10 @@ var DrizzleRepository = class DrizzleRepository {
 	}
 	/** 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));
+		for (const [op, compare] of COMPARISONS) {
+			const value = ops[op];
+			if (value !== void 0) conds.push(compare(col, value));
+		}
 		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));
@@ -229,12 +303,17 @@ var DrizzleRepository = class DrizzleRepository {
 		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));
+				if (value.length === 0) {
+					conds.push(sql`1 = 0`);
+					continue;
+				}
+				const branches = value.map((branch) => this.#where(branch));
+				if (branches.some((branch) => branch === void 0)) continue;
+				const [first, ...rest] = branches;
+				if (first !== void 0) conds.push(rest.length === 0 ? first : or(first, ...rest));
 				continue;
 			}
-			const col = this.#col(this.#table, field);
-			if (!col) throw new UnknownCriteriaField(field, getTableName(this.#table), Object.keys(getTableColumns(this.#table)));
+			const col = this.#requireCol(field);
 			if (isFieldOperators(value)) this.#pushOperators(conds, col, value);
 			else if (value === null) conds.push(isNull(col));
 			else conds.push(eq(col, value));
@@ -251,8 +330,14 @@ var DrizzleRepository = class DrizzleRepository {
 	* 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
+	* Les comparaisons scalaires ({@link COMPARISONS}) et `$null` entrent dans la
+	* forme : la COMBINAISON d'opérateurs d'un champ fait partie de la clé, leurs
+	* valeurs deviennent des placeholders `p<i>$<op>`. C'est le chemin des
+	* lectures bornées dans le temps (`expiresAt: { $gt: now }` — la révocation
+	* des jetons, lue à chaque requête authentifiée).
+	*
+	* Repli (`null`) par construction : `$or`, `$in`/`$nin` (le SQL suit la
+	* cardinalité), `$like` (clause d'échappement propre au dialecte), valeur
 	* `undefined` (le chemin actuel la rejette, même contrat), transaction
 	* (cf ctor), cache plein ({@link PREPARED_CACHE_MAX}).
 	*/
@@ -262,7 +347,22 @@ var DrizzleRepository = class DrizzleRepository {
 		if (criteria) {
 			let i = 0;
 			for (const [field, value] of Object.entries(criteria)) {
-				if (field === "$or" || value === void 0 || isFieldOperators(value)) return null;
+				if (field === "$or" || value === void 0) return null;
+				if (isFieldOperators(value)) {
+					let ops = "";
+					for (const op in value) if (!PREPARABLE_OPERATORS.has(op)) return null;
+					for (const [op] of COMPARISONS) {
+						const operand = value[op];
+						if (operand !== void 0) {
+							ops += op;
+							params[`p${i}${op}`] = operand;
+						}
+					}
+					if (value.$null !== void 0) ops += value.$null ? "$null1" : "$null0";
+					key += `${field}\x04${ops}\x00`;
+					i++;
+					continue;
+				}
 				if (value === null) key += `${field}\x01\x00`;
 				else {
 					key += `${field}\x00`;
@@ -305,14 +405,19 @@ var DrizzleRepository = class DrizzleRepository {
 			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)));
+				const col = this.#requireCol(field);
+				if (isFieldOperators(value)) {
+					for (const [op, compare] of COMPARISONS) if (value[op] !== void 0) conds.push(compare(col, sql.param(sql.placeholder(`p${i}${op}`), col)));
+					if (value.$null !== void 0) conds.push(value.$null ? isNull(col) : isNotNull(col));
+					i++;
+					continue;
+				}
 				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?.order?.length) query = query.orderBy(...options.order.map(([field, dir]) => dir === "DESC" ? desc(this.#requireCol(field)) : asc(this.#requireCol(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);
@@ -335,7 +440,7 @@ var DrizzleRepository = class DrizzleRepository {
 		const shape = this.#selectShape(criteria, options);
 		if (shape === null) return null;
 		let cache = this.#preparedSelects;
-		if (cache === null) cache = this.#preparedSelects = /* @__PURE__ */ new Map();
+		cache ??= this.#preparedSelects = /* @__PURE__ */ new Map();
 		let entry = cache.get(shape.key);
 		if (entry === void 0) {
 			if (cache.size >= PREPARED_CACHE_MAX) return null;
@@ -364,12 +469,12 @@ var DrizzleRepository = class DrizzleRepository {
 		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?.order?.length) query = query.orderBy(...options.order.map(([field, dir]) => dir === "DESC" ? desc(this.#requireCol(field)) : asc(this.#requireCol(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);
+		return this.#prof(query);
 	}
 	/** Eager-load manuel des relations déclarées (1 requête `IN (...)` par relation). */
 	async #populate(rows, relations) {
@@ -379,7 +484,7 @@ var DrizzleRepository = class DrizzleRepository {
 			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 fkCol = this.#requireCol(rel.foreignKey, rel.targetTable);
 				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) {
@@ -391,7 +496,7 @@ var DrizzleRepository = class DrizzleRepository {
 				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 idCol = this.#requireCol(rel.targetKey, rel.targetTable);
 				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;
@@ -420,7 +525,7 @@ var DrizzleRepository = class DrizzleRepository {
 	}
 	async updateOne(criteria, data) {
 		if (this.#dialect === "mysql") return this.#mysqlUpdateOneReturning(data, criteria);
-		const pick = this.#pickOne(this.#where(criteria));
+		const pick = this.#pickOne(criteria);
 		return (await this.#prof(this.#db.update(execTable(this.#table)).set(data).where(pick).returning()))[0] ?? null;
 	}
 	/**
@@ -441,8 +546,7 @@ var DrizzleRepository = class DrizzleRepository {
 				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 col = this.#requireCol(field);
 			const apply = (fn, v) => {
 				set[field] = sql`${sql.raw(fn)}(${col}, ${v})`;
 				values[field] = v;
@@ -457,9 +561,7 @@ var DrizzleRepository = class DrizzleRepository {
 	}
 	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;
+			return this.#requireCol(field);
 		});
 		const write = this.#writeSet(update);
 		const values = {
@@ -486,12 +588,11 @@ var DrizzleRepository = class DrizzleRepository {
 	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)));
+			const col = this.#requireCol(field);
 			setObj[field] = sql`${col} + ${delta}`;
 		}
 		if (this.#dialect === "mysql") return this.#mysqlUpdateOneReturning(setObj, criteria);
-		const pick = this.#pickOne(this.#where(criteria));
+		const pick = this.#pickOne(criteria);
 		return (await this.#prof(this.#db.update(execTable(this.#table)).set(setObj).where(pick).returning()))[0] ?? null;
 	}
 	async delete(criteria) {
@@ -510,8 +611,8 @@ var DrizzleRepository = class DrizzleRepository {
 	}
 	/** 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());
+		const pick = this.#pickOne(criteria);
+		return 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) {
@@ -522,7 +623,8 @@ var DrizzleRepository = class DrizzleRepository {
 	/** 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);
+		const [first, ...rest] = conds;
+		return first !== void 0 && rest.length === 0 ? first : and(...conds);
 	}
 	/** SELECT d'UNE ligne par valeurs de PK (relecture post-mutation mysql). */
 	async #selectByPk(pk, values) {
@@ -544,7 +646,7 @@ var DrizzleRepository = class DrizzleRepository {
 	async #mysqlUpdateOneReturning(set, criteria) {
 		const pk = this.#requirePk("updateOne");
 		const where = this.#where(criteria);
-		const target = (await this.#runSelect(criteria, { limit: 1 }))[0];
+		const target = (await this.#runSelect(criteria, { limit: 1 })).at(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));
@@ -556,7 +658,7 @@ var DrizzleRepository = class DrizzleRepository {
 	async #mysqlDeleteOneReturning(criteria) {
 		const pk = this.#requirePk("deleteOne");
 		const where = this.#where(criteria);
-		const target = (await this.#runSelect(criteria, { limit: 1 }))[0];
+		const target = (await this.#runSelect(criteria, { limit: 1 })).at(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));
@@ -591,7 +693,7 @@ var DrizzleRepository = class DrizzleRepository {
 	*/
 	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 builder = this.#db.select({ value: countDistinct(this.#requireCol(field)) }).from(execTable(this.#table)).$dynamic();
 		const rows = await this.#prof(where ? builder.where(where) : builder);
 		return Number(rows[0]?.value ?? 0);
 	}