feat: enhance validation capabilities for routes and handlers#1237
feat: enhance validation capabilities for routes and handlers#1237productdevbook wants to merge 5 commits into
Conversation
- Added support for response validation in defineValidatedHandler - Introduced syncValidate function for synchronous validation - Updated defineRoute to include comprehensive validation schemas - Expanded tests for full validation type inference and error handling
📝 WalkthroughWalkthroughAdds runtime and compile-time validation across request lifecycle: params, query, headers, body, and responses. Introduces typed route definitions and validated handler APIs, new validation utilities, and extensive tests exercising validation behavior and type inference. Changes
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes Suggested labels
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
commit: |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@src/handler.ts`:
- Around line 119-124: The params validation call omits the onError handler so
parameter validation doesn't use custom error formatting; update the call in
handler where syncValidate("params", params, def.validate!.params) is used to
pass the same onError callback used for body/query/headers (propagate the
onError from the route definition or surrounding context into syncValidate),
ensuring event.context.params is assigned from syncValidate("params", params,
def.validate!.params, onError) and that defineRoute's validation path forwards
that onError consistently.
In `@src/utils/internal/validate.ts`:
- Around line 214-219: The thrown 500 includes validator internals
(error?.message and error?.data) which leaks server-side schema details;
instead, in the throw new HTTPError call remove error?.message and error?.data
and replace them with a generic statusText/message like "Response validation
failed" (keep status: 500) and log the original validator error privately (e.g.,
using the existing logger) before throwing; update the throw site that
constructs the HTTPError (the throw new HTTPError({...}) block and any
surrounding validate/response-validation function) to avoid returning validator
internals to clients while preserving internal logging for diagnostics.
In `@src/utils/route.ts`:
- Around line 40-54: The example route's handler that uses await needs to be
declared async: locate the example route object that defines the handler
property (the handler: (event) => { ... } example) and change its declaration to
handler: async (event) => { ... } so await inside the function is valid; ensure
the function body and returned types remain unchanged (the change is only adding
the async keyword to the handler).
- Around line 133-155: The example's handler is using await without being async
and the route registration uses app.use instead of app.register; update the
example so the handler function passed to defineRoute is declared async (e.g.,
async (event) => { ... }) so await is valid, and replace the app.use(userRoute)
call with app.register(userRoute) to match the documented registration API;
ensure the symbol names defineRoute, handler arrow function, and userRoute are
adjusted accordingly in the snippet.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 05b6bd35-ebb3-479e-b7d2-2ebd01d071d2
📒 Files selected for processing (7)
src/handler.tssrc/index.tssrc/utils/internal/validate.tssrc/utils/route.tstest/full-validation-example.test.tstest/handler.test.tstest/route.test.ts
| throw new HTTPError({ | ||
| cause: error, | ||
| status: 500, | ||
| statusText: "Response validation failed", | ||
| message: error?.message || "Response validation failed", | ||
| data: error?.data, |
There was a problem hiding this comment.
Don't return validator internals from 500 responses.
Response-schema mismatches are server bugs, not client input errors. Forwarding error?.message and error?.data here exposes internal field names and validation rules in a public 500 payload without giving the caller anything actionable.
Suggested fix
} catch (error: any) {
throw new HTTPError({
cause: error,
status: 500,
statusText: "Response validation failed",
- message: error?.message || "Response validation failed",
- data: error?.data,
+ message: "Response validation failed",
});
}
}📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| throw new HTTPError({ | |
| cause: error, | |
| status: 500, | |
| statusText: "Response validation failed", | |
| message: error?.message || "Response validation failed", | |
| data: error?.data, | |
| throw new HTTPError({ | |
| cause: error, | |
| status: 500, | |
| statusText: "Response validation failed", | |
| message: "Response validation failed", | |
| }); |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/utils/internal/validate.ts` around lines 214 - 219, The thrown 500
includes validator internals (error?.message and error?.data) which leaks
server-side schema details; instead, in the throw new HTTPError call remove
error?.message and error?.data and replace them with a generic
statusText/message like "Response validation failed" (keep status: 500) and log
the original validator error privately (e.g., using the existing logger) before
throwing; update the throw site that constructs the HTTPError (the throw new
HTTPError({...}) block and any surrounding validate/response-validation
function) to avoid returning validator internals to clients while preserving
internal logging for diagnostics.
| handler: ( | ||
| event: H3Event< | ||
| EventHandlerRequest & { | ||
| body: V["body"] extends StandardSchemaV1 ? InferOutput<V["body"]> : unknown; | ||
| query: V["query"] extends StandardSchemaV1 | ||
| ? StringHeaders<InferOutput<V["query"]>> | ||
| : Partial<Record<string, string>>; | ||
| routerParams: V["params"] extends StandardSchemaV1 | ||
| ? InferOutput<V["params"]> | ||
| : Record<string, string>; | ||
| } | ||
| >, | ||
| ) => | ||
| | (V["response"] extends StandardSchemaV1 ? InferOutput<V["response"]> : unknown) | ||
| | Promise<V["response"] extends StandardSchemaV1 ? InferOutput<V["response"]> : unknown>; |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
cd /repo && find . -type f -name "route.ts" -o -name "index.ts" | head -20Repository: h3js/h3
Length of output: 106
🏁 Script executed:
cd /repo && wc -l src/utils/route.ts src/index.tsRepository: h3js/h3
Length of output: 106
🏁 Script executed:
cd /repo && cat -n src/utils/route.ts | head -160Repository: h3js/h3
Length of output: 106
🏁 Script executed:
cd /repo && cat -n src/index.tsRepository: h3js/h3
Length of output: 106
🏁 Script executed:
find . -type f -name "route.ts" -o -name "index.ts" 2>/dev/null | grep -E "(route\.ts|index\.ts)$"Repository: h3js/h3
Length of output: 86
🏁 Script executed:
wc -l src/utils/route.ts src/index.ts 2>/dev/null || echo "Files not found, listing directory structure..."Repository: h3js/h3
Length of output: 103
🏁 Script executed:
ls -la src/utils/ && ls -la src/ 2>/dev/null || find . -name "route.ts" -type fRepository: h3js/h3
Length of output: 2279
🏁 Script executed:
cat -n src/utils/route.tsRepository: h3js/h3
Length of output: 6883
🏁 Script executed:
cat -n src/index.tsRepository: h3js/h3
Length of output: 5568
Documentation example handler must be declared async to use await.
The example at lines 163-168 uses await on line 166 but the handler function is not declared as async. Change handler: (event) => { to handler: async (event) => {.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/utils/route.ts` around lines 40 - 54, The example route's handler that
uses await needs to be declared async: locate the example route object that
defines the handler property (the handler: (event) => { ... } example) and
change its declaration to handler: async (event) => { ... } so await inside the
function is valid; ensure the function body and returned types remain unchanged
(the change is only adding the async keyword to the handler).
| * @example | ||
| * ```js | ||
| * import { z } from "zod"; | ||
| * | ||
| * const userRoute = defineRoute({ | ||
| * method: 'POST', | ||
| * route: '/api/users/:id', | ||
| * validate: { | ||
| * query: z.object({ id: z.string().uuid() }), | ||
| * params: z.object({ id: z.string().uuid() }), | ||
| * query: z.object({ include: z.string().optional() }), | ||
| * body: z.object({ name: z.string() }), | ||
| * response: z.object({ id: z.string(), name: z.string() }), | ||
| * }, | ||
| * handler: (event) => { | ||
| * return { success: true }; | ||
| * // event.context.params, await event.req.json(), and return value are all typed! | ||
| * const { id } = event.context.params; | ||
| * const body = await event.req.json(); | ||
| * return { id, name: body.name }; | ||
| * } | ||
| * }); | ||
| * | ||
| * app.register(userRoute); | ||
| * app.use(userRoute); | ||
| * ``` |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
find . -name "route.ts" -type f | head -20Repository: h3js/h3
Length of output: 71
🏁 Script executed:
cat -n src/utils/route.ts | head -200Repository: h3js/h3
Length of output: 6883
Fix the example code before publishing it.
The example has two issues:
- The handler on line 163 uses
awaitwithoutasync— this is a syntax error - Line 171 uses
app.use(userRoute)but the API documentation states the route should be registered withapp.register()(see line 145)
Suggested fix
- * handler: (event) => {
+ * handler: async (event) => {
* // event.context.params, await event.req.json(), and return value are all typed!
* const { id } = event.context.params;
* const body = await event.req.json();
* return { id, name: body.name };
* }
* });
*
- * app.use(userRoute);
+ * app.register(userRoute);
* ```📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| * @example | |
| * ```js | |
| * import { z } from "zod"; | |
| * | |
| * const userRoute = defineRoute({ | |
| * method: 'POST', | |
| * route: '/api/users/:id', | |
| * validate: { | |
| * query: z.object({ id: z.string().uuid() }), | |
| * params: z.object({ id: z.string().uuid() }), | |
| * query: z.object({ include: z.string().optional() }), | |
| * body: z.object({ name: z.string() }), | |
| * response: z.object({ id: z.string(), name: z.string() }), | |
| * }, | |
| * handler: (event) => { | |
| * return { success: true }; | |
| * // event.context.params, await event.req.json(), and return value are all typed! | |
| * const { id } = event.context.params; | |
| * const body = await event.req.json(); | |
| * return { id, name: body.name }; | |
| * } | |
| * }); | |
| * | |
| * app.register(userRoute); | |
| * app.use(userRoute); | |
| * ``` | |
| * `@example` | |
| * |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/utils/route.ts` around lines 133 - 155, The example's handler is using
await without being async and the route registration uses app.use instead of
app.register; update the example so the handler function passed to defineRoute
is declared async (e.g., async (event) => { ... }) so await is valid, and
replace the app.use(userRoute) call with app.register(userRoute) to match the
documented registration API; ensure the symbol names defineRoute, handler arrow
function, and userRoute are adjusted accordingly in the snippet.
There was a problem hiding this comment.
🧹 Nitpick comments (3)
src/utils/route.ts (2)
88-96: Consider consolidatingValidatedRouteEventwithValidatedH3Event.This type is structurally identical to
ValidatedH3Eventinsrc/handler.ts(lines 72-79). Both define the same pattern:Omit<H3Event<RequestT>, "context"> & { context: Omit<H3Event["context"], "params"> & { params?: ParamsT } }Consider exporting one shared type to reduce maintenance burden.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/utils/route.ts` around lines 88 - 96, ValidatedRouteEvent duplicates the same shape as ValidatedH3Event; consolidate by extracting a single exported shared type and reuse it in both places: create or export the canonical type (e.g., ValidatedH3Event) and replace ValidatedRouteEvent usage with that shared type, removing the duplicate definition; ensure the exported name matches existing imports/usages and update any imports/usages referencing ValidatedRouteEvent to the shared type to avoid type drift.
9-11: Consider extractingStringHeadersto avoid duplication.This type is identical to
StringHeadersdefined insrc/handler.ts(line 62-64). Consider extracting it to a shared location (e.g.,src/types/utils.ts) and importing from both files.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/utils/route.ts` around lines 9 - 11, Extract the duplicate type alias StringHeaders into a shared module and import it where needed: create a new exported type StringHeaders in a common types file, replace the inline definition in route.ts (currently declaring type StringHeaders<T>) with an import of that shared type, and update handler.ts to import the same shared type instead of redefining it; keep the generic signature and name unchanged so existing usages compile.src/handler.ts (1)
145-152: Type cast note:onErrorcallback may receive "response" source.The cast at line 150 (
as OnValidateError<"response">) is safe at runtime, but users providing anonErrorcallback should be aware it will receive_source: "response"for response validation failures in addition to request-side sources like "params", "query", "headers", and "body".Consider documenting this behavior in the
OnValidateErrortype or thevalidate.onErrorproperty JSDoc.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/handler.ts` around lines 145 - 152, The cast using OnValidateError<"response"> should be documented or widened so callers know the onError callback can receive _source: "response" for response-side validation failures; update the OnValidateError type signature or add JSDoc on the validate.onError property to explicitly include "response" as a possible source (or use a union that includes "response"), and mention this behavior near the validateResponse call and in the OnValidateError JSDoc so users implementing onError for functions like validateResponse or def.validate know the callback may be invoked with _source === "response".
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@src/handler.ts`:
- Around line 145-152: The cast using OnValidateError<"response"> should be
documented or widened so callers know the onError callback can receive _source:
"response" for response-side validation failures; update the OnValidateError
type signature or add JSDoc on the validate.onError property to explicitly
include "response" as a possible source (or use a union that includes
"response"), and mention this behavior near the validateResponse call and in the
OnValidateError JSDoc so users implementing onError for functions like
validateResponse or def.validate know the callback may be invoked with _source
=== "response".
In `@src/utils/route.ts`:
- Around line 88-96: ValidatedRouteEvent duplicates the same shape as
ValidatedH3Event; consolidate by extracting a single exported shared type and
reuse it in both places: create or export the canonical type (e.g.,
ValidatedH3Event) and replace ValidatedRouteEvent usage with that shared type,
removing the duplicate definition; ensure the exported name matches existing
imports/usages and update any imports/usages referencing ValidatedRouteEvent to
the shared type to avoid type drift.
- Around line 9-11: Extract the duplicate type alias StringHeaders into a shared
module and import it where needed: create a new exported type StringHeaders in a
common types file, replace the inline definition in route.ts (currently
declaring type StringHeaders<T>) with an import of that shared type, and update
handler.ts to import the same shared type instead of redefining it; keep the
generic signature and name unchanged so existing usages compile.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 7daa7ad9-981b-4fba-a360-ca8c884f2c9a
📒 Files selected for processing (6)
src/handler.tssrc/utils/internal/validate.tssrc/utils/route.tstest/handler.test.tstest/route.test.tstest/unit/types.test-d.ts
🚧 Files skipped from review as they are similar to previous changes (1)
- test/handler.test.ts
|
I just realized that thanks to |
|
@sandros94 Yes, that was the whole point of it. and CLI support. |
|
I cannot stop thinking about this PR, I'm sorry... Another think I realized is that by taking advantage of the StandardSchema part, not only we have the input and output validation as always, but could theoretically also expose the typing, which then a client such as fetchdts or ofetch could directly use. With a single combination of StandardSchema and StandardJSONSchema this would cover both validation, types and openapi, wihtout re-inventing the wheel nor overcomplicating it for new comers or other frameworks Sorry for the ping, but when you have time I would also like your opinions on this @pi0 and @danielroe The only open question that remains to me would be how to handle multiple methods, as semantically speaking I'm now realizing that a defineRoute is about routes in general. It can have multiple methods in its handler, as well as different validations (and therefor types and openapi) for each |
|
So, ended up drafting an experiment which is about the DX API I'm satisfied with and now I've published for easier feedbacks and testing of that idea. Essentially I wanted the concept of a set of utils for defining routes much similar to what @productdevbook initially implemented, but both adding multi-method support as well as data validation with full type support, without being limited to async or non async schemas. Turned out that adding support for nitro and typing a fetcher were two smaller additions that I ended up seeking soon after. You can find the experiment at sandros94/h3-route-tools, if you have time to take a look at it I'll be happy to hear any feedbacks 🙌 The core is composed of:
There are two playgrounds, one for h3 and the other for a mock nitro+vue example |
|
Note: this analysis was performed by an AI agent (Claude Code) on behalf of the maintainer. This PR overlaps in design space with #1217 (compile-time route param type inference) and #1339 ( No action needed right now — just flagging the relationship for whoever reviews this next. |
3 participants
Summary
cc: #1088
This PR enhances H3's validation capabilities with comprehensive type-safe validation for routes and handlers:
/users/:id) with full type inferencedefineValidatedHandler: Now supportsparamsandresponseschemas in addition to existingbody,headers, andqueryvalidationdefineRoute: Full type-safe validation with proper TypeScript overloads for better DXsyncValidatefor synchronous validation andvalidateResponsefor response validationKey Features
1. Params Validation
2. Response Validation
3. Complete Validation
Test Plan
defineValidatedHandlerdefineValidatedHandlerdefineRoutewith all validation schemas🤖 Generated with Claude Code
Summary by CodeRabbit
Release Notes
New Features
Tests