doc: exception handling support in appsync-graphql

Author: arnabrahman

docs/Dockerfile

@@ -2,7 +2,7 @@
 FROM squidfunk/mkdocs-material@sha256:bb7b015690d9fb5ef0dbc98ca3520f153aa43129fb96aec5ca54c9154dc3b729
 
 # Install Node.js
-RUN apk add --no-cache nodejs=22.13.1-r0 npm
+RUN apk add --no-cache nodejs=22.15.1-r0 npm
 
 COPY requirements.txt /tmp/
 RUN pip install --require-hashes -r /tmp/requirements.txt

docs/features/event-handler/appsync-graphql.md

@@ -148,6 +148,30 @@ You can access the original Lambda event or context for additional information.
 
     1. The `event` parameter contains the original AppSync event and has type `AppSyncResolverEvent` from the `@types/aws-lambda`.
 
+### Exception Handling
+
+You can use the **`exceptionHandler`** method with any exception. This allows you to handle a common exception outside your resolver.
+
+When using exception handlers, you'll also need to configure your AppSync response mapping template to properly handle the custom error responses.
+
+=== "Exception Handling"
+
+    ```typescript hl_lines="11-13 16-18"
+    --8<-- "examples/snippets/event-handler/appsync-graphql/exceptionHandling.ts"
+    ```
+
+=== "VTL Response Mapping Template"
+
+    ```velocity hl_lines="1-3"
+    --8<-- "examples/snippets/event-handler/appsync-graphql/exceptionHandlingResponseMapping.vtl"
+    ```
+
+=== "Exception Handling response"
+
+    ```json hl_lines="11 20"
+    --8<-- "examples/snippets/event-handler/appsync-graphql/exceptionHandlingResponse.json"
+    ```
+
 ### Logging
 
 By default, the utility uses the global `console` logger and emits only warnings and errors.

examples/snippets/event-handler/appsync-graphql/exceptionHandling.ts

@@ -0,0 +1,22 @@
+import { AppSyncGraphQLResolver } from '@aws-lambda-powertools/event-handler/appsync-graphql';
+import { Logger } from '@aws-lambda-powertools/logger';
+import { AssertionError } from 'assert';
+import type { Context } from 'aws-lambda';
+
+const logger = new Logger({
+  serviceName: 'MyService',
+});
+const app = new AppSyncGraphQLResolver({ logger });
+
+app.exceptionHandler(AssertionError, async (error) => {
+  return { error: { message: error.message, type: error.name } };
+});
+
+app.onQuery('createSomething', async () => {
+  throw new AssertionError({
+    message: 'This is an assertion Error',
+  });
+});
+
+export const handler = async (event: unknown, context: Context) =>
+  app.resolve(event, context);

examples/snippets/event-handler/appsync-graphql/exceptionHandlingResponse.json

@@ -0,0 +1,23 @@
+{
+  "data": {
+    "createSomething": null
+  },
+  "errors": [
+    {
+      "path": [
+        "createSomething"
+      ],
+      "data": null,
+      "errorType": "AssertionError",
+      "errorInfo": null,
+      "locations": [
+        {
+          "line": 2,
+          "column": 3,
+          "sourceName": null
+        }
+      ],
+      "message": "This is an assertion Error"
+    }
+  ]
+}

examples/snippets/event-handler/appsync-graphql/exceptionHandlingResponseMapping.vtl

@@ -0,0 +1,5 @@
+#if (!$util.isNull($ctx.result.error))
+  $util.error($ctx.result.error.message, $ctx.result.error.type)
+#end
+
+$utils.toJson($ctx.result)