feat(express): add middleware composition helpers (#232)

Author: Gabrola

.changeset/serious-hotels-burn.md

@@ -0,0 +1,5 @@
+---
+'@ts-rest/express': minor
+---
+
+Add middleware directly through ts-rest with type-safe injected route object

.changeset/tricky-dingos-reflect.md

@@ -0,0 +1,5 @@
+---
+'@ts-rest/core': minor
+---
+
+Add 'metadata' property to routes

.github/workflows/prerelease.yml

@@ -1,4 +1,4 @@
-name: Release
+name: Pre-Release
 on:
   push:
     branches:

README.md

@@ -53,6 +53,9 @@ const contract = c.contract({
     responses: {
       200: c.response<Post[]>(), // <-- OR normal TS types
     },
+    headers: z.object({
+      'x-pagination-page': z.coerce.number().optional(),
+    }),
   },
 });
 ```
@@ -74,6 +77,7 @@ Consume the api on the client with a RPC-like interface:
 
 ```typescript
 const result = await client.getPosts({
+  headers: { 'x-pagination-page': 1 },
   query: { skip: 0, take: 10 },
   // ^-- Fully typed!
 });
@@ -95,8 +99,8 @@ yarn add @ts-rest/open-api
 
 Create a contract, implement it on your server then consume it in your client. Incrementally adopt, trial it with your team, then get shipping faster.
 
-<div align="center" style={{margin: "50px"}}>
-<h2>👉 Read more on the official <a href="https://ts-rest.com/docs/quickstart?utm_source=github&utm_medium=documentation&utm_campaign=readme">Quickstart Guide</a>👈</h2>
+<div align="center">
+<h3>👉 Read more on the official <a href="https://ts-rest.com/docs/quickstart?utm_source=github&utm_medium=documentation&utm_campaign=readme">Quickstart Guide</a> 👈</h3>
 </div>
 
 ## Star History

apps/docs/docs/core/core.md

@@ -22,6 +22,7 @@ export const contract = c.router({
       description: z.string().optional(),
     }),
     summary: 'Create a post',
+    metadata: { role: 'user' } as const,
   },
   getPosts: {
     method: 'GET',
@@ -38,6 +39,7 @@ export const contract = c.router({
       search: z.string().optional(),
     }),
     summary: 'Get all posts',
+    metadata: { role: 'guest' } as const,
   },
 });
 ```
@@ -123,6 +125,28 @@ export const contract = c.router({
 });
 ```
 
+## Metadata
+
+You can attach metadata with any type to your contract routes that can be accessed anywhere throughout ts-rest where
+you have access to the contract route object.
+
+```typescript
+const c = initContract();
+export const contract = c.router({
+    getPosts: {
+        ...,
+        metadata: { role: 'guest' } as const,
+    }
+});
+```
+
+:::caution
+
+As the contract is not only used on the server, but on the client as well, it will also be part of your client-side bundle.
+You should not put any sensitive information in the metadata.
+
+:::
+
 ## 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/express.mdx

@@ -0,0 +1,92 @@
+import { InstallTabs } from '@site/src/components/InstallTabs';
+
+# Express Server
+
+## Installation
+
+<InstallTabs packageName="@ts-rest/express" />
+
+## Usage
+
+```typescript
+import { initServer } from '@ts-rest/express';
+import { contract } from './contract';
+
+const app = express();
+app.use(bodyParser.urlencoded({ extended: false }));
+app.use(bodyParser.json());
+
+const s = initServer();
+const router = s.router(contract, {
+  getPost: async ({ params: { id } }) => {
+    const post = prisma.post.findUnique({ where: { id } });
+
+    return {
+      status: 200,
+      body: post ?? null,
+    };
+  },
+});
+
+createExpressEndpoints(contract, router, app);
+```
+
+`createExpressEndpoints` is a function that takes a contract, a corresponding router with implementations and middleware for each endpoint, and an express app, and it will
+create the corresponding express routes for each endpoint with the correct method, paths and middleware and attach them to your express app.
+
+## Options
+
+You can pass an optional options object as the last argument for `createExpressEndpoints`.
+
+```typescript
+type Options = {
+  logInitialization?: boolean; // print route initialization logs to console
+  jsonQuery?: boolean;
+  responseValidation?: boolean;
+  globalMiddleware?: ((req, res, next) => void)[];
+  requestValidationErrorHandler?:
+    | 'default'
+    | 'combined'
+    | ((err: RequestValidationError, req, res, next) => void);
+};
+```
+
+### Response Validation
+
+To enable response parsing and validation, you can use the `validateResponses` option.
+If there is a corresponding response Zod schema defined in the contract for the returned status code, the response will be parsed and validated.
+If validation fails a `ResponseValidationError` will be thrown causing a 500 response to be returned.
+
+```typescript
+createExpressEndpoints(contract, router, app, {
+  validateResponses: true,
+});
+```
+
+### Request Validation Error Handling
+
+The default functionality of handling request validation errors is to return a 400 response with the first validation error that the validator comes across.
+
+You can pass `combined` to the `requestValidationErrorHandler` option to return a 400 response with all validation errors in the body in this form.
+
+```typescript
+{
+  pathParameterErrors: z.ZodError | null;
+  headerErrors: z.ZodError | null;
+  queryParameterErrors: z.ZodError | null;
+  bodyErrors: z.ZodError | null;
+}
+```
+
+You can also pass a custom error handler function to the `requestValidationErrorHandler` option.
+
+```typescript
+createExpressEndpoints(contract, router, app, {
+  requestValidationErrorHandler: (err, req, res, next) => {
+    //             err is typed as ^ RequestValidationError
+    return res.status(400).json({
+      message: 'Validation failed'
+    });
+  },
+});
+```

apps/docs/docs/express/express.mdx

@@ -0,0 +1,77 @@
+# Middleware
+
+You can add middleware to your routes through ts-rest directly instead of having to attach them to your app directly.
+They are regular Express.js request handlers, but with the added benefit of having
+a typed contract route attached to the Request object at `req.tsRestRoute`.
+
+This allows you to pass metadata from your contract to your middleware to be used for authorization, logging, etc.
+
+## Route Middleware
+
+In the below example we show how you can add middleware that only runs for a specific route.
+
+```typescript
+import { initServer } from '@ts-rest/express';
+import { contract } from './contract';
+
+const s = initServer();
+
+const router = s.router(contract, {
+  getPost: {
+    middleware: [
+      (req, res, next) => {
+        // req.tsRestRoute is typed as the contract route
+        console.log('Called: ', req.tsRestRoute.method, req.tsRestRoute.path);
+        // prints: Called: GET /posts/:id
+        next();
+      }
+    ],
+    handler: async ({ params: { id } }) => {
+      const post = prisma.post.findUnique({ where: { id } });
+
+      return {
+        status: 200,
+        body: post ?? null,
+      };
+    }
+  },
+});
+
+createExpressEndpoints(contract, router, app);
+```
+
+## Global Middleware
+
+You can also add middleware that runs for all routes in a contract. These run before any route-specific middleware.
+
+```typescript
+import { initServer } from '@ts-rest/express';
+import { contract } from './contract';
+
+const s = initServer();
+
+const router = s.router(contract, {
+  getPost: {
+    middleware: [
+      (req, res, next) => {
+        // req.tsRestRoute is typed as the contract route
+        console.log('Called: ', req.tsRestRoute.method, req.tsRestRoute.path);
+        //                                   'GET' ^        '/posts/:id'  ^ 
+        next();
+      }
+    ],
+    handler: async ({ params: { id } }) => {
+      const post = prisma.post.findUnique({ where: { id } });
+
+      return {
+        status: 200,
+        body: post ?? null,
+      };
+    }
+  },
+});
+
+createExpressEndpoints(contract, router, app, {
+  globalMiddleware: [passport.authenticate('jwt', { session: false })]
+});
+```

apps/docs/docs/express/middleware.md

@@ -28,6 +28,9 @@ const contract = c.contract({
     responses: {
       200: c.response<Post[]>(), // <-- OR normal TS types
     },
+    headers: z.object({
+      'x-pagination-page': z.coerce.number().optional(),
+    }),
   },
 });
 ```
@@ -49,6 +52,7 @@ Consume the api on the client with a RPC-like interface:
 
 ```typescript
 const result = await client.getPosts({
+  headers: { 'x-pagination-page': 1 },
   query: { skip: 0, take: 10 },
   // ^-- Fully typed!
 });

apps/docs/docs/intro.md

@@ -87,9 +87,13 @@ const sidebars = {
       id: 'next',
     },
     {
-      type: 'doc',
+      type: 'category',
       label: '@ts-rest/express',
-      id: 'express',
+      collapsed: false,
+      items: [
+        { type: 'doc', id: 'express/express' },
+        { type: 'doc', id: 'express/middleware' },
+      ],
     },
     {
       type: 'doc',