Packages

@xtaskjs/validation

Schema-first request validation for controllers using Zod or Valibot adapters.

npm install @xtaskjs/validation reflect-metadata zod Package path: packages/validation

Overview

What this package owns in the runtime

Validation integrates schema-based request validation into the xtaskjs HTTP pipeline. It offers parameter decorators and route-level schema decorators, returns structured validation issues, and plugs into DI for adapter and error customization.

What it provides

ValidatedBody(), ValidatedQuery(), and ValidatedParam() bind and validate request values directly from handlers.
SchemaDto() attaches schema metadata to class DTOs used with Body(), Query(), and Param().
UseBodySchema(), UseQuerySchema(), and UseParamSchema() enable controller- or method-level schema declarations.
configureValidation() allows custom default adapters and error payload shaping.

How it fits

When installed, @xtaskjs/core can use this package as the default global HTTP validation layer.
Works beside @xtaskjs/common decorator pipelines and complements class-validator/class-transformer DTO flows.
Useful for apps moving to schema-first validation while keeping xtaskjs DI and controller patterns.

Usage Chart

How strongly this package shapes the runtime

Bootstrap

4/5

Dependency Injection

4/5

HTTP Delivery

5/5

Validation

5/5

Integrations

4/5

Package Flow

How this package moves through xtaskjs runtime phases

Before startup

Select the schema adapter and register optional validation configuration for error mapping and adapter behavior.

During CreateApplication()

Validation services and decorators integrate with route execution so request payloads are validated before controller handlers run.

During app.close()

No long-lived external resources are held; validation state is released alongside the application container.

API Surface

Representative exports from the upstream package

Usage

Typical adoption flow

1. Start with parameter decorators

Use ValidatedBody, ValidatedQuery, and ValidatedParam for schema-first validation where request arguments enter handlers.

2. Reuse schemas at route level

Apply UseBodySchema or SchemaDto to avoid duplicating validation contracts across controllers and DTOs.

3. Customize adapter and errors

Use configureValidation() to switch default adapter or shape consistent error payloads for clients and logs.

Example

Reference snippet

Schema-validated request body

import "reflect-metadata";
import { Controller, Post } from "@xtaskjs/common";
import { ValidatedBody } from "@xtaskjs/validation";
import { z } from "zod";

const createUserSchema = z.object({
  email: z.string().email(),
  age: z.coerce.number().int().min(18),
});

@Controller("/users")
export class UsersController {
  @Post("/")
  create(
    @ValidatedBody(createUserSchema)
    body: z.infer<typeof createUserSchema>
  ) {
    return body;
  }
}

Samples

Official samples to inspect next

Reference samples: Package README and package tests currently provide the primary reference.