🧪 Feedback (developer/tester)

[Dianka05]

This section contains feedback by the library’s testers.

All reviews include the version, the stack, and a link to the repository where the library was used. They also include a disclosure.
For more information on what this means, see the link

[guilherme-teixeira-gomes]

Library version tested: ds-express-errors v1.9.0
Stack: Node.js 18 · Express 5 · TypeScript 5.5 (strict) · Zod 4.4.3
Experience level: Senior
Overall rating: 8/10

I'd actually split that: the library itself is a 9, the documentation is closer to a 6. Everything I hit went wrong in the docs, not in the code.

What I built

A small Express + TypeScript API with five routes, each designed to trigger a different path through the error handler: a NotFound preset, a Zod validation failure, an unmapped throw inside asyncHandler, an unmapped throw in a synchronous handler, and a catch-all 404. Source: https://github.com/guilherme-teixeira-gomes/teste-ds-express-errors

I came to this with a specific bias: I maintain a hand-rolled centralized error handler in my own project, mapping ZodError, Postgres constraint codes and a domain error class. So I was reading this as "would I delete my own code for this."

What worked

The zero-dependency claim is real — I checked, dependencies is empty. That matters more to me than bundle size. Every transitive dependency is attack surface I didn't choose, and the supply-chain incidents of the last few years all came through packages nobody deliberately installed. A library I can audit in one sitting is worth a lot.

It ships its own index.d.ts, so no separate @types package. tsc --noEmit with strict: true passed clean against my whole test app — no casts, no any leaking in from the middleware signature. The "type-safe" claim holds up.

Errors.NotFound(...) reads better than remembering that not-found is 404. Small thing, but the kind that compounds across a codebase.

Unmapped errors became 500 without taking the process down, in both the async and the sync handler. Worth noting the sync case works even though asyncHandler doesn't wrap it — that surprised me in a good way.

The server log is genuinely well designed. Timestamp, method, route, message, status, and Operational: true/false. That last flag is the useful one: in production it's the difference between "a user sent bad input" and "wake someone up." I'd have expected to build that distinction myself.

Three problems

1. The 404 example crashes on boot under Express 5.

The "Handling 404" section shows:

 ```js app.use('*', (req, res, next) => { ... }) ``` 

With express@5 — what npm install express gives you today — that throws before the server ever listens:

PathError: Missing parameter name at index 1: *

path-to-regexp no longer accepts a bare '*'. Dropping the path entirely fixes it. This was the first error I hit, and it's the worst kind: someone following the docs on a fresh project can't start their app, and the error points at path-to-regexp, not at anything they wrote.

2. The Async Handler example doesn't run.

js
const createUser = asyncHandler(async (req, res) => {
const newUser = await db.create(req.body);
if (!newUser) return next(Errors.BadRequest('Invalid data'));
...
}));

next is used but not in the parameter list — ReferenceError at runtime. And there's an extra closing paren at the end. Copy-paste doesn't work.

3. Validation detail depends on NODE_ENV, and that isn't documented.

This one cost me the most time. Running with tsx watch and no NODE_ENV set, a Zod failure returned:

json
{ "status": "fail", "message": "Validation error: validation error" }

I assumed the Zod 4 mapper was broken — the docs promise "Validation error: email: Invalid email". I was about to write it up as a bug.

With NODE_ENV=development:

json
{
"status": "fail",
"message": "Validation error: name: Too small: expected string to have >=2 characters; email: Invalid email address",
"method": "POST",
"url": "/users",
"stack": "..."
}

Zod 4 works perfectly. The docs only say that "url, stack, method are available in development mode" — they don't say the message itself collapses.

I'd argue these are two different concerns. Hiding stack and internal paths in production is correct. But which field failed validation is the client's own input — that's not a leak, and stripping it means an API consumer gets a 400 with no idea what to fix. At minimum the behaviour needs documenting, with a setConfig example showing how to change it.

Would I use it?

In a new project, yes — without hesitation. Mongoose duplicate-key handling alone is something I've written by hand more times than I want to count, and getting Prisma, JWT and Zod in the same package for zero dependencies is a good trade.

In my existing project, probably not, and not because of the library. I already have a handler with tests, and its response shape is what my frontend expects. Migrating would be work with no user-visible benefit. That's a "when you adopt it" answer, not a quality judgement.

What would move it to a 10

Fix the two broken examples. Document the NODE_ENV behaviour, or split message detail from stack exposure. Add one TypeScript example — "type-safe" is the first thing the homepage claims, and there isn't a single line of TS in Installation or Usage. And the Installation page renders "Current latest version:" with nothing after it.

Also: the only per-technology page is the Mongoose example. Zod and Prisma are advertised on the homepage and don't have one. As a Prisma + Zod user I had to work mine out from the API reference.

None of that is deep. It's an afternoon of documentation work on a library that already does the hard part correctly.

Disclosure: I received money compensation for independently testing ds-express-errors and providing my honest feedback. Payment was not dependent on whether my review was positive or negative.

[Dianka05]

Thank you for your feedback! This will be a great help to me in improving the library and making it easier to use! Appreciate it!

Upd: Typos and some documentation missing info are updated

[HaileabT]

Library version tested: ds-express-errors v1.9.0
Stack: Node.js 26.4 · Express 5.2· Prisma 7.9 · TypeScript 7 · Zod 4.4.3 · Prisma 7.9
Experience level: Junior
Overall rating: 9/10

I built a small player and guilt management api with minimal business logic. Find it at: https://github.com/HaileabT/player-guilds

Good Side

Documentation is short, easy to understand and not overwhelming like most libraries I try to use.

It has good amount of configuration with zero initial configuration.

Package size being small and the package not having zero dependencies is I also one that I have noticed is very strong point.

Edge cases I have tested

I have tested edge cases such as throwing weird errors, calling the errorHandler middleware after I've already sent the response, throwing inside mappers, throwing inside globalErrorHandlers, and it seems to be handling them very nicely.

Things I think Could Use Some Improvement

• The tool seems to be throwing away the cause field of the Error class. I would love it if it preserved it, since cause can be very useful when debugging errors.

• PostgreSQL error code support would be valuable these days, since there are a lot of projects using Drizzle and they would benefit from PostgreSQL driver error handling. For example, 23505 represents a unique violation, which is commonly encountered when using drizzle-orm/node-postgres.

• I think the library could benefit from filtering its own internal stack frames from the final error stack. For example, errors currently include multiple ds-express-errors frames (errorHandler, errorMapper, zodMapper, etc.), which adds noise without providing much debugging value to the library consumer. Keeping the original application-level stack while omitting internal library frames would make the resulting stack trace much easier to read. (this is a very weak one but its because i get annoyed when stack traces are all crowded with the tool I'm using instead of showing me where in my code the problem started)

• In the configuration, needMappers could use a better name, such as enabledMappers, to make its purpose more straightforward.

• It would be better if I could control which logs are shown in production versus development. This would be especially useful for those of us who don't always use a dedicated logging library.

• As a suggestion, it would be better if basic configuration was shown on the installation or usage page.

• The documentation website needs some polishing. The documentation itself is short and sweet, but the overall presentation could be improved. It looks a bit outdated and laced with color. Something like https://better-auth.com/docs/introduction would work.

Would I use it

I personally found it very easy to use and it is a strong tool. I would use it in the future projects if the maintenance continues to be this active.

Would it work for production

I think it would, but it should include the log level configuration built in without needing a logging library to handle it.

Disclosure: I received money compensation for independently testing ds-express-errors and providing my honest feedback. Payment was not dependent on whether my review was positive or negative.

[Dianka05]

Hello, thank you for your feedback. As for support for DrizzleORM and Postgres, this is already in the plans and can be found in the Roadmap section.

Thank you for your work and advices! It really helps me understand which details I may have overlooked during development and maintenance.

[yadaw07]

ds-express-errors v1.9.1 — developer review

Stack tested: Node.js + Express 5 + TypeScript + Mongoose

Overall rating: 7/10

Developer experience level: Mid-level

---

I built a small Express 5 + TypeScript API with a Mongoose User model to exercise the library's error presets, asyncHandler, the Mongoose mapper (validation errors, cast errors, duplicate-key 11000), a native ReferenceError fallback, dev vs. production response shapes, and graceful shutdown via initGlobalHandlers/gracefulHttpClose. Source code: https://github.com/yadaw07/ds-express-errors-test

Installation and initial setup were painless — one package, no peer dependency headaches, and dropping errorHandler at the end of the middleware chain worked immediately.

Finding the docs was easy (the README links straight to ds-express-errors.dev), but I did have to hunt a bit to understand which config option controlled strict vs. duck-typed error detection — errorClasses isn't obviously named for that purpose until you read the whole Configuration section.

Two real TypeScript bugs I ran into, both reproducible:

1. Errors.UnprocessableContent and Errors.GatewayTimeout are documented in the preset table and work fine at runtime, but they're missing from index.d.ts. In a TypeScript project this is a compile error (TS2339: Property 'UnprocessableContent' does not exist...). If you're on JS you'd never notice; if you're on TS (which the README explicitly advertises support for, with .d.ts files), two of the thirteen documented presets are unusable without a type assertion workaround.

2. The Configuration section's own example passes Prisma inside errorClasses, but the ErrorClasses interface only declares Zod, Joi, and Sequelize — copy-pasting the documented example as-is throws TS2353: Object literal may only specify known properties, and 'Prisma' does not exist in type 'ErrorClasses'.

Both are easy fixes (just missing entries in the .d.ts files) but as written they undermine the "TypeScript support" claim for anyone actually compiling with strict mode.

On the Mongoose side specifically: worth noting for other Mongoose users that there's no errorClasses strict-check option for Mongoose the way there is for Zod/Joi/Sequelize/Prisma — Mongoose errors are always matched by duck-typing (err.name / err.code). That's fine in practice (it worked correctly for ValidationError, CastError, and a simulated 11000 duplicate-key error, mapping to 400/400/409 respectively, with sensible dev-mode messages), but it's an inconsistency worth documenting since every other integration gets the option and Mongoose doesn't.

One gap that isn't really the library's fault but bit me anyway: there's no built-in "not found" middleware, so you write your own catch-all route and call next(Errors.NotFound()). Fine — except the classic Express 4 pattern (app.use('*', (req, res) => ...)) throws at server startup under Express 5, because path-to-regexp now requires a named wildcard segment. Since the library advertises Express 5 support and ships a NotFound preset clearly meant for exactly this use case, I expected at least a one-line note about the Express 5 wildcard syntax change. I only found the fix by trial and error.

What worked well: the preset API (Errors.NotFound(...), etc.) is about as low-friction as this kind of thing gets, asyncHandler genuinely removes try/catch boilerplate, dev-mode error responses were detailed and useful for debugging, production mode correctly stripped stack/method/url, and graceful shutdown behaved exactly as documented once I ran the compiled build directly (a ts-node-dev quirk with signal forwarding gave a false negative on my first attempt — not a library issue).

Would I use it in production? With the two TS typing bugs fixed, yes — for a Node/Express API not already invested in a hand-rolled error-handling layer, this removes real boilerplate and the mapping coverage (Mongoose, Prisma, Sequelize, Zod, Joi, JWT, express-validator) is broader than most alternatives I've used. As it stands today, I'd hold off on a strict-mode TypeScript project until the .d.ts files catch up with the README.

---

Disclosure: I received monetary compensation for independently testing ds-express-errors and providing my honest feedback. Payment was not dependent on whether my review was positive or negative.

[Dianka05]

Thank you for catching these bugs! Adding the Prisma typing to errorClasses was actually already in development for the upcoming patch, but I completely missed the missing preset types, so I am really grateful you found them!

​I will definitely take your feedback on board and make sure to clarify certain points more explicitly in the documentation (like the Mongoose behavior). In the future, I also plan to add strict checking for Mongoose as well.
​Thanks again for the detailed and helpful review!

UPD: TS solved in v1.9.1

[Ashutoshbind15]

ds-express-errors v1.9.1 — developer review

7/10. The core request-error path is small, practical, and genuinely removes boilerplate. I would use the handler, presets, and custom mappers today. I would not yet delegate production validation responses, diagnostics, and process shutdown to the defaults without application-level overrides.

Test context	Details
Library	ds-express-errors@1.9.1
Stack	Node.js 25.9 · Express 5.2.1 · strict TypeScript · Zod 4.4.3 · Drizzle ORM + pg · pino · Basic Auth
Developer level	Senior
Test project	Ashutoshbind15/ds-express-errors-test
Verification	92 passing Vitest tests and a clean strict TypeScript build

Disclosure: I received monetary compensation for independently testing ds-express-errors and providing my honest feedback. Payment was not dependent on whether my review was positive or negative.

How findings are listed: The findings below are listed in the order I encountered them while working through the library and docs (top to bottom). They are not ranked by severity or importance.

What I tested

I integrated the library into an existing TypeScript CRUD API rather than a single demo route. The application has Zod request validation, Drizzle/pg persistence, Basic Auth with three authorization scopes, pino logging, and an HTTP server with database cleanup on shutdown.

The integration exercised:

• errorHandler as the final middleware, including JSON 404s for unmatched routes
• Errors.BadRequest, Unauthorized, Forbidden, NotFound, Conflict, InternalServerError, and ServiceUnavailable
• automatic Zod mapping in development and production environments
• a synchronous customMappers implementation for PostgreSQL/Drizzle errors
• pino through customLogger
• unknown errors and the generic 500 fallback
• initGlobalHandlers and gracefulHttpClose with signals, crashes, and timeouts
• ESM imports and strict TypeScript compilation

I did not install Prisma, Mongoose, Sequelize, Joi, JWT, or express-validator just to increase the feature count, so I am not making claims about those integrations.

What worked well

1. The main integration is small and composable

Registering one final error middleware and throwing Errors.* removed route-level try/catch, repeated status-code decisions, and hand-written 500 responses. The presets cover the HTTP errors I use most often, so this can also replace a separate HTTP-error package.

Incremental adoption was straightforward: I could introduce the handler and presets first, then add Zod detection, pino, the PostgreSQL mapper, and shutdown handling independently. The docs support that path well in the installation and usage sections.

2. Custom mappers solve real application gaps

Drizzle/pg is not built in, but customMappers was enough to centralize the errors this API actually produces:

• PostgreSQL 23505 → HTTP 409 with A todo with this title already exists
• connection failures such as ECONNREFUSED → HTTP 503 with Database unavailable
• undefined from my mapper → normal Zod or generic fallback processing

The custom mapper runs before built-in mappers, as documented. This let one mapper cover create and update operations without duplicating database-error catches in the service layer. Extensibility felt right: enough override surface without forcing a framework-wide abstraction.

3. The package is lightweight and works in a strict ESM project

The zero-dependency claim is accurate for v1.9.1. Imports worked with NodeNext/ESM, all exported APIs used by the project type-checked, and the application compiled in strict mode.

4. The normal shutdown path worked

On the happy path, SIGINT stopped the HTTP server, ran the database cleanup, closed the port, and exited successfully. gracefulHttpClose(server) is convenient compared with rewriting the server.close() Promise wrapper in each application. Having production-oriented shutdown helpers available — and extendible via onShutdown / onCrash — removed meaningful process-lifecycle boilerplate from my application code.

5. Docs discoverability and playground

The getting-started flow was easy to follow, and the site makes the major capabilities discoverable. The playground is a useful way to inspect response behavior quickly.

Findings and improvements

1. Production Zod responses discard the useful part of validation

Zod errors correctly map to HTTP 400. In development, the response identifies fields and messages:

{
  "status": "fail",
  "message": "Validation error: title: Invalid input: expected string, received undefined",
  "method": "POST",
  "url": "/todos"
}

For the same schema failure in production, the response becomes:

{
  "status": "fail",
  "message": "Validation error: validation error"
}

Hiding the stack, method, and URL in production is correct. Replacing every Zod issue — including application-authored messages such as "Title is required" — with the literal validation error is too aggressive. The client knows the request is invalid but cannot tell which field to correct. No issues or details value is included either.

I would keep debug fields private but surface issue.message (or add an opt-in such as includeValidationMessages), or pass the original mapped error into a formatter so an application can return its intentional client-facing validation copy. Today, achieving that requires reimplementing Zod detection and formatting in a custom mapper.

2. The Zod mapper flattens only the top-level issues array

Beyond the production sanitization above, the formatter itself is shallow. It maps each top-level issue to path.join('.') + message and never walks nested issue trees. In practice:

• invalid_union — branch failures live in issue.errors (Zod 4) / unionErrors (Zod 3). The client typically only sees a generic "Invalid input" and loses why each branch failed.
• invalid_key / invalid_element — nested issues on the issue object are ignored the same way.
• unrecognized_keys — extra keys sit on issue.keys; the mapper never reads them (it only keeps whatever Zod already put in message).

So even in development, some real Zod shapes produce weaker messages than the schema failure warrants. A recursive flatten (or exposing an issues array) would make validation responses substantially more useful.

3. Unknown production errors lose their diagnostic cause before logging

An unmapped error such as ENOTSUP: operation not supported correctly returns a generic production response:

{
  "status": "error",
  "message": "An unexpected error occurred."
}

The problem is that mapping creates the generic InternalServerError before logging. Both the default logger and my pino logger receive that mapped error, so the original name, message, code, and stack are no longer available in production logs. Client sanitization should not also sanitize server-side diagnostics.

The handler should log the original error with request context while sending the mapped error to the client.

4. Graceful shutdown has lifecycle gaps

The successful signal path works, but the implementation does not fully match the stronger shutdown claims:

1. Server draining and application cleanup run concurrently. closeServer and onShutdown are awaited with Promise.all. A database pool can therefore close while in-flight requests are still draining.
2. Crash handling does not run the normal server/database shutdown path. An uncaught exception or unhandled rejection runs onCrash and exits; it does not invoke closeServer or onShutdown.
3. Timeout does not actively force-close connections. Aborting gracefulHttpClose logs Force closing server and releases its Promise, but it does not call a socket-closing API. The subsequent process exit is what ultimately drops connections.

For a safer default, stop accepting requests, drain the server, then run database cleanup in sequence. The crash path should either reuse a documented cleanup sequence or clearly state that the caller must duplicate all cleanup in onCrash. A timeout advertised as a force-close should actually close remaining connections where the Node server API supports it.

5. Built-in mappers are replaceable, but not adjustable

The extension points are useful, but their boundaries should be clearer:

• customMappers run before all built-in mappers; a truthy result replaces the rest of mapping
• needMappers enables or disables built-ins
• formatError changes the final JSON body but cannot change the mapped HTTP status
• an AppError skips mapping entirely

There is no keyed override API such as overrideMappers: { zod: fn }. If I want Zod as HTTP 422 instead of 400, or field names in production instead of "Validation error: validation error", I have to reimplement Zod detection and formatting myself. I cannot wrap the built-in mapper or change only its status/message.

A keyed override API, or access to the original error and mapped result in formatError, would make customization substantially easier.

6. TypeScript works, but the IDE experience is thinner than “first-class”

The published declarations are sufficient for this project to compile, but they contain no JSDoc, examples, or parameter descriptions. Hovering setConfig, Errors.*, or the shutdown helpers gives types but does not explain behavior.

Some declarations also give up useful type information:

• needMappers is string[] rather than a union of supported mapper names ('zod' | 'joi' | 'mongoose' | ...), so IDE autocomplete does not guide valid values
• gracefulHttpClose accepts server: any
• the crash callback error is any
• asyncHandler accepts a handler returning any

Literal mapper names, Express/Node server types, unknown for caught errors, and short JSDoc examples would make the package much easier to learn without leaving the editor.

Documentation and API clarity

API / wording that confused me during integration

• Separate Express 4 and Express 5 guidance. Express 5 already forwards rejected promises from async handlers, so asyncHandler adds no value in this test stack. It remains useful for Express 4. The homepage’s “No try/catch needed” claim is accurate for the wrapper, but on Express 5 it can read like a Result/Effect-style promise (neverthrow, Effect) when the real win is centralized mapping and response consistency — not eliminating catch blocks as a paradigm.
• Prefer throw inside asyncHandler examples. Docs show patterns like return next(Errors.BadRequest('Registration failed')) and comments that say an example “throws” while the code uses next(...). That underplays the cleaner reason to use an async wrapper: throw Errors.BadRequest(...). For sync handlers, next(err) remains the Express-correct path; for async + asyncHandler, throw is the nicer DX.
• Explain the mapping pipeline. A short “original error → custom mapper → built-in mapper → formatError → HTTP response” section would remove ambiguity about which hook can change status, message, and body shape.
• Disambiguate status. The default formatError puts "status": "fail" | "error" on the JSON from isOperational. The HTTP status is always err.statusCode and is not taken from that JSON field. The JSON:API example then uses status a third way (err.statusCode.toString() inside the body). A reader can reasonably think formatError sets the HTTP code, or that it overlays mapping. It does neither — it only reshapes the response body after mapping.
• Document production diagnostics explicitly. The docs correctly emphasize hiding client details, but should also guarantee that the original error remains available to server-side logging.

Docs site UX notes

These are polish items from using the documentation site, not runtime defects:

• Make the zero-dependency / lightweight signals more prominent; that is a real selling point and matched what I observed in the package.
• Align before vs after code lists consistently, and show line numbers beside examples.
• Some emphasized words are underlined (for example around “provided before the error handler”). That can look like a link and is easy to mis-click mentally while reading.
• For starter kits, prefer a git clone flow over shipping zip files.
• In the Mongoose before/after example, show the shared schema once first, then the before and after handler files — the common setup is otherwise duplicated or easy to miss.
• A more subtle copy button on code blocks would reduce visual noise.
• On demo videos, reduce the music level; it competes with the narration.

Nice-to-haves

• Built-in Drizzle / pg mapping (I see Drizzle is already on the roadmap). Until then, customMappers covers the gap for this stack.
• A slicker docs UI would make early adoption even simpler for newcomers.

Verdict

I would use the centralized handler, presets, and custom mappers in my own Express projects. They removed meaningful boilerplate without forcing a framework-wide abstraction, and the package stayed easy to extend.

For a production application today, I would add my own Zod mapper (including nested-issue handling and client-facing messages), preserve/log original unknown errors before sanitizing responses, and keep shutdown orchestration in application code. Fixing those areas, plus improving the declarations and Express 5 / mapping-pipeline documentation, would move this from a useful toolkit to something I could adopt with far fewer safeguards.

[Dianka05]

Thank you for such detailed feedback. It’s been very helpful in understanding what I’d overlooked during development.

I’ll take all this on board and improve the quality of the library. In the foreseeable future, I plan to rewrite the library in pure TypeScript. In the meantime, I’ll remove the note about "First-Class" from the documentation site. Thank you for your guidance.

I’ll also look into the graceful shutdown issue in more detail.

I’ll also take note of the HTTP responses, improvements to the Zod mapper and other suggestions.

• logging
• allowing for greater freedom of customisation

I’ll also try to improve the quality of the documentation in line with the points you’ve highlighted.

Once again, my sincere thanks for such valuable feedback!

[techntools]

Tested against ds-express-errors v1.9.1

Stack: Node.js 24 | Express 4.19 | sequelize-typescript 2.1.6 | TypeScript 5.5.3

Experience level: Beginner

Score: 7/10 I liked the duck-typed vs strict mode in sequelizeMapper.js

I tested against Sequelize v6 ORM

I use code structure similar to this ds-express-errors-integration in production. I have integrated this lib into the repo. I replaced my own src/web/error.ts and src/store/error.ts with errorHandler. I was also using asyncHandler which this lib exports as Express 4 do not support them.

Check lines:

1. Using errorHandler
2. Using asyncHandler

Completely replaced my shutdown mechanism with initGlobalHandler and gracefulHttpClose. Check the commit 4c4241

Specific error classes can be used as well with setConfig({ errorClasses: { Sequelize: { ... }}}). Check commit b4ff0ab

Improvements

1. Use TypeScript to write the code as well. Do not just provide type definitions. Contributors may prefer TypeScript. I do.
2. Check dev env in errorHandler middleware and pass it further instead of checking it at multiple places

sequelizeMapper

1. Consider mirroring instanceof checks in duck-typed mode via err.constructor.name

2. Use a mapper table sequelizeErrorMap and common formatForPreset helper (removes duplication)

   const sequelizeErrorMap = [
       { match: e => e instanceof sequelize.ForeignKeyConstraintError, status: '400', preset: Conflict },
       { match: e => e instanceof sequelize.UniqueConstraintError,     status: '409', preset: Conflict },
       ...
   ]
   
   const formatForPreset = (entry, err, isDev) => {
       const { name, preset } = entry
       const isProdMsg = PROD_MESSAGES[name] // small lookup: 'unique conflict' / 'db error' / etc.
       const devDetail = buildDevDetail(err, name)   // per-error formatting helper
       return preset(`${isDev ? `${name}: ${devDetail}` : isProdMsg}`)
   }

3. Use if/else for determining is*Error with name. If a match is found, skip other matches.

4. Do not expose stack trace. Remove sql and code from message. You can map those codes to friendly user message. Already protected with isDevEnvironment but still remove as misconfigured NODE_ENV may leak them in production. But you can log them.

5. Add tests with actual express app with registered routes

** Disclosure: I received money compensation for independently testing ds-express-errors and providing my honest feedback. Payment was not dependent on whether my review was positive or negative.

[captain-something]

Tested against ds-express-errors v1.9.1

Stack: Node.js 24 | Express 5.2 | sequelize 6.37.8 | sequelize-typescript 2.1.6 | TypeScript 5.3.3 | Zod 4.4.3

Experience level: Senior

Score: 9/10 overall found it very easy to use.

I built a simple ExpressJS API with user accounts and authentication using ds-express-errors to manage exceptions, and a test suite that probed for catching NodeJS and Sequelize errors that arose unexpectedly.

Feedback

1. The setup was simple, standard Express middleware just app.use(...). It was nice to see the library doesn't have any dependencies which made it much easier to review and trust before installing and using it. This is a really big deal with all the "supply chain attacks" these days and as another reviewer said you don't mention it at all.

2. The library worked with import not just require which is appreciated, not everything is ESM yet which can be annoying.

3. Nice test coverage, this is also a helpful way to showcase how the software works since every test is basically an example.

Overall verdict: this would complement my development practices, mostly I favor using NestJS and this is functionally equivalent to what they consider an exception filter, it would make sense to offer a module providing it in that format.

Suggestions:

1. The presets provided by ds-express-errors made it easy to get started with common error handling patterns but extracting these as separate modules would allow third-parties to build additional support without needing to modify the core library. This also eliminates a "noisy" release cycle for the library maintaining the built-in integrations.

2. In the same note, I would split the library.test.js file into individual delegates for each of the presets: I'm using Sequelize so if I want to look at your tests to see example usage I have to find them... lines 217-378, which is much easier with library.sequelize.test.js and library.mongoose.test.js and library.prisma.test.js etc.

3. Complete lack of intellisense typing information, there's a lot of useful information in the readme but none of that carries through to the IDE, documenting your typedefs will often be helpful for users.

4. An option to use error codes would be helpful instead of error messages, messages usually need to be tailored to the frontend, maybe they need to be localized, maybe it is shorter on mobile resolutions or longer for administrative users. Using messages creates a dependency across-projects on the precise wording being used so if someone says "hey let's reword that slightly" it can have unintended side effects.

5. I like the formatError function for selectively including stacktrace and other information, but the logger only outputs the error code and it's useful to have this information flow through to CloudWatch or other logging software in production and testing environments.

«Disclosure: I received money compensation for independently testing ds-express-errors and providing my honest feedback. Payment was not dependent on whether my review was positive or negative.»

[Dianka05]

Thank you for your feedback. I’ll take note of your suggestions and comments. I’ll try to improve the DX for future releases (IDE, etc.).

I agree that it would be more convenient to split the tests from a single file into more compact ones, so that it is clearer where the tests for each library are located. Thank you.

I also liked your idea in point 4.

Regarding point 5, I am currently developing a more flexible configuration system, as the current one still has certain limitations.

Once again, my sincere thanks for all your hard work and your insightful feedback.

[anton-nagornyi]

Library version tested: ds-express-errors v1.9.1

Test stack: Node.js 26.7.0 + Express.js 5 + TypeScript + Prisma 7 + PostgreSQL + Zod

Developer level: Senior

Overall rating: 6/10

The library solves a useful problem and provides ready-made error mapping for common tools such as Prisma and Zod. The current documentation, configuration API, default response format, and several unexpected behaviors make the initial integration and debugging experience less convenient than expected.

Disclosure: I received monetary compensation for independently testing ds-express-errors and providing my honest feedback. Payment was not dependent on whether my review was positive or negative.

Testing Summary

I built a small Todo REST API with registration, JWT authentication, CRUD operations, PostgreSQL, Prisma, and Zod validation.

I tested the central error handler, error presets, Zod and Prisma mappers, errorClasses, needMappers, custom mappers, the default logger, and maxLoggerRequests.

The initial middleware integration was easy, and the error presets felt intuitive. The library removed some error-handling boilerplate, especially for known Prisma errors. Configuration behavior and mapper selection took more time to understand because the documentation did not explain them clearly enough.

The main issues were the default error response format, limited error details, unclear configuration options, CommonJS-only examples, unexpected mapper behavior, JWT mapping returning 500, and maxLoggerRequests appearing not to work.

The library does well at collecting common error-handling concerns in one place and supporting several popular validation and database libraries. The developer experience would improve with clearer configuration documentation, ESM examples, structured error details, selectable response formats, and more predictable mapper controls.

I would consider using the library in a small internal project. I would currently avoid using it in a production application without custom mappers and additional verification because several defaults and edge cases do not provide the response structure and predictability I expect.

Documentation (Inspected only the Github README.md)

1. The help on GitHub is inconveniently organized. I expected to see a basic configuration template directly in the Integration section, along with a link to the section that explains all configuration options in detail.

2. Many Node.js projects now use TypeScript and ESM by default. The documentation only contains CommonJS examples with require(). This makes the examples inconvenient to copy and paste into a modern TypeScript project. ESM imports should be used in the main examples.

Mapper Configuration

3. It was unclear how to disable error handling for a specific library such as Zod. The first thing I tried was removing Zod from errorClasses, but Zod errors were still handled. I had to set needMappers to an empty array to disable the mappers.

This behavior is not obvious. When needMappers is missing, all mappers are enabled. When it is an empty array, all mappers are disabled. The field combines several responsibilities.

I would rename needMappers to useMappers and add an optional disableMappers field where developers can list the mappers they do not want the handler to use.

Error Response Format

4. The default error response format is inconvenient. In my APIs, an error usually contains an internal error code, a message, and structured details similar to Zod issues. The library joins validation details into one string separated by semicolons. This format is difficult for people to read and difficult for clients to parse. I would prefer the details to remain an array of structured objects. Because of this, I would have to write custom mappers in almost every project, which reduces the value of the built-in mappers. I would add several commonly used response formats to the library and let users select one of them in the configuration. If details are returned separately from the message, it would also be useful to have a configuration option for hiding them. Some users may want to exclude detailed error information from public APIs.

Documentation Quality (Inspected only the Github README.md)

5. The documentation contains grammatical errors. For example, the sentence "the library used his own logger" uses his for a library. It should use its: "the library uses its own logger."

6. The purpose of devEnvironments is unclear. The documentation says that it can be used to customize development environments, but this does not explain what the field actually changes. It should clearly state that the value is compared with NODE_ENV and controls detailed error messages, stack traces, request data in responses, and logger output.

7. The documentation should describe every configuration field in more detail and show its default value. The current configuration snippet does not make the purpose, behavior, and defaults of the fields clear.

Error Mapping

8. A syntactically invalid JWT token returns a 500 Internal Server Error. This seems incorrect because an invalid authentication token should normally return 401 Unauthorized.

9. The documentation does not provide a list of supported authentication errors. It should show which JWT and authentication errors are recognized and which HTTP status and message each one produces.

Logging

10. The maxLoggerRequests configuration does not appear to work. I set it to 1 and sent the same invalid request several times, but the server continued to print every error log. The documentation also does not explain how this option works, what happens when it is set to 0, or what happens after the limit is reached. I initially expected behavior similar to Pino batching. I now understand that the option is intended to limit and discard logs, but this is not explained anywhere in the documentation.

11. Prisma error responses are not informative enough. A response such as {"status":"fail","message":"Conflict"} does not explain what caused the conflict. There are cases where developers and QA engineers need to see the reason and structured details. Without these details, testing and debugging microservices becomes unnecessarily difficult.

[Dianka05]

Thank you for such an in-depth analysis of everything. I’ll take all your comments on board.

Many thanks for identifying these critical issues.

1. I’ll make a note of this.

2. I’ll work on the README documentation. I’ll also make sure that, if there isn’t enough information in the README, it clearly links to the relevant section on the documentation website. Thank you

3. Yes, several testers have pointed out the poor naming to me; this will be improved in future releases. Thank you

4. This is currently in development; I’ve realised that the initial implementation turned out to be too cluttered and difficult. Thank you for further confirming that my implementation was poor!

• 5–7. I’ll take this on board and try to improve the developer experience (DX) for the README documentation.

8. I’ll try to fix this as soon as possible.

9. The description can be found here API References, but it seems they aren’t very user-friendly for finding out what types of errors the library recognises and what it returns. I’ll bear this in mind when updating the documentation!

10. Thanks for spotting that!

11. I agree about the message in prod – it’s a bit too sanitised.

[santisacri]

ds-express-errors v1.9.1 — Developer Review

Version tested: v1.9.1
Stack: Node v22.16, Express v5.2.1, TypeScript v7.0.2, Zod v4.4.3
Experience level: Junior
Overall rating: 7/10

I built a small REST APi with two related entities (Project/Task) to test the library, covering Prisma unique constraint violations, foreign key errors, not-found lookups, and Zod validation on both request body and query params, plus a couple of endpoints specifically built to trigger unmapped/unexpected errors.

Things that are wrong / I dislike

• In production mode, validation errors collapse to a generic "Validation error: validation error" message with no field-level detail. I understand hiding raw values or internals for security, but not exposing even which field failed makes debugging production issues harder than it needs to be. I'd like a config option to expose field names (not values) even when NODE_ENV !== development.
• When Prisma throws a Constraint Violation Error, the handler doesn't tell you which field failed when NODE_ENV is not dev.
• Documentation is the weakest part of the library and needs improvement:
  • Navigation UX isn't polished, clicking to the next page lands you at the bottom of that page instead of the top, so you have to scroll up every time.
  • There aren't enough code examples.
• Sometimes there's no autocomplete when there should be (e.g. the needMappers config).

What worked well

• Prisma and Zod error mapping both worked out of the box, returning detailed error descriptions while developing (NODE_ENV=development).
• No sensitive info (stack traces, raw Prisma error details) leaks when NODE_ENV is not development, the default production behavior is correctly locked down.
• Good amount of customization overall.
• Unexpected/unmapped errors are handled correctly and consistently, both when thrown inside asyncHandler and in a synchronous handler that isn't wrapped at all, the process stays up and returns a proper 500 either way.

Summary

Overall I think the library is going in the right direction: it's easy to get started, it's configurable, and it removes the need to write a custom error handler from scratch on every new project. Getting started was genuinely easy and quick, which matters a lot for adoption.

---

Disclosure: I received monetary compensation for independently testing ds-express-errors and providing my honest feedback. Payment was not dependent on whether my review was positive or negative.

[Dianka05]

Hello! Thank you for your feedback!

I am currently working on improving the responses in prod. I agree that the current implementation was extremely poor. Thank you!

I’ll do my best to address all the comments regarding the documentation and DX for needMappers. Thanks for pointing them out!

And once again, thank you for such high-quality feedback; it really helps me understand my zone for improving.

[Mithat3313]

ds-express-errors v1.9.1: developer test review

Library version tested: ds-express-errors v1.9.1
Test stack: Node.js + Express.js + TypeScript (strict) + Mongoose + Zod
Overall rating: 6/10
Developer experience level: Senior
Repository: https://github.com/Mithat3313/ds-express-errors-library-test

---

I built a small users API on Express + Mongoose with a couple of Zod-validated
endpoints. The schema has a required field, a minlength, an enum and a unique
index, so Mongoose throws ValidationError, CastError and E11000 without me
having to fake anything. I used asyncHandler, errorHandler, setConfig, the
presets, a hand-thrown AppError, and initGlobalHandlers with
gracefulHttpClose.

First impressions were good. Zero dependencies, nothing to generate, no plugin to
register. Wire errorHandler last, wrap your async routes, done. Getting a 409
out of a raw E11000 without writing that mapping myself is a real saving, and
409 is the right code where a lot of hand-written handlers just return 400.
Mongoose maps without injecting anything, which I did not expect given that
errorClasses has keys for Zod, Joi, Prisma and Sequelize but not Mongoose.

Then I started testing shutdown properly, and that is where most of my time went.

Graceful shutdown

Since this is the part you asked me to lean on, I wrote a harness that spawns a
real server per scenario, drives it into a specific socket state, sends a real
signal and records the timeline and exit code. It is in the repo under
tests/shutdown/ if you want to reproduce any of this.

Scenario	time to exit	exit code
idle server, SIGTERM	4ms	0
in-flight request, Connection: close	765ms	0
in-flight request, keep-alive socket	6771ms	0
idle TCP connection, no request ever sent	3011ms (= maxTimeout)	1
onShutdown (5s) exceeds maxTimeout (1.5s)	1518ms	1
onShutdown throws	5ms	1
closeServer omitted, request in flight	6ms	0, request dropped

Three things came out of this that I would want to know before shipping.

An idle socket blocks shutdown completely, and the process exits 1.
gracefulHttpClose is a thin wrapper around server.close(callback), and Node
only fires that callback once every socket is gone. It never calls
closeIdleConnections() or closeAllConnections(), both available since Node
18.2. So a TCP connection that is open but has never sent a request, which is
exactly what an idle load balancer socket or a keep-alive client looks like,
holds the close open until maxTimeout and then the process exits 1.

I checked that this is not just how server.close() behaves. Same server, same
socket state, only the closer differs:

socket state	gracefulHttpClose	close + closeIdleConnections()
idle socket, no request sent	still waiting at 6000ms	resolved in 2002ms
in-flight request, keep-alive	still waiting at 6000ms	resolved in 2003ms

Under Kubernetes or systemd a SIGTERM that ends in exit 1 reads as a failed
shutdown. With the default 10 second maxTimeout, a deploy behind a load
balancer holding keep-alive connections would take the full 10 seconds every
time and then report failure. The docs say the helper "stops accepting new
connections and waits for existing connections to complete", which is true in a
way that makes it worse: an idle socket has nothing to complete, so it never
does.

closeServer and onShutdown run at the same time, not one after the other.

  318  closeServer:start
  319  onShutdown:start
  319  onShutdown:end
 2020  slow:end            <- in-flight request finishes here
 6030  closeServer:end

onShutdown closed my Mongo connection at 319ms while a request that needed the
database was still running until 2020ms. Mine happened to survive because the
handler had already finished its queries, but that is luck. The usual contract
is stop accepting, drain, then tear down dependencies. Here both start together
under a Promise.all. Your own database cleanup example puts
mongoose.disconnect() in onShutdown next to a draining closeServer, so this
one is worth either fixing or calling out loudly.

After a crash the server keeps answering requests. On uncaughtException and
unhandledRejection only onCrash runs. closeServer and onShutdown are
never called, so the listener stays open for the whole onCrash window. I gave
onCrash a 2.5 second body and kept sending requests:

onCrash:start
request  800ms in -> HTTP 200
request 1800ms in -> HTTP 200
onCrash:end
exit 1

A process that has already hit an uncaught exception served traffic successfully
for the entire window, and with the default maxTimeout that window is 10
seconds. If onCrash reports to Sentry, as in your Crash Reporting example, it
lasts as long as that call. Both that example and the Complete Usage example pass
closeServer right next to onCrash, which reads like a promise that the server
gets closed here. It does not.

Debugging: the original error is gone

This is my other real complaint, and it is unrelated to shutdown.

By the time formatError runs, the error it receives is the library's
AppError. Not my error. I checked what actually arrives, and for both a
ZodError and a plain TypeError it is the same: constructor AppError, no
issues, no cause. The stack starts inside the library:

Stack: Error: Cannot read properties of null (reading '...')
    at InternalServerError (ds-express-errors/src/presets/presets.js:36:12)
    at mapErrorNameToPreset (ds-express-errors/src/presets/errorMapper.js:68:12)
    at errorHandler (ds-express-errors/src/middleware/errorHandler.js:18:30)

Not one frame points at my code. The message survives, the location does not.
For a library whose whole job is handling errors, losing where an unexpected
error came from is worse than Express's default behaviour.

The same thing costs me field-level validation. Zod's issues array is flattened
to a string before formatError can see it, so there is no supported way to
return {"errors": {"email": "..."}}. In production it collapses further, to the
literal "Validation error: validation error". Which field failed is not
sensitive information, so hiding it there is a cost to API clients rather than a
security win.

Both of these come from the same root, and setting cause on the generated
AppError and passing the original into formatError would fix them together.
I saw "Improvement of AppError: Stack trace" on the roadmap, so this may already
be on your list. I would put it first.

Documentation and the Detailed info section

Overall the docs were better than I expected for a beta. I mostly found what I
was looking for, and the Configuration page in particular is the best thing on
the site. I spot-checked its defaults against the source and they are exact, down
to devEnvironments: ['dev', 'development'] and maxLoggerRequests: 100. It
prints the real default formatError implementation instead of paraphrasing it,
documents the mapper execution order correctly, lists the six valid needMappers
names, and states the synchronous-only rule for customMappers. I trusted that
page and it earned it.

The graceful shutdown page is the weak one, and coming from Configuration the
drop was noticeable. Everything it says about API shape is right: both
signatures, the 10000ms default stated twice, the three callback shapes, and the
genuinely counter-intuitive note that onCrash does not fire when you disable
the exit flags. If the question is "what do I type", it answers it. If the
question is "what will my process do", it answers almost nothing, and the few
behavioural claims it does make are the ones that misled me.

The questions I had while integrating, that the page does not answer:

• In what order do closeServer and onShutdown run? (concurrently)
• Does onShutdown run on a crash? (no)
• What happens when maxTimeout elapses? (exit 1, every time)
• What exit code does each path produce? (not stated anywhere I could find)
• What about idle and keep-alive sockets? (not mentioned, and it is the usual
  reason server.close() hangs)

An options table with Type / Required / Default would help too. Right now only
the two exit flags get their own subsections, maxTimeout never does, and
closeServer / onShutdown / onCrash are never listed with types.

You asked about behaviour that happens under the hood. Beyond the shutdown
semantics above, the ones I hit were: setConfig can only be called once and
throws on a second call, which broke my tests until I moved it out of my
createApp() factory; onShutdown and onCrash must be literally declared
async, because the check is constructor.name === 'AsyncFunction', so
() => Promise.resolve() throws at startup even though the shipped types allow
it; and the logger silently drops everything after 100 entries per minute.

Smaller things

• res.headerSent in errorHandler is a typo for res.headersSent, so the
  guard never fires and a double-send throws instead of delegating to next.
• maxLoggerRequests has no effect. logger.js reads it at import time, before
  setConfig runs, so it is always 100. The config object stores your value,
  which makes it look like it worked.
• A typo in needMappers is silently dropped, and it changed a CastError from
  400 to 500 for me. The names are documented, but the type is string[] rather
  than a union of the six, so nothing catches it.
• needMappers: undefined throws Cannot read properties of undefined (reading 'map'). The guard is needMappers === null && !Array.isArray(needMappers),
  where the second half is redundant and undefined falls through.
• setConfig accepts unknown keys silently. My first attempt passed
  isDev: true, which TypeScript caught but JavaScript would not have.
• In production a CastError returns "Invalid value provided " with a trailing
  space.

Would I use it

In a small project, yes. It took very little time to wire up and it removed real
boilerplate immediately, and for an internal service the shutdown behaviour would
not keep me up at night.

In production, not as it stands. The two things I most need from error handling
are the stack trace of an unexpected error and field-level validation output for
clients, and I lose both. The shutdown issues matter for the same reason: exit 1
on a normal deploy would show up as a failing pod, and a crashed process serving
200s is the kind of thing that turns a small incident into a confusing one.

None of this feels fundamental. The bugs are small and specific, the library is
honest about being beta, and the roadmap already names the stack trace work. If
the original error were preserved and shutdown closed sockets properly, my answer
would change. 6/10 for now, and I would happily look at it again in a later
version.

---

Disclosure: I received monetary compensation for independently testing
ds-express-errors and providing my honest feedback. Payment was not dependent on
whether my review was positive or negative.

[Dianka05]

Hello, I’m very grateful for your in-depth analysis and such attention to detail!

Thank you for testing the graceful shutdown and for such detailed and comprehensive feedback. It’s extremely useful to me and will be a great help! I didn’t expect the feedback to be so well organised the tables are very useful! Thank you!

I’ll also work on the stack and the fact that the library is hiding things incorrectly thank you!Yes, that’s actually in development!

I’ll revise the pages and the general content in the /Detailed-info sections so that the library’s functionality is fully understood, without any gaps. The questions you raised which the page didn’t address are very valuable; they’ve really helped me understand what’s missing. Thank you!

Also, thank you for pointing out the grammatical issues!

To sum up: I’m extremely grateful for your in-depth, careful and honest analysis of the library! It’s helping me enormously to improve it. Thank you!

[aaronujah]

Library version tested: ds-express-errors v1.9.1

Stack: Node.js 22.15.0 · Express 5.2.1 · TypeScript 7.0.2 (strict) · Mongoose 9.9.2 · Zod 4.4.3 · jsonwebtoken 9.0.3

Experience level: Mid-level

Overall rating: 7/10

---

The core error pipeline is solid and removed real boilerplate for my stack. Most of my deductions are documentation gaps and production response behaviour, not broken fundamentals.

Scoring:

• Fulfilled promises: 8
• Documentation: 6
• Developer experience: 7
• Production readiness: 7

What I built

A small task-management API (register/login with JWT, create/list/get tasks) used only to exercise ds-express-errors. Source: https://github.com/aaronujah/ds-express-errors-test

Features used: setConfig (errorClasses for Zod, needMappers, devEnvironments), errorHandler, asyncHandler, HTTP presets (Unauthorized, NotFound), Zod mapper, Mongoose mapper (duplicate key + cast), JWT mapper, built-in logger, and graceful-shutdown helpers in server.ts.

Verified with 16 integration tests and manual Postman runs in development and production.

What worked

Install was fast with zero runtime dependencies, which I checked. npm install ds-express-errors and dropping errorHandler at the end of the middleware chain was enough to get started from the docs.

Errors.NotFound(...) and Errors.Unauthorized(...) are clearer than remembering status codes.

Zod 4 failures mapped to 400 with useful field-level messages in development.

Duplicate email mapped to 409. Invalid/expired JWT mapped to 401. Unmapped async and sync errors became 500 without killing the process — my /health check still responded afterward.

Strict TypeScript compiled clean with no casts. The built-in logger is well thought out: timestamp, method, route, status, and Operational: true/false.

The HTTP preset set (400/401/403/404/409/422/429/5xx) is broad enough for typical REST APIs; AppError covers anything else.

Issues and Suggestions

1. Production validation messages collapse to generic text

Validation detail is tied to NODE_ENV / devEnvironments, and that was not obvious from the docs.

In development, a Zod register failure returned:

{
  "status": "fail",
  "message": "Validation error: email: Invalid email address; password: Too small: expected string to have >=8 characters; name: Too small: expected string to have >=2 characters"
}

The same request in production returned:

{
  "status": "fail",
  "message": "Validation error: validation error"
}

Mongoose CastError follows the same pattern — dev shows CastError: Cast to ObjectId failed for value "...", prod returns only Invalid value provided.

Hiding stack, method, and url in production is correct. Stripping which field or param failed is not. Most times client's don't format error messages from API, so the message has to have enough information for the user. This should be documented clearly, and ideally configurable so field-level messages stay in production while stacks stay hidden.

2. Mongoose connection errors are not mapped like Sequelize/Prisma

The Mongoose mapper covers duplicate key, ValidationError, and CastError, but not connection failures like MongooseServerSelectionError during a request, those fall through to a generic 500.

I would not expect a wrong MONGODB_URI at startup to go through errorHandler; that happens before the server listens and is the app's job to fail fast. But if Mongo becomes unreachable mid-request, mapping those errors to 503 Service Unavailable (the way Sequelize connection errors already do) would be more accurate and consistent across DB integrations.

3. Library-mapped error names leak into client messages

Several auto-mapped errors prefix the response with the underlying error class or name, not just a client-friendly message. JWT is the clearest example I hit: invalid tokens returned JsonWebTokenError: jwt malformed instead of something like Invalid or expired token.

Mongoose CastError in development follows the same pattern (CastError: Cast to ObjectId failed...).

The status codes are right and the mapping works, this is mostly about message shape. For public APIs I would rather surface a stable, intentional message (or field-level detail) and keep library/class names in server logs only.

4. No clear path for error reporting (Sentry, etc.)

customLogger helps, but there is no documented pattern for forwarding errors to monitoring platforms. A dedicated callback like onError(err, { req, isOperational }), or even a short Sentry example in the docs, would make production adoption clearer. In production I would want that.

5. setConfig can only be called once

setConfig throws ConfigAlreadySet if called twice. I hit this in tests when creating more than one app instance. Fine as a rule, but it is not obvious from the happy-path docs.

Documentation and API clarity

Install and the basic wiring (errorHandler last, Errors.*, asyncHandler) were easy to follow. Most of the time I lost was looking for behaviour that exists in the library but is not spelled out on the pages I used first.

API / wording that confused me during integration

• Separate Express 4 and Express 5 404 examples. app.use('*', ...) crashes on Express 5 (path-to-regexp: missing parameter name). A path-less app.use((req, res, next) => next(Errors.NotFound(...))) works. The library advertises Express 5 and ships Errors.NotFound for this case — one line on the 404 page would have been enough.
• Show TypeScript in Installation / Usage. The homepage leads with type-safe / .d.ts support, but those pages are JavaScript only. A short setConfig + errorHandler TS snippet would match the claim.
• Call out setConfig is once-only. ConfigAlreadySet is easy to hit in tests. The Configuration section should say it up front.
• Per-technology pages. Mongoose has a dedicated example. Zod and JWT are advertised and worked, but I had to piece them together from the API / mapping reference rather than a short “do this in your route” page.
• Explain the mapping pipeline. A short “original error → custom mapper → built-in mapper → formatError → HTTP response” note would make it clearer which hook can change status vs body shape, and where class-name prefixes (JsonWebTokenError: ...) come from.
• Document monitoring. customLogger is documented; plugging Sentry / onError(err, { req, isOperational }) is not.

Docs site UX note

• Add in-page navigation on the right so I can jump across sections instead of scrolling to find what I need.
• The documentation feels tailored to experienced developers. People just starting with Express error handling may find them harder to follow.
• Put the starter kits on GitHub instead of zip downloads. A clone is easier than downloading and unpacking a zip.
• Add TypeScript examples next to the JS ones, not only in the type-safe marketing line.
• Put a minimal setConfig example on Installation or Usage, not only on the full Configuration page.

Nice-to-haves

• Mongoose connection errors (MongooseServerSelectionError) → 503, same idea as Sequelize.
• Client-facing mapped messages without library class prefixes.
• Optional field-level validation detail in production.
• A monitoring callback or a short Sentry example.

Would I use it?

New project: yes. Mongoose duplicate-key handling, Zod/JWT mapping, presets, and zero dependencies are a good trade for the setup cost.

Production today: with caveats. I would use the handler, presets, and mappers, but I would override or document around production validation messages, and wire monitoring myself until a clearer reporting hook exists.

What would move it higher

Document production message stripping separately from stack exposure. Fix the Express 5 404 example. Add one TypeScript usage snippet and a Sentry/onError note. Map Mongoose connection failures to 503.

None of that is deep — mostly documentation and a few mapper gaps on an otherwise capable library.

---

Disclosure: I received money compensation for independently testing ds-express-errors and providing my honest feedback. Payment was not dependent on whether my review was positive or negative.

[Dianka05]

Hello! Thank you for your thorough, detailed testing and feedback!

I’ll work on the documentation to make it clearer about the library’s behaviour. I’m also currently working on the TypeScript documentation .thank you for pointing that out!

I’ll also try to cover Mongoose as well as Sequelize/Prisma in the library.

Thank you for pointing out the leaks in the JWT mapper and its responses. I really appreciate it!

A future update to the logging system has already been added to the roadmap. Your comment regarding Sentry and others will be taken into account and I’ll add it to the roadmap as well. Thank you!

The UX of the documentation is also under review; many testers have pointed this out, thank you!

Thank you once again for your honest, thorough and incredibly detailed feedback. It’s a huge help to me!

[Marswalkerr]

Developer Experience Review: ds-express-errors (v1.9.1)

Tech stack I used for testing:

• Library Version Tested: ds-express-errors v1.9.1
• Test Stack: Node.js (v24, ES Modules) + Express.js (v5.2) + Mongoose (v9.9) + Zod (v4.4) + jsonwebtoken (v9.0)
• Developer Experience Level: Mid-level
• Overall Rating: 7.5 / 10

---

1. What I Built to Test the Library

To evaluate ds-express-errors under realistic backend conditions, I created an Express.js API testing 5 distinct functional areas:

1. HTTP Error Presets & asyncHandler: Tested all 13 standard error presets (400 to 504), custom status codes via AppError(..., 418), and both throw vs next(err) error flows.
2. Third-Party Validation Mapping (Zod): Triggered schema validation failures without controller-level try/catch.
3. Database Error Mapping (Mongoose & MongoDB): Triggered MongoDB duplicate key violations (E11000), schema validation errors, and invalid hex ID lookups (CastError).
4. Authentication Error Mapping (JWT): Tested forged signature tokens (JsonWebTokenError) and expired tokens (TokenExpiredError).
5. Advanced Configuration & Process Health: Configured setConfig with custom domain error mappers, custom response enveloper (formatError), and verified graceful shutdown (initGlobalHandlers + gracefulHttpClose).
6. Link to the test repo: https://github.com/Marswalkerr/ds-express-errors

---

2. What the Library Does Really Well (Pros & Strengths)

• Zero-Dependency Architecture: The use of smart duck-typing to detect errors (rather than bundling @prisma/client, mongoose, zod, etc. as direct dependencies) is a stellar architectural decision. It keeps node_modules lightweight without peer-dependency version conflicts.
• Significant Boilerplate Reduction: asyncHandler combined with throw Errors.<Preset>(...) completely eliminates noisy try/catch blocks from controller files.
• Accurate Status Codes for Database Operations: Mapping MongoDB 11000 duplicate key errors directly to 409 Conflict instead of generic 500 crashes saves significant manual error translation.
• Malformed JSON Interception: The library gracefully catches SyntaxError from body-parser and returns a clean 400 Bad Request ("Invalid JSON format") instead of leaking Express internal traces.
• Built-in Graceful Shutdown: Having initGlobalHandlers and gracefulHttpClose integrated directly into the error library is a unique and valuable feature for production deployments (Docker/Kubernetes).

---

3. Suggestions for Improvements

1. JWT Error Messages Feel Unfinished:

   • When jwt.verify() failed due to an expired token, the response message returned was:
     "message": "TokenExpiredError: An unexpected error occurred."
   • Suggestion: Instead of appending "An unexpected error occurred.", output clean user-facing text such as "Authentication token has expired".

2. Zod Error Detail Granularity:

   • For Zod validation errors, the returned message was generic: "Validation error: validation error".
   • Suggestion: Format the issues array into readable field paths (e.g. "email: Invalid email address format, password: Too short").

3. Mongoose CastError Trailing Space:

   • For invalid hex ObjectIds, the message returned was "Invalid value provided " with trailing whitespace and no field name.
   • Suggestion: Clean up formatting to specify the target property (e.g. "Invalid value provided for path '_id'").

4. Synchronous Limitation on customMappers:

   • customMappers functions must be synchronous. If error enrichment requires an async operation (e.g. fetching localized error messages from a remote store or Redis), it is not supported.
   • Suggestion: Support async (err, req) => Promise<AppError | void> in custom mappers.

5. Documentation Typo in needMappers Table:

   • In the Configuration documentation (/docs/detailed-info/configuration), the entry for 'prisma' in needMappers has a copy-paste typo describing it as "Zod validation errors".

6. Documentation & Express 5 Context:

   • Express 5.x natively handles async promise rejections without wrappers. Clarifying how errorHandler works in Express 5 vs Express 4 with asyncHandler would be helpful for modern stacks.

7. devEnvironments Configuration Fallback:

   • When NODE_ENV was unset or empty, isDev defaulted to false (production mode) because default devEnvironments strictly expects 'dev' or 'development'.
   • Suggestion: Document this default behavior more prominently in the Getting Started section to help developers prototyping locally.

---

4. Why I Selected a 7.5 / 10 Rating

The library achieves its primary promise: it provides centralized, type-safe, zero-dependency error management that removes repetitive code from Express apps. The addition of process signal listeners (SIGTERM/SIGINT) and custom mapping hooks makes it flexible.

It loses a few points due to minor rough edges in error message formatting strings (particularly JWT and Zod) and the need for deeper documentation examples around TypeScript types for customMappers.

---

5. Production Readiness Verdict

• Would I use it in personal/side projects? Yes. It saves time setting up standard Express error middleware from scratch.
• Would I use it in production enterprise systems? Yes, with setConfig custom formatting enabled. Once customized with formatError and customMappers to refine the output messages to match our API standards, it provides a solid foundation for Express error handling.

Disclosure

Disclosure: I received money compensation for independently testing ds-express-errors and providing my honest feedback. Payment was not dependent on whether my review was positive or negative.

[Dianka05]

Hello, thank you for your feedback!

1. Thank you for letting me know. I’ve already included this in the upcoming release 1.9.2.
2. Yes, I’ll try to make it clearer in the documentation how responses work in the library. In the production environment, they currently provide too much sanitised information, unlike in the development environment. This will also be included in 1.9.2.
3. Thank you, it seems I’d overlooked that!
4. Yes, this is a limitation for now, as I’m still figuring out how to implement it. It was originally planned to be asynchronous, but I ran into some issues in the past, which is why I decided to make the customMappers synchronous. But thank you! I hope I’ll still manage to resolve that issue and make them asynchronous.
5. Thank you very much!
6. Thanks for the suggestion. It’s true, I hadn’t thought of that. Thanks!
7. If I’m not mistaken, it’s in the Installation section. But perhaps the layout of the documentation made it hard to spot. I’ll bear that in mind!
   

Thank you once again for all the valuable work you’ve done; it’s a great help to me as I work on the library!

[juanjosechiroque]

ds-express-errors v1.9.1: Developer Review

• Library version tested: ds-express-errors v1.9.1
• Stack: Node.js + Express 5 + TypeScript + Mongoose + Zod + JWT
• Experience level: Senior
• Overall rating: 8/10. A solid approach to centralized error handling, best suited for new projects rather than migrations.
• Test repo: https://github.com/juanjosechiroque/ds-express-errors-review

What I built

A small Express + TypeScript API, based on my own API starter, to test the library. It has an auth module (Mongoose + JWT) and a product module (Mongoose + Zod). Covers signup/login and full CRUD, with validation on the query, params, and body.

Documentation

Finding my way around it was easy. The writing is direct, no filler, and I didn't need to jump between five pages to understand the basics.

Installation was simple and direct too: npm install ds-express-errors, no peer dependency warnings, and it resolved fine under my project's "type": "module" setup.

One thing I liked that I haven't seen in every library's docs: a public roadmap page, laid out like a kanban board (planned / in progress). I ended up using it a lot while writing this review, to check which of the issues below the maintainer already knows about.

What I actually used

• Global error handler (errorHandler), replacing a hand-rolled one
• Automatic Zod error mapping (body/params/query)
• Automatic JWT error mapping (jsonwebtoken errors)
• Errors.* presets (NotFound, BadRequest, Unauthorized) for custom app errors
• asyncHandler, fully migrated in both product/* (5 handlers) and auth/* (2 handlers)
• initGlobalHandlers/gracefulHttpClose, replacing my manual SIGTERM/SIGINT handler
• customLogger (setConfig), tested connecting my Pino logger. Didn't keep it wired in the final code, wanted to keep the repo lean.

What worked well

buildValidationError, my old function that built a 400 error by hand with per-field details from a ZodError, is dead code now. Passing the raw ZodError straight to next() is enough, the library maps it automatically. Same story with Errors.NotFound(...) and Errors.BadRequest(...): they worked as a drop-in replacement for my own error factory, no friction there.

Typecheck stayed clean through most of the migration too, no .d.ts friction, at least until I hit the asyncHandler problem (more on that below).

Zero dependencies. I confirmed this directly in the installed package's package.json, no dependencies field at all. Smaller supply-chain surface, worth something on its own.

The best result of the test came from breaking something on purpose: I killed the Mongo container while the server was running, mid-request. The resulting error (MongoServerSelectionError) isn't even in the library's list of named errors, and it still returned a clean 500 instead of hanging the request or crashing the process.

Graceful shutdown also checked out with a real signal, not just a read of the docs. Replaced my manual SIGTERM/SIGINT handling with initGlobalHandlers + gracefulHttpClose, it disconnects the DB and exits cleanly, no forced kill needed.

Issues and things I'd change

I checked each of these against the public roadmap (ds-express-errors.dev/roadmap), tagged below. Only #2 felt like an actual bug to me, the rest are things the library just doesn't cover yet.

1. No machine-readable error code. AppError only has message and statusCode. No way to send something like TOKEN_EXPIRED to the frontend. I even tried attaching one by hand with Object.assign, still never reached the HTTP response. (Roadmap: in progress.)

2. Errors.* presets look like middleware, but aren't. If you use app.use(Errors.NotFound) by mistake instead of calling it inside a function, the request just hangs. No error, no log. TypeScript doesn't catch it either. This is the one I'd actually call a bug. (Roadmap: planned.)

3. asyncHandler isn't generic. My own asyncHandler could wrap handlers with an extended Request type. The library's version only accepts a plain Request. Affected almost every handler in product.controller.ts, not just the one using .validatedQuery. Worked around it with local casts that are only correct because Zod already validated the data, TypeScript itself can't prove it anymore. (Roadmap: implied by the planned rewrite in TypeScript, this problem comes from hand-written .d.ts files sitting on top of plain JavaScript code.)

4. Logs every error the same way, no way to filter. A normal 400 gets logged exactly like a real 500. Confirmed this from the source code, not just by not finding it in the docs. Only workaround is wrapping your own logger and filtering by isOperational yourself. (Roadmap: in progress.)

5. Error logs don't share a request ID with the rest of my logs. The library only attaches a requestId when one already exists on the incoming request:

   ...(req?.headers?.['x-request-id'] ? {requestId: req?.headers?.['x-request-id']} : {})

   My own middleware generates an ID when the client doesn't send one, and stores it on req.id and the response header, not the incoming headers. Same request, tested live, two log lines, no shared ID:

   [ERROR] {"msg":{"url":"/v1/products/...","method":"GET"}}
   [INFO]  {"req":{"id":"0912bc67-...","method":"GET",...},"res":{...}}
   

   In production I couldn't search one ID and get the full story of a failed request. Fixable on my side, but it's real friction, and unlike the other four issues, nothing on the roadmap covers it.

Two smaller things: the generic message "Validation error: validation error" for an unrecognized ZodError is less useful than the per-field details I had before, and the response envelope uses status: "fail" for 4xx and status: "error" for 5xx (JSend-style) without documenting it anywhere. Neither breaks anything, not worth a full point off.

Would I use this in production?

Yes, but mostly for a new project. My test was a migration, since I already had error handling built into my own API starter, and that's exactly where the friction showed up: the asyncHandler problem broke almost every handler I had. Starting from scratch avoids that. The Errors.NotFound hang is the one issue that would make me pause before shipping this to a team, since it fails silently with nothing telling you what went wrong. Everything else is a real but livable gap, and four of the five issues I found already have movement on the roadmap.

---

Disclosure: I received money compensation for independently testing ds-express-errors and providing my honest feedback. Payment was not dependent on whether my review was positive or negative.

[Dianka05]

Hello, thank you for all your hard work! I really appreciate it!

Thank you for pointing out these various issues.

1. Yes, I’ve clearly made a mistake here. I’ll try to rectify this as soon as possible. Thank you!

2. I’ll try to make it clearer in the documentation what this is and how it works, and I’ll also use your example app.use(Errors.*) to highlight this as an incorrect usage in the documentation. Thank you. I’ll also try to ensure that, if a developer performs this action, they receive a notification that it is incorrect.

3. It seems I didn’t spot this because of the manual .d.ts files. I think it will be better once I’ve rewritten it in TypeScript. Thank you!

4. Yes, the logging system is still a bit basic. I’m planning to make a few different changes to it, including some major ones. Thank you!

5. It seems I hadn’t thought this through properly. thank you for pointing it out.

As for the responses, in the planned 1.9.2 release I intend to remove the strict sanitisation of responses, as I consider this to be a bug and incorrect logic embedded in the production messages.

Thank you once again for your invaluable help in helping me understand the shortcomings and potential issues. It’s a great help in improving my library.