Implement throwOnUnknownStatus to throw on unexpected responses (#228)

Author: gingermusketeer

.changeset/wise-pumas-kick.md

@@ -0,0 +1,5 @@
+---
+"@ts-rest/core": minor
+---
+
+Add `throwOnUnknownStatus` to `initClient` configuration. When set to `true` the client will throw errors for all status codes returned by the server which are not defined in the contract.

libs/ts-rest/core/src/index.ts

@@ -8,3 +8,4 @@ export * from './lib/zod-utils';
 export * from './lib/server';
 export * from './lib/response-validation-error';
 export * from './lib/infer-types';
+export * from './lib/unknown-status-error';

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

@@ -691,4 +691,38 @@ describe('custom api', () => {
       })
     );
   });
+
+  it('has correct types when throwOnUnknownStatus is configured', async () => {
+    const client = initClient(router, {
+      baseUrl: 'https://api.com',
+      baseHeaders: {
+        'X-Api-Key': 'foo',
+      },
+      throwOnUnknownStatus: true,
+    });
+
+    fetchMock.getOnce({ url: 'https://api.com/posts' }, { status: 200 });
+
+    const result = await client.posts.getPosts({});
+
+    type ClientGetPostsResponseStatusType = Expect<
+      Equal<typeof result.status, 200>
+    >;
+  });
+
+  it('throws an error when throwOnUnknownStatus is configured and response is unknown', async () => {
+    const client = initClient(router, {
+      baseUrl: 'https://isolated.com',
+      baseHeaders: {
+        'X-Api-Key': 'foo',
+      },
+      throwOnUnknownStatus: true,
+    });
+
+    fetchMock.getOnce({ url: 'https://isolated.com/posts' }, { status: 419 });
+
+    await expect(client.posts.getPosts({})).rejects.toThrowError(
+      'Server returned unexpected response. Expected one of: 200 got: 419'
+    );
+  });
 });

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

@@ -13,6 +13,7 @@ import {
   ZodInferOrType,
   ZodInputOrType,
 } from './type-utils';
+import { UnknownStatusError } from './unknown-status-error';
 
 type RecursiveProxyObj<T extends AppRouter, TClientArgs extends ClientArgs> = {
   [TKey in keyof T]: T[TKey] extends AppRoute
@@ -22,6 +23,17 @@ type RecursiveProxyObj<T extends AppRouter, TClientArgs extends ClientArgs> = {
     : never;
 };
 
+type RecursiveProxyObjNoUnknownStatus<
+  T extends AppRouter,
+  TClientArgs extends ClientArgs & { throwOnUnknownStatus: true }
+> = {
+  [TKey in keyof T]: T[TKey] extends AppRoute
+    ? AppRouteFunctionNoUnknownStatus<T[TKey], TClientArgs>
+    : T[TKey] extends AppRouter
+    ? RecursiveProxyObjNoUnknownStatus<T[TKey], TClientArgs>
+    : never;
+};
+
 type AppRouteMutationType<T> = ZodInputOrType<T>;
 
 /**
@@ -96,13 +108,16 @@ type DataReturnArgs<
   Without<DataReturnArgsBase<TRoute, TClientArgs>, never>
 >;
 
-export type ApiRouteResponse<T> =
+export type ApiRouteResponseNoUnknownStatus<T> =
   | {
       [K in keyof T]: {
         status: K;
         body: ZodInferOrType<T[K]>;
       };
-    }[keyof T]
+    }[keyof T];
+
+export type ApiRouteResponse<T> =
+  | ApiRouteResponseNoUnknownStatus<T>
   | {
       status: Exclude<HTTPStatusCode, keyof T>;
       body: unknown;
@@ -140,6 +155,22 @@ export type AppRouteFunction<
       args: Prettify<DataReturnArgs<TRoute, TClientArgs>>
     ) => Promise<Prettify<ApiRouteResponse<TRoute['responses']>>>;
 
+/**
+ * Returned from a mutation or query call when NoUnknownStatus mode is enabled
+ */
+export type AppRouteFunctionNoUnknownStatus<
+  TRoute extends AppRoute,
+  TClientArgs extends ClientArgs
+> = AreAllPropertiesOptional<DataReturnArgs<TRoute, TClientArgs>> extends true
+  ? (
+      args?: Prettify<DataReturnArgs<TRoute, TClientArgs>>
+    ) => Promise<Prettify<ApiRouteResponseNoUnknownStatus<TRoute['responses']>>>
+  : (
+      args: Prettify<DataReturnArgs<TRoute, TClientArgs>>
+    ) => Promise<
+      Prettify<ApiRouteResponseNoUnknownStatus<TRoute['responses']>>
+    >;
+
 export interface ClientArgs {
   baseUrl: string;
   baseHeaders: Record<string, string>;
@@ -293,8 +324,9 @@ export const getCompleteUrl = (
 
 export const getRouteQuery = <TAppRoute extends AppRoute>(
   route: TAppRoute,
-  clientArgs: ClientArgs
+  clientArgs: InitClientArgs
 ) => {
+  const knownResponseStatuses = Object.keys(route.responses);
   return async (inputArgs?: DataReturnArgsBase<any, ClientArgs>) => {
     const { query, params, body, headers, extraHeaders, ...extraInputArgs } =
       inputArgs || {};
@@ -307,7 +339,7 @@ export const getRouteQuery = <TAppRoute extends AppRoute>(
       !!clientArgs.jsonQuery
     );
 
-    return await fetchApi({
+    const response = await fetchApi({
       path: completeUrl,
       clientArgs,
       route,
@@ -319,6 +351,15 @@ export const getRouteQuery = <TAppRoute extends AppRoute>(
         ...headers,
       },
     });
+
+    if (!clientArgs.throwOnUnknownStatus) {
+      return response;
+    }
+
+    if (knownResponseStatuses.includes(response.status.toString())) {
+      return response;
+    }
+    throw new UnknownStatusError(response, knownResponseStatuses);
   };
 };
 
@@ -327,10 +368,28 @@ export type InitClientReturn<
   TClientArgs extends ClientArgs
 > = RecursiveProxyObj<T, TClientArgs>;
 
-export const initClient = <T extends AppRouter, TClientArgs extends ClientArgs>(
+export type InitClientReturnNoUnknownStatus<
+  T extends AppRouter,
+  TClientArgs extends ClientArgs & { throwOnUnknownStatus: true }
+> = RecursiveProxyObjNoUnknownStatus<T, TClientArgs>;
+
+export type InitClientArgs = ClientArgs & {
+  /**
+   * Ensures that the responses from the server match those defined in the
+   * contract.
+   */
+  throwOnUnknownStatus?: boolean;
+};
+
+export const initClient = <
+  T extends AppRouter,
+  TClientArgs extends InitClientArgs
+>(
   router: T,
   args: TClientArgs
-): InitClientReturn<T, TClientArgs> => {
+): TClientArgs extends { throwOnUnknownStatus: true }
+  ? InitClientReturnNoUnknownStatus<T, TClientArgs>
+  : InitClientReturn<T, TClientArgs> => {
   return Object.fromEntries(
     Object.entries(router).map(([key, subRouter]) => {
       if (isAppRoute(subRouter)) {

libs/ts-rest/core/src/lib/unknown-status-error.ts

@@ -0,0 +1,15 @@
+export class UnknownStatusError extends Error {
+  response: { status: number; body: unknown };
+
+  constructor(
+    response: { status: number; body: unknown },
+    knownResponseStatuses: string[]
+  ) {
+    const expectedStatuses = knownResponseStatuses.join(',');
+    super(
+      `Server returned unexpected response. Expected one of: ${expectedStatuses} got: ${response.status}`
+    );
+
+    this.response = response;
+  }
+}