feat: Allow Next.js request validation through error handler (#444)

Co-authored-by: michaelangeloio <email@michaelangelo.io>

Author: dennyferra

.changeset/purple-rules-shake.md

@@ -0,0 +1,5 @@
+---
+'@ts-rest/next': minor
+---
+
+feat: `ts-rest/next` allow customization for zod validation errors

apps/docs/docs/next.mdx

@@ -74,6 +74,42 @@ export default createNextRouter(api, router, {
 });
 ```
 
+#### Request Validation Error Handling
+
+The default behavior when validating request schema is to return a 400 status with the corresponding ZodError.
+To customize handling of the request validation errors enable the `throwRequestValidation` option.
+This option allows you to handle the request validation error in the global `errorHandler` function.
+
+```typescript
+export default createNextRouter(api, router, {
+  throwRequestValidation: true,
+  errorHandler: (error: unknown, req: NextApiRequest, res: NextApiResponse) => {
+    if (error instanceof RequestValidationError) {
+      if (error.body !== null) {
+        return res
+          .status(400)
+          .json({ message: 'Malformed Body', errors: error.body.flatten() });
+      }
+
+      return res.status(400).json({ message: 'Bad Request' });
+    }
+  },
+});
+```
+
+```typescript
+export class RequestValidationError extends Error {
+  constructor(
+    public pathParams: z.ZodError | null,
+    public headers: z.ZodError | null,
+    public query: z.ZodError | null,
+    public body: z.ZodError | null,
+  ) {
+    super('[ts-rest] request validation failed');
+  }
+}
+```
+
 ## Future Work
 
 As this pattern doesn't support a lambda per endpoint, it is planned to provide a helper utility to allow individual endpoints to be created.

libs/ts-rest/next/src/lib/ts-rest-next.spec.ts

@@ -1,6 +1,10 @@
 import { initContract, ResponseValidationError } from '@ts-rest/core';
 import { NextApiRequest, NextApiResponse } from 'next';
-import { createNextRoute, createNextRouter } from './ts-rest-next';
+import {
+  createNextRoute,
+  createNextRouter,
+  RequestValidationError,
+} from './ts-rest-next';
 import { z } from 'zod';
 
 const c = initContract();
@@ -286,6 +290,47 @@ describe('createNextRouter', () => {
     });
   });
 
+  describe('request validation', () => {
+    it('fails with invalid query type', async () => {
+      const errorHandler = jest.fn();
+      const resultingRouter = createNextRouter(contract, nextEndpoint, {
+        throwRequestValidation: true,
+        errorHandler,
+      });
+
+      const req = mockReq('/test/100/throw', {
+        method: 'GET',
+        query: { field: 42 },
+      });
+
+      await resultingRouter(req, mockRes);
+
+      expect(errorHandler).toHaveBeenCalledWith(
+        expect.any(RequestValidationError),
+        expect.anything(),
+        expect.anything(),
+      );
+    });
+
+    it('does not throw with invalid query type', async () => {
+      const errorHandler = jest.fn();
+      const resultingRouter = createNextRouter(contract, nextEndpoint, {
+        throwRequestValidation: false,
+        errorHandler,
+      });
+
+      const req = mockReq('/test/100/throw', {
+        method: 'GET',
+        query: { field: 42 },
+      });
+
+      await resultingRouter(req, mockRes);
+
+      expect(errorHandler).not.toHaveBeenCalled();
+      expect(mockRes.status).toHaveBeenCalledWith(400);
+    });
+  });
+
   it('should handle non-json response types from contract', async () => {
     const c = initContract();
 

libs/ts-rest/next/src/lib/ts-rest-next.ts

@@ -18,6 +18,18 @@ import {
   validateResponse,
 } from '@ts-rest/core';
 import { getPathParamsFromArray } from './path-utils';
+import { z } from 'zod';
+
+export class RequestValidationError extends Error {
+  constructor(
+    public pathParams: z.ZodError | null,
+    public headers: z.ZodError | null,
+    public query: z.ZodError | null,
+    public body: z.ZodError | null,
+  ) {
+    super('[ts-rest] request validation failed');
+  }
+}
 
 type AppRouteImplementation<T extends AppRoute> = (
   args: ServerInferRequest<T, NextApiRequest['headers']> & {
@@ -177,14 +189,19 @@ export const createNextRouter = <T extends AppRouter>(
   options?: {
     jsonQuery?: boolean;
     responseValidation?: boolean;
+    throwRequestValidation?: boolean;
     errorHandler?: (
       err: unknown,
       req: NextApiRequest,
       res: NextApiResponse
     ) => void;
   }
 ) => {
-  const { jsonQuery = false, responseValidation = false } = options || {};
+  const {
+    jsonQuery = false,
+    responseValidation = false,
+    throwRequestValidation = false
+  } = options || {};
 
   const combinedRouter = mergeRouterAndImplementation(routes, obj);
 
@@ -209,35 +226,48 @@ export const createNextRouter = <T extends AppRouter>(
       passThroughExtraKeys: true,
     });
 
-    if (!pathParamsResult.success) {
-      return res.status(400).json(pathParamsResult.error);
-    }
-
     const headersResult = checkZodSchema(req.headers, route.headers, {
       passThroughExtraKeys: true,
     });
 
-    if (!headersResult.success) {
-      return res.status(400).send(headersResult.error);
-    }
-
     query = jsonQuery
       ? parseJsonQueryObject(query as Record<string, string>)
       : req.query;
 
     const queryResult = checkZodSchema(query, route.query);
 
-    if (!queryResult.success) {
-      return res.status(400).json(queryResult.error);
-    }
-
     const bodyResult = checkZodSchema(req.body, route.body);
 
-    if (!bodyResult.success) {
-      return res.status(400).json(bodyResult.error);
-    }
-
     try {
+      if (
+        !pathParamsResult.success ||
+        !headersResult.success ||
+        !queryResult.success ||
+        !bodyResult.success
+      ) {
+        if (throwRequestValidation) {
+          throw new RequestValidationError(
+            pathParamsResult.success ? null : pathParamsResult.error,
+            headersResult.success ? null : headersResult.error,
+            queryResult.success ? null : queryResult.error,
+            bodyResult.success ? null : bodyResult.error,
+          );
+        }
+
+        if (!pathParamsResult.success) {
+          return res.status(400).json(pathParamsResult.error);
+        }
+        if (!headersResult.success) {
+          return res.status(400).send(headersResult.error);
+        }
+        if (!queryResult.success) {
+          return res.status(400).json(queryResult.error);
+        }
+        if (!bodyResult.success) {
+          return res.status(400).json(bodyResult.error);
+        }
+      }
+
       const { body, status } = await route.implementation({
         body: bodyResult.data,
         query: queryResult.data,