feat: JSON query documentation and changeset

Author: Gabrola

.changeset/silly-cameras-confess.md

@@ -0,0 +1,11 @@
+---
+'@ts-rest/core': minor
+'@ts-rest/express': minor
+'@ts-rest/nest': minor
+'@ts-rest/next': minor
+'@ts-rest/open-api': minor
+'@ts-rest/react-query': minor
+'@ts-rest/solid-query': minor
+---
+
+Allow typed query parameters by encoding them as JSON strings (disabled by default)

apps/docs/docs/core/core.md

@@ -39,6 +39,27 @@ export const contract = c.router({
 });
 ```
 
+## Query Parameters
+
+All query parameters, by default, need to have an input type of `string` since query strings inherently cannot be typed, however, ts-rest allows you to encode query parameters as JSON values.
+This will allow you to use input types other than strings in your contracts.
+
+```typescript
+const c = initContract();
+export const contract = c.router({
+    getPosts: {
+        ...,
+        query: z.object({
+            take: z.number().default(10),
+            skip: z.number().default(0),
+            search: z.string().optional(),
+        }),
+    }
+});
+```
+
+Check the relevant sections to see how to enable JSON query encoding/decoding on the client or server.
+
 ## Combining Contracts
 
 You can combine contracts to create a single contract, helpful if you want many sub contracts, especially if they are huge.

apps/docs/docs/core/fetch.md

@@ -9,15 +9,52 @@ export const client = initClient(router, {
 });
 ```
 
-### Query
+## 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
+### Typed Query Parameters
+
+By default, all query parameters are encoded as strings, however, you can use the `jsonQuery` option to encode query parameters as typed JSON values.
+Make sure to enable JSON query handling on the server as well.
+
+```typescript
+const client = initClient(router, {
+  baseUrl: 'http://localhost:3334',
+  baseHeaders: {},
+  jsonQuery: true,
+});
+
+const { data } = await client.posts.get({
+  query: {
+    take: 10,
+    skip: 0,
+    search: 'hello',
+  },
+});
+```
+
+:::caution
+
+Objects implementing `.toJSON()` will irreversibly be converted to JSON, so you will need to use custom zod transforms to convert back to the original object types.
+
+For example, Date objects will be converted ISO strings by default, so you could handle this case like so:
+
+```typescript
+const dateSchema = z
+  .union([z.string().datetime(), z.date()])
+  .transform((date) => (typeof date === 'string' ? new Date(date) : date));
+```
+
+This will ensure that you could pass Date objects in your client queries. They will be converted to ISO strings in the JSON-encoded URL query string, and then converted back to Date objects on the server by zod's parser.
+
+:::
+
+## Mutate
 
 **Mutate** against the contract, a _mutation_ is a function that does a POST, PUT, PATCH or DELETE request to the api.
 
@@ -43,7 +80,7 @@ if (status === 200) {
 }
 ```
 
-### Return type
+## Return type
 
 ```typescript
 const data: {

apps/docs/docs/express.md

@@ -18,3 +18,11 @@ createExpressEndpoints(router, completeRouter, app);
 ```
 
 `createExpressEndpoints` is a function that takes a router and a complete router, and creates endpoints, with the correct methods, paths and callbacks.
+
+### JSON Query Parameters
+
+To handle JSON query parameters, you can use the `jsonQuery` option.
+
+```typescript
+createExpressEndpoints(router, completeRouter, app, { jsonQuery: true });
+```

apps/docs/docs/nest.md

@@ -28,6 +28,34 @@ The `@Api` decorator takes the route, defines the path and method for the contro
 
 It also injects "appRoute" into the req object, allowing the `@ApiDecorator` decorator automatically parse and check the query and body parameters.
 
+### JSON Query Parameters
+
+To handle JSON query parameters, you can use the `@JsonQuery()` decorator on either your Controller classes or individual endpoint methods.
+
+```typescript
+@Controller()
+@JsonQuery()
+export class PostController implements ControllerShape {}
+
+```
+
+The method decorator can be useful to override the controller's behaviour on a per-endpoint basis.
+
+```typescript
+
+@Controller()
+@JsonQuery()
+export class PostController implements ControllerShape {
+  constructor(private readonly postService: PostService) {}
+
+  @Api(s.route.getPost)
+  @JsonQuery(false)
+  async getPost(@ApiDecorator() { params: { id } }: RouteShape['getPost']) {
+    // ...
+  }
+}
+```
+
 :::caution
 
 Currently any existing Nest global prefix, versioning, or controller prefixes will be ignored, please see https://github.com/ts-rest/ts-rest/issues/70 for more details.

apps/docs/docs/next.md

@@ -30,6 +30,14 @@ export default createNextRouter(api, router);
 
 `createNextRouter` is a function that takes a router and a complete router, and creates endpoints, with the correct methods, paths and callbacks.
 
+### JSON Query Parameters
+
+To handle JSON query parameters, you can use the `jsonQuery` option.
+
+```typescript
+export default createNextRouter(api, router, { jsonQuery: true });
+```
+
 ## Future Work
 
 As this pattern doesn't support a lambda per endpoint, it is planned to provide a helper utility to allow individual endpoints to be created.

apps/docs/docs/react-query.md

@@ -35,6 +35,18 @@ const App = () => {
 };
 ```
 
+### JSON Query Parameters
+
+To enable encoding query parameters as typed JSON values, you can use the `jsonQuery` option.
+
+```typescript
+export const client = initQueryClient(router, {
+  baseUrl: 'http://localhost:3333',
+  baseHeaders: {},
+  jsonQuery: true,
+});
+```
+
 ## Regular Query and Mutations
 
 `@ts-rest/react-query` allows for a regular fetch or mutation if you want, without having to initialise two different clients, one with `@ts-rest/core` and one with `@ts-react/react-query`.