@dphonys/nuxt-handler-validation 0.1.1 → 0.2.0

package/README.md

@@ -67,7 +67,8 @@ export default defineValidatedEventHandler(
 - **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
+  returns a `ValidatedEventHandler` - still assignable to h3's `EventHandler`,
+  carrying the `RequestInput` brand - 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
@@ -388,15 +389,26 @@ such as `handlerValidation: { channelToken: 'x' }` is a compile error.
 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`. |
+| Export                                          | Role                                                                                         |
+| ----------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `defineValidatedEventHandler({ validate }, fn)` | The wrapper. One signature. Returns a `ValidatedEventHandler`, an h3 `EventHandler` subtype. |
+| `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`.
+`ValidationIssue`, `ValidationErrorData`, and the request-input family:
+
+| Type                              | Role                                                                                                     |
+| --------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `InputOf<S>`                      | A schema's input - what the client sends, before transforms.                                             |
+| `MergedInput<T>`                  | A composed tuple's input: the intersection of its element inputs, flattened to one record.               |
+| `SourceInput<T>`                  | One slot's input - a lone schema's input, or the tuple's intersection.                                   |
+| `RequestInput<S>`                 | The request input: keys are the declared sources, values what the client sends for each.                 |
+| `ValidatedEventHandler`           | What `defineValidatedEventHandler` returns: an h3 `EventHandler` carrying its `RequestInput` as a brand. |
+| `RequestInputOfHandler<T>`        | Reads that brand off a handler type; `never` for `any` and for handlers this package did not produce.    |
+| `ValidationSchemasGuard<S>`       | The compile-time guard behind the declaration diagnostics above.                                         |
+| `ValidationDeclarationError<Msg>` | The sentence-shaped type those diagnostics surface.                                                      |
 
 **On the name.** `defineValidatedEventHandler` mirrors the _current_ vanilla
 `defineEventHandler`, so its role is obvious on sight. It is deliberately not
@@ -416,6 +428,9 @@ pnpm --filter @dphonys/nuxt-handler-validation build
 pnpm --filter @dphonys/nuxt-handler-validation publint
 ```
 
+The `internals/*` entries, consumed only by `@dphonys/nuxt-typed-handler`, are
+documented in [`INTERNALS.md`](./INTERNALS.md).
+
 ## License
 
 Licensed under the [MIT License](./LICENSE).

package/dist/module.json

@@ -4,7 +4,7 @@
   "compatibility": {
     "nuxt": ">=4.5.1 <5.0.0"
   },
-  "version": "0.1.1",
+  "version": "0.2.0",
   "builder": {
     "@nuxt/module-builder": "1.0.3",
     "unbuild": "unknown"

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

@@ -0,0 +1,4 @@
+export { sourcePlan, validatedContext } from '../../server/lib/validate.js';
+export type { SourcePlan, ValidatedContextOptions, } from '../../server/lib/validate.js';
+export { raiseValidationError } from '../../server/lib/issues.js';
+export type { OnInvalid } from '../../server/lib/issues.js';

package/dist/runtime/internals/server/index.js

@@ -0,0 +1,2 @@
+export { sourcePlan, validatedContext } from "../../server/lib/validate.js";
+export { raiseValidationError } from "../../server/lib/issues.js";

package/dist/runtime/internals/shared/index.d.ts

@@ -0,0 +1 @@
+export { markValidationError, readValidationMarker, VALIDATION_ERROR_KEY, } from '../../shared/error-marker.js';

package/dist/runtime/internals/shared/index.js

@@ -0,0 +1,5 @@
+export {
+  markValidationError,
+  readValidationMarker,
+  VALIDATION_ERROR_KEY
+} from "../../shared/error-marker.js";

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

@@ -1,10 +1,10 @@
-import type { EventHandler, EventHandlerRequest, EventHandlerResponse, H3Event } from 'h3';
-import type { ValidatedContext, ValidationErrorData, ValidationSchemas } from '../types/index.js';
-import type { ValidationSchemasGuard } from '../types/internal.js';
+import type { EventHandlerRequest, EventHandlerResponse, H3Event } from 'h3';
+import type { RequestInput, ValidatedContext, ValidatedEventHandler, ValidationErrorData, ValidationSchemas, ValidationSchemasGuard } from '../types/index.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`.
+ * `unknown`, and the returned handler is an ordinary h3 `EventHandler` that
+ * additionally carries the computed Request input as a phantom type slot.
  *
  * Sources validate in the order `routerParams -> query -> headers -> body`,
  * fail-fast across sources: the first failure answers `400` and no later source
@@ -14,7 +14,7 @@ import type { ValidationSchemasGuard } from '../types/internal.js';
  */
 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>;
+}, handler: (event: H3Event<Request>, validated: ValidatedContext<S>) => Response): ValidatedEventHandler<Request, Response, RequestInput<S>>;
 /**
  * The issues a validation failure raised, or `undefined` for "not a validation
  * failure" - for a Nitro `error` hook or a Sentry `beforeSend`.

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

@@ -1,9 +1,20 @@
 import type { StandardSchemaV1 } from '@standard-schema/spec';
-import type { ValidationSource } from '../../types/index.js';
+import type { ValidationIssue, 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.
+ * The per-request failure door. Receives projected issues, all from one
+ * source, and must not return.
  */
-export declare function raiseValidationError(source: ValidationSource, issues: readonly StandardSchemaV1.Issue[]): never;
+export type OnInvalid = (source: ValidationSource, issues: readonly ValidationIssue[]) => never;
+/**
+ * Projection by construction, never by filtering: nothing is copied across but
+ * the message and the normalized path, so no vendor extra reaches a client or
+ * an `onInvalid` hook. Module-level for `validate.ts`; no entry re-exports it.
+ */
+export declare function projectIssues(source: ValidationSource, issues: readonly StandardSchemaV1.Issue[]): ValidationIssue[];
+/**
+ * The default `onInvalid`: `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 ValidationIssue[]): never;

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

@@ -1,6 +1,6 @@
 import { createError } from "h3";
 import { markValidationError } from "../../shared/error-marker.js";
-function projectIssues(source, issues) {
+export function projectIssues(source, issues) {
   return issues.map((issue) => ({
     source,
     message: issue.message,
@@ -15,7 +15,7 @@ function projectPath(path) {
   });
 }
 export function raiseValidationError(source, issues) {
-  const data = { issues: projectIssues(source, issues) };
+  const data = { issues: [...issues] };
   const error = createError({
     statusCode: 400,
     statusMessage: "Validation Error",

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

@@ -1,7 +1,11 @@
 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;
+import type { OnInvalid } from './issues.js';
+/**
+ * How one source is taken off the event. A read that already knows the input
+ * is bad reports through `onInvalid`, the same door a rejecting schema uses.
+ */
+export type SourceReader = (event: H3Event, onInvalid: OnInvalid) => unknown;
 type SourceWalk<Remaining extends ValidationSource = ValidationSource> = [
     Remaining
 ] extends [never] ? readonly [] : {

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

@@ -1,5 +1,4 @@
 import { getQuery, getRequestHeaders, getRouterParams, readBody } from "h3";
-import { raiseValidationError } from "./issues.js";
 const PAYLOAD_METHODS = /* @__PURE__ */ new Set([
   "PATCH",
   "POST",
@@ -14,13 +13,15 @@ function isClientError(error) {
   const { statusCode } = error;
   return typeof statusCode === "number" && statusCode >= 400 && statusCode < 500;
 }
-async function readBodyForValidation(event) {
+async function readBodyForValidation(event, onInvalid) {
   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 }]);
+    onInvalid("body", [
+      { source: "body", message: UNPARSEABLE_BODY_MESSAGE, path: [] }
+    ]);
   }
 }
 export const SOURCE_WALK = [

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

@@ -1,8 +1,14 @@
 import type { StandardSchemaV1 } from '@standard-schema/spec';
 import type { H3Event } from 'h3';
 import type { ValidationSchemas, ValidationSource } from '../../types/index.js';
+import type { OnInvalid } from './issues.js';
 import type { SourceReader } from './sources.js';
-interface SourcePlan {
+/**
+ * One resolved source slot: its reader and its schema list. The schemas are
+ * always a list - a bare slot is its own one-element list, settled here so
+ * nothing downstream asks which shape the author wrote.
+ */
+export interface SourcePlan {
     readonly source: ValidationSource;
     readonly read: SourceReader;
     readonly schemas: readonly StandardSchemaV1[];
@@ -13,6 +19,14 @@ interface SourcePlan {
  * 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 {};
+/** What a caller may swap in per request; the parent passes nothing. */
+export interface ValidatedContextOptions {
+    /** Defaults to `raiseValidationError`. */
+    readonly onInvalid?: OnInvalid;
+}
+/**
+ * Run one request through the plan, in the plan's order. Every client-input
+ * rejection - a rejecting schema and an unparseable body alike - goes through
+ * `onInvalid`; the developer-mistake `500`s never do.
+ */
+export declare function validatedContext(event: H3Event, plan: readonly SourcePlan[], options?: ValidatedContextOptions): Promise<Record<string, unknown>>;

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

@@ -1,5 +1,5 @@
 import { createError } from "h3";
-import { raiseValidationError } from "./issues.js";
+import { projectIssues, raiseValidationError } from "./issues.js";
 import { SOURCE_WALK } from "./sources.js";
 export function sourcePlan(schemas) {
   const plan = [];
@@ -25,18 +25,20 @@ function raiseUnschemaedSource(source, position) {
     `[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) {
+export async function validatedContext(event, plan, options = {}) {
+  const onInvalid = options.onInvalid ?? raiseValidationError;
   const validated = {};
   for (const { source, read, schemas } of plan) {
     validated[source] = await validatedValueFor(
       source,
       schemas,
-      await read(event)
+      await read(event, onInvalid),
+      onInvalid
     );
   }
   return validated;
 }
-async function validatedValueFor(source, schemas, raw) {
+async function validatedValueFor(source, schemas, raw, onInvalid) {
   const issues = [];
   const outputs = [];
   let unreportedAt;
@@ -49,7 +51,7 @@ async function validatedValueFor(source, schemas, raw) {
     if (result.issues.length === 0) unreportedAt ??= position;
     else issues.push(...result.issues);
   }
-  if (issues.length > 0) raiseValidationError(source, issues);
+  if (issues.length > 0) onInvalid(source, projectIssues(source, issues));
   if (unreportedAt !== void 0) raiseUnreportedFailure(source, unreportedAt);
   return mergeOutputs(source, outputs);
 }

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

@@ -1,4 +1,7 @@
 import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { EventHandler, EventHandlerRequest, EventHandlerResponse } from 'h3';
+import type { IsAny } from './internal.js';
+export type { ValidationDeclarationError, ValidationSchemasGuard, } from './internal.js';
 /** The four sources, in the settled fail-fast order. Every key is optional. */
 export interface ValidationSchemas {
     routerParams?: SourceSchemas;
@@ -17,6 +20,8 @@ export type ValidationSource = keyof ValidationSchemas;
 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;
+/** A schema's input (`InferInput`) - what the client sends, before transforms. */
+export type InputOf<Schema> = Schema extends StandardSchemaV1 ? StandardSchemaV1.InferInput<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];
 };
@@ -35,6 +40,20 @@ export type SourceValue<T> = T extends readonly [
     StandardSchemaV1,
     ...StandardSchemaV1[]
 ] ? MergedOutput<T> : OutputOf<T>;
+/**
+ * A composed tuple's input: the intersection of element inputs, flattened to
+ * one record - every element parses the whole raw source, so the wire must
+ * satisfy all of them. Outputs merge later-wins; inputs intersect.
+ */
+export type MergedInput<T> = T extends readonly [
+    infer Head extends StandardSchemaV1,
+    ...infer Rest
+] ? Rest extends readonly [StandardSchemaV1, ...StandardSchemaV1[]] ? Flattened<InputOf<Head> & MergedInput<Rest>> : InputOf<Head> : never;
+/** One slot's input: a lone schema's input, or the tuple's intersection. */
+export type SourceInput<T> = T extends readonly [
+    StandardSchemaV1,
+    ...StandardSchemaV1[]
+] ? MergedInput<T> : InputOf<T>;
 /**
  * The handler's second parameter: exactly the sources the declaration
  * guarantees, each typed as its slot's delivered value. A key is guaranteed
@@ -45,6 +64,32 @@ export type SourceValue<T> = T extends readonly [
 export type ValidatedContext<S extends ValidationSchemas> = {
     [K in Extract<keyof S, ValidationSource> as undefined extends S[K] ? never : K]: SourceValue<S[K]>;
 };
+/**
+ * The Request input: keys = declared sources, values = what the client sends.
+ * Same key rule as `ValidatedContext` - a slot typed `| undefined` declares
+ * nothing and contributes no key.
+ */
+export type RequestInput<S extends ValidationSchemas> = {
+    [K in Extract<keyof S, ValidationSource> as undefined extends S[K] ? never : K]: SourceInput<S[K]>;
+};
+declare const validatedRequestInput: unique symbol;
+/**
+ * The handler `defineValidatedEventHandler` returns: an ordinary h3
+ * `EventHandler` carrying the computed Request input in a phantom slot. The
+ * slot is never assigned at runtime; it exists so a typed client can read what
+ * the route expects from `RequestInputOfHandler`.
+ */
+export interface ValidatedEventHandler<Request extends EventHandlerRequest = EventHandlerRequest, Response extends EventHandlerResponse = EventHandlerResponse, Input = never> extends EventHandler<Request, Response> {
+    [validatedRequestInput]?: Input;
+}
+/**
+ * The Request input a branded handler carries, or `never` for `any` and for
+ * any handler this package did not produce. `never` rather than `{}` on
+ * purpose: a reader guards `[Input] extends [never]` before keying on it.
+ */
+export type RequestInputOfHandler<T> = IsAny<T> extends true ? never : T extends {
+    [validatedRequestInput]?: infer I;
+} ? Exclude<I, undefined> : never;
 /**
  * One projected issue - the whole of what a client is told about a rejected
  * value. Raw Standard Schema issues never reach it.
@@ -62,4 +107,3 @@ export interface ValidationIssue {
 export interface ValidationErrorData {
     issues: ValidationIssue[];
 }
-export {};

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

@@ -11,7 +11,7 @@ export interface ValidationDeclarationError<Msg extends string> {
 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;
+export type IsAny<T> = 0 extends 1 & T ? true : false;
 type ElementOutputs<T extends readonly StandardSchemaV1[]> = {
     [I in keyof T]: OutputOf<T[I]>;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dphonys/nuxt-handler-validation",
-  "version": "0.1.1",
+  "version": "0.2.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",
@@ -29,6 +29,12 @@
       ],
       "server": [
         "./dist/runtime/server/index.d.ts"
+      ],
+      "internals/server": [
+        "./dist/runtime/internals/server/index.d.ts"
+      ],
+      "internals/shared": [
+        "./dist/runtime/internals/shared/index.d.ts"
       ]
     }
   },
@@ -44,7 +50,16 @@
     "./server": {
       "types": "./dist/runtime/server/index.d.ts",
       "import": "./dist/runtime/server/index.js"
-    }
+    },
+    "./internals/server": {
+      "types": "./dist/runtime/internals/server/index.d.ts",
+      "import": "./dist/runtime/internals/server/index.js"
+    },
+    "./internals/shared": {
+      "types": "./dist/runtime/internals/shared/index.d.ts",
+      "import": "./dist/runtime/internals/shared/index.js"
+    },
+    "./package.json": "./package.json"
   },
   "publishConfig": {
     "access": "public"