express-pro-toolkit 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,426 @@
+# express-pro-toolkit
+
+> Enterprise-grade Express.js toolkit — async error handling, configurable error handler with logging hooks, request logger with correlation IDs, structured `AppError` class, pagination helpers, and consistent JSON responses. **Zero external dependencies.**
+
+[![NPM Version](https://img.shields.io/npm/v/express-pro-toolkit.svg)](https://www.npmjs.com/package/express-pro-toolkit)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+---
+
+## Features
+
+| Utility | Description |
+| --- | --- |
+| `asyncHandler(fn)` | Wraps async route/error handlers — catches rejected promises automatically |
+| `errorHandler` | Drop-in global error handler with consistent JSON responses |
+| `createErrorHandler(opts)` | Configurable error handler with logging hooks (Sentry, Datadog, etc.) |
+| `requestLogger` | Colourised request logger with response time |
+| `createRequestLogger(opts)` | Configurable logger — skip routes, custom output, correlation IDs |
+| `correlationId(opts)` | Generates / propagates `x-request-id` for distributed tracing |
+| `notFoundHandler(opts)` | 404 catch-all middleware |
+| `AppError` | Structured error class with static factories, codes, and operational flag |
+| `sendSuccess()` | Consistent JSON success response |
+| `sendError()` | Consistent JSON error response |
+| `sendPaginated()` | Paginated JSON response with metadata |
+| `httpStatus` | Frozen enum of common HTTP status codes |
+
+**Zero external dependencies** · Works with **Express 4 & 5** · **TypeScript declarations included**
+
+---
+
+## Installation
+
+```bash
+npm install express-pro-toolkit
+```
+
+---
+
+## Quick Start
+
+```js
+const express = require('express');
+const {
+  asyncHandler,
+  createErrorHandler,
+  createRequestLogger,
+  correlationId,
+  notFoundHandler,
+  sendSuccess,
+  AppError,
+  httpStatus,
+} = require('express-pro-toolkit');
+
+const app = express();
+
+app.use(express.json());
+app.use(correlationId());                              // x-request-id
+app.use(createRequestLogger({                          // skip health checks
+  skip: (req) => req.url === '/health',
+}));
+
+app.get('/api/users', asyncHandler(async (req, res) => {
+  const users = await getUsersFromDB();
+  sendSuccess(res, users, 'Users fetched');
+}));
+
+app.post('/api/users', asyncHandler(async (req, res) => {
+  if (!req.body.email) {
+    throw AppError.validation([{ field: 'email', message: 'Required' }]);
+  }
+  const user = await createUser(req.body);
+  sendSuccess(res, user, 'Created', httpStatus.CREATED);
+}));
+
+app.use(notFoundHandler());                            // 404 catch-all
+app.use(createErrorHandler({                           // global error handler
+  onError: ({ err, requestId }) => {
+    // Send to Sentry, Datadog, Pino, etc.
+  },
+}));
+
+app.listen(3000);
+```
+
+---
+
+## API Reference
+
+### `asyncHandler(fn)`
+
+Wraps an async `(req, res, next)` handler so rejected promises are forwarded to `next(err)`. Also supports 4-arg error-handling middleware.
+
+```js
+router.get('/items', asyncHandler(async (req, res) => {
+  const items = await Item.find();
+  res.json(items);
+}));
+
+// Also works with async error middleware
+app.use(asyncHandler(async (err, req, res, next) => {
+  await logToExternalService(err);
+  next(err);
+}));
+```
+
+---
+
+### `AppError`
+
+Structured error class with HTTP status codes, machine-readable codes, operational flags, and static factory methods.
+
+```js
+const { AppError } = require('express-pro-toolkit');
+
+// Static factories (most common)
+throw AppError.badRequest('Invalid input');          // 400
+throw AppError.unauthorized('Login required');       // 401
+throw AppError.forbidden('No access');               // 403
+throw AppError.notFound('User not found');           // 404
+throw AppError.conflict('Email already exists');     // 409
+throw AppError.tooManyRequests('Slow down');         // 429
+throw AppError.internal('Unexpected failure');        // 500 (isOperational: false)
+
+// Validation with field-level details
+throw AppError.validation([
+  { field: 'email', message: 'Email is required' },
+  { field: 'name',  message: 'Name is required' },
+]);
+
+// Custom
+throw new AppError('Payment failed', 402, {
+  code: 'PAYMENT_DECLINED',
+  errors: [{ provider: 'stripe', reason: 'insufficient_funds' }],
+});
+```
+
+**Operational vs Programmer errors:**
+- `isOperational: true` (default) — expected failures, safe to expose to clients.
+- `isOperational: false` — bugs; in production the message is replaced with "Internal Server Error".
+
+---
+
+### `errorHandler` / `createErrorHandler(options)`
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `includeStack` | `boolean` | `!production` | Include stack trace in response |
+| `onError` | `function` | `console.error` | Logging hook — receives full payload |
+| `defaultStatusCode` | `number` | `500` | Fallback HTTP status |
+
+```js
+// Drop-in (default config)
+app.use(errorHandler);
+
+// Enterprise — custom logging hook
+app.use(createErrorHandler({
+  onError: ({ err, statusCode, method, url, requestId, timestamp }) => {
+    Sentry.captureException(err, { tags: { requestId } });
+  },
+}));
+```
+
+**Error response includes:**
+- `success: false`
+- `message` — safe message (sanitised in production for 5xx)
+- `errors` — detail array (validation, etc.)
+- `code` — machine-readable error code (if set on error)
+- `requestId` — correlation ID (if `correlationId` middleware is active)
+- `stack` — stack trace (dev only by default)
+
+---
+
+### `requestLogger` / `createRequestLogger(options)`
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `log` | `function` | Colourised console | Custom log function `(info) => void` |
+| `skip` | `function` | none | `(req, res) => boolean` — skip certain requests |
+
+```js
+// Default (colourised, logs everything)
+app.use(requestLogger);
+
+// Skip health checks, pipe to Pino
+app.use(createRequestLogger({
+  skip: (req) => req.url === '/health',
+  log: (info) => pino.info(info, 'http'),
+}));
+```
+
+**Log info object:**
+```js
+{
+  method: 'GET',
+  url: '/api/users',
+  status: 200,
+  duration: 4.21,       // ms
+  timestamp: '2026-03-01T12:00:00.000Z',
+  requestId: 'a1b2c3d4e5f6'
+}
+```
+
+---
+
+### `correlationId(options)`
+
+Generates or propagates a unique request ID for distributed tracing.
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `header` | `string` | `'x-request-id'` | Header to read / echo |
+| `generator` | `function` | 16-char hex | Custom ID generator |
+| `setResponseHeader` | `boolean` | `true` | Echo ID back to client |
+
+```js
+app.use(correlationId());
+
+// Custom header + UUID generator
+app.use(correlationId({
+  header: 'x-correlation-id',
+  generator: () => crypto.randomUUID(),
+}));
+
+// Access in routes
+app.get('/test', (req, res) => {
+  console.log(req.id); // 'a1b2c3d4e5f67890'
+});
+```
+
+---
+
+### `notFoundHandler(options)`
+
+Catches unmatched routes and forwards a 404 `AppError` to the error handler.
+
+```js
+// After all routes, before errorHandler
+app.use(notFoundHandler());
+app.use(notFoundHandler({ message: 'Route does not exist' }));
+```
+
+---
+
+### `sendSuccess(res, data, message?, statusCode?, meta?)`
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `res` | `Response` | — | Express response |
+| `data` | `any` | `null` | Payload |
+| `message` | `string` | `"Success"` | Human-readable message |
+| `statusCode` | `number` | `200` | HTTP status code |
+| `meta` | `object` | — | Optional metadata (pagination, etc.) |
+
+```js
+sendSuccess(res, user, 'User created', 201);
+
+// With metadata
+sendSuccess(res, users, 'Fetched', 200, { cached: true });
+```
+
+---
+
+### `sendError(res, message?, statusCode?, errors?, code?)`
+
+```js
+sendError(res, 'Validation failed', 422, [
+  { field: 'email', message: 'Required' },
+], 'VALIDATION_ERROR');
+```
+
+---
+
+### `sendPaginated(res, items, pagination, message?)`
+
+```js
+sendPaginated(res, users, { page: 2, limit: 25, total: 100 });
+
+// Response:
+// {
+//   "success": true,
+//   "message": "Success",
+//   "data": [...],
+//   "meta": {
+//     "page": 2,
+//     "limit": 25,
+//     "total": 100,
+//     "totalPages": 4,
+//     "hasNextPage": true,
+//     "hasPrevPage": true
+//   }
+// }
+```
+
+---
+
+### `httpStatus`
+
+Frozen object of common HTTP status codes — eliminates magic numbers.
+
+```js
+const { httpStatus } = require('express-pro-toolkit');
+
+res.status(httpStatus.CREATED).json(data);   // 201
+res.status(httpStatus.NO_CONTENT).end();     // 204
+```
+
+---
+
+## Response Formats
+
+### Success
+
+```json
+{
+  "success": true,
+  "message": "Message here",
+  "data": { }
+}
+```
+
+### Success (paginated)
+
+```json
+{
+  "success": true,
+  "message": "Message here",
+  "data": [ ],
+  "meta": {
+    "page": 1,
+    "limit": 25,
+    "total": 100,
+    "totalPages": 4,
+    "hasNextPage": true,
+    "hasPrevPage": false
+  }
+}
+```
+
+### Error
+
+```json
+{
+  "success": false,
+  "message": "Error message",
+  "code": "ERROR_CODE",
+  "errors": [ ],
+  "requestId": "a1b2c3d4e5f67890"
+}
+```
+
+---
+
+## Example App
+
+```bash
+cd express-pro-toolkit
+npm install express
+node example/server.js
+```
+
+---
+
+## Smoke Tests
+
+```bash
+npm test
+```
+
+---
+
+## TypeScript
+
+TypeScript declarations are bundled in `types/index.d.ts`. No `@types/` package needed.
+
+```ts
+import {
+  asyncHandler,
+  AppError,
+  createErrorHandler,
+  httpStatus,
+} from 'express-pro-toolkit';
+```
+
+---
+
+## Publishing to NPM
+
+```bash
+npm login
+npm version patch   # 2.0.0 → 2.0.1
+npm publish
+```
+
+---
+
+## Folder Structure
+
+```
+express-pro-toolkit/
+├── example/
+│   └── server.js
+├── src/
+│   ├── AppError.js
+│   ├── asyncHandler.js
+│   ├── correlationId.js
+│   ├── errorHandler.js
+│   ├── httpStatus.js
+│   ├── notFoundHandler.js
+│   ├── requestLogger.js
+│   └── responseHelpers.js
+├── test/
+│   └── smoke.js
+├── types/
+│   └── index.d.ts
+├── index.js
+├── package.json
+├── README.md
+├── LICENSE
+└── .npmignore
+```
+
+---
+
+## License
+
+[MIT](LICENSE)

package/index.js

@@ -0,0 +1,28 @@
+'use strict';
+
+const asyncHandler = require('./src/asyncHandler');
+const errorHandlerModule = require('./src/errorHandler');
+const requestLoggerModule = require('./src/requestLogger');
+const { sendSuccess, sendError, sendPaginated } = require('./src/responseHelpers');
+const AppError = require('./src/AppError');
+const correlationId = require('./src/correlationId');
+const notFoundHandler = require('./src/notFoundHandler');
+const httpStatus = require('./src/httpStatus');
+
+module.exports = {
+  // Core (v1 backward-compatible)
+  asyncHandler,
+  errorHandler: errorHandlerModule,
+  requestLogger: requestLoggerModule,
+  sendSuccess,
+  sendError,
+
+  // Enterprise additions (v2)
+  createErrorHandler: errorHandlerModule.createErrorHandler,
+  createRequestLogger: requestLoggerModule.createRequestLogger,
+  sendPaginated,
+  AppError,
+  correlationId,
+  notFoundHandler,
+  httpStatus,
+};

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "express-pro-toolkit",
+  "version": "2.0.0",
+  "description": "Enterprise-grade Express.js toolkit — async error handling, configurable error handler, request logger with correlation IDs, structured AppError class, pagination helpers, and consistent JSON responses. Zero external dependencies.",
+  "main": "index.js",
+  "types": "types/index.d.ts",
+  "scripts": {
+    "test": "jest --verbose",
+    "test:smoke": "node test/smoke.js",
+    "test:coverage": "jest --verbose --coverage",
+    "example": "node example/server.js",
+    "lint": "echo \"No linter configured yet\"",
+    "prepublishOnly": "jest"
+  },
+  "keywords": [
+    "express",
+    "error-handler",
+    "async-handler",
+    "middleware",
+    "request-logger",
+    "json-response",
+    "express-middleware",
+    "error-handling",
+    "toolkit",
+    "correlation-id",
+    "request-id",
+    "app-error",
+    "pagination",
+    "enterprise",
+    "express-pro-toolkit"
+  ],
+  "author": "Hadeed Ul Hassan <hadeed.hassan189@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hadiid1718/express-pro-toolkit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/hadiid1718/express-pro-toolkit/issues"
+  },
+  "homepage": "https://github.com/hadiid1718/express-pro-toolkit#readme",
+  "engines": {
+    "node": ">=12.0.0"
+  },
+  "peerDependencies": {
+    "express": ">=4.0.0"
+  },
+  "files": [
+    "index.js",
+    "src/",
+    "types/",
+    "LICENSE",
+    "README.md"
+  ]
+}

package/src/AppError.js

@@ -0,0 +1,175 @@
+'use strict';
+
+/**
+ * Custom application error class for express-pro-toolkit.
+ *
+ * Provides structured, operational errors with HTTP status codes,
+ * error codes, and detail arrays. Distinguishes operational errors
+ * (expected, safe to expose) from programmer errors (bugs).
+ *
+ * @extends Error
+ *
+ * @example
+ * const { AppError } = require('express-pro-toolkit');
+ *
+ * // Simple
+ * throw new AppError('User not found', 404);
+ *
+ * // With error code
+ * throw new AppError('Token expired', 401, { code: 'AUTH_TOKEN_EXPIRED' });
+ *
+ * // With validation details
+ * throw new AppError('Validation failed', 422, {
+ *   code: 'VALIDATION_ERROR',
+ *   errors: [
+ *     { field: 'email', message: 'Email is required' },
+ *   ],
+ * });
+ */
+class AppError extends Error {
+  /**
+   * @param {string}  message            - Human-readable error message
+   * @param {number}  [statusCode=500]   - HTTP status code
+   * @param {object}  [options]          - Additional options
+   * @param {string}  [options.code]     - Machine-readable error code (e.g. 'VALIDATION_ERROR')
+   * @param {Array}   [options.errors]   - Array of detailed sub-errors
+   * @param {boolean} [options.isOperational=true] - Whether this is an operational (expected) error
+   */
+  constructor(message, statusCode, options) {
+    super(message);
+
+    /** @type {string} */
+    this.name = 'AppError';
+
+    /** @type {number} */
+    this.statusCode = typeof statusCode === 'number' ? statusCode : 500;
+
+    const opts = options && typeof options === 'object' ? options : {};
+
+    /** @type {string|undefined} */
+    this.code = opts.code || undefined;
+
+    /** @type {Array|null} */
+    this.errors = Array.isArray(opts.errors) ? opts.errors : null;
+
+    /**
+     * Operational errors are expected failures (bad input, not found, etc.).
+     * Non-operational errors indicate programmer bugs and should trigger alerts.
+     * @type {boolean}
+     */
+    this.isOperational = opts.isOperational !== false;
+
+    /** @type {number} */
+    this.timestamp = Date.now();
+
+    // Capture stack trace, excluding constructor call from it
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, AppError);
+    }
+  }
+
+  /**
+   * Create a 400 Bad Request error.
+   * @param {string} [message='Bad Request']
+   * @param {object} [options]
+   * @returns {AppError}
+   */
+  static badRequest(message, options) {
+    return new AppError(message || 'Bad Request', 400, options);
+  }
+
+  /**
+   * Create a 401 Unauthorized error.
+   * @param {string} [message='Unauthorized']
+   * @param {object} [options]
+   * @returns {AppError}
+   */
+  static unauthorized(message, options) {
+    return new AppError(message || 'Unauthorized', 401, options);
+  }
+
+  /**
+   * Create a 403 Forbidden error.
+   * @param {string} [message='Forbidden']
+   * @param {object} [options]
+   * @returns {AppError}
+   */
+  static forbidden(message, options) {
+    return new AppError(message || 'Forbidden', 403, options);
+  }
+
+  /**
+   * Create a 404 Not Found error.
+   * @param {string} [message='Not Found']
+   * @param {object} [options]
+   * @returns {AppError}
+   */
+  static notFound(message, options) {
+    return new AppError(message || 'Not Found', 404, options);
+  }
+
+  /**
+   * Create a 409 Conflict error.
+   * @param {string} [message='Conflict']
+   * @param {object} [options]
+   * @returns {AppError}
+   */
+  static conflict(message, options) {
+    return new AppError(message || 'Conflict', 409, options);
+  }
+
+  /**
+   * Create a 422 Validation error with field-level details.
+   * @param {Array}  errors  - Array of { field, message } objects
+   * @param {string} [message='Validation Failed']
+   * @returns {AppError}
+   */
+  static validation(errors, message) {
+    return new AppError(message || 'Validation Failed', 422, {
+      code: 'VALIDATION_ERROR',
+      errors: errors,
+    });
+  }
+
+  /**
+   * Create a 429 Too Many Requests error.
+   * @param {string} [message='Too Many Requests']
+   * @param {object} [options]
+   * @returns {AppError}
+   */
+  static tooManyRequests(message, options) {
+    return new AppError(message || 'Too Many Requests', 429, options);
+  }
+
+  /**
+   * Create a 500 Internal Server Error.
+   * @param {string} [message='Internal Server Error']
+   * @param {object} [options]
+   * @returns {AppError}
+   */
+  static internal(message, options) {
+    return new AppError(message || 'Internal Server Error', 500, {
+      ...options,
+      isOperational: false,
+    });
+  }
+
+  /**
+   * Serialise the error to a plain object (useful for logging).
+   * @returns {object}
+   */
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      statusCode: this.statusCode,
+      code: this.code,
+      errors: this.errors,
+      isOperational: this.isOperational,
+      timestamp: this.timestamp,
+      stack: this.stack,
+    };
+  }
+}
+
+module.exports = AppError;