Revert "Revert "Add status code based error handling""

Author: oliverbutler

.changeset/bright-feet-behave.md

@@ -0,0 +1,9 @@
+---
+'@ts-rest/core': major
+'@ts-rest/express': major
+'@ts-rest/nest': major
+'@ts-rest/open-api': major
+'@ts-rest/react-query': major
+---
+
+Change contract to support multiple responses, for different statuses

.changeset/bright-tomatoes-juggle.md

@@ -0,0 +1,9 @@
+---
+'@ts-rest/express': major
+'@ts-rest/core': patch
+'@ts-rest/nest': patch
+'@ts-rest/open-api': patch
+'@ts-rest/react-query': patch
+---
+
+Add error handling support to express

.vscode/settings.json

@@ -1,5 +1,5 @@
 {
-  "cSpell.words": ["openapi", "tanstack", "TRPC", "ts-rest"],
+  "cSpell.words": ["openapi", "tanstack", "todos", "TRPC", "ts-rest"],
   "typescript.tsdk": "node_modules/typescript/lib",
   "yaml.schemas": {
     "https://json.schemastore.org/github-workflow.json": "file:///Users/olly/projects/ts-rest/.github/workflows/deploy.yml"

apps/docs/docs/comparisons/graphql-comparison.md

@@ -1,7 +1,3 @@
----
-sidebar_position: 2
----
-
 # tRPC Comparison
 
 I _love_ [tRPC](https://trpc.io/), [KATT (Alex Johansson)](https://github.com/KATT) and all the [other maintainers](https://github.com/trpc/trpc/graphs/contributors) have done some amazing work, and for applications with a single Next.js app, or an express server only consumed by TRPC clients, I whole heartily recommend using tRPC! Also I have undoubtedly taken inspiration from tRPC for tREST.
@@ -19,24 +15,3 @@ tREST allows you design an API as you would "normally", e.g. GET, POST, PUT, DEL
 tRPC structures your API as RPC calls such as `/trpc/getPosts` or `/trpc/getPostComments` etc, this provides an arguably simpler API for the client implementation, however, you loose the predictability of REST(ish) APIs if you have consumers who aren't in Typescript (able to us @ts-rest) or public consumers.
 
 tRPC has many plugins to solve this issue by mapping the API implementation to a REST-like API, however, these approaches are often a bit clunky and reduce the safety of the system overall, tREST does this heavy lifting in the client and server implementations rather than requiring a second layer of abstraction and API endpoint(s) to be defined.
-
-| **Features**      | REST | tRPC  | tREST  |
-| ----------------- | ---- | ----- | ------ |
-| E2E Type Safe     | ❌   | ✅    | ✅     |
-| Protocol          | REST | RPC   | REST   |
-| Public API        | ✅   | ❌    | ✅     |
-| Zod/Yup/Joi       | ❌   | ✅    | 🏗 v1.0 |
-| WebSocket Support | ❌   | ✅    | ❌     |
-| Cmd+Click Access  | ❌   | 🏗 v10 | ✅     |
-| Separate Contract | ❌   | ❌    | ✅     |
-
-tREST also supports [Nest](https://nestjs.com/), it appears adding Nest to tRPC is against the Nest controller principles, so it is not recommended.
-
-| **Libraries Support** | REST | tRPC        | tREST  |
-| --------------------- | ---- | ----------- | ------ |
-| Client fetch/custom   | ✅   | ✅          | ✅     |
-| Client react-query    | ✅   | ✅          | 🏗 v1.0 |
-| Client swr            | ✅   | ✅ (plugin) | 🏗 v1.0 |
-| Server Express        | ✅   | ✅          | ✅     |
-| Server Nest           | ✅   | ❌          | ✅     |
-| Server Next           | ✅   | ✅          | 🏗 v1.0 |

apps/docs/docs/comparisons/rpc-comparison.md

@@ -0,0 +1,67 @@
+# Contract
+
+Define a contract with the `@ts-rest/core` package, you may nest routers within a router, generally you'd want a router for each nested resource e.g. `/users/:id/posts` could have a nested router `contract.users.posts`, this path is what you'd use on the client to query the API.
+
+Breaking down the contract to sub-routers also allows you to split up the backend implementation, for example in Nest.js you could have multiple controllers for the sub-routers.
+
+```typescript
+const c = initContract();
+
+export const contract = c.router({
+  createPost: c.mutation({
+    method: 'POST',
+    path: () => '/posts',
+    responses: {
+      201: c.response<Post>(),
+    },
+    body: z.object({
+      title: z.string(),
+      content: z.string(),
+      published: z.boolean().optional(),
+      description: z.string().optional(),
+    }),
+    summary: 'Create a post',
+  }),
+  getPosts: c.query({
+    method: 'GET',
+    path: () => '/posts',
+    responses: {
+      200: c.response<{ posts: Post[]; total: number }>(),
+    },
+    query: z.object({
+      take: z.string().transform(Number).optional(),
+      skip: z.string().transform(Number).optional(),
+      search: z.string().optional(),
+    }),
+    summary: 'Get all posts',
+  }),
+});
+```
+
+## Combining Contracts
+
+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();
+
+export const postContract = c.router({
+  getPosts: c.query({
+    method: 'GET',
+    path: () => '/posts',
+    responses: {
+      200: c.response<{ posts: Post[]; total: number }>(),
+    },
+    query: z.object({
+      take: z.string().transform(Number).optional(),
+      skip: z.string().transform(Number).optional(),
+      search: z.string().optional(),
+    }),
+    summary: 'Get all posts',
+  }),
+});
+
+export const contract = c.router({
+  posts: postContract,
+});
+```

apps/docs/docs/core/core.md

@@ -0,0 +1,55 @@
+# Error Handling
+
+Since 2.0 ts-rest-api has a built-in error handling, all you need to do is define the response status codes in the contract. The Nest/Express libraries handle the rest for you, letting you utilise HTTP status codes fully without worrying about type safety!
+
+```typescript
+export const routerBasic = c.router({
+  updateUser: c.mutation({
+    method: 'PATCH',
+    path: ({ id }: { id: string }) => `/basic/users/${id}`,
+    response: {
+      200: c.response<User>(),
+      400: c.response<{ message: string }>(),
+    },
+    body: c.body<{ name: string | null; email: string | null }>(),
+    summary: 'Update a user',
+  }),
+});
+```
+
+## Client
+
+The default fetch client has support for this,
+
+```typescript
+const { status, data } = await client.user({ params: { id: '1' } });
+
+if (status === 200) {
+  console.log(data.email);
+} else if (status === 400) {
+  console.log('Not found');
+} else {
+  console.log('Something went wrong');
+}
+```
+
+:::info
+
+The typed response includes the typed status codes along with any other possible statuses
+
+```typescript
+const updatedUser: {
+    status: 200;
+    data: User
+} | {
+    status: 400;
+    data: {
+        message: string;
+    }
+} | {
+    status: 100 | 101 | 102 | 201 | 202 | 203 | ... 47 more ... | 511;
+    data: unknown;
+}
+```
+
+:::

apps/docs/docs/core/errors.md

@@ -0,0 +1,54 @@
+# Fetch Client
+
+Connect to your tRPC instance
+
+```typescript
+export const client = initClient(router, {
+  baseUrl: 'http://localhost:3334',
+  baseHeaders: {},
+});
+```
+
+**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** against the contract, a _mutation_ is a function that does a POST, PUT, PATCH or DELETE request to the api.
+
+```typescript
+const { data, status } = await client.posts.create({
+  body: {
+    title: 'My Post',
+    content: 'This is my post',
+  },
+});
+```
+
+:::info
+Because we type status codes, to check if the request was successful, we can use the `status` property.
+
+e.g.
+
+```typescript
+if (status === 200) {
+  console.log('Success');
+} else {
+  console.log('Something went wrong');
+}
+```
+
+Return type
+
+```typescript
+const data: {
+    status: 200;
+    data: User
+} | {
+    status: 400 | 100 | 101 | 102 | 201 | 202 | 203 | 204 | 205 | 206 | 207 | 300 | 301 | 302 | 303 | 304 | 305 | 307 | ... 36 more ... | 511;
+    data: unknown;
+}
+```
+
+:::

apps/docs/docs/core/fetch.md

@@ -0,0 +1,13 @@
+# Examples
+
+## Blog
+
+Full fledged CRUD example and can be found here [blog example](https://github.com/ts-rest/ts-rest/tree/main/apps/example-next)
+
+- Create a new post
+- View all posts
+- Search posts
+- View a posts
+- Update a post
+
+![Example banner](../static/img/blog-example.png)

apps/docs/docs/examples.mdx

@@ -1,18 +1,5 @@
----
-title: '@ts-rest/express'
-sidebar_position: 6
----
-
 # Express Server
 
-:::caution
-
-The Express implementation is a work in progress, it's missing
-
-- Body and Query Parsing
-
-:::
-
 ```typescript
 const s = initServer();