feat: add type-safe header definitions to contracts (#182)

Author: Gabrola

.changeset/twenty-tips-confess.md

@@ -0,0 +1,10 @@
+---
+'@ts-rest/core': minor
+'@ts-rest/express': minor
+'@ts-rest/nest': minor
+'@ts-rest/next': minor
+'@ts-rest/react-query': minor
+'@ts-rest/solid-query': minor
+---
+
+Add type-safe header definitions to contracts

apps/docs/docs/core/core.md

@@ -29,6 +29,9 @@ export const contract = c.router({
     responses: {
       200: c.response<{ posts: Post[]; total: number }>(),
     },
+    headers: z.object({
+      pagination: z.string().optional(),
+    }),
     query: z.object({
       take: z.string().transform(Number).optional(),
       skip: z.string().transform(Number).optional(),
@@ -62,7 +65,7 @@ Check the relevant sections to see how to enable JSON query encoding/decoding on
 
 ## Combining Contracts
 
-You can combine contracts to create a single contract, helpful if you want many sub contracts, especially if they are huge.
+You can combine contracts to create a single contract, helpful if you want many sub-contracts, especially if they are huge.
 
 ```typescript
 const c = initContract();
@@ -88,6 +91,38 @@ export const contract = c.router({
 });
 ```
 
+## Headers
+
+You can define headers in your contract, however, they must have an input type of `string`, as they cannot be typed otherwise.
+You can use Zod transforms or coercion to transform any string values to different types if needed.
+
+```typescript
+const c = initContract();
+export const contract = c.router({
+  getPosts: {
+    ...,
+    headers: z.object({
+      authorization: z.string(),
+      pagination: z.coerce.number().optional(),
+    }),
+  }
+});
+```
+
+You can also define base headers for all routes in a contract and its sub-contracts, this is useful for things like authorization headers.
+This will force the client to always pass 
+
+```typescript
+const c = initContract();
+export const contract = c.router({
+  // ...endpoints
+}, {
+  baseHeaders: z.object({
+    authorization: z.string(),
+  }),
+});
+```
+
 ## Intellisense
 
 For intellisense on your contract types, you can use [JSDoc Reference](https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html#type).

apps/docs/docs/core/fetch.md

@@ -32,7 +32,8 @@ Breaking down the arguments:
 
 - `body` - The body of the request, only used for `POST`, `PUT`, `PATCH` requests.
 - `query` - The query parameters of the request.
-- `headers` - The headers of the request (merged and overridden with `baseHeaders` in the client)
+- `headers` - Request headers defined in the contract (merged and overridden with `baseHeaders` in the client)
+- `extraHeaders` - If you want to pass headers not defined in the contract
 - `params` - The path parameters of the request.
 
 :::tip Customise the API 🎨

apps/example-express/src/tests/posts-response-validation.spec.ts

@@ -5,7 +5,9 @@ const superTestApp = supertest(app);
 
 describe('Posts Endpoints w/ Response Validation', () => {
   it('should include default value and removes extra field', async () => {
-    const res = await superTestApp.get('/validate-response/123/name?field=foo');
+    const res = await superTestApp
+      .get('/validate-response/123/name?field=foo')
+      .set('x-api-key', 'foo');
 
     expect(res.status).toStrictEqual(200);
     expect(res.body).toStrictEqual({
@@ -16,7 +18,9 @@ describe('Posts Endpoints w/ Response Validation', () => {
   });
 
   it('fails with invalid field', async () => {
-    const res = await superTestApp.get('/validate-response/2000/name');
+    const res = await superTestApp
+      .get('/validate-response/2000/name')
+      .set('x-api-key', 'foo');
 
     expect(res.status).toStrictEqual(500);
     expect(res.body).toStrictEqual({});

apps/example-express/src/tests/posts.spec.ts

@@ -5,21 +5,47 @@ const superTestApp = supertest(app);
 
 describe('Posts Endpoints', () => {
   it('GET /posts should return an array of posts', async () => {
-    const res = await superTestApp.get('/posts?skip=0&take=10');
+    const res = await superTestApp
+      .get('/posts?skip=0&take=10')
+      .set('x-api-key', 'foo')
+      .set('x-pagination', '5');
 
     expect(res.status).toStrictEqual(200);
   });
 
   it('should transform skip and take into numbers', async () => {
-    const res = await superTestApp.get('/posts?skip=0&take=10');
+    const res = await superTestApp
+      .get('/posts?skip=0&take=10')
+      .set('x-api-key', 'foo');
 
     expect(res.status).toStrictEqual(200);
     expect(res.body.skip).toStrictEqual(0);
     expect(res.body.take).toStrictEqual(10);
   });
 
+  it('should error on invalid pagination header', async () => {
+    const res = await superTestApp
+      .get('/posts?skip=0&take=10')
+      .set('x-api-key', 'foo')
+      .set('x-pagination', 'not a number');
+
+    expect(res.status).toStrictEqual(400);
+    expect(res.body).toStrictEqual({
+      issues: [
+        {
+          code: 'invalid_type',
+          expected: 'number',
+          message: 'Expected number, received nan',
+          path: ['x-pagination'],
+          received: 'nan',
+        },
+      ],
+      name: 'ZodError',
+    });
+  });
+
   it('should error if a required query param is missing', async () => {
-    const res = await superTestApp.get('/posts?skip=0');
+    const res = await superTestApp.get('/posts?skip=0').set('x-api-key', 'foo');
 
     expect(res.status).toStrictEqual(400);
     expect(res.body).toStrictEqual({
@@ -37,7 +63,7 @@ describe('Posts Endpoints', () => {
   });
 
   it('should error if body is incorrect', async () => {
-    const res = await superTestApp.post('/posts').send({
+    const res = await superTestApp.post('/posts').set('x-api-key', 'foo').send({
       title: 'Good title',
       content: 123,
     });
@@ -57,8 +83,26 @@ describe('Posts Endpoints', () => {
     });
   });
 
+  it('should error if api key header is missing', async () => {
+    const res = await superTestApp.get('/posts');
+
+    expect(res.status).toStrictEqual(400);
+    expect(res.body).toStrictEqual({
+      issues: [
+        {
+          code: 'invalid_type',
+          expected: 'string',
+          message: 'Required',
+          path: ['x-api-key'],
+          received: 'undefined',
+        },
+      ],
+      name: 'ZodError',
+    });
+  });
+
   it('should transform body correctly', async () => {
-    const res = await superTestApp.post('/posts').send({
+    const res = await superTestApp.post('/posts').set('x-api-key', 'foo').send({
       title: 'Title with extra spaces     ',
       content: 'content',
     });
@@ -68,7 +112,9 @@ describe('Posts Endpoints', () => {
   });
 
   it('should format params using pathParams correctly', async () => {
-    const res = await superTestApp.get('/test/123/name');
+    const res = await superTestApp
+      .get('/test/123/name')
+      .set('x-api-key', 'foo');
 
     expect(res.status).toStrictEqual(200);
     expect(res.body).toStrictEqual({

apps/example-nest/src/app/post-json-query.spec.ts

@@ -40,6 +40,7 @@ describe('PostJsonQueryController', () => {
 
       return request(app.getHttpServer())
         .get('/posts-json-query')
+        .set('x-api-key', 'foo')
         .query('skip=0&take=10&search="foo"')
         .expect(200)
         .expect({

apps/example-nest/src/app/post-validate-responses.spec.ts

@@ -50,6 +50,7 @@ describe('PostValidateResponsesController', () => {
 
       return request(app.getHttpServer())
         .get('/posts')
+        .set('x-api-key', 'foo')
         .expect(200)
         .expect({
           posts: [
@@ -77,6 +78,7 @@ describe('PostValidateResponsesController', () => {
 
       return request(app.getHttpServer())
         .get('/posts')
+        .set('x-api-key', 'foo')
         .expect(500)
         .expect({ statusCode: 500, message: 'Internal server error' });
     });

apps/example-nest/src/app/post.controller.spec.ts

@@ -37,6 +37,7 @@ describe('PostController', () => {
 
       return request(app.getHttpServer())
         .get('/posts')
+        .set('x-api-key', 'foo')
         .query('skip=0&take=10')
         .expect(200)
         .expect({
@@ -47,9 +48,31 @@ describe('PostController', () => {
         });
     });
 
+    it('should fetch pagination header', async () => {
+      jest.spyOn(postService, 'getPosts').mockResolvedValue({
+        posts: [],
+        totalPosts: 0,
+      });
+
+      return request(app.getHttpServer())
+        .get('/posts')
+        .set('x-api-key', 'foo')
+        .set('x-pagination', '123')
+        .query('skip=0&take=10')
+        .expect(200)
+        .expect({
+          posts: [],
+          count: 0,
+          skip: 0,
+          take: 10,
+          pagination: 123,
+        });
+    });
+
     it('should error if a required query param is missing', async () => {
       return request(app.getHttpServer())
         .get('/posts')
+        .set('x-api-key', 'foo')
         .query('skip=0')
         .expect(400)
         .expect({
@@ -71,6 +94,7 @@ describe('PostController', () => {
     it('should error if body is incorrect', async () => {
       return request(app.getHttpServer())
         .post('/posts')
+        .set('x-api-key', 'foo')
         .send({
           title: 'Good title',
           content: 123,
@@ -97,6 +121,7 @@ describe('PostController', () => {
 
       return request(app.getHttpServer())
         .post('/posts')
+        .set('x-api-key', 'foo')
         .send({
           title: 'Title with extra spaces     ',
           content: 'content',
@@ -112,6 +137,7 @@ describe('PostController', () => {
   it('should format params using pathParams correctly', async () => {
     return request(app.getHttpServer())
       .get('/test/123/name')
+      .set('x-api-key', 'foo')
       .expect(200)
       .expect({
         id: 123,

apps/example-nest/src/app/post.controller.ts

@@ -25,7 +25,10 @@ export class PostController implements NestControllerInterface<typeof c> {
   @TsRest(c.getPosts)
   async getPosts(
     @TsRestRequest()
-    { query: { take, skip, search } }: RequestShapes['getPosts']
+    {
+      query: { take, skip, search },
+      headers: { 'x-pagination': pagination },
+    }: RequestShapes['getPosts']
   ) {
     const { posts, totalPosts } = await this.postService.getPosts({
       take,
@@ -35,7 +38,7 @@ export class PostController implements NestControllerInterface<typeof c> {
 
     return {
       status: 200 as const,
-      body: { posts, count: totalPosts, skip, take },
+      body: { posts, count: totalPosts, skip, take, pagination },
     };
   }