buro26-strapi-graphql 0.1.0 → 0.2.0

package/README.md

@@ -30,13 +30,115 @@ This fluent, type-safe builder gives you the best DX, composability, and testabi
 import { createGraphQLFieldBuilder } from 'buro26-strapi-graphql';
 import { nonNull, stringArg } from 'nexus';
 
-export default createGraphQLFieldBuilder('Query')
+export default createGraphQLFieldBuilder()
+  .rootType('Query')
   .fieldName('helloWorld')
   .args({ name: nonNull(stringArg()) })
   .outputType(nonNull('String'))
   .description('Returns a personalized greeting')
-  .resolver(async (parent, args) => `Hello World ${args.name}`)
-  .resolverConfig({ auth: false });
+  .withAuth(false)
+  .resolver(async (parent, args) => `Hello World ${args.name}`);
+```
+
+> **Canonical style:** `createGraphQLFieldBuilder().rootType(...)`, `.withAuth(...)` for authentication and
+> `.authorize(...)` for authorization. `createGraphQLFieldBuilder('Query')` and `.resolverConfig({ auth })`
+> still work but are not used in new code.
+
+---
+
+## 🔗 Relations
+
+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**.
+
+```typescript
+export default createGraphQLFieldBuilder()
+  .rootType('Order')
+  .relation('api::order.order', 'customer')
+  .authorize(isOrderCustomer);
+```
+
+| | Strapi v4 | Strapi v5 |
+|---|---|---|
+| 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)).
+
+---
+
+## 🛡️ Protecting Strapi's Generated Fields
+
+`protectFields()` adds authorization and/or middleware to fields Strapi generates for a content type —
+scalars, enums, media, components and relations — **without redefining them**. Strapi's types, arguments and
+resolvers stay untouched, so it behaves the same on v4 and v5 (for v5 to-many relations the
+`<field>_connection` field is protected too).
+
+```typescript
+// e.g. src/api/customer/graphql/_protect.ts
+import { protectFields } from 'buro26-strapi-graphql';
+
+protectFields<Customer>('api::customer.customer', ['street', 'postalCode', 'iban', 'orders'])
+  .authorize((customer, _args, ctx) => isSelf(customer, ctx.state.user))
+  .middleware(auditLog);
+```
+
+The checks are attached by the package's Nexus plugins when the schema is built, so the file only needs to be
+loaded from a `graphql` folder; it does not have to export anything.
+
+> **Non-null fields:** a denied non-null field makes GraphQL null its parent object (standard error propagation).
+> Strapi generates required attributes and v5 to-many relations (`[X]!`) as non-null, so protecting those hides the
+> whole parent for users without access. A warning is logged when the schema is built. Prefer this over `overrideField` when you
+only want to restrict access.
+
+---
+
+## ⚡ Data Loading
+
+`loaders(ctx)` gives every request its own batching cache (DataLoader-style, no extra dependency). Loads from the
+same tick are combined into one query; results are cached until the request ends.
+
+```typescript
+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)
+const customer = await loaders(ctx).relation(ORDER, 'customer').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.
+
+---
+
+## 🏷️ Typing Your Project
+
+Register your user type and entity types once, so `context.state.user` and `parent` are typed everywhere:
+
+```typescript
+declare module 'buro26-strapi-graphql' {
+  interface Register {
+    user: User;
+    types: { Customer: Customer; Order: Order };
+  }
+}
+
+createGraphQLFieldBuilder()
+  .rootType('Customer')          // parent is now typed as Customer
+  .fieldName('fullName')
+  .outputType('String')
+  .resolver((customer) => `${customer?.firstName} ${customer?.lastName}`);
+```
+
+For registered entity types, `parent` is `Partial<Entity>` with `id` required: Strapi always passes the entity,
+but relations are only present when populated. Unregistered `Query`/`Mutation` fields keep `parent: any`.
 ```
 
 ---
@@ -141,10 +243,15 @@ t.field('myField', {
 You can register **global middleware** and **global authorization** that apply to multiple fields based on type, field
 name, or tags.
 
-**Important:**
-> **Global middleware and authorization must be registered _before_ any fields that consume them are built or
-registered.**  
-> This ensures that all relevant fields will pick up the global logic.
+Global middleware and authorization are matched when the GraphQL schema is built, so they apply regardless of
+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:
+
+```typescript
+registerGlobalAuthorize(() => true, rateLimit, { includeNonBuilderFields: true });
+```
 
 **Example:**
 
@@ -174,11 +281,9 @@ export default createGraphQLFieldBuilder('Query')
   .resolver(() => true);
 ```
 
-**Best Practice:**
-
-- Always register global middleware and authorization at the top of your entry file (before any field or extension
-  exports).
-- This guarantees that all fields will be able to consume the global logic.
+**Order of execution per field:** authentication (`withAuth(true)`) → global authorizes → the field's own
+`authorize` → `protectFields` authorizes → global middlewares → the field's own middlewares → `protectFields`
+middlewares → resolver (argument validation, hooks, tracing).
 
 ---
 
@@ -187,14 +292,14 @@ export default createGraphQLFieldBuilder('Query')
 - Use the **builder’s `.authorize()` and `.middleware()`** methods for most use-cases—they automatically set the correct
   `extensions` properties.
 - Use the `extensions` property directly for advanced or manual Nexus usage.
-- Register **global middleware and authorization before** any fields that should use them.
+- Use **`protectFields()`** to restrict Strapi's generated fields and **`.relation()`** for relation fields.
 - Use **tags** to target groups of fields for global logic.
 
 ---
 
 ### **Validation, Tracing, and Testing**
 
-**Argument validation with Zod:**
+**Argument validation with Zod** (also types the resolver's `args` as the parsed schema output):
 
 ```typescript
 import { z } from 'zod';
@@ -222,7 +327,8 @@ export default createGraphQLFieldBuilder('Query')
   });
 ```
 
-**Testing in isolation:**
+**Testing in isolation** (runs the same pipeline as in production: global and field authorization, `withAuth`,
+middlewares, argument validation and hooks; pass `skipAuth` / `skipMiddleware` to leave parts out):
 
 ```typescript
 const field = createGraphQLFieldBuilder('Query')
@@ -316,7 +422,11 @@ export default createGraphQLExtension()
 
 ## 🧩 Overriding and Extending Fields
 
-You can override or extend fields in existing types using the `overrideField` helper:
+> To only restrict access to generated fields, use [`protectFields()`](#️-protecting-strapis-generated-fields);
+> for relations, use [`.relation()`](#-relations). Use `overrideField` when you need to replace a field's resolver.
+
+You can override or extend fields in existing types using the `overrideField` helper. Pass authorization via
+`authorize` (or `extensions.authorize`); relation fields are generated for both Strapi v4 and v5:
 
 ```typescript
 import { createGraphQLExtension, overrideField } from 'buro26-strapi-graphql';
@@ -461,6 +571,8 @@ To run tests:
 bun test
 ```
 
+Tests live in `test/` and run against real Nexus/GraphQL schemas with a minimal `strapi` mock.
+
 ---
 
 ## 🤝 Contributing

package/dist/server/index.d.ts

@@ -27,7 +27,7 @@ declare const _default: {
         fileService: ({ strapi }: {
             strapi: Required<import("@strapi/types").Strapi>;
         }) => {
-            getAllFilesInGraphQlDirectory(directoryPath: string, collectedExtensions?: GraphQLExtension[]): Promise<GraphQLExtension[]>;
+            getAllFilesInGraphQlDirectory(directoryPath: string): Promise<GraphQLExtension[]>;
         };
         graphQlService: ({ strapi }: {
             strapi: Required<import("@strapi/types").Strapi>;

package/dist/server/nexus/plugins/field-authorize.plugin.d.ts

@@ -8,8 +8,29 @@ export interface FieldAuthorizePluginErrorConfig {
     ctx: GetGen<'context'>;
     info: GraphQLResolveInfo;
 }
+/**
+ * Options for {@link nexusFieldAuthorizePlugin}.
+ */
 export interface FieldAuthorizePluginConfig {
+    /**
+     * Turn a denied authorization into the error sent to the client.
+     * @default {@link defaultFormatError}
+     */
     formatError?: (authConfig: FieldAuthorizePluginErrorConfig) => Error;
 }
+/**
+ * Default error for denied authorization: a Strapi `ForbiddenError` with the original message and
+ * trace details (type, field, user id, args, timestamp) in `details.trace`.
+ */
 export declare const defaultFormatError: ({ error, root, args, ctx, info }: FieldAuthorizePluginErrorConfig) => Error;
+/**
+ * Field-level authentication and authorization.
+ *
+ * Applies to every field in the schema (including the ones Strapi generates) and combines:
+ * `withAuth(true)` of builder fields, global authorizes, the field's own `authorize` (in `extensions` or
+ * as top-level field option) and `protectFields()` registrations.
+ *
+ * Registered automatically by this Strapi plugin; only add it yourself when building a schema outside
+ * Strapi (e.g. in tests).
+ */
 export declare const nexusFieldAuthorizePlugin: (authConfig?: FieldAuthorizePluginConfig) => import("nexus/dist/plugin").NexusPlugin;

package/dist/server/nexus/plugins/field-authorize.plugin.js

@@ -1,9 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.nexusFieldAuthorizePlugin = exports.defaultFormatError = void 0;
+exports.nexusFieldAuthorizePlugin = exports.runAuthorization = exports.defaultFormatError = void 0;
 const nexus_1 = require("nexus");
 const utils_1 = require("nexus/dist/utils");
 const utils_2 = require("@strapi/utils");
+const graphql_1 = require("graphql");
+const resolve_field_1 = require("../../utils/registry/resolve-field");
 const fieldDefTypes = (0, utils_1.printedGenTyping)({
     optional: true,
     name: 'authorize',
@@ -17,6 +19,10 @@ const fieldDefTypes = (0, utils_1.printedGenTyping)({
   `,
     type: 'FieldAuthorizeResolver<TypeName, FieldName>',
 });
+/**
+ * Default error for denied authorization: a Strapi `ForbiddenError` with the original message and
+ * trace details (type, field, user id, args, timestamp) in `details.trace`.
+ */
 const defaultFormatError = ({ error, root, args, ctx, info }) => {
     var _a, _b;
     // Add rich tracing info
@@ -32,9 +38,15 @@ const defaultFormatError = ({ error, root, args, ctx, info }) => {
     return new utils_2.errors.ForbiddenError((error === null || error === void 0 ? void 0 : error.message) || 'Not authorized', { trace });
 };
 exports.defaultFormatError = defaultFormatError;
-const nexusFieldAuthorizePlugin = (authConfig = {}) => {
-    const { formatError = exports.defaultFormatError } = authConfig;
-    const ensureError = (root, args, ctx, info) => (error) => {
+/**
+ * Run the authentication + authorization part of a field pipeline.
+ * Resolves when allowed, rejects with the (formatted) error otherwise.
+ *
+ * @internal Used by the authorize plugin and `.test()`.
+ */
+const runAuthorization = async (pipeline, root, args, ctx, info, formatError = exports.defaultFormatError) => {
+    var _a, _b;
+    const fail = (error) => {
         const finalErr = formatError({ error, root, args, ctx, info });
         if (finalErr instanceof Error) {
             throw finalErr;
@@ -42,46 +54,67 @@ const nexusFieldAuthorizePlugin = (authConfig = {}) => {
         console.error(`Non-Error value ${finalErr} returned from custom formatError in authorize plugin`);
         throw new utils_2.errors.ForbiddenError('Not authorized');
     };
+    if (pipeline.requireAuth && !((_a = ctx === null || ctx === void 0 ? void 0 : ctx.state) === null || _a === void 0 ? void 0 : _a.user)) {
+        // Same error as before, but now evaluated before any authorize function runs
+        throw new utils_2.errors.ForbiddenError('Not authenticated');
+    }
+    for (const authorize of pipeline.authorizes) {
+        let authResult;
+        try {
+            authResult = await authorize(root, args, ctx, info);
+        }
+        catch (e) {
+            fail(e instanceof Error ? e : new utils_2.errors.ForbiddenError(String(e)));
+        }
+        if (authResult === true)
+            continue;
+        if (authResult instanceof Error)
+            fail(authResult);
+        if (authResult === false)
+            fail(new utils_2.errors.ForbiddenError('Not authorized'));
+        fail(new utils_2.errors.ForbiddenError(`Authorize for ${(_b = info === null || info === void 0 ? void 0 : info.parentType) === null || _b === void 0 ? void 0 : _b.name}.${info === null || info === void 0 ? void 0 : info.fieldName} Expected a boolean or Error, saw ${authResult}`));
+    }
+};
+exports.runAuthorization = runAuthorization;
+/**
+ * Field-level authentication and authorization.
+ *
+ * Applies to every field in the schema (including the ones Strapi generates) and combines:
+ * `withAuth(true)` of builder fields, global authorizes, the field's own `authorize` (in `extensions` or
+ * as top-level field option) and `protectFields()` registrations.
+ *
+ * Registered automatically by this Strapi plugin; only add it yourself when building a schema outside
+ * Strapi (e.g. in tests).
+ */
+const nexusFieldAuthorizePlugin = (authConfig = {}) => {
+    const { formatError = exports.defaultFormatError } = authConfig;
     return (0, nexus_1.plugin)({
         name: 'CustomFieldAuthorize',
         description: 'Custom field-level authorization for Strapi GraphQL, with tracing.',
         fieldDefTypes: fieldDefTypes,
         onCreateFieldResolver(config) {
-            var _a;
+            var _a, _b, _c;
             // @ts-ignore
-            const authorize = (_a = config.fieldConfig.extensions) === null || _a === void 0 ? void 0 : _a.authorize;
-            if (authorize == null) {
-                return;
+            const extensions = config.fieldConfig.extensions;
+            if ((extensions === null || extensions === void 0 ? void 0 : extensions.authorize) != null && typeof extensions.authorize !== 'function') {
+                console.error(new Error(`The authorize property provided to ${config.fieldConfig.name} with type ${config.fieldConfig.type} should be a function, saw ${typeof extensions.authorize}`));
+                // Fail closed: a broken authorize must not silently disable the other checks on this field
+                return async function () {
+                    throw new utils_2.errors.ForbiddenError('Not authorized');
+                };
             }
-            if (typeof authorize !== 'function') {
-                console.error(new Error(`The authorize property provided to ${config.fieldConfig.name} with type ${config.fieldConfig.type} should be a function, saw ${typeof authorize}`));
+            const pipeline = (0, resolve_field_1.resolveFieldPipeline)(config.parentTypeConfig.name, config.fieldConfig.name, extensions);
+            if (!pipeline.requireAuth && pipeline.authorizes.length === 0) {
                 return;
             }
-            return function (root, args, ctx, info, next) {
-                console.log(`Running authorize for ${info.parentType.name}.${info.fieldName}`);
-                let toComplete;
-                try {
-                    toComplete = authorize(root, args, ctx, info);
-                }
-                catch (e) {
-                    toComplete = Promise.reject(e);
-                }
-                return nexus_1.plugin.completeValue(toComplete, (authResult) => {
-                    if (authResult === true) {
-                        return next(root, args, ctx, info);
-                    }
-                    const finalFormatError = ensureError(root, args, ctx, info);
-                    if (authResult instanceof Error) {
-                        finalFormatError(authResult);
-                    }
-                    if (authResult === false) {
-                        finalFormatError(new utils_2.errors.ForbiddenError('Not authorized'));
-                    }
-                    const { fieldName, parentType: { name: parentTypeName } } = info;
-                    finalFormatError(new utils_2.errors.ForbiddenError(`Authorize for ${parentTypeName}.${fieldName} Expected a boolean or Error, saw ${authResult}`));
-                }, (err) => {
-                    ensureError(root, args, ctx, info)(err);
-                });
+            if (pipeline.isProtected && (0, graphql_1.isNonNullType)(config.fieldConfig.type)) {
+                const warn = (_c = (_b = (_a = globalThis.strapi) === null || _a === void 0 ? void 0 : _a.log) === null || _b === void 0 ? void 0 : _b.warn) !== null && _c !== void 0 ? _c : console.warn;
+                warn(`[buro26-strapi-graphql] protectFields: "${config.parentTypeConfig.name}.${config.fieldConfig.name}" is non-null; ` +
+                    `when access is denied GraphQL nulls the parent object instead of only this field.`);
+            }
+            return async function (root, args, ctx, info, next) {
+                await (0, exports.runAuthorization)(pipeline, root, args, ctx, info, formatError);
+                return next(root, args, ctx, info);
             };
         }
     });

package/dist/server/nexus/plugins/middleware.plugin.d.ts

@@ -9,9 +9,17 @@ export type Resolver = <Parent extends any, Args extends any, Context = ResolveC
  * Middleware is a function that takes a resolver and returns a new resolver.
  */
 export type Middleware<TParent = any, TArgs = any> = (resolver: ResolverFunction<TParent, TArgs>) => ResolverFunction<TParent, TArgs>;
+/**
+ * Field-level middlewares: global middlewares, the field's own `middlewares` (in `extensions` or as
+ * top-level field option) and `protectFields()` middlewares, outermost first.
+ *
+ * Registered automatically by this Strapi plugin; only add it yourself when building a schema outside
+ * Strapi (e.g. in tests).
+ */
 export declare const nexusMiddlewarePlugin: () => import("nexus/dist/plugin").NexusPlugin;
 /**
- * Logging Middleware
- * Logs the execution of the resolver.
+ * Example middleware that logs every resolve, including the result.
+ *
+ * Development only: it logs resolved values, which may contain personal data.
  */
 export declare const loggingMiddleware: Middleware;

package/dist/server/nexus/plugins/middleware.plugin.js

@@ -3,19 +3,23 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.loggingMiddleware = exports.nexusMiddlewarePlugin = void 0;
 const nexus_1 = require("nexus");
 const utils_1 = require("nexus/dist/utils");
+const resolve_field_1 = require("../../utils/registry/resolve-field");
 const fieldDefTypes = (0, utils_1.printedGenTyping)({
     optional: true,
     name: 'middlewares',
     description: `
-    Authorization for an individual field. Returning "true"
-    or "Promise<true>" means the field can be accessed.
-    Returning "false" or "Promise<false>" will respond
-    with a "Not Authorized" error for the field.
-    Returning or throwing an error will also prevent the
-    resolver from executing.
+    Middlewares for an individual field. Each middleware receives the
+    next resolver and returns a new resolver.
   `,
     type: 'any'
 });
+/**
+ * Field-level middlewares: global middlewares, the field's own `middlewares` (in `extensions` or as
+ * top-level field option) and `protectFields()` middlewares, outermost first.
+ *
+ * Registered automatically by this Strapi plugin; only add it yourself when building a schema outside
+ * Strapi (e.g. in tests).
+ */
 const nexusMiddlewarePlugin = () => (0, nexus_1.plugin)({
     name: 'NexusMiddlewarePlugin',
     description: 'The middleware plugin allows attaching middleware functions to individual fields.',
@@ -27,43 +31,26 @@ const nexusMiddlewarePlugin = () => (0, nexus_1.plugin)({
      * Hook into field resolver creation to apply middleware.
      */
     onCreateFieldResolver(config) {
-        var _a;
         const { fieldConfig } = config;
+        const { middlewares } = (0, resolve_field_1.resolveFieldPipeline)(config.parentTypeConfig.name, fieldConfig.name, 
         // @ts-ignore
-        const middlewares = ((_a = fieldConfig.extensions) === null || _a === void 0 ? void 0 : _a.middlewares) || [];
+        fieldConfig.extensions);
         if (middlewares.length === 0) {
             return undefined; // No middleware to apply
         }
-        // Convert Middleware[] to MiddlewareFn[]
-        const middlewareFns = middlewares.map(middleware => {
-            return async (source, args, context, info, next) => {
-                const newResolver = middleware(next);
-                return newResolver(source, args, context, info);
-            };
-        });
-        // Compose the middleware functions into a single MiddlewareFn
-        return async (source, args, context, info, next) => {
-            let index = -1;
-            const dispatch = async (i) => {
-                if (i <= index)
-                    throw new Error('next() called multiple times');
-                index = i;
-                const middlewareFn = middlewareFns[i];
-                if (middlewareFn) {
-                    return middlewareFn(source, args, context, info, () => dispatch(i + 1));
-                }
-                else {
-                    return next(source, args, context, info);
-                }
-            };
-            return dispatch(0);
+        // Outermost first. Each middleware may call the next resolver with changed parent/args/context,
+        // which are passed on (same composition as `.test()`).
+        return (source, args, context, info, next) => {
+            const resolver = middlewares.reduceRight((inner, middleware) => middleware(inner), (s, a, c, i) => next(s, a, c, i));
+            return resolver(source, args, context, info);
         };
     }
 });
 exports.nexusMiddlewarePlugin = nexusMiddlewarePlugin;
 /**
- * Logging Middleware
- * Logs the execution of the resolver.
+ * Example middleware that logs every resolve, including the result.
+ *
+ * Development only: it logs resolved values, which may contain personal data.
  */
 const loggingMiddleware = (resolver) => {
     return async (parent, args, context, info) => {

package/dist/server/services/file-service.d.ts

@@ -3,13 +3,14 @@ declare const _default: ({ strapi }: {
     strapi: Strapi;
 }) => {
     /**
-     * Fetch all the files in the graphql directories within the given directory path
-     * Recursively searches for files in the graphql directory
-     * Returns an array of GraphQLExtension objects
+     * Load all extensions from `graphql` folders below `directoryPath` (recursively).
      *
-     * @param directoryPath
-     * @param collectedExtensions
+     * Files are loaded in a stable order (sorted by name, depth-first), so the generated schema and the
+     * order of side effects such as `protectFields()` / `registerGlobalAuthorize()` calls are the same on
+     * every start.
+     *
+     * @param directoryPath - Usually `strapi.dirs.dist.src`.
      */
-    getAllFilesInGraphQlDirectory(directoryPath: string, collectedExtensions?: GraphQLExtension[]): Promise<GraphQLExtension[]>;
+    getAllFilesInGraphQlDirectory(directoryPath: string): Promise<GraphQLExtension[]>;
 };
 export default _default;

package/dist/server/services/file-service.js

@@ -25,50 +25,50 @@ var __importStar = (this && this.__importStar) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 const fs_1 = require("fs");
 const path = __importStar(require("path"));
+const GRAPHQL_FOLDER = 'graphql';
+const isInGraphQLFolder = (directoryPath) => directoryPath.endsWith(path.sep + GRAPHQL_FOLDER) || directoryPath.includes(path.sep + GRAPHQL_FOLDER + path.sep);
+const isLoadableFile = (file) => file.endsWith('.js');
+/**
+ * Turn a module's export into extensions. Builders (anything with `build()`) are built; arrays are flattened.
+ */
+const toExtensions = (graphqlModule) => {
+    var _a;
+    const exported = (_a = graphqlModule === null || graphqlModule === void 0 ? void 0 : graphqlModule.default) !== null && _a !== void 0 ? _a : graphqlModule;
+    if (!exported)
+        return [];
+    const build = (item) => (item && typeof item.build === 'function' ? item.build() : item);
+    if (Array.isArray(exported)) {
+        return exported.map(build).filter(Boolean);
+    }
+    // Modules without a default export (e.g. one that only calls `protectFields`) yield an empty extension,
+    // which registers nothing.
+    return [build(exported)];
+};
 exports.default = ({ strapi }) => ({
     /**
-     * Fetch all the files in the graphql directories within the given directory path
-     * Recursively searches for files in the graphql directory
-     * Returns an array of GraphQLExtension objects
+     * Load all extensions from `graphql` folders below `directoryPath` (recursively).
      *
-     * @param directoryPath
-     * @param collectedExtensions
+     * Files are loaded in a stable order (sorted by name, depth-first), so the generated schema and the
+     * order of side effects such as `protectFields()` / `registerGlobalAuthorize()` calls are the same on
+     * every start.
+     *
+     * @param directoryPath - Usually `strapi.dirs.dist.src`.
      */
-    async getAllFilesInGraphQlDirectory(directoryPath, collectedExtensions = []) {
-        const fileEntries = await fs_1.promises.readdir(directoryPath);
-        // Create an array of promises for all the files
-        const filePromises = fileEntries.map(async (file) => {
+    async getAllFilesInGraphQlDirectory(directoryPath) {
+        const fileEntries = [...await fs_1.promises.readdir(directoryPath)].sort();
+        const collected = [];
+        for (const file of fileEntries) {
             const filePath = path.join(directoryPath, file);
             const fileStats = await fs_1.promises.stat(filePath);
             if (fileStats.isDirectory()) {
-                // Recursively get files from the directory
-                return this.getAllFilesInGraphQlDirectory(filePath, collectedExtensions);
-            }
-            const folderName = 'graphql';
-            if (!directoryPath.endsWith(path.sep + folderName) &&
-                !directoryPath.includes(path.sep + folderName + path.sep)) {
-                return;
-            }
-            const graphqlModule = require(filePath.replace('.js', ''));
-            if (!graphqlModule) {
-                return;
-            }
-            // Support both ES module default export and CommonJS exports
-            let extension = graphqlModule.default || graphqlModule;
-            // If the extension is a builder (has a build function), call build() automatically
-            if (extension && typeof extension.build === 'function') {
-                extension = extension.build();
-            }
-            // If it's an array, flatten and push all
-            if (Array.isArray(extension)) {
-                collectedExtensions.push(...extension.map(ext => ext.build ? ext.build() : ext));
+                collected.push(...await this.getAllFilesInGraphQlDirectory(filePath));
+                continue;
             }
-            else if (extension) {
-                collectedExtensions.push(extension);
+            if (!isInGraphQLFolder(directoryPath) || !isLoadableFile(file)) {
+                continue;
             }
-        });
-        // Wait for all the promises to resolve
-        await Promise.all(filePromises);
-        return collectedExtensions;
+            collected.push(...toExtensions(require(filePath)));
+        }
+        return collected;
     }
 });

package/dist/server/services/index.d.ts

@@ -2,7 +2,7 @@ declare const _default: {
     fileService: ({ strapi }: {
         strapi: Required<import("@strapi/types").Strapi>;
     }) => {
-        getAllFilesInGraphQlDirectory(directoryPath: string, collectedExtensions?: import("..").GraphQLExtension[]): Promise<import("..").GraphQLExtension[]>;
+        getAllFilesInGraphQlDirectory(directoryPath: string): Promise<import("..").GraphQLExtension[]>;
     };
     graphQlService: ({ strapi }: {
         strapi: Required<import("@strapi/types").Strapi>;