feat: create fluent router builder for serverless and optimize exported return types (#639)

Author: Gabrola

.changeset/green-readers-change.md

@@ -0,0 +1,5 @@
+---
+'@ts-rest/serverless': minor
+---
+
+BREAKING CHANGE: The order of generics on the `tsr.*` methods have been swapped. Now you don't have to pass `typeof contract` first. You can now pass your request extension type only.

.changeset/spotty-ads-glow.md

@@ -0,0 +1,11 @@
+---
+'@ts-rest/react-query': minor
+'@ts-rest/solid-query': minor
+'@ts-rest/serverless': minor
+'@ts-rest/vue-query': minor
+'@ts-rest/express': minor
+'@ts-rest/fastify': minor
+'@ts-rest/next': minor
+---
+
+Make sure initialized client and router types are exported so they can be re-exported with types emitted

.changeset/violet-dogs-explode.md

@@ -0,0 +1,5 @@
+---
+'@ts-rest/serverless': minor
+---
+
+Fluent router builder for easier modification of request context type in middleware. Try it out through  `tsr.routerBuilder(contract)`!

apps/docs/docs/serverless/routers.md

@@ -35,7 +35,6 @@ import { tsr } from '@ts-rest/serverless/aws';
 import { contract } from './contract';
 
 export const postsRouter = tsr.router<
-  typeof contract,   // <-- You have to add the contract type here
   { userId: string } // <-- Add the extended part here. This will be visible in request.userId
 >(contract, { ... });
 ```

libs/ts-rest/express/src/lib/ts-rest-express.ts

@@ -22,7 +22,7 @@ import type {
 import {
   AppRouteImplementationOrOptions,
   TsRestExpressOptions,
-  RecursiveRouterObj,
+  RouterImplementation,
   TsRestRequestHandler,
   isAppRouteImplementation,
 } from './types';
@@ -31,12 +31,21 @@ import { Stream } from 'stream';
 
 export const initServer = () => {
   return {
-    router: <T extends AppRouter>(router: T, args: RecursiveRouterObj<T>) =>
-      args,
-    route: <T extends AppRoute>(
-      route: T,
-      args: AppRouteImplementationOrOptions<T>,
-    ) => args,
+    router: <
+      T extends AppRouter = AppRouter,
+      TRouter extends RouterImplementation<T> = RouterImplementation<T>,
+    >(
+      contract: T,
+      router: TRouter,
+    ) => router,
+    route: <
+      T extends AppRoute,
+      TRoute extends
+        AppRouteImplementationOrOptions<T> = AppRouteImplementationOrOptions<T>,
+    >(
+      contract: T,
+      route: TRoute,
+    ) => route,
   };
 };
 
@@ -46,7 +55,7 @@ const recursivelyApplyExpressRouter = ({
   processRoute,
 }: {
   schema: AppRouter | AppRoute;
-  router: RecursiveRouterObj<any> | AppRouteImplementationOrOptions<any>;
+  router: RouterImplementation<any> | AppRouteImplementationOrOptions<any>;
   processRoute: (
     implementation: AppRouteImplementationOrOptions<AppRoute>,
     schema: AppRoute,
@@ -60,7 +69,7 @@ const recursivelyApplyExpressRouter = ({
 
       recursivelyApplyExpressRouter({
         schema: schema[key],
-        router: (router as RecursiveRouterObj<any>)[key],
+        router: (router as RouterImplementation<any>)[key],
         processRoute,
       });
     }
@@ -286,7 +295,7 @@ const requestValidationErrorHandler = (
 
 export const createExpressEndpoints = <TRouter extends AppRouter>(
   schema: TRouter,
-  router: RecursiveRouterObj<TRouter>,
+  router: RouterImplementation<TRouter>,
   app: IRouter,
   options: TsRestExpressOptions<TRouter> = {
     logInitialization: true,

libs/ts-rest/express/src/lib/types.ts

@@ -80,9 +80,9 @@ export const isAppRouteImplementation = <TRoute extends AppRoute>(
   return typeof obj === 'function';
 };
 
-export type RecursiveRouterObj<T extends AppRouter> = {
+export type RouterImplementation<T extends AppRouter> = {
   [TKey in keyof T]: T[TKey] extends AppRouter
-    ? RecursiveRouterObj<T[TKey]>
+    ? RouterImplementation<T[TKey]>
     : T[TKey] extends AppRoute
     ? AppRouteImplementationOrOptions<T[TKey]>
     : never;

libs/ts-rest/fastify/src/lib/ts-rest-fastify.ts

@@ -61,9 +61,9 @@ type AppRouteImplementation<T extends AppRoute> = (
   },
 ) => Promise<ServerInferResponses<T>>;
 
-type RecursiveRouterObj<T extends AppRouter> = {
+export type RouterImplementation<T extends AppRouter> = {
   [TKey in keyof T]: T[TKey] extends AppRouter
-    ? RecursiveRouterObj<T[TKey]>
+    ? RouterImplementation<T[TKey]>
     : T[TKey] extends AppRoute
     ? AppRouteImplementationOrOptions<T[TKey]>
     : never;
@@ -193,8 +193,8 @@ const RouterEmbeddedContract = Symbol('RouterEmbeddedContract');
 export const initServer = () => ({
   router: <TContract extends AppRouter>(
     contract: TContract,
-    routes: RecursiveRouterObj<TContract>,
-  ): RecursiveRouterObj<TContract> => ({
+    routes: RouterImplementation<TContract>,
+  ): RouterImplementation<TContract> => ({
     ...routes,
     [RouterEmbeddedContract]: contract,
   }),
@@ -203,7 +203,7 @@ export const initServer = () => ({
     implementation: AppRouteImplementation<TAppRoute>,
   ) => implementation,
   registerRouter: <
-    T extends RecursiveRouterObj<TContract>,
+    T extends RouterImplementation<TContract>,
     TContract extends AppRouter,
   >(
     contract: TContract,
@@ -239,7 +239,7 @@ export const initServer = () => ({
   },
   plugin:
     <T extends AppRouter>(
-      router: RecursiveRouterObj<T>,
+      router: RouterImplementation<T>,
     ): fastify.FastifyPluginCallback<RegisterRouterOptions<T>> =>
     (
       app,
@@ -252,7 +252,7 @@ export const initServer = () => ({
       done,
     ) => {
       const embeddedContract = (
-        router as RecursiveRouterObj<T> & { [RouterEmbeddedContract]: T }
+        router as RouterImplementation<T> & { [RouterEmbeddedContract]: T }
       )[RouterEmbeddedContract];
 
       const { hooks = {}, ...restOfOptions } = opts;
@@ -423,7 +423,7 @@ const registerRoute = <TAppRoute extends AppRoute>(
  * @param options
  */
 const recursivelyRegisterRouter = <T extends AppRouter>(
-  routerImpl: RecursiveRouterObj<T>,
+  routerImpl: RouterImplementation<T>,
   appRouter: T,
   path: string[],
   fastify: fastify.FastifyInstance,
@@ -435,7 +435,7 @@ const recursivelyRegisterRouter = <T extends AppRouter>(
   ) {
     for (const key in routerImpl) {
       recursivelyRegisterRouter(
-        routerImpl[key] as unknown as RecursiveRouterObj<T>,
+        routerImpl[key] as unknown as RouterImplementation<T>,
         appRouter[key] as unknown as T,
         [...path, key],
         fastify,

libs/ts-rest/next/src/lib/ts-rest-next.ts

@@ -38,9 +38,9 @@ type AppRouteImplementation<T extends AppRoute> = (
   },
 ) => Promise<ServerInferResponses<T>>;
 
-type RecursiveRouterObj<T extends AppRouter> = {
+export type RouterImplementation<T extends AppRouter> = {
   [TKey in keyof T]: T[TKey] extends AppRouter
-    ? RecursiveRouterObj<T[TKey]>
+    ? RouterImplementation<T[TKey]>
     : T[TKey] extends AppRoute
     ? AppRouteImplementation<T[TKey]>
     : never;
@@ -74,7 +74,7 @@ type CreateNextRouterOptions = {
  */
 const mergeRouterAndImplementation = <T extends AppRouter>(
   router: T,
-  implementation: RecursiveRouterObj<T>,
+  implementation: RouterImplementation<T>,
 ): AppRouterWithImplementation => {
   const keys = Object.keys(router);
 
@@ -176,7 +176,7 @@ const getRouteImplementation = (
 export const createNextRoute = <T extends AppRouter | AppRoute>(
   appRouter: T,
   implementation: T extends AppRouter
-    ? RecursiveRouterObj<T>
+    ? RouterImplementation<T>
     : T extends AppRoute
     ? AppRouteImplementation<T>
     : never,
@@ -200,7 +200,7 @@ export const createNextRoute = <T extends AppRouter | AppRoute>(
  */
 export const createNextRouter = <T extends AppRouter>(
   routes: T,
-  obj: RecursiveRouterObj<T>,
+  obj: RouterImplementation<T>,
   options?: CreateNextRouterOptions,
 ) => {
   return handlerFactory((req) => {

libs/ts-rest/react-query/src/lib/react-query.ts

@@ -149,14 +149,20 @@ const getRouteUseMutation = <
   };
 };
 
+/** @deprecated Use `TsRestReactQueryClient` instead */
 export type InitClientReturn<
   T extends AppRouter,
   TClientArgs extends ClientArgs,
+> = UseTsRestQueryClient<T, TClientArgs>;
+
+export type TsRestReactQueryClient<
+  T extends AppRouter,
+  TClientArgs extends ClientArgs,
 > = {
   [TKey in keyof T]: T[TKey] extends AppRoute
     ? Without<AppRouteFunctions<T[TKey], TClientArgs>, never>
     : T[TKey] extends AppRouter
-    ? InitClientReturn<T[TKey], TClientArgs>
+    ? TsRestReactQueryClient<T[TKey], TClientArgs>
     : never;
 };
 
@@ -168,10 +174,10 @@ export const initQueryClient = <
 >(
   router: T,
   clientArgs: TClientArgs,
-): InitClientReturn<T, TClientArgs> => {
+): TsRestReactQueryClient<T, TClientArgs> => {
   const recursiveInit = <TInner extends AppRouter>(
     innerRouter: TInner,
-  ): InitClientReturn<TInner, TClientArgs> => {
+  ): TsRestReactQueryClient<TInner, TClientArgs> => {
     return Object.fromEntries(
       Object.entries(innerRouter).map(([key, subRouter]) => {
         if (isAppRoute(subRouter)) {
@@ -311,23 +317,23 @@ export const initQueryClient = <
   };
 };
 
-type InitUseTsRestQueryClientReturn<
+export type UseTsRestQueryClient<
   T extends AppRouter,
   TClientArgs extends ClientArgs,
 > = {
   [TKey in keyof T]: T[TKey] extends AppRoute
     ? Without<AppRouteFunctionsWithQueryClient<T[TKey], TClientArgs>, never>
     : T[TKey] extends AppRouter
-    ? InitUseTsRestQueryClientReturn<T[TKey], TClientArgs>
+    ? UseTsRestQueryClient<T[TKey], TClientArgs>
     : never;
 };
 
 export const useTsRestQueryClient = <
   T extends AppRouter,
   TClientArgs extends ClientArgs,
 >(
-  client: InitClientReturn<T, TClientArgs>,
-): InitUseTsRestQueryClientReturn<T, TClientArgs> => {
+  client: TsRestReactQueryClient<T, TClientArgs>,
+): UseTsRestQueryClient<T, TClientArgs> => {
   // @ts-expect-error - hidden symbol, so we can refetch the original client router and clientArgs
   const { router } = client[ClientParameters] as unknown as {
     router: T;
@@ -338,8 +344,8 @@ export const useTsRestQueryClient = <
 
   const recursiveInit = <TInner extends AppRouter>(
     innerRouter: TInner,
-    innerClient: InitClientReturn<TInner, TClientArgs>,
-  ): InitUseTsRestQueryClientReturn<TInner, TClientArgs> => {
+    innerClient: TsRestReactQueryClient<TInner, TClientArgs>,
+  ): UseTsRestQueryClient<TInner, TClientArgs> => {
     return Object.fromEntries(
       Object.entries(innerRouter).map(([key, subRouter]) => {
         if (isAppRoute(subRouter)) {

libs/ts-rest/react-query/src/lib/types.ts

@@ -15,7 +15,7 @@ import {
   PartialClientInferRequest,
   SuccessfulHttpStatusCode,
 } from '@ts-rest/core';
-import { InitClientReturn } from './react-query';
+import { TsRestReactQueryClient } from './react-query';
 
 // Data response if it's a 2XX
 export type DataResponse<TAppRoute extends AppRoute> = ClientInferResponses<
@@ -59,34 +59,34 @@ export type UseInfiniteQueryResult<
   TData = DataResponse<TAppRoute>,
 > = TanStackUseInfiniteQueryResult<TData, ErrorResponse<TAppRoute>>;
 
-type InferClientArgs<TClient extends InitClientReturn<any, any>> =
-  TClient extends InitClientReturn<any, infer TClientArgs>
+type InferClientArgs<TClient extends TsRestReactQueryClient<any, any>> =
+  TClient extends TsRestReactQueryClient<any, infer TClientArgs>
     ? TClientArgs
     : never;
 
 export type UseMutationOptions<
   TAppRoute extends AppRoute,
-  TClientArgsOrClient extends ClientArgs | InitClientReturn<any, any>,
+  TClientArgsOrClient extends ClientArgs | TsRestReactQueryClient<any, any>,
 > = TanStackUseMutationOptions<
   DataResponse<TAppRoute>,
   ErrorResponse<TAppRoute>,
   TClientArgsOrClient extends ClientArgs
     ? PartialClientInferRequest<TAppRoute, TClientArgsOrClient>
-    : TClientArgsOrClient extends InitClientReturn<any, any>
+    : TClientArgsOrClient extends TsRestReactQueryClient<any, any>
     ? PartialClientInferRequest<TAppRoute, InferClientArgs<TClientArgsOrClient>>
     : never,
   unknown
 >;
 
 export type UseMutationResult<
   TAppRoute extends AppRoute,
-  TClientArgsOrClient extends ClientArgs | InitClientReturn<any, any>,
+  TClientArgsOrClient extends ClientArgs | TsRestReactQueryClient<any, any>,
 > = TanStackUseMutationResult<
   DataResponse<TAppRoute>,
   ErrorResponse<TAppRoute>,
   TClientArgsOrClient extends ClientArgs
     ? PartialClientInferRequest<TAppRoute, TClientArgsOrClient>
-    : TClientArgsOrClient extends InitClientReturn<any, any>
+    : TClientArgsOrClient extends TsRestReactQueryClient<any, any>
     ? PartialClientInferRequest<TAppRoute, InferClientArgs<TClientArgsOrClient>>
     : never,
   unknown