feat: add type inference helpers (#193)

* feat: add inference type helpers

Author: Gabrola

.changeset/purple-comics-notice.md

@@ -0,0 +1,5 @@
+---
+'@ts-rest/core': minor
+---
+
+Added inference type helpers

apps/docs/docs/core/core.md

@@ -116,21 +116,3 @@ export const contract = c.router({
   },
 });
 ```
-
-## Response Types
-
-If you need to quickly extract the Response types from a given Contract, you can use the `ResponsesForRouter` type.
-
-```typescript
-import { ResponsesForRouter } from '@ts-rest/core'
-import { contract } from './contract'
-
-//  initContract() must called prior
-type ResponseShapes = ResponsesForRouter<typeof contract>
-
-async function someHttpCall(req: Request): Promise<ResponseShapes['getPosts']> {
-  return ...
-}
-```
-
-This is particularly useful for Services/Functions/Lambdas that do not use frameworks like Express or Nestjs. 

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

@@ -1,7 +1,7 @@
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
-# multipart/form-data
+# File Uploading
 
 ts-rest supports multipart/form-data requests, this is useful for uploading files or working with FormData from a form.
 

apps/docs/docs/core/infer-types.md

@@ -0,0 +1,69 @@
+# Inferring Types
+
+Often, we need to manually extract the request or responses types of specific contract endpoints, so functions, services, lambdas, React components, etc. can be safely typed
+when there is no automatic type inference.
+
+We have separate type helpers for server-side and client-side code since we need to infer either the Input or Output Zod types depending on
+where the code is used.
+
+## Inferring Response Types
+
+To get the response types of a contract or a specific endpoint, we have the following type helpers:
+
+- `ServerInferResponses<AppRouter | AppRoute, OptionalHttpStatusCode>`
+- `ClientInferResponses<AppRouter | AppRoute, OptionalHttpStatusCode>`
+
+```typescript
+import { ServerInferResponses } from '@ts-rest/core';
+import { contract } from './contract';
+
+type ResponseShapes = ServerInferResponses<typeof contract>;
+
+async function someHttpCall(req: Request): Promise<ResponseShapes['getPosts']> {
+  return ...;
+}
+
+function someServiceCall(): ServerInferResponses<typeof contract.getPosts> {
+  return ...;
+}
+```
+
+### Inferring Response Body
+
+If you need to infer the response body for a defined response status of a specific endpoint, we can use the following type helpers:
+
+- `ServerInferResponseBody<AppRoute, OptionalHttpStatusCode>`
+- `ClientInferResponseBody<AppRoute, OptionalHttpStatusCode>`
+
+This is syntactic sugar for `ServerInferResponses<AppRoute, OptionalHttpStatusCode & keyof AppRoute['responses']>['body']`
+
+```typescript
+import React from 'react';
+import { ClientInferResponseBody } from '@ts-rest/core';
+import { contract } from './contract';
+
+type Post = ClientInferResponseBody<typeof contract.getPost, 200>;
+
+function PostComponent(props: { post: Post }) {
+  return <>...</>;
+}
+```
+
+## Inferring Request Types
+
+To get the request (path params, query params, body) types of a contract or a specific endpoint, we have the following type helpers:
+
+- `ServerInferRequest<AppRouter | AppRoute>`
+- `ClientInferRequest<AppRouter | AppRoute>`
+
+```typescript
+import { ServerInferRequest, ServerInferResponses } from '@ts-rest/core';
+import { contract } from './contract';
+
+type GetPostRequest = ServerInferRequest<typeof contract.getPost>;
+type GetPostResponse = ServerInferResponses<typeof contract.getPost>;
+
+async function getPostLambdaHandler({ params, query }: GetPostRequest): Promise<GetPostResponse> {
+  return ...;
+}
+```

apps/docs/sidebars.js

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

libs/ts-rest/core/src/index.ts

@@ -7,3 +7,4 @@ export * from './lib/type-utils';
 export * from './lib/zod-utils';
 export * from './lib/server';
 export * from './lib/response-validation-error';
+export * from './lib/infer-types';

libs/ts-rest/core/src/lib/client.ts

@@ -34,10 +34,17 @@ export type PathParamsFromUrl<T extends AppRoute> = ParamsFromUrl<
 /**
  * Merge `PathParamsFromUrl<T>` with pathParams schema if it exists
  */
-export type PathParamsWithCustomValidators<T extends AppRoute> =
-  T['pathParams'] extends undefined
-    ? PathParamsFromUrl<T>
-    : Merge<PathParamsFromUrl<T>, ZodInferOrType<T['pathParams']>>;
+export type PathParamsWithCustomValidators<
+  T extends AppRoute,
+  TClientOrServer extends 'client' | 'server' = 'server'
+> = T['pathParams'] extends undefined
+  ? PathParamsFromUrl<T>
+  : Merge<
+      PathParamsFromUrl<T>,
+      TClientOrServer extends 'server'
+        ? ZodInferOrType<T['pathParams']>
+        : ZodInputOrType<T['pathParams']>
+    >;
 
 // Allow FormData if the contentType is multipart/form-data
 type AppRouteBodyOrFormData<T extends AppRouteMutation> =
@@ -91,24 +98,20 @@ export type ApiRouteResponse<T> =
       body: unknown;
     };
 
-export type ResponseForRoute<T extends AppRoute> = ApiRouteResponse<
+/**
+ * @deprecated Only safe to use on the client-side. Use `ServerInferResponses`/`ClientInferResponses` instead.
+ */
+export type ApiResponseForRoute<T extends AppRoute> = ApiRouteResponse<
   T['responses']
->
-
-export type ResponsesForRouter<T extends AppRouter> = {
-  [K in keyof T]: T[K] extends AppRoute
-  ? ResponseForRoute<T[K]>
-  : T[K] extends AppRouter ? ResponsesForRouter<T[K]> : never;
-};
+>;
 
 /**
- * 
- * @deprecated
+ * @deprecated Only safe to use on the client-side. Use `ServerInferResponses`/`ClientInferResponses` instead.
  */
 export function getRouteResponses<T extends AppRouter>(router: T) {
   return {} as {
     [K in keyof typeof router]: typeof router[K] extends AppRoute
-      ? ResponseForRoute<typeof router[K]>
+      ? ApiResponseForRoute<typeof router[K]>
       : 'not a route';
   };
 }