fix: enhance type safety for onQuery and onMutation handlers with generic parameters

Author: arnabrahman

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

@@ -78,6 +78,23 @@ class Router {
    *   return payload;
    * });
    
+   * export const handler = async (event, context) =>
+   *   app.resolve(event, context);
+   * ```
+   *
+   * You can also specify the type of the arguments using a generic type parameter:
+   * 
+   * @example
+   * ```ts
+   * import { AppSyncGraphQLResolver } from '@aws-lambda-powertools/event-handler/appsync-graphql';
+   *
+   * const app = new AppSyncGraphQLResolver();
+   *
+   * app.onQuery<{ postId: string }>('getPost', async ({ postId }) => {
+   *   // postId is now typed as string
+   *   return { id: postId };
+   * });
+   
    * export const handler = async (event, context) =>
    *   app.resolve(event, context);
    * ```
@@ -111,24 +128,24 @@ class Router {
    * @param options - Optional route options.
    * @param options.typeName - The name of the GraphQL type to use for the resolver (defaults to 'Query').
    */
-  public onQuery(
+  public onQuery<TParams extends Record<string, unknown>>(
     fieldName: string,
-    handler: OnQueryHandler,
+    handler: OnQueryHandler<TParams>,
     options?: GraphQlRouteOptions
   ): void;
   public onQuery(
     fieldName: string,
     options?: GraphQlRouteOptions
   ): MethodDecorator;
-  public onQuery(
+  public onQuery<TParams extends Record<string, unknown>>(
     fieldName: string,
-    handler?: OnQueryHandler | GraphQlRouteOptions,
+    handler?: OnQueryHandler<TParams> | GraphQlRouteOptions,
     options?: GraphQlRouteOptions
   ): MethodDecorator | undefined {
     if (handler && typeof handler === 'function') {
       this.onQueryRegistry.register({
         fieldName,
-        handler,
+        handler: handler as OnQueryHandler<Record<string, unknown>>,
         typeName: options?.typeName ?? 'Query',
       });
       return;
@@ -138,7 +155,7 @@ class Router {
       const routeOptions = isRecord(handler) ? handler : options;
       this.onQueryRegistry.register({
         fieldName,
-        handler: descriptor.value,
+        handler: descriptor.value as OnQueryHandler<Record<string, unknown>>,
         typeName: routeOptions?.typeName ?? 'Query',
       });
       return descriptor;
@@ -166,6 +183,23 @@ class Router {
    *   app.resolve(event, context);
    * ```
    *
+   * You can also specify the type of the arguments using a generic type parameter:
+   *
+   * @example
+   * ```ts
+   * import { AppSyncGraphQLResolver } from '@aws-lambda-powertools/event-handler/appsync-graphql';
+   *
+   * const app = new AppSyncGraphQLResolver();
+   *
+   * app.onMutation<{ title: string; content: string }>('createPost', async ({ title, content }) => {
+   *   // title and content are now typed as string
+   *   return { id: '123', title, content };
+   * });
+   *
+   * export const handler = async (event, context) =>
+   *   app.resolve(event, context);
+   * ```
+   *
    * As a decorator:
    *
    * @example
@@ -195,24 +229,24 @@ class Router {
    * @param options - Optional route options.
    * @param options.typeName - The name of the GraphQL type to use for the resolver (defaults to 'Mutation').
    */
-  public onMutation(
+  public onMutation<TParams extends Record<string, unknown>>(
     fieldName: string,
-    handler: OnMutationHandler,
+    handler: OnMutationHandler<TParams>,
     options?: GraphQlRouteOptions
   ): void;
   public onMutation(
     fieldName: string,
     options?: GraphQlRouteOptions
   ): MethodDecorator;
-  public onMutation(
+  public onMutation<TParams extends Record<string, unknown>>(
     fieldName: string,
-    handler?: OnMutationHandler | GraphQlRouteOptions,
+    handler?: OnMutationHandler<TParams> | GraphQlRouteOptions,
     options?: GraphQlRouteOptions
   ): MethodDecorator | undefined {
     if (handler && typeof handler === 'function') {
       this.onMutationRegistry.register({
         fieldName,
-        handler,
+        handler: handler as OnMutationHandler<Record<string, unknown>>,
         typeName: options?.typeName ?? 'Mutation',
       });
       return;
@@ -222,7 +256,7 @@ class Router {
       const routeOptions = isRecord(handler) ? handler : options;
       this.onMutationRegistry.register({
         fieldName,
-        handler: descriptor.value,
+        handler: descriptor.value as OnMutationHandler<Record<string, unknown>>,
         typeName: routeOptions?.typeName ?? 'Mutation',
       });
       return descriptor;

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

@@ -1,21 +1,33 @@
 import type { RouteHandlerRegistry } from '../appsync-graphql/RouteHandlerRegistry.js';
-import type { Anything, GenericLogger } from './common.js';
+import type { GenericLogger } from './common.js';
 
 // #region OnQuery fn
 
-type OnQuerySyncHandlerFn = ({ ...args }: Anything) => unknown;
+type OnQuerySyncHandlerFn<TParams extends Record<string, unknown>> = (
+  args: TParams
+) => unknown;
 
-type OnQueryHandlerFn = ({ ...args }: Anything) => Promise<unknown>;
+type OnQueryHandlerFn<TParams extends Record<string, unknown>> = (
+  args: TParams
+) => Promise<unknown>;
 
-type OnQueryHandler = OnQuerySyncHandlerFn | OnQueryHandlerFn;
+type OnQueryHandler<TParams extends Record<string, unknown>> =
+  | OnQuerySyncHandlerFn<TParams>
+  | OnQueryHandlerFn<TParams>;
 
 // #region OnMutation fn
 
-type OnMutationSyncHandlerFn = ({ ...args }: Anything) => unknown;
+type OnMutationSyncHandlerFn<TParams extends Record<string, unknown>> = (
+  args: TParams
+) => unknown;
 
-type OnMutationHandlerFn = ({ ...args }: Anything) => Promise<unknown>;
+type OnMutationHandlerFn<TParams extends Record<string, unknown>> = (
+  args: TParams
+) => Promise<unknown>;
 
-type OnMutationHandler = OnMutationSyncHandlerFn | OnMutationHandlerFn;
+type OnMutationHandler<TParams extends Record<string, unknown>> =
+  | OnMutationSyncHandlerFn<TParams>
+  | OnMutationHandlerFn<TParams>;
 
 // #region Resolver registry
 
@@ -47,7 +59,9 @@ type RouteHandlerOptions = {
   /**
    * The handler function to be called when the event is received
    */
-  handler: OnQueryHandler | OnMutationHandler;
+  handler:
+    | OnQueryHandler<Record<string, unknown>>
+    | OnMutationHandler<Record<string, unknown>>;
   /**
    * The field name of the event to be registered
    */