feat: TsRestResponseError can be thrown from any server package (#578)

Author: Gabrola

.changeset/smooth-ants-admire.md

@@ -0,0 +1,10 @@
+---
+'@ts-rest/serverless': minor
+'@ts-rest/express': minor
+'@ts-rest/fastify': minor
+'@ts-rest/core': minor
+'@ts-rest/nest': minor
+'@ts-rest/next': minor
+---
+
+`TsRestResponseError` can be thrown from any server package

apps/docs/docs/core/server-errors.md

@@ -0,0 +1,21 @@
+# Server Errors
+
+To return errors that are defined in your contract from your server, you can throw a `TsRestResponseError` from anywhere within your code,
+and it will be caught by ts-rest and served as a response. It will still go through any response validations that are enabled.
+
+```typescript
+import { TsRestResponseError } from '@ts-rest/core';
+import { contract } from './contract';
+
+// anywhere in your code
+throw new TsRestResponseError(contract.getPost, {
+  status: 404,
+  body: { message: 'Not Found' },
+});
+```
+
+:::caution
+
+Any thrown `TsRestResponseError` will NOT be caught by any error handlers, and will be served as a response straight away.
+
+:::

apps/docs/docs/serverless/options.md

@@ -20,33 +20,6 @@ For example, for a Vercel Function that lives inside `api/posts.ts`, you would s
 The `cors` option allows you to configure CORS for your handler. The `cors` option can be a boolean (setting it to `false` disables CORS) or an options object.
 We use `itty-router` under the hood for routing and CORS handling, so the options are the same as the `itty-router` CORS options. You can find the full list of options [here](https://itty.dev/itty-router/cors#corsoptions).
 
-## Error Handling
-
-To throw HTTP errors from anywhere within your code. You can use the `TsRestHttpError` class. This class takes a status code, a body and optionally a content-type header.
-
-```typescript
-import { TsRestHttpError } from '@ts-rest/serverless';
-
-// anywhere in your code
-throw new TsRestHttpError(404, { message: 'Not Found' });
-
-// or with a content-type header
-throw new TsRestHttpError(404, 'Not Found', 'text/plain');
-```
-
-You can also use the `TsRestRouteError` to return a response that is defined in your contract.
-
-```typescript
-import { TsRestRouteError } from '@ts-rest/serverless';
-import { contract } from './contract';
-
-// anywhere in your code
-throw new TsRestRouteError(contract.getPost, {
-  status: 404,
-  body: { message: 'Not Found' },
-});
-```
-
 ### Custom Error Handler
 
 The `errorHandler` option allows you to define a custom error handler to handle any uncaught exceptions. The error handler is a function that takes an error and request and optionally returns a response object.

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

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

libs/ts-rest/core/src/lib/response-error.ts

@@ -0,0 +1,29 @@
+import { AppRoute } from './dsl';
+import { ServerInferResponses } from './infer-types';
+import { HTTPStatusCode } from './status-codes';
+
+export class TsRestResponseError<T extends AppRoute> extends Error {
+  public statusCode: HTTPStatusCode;
+  public body: any;
+
+  constructor(route: T, response: ServerInferResponses<T>) {
+    super();
+
+    this.statusCode = response.status;
+    this.body = response.body;
+    this.name = this.constructor.name;
+
+    if (typeof response.body === 'string') {
+      this.message = response.body;
+    } else if (
+      typeof response.body === 'object' &&
+      response.body !== null &&
+      'message' in response.body &&
+      typeof response.body.message === 'string'
+    ) {
+      this.message = response.body['message'];
+    } else {
+      this.message = 'Error';
+    }
+  }
+}

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

@@ -1,6 +1,10 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { initContract, ResponseValidationError } from '@ts-rest/core';
+import {
+  initContract,
+  ResponseValidationError,
+  TsRestResponseError,
+} from '@ts-rest/core';
 import * as supertest from 'supertest';
 import * as express from 'express';
 import { z } from 'zod';
@@ -10,6 +14,8 @@ import * as multer from 'multer';
 const upload = multer();
 
 const c = initContract();
+const s = initServer();
+
 const postsRouter = c.router({
   getPost: {
     method: 'GET',
@@ -23,7 +29,6 @@ const postsRouter = c.router({
 describe('strict mode', () => {
   it('allows unknown responses when not in strict mode', () => {
     const cLoose = c.router({ posts: postsRouter });
-    const s = initServer();
 
     s.router(cLoose, {
       posts: {
@@ -42,7 +47,6 @@ describe('strict mode', () => {
       { posts: postsRouter },
       { strictStatusCodes: true },
     );
-    const s = initServer();
 
     s.router(cStrict, {
       posts: {
@@ -60,8 +64,6 @@ describe('strict mode', () => {
 
 describe('ts-rest-express', () => {
   it('should handle non-json response types from contract', async () => {
-    const c = initContract();
-
     const contract = c.router({
       postIndex: {
         method: 'POST',
@@ -98,9 +100,7 @@ describe('ts-rest-express', () => {
       },
     });
 
-    const server = initServer();
-
-    const postIndex = server.route(
+    const postIndex = s.route(
       contract.postIndex,
       async ({ body: { echoHtml } }) => {
         return {
@@ -110,7 +110,7 @@ describe('ts-rest-express', () => {
       },
     );
 
-    const router = server.router(contract, {
+    const router = s.router(contract, {
       postIndex,
       getRobots: async () => {
         return {
@@ -185,8 +185,6 @@ describe('ts-rest-express', () => {
   });
 
   it('should handle no content body', async () => {
-    const c = initContract();
-
     const contract = c.router({
       noContent: {
         method: 'POST',
@@ -204,8 +202,7 @@ describe('ts-rest-express', () => {
       },
     });
 
-    const server = initServer();
-    const router = server.router(contract, {
+    const router = s.router(contract, {
       noContent: async ({ params }) => {
         return {
           status: params.status,
@@ -239,8 +236,6 @@ describe('ts-rest-express', () => {
   });
 
   it('should handle optional url params', async () => {
-    const c = initContract();
-
     const contract = c.router({
       getPosts: {
         method: 'GET',
@@ -256,8 +251,7 @@ describe('ts-rest-express', () => {
       },
     });
 
-    const server = initServer();
-    const router = server.router(contract, {
+    const router = s.router(contract, {
       getPosts: async ({ params }) => {
         return {
           status: 200,
@@ -289,8 +283,6 @@ describe('ts-rest-express', () => {
   });
 
   it('should handle multipart/form-data', async () => {
-    const c = initContract();
-
     const contract = c.router({
       uploadFiles: {
         method: 'POST',
@@ -312,8 +304,7 @@ describe('ts-rest-express', () => {
       },
     });
 
-    const server = initServer();
-    const router = server.router(contract, {
+    const router = s.router(contract, {
       uploadFiles: {
         middleware: [upload.any()],
         handler: async ({ files, body }) => {
@@ -362,8 +353,6 @@ describe('ts-rest-express', () => {
   });
 
   it('allows download image', async () => {
-    const c = initContract();
-
     const contract = c.router({
       getFile: {
         method: 'GET',
@@ -379,7 +368,6 @@ describe('ts-rest-express', () => {
       },
     });
 
-    const s = initServer();
     const originalFilePath = path.join(__dirname, 'assets/logo.png');
 
     const router = s.router(contract, {
@@ -425,4 +413,59 @@ describe('ts-rest-express', () => {
     );
     expect(responseImage.headers['content-type']).toEqual('image/png');
   });
+
+  it('should handle thrown TsRestResponseError', async () => {
+    const contract = c.router({
+      getPost: {
+        method: 'GET',
+        path: '/posts/:id',
+        responses: {
+          200: z.object({
+            id: z.string(),
+          }),
+          404: z.object({
+            message: z.literal('Not found'),
+          }),
+          500: c.noBody(),
+        },
+      },
+    });
+
+    const router = s.router(contract, {
+      getPost: async ({ params: { id } }) => {
+        if (id === '500') {
+          throw new TsRestResponseError(contract.getPost, {
+            status: 500,
+            body: undefined,
+          });
+        }
+
+        throw new TsRestResponseError(contract.getPost, {
+          status: 404,
+          body: {
+            message: 'Not found',
+          },
+        });
+      },
+    });
+
+    const app = express();
+    app.use(express.json());
+    app.use(express.urlencoded({ extended: true }));
+    createExpressEndpoints(contract, router, app);
+
+    await supertest(app)
+      .get('/posts/500')
+      .expect((res) => {
+        expect(res.status).toEqual(500);
+        expect(res.text).toEqual('');
+      });
+
+    await supertest(app)
+      .get('/posts/10')
+      .expect((res) => {
+        expect(res.status).toEqual(404);
+        expect(res.body).toEqual({ message: 'Not found' });
+      });
+  });
 });

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

@@ -4,10 +4,12 @@ import {
   AppRouteQuery,
   AppRouter,
   checkZodSchema,
+  HTTPStatusCode,
   isAppRoute,
   isAppRouteNoBody,
   isAppRouteOtherResponse,
   parseJsonQueryObject,
+  TsRestResponseError,
   validateResponse,
 } from '@ts-rest/core';
 import type {
@@ -144,20 +146,32 @@ const initializeExpressRoute = ({
     try {
       const validationResults = validateRequest(req, res, schema, options);
 
-      const result = await handler({
-        params: validationResults.paramsResult.data as any,
-        body: validationResults.bodyResult.data as any,
-        query: validationResults.queryResult.data,
-        headers: validationResults.headersResult.data as any,
-        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-        // @ts-ignore
-        files: req.files,
-        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-        // @ts-ignore
-        file: req.file,
-        req: req as any,
-        res: res,
-      });
+      let result: { status: HTTPStatusCode; body: any };
+      try {
+        result = await handler({
+          params: validationResults.paramsResult.data as any,
+          body: validationResults.bodyResult.data as any,
+          query: validationResults.queryResult.data,
+          headers: validationResults.headersResult.data as any,
+          // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+          // @ts-ignore
+          files: req.files,
+          // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+          // @ts-ignore
+          file: req.file,
+          req: req as any,
+          res: res,
+        });
+      } catch (e) {
+        if (e instanceof TsRestResponseError) {
+          result = {
+            status: e.statusCode,
+            body: e.body,
+          };
+        } else {
+          throw e;
+        }
+      }
 
       const statusCode = Number(result.status);