feat(next): Add support for creating single url routes (#503)

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

Author: dodiego

.changeset/olive-balloons-nail.md

@@ -0,0 +1,5 @@
+---
+'@ts-rest/next': minor
+---
+
+Add support for creating single url routes in Next.js

apps/docs/docs/next.mdx

@@ -40,6 +40,26 @@ export default createNextRouter(contract, router);
 
 `createNextRouter` is a function that takes a contract and a complete router, and creates endpoints, with the correct methods, paths and callbacks.
 
+## Single Route Handler
+
+It's also possible to create a handler for a single contract route
+
+```typescript
+// pages/api/posts/index.tsx
+import { createSingleRouteHandler } from '@ts-rest/next';
+
+export default createSingleRouteHandler(api.posts.createPost, async (args) => {
+  const newPost = await posts.createPost(args.body);
+
+  return {
+    status: 201,
+    body: newPost,
+  };
+});
+```
+
+`createSingleRouteHandler` is a function that takes a single contract route and a handler, and creates a `nextApiHandler`
+
 ### JSON Query Parameters
 
 To handle JSON query parameters, you can use the `jsonQuery` option.

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

@@ -3,6 +3,7 @@ import { NextApiRequest, NextApiResponse } from 'next';
 import {
   createNextRoute,
   createNextRouter,
+  createSingleRouteHandler,
   RequestValidationError,
 } from './ts-rest-next';
 import { z } from 'zod';
@@ -41,6 +42,9 @@ const contract = c.router({
     responses: {
       200: c.response<{ id: string; test: string }>(),
     },
+    pathParams: z.object({
+      id: z.string(),
+    }),
   },
   getZodQuery: {
     method: 'GET',
@@ -437,6 +441,168 @@ describe('createNextRouter', () => {
   });
 });
 
+describe('createSingleUrlNextRouter', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it('should send back a 200', async () => {
+    const resultingRouter = createSingleRouteHandler(
+      contract.getWithParams,
+      nextEndpoint.getWithParams,
+    );
+
+    const req = mockSingleUrlReq('/test/123', {
+      method: 'GET',
+      query: { id: '123' },
+    });
+
+    await resultingRouter(req, mockRes);
+
+    expect(mockRes.status).toHaveBeenCalledWith(200);
+    expect(jsonMock).toHaveBeenCalledWith({
+      id: '123',
+    });
+  });
+
+  it('should send back a 404', async () => {
+    const resultingRouter = createSingleRouteHandler(
+      contract.getWithParams,
+      nextEndpoint.getWithParams,
+    );
+
+    const req = mockSingleUrlReq('/wrong-url', {
+      method: 'GET',
+    });
+
+    await resultingRouter(req, mockRes);
+
+    expect(mockRes.status).toHaveBeenCalledWith(404);
+    expect(jsonMock).not.toHaveBeenCalled();
+  });
+
+  it('should send back a 404', async () => {
+    const resultingRouter = createSingleRouteHandler(
+      contract.getWithParams,
+      nextEndpoint.getWithParams,
+    );
+
+    const req = mockSingleUrlReq('/test', {
+      method: 'GET',
+    });
+
+    await resultingRouter(req, mockRes);
+
+    expect(mockRes.status).toHaveBeenCalledWith(404);
+    expect(jsonMock).not.toHaveBeenCalled();
+  });
+
+  it('should send body, params and query correctly', async () => {
+    const resultingRouter = createSingleRouteHandler(
+      contract.advanced,
+      nextEndpoint.advanced,
+    );
+
+    const req = mockSingleUrlReq('/advanced/123', {
+      method: 'POST',
+      body: {
+        test: 'test-body',
+      },
+      query: { id: '123' },
+    });
+
+    await resultingRouter(req, mockRes);
+
+    expect(mockRes.status).toHaveBeenCalledWith(200);
+    expect(jsonMock).toHaveBeenCalledWith({
+      id: '123',
+      test: 'test-body',
+    });
+  });
+
+  it('should send json query correctly', async () => {
+    const resultingRouter = createSingleRouteHandler(
+      contract.getWithQuery,
+      nextEndpoint.getWithQuery,
+      { jsonQuery: true },
+    );
+
+    const req = mockSingleUrlReq('/test-query', {
+      method: 'GET',
+      query: { test: '"test-query-string"', foo: '123' },
+    });
+
+    await resultingRouter(req, mockRes);
+
+    expect(mockRes.status).toHaveBeenCalledWith(200);
+    expect(jsonMock).toHaveBeenCalledWith({
+      test: 'test-query-string',
+      foo: 123,
+    });
+  });
+
+  it('should differentiate between /test and /test/id', async () => {
+    const resultingRouter = createSingleRouteHandler(
+      contract.getWithParams,
+      nextEndpoint.getWithParams,
+    );
+
+    const req = mockSingleUrlReq('/test/3', {
+      method: 'GET',
+      query: { id: '3' },
+    });
+
+    await resultingRouter(req, mockRes);
+
+    expect(mockRes.status).toHaveBeenCalledWith(200);
+    expect(jsonMock).toHaveBeenCalledWith({
+      id: '3',
+    });
+  });
+
+  describe('response validation', () => {
+    it('should include default value and removes extra field', async () => {
+      const resultingRouter = createSingleRouteHandler(
+        contract.getZodQuery,
+        nextEndpoint.getZodQuery,
+        { responseValidation: true },
+      );
+
+      const req = mockSingleUrlReq('/test/123/name', {
+        method: 'GET',
+        query: { field: 'foo', id: '123', name: 'name' },
+      });
+
+      await resultingRouter(req, mockRes);
+
+      expect(mockRes.status).toHaveBeenCalledWith(200);
+      expect(jsonMock).toHaveBeenCalledWith({
+        id: 123,
+        name: 'name',
+        defaultValue: 'hello world',
+      });
+    });
+
+    it('fails with invalid field', async () => {
+      const errorHandler = jest.fn();
+      const resultingRouter = createSingleRouteHandler(
+        contract.getZodQuery,
+        nextEndpoint.getZodQuery,
+        { responseValidation: true, errorHandler },
+      );
+
+      const req = mockSingleUrlReq('/test/2000/name', {
+        method: 'GET',
+        query: { id: '2000', name: 'name' },
+      });
+
+      await resultingRouter(req, mockRes);
+
+      expect(errorHandler).toHaveBeenCalled();
+    });
+  });
+});
+
 export const mockReq = (
   url: string,
   args: {
@@ -458,3 +624,17 @@ export const mockReq = (
 
   return req;
 };
+
+const mockSingleUrlReq = (
+  url: string,
+  args: { query?: Record<string, unknown>; body?: unknown; method: string },
+): NextApiRequest => {
+  const req = {
+    url,
+    query: args.query,
+    body: args.body,
+    method: args.method,
+  } as unknown as NextApiRequest;
+
+  return req;
+};

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

@@ -54,6 +54,17 @@ type AppRouterWithImplementation = {
   [key: string]: AppRouterWithImplementation | AppRouteWithImplementation<any>;
 };
 
+type CreateNextRouterOptions = {
+  jsonQuery?: boolean;
+  responseValidation?: boolean;
+  throwRequestValidation?: boolean;
+  errorHandler?: (
+    err: unknown,
+    req: NextApiRequest,
+    res: NextApiResponse,
+  ) => void;
+};
+
 /**
  * Combine all AppRoutes with their implementations into a single object
  * which is easier to work with
@@ -186,42 +197,100 @@ export const createNextRoute = <T extends AppRouter>(
 export const createNextRouter = <T extends AppRouter>(
   routes: T,
   obj: RecursiveRouterObj<T>,
-  options?: {
-    jsonQuery?: boolean;
-    responseValidation?: boolean;
-    throwRequestValidation?: boolean;
-    errorHandler?: (
-      err: unknown,
-      req: NextApiRequest,
-      res: NextApiResponse,
-    ) => void;
-  },
+  options?: CreateNextRouterOptions,
 ) => {
-  const {
-    jsonQuery = false,
-    responseValidation = false,
-    throwRequestValidation = false,
-  } = options || {};
+  return handlerFactory((req) => {
+    const combinedRouter = mergeRouterAndImplementation(routes, obj);
 
-  const combinedRouter = mergeRouterAndImplementation(routes, obj);
-
-  return async (req: NextApiRequest, res: NextApiResponse) => {
+    // eslint-disable-next-line prefer-const
     let { 'ts-rest': params, ...query } = req.query;
-    params = (params as string[]) || [];
 
+    params = (params as string[]) || [];
     const route = getRouteImplementation(
       combinedRouter,
       params,
       req.method as string,
     );
+    let pathParams;
+    if (route) {
+      pathParams = getPathParamsFromArray(params, route);
+    } else {
+      pathParams = {};
+    }
+    return { pathParams, query, route };
+  }, options);
+};
 
+/**
+ * Turn a contract route and a handler into a Next.js compatible handler
+ * Should be exported from your pages/api/path/to/handler.tsx file.
+ *
+ * e.g.
+ *
+ * ```typescript
+ * export default createNextRouter(contract, implementationHandler);
+ * ```
+ *
+ * @param appRoute
+ * @param options
+ * @returns
+ */
+export function createSingleRouteHandler<T extends AppRoute>(
+  appRoute: AppRoute,
+  implementationHandler: AppRouteImplementation<T>,
+  options?: CreateNextRouterOptions,
+) {
+  return handlerFactory((req) => {
+    const route = { ...appRoute, implementation: implementationHandler };
+    const urlChunks = req.url!.split('/').slice(1);
+    const pathParams = getPathParamsFromArray(urlChunks, route);
+    const query = req.query
+      ? Object.fromEntries(
+          Object.entries(req.query).filter(
+            ([key]) => pathParams[key] === undefined,
+          ),
+        )
+      : {};
+
+    const isValidRoute = isRouteCorrect(
+      appRoute,
+      urlChunks,
+      req.method as string,
+    );
+
+    return { pathParams, query, route: isValidRoute ? route : null };
+  }, options);
+}
+
+/**
+ * Create a next.js compatible handler for a given route
+ * @param getArgumentsFromRequest
+ * @param options
+ * @returns
+ */
+const handlerFactory = (
+  getArgumentsFromRequest: (req: NextApiRequest) => {
+    pathParams: Record<string, string>;
+    query: NextApiRequest['query'];
+    route: AppRouterWithImplementation[keyof AppRouterWithImplementation];
+  },
+  options?: CreateNextRouterOptions,
+) => {
+  return async (req: NextApiRequest, res: NextApiResponse) => {
+    const {
+      jsonQuery = false,
+      responseValidation = false,
+      throwRequestValidation = false,
+    } = options || {};
+
+    const args = getArgumentsFromRequest(req);
+    const { pathParams, route } = args;
+    let { query } = args;
     if (!route) {
       res.status(404).end();
       return;
     }
 
-    const pathParams = getPathParamsFromArray(params, route);
-
     const pathParamsResult = checkZodSchema(pathParams, route.pathParams, {
       passThroughExtraKeys: true,
     });