feat(resolvers): JavaScript resolvers (#534)

Author: bboure

.github/workflows/ci.yml

@@ -17,11 +17,11 @@ jobs:
       matrix:
         node: [16]
     steps:
-      - uses: actions/setup-node@v1
+      - uses: actions/setup-node@v3
         with:
           node-version: ${{ matrix.node }}
       - name: Checkout code
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
       - name: Install dependencies
         run: npm install
       - name: Lint

.github/workflows/release.yml

@@ -12,9 +12,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
       - name: Setup Node.js
-        uses: actions/setup-node@v2
+        uses: actions/setup-node@v3
         with:
           node-version: 16
       - name: Install dependencies

doc/general-config.md

@@ -48,12 +48,6 @@ appSync:
 - `caching`: See [Cacing](caching.md)
 - `waf`: See [Web Application Firefall](WAF.md)
 - `logging`: See [Logging](#Logging)
-- `defaultMappingTemplates`:
-  - `request`: Optional. A default request mapping template filename for all resolvers.
-  - `response`: Optional. A default response mapping template filename for all resolvers.
-- `mappingTemplatesLocation`:
-  - `resolvers`: The location where to find resolver mapping templates, relative to the service path. Defaults to `mapping-templates`.
-  - `pipelineFunctions`: The location where to find pipeline functions mapping templates. Defaults to the same value as `mappingTemplatesLocation.resolvers`.
 - `xrayEnabled`: Boolean. Enable or disable X-Ray tracing.
 - `tags`: A key-value pair for tagging this AppSync API
 

doc/pipeline-functions.md

@@ -4,28 +4,33 @@ When you use `PIPELINE` [resolvers](resolvers.md), you will also need to define
 
 It's a key-value pair object whose key is the name of the function and the value is its configuration.
 
-The definition can also be a string in which case it's the [dataSource](dataSources.md) name to use. The other attributes use the default values.
-
 ## Quick start
 
 ```yaml
 appSync:
   pipelineFunctions:
-    myFunction: myDataSource
-    myOtherFunction:
-      dataSource: myOtherDataSource
+    myFunction:
+      dataSource: myDataSource
+      code: myFunction.js
 ```
 
 ## Configutation
 
 - `dataSource`: The name of the dataSource to use.
 - `description`: An optional description for this pipeline function.
-- `request`: The request mapping template file name to use for this resolver, or `false` for [direct lambda](https://docs.aws.amazon.com/appsync/latest/devguide/direct-lambda-reference.html). Defaults to `{functionName}.request.vtl`.
-- `response`: The request mapping template file name to use for this resolver, or `false` for [direct lambda](https://docs.aws.amazon.com/appsync/latest/devguide/direct-lambda-reference.html). Defaults to `{functionName}.response.vtl`.
+- `code`: The path to the JS resolver handler file, relative to `serverless.yml`.
+- `request`: The path to the VTL request mapping template file, relative to `serverless.yml`.
+- `response`: The path to the VTL response mapping template file, relative to `serverless.yml`.
 - `maxBatchSize`: The maximum [batch size](https://aws.amazon.com/blogs/mobile/introducing-configurable-batching-size-for-aws-appsync-lambda-resolvers/) to use (only available for AWS Lambda DataAources)
 - `substitutions`: See [VTL template substitutions](substitutions.md)
 - `sync`: [See SyncConfig](syncConfig.md)
 
+## JavaScript vs VTL vs Direct Lambda
+
+When `code` is specified, the JavaScript runtime is used. When `request` and/or `response` are specified, the VTL runtime is used.
+
+To use [direct lambda](https://docs.aws.amazon.com/appsync/latest/devguide/direct-lambda-reference.html), don't specify anything (only works with Lambda function data sources).
+
 ## Inline DataSources
 
 Just like with `UNIT` resolvers, you can [define the dataSource inline](resolvers.md#inline-datasources) in pipeline functions.

doc/resolvers.md

@@ -4,8 +4,6 @@ All the Resolvers in your AppSync API can be found in serverless.yml under the `
 
 Resolvers are defined using key-value pairs where the key can either be an arbitrary name for the resolver or the `type` and `field` in the schema it is attached to separated with a dot (`.`), and the value is the configuration of the resolver.
 
-The definition can also be a string in which case it's the [dataSource](dataSources.md) name to use. The other attributes use the default values.
-
 ## Quick start
 
 ```yaml
@@ -14,8 +12,6 @@ appSync:
     Query.user:
       dataSource: myDataSource
 
-    Query.users: myDataSource
-
     getPosts:
       type: Query
       field: getPosts
@@ -26,15 +22,34 @@ appSync:
 
 - `type`: The Type in the schema this resolver is attached to. Optional if specified in the configuration key.
 - `field`: The Field in the schema this resolver is attached to. Optional if specified in the configuration key.
-- `kind`: The kind of resolver. Can be `UNIT` or `PIPELINE` ([see below](#PIPELINE-resolvers)). Defaults to `UNIT`
+- `kind`: The kind of resolver. Can be `UNIT` or `PIPELINE` ([see below](#PIPELINE-resolvers)). Defaults to `PIPELINE`
 - `dataSource`: The name of the [dataSource](dataSources.md) this resolver uses.
 - `maxBatchSize`: The maximum [batch size](https://aws.amazon.com/blogs/mobile/introducing-configurable-batching-size-for-aws-appsync-lambda-resolvers/) to use (only available for AWS Lambda DataSources)
-- `request`: The request mapping template file name to use for this resolver, or `false` for [direct lambda](https://docs.aws.amazon.com/appsync/latest/devguide/direct-lambda-reference.html). Defaults to `{type}.{field}.request.vtl`.
-- `response`: The request mapping template file name to use for this resolver, or `false` for [direct lambda](https://docs.aws.amazon.com/appsync/latest/devguide/direct-lambda-reference.html). Defaults to `{type}.{field}.response.vtl`.
+- `code`: The path of the JavaScript resolver handler file, relative to `serverless.yml`. If not specified, a [minimalistic default](#javascript-vs-vtl) is used.
+- `request`: The path to the VTL request mapping template file, relative to `serverless.yml`.
+- `response`: The path to the VTL response mapping template file, relative to `serverless.yml`.
 - `substitutions`: See [VTL template substitutions](substitutions.md)
 - `caching`: [See below](#Caching)
 - `sync`: [See SyncConfig](syncConfig.md)
 
+## JavaScript vs VTL
+
+When `code` is specified, the JavaScript runtime is used. When `request` and/or `response` are specified, the VTL runtime is used.
+
+If neither are specified, by default, the resolver is a PIPELINE JavaScript resolver, and the following minimalistic resolver handler is used.
+
+```js
+export function request() {
+  return {};
+}
+
+export function response(ctx) {
+  return ctx.prev.result;
+}
+```
+
+To use [direct lambda](https://docs.aws.amazon.com/appsync/latest/devguide/direct-lambda-reference.html), set `kind` to `UNIT` and don't specify `request` and `response` (only works with Lambda function data sources).
+
 ## PIPELINE resolvers
 
 When `kind` is `PIPELINE`, you can specify the [pipeline function](pipeline-functions.md) names to use:
@@ -73,6 +88,19 @@ appSync:
             handler: 'functions/getUser.handler'
 ```
 
+## Inline function definitions
+
+If a [Pipeline function](pipeline-functions.md) is only used in a single resolver, you can also define it inline in the resolver configuration.
+
+```yaml
+appSync:
+  resolvers:
+    Query.user:
+      functions:
+        - dataSource: 'users'
+          code: 'getUser.js'
+```
+
 ## Caching
 
 ```yaml

doc/upgrading-from-v1.md

@@ -35,6 +35,33 @@ custom:
 
 Place your APIs into defferent stacks. Unfortunately, this WILL require **the replacement of the APIs**. You can probably use [custom domains](custom-domain.md) to workaround that, if that's an option.
 
+### Defaults to PIPELINE and JavaScript resolvers
+
+The new default runtime is JavaScript.
+
+The new default `KIND` for resolvers is `PIPELINE`. For several reasons:
+
+- The JavaScript runtime, is only supportsed with PIPELINE resolvers
+- It makes migrations easier later, if you need to add functions to your resolvers.
+
+> 💡 To simulate a UNIT resolver, use a PIPELINE with only one function.
+
+```yml
+resolvers:
+  Query.getPost:
+    functions:
+      - dataSource: posts
+        code: resolvers/getPost.js
+```
+
+### No more defaults for resolver handler paths.
+
+In `v1`, if you did not specify a path to your mapping templates, a default based on the type, field or function name was used. (e.g. `Query.getPost.request.vtl`).
+
+To avoid unexpected behaviours, you are now required to explicitely specify the path to your resolver handlers. i.e. use `code` for Pipeline JS resolvers or `request`/`response` for VTL.
+
+There is also no more `mappingTemplatesLocation` option. Paths must be relative to the `serverless.yml`. This aligns more with how Serverless Framework handles Lambda function handlers' paths.
+
 ### Graphiql "playground"
 
 The `graphql-playground` command which started a graphiql server pointing to the AppSync API has been removed.