refactor: revise some namings in Nest (#140)

* refactor: revise some namings in Nest

* fix: JsonQuery method decorator not overriding class decorator

* chore: changeset

* fix: Nest deprecation warning for Zod errors

* docs: update and fix badge links

* docs: add link to docs in deprecation message

* refactor: rename TypedRequest into TsRestRequest

* chore: update documentation and release notes

Author: Gabrola

.changeset/dull-maps-draw.md

@@ -0,0 +1,11 @@
+---
+'@ts-rest/nest': minor
+'@ts-rest/core': patch
+---
+
+Rename some Nest functions and types, and deprecate old names
+
+Fix Nest deprecation warning when passing Zod error to HttpException (#122)
+
+Some internal helper types (`NestControllerShapeFromAppRouter` and `NestAppRouteShape`) that were previously exported are now kept internal.
+You can use `NestControllerInterface` and `NestRequestShapes` instead.

README.md

@@ -4,19 +4,24 @@
  <img src="https://avatars.githubusercontent.com/u/109956939?s=400&u=8bf67b1281da46d64eab85f48255cd1892bf0885&v=4" height="150"></img>
 </p>
 
- <p align="center">RPC-like client and server helpers for a magical end to end typed experience</p> 
- <p align="center">
-   <a href="https://www.npmjs.com/package/@ts-rest/core">
-   <img src="https://img.shields.io/npm/v/@ts-rest/core.svg" alt="langue typescript"/>
-   </a>
-   <a href="https://www.npmjs.com/package/@ts-rest/core"/>
-   <img alt="npm" src="https://img.shields.io/npm/dw/@ts-rest/core"/>
-     <a href="https://github.com/ts-rest/ts-rest/blob/main/LICENSE"></a>
-    <img alt="GitHub" src="https://img.shields.io/github/license/ts-rest/ts-rest"/> 
-   <img alt="GitHub Workflow Status" src="https://img.shields.io/bundlephobia/minzip/@ts-rest/core?label=%40ts-rest%2Fcore"/>
-   <img alt="GitHub Workflow Status" src="https://img.shields.io/discord/1055855205960392724"/>
-   
- </p>
+<p align="center">RPC-like client and server helpers for a magical end to end typed experience</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@ts-rest/core">
+    <img src="https://img.shields.io/npm/v/@ts-rest/core.svg" alt="langue typescript"/>
+  </a>
+  <img alt="Github Workflow Status" src="https://img.shields.io/github/actions/workflow/status/ts-rest/ts-rest/release.yml?branch=main"/>
+  <a href="https://www.npmjs.com/package/@ts-rest/core">
+    <img alt="npm" src="https://img.shields.io/npm/dw/@ts-rest/core"/>
+  </a>
+  <a href="https://github.com/ts-rest/ts-rest/blob/main/LICENSE">
+    <img alt="License" src="https://img.shields.io/github/license/ts-rest/ts-rest"/>
+  </a>
+  <img alt="Bundle Size" src="https://img.shields.io/bundlephobia/minzip/@ts-rest/core?label=%40ts-rest%2Fcore"/>
+  <a href="https://discord.com/invite/2Megk85k5a">  
+    <img alt="Discord" src="https://img.shields.io/discord/1055855205960392724"/>
+  </a>
+</p>
 
 # Introduction
 

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

@@ -112,11 +112,11 @@ With Nest this is a pretty simple implementation, due to the extensible Decorato
 ```ts
 // nest
 @Controller()
-export class AppController implements ControllerShape {
+export class AppController implements NestControllerInterface<typeof c> {
   @Api(s.route.updateUserAvatar)
   @UseInterceptors(FileInterceptor('avatar'))
   async updateUserAvatar(
-    @ApiDecorator() { params: { id } }: RouteShape['updateUserAvatar'],
+    @TsRestRequest() { params: { id } }: RequestShapes['updateUserAvatar'],
     @UploadedFile() avatar: Express.Multer.File
   ) {
     return {

apps/docs/docs/nest.md

@@ -1,19 +1,25 @@
 # Nest
 
-By default Nest doesn't offer a nice way to ensure type safe controllers, primarily because it's decorator driven rather than functional, like Express.
+As opposed to the Express implementation, where we can infer types from a function signature, we need to explicitly define our types since Nest controllers are implemented as classes.
 
 ```typescript
-const s = initNestServer(apiBlog);
-type ControllerShape = typeof s.controllerShape;
-type RouteShape = typeof s.routeShapes;
-type ResponseShapes = typeof s.responseShapes;
+import {
+  Api,
+  nestControllerContract,
+  NestControllerInterface,
+  NestRequestShapes,
+  TsRestRequest,
+} from '@ts-rest/nest';
+
+const c = nestControllerContract(apiBlog);
+type RequestShapes = NestRequestShapes<typeof c>;
 
 @Controller()
-export class PostController implements ControllerShape {
+export class PostController implements NestControllerInterface<typeof c> {
   constructor(private readonly postService: PostService) {}
 
-  @Api(s.route.getPost)
-  async getPost(@ApiDecorator() { params: { id } }: RouteShape['getPost']) {
+  @Api(c.getPost)
+  async getPost(@TsRestRequest() { params: { id } }: RequestShapes['getPost']) {
     const post = await this.postService.getPost(id);
 
     if (!post) {
@@ -25,9 +31,17 @@ export class PostController implements ControllerShape {
 }
 ```
 
+The `nestControllerContract` filters your contract to only include immediate routes and no nested routes. Otherwise, you'd have to implement the entire contract in a single controller. As a result, it's good practice to design your contract into multiple nested contracts, one for each controller.
+
+To implement a nested contract, you can simply call `nestControllerContract(contract.nestedContract)`
+
+Having the controller class implement `NestControllerInterface` ensures that your controller implements all the routes defined in the contract. In addition, it ensures the type safety of the responses returned.
+
 The `@Api` decorator takes the route, defines the path and method for the controller route.
 
-It also injects "appRoute" into the req object, allowing the `@ApiDecorator` decorator automatically parse and check the query and body parameters.
+The `@TsRestRequest` decorator takes the contract route defined in the `@Api` decorator, and returns the parsed and validated (if using Zod) request params, query and body.
+
+As Typescript cannot infer class method parameter types from an implemented interface, we need to explicitly define the type for the request parameter using the `NestRequestShapes` type. 
 
 ## JSON Query Parameters
 
@@ -36,63 +50,61 @@ To handle JSON query parameters, you can use the `@JsonQuery()` decorator on eit
 ```typescript
 @Controller()
 @JsonQuery()
-export class PostController implements ControllerShape {}
+export class PostController implements NestControllerInterface<typeof c> {}
 ```
 
 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 {
+export class PostController implements NestControllerInterface<typeof c> {
   constructor(private readonly postService: PostService) {}
 
   @Api(s.route.getPost)
   @JsonQuery(false)
-  async getPost(@ApiDecorator() { params: { id } }: RouteShape['getPost']) {
+  async getPost(@TsRestRequest() { params: { id } }: RequestShapes['getPost']) {
     // ...
   }
 }
 ```
 
-## Response Return Type Safety
-
-You have two options to ensure HTTP type safety on your Nest Controllers:
-
-- `ControllerShape` as shown above:
-  - Your controller can implement the `ControllerShape` derived from `typeof s.controllerShape`
-  - This ensures your controller methods also align with the base interface shapes
-- `ResponseShapes`:
+## Explicit Response Type Safety
 
-  - Your controller can utilize `typeof s.responseShapes` in the return type. For example:
+In cases where you do not want to implement `NestControllerInterface`.
+Say, if you were to implement a contract's non-nested routes across multiple controllers, or use different class method names than the ones defined in your contract, you can still ensure type safety of the responses by using the `NestResponseShapes` type.
 
-    ```typescript
-    const s = initNestServer(apiBlog);
-    type ControllerShape = typeof s.controllerShape;
-    type RouteShape = typeof s.routeShapes;
-    type ResponseShapes = typeof s.responseShapes; // <- http Responses defined in contract
-
-    @Controller()
-    export class PostController {
-      constructor(private readonly postService: PostService) {}
+```typescript
+import {
+  Api,
+  nestControllerContract,
+  NestRequestShapes,
+  NestResponseShapes,
+  TsRestRequest,
+} from '@ts-rest/nest';
+
+const c = nestControllerContract(apiBlog);
+type RequestShapes = NestRequestShapes<typeof c>;
+type ResponseShapes = NestResponseShapes<typeof c>;
 
-      @Api(s.route.getPost)
-      async getPost(
-        @ApiDecorator() { params: { id } }: RouteShape['getPost']
-      ): Promise<ResponseShapes['getPost']> {
-        // <- return type defined here
-        const post = await this.postService.getPost(id);
+@Controller()
+export class PostController {
+  constructor(private readonly postService: PostService) {}
 
-        if (!post) {
-          return { status: 404, body: null };
-        }
+  @Api(c.getPost)
+  async getPost(
+    @TsRestRequest() { params: { id } }: RequestShapes['getPost']
+  ): Promise<ResponseShapes['getPost']> {
+    const post = await this.postService.getPost(id);
 
-        return { status: 200, body: post };
-      }
+    if (!post) {
+      return { status: 404 as const, body: null };
     }
-    ```
 
-  - If your controller needs to implement a difference class, or needs extra methods defined outside of a contract, this is option gives that flexibility without having to worry about maintaining class extensions.
+    return { status: 200 as const, body: post };
+  }
+}
+```
 
 :::caution
 

apps/docs/docs/quickstart.mdx

@@ -104,23 +104,22 @@ normally Nest APIs are extremely powerful, but hard to make type safe.</p>
 ```typescript
 // post.controller.ts
 
-const s = initNestServer(contract);
-type ControllerShape = typeof s.controllerShape;
-type RouteShape = typeof s.routeShapes;
+const c = nestControllerContract(apiBlog);
+type RequestShapes = NestRequestShapes<typeof c>;
 
 @Controller()
-export class PostController implements ControllerShape {
+export class PostController implements NestControllerInterface<typeof c> {
   constructor(private readonly postService: PostService) {}
 
-  @Api(s.route.getPost)
-  async getPost(@ApiDecorator() { params: { id } }: RouteShape['getPost']) {
+  @Api(c.getPost)
+  async getPost(@TsRestRequest() { params: { id } }: RequestShapes['getPost']) {
     const post = await this.postService.getPost(id);
 
     return { status: 200 as const, body: post };
   }
 
-  @Api(s.route.createPost)
-  async createPost(@ApiDecorator() { body }: RouteShape['createPost']) {
+  @Api(c.createPost)
+  async createPost(@TsRestRequest() { body }: RequestShapes['createPost']) {
     const post = await this.postService.createPost({
       title: body.title,
       body: body.body,

apps/example-microservice/users-service/src/app/app.controller.ts

@@ -1,20 +1,25 @@
 import { Controller, UploadedFile, UseInterceptors } from '@nestjs/common';
 import { usersApi } from '@ts-rest/example-microservice/util-users-api';
-import { Api, ApiDecorator, initNestServer } from '@ts-rest/nest';
+import {
+  Api,
+  TsRestRequest,
+  nestControllerContract,
+  NestControllerInterface,
+  NestRequestShapes,
+} from '@ts-rest/nest';
 import { AppService } from './app.service';
 import { FileInterceptor } from '@nestjs/platform-express';
 import 'multer';
 
-const s = initNestServer(usersApi);
-type ControllerShape = typeof s.controllerShape;
-type RouteShape = typeof s.routeShapes;
+const c = nestControllerContract(usersApi);
+type RequestShapes = NestRequestShapes<typeof c>;
 
 @Controller()
-export class AppController implements ControllerShape {
+export class AppController implements NestControllerInterface<typeof c> {
   constructor(private readonly appService: AppService) {}
 
-  @Api(s.route.getUser)
-  async getUser(@ApiDecorator() { params: { id } }: RouteShape['getUser']) {
+  @Api(c.getUser)
+  async getUser(@TsRestRequest() { params: { id } }: RequestShapes['getUser']) {
     return {
       status: 200 as const,
       body: {
@@ -25,10 +30,10 @@ export class AppController implements ControllerShape {
     };
   }
 
-  @Api(s.route.updateUserAvatar)
+  @Api(c.updateUserAvatar)
   @UseInterceptors(FileInterceptor('avatar'))
   async updateUserAvatar(
-    @ApiDecorator() { params: { id } }: RouteShape['updateUserAvatar'],
+    @TsRestRequest() { params: { id } }: RequestShapes['updateUserAvatar'],
     @UploadedFile() avatar: Express.Multer.File
   ) {
     return {

apps/example-nest/src/app/post-json-query.controller.ts

@@ -1,10 +1,17 @@
 import { Controller } from '@nestjs/common';
 import { apiBlog } from '@ts-rest/example-contracts';
-import { Api, ApiDecorator, initNestServer, JsonQuery } from '@ts-rest/nest';
+import {
+  Api,
+  TsRestRequest,
+  JsonQuery,
+  nestControllerContract,
+  NestControllerInterface,
+  NestRequestShapes,
+} from '@ts-rest/nest';
 import { z } from 'zod';
 import { PostService } from './post.service';
 
-const s = initNestServer({
+const c = nestControllerContract({
   getPosts: {
     ...apiBlog.getPosts,
     path: '/posts-json-query',
@@ -15,17 +22,19 @@ const s = initNestServer({
     }),
   },
 });
-type ControllerShape = typeof s.controllerShape;
-type RouteShape = typeof s.routeShapes;
+type RequestShapes = NestRequestShapes<typeof c>;
 
 @JsonQuery()
 @Controller()
-export class PostJsonQueryController implements ControllerShape {
+export class PostJsonQueryController
+  implements NestControllerInterface<typeof c>
+{
   constructor(private readonly postService: PostService) {}
 
-  @Api(s.route.getPosts)
+  @Api(c.getPosts)
   async getPosts(
-    @ApiDecorator() { query: { take, skip, search } }: RouteShape['getPosts']
+    @TsRestRequest()
+    { query: { take, skip, search } }: RequestShapes['getPosts']
   ) {
     const { posts, totalPosts } = await this.postService.getPosts({
       take,