nestjs-border

Note: The project is in early development. Breaking changes may occur.

Description

A NestJS module for validating and documenting your controllers using Zod.

Features

• Automatic Validation: Validate request parameters, query strings, and bodies using Zod schemas.
• OpenAPI Documentation: Automatically generates OpenAPI documentation for your endpoints.
• Easy Integration: Seamlessly integrates with NestJS controllers and decorators like Body(), Param(), and Query().
• Type Safety: Ensures type safe access to validated data using the InferFromBorder utility type.

Installation

The package depends on zod and @nestjs/swagger. Make sure to install them if you don not have them installed in your project already. Then install nestjs-border:

npm install zod @nestjs/swagger nestjs-border

The package has not been tested with Zod v4, so it is not officially supported yet, but it will probably still work.

Usage

For basic usage, no module imports are necessary. Simply define a Border and use it:

import { Controller, Post, Body, HttpStatus } from "@nestjs/common";
import { Border, UseBorder, type InferFromBorder } from "nestjs-border";
import { z } from "zod";

const BORDER = new Border({
  requestBody: z.object({
    name: z.string().min(2).max(100),
    age: z.number().min(0).max(120),
  }),
  responses: {
    [HttpStatus.CREATED]: z.object({
      id: z.string().uuid(),
      name: z.string(),
      age: z.number(),
    }),
  },
});

@Controller("users")
export class UsersController {
  @Post()
  @UseBorder(BORDER)
  createUser(@Body() body: InferFromBorder<typeof border, "body">) {
    const { name, age } = body; // { name: string; age: number; }

    // Type-safe return value depending on the defined responses
    return BORDER.createResponse(HttpStatus.CREATED, {
      id: "some-uuid",
      name,
      age,
    });
  }
}

Roadmap

• Support for additional request parts e.g., headers, cookies.
• File upload (and possibly response) validation.
• More customization options for OpenAPI documentation.
• Customizable default response format (e.g., wrapping all responses in a standard structure).
• Custom error handling strategies (e.g., logging, custom error responses).

License

This project is licensed under the MIT License - see the LICENSE file for details.