JSend Middleware for Express

JSend Middleware is a lightweight utility for Express.js applications that implements the JSend specification to standardize JSON API responses. It provides a simple, consistent way to send success, fail, and error responses with customizable status labels and robust input validation.

Features

Standardized Responses: Adheres to the JSend specification with success, fail, and error response types.
Customizable Status Labels: Allows custom status labels for flexible API designs.
Input Validation: Ensures data is JSON-serializable and error messages are non-empty strings.
Type Safety: Includes JSDoc annotations for TypeScript compatibility and better IDE support.
Express Integration: Seamlessly integrates as middleware, attaching a Jsend instance to the Express response object.
Error Handling: Validates the Express response object and input parameters to prevent runtime errors.

Installation

Install the package via npm:

npm install jsend-middleware

Ensure you have Express.js installed in your project:

npm install express

Usage

Setup

Add the jsendMiddleware to your Express application:

import express from "express";
import jsendMiddleware from "jsend-middleware";

const app = express();

// Apply JSend middleware
app.use(jsendMiddleware());

app.get("/example", (req, res) => {
  res.jsend.success({ message: "Hello, World!" });
});

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

Response Types

The middleware attaches a jsend object to the Express res object, providing three methods:

1. Success Response

Used for successful requests.

res.jsend.success({ user: { id: 1, name: "John Doe" } });
// Response:
// {
//   "status": "success",
//   "data": { "user": { "id": 1, "name": "John Doe" } }
// }

With custom status label and HTTP code:

res.jsend.success({ user: { id: 1, name: "John Doe" } }, 201, "ok");
// Response:
// {
//   "status": "ok",
//   "data": { "user": { "id": 1, "name": "John Doe" } }
// }

2. Fail Response

Used for client-side errors (e.g., invalid input).

res.jsend.fail({ error: "Invalid email format" }, 400);
// Response:
// {
//   "status": "fail",
//   "data": { "error": "Invalid email format" }
// }

3. Error Response

Used for server-side or unexpected errors.

res.jsend.error("Database connection failed", 500, {
  code: "DB_ERROR",
  details: { retryAfter: 60 },
  extra: { traceId: "abc123" },
});
// Response:
// {
//   "status": "error",
//   "message": "Database connection failed",
//   "code": "DB_ERROR",
//   "details": { "retryAfter": 60 },
//   "extra": { "traceId": "abc123" }
// }

Configuration

The middleware supports configuration for default status labels:

app.use(
  jsendMiddleware({
    successLabel: "ok",
    failLabel: "invalid",
    errorLabel: "exception",
  })
);

// Example success response with configured label
res.jsend.success({ message: "Configured!" });
// Response:
// {
//   "status": "ok",
//   "data": { "message": "Configured!" }
// }

API Reference

Jsend Class

Constructor

new Jsend(res);

res: Express response object (required).
Throws an error if res is not a valid Express response object.

Methods

success(data, status, statusLabel)
- data: Optional object or null (default: null).
- status: HTTP status code (default: 200).
- statusLabel: Custom status label (default: "success").
- Throws an error if data is not JSON-serializable.
fail(data, status, statusLabel)
- data: Optional object or null (default: null).
- status: HTTP status code (default: 400).
- statusLabel: Custom status label (default: "fail").
- Throws an error if data is not JSON-serializable.
error(message, status, options, statusLabel)
- message: Error message (default: "Internal Server Error").
- status: HTTP status code (default: 500).
- options: Optional object with code, details, and extra fields.
- statusLabel: Custom status label (default: "error").
- Throws an error if message is not a non-empty string or options.extra is not an object.