feat(event-handler): add single resolver functionality for AppSync GraphQL API

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

@@ -0,0 +1,161 @@
+import type { Context } from 'aws-lambda';
+import type { AppSyncGraphQLEvent } from '../types/appsync-graphql.js';
+import { Router } from './Router.js';
+import { ResolverNotFoundException } from './errors.js';
+import { isAppSyncGraphQLEvent } from './utils.js';
+
+/**
+ * Resolver for AWS AppSync GraphQL APIs.
+ *
+ * This resolver is designed to handle the `onQuery` and `onMutation` events
+ * from AWS AppSync GraphQL APIs. It allows you to register handlers for these events
+ * and route them to the appropriate functions based on the event's field & type.
+ *
+ * @example
+ * ```ts
+ * import { AppSyncGraphQLResolver } from '@aws-lambda-powertools/event-handler/appsync-graphql';
+ *
+ * const app = new AppSyncGraphQLResolver();
+ *
+ * app.onQuery('getPost', async ({ id }) => {
+ *   // your business logic here
+ *   return {
+ *     id,
+ *     title: 'Post Title',
+ *     content: 'Post Content',
+ *   };
+ * });
+ *
+ * export const handler = async (event, context) =>
+ *   app.resolve(event, context);
+ * ```
+ */
+export class AppSyncGraphQLResolver extends Router {
+  /**
+   * Resolve the response based on the provided event and route handlers configured.
+   *
+   * @example
+   * ```ts
+   * import { AppSyncGraphQLResolver } from '@aws-lambda-powertools/event-handler/appsync-graphql';
+   *
+   * const app = new AppSyncGraphQLResolver();
+   *
+   * app.onQuery('getPost', async ({ id }) => {
+   *   // your business logic here
+   *   return {
+   *     id,
+   *     title: 'Post Title',
+   *     content: 'Post Content',
+   *   };
+   * });
+   *
+   * export const handler = async (event, context) =>
+   *   app.resolve(event, context);
+   * ```
+   *
+   * The method works also as class method decorator, so you can use it like this:
+   *
+   * @example
+   * ```ts
+   * import { AppSyncGraphQLResolver } from '@aws-lambda-powertools/event-handler/appsync-graphql';
+   *
+   * const app = new AppSyncGraphQLResolver();
+   *
+   * class Lambda {
+   *   ⁣@app.onQuery('getPost')
+   *   async handleGetPost({ id }) {
+   *     // your business logic here
+   *     return {
+   *       id,
+   *       title: 'Post Title',
+   *       content: 'Post Content',
+   *     };
+   *   }
+   *
+   *   async handler(event, context) {
+   *     return app.resolve(event, context);
+   *   }
+   * }
+   *
+   * const lambda = new Lambda();
+   * export const handler = lambda.handler.bind(lambda);
+   * ```
+   *
+   * @param event - The incoming event, which may be an AppSync GraphQL event or an array of events.
+   * @param context - The Lambda execution context.
+   */
+  public async resolve(event: unknown, context: Context): Promise<unknown> {
+    if (Array.isArray(event)) {
+      this.logger.warn('Batch resolver is not implemented yet');
+      return;
+    }
+    if (!isAppSyncGraphQLEvent(event)) {
+      this.logger.warn(
+        'Received an event that is not compatible with this resolver'
+      );
+      return;
+    }
+    try {
+      return await this.#executeSingleResolver(event);
+    } catch (error) {
+      this.logger.error(
+        `An error occurred in handler ${event.info.fieldName}`,
+        error
+      );
+      if (error instanceof ResolverNotFoundException) throw error;
+      return this.#formatErrorResponse(error);
+    }
+  }
+
+  /**
+   * Executes the appropriate resolver (query or mutation) for a given AppSync GraphQL event.
+   *
+   * This method attempts to resolve the handler for the specified field and type name
+   * from the query and mutation registries. If a matching handler is found, it invokes
+   * the handler with the event arguments. If no handler is found, it throws a
+   * `ResolverNotFoundException`.
+   *
+   * @param event - The AppSync GraphQL event containing resolver information.
+   * @throws {ResolverNotFoundException} If no resolver is registered for the given field and type.
+   */
+  async #executeSingleResolver(event: AppSyncGraphQLEvent): Promise<unknown> {
+    const { fieldName, parentTypeName: typeName } = event.info;
+    const queryHandlerOptions = this.onQueryRegistry.resolve(
+      typeName,
+      fieldName
+    );
+    if (queryHandlerOptions) {
+      return await queryHandlerOptions.handler.apply(this, [event.arguments]);
+    }
+
+    const mutationHandlerOptions = this.onMutationRegistry.resolve(
+      typeName,
+      fieldName
+    );
+    if (mutationHandlerOptions) {
+      return await mutationHandlerOptions.handler.apply(this, [
+        event.arguments,
+      ]);
+    }
+
+    throw new ResolverNotFoundException(
+      `No resolver found for ${typeName}-${fieldName}`
+    );
+  }
+
+  /**
+   * Format the error response to be returned to the client.
+   *
+   * @param error - The error object
+   */
+  #formatErrorResponse(error: unknown) {
+    if (error instanceof Error) {
+      return {
+        error: `${error.name} - ${error.message}`,
+      };
+    }
+    return {
+      error: 'An unknown error occurred',
+    };
+  }
+}

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

@@ -0,0 +1,86 @@
+import type {
+  GenericLogger,
+  RouteHandlerOptions,
+  RouteHandlerRegistryOptions,
+} from '../types/appsync-graphql.js';
+
+/**
+ * Registry for storing route handlers for the `query` and `mutation` events in AWS AppSync GraphQL API's.
+ *
+ * This class should not be used directly unless you are implementing a custom router.
+ * Instead, use the {@link Router} class, which is the recommended way to register routes.
+ */
+class RouteHandlerRegistry {
+  /**
+   * A map of registered route handlers, keyed by their type & field name.
+   */
+  protected readonly resolvers: Map<string, RouteHandlerOptions> = new Map();
+  /**
+   * A logger instance to be used for logging debug and warning messages.
+   */
+  readonly #logger: GenericLogger;
+  /**
+   * The event type stored in the registry.
+   */
+  readonly #eventType: 'onQuery' | 'onMutation';
+
+  public constructor(options: RouteHandlerRegistryOptions) {
+    this.#logger = options.logger;
+    this.#eventType = options.eventType ?? 'onQuery';
+  }
+
+  /**
+   * Registers a new GraphQL route resolver for a specific type and field.
+   *
+   * @param options - The options for registering the route handler, including the GraphQL type name, field name, and the handler function.
+   * @param options.fieldName - The field name of the GraphQL type to be registered
+   * @param options.handler - The handler function to be called when the GraphQL event is received
+   * @param options.typeName - The name of the GraphQL type to be registered
+   *
+   */
+  public register(options: RouteHandlerOptions): void {
+    const { fieldName, handler, typeName } = options;
+    this.#logger.debug(
+      `Adding ${this.#eventType} resolver for field ${typeName}.${fieldName}`
+    );
+    const cacheKey = this.#makeKey(typeName, fieldName);
+    if (this.resolvers.has(cacheKey)) {
+      this.#logger.warn(
+        `A resolver for field '${fieldName}' is already registered for '${typeName}'. The previous resolver will be replaced.`
+      );
+    }
+    this.resolvers.set(cacheKey, {
+      fieldName,
+      handler,
+      typeName,
+    });
+  }
+
+  /**
+   * Resolves the handler for a specific GraphQL API event.
+   *
+   * @param typeName - The name of the GraphQL type (e.g., "Query", "Mutation", or a custom type).
+   * @param fieldName - The name of the field within the specified type.
+   */
+  public resolve(
+    typeName: string,
+    fieldName: string
+  ): RouteHandlerOptions | undefined {
+    this.#logger.debug(
+      `Looking for ${this.#eventType} resolver for type=${typeName}, field=${fieldName}`
+    );
+    return this.resolvers.get(this.#makeKey(typeName, fieldName));
+  }
+
+  /**
+   * Generates a unique key by combining the provided GraphQL type name and field name.
+   *
+   * @param typeName - The name of the GraphQL type.
+   * @param fieldName - The name of the GraphQL field.
+   */
+  #makeKey(typeName: string, fieldName: string): string {
+    return `${typeName}.${fieldName}`;
+  }
+}
+
+export { RouteHandlerRegistry };