@xrystal/dto 26.6.27-v12 → 26.6.27-v14

package/README.md

@@ -1,724 +1,600 @@
 # @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
-
-Everything hangs off one root: **`DTO`**.
-
-| 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 |
+### Three concepts
 
-All shape DTOs extend the same rules:
+| # | 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 |
 
-- Fluent chain in **fixed field order**
-- `.schema()` for partial input — **last call wins**
-- `payload` in `.schema()` **replaces** the entire payload (no merge)
+**Rule of thumb:** client cevabı → `builder`. Düz JSON üretmek → static `DTO.*`.
 
-`Builder` is transport on top of `ResponseDTO` — same split as HTTP status vs JSON body.
+### 1. Wire the runtime (once)
 
----
+```typescript
+import express from 'express'
+import { DTO } from '@xrystal/dto'
 
-## When to use what
+const runtime = new DTO({ withDefaultHeaders: true })
+const app = express()
+app.use(runtime.express())
+```
 
-This is the most important distinction in the library.
+This attaches `req.ctx` and `res.builder` on every request.
 
-### You **have** a request (Express, Node, Elysia, WebSocket, Socket.IO)
+### 2. Respond in a handler
 
-Middleware from `new DTO()` attaches **`builder`** to the request/socket. Use that in handlers — it has context, dispatch, HTTP status, headers, and plugins.
+Every chain ends with a **verb** — `.send()` (go to client) or `.build()` (schema only):
 
 ```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 },
-  })
+  return res.builder.as.ok(
+    { id: req.params.id },
+    'User fetched',
+    { meta: { requestId: req.ctx.requestId } },
+  ).send()
 })
-
-// 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:
+Sent JSON (fixed order: `status → message → payload? → code`):
 
-```typescript
-const bodyOnly = res.builder.dto.build() // same JSON shape, no dispatch yet
+```json
+{
+  "status": true,
+  "message": "User fetched",
+  "payload": { "data": { "id": "42" }, "meta": { "requestId": "…" } },
+  "code": 0
+}
 ```
 
-### You **do not** have a request (cron, worker, unit test, logger, queue publisher)
+| Verb | What it does |
+|------|----------------|
+| `.send()` | Assembles + **pushes** via send sink (HTTP write, WebSocket emit, …) |
+| `.build()` | Assembles **schema only** — no network side-effect |
+
+Presets (`.as.ok`, `.as.notFound`, …) configure the body and return a terminal — you still call `.send()` or `.build()`.
 
-No `req`, no `res`, no `ctx` — nothing to attach a builder to. Use **static shape DTOs**:
+### 3. Static shape DTOs (no request)
 
 ```typescript
-// Log line for your logger transport
-const logLine = DTO.Log.level('info')
-  .service('billing-cron')
+import { DTO, NodeEnvEnum } from '@xrystal/dto'
+
+// Log line
+DTO.Log.level('info')
+  .service('api')
   .env(NodeEnvEnum.PROD)
-  .message('Invoices synced')
+  .message('Server ready')
   .build()
-logger.info(logLine)
 
-// Rabbit / SQS / Bull payload
-const message = DTO.Queue.source('billing-cron')
-  .eventType('invoice.synced')
-  .payload({ count: 42 })
+// Queue message
+DTO.Queue.source('api')
+  .eventType('user.created')
+  .payload({ id: 1 })
   .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()
+// Response JSON only (no HTTP)
+DTO.Response.status(true).message('OK').data({ id: 1 }).build()
 ```
 
-### Summary
+Every shape DTO shares the same chain rules:
 
-| 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 |
+- Fixed field order
+- `.schema({ … })` for partial input — **last call wins**
+- `payload` in `.schema()` **replaces** the entire payload
 
----
+### Elysia — same idea
 
-## Response DTO
+```typescript
+import { Elysia } from 'elysia'
+import { DTO } from '@xrystal/dto'
+
+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 } }).send(),
+  )
+```
 
-Body only (`status → message → payload? → code`). No HTTP status here.
+### Fetch API — Workers, Hono, Bun.serve
 
 ```typescript
 import { DTO } from '@xrystal/dto'
 
-DTO.Response.status(true)
-  .message('User fetched')
-  .data({ id: 1 })
-  .build()
+const runtime = new DTO({ withDefaultHeaders: true })
 
-// Partial object — same .schema() rules as the builder chain
-DTO.Response.schema({
-  status: false,
-  message: 'Not found',
-  code: 1,
-  payload: { data: { reason: 'missing' } },
-}).build()
+export async function GET(request: Request) {
+  const { builder, requestId } = runtime.forRequest(request)
+  return builder.as.ok({ ok: true }, 'Healthy', { meta: { requestId } }).send()
+  // → Web Response
+}
 ```
 
-In a handler, `res.builder` delegates body fields to an internal `ResponseDTO`. Access it via `res.builder.dto` when you only need the shape.
+### When to use what
 
----
+| Situation | Use |
+|-----------|-----|
+| Express / Node / Elysia / Fetch handler | `builder…send()` |
+| WebSocket / Socket.IO | `socket.builder…send()` |
+| Schema only (log, queue, test, transform) | `builder…build()` or `DTO.*.build()` |
+| Cron, worker, logger, queue publish | `DTO.Log`, `DTO.Queue`, `DTO.Response` |
+| Custom HTTP status + headers | `builder.httpStatus(429).header(...).schema({...}).send()` |
 
-## Log DTO
+Plugins and custom `codes` on `new DTO({ … })` apply **only to `builder`** — not to static `DTO.Log` / `DTO.Queue`.
 
-Fixed field order: `level → service → message? → payload? → code? → timestamp → id? → env`
+---
 
-**Required at build:** `level`, `service`, `env`.
+## Adapters & send sinks
 
-```typescript
-import { DTO, NodeEnvEnum } from '@xrystal/dto'
+Each runtime has an **adapter** (wires `builder` per request) and a **send sink** (writes `FinalResult` to the transport on `.send()`).
 
-DTO.Log.level('info')
-  .service('users-api')
-  .env(NodeEnvEnum.PROD)
-  .message('User fetched')
-  .payload({ userId: 1 })
-  .build()
+| Piece | Role |
+|-------|------|
+| **Adapter** | Framework middleware / derive — creates `requestId`, attaches `builder`, applies default headers |
+| **Send sink** | `{ dispatch(result) }` object — one line per runtime, delegates to `send/transport.ts` |
 
-// One-shot via .schema()
-DTO.Log.schema({
-  level: 'error',
-  service: 'auth',
-  env: NodeEnvEnum.DEV,
-  message: 'Login failed',
-  code: 'AUTH_FAIL',
-}).build()
+```
+Handler chain          Core                         Transport
+─────────────         ─────                         ─────────
+builder.as.ok()  →   .build()  →  FinalResult
+                 →   .send()   →  dispatchResult()  →  sink.dispatch()
+                                                    →  send/transport.ts
+                                                    →  res.json / Response / ws.send / …
 ```
 
----
+Core dispatch lives in `dto/send/transport.ts`. Adapters pass a sink into `createBuilderRuntime()` — no separate dispatcher classes needed for normal use. `ExpressDispatcher` and friends remain as deprecated aliases for custom wiring.
 
-## Queue DTO
+### Runtime map
 
-Shape: `{ metadata, payload }` — metadata order `source → eventType → timestamp → correlationId → userId? → extraData?`
+| Runtime | Adapter | Sink | Attaches | `.send()` output |
+|---------|---------|------|----------|------------------|
+| **Express** | `ExpressAdapter` | `expressSink(res)` | `req.ctx`, `res.builder` | writes `res.status().json()` |
+| **Node http** | `NodeAdapter` | `nodeSink(res)` | `req.ctx`, `res.builder` | writes `res.end(JSON)` + Set-Cookie |
+| **Fetch API** | `FetchAdapter` | `fetchSink` | `builder`, `requestId` per `Request` | returns `Response` |
+| **Elysia** | `ElysiaAdapter` | `elysiaSink(set)` | `builder`, `requestId`, `startTime` on ctx | mutates `set`, returns body |
+| **WebSocket** | `WebSocketAdapter` | `websocketSink(socket)` | `socket.ctx`, `socket.builder` | `socket.send(wire envelope JSON)` |
+| **Socket.IO** | `SocketIoAdapter` | `socketIoSink(socket, event)` | `socket.ctx`, `socket.builder` | `socket.emit(event, wire envelope)` |
 
-**Required at build:** `source`, `eventType`.
+WebSocket and Socket.IO send the full transport envelope (`statusCode`, `headers`, `cookies`, `body`) so `.httpStatus()` and `.header()` are not lost on realtime transports.
+
+### `new DTO()` shortcuts
 
 ```typescript
-import { DTO } from '@xrystal/dto'
+const runtime = new DTO({ withDefaultHeaders: true, socket: { event: 'api:response' } })
 
-DTO.Queue.source('users-api')
-  .eventType('user.created')
-  .userId('u-1')
-  .payload({ id: 1 })
-  .build()
+runtime.express()              // → Express middleware
+runtime.node()                 // → Node http middleware
+runtime.elysia()               // → Elysia plugin
+runtime.fetch()                // → (request: Request) => { builder, requestId, … }
+runtime.forRequest(request)    // → one-shot Fetch context
 
-DTO.Queue.schema({
-  metadata: { source: 'billing', eventType: 'invoice.paid' },
-  payload: { invoiceId: 9 },
-}).build()
+runtime.websocket()            // → (socket, next?) => void
+runtime.attachWebSocket(ws)    // → attach builder to one socket
+
+runtime.socketIo()             // → (socket, next?) => void
+runtime.attachSocketIo(socket) // → attach builder to one socket
 ```
 
----
+### When to import adapters directly
 
-## Install
+Most apps only need `new DTO().express()` (etc.). Import adapters / sinks when you:
 
-```bash
-npm install @xrystal/dto
-```
+- Integrate a **custom framework** — `createBuilderRuntime(expressSink(res), options, context)`
+- **Unit-test** transport without full middleware
+- Build an **internal wrapper** (e.g. Fastify plugin)
 
-Peer dependencies (install only what you use):
+```typescript
+import { createBuilderRuntime, expressSink, ContextFactory } from '@xrystal/dto'
 
-```bash
-npm install express          # Express adapter
-npm install elysia           # Elysia adapter
+// Custom wiring example
+const context = ContextFactory.create(req)
+const { builder } = createBuilderRuntime(expressSink(res), options, context)
 ```
 
-Subpath imports are available if you want a smaller surface:
+Subpath imports (tree-shake friendly):
 
-```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'
-```
+| Import | Contents |
+|--------|----------|
+| `@xrystal/dto/express` | `ExpressAdapter`, `ExpressDispatcher`, `expressMiddleware` |
+| `@xrystal/dto/node` | `NodeAdapter`, `NodeDispatcher`, `nodeMiddleware` |
+| `@xrystal/dto/fetch` | `FetchAdapter`, `FetchDispatcher`, `createFetchDerive` |
+| `@xrystal/dto/elysia` | `ElysiaAdapter`, `ElysiaDispatcher`, `createElysiaDerive` |
+| `@xrystal/dto/websocket` | `WebSocketAdapter`, `WebSocketDispatcher` |
+| `@xrystal/dto/socketio` | `SocketIoAdapter`, `SocketIoDispatcher` |
 
 ---
 
-## Quick start (Express)
+## Core vs DTO — tek adapter yeter mi?
 
-```typescript
-import express from 'express'
-import { DTO } from '@xrystal/dto'
+Kütüphanenin **iki işi** var; mimari buna göre bölündü:
 
-const app = express()
-app.use(new DTO().express())
+| İş | Katman | Adapter gerekir mi? |
+|----|--------|---------------------|
+| **Şema üret** | `shapes/` + `shared.ts` | **Hayır** — `DTO.Log.build()`, `DTO.Response.build()`, testler |
+| **Client'a gönder** | `send/` + `adapters/` | **Evet** — `.send()` bir transport'a yazmalı |
 
-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
-}
+┌─────────────────────────────────────────────┐
+│  new DTO()  — tek giriş noktası             │
+│  runtime.express() / .fetch() / …           │
+└──────────────────┬──────────────────────────┘
+                   │
+┌──────────────────▼──────────────────────────┐
+│  adapters/  — sadece runtime wiring           │
+│  middleware → res.builder + send sink         │
+└──────────────────┬──────────────────────────┘
+                   │
+┌──────────────────▼──────────────────────────┐
+│  send/  — Builder, presets, transport     │
+│  .build() şema  |  .send() client'a yazar  │
+└──────────────────┬──────────────────────────┘
+                   │
+┌──────────────────▼──────────────────────────┐
+│  shapes/  — ResponseDTO, LogDTO, QueueDTO   │
+│  field sırası, .schema() ezme kuralları     │
+└─────────────────────────────────────────────┘
 ```
 
-Middleware attaches:
+### Tek adapter bağlamak yeter mi?
 
-- `req.ctx` — `{ requestId, startTime }`
-- `res.builder` — fluent response builder
-
----
+| Senaryo | Ne yaparsın |
+|---------|-------------|
+| **Normal HTTP app (Express vb.)** | `new DTO().express()` — başka adapter import etmezsin |
+| **Sadece JSON üret (log, queue, test)** | `DTO.Log` / `DTO.Queue` / `builder.build()` — adapter yok |
+| **Custom framework (Fastify vb.)** | `createBuilderRuntime(expressSink(res), …)` veya kendi sink'in |
+| **WS + HTTP aynı app'te** | Her transport için bir kez wire: `.express()` + `.websocket()` |
 
-## Two ways to respond
+**Özet:** Handler'dan client'a cevap gönderiyorsan bir adapter (veya sink) şart — ama çoğu app'te `new DTO().express()` tek satır yeter; `ExpressAdapter` import etmezsin. Dispatcher sınıfına gerek yok; adapter içinde `expressSink(res)` gibi tek satırlık `{ dispatch }` objesi var.
 
-### 1. Presets (recommended for most handlers)
+| Layer | Import eder misin? | Ne yapar |
+|-------|-------------------|----------|
+| **shapes** | Nadiren (`@xrystal/dto/log`) | Saf JSON şema |
+| **send** | Nadiren (`@xrystal/dto/response`) | Builder, transport, presets |
+| **adapters** | Custom entegrasyon / subpath | `builder`'ı request'e takar |
+| **DTO** | Her zaman | Config + `runtime.express()` shortcut |
 
-Call `.as.*` — dispatches automatically. **Do not call `.build()`.**
+### Request lifecycle (Express)
 
-```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')
+```
+1. Request gelir
+2. ExpressAdapter middleware:
+     ContextFactory → requestId
+     createBuilderRuntime(expressSink(res), options, ctx)
+     res.builder = builder
+3. Handler:
+     res.builder.as.ok(data).send()
+       → .build()  → FinalResult
+       → .send()   → transport.ts → expressSink → res.json()
 ```
 
-**Preset argument shape**
-
-| 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()` |
+Şema step 2'de oluşmaz — `.build()` veya `.send()` çağrıldığında assemble edilir.
 
-### 2. Manual chain (headers, cookies, custom cases)
+---
 
-Use when you need transport control or a schema-shaped body. Always end with `.build()`.
+## Architecture
 
-```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()
 ```
-
-Or apply the body in one step with `.schema()`:
-
-```typescript
-return res.builder
-  .httpStatus(429)
-  .header('Retry-After', '60')
-  .schema({
-    status: false,
-    message: 'Slow down',
-    code: 4,
-    payload: {
-      data: { retryAfter: 60 },
-      meta: { requestId: req.ctx.requestId },
-    },
-  })
-  .build()
+src/dto/
+├── shared.ts              BaseDTO, field rules, builder config
+├── factories.ts           ContextFactory, MetadataFactory
+├── shapes/                ← görev 1: şema
+│   ├── response.ts
+│   ├── log.ts
+│   └── queue.ts
+├── send/                  ← görev 2: build + push
+│   ├── builder.ts
+│   ├── presets.ts
+│   ├── transport.ts
+│   └── plugins.ts
+├── adapters/              runtime wiring
+│   ├── http.ts            Express, Node, Fetch, Elysia + *Sink helpers
+│   ├── realtime.ts        WebSocket, Socket.IO
+│   ├── bind.ts            DTO.express() shortcuts
+│   └── express.ts …       @xrystal/dto/express subpath shims
+└── runtime/
+    └── index.ts           DTO class, Hooks, createBuilderRuntime
 ```
 
-**Chain rules**
+Subpath exports (`@xrystal/dto/express`, `/response`, …) unchanged — shims map to the folders above.
 
-| 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. |
+### Package exports
 
-| 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 |
+| Import | Contents |
+|--------|----------|
+| `@xrystal/dto` | Everything (including all adapters & dispatchers) |
+| `@xrystal/dto/dto` | `DTO`, `createDTO`, runtime helpers |
+| `@xrystal/dto/response` | `ResponseDTO`, `Builder`, `PresetTerminal`, transport helpers |
+| `@xrystal/dto/log` | `LogDTO` |
+| `@xrystal/dto/queue` | `QueueDTO` |
+| `@xrystal/dto/express` | Express adapter |
+| `@xrystal/dto/node` | Node http adapter |
+| `@xrystal/dto/fetch` | Fetch API adapter |
+| `@xrystal/dto/elysia` | Elysia adapter |
+| `@xrystal/dto/websocket` | WebSocket adapter |
+| `@xrystal/dto/socketio` | Socket.IO adapter |
 
 ---
 
-## DTO setup
-
-Single entry point: **`DTO`**. Instance = runtime (middleware). Static namespaces = shape DTOs (`DTO.Response`, `DTO.Log`, `DTO.Queue`).
-
-```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())
-```
+## Response schema
 
-Default codes (always merged; override only what you need):
+| 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 |
 
-| Key | Default | Typical use |
-|-----|---------|-------------|
-| `SUCCESS` | `0` | Happy path |
-| `CLIENT` | `1` | Bad input, auth, not found, … |
-| `SERVER` | `2` | Internal errors |
-| `VALIDATION` | `3` | Schema / field validation |
+Transport (HTTP status, headers, cookies) lives on **`builder`**, not on `DTO.Response`.
 
 ---
 
-## Core presets
+## Handler API
 
-| 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 |
+### Presets (recommended)
 
----
+Presets return a terminal — always end with `.send()` or `.build()`:
 
-## HTTP-specific presets
+```typescript
+return res.builder.as.ok(data, 'Done').send()
+return res.builder.as.fail('Not found').send()
+return res.builder.as.notFound('User missing').send()
+return res.builder.as.tooManyRequests('Slow down').send()
 
-Use when you need an exact HTTP status. Core `.fail()` / `.error()` cover most cases.
+// Headers before preset
+return res.builder.header('X-Trace', traceId).as.ok(data).send()
+```
 
-### Client (4xx)
+### Manual chain
 
-| Method | HTTP | Code |
-|--------|------|------|
-| `.badRequest(…)` | 400 | CLIENT |
-| `.unauthorized(…)` | 401 | CLIENT |
-| `.forbidden(…)` | 403 | CLIENT |
-| `.notFound(…)` | 404 | CLIENT |
-| `.conflict(…)` | 409 | CLIENT |
-| `.unprocessable(…)` | 422 | VALIDATION |
-| `.tooManyRequests(…)` | 429 | CLIENT |
+```typescript
+return res.builder
+  .httpStatus(429)
+  .header('Retry-After', '60')
+  .schema({
+    status: false,
+    message: 'Slow down',
+    code: 4,
+    payload: { data: { retryAfter: 60 } },
+  })
+  .send()
+```
 
-### Server (5xx)
+Schema only (no dispatch):
 
-| Method | HTTP | Code |
-|--------|------|------|
-| `.internalServerError(…)` | 500 | SERVER |
-| `.serviceUnavailable(…)` | 503 | SERVER |
-| `.gatewayTimeout(…)` | 504 | SERVER |
+```typescript
+const result = res.builder.schema({ payload: { data: user } }).build()
+await auditLog.write(result.body)
+```
 
-All HTTP presets share the same argument shape as `.ok()` / `.fail()`.
+| 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 |
+| Preset terminal | `.as.*()` exposes only `.build()` and `.send()` |
 
 ---
 
-## Plugins
+## Shape DTOs
 
-Middleware-style pipeline. Lower `priority` runs first (default `0`).
+### Response (`DTO.Response`)
 
-| 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)
+DTO.Response.schema({
+  status: false,
+  message: 'Not found',
+  code: 1,
+}).build()
 ```
 
----
-
-## Runtime guides
+Inside a handler, `res.builder.dto` exposes the same `ResponseDTO` instance.
 
-### Express
+### Log (`DTO.Log`)
 
-```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')
-})
-```
+Order: `level → service → message? → payload? → code? → timestamp → id? → env`
 
-### Node HTTP
+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?.as.fail('Not found')
-  })
-}).listen(3000)
+DTO.Log.level('info')
+  .service('users-api')
+  .env(NodeEnvEnum.PROD)
+  .message('User fetched')
+  .build()
 ```
 
-### Bun HTTP
-
-Bun uses the Node adapter via `node:http` — same API:
-
-```typescript
-import { createServer } from 'node:http'
-import { DTO } from '@xrystal/dto'
+### Queue (`DTO.Queue`)
 
-const dto = new DTO()
+Order: `source → eventType → timestamp → correlationId → userId? → extraData?`
 
-createServer((req, res) => {
-  dto.node()(req, res, () => {
-    if (req.url === '/health') return res.builder?.as.ok({ ok: true }, 'Up')
+Required: `source`, `eventType`. Timestamp and correlationId auto-generate.
 
-    return res.builder
-      ?.code(4)
-      .httpStatus(429)
-      .status(false)
-      .message('Too many requests')
-      .build()
-  })
-}).listen(3000)
+```typescript
+DTO.Queue.source('billing')
+  .eventType('invoice.paid')
+  .payload({ invoiceId: 9 })
+  .build()
 ```
 
-`req.ctx` holds `requestId`; `res.builder` is attached by middleware (use `?.` until the handler runs).
-
-### Elysia
+---
 
-The handler argument **is** the context. The plugin adds `builder`, `requestId`, and `startTime` via scoped `derive`:
+## Runtime config
 
 ```typescript
-import { Elysia } from 'elysia'
-import { DTO } from '@xrystal/dto'
+import { DTO, definePlugin } from '@xrystal/dto'
 
-const dto = new DTO()
+const audit = definePlugin({
+  name: 'audit',
+  afterDispatch(result, ctx) {
+    console.log(ctx.context?.requestId, result.statusCode)
+  },
+})
 
-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 } }),
-  )
+const runtime = new DTO({
+  withDefaultHeaders: true,
+  codes: { RATE_LIMITED: 4 },
+  plugins: [audit],
+  socket: { event: 'api:response' },
+}).use(otherPlugin) // immutable — returns new DTO
+
+app.use(runtime.express())
+io.use(runtime.socketIo())
 ```
 
-Outside a request (e.g. startup log):
+| Option | Affects |
+|--------|---------|
+| `plugins` | `builder` pipeline only (`beforeDispatch` runs on `.send()`, not `.build()`) |
+| `codes` | `builder` presets and `.code()` |
+| `withDefaultHeaders` | HTTP / Fetch middleware |
+| `socket.event` | Socket.IO emit name |
 
-```typescript
-console.log(
-  DTO.Log.level('info')
-    .service('api')
-    .env(NodeEnvEnum.PROD)
-    .message('Server listening')
-    .build(),
-)
-```
+---
 
-### WebSocket
+## Runtimes
 
 ```typescript
-import { DTO } 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')
-    },
-  },
-})
+runtime.express()
+runtime.node()
+runtime.elysia()
+runtime.fetch() / runtime.forRequest(request)
+runtime.websocket() / runtime.attachWebSocket(ws)
+runtime.socketIo() / runtime.attachSocketIo(socket)
 ```
 
-### Socket.IO
+### Errors in handlers
 
 ```typescript
-dto.attachSocketIo(socket)
-socket.builder?.as.ok({ room: 'lobby' }, 'Connected')
-
-io.use(dto.socketIo())
-socket.builder?.as.ok({ socketId: socket.id }, 'Connected')
+try {
+  const user = await fetchUser(id)
+  return res.builder.as.ok(user, 'User fetched').send()
+} catch (err) {
+  return res.builder.fromError(err).send()
+}
 ```
 
-WebSocket and Socket.IO have no HTTP status — use presets or `.build()`. JSON is sent via `ws.send` / `socket.emit`.
+Built-in: `ClientError`, `ServerError`, `ValidationError`.
 
 ---
 
-## Full-stack example
+## Full-stack sketch
 
 ```typescript
 import express from 'express'
 import { DTO, NodeEnvEnum } from '@xrystal/dto'
 
-const runtime = new DTO({
-  withDefaultHeaders: true,
-  codes: { RATE_LIMITED: 4 },
-})
-
+const runtime = new DTO({ withDefaultHeaders: true })
 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()
+  const user = await db.findUser(req.params.id)
+  if (!user) return res.builder.as.notFound('User not found').send()
+
+  console.log(
+    DTO.Log.level('info')
+      .service('users-api')
+      .env(NodeEnvEnum.PROD)
+      .payload({ userId: user.id })
+      .build(),
+  )
 
-  queue.publish(event)
-}, 60_000)
+  return res.builder.as.ok(user, 'User fetched', {
+    meta: { requestId: req.ctx.requestId },
+  }).send()
+})
 ```
 
 ---
 
-## Errors
+## HTTP presets reference
 
-Map thrown errors to the standard body:
-
-```typescript
-try {
-  const user = await fetchUser(id)
-  return res.builder.as.ok(user, 'User fetched')
-} catch (err) {
-  return res.builder.fromError(err).build()
-}
-```
+| Preset | HTTP | Code |
+|--------|------|------|
+| `.ok()` | 200 | SUCCESS |
+| `.created()` | 201 | SUCCESS |
+| `.fail()` | 400 | CLIENT |
+| `.notFound()` | 404 | CLIENT |
+| `.unprocessable()` | 422 | VALIDATION |
+| `.tooManyRequests()` | 429 | CLIENT |
+| `.error()` | 500 | SERVER |
 
-Built-in error types: `ClientError`, `ServerError`, `ValidationError`. Unknown errors are masked when `verbose: false`.
+See source `dto/send/presets.ts` for the full list.
 
 ---
 
-## Custom codes & HTTP status
+### Breaking / API changes
 
-```typescript
-const dto = new DTO({ codes: { RATE_LIMITED: 4 } })
+- **Explicit terminal verbs** — every handler chain must end with `.send()` (dispatch to client) or `.build()` (schema only). No automatic dispatch.
+- **Preset terminal** — `.as.ok()`, `.as.fail()`, … return `PresetTerminal` with only `.build()` and `.send()`. No further chaining after presets (put headers **before** preset: `builder.header('X').as.ok(data).send()`).
+- **WebSocket / Socket.IO wire format** — emits full transport envelope (`statusCode`, `headers`, `cookies`, `body`) instead of bare body JSON. Update clients if they parsed the old shape.
 
-return res.builder
-  .code(4)
-  .httpStatus(429)
-  .status(false)
-  .message('Too many requests')
-  .build()
+### New
 
-// Or when HTTP maps cleanly:
-return res.builder.as.tooManyRequests('Too many requests')
-```
+- **Fetch API adapter** — `runtime.fetch()`, `runtime.forRequest(request)`, `@xrystal/dto/fetch`. Returns Web `Response` from `.send()`. Works with Workers, Hono, Bun.serve, Next.js route handlers.
+- **Core transport layer** — `dto/send/transport.ts` centralises headers, cookies, JSON body, Fetch `Response`, and realtime wire envelope.
+- **Exported adapters & dispatchers** — `ExpressDispatcher`, `FetchDispatcher`, `ElysiaDispatcher`, … available from main entry and subpaths for custom integrations.
 
----
+### Fixes & consistency
 
-## Release (maintainers)
+- **Elysia** — inline dispatcher replaced with `ElysiaDispatcher` class (same pattern as Express/Node/Fetch).
+- **Node http** — `Set-Cookie` support added (was Express-only via `res.cookie`).
+- **Dispatch hooks** — `beforeDispatch` / `afterDispatch` plugins run on `.send()` only, not on `.build()`.
+
+### Package surface
 
-**Source of truth:** `package.json` `"version"`. Git tag must be **identical** — no env override.
+| Runtimes | 6 — Express, Node, Fetch, Elysia, WebSocket, Socket.IO |
+| Tests | 77 passing |
+| Subpaths | `/express`, `/node`, `/fetch`, `/elysia`, `/websocket`, `/socketio`, `/response`, `/log`, `/queue`, `/dto` |
 
-Format: `YY.MM.DD-vN` (e.g. `26.06.27-v8`).
+### Migration cheat sheet
 
-### Quick tag (commit already done)
+```typescript
+// Before
+return res.builder.as.ok(data, 'Done')
 
-Bump `package.json`, commit, then:
+// After
+return res.builder.as.ok(data, 'Done').send()
 
-```bash
-npm run tag
+// Schema only (unchanged intent, now explicit)
+const body = res.builder.as.ok(data).build()
+
+// WS client — expect envelope now
+// { statusCode, headers, cookies, body: { status, message, … } }
 ```
 
-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