@vantreeseba/drizzle-graphql 14.0.0 → 15.1.0

package/dist/index.js

@@ -1,9 +1,9 @@
 import { Column, One, SQL, Table, aliasedTable, and, arrayContains, arrayOverlaps, asc, avg, count, countDistinct, desc, eq, extractExtendedColumnType, getColumns, getTableAsAliasSQL, gt, gte, ilike, inArray, is, isNotNull, isNull, like, lt, lte, max, min, ne, not, notIlike, notInArray, notLike, or, relationsFilterToSQL, sql, sum } from "drizzle-orm";
-import { MySqlAsyncDatabase, MySqlInt, MySqlSerial, MySqlTable, getTableConfig } from "drizzle-orm/mysql-core";
+import { MySqlAsyncDatabase, MySqlDate, MySqlDateString, MySqlDateTime, MySqlDateTimeString, MySqlInt, MySqlSerial, MySqlTable, MySqlTimestamp, MySqlTimestampString, getTableConfig } from "drizzle-orm/mysql-core";
 import { PgAsyncDatabase, PgDate, PgDateString, PgInteger, PgSerial, PgTable, PgTimestamp, PgTimestampString, PgUUID, getTableConfig as getTableConfig$1 } from "drizzle-orm/pg-core";
-import { SQLiteAsyncDatabase, SQLiteInteger, SQLiteTable, getTableConfig as getTableConfig$2 } from "drizzle-orm/sqlite-core";
+import { SQLiteAsyncDatabase, SQLiteInteger, SQLiteTable, SQLiteTimestamp, getTableConfig as getTableConfig$2 } from "drizzle-orm/sqlite-core";
 import { GraphQLBoolean, GraphQLEnumType, GraphQLError, GraphQLFloat, GraphQLInputObjectType, GraphQLInt, GraphQLList, GraphQLNonNull, GraphQLObjectType, GraphQLScalarType, GraphQLSchema, GraphQLString, Kind, getArgumentValues } from "graphql";
-import { GraphQLDate, GraphQLDateTime, GraphQLJSON, GraphQLUUID } from "graphql-scalars";
+import { GraphQLDateTime, GraphQLJSON, GraphQLUUID } from "graphql-scalars";
 import pluralize from "pluralize";
 //#region src/util/builders/common/errors.ts
 /**
@@ -160,6 +160,76 @@ const GraphQLDecimalString = new GraphQLScalarType({
 		return parseNumeric(ast.value);
 	}
 });
+const fullDatePattern = /^(\d{4})-(\d{2})-(\d{2})$/;
+const daysInMonth = (year, month) => {
+	if (month === 2) return year % 4 === 0 && year % 100 !== 0 || year % 400 === 0 ? 29 : 28;
+	return [
+		4,
+		6,
+		9,
+		11
+	].includes(month) ? 30 : 31;
+};
+/** Whether `value` is a `YYYY-MM-DD` string naming a day that exists on the calendar. */
+const isCalendarDate = (value) => {
+	const match = fullDatePattern.exec(value);
+	if (!match) return false;
+	const year = Number(match[1]);
+	const month = Number(match[2]);
+	const day = Number(match[3]);
+	return month >= 1 && month <= 12 && day >= 1 && day <= daysInMonth(year, month);
+};
+/**
+* A JS `Date` as the calendar day it stands for. Read in UTC, because that is how drivers
+* build one from a `date` column: `new Date('2026-09-15')` is UTC midnight, so the local
+* getters would name the previous day anywhere west of Greenwich.
+*/
+const dateToCalendarDate = (value) => {
+	if (Number.isNaN(value.getTime())) return;
+	const year = value.getUTCFullYear();
+	if (year < 0 || year > 9999) return;
+	const month = String(value.getUTCMonth() + 1).padStart(2, "0");
+	const day = String(value.getUTCDate()).padStart(2, "0");
+	return `${String(year).padStart(4, "0")}-${month}-${day}`;
+};
+const calendarDate = (code, acceptDate) => (value) => {
+	if (typeof value === "string") {
+		if (!isCalendarDate(value)) throw drizzleError(`Date cannot represent "${value}": expected a calendar date as YYYY-MM-DD`, { code });
+		return value;
+	}
+	if (acceptDate && value instanceof Date) {
+		const formatted = dateToCalendarDate(value);
+		if (formatted === void 0) throw drizzleError("Date cannot represent an invalid or out-of-range Date", { code });
+		return formatted;
+	}
+	throw drizzleError(`Date cannot represent value: ${JSON.stringify(value)}: expected a YYYY-MM-DD string`, { code });
+};
+const parseCalendarDate = calendarDate(INVALID_INPUT, false);
+/**
+* A calendar day — `date` columns, whichever `mode` drizzle reads them in. Always transported
+* as an RFC 3339 `full-date` string (`YYYY-MM-DD`), in both directions: it has no time and no
+* offset, so there is nothing for a client's timezone to shift. `graphql-scalars`' own
+* `GraphQLDate` is deliberately not used: its `parseValue` returns a JS `Date`, so the same
+* scalar would be a string on the way out and an instant on the way in.
+*
+* Input accepts only a `YYYY-MM-DD` string naming a real day (`2026-02-30` and datetime
+* strings are rejected) and hands it on unchanged. Output also accepts a JS `Date`, read as
+* the UTC day it encodes.
+*/
+const GraphQLDate = new GraphQLScalarType({
+	name: "Date",
+	description: "A calendar date with no time or offset, transported as an RFC 3339 full-date string (YYYY-MM-DD).",
+	specifiedByURL: "https://datatracker.ietf.org/doc/html/rfc3339#section-5.6",
+	serialize: calendarDate(UNREPRESENTABLE, true),
+	parseValue: parseCalendarDate,
+	parseLiteral: (ast) => {
+		if (ast.kind !== Kind.STRING) throw drizzleError(`Date cannot represent a ${ast.kind}`, {
+			code: INVALID_INPUT,
+			nodes: ast
+		});
+		return parseCalendarDate(ast.value);
+	}
+});
 //#endregion
 //#region src/util/case-ops/index.ts
 const uncapitalize = (input) => input?.length ? `${input[0].toLocaleLowerCase()}${input.length > 1 ? input.slice(1, input.length) : ""}` : input;
@@ -193,6 +263,17 @@ const singularizeMapper = (tableName) => ({
 //#endregion
 //#region src/util/type-converter/index.ts
 const allowedNameChars = /^[a-zA-Z0-9_]+$/;
+/** drizzle's `number` constraints whose values always fit a GraphQL `Int` (32-bit signed). */
+const smallIntegerConstraints = /* @__PURE__ */ new Set([
+	"int8",
+	"uint8",
+	"int16",
+	"uint16",
+	"int24",
+	"uint24",
+	"int32",
+	"year"
+]);
 /** A GraphQL `Name` that is also allowed as an enum value — the spec reserves the three literals. */
 const validEnumValueName = (name) => /^[_a-zA-Z][_a-zA-Z0-9]*$/.test(name) && name !== "true" && name !== "false" && name !== "null";
 /**
@@ -333,6 +414,52 @@ const geoXyInputType = new GraphQLInputObjectType({
 		y: { type: GraphQLFloat }
 	}
 });
+/**
+* Whether the column holds a calendar day with no time component — a SQL `date`, in either of
+* the modes drizzle reads one in (`'date'` → a JS `Date`, `'string'` → `YYYY-MM-DD`). Every
+* position a column's type appears in — output, create/update input, filter operands,
+* aggregates and group keys — gives such a column the `Date` scalar, whichever mode it uses:
+* the mode is how the server holds the value, not what the value is. SQLite has no date-only
+* column type (its integer timestamps are instants — see {@link isDateTimeColumn}), so only
+* Postgres and MySQL appear here.
+*/
+const isDateOnlyColumn = (column) => is(column, PgDate) || is(column, PgDateString) || is(column, MySqlDate) || is(column, MySqlDateString);
+/**
+* Whether the column is a MySQL `timestamp` / `datetime` read in drizzle's `'string'` mode. The
+* driver hands such a column back as MySQL's own `YYYY-MM-DD HH:MM:SS[.fraction]` text, with no
+* offset, and expects that form on write, so the data mappers translate between it and the ISO
+* 8601 instant the `DateTime` scalar carries. The text is read as UTC, the way drizzle's own
+* `'date'`-mode codecs for these columns read it.
+*/
+const isMySqlDateTimeStringColumn = (column) => is(column, MySqlTimestampString) || is(column, MySqlDateTimeString);
+/**
+* Whether the column is a Postgres `timestamp` read in drizzle's `'string'` mode. The driver hands
+* such a column back as Postgres's own text — `YYYY-MM-DD HH:MM:SS[.fraction]`, followed by an
+* offset (`+00`, `-06`, `+05:30`) for `timestamptz` — so the data mappers translate between it
+* and the ISO 8601 instant the `DateTime` scalar carries. Text without an offset (`timestamp`
+* without time zone) is read as UTC, the way drizzle's own `'date'`-mode codec reads it.
+*/
+const isPgTimestampStringColumn = (column) => is(column, PgTimestampString);
+/**
+* Whether the column is a SQLite `integer({ mode: 'timestamp' | 'timestamp_ms' })`. Both modes
+* are one drizzle class, told apart by `mode`: the stored integer counts seconds or milliseconds
+* since the Unix epoch. drizzle converts a JS `Date` to that integer on write (`'timestamp'`
+* floors to the whole second) and back on read, but a value read through a path that skips the
+* column's decoder arrives as the bare integer, which {@link sqliteTimestampToDate} reads.
+*/
+const isSQLiteTimestampColumn = (column) => is(column, SQLiteTimestamp);
+/**
+* A SQLite timestamp column's stored integer as the instant it names, using the column's own
+* unit (seconds for `'timestamp'`, milliseconds for `'timestamp_ms'`).
+*/
+const sqliteTimestampToDate = (column, value) => new Date(column.mode === "timestamp" ? value * 1e3 : value);
+/**
+* Whether the column holds an instant — a Postgres `timestamp`, a MySQL `timestamp` /
+* `datetime`, in either drizzle mode, or a SQLite integer timestamp in either unit. Every position
+* such a column appears in gives it the `DateTime` scalar and the `DateTimeFilter`, whichever
+* mode it uses, for the same reason as {@link isDateOnlyColumn}.
+*/
+const isDateTimeColumn = (column) => is(column, PgTimestamp) || isPgTimestampStringColumn(column) || is(column, MySqlTimestamp) || is(column, MySqlDateTime) || isMySqlDateTimeStringColumn(column) || isSQLiteTimestampColumn(column);
 const columnToGraphQLCore = (column, columnName, tableName, isInput) => {
 	const dimensions = column.dimensions;
 	if (dimensions !== void 0 && dimensions > 0) {
@@ -359,7 +486,11 @@ const columnBaseToGraphQLCore = (column, columnName, tableName, isInput) => {
 			typeLabel: "Boolean"
 		};
 		case "object":
-			if (column instanceof PgTimestamp || column instanceof PgDate) return {
+			if (isDateOnlyColumn(column)) return {
+				type: GraphQLDate,
+				typeLabel: "Date"
+			};
+			if (isDateTimeColumn(column)) return {
 				type: GraphQLDateTime,
 				typeLabel: "DateTime"
 			};
@@ -379,7 +510,7 @@ const columnBaseToGraphQLCore = (column, columnName, tableName, isInput) => {
 				type: GraphQLDecimalString,
 				typeLabel: "Decimal"
 			};
-			if (column instanceof PgTimestamp || column instanceof PgTimestampString) return {
+			if (isDateTimeColumn(column)) return {
 				type: GraphQLDateTime,
 				typeLabel: "DateTime"
 			};
@@ -387,10 +518,7 @@ const columnBaseToGraphQLCore = (column, columnName, tableName, isInput) => {
 				type: GraphQLUUID,
 				typeLabel: "UUID"
 			};
-			if (column instanceof PgDateString) return isInput ? {
-				type: GraphQLString,
-				typeLabel: "Date"
-			} : {
+			if (isDateOnlyColumn(column)) return {
 				type: GraphQLDate,
 				typeLabel: "Date"
 			};
@@ -402,7 +530,7 @@ const columnBaseToGraphQLCore = (column, columnName, tableName, isInput) => {
 			type: GraphQLBigIntString,
 			typeLabel: "BigInt"
 		};
-		case "number": return is(column, PgInteger) || is(column, PgSerial) || is(column, MySqlInt) || is(column, MySqlSerial) || is(column, SQLiteInteger) ? {
+		case "number": return constraint !== void 0 && smallIntegerConstraints.has(constraint) || is(column, PgInteger) || is(column, PgSerial) || is(column, MySqlInt) || is(column, MySqlSerial) || is(column, SQLiteInteger) ? {
 			type: GraphQLInt,
 			typeLabel: "Integer"
 		} : {
@@ -578,7 +706,8 @@ const isJsonColumn = (column) => (column.dataType ?? "").includes("json") && col
 * - "Decimal"     → numeric/decimal columns (Decimal-scalar-typed operators, no string pattern operators)
 * - the enum GraphQL type name → enum columns (still unique per enum; equality and
 *                       membership only, like Boolean)
-* - "DateTime"    → timestamp and date columns (ordering kept, no string pattern operators)
+* - "Date"        → date columns, either mode (ordering kept, no string pattern operators)
+* - "DateTime"    → timestamp columns (ordering kept, no string pattern operators)
 * - "Int"         → integer/serial columns (no string pattern operators)
 * - "Float"       → real/double columns (no string pattern operators)
 * - "String"      → all other text/varchar columns
@@ -617,8 +746,11 @@ const resolveGenericFilterDescriptor = (column, columnGraphQLType) => {
 		name: "Decimal",
 		kind: "scalar"
 	};
-	const ct = column.columnType ?? "";
-	if (ct === "PgTimestamp" || ct === "PgTimestampString" || ct === "PgDate") return {
+	if (columnGraphQLType.type === GraphQLDate) return {
+		name: "Date",
+		kind: "scalar"
+	};
+	if (isDateTimeColumn(column)) return {
 		name: "DateTime",
 		kind: "scalar"
 	};
@@ -1013,6 +1145,58 @@ const generateColumnFilterValues = (column, tableName, columnName, cacheCtx) =>
 };
 //#endregion
 //#region src/util/data-mappers/index.ts
+/**
+* MySQL's own text form for a `timestamp` / `datetime`: `YYYY-MM-DD HH:MM:SS`, an optional
+* fraction, and no offset. mysql2 returns it for a `'string'`-mode column, and it is what such a
+* column expects on write.
+*/
+const MYSQL_DATETIME_TEXT = /^(\d{4}-\d{2}-\d{2})[ T](\d{2}:\d{2}:\d{2}(?:\.\d+)?)$/;
+/**
+* MySQL datetime text, read as UTC, as the ISO 8601 instant the `DateTime` scalar carries.
+* UTC because that is how drizzle's own `'date'`-mode codecs read the same text, so a column's
+* two modes agree on the instant. Anything else (a zero date, a value already carrying an
+* offset) is returned unchanged for the scalar to accept or reject.
+*/
+const mySqlDateTimeTextToIso = (value) => {
+	const match = MYSQL_DATETIME_TEXT.exec(value);
+	return match ? `${match[1]}T${match[2]}Z` : value;
+};
+/**
+* A JS `Date` as offset-less `YYYY-MM-DD HH:MM:SS.mmm` text in UTC: what a MySQL `'string'`-mode
+* column and a Postgres `timestamp` (without time zone) `'string'`-mode column are written with.
+*/
+const dateToUtcWallText = (value) => value.toISOString().slice(0, -1).replace("T", " ");
+/**
+* Postgres's text form for a `timestamp` / `timestamptz` (the `ISO` `DateStyle`, the default):
+* `YYYY-MM-DD HH:MM:SS`, an optional fraction, and — for `timestamptz` only — the session zone's
+* offset as `±HH`, `±HH:MM` or, for historical local mean time, `±HH:MM:SS`.
+*/
+const PG_TIMESTAMP_TEXT = /^(\d{4}-\d{2}-\d{2})[ T](\d{2}:\d{2}:\d{2})(\.\d+)?(?:([+-])(\d{2})(?::?(\d{2}))?(?::?(\d{2}))?)?$/;
+/**
+* Postgres timestamp text as the RFC 3339 UTC instant (`…Z`) the `DateTime` scalar accepts.
+*
+* - With an offset (`timestamptz`), the instant is shifted to UTC. The offset can carry seconds,
+*   which RFC 3339 cannot express, so it is applied here rather than rewritten.
+* - Without one (`timestamp`), the wall time is read as UTC: that is what drizzle's `'date'`-mode
+*   codec does (`new Date(text + '+0000')`) and what the input side writes, so a column's two
+*   modes agree on the instant.
+* - The fraction is kept digit for digit. The scalar itself carries milliseconds, so microseconds
+*   are truncated on the wire, never rounded into the next second.
+*
+* Anything else (`infinity`, a `BC` date, a five-digit year) is returned unchanged for the scalar
+* to reject.
+*/
+const pgTimestampTextToIso = (value) => {
+	const match = PG_TIMESTAMP_TEXT.exec(value);
+	if (!match) return value;
+	const [, date, time, fraction = "", sign, hours, minutes = "0", seconds = "0"] = match;
+	if (!sign) return `${date}T${time}${fraction}Z`;
+	const wallMs = Date.parse(`${date}T${time}Z`);
+	if (Number.isNaN(wallMs)) return value;
+	const offsetSeconds = (sign === "-" ? -1 : 1) * (Number(hours) * 3600 + Number(minutes) * 60 + Number(seconds));
+	const utc = (/* @__PURE__ */ new Date(wallMs - offsetSeconds * 1e3)).toISOString();
+	return utc.length === 24 ? `${utc.slice(0, 19)}${fraction}Z` : value;
+};
 const remapToGraphQLCore = (key, value, tableName, column, relationMap) => {
 	if (Array.isArray(value)) {
 		const relations = relationMap?.[tableName];
@@ -1031,7 +1215,14 @@ const remapToGraphQLCore = (key, value, tableName, column, relationMap) => {
 	if (!column) return value;
 	if (getColumnScalarOverride(column, false)) return value;
 	if (isJsonColumn(column)) return value;
+	if (value instanceof Date && isDateOnlyColumn(column)) return dateToCalendarDate(value) ?? value;
+	if (typeof value === "number" && isSQLiteTimestampColumn(column)) {
+		const instant = sqliteTimestampToDate(column, value);
+		return Number.isNaN(instant.getTime()) ? value : instant.toISOString();
+	}
 	if (value instanceof Date) return value.toISOString();
+	if (typeof value === "string" && isMySqlDateTimeStringColumn(column)) return mySqlDateTimeTextToIso(value);
+	if (typeof value === "string" && isPgTimestampStringColumn(column)) return pgTimestampTextToIso(value);
 	if (value instanceof Buffer) return Array.from(value);
 	if (typeof value === "bigint") return value.toString();
 	if (Array.isArray(value)) {
@@ -1077,16 +1268,20 @@ const remapFromGraphQLCore = (value, column, columnName) => {
 	}
 	const dataType = column.dataType ?? "";
 	const columnType = column.columnType ?? "";
-	if (columnType === "SQLiteTimestamp" || columnType === "SQLiteTimestampMs" || columnType === "MySqlTimestamp" || columnType === "MySqlDateTime" || columnType === "PgTimestamp" || columnType === "PgTimestampString") {
-		const formatted = new Date(value);
+	if (isDateTimeColumn(column)) {
+		const isMySql = columnType.startsWith("MySql");
+		const isPgString = isPgTimestampStringColumn(column);
+		const toIso = isMySql ? mySqlDateTimeTextToIso : isPgString ? pgTimestampTextToIso : void 0;
+		const formatted = new Date(toIso && typeof value === "string" ? toIso(value) : value);
 		if (Number.isNaN(formatted.getTime())) throw drizzleError(`Field '${columnName}' is not a valid date!`, { code: "DRIZZLE_INVALID_INPUT_VALUE" });
-		return formatted;
+		if (isPgString) return column.withTimezone ? formatted.toISOString() : dateToUtcWallText(formatted);
+		return isMySqlDateTimeStringColumn(column) ? dateToUtcWallText(formatted) : formatted;
 	}
-	if ((columnType === "MySqlDate" || columnType === "PgDate") && typeof value === "string") {
-		const dateOnly = value.includes("T") ? value.split("T")[0] : value;
-		const check = new Date(dateOnly);
-		if (Number.isNaN(check.getTime())) throw drizzleError(`Field '${columnName}' is not a valid date!`, { code: "DRIZZLE_INVALID_INPUT_VALUE" });
-		return dateOnly;
+	if (isDateOnlyColumn(column)) {
+		if (Array.isArray(value)) return value.map((element) => remapFromGraphQLCore(element, column, columnName));
+		const day = value instanceof Date ? dateToCalendarDate(value) : value;
+		if (typeof day !== "string" || !isCalendarDate(day)) throw drizzleError(`Field '${columnName}' is not a valid date! Expected a calendar date as YYYY-MM-DD.`, { code: "DRIZZLE_INVALID_INPUT_VALUE" });
+		return day;
 	}
 	if (dataType.includes("bigint")) try {
 		return BigInt(value);
@@ -1442,7 +1637,8 @@ const extractFiltersColumn = (column, columnName, operators) => {
 	}
 	if (NOT) {
 		const extracted = extractFiltersColumn(column, columnName, NOT);
-		if (extracted) variants.push(not(extracted));
+		const negated = extracted ? not(extracted) : void 0;
+		if (negated) variants.push(negated);
 	}
 	if (OR?.length) {
 		const orVariants = [];
@@ -1455,6 +1651,192 @@ const extractFiltersColumn = (column, columnName, operators) => {
 	return variants.length ? variants.length > 1 ? and(...variants) : variants[0] : void 0;
 };
 //#endregion
+//#region src/util/builders/common/relations.ts
+/**
+* Flatten drizzle-orm v1 TablesRelationalConfig into the canonical
+* Record<tableName, Record<relName, TableNamedRelations>> shape used
+* throughout common.ts.  Both pg.ts and sqlite.ts call this before
+* passing the relation map to any shared function.
+*/
+const buildNamedRelations = (relations, tableEntries) => {
+	const namedRelations = {};
+	for (const [relTableName, relConfig] of Object.entries(relations)) {
+		if (!relConfig?.relations) continue;
+		const namedConfig = {};
+		for (const [innerRelName, innerRelValue] of Object.entries(relConfig.relations)) {
+			const targetTable = innerRelValue.targetTable ?? innerRelValue.referencedTable;
+			const directTargetName = innerRelValue.targetTableName;
+			let targetTableName;
+			if (directTargetName) targetTableName = tableEntries.find(([key]) => key === directTargetName)?.[0];
+			else if (targetTable) targetTableName = tableEntries.find(([, tableValue]) => tableValue === targetTable)?.[0];
+			if (!targetTableName) continue;
+			namedConfig[innerRelName] = {
+				relation: innerRelValue,
+				targetTableName
+			};
+		}
+		if (Object.keys(namedConfig).length > 0) namedRelations[relTableName] = namedConfig;
+	}
+	return namedRelations;
+};
+/**
+* Records each relation's target-table primary-key property names on the relation entry,
+* so the pagination paths (the window-function batch loader and the eager `with:` orderBy
+* default) can fall back to a deterministic PK order without re-deriving it per request.
+*
+* Composite primary keys are only visible through the dialect's getTableConfig, so the
+* dialect builder passes a `resolvePkNames` that threads the composite column names in.
+* Mutates the relation entries in place (they are shared with the pruned eager map and
+* the resolver factory, so attaching once covers every consumer).
+*/
+const attachTargetPrimaryKeys = (namedRelations, tables, resolvePkNames) => {
+	const cache = /* @__PURE__ */ new Map();
+	for (const rels of Object.values(namedRelations)) for (const relEntry of Object.values(rels)) {
+		const { targetTableName } = relEntry;
+		let pk = cache.get(targetTableName);
+		if (!pk) {
+			const targetTable = tables[targetTableName];
+			pk = targetTable ? resolvePkNames(targetTable) : [];
+			cache.set(targetTableName, pk);
+		}
+		relEntry.targetPkNames = pk;
+	}
+};
+/**
+* The table column behind one entry of a relation's `sourceColumns`, `targetColumns` or
+* `through` lists.
+*
+* drizzle-orm rc.4 stores the table's own Column objects in `sourceColumns` / `targetColumns`
+* and a `RelationsBuilderColumn` descriptor (`{ _: { column, key, tableName } }`) in `through`.
+* The rc.5 snapshots store the descriptor in all of them. Both shapes are accepted here, told
+* apart structurally rather than by importing a class one of those versions does not export.
+* Anything else yields `undefined`, which callers treat as "join columns not readable".
+*/
+const unwrapRelationColumn = (entry) => {
+	if (is(entry, Column)) return entry;
+	const inner = entry?._?.column;
+	return is(inner, Column) ? inner : void 0;
+};
+/**
+* A relation's `sourceColumns` or `targetColumns` as table columns, via
+* {@link unwrapRelationColumn}. `undefined` when the list is missing, empty, or has an entry
+* that is not a column in either known shape.
+*/
+const relationColumns = (relation, side) => {
+	const entries = relation?.[side === "source" ? "sourceColumns" : "targetColumns"];
+	if (!entries?.length) return;
+	const columns = [];
+	for (const entry of entries) {
+		const column = unwrapRelationColumn(entry);
+		if (!column) return;
+		columns.push(column);
+	}
+	return columns;
+};
+/**
+* drizzle-orm's "no filter" sentinel. rc.5 snapshots export it as `EmptyFilter` and use it as
+* the default `relation.where`; rc.4 has no such export and leaves `where` undefined. It is a
+* registered symbol, so it can be compared against without importing anything.
+*/
+const EMPTY_FILTER = Symbol.for("drizzle:EmptyFilter");
+/**
+* The relation's own declared `where` filter, or `undefined` when it has none. rc.4 leaves
+* `where` undefined in that case; rc.5 snapshots set it to the `EmptyFilter` sentinel, which is
+* truthy and must not be read as a filter.
+*/
+const relationOwnWhere = (relation) => {
+	const where = relation?.where;
+	return where == null || where === EMPTY_FILTER ? void 0 : where;
+};
+/**
+* Whether the relation's `where` was inherited from its reverse relation, and so is written
+* against the parent table rather than the target. rc.4 calls this flag `isReversed`; rc.5
+* snapshots renamed it to `isFilterReversed`. Both are set in the same place with the same
+* meaning (true only for a relation declared without `from`/`to` and without its own `where`).
+*/
+const isRelationFilterReversed = (relation) => !!(relation?.isFilterReversed ?? relation?.isReversed);
+/**
+* Warns, at build time, that a field was left out because the relation's join columns could
+* not be matched to its tables. Omitting it silently is how a drizzle-orm change in the shape
+* of relation columns (issue #179) went unnoticed. A relation that declares no join columns
+* is not reported: there is nothing that failed to match.
+*/
+const warnUnresolvedJoin = (relEntry, tableName, relationName, omitted) => {
+	const rel = relEntry.relation ?? relEntry;
+	if (!rel?.sourceColumns?.length || !rel?.targetColumns?.length) return;
+	console.warn(`Drizzle-GraphQL Warning: relation '${tableName}.${relationName}' declares join columns that could not be matched to columns of '${tableName}' and '${relEntry.targetTableName}', so ${omitted} is not generated. The installed drizzle-orm probably stores relation columns in a shape this version of drizzle-graphql does not recognize.`);
+};
+/**
+* Extracts the join column info from a drizzle-orm v1 Relation object.
+* Returns the JS property name of the local column on the parent table and the
+* Column object for the foreign column on the target table, or undefined if the
+* relation internals are not accessible.
+*/
+const extractRelationJoinColumns = (relEntry, parentTable, targetTable) => {
+	const rel = relEntry.relation ?? relEntry;
+	const sourceCol = relationColumns(rel, "source")?.[0];
+	const targetCol = relationColumns(rel, "target")?.[0];
+	if (!sourceCol || !targetCol) return;
+	const parentCols = getColumns(parentTable);
+	const localColPropName = Object.entries(parentCols).find(([, c]) => c === sourceCol)?.[0];
+	const targetCols = getColumns(targetTable);
+	const foreignColPropName = Object.entries(targetCols).find(([, c]) => c === targetCol)?.[0];
+	if (!localColPropName || !foreignColPropName) return;
+	return {
+		localColPropName,
+		foreignCol: targetCol,
+		foreignColPropName
+	};
+};
+/**
+* The junction table and its two columns for a `.through()` (many-to-many) relation:
+* `sourceCol` holds the parent's key, `targetCol` the target's. `undefined` for a relation
+* with no junction; `null` for one whose junction cannot be used here — more than one column
+* on either side, or columns that are not on the junction table.
+*/
+const extractJunctionColumns = (relEntry) => {
+	const rel = relEntry.relation ?? relEntry;
+	const junction = rel?.throughTable;
+	if (!junction) return;
+	const sourceEntries = rel.through?.source;
+	const targetEntries = rel.through?.target;
+	if (sourceEntries?.length !== 1 || targetEntries?.length !== 1) return null;
+	const junctionCols = Object.values(getColumns(junction));
+	const sourceCol = unwrapRelationColumn(sourceEntries[0]);
+	const targetCol = unwrapRelationColumn(targetEntries[0]);
+	if (!sourceCol || !targetCol || !junctionCols.includes(sourceCol) || !junctionCols.includes(targetCol)) return null;
+	return {
+		table: junction,
+		sourceCol,
+		targetCol
+	};
+};
+/**
+* The relation's own declared `where` as a condition on a query that reads the target table,
+* or `undefined` when it has none. The eager path gets this from drizzle's `with:`; the batched
+* field resolver and `<relation>Aggregate` read the target table directly, so they have to add
+* it themselves or they return rows the relation hides.
+*
+* A reversed filter (inherited from the relation on the other side) is written against the
+* parent table, so it is applied as "the row's parent key belongs to a parent that passes it".
+* `parentKeyCol` is the parent's join column and `groupCol` the column in the query that holds
+* the parent key for each row — the target's foreign key, or the junction's source column.
+*/
+const relationOwnCondition = (relEntry, parentTable, targetTable, parentKeyCol, groupCol) => {
+	const rel = relEntry.relation ?? relEntry;
+	const ownWhere = relationOwnWhere(rel);
+	if (!ownWhere) return;
+	if (!isRelationFilterReversed(rel)) return relationsFilterToSQL(targetTable, ownWhere);
+	const parentFilter = relationsFilterToSQL(parentTable, ownWhere);
+	return sql`${groupCol} in (select ${parentKeyCol} from ${parentTable} where ${parentFilter})`;
+};
+/**
+* Whether a to-one relation can back a relation orderBy hop. `.through()` (junction)
+* relations are excluded — the ordering subquery only joins the direct target, never the
+* junction table. (Relation *filters* do support `.through()` — this guard is orderBy-only.)
+*/
+const isFilterableRelation = (relation) => !relation.through;
+//#endregion
 //#region src/util/builders/common/exclusions.ts
 /**
 * Columns this build keeps out of the generated schema, keyed by the table object.
@@ -1630,8 +2012,8 @@ const relationFilterCtx = (base, tableKey) => {
 * the parent is an aliased proxy (as it is inside a relational `with:` where callback).
 */
 const buildRelationJoinCondition = (parentTable, relation, aliasedTarget, relationName) => {
-	const sourceColumns = relation.sourceColumns;
-	const targetColumns = relation.targetColumns;
+	const sourceColumns = relationColumns(relation, "source");
+	const targetColumns = relationColumns(relation, "target");
 	if (!sourceColumns?.length || sourceColumns.length !== targetColumns?.length) throw drizzleError(`WHERE ${relationName}: Relation cannot be used as a filter`, { code: "DRIZZLE_INVALID_FILTER" });
 	const parentColumns = Object.values(getColumns(parentTable));
 	const targetColumnsByName = Object.values(getColumns(aliasedTarget));
@@ -1655,7 +2037,7 @@ const resolveJunctionColumn = (aliasedThrough, junctionRef, relationName) => {
 	const key = junctionRef?._?.key;
 	const byKey = key ? throughColumns[key] : void 0;
 	if (byKey) return byKey;
-	const columnName = junctionRef?._?.column?.name;
+	const columnName = unwrapRelationColumn(junctionRef)?.name;
 	const byName = columnName ? Object.values(throughColumns).find((c) => c.name === columnName) : void 0;
 	if (!byName) throw drizzleError(`WHERE ${relationName}: Relation cannot be used as a filter`, { code: "DRIZZLE_INVALID_FILTER" });
 	return byName;
@@ -1669,8 +2051,8 @@ const resolveJunctionColumn = (aliasedThrough, junctionRef, relationName) => {
 * `through` metadata.
 */
 const buildThroughJoinConditions = (parentTable, relation, aliasedThrough, aliasedTarget, relationName) => {
-	const sourceColumns = relation.sourceColumns;
-	const targetColumns = relation.targetColumns;
+	const sourceColumns = relationColumns(relation, "source");
+	const targetColumns = relationColumns(relation, "target");
 	const through = relation.through;
 	if (!sourceColumns?.length || !targetColumns?.length || through?.source.length !== sourceColumns.length || through.target.length !== targetColumns.length) throw drizzleError(`WHERE ${relationName}: Relation cannot be used as a filter`, { code: "DRIZZLE_INVALID_FILTER" });
 	const parentColumns = Object.values(getColumns(parentTable));
@@ -1722,7 +2104,8 @@ const buildRelationExists = (parentTable, relationName, relEntry, innerFilters,
 		fromClause = getTableAsAliasSQL(aliasedTarget);
 		joinCondition = buildRelationJoinCondition(parentTable, relation, aliasedTarget, relationName);
 	}
-	const relationWhere = relation.where ? relationsFilterToSQL(relation.isReversed ? parentTable : aliasedTarget, relation.where) : void 0;
+	const ownWhere = relationOwnWhere(relation);
+	const relationWhere = ownWhere ? relationsFilterToSQL(isRelationFilterReversed(relation) ? parentTable : aliasedTarget, ownWhere) : void 0;
 	const inner = innerFilters ? extractFilters(aliasedTarget, targetTableName, innerFilters, {
 		...ctx,
 		tableKey: targetTableName,
@@ -1776,7 +2159,8 @@ const extractFilters = (table, tableName, filters, relationCtx) => {
 	}
 	if (NOT) {
 		const extracted = extractFilters(table, tableName, NOT, relationCtx);
-		if (extracted) variants.push(not(extracted));
+		const negated = extracted ? not(extracted) : void 0;
+		if (negated) variants.push(negated);
 	}
 	if (OR?.length) {
 		const orVariants = [];
@@ -2173,88 +2557,6 @@ const excludedColumnRef = (columnName) => sql`excluded.${sql.identifier(columnNa
 /** `values(<column>)` — MySQL's equivalent inside ON DUPLICATE KEY UPDATE. */
 const mysqlValuesColumnRef = (columnName) => sql`values(${sql.identifier(columnName)})`;
 //#endregion
-//#region src/util/builders/common/relations.ts
-/**
-* Flatten drizzle-orm v1 TablesRelationalConfig into the canonical
-* Record<tableName, Record<relName, TableNamedRelations>> shape used
-* throughout common.ts.  Both pg.ts and sqlite.ts call this before
-* passing the relation map to any shared function.
-*/
-const buildNamedRelations = (relations, tableEntries) => {
-	const namedRelations = {};
-	for (const [relTableName, relConfig] of Object.entries(relations)) {
-		if (!relConfig?.relations) continue;
-		const namedConfig = {};
-		for (const [innerRelName, innerRelValue] of Object.entries(relConfig.relations)) {
-			const targetTable = innerRelValue.targetTable ?? innerRelValue.referencedTable;
-			const directTargetName = innerRelValue.targetTableName;
-			let targetTableName;
-			if (directTargetName) targetTableName = tableEntries.find(([key]) => key === directTargetName)?.[0];
-			else if (targetTable) targetTableName = tableEntries.find(([, tableValue]) => tableValue === targetTable)?.[0];
-			if (!targetTableName) continue;
-			namedConfig[innerRelName] = {
-				relation: innerRelValue,
-				targetTableName
-			};
-		}
-		if (Object.keys(namedConfig).length > 0) namedRelations[relTableName] = namedConfig;
-	}
-	return namedRelations;
-};
-/**
-* Records each relation's target-table primary-key property names on the relation entry,
-* so the pagination paths (the window-function batch loader and the eager `with:` orderBy
-* default) can fall back to a deterministic PK order without re-deriving it per request.
-*
-* Composite primary keys are only visible through the dialect's getTableConfig, so the
-* dialect builder passes a `resolvePkNames` that threads the composite column names in.
-* Mutates the relation entries in place (they are shared with the pruned eager map and
-* the resolver factory, so attaching once covers every consumer).
-*/
-const attachTargetPrimaryKeys = (namedRelations, tables, resolvePkNames) => {
-	const cache = /* @__PURE__ */ new Map();
-	for (const rels of Object.values(namedRelations)) for (const relEntry of Object.values(rels)) {
-		const { targetTableName } = relEntry;
-		let pk = cache.get(targetTableName);
-		if (!pk) {
-			const targetTable = tables[targetTableName];
-			pk = targetTable ? resolvePkNames(targetTable) : [];
-			cache.set(targetTableName, pk);
-		}
-		relEntry.targetPkNames = pk;
-	}
-};
-/**
-* Extracts the join column info from a drizzle-orm v1 Relation object.
-* Returns the JS property name of the local column on the parent table and the
-* Column object for the foreign column on the target table, or undefined if the
-* relation internals are not accessible.
-*/
-const extractRelationJoinColumns = (relEntry, parentTable, targetTable) => {
-	const rel = relEntry.relation ?? relEntry;
-	const sourceColumns = rel.sourceColumns;
-	const targetColumns = rel.targetColumns;
-	if (!sourceColumns?.length || !targetColumns?.length) return;
-	const sourceCol = sourceColumns[0];
-	const targetCol = targetColumns[0];
-	const parentCols = getColumns(parentTable);
-	const localColPropName = Object.entries(parentCols).find(([, c]) => c === sourceCol)?.[0];
-	const targetCols = getColumns(targetTable);
-	const foreignColPropName = Object.entries(targetCols).find(([, c]) => c === targetCol)?.[0];
-	if (!localColPropName || !foreignColPropName) return;
-	return {
-		localColPropName,
-		foreignCol: targetCol,
-		foreignColPropName
-	};
-};
-/**
-* Whether a to-one relation can back a relation orderBy hop. `.through()` (junction)
-* relations are excluded — the ordering subquery only joins the direct target, never the
-* junction table. (Relation *filters* do support `.through()` — this guard is orderBy-only.)
-*/
-const isFilterableRelation = (relation) => !relation.through;
-//#endregion
 //#region src/util/builders/common/order-by.ts
 /**
 * Column name / direction / nulls triples from an `orderBy` argument, highest priority
@@ -2300,7 +2602,8 @@ const extendRelationOrderChain = (parentTable, relationName, relEntry, ctx, chai
 	ctx.aliases ??= { n: 0 };
 	const aliasedTarget = aliasedTable(targetTable, `dgql_ord_${ctx.aliases.n++}`);
 	const joinCondition = buildRelationJoinCondition(parentTable, relation, aliasedTarget, relationName);
-	const relationWhere = relation.where ? relationsFilterToSQL(relation.isReversed ? parentTable : aliasedTarget, relation.where) : void 0;
+	const ownWhere = relationOwnWhere(relation);
+	const relationWhere = ownWhere ? relationsFilterToSQL(isRelationFilterReversed(relation) ? parentTable : aliasedTarget, ownWhere) : void 0;
 	return {
 		fromParts: [...chain?.fromParts ?? [], getTableAsAliasSQL(aliasedTarget)],
 		conditions: [
@@ -2317,15 +2620,17 @@ const extendRelationOrderChain = (parentTable, relationName, relEntry, ctx, chai
 *
 * A ladder rather than a dialect array function (`array_position` on Postgres, `FIELD()` on
 * MySQL, neither on SQLite) because it is the one form all three share, and because every
-* list value stays a bound parameter. The branch indices are library-generated integers, so
-* they are written into the SQL text — a bound parameter there would leave Postgres unable
-* to infer the CASE result type. Values outside the list sort after every listed one.
+* list value stays a bound parameter — encoded by the column, as `eq` would, so a value whose
+* driver form differs from its JS one (a SQLite integer timestamp's `Date`) is bound as stored.
+* The branch indices are library-generated integers, so they are written into the SQL text — a
+* bound parameter there would leave Postgres unable to infer the CASE result type. Values
+* outside the list sort after every listed one.
 */
 const filterOrderExpression = (column, columnName, whereArgs) => {
 	const values = whereArgs?.[columnName]?.inArray;
 	if (!Array.isArray(values)) throw drizzleError(`ORDER BY ${columnName}: 'matchFilterOrder' needs an 'inArray' filter on the same column in this query's 'where'`, { code: "DRIZZLE_INVALID_ORDER_BY" });
 	if (!values.length) return sql`0`;
-	const branches = values.map((value, index) => sql`when ${column} = ${remapFromGraphQLCore(value, column, columnName)} then ${sql.raw(String(index))}`);
+	const branches = values.map((value, index) => sql`when ${column} = ${sql.param(remapFromGraphQLCore(value, column, columnName), column)} then ${sql.raw(String(index))}`);
 	return sql`case ${sql.join(branches, sql` `)} else ${sql.raw(String(values.length))} end`;
 };
 /**
@@ -2689,6 +2994,11 @@ const getUniqueColumnSets = (table, getTableConfig) => {
 //#endregion
 //#region src/util/builders/common/distinct.ts
 /**
+* Alias the parent key comes back under when the pass runs through a junction table. See
+* `selectDistinctKeys`' `junction` parameter.
+*/
+const DISTINCT_PARENT = "__dgql_distinct_parent";
+/**
 * Keeps the first row of each distinct combination of the requested columns, following the
 * query's own ordering, then applies `limit`/`offset` to what survives — and returns the
 * surviving rows' primary key values in that order.
@@ -2701,9 +3011,14 @@ const getUniqueColumnSets = (table, getTableConfig) => {
 * `partitionBy` prepends extra columns to the window's partition. A to-many relation field
 * uses it to pass the foreign key, which makes the pass distinct *within each parent* rather
 * than across the whole batch — the same meaning `distinct` has on a root list.
+*
+* `junction` is for a many-to-many relation: the target is joined to the junction `on` the
+* given condition, and each returned key also carries the parent it was kept for, under
+* {@link DISTINCT_PARENT}. A target row linked to several parents can be kept for one and
+* dropped for another, so a key alone cannot narrow such a batch.
 */
 const selectDistinctKeys = async (params) => {
-	const { db, table, tableName, distinct, pkNames, where, orderBy, limit, offset, partitionBy } = params;
+	const { db, table, tableName, distinct, pkNames, where, orderBy, limit, offset, partitionBy, junction } = params;
 	const cols = getColumns(table);
 	if (!pkNames.length) throw drizzleError(`Table ${tableName} has no primary key, so 'distinct' cannot be applied to it.`, { code: "DRIZZLE_INVALID_DISTINCT" });
 	const requestedCols = distinct.map((name) => cols[name]).filter(Boolean);
@@ -2712,12 +3027,17 @@ const selectDistinctKeys = async (params) => {
 	const orderEntries = orderBy ? orderByEntries(orderBy) : [];
 	const windowOrder = [...orderEntries.flatMap(([column, direction, nulls]) => orderExpressions(cols[column], direction, nulls, cols[column])), ...primaryKeyOrderExprs(table, pkNames)];
 	const rowNumber = sql`row_number() over (partition by ${sql.join(partitionCols, sql`, `)} order by ${sql.join(windowOrder, sql`, `)})`.as(DISTINCT_RN);
-	const sub = db.select({
+	const selected = db.select({
 		...cols,
+		...junction ? { [DISTINCT_PARENT]: junction.parentKey } : {},
 		[DISTINCT_RN]: rowNumber
-	}).from(table).where(where).as("__dgql_distinct");
+	}).from(table);
+	const sub = (junction ? selected.innerJoin(junction.table, junction.on) : selected).where(where).as("__dgql_distinct");
 	const outerOrder = [...orderEntries.flatMap(([column, direction, nulls]) => orderExpressions(sub[column], direction, nulls, cols[column])), ...pkNames.filter((name) => sub[name]).map((name) => asc(sub[name]))];
-	let query = db.select(Object.fromEntries(pkNames.map((name) => [name, sub[name]]))).from(sub).where(eq(sub[DISTINCT_RN], 1)).orderBy(...outerOrder);
+	let query = db.select({
+		...Object.fromEntries(pkNames.map((name) => [name, sub[name]])),
+		...junction ? { [DISTINCT_PARENT]: sub[DISTINCT_PARENT] } : {}
+	}).from(sub).where(eq(sub[DISTINCT_RN], 1)).orderBy(...outerOrder);
 	if (offset) query = query.offset(offset);
 	if (limit != null) query = query.limit(limit);
 	return await query;
@@ -3291,6 +3611,26 @@ const remapUpdateInput = (values, table, tableName) => {
 	} : remapped;
 };
 //#endregion
+//#region src/util/builders/common/rqb-config.ts
+/**
+* A copy of a relational query config with every key whose value is `undefined` left out.
+*
+* drizzle-orm rc.5 snapshots test `"where" in params` rather than its value, and throw
+* `Unexpected 'undefined' in filter value` for `{ where: undefined }`; rc.4 read the value and
+* treated both the same. The library builds its configs with conditional keys
+* (`where: cond ? … : undefined`), so every config goes through here before it reaches drizzle.
+* Only `where` is checked that way today, but leaving out every undefined key costs nothing
+* and keeps the next key that gets the same treatment from breaking queries.
+*
+* Shallow on purpose: nested `with:` entries are built (and passed through here) one level at
+* a time, and the values of the other keys are drizzle's own (column maps, callbacks, RAW).
+*/
+const omitUndefinedKeys = (config) => {
+	const out = {};
+	for (const [key, value] of Object.entries(config)) if (value !== void 0) out[key] = value;
+	return out;
+};
+//#endregion
 //#region src/util/builders/common/selected-columns.ts
 const rqbCrashTypes = [
 	"SQLiteBigInt",
@@ -3419,7 +3759,7 @@ const extractRelationsParams = (relationMap, tables, tableName, info, typeName,
 		thisRecord.offset = offset;
 		thisRecord.limit = limit;
 		thisRecord.with = extractRelationsParams(relationMap, tables, targetTableName, field, relTypeName, options);
-		args[relName] = thisRecord;
+		args[relName] = omitUndefinedKeys(thisRecord);
 	}
 	return args;
 };
@@ -3496,12 +3836,12 @@ const runRelationalSelect = async (opts) => {
 		}) : void 0
 	};
 	if (single) {
-		const result = await queryBase.findFirst(params);
+		const result = await queryBase.findFirst(omitUndefinedKeys(params));
 		return result ? remapToGraphQLSingleOutput(result, tableName, table, relationMap) : void 0;
 	}
 	if (cursorEntries && cursorSelected) for (const [column] of cursorEntries) params.columns[column] = true;
 	params.limit = distinctKeys ? void 0 : opts.limit;
-	const result = await queryBase.findMany(params);
+	const result = await queryBase.findMany(omitUndefinedKeys(params));
 	if (cursorEntries && cursorSelected) attachRowCursors(result, cursorEntries);
 	return remapToGraphQLArrayOutput(result, tableName, table, relationMap);
 };
@@ -4318,16 +4658,17 @@ const identifyRows = (field, args) => {
 * Window functions require PostgreSQL, MySQL >= 8.0, or SQLite >= 3.25.
 * Returns raw rows (NOT remapped); the caller groups + remaps them.
 */
-const batchedPaginatedRelationQuery = async (db, targetTable, foreignCol, whereCondition, orderByArg, limit, offset, pkNames, columns, orderCtx, whereArgs) => {
+const batchedPaginatedRelationQuery = async (db, targetTable, foreignCol, whereCondition, orderByArg, limit, offset, pkNames, columns, orderCtx, whereArgs, junction) => {
 	const cols = columns ?? getColumns(targetTable);
 	const orderExprs = [...orderByArg ? extractOrderBy(targetTable, orderByArg, orderCtx, whereArgs) : [], ...primaryKeyOrderExprs(targetTable, pkNames)];
 	const orderClause = orderExprs.length ? sql` order by ${sql.join(orderExprs, sql`, `)}` : sql``;
 	const RN = "__drizzle_graphql_rn";
-	const rowNumber = sql`row_number() over (partition by ${foreignCol}${orderClause})`.as(RN);
-	const sub = db.select({
+	const partitionCol = junction ? junction.sourceCol : foreignCol;
+	const rowNumber = sql`row_number() over (partition by ${partitionCol}${orderClause})`.as(RN);
+	const sub = withJunction(db.select({
 		...cols,
 		[RN]: rowNumber
-	}).from(targetTable).where(whereCondition).as("__paginated");
+	}).from(targetTable), junction, foreignCol).where(whereCondition).as("__paginated");
 	const lower = offset ?? 0;
 	const windowConds = [gt(sub[RN], lower)];
 	if (limit != null) windowConds.push(lte(sub[RN], lower + limit));
@@ -4336,6 +4677,14 @@ const batchedPaginatedRelationQuery = async (db, targetTable, foreignCol, whereC
 	return rows;
 };
 /**
+* Alias the parent key is selected under when a relation goes through a junction table. The
+* key lives on the junction, not the target, so it has to be selected explicitly to group the
+* rows by parent — and a target row linked to several parents comes back once per parent.
+*/
+const PARENT_KEY = "__drizzle_graphql_parent";
+/** `from(target)`, joined to the junction table when the relation has one. */
+const withJunction = (query, junction, foreignCol) => junction ? query.innerJoin(junction.table, eq(junction.targetCol, foreignCol)) : query;
+/**
 * Creates a RelationResolverFactory that generates field-level resolvers for each relation.
 * Each resolver:
 *   1. Returns pre-fetched data if the parent resolver already included it (eager path, zero cost).
@@ -4357,6 +4706,10 @@ const createRelationResolverFactory = (db, tables, nullOrdering, filterCtx, limi
 	const joinCols = extractRelationJoinColumns(relEntry, parentTable, targetTable);
 	if (!joinCols) return;
 	const { localColPropName, foreignCol, foreignColPropName } = joinCols;
+	const junction = extractJunctionColumns(relEntry);
+	const groupCol = junction ? junction.sourceCol : foreignCol;
+	const groupKey = junction ? PARENT_KEY : foreignColPropName;
+	const ownCondition = relationOwnCondition(relEntry, parentTable, targetTable, getColumns(parentTable)[localColPropName], groupCol);
 	const defaultDeleted = relationDeletedDefault(policies?.softDelete, targetTableName, isOne && relEntry.relation?.optional === false);
 	const limitPolicy = isOne ? void 0 : limits?.(targetTableName);
 	const targetPkNames = relEntry.targetPkNames ?? [];
@@ -4434,11 +4787,12 @@ const createRelationResolverFactory = (db, tables, nullOrdering, filterCtx, limi
 				loaderKey: `${tableName}::${relationName}::${argsKey}`
 			};
 		});
+		if (junction === null) throw drizzleError(`Relation '${tableName}.${relationName}' goes through a junction with a composite key, which can only be loaded together with its parent. Leave it to eager loading (eagerLoadRelations).`, { code: "DRIZZLE_UNSUPPORTED_RELATION" });
 		return getOrCreateLoader(context, loaderKey, async (parentIds) => {
 			const executor = resolveExecutor(db, context);
 			const uniqueIds = [...new Set(parentIds)];
 			const scope = resolveScope(policies, context, filterCtx);
-			let whereCondition = withScope(scope, targetTableName, targetTable, and(inArray(foreignCol, uniqueIds), whereArg ? extractFilters(targetTable, targetTableName, whereArg, relationFilterCtx(filterCtx, targetTableName)) : void 0, cursorValues ? buildCursorCondition(targetTable, cursorEntries, cursorValues, nullOrdering) : void 0), deleted ?? defaultDeleted);
+			let whereCondition = withScope(scope, targetTableName, targetTable, and(inArray(groupCol, uniqueIds), ownCondition, whereArg ? extractFilters(targetTable, targetTableName, whereArg, relationFilterCtx(filterCtx, targetTableName)) : void 0, cursorValues ? buildCursorCondition(targetTable, cursorEntries, cursorValues, nullOrdering) : void 0), deleted ?? defaultDeleted);
 			if (distinct) {
 				const keys = await selectDistinctKeys({
 					db: executor,
@@ -4448,27 +4802,41 @@ const createRelationResolverFactory = (db, tables, nullOrdering, filterCtx, limi
 					pkNames: targetPkNames,
 					where: whereCondition,
 					orderBy: orderByArg,
-					partitionBy: [foreignCol]
+					partitionBy: [groupCol],
+					junction: junction ? {
+						table: junction.table,
+						on: eq(junction.targetCol, foreignCol),
+						parentKey: groupCol
+					} : void 0
 				});
 				if (!keys.length) return parentIds.map(() => isOne ? null : []);
-				whereCondition = and(whereCondition, primaryKeyRestriction(targetTable, targetPkNames, keys));
+				whereCondition = and(whereCondition, junction ? or(...keys.map((key) => and(eq(groupCol, key[DISTINCT_PARENT]), primaryKeyRestriction(targetTable, targetPkNames, [key])))) : primaryKeyRestriction(targetTable, targetPkNames, keys));
 			}
+			const selection = junction ? {
+				...columns ?? getColumns(targetTable),
+				[PARENT_KEY]: groupCol
+			} : columns;
 			let rows;
-			if (limit != null || offset != null) rows = await batchedPaginatedRelationQuery(executor, targetTable, foreignCol, whereCondition, orderByArg, limit ?? null, offset ?? null, targetPkNames, columns, relationFilterCtx(filterCtx, targetTableName), whereArg);
+			if (limit != null || offset != null) rows = await batchedPaginatedRelationQuery(executor, targetTable, foreignCol, whereCondition, orderByArg, limit ?? null, offset ?? null, targetPkNames, selection, relationFilterCtx(filterCtx, targetTableName), whereArg, junction);
 			else {
-				let q = (columns ? executor.select(columns) : executor.select()).from(targetTable).where(whereCondition);
+				let q = withJunction((selection ? executor.select(selection) : executor.select()).from(targetTable), junction, foreignCol).where(whereCondition);
 				const orderExprs = cursorEntries ? cursorOrderExprs(targetTable, cursorEntries) : orderByArg ? extractOrderBy(targetTable, orderByArg, relationFilterCtx(filterCtx, targetTableName), whereArg) : [];
 				if (orderExprs.length) q = q.orderBy(...orderExprs);
 				rows = await q;
 			}
 			if (cursorEntries) attachRowCursors(rows, cursorEntries);
+			const keyOf = (row) => {
+				const key = String(row[groupKey]);
+				if (junction) delete row[PARENT_KEY];
+				return key;
+			};
 			if (isOne) {
-				const byKey = new Map(rows.map((row) => [String(row[foreignColPropName]), row]));
+				const byKey = new Map(rows.map((row) => [keyOf(row), row]));
 				remapToGraphQLArrayOutput(rows, targetTableName, targetTable);
 				return parentIds.map((id) => byKey.get(String(id)) ?? null);
 			}
 			const grouped = new Map(uniqueIds.map((id) => [String(id), []]));
-			for (const row of rows) grouped.get(String(row[foreignColPropName]))?.push(row);
+			for (const row of rows) grouped.get(keyOf(row))?.push(row);
 			remapToGraphQLArrayOutput(rows, targetTableName, targetTable);
 			return parentIds.map((id) => grouped.get(String(id)) ?? []);
 		}).load(localValue);
@@ -4803,7 +5171,7 @@ const generateSelectFields = (tables, tableName, relationMap, fromTableName, fro
 		});
 		const shell = new GraphQLObjectType({
 			name: typeName,
-			description: cacheCtx.docs.describeTable?.(tableName),
+			description: cacheCtx.docs.describeTable?.(tableName, table),
 			fields: () => ({
 				...tableFields,
 				...container.fields
@@ -4837,7 +5205,7 @@ const generateSelectFields = (tables, tableName, relationMap, fromTableName, fro
 						defaultName: resolveTypeName(targetTableName, typeNameMapper),
 						table: targetTableName
 					}),
-					description: cacheCtx.docs.describeTable?.(targetTableName),
+					description: cacheCtx.docs.describeTable?.(targetTableName, targetTable),
 					fields: () => ({
 						...targetTableFields,
 						...capturedTargetContainer.fields
@@ -4988,7 +5356,7 @@ const generateTableTypes = (tableName, tables, relationMap, withReturning, relat
 			defaultName: resolveTypeName(tableName, typeNameMapper),
 			table: tableName
 		}),
-		description: cacheCtx.docs.describeTable?.(tableName),
+		description: cacheCtx.docs.describeTable?.(tableName, tables[tableName]),
 		fields: {
 			...tableFields,
 			...relationFields
@@ -5539,14 +5907,26 @@ const GROUP_KEY = "__dgql_group_key";
 * for every other aggregate.
 */
 const createRelationAggregateFactory = (db, tables, cacheCtx, typeNameMapper, filterCtx, policies) => {
+	const warned = /* @__PURE__ */ new Set();
 	return ({ tableName, relationName, relEntry }) => {
 		const parentTable = tables[tableName];
 		const targetTableName = relEntry.targetTableName;
 		const targetTable = tables[targetTableName];
 		if (!parentTable || !targetTable) return;
 		const joinCols = extractRelationJoinColumns(relEntry, parentTable, targetTable);
-		if (!joinCols) return;
+		if (!joinCols) {
+			const key = `${tableName}.${relationName}`;
+			if (!warned.has(key)) {
+				warned.add(key);
+				warnUnresolvedJoin(relEntry, tableName, relationName, `its '${relationName}Aggregate' field`);
+			}
+			return;
+		}
 		const { localColPropName, foreignCol } = joinCols;
+		const junction = extractJunctionColumns(relEntry);
+		if (junction === null) return;
+		const groupCol = junction ? junction.sourceCol : foreignCol;
+		const ownCondition = relationOwnCondition(relEntry, parentTable, targetTable, getColumns(parentTable)[localColPropName], groupCol);
 		const defaultDeleted = relationDeletedDefault(policies?.softDelete, targetTableName, false);
 		const targetTypeName = resolveTypeName(targetTableName, typeNameMapper);
 		const type = generateAggregateTypes(targetTable, targetTableName, targetTypeName, cacheCtx);
@@ -5577,11 +5957,12 @@ const createRelationAggregateFactory = (db, tables, cacheCtx, typeNameMapper, fi
 				const loader = getOrCreateLoader(context, loaderKey, async (parentIds) => {
 					const executor = resolveExecutor(db, context);
 					const uniqueIds = [...new Set(parentIds)];
-					const whereCondition = withScope(resolveScope(policies, context, filterCtx), targetTableName, targetTable, and(inArray(foreignCol, uniqueIds), whereArg ? extractFilters(targetTable, targetTableName, whereArg, relationFilterCtx(filterCtx, targetTableName)) : void 0), deleted ?? defaultDeleted);
-					const rows = await executor.select({
-						[GROUP_KEY]: foreignCol,
+					const whereCondition = withScope(resolveScope(policies, context, filterCtx), targetTableName, targetTable, and(inArray(groupCol, uniqueIds), ownCondition, whereArg ? extractFilters(targetTable, targetTableName, whereArg, relationFilterCtx(filterCtx, targetTableName)) : void 0), deleted ?? defaultDeleted);
+					const selected = executor.select({
+						[GROUP_KEY]: groupCol,
 						...request.selection
-					}).from(targetTable).where(whereCondition).groupBy(foreignCol);
+					}).from(targetTable);
+					const rows = await (junction ? selected.innerJoin(junction.table, eq(junction.targetCol, foreignCol)) : selected).where(whereCondition).groupBy(groupCol);
 					const byKey = new Map(rows.map((row) => [row[GROUP_KEY], row]));
 					return parentIds.map((id) => byKey.get(id) ?? {});
 				});
@@ -5849,12 +6230,6 @@ const propNameOf = (table, column) => {
 	for (const [propName, candidate] of Object.entries(getColumns(table))) if (candidate === column) return propName;
 };
 /**
-* The junction column one entry of a relation's `through` config points at. Drizzle wraps it
-* in a descriptor while the relation is being defined; the raw column is accepted too, so a
-* change of shape there degrades to skipping the relation rather than mis-planning it.
-*/
-const throughColumn = (entry) => entry && is(entry, Column) ? entry : entry?._?.column;
-/**
 * A `.through()` relation's plan: the junction table plus the two columns it joins on.
 *
 * Nothing about the parent or the target row changes when a many-to-many link is made or
@@ -5865,21 +6240,27 @@ const throughColumn = (entry) => entry && is(entry, Column) ? entry : entry?._?.
 * row" guarantee lives in the junction's constraints rather than in the relation; a relation
 * joining on more than one column per side; and a junction carrying a further NOT NULL column
 * with no default, which no `connect` operand could supply a value for.
+*
+* `onUnresolved` is called when the relation's columns are of a supported shape but cannot be
+* matched to the three tables — a drizzle-orm mismatch rather than an unsupported relation.
 */
-const buildThroughPlan = (relationName, relation, table, targetTableName, targetTable, tableNameOf) => {
+const buildThroughPlan = (relationName, relation, table, targetTableName, targetTable, tableNameOf, onUnresolved) => {
 	if (is(relation, One)) return;
 	const junction = relation.throughTable;
 	const sourceEntries = relation.through?.source;
 	const targetEntries = relation.through?.target;
 	if (!junction || sourceEntries?.length !== 1 || targetEntries?.length !== 1) return;
 	if (relation.sourceColumns?.length !== 1 || relation.targetColumns?.length !== 1) return;
-	const localCol = relation.sourceColumns[0];
-	const foreignCol = relation.targetColumns[0];
+	const localCol = unwrapRelationColumn(relation.sourceColumns[0]);
+	const foreignCol = unwrapRelationColumn(relation.targetColumns[0]);
 	const localColPropName = propNameOf(table, localCol);
 	const foreignColPropName = propNameOf(targetTable, foreignCol);
-	const sourceColPropName = propNameOf(junction, throughColumn(sourceEntries[0]));
-	const targetColPropName = propNameOf(junction, throughColumn(targetEntries[0]));
-	if (!localColPropName || !foreignColPropName || !sourceColPropName || !targetColPropName) return;
+	const sourceColPropName = propNameOf(junction, unwrapRelationColumn(sourceEntries[0]));
+	const targetColPropName = propNameOf(junction, unwrapRelationColumn(targetEntries[0]));
+	if (!localCol || !foreignCol || !localColPropName || !foreignColPropName || !sourceColPropName || !targetColPropName) {
+		onUnresolved();
+		return;
+	}
 	const junctionColumns = getColumns(junction);
 	const sourceCol = junctionColumns[sourceColPropName];
 	const targetCol = junctionColumns[targetColPropName];
@@ -5949,13 +6330,17 @@ const buildNestedWritePlans = (tables, relationMap, resolveUniqueSets, resolvePr
 			const targetTableName = relEntry.targetTableName;
 			const targetTable = tables[targetTableName];
 			if (!targetTable) continue;
+			const omitted = `the '${relationName}' field of its nested-write create and update inputs`;
 			if (relation.through) {
-				const throughPlan = buildThroughPlan(relationName, relation, table, targetTableName, targetTable, tableNameOf);
+				const throughPlan = buildThroughPlan(relationName, relation, table, targetTableName, targetTable, tableNameOf, () => warnUnresolvedJoin(relEntry, tableName, relationName, omitted));
 				if (throughPlan) tablePlans[relationName] = throughPlan;
 				continue;
 			}
 			const joinColumns = extractJoinColumns(relEntry, table, targetTable);
-			if (!joinColumns) continue;
+			if (!joinColumns) {
+				warnUnresolvedJoin(relEntry, tableName, relationName, omitted);
+				continue;
+			}
 			const { localColPropName, foreignCol, foreignColPropName } = joinColumns;
 			const localCol = getColumns(table)[localColPropName];
 			if (!localCol) continue;