🚀 API Response Handler

A lightweight, highly robust, and standardized API response handler for Node.js and Express applications. It effortlessly guarantees a clean, consistent, and predictable response structure across your entire API architecture.

✨ Features

• 💎 Standardized Format: Uniform success, error, and paginated responses.
• ⚡ Lightweight & Fast: Zero external runtime dependencies.
• 📈 Smart Pagination: Built-in calculation for pages, limits, total items, and next/prev status indicators.
• 🛡️ TypeScript Ready: Full type definitions out of the box with IApiResponse.
• 🎛️ Extremely Flexible: Custom metadata and dynamic error payloads supported.

⚙️ Requirements

• Runtime: Node.js >= 12.0.0 (Works in almost any modern Node environment)
• Development & Testing: Node.js >= 18.0.0 (Required for the native node:test suite)

📦 Installation

Install the package via your favorite package manager:

# Using npm
npm install standard-api-response-handler

# Using yarn
yarn add standard-api-response-handler

# Using pnpm
pnpm add standard-api-response-handler

🛠️ Quick Start & Usage

1. Standard Success Response

Quickly send successful responses with data, optional custom messages, and custom HTTP status codes (defaults to 200).

const ApiResponse = require('standard-api-response-handler').default;

app.get('/api/users/:id', async (req, res) => {
  const user = { id: 42, username: 'dev_hero' };
  
  // Sends a standard 200 OK response
  return ApiResponse.success(res, user, 'User profile fetched successfully');
});

Response Payload:

{
  "success": true,
  "status": 200,
  "message": "User profile fetched successfully",
  "data": {
    "id": 42,
    "username": "dev_hero"
  }
}

2. Robust Error Response

Consistently catch and format error responses. Supports custom HTTP status codes (defaults to 500) and optional validation/error payload arrays.

const ApiResponse = require('standard-api-response-handler').default;

app.post('/api/register', (req, res) => {
  const errors = { email: 'Email address is invalid' };
  
  // Sends a standard 400 Bad Request with details
  return ApiResponse.error(res, 'Validation failed', 400, errors);
});

Response Payload:

{
  "success": false,
  "status": 400,
  "message": "Validation failed",
  "errors": {
    "email": "Email address is invalid"
  }
}

3. Created Response (201)

Quickly send standard 201 Created responses when a new resource is successfully created.

const ApiResponse = require('standard-api-response-handler').default;

app.post('/api/users', async (req, res) => {
  const newUser = { id: 43, username: 'new_coder' };
  
  // Sends a standard 201 Created response
  return ApiResponse.created(res, newUser, 'User created successfully');
});

Response Payload:

{
  "success": true,
  "status": 201,
  "message": "User created successfully",
  "data": {
    "id": 43,
    "username": "new_coder"
  }
}

4. Not Found Response (404)

Quickly send standard 404 Not Found responses when a requested resource is not found.

const ApiResponse = require('standard-api-response-handler').default;

app.get('/api/users/:id', async (req, res) => {
  // If user is not found in database
  return ApiResponse.notFound(res, 'User not found');
});

Response Payload:

{
  "success": false,
  "status": 404,
  "message": "User not found"
}

5. Smart Paginated Response

Pass your raw data array and pagination metrics, and let the handler auto-calculate all structural parameters (total pages, current page, limits, and next/prev page flags).

const ApiResponse = require('standard-api-response-handler').default;

app.get('/api/products', async (req, res) => {
  const page = parseInt(req.query.page) || 1;
  const limit = parseInt(req.query.limit) || 10;
  
  const { products, totalCount } = await db.products.findAndCount({ page, limit });
  
  // Auto-calculates metadata and sends pagination
  return ApiResponse.paginate(res, products, page, limit, totalCount, 'Products retrieved successfully');
});

Response Payload:

{
  "success": true,
  "status": 200,
  "message": "Products retrieved successfully",
  "data": [
    { "id": 1, "name": "Premium Keyboard" },
    { "id": 2, "name": "Ergonomic Mouse" }
  ],
  "meta": {
    "currentPage": 1,
    "itemsPerPage": 10,
    "totalItems": 45,
    "totalPages": 5,
    "hasNextPage": true,
    "hasPrevPage": false
  }
}

6. 🦕 TypeScript Usage

Fully compatible with TypeScript projects out-of-the-box. Import the helper class and leverage standard typings.

import ApiResponse, { IApiResponse } from 'standard-api-response-handler';
import { Request, Response } from 'express';

interface User {
  id: number;
  email: string;
}

export const getUserProfile = (req: Request, res: Response) => {
  const user: User = { id: 1, email: '[email protected]' };
  
  // Fully typed method signatures
  return ApiResponse.success(res, user, 'Profile loaded');
};

📖 API Reference

ApiResponse.success(res, data, message, statusCode, meta)

| Parameter | Type | Required | Default | Description | | :--- | :--- | :---: | :---: | :--- | | res | Response | Yes | — | Express-like Response Object | | data | any | No | null | The actual payload data to return | | message | string | No | 'Success' | User-friendly message for feedback | | statusCode | number | No | 200 | HTTP Status Code to return | | meta | any | No | null | Optional custom metadata object |

ApiResponse.error(res, message, statusCode, errors)

| Parameter | Type | Required | Default | Description | | :--- | :--- | :---: | :---: | :--- | | res | Response | Yes | — | Express-like Response Object | | message | string | No | 'Internal Server Error' | Human-readable error description | | statusCode | number | No | 500 | HTTP Status Code to return | | errors | any | No | null | Detailed validation errors or system debug errors |

ApiResponse.paginate(res, data, page, limit, totalItems, message)

| Parameter | Type | Required | Default | Description | | :--- | :--- | :---: | :---: | :--- | | res | Response | Yes | — | Express-like Response Object | | data | any[] | Yes | — | Array of items for the current page | | page | number | Yes | — | Active page index (1-based) | | limit | number | Yes | — | Number of items per page | | totalItems | number | Yes | — | Total item count matching the query in database | | message | string | No | 'Data retrieved successfully' | Summary success description |

💡 Specialized Status Code Helper Methods

For cleaner, more semantic code, the library provides helper methods for common HTTP status codes.

Success Responses (2xx)

• ApiResponse.created(res, data, message, meta) (201 Created)
• ApiResponse.accepted(res, data, message, meta) (202 Accepted)
• ApiResponse.noContent(res) (204 No Content - returns no response body)

Usage Example:

// Send a 201 Created response
ApiResponse.created(res, { id: 42 }, 'Resource created successfully');

// Send a 204 No Content response
ApiResponse.noContent(res);

Client Error Responses (4xx)

• ApiResponse.badRequest(res, message, errors) (400 Bad Request)
• ApiResponse.unauthorized(res, message, errors) (401 Unauthorized)
• ApiResponse.forbidden(res, message, errors) (403 Forbidden)
• ApiResponse.notFound(res, message, errors) (404 Not Found)
• ApiResponse.methodNotAllowed(res, message, errors) (405 Method Not Allowed)
• ApiResponse.conflict(res, message, errors) (409 Conflict)
• ApiResponse.unprocessableEntity(res, message, errors) (422 Unprocessable Entity)
• ApiResponse.tooManyRequests(res, message, errors) (429 Too Many Requests)

Usage Example:

// Send a 403 Forbidden response
ApiResponse.forbidden(res, 'You do not have access to this resource');

// Send a 422 Unprocessable Entity response with details
ApiResponse.unprocessableEntity(res, 'Validation failed', { email: 'Email already exists' });

Server Error Responses (5xx)

• ApiResponse.internalServerError(res, message, errors) (500 Internal Server Error)
• ApiResponse.notImplemented(res, message, errors) (501 Not Implemented)
• ApiResponse.badGateway(res, message, errors) (502 Bad Gateway)
• ApiResponse.serviceUnavailable(res, message, errors) (503 Service Unavailable)
• ApiResponse.gatewayTimeout(res, message, errors) (504 Gateway Timeout)

Usage Example:

// Send a 503 Service Unavailable response
ApiResponse.serviceUnavailable(res, 'Database connection lost', databaseError);

🪪 License

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