{"id":17632,"library":"express-promise-router","title":"Express Promise Router","description":"express-promise-router is a lightweight wrapper for Express 4's native `Router` that significantly simplifies the handling of asynchronous operations by allowing middleware and route handlers to return Promises. When a Promise is returned, its resolution or rejection is automatically managed, eliminating the need for explicit `next()` calls on successful resolution or `.catch(next)` for rejections. This package is currently on version 4.1.1 and receives regular updates, typically in the form of patch and minor releases, with major versions occurring when significant changes like Node.js version support are introduced. Its primary differentiator is its seamless integration with existing Express applications as a drop-in replacement for `express.Router()`, promoting cleaner, more readable code, especially when leveraging `async/await` syntax. Unlike solutions that patch the `app` object, this library focuses specifically on router instances, allowing for granular control over promise-aware routing.","status":"active","version":"4.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/express-promise-router/express-promise-router","tags":["javascript","express","promise","router","typescript"],"install":[{"cmd":"npm install express-promise-router","lang":"bash","label":"npm"},{"cmd":"yarn add express-promise-router","lang":"bash","label":"yarn"},{"cmd":"pnpm add express-promise-router","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides the core routing functionality that this package wraps and extends.","package":"express","optional":false},{"reason":"Provides TypeScript type definitions for Express, essential for type-safe development.","package":"@types/express","optional":true}],"imports":[{"note":"The `Router` constructor is the default export of this package. Named imports will not work for the main Router function.","wrong":"import { Router } from 'express-promise-router';","symbol":"Router","correct":"import Router from 'express-promise-router';"},{"note":"In CommonJS environments, the `Router` constructor is directly returned by `require()`.","symbol":"Router (CommonJS)","correct":"const Router = require('express-promise-router');"},{"note":"While `import * as Router` might seem intuitive, `express-promise-router` provides a default export for the constructor, making `import Router from '...'` the idiomatic and correct TypeScript import.","wrong":"import * as Router from 'express-promise-router';","symbol":"Router (TypeScript)","correct":"import Router from 'express-promise-router';"}],"quickstart":{"code":"import express from 'express';\nimport PromiseRouter from 'express-promise-router';\n\nconst app = express();\nconst router = PromiseRouter();\n\n// Mount the promise-aware router onto the express app\napp.use(router);\n\n// Example 1: Async/await route handler\nrouter.get('/users/:id', async (req, res) => {\n  try {\n    // Simulate fetching user data from a database\n    const user = await Promise.resolve({ id: req.params.id, name: 'John Doe', permission: 'USER' });\n    \n    if (user.permission !== 'ADMIN') {\n      throw new Error('Access Denied: You must be an admin.');\n    }\n    \n    res.status(200).json({ message: `Welcome, ${user.name}!` });\n  } catch (error) {\n    // Errors thrown from async functions are automatically caught and passed to next()\n    // For this example, we'll manually send a response for clarity.\n    // In a real app, an error handler middleware would catch this.\n    throw error; // This will trigger the router's error handler\n  }\n});\n\n// Example 2: Promise resolution to call next() or next('route')\nrouter.get('/next-example', (req, res) => {\n  // Equivalent to calling next()\n  return Promise.resolve('next');\n});\n\nrouter.get('/next-example', (req, res) => {\n  res.send('Reached the next handler!');\n});\n\n// Global error handler for the router (will catch errors from promise rejections)\nrouter.use((err, req, res, next) => {\n  console.error('Caught an error:', err.message);\n  res.status(err.statusCode || 500).send(err.message || 'Internal Server Error');\n});\n\nconst PORT = process.env.PORT || 3000;\napp.listen(PORT, () => {\n  console.log(`Server running on http://localhost:${PORT}`);\n});","lang":"typescript","description":"This quickstart demonstrates how to initialize and use `express-promise-router` with an Express application, including basic `async/await` route handlers, explicit promise resolution for `next()` calls, and a global error handling middleware that captures promise rejections."},"warnings":[{"fix":"Upgrade Node.js to a supported version (>=10 for v4.x) or pin `express-promise-router` dependency to `<4.0.0`.","message":"Version 4.0.0 of `express-promise-router` dropped support for older Node.js versions (v4, v6, v8). Applications targeting these environments must remain on `express-promise-router` v3.x or update their Node.js runtime.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Ensure your Node.js version is >=4 and update any Bluebird-specific Promise logic to use native Promises or pin `express-promise-router` dependency to `<2.0.0`.","message":"Version 2.0.0 removed support for Node.js versions older than 4 and switched from Bluebird to native Promises. If you rely on Bluebird-specific features or target ancient Node.js runtimes, you must stick to `express-promise-router` v1.x.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Explicitly call a response method like `res.send()`, `res.json()`, or `res.end()` within your promise chain or `async` function to send data back to the client.","message":"Values returned or resolved by promise-based route handlers are NOT automatically sent as a response to the client. This design choice prevents accidental leakage of sensitive data or internal state.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always mount an `express-promise-router` instance onto your `app` (e.g., `app.use(promiseRouter);`) and define your promise-based routes and middleware on that router instance.","message":"`express-promise-router` currently only promisifies `Router` instances, not the main Express `app` object. Attempting to use promise-returning middleware directly on `app` will not have the same automatic error handling.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Always specify a path as the first argument to router methods, for example: `router.get('/', (req, res) => { ... });`.","cause":"You are calling a router method (e.g., `router.get`, `router.post`) without providing a path argument.","error":"Cannot read property '0' of undefined"},{"fix":"Ensure you explicitly call `res.send()`, `res.json()`, `res.end()`, or similar Express response methods within your promise chain or `async` function body to send data back to the client.","cause":"The library is designed not to automatically send the resolved value of a promise as a response to prevent accidental data leakage.","error":"My promise resolves, but the client doesn't receive any response."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}