feat(appsync): implement resolvable fields for code-first schema (#9660)

Implemented interfaces and resolvable fields for code-first schema.

`Field` extends `GraphqlType` and will allow you to define arguments.

<details>

<summary> Field Example </summary>

```gql
type Node {
  test(argument: string): String
}
```

The CDK code required would be:

```ts
const field = new appsync.Field(appsync.GraphqlType.string(), {
  args: {
    argument: appsync.GraphqlType.string(),
  },
});
const type = new appsynce.ObjectType('Node', {
  definition: { test: field },
});
```

</details>

`ResolvableField` extends `Field` and will allow you to define arguments and its resolvers.
[**Object Types**](#Object-Types) can have fields that resolve and perform operations on
your backend.

<details>

<summary> Resolvable Field Example </summary>

For example, if we want to create the following type:

```gql
type Query {
  get(argument: string): String
}
```

The CDK code required would be:

```ts
const field = new appsync.Field(appsync.GraphqlType.string(), {
  args: {
    argument: appsync.GraphqlType.string(),
  },
  dataSource: api.addNoneDataSource('none'),
  requestMappingTemplate: dummyRequest,
  responseMappingTemplate: dummyResponse,
});
const type = new appsynce.ObjectType('Query', {
  definition: { get: field },
});

</details>

----

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*

Author: BryanPan342

packages/@aws-cdk/aws-appsync/README.md

@@ -180,81 +180,257 @@ api.grantMutation(role, 'updateExample');
 api.grant(role, appsync.IamResource.ofType('Mutation', 'updateExample'), 'appsync:GraphQL');
 ```
 
-### Code-First Schema
+## Code-First Schema
 
 CDK offers the ability to generate your schema in a code-first approach. 
 A code-first approach offers a developer workflow with:
 - **modularity**: organizing schema type definitions into different files
 - **reusability**: simplifying down boilerplate/repetitive code
 - **consistency**: resolvers and schema definition will always be synced
 
-The code-first approach allows for dynamic schema generation. You can generate your schema based on variables and templates to reduce code duplication.
+The code-first approach allows for **dynamic** schema generation. You can generate your schema based on variables and templates to reduce code duplication.
 
-#### Code-First Example
+### Code-First Example
 
-We are going to reference the [example](#Example) through a code-first approach.
+To showcase the code-first approach. Let's try to model the following schema segment.
+
+```gql
+interface Node {
+  id: String
+}
+
+type Query {
+  allFilms(after: String, first: Int, before: String, last: Int): FilmConnection
+}
+
+type FilmNode implements Node {
+  filmName: String
+}
+
+type FilmConnection {
+  edges: [FilmEdge]
+  films: [Film]
+  totalCount: Int
+}
+
+type FilmEdge {
+  node: Film 
+  cursor: String
+}
+```
+
+Above we see a schema that allows for generating paginated responses. For example,
+we can query `allFilms(first: 100)` since `FilmConnection` acts as an intermediary
+for holding `FilmEdges` we can write a resolver to return the first 100 films.
+
+In a separate file, we can declare our scalar types: `scalar-types.ts`.
+
+```ts
+import { GraphqlType } from '@aws-cdk/aws-appsync';
+
+export const string = appsync.GraphqlType.string();
+export const int = appsync.GraphqlType.int();
+```
+
+In another separate file, we can declare our object types and related functions.
+We will call this file `object-types.ts` and we will have created it in a way that
+allows us to generate other `XxxConnection` and `XxxEdges` in the future. 
 
 ```ts
+const pluralize = require('pluralize');
+import * as scalar from './scalar-types.ts';
 import * as appsync from '@aws-cdk/aws-appsync';
-import * as db from '@aws-cdk/aws-dynamodb';
+
+export const args = {
+  after: scalar.string, 
+  first: scalar.int,
+  before: scalar.string,
+  last: scalar.int,
+};
+
+export const Node = new appsync.InterfaceType('Node', {
+  definition: { id: scalar.string }
+});
+export const FilmNode = new appsync.ObjectType.implementInterface('FilmNode', {
+  interfaceTypes: [Node],
+  definition: { filmName: scalar.string }
+});
+
+export function generateEdgeAndConnection(base: appsync.ObjectType) {
+  const edge = new appsync.ObjectType(`${base.name}Edge`, {
+    definition: { node: base.attribute(), cursor: scalar.string }
+  });
+  const connection = new appsync.ObjectType(`${base.name}Connection`, {
+    definition: {
+      edges: edges.attribute({ isList: true }),
+      [pluralize(base.name)]: base.attribute({ isList: true }),
+      totalCount: scalar.int,
+    }
+  });
+  return { edge: edge, connection: connection };
+}
+```
+
+Finally, we will go to our `cdk-stack` and combine everything together
+to generate our schema.
+
+```ts
+import * as appsync from '@aws-cdk/aws-appsync';
+import * as schema from './object-types';
 
 const api = new appsync.GraphQLApi(stack, 'Api', {
   name: 'demo',
   schemaDefinition: appsync.SchemaDefinition.CODE,
-  authorizationConfig: {
-    defaultAuthorization: {
-      authorizationType: appsync.AuthorizationType.IAM
-    },
-  },
-});
-
-const demoTable = new db.Table(stack, 'DemoTable', {
-  partitionKey: {
-    name: 'id',
-    type: db.AttributeType.STRING,
-  },
 });
 
-const demoDS = api.addDynamoDbDataSource('demoDataSource', 'Table for Demos', demoTable);
+this.objectTypes = [ schema.Node, schema.Film ];
 
-// Schema Definition starts here
+const filmConnections = schema.generateEdgeAndConnection(schema.Film);
 
-const demo = api.addType('demo', {
+api.addType('Query', {
   definition: {
-    id: appsync.GraphqlType.string({ isRequired: true }),
-    version: appsync.GraphqlType.string({ isRequired: true }),
-  },
-});
+    allFilms: new appsync.ResolvableField(dummyDataSource, {
+      returnType: filmConnections.connection.attribute(),
+      args: schema.args,
+      requestMappingTemplate: dummyRequest,
+      responseMappingTemplate: dummyResponse,
+    },
+  }
+  });
+})
 
+this.objectTypes.map((t) => api.appendToSchema(t));
+Object.keys(filmConnections).forEach((key) => api.appendToSchema(filmConnections[key]));
 ```
 
-#### GraphQL Types
+Notice how we can utilize the `generateEdgeAndConnection` function to generate
+Object Types. In the future, if we wanted to create more Object Types, we can simply
+create the base Object Type (i.e. Film) and from there we can generate its respective
+`Connections` and `Edges`.
+
+Check out a more in-depth example [here](https://github.com/BryanPan342/starwars-code-first).
+
+### GraphQL Types
 
 One of the benefits of GraphQL is its strongly typed nature. We define the 
 types within an object, query, mutation, interface, etc. as **GraphQL Types**. 
 
 GraphQL Types are the building blocks of types, whether they are scalar, objects, 
 interfaces, etc. GraphQL Types can be:
 - [**Scalar Types**](https://docs.aws.amazon.com/appsync/latest/devguide/scalars.html): Id, Int, String, AWSDate, etc. 
-- **Object Types**: types that you generate (i.e. `demo` from the example above)
-- **Interface Types**: abstract types that define the base implementation of other 
+- [**Object Types**](#Object-Types): types that you generate (i.e. `demo` from the example above)
+- [**Interface Types**](#Interface-Types): abstract types that define the base implementation of other 
 Intermediate Types
 
 More concretely, GraphQL Types are simply the types appended to variables. 
 Referencing the object type `Demo` in the previous example, the GraphQL Types 
 is `String!` and is applied to both the names `id` and `version`.
 
-#### Intermediate Types
+### Field and Resolvable Fields
+
+While `GraphqlType` is a base implementation for GraphQL fields, we have abstractions
+on top of `GraphqlType` that provide finer grain support.
+
+#### Field
+
+`Field` extends `GraphqlType` and will allow you to define arguments. [**Interface Types**](#Interface-Types) are not resolvable and this class will allow you to define arguments,
+but not its resolvers.
+
+For example, if we want to create the following type:
+
+```gql
+type Node {
+  test(argument: string): String
+}
+```
+
+The CDK code required would be:
+
+```ts
+const field = new appsync.Field({
+  returnType: appsync.GraphqlType.string(),
+  args: {
+    argument: appsync.GraphqlType.string(),
+  },
+});
+const type = new appsync.InterfaceType('Node', {
+  definition: { test: field },
+});
+```
+
+#### Resolvable Fields
+
+`ResolvableField` extends `Field` and will allow you to define arguments and its resolvers.
+[**Object Types**](#Object-Types) can have fields that resolve and perform operations on
+your backend.
+
+You can also create resolvable fields for object types.
+
+```gql
+type Info {
+  node(id: String): String
+}
+```
+
+The CDK code required would be:
+
+```ts
+const info = new appsync.ObjectType('Info', {
+  definition: { 
+    node: new appsync.ResolvableField({
+      returnType: appsync.GraphqlType.string(),
+      args: {
+        id: appsync.GraphqlType.string(),
+      },
+      dataSource: api.addNoneDataSource('none'),
+      requestMappingTemplate: dummyRequest,
+      responseMappingTemplate: dummyResponse,
+    }),
+  },
+});
+```
+
+To nest resolvers, we can also create top level query types that call upon
+other types. Building off the previous example, if we want the following graphql
+type definition:
+
+```gql
+type Query {
+  get(argument: string): Info
+}
+```
+
+The CDK code required would be:
+
+```ts
+const query = new appsync.ObjectType('Query', {
+  definition: { 
+    get: new appsync.ResolvableField({
+      returnType: appsync.GraphqlType.string(),
+      args: {
+        argument: appsync.GraphqlType.string(),
+      },
+      dataSource: api.addNoneDataSource('none'),
+      requestMappingTemplate: dummyRequest,
+      responseMappingTemplate: dummyResponse,
+    }),
+  },
+});
+```
+
+Learn more about fields and resolvers [here](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-mapping-template-reference-overview.html).
 
-Intermediate Types are abstractions above Scalar Types. They have a set of defined 
+### Intermediate Types
+
+Intermediate Types are defined by Graphql Types and Fields. They have a set of defined 
 fields, where each field corresponds to another type in the system. Intermediate 
 Types will be the meat of your GraphQL Schema as they are the types defined by you.
 
 Intermediate Types include:
 - [**Interface Types**](#Interface-Types)
 - [**Object Types**](#Object-Types)
 
-#### Interface Types
+### Interface Types
 
 **Interface Types** are abstract types that define the implementation of other
 intermediate types. They are useful for eliminating duplication and can be used
@@ -269,7 +445,7 @@ const node = new appsync.InterfaceType('Node', {
 });
 ```
 
-#### Object Types
+### Object Types
 
 **Object Types** are types that you declare. For example, in the [code-first example](#code-first-example)
 the `demo` variable is an **Object Type**. **Object Types** are defined by 
@@ -297,7 +473,7 @@ You can create Object Types in three ways:
 
     `scalar-types.ts` - a file for scalar type definitions
     ```ts
-    export const required_string = new appsync.GraphqlType.string({ isRequired: true });
+    export const required_string = appsync.GraphqlType.string({ isRequired: true });
     ```
 
     `object-types.ts` - a file for object type definitions
@@ -324,7 +500,7 @@ You can create Object Types in three ways:
         id: appsync.GraphqlType.string({ isRequired: true }),
       },
     });
-    const demo = new appsync.ObjectType.implementInterface('Demo', {
+    const demo = new appsync.ObjectType('Demo', {
       interfaceTypes: [ node ],
       defintion: {
         version: appsync.GraphqlType.string({ isRequired: true }),
@@ -347,4 +523,4 @@ You can create Object Types in three ways:
     });
     ```
     > This method provides easy use and is ideal for smaller projects.
-    
+