@xrystal/dto 26.6.27-v15 → 26.6.28-v1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xrystal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -24,20 +24,116 @@ npm install express elysia
 | 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 |
 
-**Rule of thumb:** client cevabı → `builder`. Düz JSON üretmek → static `DTO.*`.
+**Rule of thumb:** client response → `builder`. Plain JSON without transport → static `DTO.*`.
 
-### 1. Wire the runtime (once)
+### 1. Bootstrap — create DTO once, wire one adapter
+
+**Step A — app entry (single instance):**
 
 ```typescript
-import express from 'express'
 import { DTO } from '@xrystal/dto'
 
-const runtime = new DTO({ withDefaultHeaders: true })
+export const runtime = new DTO({
+  withDefaultHeaders: true,
+  // optional: codes, plugins, socket: { event: 'api:response' }
+})
+```
+
+Create `new DTO()` **once** at startup. Handlers reuse the same `runtime`; do not create a new DTO per request.
+
+**Step B — register the adapter for your server (once, at startup):**
+
+Each method returns **middleware or a plugin** — the framework calls it per request/connection. You do **not** call `runtime.express(req, res)` inside handlers.
+
+| Stack | Wire once (bootstrap) | In handler |
+|-------|------------------------|------------|
+| **Express** | `app.use(runtime.express())` | `res.builder.as.ok(...).send()` |
+| **Node `http`** | `server.on('request', chain(runtime.node(), handler))` | `res.builder…send()` |
+| **Elysia** | `app.use(runtime.elysia())` | `builder.as.ok(...).send()` |
+| **Fetch / Workers** | no global wire — `runtime.forRequest(request)` per call | `builder…send()` → `Response` |
+| **WebSocket** | `wss.on('connection', ws => runtime.attachWebSocket(ws))` | `ws.builder…send()` |
+| **Socket.IO** | `io.use(runtime.socketIo())` or `attachSocketIo` on connect | `socket.builder…send()` |
+
+#### Express
+
+```typescript
+import express from 'express'
+import { runtime } from './dto.js'
+
 const app = express()
-app.use(runtime.express())
+app.use(runtime.express())   // ← once: attaches req.ctx + res.builder
+
+app.get('/users/:id', (req, res) =>
+  res.builder.as.ok({ id: req.params.id }, 'User fetched').send(),
+)
+```
+
+#### Elysia
+
+```typescript
+import { Elysia } from 'elysia'
+import { runtime } from './dto.js'
+
+new Elysia()
+  .use(runtime.elysia())      // ← once: derive injects builder, requestId, startTime
+  .get('/users/:id', ({ builder, requestId, params }) =>
+    builder.as.ok({ id: params.id }, 'User fetched', { meta: { requestId } }).send(),
+  )
 ```
 
-This attaches `req.ctx` and `res.builder` on every request.
+#### Socket.IO
+
+```typescript
+import { Server } from 'socket.io'
+import { runtime } from './dto.js'
+
+const io = new Server(httpServer)
+
+// Option 1 — middleware on every connection
+io.use(runtime.socketIo())
+
+io.on('connection', (socket) => {
+  socket.on('getUser', ({ id }) =>
+    socket.builder!.as.ok({ id }, 'User fetched').send(),
+  )
+})
+
+// Option 2 — attach manually in the connection handler
+io.on('connection', (socket) => {
+  runtime.attachSocketIo(socket)
+  // socket.builder is now available
+})
+```
+
+#### WebSocket (raw `ws`)
+
+```typescript
+import { WebSocketServer } from 'ws'
+import { runtime } from './dto.js'
+
+const wss = new WebSocketServer({ server: httpServer })
+
+wss.on('connection', (ws) => {
+  runtime.attachWebSocket(ws)   // or wss.use pattern via runtime.websocket() middleware
+  ws.on('message', () => ws.builder!.as.ok({ pong: true }).send())
+})
+```
+
+**HTTP + realtime in one app:** wire both transports at bootstrap — e.g. `app.use(runtime.express())` and `io.use(runtime.socketIo())`.
+
+#### With xrystal-core
+
+In a **standalone** app you pick the adapter explicitly (`runtime.express()`, `runtime.elysia()`, …).
+
+In **xrystal-core**, framework selection lives in core via **`dtoMiddleware(config)`** — it reads your config and wires the correct adapter (`express`, `elysia`, `socketIo`, …). DTO does not pick the framework; core does.
+
+Standalone apps call the adapter explicitly:
+
+```typescript
+runtime.express()    // not runtime.middleware('express')
+runtime.elysia()
+runtime.socketIo()
+```
 
 ### 2. Respond in a handler
 
@@ -99,20 +195,6 @@ Every shape DTO shares the same chain rules:
 - `.schema({ … })` for partial input — **last call wins**
 - `payload` in `.schema()` **replaces** the entire payload
 
-### Elysia — same idea
-
-```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(),
-  )
-```
-
 ### Fetch API — Workers, Hono, Bun.serve
 
 ```typescript
@@ -176,25 +258,29 @@ WebSocket and Socket.IO send the full transport envelope (`statusCode`, `headers
 
 ### `new DTO()` shortcuts
 
+Register at **bootstrap** (once). Handlers only use `builder`.
+
 ```typescript
 const runtime = new DTO({ withDefaultHeaders: true, socket: { event: 'api:response' } })
 
-runtime.express()              // → Express middleware
+// HTTP — returns middleware / plugin; pass to app.use()
+runtime.express()              // → (req, res, next) => void
+runtime.elysia()               // → Elysia plugin (derive builder per request)
 runtime.node()                 // → Node http middleware
-runtime.elysia()               // → Elysia plugin
 runtime.fetch()                // → (request: Request) => { builder, requestId, … }
 runtime.forRequest(request)    // → one-shot Fetch context
 
+// Realtime — returns connection middleware or attach helper
 runtime.websocket()            // → (socket, next?) => void
 runtime.attachWebSocket(ws)    // → attach builder to one socket
 
-runtime.socketIo()             // → (socket, next?) => void
+runtime.socketIo()             // → (socket, next?) => void  (Socket.IO middleware)
 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:
+Most apps only need `new DTO().elysia()` or `new DTO().express()` (etc.). Import adapters / sinks when you:
 
 - Integrate a **custom framework** — `createBuilderRuntime(expressSink(res), options, context)`
 - **Unit-test** transport without full middleware
@@ -221,59 +307,59 @@ Subpath imports (tree-shake friendly):
 
 ---
 
-## Core vs DTO — tek adapter yeter mi?
+## Core vs DTO — is one adapter enough?
 
-Kütüphanenin **iki işi** var; mimari buna göre bölündü:
+The library has **two jobs**; the layout reflects that:
 
-| İş | 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ı |
+| Job | Layer | Adapter required? |
+|-----|-------|-------------------|
+| **Build schema** | `shapes/` + `shared.ts` | **No** — `DTO.Log.build()`, `DTO.Response.build()`, tests |
+| **Push to client** | `send/` + `adapters/` | **Yes** — `.send()` must write to a transport |
 
 ```
 ┌─────────────────────────────────────────────┐
-│  new DTO()  — tek giriş noktası             │
+│  new DTO()  — single entry point            │
 │  runtime.express() / .fetch() / …           │
 └──────────────────┬──────────────────────────┘
                    │
 ┌──────────────────▼──────────────────────────┐
-│  adapters/  — sadece runtime wiring           │
+│  adapters/  — runtime wiring only           │
 │  middleware → res.builder + send sink         │
 └──────────────────┬──────────────────────────┘
                    │
 ┌──────────────────▼──────────────────────────┐
-│  send/  — Builder, presets, transport     │
-│  .build() şema  |  .send() client'a yazar  │
+│  send/  — Builder, presets, transport       │
+│  .build() schema  |  .send() writes client    │
 └──────────────────┬──────────────────────────┘
                    │
 ┌──────────────────▼──────────────────────────┐
-│  shapes/  — ResponseDTO, LogDTO, QueueDTO   │
-│  field sırası, .schema() ezme kuralları     │
+│  shapes/  — ResponseDTO, LogDTO, QueueDTO     │
+│  field order, .schema() override rules        │
 └─────────────────────────────────────────────┘
 ```
 
-### Tek adapter bağlamak yeter mi?
+### Is wiring one adapter enough?
 
-| 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()` |
+| Scenario | What to do |
+|----------|------------|
+| **Normal HTTP app** | Pick your stack: `runtime.express()`, `runtime.elysia()`, `runtime.fetch()`, … |
+| **JSON only (log, queue, test)** | `DTO.Log` / `DTO.Queue` / `builder.build()` — no adapter |
+| **Custom framework (Fastify, etc.)** | `createBuilderRuntime(expressSink(res), …)` or your own sink |
+| **WS + HTTP in the same app** | Wire once per transport: e.g. `.elysia()` + `.socketIo()` |
 
-**Özet:** Handler'dan client'a cevap gönderiyorsan bir adapter şart — ama çoğu app'te `new DTO().express()` tek satır yeter. Adapter request başında sink'i builder'a **takır**; sink yalnızca `.send()` çağrıldığında çalışır. `.build()` saf şema döner, transport'a dokunmaz.
+**Summary:** If you send handler responses to a client, you need an adapter — pick the one that matches your server. The adapter **attaches** the sink to the builder at request start; the sink runs **only** when `.send()` is called. `.build()` returns pure schema and never touches transport.
 
-| 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 |
+| Layer | Do you import it? | Role |
+|-------|-------------------|------|
+| **shapes** | Rarely (`@xrystal/dto/log`) | Pure JSON schema |
+| **send** | Rarely (`@xrystal/dto/response`) | Builder, transport, presets |
+| **adapters** | Custom integration / subpath | Attaches `builder` to each request |
+| **DTO** | Always | Config + `runtime.elysia()` / `runtime.express()` shortcuts |
 
 ### Request lifecycle (Express)
 
 ```
-1. Request gelir
+1. Request arrives
 2. ExpressAdapter middleware:
      ContextFactory → requestId
      createBuilderRuntime(expressSink(res), options, ctx)
@@ -284,7 +370,7 @@ Kütüphanenin **iki işi** var; mimari buna göre bölündü:
        → .send()   → transport.ts → expressSink → res.json()
 ```
 
-Şema step 2'de oluşmaz — `.build()` veya `.send()` çağrıldığında assemble edilir.
+Schema is **not** assembled at step 2 — only when you call `.build()` or `.send()`.
 
 ---
 
@@ -294,22 +380,24 @@ Kütüphanenin **iki işi** var; mimari buna göre bölündü:
 src/dto/
 ├── shared.ts              BaseDTO, field rules, builder config
 ├── factories.ts           ContextFactory, MetadataFactory
-├── shapes/                ← görev 1: şema
+├── shapes/                ← job 1: schema
 │   ├── response.ts
 │   ├── log.ts
 │   └── queue.ts
-├── send/                  ← görev 2: build + push
+├── send/                  ← job 2: build + push
 │   ├── builder.ts
 │   ├── presets.ts
 │   ├── transport.ts
 │   └── plugins.ts
 ├── adapters/              runtime wiring
-│   ├── http.ts            Express, Node, Fetch, Elysia + *Sink helpers
+│   ├── http.ts            Express, Node, Fetch + *Sink helpers
+│   ├── elysia-adapter.ts  Elysia plugin + elysiaSink (isolated for tree-shaking)
 │   ├── realtime.ts        WebSocket, Socket.IO
 │   ├── bind.ts            DTO.express() shortcuts
 │   └── express.ts …       @xrystal/dto/express subpath shims
 └── runtime/
-    └── index.ts           DTO class, Hooks, createBuilderRuntime
+    ├── builder-runtime.ts createBuilderRuntime (adapter-safe import)
+    └── index.ts           DTO class, Hooks
 ```
 
 Subpath exports (`@xrystal/dto/express`, `/response`, …) unchanged — shims map to the folders above.
@@ -318,7 +406,7 @@ Subpath exports (`@xrystal/dto/express`, `/response`, …) unchanged — shims m
 
 | Import | Contents |
 |--------|----------|
-| `@xrystal/dto` | Everything (including all adapters & dispatchers) |
+| `@xrystal/dto` | Everything (including all adapters & send sinks) |
 | `@xrystal/dto/dto` | `DTO`, `createDTO`, runtime helpers |
 | `@xrystal/dto/response` | `ResponseDTO`, `Builder`, `PresetTerminal`, transport helpers |
 | `@xrystal/dto/log` | `LogDTO` |
@@ -545,6 +633,7 @@ See source `dto/send/presets.ts` for the full list.
 
 ### Breaking / API changes
 
+- **Removed `runtime.middleware()`** — DTO no longer resolves framework from a string. Pick an adapter explicitly (`runtime.express()`, `runtime.elysia()`, `runtime.socketIo()`, …) or use **`dtoMiddleware(config)`** from **xrystal-core** for config-driven wiring. Removed exports: `normalizeRuntimeKind`, `RuntimeKind`.
 - **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.
@@ -564,12 +653,26 @@ See source `dto/send/presets.ts` for the full list.
 ### Package surface
 
 | Runtimes | 6 — Express, Node, Fetch, Elysia, WebSocket, Socket.IO |
-| Tests | 77 passing |
+| Tests | 79 passing |
 | Subpaths | `/express`, `/node`, `/fetch`, `/elysia`, `/websocket`, `/socketio`, `/response`, `/log`, `/queue`, `/dto` |
 
 ### Migration cheat sheet
 
 ```typescript
+// Removed — use explicit adapter or xrystal-core dtoMiddleware(config)
+runtime.middleware('express')   // ✗
+runtime.middleware()            // ✗
+runtime.middleware('socketio')  // ✗
+
+// Standalone
+app.use(runtime.express())
+app.use(runtime.elysia())
+io.use(runtime.socketIo())
+
+// xrystal-core (config-driven)
+import { dtoMiddleware } from 'xrystal-core/handlers' // your core export path
+app.use(dtoMiddleware(config))
+
 // Before
 return res.builder.as.ok(data, 'Done')
 
@@ -585,16 +688,25 @@ const body = res.builder.as.ok(data).build()
 
 ---
 
-## Release (maintainers)
+## Contributing
 
-Version lives in `package.json` (`YY.MM.DD-vN`). Git tag must match exactly.
+Contributions are welcome. Open an issue to discuss larger changes, or submit a pull request with a focused diff and tests where behaviour changes.
+
+Before opening a PR, run:
 
 ```bash
-npm run release   # lint → test → build → commit → tag → push
-npm run tag       # tag only (after manual commit)
-npm run version:check
+npm test
+npm run lint
 ```
 
----
+## License
+
+[MIT](LICENSE) © [xrystal](https://github.com/xdloper)
+
+## Links
 
-MIT
+| | |
+|---|---|
+| **npm** | [`@xrystal/dto`](https://www.npmjs.com/package/@xrystal/dto) |
+| **Repository** | [github.com/xdloper/dto](https://github.com/xdloper/dto) |
+| **Issues** | [github.com/xdloper/dto/issues](https://github.com/xdloper/dto/issues) |