@xrystal/dto 26.6.27-v13 → 26.6.27-v14

package/README.md

@@ -41,13 +41,15 @@ This attaches `req.ctx` and `res.builder` on every request.
 
 ### 2. Respond in a handler
 
+Every chain ends with a **verb** — `.send()` (go to client) or `.build()` (schema only):
+
 ```typescript
 app.get('/users/:id', (req, res) => {
   return res.builder.as.ok(
     { id: req.params.id },
     'User fetched',
     { meta: { requestId: req.ctx.requestId } },
-  )
+  ).send()
 })
 ```
 
@@ -62,7 +64,12 @@ Sent JSON (fixed order: `status → message → payload? → code`):
 }
 ```
 
-Presets (`.as.ok`, `.as.notFound`, …) dispatch automatically — **no `.build()`**.
+| 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()`.
 
 ### 3. Static shape DTOs (no request)
 
@@ -102,52 +109,226 @@ 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 } }),
+    builder.as.ok({ id: params.id }, 'User fetched', { meta: { requestId } }).send(),
   )
 ```
 
+### Fetch API — Workers, Hono, Bun.serve
+
+```typescript
+import { DTO } from '@xrystal/dto'
+
+const runtime = new DTO({ withDefaultHeaders: true })
+
+export async function GET(request: Request) {
+  const { builder, requestId } = runtime.forRequest(request)
+  return builder.as.ok({ ok: true }, 'Healthy', { meta: { requestId } }).send()
+  // → Web Response
+}
+```
+
 ### When to use what
 
 | Situation | Use |
 |-----------|-----|
-| Express / Node / Elysia handler | `res.builder` / `ctx.builder` |
-| WebSocket / Socket.IO | `ws.builder` / `socket.builder` |
+| 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 | `res.builder.httpStatus(429).header(...).schema({...}).build()` |
+| Custom HTTP status + headers | `builder.httpStatus(429).header(...).schema({...}).send()` |
 
 Plugins and custom `codes` on `new DTO({ … })` apply **only to `builder`** — not to static `DTO.Log` / `DTO.Queue`.
 
 ---
 
-## Architecture
+## Adapters & send sinks
+
+Each runtime has an **adapter** (wires `builder` per request) and a **send sink** (writes `FinalResult` to the transport on `.send()`).
+
+| 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` |
+
+```
+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.
+
+### Runtime map
+
+| 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)` |
+
+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
+const runtime = new DTO({ withDefaultHeaders: true, socket: { event: 'api:response' } })
+
+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
+
+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
+
+Most apps only need `new DTO().express()` (etc.). Import adapters / sinks when you:
+
+- Integrate a **custom framework** — `createBuilderRuntime(expressSink(res), options, context)`
+- **Unit-test** transport without full middleware
+- Build an **internal wrapper** (e.g. Fastify plugin)
+
+```typescript
+import { createBuilderRuntime, expressSink, ContextFactory } from '@xrystal/dto'
+
+// Custom wiring example
+const context = ContextFactory.create(req)
+const { builder } = createBuilderRuntime(expressSink(res), options, context)
+```
+
+Subpath imports (tree-shake friendly):
+
+| 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` |
+
+---
+
+## Core vs DTO — tek adapter yeter mi?
+
+Kütüphanenin **iki işi** var; mimari buna göre bölündü:
 
-Symmetric modules under `src/dto/`:
+| İş | 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ı |
 
 ```
-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
+┌─────────────────────────────────────────────┐
+│  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ı     │
+└─────────────────────────────────────────────┘
 ```
 
+### Tek adapter bağlamak yeter mi?
+
+| 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()` |
+
+**Ö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.
+
+| 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 |
+
+### Request lifecycle (Express)
+
+```
+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()
+```
+
+Şema step 2'de oluşmaz — `.build()` veya `.send()` çağrıldığında assemble edilir.
+
+---
+
+## Architecture
+
+```
+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
+```
+
+Subpath exports (`@xrystal/dto/express`, `/response`, …) unchanged — shims map to the folders above.
+
 ### Package exports
 
 | Import | Contents |
 |--------|----------|
-| `@xrystal/dto` | Everything |
+| `@xrystal/dto` | Everything (including all adapters & dispatchers) |
 | `@xrystal/dto/dto` | `DTO`, `createDTO`, runtime helpers |
-| `@xrystal/dto/response` | `ResponseDTO`, `Builder`, presets |
+| `@xrystal/dto/response` | `ResponseDTO`, `Builder`, `PresetTerminal`, transport helpers |
 | `@xrystal/dto/log` | `LogDTO` |
 | `@xrystal/dto/queue` | `QueueDTO` |
-| `@xrystal/dto/express` | Express middleware |
+| `@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 |
 
 ---
 
@@ -168,17 +349,20 @@ Transport (HTTP status, headers, cookies) lives on **`builder`**, not on `DTO.Re
 
 ### Presets (recommended)
 
+Presets return a terminal — always end with `.send()` or `.build()`:
+
 ```typescript
-res.builder.as.ok(data, 'Done')
-res.builder.as.fail('Not found')
-res.builder.as.notFound('User missing')
-res.builder.as.tooManyRequests('Slow down')
+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()
+
+// Headers before preset
+return res.builder.header('X-Trace', traceId).as.ok(data).send()
 ```
 
 ### Manual chain
 
-End with `.build()` when you need headers, cookies, or fine control:
-
 ```typescript
 return res.builder
   .httpStatus(429)
@@ -189,7 +373,14 @@ return res.builder
     code: 4,
     payload: { data: { retryAfter: 60 } },
   })
-  .build()
+  .send()
+```
+
+Schema only (no dispatch):
+
+```typescript
+const result = res.builder.schema({ payload: { data: user } }).build()
+await auditLog.write(result.body)
 ```
 
 | Chain rule | Detail |
@@ -197,6 +388,7 @@ return res.builder
 | 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()` |
 
 ---
 
@@ -272,10 +464,10 @@ io.use(runtime.socketIo())
 
 | Option | Affects |
 |--------|---------|
-| `plugins` | `builder` pipeline only |
+| `plugins` | `builder` pipeline only (`beforeDispatch` runs on `.send()`, not `.build()`) |
 | `codes` | `builder` presets and `.code()` |
-| `withDefaultHeaders` | HTTP middleware |
-| `socket.event` | WebSocket / Socket.IO emit name |
+| `withDefaultHeaders` | HTTP / Fetch middleware |
+| `socket.event` | Socket.IO emit name |
 
 ---
 
@@ -285,6 +477,7 @@ io.use(runtime.socketIo())
 runtime.express()
 runtime.node()
 runtime.elysia()
+runtime.fetch() / runtime.forRequest(request)
 runtime.websocket() / runtime.attachWebSocket(ws)
 runtime.socketIo() / runtime.attachSocketIo(socket)
 ```
@@ -294,9 +487,9 @@ runtime.socketIo() / runtime.attachSocketIo(socket)
 ```typescript
 try {
   const user = await fetchUser(id)
-  return res.builder.as.ok(user, 'User fetched')
+  return res.builder.as.ok(user, 'User fetched').send()
 } catch (err) {
-  return res.builder.fromError(err).build()
+  return res.builder.fromError(err).send()
 }
 ```
 
@@ -316,7 +509,7 @@ app.use(runtime.express())
 
 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')
+  if (!user) return res.builder.as.notFound('User not found').send()
 
   console.log(
     DTO.Log.level('info')
@@ -328,7 +521,7 @@ app.get('/users/:id', async (req, res) => {
 
   return res.builder.as.ok(user, 'User fetched', {
     meta: { requestId: req.ctx.requestId },
-  })
+  }).send()
 })
 ```
 
@@ -346,7 +539,49 @@ app.get('/users/:id', async (req, res) => {
 | `.tooManyRequests()` | 429 | CLIENT |
 | `.error()` | 500 | SERVER |
 
-See source `dto/response/presets.ts` for the full list.
+See source `dto/send/presets.ts` for the full list.
+
+---
+
+### Breaking / API changes
+
+- **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.
+
+### New
+
+- **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
+
+- **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
+
+| Runtimes | 6 — Express, Node, Fetch, Elysia, WebSocket, Socket.IO |
+| Tests | 77 passing |
+| Subpaths | `/express`, `/node`, `/fetch`, `/elysia`, `/websocket`, `/socketio`, `/response`, `/log`, `/queue`, `/dto` |
+
+### Migration cheat sheet
+
+```typescript
+// Before
+return res.builder.as.ok(data, 'Done')
+
+// After
+return res.builder.as.ok(data, 'Done').send()
+
+// 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, … } }
+```
 
 ---