@xrystal/dto 26.6.27-v12 → 26.6.27-v13

package/README.md

@@ -1,333 +1,183 @@
 # @xrystal/dto
 
-Framework-agnostic **Data Transfer Object** library for **Express**, **Node/Bun HTTP**, **Elysia**, **WebSocket**, and **Socket.IO**.
+Framework-agnostic **Data Transfer Object** library for Node.js, Bun, and TypeScript — HTTP, WebSocket, and Socket.IO.
 
-Every runtime shares the same response builder, and the same modular DTO pipeline — response, log, and queue shapes with predictable JSON field order.
+One predictable JSON contract. Three clear entry points.
 
 ---
 
-## Why use it?
+## Getting started (5 minutes)
 
-- **One response schema** across HTTP and realtime transports
-- **Presets** for common cases (`.as.ok`, `.as.notFound`, …) — no boilerplate
-- **Manual chain** when you need headers, cookies, rate limits, or a full body object via `.schema()`
-- **Plugins** to audit, trace, or transform responses middleware-style
-- **Modular DTOs** — response (request-scoped), log and queue (static global builders)
-- **TypeScript-first** with strict field ordering in every JSON body
+### Install
 
----
-
-## Response schema
-
-Every response body follows this fixed field order:
-
-```json
-{
-  "status": true,
-  "message": "User fetched",
-  "payload": {
-    "data": { "id": 1 },
-    "meta": { "requestId": "abc-123" }
-  },
-  "code": 0
-}
+```bash
+npm install @xrystal/dto
+# optional peers
+npm install express elysia
 ```
 
-| Field | Type | Required in JSON | Meaning |
-|-------|------|------------------|---------|
-| `status` | `boolean` | always | Business outcome — `true` success, `false` failure. Independent from HTTP status. |
-| `message` | `string` | always | Human-readable summary for clients and logs. |
-| `payload` | `object` | optional | Wrapper for extra data. Omitted when empty. |
-| `payload.data` | `any` | optional | Primary result — set via `.data()` or preset first argument. |
-| `payload.meta` | `object` | optional | Tracing, pagination context, etc. |
-| `code` | `number` | always | App-level code. Defaults: `0` SUCCESS, `1` CLIENT, `2` SERVER, `3` VALIDATION. Override or extend via `DTO` config. |
-
-Transport layer (HTTP status, headers, cookies) is **separate** from the body schema.
-
----
-
-## Mental model
+### Three concepts
 
-Everything hangs off one root: **`DTO`**.
+| # | What | When |
+|---|------|------|
+| 1 | **`new DTO()`** | App setup — middleware, plugins, custom codes |
+| 2 | **`res.builder`** / **`ctx.builder`** | Inside a handler — send API response to client |
+| 3 | **`DTO.Response` / `DTO.Log` / `DTO.Queue`** | No request context — cron, logger, queue, tests |
 
-| Layer | Entry | Scope | Use for |
-|-------|--------|-------|---------|
-| Runtime | `new DTO()` | App-wide config | Middleware, plugins, codes, socket event |
-| Response body | `DTO.Response` or `res.builder.dto` | Static or per-request | JSON body shape only |
-| Response dispatch | `res.builder` / `ctx.builder` | Per request | Body + HTTP status + headers + plugins |
-| Log | `DTO.Log` / `LogDTO` | Static | Structured logs |
-| Queue | `DTO.Queue` / `QueueDTO` | Static | Message bus payloads |
+**Rule of thumb:** client cevabı → `builder`. Düz JSON üretmek → static `DTO.*`.
 
-All shape DTOs extend the same rules:
-
-- Fluent chain in **fixed field order**
-- `.schema()` for partial input — **last call wins**
-- `payload` in `.schema()` **replaces** the entire payload (no merge)
-
-`Builder` is transport on top of `ResponseDTO` — same split as HTTP status vs JSON body.
-
----
-
-## When to use what
-
-This is the most important distinction in the library.
-
-### You **have** a request (Express, Node, Elysia, WebSocket, Socket.IO)
-
-Middleware from `new DTO()` attaches **`builder`** to the request/socket. Use that in handlers — it has context, dispatch, HTTP status, headers, and plugins.
+### 1. Wire the runtime (once)
 
 ```typescript
-// Express / Node — res.builder
-app.get('/users/:id', (req, res) => {
-  return res.builder.as.ok({ id: req.params.id }, 'User fetched', {
-    meta: { requestId: req.ctx.requestId },
-  })
-})
-
-// Elysia — ctx.builder (same idea, flat context)
-.get('/users/:id', ({ builder, requestId, params }) =>
-  builder.as.ok({ id: params.id }, 'User fetched', { meta: { requestId } }),
-)
-
-// Manual chain when you need HTTP + body control
-return res.builder
-  .httpStatus(429)
-  .header('Retry-After', '60')
-  .schema({ status: false, message: 'Slow down', code: 4 })
-  .build()
-```
-
-`DTO.Response` is **not** used here directly — `res.builder` already owns an internal `ResponseDTO`. You can inspect or reuse it:
+import express from 'express'
+import { DTO } from '@xrystal/dto'
 
-```typescript
-const bodyOnly = res.builder.dto.build() // same JSON shape, no dispatch yet
+const runtime = new DTO({ withDefaultHeaders: true })
+const app = express()
+app.use(runtime.express())
 ```
 
-### You **do not** have a request (cron, worker, unit test, logger, queue publisher)
+This attaches `req.ctx` and `res.builder` on every request.
 
-No `req`, no `res`, no `ctx` — nothing to attach a builder to. Use **static shape DTOs**:
+### 2. Respond in a handler
 
 ```typescript
-// Log line for your logger transport
-const logLine = DTO.Log.level('info')
-  .service('billing-cron')
-  .env(NodeEnvEnum.PROD)
-  .message('Invoices synced')
-  .build()
-logger.info(logLine)
-
-// Rabbit / SQS / Bull payload
-const message = DTO.Queue.source('billing-cron')
-  .eventType('invoice.synced')
-  .payload({ count: 42 })
-  .build()
-await queue.publish(message)
-
-// Plain response JSON (e.g. cache, test fixture, RPC payload without HTTP)
-const rpcBody = DTO.Response.status(true)
-  .message('Computed')
-  .data({ total: 100 })
-  .build()
+app.get('/users/:id', (req, res) => {
+  return res.builder.as.ok(
+    { id: req.params.id },
+    'User fetched',
+    { meta: { requestId: req.ctx.requestId } },
+  )
+})
 ```
 
-### Summary
-
-| Situation | Use | Returns |
-|-----------|-----|---------|
-| HTTP handler (Express/Node/Elysia) | `res.builder` / `ctx.builder` | Dispatches response to client |
-| WebSocket / Socket.IO handler | `ws.builder` / `socket.builder` | Sends JSON on wire |
-| Cron, worker, logger, queue | `DTO.Log`, `DTO.Queue`, `DTO.Response` | Plain object — you send/write it |
-| Need body JSON only inside a handler | `res.builder.dto` | `ResponseBody` object |
+Sent JSON (fixed order: `status → message → payload? → code`):
 
----
-
-## Response DTO
-
-Body only (`status → message → payload? → code`). No HTTP status here.
-
-```typescript
-import { DTO } from '@xrystal/dto'
-
-DTO.Response.status(true)
-  .message('User fetched')
-  .data({ id: 1 })
-  .build()
-
-// Partial object — same .schema() rules as the builder chain
-DTO.Response.schema({
-  status: false,
-  message: 'Not found',
-  code: 1,
-  payload: { data: { reason: 'missing' } },
-}).build()
+```json
+{
+  "status": true,
+  "message": "User fetched",
+  "payload": { "data": { "id": "42" }, "meta": { "requestId": "…" } },
+  "code": 0
+}
 ```
 
-In a handler, `res.builder` delegates body fields to an internal `ResponseDTO`. Access it via `res.builder.dto` when you only need the shape.
+Presets (`.as.ok`, `.as.notFound`, …) dispatch automatically — **no `.build()`**.
 
----
-
-## Log DTO
-
-Fixed field order: `level → service → message? → payload? → code? → timestamp → id? → env`
-
-**Required at build:** `level`, `service`, `env`.
+### 3. Static shape DTOs (no request)
 
 ```typescript
 import { DTO, NodeEnvEnum } from '@xrystal/dto'
 
+// Log line
 DTO.Log.level('info')
-  .service('users-api')
+  .service('api')
   .env(NodeEnvEnum.PROD)
-  .message('User fetched')
-  .payload({ userId: 1 })
+  .message('Server ready')
   .build()
 
-// One-shot via .schema()
-DTO.Log.schema({
-  level: 'error',
-  service: 'auth',
-  env: NodeEnvEnum.DEV,
-  message: 'Login failed',
-  code: 'AUTH_FAIL',
-}).build()
-```
-
----
-
-## Queue DTO
-
-Shape: `{ metadata, payload }` — metadata order `source → eventType → timestamp → correlationId → userId? → extraData?`
-
-**Required at build:** `source`, `eventType`.
-
-```typescript
-import { DTO } from '@xrystal/dto'
-
-DTO.Queue.source('users-api')
+// Queue message
+DTO.Queue.source('api')
   .eventType('user.created')
-  .userId('u-1')
   .payload({ id: 1 })
   .build()
 
-DTO.Queue.schema({
-  metadata: { source: 'billing', eventType: 'invoice.paid' },
-  payload: { invoiceId: 9 },
-}).build()
+// Response JSON only (no HTTP)
+DTO.Response.status(true).message('OK').data({ id: 1 }).build()
 ```
 
----
+Every shape DTO shares the same chain rules:
 
-## Install
+- Fixed field order
+- `.schema({ … })` for partial input — **last call wins**
+- `payload` in `.schema()` **replaces** the entire payload
 
-```bash
-npm install @xrystal/dto
-```
+### Elysia — same idea
 
-Peer dependencies (install only what you use):
+```typescript
+import { Elysia } from 'elysia'
+import { DTO } from '@xrystal/dto'
 
-```bash
-npm install express          # Express adapter
-npm install elysia           # Elysia adapter
+const runtime = new DTO()
+new Elysia()
+  .use(runtime.elysia())
+  .get('/users/:id', ({ builder, requestId, params }) =>
+    builder.as.ok({ id: params.id }, 'User fetched', { meta: { requestId } }),
+  )
 ```
 
-Subpath imports are available if you want a smaller surface:
+### When to use what
 
-```typescript
-import { DTO, LogDTO, ResponseDTO, QueueDTO, Builder } from '@xrystal/dto'
-import { DTO } from '@xrystal/dto/dto'           // runtime only
-import { ResponseDTO } from '@xrystal/dto/response'
-import { LogDTO } from '@xrystal/dto/log'
-import { QueueDTO } from '@xrystal/dto/queue'
-import { expressMiddleware } from '@xrystal/dto/express'
-```
+| Situation | Use |
+|-----------|-----|
+| Express / Node / Elysia handler | `res.builder` / `ctx.builder` |
+| WebSocket / Socket.IO | `ws.builder` / `socket.builder` |
+| Cron, worker, logger, queue publish | `DTO.Log`, `DTO.Queue`, `DTO.Response` |
+| Custom HTTP status + headers | `res.builder.httpStatus(429).header(...).schema({...}).build()` |
+
+Plugins and custom `codes` on `new DTO({ … })` apply **only to `builder`** — not to static `DTO.Log` / `DTO.Queue`.
 
 ---
 
-## Quick start (Express)
+## Architecture
 
-```typescript
-import express from 'express'
-import { DTO } from '@xrystal/dto'
+Symmetric modules under `src/dto/`:
 
-const app = express()
-app.use(new DTO().express())
-
-app.get('/users/:id', (req, res) => {
-  return res.builder.as.ok({ id: req.params.id }, 'User fetched')
-})
 ```
-
-Response sent to the client:
-
-```json
-{
-  "status": true,
-  "message": "User fetched",
-  "payload": { "data": { "id": "42" } },
-  "code": 0
-}
+dto/
+├── runtime/           ← new DTO(), middleware, ContextFactory, Hooks
+│   ├── dto.ts
+│   ├── context.ts
+│   ├── metadata.ts
+│   └── hooks.ts
+├── response/          ← ResponseDTO, Builder, presets, plugins
+├── log/
+├── queue/
+└── shared/
+    ├── base-dto.ts
+    └── schema-utils.ts
 ```
 
-Middleware attaches:
+### Package exports
 
-- `req.ctx` — `{ requestId, startTime }`
-- `res.builder` — fluent response builder
+| Import | Contents |
+|--------|----------|
+| `@xrystal/dto` | Everything |
+| `@xrystal/dto/dto` | `DTO`, `createDTO`, runtime helpers |
+| `@xrystal/dto/response` | `ResponseDTO`, `Builder`, presets |
+| `@xrystal/dto/log` | `LogDTO` |
+| `@xrystal/dto/queue` | `QueueDTO` |
+| `@xrystal/dto/express` | Express middleware |
 
 ---
 
-## Two ways to respond
-
-### 1. Presets (recommended for most handlers)
-
-Call `.as.*` — dispatches automatically. **Do not call `.build()`.**
+## Response schema
 
-```typescript
-// Success
-return res.builder.as.ok({ id: 1 }, 'User fetched')
-
-// With payload extras (meta, pagination fields, …)
-return res.builder.as.ok(
-  { id: 1 },
-  'User fetched',
-  { meta: { requestId: req.ctx.requestId } },
-)
-
-// Generic failures
-return res.builder.as.fail('Could not fetch users')
-return res.builder.as.fail({ reason: 'invalid_query' }, 'Could not fetch users')
-return res.builder.as.error({ ref: 'db-01' }, 'Something went wrong')
-
-// Exact HTTP status
-return res.builder.as.notFound('User not found')
-return res.builder.as.unauthorized('Token expired')
-return res.builder.as.tooManyRequests('Slow down')
-```
+| Field | Meaning |
+|-------|---------|
+| `status` | Business success/failure (`boolean`) — independent from HTTP status |
+| `message` | Human-readable summary |
+| `payload` | Optional wrapper (`data`, `meta`, pagination, …) |
+| `code` | App code — default `0` SUCCESS, `1` CLIENT, `2` SERVER, `3` VALIDATION |
 
-**Preset argument shape**
+Transport (HTTP status, headers, cookies) lives on **`builder`**, not on `DTO.Response`.
 
-| Pattern | Example |
-|---------|---------|
-| Message only | `.fail('Not found')` |
-| Message + extras | `.fail('Rate limited', { meta: { retryAfter: 60 } })` |
-| Data + message + extras | `.ok(data, 'Done', { meta: { … } })` — same as `.fail()` / `.error()` |
+---
 
-### 2. Manual chain (headers, cookies, custom cases)
+## Handler API
 
-Use when you need transport control or a schema-shaped body. Always end with `.build()`.
+### Presets (recommended)
 
 ```typescript
-return res.builder
-  .httpStatus(429)
-  .header('Retry-After', '60')
-  .status(false)
-  .code(4)
-  .message('Slow down')
-  .data({ retryAfter: 60 })
-  .payload({ meta: { requestId: req.ctx.requestId } })
-  .build()
+res.builder.as.ok(data, 'Done')
+res.builder.as.fail('Not found')
+res.builder.as.notFound('User missing')
+res.builder.as.tooManyRequests('Slow down')
 ```
 
-Or apply the body in one step with `.schema()`:
+### Manual chain
+
+End with `.build()` when you need headers, cookies, or fine control:
 
 ```typescript
 return res.builder
@@ -337,324 +187,109 @@ return res.builder
     status: false,
     message: 'Slow down',
     code: 4,
-    payload: {
-      data: { retryAfter: 60 },
-      meta: { requestId: req.ctx.requestId },
-    },
+    payload: { data: { retryAfter: 60 } },
   })
   .build()
 ```
 
-**Chain rules**
-
-| Rule | Detail |
-|------|--------|
-| Last call wins | `.schema()` overrides earlier `.status()` / `.code()` / `.data()`; a later `.status()` overrides `.schema()` too. |
-| `.schema()` body only | Put `meta`, `data`, etc. inside `payload`. Put `httpStatus`, headers, cookies on the chain. |
-| `payload` in `.schema()` | Replaces the entire payload — no merge with earlier chain calls. |
-| Required body fields | `status`, `message`, and `code` are always emitted. Defaults fill omissions at `.build()` time. |
-| `.data()` vs `.payload()` | Separate methods — `.data(x)` sets `payload.data` only; `.payload({ meta })` sets other payload fields. |
-
-| Method | Purpose |
-|--------|---------|
-| `.httpStatus(200)` | HTTP status code |
-| `.schema({ … })` | Apply partial response body |
-| `.status(true)` | Body `status` field |
-| `.code(0)` | Body `code` field |
-| `.message('…')` | Body `message` |
-| `.data(x)` | Sets `payload.data` |
-| `.payload({ meta })` | Other payload fields |
-| `.header()` / `.setCookies()` | Response headers and cookies |
-| `.build()` | Assemble and dispatch |
+| Chain rule | Detail |
+|------------|--------|
+| Last call wins | Later `.schema()` or `.status()` overrides earlier values |
+| `.schema()` is body-only | HTTP status and headers stay on the chain |
+| `payload` in `.schema()` | Replaces entire payload — no merge |
 
 ---
 
-## DTO setup
+## Shape DTOs
 
-Single entry point: **`DTO`**. Instance = runtime (middleware). Static namespaces = shape DTOs (`DTO.Response`, `DTO.Log`, `DTO.Queue`).
+### Response (`DTO.Response`)
 
-```typescript
-import { DTO, definePlugin } from '@xrystal/dto'
-
-const requestIdPlugin = definePlugin({
-  name: 'request-id',
-  priority: -10,
-  afterBuild(result, ctx) {
-    return {
-      ...result,
-      headers: { ...result.headers, 'X-Request-Id': ctx.context?.requestId ?? '' },
-    }
-  },
-})
-
-const dto = new DTO({
-  withDefaultHeaders: true,
-  codes: { RATE_LIMITED: 4 },
-  plugins: [requestIdPlugin],
-  socket: { event: 'api:response' },
-}).use(auditPlugin) // immutable — returns a new DTO
-
-app.use(dto.express())
-io.use(dto.socketIo())
-```
-
-Default codes (always merged; override only what you need):
-
-| Key | Default | Typical use |
-|-----|---------|-------------|
-| `SUCCESS` | `0` | Happy path |
-| `CLIENT` | `1` | Bad input, auth, not found, … |
-| `SERVER` | `2` | Internal errors |
-| `VALIDATION` | `3` | Schema / field validation |
-
----
-
-## Core presets
-
-| Method | HTTP | Code | Purpose |
-|--------|------|------|---------|
-| `.ok(data?, message?, extras?)` | 200 | SUCCESS | Success |
-| `.fail(data?, message?, extras?)` | 400 | CLIENT | Generic client failure |
-| `.error(data?, message?, extras?)` | 500 | SERVER | Generic server failure |
-| `.created(data?, message?, extras?)` | 201 | SUCCESS | Resource created |
-| `.accepted(message?, extras?)` | 202 | SUCCESS | Accepted |
-| `.noContent(extras?)` | 204 | SUCCESS | No body |
-
----
-
-## HTTP-specific presets
-
-Use when you need an exact HTTP status. Core `.fail()` / `.error()` cover most cases.
-
-### Client (4xx)
-
-| Method | HTTP | Code |
-|--------|------|------|
-| `.badRequest(…)` | 400 | CLIENT |
-| `.unauthorized(…)` | 401 | CLIENT |
-| `.forbidden(…)` | 403 | CLIENT |
-| `.notFound(…)` | 404 | CLIENT |
-| `.conflict(…)` | 409 | CLIENT |
-| `.unprocessable(…)` | 422 | VALIDATION |
-| `.tooManyRequests(…)` | 429 | CLIENT |
-
-### Server (5xx)
-
-| Method | HTTP | Code |
-|--------|------|------|
-| `.internalServerError(…)` | 500 | SERVER |
-| `.serviceUnavailable(…)` | 503 | SERVER |
-| `.gatewayTimeout(…)` | 504 | SERVER |
-
-All HTTP presets share the same argument shape as `.ok()` / `.fail()`.
-
----
-
-## Plugins
-
-Middleware-style pipeline. Lower `priority` runs first (default `0`).
-
-| Hook | When | Use for |
-|------|------|---------|
-| `beforeBuild` | Before body assembly | Mutate builder state |
-| `afterBuild` | After `FinalResult` is ready | Transform body, headers, cookies |
-| `beforeDispatch` | Same stage as `afterBuild` | Alias hook for dispatch pipeline |
-| `afterDispatch` | After response is sent | Logging, metrics, audit |
+Body only — `status → message → payload? → code`.
 
 ```typescript
-import { definePlugin } from '@xrystal/dto'
-
-export const auditPlugin = definePlugin({
-  name: 'audit',
-  priority: 0,
-  afterDispatch(result, ctx) {
-    console.log(ctx.context?.requestId, result.statusCode, result.body.code)
-  },
-})
+DTO.Response.status(true).message('OK').data({ id: 1 }).build()
 
-new DTO({ plugins: [auditPlugin] })
-new DTO().use(auditPlugin, otherPlugin)
-```
-
----
-
-## Runtime guides
-
-### Express
-
-```typescript
-import express from 'express'
-import { DTO } from '@xrystal/dto'
-
-const app = express()
-app.use(new DTO().express())
-
-app.get('/users/:id', (req, res) => {
-  return res.builder.as.ok({ id: req.params.id }, 'User fetched')
-})
+DTO.Response.schema({
+  status: false,
+  message: 'Not found',
+  code: 1,
+}).build()
 ```
 
-### Node HTTP
+Inside a handler, `res.builder.dto` exposes the same `ResponseDTO` instance.
 
-```typescript
-import { createServer } from 'node:http'
-import { DTO } from '@xrystal/dto'
+### Log (`DTO.Log`)
 
-const dto = new DTO()
+Order: `level → service → message? → payload? → code? → timestamp → id? → env`
 
-createServer((req, res) => {
-  dto.node()(req, res, () => {
-    if (req.url === '/health') return res.builder?.as.ok({ ok: true }, 'Up')
-    return res.builder?.as.fail('Not found')
-  })
-}).listen(3000)
-```
-
-### Bun HTTP
-
-Bun uses the Node adapter via `node:http` — same API:
+Required: `level`, `service`, `env`.
 
 ```typescript
-import { createServer } from 'node:http'
-import { DTO } from '@xrystal/dto'
-
-const dto = new DTO()
-
-createServer((req, res) => {
-  dto.node()(req, res, () => {
-    if (req.url === '/health') return res.builder?.as.ok({ ok: true }, 'Up')
-
-    return res.builder
-      ?.code(4)
-      .httpStatus(429)
-      .status(false)
-      .message('Too many requests')
-      .build()
-  })
-}).listen(3000)
+DTO.Log.level('info')
+  .service('users-api')
+  .env(NodeEnvEnum.PROD)
+  .message('User fetched')
+  .build()
 ```
 
-`req.ctx` holds `requestId`; `res.builder` is attached by middleware (use `?.` until the handler runs).
+### Queue (`DTO.Queue`)
 
-### Elysia
+Order: `source → eventType → timestamp → correlationId → userId? → extraData?`
 
-The handler argument **is** the context. The plugin adds `builder`, `requestId`, and `startTime` via scoped `derive`:
+Required: `source`, `eventType`. Timestamp and correlationId auto-generate.
 
 ```typescript
-import { Elysia } from 'elysia'
-import { DTO } from '@xrystal/dto'
-
-const dto = new DTO()
-
-new Elysia()
-  .use(dto.elysia())
-  .get('/health', ({ builder, requestId }) =>
-    builder.as.ok({ healthy: true }, 'OK', { meta: { requestId } }),
-  )
-  .get('/users/:id', ({ builder, requestId, params }) =>
-    builder.as.ok({ id: params.id }, 'User fetched', { meta: { requestId } }),
-  )
+DTO.Queue.source('billing')
+  .eventType('invoice.paid')
+  .payload({ invoiceId: 9 })
+  .build()
 ```
 
-Outside a request (e.g. startup log):
-
-```typescript
-console.log(
-  DTO.Log.level('info')
-    .service('api')
-    .env(NodeEnvEnum.PROD)
-    .message('Server listening')
-    .build(),
-)
-```
+---
 
-### WebSocket
+## Runtime config
 
 ```typescript
-import { DTO } from '@xrystal/dto'
+import { DTO, definePlugin } from '@xrystal/dto'
 
-const dto = new DTO()
-
-Bun.serve({
-  websocket: {
-    open(ws) {
-      dto.attachWebSocket(ws)
-      ws.builder?.as.ok({ connected: true }, 'Ready')
-    },
-    message(ws, raw) {
-      ws.builder?.as.ok({ echo: raw.toString() }, 'Echo')
-    },
+const audit = definePlugin({
+  name: 'audit',
+  afterDispatch(result, ctx) {
+    console.log(ctx.context?.requestId, result.statusCode)
   },
 })
-```
-
-### Socket.IO
-
-```typescript
-dto.attachSocketIo(socket)
-socket.builder?.as.ok({ room: 'lobby' }, 'Connected')
-
-io.use(dto.socketIo())
-socket.builder?.as.ok({ socketId: socket.id }, 'Connected')
-```
-
-WebSocket and Socket.IO have no HTTP status — use presets or `.build()`. JSON is sent via `ws.send` / `socket.emit`.
-
----
-
-## Full-stack example
-
-```typescript
-import express from 'express'
-import { DTO, NodeEnvEnum } from '@xrystal/dto'
 
 const runtime = new DTO({
   withDefaultHeaders: true,
   codes: { RATE_LIMITED: 4 },
-})
+  plugins: [audit],
+  socket: { event: 'api:response' },
+}).use(otherPlugin) // immutable — returns new DTO
 
-const app = express()
 app.use(runtime.express())
-
-app.get('/users/:id', async (req, res) => {
-  try {
-    const user = await db.findUser(req.params.id)
-    if (!user) return res.builder.as.notFound('User not found')
-
-    // Side-effect: structured log (no req/res needed for shape)
-    console.log(
-      DTO.Log.level('info')
-        .service('users-api')
-        .env(NodeEnvEnum.PROD)
-        .message('User fetched')
-        .payload({ userId: user.id })
-        .build(),
-    )
-
-    return res.builder.as.ok(user, 'User fetched', {
-      meta: { requestId: req.ctx.requestId },
-    })
-  } catch (err) {
-    return res.builder.fromError(err).build()
-  }
-})
-
-// Cron job — no builder, static DTOs only
-setInterval(() => {
-  const event = DTO.Queue.source('users-api')
-    .eventType('users.active.count')
-    .payload({ count: db.activeCount() })
-    .build()
-
-  queue.publish(event)
-}, 60_000)
+io.use(runtime.socketIo())
 ```
 
+| Option | Affects |
+|--------|---------|
+| `plugins` | `builder` pipeline only |
+| `codes` | `builder` presets and `.code()` |
+| `withDefaultHeaders` | HTTP middleware |
+| `socket.event` | WebSocket / Socket.IO emit name |
+
 ---
 
-## Errors
+## Runtimes
 
-Map thrown errors to the standard body:
+```typescript
+runtime.express()
+runtime.node()
+runtime.elysia()
+runtime.websocket() / runtime.attachWebSocket(ws)
+runtime.socketIo() / runtime.attachSocketIo(socket)
+```
+
+### Errors in handlers
 
 ```typescript
 try {
@@ -665,60 +300,66 @@ try {
 }
 ```
 
-Built-in error types: `ClientError`, `ServerError`, `ValidationError`. Unknown errors are masked when `verbose: false`.
+Built-in: `ClientError`, `ServerError`, `ValidationError`.
 
 ---
 
-## Custom codes & HTTP status
+## Full-stack sketch
 
 ```typescript
-const dto = new DTO({ codes: { RATE_LIMITED: 4 } })
+import express from 'express'
+import { DTO, NodeEnvEnum } from '@xrystal/dto'
 
-return res.builder
-  .code(4)
-  .httpStatus(429)
-  .status(false)
-  .message('Too many requests')
-  .build()
+const runtime = new DTO({ withDefaultHeaders: true })
+const app = express()
+app.use(runtime.express())
 
-// Or when HTTP maps cleanly:
-return res.builder.as.tooManyRequests('Too many requests')
+app.get('/users/:id', async (req, res) => {
+  const user = await db.findUser(req.params.id)
+  if (!user) return res.builder.as.notFound('User not found')
+
+  console.log(
+    DTO.Log.level('info')
+      .service('users-api')
+      .env(NodeEnvEnum.PROD)
+      .payload({ userId: user.id })
+      .build(),
+  )
+
+  return res.builder.as.ok(user, 'User fetched', {
+    meta: { requestId: req.ctx.requestId },
+  })
+})
 ```
 
 ---
 
-## Release (maintainers)
-
-**Source of truth:** `package.json` `"version"`. Git tag must be **identical** — no env override.
+## HTTP presets reference
 
-Format: `YY.MM.DD-vN` (e.g. `26.06.27-v8`).
-
-### Quick tag (commit already done)
+| Preset | HTTP | Code |
+|--------|------|------|
+| `.ok()` | 200 | SUCCESS |
+| `.created()` | 201 | SUCCESS |
+| `.fail()` | 400 | CLIENT |
+| `.notFound()` | 404 | CLIENT |
+| `.unprocessable()` | 422 | VALIDATION |
+| `.tooManyRequests()` | 429 | CLIENT |
+| `.error()` | 500 | SERVER |
 
-Bump `package.json`, commit, then:
+See source `dto/response/presets.ts` for the full list.
 
-```bash
-npm run tag
-```
+---
 
-Reads version from **committed** `package.json`, tags **current commit**, pushes branch + tag → Publish workflow runs.
+## Release (maintainers)
 
-### Full release (lint + test + build + commit + tag)
+Version lives in `package.json` (`YY.MM.DD-vN`). Git tag must match exactly.
 
 ```bash
-# 1. Bump version in package.json
-# 2. Run everything:
-npm run release
+npm run release   # lint → test → build → commit → tag → push
+npm run tag       # tag only (after manual commit)
+npm run version:check
 ```
 
-| Command | What it does |
-|---------|----------------|
-| `npm run version:check` | Warns if HEAD tag ≠ package.json |
-| `npm run tag` | Tag HEAD from package.json → push branch + tag |
-| `npm run release` | lint → test → build → commit → `npm run tag` |
-
-GitHub Publish verifies `tag === package.json version` before npm publish.
-
 ---
 
 MIT