Merge branch 'feature/code-first-federation' of https://github.com/tuxmachine/docs.nestjs.com into tuxmachine-feature/code-first-federation

Author: kamilmysliwiec

content/graphql/federation.md

@@ -21,6 +21,8 @@ First install the optional dependency for federation:
 $ npm install --save @apollo/federation
 ```
 
+##### Schema first
+
 The User service has a simple schema. Note the `@key` directive: it tells the Apollo query planner that a particular instance of User can be fetched if you have its `id`. Also note that we extend the `Query` type.
 
 ```graphql
@@ -74,8 +76,76 @@ import { UsersResolvers } from './users.resolvers';
 export class AppModule {}
 ```
 
+##### Code first
+
+Code first federation is very similar to regular code first GraphQL. We simply add some extra decorators to the `User` entity.
+
+```ts
+import { Directive, Field, ID, ObjectType } from '@nestjs/graphql';
+
+@ObjectType()
+@Directive('@key(fields: "id")')
+export class User {
+  @Field(type => ID)
+  public id: number;
+
+  @Field()
+  public name: string;
+
+  constructor(user: Partial<User>) {
+    Object.assign(this, user);
+  }
+}
+```
+
+Our resolver has one extra method: `resolveReference`. It's called by the Apollo Gateway whenever a related resource requires a `User` instance. We'll see an example of this in the Posts service later on. Please note the `@ResolveReference` decorator.
+
+```ts
+import { Args, Query, Resolver, ResolveReference } from '@nestjs/graphql';
+import { User } from './user.entity';
+import { UsersService } from './users.service';
+
+@Resolver(of => User)
+export class UsersResolvers {
+  constructor(private usersService: UsersService) {}
+
+  @Query(returns => User)
+  getUser(@Args('id') id: number): User {
+    return this.usersService.findById(id);
+  }
+
+  @ResolveReference()
+  resolveReference(reference: { __typename: string; id: number }): User {
+    return this.usersService.findById(reference.id);
+  }
+}
+```
+
+Finally, we hook everything up in a module together with a `GraphQLFederationModule`. This module accepts the same options as the regular `GraphQLModule`.
+
+```typescript
+import { Module } from '@nestjs/common';
+import { GraphQLFederationModule } from '@nestjs/graphql';
+import { UsersResolvers } from './users.resolvers';
+import { UsersService } from './users.service'; // Not included in this example
+
+@Module({
+  imports: [
+    GraphQLFederationModule.forRoot({
+      autoSchemaFile: true,
+    }),
+  ],
+  providers: [UsersResolvers, UsersService],
+})
+export class AppModule {}
+```
+
 #### Federated example: Posts
 
+Our Post service serves aggregated posts via a `getPosts` query, but also extends our `User` type with `user.posts`
+
+##### Schema first
+
 The Posts service references the User type in its schema by marking it with the `extend` keyword. It also adds one property to the User type. Note the `@key` directive used for matching instances of User, and the `@external` directive indicating that the `id` field is managed elsewhere.
 
 ```graphql
@@ -99,7 +169,7 @@ extend type Query {
 Our resolver has one method of interest here: `getUser`. It returns a reference containing `__typename` and any additional properties your application needs to resolve the reference, in this case only an `id`. The `__typename` is used by the GraphQL Gateway to pinpoint the microservice responsible for the User type and request the instance. The Users service discussed above will be called on the `resolveReference` method.
 
 ```typescript
-import { Query, Resolver, Parent, ResolveProperty } from '@nestjs/graphql';
+import { Query, Resolver, Parent, ResolveField } from '@nestjs/graphql';
 import { PostsService } from './posts.service';
 import { Post } from './posts.interfaces';
 
@@ -112,7 +182,7 @@ export class PostsResolvers {
     return this.postsService.findAll();
   }
 
-  @ResolveProperty('user')
+  @ResolveField('user')
   getUser(@Parent() post: Post) {
     return { __typename: 'User', id: post.userId };
   }
@@ -137,11 +207,135 @@ import { PostsResolvers } from './posts.resolvers';
 export class AppModule {}
 ```
 
+##### Code first
+
+We will need to create a class representing our `User` entity. Even though it lives in another service, we will be using and extending it. Note the `@extends` and `@external` directives.
+
+```ts
+import { Directive, ObjectType, Field, ID } from '@nestjs/graphql';
+import { Post } from './post.entity';
+
+@ObjectType()
+@Directive('@extends')
+@Directive('@key(fields: "id")')
+export class User {
+  @Field(type => ID)
+  @Directive('@external')
+  public id: number;
+
+  @Field(type => [Post])
+  public posts?: Post[];
+
+  constructor(user: Partial<User>) {
+    Object.assign(this, user);
+  }
+}
+```
+
+We create the resolver for our extension on the `User` entity as follows:
+
+```ts
+import { Parent, ResolveField, Resolver } from '@nestjs/graphql';
+import { PostsService } from './posts.service';
+import { Post } from './post.entity';
+import { User } from './user.entity';
+
+@Resolver(of => User)
+export class UsersResolvers {
+  constructor(private readonly postsService: PostsService) {}
+
+  @ResolveField(of => [Post])
+  public posts(@Parent() user: User): Post[] {
+    return this.postsService.forAuthor(user.id);
+  }
+}
+```
+
+We also need to create our `Post` entity:
+
+```ts
+import { Directive, Field, ID, Int, ObjectType } from '@nestjs/graphql';
+import { User } from './user.entity';
+
+@ObjectType()
+@Directive('@key(fields: "id")')
+export class Post {
+  @Field(type => ID)
+  public id: number;
+
+  @Field()
+  public title: string;
+
+  @Field(type => Int)
+  public authorId: number;
+
+  @Field(type => User)
+  public user?: User;
+
+  constructor(post: Partial<Post>) {
+    Object.assign(this, post);
+  }
+}
+```
+
+And its resolver:
+
+```ts
+import { Query, Args, ResolveField, Resolver, Parent } from '@nestjs/graphql';
+import { PostsService } from './posts.service';
+import { Post } from './post.entity';
+import { User } from './user.entity';
+
+@Resolver(of => Post)
+export class PostsResolvers {
+  constructor(private readonly postsService: PostsService) {}
+
+  @Query(returns => Post)
+  public findPost(@Args('id') id: number): Post {
+    return this.postsService.findOne(id);
+  }
+
+  @Query(returns => [Post])
+  public getPosts(): Post[] {
+    return this.postsService.all();
+  }
+
+  @ResolveField(of => User)
+  public user(@Parent() post: Post): any {
+    return { __typename: 'User', id: post.authorId };
+  }
+}
+```
+
+And finally tie it together in a module. Note the schema build options, where we specify that `User` is an outside type.
+
+```ts
+import { Module } from '@nestjs/common';
+import { GraphQLFederationModule } from '@nestjs/graphql';
+import { User } from './user.entity';
+import { PostsResolvers } from './posts.resolvers';
+import { UsersResolvers } from './users.resolvers';
+import { PostsService } from './posts.service'; // Not included in example
+
+@Module({
+  imports: [
+    GraphQLFederationModule.forRoot({
+      autoSchemaFile: true,
+      buildSchemaOptions: {
+        orphanedTypes: [User],
+      },
+    }),
+  ],
+  providers: [PostsResolvers, UsersResolvers, PostsService],
+})
+export class AppModule {}
+```
+
 #### Federated example: Gateway
 
 First install the optional dependency for the gateway: `npm install --save @apollo/gateway`.
 
-Our gateway only needs a list of endpoints and will auto-discover the schemas from there. The code for our gateway is therefore very short:
+Our gateway only needs a list of endpoints and will auto-discover the schemas from there. Therefore it is the same for code and schema first, and the code for our gateway is very short:
 
 ```typescript
 import { Module } from '@nestjs/common';