my-async-handler 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Krishna Karale
+
+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,123 @@
+# my_async_handler 🚀
+
+A lightweight, zero-dependency utility for **Express.js** to eliminate `try-catch` boilerplate and handle async errors gracefully.
+
+---
+
+## 🔴 The Problem
+
+In **Express 4**, when you use `async/await` in your route handlers, any error thrown or any rejected promise is **not automatically caught by Express**.
+
+This leads to:
+
+1. **Unhandled Promise Rejections**  
+   Your Node.js process might crash or behave unpredictably.
+
+2. **Repetitive Code**  
+   You end up writing `try-catch` blocks in every single controller, making your code messy and hard to maintain.
+
+---
+
+## 🟢 The Solution
+
+`my_async_handler` is a higher-order function that wraps your async middleware. It ensures that if an error occurs, it is automatically caught and passed to the Express `next(err)` function, forwarding it to your global error-handling middleware.
+
+### ✅ Features
+
+- **Clean** – Removes the need for `try-catch` in every route.
+- **Safe** – Prevents unhandled promise rejections.
+- **Lightweight** – Zero dependencies.
+- **Modern** – Fully supports ES Modules (`import/export`).
+
+---
+
+## 🛠 Installation
+
+```bash
+npm install my-async-handler
+```
+
+---
+
+## 🚀 Usage
+
+### 1️⃣ Basic Async Route
+
+Instead of wrapping your logic in a `try...catch` block, wrap the entire function in `asyncHandler`.
+
+```javascript
+import asyncHandler from 'my_async_handler';
+
+// No try-catch needed!
+export const getData = asyncHandler(async (req, res, next) => {
+    // If find() fails, the error is automatically passed to next()
+    const data = await MyModel.find(); 
+    res.status(200).json({ success: true, data });
+});
+```
+
+---
+
+### 2️⃣ Handling Custom Errors
+
+You can throw errors directly inside your logic, and `asyncHandler` will catch them and send them to your error middleware.
+
+```javascript
+export const getUser = asyncHandler(async (req, res, next) => {
+    const user = await User.findById(req.params.id);
+    
+    if (!user) {
+        const error = new Error("User not found");
+        error.status = 404;
+        throw error; // This goes straight to your global error handler
+    }
+
+    res.json(user);
+});
+```
+
+---
+
+### 3️⃣ Setup Global Error Middleware
+
+For this utility to work, ensure you have an error handler at the end of your `app.js` file (after all routes).
+
+```javascript
+// This MUST be after all your routes
+app.use((err, req, res, next) => {
+    const statusCode = err.status || 500;
+
+    res.status(statusCode).json({
+        success: false,
+        message: err.message || "Internal Server Error"
+    });
+});
+```
+
+---
+
+## 🧪 Testing
+
+This package includes a simple test script to verify functionality without needing a database.
+
+```bash
+npm test
+```
+---
+
+## ⚠️ Disclaimer: Use At Your Own Risk
+
+This software is provided **"as is"**, without any warranties or guarantees of any kind.
+
+By using this package, you agree that:
+
+- You are responsible for testing and validating it before deploying to production.
+- The author is **not liable** for any issues arising from its use.
+- This includes, but is not limited to:
+  - Server downtime
+  - Data loss
+  - Security vulnerabilities
+  - Unexpected behavior
+  - Production failures
+
+Always verify and test thoroughly in a **development environment** before using it in a live system.

package/index.js

@@ -0,0 +1,14 @@
+/**
+ * Wraps async Express middleware to catch errors and pass them to next().
+ * @param {Function} fn - The async function to wrap.
+ */
+const asyncHandler = (fn) => {
+   if (typeof fn !== "function") {
+    throw new TypeError("asyncHandler expects a function");
+  }
+  return (req, res, next) => {
+    Promise.resolve(fn(req, res, next)).catch(next);
+  };
+};
+
+export default asyncHandler;

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "my-async-handler",
+  "version": "1.0.0",
+  "description": "A lightweight wrapper for Express async routes to eliminate try-catch boilerplate.",
+  "keywords": [
+    "express",
+    "express-middleware",
+    "async",
+    "async-handler",
+    "error-handling",
+    "middleware",
+    "nodejs"
+  ],
+  "license": "MIT",
+  "author": "Krishna Karale",
+  "type": "module",
+  "main": "index.js",
+  "exports": "./index.js",
+  "engines": {
+    "node": ">=14"
+  },
+  "scripts": {
+    "test": "node test.js"
+  }
+}

package/test.js

@@ -0,0 +1,54 @@
+import asyncHandler from './index.js';
+
+// --- Test Utilities ---
+const mockReq = {};
+const mockRes = {
+  status: function(code) { this.statusCode = code; return this; },
+  json: function(data) { this.body = data; return this; }
+};
+
+const runTest = async (name, testFn) => {
+  try {
+    await testFn();
+    console.log(`✅ Passed: ${name}`);
+  } catch (err) {
+    console.error(`❌ Failed: ${name}`);
+    console.error(err);
+    process.exit(1);
+  }
+};
+
+// --- Test Cases ---
+
+// 1. Verify it returns a function
+runTest("Returns a middleware function", () => {
+  const middleware = asyncHandler(async () => {});
+  if (typeof middleware !== 'function') throw new Error("Should return a function");
+});
+
+// 2. Verify it catches errors and calls next(err)
+runTest("Catches async errors and calls next()", async () => {
+  let errorPassedToNext = null;
+  const next = (err) => { errorPassedToNext = err; };
+  
+  const error = new Error("Async Failure");
+  const handler = async () => { throw error; };
+  
+  const middleware = asyncHandler(handler);
+  await middleware(mockReq, mockRes, next);
+  
+  if (errorPassedToNext !== error) {
+    throw new Error("The error was not passed to the next() function!");
+  }
+});
+
+// 3. Verify it works with normal (non-async) functions
+runTest("Works with synchronous functions", async () => {
+  let called = false;
+  const next = () => { called = true; };
+  
+  const middleware = asyncHandler((req, res, next) => { next(); });
+  await middleware(mockReq, mockRes, next);
+  
+  if (!called) throw new Error("next() was not called in sync mode");
+});