Implement strict mode (#233)

* Implement strict mode

* Add test for nest package

* Ensure strict mode works for express

* Ensure strict mode works for next

* Improve variable name

* Add changeset

* Only throw on unknown status

* Rename strict mode

* Undo breaking change to ApiRouteResponse

* Fix types after merge

* Address PR feedback

* Update changeset

* chore: add tests to dsl.spec.ts

* more tests and some simplification of types

* fix missing change for inference helpers

* docs

* fix tests after merge

---------

Co-authored-by: Youssef Gaber <1728215+Gabrola@users.noreply.github.com>

Author: gingermusketeer

.changeset/friendly-pugs-destroy.md

@@ -0,0 +1,10 @@
+---
+"@ts-rest/core": minor
+"@ts-rest/express": minor
+"@ts-rest/nest": minor
+"@ts-rest/next": minor
+---
+
+Implement strict mode at a contract level. Strict mode ensures that only known responses are allowed by the type system. This applies both on the server and client side. Enable this with `strictStatusCodes: true` when defining a contract.
+
+If you would like to have the vanilla client throw an error when the response status is not known then you will need to use `throwOnUnknownStatus` when initializing the client.

apps/docs/docs/core/core.md

@@ -175,3 +175,35 @@ export const contract = c.router({
   },
 });
 ```
+
+## Strict Response Status Codes
+
+To help with incremental adoption, ts-rest, by default, will allow any response status code to be returned from the server
+even if it is not defined in the contract.
+
+As a result, the response types on the client will include all possible HTTP status codes, even ones that are not defined
+in the contract with those mapping to a body type of `unknown`.
+
+If you would like to disable this functionality and only allow the response status codes defined in the contract, you can
+set the `strictStatusCodes` option to `true` when initializing the contract.
+
+```typescript
+const c = initContract();
+export const contract = c.router({
+  // ...endpoints
+}, {
+  strictStatusCodes: true,
+});
+```
+
+You can also set this option on a per-route basis which will also override the global option.
+
+```typescript
+const c = initContract();
+export const contract = c.router({
+  getPosts: {
+    ...,
+    strictStatusCodes: true,
+  }
+});
+```

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

@@ -1,5 +1,5 @@
 import * as fetchMock from 'fetch-mock-jest';
-import { initContract } from '..';
+import { HTTPStatusCode, initContract } from '..';
 import { ApiFetcherArgs, initClient } from './client';
 import { Equal, Expect } from './test-helpers';
 import { z } from 'zod';
@@ -134,13 +134,24 @@ export const router = c.router(
   }
 );
 
+const routerStrict = c.router(router, {
+  strictStatusCodes: true,
+});
+
 const client = initClient(router, {
   baseUrl: 'https://api.com',
   baseHeaders: {
     'X-Api-Key': 'foo',
   },
 });
 
+const clientStrict = initClient(routerStrict, {
+  baseUrl: 'https://api.com',
+  baseHeaders: {
+    'X-Api-Key': 'foo',
+  },
+});
+
 type ClientGetPostsType = Expect<
   Equal<
     Parameters<typeof client.posts.getPosts>[0],
@@ -187,6 +198,19 @@ type ClientGetPostType = Expect<
     }
   >
 >;
+type RouterHealthStrict = Expect<
+  Equal<typeof routerStrict.health['strictStatusCodes'], true>
+>;
+type RouterGetPostStrict = Expect<
+  Equal<typeof routerStrict.posts.getPost['strictStatusCodes'], true>
+>;
+type HealthReturnType = Awaited<ReturnType<typeof clientStrict.health>>;
+type ClientGetPostResponseType = Expect<
+  Equal<
+    HealthReturnType,
+    { status: 200; body: { message: string }; headers: Headers }
+  >
+>;
 
 describe('client', () => {
   beforeEach(() => {
@@ -654,6 +678,7 @@ type CustomClientGetPostType = Expect<
 describe('custom api', () => {
   beforeEach(() => {
     argsCalledMock.mockReset();
+    fetchMock.mockReset();
   });
 
   it('should allow a uploadProgress attribute on the api call', async () => {
@@ -738,7 +763,7 @@ describe('custom api', () => {
     );
   });
 
-  it('has correct types when throwOnUnknownStatus is configured', async () => {
+  it('has correct types when throwOnUnknownStatus only is configured', async () => {
     const client = initClient(router, {
       baseUrl: 'https://api.com',
       baseHeaders: {
@@ -751,6 +776,16 @@ describe('custom api', () => {
 
     const result = await client.posts.getPosts({});
 
+    type ClientGetPostsResponseStatusType = Expect<
+      Equal<typeof result.status, HTTPStatusCode>
+    >;
+  });
+
+  it('has correct types when strictStatusCode is configured', async () => {
+    fetchMock.getOnce({ url: 'https://api.com/posts' }, { status: 200 });
+
+    const result = await clientStrict.posts.getPosts({});
+
     type ClientGetPostsResponseStatusType = Expect<
       Equal<typeof result.status, 200>
     >;

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

@@ -1,9 +1,16 @@
-import { AppRoute, AppRouteMutation, AppRouter, isAppRoute } from './dsl';
+import {
+  AppRoute,
+  AppRouteMutation,
+  AppRouter,
+  AppRouteStrictStatusCodes,
+  isAppRoute,
+} from './dsl';
 import { insertParamsIntoPath, ParamsFromUrl } from './paths';
 import { convertQueryParamsToUrlString } from './query';
 import { HTTPStatusCode } from './status-codes';
 import {
   AreAllPropertiesOptional,
+  Extends,
   LowercaseKeys,
   Merge,
   OptionalIfAllOptional,
@@ -97,28 +104,28 @@ type DataReturnArgs<
   Without<DataReturnArgsBase<TRoute, TClientArgs>, never>
 >;
 
-export type ApiRouteResponseNoUnknownStatus<T> =
+export type ApiRouteResponse<T, TStrictStatusCodes = false> =
   | {
       [K in keyof T]: {
         status: K;
         body: ZodInferOrType<T[K]>;
         headers: Headers;
       };
-    }[keyof T];
-
-export type ApiRouteResponse<T> =
-  | ApiRouteResponseNoUnknownStatus<T>
-  | {
-      status: Exclude<HTTPStatusCode, keyof T>;
-      body: unknown;
-      headers: Headers;
-    };
+    }[keyof T]
+  | (TStrictStatusCodes extends true
+      ? never
+      : {
+          status: Exclude<HTTPStatusCode, keyof T>;
+          body: unknown;
+          headers: Headers;
+        });
 
 /**
  * @deprecated Only safe to use on the client-side. Use `ServerInferResponses`/`ClientInferResponses` instead.
  */
 export type ApiResponseForRoute<T extends AppRoute> = ApiRouteResponse<
-  T['responses']
+  T['responses'],
+  Extends<T, AppRouteStrictStatusCodes>
 >;
 
 /**
@@ -132,12 +139,10 @@ export function getRouteResponses<T extends AppRouter>(router: T) {
   };
 }
 
-type AppRouteFunctionReturn<
-  TRoute extends AppRoute,
-  TClientArgs extends ClientArgs
-> = TClientArgs extends { throwOnUnknownStatus: true }
-  ? ApiRouteResponseNoUnknownStatus<TRoute['responses']>
-  : ApiRouteResponse<TRoute['responses']>;
+type AppRouteFunctionReturn<TRoute extends AppRoute> = ApiRouteResponse<
+  TRoute['responses'],
+  Extends<TRoute, AppRouteStrictStatusCodes>
+>;
 
 /**
  * Returned from a mutation or query call
@@ -148,10 +153,10 @@ export type AppRouteFunction<
 > = AreAllPropertiesOptional<DataReturnArgs<TRoute, TClientArgs>> extends true
   ? (
       args?: Prettify<DataReturnArgs<TRoute, TClientArgs>>
-    ) => Promise<Prettify<AppRouteFunctionReturn<TRoute, TClientArgs>>>
+    ) => Promise<Prettify<AppRouteFunctionReturn<TRoute>>>
   : (
       args: Prettify<DataReturnArgs<TRoute, TClientArgs>>
-    ) => Promise<Prettify<AppRouteFunctionReturn<TRoute, TClientArgs>>>;
+    ) => Promise<Prettify<AppRouteFunctionReturn<TRoute>>>;
 
 export interface ClientArgs {
   baseUrl: string;
@@ -210,19 +215,21 @@ export const tsRestFetchApi: ApiFetcher = async ({
       body: await result.json(),
       headers: result.headers,
     };
-  } else if (contentType?.includes('text/plain')) {
+  }
+
+  if (contentType?.includes('text/plain')) {
     return {
       status: result.status,
       body: await result.text(),
       headers: result.headers,
     };
-  } else {
-    return {
-      status: result.status,
-      body: await result.blob(),
-      headers: result.headers,
-    };
   }
+
+  return {
+    status: result.status,
+    body: await result.blob(),
+    headers: result.headers,
+  };
 };
 
 const createFormData = (body: unknown) => {

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

@@ -363,4 +363,118 @@ describe('contract', () => {
       >
     >;
   });
+
+  it('should add strictStatusCodes=true option to routes', () => {
+    const contract = c.router(
+      {
+        getPost: {
+          method: 'GET',
+          path: '/posts/:id',
+          responses: {
+            200: c.body<{ id: number }>(),
+          },
+        },
+      },
+      {
+        strictStatusCodes: true,
+      }
+    );
+
+    expect(contract.getPost.strictStatusCodes).toStrictEqual(true);
+
+    type ContractShape = Expect<
+      Equal<
+        Pick<typeof contract.getPost, 'strictStatusCodes'>,
+        {
+          strictStatusCodes: true;
+        }
+      >
+    >;
+  });
+
+  it('should add strictStatusCodes=false option to routes', () => {
+    const contract = c.router(
+      {
+        getPost: {
+          method: 'GET',
+          path: '/posts/:id',
+          responses: {
+            200: c.body<{ id: number }>(),
+          },
+        },
+      },
+      {
+        strictStatusCodes: false,
+      }
+    );
+
+    expect(contract.getPost.strictStatusCodes).toStrictEqual(false);
+
+    type ContractShape = Expect<
+      Equal<
+        Pick<typeof contract.getPost, 'strictStatusCodes'>,
+        {
+          strictStatusCodes: false;
+        }
+      >
+    >;
+  });
+
+  it('should merge strictStatusCodes options correctly is route is true', () => {
+    const contract = c.router(
+      {
+        getPost: {
+          method: 'GET',
+          path: '/posts/:id',
+          responses: {
+            200: c.body<{ id: number }>(),
+          },
+          strictStatusCodes: true,
+        },
+      },
+      {
+        strictStatusCodes: false,
+      }
+    );
+
+    expect(contract.getPost.strictStatusCodes).toStrictEqual(true);
+
+    type ContractShape = Expect<
+      Equal<
+        Pick<typeof contract.getPost, 'strictStatusCodes'>,
+        {
+          strictStatusCodes: true;
+        }
+      >
+    >;
+  });
+
+  it('should merge strictStatusCodes options correctly if route is false', () => {
+    const contract = c.router(
+      {
+        getPost: {
+          method: 'GET',
+          path: '/posts/:id',
+          responses: {
+            200: c.body<{ id: number }>(),
+          },
+          strictStatusCodes: false,
+        },
+      },
+      {
+        strictStatusCodes: true,
+      }
+    );
+
+    expect(contract.getPost.strictStatusCodes).toStrictEqual(false);
+
+    type ContractShape = Expect<
+      Equal<
+        Pick<typeof contract.getPost, 'strictStatusCodes'>,
+        {
+          strictStatusCodes: false;
+        }
+      >
+    >;
+  });
 });