feat(event-handler): add support for error handling in AppSync GraphQL

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 common errors outside your resolver and return a custom response.
+
+You can use a VTL response mapping template to detect these custom responses and forward them to the client gracefully.
+
+=== "Exception Handling"
+
+    ```typescript hl_lines="11-18 21-23"
+    --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,27 @@
+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)

packages/event-handler/src/appsync-graphql/AppSyncGraphQLResolver.ts

@@ -197,7 +197,7 @@ class AppSyncGraphQLResolver extends Router {
     try {
       return await fn();
     } catch (error) {
-      return this.#handleError(
+      return await this.#handleError(
         error,
         `An error occurred in handler ${event.info.fieldName}`
       );
@@ -209,16 +209,34 @@ class AppSyncGraphQLResolver extends Router {
    *
    * Logs the provided error message and error object. If the error is an instance of
    * `InvalidBatchResponseException` or `ResolverNotFoundException`, it is re-thrown.
+   * Checks for registered exception handlers and calls them if available.
    * Otherwise, the error is formatted into a response using `#formatErrorResponse`.
    *
    * @param error - The error object to handle.
    * @param errorMessage - A descriptive message to log alongside the error.
    * @throws InvalidBatchResponseException | ResolverNotFoundException
    */
-  #handleError(error: unknown, errorMessage: string) {
+  async #handleError(error: unknown, errorMessage: string): Promise<unknown> {
     this.logger.error(errorMessage, error);
     if (error instanceof InvalidBatchResponseException) throw error;
     if (error instanceof ResolverNotFoundException) throw error;
+    if (this.exceptionHandlerRegistry.hasHandlers() && error instanceof Error) {
+      const exceptionHandler = this.exceptionHandlerRegistry.resolve(error);
+      if (exceptionHandler) {
+        try {
+          this.logger.debug(
+            `Calling exception handler for error: ${error.name}`
+          );
+          return await exceptionHandler(error);
+        } catch (handlerError) {
+          this.logger.error(
+            `Exception handler for ${error.name} threw an error`,
+            handlerError
+          );
+        }
+      }
+    }
+
     return this.#formatErrorResponse(error);
   }
 

packages/event-handler/src/appsync-graphql/ExceptionHandlerRegistry.ts

@@ -0,0 +1,80 @@
+import type { GenericLogger } from '@aws-lambda-powertools/commons/types';
+import type {
+  ExceptionHandler,
+  ExceptionHandlerOptions,
+  ExceptionHandlerRegistryOptions,
+} from '../types/appsync-graphql.js';
+
+/**
+ * Registry for storing exception handlers for GraphQL resolvers in AWS AppSync GraphQL API's.
+ */
+class ExceptionHandlerRegistry {
+  /**
+   * A map of registered exception handlers, keyed by their error class name.
+   */
+  protected readonly handlers: Map<string, ExceptionHandlerOptions> = new Map();
+  /**
+   * A logger instance to be used for logging debug and warning messages.
+   */
+  readonly #logger: Pick<GenericLogger, 'debug' | 'warn' | 'error'>;
+
+  public constructor(options: ExceptionHandlerRegistryOptions) {
+    this.#logger = options.logger;
+  }
+
+  /**
+   * Registers an exception handler for a specific error class.
+   *
+   * If a handler for the given error class is already registered, it will be replaced and a warning will be logged.
+   *
+   * @param options - The options containing the error class and its associated handler.
+   */
+  public register(options: ExceptionHandlerOptions<Error>): void {
+    const { error, handler } = options;
+    const errorName = error.name;
+
+    this.#logger.debug(`Adding exception handler for error class ${errorName}`);
+
+    if (this.handlers.has(errorName)) {
+      this.#logger.warn(
+        `An exception handler for error class '${errorName}' is already registered. The previous handler will be replaced.`
+      );
+    }
+
+    this.handlers.set(errorName, {
+      error,
+      handler: handler as ExceptionHandler,
+    });
+  }
+
+  /**
+   * Resolves and returns the appropriate exception handler for a given error instance.
+   *
+   * This method attempts to find a registered exception handler based on the error class name.
+   * If a matching handler is found, it is returned; otherwise, `undefined` is returned.
+   *
+   * @param error - The error instance for which to resolve an exception handler.
+   */
+  public resolve(error: Error): ExceptionHandler | undefined {
+    const errorName = error.name;
+    this.#logger.debug(`Looking for exception handler for error: ${errorName}`);
+
+    const handlerOptions = this.handlers.get(errorName);
+    if (handlerOptions) {
+      this.#logger.debug(`Found exact match for error class: ${errorName}`);
+      return handlerOptions.handler;
+    }
+
+    this.#logger.debug(`No exception handler found for error: ${errorName}`);
+    return undefined;
+  }
+
+  /**
+   * Checks if there are any registered exception handlers.
+   */
+  public hasHandlers(): boolean {
+    return this.handlers.size > 0;
+  }
+}
+
+export { ExceptionHandlerRegistry };

packages/event-handler/src/appsync-graphql/Router.ts

@@ -5,11 +5,14 @@ import {
 } from '@aws-lambda-powertools/commons/utils/env';
 import type {
   BatchResolverHandler,
+  ErrorClass,
+  ExceptionHandler,
   GraphQlBatchRouteOptions,
   GraphQlRouteOptions,
   GraphQlRouterOptions,
   ResolverHandler,
 } from '../types/appsync-graphql.js';
+import { ExceptionHandlerRegistry } from './ExceptionHandlerRegistry.js';
 import { RouteHandlerRegistry } from './RouteHandlerRegistry.js';
 
 /**
@@ -24,6 +27,10 @@ class Router {
    * A map of registered routes for GraphQL batch events, keyed by their fieldNames.
    */
   protected readonly batchResolverRegistry: RouteHandlerRegistry;
+  /**
+   * A map of registered exception handlers for handling errors in GraphQL resolvers.
+   */
+  protected readonly exceptionHandlerRegistry: ExceptionHandlerRegistry;
   /**
    * A logger instance to be used for logging debug, warning, and error messages.
    *
@@ -51,6 +58,9 @@ class Router {
     this.batchResolverRegistry = new RouteHandlerRegistry({
       logger: this.logger,
     });
+    this.exceptionHandlerRegistry = new ExceptionHandlerRegistry({
+      logger: this.logger,
+    });
     this.isDev = isDevMode();
   }
 
@@ -946,6 +956,110 @@ class Router {
       return descriptor;
     };
   }
+
+  /**
+   * Register an exception handler for a specific error class.
+   *
+   * Registers a handler for a specific error class that can be thrown by GraphQL resolvers.
+   * The handler will be invoked when an error of the specified class is thrown from any
+   * resolver function.
+   *
+   * @example
+   * ```ts
+   * import { AppSyncGraphQLResolver } from '@aws-lambda-powertools/event-handler/appsync-graphql';
+   * import { AssertionError } from 'assert';
+   *
+   * const app = new AppSyncGraphQLResolver();
+   *
+   * // Register an exception handler for AssertionError
+   * app.exceptionHandler(AssertionError, async (error) => {
+   *   return {
+   *     error: {
+   *       message: error.message,
+   *       type: error.name
+   *     }
+   *   };
+   * });
+   *
+   * // Register a resolver that might throw an AssertionError
+   * app.onQuery('createSomething', async () => {
+   *   throw new AssertionError({
+   *     message: 'This is an assertion Error',
+   *   });
+   * });
+   *
+   * export const handler = async (event, context) =>
+   *   app.resolve(event, context);
+   * ```
+   *
+   * As a decorator:
+   *
+   * @example
+   * ```ts
+   * import { AppSyncGraphQLResolver } from '@aws-lambda-powertools/event-handler/appsync-graphql';
+   * import { AssertionError } from 'assert';
+   *
+   * const app = new AppSyncGraphQLResolver();
+   *
+   * class Lambda {
+   *   ⁣@app.exceptionHandler(AssertionError)
+   *   async handleAssertionError(error: AssertionError) {
+   *     return {
+   *       error: {
+   *         message: error.message,
+   *         type: error.name
+   *       }
+   *     };
+   *   }
+   *
+   *   ⁣@app.onQuery('getUser')
+   *   async getUser() {
+   *     throw new AssertionError({
+   *       message: 'This is an assertion Error',
+   *     });
+   *   }
+   *
+   *   async handler(event, context) {
+   *     return app.resolve(event, context, {
+   *       scope: this, // bind decorated methods to the class instance
+   *     });
+   *   }
+   * }
+   *
+   * const lambda = new Lambda();
+   * export const handler = lambda.handler.bind(lambda);
+   * ```
+   *
+   * @param error - The error class to handle.
+   * @param handler - The handler function to be called when the error is caught.
+   */
+  public exceptionHandler<T extends Error>(
+    error: ErrorClass<T>,
+    handler: ExceptionHandler<T>
+  ): void;
+  public exceptionHandler<T extends Error>(
+    error: ErrorClass<T>
+  ): MethodDecorator;
+  public exceptionHandler<T extends Error>(
+    error: ErrorClass<T>,
+    handler?: ExceptionHandler<T>
+  ): MethodDecorator | undefined {
+    if (typeof handler === 'function') {
+      this.exceptionHandlerRegistry.register({
+        error,
+        handler: handler as ExceptionHandler<Error>,
+      });
+      return;
+    }
+
+    return (_target, _propertyKey, descriptor: PropertyDescriptor) => {
+      this.exceptionHandlerRegistry.register({
+        error,
+        handler: descriptor?.value,
+      });
+      return descriptor;
+    };
+  }
 }
 
 export { Router };