# AWS AppSync resolver reference (JavaScript)
The following sections contain the `APPSYNC_JS` runtime and JavaScript resolver reference:
+ [ JavaScript resolvers overview ](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-overview-js.html) - Learn more about how resolvers work in AWS AppSync.
+ [ Resolver context object reference ](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-context-reference-js.html) - Learn more about the context object and how it's used in resolvers.
+ [ JavaScript runtime features for resolvers and functions ](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-util-reference-js.html) - Learn more about supported runtime features and using utilities to simplify code.
+ [ JavaScript resolver function reference for DynamoDB ](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html) - Learn more about how resolvers interact with DynamoDB.
+ [ JavaScript resolver function reference for OpenSearch ](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-elasticsearch-js.html) - Learn more about resolver request and response structure and interactions with OpenSearch Service.
+ [ JavaScript resolver function reference for Lambda ](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-lambda-js.html) - Learn more about resolver request and response structure and interactions with Lambda.
+ [ JavaScript resolver function reference for EventBridge data source ](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-eventbridge-js.html) - Learn more about resolver request and response structure and interactions with EventBridge.
+ [ JavaScript resolver function reference for None data source ](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-none-js.html) - Learn more about resolver request and response structure and interactions with NONE data sources.
+ [ JavaScript resolver function reference for HTTP ](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-http-js.html) - Learn more about resolver request and response structure and interactions with HTTP endpoints.
+ [ JavaScript resolver function reference for Amazon RDS ](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-rds-js.html) - Learn more about resolver structure and interactions with RDS.
+ [ JavaScript resolver function reference for Amazon Bedrock](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-bedrock-js.html) - Learn more about resolver structure and interactions with Amazon Bedrock.
# AWS AppSync JavaScript resolvers overview
AWS AppSync lets you respond to GraphQL requests by performing operations on your data sources. For each GraphQL field you wish to run a query, mutation, or subscription on, a resolver must be attached.
Resolvers are the connectors between GraphQL and a data source. They tell AWS AppSync how to translate an incoming GraphQL request into instructions for your backend data source and how to translate the response from that data source back into a GraphQL response. With AWS AppSync, you can write your resolvers using JavaScript and run them in the AWS AppSync (`APPSYNC_JS`) environment.
AWS AppSync allows you to write unit resolvers or pipeline resolvers composed of multiple AWS AppSync functions in a pipeline.
## Supported runtime features
The AWS AppSync JavaScript runtime provides a subset of JavaScript libraries, utilities, and features. For a complete list of features and functionality supported by the `APPSYNC_JS` runtime, see [JavaScript runtime features for resolvers and functions](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-util-reference-js.html).
## Unit resolvers
A unit resolver is composed of code that defines a request and response handler that are executed against a data source. The request handler takes a context object as an argument and returns the request payload used to call your data source. The response handler receives a payload back from the data source with the result of the executed request. The response handler transforms the payload into a GraphQL response to resolve the GraphQL field. In the example below, a resolver retrieves an item from an DynamoDB data source:
```
import * as ddb from '@aws-appsync/utils/dynamodb'
export function request(ctx) {
return ddb.get({ key: { id: ctx.args.id } });
}
export const response = (ctx) => ctx.result;
```
## Anatomy of a JavaScript pipeline resolver
A pipeline resolver is composed of code that defines a request and response handler and a list of functions. Each function has a **request** and **response** handler that it executes against a data source. As a pipeline resolver delegates runs to a list of functions, it is therefore not linked to any data source. Unit resolvers and functions are primitives that execute operation against data sources.
### Pipeline resolver request handler
The request handler of a pipeline resolver (the before step) allows you to perform some preparation logic before running the defined functions.
### Functions list
The list of functions a pipeline resolver will run in sequence. The pipeline resolver request handler evaluation result is made available to the first function as `ctx.prev.result`. Each function evaluation result is available to the next function as `ctx.prev.result`.
### Pipeline resolver response handler
The response handler of a pipeline resolver allows you to perform some final logic from the output of the last function to the expected GraphQL field type. The output of the last function in the functions list is available in the pipeline resolver response handler as `ctx.prev.result` or `ctx.result`.
### Execution flow
Given a pipeline resolver comprised of two functions, the list below represents the execution flow when the resolver is invoked:
1. Pipeline resolver request handler
1. Function 1: Function request handler
1. Function 1: Data source invocation
1. Function 1: Function response handler
1. Function 2: Function request handler
1. Function 2: Data source invocation
1. Function 2: Function response handler
1. Pipeline resolver response handler
![\[GraphQL request flow diagram showing interactions between request, data sources, and response components.\]](http://docs.aws.amazon.com/appsync/latest/devguide/images/appsync-js-resolver-logic.png)
### Useful `APPSYNC_JS` runtime built-in utilities
The following utilities can help you when you’re working with pipeline resolvers.
#### ctx.stash
The stash is an object that is made available inside each resolver and function request and response handler. The same stash instance lives through a single resolver run. This means that you can use the stash to pass arbitrary data across request and response handlers and across functions in a pipeline resolver. You can test the stash like a regular JavaScript object.
#### ctx.prev.result
The `ctx.prev.result` represents the result of the previous operation that was executed in the pipeline. If the previous operation was the pipeline resolver request handler, then `ctx.prev.result` is made available to the first function in the chain. If the previous operation was the first function, then `ctx.prev.result` represents the output of the first function and is made available to the second function in the pipeline. If the previous operation was the last function, then `ctx.prev.result` represents the output of the last function and is made available to the pipeline resolver response handler.
#### util.error
The `util.error` utility is useful to throw a field error. Using `util.error` inside a function request or response handler throws a field error immediately, which prevents subsequent functions from being executed. For more details and other `util.error` signatures, visit [JavaScript runtime features for resolvers and functions](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-util-reference-js.html).
#### util.appendError
`util.appendError` is similar to `util.error()`, with the major distinction that it doesn’t interrupt the evaluation of the handler. Instead, it signals there was an error with the field, but allows the handler to be evaluated and consequently return data. Using `util.appendError` inside a function will not disrupt the execution flow of the pipeline. For more details and other `util.error` signatures, visit the [JavaScript runtime features for resolvers and functions](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-util-reference-js.html).
#### runtime.earlyReturn
The `runtime.earlyReturn` function allows you to prematurely return from any request function. Using `runtime.earlyReturn` inside of a resolver request handler will return from the resolver. Calling it from an AWS AppSync function request handler will return from the function and will continue the run to either the next function in the pipeline or the resolver response handler.
### Writing pipeline resolvers
A pipeline resolver also has a request and a response handler surrounding the run of the functions in the pipeline: its request handler is run before the first function’s request, and its response handler is run after the last function’s response. The resolver request handler can set up data to be used by functions in the pipeline. The resolver response handler is responsible for returning data that maps to the GraphQL field output type. In the example below, a resolver request handler, defines `allowedGroups`; the data returned should belong to one of these groups. This value can be used by the resolver’s functions to request data. The resolver’s response handler conducts a final check and filters the result to make sure that only items that belong to the allowed groups are returned.
```
import { util } from '@aws-appsync/utils';
/**
* Called before the request function of the first AppSync function in the pipeline.
* @param ctx the context object holds contextual information about the function invocation.
*/
export function request(ctx) {
ctx.stash.allowedGroups = ['admin'];
ctx.stash.startedAt = util.time.nowISO8601();
return {};
}
/**
* Called after the response function of the last AppSync function in the pipeline.
* @param ctx the context object holds contextual information about the function invocation.
*/
export function response(ctx) {
const result = [];
for (const item of ctx.prev.result) {
if (ctx.stash.allowedGroups.indexOf(item.group) > -1) result.push(item);
}
return result;
}
```
#### Writing AWS AppSync functions
AWS AppSync functions enable you to write common logic that you can reuse across multiple resolvers in your schema. For example, you can have one AWS AppSync function called `QUERY_ITEMS` that is responsible for querying items from an Amazon DynamoDB data source. For resolvers that you'd like to query items with, simply add the function to the resolver's pipeline and provide the query index to be used. The logic doesn't have to be re-implemented.
## Supplemental topics
**Topics**
+ [Example pipeline resolver with Amazon DynamoDB](https://docs.aws.amazon.com/appsync/latest/devguide/writing-code.html)
+ [Configuring utilities for the `APPSYNC_JS` runtime](https://docs.aws.amazon.com/appsync/latest/devguide/utility-resolvers.html)
+ [Bundling, TypeScript, and source maps for the `APPSYNC_JS` runtime](https://docs.aws.amazon.com/appsync/latest/devguide/additional-utilities.html)
+ [Testing your resolver and function handlers](https://docs.aws.amazon.com/appsync/latest/devguide/test-resolvers.html)
+ [Migrating from VTL to JavaScript](https://docs.aws.amazon.com/appsync/latest/devguide/migrating-resolvers.html)
+ [Choosing between direct data source access and proxying via a Lambda data source](https://docs.aws.amazon.com/appsync/latest/devguide/choosing-data-source.html)
# Example pipeline resolver with Amazon DynamoDB
Suppose you wanted to attach a pipeline resolver on a field named `getPost(id:ID!)` that returns a `Post` type from an Amazon DynamoDB data source with the following GraphQL query:
```
getPost(id:1){
id
title
content
}
```
First, attach a simple resolver to `Query.getPost` with the code below. This is an example of simple resolver code. There is no logic defined in the request handler, and the response handler simply returns the result of the last function.
```
/**
* Invoked **before** the request handler of the first AppSync function in the pipeline.
* The resolver `request` handler allows to perform some preparation logic
* before executing the defined functions in your pipeline.
* @param ctx the context object holds contextual information about the function invocation.
*/
export function request(ctx) {
return {}
}
/**
* Invoked **after** the response handler of the last AppSync function in the pipeline.
* The resolver `response` handler allows to perform some final evaluation logic
* from the output of the last function to the expected GraphQL field type.
* @param ctx the context object holds contextual information about the function invocation.
*/
export function response(ctx) {
return ctx.prev.result
}
```
Next, define function `GET_ITEM` that retrieves a postitem from your data source:
```
import { util } from '@aws-appsync/utils'
import * as ddb from '@aws-appsync/utils/dynamodb'
/**
* Request a single item from the attached DynamoDB table datasource
* @param ctx the context object holds contextual information about the function invocation.
*/
export function request(ctx) {
const { id } = ctx.args
return ddb.get({ key: { id } })
}
/**
* Returns the result
* @param ctx the context object holds contextual information about the function invocation.
*/
export function response(ctx) {
const { error, result } = ctx
if (error) {
return util.appendError(error.message, error.type, result)
}
return ctx.result
}
```
If there is an error during the request, the function’s response handler appends an error that will be returned to the calling client in the GraphQL response. Add the `GET_ITEM` function to your resolver functions list. When you execute the query, the `GET_ITEM` function’s request handler uses the utils provided by AWS AppSync's DynamoDB module to create a `DynamoDBGetItem` request using the `id` as the key. `ddb.get({ key: { id } })` generates the appropriate `GetItem` operation:
```
{
"operation" : "GetItem",
"key" : {
"id" : { "S" : "1" }
}
}
```
AWS AppSync uses the request to fetch the data from Amazon DynamoDB. Once the data is returned, it is handled by the `GET_ITEM` function’s response handler, which checks for errors and then returns the result.
```
{
"result" : {
"id": 1,
"title": "hello world",
"content": ""
}
}
```
Finally, the resolver’s response handler returns the result directly.
## Working with errors
If an error occurs in your function during a request, the error will be made available in your function response handler in `ctx.error`. You can append the error to your GraphQL response using the `util.appendError` utility. You can make the error available to other functions in the pipeline by using the stash. See the example below:
```
/**
* Returns the result
* @param ctx the context object holds contextual information about the function invocation.
*/
export function response(ctx) {
const { error, result } = ctx;
if (error) {
if (!ctx.stash.errors) ctx.stash.errors = []
ctx.stash.errors.push(ctx.error)
return util.appendError(error.message, error.type, result);
}
return ctx.result;
}
```
# Configuring utilities for the `APPSYNC_JS` runtime
AWS AppSync provides two libraries that aid in the development of resolvers with the `APPSYNC_JS` runtime:
+ `@aws-appsync/eslint-plugin` - Catches and fixes problems quickly during development.
+ `@aws-appsync/utils` - Provides type validation and autocompletion in code editors.
## Configuring the eslint plugin
[ESLint](https://eslint.org/) is a tool that statically analyzes your code to quickly find problems. You can run ESLint as part of your continuous integration pipeline. `@aws-appsync/eslint-plugin` is an ESLint plugin that catches invalid syntax in your code when leveraging the `APPSYNC_JS` runtime. The plugin allows you to quickly get feedback about your code during development without having to push your changes to the cloud.
`@aws-appsync/eslint-plugin` provides two rule sets that you can use during development.
**"plugin:@aws-appsync/base"** configures a base set of rules that you can leverage in your project:
| Rule | Description |
| --- | --- |
| no-async | Async processes and promises are not supported. |
| no-await | Async processes and promises are not supported. |
| no-classes | Classes are not supported. |
| no-for | for is not supported (except for for-in and for-of, which are supported) |
| no-continue | continue is not supported. |
| no-generators | Generators are not supported. |
| no-yield | yield is not supported. |
| no-labels | Labels are not supported. |
| no-this | this keyword is not supported. |
| no-try | Try/catch structure is not supported. |
| no-while | While loops are not supported. |
| no-disallowed-unary-operators | \$1\$1, --, and \$1 unary operators are not allowed. |
| no-disallowed-binary-operators | The instanceof operator is not allowed. |
| no-promise | Async processes and promises are not supported. |
**"plugin:@aws-appsync/recommended"** provides some additional rules but also requires you to add TypeScript configurations to your project.
| Rule | Description |
| --- | --- |
| no-recursion | Recursive function calls are not allowed. |
| no-disallowed-methods | Some methods are not allowed. See the [reference](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-util-reference-js.html) for a full set of supported built-in functions. |
| no-function-passing | Passing functions as function arguments to functions is not allowed. |
| no-function-reassign | Functions cannot be reassigned. |
| no-function-return | Functions cannot be the return value of functions. |
To add the plugin to your project, follow the installation and usage steps at [Getting Started with ESLint](https://eslint.org/docs/latest/user-guide/getting-started#installation-and-usage). Then, install the [plugin](https://www.npmjs.com/package/@aws-appsync/eslint-plugin) in your project using your project package manager (e.g., npm, yarn, or pnpm):
```
$ npm install @aws-appsync/eslint-plugin
```
In your `.eslintrc.{js,yml,json}` file, add **"plugin:@aws-appsync/base"** or **"plugin:@aws-appsync/recommended"** to the `extends` property. The snippet below is a basic sample `.eslintrc` configuration for JavaScript:
```
{
"extends": ["plugin:@aws-appsync/base"]
}
```
To use the **"plugin:@aws-appsync/recommended"** rule set, install the required dependency:
```
$ npm install -D @typescript-eslint/parser
```
Then, create an `.eslintrc.js` file:
```
{
"parser": "@typescript-eslint/parser",
"parserOptions": {
"ecmaVersion": 2018,
"project": "./tsconfig.json"
},
"extends": ["plugin:@aws-appsync/recommended"]
}
```
# Bundling, TypeScript, and source maps for the `APPSYNC_JS` runtime
TypeScript enhances AWS AppSync development by providing type safety and early error detection. You can write TypeScript code locally and transpile it to JavaScript before using it with the `APPSYNC_JS` runtime. The process starts with installing TypeScript and configuring tsconfig.json for the `APPSYNC_JS` environment. You can then use bundling tools like esbuild to compile and bundle the code. The Amplify CLI will generate types from the GraphQL schema, allowing you to use these types in resolver code.
You can leverage custom and external libraries in your resolver and function code, as long as they comply with `APPSYNC_JS` requirements. Bundling tools combine code into a single file for use in AWS AppSync. Source maps can be included to aid debugging.
## Leveraging libraries and bundling your code
In your resolver and function code, you can leverage both custom and external libraries so long as they comply with the `APPSYNC_JS` requirements. This makes it possible to reuse existing code in your application. To make use of libraries that are defined by multiple files, you must use a bundling tool, such as [esbuild](https://esbuild.github.io/), to combine your code in a single file that can then be saved to your AWS AppSync resolver or function.
When bundling your code, keep the following in mind:
+ `APPSYNC_JS` only supports ECMAScript modules (ESM).
+ `@aws-appsync/*` modules are integrated into `APPSYNC_JS` and should not be bundled with your code.
+ The `APPSYNC_JS` runtime environment is similar to NodeJS in that code does not run in a browser environment.
+ You can include an optional source map. However, do not include the source content.
To learn more about source maps, see [Using source maps](#source-maps).
For example, to bundle your resolver code located at `src/appsync/getPost.resolver.js`, you can use the following esbuild CLI command:
```
$ esbuild --bundle \
--sourcemap=inline \
--sources-content=false \
--target=esnext \
--platform=node \
--format=esm \
--external:@aws-appsync/utils \
--outdir=out/appsync \
src/appsync/getPost.resolver.js
```
## Building your code and working with TypeScript
[TypeScript](https://www.typescriptlang.org/) is a programming language developed by Microsoft that offers all of JavaScript’s features along with the TypeScript typing system. You can use TypeScript to write type-safe code and catch errors and bugs at build time before saving your code to AWS AppSync. The `@aws-appsync/utils` package is fully typed.
The `APPSYNC_JS` runtime doesn't support TypeScript directly. You must first transpile your TypeScript code to JavaScript code that the `APPSYNC_JS` runtime supports before saving your code to AWS AppSync. You can use TypeScript to write your code in your local integrated development environment (IDE), but note that you cannot create TypeScript code in the AWS AppSync console.
To get started, make sure you have [TypeScript](https://www.typescriptlang.org/download) installed in your project. Then, configure your TypeScript transcompilation settings to work with the `APPSYNC_JS` runtime using [TSConfig](https://www.typescriptlang.org/tsconfig). Here’s an example of a basic `tsconfig.json` file that you can use:
```
// tsconfig.json
{
"compilerOptions": {
"target": "esnext",
"module": "esnext",
"noEmit": true,
"moduleResolution": "node",
}
}
```
You can then use a bundling tool like esbuild to compile and bundle your code. For example, given a project with your AWS AppSync code located at `src/appsync`, you can use the following command to compile and bundle your code:
```
$ esbuild --bundle \
--sourcemap=inline \
--sources-content=false \
--target=esnext \
--platform=node \
--format=esm \
--external:@aws-appsync/utils \
--outdir=out/appsync \
src/appsync/**/*.ts
```
### Using Amplify codegen
You can use the [Amplify CLI](https://docs.amplify.aws/cli/) to generate the types for your schema. From the directory where your `schema.graphql` file is located, run the following command and review the prompts to configure your codegen:
```
$ npx @aws-amplify/cli codegen add
```
To regenerate your codegen under certain circumstances (e.g., when your schema is updated), run the following command:
```
$ npx @aws-amplify/cli codegen
```
You can then use the generated types in your resolver code. For example, given the following schema:
```
type Todo {
id: ID!
title: String!
description: String
}
type Mutation {
createTodo(title: String!, description: String): Todo
}
type Query {
listTodos: Todo
}
```
You could use the generated types in the following example AWS AppSync function:
```
import { Context, util } from '@aws-appsync/utils'
import * as ddb from '@aws-appsync/utils/dynamodb'
import { CreateTodoMutationVariables, Todo } from './API' // codegen
export function request(ctx: Context) {
ctx.args.description = ctx.args.description ?? 'created on ' + util.time.nowISO8601()
return ddb.put({ key: { id: util.autoId() }, item: ctx.args })
}
export function response(ctx) {
return ctx.result as Todo
}
```
### Using generics in TypeScript
You can use generics with several of the provided types. For example, the snippet below is a `Todo` type:
```
export type Todo = {
__typename: "Todo",
id: string,
title: string,
description?: string | null,
};
```
You can write a resolver for a subscription that makes use of `Todo`. In your IDE, type definitions and auto-complete hints will guide you into properly using the `toSubscriptionFilter` transform utility:
```
import { util, Context, extensions } from '@aws-appsync/utils'
import { Todo } from './API'
export function request(ctx: Context) {
return {}
}
export function response(ctx: Context) {
const filter = util.transform.toSubscriptionFilter({
title: { beginsWith: 'hello' },
description: { contains: 'created' },
})
extensions.setSubscriptionFilter(filter)
return null
}
```
## Linting your bundles
You can automatically lint your bundles by importing the `esbuild-plugin-eslint` plugin. You can then enable it by providing a `plugins` value that enables eslint capabilities. Below is a snippet that uses the esbuild JavaScript API in a file called `build.mjs`:
```
/* eslint-disable */
import { build } from 'esbuild'
import eslint from 'esbuild-plugin-eslint'
import glob from 'glob'
const files = await glob('src/**/*.ts')
await build({
format: 'esm',
target: 'esnext',
platform: 'node',
external: ['@aws-appsync/utils'],
outdir: 'dist/',
entryPoints: files,
bundle: true,
plugins: [eslint({ useEslintrc: true })],
})
```
## Using source maps
You can provide an inline source map (`sourcemap`) with your JavaScript code. Source maps are useful for when you bundle JavaScript or TypeScript code and want to see references to your input source files in your logs and runtime JavaScript error messages.
Your `sourcemap` must appear at the end of your code. It is defined by a single comment line that follows the following format:
```
//# sourceMappingURL=data:application/json;base64,
```
Here's an example:
```
//# sourceMappingURL=data:application/json;base64,ewogICJ2ZXJzaW9uIjogMywKICAic291cmNlcyI6IFsibGliLmpzIiwgImNvZGUuanMiXSwKICAibWFwcGluZ3MiOiAiO0FBQU8sU0FBUyxRQUFRO0FBQ3RCLFNBQU87QUFDVDs7O0FDRE8sU0FBUyxRQUFRLEtBQUs7QUFDM0IsU0FBTyxNQUFNO0FBQ2Y7IiwKICAibmFtZXMiOiBbXQp9Cg==
```
Source maps can be created with esbuild. The example below shows you how to use the esbuild JavaScript API to include an inline source map when code is built and bundled:
```
/* eslint-disable */
import { build } from 'esbuild'
import eslint from 'esbuild-plugin-eslint'
import glob from 'glob'
const files = await glob('src/**/*.ts')
await build({
sourcemap: 'inline',
sourcesContent: false,
format: 'esm',
target: 'esnext',
platform: 'node',
external: ['@aws-appsync/utils'],
outdir: 'dist/',
entryPoints: files,
bundle: true,
plugins: [eslint({ useEslintrc: true })],
})
```
In particular, the `sourcemap` and `sourcesContent` options specify that a source map should be added in line at the end of each build but should not include the source content. As a convention, we recommend not including source content in your `sourcemap`. You can disable this in esbuild by setting `sources-content` to `false`.
To illustrate how source maps work, review the following example in which a resolver code references helper functions from a helper library. The code contains log statements in the resolver code and in the helper library:
**./src/default.resolver.ts** (your resolver)
```
import { Context } from '@aws-appsync/utils'
import { hello, logit } from './helper'
export function request(ctx: Context) {
console.log('start >')
logit('hello world', 42, true)
console.log('< end')
return 'test'
}
export function response(ctx: Context): boolean {
hello()
return ctx.prev.result
}
```
**.src/helper.ts** (a helper file)
```
export const logit = (...rest: any[]) => {
// a special logger
console.log('[logger]', ...rest.map((r) => `<${r}>`))
}
export const hello = () => {
// This just returns a simple sentence, but it could do more.
console.log('i just say hello..')
}
```
When you build and bundle the resolver file, your resolver code will include an inline source map. When your resolver runs, the following entries appear in the CloudWatch logs:
![\[CloudWatch log entries showing resolver code execution with inline source map information.\]](http://docs.aws.amazon.com/appsync/latest/devguide/images/cloudwatch-sourcemap.jpeg)
Looking at the entries in the CloudWatch log, you'll notice that the functionality of the two files have been bundled together and are running concurrently. The original file name of each file is also clearly reflected in the logs.
# Testing your resolver and function handlers in AWS AppSync
You can use the `EvaluateCode` API command to remotely test your resolver and function handlers with mocked data before ever saving your code to a resolver or function. To get started with the command, make sure you have added the `appsync:evaluatecode` permission to your policy. For example:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "appsync:evaluateCode",
"Resource": "arn:aws:appsync:us-east-1:111122223333:*"
}
]
}
```
------
You can leverage the command by using the [AWS CLI](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/index.html) or [AWS SDKs](https://aws.amazon.com/tools/). For example, to test your code using the CLI, simply point to your file, provide a context, and specify the handler you want to evaluate:
```
aws appsync evaluate-code \
--code file://code.js \
--function request \
--context file://context.json \
--runtime name=APPSYNC_JS,runtimeVersion=1.0.0
```
The response contains an `evaluationResult` containing the payload returned by your handler. It also contains a `logs` object that holds the list of logs that were generated by your handler during the evaluation. This makes it easy to debug your code execution and see information about your evaluation to help troubleshoot. For example:
```
{
"evaluationResult": "{\"operation\":\"PutItem\",\"key\":{\"id\":{\"S\":\"record-id\"}},\"attributeValues\":{\"owner\":{\"S\":\"John doe\"},\"expectedVersion\":{\"N\":2},\"authorId\":{\"S\":\"Sammy Davis\"}}}",
"logs": [
"INFO - code.js:5:3: \"current id\" \"record-id\"",
"INFO - code.js:9:3: \"request evaluated\""
]
}
```
The evaluation result can be parsed as JSON, which gives:
```
{
"operation": "PutItem",
"key": {
"id": {
"S": "record-id"
}
},
"attributeValues": {
"owner": {
"S": "John doe"
},
"expectedVersion": {
"N": 2
},
"authorId": {
"S": "Sammy Davis"
}
}
}
```
Using the SDK, you can easily incorporate tests from your test suite to validate your code's behavior. Our example here uses the [Jest Testing Framework](https://jestjs.io/), but any testing suite works. The following snippet shows a hypothetical validation run. Note that we expect the evaluation response to be valid JSON, so we use `JSON.parse` to retrieve JSON from the string response:
```
const AWS = require('aws-sdk')
const fs = require('fs')
const client = new AWS.AppSync({ region: 'us-east-2' })
const runtime = {name:'APPSYNC_JS',runtimeVersion:'1.0.0')
test('request correctly calls DynamoDB', async () => {
const code = fs.readFileSync('./code.js', 'utf8')
const context = fs.readFileSync('./context.json', 'utf8')
const contextJSON = JSON.parse(context)
const response = await client.evaluateCode({ code, context, runtime, function: 'request' }).promise()
const result = JSON.parse(response.evaluationResult)
expect(result.key.id.S).toBeDefined()
expect(result.attributeValues.firstname.S).toEqual(contextJSON.arguments.firstname)
})
```
This yields the following result:
```
Ran all test suites.
> jest
PASS ./index.test.js
✓ request correctly calls DynamoDB (543 ms)
Test Suites: 1 passed, 1 total
Tests: 1 passed, 1 total
Snapshots: 0 totalTime: 1.511 s, estimated 2 s
```
# Migrating from VTL to JavaScript in AWS AppSync
AWS AppSync allows you to write your business logic for your resolvers and functions using VTL or JavaScript. With both languages, you write logic that instructs the AWS AppSync service on how to interact with your data sources. With VTL, you write mapping templates that must evaluate to a valid JSON-encoded string. With JavaScript, you write request and response handlers that return objects. You don't return a JSON-encoded string.
For example, take the following VTL mapping template to get an Amazon DynamoDB item:
```
{
"operation": "GetItem",
"key": {
"id": $util.dynamodb.toDynamoDBJson($ctx.args.id),
}
}
```
The utility `$util.dynamodb.toDynamoDBJson` returns a JSON-encoded string. If `$ctx.args.id` is set to ``, the template evaluates to a valid JSON-encoded string:
```
{
"operation": "GetItem",
"key": {
"id": {"S": ""},
}
}
```
When working with JavaScript, you do not need to print out raw JSON-encoded strings within your code, and using a utility like `toDynamoDBJson` is not needed. An equivalent example of the mapping template above is:
```
import { util } from '@aws-appsync/utils';
export function request(ctx) {
return {
operation: 'GetItem',
key: {id: util.dynamodb.toDynamoDB(ctx.args.id)}
};
}
```
An alternative is to use `util.dynamodb.toMapValues`, which is the recommended approach to handle an object of values:
```
import { util } from '@aws-appsync/utils';
export function request(ctx) {
return {
operation: 'GetItem',
key: util.dynamodb.toMapValues({ id: ctx.args.id }),
};
}
```
This evaluates to:
```
{
"operation": "GetItem",
"key": {
"id": {
"S": ""
}
}
}
```
**Note**
We recommend using the DynamoDB module with DynamoDB data sources:
```
import * as ddb from '@aws-appsync/utils/dynamodb'
export function request(ctx) {
ddb.get({ key: { id: ctx.args.id } })
}
```
As another example, take the following mapping template to put an item in an Amazon DynamoDB data source:
```
{
"operation" : "PutItem",
"key" : {
"id": $util.dynamodb.toDynamoDBJson($util.autoId()),
},
"attributeValues" : $util.dynamodb.toMapValuesJson($ctx.args)
}
```
When evaluated, this mapping template string must produce a valid JSON-encoded string. When using JavaScript, your code returns the request object directly:
```
import { util } from '@aws-appsync/utils';
export function request(ctx) {
const { id = util.autoId(), ...values } = ctx.args;
return {
operation: 'PutItem',
key: util.dynamodb.toMapValues({ id }),
attributeValues: util.dynamodb.toMapValues(values),
};
}
```
which evaluates to:
```
{
"operation": "PutItem",
"key": {
"id": { "S": "2bff3f05-ff8c-4ed8-92b4-767e29fc4e63" }
},
"attributeValues": {
"firstname": { "S": "Shaggy" },
"age": { "N": 4 }
}
}
```
**Note**
We recommend using the DynamoDB module with DynamoDB data sources:
```
import { util } from '@aws-appsync/utils'
import * as ddb from '@aws-appsync/utils/dynamodb'
export function request(ctx) {
const { id = util.autoId(), ...item } = ctx.args
return ddb.put({ key: { id }, item })
}
```
# Choosing between direct data source access and proxying via a Lambda data source
With AWS AppSync and the `APPSYNC_JS` runtime, you can write your own code that implements your custom business logic by using AWS AppSync functions to access your data sources. This makes it easy for you to directly interact with data sources like Amazon DynamoDB, Aurora Serverless, OpenSearch Service, HTTP APIs, and other AWS services without having to deploy additional computational services or infrastructure. AWS AppSync also makes it easy to interact with an AWS Lambda function by configuring a Lambda data source. Lambda data sources allow you to run complex business logic using AWS Lambda’s full set capabilities to resolve a GraphQL request. In most cases, an AWS AppSync function directly connected to its target data source will provide all of the functionality you need. In situations where you need to implement complex business logic that is not supported by the `APPSYNC_JS` runtime, you can use a Lambda data source as a proxy to interact with your target data source.
| | | |
| --- |--- |--- |
| | Direct data source integration | Lambda data source as a proxy |
| Use case | AWS AppSync functions interact directly with API data sources. | AWS AppSync functions call Lambdas that interact with API data sources. |
| Runtime | APPSYNC\$1JS (JavaScript) | Any supported Lambda runtime |
| Maximum size of code | 32,000 characters per AWS AppSync function | 50 MB (zipped, for direct upload) per Lambda |
| External modules | Limited - APPSYNC\$1JS supported features only | Yes |
| Call any AWS service | Yes - Using AWS AppSync HTTP datasource | Yes - Using AWS SDK |
| Access to the request header | Yes | Yes |
| Network access | No | Yes |
| File system access | No | Yes |
| Logging and metrics | Yes | Yes |
| Build and test entirely within AppSync | Yes | No |
| Cold start | No | No - With provisioned concurrency |
| Auto-scaling | Yes - transparently by AWS AppSync | Yes - As configured in Lambda |
| Pricing | No additional charge | Charged for Lambda usage |
AWS AppSync functions that integrate directly with their target data source are ideal for use cases like the following:
+ Interacting with Amazon DynamoDB, Aurora Serverless, and OpenSearch Service
+ Interacting with HTTP APIs and passing incoming headers
+ Interacting with AWS services using HTTP data sources (with AWS AppSync automatically signing requests with the provided data source role)
+ Implementing access control before accessing data sources
+ Implementing the filtering of retrieved data prior to fulfilling a request
+ Implementing simple orchestration with sequential execution of AWS AppSync functions in a resolver pipeline
+ Controlling caching and subscription connections in queries and mutations.
AWS AppSync functions that use a Lambda data source as a proxy are ideal for use cases like the following:
+ Using a language other than JavaScript or Velocity Template Language (VTL)
+ Adjusting and controlling CPU or memory to optimize performance
+ Importing third-party libraries or requiring unsupported features in `APPSYNC_JS`
+ Making multiple network requests and/or getting file system access to fulfill a query
+ Batching requests using [ batching configuration](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-lambda-js.html).
# AWS AppSync JavaScript resolver context object reference
AWS AppSync defines a set of variables and functions for working with request and response handlers. This makes logical operations on data easier with GraphQL. This document describes those functions and provides examples.
## Accessing the `context`
The `context` argument of a request and response handler is an object that holds all of the contextual information for your resolver invocation. It has the following structure:
```
type Context = {
arguments: any;
args: any;
identity: Identity;
source: any;
error?: {
message: string;
type: string;
};
stash: any;
result: any;
prev: any;
request: Request;
info: Info;
};
```
**Note**
You will often find that the `context` object is referred to as `ctx`.
Each field in the `context` object is defined as follows:
### `context` fields
** `arguments` **
A map that contains all GraphQL arguments for this field.
** `identity` **
An object that contains information about the caller. For more information about the structure of this field, see [Identity](#aws-appsync-resolver-context-reference-identity-js).
** `source` **
A map that contains the resolution of the parent field.
** `stash` **
The stash is an object that is made available inside each resolver and function handler. The same stash object lives through a single resolver run. This means that you can use the stash to pass arbitrary data across request and response handlers and across functions in a pipeline resolver.
You cannot delete or replace the entire stash, but you can add, update, delete, and read properties of the stash.
You can add items to the stash by modifying one of the code examples below:
```
//Example 1
ctx.stash.newItem = { key: "something" }
//Example 2
Object.assign(ctx.stash, {key1: value1, key2: value})
```
You can remove items from the stash by modifying the code below:
```
delete ctx.stash.key
```
** `result` **
A container for the results of this resolver. This field is available only to response handlers.
For example, if you're resolving the `author` field of the following query:
```
query {
getPost(id: 1234) {
postId
title
content
author {
id
name
}
}
}
```
Then the full `context` variable is available when a response handler is evaluated:
```
{
"arguments" : {
id: "1234"
},
"source": {},
"result" : {
"postId": "1234",
"title": "Some title",
"content": "Some content",
"author": {
"id": "5678",
"name": "Author Name"
}
},
"identity" : {
"sourceIp" : ["x.x.x.x"],
"userArn" : "arn:aws:iam::123456789012:user/appsync",
"accountId" : "666666666666",
"user" : "AIDAAAAAAAAAAAAAAAAAA"
}
}
```
** `prev.result` **
The result of whatever previous operation was executed in a pipeline resolver.
If the previous operation was the pipeline resolver's request handler, then `ctx.prev.result` represents that evaluation result and is made available to the first function in the pipeline.
If the previous operation was the first function, then `ctx.prev.result` represents the evaluation result of the first function response handler and is made available to the second function in the pipeline.
If the previous operation was the last function, then `ctx.prev.result` represents the evaluation result of the last function and is made available to the pipeline resolver's response handler.
** `info` **
An object that contains information about the GraphQL request. For the structure of this field, see [Info](#aws-appsync-resolver-context-reference-info-js).
### Identity
The `identity` section contains information about the caller. The shape of this section depends on the authorization type of your AWS AppSync API.
For more information about AWS AppSync security options, see [Authorization and authentication](security-authz.md#aws-appsync-security).
** `API_KEY` authorization**
The `identity` field isn't populated.
**`AWS_LAMBDA` authorization**
The `identity` has the following form:
```
type AppSyncIdentityLambda = {
resolverContext: any;
};
```
The `identity` contains the `resolverContext` key, containing the same `resolverContext` content returned by the Lambda function authorizing the request.
** `AWS_IAM` authorization**
The `identity` has the following form:
```
type AppSyncIdentityIAM = {
accountId: string;
cognitoIdentityPoolId: string;
cognitoIdentityId: string;
sourceIp: string[];
username: string;
userArn: string;
cognitoIdentityAuthType: string;
cognitoIdentityAuthProvider: string;
};
```
** `AMAZON_COGNITO_USER_POOLS` authorization**
The `identity` has the following form:
```
type AppSyncIdentityCognito = {
sourceIp: string[];
username: string;
groups: string[] | null;
sub: string;
issuer: string;
claims: any;
defaultAuthStrategy: string;
};
```
Each field is defined as follows:
** `accountId` **
The AWS account ID of the caller.
** `claims` **
The claims that the user has.
** `cognitoIdentityAuthType` **
Either authenticated or unauthenticated based on the identity type.
** `cognitoIdentityAuthProvider` **
A comma-separated list of external identity provider information used in obtaining the credentials used to sign the request.
** `cognitoIdentityId` **
The Amazon Cognito identity ID of the caller.
** `cognitoIdentityPoolId` **
The Amazon Cognito identity pool ID associated with the caller.
** `defaultAuthStrategy` **
The default authorization strategy for this caller (`ALLOW` or `DENY`).
** `issuer` **
The token issuer.
** `sourceIp` **
The source IP address of the caller that AWS AppSync receives. If the request doesn't include the `x-forwarded-for` header, the source IP value contains only a single IP address from the TCP connection. If the request includes a `x-forwarded-for` header, the source IP is a list of IP addresses from the `x-forwarded-for` header, in addition to the IP address from the TCP connection.
** `sub` **
The UUID of the authenticated user.
** `user` **
The IAM user.
** `userArn` **
The Amazon Resource Name (ARN) of the IAM user.
** `username` **
The user name of the authenticated user. In the case of `AMAZON_COGNITO_USER_POOLS` authorization, the value of *username* is the value of attribute *cognito:username*. In the case of `AWS_IAM` authorization, the value of *username* is the value of the AWS user principal. If you're using IAM authorization with credentials vended from Amazon Cognito identity pools, we recommend that you use `cognitoIdentityId`.
### Access request headers
AWS AppSync supports passing custom headers from clients and accessing them in your GraphQL resolvers by using `ctx.request.headers`. You can then use the header values for actions such as inserting data into a data source or authorization checks. You can use single or multiple request headers using `$curl` with an API key from the command line, as shown in the following examples:
**Single header example**
Suppose you set a header of `custom` with a value of `nadia` like the following:
```
curl -XPOST -H "Content-Type:application/graphql" -H "custom:nadia" -H "x-api-key:" -d '{"query":"mutation { createEvent(name: \"demo\", when: \"Next Friday!\", where: \"Here!\") {id name when where description}}"}' https:///graphql
```
This could then be accessed with `ctx.request.headers.custom`. For example, it might be in the following code for DynamoDB:
```
"custom": util.dynamodb.toDynamoDB(ctx.request.headers.custom)
```
**Multiple header example**
You can also pass multiple headers in a single request and access these in the resolver handler. For example, if the `custom` header is set with two values:
```
curl -XPOST -H "Content-Type:application/graphql" -H "custom:bailey" -H "custom:nadia" -H "x-api-key:" -d '{"query":"mutation { createEvent(name: \"demo\", when: \"Next Friday!\", where: \"Here!\") {id name when where description}}"}' https:///graphql
```
You could then access these as an array, such as `ctx.request.headers.custom[1]`.
**Note**
AWS AppSync doesn't expose the cookie header in `ctx.request.headers`.
### Access the request custom domain name
AWS AppSync supports configuring a custom domain that you can use to access your GraphQL and real-time endpoints for your APIs. When making a request with a custom domain name, you can get the domain name using `ctx.request.domainName`.
When using the default GraphQL endpoint domain name, the value is `null`.
### Info
The `info` section contains information about the GraphQL request. This section has the following form:
```
type Info = {
fieldName: string;
parentTypeName: string;
variables: any;
selectionSetList: string[];
selectionSetGraphQL: string;
};
```
Each field is defined as follows:
** `fieldName` **
The name of the field that is currently being resolved.
** `parentTypeName` **
The name of the parent type for the field that is currently being resolved.
** `variables` **
A map which holds all variables that are passed into the GraphQL request.
** `selectionSetList` **
A list representation of the fields in the GraphQL selection set. Fields that are aliased are referenced only by the alias name, not the field name. The following example shows this in detail.
** `selectionSetGraphQL` **
A string representation of the selection set, formatted as GraphQL schema definition language (SDL). Although fragments aren't merged into the selection set, inline fragments are preserved, as shown in the following example.
**Note**
`JSON.stringify` will not include `selectionSetGraphQL` and `selectionSetList` in the string serialization. You must reference these properties directly.
For example, if you are resolving the `getPost` field of the following query:
```
query {
getPost(id: $postId) {
postId
title
secondTitle: title
content
author(id: $authorId) {
authorId
name
}
secondAuthor(id: "789") {
authorId
}
... on Post {
inlineFrag: comments: {
id
}
}
... postFrag
}
}
fragment postFrag on Post {
postFrag: comments: {
id
}
}
```
Then the full `ctx.info` variable that is available when processing a handler might be:
```
{
"fieldName": "getPost",
"parentTypeName": "Query",
"variables": {
"postId": "123",
"authorId": "456"
},
"selectionSetList": [
"postId",
"title",
"secondTitle"
"content",
"author",
"author/authorId",
"author/name",
"secondAuthor",
"secondAuthor/authorId",
"inlineFragComments",
"inlineFragComments/id",
"postFragComments",
"postFragComments/id"
],
"selectionSetGraphQL": "{\n getPost(id: $postId) {\n postId\n title\n secondTitle: title\n content\n author(id: $authorId) {\n authorId\n name\n }\n secondAuthor(id: \"789\") {\n authorId\n }\n ... on Post {\n inlineFrag: comments {\n id\n }\n }\n ... postFrag\n }\n}"
}
```
`selectionSetList` exposes only fields that belong to the current type. If the current type is an interface or union, only selected fields that belong to the interface are exposed. For example, given the following schema:
```
type Query {
node(id: ID!): Node
}
interface Node {
id: ID
}
type Post implements Node {
id: ID
title: String
author: String
}
type Blog implements Node {
id: ID
title: String
category: String
}
```
And the following query:
```
query {
node(id: "post1") {
id
... on Post {
title
}
... on Blog {
title
}
}
}
```
When calling `ctx.info.selectionSetList` at the `Query.node` field resolution, only `id` is exposed:
```
"selectionSetList": [
"id"
]
```
# AWS AppSync JavaScript runtime features for resolvers and functions
The `APPSYNC_JS` runtime environment provides functionality similar to [ECMAScript (ES) version 6.0](https://262.ecma-international.org/6.0/). It supports a subset of its features and provides some additional methods (utilities) that are not part of the ES specifications. The following topics list all the supported language features:
+ [ Supported runtime features ](https://docs.aws.amazon.com/appsync/latest/devguide/supported-features.html) - Learn more about supported core features, primitive objects, built-in objects and functions, etc.
+ [ Built-in utilities ](https://docs.aws.amazon.com/appsync/latest/devguide/built-in-util-js.html) - The util variable contains general utility methods to help you work with data. Unless otherwise specified, all utilities use the UTF-8 character set.
+ [ Built-in modules ](https://docs.aws.amazon.com/appsync/latest/devguide/built-in-modules-js.html) - Learn more about how built-in modules can help write JavaScript resolvers and functions.
+ [ Runtime utilities ](https://docs.aws.amazon.com/appsync/latest/devguide/runtime-utils-js.html) - The runtime library provides utilities to control or modify the runtime properties of your resolvers and functions.
+ [ Time helpers in util.time ](https://docs.aws.amazon.com/appsync/latest/devguide/time-helpers-in-util-time-js.html) - The util.time variable contains datetime methods to help generate timestamps, convert between datetime formats, and parse datetime strings. The syntax for datetime formats is based on [DateTimeFormatter](https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html), which you can reference for further documentation.
+ [ DynamoDB helpers in util.dynamodb ](https://docs.aws.amazon.com/appsync/latest/devguide/dynamodb-helpers-in-util-dynamodb-js.html) - util.dynamodb contains helper methods that make it easier to write and read data to Amazon DynamoDB, such as automatic type mapping and formatting.
+ [ HTTP helpers in util.http ](https://docs.aws.amazon.com/appsync/latest/devguide/http-helpers-in-utils-http-js.html) - The util.http utility provides helper methods that you can use to manage HTTP request parameters and to add response headers.
+ [ Transformation helpers in util.transform ](https://docs.aws.amazon.com/appsync/latest/devguide/transformation-helpers-in-utils-transform-js.html) - util.transform contains helper methods that make it easier to perform complex operations against data sources.
+ [ String helpers in util.str ](https://docs.aws.amazon.com/appsync/latest/devguide/str-helpers-in-util-str-js.html) - util.str contains methods to help with common String operations.
+ [ Extensions ](https://docs.aws.amazon.com/appsync/latest/devguide/extensions-js.html) - extensions contains a set of methods to make additional actions within your resolvers.
+ [ XML helpers in util.xml ](https://docs.aws.amazon.com/appsync/latest/devguide/xml-helpers-in-util-xml-js.html) - util.xml contains methods to help with XML string conversion.
**Note**
Currently, this reference only applies to runtime version **1.0.0**.
# Supported runtime features
The sections below describe the supported feature set of the APPSYNC\$1JS runtime.
## Core features
The following core features are supported.
------
#### [ Types ]
The following types are supported:
+ numbers
+ strings
+ booleans
+ objects
+ arrays
+ functions
------
#### [ Operators ]
Operators are supported, including:
+ standard math operators (`+`, `-`, `/`, `%`, `*`, etc.)
+ nullish coalescing operator (`??`)
+ Optional chaining (`?.`)
+ bitwise operators
+ `void` and `typeof` operators
+ spread operators (`...`)
The following operators are not supported:
+ unary operators (`++`, `--`, and `~`)
+ `in` operator
**Note**
Use the `Object.hasOwn` operator to check if the specified property is in the specified object.
------
#### [ Statements ]
The following statements are supported:
+ `const`
+ `let`
+ `var`
+ `break`
+ `else`
+ `for-in`
+ `for-of`
+ `if`
+ `return`
+ `switch`
+ spread syntax
The following are not supported:
+ `catch`
+ `continue`
+ `do-while`
+ `finally`
+ `for(initialization; condition; afterthought)`
**Note**
The exceptions are `for-in` and `for-of` expressions, which are supported.
+ `throw`
+ `try`
+ `while`
+ labeled statements
------
#### [ Literals ]
The following ES 6 [template literals](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals) are supported:
+ Multi-line strings
+ Expression interpolation
+ Nesting templates
------
#### [ Functions ]
The following function syntax is supported:
+ Function declarations are supported.
+ ES 6 arrow functions are supported.
+ ES 6 rest parameter syntax is supported.
------
#### [ Strict mode ]
Functions operate in strict mode by default, so you don’t need to add a `use_strict` statement in your function code. This cannot be changed.
------
## Primitive objects
The following primitive objects of ES and their functions are supported.
------
#### [ Object ]
The following objects are supported:
+ `Object.assign()`
+ `Object.entries()`
+ `Object.hasOwn()`
+ `Object.keys()`
+ `Object.values()`
+ `delete`
------
#### [ String ]
The following strings are supported:
+ `String.prototype.length()`
+ `String.prototype.charAt()`
+ `String.prototype.concat()`
+ `String.prototype.endsWith()`
+ `String.prototype.indexOf()`
+ `String.prototype.lastIndexOf()`
+ `String.raw()`
+ `String.prototype.replace()`
**Note**
Regular expressions are not supported.
However, Java-styled regular expression constructs are supported in the provided parameter. For more information see [Pattern](https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html).
+ `String.prototype.replaceAll()`
**Note**
Regular expressions are not supported.
However, Java-styled regular expression constructs are supported in the provided parameter. For more information see [Pattern](https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html).
+ `String.prototype.slice()`
+ `String.prototype.split()`
+ `String.prototype.startsWith()`
+ `String.prototype.toLowerCase()`
+ `String.prototype.toUpperCase()`
+ `String.prototype.trim()`
+ `String.prototype.trimEnd()`
+ `String.prototype.trimStart()`
------
#### [ Number ]
The following numbers are supported:
+ `Number.isFinite`
+ `Number.isNaN`
------
## Built-in objects and functions
The following functions and objects are supported.
------
#### [ Math ]
The following math functions are supported:
+ `Math.random()`
+ `Math.min()`
+ `Math.max()`
+ `Math.round()`
+ `Math.floor()`
+ `Math.ceil()`
------
#### [ Array ]
The following array methods are supported:
+ `Array.prototype.length`
+ `Array.prototype.concat()`
+ `Array.prototype.fill()`
+ `Array.prototype.flat()`
+ `Array.prototype.indexOf()`
+ `Array.prototype.join()`
+ `Array.prototype.lastIndexOf()`
+ `Array.prototype.pop()`
+ `Array.prototype.push()`
+ `Array.prototype.reverse()`
+ `Array.prototype.shift()`
+ `Array.prototype.slice()`
+ `Array.prototype.sort()`
**Note**
`Array.prototype.sort()` doesn't support arguments.
+ `Array.prototype.splice()`
+ `Array.prototype.unshift()`
+ `Array.prototype.forEach()`
+ `Array.prototype.map()`
+ `Array.prototype.flatMap()`
+ `Array.prototype.filter()`
+ `Array.prototype.reduce()`
+ `Array.prototype.reduceRight()`
+ `Array.prototype.find()`
+ `Array.prototype.some()`
+ `Array.prototype.every()`
+ `Array.prototype.findIndex()`
+ `Array.prototype.findLast()`
+ `Array.prototype.findLastIndex()`
+ `delete`
------
#### [ Console ]
The console object is available for debugging. During live query execution, console log/error statements are sent to Amazon CloudWatch Logs (if logging is enabled). During code evaluation with `evaluateCode`, log statements are returned in the command response.
+ `console.error()`
+ `console.log()`
------
#### [ Function ]
+ The `apply`, `bind`, and `call` methods not are supported.
+ Function constructors are not supported.
+ Passing a function as an argument is not supported.
+ Recursive function calls are not supported.
------
#### [ JSON ]
The following JSON methods are supported:
+ `JSON.parse()`
**Note**
Returns a blank string if the parsed string is not valid JSON.
+ `JSON.stringify()`
------
#### [ Promises ]
Async processes are not supported, and promises are not supported.
**Note**
Network and file system access is not supported within the `APPSYNC_JS` runtime in AWS AppSync. AWS AppSync handles all I/O operations based on the requests made by the AWS AppSync resolver or AWS AppSync function.
------
## Globals
The following global constants are supported:
+ `NaN`
+ `Infinity`
+ `undefined`
+ [https://docs.aws.amazon.com/appsync/latest/devguide/built-in-util-js.html](https://docs.aws.amazon.com/appsync/latest/devguide/built-in-util-js.html)
+ [https://docs.aws.amazon.com/appsync/latest/devguide/extensions-js.html](https://docs.aws.amazon.com/appsync/latest/devguide/extensions-js.html)
+ `runtime`
## Error types
Throwing errors with `throw` is not supported. You can return an error by using `util.error()` function. You can include an error in your GraphQL response by using the `util.appendError` function.
For more information, see [Error utils](https://docs.aws.amazon.com/appsync/latest/devguide/built-in-util-js.html#utility-helpers-in-error-js).
# Built-in utilities
The `util` variable contains general utility methods to help you work with data. Unless otherwise specified, all utilities use the UTF-8 character set.
## Encoding utils
### Encoding utils list
**`util.urlEncode(String)`**
Returns the input string as an `application/x-www-form-urlencoded` encoded string.
**`util.urlDecode(String)`**
Decodes an `application/x-www-form-urlencoded` encoded string back to its non-encoded form.
**`util.base64Encode(string) : string`**
Encodes the input into a base64-encoded string.
**`util.base64Decode(string) : string`**
Decodes the data from a base64-encoded string.
## ID generation utils
### ID generation utils list
**`util.autoId()`**
Returns a 128-bit randomly generated UUID.
**`util.autoUlid()`**
Returns a 128-bit randomly generated ULID (Universally Unique Lexicographically Sortable Identifier).
**`util.autoKsuid()`**
Returns a 128-bit randomly generated KSUID (K-Sortable Unique Identifier) base62 encoded as a String with a length of 27.
## Error utils
### Error utils list
**`util.error(String, String?, Object?, Object?)`**
Throws a custom error. This can be used in request or response mapping templates if the template detects an error with the request or with the invocation result. Additionally, an `errorType` field, a `data` field, and an `errorInfo` field can be specified. The `data` value will be added to the corresponding `error` block inside `errors` in the GraphQL response.
`data` will be filtered based on the query selection set. The `errorInfo` value will be added to the corresponding `error` block inside `errors` in the GraphQL response.
`errorInfo` will **not** be filtered based on the query selection set.
**`util.appendError(String, String?, Object?, Object?)`**
Appends a custom error. This can be used in request or response mapping templates if the template detects an error with the request or with the invocation result. Additionally, an `errorType` field, a `data` field, and an `errorInfo` field can be specified. Unlike `util.error(String, String?, Object?, Object?)`, the template evaluation will not be interrupted, so that data can be returned to the caller. The `data` value will be added to the corresponding `error` block inside `errors` in the GraphQL response.
`data` will be filtered based on the query selection set. The `errorInfo` value will be added to the corresponding `error` block inside `errors` in the GraphQL response.
`errorInfo` will **not** be filtered based on the query selection set.
## Type and pattern matching utils
### Type and pattern matching utils list
**`util.matches(String, String) : Boolean`**
Returns true if the specified pattern in the first argument matches the supplied data in the second argument. The pattern must be a regular expression such as `util.matches("a*b", "aaaaab")`. The functionality is based on [Pattern](https://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html), which you can reference for further documentation.
**`util.authType()`**
Returns a String describing the multi-auth type being used by a request, returning back either "IAM Authorization", "User Pool Authorization", "Open ID Connect Authorization", or "API Key Authorization".
## Return value behavior utils
### Return value behavior utils list
**`util.escapeJavaScript(String)`**
Returns the input string as a JavaScript escaped string.
## Resolver authorization utils
### Resolver authorization utils list
**`util.unauthorized()`**
Throws `Unauthorized` for the field being resolved. Use this in request or response mapping templates to determine whether to allow the caller to resolve the field.
# Built-in modules
Modules are a part of the `APPSYNC_JS` runtime and provide utilities to help write JavaScript resolvers and functions. For samples and examples, see the [aws-appsync-resolver-samples](https://github.com/aws-samples/aws-appsync-resolver-samples) GitHub repository.
## DynamoDB module functions
DynamoDB module functions provide an enhanced experience when interacting with DynamoDB data sources. You can make requests toward your DynamoDB data sources using the functions and without adding type mapping.
Modules are imported using `@aws-appsync/utils/dynamodb`:
```
// Modules are imported using @aws-appsync/utils/dynamodb
import * as ddb from '@aws-appsync/utils/dynamodb';
```
### Functions
#### Functions list
**` get(payload: GetInput): DynamoDBGetItemRequest`**
See [Inputs](#built-in-ddb-modules-inputs) for information about GetInput.
Generates a `DynamoDBGetItemRequest` object to make a [GetItem](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-getitem) request to DynamoDB.
```
import { get } from '@aws-appsync/utils/dynamodb';
export function request(ctx) {
return get({ key: { id: ctx.args.id } });
}
```
**`put(payload): DynamoDBPutItemRequest`**
Generates a `DynamoDBPutItemRequest` object to make a [PutItem](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-putitem) request to DynamoDB.
```
import * as ddb from '@aws-appsync/utils/dynamodb'
export function request(ctx) {
return ddb.put({ key: { id: util.autoId() }, item: ctx.args });
}
```
**`remove(payload): DynamoDBDeleteItemRequest`**
Generates a `DynamoDBDeleteItemRequest` object to make a [DeleteItem](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-deleteitem) request to DynamoDB.
```
import * as ddb from '@aws-appsync/utils/dynamodb';
export function request(ctx) {
return ddb.remove({ key: { id: ctx.args.id } });
}
```
**`scan(payload): DynamoDBScanRequest`**
Generates a `DynamoDBScanRequest` to make a [Scan](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-scan) request to DynamoDB.
```
import * as ddb from '@aws-appsync/utils/dynamodb';
export function request(ctx) {
const { limit = 10, nextToken } = ctx.args;
return ddb.scan({ limit, nextToken });
}
```
**`sync(payload): DynamoDBSyncRequest`**
Generates a `DynamoDBSyncRequest` object to make a [Sync](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-sync) request. The request only receives the data altered since the last query (delta updates). Requests can only be made to versioned DynamoDB data sources.
```
import * as ddb from '@aws-appsync/utils/dynamodb';
export function request(ctx) {
const { limit = 10, nextToken, lastSync } = ctx.args;
return ddb.sync({ limit, nextToken, lastSync });
}
```
**`update(payload): DynamoDBUpdateItemRequest`**
Generates a `DynamoDBUpdateItemRequest` object to make an [UpdateItem](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-updateitem) request to DynamoDB.
### Operations
Operation helpers allow you to take specific actions on parts of your data during updates. To get started, import `operations` from `@aws-appsync/utils/dynamodb`:
```
// Modules are imported using operations
import {operations} from '@aws-appsync/utils/dynamodb';
```
#### Operations list
**`add(payload)`**
A helper function that adds a new attribute item when updating DynamoDB.
**Example**
To add an address (street, city, and zip code) to an existing DynamoDB item using the ID value:
```
import { update, operations } from '@aws-appsync/utils/dynamodb';
export function request(ctx) {
const updateObj = {
address: operations.add({
street1: '123 Main St',
city: 'New York',
zip: '10001',
}),
};
return update({ key: { id: 1 }, update: updateObj });
}
```
**`append (payload)`**
A helper function that appends a payload to the existing list in DynamoDB.
**Example**
To append newly added friend IDs (`newFriendIds`) to an existing friends list (`friendsIds`) during an update:
```
import { update, operations } from '@aws-appsync/utils/dynamodb';
export function request(ctx) {
const newFriendIds = [101, 104, 111];
const updateObj = {
friendsIds: operations.append(newFriendIds),
};
return update({ key: { id: 1 }, update: updateObj });
}
```
**`decrement (by?)`**
A helper function that decrements the existing attribute value in the item when updating DynamoDB.
**Example**
To decrement a friends counter (`friendsCount`) by 10:
```
import { update, operations } from '@aws-appsync/utils/dynamodb';
export function request(ctx) {
const updateObj = {
friendsCount: operations.decrement(10),
};
return update({ key: { id: 1 }, update: updateObj });
}
```
**`increment (by?)`**
A helper function that increments the existing attribute value in the item when updating DynamoDB.
**Example**
To increment a friends counter (`friendsCount`) by 10:
```
import { update, operations } from '@aws-appsync/utils/dynamodb';
export function request(ctx) {
const updateObj = {
friendsCount: operations.increment(10),
};
return update({ key: { id: 1 }, update: updateObj });
}
```
**`prepend (payload)`**
A helper function that prepends to the existing list in DynamoDB.
**Example**
To prepend newly added friend IDs (`newFriendIds`) to an existing friends list (`friendsIds`) during an update:
```
import { update, operations } from '@aws-appsync/utils/dynamodb';
export function request(ctx) {
const newFriendIds = [101, 104, 111];
const updateObj = {
friendsIds: operations.prepend(newFriendIds),
};
return update({ key: { id: 1 }, update: updateObj });
}
```
**`replace (payload)`**
A helper function that replaces an existing attribute when updating an item in DynamoDB. This is useful for when you want to update the entire object or subobject in the attribute and not just the keys in the payload.
**Example**
To replace an address (street, city, and zip code) in an `info` object:
```
import { update, operations } from '@aws-appsync/utils/dynamodb';
export function request(ctx) {
const updateObj = {
info: {
address: operations.replace({
street1: '123 Main St',
city: 'New York',
zip: '10001',
}),
},
};
return update({ key: { id: 1 }, update: updateObj });
}
```
**`updateListItem (payload, index)`**
A helper function that replaces an item in a list.
**Example**
In the scope of the update (`newFriendIds`), this example used `updateListItem` to update the ID values of the second item (index: `1`, new ID: `102`) and third item (index: `2`, new ID: `112`) in a list (`friendsIds`).
```
import { update, operations as ops } from '@aws-appsync/utils/dynamodb';
export function request(ctx) {
const newFriendIds = [
ops.updateListItem('102', 1), ops.updateListItem('112', 2)
];
const updateObj = { friendsIds: newFriendIds };
return update({ key: { id: 1 }, update: updateObj });
}
```
### Inputs
#### Inputs list
**`Type GetInput`**
```
GetInput: {
consistentRead?: boolean;
key: DynamoDBKey;
}
```
**Type Declaration**
+ `consistentRead?: boolean` (optional)
An optional boolean to specify whether you want to perform a strongly consistent read with DynamoDB.
+ `key: DynamoDBKey` (required)
A required parameter that specifies the key of the item in DynamoDB. DynamoDB items may have a single hash key or hash and sort keys.
**`Type PutInput`**
```
PutInput: {
_version?: number;
condition?: DynamoDBFilterObject | null;
customPartitionKey?: string;
item: Partial;
key: DynamoDBKey;
populateIndexFields?: boolean;
}
```
**Type Declaration**
+ `_version?: number` (optional)
+ `condition?: DynamoDBFilterObject | null` (optional)
When you put an object in a DynamoDB table, you can optionally specify a conditional expression that controls whether the request should succeed or not based on the state of the object already in DynamoDB before the operation is performed.
+ `customPartitionKey?: string` (optional)
When enabled, this string value modifies the format of the `ds_sk` and `ds_pk` records used by the delta sync table when versioning has been enabled. When enabled, the processing of the `populateIndexFields` entry is also enabled.
+ `item: Partial` (required)
The rest of the attributes of the item to be placed into DynamoDB.
+ `key: DynamoDBKey` (required)
A required parameter that specifies the key of the item in DynamoDB on which the put will be performed. DynamoDB items may have a single hash key or hash and sort keys.
+ `populateIndexFields?: boolean` (optional)
A boolean value that, when enabled along with the `customPartitionKey`, creates new entries for each record in the delta sync table, specifically in the `gsi_ds_pk` and `gsi_ds_sk` columns. For more information, see [Conflict detection and sync](https://docs.aws.amazon.com/appsync/latest/devguide/conflict-detection-and-sync.html) in the *AWS AppSync Developer Guide*.
**`Type QueryInput`**
```
QueryInput: ScanInput & {
query: DynamoDBKeyCondition>;
}
```
**Type Declaration**
+ `query: DynamoDBKeyCondition>` (required)
Specifies a key condition that describes items to query. For a given index, the condition for a partition key should be an equality and the sort key a comparison or a `beginsWith` (when it's a string). Only number and string types are supported for partition and sort keys.
**Example**
Take the `User` type below:
```
type User = {
id: string;
name: string;
age: number;
isVerified: boolean;
friendsIds: string[]
}
```
The query can only include the following fields: `id`, `name`, and `age`:
```
const query: QueryInput = {
name: { eq: 'John' },
age: { gt: 20 },
}
```
**`Type RemoveInput`**
```
RemoveInput: {
_version?: number;
condition?: DynamoDBFilterObject;
customPartitionKey?: string;
key: DynamoDBKey;
populateIndexFields?: boolean;
}
```
**Type Declaration**
+ `_version?: number` (optional)
+ `condition?: DynamoDBFilterObject` (optional)
When you remove an object in DynamoDB, you can optionally specify a conditional expression that controls whether the request should succeed or not based on the state of the object already in DynamoDB before the operation is performed.
**Example**
The following example is a `DeleteItem` expression containing a condition that allows the operation succeed only if the owner of the document matches the user making the request.
```
type Task = {
id: string;
title: string;
description: string;
owner: string;
isComplete: boolean;
}
const condition: DynamoDBFilterObject = {
owner: { eq: 'XXXXXXXXXXXXXXXX' },
}
remove({
key: {
id: 'XXXXXXXXXXXXXXXX',
},
condition,
});
```
+ `customPartitionKey?: string` (optional)
When enabled, the `customPartitionKey` value modifies the format of the `ds_sk` and `ds_pk` records used by the delta sync table when versioning has been enabled. When enabled, the processing of the `populateIndexFields` entry is also enabled.
+ `key: DynamoDBKey` (required)
A required parameter that specifies the key of the item in DynamoDB that is being removed. DynamoDB items may have a single hash key or hash and sort keys.
**Example**
If a `User` only has the hash key with a user `id`, then the key would look like this:
```
type User = {
id: number
name: string
age: number
isVerified: boolean
}
const key: DynamoDBKey = {
id: 1,
}
```
If the table user has a hash key (`id`) and sort key (`name`), then the key would look like this:
```
type User = {
id: number
name: string
age: number
isVerified: boolean
friendsIds: string[]
}
const key: DynamoDBKey = {
id: 1,
name: 'XXXXXXXXXX',
}
```
+ `populateIndexFields?: boolean` (optional)
A boolean value that, when enabled along with the `customPartitionKey`, creates new entries for each record in the delta sync table, specifically in the `gsi_ds_pk` and `gsi_ds_sk` columns.
**`Type ScanInput`**
```
ScanInput: {
consistentRead?: boolean | null;
filter?: DynamoDBFilterObject | null;
index?: string | null;
limit?: number | null;
nextToken?: string | null;
scanIndexForward?: boolean | null;
segment?: number;
select?: DynamoDBSelectAttributes;
totalSegments?: number;
}
```
**Type Declaration**
+ `consistentRead?: boolean | null` (optional)
An optional boolean to indicate consistent reads when querying DynamoDB. The default value is `false`.
+ `filter?: DynamoDBFilterObject | null` (optional)
An optional filter to apply to the results after retrieving it from the table.
+ `index?: string | null` (optional)
An optional name of the index to scan.
+ `limit?: number | null` (optional)
An optional max number of results to return.
+ `nextToken?: string | null` (optional)
An optional pagination token to continue a previous query. This would have been obtained from a previous query.
+ `scanIndexForward?: boolean | null` (optional)
An optional boolean to indicate whether the query is performed in ascending or descending order. By default, this value is set to `true`.
+ `segment?: number` (optional)
+ `select?: DynamoDBSelectAttributes` (optional)
Attributes to return from DynamoDB. By default, the AWS AppSync DynamoDB resolver only returns attributes that are projected into the index. The supported values are:
+ `ALL_ATTRIBUTES`
Returns all the item attributes from the specified table or index. If you query a local secondary index, DynamoDB fetches the entire item from the parent table for each matching item in the index. If the index is configured to project all item attributes, all of the data can be obtained from the local secondary index and no fetching is required.
+ `ALL_PROJECTED_ATTRIBUTES`
Returns all attributes that have been projected into the index. If the index is configured to project all attributes, this return value is equivalent to specifying `ALL_ATTRIBUTES`.
+ `SPECIFIC_ATTRIBUTES`
Returns only the attributes listed in `ProjectionExpression`. This return value is equivalent to specifying `ProjectionExpression` without specifying any value for `AttributesToGet`.
+ `totalSegments?: number` (optional)
**`Type DynamoDBSyncInput`**
```
DynamoDBSyncInput: {
basePartitionKey?: string;
deltaIndexName?: string;
filter?: DynamoDBFilterObject | null;
lastSync?: number;
limit?: number | null;
nextToken?: string | null;
}
```
**Type Declaration**
+ `basePartitionKey?: string` (optional)
The partition key of the base table to be used when performing a Sync operation. This field allows a Sync operation to be performed when the table utilizes a custom partition key.
+ `deltaIndexName?: string` (optional)
The index used for the Sync operation. This index is required to enable a Sync operation on the whole delta store table when the table uses a custom partition key. The Sync operation will be performed on the GSI (created on `gsi_ds_pk` and `gsi_ds_sk`).
+ `filter?: DynamoDBFilterObject | null` (optional)
An optional filter to apply to the results after retrieving it from the table.
+ `lastSync?: number` (optional)
The moment, in epoch milliseconds, at which the last successful Sync operation started. If specified, only items that have changed after `lastSync` are returned. This field should only be populated after retrieving all pages from an initial Sync operation. If omitted, results from the base table will be returned. Otherwise, results from the delta table will be returned.
+ `limit?: number | null` (optional)
An optional maximum number of items to evaluate at a single time. If omitted, the default limit will be set to `100` items. The maximum value for this field is `1000` items.
+ `nextToken?: string | null` (optional)
**`Type DynamoDBUpdateInput`**
```
DynamoDBUpdateInput: {
_version?: number;
condition?: DynamoDBFilterObject;
customPartitionKey?: string;
key: DynamoDBKey;
populateIndexFields?: boolean;
update: DynamoDBUpdateObject;
}
```
**Type Declaration**
+ `_version?: number` (optional)
+ `condition?: DynamoDBFilterObject` (optional)
When you update an object in DynamoDB, you can optionally specify a conditional expression that controls whether the request should succeed or not based on the state of the object already in DynamoDB before the operation is performed.
+ `customPartitionKey?: string` (optional)
When enabled, the `customPartitionKey` value modifies the format of the `ds_sk` and `ds_pk` records used by the delta sync table when versioning has been enabled. When enabled, the processing of the `populateIndexFields` entry is also enabled.
+ `key: DynamoDBKey` (required)
A required parameter that specifies the key of the item in DynamoDB that is being updated. DynamoDB items may have a single hash key or hash and sort keys.
+ `populateIndexFields?: boolean` (optional)
A boolean value that, when enabled along with the `customPartitionKey`, creates new entries for each record in the delta sync table, specifically in the `gsi_ds_pk` and `gsi_ds_sk` columns.
+ `update: DynamoDBUpdateObject`
An object that specifies the attributes to be updated along with the new values for them. The update object can be used with `add`, `remove`, `replace`, `increment`, `decrement`, `append`, `prepend`, `updateListItem`.
## Amazon RDS module functions
Amazon RDS module functions provide an enhanced experience when interacting with databases configured with the Amazon RDS Data API. The module is imported using `@aws-appsync/utils/rds`:
```
import * as rds from '@aws-appsync/utils/rds';
```
Functions can also be imported individually. For instance, the import below uses `sql`:
```
import { sql } from '@aws-appsync/utils/rds';
```
### Functions
You can use the AWS AppSync RDS module's utility helpers to interact with your database.
#### Select
The `select` utility creates a `SELECT` statement to query your relational database.
**Basic use**
In its basic form, you can specify the table you want to query:
```
import { select, createPgStatement } from '@aws-appsync/utils/rds';
export function request(ctx) {
// Generates statement:
// "SELECT * FROM "persons"
return createPgStatement(select({table: 'persons'}));
}
```
Note that you can also specify the schema in your table identifier:
```
import { select, createPgStatement } from '@aws-appsync/utils/rds';
export function request(ctx) {
// Generates statement:
// SELECT * FROM "private"."persons"
return createPgStatement(select({table: 'private.persons'}));
}
```
**Specifying columns**
You can specify columns with the `columns` property. If this isn't set to a value, it defaults to `*`:
```
export function request(ctx) {
// Generates statement:
// SELECT "id", "name"
// FROM "persons"
return createPgStatement(select({
table: 'persons',
columns: ['id', 'name']
}));
}
```
You can specify a column's table as well:
```
export function request(ctx) {
// Generates statement:
// SELECT "id", "persons"."name"
// FROM "persons"
return createPgStatement(select({
table: 'persons',
columns: ['id', 'persons.name']
}));
}
```
**Limits and offsets**
You can apply `limit` and `offset` to the query:
```
export function request(ctx) {
// Generates statement:
// SELECT "id", "name"
// FROM "persons"
// LIMIT :limit
// OFFSET :offset
return createPgStatement(select({
table: 'persons',
columns: ['id', 'name'],
limit: 10,
offset: 40
}));
}
```
**Order By**
You can sort your results with the `orderBy` property. Provide an array of objects specifying the column and an optional `dir` property:
```
export function request(ctx) {
// Generates statement:
// SELECT "id", "name" FROM "persons"
// ORDER BY "name", "id" DESC
return createPgStatement(select({
table: 'persons',
columns: ['id', 'name'],
orderBy: [{column: 'name'}, {column: 'id', dir: 'DESC'}]
}));
}
```
**Filters**
You can build filters by using the special condition object:
```
export function request(ctx) {
// Generates statement:
// SELECT "id", "name"
// FROM "persons"
// WHERE "name" = :NAME
return createPgStatement(select({
table: 'persons',
columns: ['id', 'name'],
where: {name: {eq: 'Stephane'}}
}));
}
```
You can also combine filters:
```
export function request(ctx) {
// Generates statement:
// SELECT "id", "name"
// FROM "persons"
// WHERE "name" = :NAME and "id" > :ID
return createPgStatement(select({
table: 'persons',
columns: ['id', 'name'],
where: {name: {eq: 'Stephane'}, id: {gt: 10}}
}));
}
```
You can also create `OR` statements:
```
export function request(ctx) {
// Generates statement:
// SELECT "id", "name"
// FROM "persons"
// WHERE "name" = :NAME OR "id" > :ID
return createPgStatement(select({
table: 'persons',
columns: ['id', 'name'],
where: { or: [
{ name: { eq: 'Stephane'} },
{ id: { gt: 10 } }
]}
}));
}
```
You can also negate a condition with `not`:
```
export function request(ctx) {
// Generates statement:
// SELECT "id", "name"
// FROM "persons"
// WHERE NOT ("name" = :NAME AND "id" > :ID)
return createPgStatement(select({
table: 'persons',
columns: ['id', 'name'],
where: { not: [
{ name: { eq: 'Stephane'} },
{ id: { gt: 10 } }
]}
}));
}
```
You can also use the following operators to compare values:
|
|
| Operator | Description | Possible value types |
| --- |--- |--- |
| eq | Equal | number, string, boolean |
| ne | Not equal | number, string, boolean |
| le | Less than or equal | number, string |
| lt | Less than | number, string |
| ge | Greater than or equal | number, string |
| gt | Greater than | number, string |
| contains | Like | string |
| notContains | Not like | string |
| beginsWith | Starts with prefix | string |
| between | Between two values | number, string |
| attributeExists | The attribute is not null | number, string, boolean |
| size | checks the length of the element | string |
#### Insert
The `insert` utility provides a straightforward way of inserting single row items in your database with the `INSERT` operation.
**Single item insertions**
To insert an item, specify the table and then pass in your object of values. The object keys are mapped to your table columns. Columns names are automatically escaped, and values are sent to the database using the variable map:
```
import { insert, createMySQLStatement } from '@aws-appsync/utils/rds';
export function request(ctx) {
const { input: values } = ctx.args;
const insertStatement = insert({ table: 'persons', values });
// Generates statement:
// INSERT INTO `persons`(`name`)
// VALUES(:NAME)
return createMySQLStatement(insertStatement)
}
```
**MySQL use case**
You can combine an `insert` followed by a `select` to retrieve your inserted row:
```
import { insert, select, createMySQLStatement } from '@aws-appsync/utils/rds';
export function request(ctx) {
const { input: values } = ctx.args;
const insertStatement = insert({ table: 'persons', values });
const selectStatement = select({
table: 'persons',
columns: '*',
where: { id: { eq: values.id } },
limit: 1,
});
// Generates statement:
// INSERT INTO `persons`(`name`)
// VALUES(:NAME)
// and
// SELECT *
// FROM `persons`
// WHERE `id` = :ID
return createMySQLStatement(insertStatement, selectStatement)
}
```
**Postgres use case**
With Postgres, you can use [https://www.postgresql.org/docs/current/dml-returning.html](https://www.postgresql.org/docs/current/dml-returning.html) to obtain data from the row that you inserted. It accepts `*` or an array of column names:
```
import { insert, createPgStatement } from '@aws-appsync/utils/rds';
export function request(ctx) {
const { input: values } = ctx.args;
const insertStatement = insert({
table: 'persons',
values,
returning: '*'
});
// Generates statement:
// INSERT INTO "persons"("name")
// VALUES(:NAME)
// RETURNING *
return createPgStatement(insertStatement)
}
```
#### Update
The `update` utility allows you to update existing rows. You can use the condition object to apply changes to the specified columns in all the rows that satisfy the condition. For example, let's say we have a schema that allows us to make this mutation. We want to update the `name` of `Person` with the `id` value of `3` but only if we've known them (`known_since`) since the year `2000`:
```
mutation Update {
updatePerson(
input: {id: 3, name: "Jon"},
condition: {known_since: {ge: "2000"}}
) {
id
name
}
}
```
Our update resolver looks like this:
```
import { update, createPgStatement } from '@aws-appsync/utils/rds';
export function request(ctx) {
const { input: { id, ...values }, condition } = ctx.args;
const where = {
...condition,
id: { eq: id },
};
const updateStatement = update({
table: 'persons',
values,
where,
returning: ['id', 'name'],
});
// Generates statement:
// UPDATE "persons"
// SET "name" = :NAME, "birthday" = :BDAY, "country" = :COUNTRY
// WHERE "id" = :ID
// RETURNING "id", "name"
return createPgStatement(updateStatement)
}
```
We can add a check to our condition to make sure that only the row that has the primary key `id` equal to `3` is updated. Similarly, for Postgres `inserts`, you can use `returning` to return the modified data.
#### Remove
The `remove` utility allows you to delete existing rows. You can use the condition object on all rows that satisfy the condition. Note that `delete` is a reserved keyword in JavaScript. `remove` should be used instead:
```
import { remove, createPgStatement } from '@aws-appsync/utils/rds';
export function request(ctx) {
const { input: { id }, condition } = ctx.args;
const where = { ...condition, id: { eq: id } };
const deleteStatement = remove({
table: 'persons',
where,
returning: ['id', 'name'],
});
// Generates statement:
// DELETE "persons"
// WHERE "id" = :ID
// RETURNING "id", "name"
return createPgStatement(updateStatement)
}
```
### Casting
In some cases, you may want more specificity about the correct object type to use in your statement. You can use the provided type hints to specify the type of your parameters. AWS AppSync supports the [same type hints](https://docs.aws.amazon.com//rdsdataservice/latest/APIReference/API_SqlParameter.html#rdsdtataservice-Type-SqlParameter-typeHint) as the Data API. You can cast your parameters by using the `typeHint` functions from the AWS AppSync `rds` module.
The following example allows you to send an array as a value that is casted as a JSON object. We use the `->` operator to retrieve the element at the `index` `2` in the JSON array:
```
import { sql, createPgStatement, toJsonObject, typeHint } from '@aws-appsync/utils/rds';
export function request(ctx) {
const arr = ctx.args.list_of_ids
const statement = sql`select ${typeHint.JSON(arr)}->2 as value`
return createPgStatement(statement)
}
export function response(ctx) {
return toJsonObject(ctx.result)[0][0].value
}
```
Casting is also useful when handling and comparing `DATE`, `TIME`, and `TIMESTAMP`:
```
import { select, createPgStatement, typeHint } from '@aws-appsync/utils/rds';
export function request(ctx) {
const when = ctx.args.when
const statement = select({
table: 'persons',
where: { createdAt : { gt: typeHint.DATETIME(when) } }
})
return createPgStatement(statement)
}
```
Here's another example showing how you can send the current date and time:
```
import { sql, createPgStatement, typeHint } from '@aws-appsync/utils/rds';
export function request(ctx) {
const now = util.time.nowFormatted('YYYY-MM-dd HH:mm:ss')
return createPgStatement(sql`select ${typeHint.TIMESTAMP(now)}`)
}
```
**Available type hints**
+ `typeHint.DATE` - The corresponding parameter is sent as an object of the `DATE` type to the database. The accepted format is `YYYY-MM-DD`.
+ `typeHint.DECIMAL` - The corresponding parameter is sent as an object of the `DECIMAL` type to the database.
+ `typeHint.JSON` - The corresponding parameter is sent as an object of the `JSON` type to the database.
+ `typeHint.TIME` - The corresponding string parameter value is sent as an object of the `TIME` type to the database. The accepted format is `HH:MM:SS[.FFF]`.
+ `typeHint.TIMESTAMP` - The corresponding string parameter value is sent as an object of the `TIMESTAMP` type to the database. The accepted format is `YYYY-MM-DD HH:MM:SS[.FFF]`.
+ `typeHint.UUID` - The corresponding string parameter value is sent as an object of the `UUID` type to the database.
# Runtime utilities
The `runtime` library provides utilities to control or modify the runtime properties of your resolvers and functions.
## Runtime utils list
**`runtime.earlyReturn(obj?: unknown, returnOptions?: {skipTo: 'END' | 'NEXT'}): never`**
Invoking this function will halt the execution of the current handler, AWS AppSync function or resolver (Unit or Pipeline Resolver) depending on the current context. The specified object is returned as the result.
+ When called in an AWS AppSync function request handler, the data source and response handler are skipped, and the next function request handler (or the pipeline resolver response handler if this was the last AWS AppSync function) is called.
+ When called in an AWS AppSync pipeline resolver request handler, the pipeline execution is skipped, and the pipeline resolver response handler is called immediately.
+ When `returnOptions` is given with `skipTo` set to "END", the pipeline execution is skipped, and the pipeline resolver response handler is called immediately.
+ When `returnOptions` is given with `skipTo` set to "NEXT", the function execution is skipped, and the next pipeline handler is called.
**Example**
```
import { runtime } from '@aws-appsync/utils'
export function request(ctx) {
runtime.earlyReturn({ hello: 'world' })
// code below is not executed
return ctx.args
}
// never called because request returned early
export function response(ctx) {
return ctx.result
}
```
# Time helpers in util.time
The `util.time` variable contains datetime methods to help generate timestamps, convert between datetime formats, and parse datetime strings. The syntax for datetime formats is based on [DateTimeFormatter](https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html) which you can reference for further documentation.
## Time utils list
**`util.time.nowISO8601()`**
Returns a String representation of UTC in [ISO8601 format](https://en.wikipedia.org/wiki/ISO_8601).
**`util.time.nowEpochSeconds()`**
Returns the number of seconds from the epoch of 1970-01-01T00:00:00Z to now.
**`util.time.nowEpochMilliSeconds()`**
Returns the number of milliseconds from the epoch of 1970-01-01T00:00:00Z to now.
**`util.time.nowFormatted(String)`**
Returns a string of the current timestamp in UTC using the specified format from a String input type.
**`util.time.nowFormatted(String, String)`**
Returns a string of the current timestamp for a timezone using the specified format and timezone from String input types.
**`util.time.parseFormattedToEpochMilliSeconds(String, String)`**
Parses a timestamp passed as a String along with a format containing a time zone, then returns the timestamp as milliseconds since epoch.
**`util.time.parseFormattedToEpochMilliSeconds(String, String, String)`**
Parses a timestamp passed as a String along with a format and time zone, then returns the timestamp as milliseconds since epoch.
**`util.time.parseISO8601ToEpochMilliSeconds(String)`**
Parses an ISO8601 timestamp passed as a String, then returns the timestamp as milliseconds since epoch.
**`util.time.epochMilliSecondsToSeconds(long)`**
Converts an epoch milliseconds timestamp to an epoch seconds timestamp.
**`util.time.epochMilliSecondsToISO8601(long)`**
Converts an epoch milliseconds timestamp to an ISO8601 timestamp.
**`util.time.epochMilliSecondsToFormatted(long, String)`**
Converts an epoch milliseconds timestamp, passed as long, to a timestamp formatted according to the supplied format in UTC.
**`util.time.epochMilliSecondsToFormatted(long, String, String)`**
Converts an epoch milliseconds timestamp, passed as a long, to a timestamp formatted according to the supplied format in the supplied timezone.
# DynamoDB helpers in util.dynamodb
`util.dynamodb` contains helper methods that make it easier to write and read data to Amazon DynamoDB, such as automatic type mapping and formatting.
## toDynamoDB
### toDynamoDB utils list
**`util.dynamodb.toDynamoDB(Object)`**
General object conversion tool for DynamoDB that converts input objects to the appropriate DynamoDB representation. It's opinionated about how it represents some types: e.g., it will use lists ("L") rather than sets ("SS", "NS", "BS"). This returns an object that describes the DynamoDB attribute value.
**String example**
```
Input: util.dynamodb.toDynamoDB("foo")
Output: { "S" : "foo" }
```
**Number example**
```
Input: util.dynamodb.toDynamoDB(12345)
Output: { "N" : 12345 }
```
**Boolean example**
```
Input: util.dynamodb.toDynamoDB(true)
Output: { "BOOL" : true }
```
**List example**
```
Input: util.dynamodb.toDynamoDB([ "foo", 123, { "bar" : "baz" } ])
Output: {
"L" : [
{ "S" : "foo" },
{ "N" : 123 },
{
"M" : {
"bar" : { "S" : "baz" }
}
}
]
}
```
**Map example**
```
Input: util.dynamodb.toDynamoDB({ "foo": "bar", "baz" : 1234, "beep": [ "boop"] })
Output: {
"M" : {
"foo" : { "S" : "bar" },
"baz" : { "N" : 1234 },
"beep" : {
"L" : [
{ "S" : "boop" }
]
}
}
}
```
## toString utils
### toString utils list
**`util.dynamodb.toString(String)`**
Converts an input string to the DynamoDB string format. This returns an object that describes the DynamoDB attribute value.
```
Input: util.dynamodb.toString("foo")
Output: { "S" : "foo" }
```
**`util.dynamodb.toStringSet(List)`**
Converts a list with Strings to the DynamoDB string set format. This returns an object that describes the DynamoDB attribute value.
```
Input: util.dynamodb.toStringSet([ "foo", "bar", "baz" ])
Output: { "SS" : [ "foo", "bar", "baz" ] }
```
## toNumber utils
### toNumber utils list
**`util.dynamodb.toNumber(Number)`**
Converts a number to the DynamoDB number format. This returns an object that describes the DynamoDB attribute value.
```
Input: util.dynamodb.toNumber(12345)
Output: { "N" : 12345 }
```
**`util.dynamodb.toNumberSet(List)`**
Converts a list of numbers to the DynamoDB number set format. This returns an object that describes the DynamoDB attribute value.
```
Input: util.dynamodb.toNumberSet([ 1, 23, 4.56 ])
Output: { "NS" : [ 1, 23, 4.56 ] }
```
## toBinary utils
### toBinary utils list
**`util.dynamodb.toBinary(String)`**
Converts binary data encoded as a base64 string to DynamoDB binary format. This returns an object that describes the DynamoDB attribute value.
```
Input: util.dynamodb.toBinary("foo")
Output: { "B" : "foo" }
```
**`util.dynamodb.toBinarySet(List)`**
Converts a list of binary data encoded as base64 strings to DynamoDB binary set format. This returns an object that describes the DynamoDB attribute value.
```
Input: util.dynamodb.toBinarySet([ "foo", "bar", "baz" ])
Output: { "BS" : [ "foo", "bar", "baz" ] }
```
## toBoolean utils
### toBoolean utils list
**`util.dynamodb.toBoolean(Boolean)`**
Converts a Boolean to the appropriate DynamoDB Boolean format. This returns an object that describes the DynamoDB attribute value.
```
Input: util.dynamodb.toBoolean(true)
Output: { "BOOL" : true }
```
## toNull utils
### toNull utils list
**`util.dynamodb.toNull()`**
Returns a null in DynamoDB null format. This returns an object that describes the DynamoDB attribute value.
```
Input: util.dynamodb.toNull()
Output: { "NULL" : null }
```
## toList utils
### toList utils list
**`util.dynamodb.toList(List)`**
Converts a list of objects to the DynamoDB list format. Each item in the list is also converted to its appropriate DynamoDB format. It's opinionated about how it represents some of the nested objects: e.g., it will use lists ("L") rather than sets ("SS", "NS", "BS"). This returns an object that describes the DynamoDB attribute value.
```
Input: util.dynamodb.toList([ "foo", 123, { "bar" : "baz" } ])
Output: {
"L" : [
{ "S" : "foo" },
{ "N" : 123 },
{
"M" : {
"bar" : { "S" : "baz" }
}
}
]
}
```
## toMap utils
### toMap utils list
**`util.dynamodb.toMap(Map)`**
Converts a map to the DynamoDB map format. Each value in the map is also converted to its appropriate DynamoDB format. It's opinionated about how it represents some of the nested objects: e.g., it will use lists ("L") rather than sets ("SS", "NS", "BS"). This returns an object that describes the DynamoDB attribute value.
```
Input: util.dynamodb.toMap({ "foo": "bar", "baz" : 1234, "beep": [ "boop"] })
Output: {
"M" : {
"foo" : { "S" : "bar" },
"baz" : { "N" : 1234 },
"beep" : {
"L" : [
{ "S" : "boop" }
]
}
}
}
```
**`util.dynamodb.toMapValues(Map)`**
Creates a copy of the map where each value has been converted to its appropriate DynamoDB format. It's opinionated about how it represents some of the nested objects: e.g., it will use lists ("L") rather than sets ("SS", "NS", "BS").
```
Input: util.dynamodb.toMapValues({ "foo": "bar", "baz" : 1234, "beep": [ "boop"] })
Output: {
"foo" : { "S" : "bar" },
"baz" : { "N" : 1234 },
"beep" : {
"L" : [
{ "S" : "boop" }
]
}
}
```
This is slightly different to `util.dynamodb.toMap(Map)` as it returns only the contents of the DynamoDB attribute value, but not the whole attribute value itself. For example, the following statements are exactly the same:
```
util.dynamodb.toMapValues(