• Synopsis
• Support
• Installation
• Error Flow
• Database Transaction Rollback
• Usage
• API Reference
• Logs
• Contributors
• Stack

Synopsis

Errandler-express.js is an open source Errandler gateway toolset for Express.js.

• 🪶 Very lightweight
• ⚡ High performance
• 🔧 Easy to use
• 📦 Only 1 dependency to log errors
• 🧪 Thoroughly tested
• 🚚 Shipped as ECMAScript Express module
• 📝 Written in TypeScript

Support

• node: 22

This is the oldest targeted version.

Installation

$ npm i @dwtechs/errandler-express

Error Flow

┌─────────────────┐
│ Error Occurs    │
│ next(error)     │
└─────────┬───────┘
          │
          ▼
┌──────────────────┐
│ Step 1: logError │
│ • Log stack      │
│ • Log message    │
│ • next(err) ─────┼──┐
└──────────────────┘  │
                      │
          ┌───────────┘
          ▼
┌───────────────────┐
│ Step 2: rollback  │
│ • Check db client │
│ • ROLLBACK        │
│ • Release conn    │
│ • next(err) ──────┼─┐
└───────────────────┘ │
                      │
          ┌───────────┘
          ▼
┌───────────────────┐
│ Step 3: clientErr │
│ • Get status      │
│ • Send response   │
│ • END CHAIN       │
└───────────────────┘

┌──────────────────┐
│ No route matches │ 
│ • Unmatched URL  │
│ • Send 404       │
└──────────────────┘

Database Transaction Rollback

The error handling pipeline automatically manages database transaction rollback when errors occur, ensuring data consistency and preventing connexion leaks.

The rollbackTransaction middleware automatically detects a database client stored in res.locals.dbClient and performs rollback operations when errors occur:

1. Detects Active Transaction: Checks for database client in res.locals.dbClient
2. Executes ROLLBACK: Runs ROLLBACK command to undo pending changes
3. Releases Connection: Returns connection to pool preventing memory leaks
4. Cleans Up: Sets res.locals.dbClient to undefined

Requirements

• Database client must be stored in res.locals.dbClient
• Client must have query(sql) and release() methods
• Transaction should be active (BEGIN already executed)

Usage

Error Handler

// @ts-check
import express from "express";
// const cors = require("cors");
import { log } from '@dwtechs/winstan';
import { errorHandler } from "@dwtechs/errandler-express";
import { listen } from "@dwtechs/servpico-express";

const app = express();
app.disable("x-powered-by");

// Mandatory modules for any service
import health from "health";
 
// import services
// import middlewares
// import routes

app.use(express.json());
app.use("/health", health);

// Routes
app.use("/xx", ...);
app.use("/xxx", ...);


// Error handling
errorHandler(app);

// Init reference data
Promise.all([
    data1.init(), 
    data2.init(),
  ])
  .then(() => listen(app))
  .catch((err) => log.error(`App cannot start: ${err.msg}`));

Error Codes

import { 
  EC_CLIENT_BAD_REQUEST, 
  EC_CLIENT_UNAUTHORIZED, 
  EC_CLIENT_FORBIDDEN, 
  EC_CLIENT_NOT_FOUND,
  EC_CLIENT_CONFLICT,
  EC_CLIENT_MALFORMED_SYNTAX,
  EC_CLIENT_TOO_MANY_REQUESTS,
  EC_SERVER_INTERNAL_ERROR, 
  EC_SERVER_SERVICE_UNAVAILABLE
 } from '@dwtechs/errandler-express';

// Create custom errors with status codes
function createValidationError(message: string) {
  const error = new Error(message);
  error.statusCode = EC_CLIENT_BAD_REQUEST;
  return error;
}

// Use in middleware
app.use('/api/protected', (req, res, next) => {
  if (!req.user) {
    return res.status(EC_CLIENT_UNAUTHORIZED)
              .send('Authentication required');
  }
  next();
});

// Error handling in routes
app.get('/api/users/:id', async (req, res, next) => {
  try {
    const user = await getUserById(req.params.id);
    if (!user) {
      return res.status(EC_CLIENT_NOT_FOUND)
                .send('User not found');
    }
    res.json(user);
  } catch (error) {
    error.statusCode = EC_SERVER_INTERNAL_ERROR;
    next(error);
  }
});

API Reference

/**
 * Exported HTTP Error Status Codes grouped by category
 * Client Error Responses (4xx)
 * These errors indicate that the client made an error in the request
 * Server Error Responses (5xx)
 * These errors indicate that the server encountered an error 
 */
const EC_CLIENT_BAD_REQUEST = 400; // 400 - The server cannot process the request due to client error 
const EC_CLIENT_UNAUTHORIZED = 401; // 401 - Authentication is required and has failed or not been provided
const EC_CLIENT_FORBIDDEN = 403; // 403 - The client does not have access rights to the content
const EC_CLIENT_NOT_FOUND = 404; // 404 - The server cannot find the requested resource
const EC_CLIENT_CONFLICT = 409; // 409 - Request conflicts with the current state of the server
const EC_CLIENT_MALFORMED_SYNTAX = 422; // 422 - The request was well-formed but contains semantic errors
const EC_CLIENT_TOO_MANY_REQUESTS = 429; // 429 - The user has sent too many requests in a given time
const EC_SERVER_INTERNAL_ERROR = 500; // 500 - The server encountered an unexpected condition */
const EC_SERVER_SERVICE_UNAVAILABLE = 503; // 503 - The server is not ready to handle the request */

/**
 * Sets up comprehensive error handling middleware for an Express application.
 * This function configures a complete error handling pipeline that should be registered
 * after all other middleware and routes to properly handle errors and invalid paths.
 * 
 * The middleware stack is applied in the following order:
 * 1. **Error Logging** - Logs error details for debugging and monitoring
 * 2. **DB Transaction Rollback** - Rolls back database transactions on errors (PostgreSQL)
 * 3. **Client Error Response** - Sends formatted HTTP error responses to clients
 * 4. **Invalid Path Handling** - Handles 404 errors for undefined routes
 * 
 * @param {Application} app - The Express application instance to configure with error handlers
 * 
 * @returns {void} Configures the application with error handling middleware
 * 
 * @example
 * ```typescript
 * import express from 'express';
 * import { errorHandler } from './error';
 * 
 * const app = express();
 * 
 * // Configure your routes and middleware first
 * app.use(express.json());
 * app.get('/api/users', getUsersHandler);
 * app.post('/api/users', createUserHandler);
 * 
 * // Apply comprehensive error handling (should be last)
 * errorHandler(app);
 * 
 * app.listen(3000, () => {
 *   console.log('Server running with error handling configured');
 * });
 * ```
 * 
 */
function errorHandler(app) {}

Error Code Reference

Code	Value	Description
EC_CLIENT_BAD_REQUEST	400	The server cannot process the request due to Client error
EC_CLIENT_UNAUTHORIZED	401	Authentication is required and has failed or not been provided
EC_CLIENT_FORBIDDEN	403	The Client does not have access rights to the content
EC_CLIENT_NOT_FOUND	404	The server cannot find the requested resource
EC_CLIENT_CONFLICT	409	Request conflicts with the current state of the server
EC_CLIENT_MALFORMED_SYNTAX	422	The request was well-formed but contains semantic errors
EC_CLIENT_TOO_MANY_REQUESTS	429	The user has sent too many requests in a given time
EC_SERVER_INTERNAL_ERROR	500	The server encountered an unexpected condition
EC_SERVER_SERVICE_UNAVAILABLE	503	The server is not ready to handle the request

Logs

Errandler-express.js uses @dwtechs/Winstan library for logging. All logs are in debug mode. Meaning they should not appear in production mode.

Contributors

Errandler-express.js is still in development and we would be glad to get all the help you can provide. To contribute please read contributor.md for detailed installation guide.

Stack

Purpose	Choice	Motivation
repository	Github	hosting for software development version control using Git
package manager	npm	default node.js package manager
language	TypeScript	static type checking along with the latest ECMAScript features
module bundler	Rollup	advanced module bundler for ES6 modules
unit testing	Jest	delightful testing with a focus on simplicity