feat: add response validation to the client (#373)

* feat: automatic validating the schema on the client

* feat: add a flag to enable/disable the client validation behaviour

* chore: add minor changeset to the ts-rest/core package

* Update afraid-eagles-report.md

* docs: add guidelines for the `validateResponseOnClient` option

* docs: add notes for those using zod as the schema validator

* docs: move the caution for schema validation to the correct spot

---------

Co-authored-by: Michael Angelo Rivera <55844504+michaelangeloio@users.noreply.github.com>

Author: SeanCassiere

.changeset/afraid-eagles-report.md

@@ -0,0 +1,5 @@
+---
+'@ts-rest/core': minor
+---
+
+feat: add support for client-side response validation against contract schemas for `@ts-rest/core`

apps/docs/docs/core/core.md

@@ -90,13 +90,16 @@ This will force the client to always pass
 
 ```typescript
 const c = initContract();
-export const contract = c.router({
-  // ...endpoints
-}, {
-  baseHeaders: z.object({
-    authorization: z.string(),
-  }),
-});
+export const contract = c.router(
+  {
+    // ...endpoints
+  },
+  {
+    baseHeaders: z.object({
+      authorization: z.string(),
+    }),
+  }
+);
 ```
 
 ## Responses
@@ -165,6 +168,55 @@ export const contract = c.router({
 });
 ```
 
+### Schema validation on the client
+
+By default, all responses are inferred at the type-level by the client using the contract, and are not validated at runtime.
+
+However, you can use the `validateResponseOnClient` option to validate the response at runtime by checking it against the defined schema associated with the status code in the contract. By default, this option is set to `false`.
+
+If you would like to enable this functionality for all routes in the contract, you can set the `validateResponseOnClient` option to `true` when initializing the contract.
+
+```typescript
+const c = initContract();
+export const contract = c.router({
+  {
+    // ...endpoints
+  },
+  {
+    validateResponseOnClient: true,
+  }
+});
+```
+
+You can also control this option on a per-route basis which will also override the globally set option.
+
+```typescript
+const c = initContract();
+export const contract = c.router({
+  getPosts: {
+    ...,
+    validateResponseOnClient: true,
+  }
+});
+```
+
+:::caution
+When using `zod` as the schema, should the validation fail, the error will be thrown as a `ZodError`.
+
+You can catch this error and handle it however you like.
+
+```typescript
+try {
+  const posts = await client.getPosts();
+} catch (error) {
+  if (error instanceof ZodError) {
+    // handle error
+  }
+}
+```
+
+:::
+
 ## Combining Contracts
 
 You can combine contracts to create a single contract, helpful if you want many sub-contracts, especially if they are huge.
@@ -254,13 +306,16 @@ You can assign `baseHeaders` which will be merged with the contract `headers`. H
 
 ```typescript
 const c = initContract();
-export const contract = c.router({
-  // ...endpoints
-}, {
-  baseHeaders: z.object({
+export const contract = c.router(
+  {
+    // ...endpoints
+  },
+  {
+    baseHeaders: z.object({
       authorization: z.string(),
     }),
-});
+  }
+);
 ```
 
 ### Path Prefix

libs/ts-rest/core/src/lib/client.ts

@@ -8,15 +8,15 @@ import {
   ClientInferResponses,
   PartialClientInferRequest,
   NextClientArgs,
-  Frameworks
+  Frameworks,
 } from './infer-types';
 
 type RecursiveProxyObj<T extends AppRouter, TClientArgs extends ClientArgs> = {
   [TKey in keyof T]: T[TKey] extends AppRoute
-  ? AppRouteFunction<T[TKey], TClientArgs>
-  : T[TKey] extends AppRouter
-  ? RecursiveProxyObj<T[TKey], TClientArgs>
-  : never;
+    ? AppRouteFunction<T[TKey], TClientArgs>
+    : T[TKey] extends AppRouter
+    ? RecursiveProxyObj<T[TKey], TClientArgs>
+    : never;
 };
 
 /**
@@ -90,7 +90,8 @@ export const tsRestFetchApi: ApiFetcher = async ({
   credentials,
   signal,
   cache,
-  next
+  next,
+  route,
 }) => {
   const result = await fetch(path, {
     method,
@@ -99,16 +100,31 @@ export const tsRestFetchApi: ApiFetcher = async ({
     credentials,
     signal,
     cache,
-    next
+    next,
     // we must type cast here because the typescript types for RequestInit
     // do not include properties like "next" for Frameworks (like Nextjs)
   } as RequestInit);
   const contentType = result.headers.get('content-type');
 
-  if (contentType?.includes("application/") && contentType?.includes('json')) {
+  if (contentType?.includes('application/') && contentType?.includes('json')) {
+    if (!route.validateResponseOnClient) {
+      return {
+        status: result.status,
+        body: await result.json(),
+        headers: result.headers,
+      };
+    }
+
+    const jsonData = await result.json();
+    const statusCode = result.status;
+    const response = route.responses[statusCode];
+
     return {
-      status: result.status,
-      body: await result.json(),
+      status: statusCode,
+      body:
+        response && typeof response !== 'symbol' && 'parse' in response
+          ? response?.parse(jsonData)
+          : jsonData,
       headers: result.headers,
     };
   }
@@ -157,7 +173,7 @@ export const fetchApi = ({
   extraInputArgs,
   headers,
   signal,
-  next
+  next,
 }: {
   path: string;
   clientArgs: ClientArgs;
@@ -243,21 +259,31 @@ export const getCompleteUrl = (
   return `${baseUrl}${path}${queryComponent}`;
 };
 
-export const getRouteQuery = <TAppRoute extends AppRoute, Framework extends Frameworks = 'none'>(
+export const getRouteQuery = <
+  TAppRoute extends AppRoute,
+  Framework extends Frameworks = 'none'
+>(
   route: TAppRoute,
-  clientArgs: InitClientArgs,
+  clientArgs: InitClientArgs
 ) => {
   const knownResponseStatuses = Object.keys(route.responses);
   return async (
-    inputArgs?: Framework extends 'nextjs' ? 
-      ClientInferRequest<AppRouteMutation, ClientArgs, 'nextjs'> 
+    inputArgs?: Framework extends 'nextjs'
+      ? ClientInferRequest<AppRouteMutation, ClientArgs, 'nextjs'>
       : ClientInferRequest<AppRouteMutation, ClientArgs>
   ) => {
-    const { query, params, body, headers, extraHeaders, next, ...extraInputArgs } =
+    const {
+      query,
+      params,
+      body,
+      headers,
+      extraHeaders,
+      next,
+      ...extraInputArgs
+    } =
       // ---- Merge all framework Request infer types ----
-      inputArgs as ClientInferRequest<AppRouteMutation, ClientArgs, 'nextjs'> &
-        ClientInferRequest<AppRouteMutation, ClientArgs>
-      || {};
+      (inputArgs as ClientInferRequest<AppRouteMutation, ClientArgs, 'nextjs'> &
+        ClientInferRequest<AppRouteMutation, ClientArgs>) || {};
 
     const completeUrl = getCompleteUrl(
       query,

libs/ts-rest/core/src/lib/dsl.ts

@@ -15,7 +15,7 @@ declare const NullSymbol: unique symbol;
 export type ContractPlainType<T> = Opaque<T, 'ContractPlainType'>;
 export type ContractNullType = Opaque<typeof NullSymbol, 'ContractNullType'>;
 export type ContractAnyType =
-  | z.ZodTypeAny
+  | z.ZodSchema
   | ContractPlainType<unknown>
   | ContractNullType
   | null;
@@ -38,6 +38,7 @@ type AppRouteCommon = {
   >;
   strictStatusCodes?: boolean;
   metadata?: unknown;
+  validateResponseOnClient?: boolean;
 };
 
 /**
@@ -152,6 +153,7 @@ export type RouterOptions<TPrefix extends string = string> = {
   baseHeaders?: unknown;
   strictStatusCodes?: boolean;
   pathPrefix?: TPrefix;
+  validateResponseOnClient?: boolean;
 };
 
 /**