HTTP Status Code Response Library

A comprehensive TypeScript library for standardizing HTTP responses in Express.js applications with proper status codes and consistent response formats.

🚀 Quick Start — Step by Step

1) Install

npm install response-standardizes

2) Import and initialize

import express from 'express';
import { 
  ResponseSuccess,
  ResponseCreated,
  ResponseNoContent,
  ResponseBadRequest,
  ResponseUnauthorized,
  ResponseNotFound,
  ResponseInternalServerError,
  ResponseMovedPermanently,
  ResponseFound,
  ResponseProcessing,
  createAppLogger
} from 'your-package-name';

const app = express();
const logger = createAppLogger();

app.use(express.json());

3) (Optional) Log each request with Winston

app.use((req, _res, next) => {
  logger.info({ method: req.method, url: req.url });
  next();
});

4) Add success endpoints (2xx)

// 200 OK
app.get('/api/data', (req, res) => {
  const data = { message: 'Hello World' };
  return ResponseSuccess(res, 'Data retrieved successfully', data);
});

// 201 Created
app.post('/api/users', (req, res) => {
  const newUser = { id: 1, name: req.body.name };
  return ResponseCreated(res, 'User created successfully', newUser);
});

// 204 No Content
app.delete('/api/users/:id', (req, res) => {
  // delete logic
  return ResponseNoContent(res, 'User deleted successfully');
});

5) Add client error endpoints (4xx)

// 400 Bad Request
app.post('/api/validate', (req, res) => {
  if (!req.body.email) {
    return ResponseBadRequest(res, 'Email is required');
  }
  return ResponseSuccess(res, 'Valid payload');
});

// 401 Unauthorized
app.get('/api/protected', (req, res) => {
  if (!req.headers.authorization) {
    return ResponseUnauthorized(res, 'Authentication required');
  }
  return ResponseSuccess(res, 'Authorized');
});

// 404 Not Found
app.get('/api/users/:id', (req, res) => {
  const user = undefined; // replace with lookup
  if (!user) {
    return ResponseNotFound(res, 'User not found');
  }
  return ResponseSuccess(res, 'User found', user);
});

6) Add server error handling (5xx)

app.get('/api/risky-operation', (req, res) => {
  try {
    // riskyOperation();
    return ResponseSuccess(res, 'Operation completed');
  } catch (error) {
    logger.error('Risky operation failed', error);
    return ResponseInternalServerError(res, 'Something went wrong');
  }
});

7) Add redirections (3xx)

// 301 Moved Permanently
app.get('/old-endpoint', (req, res) => {
  return ResponseMovedPermanently(res, 'This resource has moved', { newLocation: '/new-endpoint' });
});

// 302 Found (Temporary)
app.get('/temp-redirect', (req, res) => {
  return ResponseFound(res, 'Temporarily redirected', { redirectTo: '/alternative-endpoint' });
});

8) (Optional) Informational responses (1xx)

// 102 Processing
app.post('/api/long-operation', (req, res) => {
  ResponseProcessing(res, 'Request is being processed');
  // continue in background (e.g., queue / worker / websocket updates)
});

9) Consistent response format

Success

{
  "success": true,
  "message": "Request was successful",
  "data": { "id": 1, "name": "Example" }
}

Error

{
  "success": false,
  "message": "Resource not found",
  "data": null
}

10) Customize default messages

ResponseSuccess(res, 'Custom success message', data);
ResponseNotFound(res, 'We looked everywhere but could not find it');

11) Test without a real Express res

// Example Jest test
test('should return success response', () => {
  const response = ResponseSuccess(null, 'Test message', { id: 1 });
  expect(response.success).toBe(true);
  expect(response.message).toBe('Test message');
  expect(response.data.id).toBe(1);
});

12) Start the server

app.listen(3000, () => {
  logger.info('Server running on http://localhost:3000');
});

📚 API Reference (by status class)

1xx — Informational

• ResponseContinue(res, message, data)
• ResponseSwitchingProtocols(res, message, data)
• ResponseProcessing(res, message, data)
• ResponseEarlyHints(res, message, data)

2xx — Success

• ResponseSuccess(res, message, data) — 200 OK
• ResponseCreated(res, message, data) — 201 Created
• ResponseAccepted(res, message, data) — 202 Accepted
• ResponseNonAuthoritativeInformation(res, message, data) — 203
• ResponseNoContent(res, message, data) — 204 No Content
• ResponseResetContent(res, message, data) — 205
• ResponsePartialContent(res, message, data) — 206

3xx — Redirection

• ResponseMultipleChoices(res, message, data) — 300
• ResponseMovedPermanently(res, message, data) — 301
• ResponseFound(res, message, data) — 302
• ResponseSeeOther(res, message, data) — 303
• ResponseNotModified(res, message, data) — 304
• ResponseTemporaryRedirect(res, message, data) — 307
• ResponsePermanentRedirect(res, message, data) — 308

4xx — Client Errors

• ResponseBadRequest(res, message, data) — 400
• ResponseUnauthorized(res, message, data) — 401
• ResponsePaymentRequired(res, message, data) — 402
• ResponseForbidden(res, message, data) — 403
• ResponseNotFound(res, message, data) — 404
• ResponseMethodNotAllowed(res, message, data) — 405
• ResponseNotAcceptable(res, message, data) — 406
• ResponseProxyAuthenticationRequired(res, message, data) — 407
• ResponseRequestTimeout(res, message, data) — 408
• ResponseConflict(res, message, data) — 409
• ResponseGone(res, message, data) — 410
• ResponseLengthRequired(res, message, data) — 411
• ResponsePreconditionFailed(res, message, data) — 412
• ResponsePayloadTooLarge(res, message, data) — 413
• ResponseUriTooLong(res, message, data) — 414
• ResponseUnsupportedMediaType(res, message, data) — 415
• ResponseRangeNotSatisfiable(res, message, data) — 416
• ResponseExpectationFailed(res, message, data) — 417
• ResponseImATeapot(res, message, data) — 418
• ResponseUnprocessableEntity(res, message, data) — 422
• ResponseTooManyRequests(res, message, data) — 429

5xx — Server Errors

• ResponseInternalServerError(res, message, data) — 500
• ResponseNotImplemented(res, message, data) — 501
• ResponseBadGateway(res, message, data) — 502
• ResponseServiceUnavailable(res, message, data) — 503
• ResponseGatewayTimeout(res, message, data) — 504
• ResponseHttpVersionNotSupported(res, message, data) — 505

🧭 Error Handling Best Practices

• Always return the response function result

  return ResponseNotFound(res, 'User not found');

• Use the most appropriate status code for the scenario

• Log errors with the provided logger and avoid leaking sensitive details

  try { /* risky work */ } catch (error) {
    logger.error('Operation failed', error);
    return ResponseInternalServerError(res, 'Operation failed');
  }

📝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

📄 License

MIT License — see LICENSE for details.