feat(parser): add errorHandler option for inline parse error handling

[Zelys-DFKH]

Summary

Changes

Adds an optional errorHandler callback to ParserOptions, letting callers intercept parse failures and return a custom response instead of throwing.

The motivation comes from #4191: when @parser is stacked with other decorators that expect a fully-typed event, safeParse: true doesn't compose well -- the outer decorators see ParsedResult rather than the actual payload. An error handler keeps the event type clean while still providing a recovery path on parse failure. Thanks to @codyfrisch for walking through this use case in detail.

The callback receives the ParseError. If it returns a non-undefined value, that becomes the Lambda/Middy response and stops further processing. If it returns undefined, the original error is rethrown -- so you can handle specific failure cases without silently absorbing unexpected ones. Non-ParseError exceptions (e.g., from schema transforms) always propagate as-is.

Both the @parser class decorator and parser() Middy middleware support the new option.

Issue number: closes #4191

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Disclaimer: We value your time and bandwidth. As such, any pull requests created on non-triaged issues might not be successful.

[dreamorosi]

Hi @Zelys-DFKH, thank you for picking this up and for the well-structured PR - and apologies for the delay in getting to the review.

The direction matches what we discussed in #4191 and the implementation is easy to follow, however there are a few things we need to address before this can move forward - see the inline comments for the details and reasoning:

• an async errorHandler currently swallows parse failures and lets the handler run with the unparsed event (must fix)
• in the Middy.js flavor, short-circuiting from before skips every other middleware's after phase - I'd like the recovery to go through the onError phase instead
• safeParse and errorHandler should be mutually exclusive at the type level
• the callback should receive the original event alongside the error
• the Middy.js middleware's response type should reflect the error handler's return type

On top of that:

• the feature needs documentation in docs/features/parser.md (the safeParse section is the natural home for it) plus code snippets under examples/snippets/parser
• missing test cases: envelope + errorHandler, non-ParseError propagation, and the safeParse interaction
• biome check currently fails on formatting in parser.middy.test.ts

Happy to clarify or discuss any of these - thanks again for the contribution!

[dreamorosi]

btw could you please leave a quick comment on #4191? We'd like to assign the issue to you for tracking, but GitHub only allows assigning users who have either commented on the issue or are collaborators — so right now we can't. Once you've commented, we'll assign it to you. Thanks!

[Zelys-DFKH]

Thanks for the thorough review, @dreamorosi, and sorry for the slow turnaround. All five points are addressed below, along with the docs, tests, and the biome fix.

• errorHandler is now constrained to synchronous returns at the type level, with a runtime guard as a backstop. A type test and a runtime test cover the async case.
• Moved the Middy.js recovery into onError, exactly as you suggested: request.response is set directly (never returned), so the rest of the onError chain still runs. A regression test attaches another middleware's onError and confirms it still fires after parser recovers.
• safeParse and errorHandler are now mutually exclusive via a discriminated union; the invalid combination fails to compile, covered by a type test.
• errorHandler now receives (error, event) in both flavors.
• The Middy MiddlewareObj response type threads through the errorHandler's return type now. Kept the decorator loosely typed per your note.
• Docs live under the safeParse section in docs/features/parser.md, with snippets for both flavors under examples/snippets/parser.
• Added the three missing test cases (envelope + errorHandler, non-ParseError propagation, safeParse/errorHandler exclusion), plus a couple more that fell out of the onError change.
• Fixed the biome formatting failure.

One more thing came up while testing the onError change: since ParseError is public API, both flavors were treating any ParseError reaching them as this parser's own failure, including one a customer's handler might throw for unrelated reasons. Fixed that by scoping recovery to this parser instance's own before-phase failure (a WeakSet keyed on the request for the middleware, a narrower try/catch around just the parse() call for the decorator), with regression tests for both.

Let me know if I've missed anything, or if you'd rather take a different approach on any of these.

[svozza]

There is a SonarQube issue (very simple fix), can you address it?

[dreamorosi]

Thanks for the quick and thorough turnaround @Zelys-DFKH - all the points from the previous review have been addressed exactly as discussed: the sync-only errorHandler constraint, the onError-based recovery in the Middy.js flavor, the mutually exclusive types, the event in the callback signature, the threaded response type, plus the docs, snippets, and the extra test coverage. We're getting close to merging this.

There's one small inconsistency left, introduced by the SonarQube follow-up - see the inline comment. Once that's sorted I think we're good to go.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
5.3% Duplication on New Code

See analysis details on SonarQube Cloud

[dreamorosi]

Thank you for addressing the review comments and implementing the feature!