docs(graphql): add chapter about field middleware feature

Author: kamilmysliwiec

content/graphql/enums.md

@@ -14,51 +14,43 @@ To attach custom metadata for a field, use the `@Extensions()` decorator exporte
 password: string;
 ```
 
-In the example above, we assigned the `role` metadata property the value of `Role.ADMIN`.  `Role` is a simple TypeScript enum that groups all the user roles available in our system.
+In the example above, we assigned the `role` metadata property the value of `Role.ADMIN`. `Role` is a simple TypeScript enum that groups all the user roles available in our system.
 
 Note, in addition to setting metadata on fields, you can use the `@Extensions()` decorator at the class level and method level (e.g., on the query handler).
 
 #### Using custom metadata
 
-The logic that leverages the custom metadata can be as complex as needed. For example, you can create a simple interceptor that stores/logs events per method invocation, or create a sophisticated guard that **analyzes requested fields**, iterates through the `GraphQLObjectType` definition, and matches the roles required to retrieve specific fields with the caller permissions (field-level permissions system).
+Logic that leverages the custom metadata can be as complex as needed. For example, you can create a simple interceptor that stores/logs events per method invocation, or a [field middleware](/graphql/field-middleware) that matches roles required to retrieve a field with the caller permissions (field-level permissions system).
 
-Let's define a `FieldRolesGuard` that implements a basic version of such a field-level permissions system.
+For illustration purposes, let's define a `checkRoleMiddleware` that compares a user's role (hardcoded here) with a role required to access a target field:
 
 ```typescript
-import { CanActivate, ExecutionContext, Injectable } from '@nestjs/common';
-import { GqlExecutionContext } from '@nestjs/graphql';
-import { GraphQLNonNull, GraphQLObjectType, GraphQLResolveInfo } from 'graphql';
-import * as graphqlFields from 'graphql-fields';
-
-@Injectable()
-export class FieldRolesGuard implements CanActivate {
-  canActivate(context: ExecutionContext): boolean {
-    const info = GqlExecutionContext.create(context).getInfo<
-      GraphQLResolveInfo
-    >();
-    const returnType = (info.returnType instanceof GraphQLNonNull
-      ? info.returnType.ofType
-      : info.returnType) as GraphQLObjectType;
-
-    const fields = returnType.getFields();
-    const requestedFields = graphqlFields(info);
-
-    Object.entries(fields)
-      .filter(([key]) => key in requestedFields)
-      .map(([_, field]) => field)
-      .filter((field) => field.extensions && field.extensions.role)
-      .forEach((field) => {
-        // match user and field roles here
-        console.log(field.extensions.role);
-      });
-
-    return true;
+export const checkRoleMiddleware: FieldMiddleware = async (
+  ctx: MiddlewareContext,
+  next: NextFn,
+) => {
+  const { info } = ctx;
+  const { extensions } = info.parentType.getFields()[info.fieldName];
+
+  /**
+   * In a real-world application, the "userRole" variable
+   * should represent the caller's (user) role (for example, "ctx.user.role").
+   */
+  const userRole = Role.USER;
+  if (userRole === extensions.role) {
+    // or just "return null" to ignore
+    throw new ForbiddenException(
+      `User does not have sufficient permissions to access "${info.fieldName}" field.`,
+    );
   }
-}
+  return next();
+};
 ```
 
-> warning **Warning** For illustration purposes, we assumed that **every** resolver returns either the `GraphQLObjectType` or `GraphQLNonNull` that wraps the object type. In a real-world application, you should cover other cases (scalars, etc.). Note that using this particular implementation can lead to unexpected errors (e.g., missing `getFields()` method).
-
-In the example above, we've used the [graphql-fields](https://github.com/robrichard/graphql-fields) package that turns the `GraphQLResolveInfo` object into an object that consists of the requested fields. We used this specific library to make the presented example somewhat simpler.
+With this in place, we can register a middleware for the `password` field, as follows:
 
-With this guard in place, if the return type of any resolver contains a field annotated with the `@Extensions({{ '{' }} role: Role.ADMIN {{ '}' }}})` decorator, this `role` (`Role.ADMIN`) will be logged in the console **if requested** in the GraphQL query.
+```typescript
+@Field({ middleware: [checkRoleMiddleware] })
+@Extensions({ role: Role.ADMIN })
+password: string;
+```

content/graphql/extensions.md

@@ -0,0 +1,79 @@
+### Field middleware
+
+> warning **Warning** This chapter applies only to the code first approach.
+
+Field Middleware lets you run arbitrary code **before or after** a field is resolved. A field middleware can be used to convert the result of a field, validate the arguments of a field, or even check field-level roles (for example, required to access a target field for which a middleware function is executed).
+
+You can connect multiple middleware functions to a field. In this case, they will be called sequentially along the chain where the previous middleware decides to call the next one. The order of the middleware functions in the `middleware` array is important. The first resolver is the "most-outer" layer, so it gets executed first and last (similarly to the `graphql-middleware` package). The second resolver is the "second-outer" layer, so it gets executed second and second to last.
+
+#### Getting started
+
+Let's start off by creating a simple middleware that will log a field value before it's sent back to the client:
+
+```typescript
+import { FieldMiddleware, MiddlewareContext, NextFn } from '@nestjs/graphql';
+
+const loggerMiddleware: FieldMiddleware = async (
+  ctx: MiddlewareContext,
+  next: NextFn,
+) => {
+  const value = await next();
+  console.log(value);
+  return value;
+};
+```
+
+> info **Hint** The `MiddlewareContext` is an object that consist of the same arguments that are normally received by the GraphQL resolver function (`{{ '{' }} source, args, context, info {{ '}' }}`), while `NextFn` is a function that let you execute the next middleware in the stack (bound to this field) or the actual field resolver.
+
+> warning **Warning** Field middleware functions cannot inject dependencies nor access Nest's DI container as they are designed to be very lightweight and shouldn't perform any potentially time-consuming operations (like retrieving data from the database). If you need to call external services/query data from the data source, you should do it in a guard/interceptor bounded to a root query/mutation handler and assing it to `context` object which you can access from within the field middleware (specifically, from the `MiddlewareContext` object).
+
+Note that field middleware must match the `FieldMiddleware` interface. In the example above, we first run the `next()` function (which executes the actual field resolver and returns a field value) and then, we log this value to our terminal. Also, the value returned from the middleware function completely overrides the previous value and since we don't want to perform any changes, we simply return the original value.
+
+With this in place, we can register our middleware directly in the `@Field()` decorator, as follows:
+
+```typescript
+@ObjectType()
+export class Recipe {
+  @Field({ middleware: [loggerMiddleware] })
+  title: string;
+}
+```
+
+Now whenever we request the `title` field of `Recipe` object type, the original field's value will be logged to the console.
+
+> info **Hint** To learn how you can implement a field-level permissions system with the use of [extensions](/graphql/extensions) feature, check out this [section](/graphql/extensions#using-custom-metadata).
+
+Also, as mentioned above, we can control the field's value from within the middleware function. For demonstration purposes, let's capitalise a recipe's title (if present):
+
+```typescript
+const value = await next();
+return value?.toUpperCase();
+```
+
+In this case, every title will be automatically uppercased, when requested.
+
+Likewise, you can bind a field middleware to a custom field resolver (a method annotated with the `@ResolveField()` decorator), as follows:
+
+```typescript
+@ResolveField(() => String, { middleware: [loggerMiddleware] })
+title() {
+  return 'Placeholder';
+}
+```
+
+> warning **Warning** In case enhancers are enabled at the field resolver level ([read more](/graphl//other-features#execute-enhancers-at-the-field-resolver-level)), field middleware functions will run before any interceptors, guards, etc., **bounded to the method** (but after the root-level enhancers registered for query or mutation handlers).
+
+#### Global field middleware
+
+In addition to binding a middleware directly to a specific field, you can also register one or multiple middleware functions globally. In this case, they will be automatically connected to all fields of your object types.
+
+```typescript
+GraphQLModule.forRoot({
+  autoSchemaFile: 'schema.gql',
+  buildSchemaOptions: {
+    fieldMiddleware: [loggerMiddleware],
+  },
+}),
+```
+
+> info **Hint** Globally registered field middleware functions will be executed **before** locally registered ones (those bound directly to specific fields).