@vantreeseba/drizzle-graphql 15.0.0 → 15.1.0

package/dist/index.d.cts

@@ -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

@@ -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

@@ -1789,6 +1789,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.)
@@ -2952,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.
@@ -2964,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);
@@ -2975,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;
@@ -4601,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));
@@ -4619,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).
@@ -4640,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 ?? [];
@@ -4717,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,
@@ -4731,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);
@@ -5086,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
@@ -5120,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
@@ -5271,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
@@ -5838,6 +5923,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 +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) ?? {});
 				});