@xrystal/dto 26.6.27-v12

package/README.md

@@ -0,0 +1,724 @@
+# @xrystal/dto
+
+Framework-agnostic **Data Transfer Object** library for **Express**, **Node/Bun HTTP**, **Elysia**, **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.
+
+---
+
+## Why use it?
+
+- **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
+
+---
+
+## 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
+}
+```
+
+| 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 |
+
+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.
+
+```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:
+
+```typescript
+const bodyOnly = res.builder.dto.build() // same JSON shape, no dispatch yet
+```
+
+### You **do not** have a request (cron, worker, unit test, logger, queue publisher)
+
+No `req`, no `res`, no `ctx` — nothing to attach a builder to. Use **static shape DTOs**:
+
+```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()
+```
+
+### 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 |
+
+---
+
+## 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()
+```
+
+In a handler, `res.builder` delegates body fields to an internal `ResponseDTO`. Access it via `res.builder.dto` when you only need the shape.
+
+---
+
+## Log DTO
+
+Fixed field order: `level → service → message? → payload? → code? → timestamp → id? → env`
+
+**Required at build:** `level`, `service`, `env`.
+
+```typescript
+import { DTO, NodeEnvEnum } from '@xrystal/dto'
+
+DTO.Log.level('info')
+  .service('users-api')
+  .env(NodeEnvEnum.PROD)
+  .message('User fetched')
+  .payload({ userId: 1 })
+  .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')
+  .eventType('user.created')
+  .userId('u-1')
+  .payload({ id: 1 })
+  .build()
+
+DTO.Queue.schema({
+  metadata: { source: 'billing', eventType: 'invoice.paid' },
+  payload: { invoiceId: 9 },
+}).build()
+```
+
+---
+
+## Install
+
+```bash
+npm install @xrystal/dto
+```
+
+Peer dependencies (install only what you use):
+
+```bash
+npm install express          # Express adapter
+npm install elysia           # Elysia adapter
+```
+
+Subpath imports are available if you want a smaller surface:
+
+```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'
+```
+
+---
+
+## Quick start (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')
+})
+```
+
+Response sent to the client:
+
+```json
+{
+  "status": true,
+  "message": "User fetched",
+  "payload": { "data": { "id": "42" } },
+  "code": 0
+}
+```
+
+Middleware attaches:
+
+- `req.ctx` — `{ requestId, startTime }`
+- `res.builder` — fluent response builder
+
+---
+
+## Two ways to respond
+
+### 1. Presets (recommended for most handlers)
+
+Call `.as.*` — dispatches automatically. **Do not call `.build()`.**
+
+```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')
+```
+
+**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()` |
+
+### 2. Manual chain (headers, cookies, custom cases)
+
+Use when you need transport control or a schema-shaped body. Always end with `.build()`.
+
+```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()
+```
+
+**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 |
+
+---
+
+## 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())
+```
+
+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 |
+
+```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)
+  },
+})
+
+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')
+})
+```
+
+### Node HTTP
+
+```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)
+```
+
+### Bun HTTP
+
+Bun uses the Node adapter via `node:http` — same API:
+
+```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)
+```
+
+`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`:
+
+```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 } }),
+  )
+```
+
+Outside a request (e.g. startup log):
+
+```typescript
+console.log(
+  DTO.Log.level('info')
+    .service('api')
+    .env(NodeEnvEnum.PROD)
+    .message('Server listening')
+    .build(),
+)
+```
+
+### WebSocket
+
+```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')
+    },
+  },
+})
+```
+
+### 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 },
+})
+
+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)
+```
+
+---
+
+## Errors
+
+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()
+}
+```
+
+Built-in error types: `ClientError`, `ServerError`, `ValidationError`. Unknown errors are masked when `verbose: false`.
+
+---
+
+## Custom codes & HTTP status
+
+```typescript
+const dto = new DTO({ codes: { RATE_LIMITED: 4 } })
+
+return res.builder
+  .code(4)
+  .httpStatus(429)
+  .status(false)
+  .message('Too many requests')
+  .build()
+
+// Or when HTTP maps cleanly:
+return res.builder.as.tooManyRequests('Too many requests')
+```
+
+---
+
+## Release (maintainers)
+
+**Source of truth:** `package.json` `"version"`. Git tag must be **identical** — no env override.
+
+Format: `YY.MM.DD-vN` (e.g. `26.06.27-v8`).
+
+### Quick tag (commit already done)
+
+Bump `package.json`, commit, then:
+
+```bash
+npm run tag
+```
+
+Reads version from **committed** `package.json`, tags **current commit**, pushes branch + tag → Publish workflow runs.
+
+### Full release (lint + test + build + commit + tag)
+
+```bash
+# 1. Bump version in package.json
+# 2. Run everything:
+npm run release
+```
+
+| 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