buro26-strapi-graphql 0.2.0 → 0.3.0

package/README.md

@@ -50,7 +50,7 @@ export default createGraphQLFieldBuilder()
 
 Use `.relation()` to define (or protect) a relation field. It produces exactly the field Strapi generates:
 the same output type, filter/pagination arguments, resolver (with query validation and output sanitizing)
-and `<target>.find` permission scope, on **Strapi v4 and v5**.
+and, for relations, the `<target>.find` permission scope, on **Strapi v4 and v5**.
 
 ```typescript
 export default createGraphQLFieldBuilder()
@@ -64,8 +64,22 @@ export default createGraphQLFieldBuilder()
 | to-one | `XEntityResponse` | `X` |
 | to-many | `XRelationResponseCollection` | `[X]!` **and** `<field>_connection` (both get the same auth/middleware) |
 
-For to-one relations you can pass `{ batch: true }` to load the relation of all parents in the request with a
-single query (see [Data loading](#-data-loading)).
+Media attributes (`type: 'media'`) work too: `.relation('api::customer.customer', 'avatar')` uses
+`UploadFileEntityResponse` (v4) or `UploadFile` (v5); a `multiple: true` media field uses
+`UploadFileRelationResponseCollection` (v4) or `[UploadFile]!` plus `<field>_connection` (v5). Strapi
+attaches no permission scope to the media fields it generates, so `.relation()` adds none either.
+
+For to-one **and** to-many relations and for single or multiple media you can pass `{ batch: true }` to load
+the relation of all parents in the request with a single query (see [Data loading](#-data-loading)). A batched
+to-many field returns the same relation response collection as Strapi's own resolver; on v5 both the list
+field and `<field>_connection` use it.
+
+Batched loads cannot apply per-parent query arguments. When a client passes `filters`, `pagination`, `sort` or
+(v4 only) `publicationState`, that call falls back to Strapi's normal per-parent association resolver, so the
+arguments keep working; only those calls lose the batching benefit.
+
+Batched relations go through the [relation loader](#-data-loading), so draft & publish content is loaded as the
+published version. Media are files, so draft & publish never applies to them.
 
 ---
 
@@ -106,15 +120,31 @@ import { loaders, sanitizeOutput } from 'buro26-strapi-graphql';
 // One findMany ... where id IN (...) for all parents in the request
 const order = await loaders(ctx).entity(ORDER, { populate: { customer: true } }).load(parent.id);
 
-// The relation of many parents in one query (raw rows, sanitize before returning them)
+// The relation of many parents in one query. Raw rows: sanitize before returning them.
 const customer = await loaders(ctx).relation(ORDER, 'customer').load(parent.id);
 
+// Media work the same way: a file row (single) or an array (multiple)
+const avatar = await loaders(ctx).relation(CUSTOMER, 'avatar').load(parent.id);
+
+// Or let the loader sanitize every row for the content API
+const safeOrder = await loaders(ctx).entity(ORDER, { sanitize: true }).load(parent.id);
+
 // Your own batch function, e.g. for an external API
 const profile = await loaders(ctx).custom('profile', (ids: readonly number[]) => fetchProfiles(ids)).load(parent.id);
 ```
 
-Loaders use `strapi.db.query()` (identical in v4 and v5) and return **unsanitized** database rows. For draft &
-publish content types they load the published version unless `status: 'draft'` is passed.
+Loaders use `strapi.db.query()` (identical in v4 and v5) and return **unsanitized** database rows by default,
+including private fields. Pass `{ sanitize: true }` to run each row through `sanitizeOutput` first, or sanitize
+the rows yourself. For draft & publish content types they load the published version unless `status: 'draft'`
+is passed; files have no draft & publish status.
+
+Media attributes are stored as a morph relation to `plugin::upload.file`. `relation()` populates them in the
+same query and returns the file row for a single media attribute, or an array (empty when there is none) for
+`multiple: true`. With `{ sanitize: true }` files are sanitized against `plugin::upload.file`.
+
+Loaders are cached per request and per options value. Options are compared by value: property order does not
+matter and `select` is treated as a set, so `{ select: ['id', 'title'] }` and `{ select: ['title', 'id'] }` share
+one loader. Loaders with a different `populate` never share a batch, because they load different rows.
 
 ---
 
@@ -247,10 +277,19 @@ Global middleware and authorization are matched when the GraphQL schema is built
 the order in which files are loaded. The matcher receives `{ type, fieldName, tags, contentType, isBuilderField }`.
 
 By default globals only apply to fields created with the field builder. Pass `{ includeNonBuilderFields: true }`
-to also apply them to Strapi's generated fields and plain Nexus fields:
+to also apply them to Strapi's generated fields and plain Nexus fields.
+
+> **Cost: globals run once per resolved field, not once per request.** A query that resolves 50 fields runs every
+> matching global check and middleware 50 times. Keep them cheap and free of per-request side effects. Rate
+> limiting, request logging and similar per-request concerns belong in a Koa/Strapi middleware:
 
 ```typescript
-registerGlobalAuthorize(() => true, rateLimit, { includeNonBuilderFields: true });
+// src/middlewares/rate-limit.ts — runs once per HTTP request, before GraphQL resolves anything
+export default () => async (ctx, next) => {
+  const key = ctx.state.user?.id ?? ctx.ip;
+  if (!(await hits.allow(key))) return ctx.throw(429, 'Too many requests');
+  return next();
+};
 ```
 
 **Example:**
@@ -273,6 +312,12 @@ registerGlobalAuthorize(
   async (parent, args, ctx) => ctx.state.user?.isAdmin
 );
 
+// Or for every field of one content type, e.g. requiring a subscription
+registerGlobalAuthorize(
+  ({ contentType }) => contentType === 'api::customer.customer',
+  (_parent, _args, ctx) => Boolean(ctx.state.user?.subscription)
+);
+
 // Now define fields that will use these global middlewares/authorizations
 export default createGraphQLFieldBuilder('Query')
   .fieldName('deleteUser')

package/dist/server/utils/field-builder/builder.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resetBuiltFields = exports.createGraphQLFieldBuilder = void 0;
+exports.batchedRelationResolver = exports.resetBuiltFields = exports.createGraphQLFieldBuilder = void 0;
 const nexus_1 = require("nexus");
 const utils_1 = require("@strapi/utils");
 const immer_1 = require("immer");
@@ -482,27 +482,80 @@ function composeResolver(state, baseResolver) {
     return withTracing(withHooks, (_a = options.traceHandlers) !== null && _a !== void 0 ? _a : []);
 }
 /**
- * Resolver for `.relation(..., { batch: true })`: loads the related entity of all parents in the request
- * with one query, sanitizes it like Strapi does and returns the shape the relation field expects.
+ * Arguments of Strapi's relation fields that shape the related query per parent. A batched load cannot
+ * apply them, so a call that passes any of them uses Strapi's own association resolver instead.
+ *
+ * `publicationState` only exists on Strapi v4 to-many relation fields.
+ */
+const RELATION_QUERY_ARGS = ['filters', 'pagination', 'sort', 'publicationState'];
+/**
+ * True when an argument value changes the related query. Strapi fills in defaults on every call
+ * (`pagination: {}`, `sort: []` and, on v4, `publicationState: 'live'`); those count as not passed.
+ */
+function isEffectiveRelationArg(name, value) {
+    if (value === undefined || value === null)
+        return false;
+    if (Array.isArray(value))
+        return value.length > 0;
+    if (typeof value === 'object')
+        return Object.keys(value).length > 0;
+    if (name === 'publicationState')
+        return value !== 'live';
+    return true;
+}
+/** True when the client passed filters, pagination, sort or publication state to the relation field. */
+function hasRelationQueryArgs(args) {
+    if (!args)
+        return false;
+    return RELATION_QUERY_ARGS.some((name) => isEffectiveRelationArg(name, args[name]));
+}
+/**
+ * Resolver for `.relation(..., { batch: true })`: loads the relation or media attribute of all parents
+ * in the request with one query, sanitizes the rows like Strapi does and returns the shape the relation
+ * field expects.
+ *
+ * To-one resolves to an entity response; to-many resolves to a relation response collection
+ * (`{ nodes }`, on both v4 and v5 — the v5 list field unwraps `nodes`). Media resolve against
+ * `plugin::upload.file`; `multiple` decides the shape.
+ *
+ * Filters, pagination, sort and publication state cannot be applied to a batched load, so a call that
+ * passes them falls back to Strapi's per-parent association resolver. Draft & publish content is
+ * loaded through the relation loader, which defaults to the published version.
+ *
+ * @internal Exported for tests.
  */
 function batchedRelationResolver({ contentType, attribute }) {
     var _a, _b;
     const attr = (_b = (_a = strapi.getModel(contentType)) === null || _a === void 0 ? void 0 : _a.attributes) === null || _b === void 0 ? void 0 : _b[attribute];
-    if (!attr || attr.type !== 'relation') {
-        throw new utils_1.errors.ApplicationError(`"${contentType}.${attribute}" is not a relation`);
+    const isMedia = (attr === null || attr === void 0 ? void 0 : attr.type) === 'media';
+    if (!attr || (!isMedia && attr.type !== 'relation')) {
+        throw new utils_1.errors.ApplicationError(`"${contentType}.${attribute}" is not a relation or media attribute`);
     }
-    if (String(attr.relation).endsWith('Many')) {
-        throw new utils_1.errors.ApplicationError(`relation(..., { batch: true }) is only supported for to-one relations ("${contentType}.${attribute}" is to-many)`);
-    }
-    // Returns Strapi's response wrapper (`{ value, info }`), like `buildAssociationResolver`; the relation
-    // field spec unwraps it on Strapi v5.
-    const { toEntityResponse } = strapi.plugin('graphql').service('format').returnTypes;
-    return async (parent, _args, context) => {
+    const targetUID = isMedia ? 'plugin::upload.file' : attr.target;
+    const isToMany = isMedia ? Boolean(attr.multiple) : String(attr.relation).endsWith('Many');
+    // Returns Strapi's response wrapper (`{ value }` / `{ nodes }`), like `buildAssociationResolver`;
+    // the relation field spec unwraps the to-one value on Strapi v5.
+    const { toEntityResponse, toEntityResponseCollection } = strapi.plugin('graphql').service('format').returnTypes;
+    const associationResolver = strapi
+        .plugin('graphql')
+        .service('builders')
+        .get('content-api')
+        .buildAssociationResolver({ contentTypeUID: contentType, attributeName: attribute, strapi });
+    return async (parent, args, context, info) => {
+        if (hasRelationQueryArgs(args)) {
+            return associationResolver(parent, args, context, info);
+        }
         const related = (parent === null || parent === void 0 ? void 0 : parent.id) ? await (0, loaders_1.loaders)(context).relation(contentType, attribute).load(parent.id) : null;
-        const sanitized = related ? await (0, strapi_compat_1.sanitizeOutput)(related, attr.target, context) : null;
-        return toEntityResponse(sanitized, { args: {}, resourceUID: attr.target });
+        if (!isToMany) {
+            const sanitized = related ? await (0, strapi_compat_1.sanitizeOutput)(related, targetUID, context) : null;
+            return toEntityResponse(sanitized, { args: {}, resourceUID: targetUID });
+        }
+        const rows = Array.isArray(related) ? related : [];
+        const sanitized = await (0, strapi_compat_1.sanitizeOutput)(rows, targetUID, context);
+        return toEntityResponseCollection(sanitized !== null && sanitized !== void 0 ? sanitized : [], { args: {}, resourceUID: targetUID });
     };
 }
+exports.batchedRelationResolver = batchedRelationResolver;
 function defaultTraceHandler({ type, fieldName, durationMs, args, error }) {
     // Colors
     const green = '\x1b[32m';

package/dist/server/utils/field-builder/types.d.ts

@@ -83,11 +83,14 @@ export type RelationOptions = {
     /** Relation attribute name on that content type, e.g. `customer` */
     attribute: string;
     /**
-     * Resolve a to-one relation with the per-request relation loader: one query for all parents in the
+     * Resolve the relation with the per-request relation loader: one query for all parents in the
      * request instead of one query per parent. Output is sanitized for the content API, like Strapi's own
-     * resolver does.
+     * resolver does. Works for to-one and to-many relations; a to-many field returns the same relation
+     * response collection as Strapi.
      *
-     * Not supported for to-many relations, because those take filter/pagination arguments per parent.
+     * Batched loads cannot apply per-parent query arguments: when a client passes `filters`,
+     * `pagination`, `sort` or (v4) `publicationState`, that call falls back to Strapi's normal
+     * per-parent association resolver.
      *
      * @default false
      * @see {@link loaders}
@@ -134,9 +137,12 @@ export interface FieldExtensionBuilder<Type = any, TArgs = any, TOutput = Type>
      */
     rootType<N extends string>(type: N): FieldExtensionBuilder<ParentOf<N, Type>, TArgs, TOutput>;
     /**
-     * Define the field as a relation of a Strapi content type. It gets exactly the type, filter/pagination
-     * arguments, resolver (query validation, output sanitizing, draft & publish handling) and `<target>.find`
-     * permission scope of the field Strapi generates, on Strapi v4 and v5.
+     * Define the field as a relation or media attribute of a Strapi content type. It gets exactly the
+     * type, filter/pagination arguments, resolver (query validation, output sanitizing, draft & publish
+     * handling) and permission scope of the field Strapi generates, on Strapi v4 and v5.
+     *
+     * Media fields resolve against `plugin::upload.file`. Strapi attaches no permission scope to the
+     * media fields it generates, so neither does this builder.
      *
      * Sets {@link FieldExtensionBuilder.fieldName | fieldName} to `attribute`; `outputType` and `resolver`
      * are optional (a custom `resolver` replaces Strapi's association resolver). Combine with
@@ -150,18 +156,22 @@ export interface FieldExtensionBuilder<Type = any, TArgs = any, TOutput = Type>
      * On v5 both to-many fields get the same authorization and middleware. Note that the v5 list field is
      * non-null: when `.authorize()` denies it, GraphQL nulls the parent object (standard error propagation).
      *
-     * @param contentType - UID of the content type that owns the relation.
-     * @param attribute - Name of a regular (non-polymorphic) relation attribute.
+     * @param contentType - UID of the content type that owns the relation or media attribute.
+     * @param attribute - Name of a regular (non-polymorphic) relation or media attribute.
      * @param options - See {@link RelationOptions}.
      * @throws Error when a relation was already set, or `fieldName` was set to a different name.
-     * @throws ApplicationError at schema build when the attribute is not a relation, or `batch` is used on
-     *   a to-many relation.
+     * @throws ApplicationError at schema build when the attribute is not a relation or media attribute.
      *
      * @example
      * createGraphQLFieldBuilder()
      *   .rootType('Order')
      *   .relation('api::order.order', 'customer', { batch: true })
      *   .authorize(isOrderCustomer)
+     *
+     * @example
+     * createGraphQLFieldBuilder()
+     *   .rootType('Customer')
+     *   .relation('api::customer.customer', 'avatar', { batch: true })
      */
     relation(contentType: string, attribute: string, options?: Pick<RelationOptions, 'batch'>): FieldExtensionBuilder<Type, TArgs, TOutput>;
     /**

package/dist/server/utils/loaders.d.ts

@@ -1,10 +1,3 @@
-/**
- * Per-request batching and caching for GraphQL resolvers (DataLoader-style, without the dependency).
- *
- * Loads requested in the same tick are combined into one batch call; results are cached for the rest
- * of the request. The cache lives on the GraphQL context object, which Strapi creates per request in
- * both v4 and v5, so nothing leaks between requests or users.
- */
 type AnyRecord = Record<string, any>;
 /**
  * Loads values for many keys at once. Must return one result per key, **in the same order**; return an
@@ -40,6 +33,9 @@ export declare function createLoader<K, V>(batch: BatchFunction<K, V>, { maxBatc
 }): Loader<K, V>;
 /**
  * Options for {@link RequestLoaders.entity}. Loaders with different options are cached separately.
+ *
+ * Options are compared by value, not by reference: key order does not matter and `select` is treated
+ * as a set. Loaders with a different `populate` never share a batch, because the rows they load differ.
  */
 export type EntityLoaderOptions = {
     /** Columns to select (default: all) */
@@ -51,6 +47,15 @@ export type EntityLoaderOptions = {
      * @default 'published'
      */
     status?: 'published' | 'draft';
+    /**
+     * Pass every loaded row through {@link sanitizeOutput} before resolving it, so private fields and
+     * fields the current auth may not read are removed.
+     *
+     * Sanitizing needs the content type schema, so this throws for an unknown `uid`.
+     *
+     * @default false
+     */
+    sanitize?: boolean;
 };
 /**
  * Loaders scoped to one GraphQL request, returned by {@link loaders}.
@@ -60,15 +65,21 @@ export interface RequestLoaders {
      * Load entities of a content type by database id, batched into one `findMany` per tick.
      * Resolves to `null` for ids that do not exist.
      *
-     * Returns raw database rows (including private fields): sanitize before returning them to clients,
-     * see {@link sanitizeOutput}.
+     * **Returns raw database rows, including private fields and fields the current auth may not read.**
+     * Pass `{ sanitize: true }` to run every row through {@link sanitizeOutput} first, or sanitize the
+     * rows yourself before returning them to clients.
      */
     entity<T = AnyRecord>(uid: string, options?: EntityLoaderOptions): Loader<number | string, T | null>;
     /**
-     * Load a relation of many parents with one query on the parent content type.
-     * Resolves to the related entity or `null` (to-one), or an array (to-many), as raw database rows.
+     * Load a relation or media attribute of many parents with one query on the parent content type.
+     * Resolves to the related entity or `null` (to-one, single media), or an array (to-many, multiple
+     * media; empty when there is none).
      *
-     * @throws Error when `attribute` is not a relation of `uid`.
+     * **Returns raw database rows, including private fields and fields the current auth may not read.**
+     * Pass `{ sanitize: true }` to run every related row through {@link sanitizeOutput} first, or
+     * sanitize the rows yourself before returning them to clients.
+     *
+     * @throws Error when `attribute` is not a relation or media attribute of `uid`.
      */
     relation<T = AnyRecord>(uid: string, attribute: string, options?: Omit<EntityLoaderOptions, 'select'>): Loader<number | string, T>;
     /**
@@ -81,7 +92,11 @@ export interface RequestLoaders {
  * Loaders scoped to the current GraphQL request.
  *
  * Uses `strapi.db.query()` (same API in v4 and v5). That is the query engine, not the entity/document
- * service: lifecycle-free and unsanitized, so it is meant for reading data inside resolvers.
+ * service: lifecycle-free and unsanitized, so it is meant for reading data inside resolvers. Add
+ * `{ sanitize: true }` to return rows that are safe for the content API.
+ *
+ * Loaders are cached per request and per options value: options are compared by value (key order and
+ * `select` order do not matter), and loaders with a different `populate` do not share batches.
  *
  * @param context - The resolver's third argument (`ctx`).
  * @throws Error when `context` is not an object.
@@ -89,6 +104,7 @@ export interface RequestLoaders {
  * @example
  * const order = await loaders(ctx).entity(ORDER, { populate: { customer: true } }).load(parent.id)
  * const customer = await loaders(ctx).relation(ORDER, 'customer').load(parent.id)
+ * const safeOrder = await loaders(ctx).entity(ORDER, { sanitize: true }).load(parent.id)
  */
 export declare function loaders(context: object): RequestLoaders;
 export {};

package/dist/server/utils/loaders.js

@@ -1,4 +1,6 @@
 "use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loaders = exports.createLoader = void 0;
 /**
  * Per-request batching and caching for GraphQL resolvers (DataLoader-style, without the dependency).
  *
@@ -6,8 +8,7 @@
  * of the request. The cache lives on the GraphQL context object, which Strapi creates per request in
  * both v4 and v5, so nothing leaks between requests or users.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.loaders = exports.createLoader = void 0;
+const strapi_compat_1 = require("./strapi-compat");
 /**
  * Create a batching loader. Keys are compared by `String(key)`, so `1` and `'1'` share a cache entry.
  * Failed batches are not cached, so a later `load` retries.
@@ -85,6 +86,41 @@ function createLoader(batch, { maxBatchSize = 500 } = {}) {
 }
 exports.createLoader = createLoader;
 const requestLoaders = new WeakMap();
+/**
+ * Normalize a value for a cache key: object keys are sorted recursively, `select` arrays are sorted,
+ * and `undefined` properties are dropped.
+ */
+const normalizeCacheValue = (value) => {
+    if (Array.isArray(value))
+        return value.map(normalizeCacheValue);
+    if (!value || typeof value !== 'object')
+        return value;
+    const entries = Object.entries(value)
+        .filter(([, entryValue]) => entryValue !== undefined)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([key, entryValue]) => [
+        key,
+        key === 'select' && Array.isArray(entryValue)
+            ? [...entryValue].sort()
+            : normalizeCacheValue(entryValue)
+    ]);
+    return Object.fromEntries(entries);
+};
+/**
+ * Stable cache key for loader options, so equivalent options share one loader regardless of property
+ * order (`{ status: 'draft', populate: {...} }` and `{ populate: {...}, status: 'draft' }`) or column
+ * order in `select`.
+ */
+const optionsCacheKey = (options) => JSON.stringify(normalizeCacheValue(options));
+/** Sanitize one related value: an array for to-many, a single row for to-one, or `null`. */
+const sanitizeRelationValue = async (value, targetUID, context) => {
+    if (value == null)
+        return value;
+    if (Array.isArray(value)) {
+        return Promise.all(value.map((row) => (0, strapi_compat_1.sanitizeOutput)(row, targetUID, context)));
+    }
+    return (0, strapi_compat_1.sanitizeOutput)(value, targetUID, context);
+};
 const hasDraftAndPublish = (uid) => { var _a, _b; return Boolean((_b = (_a = strapi.getModel(uid)) === null || _a === void 0 ? void 0 : _a.options) === null || _b === void 0 ? void 0 : _b.draftAndPublish); };
 const statusWhere = (uid, status) => {
     if (!hasDraftAndPublish(uid))
@@ -95,7 +131,11 @@ const statusWhere = (uid, status) => {
  * Loaders scoped to the current GraphQL request.
  *
  * Uses `strapi.db.query()` (same API in v4 and v5). That is the query engine, not the entity/document
- * service: lifecycle-free and unsanitized, so it is meant for reading data inside resolvers.
+ * service: lifecycle-free and unsanitized, so it is meant for reading data inside resolvers. Add
+ * `{ sanitize: true }` to return rows that are safe for the content API.
+ *
+ * Loaders are cached per request and per options value: options are compared by value (key order and
+ * `select` order do not matter), and loaders with a different `populate` do not share batches.
  *
  * @param context - The resolver's third argument (`ctx`).
  * @throws Error when `context` is not an object.
@@ -103,6 +143,7 @@ const statusWhere = (uid, status) => {
  * @example
  * const order = await loaders(ctx).entity(ORDER, { populate: { customer: true } }).load(parent.id)
  * const customer = await loaders(ctx).relation(ORDER, 'customer').load(parent.id)
+ * const safeOrder = await loaders(ctx).entity(ORDER, { sanitize: true }).load(parent.id)
  */
 function loaders(context) {
     if (!context || typeof context !== 'object') {
@@ -123,7 +164,7 @@ function loaders(context) {
     };
     return {
         entity(uid, options = {}) {
-            return getOrCreate(`entity:${uid}:${JSON.stringify(options)}`, () => createLoader(async (ids) => {
+            return getOrCreate(`entity:${uid}:${optionsCacheKey(options)}`, () => createLoader(async (ids) => {
                 const select = options.select ? Array.from(new Set(['id', ...options.select])) : undefined;
                 const rows = await strapi.db.query(uid).findMany({
                     where: { id: { $in: ids }, ...statusWhere(uid, options.status) },
@@ -131,31 +172,46 @@ function loaders(context) {
                     ...(options.populate && { populate: options.populate }),
                 });
                 const byId = new Map(rows.map((row) => [String(row.id), row]));
-                return ids.map((id) => { var _a; return (_a = byId.get(String(id))) !== null && _a !== void 0 ? _a : null; });
+                const resolved = ids.map((id) => { var _a; return (_a = byId.get(String(id))) !== null && _a !== void 0 ? _a : null; });
+                if (!options.sanitize)
+                    return resolved;
+                return Promise.all(resolved.map((row) => (row ? (0, strapi_compat_1.sanitizeOutput)(row, uid, context) : row)));
             }));
         },
         relation(uid, attribute, options = {}) {
-            return getOrCreate(`relation:${uid}:${attribute}:${JSON.stringify(options)}`, () => createLoader(async (ids) => {
+            return getOrCreate(`relation:${uid}:${attribute}:${optionsCacheKey(options)}`, () => createLoader(async (ids) => {
                 var _a, _b;
                 const attr = (_b = (_a = strapi.getModel(uid)) === null || _a === void 0 ? void 0 : _a.attributes) === null || _b === void 0 ? void 0 : _b[attribute];
-                if (!attr || attr.type !== 'relation') {
-                    throw new Error(`[buro26-strapi-graphql] "${uid}.${attribute}" is not a relation`);
+                const isMedia = (attr === null || attr === void 0 ? void 0 : attr.type) === 'media';
+                if (!attr || (!isMedia && attr.type !== 'relation')) {
+                    throw new Error(`[buro26-strapi-graphql] "${uid}.${attribute}" is not a relation or media attribute`);
                 }
-                const isToMany = String(attr.relation).endsWith('Many');
+                // Media are stored as a morph relation to the upload plugin's file content type. Their
+                // target lives there, not on the attribute, and draft & publish never applies to files.
+                const targetUID = isMedia ? 'plugin::upload.file' : attr.target;
+                const isToMany = isMedia ? Boolean(attr.multiple) : String(attr.relation).endsWith('Many');
+                const nestedPopulate = options.populate && typeof options.populate === 'object' && !Array.isArray(options.populate)
+                    ? { populate: options.populate }
+                    : {};
+                // Media always need `true`/a nested populate; their file rows have no draft & publish status.
+                const populate = isMedia
+                    ? Object.keys(nestedPopulate).length > 0
+                        ? nestedPopulate
+                        : true
+                    : {
+                        ...nestedPopulate,
+                        ...(hasDraftAndPublish(targetUID) && { where: statusWhere(targetUID, options.status) }),
+                    };
                 const rows = await strapi.db.query(uid).findMany({
                     where: { id: { $in: ids } },
                     select: ['id'],
-                    populate: {
-                        [attribute]: {
-                            ...(options.populate && typeof options.populate === 'object' && !Array.isArray(options.populate)
-                                ? { populate: options.populate }
-                                : {}),
-                            ...(hasDraftAndPublish(attr.target) && { where: statusWhere(attr.target, options.status) }),
-                        },
-                    },
+                    populate: { [attribute]: populate },
                 });
                 const byId = new Map(rows.map((row) => [String(row.id), row[attribute]]));
-                return ids.map((id) => { var _a; return (_a = byId.get(String(id))) !== null && _a !== void 0 ? _a : (isToMany ? [] : null); });
+                const resolved = ids.map((id) => { var _a; return (_a = byId.get(String(id))) !== null && _a !== void 0 ? _a : (isToMany ? [] : null); });
+                if (!options.sanitize)
+                    return resolved;
+                return Promise.all(resolved.map((value) => sanitizeRelationValue(value, targetUID, context)));
             }));
         },
         custom(name, batch) {

package/dist/server/utils/registry/global-registry.d.ts

@@ -40,6 +40,10 @@ export type GlobalRegistrationOptions = {
  * first). Matched when the schema is built, so registration order relative to fields does not matter;
  * register before Strapi's bootstrap (i.e. at module level in a `graphql` folder).
  *
+ * **Runs once per resolved field, not once per request.** A query that resolves 50 fields runs the
+ * middleware 50 times. Per-request concerns such as rate limiting or request logging belong in a
+ * Koa/Strapi middleware, not here.
+ *
  * @param matcher - Decides per field; see {@link FieldMatcherInfo}.
  * @param middleware - `(next) => resolver`, as in `.middleware()`.
  * @param options - See {@link GlobalRegistrationOptions}.
@@ -52,12 +56,19 @@ export declare function registerGlobalMiddleware(matcher: FieldMatcher, middlewa
  * Register an authorization check for all fields that match. Global checks run before the field's own
  * checks; all must return `true`. Matched when the schema is built, so registration order does not matter.
  *
+ * **Runs once per resolved field, not once per request.** A query that resolves 50 fields runs the
+ * check 50 times, so a per-field check must stay cheap and free of per-request side effects. Rate
+ * limiting and similar per-request concerns belong in a Koa/Strapi middleware, not here.
+ *
  * @param matcher - Decides per field; see {@link FieldMatcherInfo}.
  * @param authorize - Return `true` to allow, `false` or an `Error` to deny.
  * @param options - See {@link GlobalRegistrationOptions}.
  *
  * @example
- * // Rate limit every field, including Strapi's generated ones
- * registerGlobalAuthorize(() => true, rateLimit, { includeNonBuilderFields: true })
+ * // Require a paid subscription for every customer field
+ * registerGlobalAuthorize(
+ *   ({ contentType }) => contentType === 'api::customer.customer',
+ *   (_parent, _args, ctx) => Boolean(ctx.state.user?.subscription)
+ * )
  */
 export declare function registerGlobalAuthorize(matcher: FieldMatcher, authorize: ResolverFunction, options?: GlobalRegistrationOptions): void;

package/dist/server/utils/registry/global-registry.js

@@ -8,6 +8,10 @@ const globalAuthorizes = [];
  * first). Matched when the schema is built, so registration order relative to fields does not matter;
  * register before Strapi's bootstrap (i.e. at module level in a `graphql` folder).
  *
+ * **Runs once per resolved field, not once per request.** A query that resolves 50 fields runs the
+ * middleware 50 times. Per-request concerns such as rate limiting or request logging belong in a
+ * Koa/Strapi middleware, not here.
+ *
  * @param matcher - Decides per field; see {@link FieldMatcherInfo}.
  * @param middleware - `(next) => resolver`, as in `.middleware()`.
  * @param options - See {@link GlobalRegistrationOptions}.
@@ -23,13 +27,20 @@ exports.registerGlobalMiddleware = registerGlobalMiddleware;
  * Register an authorization check for all fields that match. Global checks run before the field's own
  * checks; all must return `true`. Matched when the schema is built, so registration order does not matter.
  *
+ * **Runs once per resolved field, not once per request.** A query that resolves 50 fields runs the
+ * check 50 times, so a per-field check must stay cheap and free of per-request side effects. Rate
+ * limiting and similar per-request concerns belong in a Koa/Strapi middleware, not here.
+ *
  * @param matcher - Decides per field; see {@link FieldMatcherInfo}.
  * @param authorize - Return `true` to allow, `false` or an `Error` to deny.
  * @param options - See {@link GlobalRegistrationOptions}.
  *
  * @example
- * // Rate limit every field, including Strapi's generated ones
- * registerGlobalAuthorize(() => true, rateLimit, { includeNonBuilderFields: true })
+ * // Require a paid subscription for every customer field
+ * registerGlobalAuthorize(
+ *   ({ contentType }) => contentType === 'api::customer.customer',
+ *   (_parent, _args, ctx) => Boolean(ctx.state.user?.subscription)
+ * )
  */
 function registerGlobalAuthorize(matcher, authorize, options = {}) {
     globalAuthorizes.push({ matcher, value: authorize, options });

package/dist/server/utils/strapi-compat.d.ts

@@ -34,13 +34,16 @@ export type RelationFieldSpec = {
     resolverConfigPaths: string[];
 };
 /**
- * Describes the GraphQL field(s) Strapi itself generates for a regular (non-morph) relation, so we can
+ * Describes the GraphQL field(s) Strapi itself generates for a relation or media attribute, so we can
  * (re)define them with exactly the same type, arguments, resolver and permission scope.
  *
  * - v4: to-one → `XEntityResponse`, to-many → `XRelationResponseCollection` (with filters/pagination args).
  * - v5: to-one → `X` (unwrapped), to-many → `[X]!` (unwrapped `nodes`) **and** `<field>_connection`
  *   returning `XRelationResponseCollection`.
  *
+ * Media (`type: 'media'`) resolves against `plugin::upload.file`; Strapi generates the same fields as
+ * for a relation, with `multiple` deciding the to-one/to-many shape.
+ *
  * All variants use Strapi's own `buildAssociationResolver`, so query validation, output sanitizing and
  * draft/publish handling stay identical to the generated field.
  *
@@ -48,7 +51,7 @@ export type RelationFieldSpec = {
  *
  * @param resolveOverride - Replaces Strapi's association resolver. It must return Strapi's response
  *   wrapper (`{ value }` / `{ nodes }`); v5 unwrapping is applied on top.
- * @throws Error when the content type is unknown or the attribute is not a regular relation.
+ * @throws Error when the content type is unknown or the attribute is not a relation or media attribute.
  */
 export declare const relationFieldSpecs: (contentTypeUID: string, attributeName: string, resolveOverride?: RelationFieldSpec['resolve']) => RelationFieldSpec[];
 /**
@@ -56,7 +59,9 @@ export declare const relationFieldSpecs: (contentTypeUID: string, attributeName:
  * exactly like the generated relation fields do. Pass it to an extension's `resolversConfig` when you
  * define relation fields yourself.
  *
- * @returns A map of `Type.field` paths to `{ auth: { scope } }`.
+ * Media fields get no scope, because Strapi does not attach one to the media fields it generates.
+ *
+ * @returns A map of `Type.field` paths to `{ auth: { scope } }`, or `{}` for media.
  */
 export declare const relationResolversConfig: (contentTypeUID: string, attributeName: string) => {
     [k: string]: {