adorn-api 1.0.11 → 1.0.13

package/README.md

@@ -1,18 +1,30 @@
 # Adorn-API
 
-Stage-3 decorator-first OpenAPI + routing toolkit for TypeScript.
+A Stage-3 decorator-first OpenAPI + routing toolkit for Express with full TypeScript support.
 
-Build type-safe REST APIs with decorators. Get automatic OpenAPI 3.1 documentation, runtime validation, and authentication out of the box.
+## Features
 
-## Quick Start
+- **Decorators-First**: Use Stage-3 decorators to define controllers, routes, middleware, and auth
+- **Auto-Generated OpenAPI**: OpenAPI 3.1 specs generated from your TypeScript types
+- **Swagger UI**: Interactive API documentation at `/docs` with zero configuration
+- **Type-Safe**: Full TypeScript inference throughout your API
+- **Authentication**: Built-in auth support with scope-based authorization
+- **Middleware**: Apply middleware globally, per-controller, or per-route
+- **Metal-ORM Integration**: Seamless database integration with type-safe queries
+- **Validation**: AJV runtime validation with optional precompiled validators
+- **Hot Reload**: Development mode with automatic rebuilds
+
+## Installation
 
 ```bash
 npm install adorn-api
+npm install -D @types/express
 ```
 
-Create a controller:
+## Quick Start
 
 ```typescript
+// controller.ts
 import { Controller, Get, Post } from "adorn-api";
 
 interface User {
@@ -21,812 +33,498 @@ interface User {
   email: string;
 }
 
-const users: User[] = [
-  { id: 1, name: "Alice", email: "alice@example.com" },
-];
-
 @Controller("/users")
 export class UserController {
   @Get("/")
   async getUsers(): Promise<User[]> {
-    return users;
-  }
-
-  @Get("/:id")
-  async getUser(id: number): Promise<User | null> {
-    return users.find(u => u.id === id) || null;
+    return [{ id: 1, name: "Alice", email: "alice@example.com" }];
   }
 
   @Post("/")
   async createUser(body: { name: string; email: string }): Promise<User> {
-    const user: User = {
-      id: users.length + 1,
-      name: body.name,
-      email: body.email,
-    };
-    users.push(user);
-    return user;
+    return { id: 2, name: body.name, email: body.email };
   }
 }
 ```
 
-Start your server:
-
 ```typescript
+// server.ts
 import { bootstrap } from "adorn-api/express";
 import { UserController } from "./controller.js";
 
-await bootstrap({ controllers: [UserController] });
-```
-
-Visit http://localhost:3000/docs to see your auto-generated Swagger UI.
-
-## Features
-
-- **Decorator-based routing** - `@Controller`, `@Get`, `@Post`, `@Put`, `@Patch`, `@Delete`
-- **Automatic OpenAPI 3.1** - Generate specs from TypeScript decorators
-- **Runtime validation** - AJV-powered request validation
-- **Authentication** - `@Auth()` and `@Public()` decorators with custom schemes
-- **Middleware** - Global, controller-level, and route-level middleware
-- **Type-safe** - Full TypeScript inference throughout
-- **Incremental builds** - Smart caching with `--if-stale` flag
-- **Precompiled validators** - Optimized validation for production
-- **Swagger UI** - Built-in documentation at `/docs`
-- **Metal ORM integration** - Auto-generate schemas from entities
-
-## Installation
-
-```bash
-npm install adorn-api
+await bootstrap({
+  controllers: [UserController],
+});
 ```
 
-**Peer dependency:**
+Run with:
 
 ```bash
-npm install express
+npx adorn-api dev
 ```
 
-**Requirements:**
-- Node.js 18+
-- TypeScript 5.0+
+Open http://localhost:3000/docs to see your Swagger UI documentation.
 
 ## Core Concepts
 
 ### Controllers
 
-A controller is a class decorated with `@Controller(path)` that groups related endpoints:
+Define a controller with a base path:
 
 ```typescript
 @Controller("/api/users")
-export class UsersController {
-  @Get("/")
-  async getUsers() { /* ... */ }
-
-  @Get("/:id")
-  async getUser(id: number) { /* ... */ }
-}
+export class UserController {}
 ```
 
-### HTTP Methods
+### Route Handlers
 
-All standard HTTP methods are supported:
+Use HTTP method decorators to define routes:
 
 ```typescript
-@Get("/")       // GET
-@Post("/")      // POST
-@Put("/:id")    // PUT
-@Patch("/:id")  // PATCH
-@Delete("/:id") // DELETE
-```
-
-### Parameters
-
-Adorn-API automatically extracts parameters from your handler signatures:
+@Controller("/users")
+export class UserController {
+  @Get("/")
+  async list(): Promise<User[]> {}
 
-```typescript
-@Controller("/products")
-export class ProductsController {
   @Get("/:id")
-  async getProduct(
-    id: number,                    // Path parameter
-    query?: { category?: string }  // Query parameter
-  ) { /* ... */ }
+  async get(id: number): Promise<User> {}
 
   @Post("/")
-  async createProduct(
-    body: { name: string },        // Request body
-    headers: { "X-Request-Id": string } // Headers
-  ) { /* ... */ }
-}
-```
-
-### Query Objects
-
-Use an object-typed parameter to bind flat query keys:
+  async create(body: CreateUserDto): Promise<User> {}
 
-```typescript
-import type { Query } from "adorn-api";
+  @Put("/:id")
+  async update(id: number, body: UpdateUserDto): Promise<User> {}
 
-type Filters = {
-  status?: string;
-  responsavelId?: number;
-};
+  @Patch("/:id")
+  async patch(id: number, body: Partial<User>): Promise<User> {}
 
-@Get("/")
-async list(query?: Query<Filters>) {
-  return query;
+  @Delete("/:id")
+  async delete(id: number): Promise<void> {}
 }
 ```
 
-`GET /posts?status=published&responsavelId=1`
-
-### Deep Object Query (opt-in)
+### Parameters
 
-For bracketed query serialization, opt in with `@QueryStyle({ style: "deepObject" })`:
+Parameters are automatically extracted from your handler signature:
 
 ```typescript
-import { QueryStyle } from "adorn-api";
-
-type WhereFilter = {
-  responsavel?: {
-    perfil?: {
-      nome?: string;
-    };
-  };
-  tags?: string[];
-};
-
-@Get("/")
-  @QueryStyle({ style: "deepObject" })
-async list(where?: WhereFilter) {
-  return where;
-}
+async handler(
+  id: number,        // Path parameter
+  query: { limit?: number; sort?: string },  // Query parameters
+  body: CreateUserDto,  // Request body
+  headers: { authorization?: string },  // Headers
+  cookies: { sessionId?: string }  // Cookies
+) {}
 ```
 
-- `GET /posts?where[responsavel][perfil][nome]=Admin`
-- `GET /posts?where[tags]=a&where[tags]=b`
-- `GET /posts?where[comments][author][name]=Ali` (matches `Alice`)
-
-Notes:
-- Deep object is explicit and only applies to the query object parameter on that method.
-- Repeated keys become arrays (for example, `where[tags]=a&where[tags]=b`).
-- The `[]` shorthand is not supported; use repeated keys instead.
-
-## Examples
-
-### Basic Example
+### Middleware
 
-Minimal API with CRUD operations. See: `examples/basic/`
+Apply middleware at any level:
 
 ```typescript
-import { Controller, Get, Post, Put, Delete } from "adorn-api";
+// Global middleware
+const app = await bootstrap({
+  controllers: [UserController],
+  middleware: {
+    global: [loggingMiddleware, corsMiddleware],
+    named: { auth: authMiddleware },
+  },
+});
 
+// Controller-level middleware
 @Controller("/users")
-export class UserController {
-  @Get("/")
-  async getUsers() { return [{ id: 1, name: "Alice" }]; }
+@Use(authMiddleware)
+export class UserController {}
 
-  @Get("/:id")
-  async getUser(id: number) { /* ... */ }
+// Route-level middleware
+@Get("/admin")
+@Use(adminMiddleware)
+async adminOnly() {}
 
-  @Post("/")
-  async createUser(body: { name: string }) { /* ... */ }
-
-  @Put("/:id")
-  async updateUser(id: number, body: { name?: string }) { /* ... */ }
-
-  @Delete("/:id")
-  async deleteUser(id: number) { return { success: true }; }
-}
+// Named middleware
+@Get("/protected")
+@Use("auth")
+async protected() {}
 ```
 
-### Authentication Example
+Middleware executes in order: global → controller → route → handler.
 
-Bearer token auth with scopes and public endpoints. See: `examples/simple-auth/`
+### Authentication
 
-```typescript
-import { Controller, Get, Post } from "adorn-api";
-import { Auth, Public } from "adorn-api/decorators";
-
-@Controller("/api")
-export class ApiController {
-  @Get("/public")
-  @Public()
-  async publicEndpoint() {
-    return { message: "No auth required" };
-  }
-
-  @Get("/profile")
-  @Auth("BearerAuth")
-  async getProfile(req: any) {
-    return { user: req.auth };
-  }
-
-  @Get("/data")
-  @Auth("BearerAuth", { scopes: ["read"] })
-  async getData() {
-    return { data: ["item1", "item2"] };
-  }
-
-  @Post("/items")
-  @Auth("BearerAuth", { scopes: ["write"] })
-  async createItem(req: any) {
-    return { id: 1, name: req.body.name };
-  }
-}
-```
-
-Configure the auth scheme when creating your router:
+Define auth schemes and protect routes:
 
 ```typescript
+import { Auth, Public } from "adorn-api";
+
+// Define auth scheme
 const bearerRuntime = {
   name: "BearerAuth",
-  async authenticate(req) {
-    const auth = req.headers.authorization;
-    if (!auth?.startsWith("Bearer ")) return null;
-    if (auth !== "Bearer valid-token") return null;
-    return { principal: { userId: 1 }, scopes: ["read", "write"] };
+  async authenticate(req: any) {
+    const token = req.headers.authorization?.replace("Bearer ", "");
+    const user = await verifyToken(token);
+    return user ? { principal: user, scopes: user.scopes } : null;
   },
-  challenge(res) {
+  challenge(res: any) {
     res.status(401).json({ error: "Unauthorized" });
   },
-  authorize(auth, requiredScopes) {
+  authorize(auth: any, requiredScopes: string[]) {
     return requiredScopes.every(s => auth.scopes?.includes(s));
   },
 };
 
-await createExpressRouter({
-  controllers: [ApiController],
-  auth: { schemes: { BearerAuth: bearerRuntime } },
+// Bootstrap with auth
+await bootstrap({
+  controllers: [UserController],
+  auth: {
+    schemes: { BearerAuth: bearerRuntime },
+  },
 });
-```
-
-### E-commerce Example
 
-Full CRUD with search and status management. See: `examples/ecommerce/`
-
-```typescript
-@Controller("/products")
-export class ProductsController {
-  @Get("/")
-  async getProducts() {
-    return products.filter(p => p.status === "published");
-  }
-
-  @Get("/:id")
-  async getProduct(id: number) { /* ... */ }
-
-  @Post("/")
-  async createProduct(body: { name: string; price: number }) { /* ... */ }
+// Protect routes
+@Controller("/api")
+export class ApiController {
+  @Get("/public")
+  @Public()
+  async publicEndpoint() {}
 
-  @Put("/:id")
-  async updateProduct(id: number, body: Partial<{ name: string; price: number }>) { /* ... */ }
+  @Get("/profile")
+  @Auth("BearerAuth")
+  async getProfile() {}
 
-  @Delete("/:id")
-  async deleteProduct(id: number) { return { success: true }; }
-
-  @Post("/:id/publish")
-  async publishProduct(id: number) { /* ... */ }
-
-  @Post("/search/advanced")
-  async advancedSearch(body: {
-    query?: string;
-    minPrice?: number;
-    maxPrice?: number;
-    inStockOnly?: boolean;
-  }) { /* ... */ }
+  @Post("/admin")
+  @Auth("BearerAuth", { scopes: ["admin"] })
+  async adminOnly() {}
 }
 ```
 
-### Blog Platform with Metal ORM
-
-Database-driven API using Metal ORM entities. See: `examples/blog-platform-metal-orm/`
+### Optional Authentication
 
 ```typescript
-import { Controller, Get, Post, Put, Delete } from "adorn-api";
-import { BlogPost } from "../entities/index.js";
-import { getSession, selectFromEntity, eq } from "metal-orm";
-
-@Controller("/blog-posts")
-export class BlogPostsController {
-  @Get("/")
-  async getPosts(query?: { authorId?: number; status?: string }) {
-    const session = getSession();
-    let qb = selectFromEntity(BlogPost);
-    if (query?.authorId) qb = qb.where(eq(BlogPost.authorId, query.authorId));
-    if (query?.status) qb = qb.where(eq(BlogPost.status, query.status));
-    return qb.execute(session);
+@Get("/resource")
+@Auth("BearerAuth", { optional: true })
+async getResource(req: any) {
+  if (req.auth) {
+    return { user: req.auth.principal };
   }
-
-  @Get("/:id")
-  async getPost(id: number) { /* ... */ }
-
-  @Post("/")
-  async createPost(body: Pick<BlogPost, "title" | "content" | "authorId">) {
-    const session = getSession();
-    const post = new BlogPost();
-    Object.assign(post, body);
-    await session.persist(post);
-    await session.flush();
-    return post;
-  }
-
-  @Put("/:id")
-  async updatePost(id: number, body: Partial<BlogPost>) { /* ... */ }
-
-  @Delete("/:id")
-  async deletePost(id: number) { return { success: true }; }
+  return { user: null };
 }
 ```
 
-### Task Manager Example
+## Metal-ORM Integration
 
-Multi-controller architecture with SQL database. See: `examples/task-manager/`
+Seamlessly integrate with Metal-ORM for database operations:
 
 ```typescript
+import { Controller, Get } from "adorn-api";
+import type { ListQuery } from "adorn-api/metal";
+import { applyListQuery } from "adorn-api/metal";
+import { selectFromEntity, entityRef } from "metal-orm";
+
 @Controller("/tasks")
 export class TasksController {
   @Get("/")
-  async getTasks(query?: { status?: string; priority?: string; search?: string }) {
-    let sql = "SELECT * FROM tasks WHERE 1=1";
-    if (query?.status) sql += " AND status = ?";
-    return allQuery(sql, params);
-  }
-
-  @Get("/:id")
-  async getTask(id: number) { /* returns task with tags */ }
-
-  @Post("/")
-  async createTask(body: { title: string; priority?: "low" | "medium" | "high" }) {
-    const now = new Date().toISOString();
-    return runQuery(sql, [...values, now, now]);
-  }
-
-  @Put("/:id")
-  async updateTask(id: number, body: Partial<Task>) { /* ... */ }
-
-  @Delete("/:id")
-  async deleteTask(id: number) { return { success: result.changes > 0 }; }
-
-  @Post("/:id/tags")
-  async addTagToTask(id: number, body: { tag_id: number }) { /* ... */ }
-}
-
-@Controller("/tags")
-export class TagsController {
-  @Get("/")
-  async getTags() { return allQuery("SELECT * FROM tags"); }
-
-  @Post("/")
-  async createTag(body: { name: string; color?: string }) { /* ... */ }
-}
-
-@Controller("/stats")
-export class StatsController {
-  @Get("/")
-  async getStats() {
-    return {
-      total: count,
-      byStatus: statusMap,
-      byPriority: priorityMap,
-    };
-  }
-}
-```
-
-## Authentication
-
-### @Auth Decorator
-
-Protect endpoints with authentication requirements:
-
-```typescript
-@Controller("/api")
-export class ApiController {
-  @Get("/secure")
-  @Auth("BearerAuth")
-  async secureEndpoint(req: any) {
-    return { user: req.auth };
-  }
+  async list(query: ListQuery<Task>): Promise<PaginatedResult<Task>> {
+    const session = getSession();
+    const T = entityRef(Task);
 
-  @Get("/with-scopes")
-  @Auth("BearerAuth", { scopes: ["read", "write"] })
-  async scopedEndpoint() {
-    return { data: "secret" };
-  }
+    const qb = selectFromEntity(Task)
+      .select("id", "title", "completed")
+      .where(eq(T.completed, false));
 
-  @Get("/optional")
-  @Auth("BearerAuth", { optional: true })
-  async optionalAuth(req: any) {
-    return { user: req.auth }; // null if no token
+    return applyListQuery(qb, session, query);
   }
 }
 ```
 
-### @Public Decorator
+`ListQuery` supports:
+- Pagination: `page`, `perPage`
+- Sorting: `sort` (string or array, prefix with `-` for DESC)
+- Filtering: `where` (deep object filters)
 
-Mark endpoints as publicly accessible (bypasses auth):
+### Register Metal Entities
 
-```typescript
-@Controller("/api")
-export class ApiController {
-  @Get("/public")
-  @Public()
-  async publicEndpoint() {
-    return { message: "Anyone can access this" };
-  }
-
-  @Get("/protected")
-  @Auth("BearerAuth")
-  async protectedEndpoint() {
-    return { message: "Auth required" };
-  }
-}
-```
-
-### Auth Scheme Configuration
-
-Define custom authentication schemes:
+Auto-generate OpenAPI schemas from Metal-ORM entities:
 
 ```typescript
-const jwtRuntime = {
-  name: "JwtAuth",
-  async authenticate(req) {
-    const token = req.headers.authorization?.split(" ")[1];
-    if (!token) return null;
-    try {
-      const payload = verify(token, process.env.JWT_SECRET!);
-      return { principal: payload, scopes: payload.scopes || [] };
-    } catch {
-      return null;
-    }
-  },
-  challenge(res) {
-    res.setHeader("WWW-Authenticate", 'Bearer realm="api"');
-    res.status(401).json({ error: "Invalid token" });
-  },
-  authorize(auth, requiredScopes) {
-    return requiredScopes.every(s => auth.scopes.includes(s));
-  },
-};
+import { registerMetalEntities } from "adorn-api/metal";
+import { User, Post, Comment } from "./entities/index.js";
 
-await createExpressRouter({
-  controllers: [ApiController],
-  auth: { schemes: { JwtAuth: jwtRuntime } },
+registerMetalEntities(openapi, [User, Post, Comment], {
+  mode: "read",
+  stripEntitySuffix: true,
+  includeRelations: "inline",
 });
 ```
 
-## Middleware
-
-Adorn-API supports middleware at three levels: global, controller, and route.
+## Examples
 
-### Global Middleware
+The repository includes several examples demonstrating different features:
 
-Apply middleware to all routes:
+### [Basic](examples/basic/)
+Simple CRUD API with GET, POST endpoints and in-memory data.
 
-```typescript
-await createExpressRouter({
-  controllers: [ControllerA, ControllerB],
-  middleware: {
-    global: [loggingMw, corsMw],
-  },
-});
+```bash
+npm run example basic
 ```
 
-### Controller-Level Middleware
+### [Simple Auth](examples/simple-auth/)
+Authentication with bearer tokens, scope-based authorization, public/protected endpoints.
 
-Use `@Use` on a controller class:
-
-```typescript
-@Controller("/api")
-@Use(controllerMw)
-export class ApiController {
-  @Get("/")
-  async getData() { /* global, controller, then handler */ }
-}
+```bash
+npm run example simple-auth
 ```
 
-### Route-Level Middleware
-
-Use `@Use` on individual methods:
+### [Task Manager](examples/task-manager/)
+Complete task management API with SQLite3, filtering, tags, and statistics.
 
-```typescript
-@Controller("/api")
-export class ApiController {
-  @Get("/")
-  @Use(routeMw)
-  async getData() { /* global, controller, route, then handler */ }
-}
+```bash
+npm run example task-manager
 ```
 
-Middleware execution order: `global` → `controller` → `route` → `handler`
-
-### Named Middleware
+### [Three Controllers](examples/three-controllers/)
+Multiple controllers (Users, Posts, Comments) in a blog application.
 
-Register middleware by name for reuse:
-
-```typescript
-const rateLimiter = (req: any, res: any, next: any) => {
-  // rate limiting logic
-  next();
-};
-
-await createExpressRouter({
-  controllers: [ApiController],
-  middleware: {
-    named: { rateLimiter },
-  },
-});
-```
-
-```typescript
-@Controller("/api")
-export class ApiController {
-  @Get("/")
-  @Use("rateLimiter")
-  async getData() { /* uses named middleware */ }
-}
+```bash
+npm run example three-controllers
 ```
 
-## Schema & Validation
-
-### Schema Decorators
-
-Apply validation rules to object properties:
+### [Blog Platform (Metal-ORM)](examples/blog-platform-metal-orm/)
+Full-featured blog platform with Metal-ORM, relationships, and advanced queries.
 
-```typescript
-import { Schema, Min, Max, MinLength, MaxLength, Pattern, Enum } from "adorn-api/schema";
-
-class CreateUserRequest {
-  @MinLength(2)
-  @MaxLength(50)
-  name: string;
-
-  @Pattern("^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$")
-  email: string;
-
-  @Min(18)
-  @Max(120)
-  age: number;
-
-  @Enum(["admin", "user", "guest"])
-  role: "admin" | "user" | "guest";
-}
+```bash
+npm run example blog-platform-metal-orm
 ```
 
-Available decorators:
-
-| Decorator | Purpose |
-|-----------|---------|
-| `@Min(n)` | Minimum numeric value |
-| `@Max(n)` | Maximum numeric value |
-| `@ExclusiveMin(n)` | Exclusive minimum |
-| `@ExclusiveMax(n)` | Exclusive maximum |
-| `@MinLength(n)` | Minimum string/array length |
-| `@MaxLength(n)` | Maximum string/array length |
-| `@Pattern(regex)` | Regex pattern match |
-| `@Format(fmt)` | Format validation (email, uuid, etc.) |
-| `@MinItems(n)` | Minimum array items |
-| `@MaxItems(n)` | Maximum array items |
-| `@MinProperties(n)` | Minimum object properties |
-| `@MaxProperties(n)` | Maximum object properties |
-| `@MultipleOf(n)` | Numeric multiple |
-| `@Enum([...])` | Enumeration values |
-| `@Const(value)` | Constant value |
-| `@Default(value)` | Default value |
-| `@Example(value)` | Example value for docs |
-| `@Description(text)` | Property description |
-| `@Closed()` | No additional properties |
-| `@ClosedUnevaluated()` | Unevaluated properties not allowed |
-
-### Validation Modes
-
-Control how validation runs:
-
-**Runtime (default):**
+### [E-commerce](examples/ecommerce/)
+E-commerce API with RESTful and non-RESTful endpoints, carts, orders, and coupons.
 
 ```bash
-adorn-api build --validation-mode ajv-runtime
+npm run example ecommerce
 ```
 
-**Precompiled (production-optimized):**
+### [Simple Pagination (Metal-ORM)](examples/simple-pagination-metal-orm/)
+Pagination and sorting with Metal-ORM integration.
 
 ```bash
-adorn-api build --validation-mode precompiled
+npm run example simple-pagination-metal-orm
 ```
 
-Generates optimized validator modules for faster startup.
-
-**Disabled:**
+### [Query JSON (Metal-ORM)](examples/query-json-metal-orm/)
+Advanced filtering with deep object query parameters.
 
 ```bash
-adorn-api build --validation-mode none
+npm run example query-json-metal-orm
 ```
 
-## CLI Reference
-
-### Build Command
+## CLI
 
-Generate OpenAPI spec and manifest from TypeScript source:
+### Development
 
 ```bash
-adorn-api build -p ./tsconfig.json --output .adorn
+npx adorn-api dev
 ```
 
-**Options:**
-
-| Option | Description | Default |
-|--------|-------------|---------|
-| `-p <path>` | Path to tsconfig.json | `./tsconfig.json` |
-| `--output <dir>` | Output directory | `.adorn` |
-| `--if-stale` | Only rebuild if stale | `false` |
-| `--validation-mode <mode>` | Validation mode | `ajv-runtime` |
-
-**Validation modes:** `none`, `ajv-runtime`, `precompiled`
+Builds artifacts and starts server with hot-reload.
 
-### Clean Command
-
-Remove generated artifacts:
+### Build
 
 ```bash
-adorn-api clean --output .adorn
+npx adorn-api build
 ```
 
-### Incremental Builds
+Generates `.adorn/` directory with:
+- `openapi.json` - OpenAPI 3.1 specification
+- `manifest.json` - Runtime binding metadata
+- `cache.json` - Build cache for incremental rebuilds
+- `validator.js` - Precompiled validators (if enabled)
 
-Use `--if-stale` for efficient rebuilds:
+### Run Examples
 
 ```bash
-adorn-api build --if-stale
-```
+# List all examples
+npm run example:list
 
-Only rebuilds when:
-- Controller source files changed
-- TypeScript version changed
-- Adorn-API version changed
+# Run specific example
+npm run example basic
+npm run example blog-platform-metal-orm
+```
 
 ## API Reference
 
-### bootstrap()
+### Decorators
+
+- `@Controller(path)` - Define a controller with base path
+- `@Get(path)` - GET route handler
+- `@Post(path)` - POST route handler
+- `@Put(path)` - PUT route handler
+- `@Patch(path)` - PATCH route handler
+- `@Delete(path)` - DELETE route handler
+- `@Use(...middleware)` - Apply middleware
+- `@Auth(scheme, options)` - Require authentication
+- `@Public()` - Mark route as public (bypasses auth)
 
-Quick server setup with sensible defaults:
+### Exports
 
 ```typescript
-import { bootstrap } from "adorn-api/express";
+import {
+  Controller,
+  Get,
+  Post,
+  Put,
+  Patch,
+  Delete,
+  Use,
+  Auth,
+  Public,
+} from "adorn-api";
+
+import {
+  bootstrap,
+  createExpressRouter,
+  setupSwagger,
+} from "adorn-api/express";
+
+import {
+  ListQuery,
+  applyListQuery,
+  registerMetalEntities,
+} from "adorn-api/metal";
+
+import { readAdornBucket } from "adorn-api";
+import type { AdornBucket, AuthSchemeRuntime, AuthResult } from "adorn-api";
+```
+
+### Bootstrap Options
 
+```typescript
 await bootstrap({
-  controllers: [UserController],
-  port?: number,              // Default: 3000 or PORT env
-  host?: string,              // Default: "0.0.0.0" or HOST env
-  artifactsDir?: string,      // Default: ".adorn"
-  enableSwagger?: boolean,    // Default: true
-  swaggerPath?: string,       // Default: "/docs"
-  swaggerJsonPath?: string,   // Default: "/docs/openapi.json"
-  middleware?: CreateRouterOptions["middleware"],
-  auth?: CreateRouterOptions["auth"],
-  coerce?: CreateRouterOptions["coerce"],
+  controllers: [UserController, PostController],
+  auth: {
+    schemes: {
+      BearerAuth: bearerRuntime,
+      ApiKey: apiKeyRuntime,
+    },
+  },
+  middleware: {
+    global: [logger, cors],
+    named: { auth: authMiddleware },
+  },
+  port: 3000,
+  host: "0.0.0.0",
 });
 ```
 
-**Returns:** `{ server, app, url, port, host, close }`
-
-### createExpressRouter()
-
-Full control over router creation:
+### Auth Scheme
 
 ```typescript
-import { createExpressRouter } from "adorn-api/express";
-
-const router = await createExpressRouter({
-  controllers: [UserController],
-  artifactsDir?: string,      // Default: ".adorn"
-  manifest?: ManifestV1,      // Auto-loaded if not provided
-  openapi?: OpenAPI31,        // Auto-loaded if not provided
-  auth?: {
-    schemes: Record<string, AuthSchemeRuntime>,
+const authScheme: AuthSchemeRuntime = {
+  name: "MyAuth",
+  async authenticate(req: any) {
+    return { principal: user, scopes: ["read", "write"] };
   },
-  coerce?: {
-    body?: boolean,
-    query?: boolean,
-    path?: boolean,
-    header?: boolean,
-    cookie?: boolean,
-    dateTime?: boolean,
-    date?: boolean,
+  challenge(res: any) {
+    res.status(401).json({ error: "Unauthorized" });
   },
-  middleware?: {
-    global?: Middleware[],
-    named?: Record<string, Middleware>,
+  authorize(auth: any, requiredScopes: string[]) {
+    return requiredScopes.every(s => auth.scopes?.includes(s));
   },
-});
+};
 ```
 
-Date properties in TypeScript map to OpenAPI `type: "string"` with `format: "date-time"`. Enable `coerce` to convert ISO 8601 date-time strings into `Date` instances before your handler runs. For date-only strings, use `@Format("date")` and keep `date` coercion off to avoid timezone shifts. You can disable per-field coercion with `@Schema({ "x-adorn-coerce": false })`.
+## Validation
 
-### setupSwagger()
+Adorn-API supports two validation modes:
 
-Add Swagger UI to any Express app:
+### Runtime Validation (AJV)
 
 ```typescript
-import { setupSwagger } from "adorn-api/express";
-
-app.use(setupSwagger({
-  artifactsDir?: string,      // Default: ".adorn"
-  jsonPath?: string,          // Default: "/docs/openapi.json"
-  uiPath?: string,            // Default: "/docs"
-  swaggerOptions?: {
-    servers?: [{ url: string }],
-    // Other Swagger UI options
+await bootstrap({
+  controllers: [UserController],
+  validation: {
+    mode: "ajv-runtime",
   },
-}));
+});
 ```
 
-## Why Adorn-API?
+### Precompiled Validators
 
-| Feature | Adorn-API | tsoa | NestJS |
-|---------|-----------|------|--------|
-| Decorator-first | Yes | Yes | Yes |
-| OpenAPI 3.1 | Yes | Yes | Yes |
-| No transpilation | Yes | No | No |
-| Incremental builds | Yes | No | No |
-| Precompiled validators | Yes | No | No |
-| Stage-3 decorators | Yes | Stage 2 | Custom |
-| Learning curve | Low | Medium | High |
-| Framework agnostic | Yes | Partial | No |
-| Metal ORM integration | Yes | No | No |
+```typescript
+await bootstrap({
+  controllers: [UserController],
+  validation: {
+    mode: "precompiled",
+  },
+});
+```
 
-### What Makes Adorn-API Different
+Precompiled validators are generated at build time in `.adorn/validator.js` for better performance.
 
-**Stage-3 Decorators:** Uses the official TC39 decorators proposal (ES2024), not legacy TypeScript experimental decorators. This means no build-time transformer is required—your decorators compile directly to metadata that Adorn-API reads at runtime.
+## Testing
 
-**No Transpilation Needed:** Unlike tsoa, Adorn-API doesn't require a custom TypeScript transformer. Controllers are regular TypeScript classes that work with native decorators.
+Tests are written with Vitest and cover:
 
-**Incremental Builds:** The `--if-stale` flag intelligently determines when rebuilds are needed, caching TypeScript program states for fast iteration.
+- Compiler schema generation
+- Decorator metadata
+- Express integration
+- Middleware execution order
+- Authentication and authorization
+- Metal-ORM integration
 
-**Precompiled Validators:** Generate optimized validation modules at build time for production deployments where startup time matters.
+```bash
+npm test
+```
 
-**Framework Agnostic:** While Express is the primary adapter, the core is adapter-based and could support other frameworks in the future.
+### Test Structure
 
-## Metal ORM Integration
+```
+test/
+├── integration/        # Express integration tests
+├── compiler/          # Schema and manifest generation
+├── runtime/            # Decorator metadata
+├── middleware/         # Middleware ordering and auth
+├── metal/             # Metal-ORM integration
+└── fixtures/          # Test fixtures
+```
 
-Adorn-API can auto-generate OpenAPI schemas from Metal ORM entities:
+## Configuration
 
-```typescript
-import { Controller, Get } from "adorn-api";
-import { User } from "./entities/index.js";
-import { registerMetalEntities } from "adorn-api/metal";
+### TypeScript Config
 
-@Controller("/users")
-export class UsersController {
-  @Get("/")
-  async getUsers(): Promise<User[]> {
-    return session.find(User);
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true
   }
 }
-
-// Auto-generate schema from entity
-const openapi = { /* base openapi */ };
-registerMetalEntities(openapi, [User], { stripEntitySuffix: true });
 ```
 
-Options:
-- `mode`: `"read"` or `"create"` (excludes auto-generated columns)
-- `stripEntitySuffix`: Remove `_Entity` suffix from schema names
-
-## Project Structure
+### Vitest Config
 
+```typescript
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    include: ["test/**/*.test.ts"],
+    typecheck: {
+      enabled: true,
+      tsconfig: "./tsconfig.json",
+    },
+  },
+});
 ```
-my-api/
-├── src/
-│   ├── controller.ts      # Your controllers
-│   └── server.ts          # Entry point
-├── .adorn/                # Generated artifacts (gitignored)
-│   ├── openapi.json       # OpenAPI spec
-│   ├── manifest.json      # Route manifest
-│   └── cache.json         # Build cache
-├── tsconfig.json
-└── package.json
-```
+
+## How It Works
+
+1. **Compile**: The CLI analyzes your TypeScript controllers and extracts metadata using the compiler API
+2. **Generate**: OpenAPI schemas and runtime manifests are generated from type information
+3. **Bind**: At runtime, metadata is merged with controller instances to bind routes to Express
+4. **Validate**: Optional validation ensures requests match your TypeScript types
+5. **Document**: Swagger UI serves interactive documentation based on generated OpenAPI spec
 
 ## License