migrate AWS SDK v2 → v3

README.md

@@ -8,12 +8,13 @@ Deploy [AppSync](https://aws.amazon.com/appsync) API's in minutes using this [Se
 Contact me @[linkedin](https://www.linkedin.com/in/sid88in/)
 
 ### Adoption **8M+ total downloads** on npm (see npm totals and charts below):
-  - https://www.npmjs.com/package/serverless-appsync-plugin
-  - https://npm-stat.com/charts.html?package=serverless-appsync-plugin&from=2018-01-27&to=2025-12-31
+
+- https://www.npmjs.com/package/serverless-appsync-plugin
+- https://npm-stat.com/charts.html?package=serverless-appsync-plugin&from=2018-01-27&to=2025-12-31
 
 # Minimum requirements
 
-- [Node.js v16 or higher](https://nodejs.org)
+- [Node.js v20 or higher](https://nodejs.org)
 - [Serverless v3.0.0 or higher](https://github.com/serverless/serverless)
 
 # Installation
@@ -61,11 +62,25 @@ appSync:
 - [Variable Substitutions](doc/substitutions.md)
 - [Caching](doc/caching.md)
 - [Web Application Firewall (WAF)](doc/WAF.md)
+- [Testing Resolvers](doc/testing-resolvers.md)
 
 # CLI
 
 This plugin adds some useful CLI commands. See [CLI commands documentation](doc/commands.md)
 
+| Command                         | Description                                              |
+| ------------------------------- | -------------------------------------------------------- |
+| `sls appsync validate-schema`   | Validate the GraphQL schema                              |
+| `sls appsync get-introspection` | Export the introspection schema (JSON or SDL)            |
+| `sls appsync flush-cache`       | Flush the API cache                                      |
+| `sls appsync console`           | Open the AWS AppSync console                             |
+| `sls appsync cloudwatch`        | Open CloudWatch logs                                     |
+| `sls appsync logs`              | Stream logs to stdout                                    |
+| `sls appsync evaluate`          | Evaluate a JS resolver or VTL template without deploying |
+| `sls appsync env get`           | Get runtime environment variables of the deployed API    |
+| `sls appsync env set`           | Set a runtime environment variable on the deployed API   |
+| `sls appsync domain *`          | Manage custom domains                                    |
+
 # Variables
 
 This plugin exports some handy variables that you can use in your yml files to reference some values generated by CloudFormation:

doc/commands.md

@@ -2,6 +2,21 @@
 
 This plugin provides some useful commands to explore and manage your API.
 
+## Quick reference
+
+| Command                         | Description                         |
+| ------------------------------- | ----------------------------------- |
+| `sls appsync validate-schema`   | Validate the GraphQL schema         |
+| `sls appsync get-introspection` | Export the introspection schema     |
+| `sls appsync flush-cache`       | Flush the API cache                 |
+| `sls appsync console`           | Open the AWS console                |
+| `sls appsync cloudwatch`        | Open CloudWatch logs                |
+| `sls appsync logs`              | Stream logs to stdout               |
+| `sls appsync evaluate`          | Evaluate a resolver or VTL template |
+| `sls appsync env get`           | Get API environment variables       |
+| `sls appsync env set`           | Set an API environment variable     |
+| `sls appsync domain *`          | Manage custom domains               |
+
 ## `validate-schema`
 
 This commands allows you to validate your GraphQL schema.
@@ -62,6 +77,69 @@ Outputs the logs of the AppSync API to stdout.
 sls appsync logs --filter '86771d0c-c0f3-4f54-b048-793a233e3ed9'
 ```
 
+## `evaluate`
+
+Evaluate a resolver or VTL mapping template against a context without deploying. Uses the AppSync `EvaluateCode` and `EvaluateMappingTemplate` APIs.
+
+**Evaluate a JS resolver (APPSYNC_JS runtime)**
+
+The resolver must be a `UNIT` resolver with a `code` property defined in your configuration.
+
+**Options**
+
+- `--type` or `-t`: GraphQL type (e.g. `Query`)
+- `--field` or `-f`: GraphQL field (e.g. `getUser`)
+- `--function`: Function to evaluate: `request` or `response`. Default: `request`
+- `--context` or `-c`: Path to a JSON context file, or an inline JSON string. Default: `{}`
+
+```bash
+sls appsync evaluate --type Query --field getUser --function request
+sls appsync evaluate --type Query --field getUser --function response --context context.json
+sls appsync evaluate --type Mutation --field createPost --context '{"arguments":{"title":"Hello"}}'
+```
+
+**Evaluate a VTL mapping template**
+
+- `--template`: Path to a `.vtl` template file
+- `--context` or `-c`: Path to a JSON context file, or an inline JSON string. Default: `{}`
+
+```bash
+sls appsync evaluate --template templates/getUser.request.vtl
+sls appsync evaluate --template templates/getUser.request.vtl --context context.json
+```
+
+The command prints the evaluation result to stdout. Errors (including line/column info for JS) are printed to stderr.
+
+For a detailed guide on testing unit and pipeline resolvers with this command — including fixture structure, a shell script for chaining pipeline steps, and Jest integration test examples — see [Testing Resolvers](testing-resolvers.md).
+
+## `env`
+
+Manage the environment variables of the deployed AppSync API at runtime, without redeploying. Uses the `GetGraphqlApiEnvironmentVariables` and `PutGraphqlApiEnvironmentVariables` APIs.
+
+> **Note:** These commands operate on the _deployed_ API. To set environment variables that are baked into the CloudFormation stack, use the [`environment`](general-config.md) configuration key instead.
+
+### `env get`
+
+Prints all environment variables currently set on the deployed API.
+
+```bash
+sls appsync env get
+```
+
+### `env set`
+
+Adds or updates a single environment variable on the deployed API. Existing variables are preserved — only the specified key is changed.
+
+**Options**
+
+- `--key` or `-k`: Environment variable key (required)
+- `--value` or `-v`: Environment variable value (required)
+
+```bash
+sls appsync env set --key TABLE_NAME --value prod-table
+sls appsync env set --key STAGE --value production
+```
+
 ## `domain`
 
 Manage the domain for this AppSync API.