@stone-js/validation 0.8.7 → 0.8.9

package/README.md

@@ -25,6 +25,33 @@ domain once, and the context (runtime, protocol, caller) applies to it at run ti
 npm i @stone-js/validation
 ```
 
+## Enabling it
+
+Like every Stone.js module, it is enabled in one of two ways, and configured afterwards under
+`stone.validation`. It registers the validation provider, so the validator is injectable and the route decorators resolve.
+
+```ts
+import { Validation } from '@stone-js/validation'
+import { StoneApp } from '@stone-js/core'
+
+@Validation()
+@StoneApp({ name: 'my-app' })
+export class Application {}
+```
+
+```ts
+import { defineStoneApp } from '@stone-js/core'
+import { validationBlueprint } from '@stone-js/validation'
+
+export const Application = defineStoneApp({ name: 'my-app' }, [validationBlueprint])
+```
+
+Configure it from a `@Configuration` class or `defineConfig`:
+
+```ts
+export const AppConfig = defineConfig((blueprint) => blueprint.set('stone.validation', { /* ... */ }))
+```
+
 ## Usage
 
 ```ts

package/dist/ValidationServiceProvider.d.ts

@@ -2,6 +2,14 @@ import { IContainer, IServiceProvider, Promiseable } from '@stone-js/core';
 /**
  * Registers the {@link Validator} service (singleton) in the container, aliased as
  * `validator`/`Validator`, so middleware, handlers and services can resolve it.
+ *
+ * It also binds whatever schema engines the application declared under
+ * `stone.validation.engines`, so a schema class can take its engine through its constructor:
+ * `constructor ({ zod })`. That is more elegant than importing the library at every schema, and more
+ * testable, since a test hands the class a fake instead of mocking a module.
+ *
+ * The application names the engine; this module never imports one. That is what keeps it agnostic:
+ * Zod, Valibot and ArkType arrive through Standard Schema, and a native schema needs no engine at all.
  */
 export declare class ValidationServiceProvider implements IServiceProvider {
     private readonly container;
@@ -10,7 +18,7 @@ export declare class ValidationServiceProvider implements IServiceProvider {
      */
     constructor(container: IContainer);
     /**
-     * Register the validation service.
+     * Register the validation service and any declared schema engine.
      */
     register(): Promiseable<void>;
 }

package/dist/Validator.d.ts

@@ -1,4 +1,4 @@
-import { IValidator, SchemaInput, ValidationResult } from './declarations';
+import { IValidator, SchemaInput, ValidationResult } from './declarations.js';
 /**
  * The validation service.
  *

package/dist/adapters/standardSchema.d.ts

@@ -1,4 +1,4 @@
-import { ValidationSchema, StandardSchemaV1 } from '../declarations';
+import { ValidationSchema, StandardSchemaV1 } from '../declarations.js';
 /**
  * Adapts a [Standard Schema](https://standardschema.dev) (Zod 3.24+, Valibot, ArkType, …) to the
  * Stone.js {@link ValidationSchema} contract. Only the synchronous path is supported here; an

package/dist/adapters/zod.d.ts

@@ -1,4 +1,4 @@
-import { ValidationSchema, ZodLikeSchema } from '../declarations';
+import { ValidationSchema, ZodLikeSchema } from '../declarations.js';
 /**
  * Adapts a Zod-style schema (anything exposing a synchronous `safeParse`) to the Stone.js
  * {@link ValidationSchema} contract. Structural — never imports Zod, so it works with any

package/dist/declarations.d.ts

@@ -95,6 +95,40 @@ export interface IValidator {
  * Validation configuration (`stone.validation.*`).
  */
 export interface ValidationOptions {
-    /** Whether to strip unknown keys is left to the schema; reserved for future options. */
-    reserved?: never;
+    /**
+     * Named rule sets a route can refer to by name, instead of importing the schemas at the route.
+     *
+     * ```ts
+     * blueprint.set('stone.validation.schemas', { createUser: { body: CreateUserSchema } })
+     * // then, on the route: { validation: 'createUser' }
+     * ```
+     *
+     * Naming a rule set that is not registered fails loudly at request time rather than validating
+     * nothing, because silently accepting anything is the one outcome a validator must never have.
+     */
+    schemas?: Record<string, Record<string, SchemaInput>>;
+    /**
+     * Schema engines to make resolvable from the container, keyed by the name to resolve them under.
+     *
+     * ```ts
+     * import { z } from 'zod'
+     * blueprint.set('stone.validation.engines', { zod: z })
+     * ```
+     *
+     * A schema class then takes its engine through its constructor, which is both more elegant and
+     * more testable: a test hands it a fake instead of mocking a module.
+     *
+     * ```ts
+     * @ValidationSchema('createUser')
+     * export class CreateUserSchema implements IValidationSchema {
+     *   constructor ({ zod }: { zod: typeof z }) { this.z = zod }
+     *   rules () { return { body: this.z.object({ email: this.z.string().email() }) } }
+     * }
+     * ```
+     *
+     * The application names the engine; this module never imports one. That is what keeps it agnostic:
+     * Zod, Valibot and ArkType arrive through Standard Schema, and a native schema needs no engine at
+     * all. Binding a specific library here would make every application depend on it.
+     */
+    engines?: Record<string, unknown>;
 }

package/dist/decorators/Validate.d.ts

@@ -0,0 +1,34 @@
+import { RouteValidationInput } from '../sources.js';
+/**
+ * What a handler declares it accepts: a schema (the body), a map of schemas by source, or the alias
+ * of a schema class registered with `@ValidationSchema`.
+ */
+export type ValidateInput = RouteValidationInput | string;
+/**
+ * What `@Validate` records for one handler method.
+ */
+export interface ValidateMetadata {
+    /** The decorated method's name, so the declaration can be found again at request time. */
+    action: string | symbol;
+    /** What that method accepts. */
+    validation: ValidateInput;
+}
+/**
+ * Method decorator: declare what a handler accepts.
+ *
+ * ```ts
+ * @Validate(CreateUserSchema)                       // the body
+ * @Validate({ body: CreateUserSchema, query: Page }) // several sources
+ * @Validate('createUser')                            // a registered schema class
+ * ```
+ *
+ * This knows nothing about the router, and that is the point: the declaration is recorded on the
+ * handler itself, under this module's own key, so validation runs the same in a routed application,
+ * a single-handler service, a CLI command or the browser. When a router *is* in play you may instead
+ * put it on the route (`@Post('/users', { validation: … })`), which keeps the method uncluttered and
+ * puts everything a route does in one place; both forms end up in the same middleware.
+ *
+ * @param validation - What the handler accepts.
+ * @returns A method decorator.
+ */
+export declare const Validate: <T extends Function = Function>(validation: ValidateInput) => MethodDecorator;

package/dist/decorators/Validation.d.ts

@@ -0,0 +1,29 @@
+import { ValidationConfig } from '../options/ValidationBlueprint.js';
+import { ClassType } from '@stone-js/core';
+/**
+ * Options for the `@Validation` decorator: the `stone.validation` bucket, every key optional.
+ */
+export interface ValidationDecoratorOptions extends ValidationConfig {
+}
+/**
+ * Class decorator: validate incoming data against the schemas you already write, declaratively.
+ *
+ * `@Validation()` registers the validation service provider, so `constructor ({ validator })` works
+ * anywhere and the `@Validate()` route decorators have something to resolve. There is no kernel
+ * middleware here: validation runs where it is asked for, not on every event.
+ *
+ * The declarative half of the pair; `validationBlueprint` handed to `defineStoneApp` is the imperative one.
+ *
+ * @param options - The validation configuration. Everything is optional.
+ * @returns A class decorator.
+ *
+ * @example
+ * ```typescript
+ * import { Validation } from '@stone-js/validation'
+ *
+ * @Validation({ abortEarly: false })
+ * @StoneApp({ name: 'my-app' })
+ * export class Application {}
+ * ```
+ */
+export declare const Validation: <T extends ClassType = ClassType>(options?: ValidationDecoratorOptions) => ClassDecorator;

package/dist/decorators/ValidationSchema.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Class decorator: register a schema class under a name.
+ *
+ * ```ts
+ * @ValidationSchema('createUser')
+ * export class CreateUserSchema implements IValidationSchema { rules () { … } }
+ * ```
+ *
+ * Routes and handlers then refer to it by name (`@Validate('createUser')`), so schemas live in their
+ * own files, organised however the application likes, and nothing has to be imported at the route.
+ * The class is resolved by the container, so its constructor receives services and `rules()` can use
+ * them.
+ *
+ * @param alias - The name the schema is registered under. Defaults to the class name, which the
+ * discovery middleware fills in, since it is the one holding the class.
+ * @returns A class decorator.
+ */
+export declare const ValidationSchema: (alias?: string) => ClassDecorator;

package/dist/decorators/constants.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Metadata key carrying what a handler method declared with `@Validate`.
+ *
+ * The module owns its key, which is what makes it independent: validation works whether or not a
+ * router is in play, because the declaration lives on the handler, not on a route.
+ */
+export declare const VALIDATE_KEY = "@stone-js/validation/validate";
+/**
+ * Metadata key carrying the alias a schema class registered itself under.
+ */
+export declare const VALIDATION_SCHEMA_KEY = "@stone-js/validation/schema";

package/dist/errors/ValidationError.d.ts

@@ -1,4 +1,4 @@
-import { ValidationIssue } from '../declarations';
+import { ValidationIssue } from '../declarations.js';
 import { IntegrationError } from '@stone-js/core';
 import type { ErrorOptions } from '@stone-js/core';
 /**

package/dist/index.d.ts

@@ -1,10 +1,18 @@
-export * from './ValidationServiceProvider';
-export * from './Validator';
-export * from './adapters/standardSchema';
-export * from './adapters/zod';
-export * from './declarations';
-export * from './errors/ValidationError';
-export * from './middleware/validate';
-export * from './options/ValidationBlueprint';
-export * from './schema';
-export * from './validateEvent';
+export * from './ValidationServiceProvider.js';
+export * from './Validator.js';
+export * from './adapters/standardSchema.js';
+export * from './adapters/zod.js';
+export * from './declarations.js';
+export * from './decorators/Validate.js';
+export * from './decorators/Validation.js';
+export * from './decorators/ValidationSchema.js';
+export * from './decorators/constants.js';
+export * from './errors/ValidationError.js';
+export * from './middleware/BlueprintMiddleware.js';
+export * from './middleware/ValidateRouteMiddleware.js';
+export * from './middleware/validate.js';
+export * from './options/ValidationBlueprint.js';
+export * from './schema.js';
+export * from './schemaClass.js';
+export * from './sources.js';
+export * from './validateEvent.js';

package/dist/index.js

@@ -1,4 +1,5 @@
-import { IntegrationError } from '@stone-js/core';
+import { IntegrationError, hasMetadata, getMetadata, classDecoratorLegacyWrapper, addBlueprint, methodDecoratorLegacyWrapper, addMetadata, setClassMetadata } from '@stone-js/core';
+import { cloneValue } from '@stone-js/config';
 
 /**
  * Adapts a Zod-style schema (anything exposing a synchronous `safeParse`) to the Stone.js
@@ -198,6 +199,14 @@ class Validator {
 /**
  * Registers the {@link Validator} service (singleton) in the container, aliased as
  * `validator`/`Validator`, so middleware, handlers and services can resolve it.
+ *
+ * It also binds whatever schema engines the application declared under
+ * `stone.validation.engines`, so a schema class can take its engine through its constructor:
+ * `constructor ({ zod })`. That is more elegant than importing the library at every schema, and more
+ * testable, since a test hands the class a fake instead of mocking a module.
+ *
+ * The application names the engine; this module never imports one. That is what keeps it agnostic:
+ * Zod, Valibot and ArkType arrive through Standard Schema, and a native schema needs no engine at all.
  */
 class ValidationServiceProvider {
     container;
@@ -208,13 +217,141 @@ class ValidationServiceProvider {
         this.container = container;
     }
     /**
-     * Register the validation service.
+     * Register the validation service and any declared schema engine.
      */
     register() {
         this.container
             .singletonIf(Validator, () => Validator.create())
             .alias(Validator, ['validator', 'Validator']);
+        const engines = this.container
+            .make('blueprint')
+            .get('stone.validation', {})
+            .engines ?? {};
+        for (const [name, engine] of Object.entries(engines)) {
+            // `instanceIf` so an application that already bound the name keeps its own binding.
+            this.container.instanceIf(name, engine);
+        }
+    }
+}
+
+/**
+ * Whether a value is a schema rather than a map of schemas.
+ *
+ * A schema is recognised by what it can do, not by what it is: every engine Stone.js accepts exposes
+ * one of `validate`, `~standard`, `parse` or `safeParse`. Anything else is treated as a map of
+ * sources, which is why `{ body: X }` and `X` can share one option without ambiguity.
+ *
+ * @param value - The declared value.
+ * @returns Whether it is a single schema.
+ */
+function isSchemaLike(value) {
+    if (typeof value !== 'object' || value === null) {
+        return typeof value === 'function';
+    }
+    const candidate = value;
+    return (typeof candidate.validate === 'function' ||
+        typeof candidate.parse === 'function' ||
+        typeof candidate.safeParse === 'function' ||
+        candidate['~standard'] !== undefined);
+}
+/**
+ * Normalise what a route declared into rules keyed by source.
+ *
+ * A bare schema becomes `{ body: schema }`, because a route that names one schema means its payload.
+ *
+ * @param declared - What the route declared.
+ * @returns The rules, keyed by source.
+ */
+function toValidationRules(declared) {
+    return isSchemaLike(declared) ? { body: declared } : declared;
+}
+/**
+ * Read a whole source off an event.
+ *
+ * `body`, `query` and `params` are read as wholes, because a schema validates the payload, not one
+ * field of it. `event.get('body')` would look for a field *named* body inside the body, which is a
+ * different question. Any other key falls back to `event.get`, so a context that exposes something
+ * else (a CLI argument set, a message attribute) validates just as well.
+ *
+ * `query` is normalised from `URLSearchParams` to a plain object, since that is what a schema can
+ * parse.
+ *
+ * @param event - The incoming event.
+ * @param source - The source name.
+ * @returns The value to validate.
+ */
+function readSource(event, source) {
+    if (source === 'body') {
+        return event.getBody?.() ?? event.body;
     }
+    if (source === 'params') {
+        return event.params ?? event.get(source);
+    }
+    if (source === 'query') {
+        const query = event.query ?? event.get(source);
+        return query instanceof URLSearchParams ? Object.fromEntries(query) : query;
+    }
+    return event.get(source);
+}
+/**
+ * The metadata key a validated source is published under.
+ *
+ * `body` becomes `validatedBody`, `query` becomes `validatedQuery`. The name is predictable on
+ * purpose: a handler reads `event.get<CreateUser>('validatedBody')` and needs no helper, no import
+ * and nothing to remember beyond the source it declared.
+ *
+ * @param source - The source name.
+ * @returns The metadata key.
+ */
+function metadataKeyFor(source) {
+    return `validated${source.charAt(0).toUpperCase()}${source.slice(1)}`;
+}
+
+/**
+ * Whether a value is a schema class rather than a schema or a rule map.
+ *
+ * @param value - The candidate.
+ * @returns Whether it must be resolved before use.
+ */
+function isValidationSchemaClass(value) {
+    return typeof value === 'function' && typeof value.prototype?.rules === 'function';
+}
+/**
+ * Whether a value is an already-built schema instance.
+ *
+ * @param value - The candidate.
+ * @returns Whether it exposes `rules()`.
+ */
+function isValidationSchema(value) {
+    return typeof value === 'object' && value !== null && typeof value.rules === 'function';
+}
+/**
+ * The imperative counterpart of a schema class: a plain function returning the rules.
+ *
+ * It receives the same dependencies a class would get through its constructor, so it can reach the
+ * container's services too.
+ *
+ * @param rules - Returns what to validate, per source.
+ * @returns A schema instance.
+ *
+ * @example
+ * ```typescript
+ * export const createUserSchema = defineValidationSchema(({ i18n }) => ({
+ *   body: z.object({ email: z.string().email(i18n.t('validation.email')) })
+ * }))
+ * ```
+ */
+function defineValidationSchema(rules) {
+    return (dependencies) => ({ rules: () => rules(dependencies) });
+}
+/**
+ * Read the rules out of whatever a declaration resolved to.
+ *
+ * @param resolved - A schema instance, a schema, or a rule map.
+ * @returns The rules, keyed by source.
+ */
+function rulesOf(resolved) {
+    return toValidationRules(isValidationSchema(resolved) ? resolved.rules() : resolved);
 }
 
 /**
@@ -227,16 +364,26 @@ class ValidationServiceProvider {
  * Platform-agnostic: the event only needs a `get(key)` method, so it works for HTTP, CLI, browser
  * or any other context.
  *
+ * Returns the **parsed** values, keyed as the rules were. A schema does not only accept or reject,
+ * it coerces and strips: `z.coerce.number()` turns `"42"` into `42`, and a strict object drops the
+ * keys you did not declare. Throwing the parsed value away and reading the raw input again is how
+ * an application ends up validating one value and using another.
+ *
  * @param event - The incoming event (anything with `get`).
  * @param rules - The validation rules.
  * @param validator - The validator to use (defaults to a fresh stateless one).
+ * @returns The parsed value for each rule.
  * @throws {ValidationError} When any input fails validation.
  */
 function validateEvent(event, rules, validator = Validator.create()) {
     const issues = [];
+    const parsed = {};
     for (const [key, schema] of Object.entries(rules)) {
         const result = validator.validate(schema, event.get(key));
-        if (!result.success) {
+        if (result.success) {
+            parsed[key] = result.value;
+        }
+        else {
             for (const issue of result.issues) {
                 issues.push({ ...issue, path: [key, ...issue.path] });
             }
@@ -245,8 +392,327 @@ function validateEvent(event, rules, validator = Validator.create()) {
     if (issues.length > 0) {
         throw new ValidationError('The given data failed validation.', { issues });
     }
+    return parsed;
 }
 
+/**
+ * Metadata key carrying what a handler method declared with `@Validate`.
+ *
+ * The module owns its key, which is what makes it independent: validation works whether or not a
+ * router is in play, because the declaration lives on the handler, not on a route.
+ */
+const VALIDATE_KEY = '@stone-js/validation/validate';
+/**
+ * Metadata key carrying the alias a schema class registered itself under.
+ */
+const VALIDATION_SCHEMA_KEY = '@stone-js/validation/schema';
+
+/**
+ * Route middleware: validates what a route declared, before its handler runs.
+ *
+ * A route says what it accepts, once, where the route is defined:
+ *
+ * ```ts
+ * @Post('/users', { validation: { body: CreateUserSchema } })
+ * ```
+ *
+ * A single schema means the body, which is what almost every route means; a map validates several
+ * sources at once (`{ body, query, params }`).
+ *
+ * This middleware reads that from the matched route and validates it. On success each **parsed**
+ * source is published in the event's metadata under a predictable name, so a handler reads
+ * `event.get<CreateUser>('validatedBody')` with no helper and no import. That matters more than it
+ * looks: a schema coerces and strips, and re-reading the raw value is how an application validates
+ * one thing and uses another. On failure it throws a `ValidationError` carrying every issue at once.
+ *
+ * The route stays the single description of itself, which is what lets `@stone-js/openapi` publish
+ * the request schema without being told a second time.
+ */
+class ValidateRouteMiddleware {
+    blueprint;
+    container;
+    validator;
+    /**
+     * @param dependencies - Auto-wired container services.
+     */
+    constructor({ blueprint, container }) {
+        this.blueprint = blueprint;
+        this.container = container;
+        this.validator = Validator.create();
+    }
+    /**
+     * Validate the matched route's declared input, then continue.
+     *
+     * @param event - The incoming event.
+     * @param next - The next middleware.
+     * @returns The response.
+     */
+    async handle(event, next) {
+        const rules = this.rulesFor(event);
+        if (rules !== undefined) {
+            event.setMetadataValue(this.validateSources(event, rules));
+        }
+        return await next(event);
+    }
+    /**
+     * Validate every declared source, and return what to publish on the event.
+     *
+     * Every source is validated before anything is thrown, so a caller sees the full picture rather
+     * than one failure at a time.
+     *
+     * @param event - The incoming event.
+     * @param rules - The rules, keyed by source.
+     * @returns The parsed sources, keyed by their metadata name.
+     * @throws {ValidationError} When any source fails.
+     */
+    validateSources(event, rules) {
+        const issues = [];
+        const parsed = {};
+        for (const [source, schema] of Object.entries(rules)) {
+            const result = this.validator.validate(schema, readSource(event, source));
+            if (result.success) {
+                parsed[metadataKeyFor(source)] = result.value;
+            }
+            else {
+                issues.push(...result.issues.map((issue) => ({ ...issue, path: [source, ...issue.path] })));
+            }
+        }
+        if (issues.length > 0) {
+            throw new ValidationError('The given data failed validation.', { issues });
+        }
+        return parsed;
+    }
+    /**
+     * The rules the matched route declared, with a registered name resolved to its rule set.
+     *
+     * @param event - The incoming event.
+     * @returns The rules, or `undefined` when the route declares none.
+     */
+    rulesFor(event) {
+        const declared = this.declarationFor(event);
+        if (declared === undefined) {
+            return undefined;
+        }
+        if (typeof declared !== 'string') {
+            return rulesOf(declared);
+        }
+        const registry = this.blueprint.get('stone.validation', {}).schemas ?? {};
+        const named = registry[declared];
+        if (named === undefined) {
+            throw new TypeError(`The route declares \`validation: '${declared}'\`, but no rule set is registered under that ` +
+                'name. Register it with `blueprint.set(\'stone.validation.schemas\', { ' + declared + ': { … } })`, ' +
+                'or declare the rules inline on the route.');
+        }
+        return rulesOf(this.resolve(named));
+    }
+    /**
+     * What the handler about to run declared, from either of the two places it may live.
+     *
+     * The route's own option comes first, because when a router is in play a route is the single
+     * description of itself and that is where a reader looks. Failing that, the handler's own
+     * `@Validate` metadata is read: that form owns its key and needs no router at all, so the same
+     * module validates a routed request, a single-handler service, a CLI command or a browser event.
+     *
+     * @param event - The incoming event.
+     * @returns What was declared, or `undefined`.
+     */
+    declarationFor(event) {
+        // Duck-typed throughout: the kernel is agnostic, and an event without a router carries no route.
+        const route = event.getRoute?.();
+        const onRoute = route?.getOption?.('validation');
+        if (onRoute !== undefined) {
+            return onRoute;
+        }
+        const handler = route?.getOption?.('handler') ??
+            this.blueprint.get('stone.kernel.eventHandler', {});
+        return this.declaredOnHandler(handler);
+    }
+    /**
+     * What a handler declared with `@Validate`, if anything.
+     *
+     * @param handler - The handler about to run.
+     * @returns What the matching method declared, or `undefined`.
+     */
+    declaredOnHandler(handler) {
+        const module = handler?.module;
+        if (module === undefined || !hasMetadata(module, VALIDATE_KEY)) {
+            return undefined;
+        }
+        const declarations = getMetadata(module, VALIDATE_KEY, []);
+        const action = handler?.action;
+        // A single-handler module declares one; a controller declares one per method.
+        return (action === undefined
+            ? declarations[0]
+            : declarations.find((declaration) => declaration.action === action))?.validation;
+    }
+    /**
+     * Resolve a registered entry: a schema class goes through the container, so its constructor gets
+     * the services it asked for and `rules()` can use them, i18n included.
+     *
+     * @param entry - What the registry holds.
+     * @returns Something `rulesOf` can read.
+     */
+    resolve(entry) {
+        if (!isValidationSchemaClass(entry)) {
+            return entry;
+        }
+        return this.container?.resolve?.(entry, true) ?? new entry({});
+    }
+}
+/**
+ * Meta middleware for route-declared validation.
+ *
+ * Registered on `stone.router.middleware` by {@link validationBlueprint}, so it runs for every
+ * matched route and does nothing on the routes that declare no validation.
+ */
+const MetaValidateRouteMiddleware = {
+    module: ValidateRouteMiddleware,
+    isClass: true,
+    priority: 5
+};
+
+/**
+ * Build-phase middleware: collect every class registered with `@ValidationSchema` into the registry.
+ *
+ * The same scan the router does for its route definitions, applied to this module's own key. After
+ * it runs, `stone.validation.schemas` maps each alias to its class, so a route or a handler can name
+ * a schema instead of importing it, and `@stone-js/openapi` can walk the registry to publish request
+ * schemas without loading anything itself.
+ *
+ * @param context - The blueprint context.
+ * @param next - The next blueprint middleware.
+ * @returns The blueprint.
+ */
+async function ValidationSchemaMiddleware(context, next) {
+    const registered = context
+        .modules
+        .filter((module) => hasMetadata(module, VALIDATION_SCHEMA_KEY))
+        .reduce((registry, module) => {
+        const { alias } = getMetadata(module, VALIDATION_SCHEMA_KEY, {});
+        return { ...registry, [alias ?? module.name]: module };
+    }, {});
+    if (Object.keys(registered).length > 0) {
+        context.blueprint.set('stone.validation.schemas', {
+            ...context.blueprint.get('stone.validation.schemas', {}),
+            ...registered
+        });
+    }
+    return await next(context);
+}
+/**
+ * Meta blueprint middleware for schema discovery.
+ */
+const MetaValidationSchemaMiddleware = {
+    module: ValidationSchemaMiddleware,
+    priority: 5
+};
+
+/**
+ * Opt-in blueprint: import and register it to enable validation.
+ *
+ * It contributes the validation service provider and the route middleware that validates what a
+ * route declared under `validation`. Both `stone.providers` and `stone.router.middleware` are
+ * arrays, so this merges with the rest of the app rather than replacing anything.
+ *
+ * The route middleware is a no-op on routes that declare nothing, so enabling validation costs an
+ * application that does not use it one function call per request.
+ */
+const validationBlueprint = {
+    stone: {
+        validation: {},
+        blueprint: {
+            middleware: [
+                MetaValidationSchemaMiddleware
+            ]
+        },
+        providers: [
+            ValidationServiceProvider
+        ],
+        router: {
+            middleware: [
+                MetaValidateRouteMiddleware
+            ]
+        }
+    }
+};
+
+/**
+ * Class decorator: validate incoming data against the schemas you already write, declaratively.
+ *
+ * `@Validation()` registers the validation service provider, so `constructor ({ validator })` works
+ * anywhere and the `@Validate()` route decorators have something to resolve. There is no kernel
+ * middleware here: validation runs where it is asked for, not on every event.
+ *
+ * The declarative half of the pair; `validationBlueprint` handed to `defineStoneApp` is the imperative one.
+ *
+ * @param options - The validation configuration. Everything is optional.
+ * @returns A class decorator.
+ *
+ * @example
+ * ```typescript
+ * import { Validation } from '@stone-js/validation'
+ *
+ * @Validation({ abortEarly: false })
+ * @StoneApp({ name: 'my-app' })
+ * export class Application {}
+ * ```
+ */
+const Validation = (options = {}) => {
+    return classDecoratorLegacyWrapper((target, context) => {
+        // The blueprint is the single source of truth for what the module declares; the decorator only
+        // overrides what it can, its options bucket. Cloning is what lets it: two decorated applications
+        // get their own copy instead of sharing the exported constant.
+        const blueprint = cloneValue(validationBlueprint);
+        blueprint.stone.validation = { ...blueprint.stone.validation, ...options };
+        addBlueprint(target, context, blueprint);
+    });
+};
+
+/**
+ * Method decorator: declare what a handler accepts.
+ *
+ * ```ts
+ * @Validate(CreateUserSchema)                       // the body
+ * @Validate({ body: CreateUserSchema, query: Page }) // several sources
+ * @Validate('createUser')                            // a registered schema class
+ * ```
+ *
+ * This knows nothing about the router, and that is the point: the declaration is recorded on the
+ * handler itself, under this module's own key, so validation runs the same in a routed application,
+ * a single-handler service, a CLI command or the browser. When a router *is* in play you may instead
+ * put it on the route (`@Post('/users', { validation: … })`), which keeps the method uncluttered and
+ * puts everything a route does in one place; both forms end up in the same middleware.
+ *
+ * @param validation - What the handler accepts.
+ * @returns A method decorator.
+ */
+const Validate = (validation) => {
+    return methodDecoratorLegacyWrapper((_target, context) => {
+        addMetadata(context, VALIDATE_KEY, { action: context.name, validation });
+    });
+};
+
+/**
+ * Class decorator: register a schema class under a name.
+ *
+ * ```ts
+ * @ValidationSchema('createUser')
+ * export class CreateUserSchema implements IValidationSchema { rules () { … } }
+ * ```
+ *
+ * Routes and handlers then refer to it by name (`@Validate('createUser')`), so schemas live in their
+ * own files, organised however the application likes, and nothing has to be imported at the route.
+ * The class is resolved by the container, so its constructor receives services and `rules()` can use
+ * them.
+ *
+ * @param alias - The name the schema is registered under. Defaults to the class name, which the
+ * discovery middleware fills in, since it is the one holding the class.
+ * @returns A class decorator.
+ */
+const ValidationSchema = (alias) => {
+    return setClassMetadata(VALIDATION_SCHEMA_KEY, { alias });
+};
+
 /**
  * Builds a route middleware that validates the event's inputs before the handler runs.
  *
@@ -268,19 +734,4 @@ function validate(rules) {
     };
 }
 
-/**
- * Opt-in blueprint: import and register it to enable validation.
- *
- * It contributes the validation service provider. `stone.providers` is an array, so this merges
- * with the rest of the app rather than replacing anything.
- */
-const validationBlueprint = {
-    stone: {
-        validation: {},
-        providers: [
-            ValidationServiceProvider
-        ]
-    }
-};
-
-export { ValidationError, ValidationServiceProvider, Validator, fromStandard, fromZod, isNativeSchema, isStandardSchema, isZodLike, resolveSchema, validate, validateEvent, validationBlueprint };
+export { MetaValidateRouteMiddleware, MetaValidationSchemaMiddleware, VALIDATE_KEY, VALIDATION_SCHEMA_KEY, Validate, ValidateRouteMiddleware, Validation, ValidationError, ValidationSchema, ValidationSchemaMiddleware, ValidationServiceProvider, Validator, defineValidationSchema, fromStandard, fromZod, isNativeSchema, isSchemaLike, isStandardSchema, isValidationSchema, isValidationSchemaClass, isZodLike, metadataKeyFor, readSource, resolveSchema, rulesOf, toValidationRules, validate, validateEvent, validationBlueprint };

package/dist/middleware/BlueprintMiddleware.d.ts

@@ -0,0 +1,18 @@
+import { BlueprintContext, ClassType, IBlueprint, NextMiddleware, type MetaMiddleware } from '@stone-js/core';
+/**
+ * Build-phase middleware: collect every class registered with `@ValidationSchema` into the registry.
+ *
+ * The same scan the router does for its route definitions, applied to this module's own key. After
+ * it runs, `stone.validation.schemas` maps each alias to its class, so a route or a handler can name
+ * a schema instead of importing it, and `@stone-js/openapi` can walk the registry to publish request
+ * schemas without loading anything itself.
+ *
+ * @param context - The blueprint context.
+ * @param next - The next blueprint middleware.
+ * @returns The blueprint.
+ */
+export declare function ValidationSchemaMiddleware(context: BlueprintContext<IBlueprint, ClassType>, next: NextMiddleware<BlueprintContext<IBlueprint, ClassType>, IBlueprint>): Promise<IBlueprint>;
+/**
+ * Meta blueprint middleware for schema discovery.
+ */
+export declare const MetaValidationSchemaMiddleware: MetaMiddleware<any, any>;

package/dist/middleware/ValidateRouteMiddleware.d.ts

@@ -0,0 +1,101 @@
+import { RouteValidationInput } from '../sources.js';
+import { IBlueprint, IContainer, IncomingEvent, NextMiddleware, OutgoingResponse, type MetaMiddleware } from '@stone-js/core';
+/**
+ * What a route's `validation` option accepts: a schema, a map of schemas keyed by source, or the
+ * name of either registered under `stone.validation.schemas`.
+ */
+export type RouteValidation = RouteValidationInput | string;
+/**
+ * Route middleware: validates what a route declared, before its handler runs.
+ *
+ * A route says what it accepts, once, where the route is defined:
+ *
+ * ```ts
+ * @Post('/users', { validation: { body: CreateUserSchema } })
+ * ```
+ *
+ * A single schema means the body, which is what almost every route means; a map validates several
+ * sources at once (`{ body, query, params }`).
+ *
+ * This middleware reads that from the matched route and validates it. On success each **parsed**
+ * source is published in the event's metadata under a predictable name, so a handler reads
+ * `event.get<CreateUser>('validatedBody')` with no helper and no import. That matters more than it
+ * looks: a schema coerces and strips, and re-reading the raw value is how an application validates
+ * one thing and uses another. On failure it throws a `ValidationError` carrying every issue at once.
+ *
+ * The route stays the single description of itself, which is what lets `@stone-js/openapi` publish
+ * the request schema without being told a second time.
+ */
+export declare class ValidateRouteMiddleware {
+    private readonly blueprint;
+    private readonly container?;
+    private readonly validator;
+    /**
+     * @param dependencies - Auto-wired container services.
+     */
+    constructor({ blueprint, container }: {
+        blueprint: IBlueprint;
+        container?: IContainer;
+    });
+    /**
+     * Validate the matched route's declared input, then continue.
+     *
+     * @param event - The incoming event.
+     * @param next - The next middleware.
+     * @returns The response.
+     */
+    handle(event: IncomingEvent, next: NextMiddleware<IncomingEvent, OutgoingResponse>): Promise<OutgoingResponse>;
+    /**
+     * Validate every declared source, and return what to publish on the event.
+     *
+     * Every source is validated before anything is thrown, so a caller sees the full picture rather
+     * than one failure at a time.
+     *
+     * @param event - The incoming event.
+     * @param rules - The rules, keyed by source.
+     * @returns The parsed sources, keyed by their metadata name.
+     * @throws {ValidationError} When any source fails.
+     */
+    private validateSources;
+    /**
+     * The rules the matched route declared, with a registered name resolved to its rule set.
+     *
+     * @param event - The incoming event.
+     * @returns The rules, or `undefined` when the route declares none.
+     */
+    private rulesFor;
+    /**
+     * What the handler about to run declared, from either of the two places it may live.
+     *
+     * The route's own option comes first, because when a router is in play a route is the single
+     * description of itself and that is where a reader looks. Failing that, the handler's own
+     * `@Validate` metadata is read: that form owns its key and needs no router at all, so the same
+     * module validates a routed request, a single-handler service, a CLI command or a browser event.
+     *
+     * @param event - The incoming event.
+     * @returns What was declared, or `undefined`.
+     */
+    private declarationFor;
+    /**
+     * What a handler declared with `@Validate`, if anything.
+     *
+     * @param handler - The handler about to run.
+     * @returns What the matching method declared, or `undefined`.
+     */
+    private declaredOnHandler;
+    /**
+     * Resolve a registered entry: a schema class goes through the container, so its constructor gets
+     * the services it asked for and `rules()` can use them, i18n included.
+     *
+     * @param entry - What the registry holds.
+     * @returns Something `rulesOf` can read.
+     */
+    private resolve;
+}
+/**
+ * Meta middleware for route-declared validation.
+ *
+ * Registered on `stone.router.middleware` by {@link validationBlueprint}, so it runs for every
+ * matched route and does nothing on the routes that declare no validation.
+ */
+export declare const MetaValidateRouteMiddleware: MetaMiddleware<any, any>;

package/dist/middleware/validate.d.ts

@@ -1,4 +1,4 @@
-import { ValidationRules } from '../validateEvent';
+import { ValidationRules } from '../validateEvent.js';
 import { IncomingEvent, OutgoingResponse, FunctionalMiddleware } from '@stone-js/core';
 /**
  * Builds a route middleware that validates the event's inputs before the handler runs.

package/dist/options/ValidationBlueprint.d.ts

@@ -1,4 +1,4 @@
-import { ValidationOptions } from '../declarations';
+import { ValidationOptions } from '../declarations.js';
 import { AppConfig, StoneBlueprint } from '@stone-js/core';
 /**
  * Validation configuration bucket (`stone.validation`).
@@ -20,7 +20,11 @@ export interface ValidationBlueprint extends StoneBlueprint {
 /**
  * Opt-in blueprint: import and register it to enable validation.
  *
- * It contributes the validation service provider. `stone.providers` is an array, so this merges
- * with the rest of the app rather than replacing anything.
+ * It contributes the validation service provider and the route middleware that validates what a
+ * route declared under `validation`. Both `stone.providers` and `stone.router.middleware` are
+ * arrays, so this merges with the rest of the app rather than replacing anything.
+ *
+ * The route middleware is a no-op on routes that declare nothing, so enabling validation costs an
+ * application that does not use it one function call per request.
  */
 export declare const validationBlueprint: ValidationBlueprint;

package/dist/schema.d.ts

@@ -1,4 +1,4 @@
-import { SchemaInput, ValidationSchema } from './declarations';
+import { SchemaInput, ValidationSchema } from './declarations.js';
 /**
  * Normalises any supported schema input into a Stone.js {@link ValidationSchema}.
  *

package/dist/schemaClass.d.ts

@@ -0,0 +1,74 @@
+import { ValidationRules } from './validateEvent.js';
+import { RouteValidationInput } from './sources.js';
+/**
+ * The contract a schema class exposes.
+ *
+ * One method, `rules()`, returning what to validate per source. It is deliberately declarative:
+ * a contract that *describes* itself can be read by `@stone-js/openapi` to publish the request
+ * schema, which a method that merely validated could never be.
+ *
+ * The class is resolved by the container, so its constructor receives services and `rules()` can use
+ * them. That is what makes translated messages possible without a second method for them:
+ *
+ * ```ts
+ * @ValidationSchema('createUser')
+ * export class CreateUserSchema implements IValidationSchema {
+ *   private readonly i18n: II18n
+ *   constructor ({ i18n }: { i18n: II18n }) { this.i18n = i18n }
+ *
+ *   rules () {
+ *     return {
+ *       body: z.object({ email: z.string().email(this.i18n.t('validation.email')) })
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * The same class validates a form on the frontend, because nothing here knows about HTTP: resolve it
+ * from the container and call `rules()`, or hand it to the `Validator` directly. One schema, both
+ * sides, which is the whole reason the module is agnostic.
+ */
+export interface IValidationSchema {
+    /** What this schema validates, per source. A bare schema is read as the body. */
+    rules: () => RouteValidationInput;
+}
+/** A class that can be resolved into an {@link IValidationSchema}. */
+export type ValidationSchemaClass = new (...args: any[]) => IValidationSchema;
+/**
+ * Whether a value is a schema class rather than a schema or a rule map.
+ *
+ * @param value - The candidate.
+ * @returns Whether it must be resolved before use.
+ */
+export declare function isValidationSchemaClass(value: unknown): value is ValidationSchemaClass;
+/**
+ * Whether a value is an already-built schema instance.
+ *
+ * @param value - The candidate.
+ * @returns Whether it exposes `rules()`.
+ */
+export declare function isValidationSchema(value: unknown): value is IValidationSchema;
+/**
+ * The imperative counterpart of a schema class: a plain function returning the rules.
+ *
+ * It receives the same dependencies a class would get through its constructor, so it can reach the
+ * container's services too.
+ *
+ * @param rules - Returns what to validate, per source.
+ * @returns A schema instance.
+ *
+ * @example
+ * ```typescript
+ * export const createUserSchema = defineValidationSchema(({ i18n }) => ({
+ *   body: z.object({ email: z.string().email(i18n.t('validation.email')) })
+ * }))
+ * ```
+ */
+export declare function defineValidationSchema(rules: (dependencies: any) => RouteValidationInput): (dependencies: any) => IValidationSchema;
+/**
+ * Read the rules out of whatever a declaration resolved to.
+ *
+ * @param resolved - A schema instance, a schema, or a rule map.
+ * @returns The rules, keyed by source.
+ */
+export declare function rulesOf(resolved: IValidationSchema | RouteValidationInput): ValidationRules;

package/dist/sources.d.ts

@@ -0,0 +1,79 @@
+import { SchemaInput } from './declarations.js';
+import { ValidationRules } from './validateEvent.js';
+/**
+ * What a route may declare under `validation`.
+ *
+ * A single schema validates the **body**, which is what almost every route means:
+ *
+ * ```ts
+ * @Post('/users', { validation: CreateUserSchema })
+ * ```
+ *
+ * A map validates several sources at once, each under its own key:
+ *
+ * ```ts
+ * @Get('/users', { validation: { query: ListQuerySchema, params: IdSchema } })
+ * ```
+ */
+export type RouteValidationInput = SchemaInput | ValidationRules;
+/** The source a rule reads from, when it is one of the ones an event exposes wholesale. */
+export type ValidationSource = 'body' | 'query' | 'params';
+/**
+ * A duck-typed event: the kernel is agnostic, so this reads whatever the context happens to expose
+ * and never imports an HTTP type.
+ */
+interface SourceEvent {
+    body?: unknown;
+    params?: unknown;
+    query?: unknown;
+    getBody?: <T>() => T | undefined;
+    get: <T>(key: string) => T | undefined;
+}
+/**
+ * Whether a value is a schema rather than a map of schemas.
+ *
+ * A schema is recognised by what it can do, not by what it is: every engine Stone.js accepts exposes
+ * one of `validate`, `~standard`, `parse` or `safeParse`. Anything else is treated as a map of
+ * sources, which is why `{ body: X }` and `X` can share one option without ambiguity.
+ *
+ * @param value - The declared value.
+ * @returns Whether it is a single schema.
+ */
+export declare function isSchemaLike(value: unknown): value is SchemaInput;
+/**
+ * Normalise what a route declared into rules keyed by source.
+ *
+ * A bare schema becomes `{ body: schema }`, because a route that names one schema means its payload.
+ *
+ * @param declared - What the route declared.
+ * @returns The rules, keyed by source.
+ */
+export declare function toValidationRules(declared: RouteValidationInput): ValidationRules;
+/**
+ * Read a whole source off an event.
+ *
+ * `body`, `query` and `params` are read as wholes, because a schema validates the payload, not one
+ * field of it. `event.get('body')` would look for a field *named* body inside the body, which is a
+ * different question. Any other key falls back to `event.get`, so a context that exposes something
+ * else (a CLI argument set, a message attribute) validates just as well.
+ *
+ * `query` is normalised from `URLSearchParams` to a plain object, since that is what a schema can
+ * parse.
+ *
+ * @param event - The incoming event.
+ * @param source - The source name.
+ * @returns The value to validate.
+ */
+export declare function readSource(event: SourceEvent, source: string): unknown;
+/**
+ * The metadata key a validated source is published under.
+ *
+ * `body` becomes `validatedBody`, `query` becomes `validatedQuery`. The name is predictable on
+ * purpose: a handler reads `event.get<CreateUser>('validatedBody')` and needs no helper, no import
+ * and nothing to remember beyond the source it declared.
+ *
+ * @param source - The source name.
+ * @returns The metadata key.
+ */
+export declare function metadataKeyFor(source: string): string;
+export {};

package/dist/validateEvent.d.ts

@@ -1,4 +1,4 @@
-import { IValidator, SchemaInput } from './declarations';
+import { IValidator, SchemaInput } from './declarations.js';
 /**
  * A map of event keys to the schema that validates each one.
  *
@@ -22,9 +22,15 @@ export interface ReadableEvent {
  * Platform-agnostic: the event only needs a `get(key)` method, so it works for HTTP, CLI, browser
  * or any other context.
  *
+ * Returns the **parsed** values, keyed as the rules were. A schema does not only accept or reject,
+ * it coerces and strips: `z.coerce.number()` turns `"42"` into `42`, and a strict object drops the
+ * keys you did not declare. Throwing the parsed value away and reading the raw input again is how
+ * an application ends up validating one value and using another.
+ *
  * @param event - The incoming event (anything with `get`).
  * @param rules - The validation rules.
  * @param validator - The validator to use (defaults to a fresh stateless one).
+ * @returns The parsed value for each rule.
  * @throws {ValidationError} When any input fails validation.
  */
-export declare function validateEvent(event: ReadableEvent, rules: ValidationRules, validator?: IValidator): void;
+export declare function validateEvent(event: ReadableEvent, rules: ValidationRules, validator?: IValidator): Record<string, unknown>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stone-js/validation",
-  "version": "0.8.7",
+  "version": "0.8.9",
   "description": "Framework-agnostic input validation for Stone.js. Define a schema once (Zod, Valibot, ArkType — anything Standard Schema) and validate it identically on the backend and the frontend.",
   "author": "Mr. Stone <evensstone@gmail.com>",
   "license": "MIT",
@@ -40,7 +40,7 @@
     "node": ">=18.17.0"
   },
   "peerDependencies": {
-    "@stone-js/core": "0.8.7"
+    "@stone-js/core": "0.8.9"
   },
   "devDependencies": {
     "@commitlint/cli": "^19.8.1",
@@ -62,7 +62,7 @@
     "typescript": "^5.6.3",
     "vitest": "^3.2.4",
     "zod": "^3.24.1",
-    "@stone-js/core": "0.8.7"
+    "@stone-js/core": "0.8.9"
   },
   "ts-standard": {
     "globals": [
@@ -74,6 +74,9 @@
       "beforeEach"
     ]
   },
+  "dependencies": {
+    "@stone-js/config": "0.8.9"
+  },
   "scripts": {
     "lint": "ts-standard src",
     "lint:fix": "ts-standard --fix src tests",