feat: Add bundling and TS support (#576)

doc/general-config.md

@@ -51,6 +51,7 @@ appSync:
 - `xrayEnabled`: Boolean. Enable or disable X-Ray tracing.
 - `visibility`: Optional. `GLOBAL` or `PRIVATE`. **Changing this value requires the replacement of the API.**
 - `tags`: A key-value pair for tagging this AppSync API
+- `esbuild`: Custom esbuild options, or `false` See [Esbuild](#Esbuild)
 
 ## Schema
 
@@ -186,3 +187,22 @@ appSync:
 - `excludeVerboseContent`: Boolean, Optional. Exclude or not verbose content (headers, response headers, context, and evaluated mapping templates), regardless of field logging level. Defaults to `false`.
 - `retentionInDays`: Optional. Number of days to retain the logs. Defaults to [`provider.logRetentionInDays`](https://www.serverless.com/framework/docs/providers/aws/guide/serverless.yml#general-function-settings).
 - `roleArn`: Optional. The role ARN to use for AppSync to write into CloudWatch. If not specified, a new role is created by default.
+
+## Esbuild
+
+By default, this plugin uses esbuild in order to bundle Javascript resolvers. TypeScript files are also transpiled into compatible JavaScript. This option allows you to pass custom options that must be passed to the esbuild command.
+
+⚠️ Use these options carefully. Some options are not compatible with AWS AppSync. For more details about using esbuild with AppSync, see the [official guidelines](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-overview-js.html#additional-utilities)
+
+Set this option to `false` to disable esbuild completely. You code will be sent as-is to AppSync.
+
+Example:
+
+Override the target and disable sourcemap.
+
+```yml
+appSync:
+  esbuild:
+    target: 'es2020',
+    sourcemap: false
+```

doc/resolvers.md

@@ -64,6 +64,76 @@ appSync:
       code: getUser.js
 ```
 
+## Bundling
+
+AppSync requires resolvers to be bundled in one single file. By default, this plugin bundles your code with [esbuild](https://esbuild.github.io/), using the given path as the entry point.
+
+This means that you can import external libraries and utilities. e.g.
+
+```js
+import { Context, util } from '@aws-appsync/utils';
+import { generateUpdateExpressions, updateItem } from '../lib/helpers';
+
+export function request(ctx) {
+  const { id, ...post } = ctx.args.post;
+
+  const item = updateItem(post);
+
+  return {
+    operation: 'UpdateItem',
+    key: {
+      id: util.dynamodb.toDynamoDB(id),
+    },
+    update: generateUpdateExpressions(item),
+    condition: {
+      expression: 'attribute_exists(#id)',
+      expressionNames: {
+        '#id': 'id',
+      },
+    },
+  };
+}
+
+export function response(ctx: Context) {
+  return ctx.result;
+}
+```
+
+For more information, also see the [esbuild option](./general-config.md#Esbuild).
+
+## TypeScript support
+
+You can write JS resolver in TypeScript. Resolver files with the `.ts` extension are automatically transpiled and bundled using esbuild.
+
+```yaml
+resolvers:
+  Query.user:
+    kind: UNIT
+    dataSource: 'users'
+    code: 'getUser.ts'
+```
+
+```ts
+// getUser.ts
+import { Context, util } from '@aws-appsync/utils';
+
+export function request(ctx: Context) {
+  const {
+    args: { id },
+  } = ctx;
+  return {
+    operation: 'GetItem',
+    key: util.dynamodb.toMapValues({ id }),
+  };
+}
+
+export function response(ctx: Context) {
+  return ctx.result;
+}
+```
+
+For more information, also see the [esbuild option](./general-config.md#Esbuild).
+
 ## PIPELINE resolvers
 
 When `kind` is `PIPELINE`, you can specify the [pipeline function](pipeline-functions.md) names to use: