@kemets/response 1.0.0

package/README.md

@@ -0,0 +1,152 @@
+# @kemet/response
+
+Standardized JSON API response helpers for Node.js backends (Express.js and compatible frameworks).
+
+Every response shares the same shape so clients can parse success and error payloads predictably.
+
+## Installation
+
+```bash
+npm install @kemet/response
+```
+
+## Response formats
+
+### Success
+
+```json
+{
+  "success": true,
+  "status": 200,
+  "message": "OK",
+  "data": {}
+}
+```
+
+### Error
+
+```json
+{
+  "success": false,
+  "status": 404,
+  "message": "Resource not found",
+  "error": {}
+}
+```
+
+## Quick start (Express)
+
+```javascript
+const express = require('express');
+const {
+  OK,
+  CREATED,
+  NOT_FOUND,
+  BAD_REQUEST,
+  VALIDATION_ERROR,
+  INTERNAL_SERVER_ERROR,
+} = require('@kemet/response');
+
+const app = express();
+app.use(express.json());
+
+app.get('/users/:id', (req, res) => {
+  const user = findUser(req.params.id);
+
+  if (!user) {
+    return NOT_FOUND(res, 'User not found');
+  }
+
+  return OK(res, user, 'User retrieved');
+});
+
+app.post('/users', (req, res) => {
+  const { error, value } = validateUser(req.body);
+
+  if (error) {
+    return VALIDATION_ERROR(res, error.details);
+  }
+
+  const user = createUser(value);
+  return CREATED(res, user, 'User created');
+});
+
+app.use((err, req, res, next) => {
+  INTERNAL_SERVER_ERROR(res, { message: err.message });
+});
+
+app.listen(3000);
+```
+
+## API reference
+
+### Success helpers
+
+| Function | Status | Description |
+|----------|--------|-------------|
+| `OK(res, data?, message?)` | 200 | Standard success response |
+| `CREATED(res, data?, message?)` | 201 | Resource created |
+
+### Error helpers
+
+| Function | Status | Description |
+|----------|--------|-------------|
+| `BAD_REQUEST(res, message?, errors?)` | 400 | Invalid client request |
+| `UNAUTHORIZED(res, message?)` | 401 | Authentication required |
+| `FORBIDDEN(res, message?)` | 403 | Access denied |
+| `NOT_FOUND(res, message?)` | 404 | Resource not found |
+| `VALIDATION_ERROR(res, errors?)` | 422 | Validation failed |
+| `TOO_MANY_REQUESTS(res, message?)` | 429 | Rate limit exceeded |
+| `INTERNAL_SERVER_ERROR(res, error?)` | 500 | Server error |
+
+Omitted `message` arguments use built-in defaults (for example, `"Resource not found"` for 404).
+
+### Builders (framework-agnostic)
+
+Use these when you are not using Express, or when you need the payload object without sending it:
+
+```javascript
+const { buildSuccessResponse, buildErrorResponse } = require('@kemet/response');
+
+const body = buildSuccessResponse(200, 'OK', { id: 1 });
+// { success: true, status: 200, message: 'OK', data: { id: 1 } }
+
+const errBody = buildErrorResponse(400, 'Invalid input', { field: 'email' });
+// { success: false, status: 400, message: 'Invalid input', error: { field: 'email' } }
+```
+
+### Constants
+
+```javascript
+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                 # Public entry point
+├── package.json
+├── README.md
+└── response/
+    ├── constants/           # Status codes and default messages
+    ├── utilities/           # Builders and senders
+    ├── success/             # 2xx helpers
+    └── error/               # 4xx / 5xx helpers
+```
+
+## Publishing to npm
+
+1. Log in: `npm login`
+2. For scoped packages, publish with public access:
+
+   ```bash
+   npm publish --access public
+   ```
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,46 @@
+'use strict';
+
+const { STATUS_CODES, DEFAULT_MESSAGES } = require('./response/constants');
+const {
+  buildSuccessResponse,
+  buildErrorResponse,
+  sendSuccess,
+  sendError,
+} = require('./response/utilities');
+const { OK, CREATED } = require('./response/success');
+const {
+  BAD_REQUEST,
+  UNAUTHORIZED,
+  FORBIDDEN,
+  NOT_FOUND,
+  VALIDATION_ERROR,
+  TOO_MANY_REQUESTS,
+  INTERNAL_SERVER_ERROR,
+} = require('./response/error');
+
+module.exports = {
+  // Success helpers
+  OK,
+  CREATED,
+
+  // Error helpers
+  BAD_REQUEST,
+  UNAUTHORIZED,
+  FORBIDDEN,
+  NOT_FOUND,
+  VALIDATION_ERROR,
+  TOO_MANY_REQUESTS,
+  INTERNAL_SERVER_ERROR,
+
+  // Response builders (use without Express)
+  buildSuccessResponse,
+  buildErrorResponse,
+
+  // Low-level senders
+  sendSuccess,
+  sendError,
+
+  // Constants
+  STATUS_CODES,
+  DEFAULT_MESSAGES,
+};

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@kemets/response",
+  "version": "1.0.0",
+  "description": "Standardized API response helpers for Express.js and Node.js backends",
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "response"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "keywords": [
+    "express",
+    "api",
+    "response",
+    "http",
+    "rest",
+    "json"
+  ],
+  "author": "",
+  "license": "MIT",
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": ""
+  }
+}

package/response/constants/index.js

@@ -0,0 +1,9 @@
+'use strict';
+
+const STATUS_CODES = require('./statusCodes');
+const DEFAULT_MESSAGES = require('./messages');
+
+module.exports = {
+  STATUS_CODES,
+  DEFAULT_MESSAGES,
+};

package/response/constants/messages.js

@@ -0,0 +1,17 @@
+'use strict';
+
+const STATUS_CODES = require('./statusCodes');
+
+const DEFAULT_MESSAGES = Object.freeze({
+  [STATUS_CODES.OK]: 'OK',
+  [STATUS_CODES.CREATED]: 'Created',
+  [STATUS_CODES.BAD_REQUEST]: 'Bad request',
+  [STATUS_CODES.UNAUTHORIZED]: 'Unauthorized',
+  [STATUS_CODES.FORBIDDEN]: 'Forbidden',
+  [STATUS_CODES.NOT_FOUND]: 'Resource not found',
+  [STATUS_CODES.VALIDATION_ERROR]: 'Validation failed',
+  [STATUS_CODES.TOO_MANY_REQUESTS]: 'Too many requests',
+  [STATUS_CODES.INTERNAL_SERVER_ERROR]: 'Internal server error',
+});
+
+module.exports = DEFAULT_MESSAGES;

package/response/constants/statusCodes.js

@@ -0,0 +1,15 @@
+'use strict';
+
+const STATUS_CODES = Object.freeze({
+  OK: 200,
+  CREATED: 201,
+  BAD_REQUEST: 400,
+  UNAUTHORIZED: 401,
+  FORBIDDEN: 403,
+  NOT_FOUND: 404,
+  VALIDATION_ERROR: 422,
+  TOO_MANY_REQUESTS: 429,
+  INTERNAL_SERVER_ERROR: 500,
+});
+
+module.exports = STATUS_CODES;

package/response/error/index.js

@@ -0,0 +1,85 @@
+'use strict';
+
+const { STATUS_CODES } = require('../constants');
+const { sendError } = require('../utilities');
+
+/**
+ * 400 Bad Request — client sent an invalid request.
+ *
+ * @param {import('express').Response} res
+ * @param {string} [message]
+ * @param {*} [errors]
+ */
+function BAD_REQUEST(res, message, errors) {
+  return sendError(res, STATUS_CODES.BAD_REQUEST, message, errors);
+}
+
+/**
+ * 401 Unauthorized — authentication is required or failed.
+ *
+ * @param {import('express').Response} res
+ * @param {string} [message]
+ */
+function UNAUTHORIZED(res, message) {
+  return sendError(res, STATUS_CODES.UNAUTHORIZED, message);
+}
+
+/**
+ * 403 Forbidden — authenticated but not permitted.
+ *
+ * @param {import('express').Response} res
+ * @param {string} [message]
+ */
+function FORBIDDEN(res, message) {
+  return sendError(res, STATUS_CODES.FORBIDDEN, message);
+}
+
+/**
+ * 404 Not Found — requested resource does not exist.
+ *
+ * @param {import('express').Response} res
+ * @param {string} [message]
+ */
+function NOT_FOUND(res, message) {
+  return sendError(res, STATUS_CODES.NOT_FOUND, message);
+}
+
+/**
+ * 422 Validation Error — request body or params failed validation.
+ *
+ * @param {import('express').Response} res
+ * @param {*} [errors]
+ */
+function VALIDATION_ERROR(res, errors) {
+  return sendError(res, STATUS_CODES.VALIDATION_ERROR, undefined, errors);
+}
+
+/**
+ * 429 Too Many Requests — rate limit exceeded.
+ *
+ * @param {import('express').Response} res
+ * @param {string} [message]
+ */
+function TOO_MANY_REQUESTS(res, message) {
+  return sendError(res, STATUS_CODES.TOO_MANY_REQUESTS, message);
+}
+
+/**
+ * 500 Internal Server Error — unexpected server failure.
+ *
+ * @param {import('express').Response} res
+ * @param {*} [error]
+ */
+function INTERNAL_SERVER_ERROR(res, error) {
+  return sendError(res, STATUS_CODES.INTERNAL_SERVER_ERROR, undefined, error);
+}
+
+module.exports = {
+  BAD_REQUEST,
+  UNAUTHORIZED,
+  FORBIDDEN,
+  NOT_FOUND,
+  VALIDATION_ERROR,
+  TOO_MANY_REQUESTS,
+  INTERNAL_SERVER_ERROR,
+};

package/response/success/index.js

@@ -0,0 +1,31 @@
+'use strict';
+
+const { STATUS_CODES } = require('../constants');
+const { sendSuccess } = require('../utilities');
+
+/**
+ * 200 OK — successful request with optional data payload.
+ *
+ * @param {import('express').Response} res
+ * @param {*} [data]
+ * @param {string} [message]
+ */
+function OK(res, data, message) {
+  return sendSuccess(res, STATUS_CODES.OK, data, message);
+}
+
+/**
+ * 201 Created — resource successfully created.
+ *
+ * @param {import('express').Response} res
+ * @param {*} [data]
+ * @param {string} [message]
+ */
+function CREATED(res, data, message) {
+  return sendSuccess(res, STATUS_CODES.CREATED, data, message);
+}
+
+module.exports = {
+  OK,
+  CREATED,
+};

package/response/utilities/builder.js

@@ -0,0 +1,42 @@
+'use strict';
+
+const { DEFAULT_MESSAGES } = require('../constants');
+
+/**
+ * Builds a standardized success response payload.
+ *
+ * @param {number} status - HTTP status code
+ * @param {string} [message] - Human-readable message
+ * @param {*} [data] - Response payload
+ * @returns {object}
+ */
+function buildSuccessResponse(status, message, data) {
+  return {
+    success: true,
+    status,
+    message: message ?? DEFAULT_MESSAGES[status] ?? 'OK',
+    data: data !== undefined && data !== null ? data : {},
+  };
+}
+
+/**
+ * Builds a standardized error response payload.
+ *
+ * @param {number} status - HTTP status code
+ * @param {string} [message] - Human-readable message
+ * @param {*} [error] - Error details (validation errors, stack info, etc.)
+ * @returns {object}
+ */
+function buildErrorResponse(status, message, error) {
+  return {
+    success: false,
+    status,
+    message: message ?? DEFAULT_MESSAGES[status] ?? 'Error',
+    error: error !== undefined && error !== null ? error : {},
+  };
+}
+
+module.exports = {
+  buildSuccessResponse,
+  buildErrorResponse,
+};

package/response/utilities/index.js

@@ -0,0 +1,11 @@
+'use strict';
+
+const { buildSuccessResponse, buildErrorResponse } = require('./builder');
+const { sendSuccess, sendError } = require('./sender');
+
+module.exports = {
+  buildSuccessResponse,
+  buildErrorResponse,
+  sendSuccess,
+  sendError,
+};

package/response/utilities/sender.js

@@ -0,0 +1,36 @@
+'use strict';
+
+const { buildSuccessResponse, buildErrorResponse } = require('./builder');
+
+/**
+ * Sends a standardized success JSON response.
+ *
+ * @param {import('express').Response} res - Express response object
+ * @param {number} status - HTTP status code
+ * @param {*} [data] - Response payload
+ * @param {string} [message] - Human-readable message
+ * @returns {import('express').Response}
+ */
+function sendSuccess(res, status, data, message) {
+  const payload = buildSuccessResponse(status, message, data);
+  return res.status(status).json(payload);
+}
+
+/**
+ * Sends a standardized error JSON response.
+ *
+ * @param {import('express').Response} res - Express response object
+ * @param {number} status - HTTP status code
+ * @param {string} [message] - Human-readable message
+ * @param {*} [error] - Error details
+ * @returns {import('express').Response}
+ */
+function sendError(res, status, message, error) {
+  const payload = buildErrorResponse(status, message, error);
+  return res.status(status).json(payload);
+}
+
+module.exports = {
+  sendSuccess,
+  sendError,
+};