@vantreeseba/drizzle-graphql 15.0.0 → 15.1.1

package/dist/index.d.cts

@@ -449,7 +449,7 @@ type DrizzleErrorCode =
 'DRIZZLE_INVALID_DISTINCT' |
 /** An `onConflict` named a target or update column the upsert cannot use. */
 'DRIZZLE_INVALID_ON_CONFLICT' |
-/** A written value could not be converted to what its column stores. */
+/** A written value could not be converted to what its column stores, or a `limit` / `offset` was negative. */
 'DRIZZLE_INVALID_INPUT_VALUE' |
 /** An update's `set` gave a column that cannot hold null an explicit null. */
 'DRIZZLE_NOT_NULL' |
@@ -458,7 +458,9 @@ type DrizzleErrorCode =
 /** A stored value could not be represented by the scalar that transports it. */
 'DRIZZLE_UNREPRESENTABLE_VALUE' |
 /** The request's shared mutation transaction was rolled back, so this field never ran. */
-'DRIZZLE_TRANSACTION_ABORTED';
+'DRIZZLE_TRANSACTION_ABORTED' |
+/** A relation was read on a path it cannot be loaded through (see the message). */
+'DRIZZLE_UNSUPPORTED_RELATION';
 /**
  * What an error was about, published as `extensions.drizzle` beside the code — the runtime
  * half of the `extensions.drizzle` markers a generated field carries.
@@ -607,8 +609,11 @@ type ColumnDescriber = (column: Column, info: ColumnDocInfo) => string | undefin
  * `BuildSchemaConfig.deprecateColumn`.
  */
 type ColumnDeprecator = (column: Column, info: ColumnDocInfo) => string | undefined;
-/** Supplies the GraphQL `description` for a table's object type. See `BuildSchemaConfig.describeTable`. */
-type TableDescriber = (tableName: string) => string | undefined;
+/**
+ * Supplies the GraphQL `description` for a table's object type. Receives the Drizzle table
+ * itself as well as its schema key. See `BuildSchemaConfig.describeTable`.
+ */
+type TableDescriber = (tableName: string, table: Table) => string | undefined;
 /**
  * Supplies the GraphQL `description` for a relation field. See
  * `BuildSchemaConfig.describeRelation`.
@@ -2444,6 +2449,17 @@ type BuildSchemaConfig = {
    * ```ts
    * buildSchema(db, { describeTable: (tableName) => tableDocs[tableName] });
    * ```
+   *
+   * The second argument is the Drizzle table itself, so documentation attached to the table
+   * where it is declared can be read straight off it:
+   *
+   * ```ts
+   * const tableDocs = new WeakMap<object, string>();
+   * export const Users = pgTable('users', { ... });
+   * tableDocs.set(Users, 'A person who can sign in.');
+   *
+   * buildSchema(db, { describeTable: (_tableName, table) => tableDocs.get(table) });
+   * ```
    */
   describeTable?: TableDescriber;
   /**

package/dist/index.d.ts

@@ -449,7 +449,7 @@ type DrizzleErrorCode =
 'DRIZZLE_INVALID_DISTINCT' |
 /** An `onConflict` named a target or update column the upsert cannot use. */
 'DRIZZLE_INVALID_ON_CONFLICT' |
-/** A written value could not be converted to what its column stores. */
+/** A written value could not be converted to what its column stores, or a `limit` / `offset` was negative. */
 'DRIZZLE_INVALID_INPUT_VALUE' |
 /** An update's `set` gave a column that cannot hold null an explicit null. */
 'DRIZZLE_NOT_NULL' |
@@ -458,7 +458,9 @@ type DrizzleErrorCode =
 /** A stored value could not be represented by the scalar that transports it. */
 'DRIZZLE_UNREPRESENTABLE_VALUE' |
 /** The request's shared mutation transaction was rolled back, so this field never ran. */
-'DRIZZLE_TRANSACTION_ABORTED';
+'DRIZZLE_TRANSACTION_ABORTED' |
+/** A relation was read on a path it cannot be loaded through (see the message). */
+'DRIZZLE_UNSUPPORTED_RELATION';
 /**
  * What an error was about, published as `extensions.drizzle` beside the code — the runtime
  * half of the `extensions.drizzle` markers a generated field carries.
@@ -607,8 +609,11 @@ type ColumnDescriber = (column: Column, info: ColumnDocInfo) => string | undefin
  * `BuildSchemaConfig.deprecateColumn`.
  */
 type ColumnDeprecator = (column: Column, info: ColumnDocInfo) => string | undefined;
-/** Supplies the GraphQL `description` for a table's object type. See `BuildSchemaConfig.describeTable`. */
-type TableDescriber = (tableName: string) => string | undefined;
+/**
+ * Supplies the GraphQL `description` for a table's object type. Receives the Drizzle table
+ * itself as well as its schema key. See `BuildSchemaConfig.describeTable`.
+ */
+type TableDescriber = (tableName: string, table: Table) => string | undefined;
 /**
  * Supplies the GraphQL `description` for a relation field. See
  * `BuildSchemaConfig.describeRelation`.
@@ -2444,6 +2449,17 @@ type BuildSchemaConfig = {
    * ```ts
    * buildSchema(db, { describeTable: (tableName) => tableDocs[tableName] });
    * ```
+   *
+   * The second argument is the Drizzle table itself, so documentation attached to the table
+   * where it is declared can be read straight off it:
+   *
+   * ```ts
+   * const tableDocs = new WeakMap<object, string>();
+   * export const Users = pgTable('users', { ... });
+   * tableDocs.set(Users, 'A person who can sign in.');
+   *
+   * buildSchema(db, { describeTable: (_tableName, table) => tableDocs.get(table) });
+   * ```
    */
   describeTable?: TableDescriber;
   /**

package/dist/index.js

@@ -1592,13 +1592,20 @@ const nullableOps = {
 	isNull,
 	isNotNull
 };
+/** Operators whose operand is an on/off flag rather than a value: `false` adds no condition. */
+const FLAG_OPERATORS = /* @__PURE__ */ new Set([
+	"isNull",
+	"isNotNull",
+	"isEmpty"
+]);
 const extractFiltersColumn = (column, columnName, operators) => {
 	const { OR, AND, NOT, insensitive, ...restOperators } = operators;
 	const foldCase = insensitive === true;
 	const entries = Object.entries(restOperators);
 	const variants = [];
 	for (const [operatorName, operatorValue] of entries) {
-		if (operatorValue === null || operatorValue === false) continue;
+		if (operatorValue === null || operatorValue === void 0) continue;
+		if (operatorValue === false && FLAG_OPERATORS.has(operatorName)) continue;
 		if (operatorName in singleValueOps) {
 			const singleValue = remapFromGraphQLCore(operatorValue, column, columnName);
 			variants.push(foldCase ? lowerComparison(column, operatorName, singleValue) : singleValueOps[operatorName](column, singleValue));
@@ -1789,6 +1796,48 @@ const extractRelationJoinColumns = (relEntry, parentTable, targetTable) => {
 	};
 };
 /**
+* 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.)
@@ -2690,6 +2739,45 @@ const cursorOrderExprs = (table, entries) => {
 	return entries.flatMap(([column, direction, nulls]) => orderExpressions(cols[column], direction, nulls ?? void 0, cols[column]));
 };
 /**
+* Property a row carries an ordering column's full-precision text under, when the column holds
+* more than a JS Date can. Namespaced like {@link ROW_CURSOR_PROP}, and removed from the row
+* once its cursor is encoded.
+*/
+const preciseTextProp = (column) => `__drizzle_graphql_cursor_text_${column}`;
+/**
+* Whether a column reads into a JS Date (milliseconds) while the database keeps finer
+* fractional seconds: a PostgreSQL `timestamp` / `timestamptz` in `mode: 'date'` (precision 6
+* unless it says otherwise) or a MySQL `datetime` / `timestamp` in `mode: 'date'` with
+* `fsp` above 3. String-mode columns already arrive as the database's own text, and `time` is
+* always a string, so neither loses anything.
+*/
+const outgrowsJsDate = (column) => {
+	if (is(column, PgTimestamp)) return column.precision === void 0 || column.precision > 3;
+	if (is(column, MySqlDateTime) || is(column, MySqlTimestamp)) return (column.fsp ?? 0) > 3;
+	return false;
+};
+/**
+* Extra SQL expressions a cursor-computing query selects alongside the row: for each ordering
+* column whose values a JS Date would truncate, the value as the database's own text. The
+* cursor then encodes that text rather than the Date, and `after` compares the column against
+* it — so two rows a microsecond apart stay distinct positions. `table` may be the aliased RQB
+* proxy. Empty when no ordering column needs it.
+*/
+const cursorPreciseExtras = (table, entries) => {
+	const cols = getColumns(table);
+	const extras = {};
+	for (const [name] of entries) {
+		const column = cols[name];
+		if (column && outgrowsJsDate(column)) extras[preciseTextProp(name)] = is(column, PgTimestamp) ? sql`${column}::text` : sql`cast(${column} as char)`;
+	}
+	return extras;
+};
+/**
+* {@link cursorPreciseExtras} aliased under their property names, for a `select({...})` that
+* may be wrapped in a subquery (where a bare SQL expression would have no name).
+*/
+const cursorPreciseSelection = (table, entries) => Object.fromEntries(Object.entries(cursorPreciseExtras(table, entries)).map(([prop, expression]) => [prop, expression.as(prop)]));
+/**
 * Serializes one ordering-tuple value into a JSON-safe shape. Dates and bigints don't survive
 * JSON.stringify losslessly (bigint throws, Date turns into an untagged string), so they are
 * tagged; decimals already arrive from the driver as strings, which are lossless as-is.
@@ -2724,7 +2812,11 @@ const cursorEncoder = (entries) => {
 	const spec = JSON.stringify(entries);
 	const columns = entries.map(([column]) => column);
 	return (row) => {
-		const values = JSON.stringify(columns.map((column) => encodeCursorValue(row[column] ?? null)));
+		const values = JSON.stringify(columns.map((column) => {
+			const value = row[column] ?? null;
+			const precise = row[preciseTextProp(column)];
+			return value !== null && typeof precise === "string" ? precise : encodeCursorValue(value);
+		}));
 		return Buffer.from(`{"o":${spec},"v":${values}}`, "utf8").toString("base64url");
 	};
 };
@@ -2817,7 +2909,11 @@ const selectsCursorField = (info, table) => {
 */
 const attachRowCursors = (rows, entries) => {
 	const encode = cursorEncoder(entries);
-	for (const row of rows) row[ROW_CURSOR_PROP] = encode(row);
+	const preciseProps = entries.map(([column]) => preciseTextProp(column));
+	for (const row of rows) {
+		row[ROW_CURSOR_PROP] = encode(row);
+		for (const prop of preciseProps) delete row[prop];
+	}
 };
 /** Resolver for the `cursor` meta field: reads the value a list resolver attached, if any. */
 const rowCursorResolver = (source) => source?.[ROW_CURSOR_PROP] ?? null;
@@ -2952,6 +3048,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.
@@ -2964,9 +3065,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);
@@ -2975,12 +3081,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;
@@ -3160,6 +3271,21 @@ const withDefaultOrderBy = (args, tableName, defaults) => {
 	} : args;
 };
 /**
+* Rejects a negative `limit` or `offset`. Neither is a page size or a position, and the
+* dialects disagree on what one means: SQLite reads `LIMIT -1` as "no limit" — which would walk
+* straight past `maxLimit` — while PostgreSQL and MySQL fail with a raw database error. Applied
+* whether or not the table has a limit policy.
+*/
+const assertPagingNotNegative = (paging, errorCtx) => {
+	for (const name of ["limit", "offset"]) {
+		const value = paging[name];
+		if (value != null && value < 0) throw drizzleError(`'${name}' must not be negative, got ${value}.`, {
+			code: "DRIZZLE_INVALID_INPUT_VALUE",
+			...errorCtx
+		});
+	}
+};
+/**
 * The `limit` a query actually runs with, given the policy for the table it reads.
 *
 * A request that passes no `limit` falls back to `defaultLimit`, or to `maxLimit` when only
@@ -3171,6 +3297,7 @@ const withDefaultOrderBy = (args, tableName, defaults) => {
 * fail a client's query over.
 */
 const applyLimitPolicy = (limit, policy, errorCtx) => {
+	assertPagingNotNegative({ limit }, errorCtx);
 	if (!policy) return limit ?? void 0;
 	const { defaultLimit, maxLimit, clampToMax } = policy;
 	if (limit == null) {
@@ -3688,6 +3815,11 @@ const extractRelationsParams = (relationMap, tables, tableName, info, typeName,
 		thisRecord.columns = columns;
 		const relationArgs = is(relEntry.relation, One) ? field.args : withDefaultOrderBy(field.args ?? {}, targetTableName, defaultOrderBy);
 		const offset = relationArgs?.offset ?? void 0;
+		assertPagingNotNegative({ offset }, {
+			table: targetTableName,
+			operation: "relation",
+			relation: relName
+		});
 		const limit = is(relEntry.relation, One) ? relationArgs?.limit ?? void 0 : applyLimitPolicy(relationArgs?.limit, limits?.(targetTableName), {
 			table: targetTableName,
 			operation: "relation",
@@ -3731,6 +3863,10 @@ const pruneNonEagerRelations = (relationMap, shouldEagerLoad) => {
 const runRelationalSelect = async (opts) => {
 	const { queryBase, tables, tableName, table, relationMap, typeName, typeNameMapper, parsedInfo, offset, orderBy, where, single, filterCtx, pkNames, after, scope, deleted } = opts;
 	const distinct = opts.distinct?.length ? opts.distinct : void 0;
+	assertPagingNotNegative({
+		limit: opts.limit,
+		offset
+	});
 	const cursorSelected = !single && isCursorFieldSelected(parsedInfo.fieldsByTypeName[typeName], table);
 	let cursorEntries;
 	if (!single && (after != null || cursorSelected)) {
@@ -3782,7 +3918,11 @@ const runRelationalSelect = async (opts) => {
 		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;
+	if (cursorEntries && cursorSelected) {
+		for (const [column] of cursorEntries) params.columns[column] = true;
+		const preciseProps = Object.keys(cursorPreciseExtras(table, cursorEntries));
+		if (preciseProps.length) params.extras = Object.fromEntries(preciseProps.map((prop) => [prop, (aliasedTable) => cursorPreciseExtras(aliasedTable, cursorEntries)[prop]]));
+	}
 	params.limit = distinctKeys ? void 0 : opts.limit;
 	const result = await queryBase.findMany(omitUndefinedKeys(params));
 	if (cursorEntries && cursorSelected) attachRowCursors(result, cursorEntries);
@@ -4601,16 +4741,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));
@@ -4619,6 +4760,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).
@@ -4640,6 +4789,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 ?? [];
@@ -4673,7 +4826,10 @@ const createRelationResolverFactory = (db, tables, nullOrdering, filterCtx, limi
 			const column = targetColumns[columnName];
 			if (column) columns[columnName] = column;
 		}
-		return columns;
+		return cursorEntries ? {
+			...columns,
+			...cursorPreciseSelection(targetTable, cursorEntries)
+		} : columns;
 	};
 	const resolve = async (parent, args, context, info) => {
 		if (parent[relationName] !== void 0) return parent[relationName];
@@ -4683,6 +4839,7 @@ const createRelationResolverFactory = (db, tables, nullOrdering, filterCtx, limi
 		const { orderByArg, limit, distinct, cursorEntries, cursorValues, columns, loaderKey } = getOrCreateRequestValue(context, info?.fieldNodes?.[0], `relation:${tableName}::${relationName}`, () => {
 			const orderByArg = isOne ? args?.orderBy : withDefaultOrderBy(args ?? {}, targetTableName, policies?.defaultOrderBy).orderBy;
 			const limit = applyLimitPolicy(requestedLimit, limitPolicy, errorCtx);
+			assertPagingNotNegative({ offset }, errorCtx);
 			const distinct = (args ?? {}).distinct?.length ? (args ?? {}).distinct : void 0;
 			const cursorSelected = !isOne && !!info && selectsCursorField(info, targetTable);
 			let cursorEntries;
@@ -4717,11 +4874,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,
@@ -4731,27 +4889,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);
@@ -5086,7 +5258,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
@@ -5120,7 +5292,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
@@ -5271,7 +5443,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
@@ -5838,6 +6010,10 @@ const createRelationAggregateFactory = (db, tables, cacheCtx, typeNameMapper, fi
 			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);
@@ -5868,11 +6044,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) ?? {});
 				});