docs(graphql) - edits for mapped types, etc.

Author: johnbiundo

content/graphql/mapped-types.md

@@ -1,14 +1,16 @@
 ### Mapped types
 
-##### This chapter applies only to code first approach
+> warning **Warning** This chapter applies only to the 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.
+As you build out features like CRUD (Create/Read/Update/Delete) it's often useful to construct variants on a base entity type. Nest provides several utility functions that perform type transformations to make this task more convenient.
 
-#### Partial
+#### Partial: PartialType() function
 
-Make all properties of a type optional.
+When building input validation types (also called DTOs), it's often useful to build **create** and **update** variations on the same type. For example, the **create** variant may require all fields, while the **update** variant may make all fields optional.
 
-Original type:
+Nest provides the `PartialType()` utility function to make this task easier and minimize boilerplate.
+
+The `PartialType()` function returns a type (class) with all the properties of the input type set to optional. For example, suppose we have a **create** type as follows:
 
 ```typescript
 @InputType()
@@ -24,7 +26,7 @@ class CreateUserInput {
 }
 ```
 
-Mapped type:
+By default, all of these fields are required. To create a type with the same fields, but with each one optional, use `PartialType()` passing the class reference (`CreateUserInput`) as an argument:
 
 ```typescript
 @InputType()
@@ -33,13 +35,16 @@ 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.
+The `PartialType()` function takes an optional second argument that is a reference to the decorator factory of the type being extended. In the example above, we are extending `CreateUserInput` which is annotated with the `@InputType()` decorator. We didn't need to pass `InputType` as the second argument since it's the default value. If you want to extend a class decorated with `@ObjectType`, pass `ObjectType` as the second argument. For example:
 
-#### Pick
+```typescript
+@InputType()
+export class UpdateUserInput extends PartialType(User, ObjectType) {}
+```
 
-Constructs a type by picking the set of properties from type.
+#### Pick: PickType() function
 
-Original type:
+The `PickType()` function constructs a new type (class) by picking a set of properties from an input type. For example, suppose we start with a type like:
 
 ```typescript
 @InputType()
@@ -55,7 +60,7 @@ class CreateUserInput {
 }
 ```
 
-Mapped type:
+We can pick a set of properties from this class using the `PickType()` utility function:
 
 ```typescript
 @InputType()
@@ -64,11 +69,9 @@ 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.
+#### Omit: OmitType() function
 
-Original type:
+The `OmitType()` function constructs a type by picking all properties from an input type and then removing a particular set of keys. For example, suppose we start with a type like:
 
 ```typescript
 @InputType()
@@ -84,7 +87,7 @@ class CreateUserInput {
 }
 ```
 
-Mapped type:
+We can generate a derived type that has every property **except** `email` as shown below. In this construct, the second argument to `OmitType` is an array of property names.
 
 ```typescript
 @InputType()
@@ -95,13 +98,11 @@ export class UpdateUserInput extends OmitType(CreateUserInput, ['email']) {}
 
 #### Composition
 
-Mapped types are composeable.
-
-Example:
+The type mapping utility functions are composable. For example, the following will produce a type (class) that has all of the properties of the `CreateUserInput` type except for `email`, and those properties will be set to optional:
 
 ```typescript
 @InputType()
-export class UpdateUserInput extends Partial(
+export class UpdateUserInput extends PartialType(
   OmitType(CreateUserInput, ['email']),
 ) {}
 ```

content/graphql/quick-start.md

@@ -173,13 +173,13 @@ A fully working schema first sample is available [here](https://github.com/nestj
 
 #### Accessing generated schema
 
-To access the generated schema (in either code first or schema first approach), use the `GraphQLHost` class:
+To access the generated schema (in either the code first or schema first approach), use the `GraphQLSchemaHost` 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.
+> info **Hint** You must call the `GraphQLSchemaHost#schema` getter after the application has been initialized (after the `onModuleInit` hook has been triggered by either the `app.listen()` or `app.init()` method).
 
 #### Async configuration
 

content/graphql/resolvers-map.md

@@ -308,19 +308,23 @@ type Query {
 
 #### Class inheritance
 
-Args:
+You can use standard TypeScript class inheritance to create base classes with generic utility type features (fields and field properties, validations, etc.) that can be extended. For example, you may have a set of pagination related arguments that always include the standard `offset` and `limit` fields, but also other index fields that are type-specific. You can set up a class hierarchy as shown below.
+
+Base `@ArgsType()` class:
 
 ```typescript
 @ArgsType()
 class PaginationArgs {
-  @Field(type => Int)
+  @Field((type) => Int)
   offset: number = 0;
 
-  @Field(type => Int)
+  @Field((type) => Int)
   limit: number = 10;
 }
 ```
 
+Type specific sub-class of the base `@ArgsType()` class:
+
 ```typescript
 @ArgsType()
 class GetAuthorArgs extends PaginationArgs {
@@ -333,19 +337,21 @@ class GetAuthorArgs extends PaginationArgs {
 }
 ```
 
-Object types:
+The same approach can be taken with `@ObjectType()` objects. Define generic properties on the base class:
 
 ```typescript
 @ObjectType()
 class Character {
-  @Field(type => Int)
+  @Field((type) => Int)
   id: number;
 
   @Field()
   name: string;
 }
 ```
 
+Add type-specific properties on sub-classes:
+
 ```typescript
 @ObjectType()
 class Warrior extends Character {
@@ -354,13 +360,13 @@ class Warrior extends Character {
 }
 ```
 
-Resolver inheritance (creating base resolver):
+You can use inheritance with a resolver as well. You can ensure type safety by combining inheritance and TypeScript generics. For example, to create a base class with a generic `findAll` query, use a construction like this:
 
 ```typescript
 function BaseResolver<T extends Type<unknown>>(classRef: T): any {
   @Resolver({ isAbstract: true })
   abstract class BaseResolverHost {
-    @Query(type => [classRef], { name: `findAll${classRef.name}` })
+    @Query((type) => [classRef], { name: `findAll${classRef.name}` })
     async findAll(): Promise<T[]> {
       return [];
     }
@@ -369,20 +375,24 @@ function BaseResolver<T extends Type<unknown>>(classRef: T): any {
 }
 ```
 
-- explicit return type `any` is required: otherwise TypeScript complains about the usage of private class definition (recommended: define an interface instead of `any`)
+Note the following:
+
+- an explicit return type (`any` above) is required: otherwise TypeScript complains about the usage of a private class definition. Recommended: define an interface instead of using `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)
+- The `isAbstract: true` property indicates that SDL (Schema Definition Language statements) shouldn't be generated for this class. Note, you can set this property for other types as well to suppress SDL generation.
+
+Here's how you could generate a concrete sub-class of the `BaseResolver`:
 
 ```typescript
-@Resolver(of => Recipe)
+@Resolver((of) => Recipe)
 export class RecipesResolver extends BaseResolver(Recipe) {
   constructor(private recipesService: RecipesService) {
     super();
   }
 }
 ```
 
-Generated SDL:
+This construct would generated the following SDL:
 
 ```graphql
 type Query {
@@ -392,7 +402,7 @@ type Query {
 
 #### Generics
 
-Cursor-based pagination example:
+We saw one use of generics above. This powerful TypeScript feature can be used to create useful abstractions. For example, here's a sample cursor-based pagination implementation based on [this documentation](https://graphql.org/learn/pagination/#pagination-and-edges):
 
 ```typescript
 import { Field, ObjectType, Int } from '@nestjs/graphql';
@@ -401,22 +411,22 @@ import { Type } from '@nestjs/common';
 export function Paginated<T>(classRef: Type<T>) {
   @ObjectType(`${classRef.name}Edge`)
   abstract class EdgeType {
-    @Field(type => String)
+    @Field((type) => String)
     cursor: string;
 
-    @Field(type => classRef)
+    @Field((type) => classRef)
     node: T;
   }
 
   @ObjectType({ isAbstract: true })
   abstract class PaginatedType {
-    @Field(type => [EdgeType], { nullable: true })
+    @Field((type) => [EdgeType], { nullable: true })
     edges: EdgeType[];
 
-    @Field(type => [classRef], { nullable: true })
+    @Field((type) => [classRef], { nullable: true })
     nodes: T[];
 
-    @Field(type => Int)
+    @Field((type) => Int)
     totalCount: number;
 
     @Field()
@@ -426,7 +436,7 @@ export function Paginated<T>(classRef: Type<T>) {
 }
 ```
 
-No reason to explain everything in detail. We can link this doc: https://graphql.org/learn/pagination/#pagination-and-edges
+With the above base class defined, we can now easily create specialized types that inherit this behavior. For example:
 
 ```typescript
 @ObjectType()

content/graphql/schema-generator.md

@@ -1,8 +1,8 @@
 ### Generating SDL
 
-##### This chapter applies only to code first approach
+> warning **Warning** This chapter applies only to the code first approach.
 
-To manually generate (without running an application, connecting to the database, hooking up resolvers, etc.) a GraphQL SDL, use the `GraphQLSchemaBuilderModule`.
+To manually generate a GraphQL SDL schema (i.e., without running an application, connecting to the database, hooking up resolvers, etc.), use the `GraphQLSchemaBuilderModule`.
 
 ```typescript
 async function generateSchema() {
@@ -15,9 +15,9 @@ async function generateSchema() {
 }
 ```
 
-> info **Hint** The `GraphQLSchemaBuilderModule` and `GraphQLSchemaFactory` are imported the `@nestjs/graphql` package, while the `printSchema` function is imported from the `graphql` package.
+> info **Hint** The `GraphQLSchemaBuilderModule` and `GraphQLSchemaFactory` are imported from the `@nestjs/graphql` package. The `printSchema` function is imported from the `graphql` package.
 
-Multiple resolvers:
+The `gqlSchemaFactory.create()` method takes an array of resolver class references. For example:
 
 ```typescript
 const schema = await gqlSchemaFactory.create([
@@ -27,7 +27,7 @@ const schema = await gqlSchemaFactory.create([
 ]);
 ```
 
-Passing options:
+It also allows several options:
 
 ```typescript
 const schema = await gqlSchemaFactory.create([RecipesResolver], {