buro26-strapi-graphql 0.1.0 → 0.3.0

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

@@ -1,19 +1,34 @@
 import type { FieldExtensionBuilder, FieldGroupPreset, GraphQLFieldPreset } from './types';
 import type { Middleware } from '../../nexus';
 /**
- * Parse argument definitions into Nexus-compatible args.
+ * Middleware that throws a `ForbiddenError` ("Not authenticated") when there is no `ctx.state.user`.
+ *
+ * @deprecated Use `.withAuth(true)` on the field builder; it is checked before authorization runs.
  */
-export declare function parseArgs(args: Record<string, string | unknown>): Record<string, unknown>;
+export declare function makeAuthMiddleware(): Middleware;
 /**
- * Middleware that throws if the user is not authenticated.
+ * Define a reusable preset for `.use()`. Identity function that exists for typing and readability.
+ *
+ * @example
+ * export const adminOnly = createGraphQLFieldPreset((builder) =>
+ *   builder.withAuth(true).authorize((_p, _a, ctx) => ctx.state.user?.role?.type === 'admin')
+ * )
+ *
+ * createGraphQLFieldBuilder().use(adminOnly).rootType('Query') // ...
  */
-export declare function makeAuthMiddleware(): Middleware;
 export declare function createGraphQLFieldPreset(preset: GraphQLFieldPreset): GraphQLFieldPreset;
 /**
- * Combine multiple field builders into a single GraphQL extension.
+ * Export several fields from one file. Builds each builder and returns the extensions.
+ *
+ * @example
+ * export default registerFields(fieldA, fieldB)
  */
 export declare function registerFields(...fields: FieldExtensionBuilder[]): import("../..").GraphQLExtension[];
 /**
- * Apply one or more presets to a group of fields.
+ * Apply presets to every field in a group (e.g. one auth rule for all fields of a feature).
+ * Presets are applied in order. Returns unbuilt builders; export them with {@link registerFields}.
+ *
+ * @example
+ * export default registerFields(...createFieldGroup([fieldA, fieldB], requireUser))
  */
 export declare function createFieldGroup(fields: FieldExtensionBuilder[], ...presets: FieldGroupPreset[]): FieldExtensionBuilder[];

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

@@ -4,7 +4,10 @@ exports.createFieldGroup = exports.registerFields = exports.createGraphQLFieldPr
 const nexus_1 = require("nexus");
 const utils_1 = require("@strapi/utils");
 /**
- * Parse argument definitions into Nexus-compatible args.
+ * Convert an args map with type strings (`'String!'`, `'[ID]'`) into Nexus args.
+ * Non-string values (e.g. `arg({ type: 'X' })`) are passed through unchanged.
+ *
+ * @internal Used by `.args()`.
  */
 function parseArgs(args) {
     const nexusArgs = {};
@@ -23,7 +26,9 @@ function parseArgs(args) {
 }
 exports.parseArgs = parseArgs;
 /**
- * Middleware that throws if the user is not authenticated.
+ * Middleware that throws a `ForbiddenError` ("Not authenticated") when there is no `ctx.state.user`.
+ *
+ * @deprecated Use `.withAuth(true)` on the field builder; it is checked before authorization runs.
  */
 function makeAuthMiddleware() {
     return (next) => async (root, args, context, info) => {
@@ -36,19 +41,36 @@ function makeAuthMiddleware() {
     };
 }
 exports.makeAuthMiddleware = makeAuthMiddleware;
+/**
+ * Define a reusable preset for `.use()`. Identity function that exists for typing and readability.
+ *
+ * @example
+ * export const adminOnly = createGraphQLFieldPreset((builder) =>
+ *   builder.withAuth(true).authorize((_p, _a, ctx) => ctx.state.user?.role?.type === 'admin')
+ * )
+ *
+ * createGraphQLFieldBuilder().use(adminOnly).rootType('Query') // ...
+ */
 function createGraphQLFieldPreset(preset) {
     return preset;
 }
 exports.createGraphQLFieldPreset = createGraphQLFieldPreset;
 /**
- * Combine multiple field builders into a single GraphQL extension.
+ * Export several fields from one file. Builds each builder and returns the extensions.
+ *
+ * @example
+ * export default registerFields(fieldA, fieldB)
  */
 function registerFields(...fields) {
     return fields.map(builder => builder.build());
 }
 exports.registerFields = registerFields;
 /**
- * Apply one or more presets to a group of fields.
+ * Apply presets to every field in a group (e.g. one auth rule for all fields of a feature).
+ * Presets are applied in order. Returns unbuilt builders; export them with {@link registerFields}.
+ *
+ * @example
+ * export default registerFields(...createFieldGroup([fieldA, fieldB], requireUser))
  */
 function createFieldGroup(fields, ...presets) {
     return fields.map(field => presets.reduce((acc, preset) => preset(acc), field));

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

@@ -1,160 +1,381 @@
 import type { GraphQLResolveInfo } from 'graphql';
-import type { ZodSchema, ZodTypeAny } from 'zod';
+import type { output, ZodTypeAny } from 'zod';
 import type { ResolverConfigOption, ResolverFunction } from '../../types';
 import type { Middleware } from '../../nexus';
 import type { createGraphQLExtension } from '../graphql-extension';
-import type { ResolveContext } from '../types';
+import type { ParentOf, ResolveContext } from '../types';
 /**
- * Options for configuring a GraphQL field extension.
+ * The `parent` value resolvers, authorize functions and middlewares receive.
+ *
+ * - Untyped builders (`Type` is `any`, e.g. `Query`/`Mutation` fields): `any`.
+ * - Entity types with an `id` (e.g. registered via {@link Register} `types`): `Partial<Type>` with `id`
+ *   required. Strapi always passes the entity, but relations are only present when populated.
+ * - Other types: `Partial<Type> | null`.
  */
-export type FieldExtensionOptions<Type = any, TArgs = any, TOutput = Type> = {
-    rootType: string;
-    fieldName?: string;
-    description?: string;
-    deprecationReason?: string;
-    init?: () => void;
-    resolver?: ResolverFunction<Partial<Type> | null, TArgs, Partial<TOutput> | null>;
-    resolverConfig: ResolverConfigOption<Partial<Type> | null, TArgs, Partial<TOutput> | null>;
-    typeDefs?: string;
-    types?: (() => unknown[]) | unknown[];
-    args?: Record<string, string | unknown>;
-    validateArgsSchema?: ZodSchema<any> | ZodTypeAny;
-    outputType?: string | unknown;
-    auth?: boolean;
-    tags?: string[];
-    traceHandlers?: Array<(info: {
-        type: string;
-        fieldName: string;
-        durationMs: number;
-        args: any;
-        context: any;
-        result: any;
-        error?: any;
-    }) => void>;
+export type FieldParent<Type> = 0 extends (1 & Type) ? any : Type extends {
+    id: infer Id;
+} ? Partial<Type> & {
+    id: Id;
+} : Partial<Type> | null;
+/**
+ * TypeScript types for GraphQL scalar names used in `.args()` type strings.
+ * Unknown names (custom scalars, input types) map to `unknown`.
+ */
+export type GraphQLScalarTypes = {
+    String: string;
+    ID: string | number;
+    Int: number;
+    Float: number;
+    Long: number;
+    Boolean: boolean;
+    Date: string;
+    DateTime: string;
+    Time: string;
+    JSON: unknown;
+};
+type ParseNonNullArg<S extends string> = S extends `[${infer Item}]` ? Array<ParseArgType<Item>> : S extends keyof GraphQLScalarTypes ? GraphQLScalarTypes[S] : unknown;
+/** TypeScript type for a GraphQL type string such as `'String!'`, `'[ID!]'` or `'Int'`. */
+export type ParseArgType<S extends string> = S extends `${infer Inner}!` ? ParseNonNullArg<Inner> : ParseNonNullArg<S> | null;
+type RequiredArgKeys<A> = {
+    [K in keyof A]: A[K] extends `${string}!` ? K : never;
+}[keyof A];
+/**
+ * Argument types for an `.args()` map, for typing a builder explicitly. Non-null (`!`) arguments are
+ * required; others optional. Non-string definitions (e.g. Nexus `arg()`) are `unknown`.
+ *
+ * @example
+ * type A = InferArgs<{ id: 'ID!'; limit: 'Int' }> // { id: string | number; limit?: number | null }
+ */
+export type InferArgs<A> = {
+    [K in Extract<keyof A, RequiredArgKeys<A>>]: A[K] extends string ? ParseArgType<A[K]> : unknown;
+} & {
+    [K in Exclude<keyof A, RequiredArgKeys<A>>]?: A[K] extends string ? ParseArgType<A[K]> : unknown;
+};
+/**
+ * Information passed to a trace handler after a field resolved (or failed).
+ *
+ * @see {@link FieldExtensionBuilder.trace}
+ */
+export type FieldTraceInfo = {
+    /** GraphQL parent type name, e.g. `Query` */
+    type: string;
+    fieldName: string;
+    /** Wall-clock duration of the resolver, in milliseconds */
+    durationMs: number;
+    args: any;
+    context: any;
+    /** The resolved value; `undefined` when the resolver threw */
+    result: any;
+    /** The thrown error, if any */
+    error?: any;
 };
 /**
- * Fluent builder for extending a root field in the GraphQL schema.
- * All methods return a new builder instance (immutable).
+ * Handler that receives {@link FieldTraceInfo}. Runs asynchronously after the resolver and never affects
+ * the response; errors thrown by a handler are logged and swallowed.
+ */
+export type FieldTraceHandler = (info: FieldTraceInfo) => void;
+/**
+ * Relation configuration set by {@link FieldExtensionBuilder.relation}.
+ */
+export type RelationOptions = {
+    /** Content type UID that owns the relation, e.g. `api::order.order` */
+    contentType: string;
+    /** Relation attribute name on that content type, e.g. `customer` */
+    attribute: string;
+    /**
+     * 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. Works for to-one and to-many relations; a to-many field returns the same relation
+     * response collection as Strapi.
+     *
+     * 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}
+     */
+    batch?: boolean;
+};
+/**
+ * Fluent, immutable builder for one GraphQL field. Every method returns a **new** builder, so a
+ * partially configured builder can be shared as a base for several fields.
+ *
+ * A field needs at least {@link FieldExtensionBuilder.rootType | rootType},
+ * {@link FieldExtensionBuilder.fieldName | fieldName}, {@link FieldExtensionBuilder.outputType | outputType}
+ * and {@link FieldExtensionBuilder.resolver | resolver} — or `rootType` plus
+ * {@link FieldExtensionBuilder.relation | relation}.
+ *
+ * Export the builder (or an array via `registerFields`) as the default export of a file in a `graphql`
+ * folder; the plugin calls {@link FieldExtensionBuilder.build | build} for you.
+ *
+ * @typeParam Type - Parent value the resolver receives. Inferred from {@link Register} `types` when
+ *   `rootType` is a registered type name.
+ * @typeParam TArgs - Field arguments.
+ * @typeParam TOutput - Resolved value.
+ *
+ * @example
+ * export default createGraphQLFieldBuilder()
+ *   .rootType('Query')
+ *   .fieldName('hello')
+ *   .args({ name: 'String!' })
+ *   .outputType('String')
+ *   .withAuth(true)
+ *   .resolver((_parent, { name }) => `Hello ${name}`)
+ *
+ * @see https://gitlab.com/buro26/public/strapi/strapi-graphql-extension#-recommended-the-field-builder-pattern
  */
 export interface FieldExtensionBuilder<Type = any, TArgs = any, TOutput = Type> {
     /**
-     * Set the root type to extend (e.g., 'Query', 'Mutation').
+     * Set the GraphQL type the field is added to: `Query`, `Mutation` or any object type such as a
+     * content type (`Customer`).
+     *
+     * When `type` is registered in {@link Register} `types`, the resolver's `parent` is typed accordingly.
+     *
+     * @param type - GraphQL type name.
+     * @throws Error when the root type was already set (e.g. by `createGraphQLFieldBuilder('Query')`).
      */
-    rootType(type: string): FieldExtensionBuilder<Type, TArgs, TOutput>;
+    rootType<N extends string>(type: N): FieldExtensionBuilder<ParentOf<N, Type>, TArgs, TOutput>;
     /**
-     * Set the name of the field to add/extend.
+     * 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
+     * `.authorize()`, `.middleware()` or presets to protect or extend the relation.
+     *
+     * | | v4 | v5 |
+     * |---|---|---|
+     * | to-one | `XEntityResponse` | `X` |
+     * | to-many | `XRelationResponseCollection` | `[X]!` and `<attribute>_connection` |
+     *
+     * 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 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 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>;
+    /**
+     * Set the field name. Use the name of an existing field to replace it.
+     *
+     * @throws Error when the field name was already set (also by `.relation()`).
      */
     fieldName(name: string): FieldExtensionBuilder<Type, TArgs, TOutput>;
     /**
-     * Add a description for this field (for schema docs and IDE hints).
+     * Description shown in the GraphQL schema, GraphiQL and IDE hints.
      */
     description(text: string): FieldExtensionBuilder<Type, TArgs, TOutput>;
     /**
-     * Mark this field as deprecated with a reason.
+     * Mark the field as deprecated in the schema.
+     *
+     * @param reason - Shown to API consumers; mention the replacement.
      */
     deprecate(reason: string): FieldExtensionBuilder<Type, TArgs, TOutput>;
     /**
-     * Register a function to be called when the extension is initialized.
+     * Run a function once when the plugin registers the field (Strapi's `register` phase), e.g. to
+     * configure shadow CRUD. Can be called multiple times; functions run in order.
      */
     init(fn: () => void): FieldExtensionBuilder<Type, TArgs, TOutput>;
     /**
-     * Set the resolver function for the field.
+     * Set the resolver. It runs inside the authorization and middlewares, after argument validation and
+     * `beforeResolve` hooks.
+     *
+     * @throws Error when a resolver was already set.
      */
-    resolver(fn: ResolverFunction<Partial<Type> | null, TArgs, Partial<TOutput> | null | any>): FieldExtensionBuilder<Type, TArgs, TOutput>;
+    resolver(fn: ResolverFunction<FieldParent<Type>, TArgs, Partial<TOutput> | null | any>): FieldExtensionBuilder<Type, TArgs, TOutput>;
     /**
-     * Set resolver config (policies, middlewares, etc).
-     * Only supported for Query and Mutation root types.
+     * Strapi resolver config (policies, Strapi middlewares, `auth`). Merged with earlier calls.
+     * Only applies to `Query` and `Mutation` fields; for other types use `.authorize()` / `.middleware()`.
+     *
+     * @deprecated Use {@link FieldExtensionBuilder.withAuth | withAuth} for authentication and
+     *   {@link FieldExtensionBuilder.authorize | authorize} / {@link FieldExtensionBuilder.middleware | middleware}
+     *   for the rest; they work on every type and run in a defined order.
+     * @see https://docs.strapi.io/dev-docs/plugins/graphql#customization
      */
-    resolverConfig(config: (() => ResolverConfigOption<Type, TArgs, TOutput>) | ResolverConfigOption<Type, TArgs, TOutput>): FieldExtensionBuilder;
+    resolverConfig(config: (() => ResolverConfigOption<Type, TArgs, TOutput>) | ResolverConfigOption<Type, TArgs, TOutput>): FieldExtensionBuilder<Type, TArgs, TOutput>;
     /**
-     * Add a middleware function for the field.
+     * Wrap the resolver. Middlewares receive `next` and return a resolver; call `next` to continue.
+     * Field middlewares run after global middlewares and before `protectFields` middlewares.
+     *
+     * @example
+     * .middleware((next) => async (parent, args, ctx, info) => {
+     *   const result = await next(parent, args, ctx, info)
+     *   return result ?? fallback
+     * })
      */
-    middleware(middleware: Middleware<Partial<Type> | null, TArgs>): FieldExtensionBuilder<Type, TArgs, TOutput>;
+    middleware(middleware: Middleware<FieldParent<Type>, TArgs>): FieldExtensionBuilder<Type, TArgs, TOutput>;
     /**
-     * Add SDL type definitions for the field.
+     * Add SDL type definitions needed by this field (e.g. its output type). Appended to earlier calls.
+     * Prefer {@link FieldExtensionBuilder.types | types} with Nexus for type-safe definitions.
      */
     typeDefs(sdl: string): FieldExtensionBuilder<Type, TArgs, TOutput>;
     /**
-     * Add additional Nexus types if needed.
+     * Add Nexus types needed by this field (object types, input types, enums). Appended to earlier calls.
      */
     types(typesFn: (() => unknown[]) | unknown[]): FieldExtensionBuilder<Type, TArgs, TOutput>;
     /**
-     * Set the arguments for the field.
+     * Set the field arguments. Replaces earlier calls.
+     *
+     * This does not change the resolver's `args` type. Type them with {@link FieldExtensionBuilder.validateArgs}
+     * (inferred from the schema), or explicitly with {@link InferArgs}:
+     * `createGraphQLFieldBuilder<unknown, InferArgs<typeof args>>()`.
+     *
+     * @param a - Map of argument name to a type string (`'String!'`, `'ID'`) or a Nexus `arg()`.
      */
     args(a: Record<string, string | unknown>): FieldExtensionBuilder<Type, TArgs, TOutput>;
     /**
-     * Validate arguments using a Zod schema.
+     * Validate (and parse) arguments with Zod before the resolver runs. The resolver receives the parsed
+     * value. Invalid arguments throw a Strapi `ValidationError` ("Invalid arguments") with the `ZodError`
+     * as `cause`.
+     *
+     * When the builder has no explicit `TArgs`, the resolver's `args` are typed as the schema's output.
+     *
+     * @example
+     * .args({ id: 'ID!', limit: 'Int' })
+     * .validateArgs(z.object({ id: z.coerce.number(), limit: z.number().default(10) }))
+     * .resolver((_parent, { id, limit }) => ...) // id: number, limit: number
      */
-    validateArgs(schema: ZodSchema<TArgs> | ZodTypeAny): FieldExtensionBuilder<Type, TArgs, TOutput>;
+    validateArgs<S extends ZodTypeAny>(schema: S): FieldExtensionBuilder<Type, 0 extends (1 & TArgs) ? output<S> : TArgs, TOutput>;
     /**
-     * Set the output type for the field.
+     * Set the GraphQL output type: a type name (`'String'`, `'CustomerEntityResponse'`) or a Nexus wrapper
+     * (`nonNull('Boolean')`, `list('Customer')`). Not needed with {@link FieldExtensionBuilder.relation | relation}.
      */
     outputType(type: string | unknown): FieldExtensionBuilder<Type, TArgs, TOutput>;
     /**
-     * Make authentication mandatory/optional for the field.
+     * Require an authenticated user. Checked before any authorization runs; unauthenticated requests get a
+     * `ForbiddenError` ("Not authenticated"). For `Query`/`Mutation` fields this also sets Strapi's
+     * resolver `auth` option.
+     *
+     * @default false
      */
     withAuth(auth: boolean): FieldExtensionBuilder<Type, TArgs, TOutput>;
     /**
-     * Add additional authorization logic to the field.
+     * Add an authorization check. All checks (global, field and `protectFields`) must return `true`;
+     * return `false` for a generic "Not authorized" or an `Error` to send that error to the client.
+     * Checks run in order and stop at the first failure.
+     *
+     * @example
+     * .authorize((parent, _args, ctx) => parent?.user?.id === ctx.state.user?.id)
      */
-    authorize(authorizeFn: ResolverFunction<Partial<Type> | null, TArgs, Partial<TOutput> | null | any>): FieldExtensionBuilder<Type, TArgs, TOutput>;
+    authorize(authorizeFn: ResolverFunction<FieldParent<Type>, TArgs, Partial<TOutput> | null | any>): FieldExtensionBuilder<Type, TArgs, TOutput>;
     /**
-     * Add a tag to this field.
+     * Add a tag. Tags let global middleware/authorization target groups of fields.
+     *
+     * @see {@link registerGlobalAuthorize}
+     * @see {@link registerGlobalMiddleware}
      */
     tag(tag: string): FieldExtensionBuilder<Type, TArgs, TOutput>;
     /**
-     * Add multiple tags to this field.
+     * Add several tags at once.
+     *
+     * @see {@link FieldExtensionBuilder.tag}
      */
     tags(tags: string[]): FieldExtensionBuilder<Type, TArgs, TOutput>;
     /**
-     * Apply a preset or extension to this builder.
-     * A preset is a function that takes a builder and returns a builder.
+     * Apply a preset: a function that takes a builder and returns a configured builder. Use presets for
+     * reusable auth, feature flags or tags.
+     *
+     * @see {@link createGraphQLFieldPreset}
      */
     use(preset: (builder: FieldExtensionBuilder) => FieldExtensionBuilder<Type, TArgs, TOutput>): FieldExtensionBuilder<Type, TArgs, TOutput>;
     /**
-     * Attach a hook to this field.
+     * Add `beforeResolve` / `afterResolve` hooks. They run inside the middlewares, around the resolver;
+     * hooks are awaited and can throw to abort the request.
      */
-    hook(hook: GraphQLFieldHook<Type, TArgs>): FieldExtensionBuilder<Type, TArgs, TOutput>;
+    hook(hook: GraphQLFieldHook<FieldParent<Type>, TArgs>): FieldExtensionBuilder<Type, TArgs, TOutput>;
     /**
-     * Validate the builder configuration. Throws if invalid.
+     * Check that the configuration is complete. Called by `build()` and `test()`.
+     *
+     * @throws ApplicationError when `rootType` or `fieldName` is missing, `outputType`/`resolver` is missing
+     *   on a non-relation field, or resolver config policies/middlewares are used outside `Query`/`Mutation`.
      */
     validate(): void;
     /**
-     * Describe the current builder configuration.
+     * Snapshot of the configuration, for debugging and documentation tooling. The shape is not stable.
      */
     describe(): unknown;
     /**
-     * Test the field's resolver (and optionally middleware/auth) in isolation.
+     * Run the field in isolation with the same pipeline as in production: `withAuth`, global and field
+     * authorization, `protectFields` checks, middlewares, argument validation, hooks and tracing.
+     *
+     * @returns The resolved value.
+     * @throws ForbiddenError when authentication or authorization fails (unless `skipAuth`).
+     * @throws ApplicationError for relation fields without a custom resolver (they need a running Strapi).
+     *
+     * @example
+     * await expect(field.test({ context: { state: {} } })).rejects.toThrow('Not authenticated')
      */
     test(params: {
-        parent?: Partial<Type> | null;
-        args?: TArgs;
-        context?: ResolveContext;
+        parent?: FieldParent<Type>;
+        /** Raw arguments, as a client sends them (before `validateArgs` parsing) */
+        args?: TArgs | Record<string, unknown>;
+        /** Resolver context; set `state.user` to simulate a logged-in user */
+        context?: Partial<ResolveContext> | Record<string, unknown>;
+        /** Defaults to a minimal object with `fieldName` and `parentType.name` */
         info?: GraphQLResolveInfo;
+        /**
+         * Skip all middlewares (global and field-level).
+         * @default false
+         */
         skipMiddleware?: boolean;
+        /**
+         * Skip authentication and all authorization (global and field-level).
+         * @default false
+         */
         skipAuth?: boolean;
     }): Promise<any>;
     /**
-     * Add a trace/profiling handler for this field.
-     * Multiple handlers can be registered.
+     * Log or collect timing information for each resolve. Can be called multiple times.
+     *
+     * @param handler - Defaults to a coloured console table.
      */
-    trace(handler?: (info: {
-        type: string;
-        fieldName: string;
-        durationMs: number;
-        args: any;
-        context: any;
-        result: any;
-        error?: any;
-    }) => void): FieldExtensionBuilder<Type, TArgs, TOutput>;
+    trace(handler?: FieldTraceHandler): FieldExtensionBuilder<Type, TArgs, TOutput>;
     /**
-     * Build the extension for registration.
+     * Build the GraphQL extension. Called by the plugin for default exports in `graphql` folders, so you
+     * normally don't call this yourself. A builder can only be built once.
+     *
+     * @throws ApplicationError when the builder was already built or {@link FieldExtensionBuilder.validate | validate} fails.
      */
     build(): ReturnType<typeof createGraphQLExtension>;
 }
+/**
+ * A reusable function that configures a field builder.
+ *
+ * @see {@link createGraphQLFieldPreset}
+ */
 export type GraphQLFieldPreset = (builder: FieldExtensionBuilder) => FieldExtensionBuilder;
+/**
+ * Hooks around a field resolver. Both are awaited; throwing aborts the resolve.
+ */
 export type GraphQLFieldHook<TParent = any, TArgs = any> = {
+    /** Runs after argument validation, before the resolver */
     beforeResolve?: (parent: TParent, args: TArgs, context: ResolveContext, info: GraphQLResolveInfo) => void | Promise<void>;
-    afterResolve?: (result: any, parent: TArgs, args: TArgs, context: ResolveContext, info: GraphQLResolveInfo) => void | Promise<void>;
+    /** Runs after the resolver succeeded, with its result */
+    afterResolve?: (result: any, parent: TParent, args: TArgs, context: ResolveContext, info: GraphQLResolveInfo) => void | Promise<void>;
 };
+/**
+ * A preset applied to every field of a group.
+ *
+ * @see {@link createFieldGroup}
+ */
 export type FieldGroupPreset<TContext = any, TArgs = any> = (builder: FieldExtensionBuilder<TContext, TArgs>) => FieldExtensionBuilder<TContext, TArgs>;
+export {};

package/dist/server/utils/graphql-extension.d.ts

@@ -1,4 +1,5 @@
 import type { GraphQLExtension, ResolverConfigOption, ResolverFunction, Strapi } from '../types';
+import { GraphQLFieldPreset } from './field-builder';
 type ResolversObject = {
     Query?: Record<string, ResolverFunction>;
     Mutation?: Record<string, ResolverFunction>;
@@ -21,10 +22,30 @@ interface GraphQLExtensionBuilder {
     build(): GraphQLExtension;
 }
 /**
- * Overloaded createGraphQLExtension:
- * - When called with no arguments, returns a new builder.
- * - When called with a factory function returns a GraphQLExtension.
+ * Create a full GraphQL extension: custom types, SDL, resolvers, Nexus plugins and resolver config.
+ *
+ * Use it when you need control over the whole extension, e.g. shared type bundles, full type overrides,
+ * Nexus plugins or shadow CRUD changes. For the common cases there are more focused APIs: fields with
+ * {@link createGraphQLFieldBuilder}, access to generated fields with {@link protectFields} and relations
+ * with {@link FieldExtensionBuilder.relation}.
+ *
+ * - Without arguments: returns a fluent builder (`.types()`, `.resolvers()`, ... then `.build()`).
+ * - With a factory: calls it with `strapi` and returns the {@link GraphQLExtension}.
+ *
+ * @example
+ * export default createGraphQLExtension((strapi) => ({
+ *   types: () => [objectType({ name: 'Stats', definition: (t) => t.int('total') })],
+ * }))
  */
 export declare function createGraphQLExtension(): GraphQLExtensionBuilder;
 export declare function createGraphQLExtension(extension: ((strapi: Strapi) => GraphQLExtension)): GraphQLExtension;
+/**
+ * Maps a field-level preset to all (or matching) fields in a GraphQLExtension.
+ * Throws if a field is not a function (i.e., not a resolver).
+ *
+ * @param fieldPreset - a GraphQLFieldPreset (FieldExtensionBuilder => FieldExtensionBuilder)
+ * @param matcher - a function (type, fieldName) => boolean or an array of field names
+ * @returns a function that takes a GraphQLExtension and returns a new one with wrapped resolvers
+ */
+export declare function mapFieldPresetToExtension(fieldPreset: GraphQLFieldPreset, matcher?: ((type: string, fieldName: string) => boolean) | string[]): (extension: GraphQLExtension) => GraphQLExtension;
 export {};