express-pro-toolkit 2.0.0

package/src/asyncHandler.js

@@ -0,0 +1,48 @@
+'use strict';
+
+/**
+ * Wraps an async Express route handler to automatically catch
+ * rejected promises and forward them to Express error-handling middleware.
+ *
+ * Compatible with Express 4 and 5. Preserves the original function's
+ * `length` property so Express can distinguish middleware (3 args) from
+ * error handlers (4 args).
+ *
+ * @param {Function} fn - Async route handler `(req, res, next) => Promise<void>`
+ * @returns {Function} Express middleware that catches async errors
+ *
+ * @example
+ * const { asyncHandler } = require('express-pro-toolkit');
+ *
+ * router.get('/users', asyncHandler(async (req, res) => {
+ *   const users = await User.find();
+ *   res.json(users);
+ * }));
+ *
+ * // Also works with error-handling middleware (4 args)
+ * app.use(asyncHandler(async (err, req, res, next) => {
+ *   await logErrorToService(err);
+ *   next(err);
+ * }));
+ */
+function asyncHandler(fn) {
+  if (typeof fn !== 'function') {
+    throw new TypeError('asyncHandler requires a function argument');
+  }
+
+  // Express uses fn.length to distinguish regular middleware (3) from
+  // error-handling middleware (4). We must preserve it.
+  if (fn.length === 4) {
+    // Error-handling middleware: (err, req, res, next)
+    return function asyncErrorHandlerWrapper(err, req, res, next) {
+      Promise.resolve().then(() => fn(err, req, res, next)).catch(next);
+    };
+  }
+
+  // Standard middleware / route handler: (req, res, next)
+  return function asyncHandlerWrapper(req, res, next) {
+    Promise.resolve().then(() => fn(req, res, next)).catch(next);
+  };
+}
+
+module.exports = asyncHandler;

package/src/correlationId.js

@@ -0,0 +1,58 @@
+'use strict';
+
+const { randomBytes } = require('crypto');
+
+/**
+ * Default ID generator — 16 random hex characters.
+ * Highly performant; avoids UUID overhead.
+ * @returns {string}
+ */
+function defaultGenerateId() {
+  return randomBytes(8).toString('hex');
+}
+
+/**
+ * Creates middleware that attaches a unique correlation / request ID
+ * to every incoming request, enabling distributed tracing.
+ *
+ * The ID is:
+ * 1. Read from an incoming header (default `x-request-id`) — honours
+ *    upstream load-balancers / API gateways.
+ * 2. Generated if not present.
+ * 3. Stored on `req.id` for downstream use.
+ * 4. Echoed back on the response in the same header.
+ *
+ * @param {object}   [options]
+ * @param {string}   [options.header='x-request-id']  - Header to read / write
+ * @param {Function} [options.generator]               - Custom ID generator `() => string`
+ * @param {boolean}  [options.setResponseHeader=true]  - Whether to echo ID on response
+ * @returns {Function} Express middleware
+ *
+ * @example
+ * const { correlationId } = require('express-pro-toolkit');
+ * app.use(correlationId());
+ * app.use(correlationId({ header: 'x-correlation-id' }));
+ */
+function correlationId(options) {
+  const opts = options && typeof options === 'object' ? options : {};
+  const header = (typeof opts.header === 'string' && opts.header) || 'x-request-id';
+  const headerLower = header.toLowerCase();
+  const generate = typeof opts.generator === 'function' ? opts.generator : defaultGenerateId;
+  const setResponse = opts.setResponseHeader !== false;
+
+  return function correlationIdMiddleware(req, res, next) {
+    const incoming = req.headers[headerLower];
+    const id = (typeof incoming === 'string' && incoming.length > 0) ? incoming : generate();
+
+    /** @type {string} Unique request identifier */
+    req.id = id;
+
+    if (setResponse) {
+      res.setHeader(header, id);
+    }
+
+    next();
+  };
+}
+
+module.exports = correlationId;

package/src/errorHandler.js

@@ -0,0 +1,153 @@
+'use strict';
+
+const AppError = require('./AppError');
+
+/* ─── Default logger (console) ────────────────────────────────────── */
+
+/**
+ * @param {object} payload
+ */
+function defaultOnError(payload) {
+  console.error(
+    `[express-pro-toolkit] ERROR ${payload.statusCode} — ${payload.method} ${payload.url}`,
+  );
+  console.error(payload.stack || payload.message);
+}
+
+/* ─── Helpers ─────────────────────────────────────────────────────── */
+
+/**
+ * Resolves the HTTP status code from an error object.
+ * Supports err.statusCode, err.status, and defaults to 500.
+ * @param {Error} err
+ * @returns {number}
+ */
+function resolveStatus(err) {
+  const code = err.statusCode || err.status;
+  return typeof code === 'number' && code >= 100 && code < 600 ? code : 500;
+}
+
+/**
+ * Determines if an error message is safe to expose to clients.
+ * Non-operational / 5xx errors get a generic message in production.
+ * @param {Error}   err
+ * @param {number}  statusCode
+ * @param {boolean} isProduction
+ * @returns {string}
+ */
+function resolveMessage(err, statusCode, isProduction) {
+  if (!isProduction) return err.message || 'Internal Server Error';
+
+  // In production, only expose messages for operational / client errors
+  if (err instanceof AppError && err.isOperational) return err.message;
+  if (statusCode < 500) return err.message || 'Error';
+
+  return 'Internal Server Error';
+}
+
+/* ─── Factory ─────────────────────────────────────────────────────── */
+
+/**
+ * Creates a configurable global Express error-handling middleware.
+ *
+ * Options:
+ * - `includeStack` — Include stack traces in the response.
+ *    Defaults to `true` outside production.
+ * - `onError(payload)` — Custom error logging / alerting hook.
+ *    Receives `{ err, statusCode, method, url, requestId, message, stack, timestamp }`.
+ * - `defaultStatusCode` — Fallback status code (default `500`).
+ *
+ * @param {object}   [options]
+ * @param {boolean}  [options.includeStack]
+ * @param {Function} [options.onError]
+ * @param {number}   [options.defaultStatusCode=500]
+ * @returns {Function} Express error-handling middleware `(err, req, res, next)`
+ *
+ * @example
+ * const { createErrorHandler } = require('express-pro-toolkit');
+ *
+ * // Basic
+ * app.use(createErrorHandler());
+ *
+ * // With external logging service
+ * app.use(createErrorHandler({
+ *   onError: ({ err, requestId }) => Sentry.captureException(err, { tags: { requestId } }),
+ * }));
+ */
+function createErrorHandler(options) {
+  const opts = options && typeof options === 'object' ? options : {};
+  const isProduction = process.env.NODE_ENV === 'production';
+  const showStack = typeof opts.includeStack === 'boolean' ? opts.includeStack : !isProduction;
+  const onError = typeof opts.onError === 'function' ? opts.onError : defaultOnError;
+
+  return function errorHandlerMiddleware(err, req, res, _next) {
+    const statusCode = resolveStatus(err) || (opts.defaultStatusCode || 500);
+    const message = resolveMessage(err, statusCode, isProduction);
+    const requestId = req.id || null;
+
+    // ── Build payload for the logging hook ────────────────────────
+    const logPayload = {
+      err,
+      statusCode,
+      method: req.method,
+      url: req.originalUrl || req.url,
+      requestId,
+      message,
+      stack: err.stack || null,
+      timestamp: new Date().toISOString(),
+    };
+
+    // Fire logging / alerting hook (non-blocking)
+    try { onError(logPayload); } catch (_) { /* never let logger crash the response */ }
+
+    // ── Build JSON response ───────────────────────────────────────
+    /** @type {object} */
+    const body = {
+      success: false,
+      message,
+    };
+
+    // Error code (machine-readable)
+    if (err.code) {
+      body.code = err.code;
+    }
+
+    // Detailed sub-errors (validation, etc.)
+    if (err.errors) {
+      body.errors = Array.isArray(err.errors) ? err.errors : [err.errors];
+    } else {
+      body.errors = null;
+    }
+
+    // Correlation ID for client-side tracing
+    if (requestId) {
+      body.requestId = requestId;
+    }
+
+    // Stack trace (dev only by default)
+    if (showStack) {
+      body.stack = err.stack || null;
+    }
+
+    // Prevent double-send if headers already flushed
+    if (res.headersSent) {
+      return;
+    }
+
+    res.status(statusCode).json(body);
+  };
+}
+
+/* ─── Backward-compatible default instance ────────────────────────── */
+
+/**
+ * Pre-configured error handler using default options.
+ * Drop-in replacement for the v1 export.
+ *
+ * @type {Function}
+ */
+const errorHandler = createErrorHandler();
+
+module.exports = errorHandler;
+module.exports.errorHandler = errorHandler;
+module.exports.createErrorHandler = createErrorHandler;

package/src/httpStatus.js

@@ -0,0 +1,48 @@
+'use strict';
+
+/**
+ * Common HTTP status code constants.
+ *
+ * Avoids magic numbers throughout application code.
+ *
+ * @example
+ * const { httpStatus } = require('express-pro-toolkit');
+ * res.status(httpStatus.CREATED).json(data);
+ *
+ * @readonly
+ * @enum {number}
+ */
+const httpStatus = Object.freeze({
+  // ── 2xx Success ──────────────────────────────
+  OK: 200,
+  CREATED: 201,
+  ACCEPTED: 202,
+  NO_CONTENT: 204,
+
+  // ── 3xx Redirection ──────────────────────────
+  MOVED_PERMANENTLY: 301,
+  FOUND: 302,
+  NOT_MODIFIED: 304,
+  TEMPORARY_REDIRECT: 307,
+  PERMANENT_REDIRECT: 308,
+
+  // ── 4xx Client Errors ────────────────────────
+  BAD_REQUEST: 400,
+  UNAUTHORIZED: 401,
+  FORBIDDEN: 403,
+  NOT_FOUND: 404,
+  METHOD_NOT_ALLOWED: 405,
+  CONFLICT: 409,
+  GONE: 410,
+  UNPROCESSABLE_ENTITY: 422,
+  TOO_MANY_REQUESTS: 429,
+
+  // ── 5xx Server Errors ────────────────────────
+  INTERNAL_SERVER_ERROR: 500,
+  NOT_IMPLEMENTED: 501,
+  BAD_GATEWAY: 502,
+  SERVICE_UNAVAILABLE: 503,
+  GATEWAY_TIMEOUT: 504,
+});
+
+module.exports = httpStatus;

package/src/notFoundHandler.js

@@ -0,0 +1,34 @@
+'use strict';
+
+const AppError = require('./AppError');
+
+/**
+ * Middleware that catches requests which did not match any route
+ * and forwards a 404 AppError to the error handler.
+ *
+ * Must be registered **after** all routes and **before** the error handler.
+ *
+ * @param {object} [options]
+ * @param {string} [options.message]  - Custom "not found" message
+ * @returns {Function} Express middleware
+ *
+ * @example
+ * const { notFoundHandler, errorHandler } = require('express-pro-toolkit');
+ *
+ * // After all routes
+ * app.use(notFoundHandler());
+ * app.use(errorHandler());
+ */
+function notFoundHandler(options) {
+  const opts = options && typeof options === 'object' ? options : {};
+
+  return function notFoundMiddleware(req, res, next) {
+    const msg =
+      (typeof opts.message === 'string' && opts.message) ||
+      `Cannot ${req.method} ${req.originalUrl || req.url}`;
+
+    next(new AppError(msg, 404, { code: 'ROUTE_NOT_FOUND' }));
+  };
+}
+
+module.exports = notFoundHandler;

package/src/requestLogger.js

@@ -0,0 +1,119 @@
+'use strict';
+
+/* ─── Colour helpers (ANSI 256 — only when stdout is a TTY) ────── */
+
+const isTTY = process.stdout.isTTY;
+
+/**
+ * @param {number} code ANSI colour code
+ * @param {string} text
+ * @returns {string}
+ */
+function colour(code, text) {
+  return isTTY ? `\x1b[${code}m${text}\x1b[0m` : text;
+}
+
+/**
+ * Pick a colour based on HTTP status code.
+ * @param {number} status
+ * @returns {string}
+ */
+function colourStatus(status) {
+  if (status >= 500) return colour(31, String(status)); // red
+  if (status >= 400) return colour(33, String(status)); // yellow
+  if (status >= 300) return colour(36, String(status)); // cyan
+  if (status >= 200) return colour(32, String(status)); // green
+  return String(status);
+}
+
+/**
+ * Pick a colour for response time.
+ * @param {number} ms
+ * @returns {string}
+ */
+function colourTime(ms) {
+  const text = ms.toFixed(2) + 'ms';
+  if (ms >= 1000) return colour(31, text);  // red   ≥ 1 s
+  if (ms >= 500)  return colour(33, text);  // yellow ≥ 500 ms
+  return colour(32, text);                  // green
+}
+
+/* ─── Default log function ────────────────────────────────────────── */
+
+/**
+ * @param {object} info
+ */
+function defaultLog(info) {
+  console.log(
+    `[${info.timestamp}] ${colour(1, info.method)} ${info.url} ${colourStatus(info.status)} — ${colourTime(info.duration)}${info.requestId ? ' id=' + info.requestId : ''}`,
+  );
+}
+
+/* ─── Factory ─────────────────────────────────────────────────────── */
+
+/**
+ * Creates a configurable request-logging middleware.
+ *
+ * @param {object}   [options]
+ * @param {Function} [options.log]    - Custom log function `(info) => void`.
+ *   Receives `{ method, url, status, duration, timestamp, requestId }`.
+ * @param {Function} [options.skip]   - `(req, res) => boolean` — skip logging
+ *   for certain requests (e.g. health checks).
+ * @param {boolean}  [options.colorize=true] - Enable ANSI colours (auto-detected)
+ * @returns {Function} Express middleware
+ *
+ * @example
+ * const { createRequestLogger } = require('express-pro-toolkit');
+ *
+ * // Default
+ * app.use(createRequestLogger());
+ *
+ * // Skip health checks, custom logger
+ * app.use(createRequestLogger({
+ *   skip: (req) => req.url === '/health',
+ *   log: (info) => pinoLogger.info(info, 'request'),
+ * }));
+ */
+function createRequestLogger(options) {
+  const opts = options && typeof options === 'object' ? options : {};
+  const logFn  = typeof opts.log  === 'function' ? opts.log  : defaultLog;
+  const skipFn = typeof opts.skip === 'function' ? opts.skip : null;
+
+  return function requestLoggerMiddleware(req, res, next) {
+    // Use hrtime tuple for high-resolution, Node 12+ compatible timing
+    const start = process.hrtime();
+
+    res.on('finish', function onFinish() {
+      // Allow caller to skip specific requests (health, metrics, etc.)
+      if (skipFn && skipFn(req, res)) return;
+
+      const diff = process.hrtime(start);
+      const durationMs = diff[0] * 1e3 + diff[1] / 1e6;
+
+      logFn({
+        method:    req.method,
+        url:       req.originalUrl || req.url,
+        status:    res.statusCode,
+        duration:  durationMs,
+        timestamp: new Date().toISOString(),
+        requestId: req.id || null,
+      });
+    });
+
+    next();
+  };
+}
+
+/* ─── Backward-compatible default instance ────────────────────────── */
+
+/**
+ * Pre-configured request logger using default options.
+ * Drop-in replacement for the v1 export.
+ *
+ * @type {Function}
+ */
+const requestLogger = createRequestLogger();
+
+module.exports = requestLogger;
+module.exports.requestLogger = requestLogger;
+module.exports.createRequestLogger = createRequestLogger;

package/src/responseHelpers.js

@@ -0,0 +1,108 @@
+'use strict';
+
+/**
+ * Send a consistent JSON **success** response.
+ *
+ * @param {import('express').Response} res              - Express response object
+ * @param {*}                          data             - Payload to return under `data`
+ * @param {string}                     [message]        - Human-readable message (default: `"Success"`)
+ * @param {number}                     [statusCode=200] - HTTP status code
+ * @param {object}                     [meta]           - Optional pagination / extra metadata
+ * @returns {void}
+ *
+ * @example
+ * const { sendSuccess } = require('express-pro-toolkit');
+ *
+ * sendSuccess(res, users, 'Users fetched', 200, {
+ *   page: 1, limit: 25, total: 100,
+ * });
+ *
+ * // Response:
+ * // {
+ * //   "success": true,
+ * //   "message": "Users fetched",
+ * //   "data": [...],
+ * //   "meta": { "page": 1, "limit": 25, "total": 100 }
+ * // }
+ */
+function sendSuccess(res, data, message, statusCode, meta) {
+  const code = typeof statusCode === 'number' ? statusCode : 200;
+  const msg  = typeof message === 'string' && message.length > 0 ? message : 'Success';
+
+  const body = {
+    success: true,
+    message: msg,
+    data: data !== undefined ? data : null,
+  };
+
+  if (meta !== undefined && meta !== null) {
+    body.meta = meta;
+  }
+
+  res.status(code).json(body);
+}
+
+/**
+ * Send a consistent JSON **error** response.
+ *
+ * @param {import('express').Response} res              - Express response object
+ * @param {string}                     [message]        - Human-readable error message
+ * @param {number}                     [statusCode=500] - HTTP status code
+ * @param {Array|null}                 [errors=null]    - Optional array of detailed error objects
+ * @param {string}                     [code]           - Machine-readable error code
+ * @returns {void}
+ *
+ * @example
+ * sendError(res, 'Validation failed', 422, [
+ *   { field: 'email', message: 'Email is required' },
+ * ], 'VALIDATION_ERROR');
+ */
+function sendError(res, message, statusCode, errors, code) {
+  const httpCode = typeof statusCode === 'number' ? statusCode : 500;
+  const msg = typeof message === 'string' && message.length > 0 ? message : 'Internal Server Error';
+
+  const body = {
+    success: false,
+    message: msg,
+    errors: errors != null ? (Array.isArray(errors) ? errors : [errors]) : null,
+  };
+
+  if (typeof code === 'string' && code.length > 0) {
+    body.code = code;
+  }
+
+  res.status(httpCode).json(body);
+}
+
+/**
+ * Send a paginated JSON success response.
+ *
+ * @param {import('express').Response} res
+ * @param {Array}   items
+ * @param {object}  pagination
+ * @param {number}  pagination.page
+ * @param {number}  pagination.limit
+ * @param {number}  pagination.total
+ * @param {string}  [message]
+ * @returns {void}
+ *
+ * @example
+ * sendPaginated(res, users, { page: 2, limit: 25, total: 100 });
+ */
+function sendPaginated(res, items, pagination, message) {
+  const page      = pagination.page  || 1;
+  const limit     = pagination.limit || 25;
+  const total     = pagination.total || 0;
+  const totalPages = Math.ceil(total / limit) || 1;
+
+  sendSuccess(res, items, message || 'Success', 200, {
+    page,
+    limit,
+    total,
+    totalPages,
+    hasNextPage: page < totalPages,
+    hasPrevPage: page > 1,
+  });
+}
+
+module.exports = { sendSuccess, sendError, sendPaginated };