@dphonys/nuxt-handler-validation 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Petr Honys
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,421 @@
+# Nuxt Handler Validation
+
+Declare a Nitro handler's request schemas once, and receive the validated,
+fully-typed values in the handler's second parameter - route params, query,
+headers and body, checked by any [Standard Schema](https://standardschema.dev)
+library _before_ the handler body runs. Failures answer with one stable,
+documented wire shape, identical in development and production.
+
+One sentence for the whole model: **a source slot takes a schema, or a tuple of
+schemas; reuse is exporting a schema value; composition is writing a tuple.**
+
+## Installation
+
+```sh
+pnpm add @dphonys/nuxt-handler-validation
+```
+
+```ts
+export default defineNuxtConfig({
+  modules: ['@dphonys/nuxt-handler-validation'],
+})
+```
+
+That is the only setup step - the module has **zero options**. Nothing about a
+route's validation is configured; it is declared, in the route.
+
+Bring your own schema library. Anything implementing Standard Schema works -
+[zod](https://zod.dev), [valibot](https://valibot.dev),
+[arktype](https://arktype.io), and others - nothing is bundled for you.
+
+**Requirements:** Nuxt `>=4.5.1 <5.0.0`, Node 22.19+ / 24.11+ / 26+.
+
+## Quick start
+
+```ts
+// server/api/users/[id].post.ts
+import * as v from 'valibot'
+import { z } from 'zod'
+
+export default defineValidatedEventHandler(
+  {
+    validate: {
+      routerParams: v.object({ id: v.pipe(v.string(), v.transform(Number)) }),
+      query: z.object({ page: z.coerce.number() }),
+      body: z.object({
+        name: z.string(),
+        tags: z.string().transform((s) => s.split(',')),
+      }),
+    },
+  },
+  async (event, { routerParams, query, body }) => {
+    // routerParams: { id: number }
+    // query:        { page: number }
+    // body:         { name: string, tags: string[] }
+    return updateUser(routerParams.id, body)
+  }
+)
+```
+
+- **Schemas nest under `validate`**, keyed by source. The four sources are
+  `routerParams`, `query`, `headers` and `body`.
+- **Validated values arrive eagerly and fully typed in the second parameter**,
+  each typed as its schema's _output_ - so coercions and transforms land in the
+  handler already applied. Undeclared sources are **absent** from that
+  parameter, not `unknown` and not optional; reading one is a compile error
+  naming the key.
+- **Mix libraries freely.** zod and valibot can sit in one declaration, or even
+  in one composed tuple. Async schemas are supported; the wrapper awaits them.
+- **Your return type flows to Nitro's typed routes unchanged.** The wrapper
+  returns a plain h3 `EventHandler`, so `$fetch('/api/users/1')` infers the
+  response exactly as it would with `defineEventHandler`. Nothing to unwrap.
+- `defineValidatedEventHandler` and `recognizeValidationError` are
+  **auto-imported inside `server/`**, the same ambient position as
+  `defineEventHandler`. Import them from
+  `@dphonys/nuxt-handler-validation/server` where auto-imports do not reach -
+  Nitro plugins and tasks, tests, non-Nuxt Nitro apps,
+  `imports.autoImport: false`. That entry carries the runtime and depends on
+  h3, so never import it from client code; use
+  `@dphonys/nuxt-handler-validation/types` for types in app code.
+
+### The second parameter is the only door
+
+Each source is read **once** per request, before your handler body runs.
+Calling `readBody(event)` afterwards hands back h3's memoized _unvalidated_
+parse - not what your schema produced. Read what you declared from the second
+parameter and nothing has to be re-parsed or re-checked.
+
+## Reusing and composing schemas
+
+A reusable unit is a **plain schema value**. There is no definer, no set, no
+group, and no name to register - a Standard Schema already travels as an
+export, and it carries no source keys to misspell.
+
+```ts
+// server/validation/listing.ts
+import * as v from 'valibot'
+import { z } from 'zod'
+
+export const pagination = z.object({
+  page: z.coerce.number(),
+  size: z.coerce.number(),
+})
+
+export const sorting = v.object({ sort: v.picklist(['asc', 'desc']) })
+```
+
+Give a source a tuple to compose several schemas onto it:
+
+```ts
+// server/api/users/index.get.ts
+import { pagination, sorting } from '~~/server/validation/listing'
+import { profileBody } from '~~/server/validation/profile'
+
+export default defineValidatedEventHandler(
+  { validate: { query: [pagination, sorting], body: profileBody } },
+  async (event, { query, body }) => {
+    // query: { page: number, size: number, sort: 'asc' | 'desc' }
+    return listUsers(query, body)
+  }
+)
+```
+
+- **Every element parses the whole raw source, in order**, and you receive the
+  merge of their outputs. The wire is untouched - the client still sends a flat
+  `?page=1&size=20&sort=asc`, and an issue's `path` stays relative to that raw
+  source.
+- **The merged type is one flat record**, not a chain of `&`. It reads on hover
+  the way the runtime value looks, and it is spellable as a declared return
+  type.
+- **Issues aggregate within a source.** An early element's failure does not
+  stop the later ones, so reordering a tuple never changes what a client sees.
+  Elements run sequentially, so async schemas are deterministic.
+- **A tuple, not an array.** A widened `StandardSchemaV1[]` cannot say how many
+  schemas it holds, so its merge could not be typed. Write the array literal
+  inline, or add `as const`.
+- **A lone schema and a one-element tuple are identical.** `x` and `[x]`
+  deliver the same value, and neither has anything to merge - so a lone
+  schema's output may be anything, primitives and unions included.
+- **A set spanning several sources is just an object of schema values.** Export
+  `{ headers, query }` from one file and let each route say which slot each
+  schema fills.
+
+### Two rules for composed sources
+
+Composing two or more schemas onto one source has exactly two compile-time
+rules, both reported **at the offending source key, at the declaration**:
+
+1. **Every composed output must be an object** - not a primitive, an array or a
+   function. The test is structural, so an interface-typed output (a
+   `z.custom<ThirdParty>()`, a hand-written schema) is not falsely refused.
+2. **Their output keys must be pairwise disjoint.** An intersection would lie
+   about which value survives, so an overlap is refused. Merge at the schema
+   library level instead (`.extend`, `v.intersect`, …) or rename the key.
+   Composing the _same_ schema twice counts as an overlap.
+
+A composed value satisfies each part structurally - `helper(query)` typed off
+`pagination` alone still typechecks - but the other elements' keys ride along.
+The promise is "existing keys do not change", not "the shape does not change".
+
+## What each source receives
+
+Sources are handed to your schemas exactly as h3 yields them. Nothing is
+normalized or coerced on the way, because every conversion belongs in the
+schema where the rest of your parsing rules live.
+
+- **Order is guaranteed and fail-fast:
+  `routerParams -> query -> headers -> body`.** Cheap-and-sync first,
+  stream-consuming last, so an invalid route param spares the body parse. There
+  is no aggregate mode. Multiple issues _within_ one source still arrive
+  together, so a form with two bad fields needs one round trip.
+- **Query** values are `string | string[]`; duplicate keys become arrays. All
+  coercion belongs in your schema (`z.coerce.number()` and friends).
+- **Headers** have lowercase keys, with multi-values joined by `", "`. No
+  case-insensitivity or splitting magic is added.
+- **Route params** arrive URL-decoded. A catch-all is one slash-joined decoded
+  string, under key `_` for an anonymous `[...].ts`.
+- **A method that cannot carry a body validates `undefined`.** Outside h3's
+  payload methods (`PATCH`, `POST`, `PUT`, `DELETE`) the body read is skipped
+  entirely, so a method-agnostic route file that declares a body keeps working
+  for `GET` instead of answering h3's bare `405`.
+- **An empty body validates `undefined`** too. Express "optional body" in the
+  schema, where all other optionality lives.
+- **A body the request made unreadable fails like any other bad input**: any
+  `4xx` from the body read becomes exactly one issue,
+  `{ "source": "body", "message": "Request body could not be parsed", "path": [] }`.
+  The message never echoes body content. `5xx` and non-HTTP throws - a dropped
+  connection, a stream error - propagate untouched rather than being dressed up
+  as validation issues.
+
+The body is read through h3's own validated-body door
+(`readBody(event, { strict: true })`), so today
+`application/x-www-form-urlencoded` arrives as an object of `string | string[]`
+(HTML form posts validate for free), `text/*` arrives as the raw string, and
+everything else parses strictly as JSON. **That branching is h3's, described
+here rather than promised** - h3 v2 keeps none of it.
+
+## When validation fails: the wire shape
+
+A failing request answers `400` with one fixed shape - **no options, and
+identical in development and production**:
+
+```jsonc
+{
+  "statusCode": 400,
+  "statusMessage": "Validation Error",
+  "message": "...", // a short human summary; nothing may parse it
+  "data": {
+    "issues": [
+      { "source": "query", "message": "Expected number", "path": ["page"] },
+    ],
+  },
+}
+```
+
+- **Status is `400`, not configurable.** A fixed status is what makes the shape
+  stable and documentable.
+- **Every issue is projected to `{ source, message, path }` - nothing else.**
+  Raw Standard Schema issues are not JSON-safe and can carry the request's own
+  input, so the projection is built by construction rather than by filtering:
+  vendor extras are dropped and `path` normalizes to `Array<string | number>`.
+  The projection **is** the sanitization, which is why there is no redaction
+  option and no production branch.
+- Those four keys are this package's. The envelope around them is Nitro's - it
+  adds `url`, and a `stack` in development.
+
+### Rendering issues on the client
+
+`ValidationIssue` and `ValidationErrorData` come from
+`@dphonys/nuxt-handler-validation/types`, which is type-only and safe to import
+from components.
+
+```vue
+<script setup lang="ts">
+import type { ValidationErrorData } from '@dphonys/nuxt-handler-validation/types'
+import type { FetchError } from 'ofetch'
+
+const fieldErrors = ref<Record<string, string>>({})
+
+async function submit(body: unknown) {
+  fieldErrors.value = {}
+
+  try {
+    await $fetch('/api/users', { method: 'POST', body })
+  } catch (error) {
+    const failure = error as FetchError<{ data?: ValidationErrorData }>
+
+    for (const issue of failure.data?.data?.issues ?? []) {
+      fieldErrors.value[issue.path.join('.')] = issue.message
+    }
+  }
+}
+</script>
+```
+
+**Note the double `data`.** `FetchError.data` is the whole error body, and this
+package's payload is that body's `data` - so issues sit at
+`err.data.data.issues`, and there is nothing at `err.data.issues`. Both `data`s
+are the framework's.
+
+## Observability
+
+`recognizeValidationError` answers the issues a validation failure raised, or
+`undefined` for "not a validation failure". It reads a symbol marker on the
+error and nothing else - never `data`, never `cause` at any depth - and the
+marker never reaches the wire.
+
+```ts
+// server/plugins/observability.ts
+export default defineNitroPlugin((nitroApp) => {
+  nitroApp.hooks.hook('error', (error) => {
+    // A request that failed validation: expected, not a bug.
+    if (recognizeValidationError(error)) return
+
+    report(error)
+  })
+})
+```
+
+The same predicate works in Sentry's `beforeSend` over
+`hint.originalException`. It returns a value rather than being a type
+predicate, so it pairs with the sibling package's `recognizeKnownError` in one
+hook.
+
+**Only a `400` validation failure is marked** - including the body read this
+package absorbs into a single `body` issue. Every developer mistake the package
+raises carries no marker, so the recipe above still reports all of them.
+
+**What a marked error tells you, exactly:** it was raised by this package **in
+this process**, and never arrived over a fetch. It is _not_ necessarily this
+route's own declaration failing - an `H3Error` propagates in-process by
+identity, so a directly called handler or shared function running the wrapper's
+validation delivers an indistinguishable marked error. It also does not
+guarantee the request answered `400`: an SWR revalidation fires the hook while
+the response was served `200` from cache. Nitro types the hook's event argument
+as optional, so write the hook against the error itself.
+
+## Troubleshooting
+
+### `satisfies`, never `: ValidationSchemas`
+
+This is the one footgun worth memorizing. Annotating a declaration compiles,
+but delivers no readable sources:
+
+```ts
+// Wrong: `validated.query` is a compile error, even though query is declared.
+const schemas: ValidationSchemas = { query: pagination }
+
+// Right: the inferred literal is what the second parameter is computed from.
+const schemas = { query: pagination } satisfies ValidationSchemas
+```
+
+The annotation throws away the very value the inference needed. The second
+parameter is mapped over the declaration's **inferred** keys, and annotating
+replaces the literal's one known key with the interface's four optional ones -
+so nothing is guaranteed and nothing is delivered. Leave the literal inline, or
+use `satisfies`.
+
+### Compile errors this package writes itself
+
+A typo'd or stray key is rejected **even when it sits beside valid ones** -
+`{ query: q, boyd: schema }` is a compile error, not a body that silently never
+validates. The wrapper has one signature, so no rejection collapses into a
+`TS2769: No overload matches this call` paragraph; every diagnostic lands at the
+key that caused it. Three sentences are the whole surface:
+
+```text
+every schema composed on one source must produce an object output - not a primitive, an array or a function
+schemas composed on one source must produce disjoint output keys - merge them in your schema library instead
+'boyd' is not a validation source - the sources are routerParams, query, headers and body
+```
+
+A value that is not a schema is rejected at the offending property, and reading
+an undeclared source in the handler reports as
+`Property 'body' does not exist on type 'ValidatedContext<…>'`.
+
+### Runtime errors for what the types cannot see
+
+For plain-JS callers, `any`-typed schemas, and runtime values no type can
+predict, the runtime mirrors the same rules. **None of these is marked**, so
+`recognizeValidationError` returns `undefined` and your observability hook
+still reports every one.
+
+**At route evaluation**, before any request is served, a plain `Error`: a source
+slot holding something that is not a Standard Schema, naming the source and the
+element index. The route never becomes servable - which is what keeps a `null`
+in a slot from becoming an unattributed
+`TypeError: Cannot read properties of null (reading '~standard')` on every
+request.
+
+**Per request**, as a plain unmarked `500` naming the source:
+
+| what happened                                                             | detected                                     |
+| ------------------------------------------------------------------------- | -------------------------------------------- |
+| an element output that is not a plain object at merge time                | after the tuple ran; names the element index |
+| an element that reported neither a value nor any issue (`{ issues: [] }`) | after the tuple ran; names the element index |
+| a source declared with an empty tuple, so nothing validated it            | at merge time                                |
+
+These are latent by nature - such a route serves `200`s until a request reaches
+the case, and what a schema answers is unknowable without running it. The rule
+behind all three: **a declared source must be delivered as something every
+element actually contributed to.**
+
+### Edges the compile-time guard does not catch
+
+- **Overlap between outputs carrying an index signature is allowed.**
+  `z.looseObject`, `z.record` and any passthrough output widen `keyof` to
+  `string`, so the guard cannot compare them against a sibling's without
+  refusing every merge they appear in. Colliding keys are decided by the
+  runtime's later-wins spread, in tuple order.
+- **An `any`-typed element is accepted, and takes the whole slot with it.** The
+  slot's delivered type becomes `any` - the honest report, since an element that
+  promises nothing cannot be merged into a promise.
+- **Exotic object outputs pass the compile gate.** A `Date`, a `Map` or any
+  class instance _is_ structurally an object, so the declaration is accepted;
+  the runtime merge refuses it with the `500` above, because its meaning lives
+  outside its own enumerable keys.
+- **A malformed `validate` object itself is an untyped `TypeError`.** The guard
+  covers what is _inside_ `validate`, not a `null` in the object's place.
+
+## Turning the module off
+
+`handlerValidation: false` disables the module - a real off-switch for the day
+an auto-import collision needs isolating. It is not an options bag: a stray key
+such as `handlerValidation: { channelToken: 'x' }` is a compile error.
+
+## API reference
+
+Runtime, from `@dphonys/nuxt-handler-validation/server`, both auto-imported
+inside `server/`:
+
+| Export                                          | Role                                                                                    |
+| ----------------------------------------------- | --------------------------------------------------------------------------------------- |
+| `defineValidatedEventHandler({ validate }, fn)` | The wrapper. One signature. Returns a plain h3 `EventHandler`.                          |
+| `recognizeValidationError(error)`               | Observability predicate, process-side only. Returns `ValidationErrorData \| undefined`. |
+
+Types, from `@dphonys/nuxt-handler-validation/types` - type-only, safe to
+import from app code: `ValidationSchemas`, `SourceSchemas`, `ValidationSource`,
+`ValidatedContext<S>`, `SourceValue<T>`, `MergedOutput<T>`, `OutputOf<S>`,
+`ValidationIssue`, `ValidationErrorData`.
+
+**On the name.** `defineValidatedEventHandler` mirrors the _current_ vanilla
+`defineEventHandler`, so its role is obvious on sight. It is deliberately not
+h3 v2's `defineValidatedHandler` - taking that name now would squat on the one
+h3 will auto-import the day Nuxt ships it. Expect a rename at that alignment
+point.
+
+## Repository development
+
+From the repository root:
+
+```sh
+pnpm --filter @dphonys/nuxt-handler-validation dev
+pnpm --filter @dphonys/nuxt-handler-validation typecheck
+pnpm --filter @dphonys/nuxt-handler-validation test
+pnpm --filter @dphonys/nuxt-handler-validation build
+pnpm --filter @dphonys/nuxt-handler-validation publint
+```
+
+## License
+
+Licensed under the [MIT License](./LICENSE).

package/dist/module.d.mts

@@ -0,0 +1,12 @@
+import * as _nuxt_schema from '@nuxt/schema';
+
+/**
+ * The module has zero options. `Record<string, never>` rather than an open
+ * empty type, so a stray key in `handlerValidation` is a compile error while
+ * `{}` and the `false` off-switch still type-check.
+ */
+type ModuleOptions = Record<string, never>;
+declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
+
+export { _default as default };
+export type { ModuleOptions };

package/dist/module.json

@@ -0,0 +1,12 @@
+{
+  "name": "nuxt-handler-validation",
+  "configKey": "handlerValidation",
+  "compatibility": {
+    "nuxt": ">=4.5.1 <5.0.0"
+  },
+  "version": "0.1.0",
+  "builder": {
+    "@nuxt/module-builder": "1.0.3",
+    "unbuild": "unknown"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,22 @@
+import { defineNuxtModule, createResolver, addServerImports } from '@nuxt/kit';
+
+const module$1 = defineNuxtModule({
+  meta: {
+    name: "nuxt-handler-validation",
+    configKey: "handlerValidation",
+    // The ceiling is the only guard against the h3 v2 / Nitro 3 line.
+    compatibility: { nuxt: ">=4.5.1 <5.0.0" }
+  },
+  defaults: {},
+  setup() {
+    const serverEntry = createResolver(import.meta.url).resolve(
+      "./runtime/server/index"
+    );
+    addServerImports([
+      { name: "defineValidatedEventHandler", from: serverEntry },
+      { name: "recognizeValidationError", from: serverEntry }
+    ]);
+  }
+});
+
+export { module$1 as default };

package/dist/runtime/server/index.d.ts

@@ -0,0 +1,34 @@
+import type { EventHandler, EventHandlerRequest, EventHandlerResponse, H3Event } from 'h3';
+import type { ValidatedContext, ValidationErrorData, ValidationSchemas } from '../types/index.js';
+import type { ValidationSchemasGuard } from '../types/internal.js';
+/**
+ * Declare what a route validates, and get the validated values eagerly in the
+ * handler's second parameter. Undeclared sources are absent from it rather than
+ * `unknown`, and the returned handler is an ordinary h3 `EventHandler`.
+ *
+ * Sources validate in the order `routerParams -> query -> headers -> body`,
+ * fail-fast across sources: the first failure answers `400` and no later source
+ * is read, while issues within one source arrive together. The second parameter
+ * is the only door to the validated values - reading the body again with
+ * `readBody` yields h3's memoized unvalidated parse.
+ */
+export declare function defineValidatedEventHandler<const S extends ValidationSchemas, Response extends EventHandlerResponse, Request extends EventHandlerRequest = EventHandlerRequest>(options: {
+    validate: S & ValidationSchemasGuard<S>;
+}, handler: (event: H3Event<Request>, validated: ValidatedContext<S>) => Response): EventHandler<Request, Response>;
+/**
+ * The issues a validation failure raised, or `undefined` for "not a validation
+ * failure" - for a Nitro `error` hook or a Sentry `beforeSend`.
+ *
+ * ```ts
+ * nitroApp.hooks.hook('error', (error) => {
+ *   if (recognizeValidationError(error)) return
+ *   report(error)
+ * })
+ * ```
+ *
+ * Only a `400` validation failure is marked - every developer mistake this
+ * package raises carries no marker, so the early return cannot swallow a bug.
+ * The marker is a non-serialized symbol: recognition works on the live server
+ * error, never on a payload that already crossed the wire.
+ */
+export declare function recognizeValidationError(error: unknown): ValidationErrorData | undefined;

package/dist/runtime/server/index.js

@@ -0,0 +1,12 @@
+import { defineEventHandler } from "h3";
+import { readValidationMarker } from "../shared/error-marker.js";
+import { sourcePlan, validatedContext } from "./lib/validate.js";
+export function defineValidatedEventHandler(options, handler) {
+  const plan = sourcePlan(options.validate);
+  return defineEventHandler(
+    async (event) => handler(event, await validatedContext(event, plan))
+  );
+}
+export function recognizeValidationError(error) {
+  return readValidationMarker(error);
+}

package/dist/runtime/server/lib/issues.d.ts

@@ -0,0 +1,9 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { ValidationSource } from '../../types/index.js';
+/**
+ * The one failure this package answers with: `400`, one fixed shape, identical
+ * in dev and prod, over one source's projected issues. It is also the only
+ * raise in the package that marks its error - what reaches here is a client's
+ * bad input, so an observability hook may skip it.
+ */
+export declare function raiseValidationError(source: ValidationSource, issues: readonly StandardSchemaV1.Issue[]): never;

package/dist/runtime/server/lib/issues.js

@@ -0,0 +1,27 @@
+import { createError } from "h3";
+import { markValidationError } from "../../shared/error-marker.js";
+function projectIssues(source, issues) {
+  return issues.map((issue) => ({
+    source,
+    message: issue.message,
+    path: projectPath(issue.path)
+  }));
+}
+function projectPath(path) {
+  if (path === void 0) return [];
+  return Array.from(path, (segment) => {
+    const key = segment !== null && typeof segment === "object" ? segment.key : segment;
+    return typeof key === "string" || typeof key === "number" ? key : String(key);
+  });
+}
+export function raiseValidationError(source, issues) {
+  const data = { issues: projectIssues(source, issues) };
+  const error = createError({
+    statusCode: 400,
+    statusMessage: "Validation Error",
+    message: `Validation failed for ${source}`,
+    data
+  });
+  markValidationError(error, data.issues);
+  throw error;
+}

package/dist/runtime/server/lib/sources.d.ts

@@ -0,0 +1,20 @@
+import type { H3Event } from 'h3';
+import type { ValidationSource } from '../../types/index.js';
+/** How one source is taken off the event. */
+export type SourceReader = (event: H3Event) => unknown;
+type SourceWalk<Remaining extends ValidationSource = ValidationSource> = [
+    Remaining
+] extends [never] ? readonly [] : {
+    [S in Remaining]: readonly [
+        readonly [source: S, read: SourceReader],
+        ...SourceWalk<Exclude<Remaining, S>>
+    ];
+}[Remaining];
+/**
+ * The four sources in the order they validate - the promise that a bad route
+ * param means the body is never read. Each reaches its schema exactly as h3
+ * yields it: route params decoded and a catch-all slash-joined under one key,
+ * query values as `string | string[]`, header keys lowercased.
+ */
+export declare const SOURCE_WALK: SourceWalk;
+export {};

package/dist/runtime/server/lib/sources.js

@@ -0,0 +1,31 @@
+import { getQuery, getRequestHeaders, getRouterParams, readBody } from "h3";
+import { raiseValidationError } from "./issues.js";
+const PAYLOAD_METHODS = /* @__PURE__ */ new Set([
+  "PATCH",
+  "POST",
+  "PUT",
+  "DELETE"
+]);
+const UNPARSEABLE_BODY_MESSAGE = "Request body could not be parsed";
+function isClientError(error) {
+  if (typeof error !== "object" || error === null || !("statusCode" in error)) {
+    return false;
+  }
+  const { statusCode } = error;
+  return typeof statusCode === "number" && statusCode >= 400 && statusCode < 500;
+}
+async function readBodyForValidation(event) {
+  if (!PAYLOAD_METHODS.has(event.method)) return void 0;
+  try {
+    return await readBody(event, { strict: true });
+  } catch (error) {
+    if (!isClientError(error)) throw error;
+    raiseValidationError("body", [{ message: UNPARSEABLE_BODY_MESSAGE }]);
+  }
+}
+export const SOURCE_WALK = [
+  ["routerParams", (event) => getRouterParams(event, { decode: true })],
+  ["query", (event) => getQuery(event)],
+  ["headers", (event) => getRequestHeaders(event)],
+  ["body", readBodyForValidation]
+];

package/dist/runtime/server/lib/validate.d.ts

@@ -0,0 +1,18 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { H3Event } from 'h3';
+import type { ValidationSchemas, ValidationSource } from '../../types/index.js';
+import type { SourceReader } from './sources.js';
+interface SourcePlan {
+    readonly source: ValidationSource;
+    readonly read: SourceReader;
+    readonly schemas: readonly StandardSchemaV1[];
+}
+/**
+ * Resolve a declaration, once, when the route file is evaluated. Walking
+ * `SOURCE_WALK` rather than the declaration's own keys is what makes the
+ * fail-fast order the package's promise instead of the author's key order.
+ */
+export declare function sourcePlan(schemas: ValidationSchemas): readonly SourcePlan[];
+/** Run one request through the plan, in the plan's order. */
+export declare function validatedContext(event: H3Event, plan: readonly SourcePlan[]): Promise<Record<string, unknown>>;
+export {};

package/dist/runtime/server/lib/validate.js

@@ -0,0 +1,106 @@
+import { createError } from "h3";
+import { raiseValidationError } from "./issues.js";
+import { SOURCE_WALK } from "./sources.js";
+export function sourcePlan(schemas) {
+  const plan = [];
+  for (const [source, read] of SOURCE_WALK) {
+    const slot = schemas[source];
+    if (slot === void 0) continue;
+    const elements = [slot].flat();
+    for (const [position, element] of elements.entries()) {
+      if (!isStandardSchema(element)) raiseUnschemaedSource(source, position);
+    }
+    plan.push({ source, read, schemas: elements });
+  }
+  return plan;
+}
+function isStandardSchema(value) {
+  if (typeof value !== "object" || value === null) return false;
+  if (!("~standard" in value)) return false;
+  const standard = value["~standard"];
+  return typeof standard === "object" && standard !== null && "validate" in standard && typeof standard.validate === "function";
+}
+function raiseUnschemaedSource(source, position) {
+  throw new Error(
+    `[nuxt-handler-validation] cannot validate ${source}: the value at index ${position} is not a Standard Schema. A source slot holds a schema or a non-empty tuple of them - every element must carry a '~standard' property.`
+  );
+}
+export async function validatedContext(event, plan) {
+  const validated = {};
+  for (const { source, read, schemas } of plan) {
+    validated[source] = await validatedValueFor(
+      source,
+      schemas,
+      await read(event)
+    );
+  }
+  return validated;
+}
+async function validatedValueFor(source, schemas, raw) {
+  const issues = [];
+  const outputs = [];
+  let unreportedAt;
+  for (const [position, schema] of schemas.entries()) {
+    const result = await schema["~standard"].validate(raw);
+    if (result.issues === void 0) {
+      outputs.push(result.value);
+      continue;
+    }
+    if (result.issues.length === 0) unreportedAt ??= position;
+    else issues.push(...result.issues);
+  }
+  if (issues.length > 0) raiseValidationError(source, issues);
+  if (unreportedAt !== void 0) raiseUnreportedFailure(source, unreportedAt);
+  return mergeOutputs(source, outputs);
+}
+function mergeOutputs(source, outputs) {
+  if (outputs.length === 0) raiseUnvalidatedSource(source);
+  if (outputs.length === 1) return outputs[0];
+  const merged = {};
+  for (const [position, value] of outputs.entries()) {
+    if (!isPlainObject(value)) raiseUnmergeableOutput(source, position, value);
+    for (const [key, entry] of Object.entries(value)) {
+      Object.defineProperty(merged, key, {
+        value: entry,
+        writable: true,
+        enumerable: true,
+        configurable: true
+      });
+    }
+  }
+  return merged;
+}
+function isPlainObject(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+function raiseSourceFault(message) {
+  throw createError({
+    statusCode: 500,
+    message: `[nuxt-handler-validation] ${message}`
+  });
+}
+function raiseUnmergeableOutput(source, position, value) {
+  raiseSourceFault(
+    `cannot merge the validated ${source}: the schema at index ${position} produced ${describeValue(value)}. Schemas composed on one source merge their outputs, so every element of the tuple must produce a plain object.`
+  );
+}
+function raiseUnreportedFailure(source, position) {
+  raiseSourceFault(
+    `cannot deliver the validated ${source}: the schema at index ${position} reported a failure with no issues. A Standard Schema answers with a value or with at least one issue, so this result names neither an output to deliver nor a reason to reject the request.`
+  );
+}
+function raiseUnvalidatedSource(source) {
+  raiseSourceFault(
+    `cannot deliver the validated ${source}: no schema ran for it. A source slot holds a schema or a non-empty tuple of them - remove the key instead of declaring it empty.`
+  );
+}
+function describeValue(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "an array";
+  if (typeof value === "object") {
+    return `an instance of ${value.constructor?.name ?? "an anonymous class"}`;
+  }
+  return `a value of type ${typeof value}`;
+}

package/dist/runtime/server/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "../../../.nuxt/tsconfig.server.json"
+}

package/dist/runtime/shared/error-marker.d.ts

@@ -0,0 +1,16 @@
+import type { H3Error } from 'h3';
+import type { ValidationErrorData, ValidationIssue } from '../types/index.js';
+export declare const VALIDATION_ERROR_KEY: unique symbol;
+/**
+ * Hang the marker on a validation failure, so an observability hook can tell a
+ * client's bad input from a bug. Non-enumerable and symbol-keyed, so it
+ * survives none of the copies the error takes on its way out; and it is this
+ * function's own snapshot, sharing no object with the enumerable `data` a
+ * middleware downstream can edit.
+ *
+ * The carrier must be an `H3Error`: h3's `createError` is the identity function
+ * for values passing its `__h3_error__` duck check, while any other thrown
+ * value is re-wrapped into a fresh error that copies no symbols.
+ */
+export declare function markValidationError(error: H3Error, issues: readonly ValidationIssue[]): void;
+export declare function readValidationMarker(error: unknown): ValidationErrorData | undefined;

package/dist/runtime/shared/error-marker.js

@@ -0,0 +1,16 @@
+export const VALIDATION_ERROR_KEY = Symbol.for(
+  "@dphonys/nuxt-handler-validation:error"
+);
+export function markValidationError(error, issues) {
+  const marked = {
+    issues: issues.map((issue) => ({ ...issue, path: [...issue.path] }))
+  };
+  Object.defineProperty(error, VALIDATION_ERROR_KEY, {
+    value: marked,
+    enumerable: false
+  });
+}
+export function readValidationMarker(error) {
+  const marker = error?.[VALIDATION_ERROR_KEY];
+  return typeof marker === "object" && marker !== null && Array.isArray(marker.issues) ? marker : void 0;
+}

package/dist/runtime/types/index.d.ts

@@ -0,0 +1,65 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+/** The four sources, in the settled fail-fast order. Every key is optional. */
+export interface ValidationSchemas {
+    routerParams?: SourceSchemas;
+    query?: SourceSchemas;
+    headers?: SourceSchemas;
+    body?: SourceSchemas;
+}
+/** `'routerParams' | 'query' | 'headers' | 'body'`. */
+export type ValidationSource = keyof ValidationSchemas;
+/**
+ * What one source slot accepts: a schema, or a non-empty tuple of schemas that
+ * each parse the same raw source and whose outputs merge. A tuple, not an
+ * array, because a widened `StandardSchemaV1[]` cannot say how many schemas it
+ * holds and the merged output could not be typed.
+ */
+export type SourceSchemas = StandardSchemaV1 | readonly [StandardSchemaV1, ...StandardSchemaV1[]];
+/** A schema's output (`InferOutput`), so transforms land already applied. */
+export type OutputOf<Schema> = Schema extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<Schema> : never;
+type Flattened<T> = string extends keyof T ? T : number extends keyof T ? T : symbol extends keyof T ? T : {
+    [K in keyof T]: T[K];
+};
+type Merged<Head, Rest> = Head extends unknown ? Rest extends unknown ? Flattened<Head & Rest> : never : never;
+/**
+ * A composed tuple's delivered value: element by element rather than through
+ * `UnionToIntersection`, so a schema outputting a union of objects stays a
+ * union through the merge.
+ */
+export type MergedOutput<T> = T extends readonly [
+    infer Head extends StandardSchemaV1,
+    ...infer Rest
+] ? Rest extends readonly [StandardSchemaV1, ...StandardSchemaV1[]] ? Merged<OutputOf<Head>, MergedOutput<Rest>> : OutputOf<Head> : never;
+/** One slot's delivered value: a lone schema's output, or the tuple's merge. */
+export type SourceValue<T> = T extends readonly [
+    StandardSchemaV1,
+    ...StandardSchemaV1[]
+] ? MergedOutput<T> : OutputOf<T>;
+/**
+ * The handler's second parameter: exactly the sources the declaration
+ * guarantees, each typed as its slot's delivered value. A key is guaranteed
+ * only when its slot type cannot be `undefined`, so a declaration annotated
+ * `const schemas: ValidationSchemas = { query }` guarantees nothing and
+ * delivers no sources; use `satisfies ValidationSchemas` instead.
+ */
+export type ValidatedContext<S extends ValidationSchemas> = {
+    [K in Extract<keyof S, ValidationSource> as undefined extends S[K] ? never : K]: SourceValue<S[K]>;
+};
+/**
+ * One projected issue - the whole of what a client is told about a rejected
+ * value. Raw Standard Schema issues never reach it.
+ */
+export interface ValidationIssue {
+    source: ValidationSource;
+    message: string;
+    path: Array<string | number>;
+}
+/**
+ * The h3 error's `data` payload on the wire, and what
+ * `recognizeValidationError` hands a hook. A fetched failure sits at
+ * `err.data.data.issues`.
+ */
+export interface ValidationErrorData {
+    issues: ValidationIssue[];
+}
+export {};

package/dist/runtime/types/internal.d.ts

@@ -0,0 +1,32 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { OutputOf, ValidationSource } from './index.js';
+/**
+ * A rule the declaration broke. Nothing the author wrote can satisfy it, so the
+ * diagnostic prints at the offending source key with this message inside it.
+ */
+export interface ValidationDeclarationError<Msg extends string> {
+    'validation-declaration-error': Msg;
+}
+/** The keys of any member of a union - distributes, unlike bare `keyof`. */
+type KeysOfUnion<T> = T extends unknown ? keyof T : never;
+type NamedKey<K> = string extends K ? never : number extends K ? never : symbol extends K ? never : K;
+type NamedKeys<T> = NamedKey<KeysOfUnion<T>>;
+type IsAny<T> = 0 extends 1 & T ? true : false;
+type ElementOutputs<T extends readonly StandardSchemaV1[]> = {
+    [I in keyof T]: OutputOf<T[I]>;
+};
+type HasKeyOverlap<Outputs extends readonly unknown[]> = Outputs extends readonly [
+    infer Head,
+    ...infer Rest extends readonly unknown[]
+] ? [NamedKeys<Head> & NamedKeys<Rest[number]>] extends [never] ? HasKeyOverlap<Rest> : true : false;
+type IsMergeableOutput<O> = IsAny<O> extends true ? true : O extends object ? O extends readonly unknown[] | ((...args: never[]) => unknown) ? false : true : false;
+type ComposableSlot<T> = T extends readonly [StandardSchemaV1] ? unknown : T extends readonly [StandardSchemaV1, ...StandardSchemaV1[]] ? [IsMergeableOutput<OutputOf<T[number]>>] extends [true] ? HasKeyOverlap<ElementOutputs<T>> extends true ? ValidationDeclarationError<'schemas composed on one source must produce disjoint output keys - merge them in your schema library instead'> : unknown : ValidationDeclarationError<'every schema composed on one source must produce an object output - not a primitive, an array or a function'> : unknown;
+/**
+ * The guard the `validate` parameter intersects with, so a misspelled key
+ * beside a valid one is a compile error at that key rather than a source that
+ * silently never validates.
+ */
+export type ValidationSchemasGuard<S> = {
+    [K in keyof S]: K extends ValidationSource ? ComposableSlot<S[K]> : K extends string ? ValidationDeclarationError<`'${K}' is not a validation source - the sources are routerParams, query, headers and body`> : never;
+};
+export {};

package/dist/types.d.mts

@@ -0,0 +1,3 @@
+export { default } from './module.mjs'
+
+export { type ModuleOptions } from './module.mjs'

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "@dphonys/nuxt-handler-validation",
+  "version": "0.1.0",
+  "description": "Declare a Nitro handler's request schemas once and receive the validated, fully-typed values in the handler's second parameter.",
+  "keywords": [
+    "nuxt",
+    "nuxt-handler-validation",
+    "nuxt-module"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DPHonys/dph-nuxt-stuff.git",
+    "directory": "packages/nuxt-handler-validation"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/module.mjs",
+  "typesVersions": {
+    "*": {
+      ".": [
+        "./dist/types.d.mts"
+      ],
+      "types": [
+        "./dist/runtime/types/index.d.ts"
+      ],
+      "server": [
+        "./dist/runtime/server/index.d.ts"
+      ]
+    }
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/types.d.mts",
+      "import": "./dist/module.mjs"
+    },
+    "./types": {
+      "types": "./dist/runtime/types/index.d.ts",
+      "import": "./dist/runtime/types/index.js"
+    },
+    "./server": {
+      "types": "./dist/runtime/server/index.d.ts",
+      "import": "./dist/runtime/server/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@nuxt/kit": "^4.5.1",
+    "@standard-schema/spec": "^1.1.0",
+    "h3": "^1.15.11"
+  },
+  "devDependencies": {
+    "@nuxt/devtools": "^3.3.1",
+    "@nuxt/module-builder": "^1.0.3",
+    "@nuxt/schema": "^4.5.1",
+    "@nuxt/test-utils": "^4.1.0",
+    "@types/node": "latest",
+    "nuxt": "^4.5.1",
+    "publint": "^0.3.22",
+    "typescript": "^5.9.3",
+    "valibot": "^1.4.2",
+    "vitest": "^4.1.10",
+    "vue-tsc": "^3.3.8",
+    "zod": "^4.4.3"
+  },
+  "engines": {
+    "node": "^22.19.0 || ^24.11.0 || >=26.0.0"
+  },
+  "scripts": {
+    "build": "nuxt-module-build build",
+    "dev": "pnpm run dev:prepare && nuxt dev playground",
+    "dev:build": "nuxt build playground",
+    "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxt prepare playground",
+    "lint": "eslint .",
+    "prebuild": "nuxt-module-build prepare",
+    "pretest": "nuxt-module-build prepare",
+    "pretypecheck": "pnpm run build",
+    "publint": "publint",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "typecheck": "nuxt prepare playground && vue-tsc --noEmit && vue-tsc --noEmit --project playground/tsconfig.json"
+  }
+}