Allow extra API client args, allow headers, and prettify query args (#179)

Co-authored-by: Youssef Gaber <1728215+Gabrola@users.noreply.github.com>

Author: oliverbutler

.changeset/calm-bananas-guess.md

@@ -0,0 +1,5 @@
+---
+'@ts-rest/react-query': minor
+---
+
+Allow custom API to allow extra args, type them in the react query api calls

.changeset/clean-dots-relate.md

@@ -0,0 +1,6 @@
+---
+'@ts-rest/core': minor
+'@ts-rest/solid-query': minor
+---
+
+Export the default fetch API as `tsRestFetchApi` from the core library, enables you to easy modify the fetcher

.changeset/early-pillows-train.md

@@ -0,0 +1,7 @@
+---
+'@ts-rest/core': minor
+'@ts-rest/react-query': minor
+'@ts-rest/solid-query': minor
+---
+
+Add the ability to remove a baseHeader on a per-request basis by setting the headers value to undefined

.changeset/gorgeous-crews-scream.md

@@ -0,0 +1,5 @@
+---
+'@ts-rest/solid-query': minor
+---
+
+Add solid-query support for extra args and custom headers

.changeset/pretty-books-marry.md

@@ -0,0 +1,5 @@
+---
+'@ts-rest/core': minor
+---
+
+Allow custom API to allow extra args, and type them in the individual api calls

.changeset/spicy-kiwis-teach.md

@@ -0,0 +1,7 @@
+---
+'@ts-rest/core': minor
+'@ts-rest/react-query': minor
+'@ts-rest/solid-query': minor
+---
+
+Prettify the arguments of API calls, making it much clearer what data should be passed to ts-rest api calls (thanks @mattpocockuk!)

README.md

@@ -25,20 +25,60 @@
 
 # Introduction
 
-ts-rest provides an RPC-like client side interface over your existing REST APIs, as well as allowing you define a _separate_ contract implementation rather than going for a 'implementation is the contract' approach, which is best suited for smaller or simpler APIs.
+ts-rest offers a simple way to define a contract for your API, which can be both consumed and implemented by your application, giving you end to end type safety without the hassle or code generation.
 
-If you have non typescript consumers, a public API, or maybe want to add type safety to your existing REST API? ts-rest is what you're looking for!
-
-## Features
+### Features
 
 - End to end type safety 🛟
-- Magic RPC-like API 🪄
-- Tiny bundle size 🌟 (1kb!)
+- RPC-like client side interface 📡
+- [Tiny bundle size 🌟](https://bundlephobia.com/package/@ts-rest/core) (1kb!)
 - Well-tested and production ready ✅
 - No Code Generation 🏃‍♀️
-- Zod support for body parsing 👮‍♀️
+- Zod support for runtime type checks 👮‍♀️
 - Full optional OpenAPI integration 📝
 
+### Super Simple Example
+
+Easily define your API contract somewhere shared
+
+```typescript
+const contract = c.contract({
+  getPosts: {
+    method: 'GET',
+    path: '/posts',
+    query: z.object({
+      skip: z.number(),
+      take: z.number(),
+    }), // <-- Zod schema
+    responses: {
+      200: c.response<Post[]>(), // <-- OR normal TS types
+    },
+  },
+});
+```
+
+Fulfil the contract on your sever, with a type-safe router:
+
+```typescript
+const router = s.router(contract, {
+  getPost: async ({ params: { id } }) => {
+    return {
+      status: 200,
+      body: prisma.post.findUnique({ where: { id } }),
+    };
+  },
+});
+```
+
+Consume the api on the client with a RPC-like interface:
+
+```typescript
+const result = await client.getPosts({
+  query: { skip: 0, take: 10 },
+  // ^-- Fully typed!
+});
+```
+
 ## Quickstart
 
 Install the core package

apps/docs/docs/core/custom.md

@@ -1,70 +1,131 @@
 # Custom Client
 
-:::info
-The `credentials` option has no effect when using a custom client. Make sure you handle credentials in your custom client
-(e.g., setting `withCredentials` in axios).
+By default, not specifying an `api` will use the default `tsRestFetchApi` which uses fetch under the hood.
+
+```typescript
+const client = initQueryClient(postsApi, {
+  baseUrl: 'http://localhost:5003',
+  baseHeaders: {},
+  // Uses `tsRestFetchApi` by default
+});
+```
+
+## Adding a Custom API
+
+If you want a custom api, you can reuse the internal `tsRestFetchApi` to add logging/custom logic to your requests!
+
+```typescript
+const client = initQueryClient(postsApi, {
+  baseUrl: 'http://localhost:5003',
+  baseHeaders: {},
+  api: async (args) => {
+    // Add anything you want here!
+
+    return tsRestFetchApi(args);
+  },
+});
+```
+
+### Extra Query Arguments
+
+By default when you make a ts-rest request you can pass in `params`, `query`, `body`, `headers` etc. However, sometimes you may want to pass in extra arguments to your custom api. You can do this by extending the type of the `args` parameter in your custom api.
+
+```typescript
+const client = initQueryClient(postsApi, {
+  baseUrl: 'http://localhost:5003',
+  baseHeaders: {},
+  api: async (args: ApiFetcherArgs & { myCustomArg?: string }) => {
+    if (args.myCustomArg) {
+      // do something with myCustomArg ✨
+    }
+
+    return tsRestFetchApi(args);
+  },
+});
+```
+
+The magical bit, is this is now fully typed and will work with your IDE's autocomplete! 🤯
+
+One note here, any extra args which are provided here but aren't typed correctly - e.g. if you've `@ts-expect-error`'d, **will still be passed to your api**. This is because the `args` parameter is a spread of all the other arguments you pass in to your api.
+
+```typescript
+client.getPosts({
+  query: { skip: 0, take: 10 },
+  myCustomArg: 'hello',
+  // ^-- autocomplete will work here, allowing you to extend ts-rest however you want
+});
+```
+
+:::tip
+You can use this to accomplish loads of patterns, such as adding a `cache` argument to your api, or adding a `logger` argument to your api - maybe you want to add an `onUploadProgress` argument to your api to track upload progress? You can do all of this with the `args` parameter!
 :::
 
 ## Using Axios (custom api override)
 
-By default ts-rest ships with an incredibly simple fetch 
+By default ts-rest ships with an incredibly simple fetch
 implementation for data fetching, because fetch requires zero extra
-dependencies and works perfectly for most use cases, however, 
+dependencies and works perfectly for most use cases, however,
 sometimes you may want to use Axios, or another data fetching strategy, for that
 you can pass a `api` attribute to the `initClient` or `initQueryClient`.
 
+:::info
+The `credentials` option has no effect when using a custom client. Make sure you handle credentials in your custom client
+(e.g., setting `withCredentials` in axios).
+:::
+
 **Here's a basic example: **
+
 ```typescript
-import { contract } from './some-contract'
-import axios, { Method, AxiosError, AxiosResponse, isAxiosError } from 'axios'
+import { contract } from './some-contract';
+import axios, { Method, AxiosError, AxiosResponse, isAxiosError } from 'axios';
 
 const client = initClient(contract, {
-  baseUrl: "http://localhost:3333/api",
+  baseUrl: 'http://localhost:3333/api',
   baseHeaders: {
-    'Content-Type': 'application/json'
+    'Content-Type': 'application/json',
   },
   api: async ({ path, method, headers, body }) => {
-    const baseUrl = 'http://localhost:3333/api' //baseUrl is not available as a param, yet
+    const baseUrl = 'http://localhost:3333/api'; //baseUrl is not available as a param, yet
     try {
       const result = await axios.request({
         method: method as Method,
         url: `${this.baseUrl}/${path}`,
         headers,
         data: body,
-      })
-      return { status: result.status, body: result.data }
+      });
+      return { status: result.status, body: result.data };
     } catch (e: Error | AxiosError | any) {
       if (isAxiosError(e)) {
-        const error = e as AxiosError
-        const response = error.response as AxiosResponse
-        return { status: response.status, body: response.data }
+        const error = e as AxiosError;
+        const response = error.response as AxiosResponse;
+        return { status: response.status, body: response.data };
       }
-      throw e
+      throw e;
     }
   },
-})
+});
 ```
 
 Sometimes you need dynamic headers, IE passing in a Bearer token. There are two approaches you can take:
 
 ### Instantiate the `client` with the header passed in:
 
 ```typescript
-import { contract } from './some-contract'
-import axios, { Method, AxiosError, AxiosResponse, isAxiosError } from 'axios'
+import { contract } from './some-contract';
+import axios, { Method, AxiosError, AxiosResponse, isAxiosError } from 'axios';
 
 export class SampleAPI {
-  token: string
+  token: string;
   constructor(params: { token: string }) {
-    this.token = params.token
-    this.baseUrl = 'http://localhost:3333/api'
+    this.token = params.token;
+    this.baseUrl = 'http://localhost:3333/api';
   }
   client = () => {
     return initClient(contract, {
       baseUrl: this.baseUrl,
       baseHeaders: {
         Authorization: `Bearer ${idToken}`,
-        'Content-Type': 'application/json'
+        'Content-Type': 'application/json',
       },
       api: async ({ path, method, headers, body }) => {
         try {
@@ -73,33 +134,33 @@ export class SampleAPI {
             url: `${this.baseUrl}/${path}`,
             headers,
             data: body,
-          })
-          return { status: result.status, body: result.data }
+          });
+          return { status: result.status, body: result.data };
         } catch (e: Error | AxiosError | any) {
           if (isAxiosError(e)) {
-            const error = e as AxiosError
-            const response = error.response as AxiosResponse
-            return { status: response.status, body: response.data }
+            const error = e as AxiosError;
+            const response = error.response as AxiosResponse;
+            return { status: response.status, body: response.data };
           }
-          throw e
+          throw e;
         }
       },
-    })
-  }
+    });
+  };
 }
 ```
 
 ### Instantiate the `client` but access a token during runtime:
 
-Here's an example using the `firebase/auth` library. Because `api` is async, you can `await` various calls when using the method. 
+Here's an example using the `firebase/auth` library. Because `api` is async, you can `await` various calls when using the method.
 
 ```typescript
-import { contract } from './some-contract'
-import axios, { Method, AxiosError, AxiosResponse, isAxiosError } from 'axios'
+import { contract } from './some-contract';
+import axios, { Method, AxiosError, AxiosResponse, isAxiosError } from 'axios';
 export class SampleAPI {
-  authInstance: Auth
+  authInstance: Auth;
   constructor(params: { authInstance: Auth }) {
-    this.authInstance = params.authInstance
+    this.authInstance = params.authInstance;
   }
   client = () => {
     return initClient(contract, {
@@ -108,30 +169,30 @@ export class SampleAPI {
         'Content-Type': 'application/json',
       },
       api: async ({ path, method, headers, body }) => {
-        const token = await this.authInstance.currentUser.getIdToken()
+        const token = await this.authInstance.currentUser.getIdToken();
         try {
           const result = await axios.request({
             method: method as Method,
             url: `${this.baseUrl}/${path}`,
-            headers: { 
+            headers: {
               ...headers,
-              Authorization: `Bearer ${idToken}` 
+              Authorization: `Bearer ${idToken}`,
             },
             data: body,
-          })
-          return { status: result.status, body: result.data }
+          });
+          return { status: result.status, body: result.data };
         } catch (e: Error | AxiosError | any) {
           if (isAxiosError(e)) {
-            const error = e as AxiosError
-            const response = error.response as AxiosResponse
-            return { status: response.status, body: response.data }
+            const error = e as AxiosError;
+            const response = error.response as AxiosResponse;
+            return { status: response.status, body: response.data };
           }
-          throw e
+          throw e;
         }
       },
-    })
-  }
+    });
+  };
 }
 ```
 
-:::
+:::