feat: allow server to send no response body (#547)

Author: Gabrola

.changeset/cuddly-experts-press.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
+---
+
+Add contract definition for an absent body and handle accordingly on the server

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

@@ -121,10 +121,10 @@ const postsRouter = c.router({
   deletePost: {
     method: 'DELETE',
     path: `/posts/:id`,
+    body: c.noBody(),
     responses: {
-      200: c.type<boolean>(),
+      204: c.noBody(),
     },
-    body: null,
   },
 });
 
@@ -552,23 +552,22 @@ describe('client', () => {
   });
 
   describe('delete', () => {
-    it('w/ body', async () => {
-      const value = { key: 'value' };
+    it('w/ no body', async () => {
       fetchMock.deleteOnce(
         {
           url: 'https://api.com/posts/1',
         },
-        { body: value, status: 200 },
+        { status: 204 },
       );
 
       const result = await client.posts.deletePost({
         params: { id: '1' },
       });
 
-      expect(result.body).toStrictEqual(value);
-      expect(result.status).toBe(200);
-      expect(result.headers.get('Content-Length')).toBe('15');
-      expect(result.headers.get('Content-Type')).toBe('application/json');
+      expect((result.body as Blob).size).toStrictEqual(0);
+      expect(result.status).toBe(204);
+      expect(result.headers.has('Content-Length')).toBe(false);
+      expect(result.headers.has('Content-Type')).toBe(false);
     });
   });
 

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

@@ -5,6 +5,7 @@ import {
   ContractOtherResponse,
   ContractPlainType,
   ContractPlainTypeRuntimeSymbol,
+  ContractNoBodyType,
 } from './dsl';
 import type { Equal, Expect } from './test-helpers';
 
@@ -739,4 +740,20 @@ describe('contract', () => {
       >
     >;
   });
+
+  it('should set type correctly for no body', () => {
+    const contract = c.router({
+      get: {
+        method: 'GET',
+        path: '/',
+        responses: {
+          204: c.noBody(),
+        },
+      },
+    });
+
+    type ResponseType = Expect<
+      Equal<(typeof contract.get.responses)['204'], ContractNoBodyType>
+    >;
+  });
 });

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

@@ -11,9 +11,11 @@ type MixedZodError<A, B> = Opaque<{ a: A; b: B }, 'MixedZodError'>;
 type Path = string;
 
 declare const NullSymbol: unique symbol;
+export const ContractNoBody = Symbol('ContractNoBody');
 
 export type ContractPlainType<T> = Opaque<T, 'ContractPlainType'>;
 export type ContractNullType = Opaque<typeof NullSymbol, 'ContractNullType'>;
+export type ContractNoBodyType = typeof ContractNoBody;
 export type ContractAnyType =
   | z.ZodSchema
   | ContractPlainType<unknown>
@@ -34,7 +36,9 @@ type AppRouteCommon = {
   deprecated?: boolean;
   responses: Record<
     number,
-    ContractAnyType | ContractOtherResponse<ContractAnyType>
+    | ContractAnyType
+    | ContractNoBodyType
+    | ContractOtherResponse<ContractAnyType>
   >;
   strictStatusCodes?: boolean;
   metadata?: unknown;
@@ -62,7 +66,7 @@ export type AppRouteMutation = AppRouteCommon & {
     | 'application/json'
     | 'multipart/form-data'
     | 'application/x-www-form-urlencoded';
-  body: ContractAnyType;
+  body: ContractAnyType | ContractNoBodyType;
 };
 
 type ValidatedHeaders<
@@ -236,6 +240,8 @@ type ContractInstance = {
     contentType: string;
     body: T;
   }) => ContractOtherResponse<T>;
+  /** Use to indicate that a route takes no body or responds with no body */
+  noBody: () => ContractNoBodyType;
 };
 
 /**
@@ -303,5 +309,6 @@ export const initContract = (): ContractInstance => {
         contentType,
         body,
       }) as ContractOtherResponse<T>,
+    noBody: () => ContractNoBody,
   };
 };

libs/ts-rest/core/src/lib/infer-types.ts

@@ -4,6 +4,7 @@ import {
   AppRouter,
   AppRouteStrictStatusCodes,
   ContractAnyType,
+  ContractNoBodyType,
   ContractOtherResponse,
 } from './dsl';
 import { HTTPStatusCode } from './status-codes';
@@ -60,7 +61,10 @@ type PathParamsWithCustomValidators<
     >;
 
 export type ResolveResponseType<
-  T extends ContractAnyType | ContractOtherResponse<ContractAnyType>,
+  T extends
+    | ContractAnyType
+    | ContractNoBodyType
+    | ContractOtherResponse<ContractAnyType>,
 > = T extends ContractOtherResponse<infer U> ? U : T;
 
 type AppRouteResponses<

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

@@ -1,7 +1,13 @@
 import { HTTPStatusCode } from './status-codes';
 import { checkZodSchema } from './zod-utils';
 import { ResponseValidationError } from './response-validation-error';
-import { AppRoute, ContractAnyType, ContractOtherResponse } from './dsl';
+import {
+  AppRoute,
+  ContractAnyType,
+  ContractNoBody,
+  ContractNoBodyType,
+  ContractOtherResponse,
+} from './dsl';
 
 export const isAppRouteResponse = (
   value: unknown,
@@ -15,7 +21,10 @@ export const isAppRouteResponse = (
 };
 
 export const isAppRouteOtherResponse = (
-  response: ContractAnyType | ContractOtherResponse<ContractAnyType>,
+  response:
+    | ContractAnyType
+    | ContractNoBodyType
+    | ContractOtherResponse<ContractAnyType>,
 ): response is ContractOtherResponse<ContractAnyType> => {
   return (
     response != null &&
@@ -24,6 +33,15 @@ export const isAppRouteOtherResponse = (
   );
 };
 
+export const isAppRouteNoBody = (
+  response:
+    | ContractAnyType
+    | ContractNoBodyType
+    | ContractOtherResponse<ContractAnyType>,
+): response is ContractNoBodyType => {
+  return response === ContractNoBody;
+};
+
 export const validateResponse = ({
   appRoute,
   response,

libs/ts-rest/core/src/lib/type-utils.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { ContractNullType, ContractPlainType } from './dsl';
+import { ContractNoBodyType, ContractNullType, ContractPlainType } from './dsl';
 
 type GetIndexedField<T, K> = K extends keyof T
   ? T[K]
@@ -53,6 +53,8 @@ export type With<T, V> = Pick<T, ExcludeKeysWithoutTypeOf<T, V>>;
 
 export type ZodInferOrType<T> = T extends ContractNullType
   ? null
+  : T extends ContractNoBodyType
+  ? undefined
   : T extends ContractPlainType<infer U>
   ? U
   : T extends z.ZodTypeAny
@@ -61,6 +63,8 @@ export type ZodInferOrType<T> = T extends ContractNullType
 
 export type ZodInputOrType<T> = T extends ContractNullType
   ? null
+  : T extends ContractNoBodyType
+  ? undefined
   : T extends ContractPlainType<infer U>
   ? U
   : T extends z.ZodTypeAny

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

@@ -180,6 +180,60 @@ describe('ts-rest-express', () => {
       'text/css; charset=utf-8',
     );
   });
+
+  it('should handle no content body', async () => {
+    const c = initContract();
+
+    const contract = c.router({
+      noContent: {
+        method: 'POST',
+        path: '/:status',
+        pathParams: z.object({
+          status: z.coerce
+            .number()
+            .pipe(z.union([z.literal(200), z.literal(204)])),
+        }),
+        body: c.noBody(),
+        responses: {
+          200: c.noBody(),
+          204: c.noBody(),
+        },
+      },
+    });
+
+    const server = initServer();
+    const router = server.router(contract, {
+      noContent: async ({ params }) => {
+        return {
+          status: params.status,
+          body: undefined,
+        };
+      },
+    });
+
+    const app = express();
+    app.use(express.json());
+    app.use(express.urlencoded({ extended: true }));
+    createExpressEndpoints(contract, router, app);
+
+    await supertest(app)
+      .post('/200')
+      .expect((res) => {
+        expect(res.status).toEqual(200);
+        expect(res.text).toEqual('');
+        expect(res.header['content-type']).toBeUndefined();
+        expect(res.header['content-length']).toStrictEqual('0');
+      });
+
+    await supertest(app)
+      .post('/204')
+      .expect((res) => {
+        expect(res.status).toEqual(204);
+        expect(res.text).toEqual('');
+        expect(res.header['content-type']).toBeUndefined();
+        expect(res.header['content-length']).toBeUndefined();
+      });
+  });
 });
 
 describe('download', () => {

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

@@ -5,6 +5,7 @@ import {
   AppRouter,
   checkZodSchema,
   isAppRoute,
+  isAppRouteNoBody,
   isAppRouteOtherResponse,
   parseJsonQueryObject,
   validateResponse,
@@ -179,6 +180,11 @@ const initializeExpressRoute = ({
       }
 
       const responseType = schema.responses[statusCode];
+
+      if (isAppRouteNoBody(responseType)) {
+        return res.status(statusCode).end();
+      }
+
       if (isAppRouteOtherResponse(responseType)) {
         res.setHeader('content-type', responseType.contentType);
         return res.status(statusCode).send(validatedResponseBody);

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

@@ -28,6 +28,14 @@ const contract = c.router({
       }),
     },
   },
+  noContent: {
+    method: 'POST',
+    path: '/no-content',
+    body: c.noBody(),
+    responses: {
+      204: c.noBody(),
+    },
+  },
   testPathParams: {
     method: 'GET',
     path: '/test/:id',
@@ -73,6 +81,12 @@ describe('ts-rest-fastify', () => {
         },
       };
     }),
+    noContent: async () => {
+      return {
+        status: 204,
+        body: undefined,
+      };
+    },
     testPathParams: async ({ params }) => {
       return {
         status: 200,
@@ -183,6 +197,23 @@ describe('ts-rest-fastify', () => {
     });
   });
 
+  it('should handle no content response', async () => {
+    const app = fastify({ logger: false });
+
+    s.registerRouter(contract, router, app, {
+      logInitialization: false,
+    });
+
+    await app.ready();
+
+    const response = await supertest(app.server).post('/no-content');
+
+    expect(response.statusCode).toEqual(204);
+    expect(response.text).toEqual('');
+    expect(response.header['content-type']).toBeUndefined();
+    expect(response.header['content-length']).toBeUndefined();
+  });
+
   it("should allow for custom error handler if body doesn't match", async () => {
     const app = fastify({ logger: false });
 
@@ -433,6 +464,9 @@ describe('ts-rest-fastify', () => {
       ping: async () => {
         throw new Error('not implemented');
       },
+      noContent: async () => {
+        throw new Error('not implemented');
+      },
       testPathParams: async () => {
         throw new Error('not implemented');
       },