adorn-api 1.1.13 → 1.1.14

package/README.md

@@ -1,23 +1,24 @@
 # Adorn API
 
-A modern, decorator-first web framework built on Express with built-in OpenAPI 3.1 schema generation, designed for rapid API development with excellent Type safety and developer experience.
+Decorator-first API framework for TypeScript with Express, Fastify, native Node HTTP, OpenAPI 3.1 generation, request validation, Bearer auth, file uploads, streaming, and optional Metal ORM helpers.
+
+Adorn is designed for APIs where the route contract should live beside the handler: controllers, DTOs, schemas, validation, serialization, and OpenAPI are all derived from the same decorators.
 
 ## Features
 
-- ✨ **Decorator-First API Definition**: Define controllers and DTOs with intuitive decorators
-- 📚 **Automatic OpenAPI 3.1 Generation**: API documentation is generated from your code
-- 🔌 **Express Integration**: Built on top of Express for familiarity and extensibility
-- 🎯 **Type-Safe Data Transfer Objects**: Define schemas with TypeScript for compile-time checks
-- 🔄 **DTO Composition**: Reuse and compose DTOs with PickDto, OmitDto, PartialDto, and MergeDto
-- 📦 **Metal ORM Integration**: First-class support for Metal ORM with auto-generated CRUD DTOs, transformer-aware schema generation, and tree DTOs for nested set (MPTT) models
-- 🚀 **Streaming Support**: Server-Sent Events (SSE) and streaming responses
-- 🔧 **Raw Responses**: Return binary data, files, and non-JSON content with the `@Raw` decorator
-- 📝 **Request Validation**: Automatic validation of request bodies, params, query, and headers
-- 🔧 **Transformers**: Custom field transformations with @Transform decorator and built-in transform functions
--  **Error Handling**: Structured error responses with error DTO support
-- 💾 **File Uploads**: Easy handling of file uploads with multipart form data
-- 🌐 **CORS Support**: Built-in CORS configuration
-- 🏗️ **Lifecycle Hooks**: Application bootstrap and shutdown lifecycle events
+- Controller and route decorators: `@Controller`, `@Get`, `@Post`, `@Put`, `@Patch`, `@Delete`
+- DTO decorators: `@Dto`, `@Field`, `@PickDto`, `@OmitDto`, `@PartialDto`, `@MergeDto`
+- Schema builder: `t.string`, `t.uuid`, `t.integer`, `t.object`, `t.array`, `t.file`, and more
+- OpenAPI 3.1 JSON and Swagger UI
+- Express, Fastify, and native Node HTTP adapters
+- Built-in Bearer token auth for `@Auth`, `@Roles`, `@AllRoles`, and `@Public`
+- Runtime validation for body, query, params, and headers
+- Input coercion for params/query/body
+- Multipart file uploads
+- Raw responses, SSE, and streaming responses
+- Response serialization with `@Expose`, `@Exclude`, and `@Transform`
+- Health checks, request logging, and lifecycle hooks
+- Metal ORM DTO, CRUD, pagination, filtering, sorting, and tree helpers
 
 ## Installation
 
@@ -25,17 +26,31 @@ A modern, decorator-first web framework built on Express with built-in OpenAPI 3
 npm install adorn-api
 ```
 
-Note: Adorn uses Stage 3 decorator metadata (`Symbol.metadata`). If the runtime does not provide it, Adorn polyfills `Symbol.metadata` on import to keep decorator metadata consistent.
+Adorn uses Stage 3 decorators and `Symbol.metadata`. The package polyfills `Symbol.metadata` on import when the runtime does not provide it.
+
+Recommended TypeScript settings:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "moduleResolution": "Node",
+    "experimentalDecorators": false,
+    "emitDecoratorMetadata": false,
+    "useDefineForClassFields": true,
+    "strict": true
+  }
+}
+```
 
 ## Quick Start
 
-### 1. Define DTOs
+### DTOs
 
 ```typescript
-// user.dtos.ts
 import { Dto, Field, OmitDto, PickDto, t } from "adorn-api";
 
-@Dto({ description: "User record returned by the API." })
+@Dto({ description: "User returned by the API." })
 export class UserDto {
   @Field(t.uuid({ description: "User identifier." }))
   id!: string;
@@ -47,17 +62,20 @@ export class UserDto {
   nickname?: string;
 }
 
+export interface CreateUserDto extends Omit<UserDto, "id"> {}
+
 @OmitDto(UserDto, ["id"])
 export class CreateUserDto {}
 
+export interface UserParamsDto extends Pick<UserDto, "id"> {}
+
 @PickDto(UserDto, ["id"])
 export class UserParamsDto {}
 ```
 
-### 2. Create a Controller
+### Controller
 
 ```typescript
-// user.controller.ts
 import {
   Body,
   Controller,
@@ -95,1169 +113,834 @@ export class UserController {
 }
 ```
 
-### 3. Bootstrap the Application
+### App
 
 ```typescript
-// app.ts
 import { createExpressApp } from "adorn-api";
 import { UserController } from "./user.controller";
 
-export async function createApp() {
-  return createExpressApp({
+async function start() {
+  const app = await createExpressApp({
     controllers: [UserController],
     openApi: {
       info: {
-        title: "Adorn API",
+        title: "Users API",
         version: "1.0.0"
       },
       docs: true
     }
   });
-}
-
-// index.ts
-import { createApp } from "./app";
 
-async function start() {
-  const app = await createApp();
-  const PORT = 3000;
-  
-  app.listen(PORT, () => {
-    console.log(`Server running at http://localhost:${PORT}`);
-    console.log(`OpenAPI documentation: http://localhost:${PORT}/openapi.json`);
+  app.listen(3000, () => {
+    console.log("API: http://localhost:3000");
+    console.log("Docs: http://localhost:3000/docs");
+    console.log("OpenAPI: http://localhost:3000/openapi.json");
   });
 }
 
-start().catch(error => {
-  console.error("Failed to start server:", error);
+start().catch((error) => {
+  console.error(error);
   process.exit(1);
 });
 ```
 
-## Core Concepts
-
-### Controllers
-
-Controllers are classes decorated with `@Controller()` that group related API endpoints. Each controller has a base path and contains route handlers.
+Run the bundled basic example:
 
-```typescript
-@Controller("/api/v1/users")
-export class UserController {
-  // Routes go here
-}
+```bash
+npm run example -- basic
 ```
 
-### Routes
+## Adapters
 
-Routes are methods decorated with HTTP verb decorators like `@Get()`, `@Post()`, `@Put()`, `@Patch()`, or `@Delete()`.
+### Express
 
 ```typescript
-@Get("/:id")
-@Params(UserParamsDto)
-@Returns(UserDto)
-async getOne(ctx: RequestContext) {
-  // Route handler logic
-}
-```
+import { createExpressApp } from "adorn-api";
 
-### DTOs (Data Transfer Objects)
+const app = await createExpressApp({
+  controllers: [UserController],
+  cors: {
+    origin: "https://app.example.com",
+    credentials: true
+  },
+  jsonBody: true,
+  jsonLimit: "1mb",
+  inputCoercion: "safe",
+  validation: { enabled: true, mode: "strict" },
+  multipart: {
+    storage: "memory",
+    maxFileSize: 10 * 1024 * 1024,
+    maxFiles: 10
+  },
+  openApi: {
+    info: { title: "API", version: "1.0.0" },
+    path: "/openapi.json",
+    docs: { path: "/docs" }
+  }
+});
+```
 
-DTOs define the shape of data sent to and from your API. They provide validation, documentation, and type safety.
+### Fastify
 
 ```typescript
-@Dto({ description: "User data" })
-export class UserDto {
-  @Field(t.uuid({ description: "Unique identifier" }))
-  id!: string;
+import { createFastifyApp } from "adorn-api";
 
-  @Field(t.string({ minLength: 2, maxLength: 100 }))
-  name!: string;
-}
+const app = await createFastifyApp({
+  controllers: [UserController],
+  bodyLimit: 1_048_576,
+  cors: true,
+  inputCoercion: "safe",
+  multipart: true,
+  openApi: {
+    info: { title: "API", version: "1.0.0" },
+    docs: true
+  }
+});
+
+await app.listen({ port: 3000 });
 ```
 
-### Stage 3 Decorator Metadata
+### Native Node HTTP
 
-Adorn relies on Stage 3 decorator metadata (`Symbol.metadata`) to connect information across decorators (DTO fields, routes, params, etc.). If the runtime does not provide it, Adorn polyfills `Symbol.metadata` on import so decorators share a consistent metadata object.
+```typescript
+import { createNativeApp } from "adorn-api";
 
-### Request Context
+const app = await createNativeApp({
+  controllers: [UserController],
+  bodyLimit: 1_048_576,
+  openApi: {
+    info: { title: "API", version: "1.0.0" },
+    docs: true
+  }
+});
 
-Each route handler receives a `RequestContext` object that provides access to:
-- `ctx.body` - The request body (validated and typed)
-- `ctx.params` - Route parameters
-- `ctx.query` - Query parameters
-- `ctx.headers` - Request headers
-- `ctx.req` - The raw Express request
-- `ctx.res` - The raw Express response
-- `ctx.sse` - SSE emitter (for SSE routes)
-- `ctx.stream` - Streaming writer (for streaming routes)
+app.listen(3000, () => {
+  console.log("Native API running on http://localhost:3000");
+});
+```
 
-## Advanced Features
+## Request Context
 
-### Server-Sent Events (SSE)
+Every handler receives a `RequestContext`:
 
 ```typescript
-import { Controller, Get, Sse } from "adorn-api";
-
-@Controller("/events")
-class EventsController {
-  @Get("/")
-  @Sse({ description: "Real-time events stream" })
-  async streamEvents(ctx: any) {
-    const emitter = ctx.sse;
-    
-    let count = 0;
-    const interval = setInterval(() => {
-      count++;
-      emitter.emit("message", {
-        id: count,
-        timestamp: new Date().toISOString(),
-        message: `Event ${count}`
-      });
-
-      if (count >= 5) {
-        clearInterval(interval);
-        emitter.close();
-      }
-    }, 1000);
-
-    ctx.req.on("close", () => {
-      clearInterval(interval);
-      emitter.close();
-    });
-  }
+interface RequestContext<TBody, TQuery, TParams, THeaders, TFiles> {
+  req: any;
+  res: any;
+  body: TBody;
+  query: TQuery;
+  params: TParams;
+  headers: THeaders;
+  files: TFiles;
+  sse?: SseEmitterInterface;
+  stream?: StreamWriterInterface;
 }
 ```
 
-### Streaming Responses
+Use adapter-specific aliases when useful:
 
 ```typescript
-import { Controller, Get, Streaming } from "adorn-api";
+import type {
+  ExpressRequestContext,
+  FastifyRequestContext,
+  NativeRequestContext
+} from "adorn-api";
+```
 
-@Controller("/streaming")
-class StreamingController {
-  @Get("/")
-  @Streaming({ contentType: "text/plain" })
-  async streamText(ctx: any) {
-    const writer = ctx.stream;
-    const data = ["First line", "Second line", "Third line"];
-    
-    for (let i = 0; i < data.length; i++) {
-      writer.writeLine(data[i]);
-      await new Promise(resolve => setTimeout(resolve, 500));
-    }
-    
-    writer.close();
+## Controllers and Decorators
+
+### Route Definition
+
+```typescript
+@Controller({ path: "/tasks", tags: ["Tasks"] })
+class TaskController {
+  @Get("/:id")
+  @Doc({ summary: "Get a task" })
+  @Params(t.object({ id: t.uuid() }))
+  @Query(t.object({ includeHistory: t.optional(t.boolean()) }))
+  @Headers(t.object({ "x-request-id": t.optional(t.string()) }))
+  @Returns(TaskDto)
+  async getTask(ctx: RequestContext) {
+    return findTask(ctx.params.id);
   }
 }
 ```
 
-### Raw Responses
+Available route decorators:
 
-Use the `@Raw()` decorator to return binary data (files, images, PDFs, etc.) without JSON serialization. The response body is sent with `res.send()` instead of `res.json()`.
+- HTTP methods: `@Get`, `@Post`, `@Put`, `@Patch`, `@Delete`
+- Inputs: `@Body`, `@Query`, `@Params`, `@Headers`
+- Outputs: `@Returns`, `@ReturnsError`, `@Errors`
+- Docs: `@Doc`, controller `tags`
+- Auth: `@Auth`, `@Roles`, `@AllRoles`, `@Public`
+- Files and streams: `@UploadedFile`, `@UploadedFiles`, `@Raw`, `@Sse`, `@Streaming`
 
-```typescript
-import { Controller, Get, Raw, Params, ok, type RequestContext } from "adorn-api";
-import fs from "fs/promises";
+### HTTP Responses
 
-@Controller("/files")
-class FileController {
-  @Get("/report.pdf")
-  @Raw({ contentType: "application/pdf", description: "Download PDF report" })
-  async downloadPdf(ctx: RequestContext) {
-    const buffer = await fs.readFile("report.pdf");
-    return ok(buffer);
-  }
+Return a plain value for the default status, or return `HttpResponse` helpers when status/headers matter:
 
-  @Get("/avatar/:id")
-  @Raw({ contentType: "image/png" })
-  async getAvatar(ctx: RequestContext) {
-    const image = await fs.readFile(`avatars/${ctx.params.id}.png`);
-    return image;
-  }
+```typescript
+import { created, noContent, ok, redirect } from "adorn-api";
+
+@Post("/")
+@Returns({ status: 201, schema: TaskDto })
+async create(ctx: RequestContext<CreateTaskDto>) {
+  return created(await createTask(ctx.body));
 }
-```
 
-You can also set custom headers (e.g. `Content-Disposition`) via `HttpResponse`:
+@Delete("/:id")
+@Returns({ status: 204 })
+async remove() {
+  return noContent();
+}
 
-```typescript
-import { HttpResponse } from "adorn-api";
-
-@Get("/download/:filename")
-@Raw({ contentType: "application/octet-stream" })
-async download(ctx: RequestContext) {
-  const buffer = await fs.readFile(`uploads/${ctx.params.filename}`);
-  return new HttpResponse(200, buffer, {
-    "Content-Disposition": `attachment; filename="${ctx.params.filename}"`
-  });
+@Get("/legacy")
+async legacy() {
+  return redirect("/tasks", 301);
 }
 ```
 
-### File Uploads
+Throw structured HTTP errors:
 
 ```typescript
-import { Controller, Post, UploadedFile, Returns, t } from "adorn-api";
+import { badRequest, forbidden, notFound, unauthorized } from "adorn-api";
 
-@Controller("/uploads")
-class UploadController {
-  @Post("/")
-  @UploadedFile("file", t.file({ accept: ["image/*"], maxSize: 5 * 1024 * 1024 }))
-  @Returns({ status: 200, schema: t.string() })
-  async uploadFile(ctx: any) {
-    const file = ctx.files?.file[0];
-    return `File uploaded: ${file.originalname}`;
-  }
+if (!task) {
+  notFound("Task not found");
 }
 ```
 
-## Metal ORM Integration
+Available helpers: `badRequest`, `unauthorized`, `forbidden`, `notFound`, `conflict`, `unprocessableEntity`, `tooManyRequests`, `serviceUnavailable`, and `internalServerError`.
 
-Adorn API has first-class support for Metal ORM, providing automatic CRUD DTO generation.
-Transformer decorators such as `@Email`, `@Length`, `@Pattern`, and `@Alphanumeric` are reflected in the generated DTO schemas (validation + OpenAPI).
+## Schemas and DTOs
 
-### 1. Define Entities
+### Schema Builder
+
+The `t` builder creates runtime validation and OpenAPI schemas:
 
 ```typescript
-// user.entity.ts
-import { Entity, PrimaryKey, Property } from "metal-orm";
+const TaskSchema = t.object({
+  id: t.uuid(),
+  title: t.string({ minLength: 1, maxLength: 120 }),
+  status: t.enum(["todo", "doing", "done"]),
+  priority: t.integer({ minimum: 1, maximum: 5 }),
+  tags: t.array(t.string(), { uniqueItems: true }),
+  metadata: t.record(t.any()),
+  dueAt: t.nullable(t.dateTime()),
+  attachment: t.optional(t.file({ accept: ["application/pdf"] }))
+});
+```
+
+Available schema helpers:
 
-@Entity("users")
-export class User {
-  @PrimaryKey()
-  id!: number;
+- Primitives: `t.string`, `t.number`, `t.integer`, `t.boolean`
+- Formats: `t.uuid`, `t.dateTime`, `t.bytes`
+- Containers: `t.object`, `t.array`, `t.record`
+- Composition: `t.enum`, `t.literal`, `t.union`, `t.ref`
+- Utility: `t.any`, `t.null`, `t.file`, `t.optional`, `t.nullable`
 
-  @Property()
+Common options include `description`, `title`, `default`, `examples`, `deprecated`, `readOnly`, `writeOnly`, `optional`, and `nullable`.
+
+### DTO Composition
+
+```typescript
+@Dto()
+class UserDto {
+  @Field(t.uuid())
+  id!: string;
+
+  @Field(t.string())
   name!: string;
 
-  @Property({ nullable: true })
-  nickname?: string;
+  @Field(t.string())
+  passwordHash!: string;
 }
-```
 
-### 2. Generate CRUD DTOs
+@PickDto(UserDto, ["id", "name"])
+class PublicUserDto {}
 
-```typescript
-// user.dtos.ts
-import { createMetalCrudDtoClasses, t } from "adorn-api";
-import { User } from "./user.entity";
+@OmitDto(UserDto, ["id", "passwordHash"])
+class CreateUserDto {}
 
-export const {
-  response: UserDto,
-  create: CreateUserDto,
-  replace: ReplaceUserDto,
-  update: UpdateUserDto,
-  params: UserParamsDto,
-  queryDto: UserQueryDto,
-  optionsQueryDto: UserOptionsQueryDto,
-  pagedResponseDto: UserPagedResponseDto,
-  optionDto: UserOptionDto,
-  optionsDto: UserOptionsDto,
-  errors: UserErrors,
-  filterMappings: USER_FILTER_MAPPINGS,
-  sortableColumns: USER_SORTABLE_COLUMNS,
-  listConfig: USER_LIST_CONFIG
-} = createMetalCrudDtoClasses(User, {
-  mutationExclude: ["id", "createdAt"],
-  query: {
-    filters: {
-      nameContains: {
-        schema: t.string({ minLength: 1 }),
-        field: "name",
-        operator: "contains"
-      },
-      emailContains: {
-        schema: t.string({ minLength: 1 }),
-        field: "email",
-        operator: "contains"
-      }
-    },
-    sortableColumns: {
-      id: "id",
-      name: "name",
-      createdAt: "createdAt"
-    },
-    options: {
-      labelField: "name"
-    }
-  },
-  errors: true
-});
+@PartialDto(CreateUserDto)
+class UpdateUserDto {}
+
+@MergeDto([PublicUserDto, ProfileDto])
+class UserProfileDto {}
 ```
 
-### 3. Create a CRUD Controller
+Composition decorators can override schema, optionality, descriptions, name, and `additionalProperties`.
+
+## Authentication
+
+Decorate controllers or routes with `@Auth`. `@Roles` and `@AllRoles` imply authentication. `@Public` overrides controller-level auth for one route.
 
 ```typescript
-// user.controller.ts
 import {
+  Auth,
   Controller,
   Get,
-  Post,
-  Put,
-  Patch,
-  Delete,
-  Params,
-  Body,
-  Query,
-  Returns,
-  runPagedList,
-  t,
+  Public,
+  Roles,
+  createExpressApp,
+  getUser,
+  type AuthUser,
   type RequestContext
 } from "adorn-api";
-import { createSession } from "./db";
-import { User } from "./user.entity";
-import {
-  UserDto,
-  CreateUserDto,
-  ReplaceUserDto,
-  UpdateUserDto,
-  UserParamsDto,
-  UserQueryDto,
-  UserOptionsQueryDto,
-  UserPagedResponseDto,
-  UserOptionsDto,
-  UserErrors,
-  USER_FILTER_MAPPINGS,
-  USER_SORTABLE_COLUMNS
-} from "./user.dtos";
 
-@Controller("/users")
-export class UserController {
-  @Get("/")
-  @Query(UserQueryDto)
-  @Returns(UserPagedResponseDto)
-  async list(ctx: RequestContext<unknown, UserQueryDto>) {
-    const session = createSession();
+@Auth()
+@Controller("/account")
+class AccountController {
+  @Get("/health")
+  @Public()
+  health() {
+    return { ok: true };
+  }
 
-    try {
-      return await runPagedList({
-        query: (ctx.query ?? {}) as Record<string, unknown>,
-        target: User,
-        qb: () => User.select(),
-        session,
-        filterMappings: USER_FILTER_MAPPINGS,
-        sortableColumns: USER_SORTABLE_COLUMNS,
-        defaultSortBy: "id"
-      });
-    } finally {
-      await session.dispose();
-    }
+  @Get("/me")
+  me(ctx: RequestContext) {
+    return getUser<AuthUser>(ctx.req);
   }
 
-  @Get("/options")
-  @Query(UserOptionsQueryDto)
-  @Returns(UserOptionsDto)
-  async options(ctx: RequestContext<unknown, UserOptionsQueryDto>) {
-    const query = (ctx.query ?? {}) as Record<string, unknown>;
-    const { page, pageSize } = parsePagination(query);
-    const filters = parseFilter(query, USER_FILTER_MAPPINGS);
-    // run your options query using the same mappings + generated DTOs
-    return {
-      items: [],
-      totalItems: 0,
-      page,
-      pageSize,
-      totalPages: 1,
-      hasNextPage: false,
-      hasPrevPage: false
-    };
+  @Get("/admin")
+  @Roles("admin")
+  adminOnly() {
+    return { ok: true };
   }
+}
 
-  @Get("/:id")
-  @Params({ id: t.integer() })
-  @Returns(UserDto)
-  @UserErrors
-  async getOne(ctx: RequestContext<unknown, undefined, { id: string }>) {
-    const session = createSession();
-    
-    try {
-      const user = await session.find(User, parseInt(ctx.params.id));
-      return user;
-    } finally {
-      await session.dispose();
+const app = await createExpressApp({
+  controllers: [AccountController],
+  bearerAuth: {
+    async verifyToken(token, req) {
+      if (token === "admin-token") {
+        return { id: "admin-1", roles: ["admin"] };
+      }
+      if (token === "user-token") {
+        return { id: "user-1", roles: ["user"] };
+      }
+      return null;
     }
   }
-
-  // Other CRUD operations...
-}
+});
 ```
 
-### Migration Guide (Breaking)
+Bearer auth reads only:
 
-### CRUD Controller Factory (`createCrudController`)
+```text
+Authorization: Bearer <token>
+```
 
-When your controller only wires DTOs + service calls, you can generate the full CRUD controller and remove decorator boilerplate.
+`verifyToken` is intentionally application-owned. Use it to verify JWTs, opaque tokens, API keys, or session tokens. Returning `null` means the request is unauthenticated.
 
-```typescript
-// user.controller.ts
-import { createCrudController } from "adorn-api";
-import { userCrudDtos } from "./user.dtos";
-import { UserCrudService } from "./user.service";
+Protected routes are emitted in OpenAPI with:
 
-export const UserController = createCrudController({
-  path: "/users",
-  service: UserCrudService, // class or instance
-  dtos: userCrudDtos,       // result of createMetalCrudDtoClasses(...)
-  entityName: "User",       // used by parseIdOrThrow messages
-  withOptionsRoute: true,
-  withReplace: true,
-  withPatch: true,
-  withDelete: true
-});
+```json
+{
+  "components": {
+    "securitySchemes": {
+      "bearerAuth": {
+        "type": "http",
+        "scheme": "bearer"
+      }
+    }
+  }
+}
 ```
 
-Generated routes:
-- `GET /`
-- `GET /options` (optional)
-- `GET /:id`
-- `POST /`
-- `PUT /:id` (optional)
-- `PATCH /:id` (optional)
-- `DELETE /:id` (optional)
+CORS is not enabled automatically. Server-to-server clients do not need CORS. Browser clients still need explicit `cors` configuration.
 
-The factory applies the correct `@Query/@Body/@Params/@Returns` schemas and also propagates `dtos.errors` to all `/:id` routes.
+Try the Swagger auth example:
 
-Before (manual, repeated decorators/status/schema wiring):
+```bash
+npm run example -- bearer-auth-swagger
+```
 
-```typescript
-@Controller("/users")
-class UserController {
-  @Get("/")
-  @Query(UserQueryDto)
-  @Returns(UserPagedResponseDto)
-  async list(ctx: RequestContext<unknown, UserQueryDto>) { ... }
+Then open `http://localhost:3001/docs` and use `user-token` or `admin-token` in Swagger Authorize.
 
-  @Get("/:id")
-  @Params(UserParamsDto)
-  @Returns(UserDto)
-  @UserErrors
-  async getById(ctx: RequestContext<unknown, undefined, UserParamsDto>) { ... }
+## OpenAPI and Swagger UI
 
-  @Post("/")
-  @Body(CreateUserDto)
-  @Returns({ status: 201, schema: UserDto })
-  async create(ctx: RequestContext<CreateUserDto>) { ... }
+Adapters can serve OpenAPI JSON and Swagger UI:
 
-  // put/patch/delete/options...
-}
+```typescript
+await createExpressApp({
+  controllers: [UserController],
+  openApi: {
+    info: {
+      title: "Users API",
+      version: "1.0.0",
+      description: "Public API contract"
+    },
+    servers: [{ url: "https://api.example.com", description: "Production" }],
+    path: "/openapi.json",
+    prettyPrint: true,
+    docs: {
+      path: "/docs",
+      title: "Users API Docs"
+    }
+  }
+});
 ```
 
-After (factory + service):
+You can also build the document without starting an HTTP server:
 
 ```typescript
-export const UserController = createCrudController({
-  path: "/users",
-  service: new UserCrudService(),
-  dtos: userCrudDtos,
-  entityName: "User"
+import { buildOpenApi } from "adorn-api";
+
+const document = buildOpenApi({
+  info: { title: "Users API", version: "1.0.0" },
+  controllers: [UserController]
 });
 ```
 
-When to use factory vs manual controller:
-- Use `createCrudController` when routes follow standard CRUD and behavior lives in a service.
-- Use a manual controller when route contracts diverge (custom status/body shape, non-standard params, upload/stream/raw endpoints, or route-level auth/doc decorators not shared by all CRUD routes).
-- For extra endpoints, keep the generated CRUD controller and add a second manual controller for custom routes on the same base path.
+OpenAPI generation includes:
 
-Before (duplicated config):
+- DTO schemas under `components.schemas`
+- query, path, header, body, multipart, and response schemas
+- route summaries/descriptions/tags from `@Doc`
+- Bearer security schemes for protected routes
+- raw, SSE, and streaming content types
+
+## Validation and Coercion
+
+Validation runs for `@Body`, `@Query`, `@Params`, and `@Headers` unless disabled:
 
 ```typescript
-const UserQueryDto = createPagedFilterQueryDtoClass({
-  filters: {
-    nameContains: { schema: t.string(), operator: "contains" }
-  }
+await createExpressApp({
+  controllers: [UserController],
+  validation: { enabled: true, mode: "strict" },
+  inputCoercion: "safe"
 });
-
-const USER_FILTER_MAPPINGS = {
-  nameContains: { field: "name", operator: "contains" as const }
-};
 ```
 
-After (single source of truth):
+Invalid input returns a structured 400 response with field-level errors.
+
+Manual validation is also available:
 
 ```typescript
-const {
-  queryDto: UserQueryDto,
-  filterMappings: USER_FILTER_MAPPINGS
-} = createMetalCrudDtoClasses(User, {
-  query: {
-    filters: {
-      nameContains: {
-        schema: t.string({ minLength: 1 }),
-        field: "name",
-        operator: "contains"
-      }
-    }
-  }
+import { ValidationErrors, t, validate } from "adorn-api";
+
+const schema = t.object({
+  email: t.string({ format: "email" }),
+  age: t.integer({ minimum: 18 })
 });
+
+const errors = validate(data, schema);
+if (errors.length) {
+  throw new ValidationErrors(errors);
+}
 ```
 
-Breaking changes summary:
-- `createMetalCrudDtoClasses` now generates query/options/paged/error artifacts directly.
-- Query filter definitions now include schema + operator + field mapping in one `query.filters` block.
-- Sort allowlist now lives in `query.sortableColumns` and feeds both DTO schemas and runtime metadata.
-- Generated outputs now include `queryDto`, `optionsQueryDto`, `pagedResponseDto`, `optionDto`, `optionsDto`, `errors`, `filterMappings`, and `sortableColumns`.
-- Consumers no longer need internal `dist/...` imports for query/filter metadata types; all relevant types/utilities are publicly exported from `adorn-api`.
+Input coercion can be:
 
-### Using `listConfig` (Zero-Duplication Service Layer)
+- `"safe"`: coerce common values such as `"1"` to `1` and `"true"` to `true`
+- `"strict"`: stricter conversion rules
+- `false`: disabled
 
-`createMetalCrudDtoClasses` now exposes a `listConfig` object that bundles all filter/sort/pagination config needed by your service layer. No more re-declaring mappings in your repository:
+Low-level coercion helpers are exported as `coerce`, `parseNumber`, `parseInteger`, `parseBoolean`, and `parseId`.
+
+## Serialization
+
+Response serialization respects DTO schemas and transformation decorators:
 
 ```typescript
-// user.controller.ts — using listConfig directly
-import {
-  Controller, Get, Query, Returns,
-  runPagedList,
-  type RequestContext
-} from "adorn-api";
-import { createSession } from "./db";
-import { User } from "./user.entity";
-import {
-  UserQueryDto,
-  UserPagedResponseDto,
-  USER_LIST_CONFIG
-} from "./user.dtos";
+import { Dto, Exclude, Expose, Field, Transform, Transforms, serialize, t } from "adorn-api";
 
-@Controller("/users")
-export class UserController {
-  @Get("/")
-  @Query(UserQueryDto)
-  @Returns(UserPagedResponseDto)
-  async list(ctx: RequestContext<unknown, UserQueryDto>) {
-    const session = createSession();
-    try {
-      return await runPagedList({
-        query: (ctx.query ?? {}) as Record<string, unknown>,
-        target: User,
-        qb: () => User.select(),
-        session,
-        ...USER_LIST_CONFIG
-      });
-    } finally {
-      await session.dispose();
-    }
-  }
-}
-```
-
-The `listConfig` object contains: `filterMappings`, `sortableColumns`, `defaultSortBy`, `defaultSortDirection`, `defaultPageSize`, `maxPageSize`, `sortByKey`, and `sortDirectionKey`.
-
-### Type-Only Query Interfaces
+@Dto()
+class UserDto {
+  @Field(t.string())
+  id!: string;
 
-For consumer projects that need pure TypeScript interfaces (without creating extra DTO classes), Adorn exports:
-- `PaginationQueryParams`
-- `SortingQueryParams`
-- `PagedQueryParams`
+  @Field(t.string())
+  @Transform(Transforms.toLowerCase)
+  email!: string;
 
-```typescript
-import type { PagedQueryParams } from "adorn-api";
+  @Field(t.string())
+  @Exclude()
+  passwordHash!: string;
 
-interface CaixaEntradaQueryDto extends PagedQueryParams {
-  usuarioId?: number;
-  lido?: boolean;
+  @Field(t.string())
+  @Expose({ name: "display_name" })
+  name!: string;
 }
+
+const output = serialize(user);
 ```
 
-`sortDirection` is the official typed sort field (`"asc" | "desc"`). `sortOrder` remains parser compatibility for legacy/external clients.
+Use `createSerializer({ groups: [...] })` when you need reusable serialization presets.
 
-### `BaseService.list` Before/After (Boilerplate Reduction)
+## File Uploads
 
-Before:
+Enable multipart on the adapter and declare file fields on the route:
 
 ```typescript
-async list(query: Record<string, unknown>) {
-  const { page, pageSize } = parsePagination(query, this.listConfig);
-  const filters = parseFilter(query, this.listConfig.filterMappings);
-  const sort = parseSort(query, this.listConfig.sortableColumns, {
-    defaultSortBy: this.listConfig.defaultSortBy,
-    defaultSortDirection: this.listConfig.defaultSortDirection,
-    sortByKey: this.listConfig.sortByKey,
-    sortDirectionKey: this.listConfig.sortDirectionKey
-  });
-  const direction = sort?.sortDirection === "desc" ? "DESC" : "ASC";
-
-  return withSession(this.createSession, async (session) => {
-    const qb = applyFilter(this.baseQuery().orderBy(this.ref.id, direction), this.entity, filters);
-    const paged = await qb.executePaged(session, { page, pageSize });
-    return toPagedResponse(paged);
-  });
-}
-```
+import { Controller, Post, Returns, UploadedFile, UploadedFiles, t } from "adorn-api";
 
-After:
+@Controller("/uploads")
+class UploadController {
+  @Post("/avatar")
+  @UploadedFile("file", t.file({ accept: ["image/*"], maxSize: 5 * 1024 * 1024 }))
+  @Returns(t.object({ originalName: t.string(), size: t.integer() }))
+  async avatar(ctx: any) {
+    const file = ctx.files.file;
+    return {
+      originalName: file.originalName,
+      size: file.size
+    };
+  }
 
-```typescript
-async list(query: Record<string, unknown>) {
-  return withSession(this.createSession, async (session) =>
-    runPagedList({
-      query,
-      target: this.entity,
-      qb: () => this.baseQuery(),
-      session,
-      ...this.listConfig
-    })
-  );
+  @Post("/gallery")
+  @UploadedFiles("files", t.file({ accept: ["image/*"] }))
+  async gallery(ctx: any) {
+    return { count: ctx.files.files.length };
+  }
 }
-```
-
-Migration note:
-- Existing `parsePagination`, `parseFilter`, and `parseSort` remain unchanged and can still be used manually.
-- `runPagedList`/`executeCrudList` is additive and optional; no breaking API changes.
-- For sortable fields that are not direct columns of the base table, pass `allowedSortColumns` with explicit metal-orm sort terms.
-
-### Sort Order Compatibility (`sortOrder` / `sortDirection`)
-
-`parseSort` now accepts both `sortDirection` (lowercase `asc`/`desc`) and `sortOrder` (uppercase `ASC`/`DESC`). This avoids the need for a custom helper when integrating with clients that send uppercase sort orders.
-
-**Precedence**: `sortDirection` > `sortOrder` > default. Direction values are case-insensitive.
 
-```typescript
-// Client sends: ?sortBy=name&sortOrder=DESC
-const sort = parseSort(query, sortableColumns);
-// → { sortBy: "name", sortDirection: "desc", field: "name" }
-
-// Client sends both: ?sortBy=name&sortDirection=asc&sortOrder=DESC
-const sort2 = parseSort(query, sortableColumns);
-// → { sortBy: "name", sortDirection: "asc", field: "name" }  (sortDirection wins)
-
-// Custom sortOrder key:
-const sort3 = parseSort({
-  query,
-  sortableColumns,
-  sortOrderKey: "order"  // reads from query.order instead of query.sortOrder
+await createExpressApp({
+  controllers: [UploadController],
+  multipart: {
+    storage: "memory",
+    maxFileSize: 10 * 1024 * 1024,
+    maxFiles: 10
+  }
 });
 ```
 
-### Deep Relation Filters
-
-`parseFilter` now accepts nested relation paths, so you can filter deep chains like Alpha → Bravo → Charlie → Delta. If
-you type your filter mappings with `FilterMapping`, VS Code will enforce relation quantifiers like `some`, `every`, or
-`none` for relation filters, matching Metal ORM's runtime rules.
-
-```typescript
-// alpha.entity.ts
-import { BelongsTo, Column, Entity, HasMany, PrimaryKey, col } from "metal-orm";
-import type { BelongsToReference, HasManyCollection } from "metal-orm";
+Uploaded file info contains `originalName`, `mimeType`, `size`, `buffer`, `path`, and `fieldName`.
 
-@Entity({ tableName: "alphas" })
-export class Alpha {
-  @PrimaryKey(col.autoIncrement(col.int()))
-  id!: number;
+## Raw, SSE, and Streaming
 
-  @Column(col.notNull(col.text()))
-  name!: string;
-
-  @HasMany({ target: () => Bravo, foreignKey: "alphaId" })
-  bravos!: HasManyCollection<Bravo>;
-}
-
-@Entity({ tableName: "bravos" })
-export class Bravo {
-  @PrimaryKey(col.autoIncrement(col.int()))
-  id!: number;
-
-  @Column(col.notNull(col.text()))
-  code!: string;
-
-  @Column(col.notNull(col.int()))
-  alphaId!: number;
-
-  @BelongsTo({ target: () => Alpha, foreignKey: "alphaId" })
-  alpha!: BelongsToReference<Alpha>;
-
-  @HasMany({ target: () => Charlie, foreignKey: "bravoId" })
-  charlies!: HasManyCollection<Charlie>;
-}
-
-@Entity({ tableName: "charlies" })
-export class Charlie {
-  @PrimaryKey(col.autoIncrement(col.int()))
-  id!: number;
-
-  @Column(col.notNull(col.int()))
-  score!: number;
-
-  @Column(col.notNull(col.int()))
-  bravoId!: number;
-
-  @Column(col.int())
-  deltaId?: number | null;
-
-  @BelongsTo({ target: () => Bravo, foreignKey: "bravoId" })
-  bravo!: BelongsToReference<Bravo>;
-
-  @BelongsTo({ target: () => Delta, foreignKey: "deltaId" })
-  delta?: BelongsToReference<Delta>;
-}
+### Raw Responses
 
-@Entity({ tableName: "deltas" })
-export class Delta {
-  @PrimaryKey(col.autoIncrement(col.int()))
-  id!: number;
+```typescript
+import { Controller, Get, Raw, ok } from "adorn-api";
+import fs from "node:fs/promises";
 
-  @Column(col.notNull(col.text()))
-  name!: string;
+@Controller("/files")
+class FileController {
+  @Get("/report.pdf")
+  @Raw({ contentType: "application/pdf", description: "Download PDF report" })
+  async report() {
+    return ok(await fs.readFile("report.pdf"));
+  }
 }
 ```
 
+### Server-Sent Events
+
 ```typescript
-// alpha.controller.ts (filtering)
-import { parseFilter, type FilterMapping } from "adorn-api";
-import { applyFilter, selectFromEntity, type WhereInput } from "metal-orm";
-import { Alpha } from "./alpha.entity";
+import { Controller, Get, Sse } from "adorn-api";
 
-const ALPHA_FILTERS = {
-  deltaNameContains: {
-    field: "bravos.some.charlies.some.delta.some.name",
-    operator: "contains"
-  },
-  deltaIsMissing: {
-    field: "bravos.some.charlies.some.delta",
-    operator: "isEmpty"
-  },
-  charlieScoreGte: {
-    field: "bravos.some.charlies.some.score",
-    operator: "gte"
+@Controller("/events")
+class EventsController {
+  @Get("/")
+  @Sse({ description: "Event stream" })
+  async stream(ctx: any) {
+    ctx.sse.send({ message: "connected" });
+    ctx.sse.close();
   }
-} as const satisfies Record<string, FilterMapping<Alpha>>;
-
-const filters = parseFilter(
-  (ctx.query ?? {}) as Record<string, unknown>,
-  ALPHA_FILTERS
-);
-
-const query = applyFilter(
-  selectFromEntity(Alpha),
-  Alpha,
-  filters as WhereInput<typeof Alpha>
-);
+}
 ```
 
-Example query string: `?deltaNameContains=core&charlieScoreGte=90`
-
-### Tree DTOs (Nested Set / MPTT)
-
-Metal ORM's tree helpers map cleanly into Adorn. Use `createMetalTreeDtoClasses` to generate DTOs for tree nodes,
-node results, threaded trees, and tree lists. These schemas are included in OpenAPI automatically.
+### Streaming
 
 ```typescript
-// category.dtos.ts
-import { createMetalTreeDtoClasses } from "adorn-api";
-import { CategoryDto } from "./category.dtos";
-import { Category } from "./category.entity";
-
-export const {
-  node: CategoryNodeDto,
-  nodeResult: CategoryNodeResultDto,
-  threadedNode: CategoryThreadedNodeDto,
-  treeListEntry: CategoryTreeListEntryDto,
-  treeListSchema: CategoryTreeListSchema,
-  threadedTreeSchema: CategoryThreadedTreeSchema
-} = createMetalTreeDtoClasses(Category, {
-  entityDto: CategoryDto
-});
-```
+import { Controller, Get, Streaming } from "adorn-api";
 
-```typescript
-// category.controller.ts
-import { Controller, Get, Returns } from "adorn-api";
-import { CategoryThreadedTreeSchema } from "./category.dtos";
-
-@Controller("/categories")
-class CategoryController {
-  @Get("/tree")
-  @Returns(CategoryThreadedTreeSchema)
-  async tree() {
-    // return threaded tree data
+@Controller("/exports")
+class ExportController {
+  @Get("/ndjson")
+  @Streaming({ contentType: "application/x-ndjson" })
+  async ndjson(ctx: any) {
+    ctx.stream.writeJsonLine({ id: 1 });
+    ctx.stream.writeJsonLine({ id: 2 });
+    ctx.stream.close();
   }
 }
 ```
 
-## Configuration
+## Health, Logging, and Lifecycle
 
-### Express App Options
+### Health Checks
 
 ```typescript
-createExpressApp({
-  // Required
-  controllers: [UserController],
-  
-  // Optional
-  cors: true, // Enable CORS with default options or configure
-  jsonBody: true, // Parse JSON bodies (default: true)
-  inputCoercion: "safe", // Input coercion mode ("safe" or "strict")
-  validation: { // Validation configuration
-    enabled: true, // Enable validation (default: true)
-    mode: "strict" // Validation mode: "strict" or "safe"
-  },
-  multipart: { // File upload configuration
-    dest: "./uploads",
-    limits: { fileSize: 50 * 1024 * 1024 }
-  },
-  openApi: {
-    info: {
-      title: "My API",
-      version: "1.0.0",
-      description: "API documentation"
-    },
-    path: "/openapi.json", // OpenAPI schema endpoint
-    docs: true // Serve Swagger UI
-  }
+import {
+  createHealthController,
+  databaseIndicator,
+  memoryIndicator
+} from "adorn-api";
+
+const HealthController = createHealthController({
+  path: "/health",
+  indicators: [
+    memoryIndicator({ degradedMB: 512, unhealthyMB: 1024 }),
+    databaseIndicator("database", async () => {
+      await db.ping();
+    })
+  ]
 });
 ```
 
-## Schema Types
-
-The `t` object provides a rich set of schema types:
-
-- Primitives: `t.string()`, `t.number()`, `t.integer()`, `t.boolean()`
-- Formats: `t.uuid()`, `t.dateTime()`
-- Complex: `t.array()`, `t.object()`, `t.record()`
-- Combinators: `t.union()`, `t.enum()`, `t.literal()`
-- Special: `t.ref()`, `t.any()`, `t.null()`, `t.file()`
-- Modifiers: `t.optional()`, `t.nullable()`
-
-## DTO Composition
-
-Reuse and compose DTOs with these decorators:
+### Logging
 
 ```typescript
-// Pick specific fields from an existing DTO
-@PickDto(UserDto, ["id", "name"])
-export class UserSummaryDto {}
-
-// Omit specific fields from an existing DTO
-@OmitDto(UserDto, ["password"])
-export class PublicUserDto {}
-
-// Make all fields optional
-@PartialDto(UserDto)
-export class UpdateUserDto {}
-
-// Merge multiple DTOs
-@MergeDto([UserDto, AddressDto])
-export class UserWithAddressDto {}
-```
+import { createLogger, prettyTransport, requestLogger } from "adorn-api";
 
-## Error Handling
+const logger = createLogger({
+  level: "info",
+  transport: prettyTransport
+});
 
-Define structured error responses:
+logger.info("Application booted");
 
-```typescript
-import { Controller, Get, ReturnsError, t } from "adorn-api";
-
-@Controller("/")
-class ErrorController {
-  @Get("/error")
-  @ReturnsError({
-    status: 404,
-    schema: t.object({
-      code: t.string(),
-      message: t.string(),
-      details: t.optional(t.record(t.any()))
-    }),
-    description: "Resource not found"
-  })
-  async notFound() {
-    throw new HttpError(404, "Resource not found", { code: "NOT_FOUND" });
-  }
-}
+app.use(requestLogger({
+  transport: prettyTransport,
+  skip: ["/health/live"]
+}));
 ```
 
-## Lifecycle Hooks
+### Lifecycle Hooks
 
 ```typescript
 import {
-  OnApplicationBootstrap,
-  OnShutdown
+  lifecycleRegistry,
+  type OnApplicationBootstrap,
+  type OnApplicationShutdown
 } from "adorn-api";
 
-class DatabaseService implements OnApplicationBootstrap, OnShutdown {
+class DatabaseService implements OnApplicationBootstrap, OnApplicationShutdown {
   async onApplicationBootstrap() {
-    console.log("Connecting to database...");
-    // Initialize database connection
+    await db.connect();
   }
 
-  async onShutdown(signal?: string) {
-    console.log(`Shutting down (${signal})...`);
-    // Cleanup resources
+  async onApplicationShutdown() {
+    await db.close();
   }
 }
 
-// Register the service
-import { lifecycleRegistry } from "adorn-api";
 lifecycleRegistry.register(new DatabaseService());
 ```
 
-## Validation
+Use `shutdownExpressApp`, `shutdownFastifyApp`, or `shutdownNativeApp` to trigger shutdown hooks and clear the lifecycle registry.
 
-Adorn API provides automatic request validation and a comprehensive validation system for your DTOs and schemas.
+## Metal ORM
 
-### Validation Configuration
+Adorn includes optional helpers for Metal ORM projects. They generate DTOs, OpenAPI schemas, filters, pagination, sorting, and CRUD controllers from entity metadata.
 
-```typescript
-createExpressApp({
-  controllers: [UserController],
-  validation: {
-    enabled: true, // Enable validation (default: true)
-    mode: "strict" // Validation mode: "strict" or "safe"
-  }
-});
-```
-
-### Validation Errors
-
-Invalid requests automatically return structured validation errors:
+### Entity DTOs
 
 ```typescript
-// Example error response
-{
-  "statusCode": 400,
-  "message": "Validation failed",
-  "errors": [
-    {
-      "field": "name",
-      "message": "must be at least 1 character long",
-      "value": "",
-      "code": "STRING_MIN_LENGTH"
+import { createMetalCrudDtoClasses, t } from "adorn-api";
+import { User } from "./user.entity";
+
+export const userCrudDtos = createMetalCrudDtoClasses(User, {
+  mutationExclude: ["id", "createdAt"],
+  query: {
+    filters: {
+      nameContains: {
+        schema: t.string({ minLength: 1 }),
+        field: "name",
+        operator: "contains"
+      }
+    },
+    sortableColumns: {
+      id: "id",
+      name: "name",
+      createdAt: "createdAt"
     },
-    {
-      "field": "email",
-      "message": "must be a valid email",
-      "value": "invalid-email",
-      "code": "FORMAT_EMAIL"
+    options: {
+      labelField: "name"
     }
-  ]
-}
-```
-
-### Validation Error Codes
-
-Adorn API provides machine-readable error codes for programmatic error handling:
-
-```typescript
-import { ValidationErrorCode } from "adorn-api";
+  },
+  errors: true
+});
 
-console.log(ValidationErrorCode.FORMAT_EMAIL); // "FORMAT_EMAIL"
-console.log(ValidationErrorCode.STRING_MIN_LENGTH); // "STRING_MIN_LENGTH"
+export const {
+  response: UserDto,
+  create: CreateUserDto,
+  replace: ReplaceUserDto,
+  update: UpdateUserDto,
+  params: UserParamsDto,
+  queryDto: UserQueryDto,
+  optionsQueryDto: UserOptionsQueryDto,
+  pagedResponseDto: UserPagedResponseDto,
+  optionDto: UserOptionDto,
+  optionsDto: UserOptionsDto,
+  errors: UserErrors,
+  filterMappings: USER_FILTER_MAPPINGS,
+  sortableColumns: USER_SORTABLE_COLUMNS,
+  listConfig: USER_LIST_CONFIG
+} = userCrudDtos;
 ```
 
-### Manual Validation
-
-You can also manually validate data using the `validate` function:
+### Paged Lists
 
 ```typescript
-import { validate, ValidationErrors, t } from "adorn-api";
-
-const data = { name: "", email: "invalid" };
-const errors = validate(data, t.object({
-  name: t.string({ minLength: 1 }),
-  email: t.string({ format: "email" })
-}));
+import { Controller, Get, Query, Returns, runPagedList, type RequestContext } from "adorn-api";
+import { createSession } from "./db";
+import { User } from "./user.entity";
+import { UserPagedResponseDto, UserQueryDto, USER_LIST_CONFIG } from "./user.dtos";
 
-if (errors.length > 0) {
-  throw new ValidationErrors(errors);
+@Controller("/users")
+class UserController {
+  @Get("/")
+  @Query(UserQueryDto)
+  @Returns(UserPagedResponseDto)
+  async list(ctx: RequestContext<unknown, UserQueryDto>) {
+    const session = createSession();
+    try {
+      return await runPagedList({
+        query: (ctx.query ?? {}) as Record<string, unknown>,
+        target: User,
+        qb: () => User.select(),
+        session,
+        ...USER_LIST_CONFIG
+      });
+    } finally {
+      await session.dispose();
+    }
+  }
 }
 ```
 
-## Transformers
-
-Transform fields during serialization with custom transform functions or built-in transform utilities.
-
-### Basic Transform
+### CRUD Controller Factory
 
 ```typescript
-import { Dto, Field, Transform, t } from "adorn-api";
-
-@Dto()
-export class UserDto {
-  @Field(t.string())
-  @Transform((value) => value.toUpperCase())
-  name!: string;
+import { createCrudController } from "adorn-api";
+import { userCrudDtos } from "./user.dtos";
+import { UserCrudService } from "./user.service";
 
-  @Field(t.dateTime())
-  @Transform((value) => value.toISOString())
-  createdAt!: Date;
-}
+export const UserController = createCrudController({
+  path: "/users",
+  service: new UserCrudService(),
+  dtos: userCrudDtos,
+  entityName: "User",
+  withOptionsRoute: true,
+  withReplace: true,
+  withPatch: true,
+  withDelete: true
+});
 ```
 
-### Built-in Transforms
-
-Adorn API includes common transform functions:
-
-```typescript
-import { Dto, Field, Transform, Transforms, t } from "adorn-api";
-
-@Dto()
-export class UserDto {
-  @Field(t.string())
-  @Transform(Transforms.toLowerCase)
-  email!: string;
-
-  @Field(t.number())
-  @Transform(Transforms.round(2))
-  price!: number;
-
-  @Field(t.string())
-  @Transform(Transforms.mask(4)) // Mask all but last 4 characters
-  creditCard!: string;
+Generated routes:
 
-  @Field(t.dateTime())
-  @Transform(Transforms.toISOString)
-  birthDate!: Date;
-}
-```
+- `GET /`
+- `GET /options` when `withOptionsRoute` is true
+- `GET /:id`
+- `POST /`
+- `PUT /:id` when `withReplace` is true
+- `PATCH /:id` when `withPatch` is true
+- `DELETE /:id` when `withDelete` is true
 
-### Conditional Transforms with Groups
+### Filters and Sort
 
-Apply transforms only to specific serialization groups:
+Use generated `filterMappings`, `sortableColumns`, and `listConfig` where possible. Manual parsers are also public:
 
 ```typescript
-import { Dto, Field, Transform, Expose, t } from "adorn-api";
-
-@Dto()
-export class UserDto {
-  @Field(t.string())
-  name!: string;
-
-  @Field(t.string())
-  @Expose({ groups: ["admin"] })
-  @Transform((value) => Transforms.mask(2), { groups: ["admin"] })
-  phoneNumber!: string;
+import { parseFilter, parsePagination, parseSort } from "adorn-api";
 
-  @Field(t.string())
-  @Expose({ groups: ["internal"] })
-  @Transform((value) => "[REDACTED]", { groups: ["external"] })
-  internalNote!: string;
-}
+const pagination = parsePagination(ctx.query);
+const filters = parseFilter(ctx.query, USER_FILTER_MAPPINGS);
+const sort = parseSort(ctx.query, USER_SORTABLE_COLUMNS);
 ```
 
-### Custom Transform Functions
+`parseSort` accepts `sortDirection=asc|desc` and legacy `sortOrder=ASC|DESC`. `sortDirection` wins when both are present.
 
-Create custom transform functions:
+Deep relation filters are supported through typed Metal ORM field paths such as:
 
 ```typescript
-import { Dto, Field, Transform, t } from "adorn-api";
-
-const toCurrency = (value: number, currency: string = "USD") => {
-  return new Intl.NumberFormat("en-US", {
-    style: "currency",
-    currency
-  }).format(value);
-};
-
-@Dto()
-export class ProductDto {
-  @Field(t.string())
-  name!: string;
-
-  @Field(t.number())
-  @Transform(toCurrency)
-  price!: number;
-
-  @Field(t.number())
-  @Transform((value) => toCurrency(value, "EUR"))
-  priceEUR!: number;
-}
+const filters = {
+  deltaNameContains: {
+    field: "bravos.some.charlies.some.delta.some.name",
+    operator: "contains"
+  }
+} as const;
 ```
 
-### Serialization with Options
-
-Control serialization with custom options:
+### Tree DTOs
 
 ```typescript
-import { serialize, createSerializer } from "adorn-api";
-import { UserDto } from "./user.dtos";
-
-const user = new UserDto();
-user.name = "John Doe";
-user.phoneNumber = "123-456-7890";
-user.internalNote = "This is an internal note";
-
-// Basic serialization
-const basic = serialize(user);
-// Output: { name: "John Doe" }
-
-// Admin group serialization
-const admin = serialize(user, { groups: ["admin"] });
-// Output: { name: "John Doe", phoneNumber: "********90" }
-
-// External group serialization
-const external = serialize(user, { groups: ["external"] });
-// Output: { name: "John Doe", internalNote: "[REDACTED]" }
+import { createMetalTreeDtoClasses } from "adorn-api";
+import { CategoryDto } from "./category.dtos";
+import { Category } from "./category.entity";
 
-// Create a preset serializer
-const adminSerializer = createSerializer({ groups: ["admin"] });
-const adminData = adminSerializer(user);
+export const {
+  node: CategoryNodeDto,
+  nodeResult: CategoryNodeResultDto,
+  threadedNode: CategoryThreadedNodeDto,
+  treeListEntry: CategoryTreeListEntryDto,
+  treeListSchema: CategoryTreeListSchema,
+  threadedTreeSchema: CategoryThreadedTreeSchema
+} = createMetalTreeDtoClasses(Category, {
+  entityDto: CategoryDto
+});
 ```
 
-### Exclude Fields
-
-Control which fields are excluded or exposed:
+## Examples
 
-```typescript
-import { Dto, Field, Exclude, Expose, t } from "adorn-api";
+Run examples with:
 
-@Dto()
-export class UserDto {
-  @Field(t.string())
-  name!: string;
+```bash
+npm run example -- <name>
+```
+
+Available examples:
+
+- `basic`: Express API with DTOs and OpenAPI
+- `bearer-auth-swagger`: Bearer token auth in Swagger UI
+- `fastify`: Fastify adapter
+- `openapi`: build and print an OpenAPI document
+- `restful`: in-memory REST CRUD
+- `streaming`: SSE and streaming routes
+- `validation`: schema validation examples
+- `metal-orm`: baseline Metal ORM example
+- `metal-orm-collection-lawsuit`: collection/relation scenario with Metal ORM
+- `metal-orm-sqlite`: Metal ORM with SQLite
+- `metal-orm-postgres`: Metal ORM with Postgres
+- `metal-orm-sqlite-music`: richer Metal ORM relations
+- `metal-orm-deep-filters`: nested relation filters
+- `metal-orm-tree`: tree DTO generation
 
-  @Field(t.string())
-  @Exclude() // Always exclude from serialization
-  password!: string;
+## Testing
 
-  @Field(t.string())
-  @Expose({ name: "email_address" }) // Rename field in output
-  email!: string;
+The project uses Vitest and SuperTest.
 
-  @Field(t.string())
-  @Exclude({ groups: ["public"] }) // Exclude from public group
-  internalComment!: string;
-}
+```bash
+npm run build
+npm test
+npm run typecheck:tests
 ```
 
-## Examples
-
-Check out the `examples/` directory for more comprehensive examples:
-
-- `basic/` - Simple API with controllers and DTOs
-- `restful/` - RESTful API with complete CRUD operations
-- `metal-orm-sqlite/` - Metal ORM integration with SQLite
-- `metal-orm-tree/` - Metal ORM tree (nested set) DTO + OpenAPI integration
-- `metal-orm-deep-filters/` - Deep relation filtering example (Alpha → Bravo → Charlie → Delta)
-- `metal-orm-sqlite-music/` - Complex relations with Metal ORM
-- `streaming/` - SSE and streaming responses
-- `openapi/` - OpenAPI documentation customization
-- `validation/` - Comprehensive validation examples with various schema types
-
-## Testing
-
-Adorn API works great with testing frameworks like Vitest and SuperTest. Here's an example:
+Example app test:
 
 ```typescript
-import { describe, it, expect } from "vitest";
+import { describe, expect, it } from "vitest";
 import request from "supertest";
 import { createApp } from "./app";
 
-describe("User API", () => {
-  it("should get user by id", async () => {
+describe("Users API", () => {
+  it("gets a user", async () => {
     const app = await createApp();
-    
+
     const response = await request(app)
-      .get("/users/1")
+      .get("/users/3f0f4d0f-1cb1-4cf1-9c32-3d4bce1b3f36")
       .expect(200);
-    
-    expect(response.body).toEqual({
-      id: "1",
-      name: "Ada Lovelace",
-      nickname: "Ada"
-    });
+
+    expect(response.body.name).toBe("Ada Lovelace");
   });
 });
 ```
 
-## License
+## Public Entry Points
 
-MIT
+The package exports:
 
-## Contributing
+- Core decorators, schemas, OpenAPI, errors, responses, validation, coercion, serialization, auth, lifecycle, streaming, health, and logger helpers
+- Express adapter: `createExpressApp`, `attachExpressControllers`, `attachExpressOpenApi`, `shutdownExpressApp`
+- Fastify adapter: `createFastifyApp`, `attachFastifyControllers`, `attachFastifyOpenApi`, `shutdownFastifyApp`
+- Native adapter: `createNativeApp`, `attachNativeControllers`, `attachNativeOpenApi`, `shutdownNativeApp`
+- Metal ORM helpers from `adorn-api`
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+## License
+
+MIT