@kemet/response

Standardized JSON API response helpers for Express.js. Middleware injects typed helpers onto each res object — no global prototype patching.

Every response shares the same shape so clients can parse success and error payloads predictably.

Installation

npm install @kemet/response express

Response formats

Success

{
  "success": true,
  "status": 200,
  "message": "OK",
  "data": {}
}

Error

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

Quick start

const express = require('express');
const kemetResponse = require('@kemet/response');

const app = express();

app.use(express.json());
app.use(kemetResponse());

app.get('/users/:id', (req, res) => {
  const user = findUser(req.params.id);

  if (!user) {
    return res.NOT_FOUND('User not found');
  }

  return res.OK(user, 'User retrieved successfully');
});

app.post('/users', (req, res) => {
  const { error, value } = validateUser(req.body);

  if (error) {
    return res.VALIDATION_ERROR(error.details);
  }

  const user = createUser(value);
  return res.CREATED(user, 'User created');
});

app.use((err, req, res, next) => {
  if (typeof res.INTERNAL_SERVER_ERROR === 'function') {
    return res.INTERNAL_SERVER_ERROR({ message: err.message });
  }
  next(err);
});

app.listen(3000);

How it works

kemetResponse() registers middleware that binds helpers to each request’s res object with .bind(res). Express’s shared Response prototype is never modified, so other apps and libraries stay isolated.

Helpers are attached once per response (idempotent if middleware runs again).

API reference

Middleware

| Export | Description | |--------|-------------| | kemetResponse() | Default export — returns Express middleware | | attachResponseMethods(res) | Manually attach helpers (tests, custom stacks) |

res methods

Success

| Method | Status | Signature | |--------|--------|-----------| | res.OK() | 200 | (data?, message?) | | res.CREATED() | 201 | (data?, message?) |

Error

| Method | Status | Signature | |--------|--------|-----------| | res.BAD_REQUEST() | 400 | (message?, errors?) | | res.UNAUTHORIZED() | 401 | (message?) | | res.FORBIDDEN() | 403 | (message?) | | res.NOT_FOUND() | 404 | (message?) | | res.VALIDATION_ERROR() | 422 | (errors?) | | res.TOO_MANY_REQUESTS() | 429 | (message?) | | res.INTERNAL_SERVER_ERROR() | 500 | (error?) |

Omitted message arguments use built-in defaults (for example, "Resource not found" for 404).

Builders (framework-agnostic)

const { buildSuccessResponse, buildErrorResponse } = require('@kemet/response');

const body = buildSuccessResponse(200, 'OK', { id: 1 });
const errBody = buildErrorResponse(400, 'Invalid input', { field: 'email' });

Constants

const { STATUS_CODES, DEFAULT_MESSAGES } = require('@kemet/response');

console.log(STATUS_CODES.NOT_FOUND); // 404
console.log(DEFAULT_MESSAGES[404]);  // 'Resource not found'

Project structure

.
├── index.js
├── package.json
├── README.md
└── response/
    ├── constants/
    ├── utilities/
    ├── success/             # 2xx res.* methods
    ├── error/               # 4xx / 5xx res.* methods
    ├── methods/             # Merged method registry
    └── middleware/          # kemetResponse() + attach helper

Publishing to npm

npm login
npm publish --access public

License

MIT