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

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

@@ -148,6 +148,38 @@ 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 to handle any exception. This allows you to handle common errors outside your resolver and return a custom response.
+
+The `exceptionHandler` method also supports passing an array of exceptions that you wish to handle with a single handler.
+
+You can use an AppSync JavaScript resolver or 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"
+    ```
+
+=== "APPSYNC JS Resolver"
+
+    ```js hl_lines="11-13"
+    --8<-- "examples/snippets/event-handler/appsync-graphql/exceptionHandlingResolver.js"
+    ```
+
+=== "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 'node: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/exceptionHandlingResolver.js

@@ -0,0 +1,15 @@
+import { util } from '@aws-appsync/utils';
+
+export function request(ctx) {
+  return {
+    operation: 'Invoke',
+    payload: ctx,
+  };
+}
+
+export function response(ctx) {
+  if (ctx.result.error) {
+    return util.error(ctx.result.error.message, ctx.result.error.type);
+  }
+  return ctx.result;
+}

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

@@ -166,7 +166,8 @@ class AppSyncGraphQLResolver extends Router {
       }
       return this.#withErrorHandling(
         () => this.#executeBatchResolvers(event, context, options),
-        event[0]
+        event[0],
+        options
       );
     }
     if (!isAppSyncGraphQLEvent(event)) {
@@ -178,7 +179,8 @@ class AppSyncGraphQLResolver extends Router {
 
     return this.#withErrorHandling(
       () => this.#executeSingleResolver(event, context, options),
-      event
+      event,
+      options
     );
   }
 
@@ -189,17 +191,20 @@ class AppSyncGraphQLResolver extends Router {
    *
    * @param fn - A function returning a Promise to be executed with error handling.
    * @param event - The AppSync resolver event (single or first of batch).
+   * @param options - Optional resolve options for customizing resolver behavior.
    */
   async #withErrorHandling(
     fn: () => Promise<unknown>,
-    event: AppSyncResolverEvent<Record<string, unknown>>
+    event: AppSyncResolverEvent<Record<string, unknown>>,
+    options?: ResolveOptions
   ): Promise<unknown> {
     try {
       return await fn();
     } catch (error) {
       return this.#handleError(
         error,
-        `An error occurred in handler ${event.info.fieldName}`
+        `An error occurred in handler ${event.info.fieldName}`,
+        options
       );
     }
   }
@@ -209,16 +214,39 @@ 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.
+   * @param options - Optional resolve options for customizing resolver behavior.
    * @throws InvalidBatchResponseException | ResolverNotFoundException
    */
-  #handleError(error: unknown, errorMessage: string) {
+  async #handleError(
+    error: unknown,
+    errorMessage: string,
+    options?: ResolveOptions
+  ): Promise<unknown> {
     this.logger.error(errorMessage, error);
     if (error instanceof InvalidBatchResponseException) throw error;
     if (error instanceof ResolverNotFoundException) throw error;
+    if (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.apply(options?.scope ?? this, [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,93 @@
+import type { GenericLogger } from '@aws-lambda-powertools/commons/types';
+import type {
+  ErrorClass,
+  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 one or more error classes.
+   *
+   * 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(es) and their associated handler.
+   * @param options.error - A single error class or an array of error classes to handle.
+   * @param options.handler - The exception handler function that will be invoked when the error occurs.
+   */
+  public register(options: ExceptionHandlerOptions<Error>): void {
+    const { error, handler } = options;
+    const errors = Array.isArray(error) ? error : [error];
+
+    for (const err of errors) {
+      this.registerErrorHandler(err, handler);
+    }
+  }
+
+  /**
+   * Registers a error handler for a specific error class.
+   *
+   * @param errorClass - The error class to register the handler for.
+   * @param handler - The exception handler function.
+   */
+  private registerErrorHandler(
+    errorClass: ErrorClass<Error>,
+    handler: ExceptionHandler
+  ): void {
+    const errorName = errorClass.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: errorClass,
+      handler,
+    });
+  }
+
+  /**
+   * 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, `null` is returned.
+   *
+   * @param error - The error instance for which to resolve an exception handler.
+   */
+  public resolve(error: Error): ExceptionHandler | null {
+    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 null;
+  }
+}
+
+export { ExceptionHandlerRegistry };