feat: Add multipart/form-data

Author: oliverbutler

.changeset/shaggy-kings-collect.md

@@ -0,0 +1,8 @@
+---
+'@ts-rest/core': minor
+'@ts-rest/express': minor
+'@ts-rest/nest': minor
+'@ts-rest/react-query': minor
+---
+
+Add support for multipart/form-data

.gitignore

@@ -58,3 +58,6 @@ web-build/
 
 apps/example-expo-e2e/artifacts
 apps/expo-e2e/artifacts
+
+# example apps upload directory
+uploads/ 

apps/docs/docs/core/errors.md

@@ -17,7 +17,7 @@ export const routerBasic = c.router({
 });
 ```
 
-## Client
+## Client Errors
 
 The default fetch client has support for this,
 
@@ -33,6 +33,8 @@ if (status === 200) {
 }
 ```
 
+### Client Error Typing
+
 :::info
 
 The typed response includes the typed status codes along with any other possible statuses

apps/docs/docs/core/fetch.md

@@ -9,12 +9,16 @@ export const client = initClient(router, {
 });
 ```
 
+### Query
+
 **Query** against the contract, a _query_ is a function that does a GET request to the api.
 
 ```typescript
 const { data } = await client.posts.get();
 ```
 
+### Mutate
+
 **Mutate** against the contract, a _mutation_ is a function that does a POST, PUT, PATCH or DELETE request to the api.
 
 ```typescript
@@ -39,7 +43,7 @@ if (status === 200) {
 }
 ```
 
-Return type
+### Return type
 
 ```typescript
 const data: {

apps/docs/docs/core/form-data.mdx

@@ -0,0 +1,130 @@
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# multipart/form-data
+
+ts-rest supports multipart/form-data requests, this is useful for uploading files or working with FormData from a form.
+
+## Contract
+
+The contract implementation is the same as any other mutation, however, `contentType` must be set to `multipart/form-data` and the `body` must be a `FormData-compatible` object (one level deep, no weird nested structures!).
+
+```ts
+const c = initContract();
+
+export const postsApi = c.router({
+  updatePostThumbnail: {
+    method: 'POST',
+    path: '/posts/:id/thumbnail',
+    contentType: 'multipart/form-data', // <- Only difference
+    body: c.body<{ thumbnail: File }>(), // <- Use File type in here
+    responses: {
+      200: z.object({
+        uploadedFile: z.object({
+          name: z.string(),
+          size: z.number(),
+          type: z.string(),
+        }),
+      }),
+      400: z.object({
+        message: z.string(),
+      }),
+    },
+  },
+});
+```
+
+## Client
+
+If your query utilizes multipart/form-data, ts-rest allows you to choose from FormData or a type safe object, the latter is recommended in most cases, just make sure you don't make a nested object.
+
+```ts
+// client.ts
+
+const App = () => {
+  const [thumbnail, setThumbnail] = React.useState<File | null>(null);
+
+  return (
+    <div>
+      <input
+        multiple={false}
+        type="file"
+        onChange={(e) => setThumbnail(e.target.files?.[0] || null)}
+      />
+      <button
+        onClick={() => {
+          if (file) {
+            apiClient.uploadFile({
+              body: {
+                thumbnail: file, // <- typed body with "File" type
+              },
+            });
+          }
+        }}
+      >
+        Upload
+      </button>
+    </div>
+  );
+};
+```
+
+## Server - Express
+
+With Express it is recommend to use the `multer` package to handle the multipart/form-data requests.
+
+ts-rest offers some nice types to help with this, however, we're leaving this up to you to implement with middleware outside of ts-rest.
+
+- `file` is typed as `unknown` <- BYO middleware
+- `files` is typed as `unknown` <- BYO middleware
+- `body` has had any `File` types removed (so other types are still there)
+
+```ts
+const s = initServer();
+
+const postsRouter = s.router(postsApi, {
+  updatePostThumbnail: async ({ file, files, body }) => {
+    const thumbnail = file as Express.Multer.File;
+
+    return {
+      status: 200,
+      body: {
+        message: `File ${thumbnail.originalname} successfully!`,
+      },
+    };
+  },
+});
+
+const app = express();
+
+app.use(cors());
+
+// File upload
+app.post(postsApi.updatePostThumbnail.path, upload.single('thumbnail'));
+```
+
+## Server - Nest
+
+With Nest this is a pretty simple implementation, due to the extensible Decorator driven approach of Nest, you're able to utilize you're favourite multipart/form-data middleware, in this case we're following <a href="https://docs.nestjs.com/techniques/file-upload">https://docs.nestjs.com/techniques/file-upload</a> from Nest.
+
+- `body` has had any `File` types removed (so other types are still there)
+
+```ts
+// nest
+@Controller()
+export class AppController implements ControllerShape {
+  @Api(s.route.updateUserAvatar)
+  @UseInterceptors(FileInterceptor('avatar'))
+  async updateUserAvatar(
+    @ApiDecorator() { params: { id } }: RouteShape['updateUserAvatar'],
+    @UploadedFile() avatar: Express.Multer.File
+  ) {
+    return {
+      status: 200 as const,
+      body: {
+        message: `Updated user ${id}'s avatar with ${avatar.originalname}`,
+      },
+    };
+  }
+}
+```

apps/docs/sidebars.js

@@ -40,6 +40,7 @@ const sidebars = {
         { type: 'doc', id: 'core/core' },
         { type: 'doc', id: 'core/fetch' },
         { type: 'doc', id: 'core/errors' },
+        { type: 'doc', id: 'core/form-data' },
       ],
     },
     {

apps/example-microservice/posts-service/src/main.ts

@@ -5,6 +5,9 @@
 
 import * as express from 'express';
 import * as cors from 'cors';
+import * as multer from 'multer';
+
+const upload = multer({ dest: 'uploads/' });
 
 import { postsApi } from '@ts-rest/example-microservice/util-posts-api';
 import { createExpressEndpoints, initServer } from '@ts-rest/express';
@@ -44,12 +47,25 @@ const postsRouter = s.router(postsApi, {
       ],
     };
   },
+  updatePostThumbnail: async ({ file }) => {
+    const thumbnail = file as Express.Multer.File;
+
+    return {
+      status: 200,
+      body: {
+        message: `File ${thumbnail.originalname} successfully!`,
+      },
+    };
+  },
 });
 
 const app = express();
 
 app.use(cors());
 
+// File upload
+app.post(postsApi.updatePostThumbnail.path, upload.single('thumbnail'));
+
 createExpressEndpoints(postsApi, postsRouter, app);
 
 const port = process.env.port || 5003;

apps/example-microservice/users-service/src/app/app.controller.ts

@@ -1,7 +1,9 @@
-import { Controller, Get } from '@nestjs/common';
+import { Controller, UploadedFile, UseInterceptors } from '@nestjs/common';
 import { usersApi } from '@ts-rest/example-microservice/util-users-api';
 import { Api, ApiDecorator, initNestServer } from '@ts-rest/nest';
 import { AppService } from './app.service';
+import { FileInterceptor } from '@nestjs/platform-express';
+import 'multer';
 
 const s = initNestServer(usersApi);
 type ControllerShape = typeof s.controllerShape;
@@ -22,4 +24,18 @@ export class AppController implements ControllerShape {
       },
     };
   }
+
+  @Api(s.route.updateUserAvatar)
+  @UseInterceptors(FileInterceptor('avatar'))
+  async updateUserAvatar(
+    @ApiDecorator() { params: { id } }: RouteShape['updateUserAvatar'],
+    @UploadedFile() avatar: Express.Multer.File
+  ) {
+    return {
+      status: 200 as const,
+      body: {
+        message: `Updated user ${id}'s avatar with ${avatar.originalname}`,
+      },
+    };
+  }
 }

apps/example-microservice/web-app/src/App.tsx

@@ -8,13 +8,37 @@ export const App = () => {
 
   const posts = data?.body || [];
 
+  const [file, setFile] = React.useState<File | null>(null);
+
   return (
     <div>
       <h1>Posts from posts-service</h1>
       {posts.map((post) => (
         <div key={post.id}>
           <h1>{post.title}</h1>
           <p>{post.content}</p>
+          <input
+            multiple={false}
+            type="file"
+            onChange={(e) => setFile(e.target.files?.[0] || null)}
+          />
+          <button
+            onClick={() => {
+              if (file) {
+                postsClient.updatePostThumbnail.mutation({
+                  body: {
+                    thumbnail: file,
+                    data: 'Hey there!',
+                  },
+                  params: {
+                    id: '1',
+                  },
+                });
+              }
+            }}
+          >
+            Upload
+          </button>
         </div>
       ))}
     </div>

libs/example-microservice/util-posts-api/src/lib/example-microservice-util-posts-api.ts

@@ -33,4 +33,18 @@ export const postsApi = c.router({
       }),
     },
   },
+  updatePostThumbnail: {
+    method: 'POST',
+    path: '/posts/:id/thumbnail',
+    contentType: 'multipart/form-data',
+    body: c.body<{ thumbnail: File; data: string }>(),
+    responses: {
+      200: z.object({
+        message: z.string(),
+      }),
+      400: z.object({
+        message: z.string(),
+      }),
+    },
+  },
 });