devdad-express-utils 1.0.0

package/README.md

@@ -0,0 +1,160 @@
+# Express Utils
+
+A collection of reusable utilities for Express.js applications, including error handling, async route wrapping, and custom error classes.
+
+## Installation
+
+```bash
+npm install express-utils
+# or
+yarn add express-utils
+# or
+pnpm add express-utils
+```
+
+## Usage
+
+### Error Handling
+
+```typescript
+import express from "express";
+import { errorHandler, AppError } from "express-utils";
+
+const app = express();
+
+// Your routes here
+
+// Use the error handler as the last middleware
+app.use(errorHandler);
+
+// In your controllers, throw AppError for operational errors
+throw new AppError("Something went wrong", 400);
+```
+
+### Async Route Wrapping
+
+```typescript
+import { catchAsync } from "express-utils";
+
+const getUsers = catchAsync(async (req, res, next) => {
+  const users = await User.find();
+  res.json(users);
+});
+
+app.get("/users", getUsers);
+```
+
+### Custom Error Class
+
+```typescript
+import { AppError } from "express-utils";
+
+throw new AppError("Validation failed", 400, ["Email is required"]);
+```
+
+#### JavaScript Usage
+
+```javascript
+const { AppError, catchAsync, errorHandler } = require("express-utils");
+
+// Or with ES modules
+import { AppError, catchAsync, errorHandler } from "express-utils";
+```
+
+## Error Handling Patterns
+
+### Using AppError
+
+**For operational errors (expected errors like validation):**
+
+```typescript
+// In controllers wrapped with catchAsync
+const createUser = catchAsync(async (req, res, next) => {
+  // Validation fails
+  return next(new AppError("Email is required", 400));
+});
+
+// Or for unexpected errors
+throw new AppError("Database connection failed", 500);
+```
+
+**Why `next(new AppError())` over `throw`?**
+
+- `next()` passes the error to your error handler middleware
+- Allows centralized error handling and formatting
+- Better for Express middleware pattern
+- `throw` is more for unexpected errors that bubble up
+
+### Complete Example
+
+```javascript
+const express = require("express");
+const { AppError, catchAsync, errorHandler } = require("express-utils");
+
+const app = express();
+
+const getUser = catchAsync(async (req, res, next) => {
+  const user = await User.findById(req.params.id);
+  if (!user) {
+    return next(new AppError("User not found", 404));
+  }
+  res.json(user);
+});
+
+app.get("/users/:id", getUser);
+
+// Error handler should be last
+app.use(errorHandler);
+```
+
+#### JavaScript Usage
+
+```javascript
+const { AppError, catchAsync, errorHandler } = require("express-utils");
+
+// Or with ES modules
+import { AppError, catchAsync, errorHandler } from "express-utils";
+```
+
+## API
+
+### AppError
+
+Custom error class for operational errors.
+
+```typescript
+new AppError(message: string, statusCode: number, errors?: string[])
+```
+
+### catchAsync
+
+Higher-order function to wrap async route handlers and catch errors.
+
+```typescript
+catchAsync(fn: (req, res, next) => Promise<any>) => (req, res, next) => void
+```
+
+### errorHandler
+
+Express error handling middleware with detailed logging in development.
+
+```typescript
+errorHandler(err: any, req: Request, res: Response, next: NextFunction) => void
+```
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build the package
+pnpm run build
+
+# Publish to npm
+npm publish
+```
+
+## License
+
+ISC

package/dist/AppError.1.js

@@ -0,0 +1 @@
+"use strict";

package/dist/AppError.2.js

@@ -0,0 +1 @@
+"use strict";

package/dist/AppError.d.ts

@@ -0,0 +1,7 @@
+export declare class AppError extends Error {
+    readonly statusCode: number;
+    readonly status: "fail" | "error";
+    readonly isOperational: true;
+    readonly errors?: string[];
+    constructor(message: string, statusCode: number, errors?: string[]);
+}

package/dist/AppError.js

@@ -0,0 +1,15 @@
+export class AppError extends Error {
+    statusCode;
+    status;
+    isOperational;
+    errors;
+    constructor(message, statusCode, errors = []) {
+        super(message);
+        this.statusCode = statusCode;
+        this.status = statusCode.toString().startsWith("4") ? "fail" : "error";
+        this.isOperational = true;
+        this.errors = errors.length > 0 ? errors : undefined;
+        // Maintain proper stack trace
+        Error.captureStackTrace(this, this.constructor);
+    }
+}

package/dist/catchAsync.d.ts

@@ -0,0 +1,2 @@
+import type { NextFunction, Request, Response } from "express";
+export declare const catchAsync: (fn: (req: Request, res: Response, next: NextFunction) => Promise<any>) => (req: Request, res: Response, next: NextFunction) => void;

package/dist/catchAsync.js

@@ -0,0 +1,5 @@
+//#region Catch Async Handler
+export const catchAsync = (fn) => (req, res, next) => {
+    fn(req, res, next).catch(next);
+};
+//#endregion

package/dist/errorHandler.d.ts

@@ -0,0 +1,3 @@
+import { Request, Response, NextFunction } from "express";
+declare const errorHandler: (err: any, req: Request, res: Response, next: NextFunction) => void;
+export { errorHandler };

package/dist/errorHandler.js

@@ -0,0 +1,47 @@
+import { AppError } from "./AppError.js";
+const sendErrorDev = (err, res) => {
+    res.status(err.statusCode || 500).json({
+        status: err.status || "error",
+        message: err.message,
+        error: err,
+        errors: err.errors || [],
+        stack: err.stack,
+    });
+};
+const sendErrorProd = (err, res) => {
+    // Operational, trusted error → send to client
+    if (err.isOperational) {
+        res.status(err.statusCode).json({
+            status: err.status,
+            message: err.message,
+            ...(err.errors && err.errors.length > 0 && { errors: err.errors }),
+        });
+    }
+    else {
+        // Unknown error → hide details
+        console.error("ERROR", err);
+        res.status(500).json({
+            status: "error",
+            message: "Something went wrong!",
+        });
+    }
+};
+const errorHandler = (err, req, res, next) => {
+    err.statusCode = err.statusCode || 500;
+    err.status = err.status || "error";
+    // Add this for Extra In-Depth Error Logging
+    console.error("Error details:", {
+        message: err.message,
+        statusCode: err.statusCode,
+        errors: err.errors,
+        stack: err.stack,
+        fullError: err,
+    });
+    if (process.env.NODE_ENV === "development") {
+        sendErrorDev(err, res);
+    }
+    else {
+        sendErrorProd(err instanceof AppError ? err : new AppError(err.message, 500), res);
+    }
+};
+export { errorHandler };

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { AppError } from "./AppError.js";
+export { catchAsync } from "./catchAsync.js";
+export { errorHandler } from "./errorHandler.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { AppError } from "./AppError.js";
+export { catchAsync } from "./catchAsync.js";
+export { errorHandler } from "./errorHandler.js";

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "devdad-express-utils",
+  "version": "1.0.0",
+  "description": "Reusable Express.js utilities for error handling, async wrapping, and more",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "express",
+    "utilities",
+    "error-handling",
+    "typescript"
+  ],
+  "author": "Oliver Metz",
+  "license": "ISC",
+  "dependencies": {
+    "express": "^5.1.0"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.5",
+    "typescript": "^5.9.3"
+  },
+  "files": [
+    "dist"
+  ]
+}