Merge branch 'feat/mapped-types-generator' of https://github.com/nestjs/docs.nestjs.com into biundo/graphql-mapped-types

Author: johnbiundo

content/graphql/mapped-types.md

@@ -0,0 +1,107 @@
+### Mapped types
+
+##### This chapter applies only to code first approach
+
+A common task is to take an existing type and make each of its properties optional. This happens often enough that NestJS provides a way to create new types based on old types — mapped types.
+
+#### Partial
+
+Make all properties of a type optional.
+
+Original type:
+
+```typescript
+@InputType()
+class CreateUserInput {
+  @Field()
+  email: string;
+
+  @Field()
+  password: string;
+
+  @Field()
+  firstName: string;
+}
+```
+
+Mapped type:
+
+```typescript
+@InputType()
+export class UpdateUserInput extends PartialType(CreateUserInput) {}
+```
+
+> info **Hint** The `PartialType()` function is imported from the `@nestjs/graphql` package.
+
+> warning **Warning** If you want to create an `InputType` based on the `ObjectType`, you must explicitly specify it in the function, as follows: `PartialType(CreateUserInput, InputType)` where `InputType` is a reference to a decorator factory.
+
+#### Pick
+
+Constructs a type by picking the set of properties from type.
+
+Original type:
+
+```typescript
+@InputType()
+class CreateUserInput {
+  @Field()
+  email: string;
+
+  @Field()
+  password: string;
+
+  @Field()
+  firstName: string;
+}
+```
+
+Mapped type:
+
+```typescript
+@InputType()
+export class UpdateEmailInput extends PickType(CreateUserInput, ['email']) {}
+```
+
+> info **Hint** The `PickType()` function is imported from the `@nestjs/graphql` package.
+
+#### Pick
+
+Constructs a type by picking all properties from type and then removing particular set of keys.
+
+Original type:
+
+```typescript
+@InputType()
+class CreateUserInput {
+  @Field()
+  email: string;
+
+  @Field()
+  password: string;
+
+  @Field()
+  firstName: string;
+}
+```
+
+Mapped type:
+
+```typescript
+@InputType()
+export class UpdateUserInput extends OmitType(CreateUserInput, ['email']) {}
+```
+
+> info **Hint** The `PickType()` function is imported from the `@nestjs/graphql` package.
+
+#### Composition
+
+Mapped types are composeable.
+
+Example:
+
+```typescript
+@InputType()
+export class UpdateUserInput extends Partial(
+  OmitType(CreateUserInput, ['email']),
+) {}
+```

content/graphql/mutations.md

@@ -50,6 +50,8 @@ async upvotePost(
 ) {}
 ```
 
+// Should we add note about Inheritance here? (input types inheritance)
+
 #### Schema first
 
 Let's extend our `AuthorResolver` used in the previous section (see [resolvers](/graphql/resolvers)).

content/graphql/quick-start.md

@@ -171,6 +171,16 @@ definitionsFactory.generate({
 
 A fully working schema first sample is available [here](https://github.com/nestjs/nest/tree/master/sample/12-graphql-schema-first).
 
+#### Accessing generated schema
+
+To access the generated schema (in either code first or schema first approach), use the `GraphQLHost` class:
+
+```typescript
+const { schema } = app.get(GraphQLSchemaHost);
+```
+
+> info **Hint** Make sure to call the `GraphQLSchemaHost#schema` getter when the application is already initialized (after the `onModuleInit` hook triggered by either `app.listen()` or `app.init()` method.
+
 #### Async configuration
 
 When you need to pass module options asynchronously instead of statically, use the `forRootAsync()` method. As with most dynamic modules, Nest provides several techniques to deal with async configuration.

content/graphql/resolvers-map.md

@@ -306,6 +306,133 @@ type Query {
 
 > info **Hint** Note that arguments classes like `GetAuthorArgs` play very well with the `ValidationPipe` (read [more](/techniques/validation)).
 
+#### Class inheritance
+
+Args:
+
+```typescript
+@ArgsType()
+class PaginationArgs {
+  @Field(type => Int)
+  offset: number = 0;
+
+  @Field(type => Int)
+  limit: number = 10;
+}
+```
+
+```typescript
+@ArgsType()
+class GetAuthorArgs extends PaginationArgs {
+  @Field({ nullable: true })
+  firstName?: string;
+
+  @Field({ defaultValue: '' })
+  @MinLength(3)
+  lastName: string;
+}
+```
+
+Object types:
+
+```typescript
+@ObjectType()
+class Character {
+  @Field(type => Int)
+  id: number;
+
+  @Field()
+  name: string;
+}
+```
+
+```typescript
+@ObjectType()
+class Warrior extends Character {
+  @Field()
+  level: number;
+}
+```
+
+Resolver inheritance (creating base resolver):
+
+```typescript
+function BaseResolver<T extends Type<unknown>>(classRef: T): any {
+  @Resolver({ isAbstract: true })
+  abstract class BaseResolverHost {
+    @Query(type => [classRef], { name: `findAll${classRef.name}` })
+    async findAll(): Promise<T[]> {
+      return [];
+    }
+  }
+  return BaseResolverHost;
+}
+```
+
+- explicit return type `any` is required: otherwise TypeScript complains about the usage of private class definition (recommended: define an interface instead of `any`)
+- `Type` is imported from the `@nestjs/common` package
+- `isAbstract: true` indicates that SDL shouldn't be generated for this class (you can set this for other types as well, e.g., object type)
+
+```typescript
+@Resolver(of => Recipe)
+export class RecipesResolver extends BaseResolver(Recipe) {
+  constructor(private recipesService: RecipesService) {
+    super();
+  }
+}
+```
+
+Generated SDL:
+
+```graphql
+type Query {
+  findAllRecipe: [Recipe!]!
+}
+```
+
+#### Generics
+
+Cursor-based pagination example:
+
+```typescript
+import { Field, ObjectType, Int } from '@nestjs/graphql';
+import { Type } from '@nestjs/common';
+
+export function Paginated<T>(classRef: Type<T>) {
+  @ObjectType(`${classRef.name}Edge`)
+  abstract class EdgeType {
+    @Field(type => String)
+    cursor: string;
+
+    @Field(type => classRef)
+    node: T;
+  }
+
+  @ObjectType({ isAbstract: true })
+  abstract class PaginatedType {
+    @Field(type => [EdgeType], { nullable: true })
+    edges: EdgeType[];
+
+    @Field(type => [classRef], { nullable: true })
+    nodes: T[];
+
+    @Field(type => Int)
+    totalCount: number;
+
+    @Field()
+    hasNextPage: boolean;
+  }
+  return PaginatedType;
+}
+```
+
+No reason to explain everything in detail. We can link this doc: https://graphql.org/learn/pagination/#pagination-and-edges
+
+```typescript
+@ObjectType()
+class PaginatedAuthor extends Paginated(Author) {}
+```
+
 #### Schema first
 
 As mentioned in the [previous](/graphql/quick-start) chapter, in the schema first approach we start by manually defining schema types in SDL (read [more](http://graphql.org/learn/schema/#type-language)). Consider the following SDL type definitions.
@@ -527,6 +654,8 @@ export class AuthorsModule {}
 
 > info **Hint** It is helpful to organize your code by your so-called **domain model** (similar to the way you would organize entry points in a REST API). In this approach, keep your models (`ObjectType` classes), resolvers and services together within a Nest module representing the domain model. Keep all of these components in a single folder per module. When you do this, and use the [Nest CLI](/cli/overview) to generate each element, Nest will wire all of these parts together (locating files in appropriate folders, generating entries in `provider` and `imports` arrays, etc.) automatically for you.
 
+/////// MAYBE LET'S CREATE A SEPARATE CHAPTER(PAGE) FOR THIS? [CLI plugin]
+
 #### CLI Plugin
 
 TypeScript's metadata reflection system has several limitations which make it impossible to, for instance, determine what properties a class consists of or recognize whether a given property is optional or required. However, some of these constraints can be addressed at compilation time. Nest provides a plugin that enhances the TypeScript compilation process to reduce the amount of boilerplate code required.

content/graphql/schema-generator.md

@@ -0,0 +1,37 @@
+### Generating SDL
+
+##### This chapter applies only to code first approach
+
+To manually generate (without running an application, connecting to the database, hooking up resolvers, etc.) a GraphQL SDL, use the `GraphQLSchemaBuilderModule`.
+
+```typescript
+async function generateSchema() {
+  const app = await NestFactory.create(GraphQLSchemaBuilderModule);
+  await app.init();
+
+  const gqlSchemaFactory = app.get(GraphQLSchemaFactory);
+  const schema = await gqlSchemaFactory.create([RecipesResolver]);
+  console.log(printSchema(schema));
+}
+```
+
+> info **Hint** The `GraphQLSchemaBuilderModule` and `GraphQLSchemaFactory` are imported the `@nestjs/graphql` package, while the `printSchema` function is imported from the `graphql` package.
+
+Multiple resolvers:
+
+```typescript
+const schema = await gqlSchemaFactory.create([
+  RecipesResolver,
+  AuthorsResolver,
+  PostsResolvers,
+]);
+```
+
+Passing options:
+
+```typescript
+const schema = await gqlSchemaFactory.create([RecipesResolver], {
+  skipCheck: true,
+  orphanedTypes: [],
+});
+```

src/app/homepage/menu/menu.component.ts

@@ -113,6 +113,8 @@ export class MenuComponent implements OnInit {
         { title: 'Interfaces', path: '/graphql/interfaces' },
         { title: 'Unions', path: '/graphql/unions' },
         { title: 'Enums', path: '/graphql/enums' },
+        { title: 'Mapped types', path: '/graphql/mapped-types' },
+        { title: 'Generating SDL', path: '/graphql/generating-sdl' },
         {
           title: 'Other features',
           path: '/graphql/tooling',

src/app/homepage/pages/graphql/graphql.module.ts

@@ -7,11 +7,13 @@ import { EnumsComponent } from './enums/enums.component';
 import { FederationComponent } from './federation/federation.component';
 import { GuardsInterceptorsComponent } from './guards-interceptors/guards-interceptors.component';
 import { InterfacesComponent } from './interfaces/interfaces.component';
+import { MappedTypesComponent } from './mapped-types/mapped-types.component';
 import { MutationsComponent } from './mutations/mutations.component';
 import { PluginsComponent } from './plugins/plugins.component';
 import { QuickStartComponent } from './quick-start/quick-start.component';
 import { ResolversMapComponent } from './resolvers-map/resolvers-map.component';
 import { ScalarsComponent } from './scalars/scalars.component';
+import { SchemaGeneratorComponent } from './schema-generator/schema-generator.component';
 import { SubscriptionsComponent } from './subscriptions/subscriptions.component';
 import { UnionsComponent } from './unions/unions.component';
 
@@ -84,6 +86,16 @@ const routes: Routes = [
     component: InterfacesComponent,
     data: { title: 'GraphQL + TypeScript - Interfaces' },
   },
+  {
+    path: 'mapped-types',
+    component: MappedTypesComponent,
+    data: { title: 'GraphQL + TypeScript - Mapped types' },
+  },
+  {
+    path: 'generating-sdl',
+    component: SchemaGeneratorComponent,
+    data: { title: 'GraphQL + TypeScript - Generating SDL' },
+  },
 ];
 
 @NgModule({
@@ -99,6 +111,8 @@ const routes: Routes = [
     PluginsComponent,
     GuardsInterceptorsComponent,
     ScalarsComponent,
+    SchemaGeneratorComponent,
+    MappedTypesComponent,
     FederationComponent,
   ],
 })

src/app/homepage/pages/graphql/mapped-types/mapped-types.component.ts

@@ -0,0 +1,9 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { BasePageComponent } from '../../page/page.component';
+
+@Component({
+  selector: 'app-mapped-types',
+  templateUrl: './mapped-types.component.html',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class MappedTypesComponent extends BasePageComponent {}

src/app/homepage/pages/graphql/schema-generator/schema-generator.component.ts

@@ -0,0 +1,9 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { BasePageComponent } from '../../page/page.component';
+
+@Component({
+  selector: 'app-schema-generator',
+  templateUrl: './schema-generator.component.html',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class SchemaGeneratorComponent extends BasePageComponent {}