response-kit 1.0.0 → 2.0.0

package/package.json

@@ -1,51 +1,67 @@
-{
-"name": "response-kit",
-"version": "1.0.0",
-"description": "Standardized API response utility for Node.js and Express.js",
-"main": "./src/index.js",
-"types": "./index.d.ts",
-"exports": {
-".": {
-"require": "./src/index.js",
-"import": "./src/index.js",
-"types": "./index.d.ts"
-}
-},
-"files": [
-"src",
-"docs",
-"index.d.ts",
-"README.md",
-"LICENSE"
-],
-"scripts": {
-"lint": "eslint .",
-"format": "prettier --write ."
-},
-"keywords": [
-"express",
-"nodejs",
-"api",
-"response",
-"response-helper",
-"api-response",
-"backend"
-],
-"author": "Piyush Yadav",
-"license": "MIT",
-"type": "commonjs",
-"repository": {
-"type": "git",
-"url": "git+https://github.com/piyush72yaduvanshi/api-response-kit.git"
-},
-"bugs": {
-"url": "https://github.com/piyush72yaduvanshi/api-response-kit/issues"
-},
-"homepage": "https://github.com/piyush72yaduvanshi/api-response-kit#readme",
-"devDependencies": {
-"eslint": "^10.5.0",
-"jest": "^30.4.2",
-"prettier": "^3.8.4",
-"typescript": "^6.0.3"
-}
-}
+{
+"name": "response-kit",
+"version": "2.0.0",
+"description": "Production-grade API response utility for Node.js and Express.js with middleware support, global configuration, and async handlers",
+"main": "./src/index.js",
+"types": "./index.d.ts",
+"exports": {
+".": {
+"require": "./src/index.js",
+"import": "./src/index.js",
+"types": "./index.d.ts"
+}
+},
+"files": [
+"src",
+"docs",
+"index.d.ts",
+"README.md",
+"LICENSE"
+],
+"scripts": {
+"lint": "eslint .",
+"format": "prettier --write .",
+"test:ts": "tsc -p tsconfig.json"
+},
+"keywords": [
+"express",
+"nodejs",
+"api",
+"response",
+"response-helper",
+"api-response",
+"backend",
+"middleware",
+"async-handler",
+"express-middleware",
+"response-kit",
+"error-handler"
+],
+"author": "Piyush Yadav",
+"license": "MIT",
+"type": "commonjs",
+"repository": {
+"type": "git",
+"url": "git+https://github.com/piyush72yaduvanshi/api-response-kit.git"
+},
+"bugs": {
+"url": "https://github.com/piyush72yaduvanshi/api-response-kit/issues"
+},
+"homepage": "https://github.com/piyush72yaduvanshi/api-response-kit#readme",
+"peerDependencies": {
+"express": ">=4.0.0"
+},
+"peerDependenciesMeta": {
+"express": {
+"optional": true
+}
+},
+"devDependencies": {
+    "@types/express": "^4.17.25",
+    "@types/node": "^20.14.5",
+    "express": "^4.21.2",
+    "jest": "^30.4.2",
+    "prettier": "^3.8.4",
+    "typescript": "^6.0.3"
+}
+}

package/src/core/config.js

@@ -0,0 +1,94 @@
+class Config {
+  constructor() {
+    this.settings = {
+      successKey: 'success',
+      dataKey: 'data',
+      messageKey: 'message',
+      errorKey: 'errors',
+      includeTimestamp: false,
+      includeRequestId: false,
+      includeMeta: false,
+      timestampKey: 'timestamp',
+      requestIdKey: 'requestId',
+      metaKey: 'meta',
+    };
+  }
+
+  /**
+   * Configure global settings
+   * @param {Object} options - Configuration options
+   */
+  configure(options = {}) {
+    this.settings = {
+      ...this.settings,
+      ...options,
+    };
+  }
+
+  /**
+   * Get current configuration
+   * @returns {Object} Current settings
+   */
+  getConfig() {
+    return { ...this.settings };
+  }
+
+  /**
+   * Reset to default configuration
+   */
+  reset() {
+    this.settings = {
+      successKey: 'success',
+      dataKey: 'data',
+      messageKey: 'message',
+      errorKey: 'errors',
+      includeTimestamp: false,
+      includeRequestId: false,
+      includeMeta: false,
+      timestampKey: 'timestamp',
+      requestIdKey: 'requestId',
+      metaKey: 'meta',
+    };
+  }
+
+  /**
+   * Build response object based on configuration
+   * @param {Object} baseResponse - Base response object
+   * @param {Object} req - Express request object
+   * @returns {Object} Configured response object
+   */
+  buildResponse(baseResponse, req = null) {
+    const response = { ...baseResponse };
+
+    if (this.settings.includeTimestamp) {
+      response[this.settings.timestampKey] = new Date().toISOString();
+    }
+
+    if (this.settings.includeRequestId && req) {
+      const requestId = req.id || req.headers['x-request-id'] || this.generateRequestId();
+      response[this.settings.requestIdKey] = requestId;
+    }
+
+    if (this.settings.includeMeta && req) {
+      response[this.settings.metaKey] = {
+        method: req.method,
+        path: req.path,
+      };
+    }
+
+    return response;
+  }
+
+  /**
+   * Generate a simple request ID
+   * @returns {string} Generated request ID
+   */
+  generateRequestId() {
+    return `${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+  }
+}
+
+// Singleton instance
+const config = new Config();
+
+module.exports = config;

package/src/helpers/error.js

@@ -0,0 +1,104 @@
+const config = require('../core/config');
+
+/**
+ * Send error response
+ * @param {Object} res - Express response object
+ * @param {number} statusCode - HTTP status code
+ * @param {string} message - Error message
+ * @param {*} errors - Error details
+ * @param {Object} req - Express request object (optional)
+ * @returns {Object} Express response
+ */
+const sendError = (
+  res,
+  statusCode,
+  message,
+  errors = null,
+  req = null
+) => {
+  const settings = config.getConfig();
+  
+  const baseResponse = {
+    [settings.successKey]: false,
+    [settings.messageKey]: message,
+  };
+
+  // Only include errors if they exist
+  if (errors !== null) {
+    baseResponse[settings.errorKey] = errors;
+  }
+
+  const response = config.buildResponse(baseResponse, req);
+
+  return res.status(statusCode).json(response);
+};
+
+/**
+ * Send 400 Bad Request response
+ * @param {Object} res - Express response object
+ * @param {string} message - Error message
+ * @param {Object} req - Express request object (optional)
+ * @returns {Object} Express response
+ */
+const badRequest = (res, message = 'Bad Request', req = null) =>
+  sendError(res, 400, message, null, req);
+
+/**
+ * Send 401 Unauthorized response
+ * @param {Object} res - Express response object
+ * @param {string} message - Error message
+ * @param {Object} req - Express request object (optional)
+ * @returns {Object} Express response
+ */
+const unauthorized = (res, message = 'Unauthorized', req = null) =>
+  sendError(res, 401, message, null, req);
+
+/**
+ * Send 403 Forbidden response
+ * @param {Object} res - Express response object
+ * @param {string} message - Error message
+ * @param {Object} req - Express request object (optional)
+ * @returns {Object} Express response
+ */
+const forbidden = (res, message = 'Forbidden', req = null) =>
+  sendError(res, 403, message, null, req);
+
+/**
+ * Send 404 Not Found response
+ * @param {Object} res - Express response object
+ * @param {string} message - Error message
+ * @param {Object} req - Express request object (optional)
+ * @returns {Object} Express response
+ */
+const notFound = (res, message = 'Not Found', req = null) =>
+  sendError(res, 404, message, null, req);
+
+/**
+ * Send 409 Conflict response
+ * @param {Object} res - Express response object
+ * @param {string} message - Error message
+ * @param {Object} req - Express request object (optional)
+ * @returns {Object} Express response
+ */
+const conflict = (res, message = 'Conflict', req = null) =>
+  sendError(res, 409, message, null, req);
+
+/**
+ * Send 500 Internal Server Error response
+ * @param {Object} res - Express response object
+ * @param {string} message - Error message
+ * @param {Object} req - Express request object (optional)
+ * @returns {Object} Express response
+ */
+const internalError = (res, message = 'Internal Server Error', req = null) =>
+  sendError(res, 500, message, null, req);
+
+module.exports = {
+  sendError,
+  badRequest,
+  unauthorized,
+  forbidden,
+  notFound,
+  conflict,
+  internalError,
+};

package/src/helpers/pagination.js

@@ -0,0 +1,41 @@
+const config = require('../core/config');
+
+/**
+ * Send paginated response
+ * @param {Object} res - Express response object
+ * @param {Array} data - Array of data items
+ * @param {number} page - Current page number
+ * @param {number} limit - Items per page
+ * @param {number} total - Total number of items
+ * @param {Object} req - Express request object (optional)
+ * @returns {Object} Express response
+ */
+const paginate = (
+  res,
+  data,
+  page,
+  limit,
+  total,
+  req = null
+) => {
+  const settings = config.getConfig();
+  
+  const baseResponse = {
+    [settings.successKey]: true,
+    [settings.dataKey]: data,
+    pagination: {
+      page: parseInt(page),
+      limit: parseInt(limit),
+      total: parseInt(total),
+      totalPages: Math.ceil(total / limit),
+    },
+  };
+
+  const response = config.buildResponse(baseResponse, req);
+
+  return res.status(200).json(response);
+};
+
+module.exports = {
+  paginate,
+};

package/src/helpers/success.js

@@ -0,0 +1,52 @@
+const config = require('../core/config');
+
+/**
+ * Send success response
+ * @param {Object} res - Express response object
+ * @param {*} data - Response data
+ * @param {string} message - Success message
+ * @param {number} statusCode - HTTP status code
+ * @param {Object} req - Express request object (optional)
+ * @returns {Object} Express response
+ */
+const success = (
+  res,
+  data = null,
+  message = 'Success',
+  statusCode = 200,
+  req = null
+) => {
+  const settings = config.getConfig();
+  
+  const baseResponse = {
+    [settings.successKey]: true,
+    [settings.messageKey]: message,
+    [settings.dataKey]: data,
+  };
+
+  const response = config.buildResponse(baseResponse, req);
+
+  return res.status(statusCode).json(response);
+};
+
+/**
+ * Send created response (201)
+ * @param {Object} res - Express response object
+ * @param {*} data - Response data
+ * @param {string} message - Success message
+ * @param {Object} req - Express request object (optional)
+ * @returns {Object} Express response
+ */
+const created = (
+  res,
+  data = null,
+  message = 'Created Successfully',
+  req = null
+) => {
+  return success(res, data, message, 201, req);
+};
+
+module.exports = {
+  success,
+  created,
+};

package/src/helpers/validation.js

@@ -0,0 +1,32 @@
+const config = require('../core/config');
+
+/**
+ * Send validation error response (422)
+ * @param {Object} res - Express response object
+ * @param {Object} errors - Validation errors
+ * @param {string} message - Error message
+ * @param {Object} req - Express request object (optional)
+ * @returns {Object} Express response
+ */
+const validationError = (
+  res,
+  errors = {},
+  message = 'Validation Failed',
+  req = null
+) => {
+  const settings = config.getConfig();
+  
+  const baseResponse = {
+    [settings.successKey]: false,
+    [settings.messageKey]: message,
+    [settings.errorKey]: errors,
+  };
+
+  const response = config.buildResponse(baseResponse, req);
+
+  return res.status(422).json(response);
+};
+
+module.exports = {
+  validationError,
+};

package/src/index.js

@@ -1,6 +1,83 @@
-module.exports = {
-  ...require("./success"),
-  ...require("./error"),
-  ...require("./validation"),
-  ...require("./pagination"),
-};
+/**
+ * Response Kit v2.0.0
+ * Production-grade API response utility for Express.js
+ * 
+ * Backward compatible with v1.x
+ */
+
+const config = require('./core/config');
+const responseMiddleware = require('./middleware/response');
+const asyncHandler = require('./middleware/asyncHandler');
+
+// Import refactored helpers (v2 - with config support)
+const { success, created } = require('./helpers/success');
+const {
+  badRequest,
+  unauthorized,
+  forbidden,
+  notFound,
+  conflict,
+  internalError,
+} = require('./helpers/error');
+const { validationError } = require('./helpers/validation');
+const { paginate } = require('./helpers/pagination');
+
+/**
+ * Main response object
+ * Provides both v1 (backward compatible) and v2 (new) APIs
+ */
+const response = {
+  // V1 API - Backward compatible
+  // These maintain the original signature: fn(res, ...)
+  success,
+  created,
+  badRequest,
+  unauthorized,
+  forbidden,
+  notFound,
+  conflict,
+  internalError,
+  validationError,
+  paginate,
+
+  // V2 API - New features
+  /**
+   * Configure global response settings
+   * @param {Object} options - Configuration options
+   */
+  configure: (options) => config.configure(options),
+
+  /**
+   * Get current configuration
+   * @returns {Object} Current configuration
+   */
+  getConfig: () => config.getConfig(),
+
+  /**
+   * Reset configuration to defaults
+   */
+  resetConfig: () => config.reset(),
+
+  /**
+   * Express middleware factory
+   * Attaches response helpers to res object
+   * Usage: app.use(response.middleware())
+   * @returns {Function} Express middleware
+   */
+  middleware: responseMiddleware,
+
+  /**
+   * Async handler wrapper
+   * Eliminates try-catch blocks in route handlers
+   * Usage: router.get('/path', response.asyncHandler(async (req, res) => {...}))
+   * @param {Function} fn - Async route handler
+   * @returns {Function} Wrapped handler
+   */
+  asyncHandler,
+};
+
+// For CommonJS default export
+module.exports = response;
+
+// For ES modules compatibility
+module.exports.default = response;

package/src/middleware/asyncHandler.js

@@ -0,0 +1,14 @@
+
+/**
+ * Wraps async route handlers to catch errors
+ * @param {Function} fn - Async route handler function
+ * @returns {Function} Express middleware function
+ */
+function asyncHandler(fn) {
+  return function (req, res, next) {
+    // Ensure fn returns a promise, then catch any errors
+    Promise.resolve(fn(req, res, next)).catch(next);
+  };
+}
+
+module.exports = asyncHandler;

package/src/middleware/response.js

@@ -0,0 +1,69 @@
+const config = require('../core/config');
+const { success, created } = require('../helpers/success');
+const {
+  badRequest,
+  unauthorized,
+  forbidden,
+  notFound,
+  conflict,
+  internalError,
+} = require('../helpers/error');
+const { validationError } = require('../helpers/validation');
+const { paginate } = require('../helpers/pagination');
+
+/**
+ * Response middleware factory
+ * Attaches all response helpers to Express res object
+ * @returns {Function} Express middleware
+ */
+function responseMiddleware() {
+  return function (req, res, next) {
+    // Success responses
+    res.success = function (data = null, message = 'Success', statusCode = 200) {
+      return success(res, data, message, statusCode, req);
+    };
+
+    res.created = function (data = null, message = 'Created Successfully') {
+      return created(res, data, message, req);
+    };
+
+    // Error responses
+    res.badRequest = function (message = 'Bad Request') {
+      return badRequest(res, message, req);
+    };
+
+    res.unauthorized = function (message = 'Unauthorized') {
+      return unauthorized(res, message, req);
+    };
+
+    res.forbidden = function (message = 'Forbidden') {
+      return forbidden(res, message, req);
+    };
+
+    res.notFound = function (message = 'Not Found') {
+      return notFound(res, message, req);
+    };
+
+    res.conflict = function (message = 'Conflict') {
+      return conflict(res, message, req);
+    };
+
+    res.internalError = function (message = 'Internal Server Error') {
+      return internalError(res, message, req);
+    };
+
+    // Validation error
+    res.validationError = function (errors = {}, message = 'Validation Failed') {
+      return validationError(res, errors, message, req);
+    };
+
+    // Pagination
+    res.paginate = function (data, page, limit, total) {
+      return paginate(res, data, page, limit, total, req);
+    };
+
+    next();
+  };
+}
+
+module.exports = responseMiddleware;

package/src/types/index.js

@@ -0,0 +1,71 @@
+/**
+ * Validate if value is a valid HTTP status code
+ * @param {number} statusCode - Status code to validate
+ * @returns {boolean} True if valid
+ */
+function isValidStatusCode(statusCode) {
+  return typeof statusCode === 'number' && statusCode >= 100 && statusCode < 600;
+}
+
+/**
+ * Validate if value is a string
+ * @param {*} value - Value to validate
+ * @returns {boolean} True if string
+ */
+function isString(value) {
+  return typeof value === 'string';
+}
+
+/**
+ * Validate if value is an object
+ * @param {*} value - Value to validate
+ * @returns {boolean} True if object
+ */
+function isObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * Validate if value is an array
+ * @param {*} value - Value to validate
+ * @returns {boolean} True if array
+ */
+function isArray(value) {
+  return Array.isArray(value);
+}
+
+/**
+ * Validate pagination parameters
+ * @param {number} page - Page number
+ * @param {number} limit - Items per page
+ * @param {number} total - Total items
+ * @returns {Object} Validation result
+ */
+function validatePaginationParams(page, limit, total) {
+  const errors = [];
+
+  if (!Number.isInteger(page) || page < 1) {
+    errors.push('Page must be a positive integer');
+  }
+
+  if (!Number.isInteger(limit) || limit < 1) {
+    errors.push('Limit must be a positive integer');
+  }
+
+  if (!Number.isInteger(total) || total < 0) {
+    errors.push('Total must be a non-negative integer');
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}
+
+module.exports = {
+  isValidStatusCode,
+  isString,
+  isObject,
+  isArray,
+  validatePaginationParams,
+};