feat(core): add contract option to define common responses (#558)

Author: Gabrola

.changeset/unlucky-crabs-fix.md

@@ -0,0 +1,5 @@
+---
+'@ts-rest/core': minor
+---
+
+Add contract option to define common responses

apps/docs/docs/core/core.md

@@ -165,6 +165,28 @@ export const contract = c.router({
 });
 ```
 
+### Common Responses
+
+APIs often have shared common response schemas, specifically for error responses. You can define these common responses in the contract options.
+
+```typescript
+const c = initContract();
+export const contract = c.router(
+  {
+    // ...endpoints
+  },
+  {
+    commonResponses: {
+      404: c.type<{ message: 'Not Found'; reason: string }>(),
+      500: c.otherResponse({
+        contentType: 'text/plain',
+        body: z.literal('Server Error'),
+      }),
+    },
+  }
+);
+```
+
 ### 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

apps/docs/docs/next.mdx

@@ -40,9 +40,7 @@ export default createNextRouter(contract, router);
 
 `createNextRouter` is a function that takes a contract and a complete router, and creates endpoints, with the correct methods, paths and callbacks.
 
-## Single Route Handler
-
-It's also possible to create a handler for a single contract route
+It's also possible to create a handler for a single contract route.
 
 ```typescript
 // pages/api/posts/index.tsx
@@ -130,9 +128,3 @@ export class RequestValidationError extends Error {
   }
 }
 ```
-
-## 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.
-
-The downside of this is that it will not be possible to give a Typescript warning if the path is incorrect.

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

@@ -789,4 +789,157 @@ describe('contract', () => {
       Equal<(typeof contract.get.responses)['204'], ContractNoBodyType>
     >;
   });
+
+  it('should be typed correctly with merged common responses', () => {
+    const contract = c.router(
+      {
+        posts: {
+          getPost: {
+            method: 'GET',
+            path: '/posts/:id',
+            responses: {
+              200: z.object({
+                id: z.number(),
+              }),
+            },
+          },
+        },
+      },
+      {
+        commonResponses: {
+          404: z.object({
+            message: z.string(),
+          }),
+        },
+      },
+    );
+
+    type ContractShape = Expect<
+      Equal<
+        typeof contract,
+        {
+          posts: {
+            getPost: {
+              method: 'GET';
+              path: '/posts/:id';
+              responses: {
+                200: z.ZodObject<
+                  {
+                    id: z.ZodNumber;
+                  },
+                  'strip',
+                  z.ZodTypeAny,
+                  {
+                    id: number;
+                  },
+                  {
+                    id: number;
+                  }
+                >;
+                404: z.ZodObject<
+                  {
+                    message: z.ZodString;
+                  },
+                  'strip',
+                  z.ZodTypeAny,
+                  {
+                    message: string;
+                  },
+                  {
+                    message: string;
+                  }
+                >;
+              };
+            };
+          };
+        }
+      >
+    >;
+  });
+
+  it('should be typed correctly with merged common responses and overriding common response', () => {
+    const contract = c.router(
+      {
+        posts: {
+          getPost: {
+            method: 'GET',
+            path: '/posts/:id',
+            responses: {
+              200: z.object({
+                id: z.number(),
+              }),
+              400: z.object({
+                overrideReason: z.string(),
+              }),
+            },
+          },
+        },
+      },
+      {
+        commonResponses: {
+          400: z.object({
+            reason: z.string(),
+          }),
+          404: z.object({
+            message: z.string(),
+          }),
+        },
+      },
+    );
+
+    type ContractShape = Expect<
+      Equal<
+        typeof contract,
+        {
+          posts: {
+            getPost: {
+              method: 'GET';
+              path: '/posts/:id';
+              responses: {
+                200: z.ZodObject<
+                  {
+                    id: z.ZodNumber;
+                  },
+                  'strip',
+                  z.ZodTypeAny,
+                  {
+                    id: number;
+                  },
+                  {
+                    id: number;
+                  }
+                >;
+                400: z.ZodObject<
+                  {
+                    overrideReason: z.ZodString;
+                  },
+                  'strip',
+                  z.ZodTypeAny,
+                  {
+                    overrideReason: string;
+                  },
+                  {
+                    overrideReason: string;
+                  }
+                >;
+                404: z.ZodObject<
+                  {
+                    message: z.ZodString;
+                  },
+                  'strip',
+                  z.ZodTypeAny,
+                  {
+                    message: string;
+                  },
+                  {
+                    message: string;
+                  }
+                >;
+              };
+            };
+          };
+        }
+      >
+    >;
+  });
 });

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

@@ -26,6 +26,11 @@ export type ContractOtherResponse<T extends ContractAnyType> = Opaque<
   'ContractOtherResponse'
 >;
 
+export type AppRouteResponse =
+  | ContractAnyType
+  | ContractNoBodyType
+  | ContractOtherResponse<ContractAnyType>;
+
 type AppRouteCommon = {
   path: Path;
   pathParams?: ContractAnyType;
@@ -34,12 +39,7 @@ type AppRouteCommon = {
   summary?: string;
   description?: string;
   deprecated?: boolean;
-  responses: Record<
-    number,
-    | ContractAnyType
-    | ContractNoBodyType
-    | ContractOtherResponse<ContractAnyType>
-  >;
+  responses: Record<number, AppRouteResponse>;
   strictStatusCodes?: boolean;
   metadata?: unknown;
 
@@ -131,7 +131,7 @@ type UniversalMerge<A, B> = A extends z.AnyZodObject
 type ApplyOptions<
   TRoute extends AppRoute,
   TOptions extends RouterOptions,
-> = Omit<TRoute, 'headers' | 'path'> &
+> = Omit<TRoute, 'headers' | 'path' | 'responses'> &
   WithoutUnknown<{
     path: TOptions['pathPrefix'] extends string
       ? `${TOptions['pathPrefix']}${TRoute['path']}`
@@ -142,6 +142,9 @@ type ApplyOptions<
       : TOptions['strictStatusCodes'] extends boolean
       ? TOptions['strictStatusCodes']
       : unknown;
+    responses: 'commonResponses' extends keyof TOptions
+      ? Prettify<Merge<TOptions['commonResponses'], TRoute['responses']>>
+      : TRoute['responses'];
   }>;
 
 /**
@@ -164,6 +167,7 @@ export type RouterOptions<TPrefix extends string = string> = {
   baseHeaders?: unknown;
   strictStatusCodes?: boolean;
   pathPrefix?: TPrefix;
+  commonResponses?: Record<number, AppRouteResponse>;
 
   /**
    * @deprecated Use `validateResponse` on the client options
@@ -210,12 +214,7 @@ type ContractInstance = {
    * a {@link AppRouter}
    */
   mutation: <T extends AppRouteMutation>(mutation: NarrowObject<T>) => T;
-  responses: <
-    TResponses extends Record<
-      number,
-      ContractAnyType | ContractOtherResponse<ContractAnyType>
-    >,
-  >(
+  responses: <TResponses extends Record<number, AppRouteResponse>>(
     responses: TResponses,
   ) => TResponses;
   /**
@@ -270,6 +269,10 @@ const recursivelyApplyOptions = <T extends AppRouter>(
             validateResponseOnClient:
               value.validateResponseOnClient ??
               options?.validateResponseOnClient,
+            responses: {
+              ...options?.commonResponses,
+              ...value.responses,
+            },
           },
         ];
       } else {