@apisr/drizzle-model 2.0.2 → 2.0.3

package/dist/core/query/joins.mjs

@@ -0,0 +1,334 @@
+import { ProjectionBuilder } from "./projection.mjs";
+import { WhereCompiler } from "./where.mjs";
+import { and, eq } from "drizzle-orm";
+
+//#region src/core/query/joins.ts
+/**
+* Executes queries that load related entities via LEFT JOINs.
+*
+* Builds a join tree from the `.with()` descriptor, constructs a single
+* multi-join query, and then groups the flat rows back into a nested
+* object structure matching the requested relations.
+*
+* Usage:
+* ```ts
+* const executor = new JoinExecutor(dialectHelper);
+* const result = await executor.execute(config);
+* ```
+*/
+var JoinExecutor = class {
+	dialect;
+	projection;
+	whereCompiler;
+	constructor(dialect) {
+		this.dialect = dialect;
+		this.projection = new ProjectionBuilder();
+		this.whereCompiler = new WhereCompiler();
+	}
+	/**
+	* Executes a query with LEFT JOINs for the requested relations,
+	* then groups the flat result into a nested object tree.
+	*
+	* @param config - The full join execution configuration.
+	* @returns A single object (when `limitOne`) or an array of grouped results.
+	*/
+	async execute(config) {
+		const root = await this.buildJoinTree(config);
+		const flatNodes = this.flattenNodes(root);
+		const rows = await this.executeQuery(config, root, flatNodes);
+		const grouped = this.groupRows(rows, root, flatNodes);
+		return config.limitOne ? grouped[0] : grouped;
+	}
+	/**
+	* Builds the full join tree from the `.with()` descriptor.
+	*
+	* The root node represents the base table. Each key in the `withValue`
+	* map becomes a child node, potentially with nested children.
+	*/
+	async buildJoinTree(config) {
+		const usedAliasKeys = /* @__PURE__ */ new Set();
+		usedAliasKeys.add(`table:${config.baseTableName}`);
+		const root = {
+			path: [],
+			key: "$root",
+			relationType: "one",
+			sourceTableName: config.baseTableName,
+			targetTableName: config.baseTableName,
+			sourceTable: config.baseTable,
+			targetTable: config.baseTable,
+			targetAliasTable: config.baseTable,
+			aliasKey: "$base",
+			sourceColumns: [],
+			targetColumns: [],
+			pkField: this.getPrimaryKeyField(config.baseTable),
+			children: []
+		};
+		for (const [key, value] of Object.entries(config.withValue)) {
+			if (value !== true && (typeof value !== "object" || value == null)) continue;
+			const child = await this.buildNode(config, usedAliasKeys, void 0, config.baseTableName, config.baseTable, key, value, []);
+			root.children.push(child);
+		}
+		return root;
+	}
+	/**
+	* Recursively builds a single join node and its children.
+	*
+	* Resolves relation metadata, determines whether aliasing is needed,
+	* and descends into nested sub-relations.
+	*/
+	async buildNode(config, usedAliasKeys, parent, currentTableName, currentTable, key, value, path) {
+		const { whereValue, nestedWith } = this.extractRelationDescriptor(value);
+		const relMeta = this.getRelationMeta(config.relations, currentTableName, key);
+		const targetTableName = relMeta.targetTableName;
+		const targetTable = config.schema[targetTableName] ?? {};
+		const aliasKey = this.resolveUniqueAlias(usedAliasKeys, [...path, key]);
+		const needsAlias = targetTableName === currentTableName || usedAliasKeys.has(`table:${targetTableName}`);
+		usedAliasKeys.add(`table:${targetTableName}`);
+		const targetAliasTable = needsAlias ? await this.dialect.createTableAlias(targetTable, aliasKey) : targetTable;
+		const whereFilter = whereValue ? this.whereCompiler.compile(targetAliasTable, whereValue) : void 0;
+		const node = {
+			path: [...path, key],
+			key,
+			relationType: relMeta.relationType,
+			sourceTableName: currentTableName,
+			targetTableName,
+			sourceTable: currentTable,
+			targetTable,
+			targetAliasTable,
+			aliasKey,
+			sourceColumns: relMeta.sourceColumns ?? [],
+			targetColumns: relMeta.targetColumns ?? [],
+			pkField: this.getPrimaryKeyField(targetAliasTable),
+			parent,
+			children: [],
+			whereFilter
+		};
+		if (nestedWith && typeof nestedWith === "object") for (const [childKey, childVal] of Object.entries(nestedWith)) {
+			if (childVal !== true && (typeof childVal !== "object" || childVal == null)) continue;
+			const child = await this.buildNode(config, usedAliasKeys, node, targetTableName, targetAliasTable, childKey, childVal, [...path, key]);
+			node.children.push(child);
+		}
+		return node;
+	}
+	/**
+	* Builds and executes the multi-join SELECT query.
+	*
+	* Constructs a select map namespaced by alias key (base + each join),
+	* applies LEFT JOINs in preorder, and optionally limits to one row.
+	*/
+	async executeQuery(config, root, nodes) {
+		const selectMap = { base: this.projection.build(root.targetAliasTable, config.select, config.exclude).selectMap };
+		for (const node of nodes) selectMap[node.aliasKey] = this.projection.extractColumns(node.targetAliasTable);
+		let query = config.db.select(selectMap);
+		query = query.from(config.baseTable);
+		if (config.whereSql) query = query.where(config.whereSql);
+		for (const node of nodes) {
+			const onCondition = this.buildJoinOn(node);
+			query = query.leftJoin(node.targetAliasTable, onCondition);
+		}
+		if (config.limitOne) query = query.limit(1);
+		return await query;
+	}
+	/**
+	* Groups flat joined rows back into a nested object structure.
+	*
+	* Uses the base table's primary key to deduplicate base rows, then
+	* attaches relation data to the correct parent in the tree.
+	*/
+	groupRows(rows, root, nodes) {
+		const basePk = root.pkField;
+		const baseMap = /* @__PURE__ */ new Map();
+		const manyIndexByPath = /* @__PURE__ */ new Map();
+		for (const row of rows) {
+			const baseRow = row.base;
+			const baseId = baseRow[basePk];
+			if (baseId === void 0) continue;
+			const baseObj = this.getOrCreateBase(baseMap, baseId, baseRow);
+			for (const node of nodes) {
+				const data = row[node.aliasKey];
+				const relPath = node.path.join(".");
+				const parentObj = this.resolveParentObject(node, baseObj, manyIndexByPath);
+				if (this.isAllNull(data)) {
+					this.ensureContainer(parentObj, node);
+					continue;
+				}
+				const pk = data[node.pkField];
+				if (node.relationType === "one") parentObj[node.key] = { ...data };
+				else {
+					this.ensureManyArray(parentObj, node.key);
+					const indexMap = this.getOrCreateIndexMap(manyIndexByPath, relPath);
+					if (!indexMap.has(pk)) {
+						const obj = { ...data };
+						indexMap.set(pk, obj);
+						parentObj[node.key].push(obj);
+					}
+				}
+			}
+		}
+		return Array.from(baseMap.values());
+	}
+	/**
+	* Builds the ON clause for a single join node.
+	*
+	* Maps source columns to their corresponding aliased target columns
+	* and produces an equality (or multi-equality with AND) condition.
+	*/
+	buildJoinOn(node) {
+		const parts = node.sourceColumns.map((src, i) => {
+			const tgt = node.targetColumns[i];
+			const tgtKey = Object.entries(node.targetTable).find(([, v]) => v === tgt)?.[0];
+			return eq(tgtKey ? node.targetAliasTable[tgtKey] : tgt, src);
+		});
+		if (node.whereFilter) parts.push(node.whereFilter);
+		return parts.length === 1 ? parts[0] : and(...parts);
+	}
+	/**
+	* Flattens the join tree into a preorder list (excluding the root).
+	*
+	* The order matches the LEFT JOIN application order in the query.
+	*/
+	flattenNodes(root) {
+		const nodes = [];
+		const walk = (node) => {
+			for (const child of node.children) {
+				nodes.push(child);
+				walk(child);
+			}
+		};
+		walk(root);
+		return nodes;
+	}
+	/**
+	* Generates a unique alias key for a join node, avoiding collisions
+	* with previously used keys.
+	*/
+	resolveUniqueAlias(usedKeys, path) {
+		const base = path.join("__");
+		let alias = base;
+		let counter = 1;
+		while (usedKeys.has(alias)) alias = `${base}_${counter++}`;
+		usedKeys.add(alias);
+		return alias;
+	}
+	/**
+	* Retrieves the relation metadata for a given table and relation key.
+	*
+	* @throws {Error} When the relation is not found in the schema metadata.
+	*/
+	getRelationMeta(relations, tableName, key) {
+		const relMeta = (relations[tableName]?.relations)?.[key];
+		if (!relMeta) throw new Error(`Unknown relation '${key}' on table '${tableName}'.`);
+		return relMeta;
+	}
+	/**
+	* Detects the primary key field name of a Drizzle table.
+	*
+	* Tries (in order):
+	* 1. A column with `primary === true`.
+	* 2. A column with `config.primaryKey === true`.
+	* 3. A field named `"id"`.
+	* 4. The first Drizzle column found.
+	*/
+	getPrimaryKeyField(table) {
+		for (const [key, value] of Object.entries(table)) {
+			if (!this.isDrizzleColumn(value)) continue;
+			const col = value;
+			if (col.primary === true) return key;
+			if (col.config?.primaryKey === true) return key;
+		}
+		if ("id" in table) return "id";
+		return Object.keys(table).find((k) => this.isDrizzleColumn(table[k])) ?? "id";
+	}
+	/** Checks whether a value is a Drizzle column reference. */
+	isDrizzleColumn(value) {
+		return !!value && typeof value === "object" && typeof value.getSQL === "function";
+	}
+	/**
+	* Extracts relation where clause and nested relations from a `.with()` value.
+	*
+	* Handles three cases:
+	* - `true` → no filter, no nested relations.
+	* - A ModelRuntime (has `$model === "model"`) → extract `$where`, no nested.
+	* - A model descriptor (`__modelRelation: true`) → extract `whereValue` and `with`.
+	* - A plain object → treat as nested relation map.
+	*/
+	extractRelationDescriptor(value) {
+		if (value === true || value == null) return {
+			whereValue: void 0,
+			nestedWith: void 0
+		};
+		if (typeof value !== "object") return {
+			whereValue: void 0,
+			nestedWith: void 0
+		};
+		const rec = value;
+		if (rec.$model === "model") return {
+			whereValue: rec.$where,
+			nestedWith: void 0
+		};
+		if (rec.__modelRelation === true) return {
+			whereValue: rec.whereValue,
+			nestedWith: rec.with
+		};
+		return {
+			whereValue: void 0,
+			nestedWith: value
+		};
+	}
+	/**
+	* Gets or creates the base-row object for a given primary key.
+	*/
+	getOrCreateBase(baseMap, baseId, baseRow) {
+		const existing = baseMap.get(baseId);
+		if (existing) return existing;
+		const created = { ...baseRow };
+		baseMap.set(baseId, created);
+		return created;
+	}
+	/**
+	* Resolves the parent object that a join node's data should attach to.
+	*
+	* For root-level relations, the parent is the base row. For nested
+	* relations, it is the last inserted instance of the parent node.
+	*/
+	resolveParentObject(node, baseObj, manyIndexByPath) {
+		if (!node.parent) return baseObj;
+		const parentPath = node.parent.path.join(".");
+		if (!parentPath) return baseObj;
+		const parentIndex = manyIndexByPath.get(parentPath);
+		if (parentIndex && parentIndex.size > 0) return Array.from(parentIndex.values()).at(-1);
+		return baseObj[node.parent.key] ?? baseObj;
+	}
+	/** Checks whether all values in a row are `null` or `undefined`. */
+	isAllNull(obj) {
+		if (!obj || typeof obj !== "object") return true;
+		for (const value of Object.values(obj)) if (value !== null && value !== void 0) return false;
+		return true;
+	}
+	/**
+	* Ensures the correct empty container exists on the parent for a node.
+	*
+	* Creates `[]` for many-relations and `null` for one-relations.
+	*/
+	ensureContainer(parentObj, node) {
+		if (node.relationType === "one") {
+			if (!(node.key in parentObj)) parentObj[node.key] = null;
+		} else this.ensureManyArray(parentObj, node.key);
+	}
+	/** Ensures `parentObj[key]` is an array. */
+	ensureManyArray(parentObj, key) {
+		if (!Array.isArray(parentObj[key])) parentObj[key] = [];
+	}
+	/** Gets or creates a deduplication index map for a many-relation path. */
+	getOrCreateIndexMap(manyIndexByPath, relPath) {
+		let indexMap = manyIndexByPath.get(relPath);
+		if (!indexMap) {
+			indexMap = /* @__PURE__ */ new Map();
+			manyIndexByPath.set(relPath, indexMap);
+		}
+		return indexMap;
+	}
+};
+
+//#endregion
+export { JoinExecutor };

package/dist/core/query/projection.mjs

@@ -0,0 +1,78 @@
+//#region src/core/query/projection.ts
+/**
+* Builds column projections for Drizzle `select()` calls.
+*
+* Resolves which columns should be included in the SQL query
+* based on user-supplied `select` and `exclude` maps.
+*/
+var ProjectionBuilder = class {
+	/**
+	* Builds a select map from a Drizzle table, optionally filtered
+	* by a `select` whitelist or an `exclude` blacklist.
+	*
+	* Priority:
+	* 1. If `select` is provided, only the listed columns are included.
+	* 2. If `exclude` is provided, all columns *except* the listed ones are included.
+	* 3. If neither is provided, all columns are included.
+	*
+	* Falls back to all columns when the filter would result in an empty map.
+	*
+	* @param table   - The Drizzle table object whose columns are introspected.
+	* @param select  - Optional whitelist: `{ columnName: true }`.
+	* @param exclude - Optional blacklist: `{ columnName: true }`.
+	* @returns A {@link ProjectionResult} containing the resolved column map.
+	*/
+	build(table, select, exclude) {
+		const allColumns = this.extractColumns(table);
+		if (select && typeof select === "object") return this.buildFromSelect(allColumns, select);
+		if (exclude && typeof exclude === "object") return this.buildFromExclude(allColumns, exclude);
+		return { selectMap: allColumns };
+	}
+	/**
+	* Extracts a column map for a table, including only actual Drizzle columns.
+	*
+	* Useful for building join select maps where every column of an
+	* aliased table needs to be enumerated.
+	*
+	* @param table - The Drizzle table (or aliased table) to extract from.
+	* @returns A record mapping column names to their Drizzle column references.
+	*/
+	extractColumns(table) {
+		const columns = {};
+		for (const [key, value] of Object.entries(table)) if (this.isDrizzleColumn(value)) columns[key] = value;
+		return columns;
+	}
+	/**
+	* Builds a select map by picking only the columns listed in `select`.
+	*
+	* Falls back to all columns if the resulting map is empty.
+	*/
+	buildFromSelect(allColumns, select) {
+		const picked = {};
+		for (const [key, value] of Object.entries(select)) if (value === true && key in allColumns) picked[key] = allColumns[key];
+		if (Object.keys(picked).length > 0) return { selectMap: picked };
+		return { selectMap: allColumns };
+	}
+	/**
+	* Builds a select map by omitting columns listed in `exclude`.
+	*
+	* Falls back to all columns if everything would be excluded.
+	*/
+	buildFromExclude(allColumns, exclude) {
+		const remaining = { ...allColumns };
+		for (const [key, value] of Object.entries(exclude)) if (value === true) delete remaining[key];
+		if (Object.keys(remaining).length > 0) return { selectMap: remaining };
+		return { selectMap: allColumns };
+	}
+	/**
+	* Checks whether a value is a Drizzle column reference.
+	*
+	* Drizzle columns expose a `.getSQL()` method used for query building.
+	*/
+	isDrizzleColumn(value) {
+		return !!value && typeof value === "object" && typeof value.getSQL === "function";
+	}
+};
+
+//#endregion
+export { ProjectionBuilder };

package/dist/core/query/where.mjs

@@ -0,0 +1,265 @@
+import { and, between, eq, gt, gte, ilike, inArray, isNull, like, lt, lte, ne, notBetween, notInArray, or } from "drizzle-orm";
+
+//#region src/core/query/where.ts
+/**
+* Compiles user-facing where objects into Drizzle SQL conditions.
+*
+* Handles plain column equality, operator objects (`eq`, `gt`, `like`, …),
+* logical combinators (`and`, `or`), and the `esc()` escape-hatch values.
+*
+* Designed as a stateless utility — every method receives its inputs
+* explicitly so the class can be instantiated once and reused.
+*/
+var WhereCompiler = class {
+	/**
+	* Compiles a where value against a set of table fields into a Drizzle SQL condition.
+	*
+	* Accepts multiple forms:
+	* - A raw Drizzle `SQL` expression (passed through as-is).
+	* - A plain object mapping column names to values or operator descriptors.
+	* - `undefined` / `null` / falsy (returns `undefined`).
+	*
+	* @param fields - The Drizzle column map for the table (e.g. `schema.users`).
+	* @param where  - The user-supplied where clause.
+	* @returns A compiled `SQL` fragment, or `undefined` when no conditions apply.
+	*/
+	compile(fields, where) {
+		if (!where) return;
+		if (typeof where !== "object" || this.isPromiseLike(where)) return where;
+		if (this.isDrizzleSql(where)) return where;
+		return this.compileObject(fields, where);
+	}
+	/**
+	* Merges two independent where sources (e.g. model-level + call-level)
+	* into a single `AND` condition.
+	*
+	* Either source may be `undefined`; the other is returned unchanged.
+	* When both are present they are joined with `AND`.
+	*
+	* @param fields       - The Drizzle column map.
+	* @param optionsWhere - The where clause defined on the model options.
+	* @param stateWhere   - The where clause set via `.where()` at call-site.
+	* @returns The merged SQL condition, or `undefined`.
+	*/
+	compileEffective(fields, optionsWhere, stateWhere) {
+		const base = this.compile(fields, optionsWhere);
+		const extra = this.compile(fields, stateWhere);
+		if (base && extra) return and(base, extra);
+		return base ?? extra;
+	}
+	/**
+	* Compiles a plain object where clause against the table's column map.
+	*
+	* Each key in `where` is matched to a column in `fields`.
+	* The value is compiled via {@link compileColumnValue}.
+	*
+	* @param fields - The Drizzle column map.
+	* @param where  - A record of column-name → condition entries.
+	* @returns The combined `SQL` condition, or `undefined`.
+	*/
+	compileObject(fields, where) {
+		const parts = [];
+		for (const [key, value] of Object.entries(where)) {
+			if (value === void 0) continue;
+			const column = fields[key];
+			if (column) {
+				const sql = this.compileColumnValue(column, value);
+				if (sql) parts.push(sql);
+				continue;
+			}
+			if (value && typeof value === "object") throw new Error(`Relation where is not implemented yet for key '${key}'.`);
+		}
+		return this.combineWithAnd(parts);
+	}
+	/**
+	* Compiles a single column's condition into an SQL fragment.
+	*
+	* Supports:
+	* - Escaped values produced by `esc()`.
+	* - Operator objects (`{ eq, not, gt, in, like, … }`).
+	* - Logical combinators (`{ or: [...], and: [...] }`).
+	* - Plain scalar values (compiled as equality).
+	*
+	* @param column - The Drizzle column reference.
+	* @param value  - The condition value (scalar, operator object, or escaped).
+	* @returns A compiled `SQL` fragment, or `undefined`.
+	*/
+	compileColumnValue(column, value) {
+		if (this.isEscapedValue(value)) return this.compileEscapedValue(column, value);
+		if (value && typeof value === "object" && !Array.isArray(value)) return this.compileOperatorObject(column, value);
+		return eq(column, value);
+	}
+	/**
+	* Compiles an operator object (e.g. `{ gt: 5, lt: 10 }`) for a column.
+	*
+	* Iterates through all recognised operator keys and produces
+	* individual SQL fragments, then combines them with `AND`.
+	*/
+	compileOperatorObject(column, value) {
+		const parts = [];
+		this.compileEquality(column, value, parts);
+		this.compileComparison(column, value, parts);
+		this.compileRange(column, value, parts);
+		this.compilePattern(column, value, parts);
+		this.compileSet(column, value, parts);
+		this.compileNull(column, value, parts);
+		this.compileLogical(column, value, parts);
+		return this.combineWithAnd(parts);
+	}
+	/** Handles `eq` and `equal` operators. */
+	compileEquality(column, value, parts) {
+		if ("eq" in value) {
+			const u = this.unwrapEscaped(column, value.eq);
+			this.pushIfDefined(parts, u.sql ?? eq(column, u.value));
+		}
+		if ("equal" in value) {
+			const u = this.unwrapEscaped(column, value.equal);
+			this.pushIfDefined(parts, u.sql ?? eq(column, u.value));
+		}
+		if ("not" in value) {
+			const u = this.unwrapEscaped(column, value.not);
+			this.pushIfDefined(parts, u.sql ?? ne(column, u.value));
+		}
+	}
+	/** Handles `gt`, `gte`, `lt`, `lte` operators. */
+	compileComparison(column, value, parts) {
+		if ("gt" in value) {
+			const u = this.unwrapEscaped(column, value.gt);
+			this.pushIfDefined(parts, u.sql ?? gt(column, u.value));
+		}
+		if ("gte" in value) {
+			const u = this.unwrapEscaped(column, value.gte);
+			this.pushIfDefined(parts, u.sql ?? gte(column, u.value));
+		}
+		if ("lt" in value) {
+			const u = this.unwrapEscaped(column, value.lt);
+			this.pushIfDefined(parts, u.sql ?? lt(column, u.value));
+		}
+		if ("lte" in value) {
+			const u = this.unwrapEscaped(column, value.lte);
+			this.pushIfDefined(parts, u.sql ?? lte(column, u.value));
+		}
+	}
+	/** Handles `between` and `notBetween` operators. */
+	compileRange(column, value, parts) {
+		if ("between" in value) {
+			const pair = value.between;
+			if (pair) {
+				const a = this.unwrapEscaped(column, pair[0]);
+				const b = this.unwrapEscaped(column, pair[1]);
+				this.pushIfDefined(parts, a.sql);
+				this.pushIfDefined(parts, b.sql);
+				this.pushIfDefined(parts, between(column, a.value, b.value));
+			}
+		}
+		if ("notBetween" in value) {
+			const pair = value.notBetween;
+			if (pair) {
+				const a = this.unwrapEscaped(column, pair[0]);
+				const b = this.unwrapEscaped(column, pair[1]);
+				this.pushIfDefined(parts, a.sql);
+				this.pushIfDefined(parts, b.sql);
+				this.pushIfDefined(parts, notBetween(column, a.value, b.value));
+			}
+		}
+	}
+	/** Handles `like` and `ilike` operators. */
+	compilePattern(column, value, parts) {
+		if ("like" in value) {
+			const u = this.unwrapEscaped(column, value.like);
+			this.pushIfDefined(parts, u.sql ?? like(column, u.value));
+		}
+		if ("ilike" in value) {
+			const u = this.unwrapEscaped(column, value.ilike);
+			this.pushIfDefined(parts, u.sql ?? ilike(column, u.value));
+		}
+	}
+	/** Handles `in` and `nin` (not-in) operators. */
+	compileSet(column, value, parts) {
+		if ("in" in value) this.compileArrayOperator(column, value.in, parts, inArray);
+		if ("nin" in value) this.compileArrayOperator(column, value.nin, parts, notInArray);
+	}
+	/** Handles `isNull` operator. */
+	compileNull(column, value, parts) {
+		if ("isNull" in value && value.isNull) this.pushIfDefined(parts, isNull(column));
+	}
+	/** Handles `or` and `and` logical combinators at the column level. */
+	compileLogical(column, value, parts) {
+		if (Array.isArray(value.or)) {
+			const sub = value.or.map((item) => this.compileColumnValue(column, item)).filter(Boolean);
+			if (sub.length > 0) this.pushIfDefined(parts, or(...sub));
+		}
+		if (Array.isArray(value.and)) {
+			const sub = value.and.map((item) => this.compileColumnValue(column, item)).filter(Boolean);
+			if (sub.length > 0) this.pushIfDefined(parts, and(...sub));
+		}
+	}
+	/**
+	* Compiles an array-based set operator (`IN` or `NOT IN`).
+	*
+	* Each element is unwrapped; raw SQL fragments are combined with `OR`,
+	* plain values are passed to the set operator.
+	*/
+	compileArrayOperator(column, items, parts, setFn) {
+		if (!items) return;
+		const unwrapped = items.map((item) => this.unwrapEscaped(column, item));
+		const sqlFragments = unwrapped.map((u) => u.sql).filter(Boolean);
+		const plainValues = unwrapped.map((u) => u.value).filter((v) => v !== void 0);
+		if (sqlFragments.length > 0) this.pushIfDefined(parts, or(...sqlFragments));
+		if (plainValues.length > 0) this.pushIfDefined(parts, setFn(column, plainValues));
+	}
+	/**
+	* Compiles an `esc()`-produced escaped value.
+	*
+	* If the escaped value carries an explicit operator, it is invoked
+	* with the column. Otherwise, implicit equality is applied.
+	*/
+	compileEscapedValue(column, value) {
+		if ("__kind" in value && value.__kind === "esc-op") {
+			const escaped = value;
+			return escaped.op(column, escaped.value);
+		}
+		return eq(column, value.equal);
+	}
+	/**
+	* Unwraps a potentially escaped value into either a raw SQL fragment
+	* or a plain value suitable for parameterised queries.
+	*/
+	unwrapEscaped(column, value) {
+		if (!this.isEscapedValue(value)) return { value };
+		if ("__kind" in value && value.__kind === "esc-op") {
+			const escaped = value;
+			return { sql: escaped.op(column, escaped.value) };
+		}
+		return { value: value.equal };
+	}
+	/** Checks whether a value is an `esc()` descriptor. */
+	isEscapedValue(value) {
+		return !!value && typeof value === "object" && ("equal" in value || value.__kind === "esc-op");
+	}
+	/** Checks whether a value exposes a Drizzle `.getSQL()` method. */
+	isDrizzleSql(value) {
+		return !!value && typeof value === "object" && typeof value.getSQL === "function";
+	}
+	/** Checks whether a value is thenable (a promise). */
+	isPromiseLike(value) {
+		return !!value && (typeof value === "object" || typeof value === "function") && typeof value.then === "function";
+	}
+	/** Pushes an SQL fragment into `parts` only when it is defined. */
+	pushIfDefined(parts, sql) {
+		if (sql) parts.push(sql);
+	}
+	/**
+	* Combines an array of SQL fragments with `AND`.
+	*
+	* Returns `undefined` for an empty array, the single element
+	* for a one-item array, or a full `AND(…)` expression otherwise.
+	*/
+	combineWithAnd(parts) {
+		if (parts.length === 0) return;
+		return parts.length === 1 ? parts[0] : and(...parts);
+	}
+};
+
+//#endregion
+export { WhereCompiler };