[svozza]

Summary

Zod doesn't catch errors thrown inside a transform, so they are thrown even when safeParse is used ("Transform functions should never throw", Zod docs). This PR documents that behaviour in the parser docs and shows how to report a transform failure as a validation error with ctx.issues and z.NEVER, the same way the built-in helpers like JSONStringified do.

Changes

• Add a "Reporting errors from transforms" subsection under "Custom validation" in docs/features/parser.md, explaining that thrown errors aren't caught and showing the ctx.issues.push / z.NEVER pattern.
• Add the examples/snippets/parser/transformIssues.ts snippet, a transform that catches the URIError from decodeURIComponent and reports it as a custom issue.
• Add a note to the "Safe parsing" section that safeParse doesn't catch errors thrown by a schema's transform, linking to the new subsection.

Issue number: closes #5769

---

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.

🤖 Generated with Claude Code