Forem: Nse569h

DS Express Errors (centralizing errors library) — v1.8.0 & v1.8.1 Release Notes

Nse569h — Mon, 12 Jan 2026 13:02:41 +0000

v1.8.0 – January 11, 2026

Added support for user-provided error classes in custom mappers (Zod, Joi)
Added support for turning only needed mappers in config
Rate limiting logger
Express-validator mapper fix incorrect logic
Expand prisma errors ['P2005', P2006, P2007, P2011, P2027]
updated mongoose & sequelize mappers check

What is mean?

Starting with version v1.8.0+, you will be able to choose which mappers to enable so as not to use unnecessary ones, reducing the cost of checking unnecessary mappers.

This version also adds the ability (currently only with Zod and Joi) to pass library classes via setConfig for more rigorous verification. By default, the ds-express-errors library uses duck typing verification, which in turn allows it to remain dependency-free. The ability to pass your own error classes preserves this feature of the library.

Previously, the library's built-in loggers did not have a rate limit, which could cause crashes and freezes.

Small improvements:

New Prisma errors have been added, and the verification logic has been improved in some mappers.

Also, starting with this update, the built-in loggers support colour output for easier reading.

v1.8.1 – January 12, 2026

Fixed missing api import for logDebug
maxLoggerRequests new property in config to set maximal log rate requets per 1 minute (default 100)
Added check for BigIntfor internal safeStringifymethod
Fixed incorrect status code in mongoose mapper
Fixed incorrect status code in sequelize mapper
Logger refactor for customLogger
Added Errors.GatewayTimeout(message)
Fix mapping sequileze now correct map:
- SequelizeOptimisticLockError,
- SequelizeEmptyResultError,
- SequelizeDatabaseError,
- SequelizeConnectionError
- SequelizeTimeoutError

Website: Official documentation ds-express-errors

Website Changelog: Official ds-express-errors Changelog

Website Roadmap: Official ds-express-errors Roadmap

Have a idea?: ds-express-errors discussions

DS Express Errors — v1.7.0 & v1.7.1 Release Notes

Nse569h — Tue, 06 Jan 2026 14:55:30 +0000

In this post, I’m covering updates from v1.7.0 and v1.7.1.
Version 1.7.0 introduced new features and internal improvements, while 1.7.1 focuses on bug fixes, security hardening, and stability.

ds-express-errors v1.7.0 – January 5, 2026

Changes

Added express-validator support
Updated error mapping logic for Mongoose and Prisma
Added validation checks for setConfig
Refactored internal error handling logic
Fixed a logger-related bug

What this means

Version 1.7.0 improves validation support, provides more reliable database error mapping, and strengthens overall logging behavior.

ds-express-errors v1.7.1 – January 7, 2026

This patch release focuses on security, stability, and edge-case fixes discovered shortly after v1.7.0.

Security

Fixed a log injection vulnerability in the internal logger

Fixes & Improvements

Improved validation checks for setConfig to prevent invalid configurations
Fixed a crash in custom mappers when returning Promises or async functions
Enhanced environment configuration checks for safer runtime detection
Added a missing fallback statusCode in defaultErrorAnswer to prevent unexpected 500 responses

Why you should upgrade

If you use custom mappers, custom configuration, or rely on internal logging, upgrading to v1.7.1 is strongly recommended for improved safety and reliability.

Upgrade Notes

Update to the latest version:

npm install ds-express-errors@latest

Additional notes:

express-validator: Make sure validators are properly registered in your routes to take full advantage of the new support.

Custom mappers / setConfig: Ensure your configuration and custom mappers follow the validation rules to avoid runtime errors.

Example usage:

const { setConfig, errorHandler } = require('ds-express-errors');

setConfig({
  customLogger: logger,
  customMappers: [
    (err) => {
      if (err.name === 'newError') {
        return Errors.BadRequest();
      }
    }
  ],
  devEnvironments: ['development', 'dev'],
  formatError: (err, { req, isDev }) => ({
    success: false,
    error: {
      code: err.statusCode,
      message: err.message,
      ...(isDev ? { debug_stack: err.stack } : {})
    }
  })
});

const app = express();
// ... your routes ...
app.use(errorHandler);

More details:

Website & full changelog: ds-express-errors changelog

Don't Let Your Node.js App Die Ugly: A Guide to Perfect Graceful Shutdowns

Nse569h — Fri, 26 Dec 2025 14:43:15 +0000

We spend hours perfecting our CI/CD pipelines, optimizing database queries, and writing clean code. But we often ignore one crucial part of the application lifecycle: Death.

When you deploy a new version of your app to Kubernetes, Docker Swarm, or even PM2, the orchestrator sends a SIGTERM signal to your running process.

If you don't handle this signal, Node.js might terminate immediately. Active HTTP requests are severed, database connections remain open (ghost connections), and transactions might be left in limbo.

Today, I want to show you how to handle this professionally using ds-express-errors, specifically diving deep into its Graceful Shutdown API.

The "Zero-Dependency" Approach

I built ds-express-errors primarily for error mapping, but I included a robust shutdown manager because I was tired of pulling in extra dependencies just to catch a SIGINT.

The library has 0 dependencies, meaning it's lightweight and secure.

The Full Configuration (Not Just the Basics)

Most tutorials only show you how to close the server. But real production apps need more: they need to distinguish between a "Planned Shutdown" (Deployment) and a "Crash" (Uncaught Exception), and they need granular control over exit behavior.

Here is the complete API reference for initGlobalHandlers.

The Setup

First, install the package:

npm install ds-express-errors

Now, let's look at the "Power User" configuration in your entry file (e.g., index.js):

const express = require('express');
const mongoose = require('mongoose');
const { initGlobalHandlers, gracefulHttpClose } = require('ds-express-errors');

const app = express();
const server = app.listen(3000);

// The Complete Configuration
initGlobalHandlers({

    // 1. The HTTP Draining Mechanism
    // Wraps server.close() in a promise that waits for active requests to finish.
    closeServer: gracefulHttpClose(server),

    // 2. Normal Shutdown Logic (SIGINT, SIGTERM)
    // This runs when you redeploy or stop the server manually.
    onShutdown: async () => {
        console.log('SIGTERM received. Closing external connections...');

        // Close DB, Redis, Socket.io, etc.
        await mongoose.disconnect();

        console.log('Cleanup finished. Exiting.');
    },

    // 3. Crash Handling (Uncaught Exceptions / Unhandled Rejections)
    // This runs when your code throws an error you didn't catch.
    onCrash: async (error) => {
        console.error('CRITICAL ERROR:', error);

        // Critical: Send alert to Sentry/Slack/PagerDuty immediately
        // await sendAlert(error); 
    },

    // 4. Exit Strategy for Unhandled Rejections
    // Default: true. 
    // If false, the process continues running even after an unhandled promise rejection.
    // (Recommended: true, because an unhandled rejection can leave the app in an unstable state)
    exitOnUnhandledRejection: true,

    // 5. Exit Strategy for Uncaught Exceptions
    // Default: true.
    // If false, the app tries to stay alive after a sync error. 
    // (High risk of memory leaks or corrupted state if set to false).
    exitOnUncaughtException: true
});

Breakdown of the Options

Let's dissect what we just wrote. The initGlobalHandlers function accepts an options object with these specific keys:

closeServer

Type: Function (Async)

This is where you handle the HTTP layer. The library provides a helper gracefulHttpClose(server) which listens for the abort signal and handles the callback hell of the native Node.js server.close(). It ensures no new connections are accepted, but keeps the process alive until existing users finish their requests.

onShutdown

Type: Function (Async)

This is for your business logic cleanup. It is triggered only by system signals (SIGINT, SIGTERM, SIGQUIT).
This is the "Happy Path" of death. You should:

Close Database connections.
Flush logs.
Cancel long-running jobs.

onCrash

Type: Function (Async)

This is unique. Many libraries treat a crash the same as a shutdown. But ds-express-errors separates them. onCrash is triggered by uncaughtException or unhandledRejection.

Why separate them?

In onShutdown, you are calm. In onCrash, the house is on fire. You might not want to wait for a graceful DB disconnect; you might want to fire a "HELP ME" alert to Slack and die immediately.

exitOnUnhandledRejection & exitOnUncaughtException

Type: Boolean (Default: true)

By default, the library follows Node.js best practices: fail fast. If the process state is corrupted (unhandled error), it logs the error, runs onCrash, and exits with code 1.

However, if you have a specific requirement to keep the process alive (perhaps you have an external supervisor or a very specific resilience strategy), you can toggle these to false.

The Safety Net: Timeouts

What if your onShutdown logic hangs? What if mongoose.disconnect() never resolves?

You don't want your pod to hang in the "Terminating" state forever (Kubernetes will eventually SIGKILL it anyway).

ds-express-errors wraps your shutdown logic in a 10-second timeout. If your cleanup functions don't resolve by then, it forces an exit to prevent zombie processes.
Conclusion

Handling process termination is part of being a senior engineer. It distinguishes a "hobby project" from a reliable distributed system.

With ds-express-errors, you don't need complex boilerplate. You get a fully typed, zero-dependency solution that handles both graceful shutdowns and critical crashes out of the box
.
Links:

Happy coding (and happy shutting down)! 🔌

I finally stopped writing try-catch in every Express controller (and you should too)

Nse569h — Thu, 25 Dec 2025 01:15:36 +0000

Let’s be honest for a second. We all hate writing error handling in Express.

You start with a beautiful, clean controller function. It’s supposed to do one thing: register a user. But then reality hits. You need to validate the body. You need to check if the email exists in MongoDB. You need to catch unexpected crashes.

Before you know it, your 5-line function has turned into a 50-line spaghetti monster wrapped in a massive try/catch block.

I used to copy-paste this boilerplate from project to project until I found a cleaner way. Recently, I started using ds-express-errors, and it actually made coding backend logic fun again.

Here is how I cleaned up my code.

The "Old Me" Approach 🍝

This is actual code from one of my old projects. It hurts just looking at it.

// controllers/authController.js
const User = require('../models/User');

exports.register = async (req, res, next) => {
  try {
    // 1. Manually checking for missing fields... boring.
    if (!req.body.email || !req.body.password) {
        return res.status(400).json({ status: 'error', message: 'Missing fields' });
    }

    const newUser = await User.create(req.body);

    res.status(201).json({ success: true, data: newUser });

  } catch (err) {
    // 2. The "Error parsing hell"
    // Is it a validation error? A duplicate key? Who knows?
    if (err.name === 'ValidationError') {
        const msg = Object.values(err.errors).map(val => val.message).join(', ');
        return res.status(400).json({ success: false, message: msg });
    }

    if (err.code === 11000) {
        return res.status(409).json({ success: false, message: 'Email already taken' });
    }

    // 3. Just giving up
    console.error(err);
    res.status(500).json({ success: false, message: 'Server Error' });
  }
};

If you have 20 controllers, you have 20 copies of this catch block. If you change your error response format, you have to refactor everything.

The "New Me" Approach ✨

I switched to using ds-express-errors because it specifically handles the heavy lifting for libraries I already use (Mongoose, Prisma, Zod).

Here is the exact same controller rewritten.

// controllers/authController.js
const User = require('../models/User');
const { asyncHandler, Errors } = require('ds-express-errors'); //

// No try-catch. Just logic.
exports.register = asyncHandler(async (req, res) => {
    const newUser = await User.create(req.body);

    // Need to throw a custom error? Easy.
    if (!newUser) {
        throw Errors.BadRequest('Could not create user'); //
    }

    res.status(201).json({ success: true, data: newUser });
});

That’s it.

"Wait, what happens if MongoDB throws an error?"

That's the cool part. The library's middleware automatically detects that it's a Mongoose error.

If it's a Duplicate Key (E11000) -> It sends a 400 Bad Request with "Duplicate field value entered".
If it's a Validation Error -> It joins your validation messages and sends a 400.
If it's a JWT Error -> It sends a 401 Unauthorized.

I didn't have to write a single if statement for that.

Setup is stupidly simple

I hate complex configs. Luckily, this is just a middleware drop-in.

In your app.js or index.js:

const express = require('express');
const { errorHandler } = require('ds-express-errors'); //

const app = express();

// ... define your routes here ...

// Just put this at the END of your middleware chain
app.use(errorHandler);

app.listen(3000, () => console.log('Server is flying 🚀'));

Bonus: Sleeping better at night (Graceful Shutdown) v1.5.0

Another thing I used to ignore was proper server shutdown. If my app crashed or Docker restarted the container, active requests would just get cut off. Users would lose data.

This lib has a built-in helper for this. It ensures the server closes connections properly before dying.

const { initGlobalHandlers, gracefulHttpClose } = require('ds-express-errors'); //

const server = app.listen(PORT);

initGlobalHandlers({
    // Wraps the server close method safely
    closeServer: gracefulHttpClose(server),

    // Close your DB connections here
    onShutdown: async () => {
        console.log('Closing DB...');
        await mongoose.disconnect();
    }
});

Now, if I get a SIGTERM or an unhandled rejection, the app cleans up its mess before exiting.

Verdict

There are a million error handlers out there, but I stick with this one because it has zero dependencies and supports TypeScript out of the box. It just removes the noise from my code.

Link: ds-express-errors documentation

Standardizing Express.js Error Handling with One Library

Nse569h — Fri, 05 Dec 2025 10:52:21 +0000

If you've been working with Express.js error handling for a while, you know the struggle. What starts as a simple project quickly turns into controllers filled with repetitive try/catch blocks and scattered status code logic:

// The "Bad" Way
app.post('/users', async (req, res) => {
  try {
    // ... logic
  } catch (error) {
    console.error(error);
    if (error.code === 'P2002') { // Prisma unique constraint
        return res.status(400).json({ message: 'User already exists' });
    }
    // ... 10 more if/else checks
    res.status(500).json({ message: 'Something went wrong' });
  }
});

It's repetitive, hard to maintain, and prone to bugs. I got tired of copy-pasting error handling logic between my projects, so I built a tool to fix it once and for all.

Meet ds-express-errors zero dependencies library!

Why you need centralized error handling in Express.js

Express developers often search for best practices to avoid repetitive try/catch blocks, inconsistent status codes, and unreadable controller logic. ds-express-errors solves these issues by providing a structured, predictable, and type-safe error handling flow for Express.js applications.

Here is why I think it's worth checking out:

Ready-to-use Error Presets for Express.js 🛠️

Forget about remembering if "Forbidden" is 401 or 403. Just use the presets.

import { Errors } from 'ds-express-errors';

if (!user) {
  throw Errors.NotFound('User not found'); // Automatically sends 404
}

if (!user.hasAccess) {
  throw Errors.Forbidden('Access denied'); // Automatically sends 403
}

Auto-Mapping for Zod, Joi, Prisma, Mongoose, Sequelize, JWT Errors 🪄

This is my favorite part. If you use Zod, Joi, Prisma, Mongoose, Sequelize, JWT, the library automatically detects their native errors and converts them into readable HTTP 400 Bad Requests.

Example with Zod:
You don't need to manually parse error.issues.

Input (Invalid):

{
    "issues": [
        {
            "path": ["user", "email"],
            "message": "Invalid email address"
        },
    ],
    "name": "ZodError"
}

Output (Automatic):

{
  "status": "fail",
  "method": "GET", // showed when development environment,
  "url": "/login", // showed when development environment,
  "message": "Validation error: user.email: Invalid email address;",
  "stack": // showed when development environment,
}

No More try/catch in Express Controllers

With the included asyncHandler, your controllers become clean again.

import { asyncHandler, Errors } from 'ds-express-errors';

const createUser = asyncHandler(async (req, res) => {
  const user = await db.create(req.body); // If this throws, it's handled automatically!
  res.json(user);
});

Graceful Shutdown in Node.js & Express.js (v1.4.1)

A graceful shutdown in Express.js ensures your Node.js application can handle critical process-level errors such as uncaughtException and unhandledRejection without immediate crashes.

This approach allows the server to close database connections safely and predictably before the application stops, improving reliability and stability in production.

Implementing a proper Node.js graceful shutdown mechanism helps maintain data integrity and prevents abrupt termination of your Express server.

import { initGlobalHandlers } from 'ds-express-errors';

initGlobalHandlers({
  // Optional: Prevent exit on unhandledRejection (default: true)
  exitOnUnhandledRejection: true,

  // Async callback with error access
  onCrash: async (err) => {
    console.error('CRASH DETECTED:', err.message); // Access the error!

    // Send alert to Sentry/Telegram
    await sendAlertToAdmin(err);

    // Close resources
    await db.disconnect();
    console.log('Cleanup finished.');

    // The library will automatically execute process.exit(1) after this function
  }
});

Configuration (Custom Response Format)

You can customize the structure of the error response sent to the client. This is useful if you need to adhere to a specific API standard (e.g., JSON:API) or hide certain fields.

Customize the dev environment by using devEnvironments: []

Looking to manage an error from a library that isn’t natively supported? Or do you want to modify the standard behavior? You can pass an array of customMappers.

Use setConfig before initializing the error handler middleware.

import { setConfig, errorHandler } from('ds-express-errors');

// Optional: Customize response format
setConfig({
// Your Winston/Pino logger
    customLogger: logger, 
    customMappers: [
        (err, req) => {
            if (err.name === 'newErrorWithReq') {
                return Errors.Forbidden(`[${req.baseUrl}] ${err.message}`)
            }
            //... other if
        }
    ],
    devEnvironments: ['development', 'dev'],
    formatError: (err, {req, isDev}) => {
        return {
            success: false,
            error: {
                code: err.statusCode,
                message: err.message,
                // Add stack trace only in development
                ...(isDev ? { debug_stack: err.stack } : {})
            }
        };
    }
});

const app = express();
// ... your routes ...
app.use(errorHandler);

Default Format
If no config is provided, the library uses the default format:

{
  "status": "error", // or 'fail'
  "method": "GET", // showed when development environment
  "url": "/api/resource", // showed when development environment
  "message": "Error description",
  "stack": // showed when development environment,
}

Default Config Format

let config = {
    customMappers: [],
    devEnvironments: ['dev', 'development'],
    formatError: (err, {req, isDev}) => ({ 
        status: err.isOperational ? 'fail' : 'error',
        message: err.message,
        ...(isDev ? { 
            method: req.method,
            url: req.originalUrl,
            stack: err.stack
         } : {})
    })
}

📦 How to use it?

Installation is standard:

npm install ds-express-errors

📚 Documentation

I've built a full documentation website where you can see advanced usage, API references, and more examples:

👉ds-express-errors official documentation

FAQ

1. Does ds-express-errors replace Express’s default error handler?

Yes—it extends it with a fully typed and configurable error-handling layer.

2. Does it work with TypeScript?

Absolutely. The library is built with full TypeScript support.

3. Can I use it with Zod, Joi, Prisma, Mongoose, Sequelize, express-validator, or JWT?

Yes—the auto-mapping feature automatically converts their native errors into consistent HTTP responses.

Conclusion

This library allowed me to finally unify and simplify Express.js error handling across my Node.js projects. If you want predictable status codes, type-safe errors, and cleaner controllers without endless try/catch blocks, ds-express-errors can save you a lot of time.

Please don't hesitate to try it out and share your feedback. A star on GitHub means a lot. ❤️