@ltvn/http-response-builder NPM

HTTP Response Builder

A TypeScript library for building consistent HTTP responses with support for custom status codes.

Features

Builder pattern for constructing HTTP responses
Type-safe response data handling with generics
Built-in pagination support
Metadata support for additional response information
Comprehensive HTTP status codes and messages
Fluent interface for method chaining

Installation

npm install @ltvn/http-response-builder
# or
yarn add @ltvn/http-response-builder

Usage

Basic Usage

import { HttpResponseBuilder } from '@ltvn/http-response-builder';

// Create a success response
const response = HttpResponseBuilder
    .ok()
    .setData({ message: 'Hello World' })
    .build();

// Result:
// {
//     status: 200,
//     message: "OK",
//     data: { message: "Hello World" }
// }

With Pagination

import { HttpResponseBuilder, Paging } from '@ltvn/http-response-builder';

const response = HttpResponseBuilder
    .ok()
    .setData([/* your data */])
    .setPaging(new Paging(1, 10, 100))
    .build();

// Result:
// {
//     status: 200,
//     message: "OK",
//     data: [/* your data */],
//     paging: {
//         page: 1,
//         size: 10,
//         total: 100
//     }
// }

With Metadata

const response = HttpResponseBuilder
    .ok()
    .setData({/* your data */})
    .setMetadata({
        timestamp: new Date().toISOString(),
        version: '1.0.0'
    })
    .build();

// Result:
// {
//     status: 200,
//     message: "OK",
//     data: {/* your data */},
//     metadata: {
//         timestamp: "2024-03-14T12:00:00.000Z",
//         version: "1.0.0"
//     }
// }

Custom Response

const response = HttpResponseBuilder
    .customResponse()
    .setStatus(418)  // I'm a teapot
    .setMessage("Custom message")
    .setData({ message: "Hello World" })
    .build();

Response Format

All responses follow this format:

{
    status: number;      // HTTP status code
    message: string;     // Status message
    data?: T;           // Response data (generic type)
    paging?: {          // Optional pagination info
        page: number;
        size: number;
        total: number;
    };
    metadata?: Record<string, any>;  // Optional additional metadata
}

Available Status Codes

Standard HTTP Status Codes (100-599)

1xx: Information
2xx: Success
3xx: Redirection
4xx: Client Error
5xx: Server Error

Custom Status Codes (>=4000)

4000: SUCCESS
4001: INVALID_MAIL_FORMAT
4002: ACCOUNTALREADY
4003: EMAIL_ALREADY_EXISTS
4004: USER_NOT_FOUND
4005: WRONG_PASS
4006: EMAIL_TIMEOUT
4007: AUTHEN_NOT_MATCH
4008: INVALID_EMAIL

Usage with NestJS

Controller Example

import { Controller, Get } from '@nestjs/common';
import { HttpResponseBuilder, Paging } from '@ltvn/http-response-builder';

interface UserDTO {
  id: number;
  name: string;
  email: string;
}

@Controller('users')
export class UsersController {
  @Get()
  async getUsers() {
    const users: UserDTO[] = [
      { id: 1, name: 'John Doe', email: 'john@example.com' },
      { id: 2, name: 'Jane Doe', email: 'jane@example.com' }
    ];

    const totalUsers = users.length;
    const paging = new Paging(1, 10, totalUsers);

    return HttpResponseBuilder.ok<UserDTO[]>()
      .setData(users)
      .setPaging(paging)
      .setMetadata({ timestamp: new Date() })
      .build();
  }

  @Get(':id')
  async getUser() {
    const user: UserDTO = { 
      id: 1, 
      name: 'John Doe', 
      email: 'john@example.com' 
    };

    return HttpResponseBuilder.ok<UserDTO>()
      .setData(user)
      .build();
  }
}

Usage with Express

Route Handler Example

import express from "express";
import { HttpResponseBuilder } from "@ltvn/http-response-builder";

const app = express();

app.get("/api/photo/list", function (req, res) {
  const photoList = [
    {
      id: "001",
      name: "photo001.jpg",
      type: "jpg",
      dataUrl: "http://localhost:3000/data/photo001.jpg",
    },
    {
      id: "002",
      name: "photo002.jpg",
      type: "jpg",
      dataUrl: "http://localhost:3000/data/photo002.jpg",
    },
  ];

  const response = HttpResponseBuilder.ok()
    .setData(photoList)
    .setMessage("Get photo list")
    .build();
    
  res.json(response);
});

const server = app.listen(3000, () => {
  console.log("Server is running on port 3000");
});

Error Handling

The builder includes validation and will throw TypeError for invalid inputs:

Invalid status codes (must be between 100 and 599, or >= 4000 for custom codes)
Invalid message types (must be string)
Invalid paging instance
Invalid metadata type (must be a non-null object)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

References

This project was inspired by and built upon the work of @anot/http-response-builder. We would like to acknowledge their contribution to the open-source community.