@dangao/bun-server 2.3.0 → 3.0.1

package/docs/platform.md

@@ -0,0 +1,299 @@
+# Platform Adapter Guide
+
+**English** | [中文](./zh/platform.md)
+
+---
+
+Bun Server runs natively on **Bun** and **Node.js 22+** through an internal Platform Adapter Layer. All runtime-specific APIs (HTTP server, file I/O, crypto, parsers, process management, WebSocket) are abstracted behind unified TypeScript interfaces. You write one codebase; the framework picks the right implementation at startup — no extra configuration required.
+
+## Table of Contents
+
+- [Architecture](#architecture)
+- [Runtime Detection](#runtime-detection)
+- [Platform Configuration](#platform-configuration)
+- [Support Matrix](#support-matrix)
+- [Database Auto-Adaptation](#database-auto-adaptation)
+- [Public API Changes](#public-api-changes)
+- [Bun-Exclusive Features](#bun-exclusive-features)
+- [Node.js Startup Guide](#nodejs-startup-guide)
+- [Testing on Multiple Runtimes](#testing-on-multiple-runtimes)
+- [Known Limitations](#known-limitations)
+
+---
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────────────┐
+│                  Application Layer                    │
+│   Controllers / Services / Modules / Middleware       │
+└──────────────────────────┬───────────────────────────┘
+                           │ getRuntime()
+┌──────────────────────────▼───────────────────────────┐
+│              Platform Adapter Layer                   │
+│  IFsAdapter · ICryptoAdapter · IParserAdapter         │
+│  IProcessAdapter · IHttpDriver · IWebSocket           │
+└──────┬───────────────────────────────┬───────────────┘
+       │                               │
+┌──────▼──────┐                 ┌──────▼──────┐
+│ BunPlatform │                 │ NodePlatform│
+│ Bun.serve   │                 │ node:http   │
+│ Bun.file    │                 │ node:fs     │
+│ Bun.Crypto  │                 │ node:crypto │
+│ spawn(bun)  │                 │ ws package  │
+└─────────────┘                 └─────────────┘
+```
+
+Each adapter surface has a corresponding TypeScript interface:
+
+| Interface | Bun Implementation | Node.js Implementation |
+|---|---|---|
+| `IFsAdapter` | `Bun.file`, `Bun.write`, `Bun.Glob` | `node:fs/promises`, `node:fs` glob |
+| `ICryptoAdapter` | `Bun.CryptoHasher` | `node:crypto` HMAC/hash |
+| `IParserAdapter` | `Bun.JSONC`, `Bun.JSON5`, `Bun.JSONL`, `Bun.markdown` | `jsonc-parser`, `json5`, custom JSONL, `marked` |
+| `IProcessAdapter` | `spawn` (bun), `Bun.sleep` | `node:child_process`, `setTimeout` |
+| `IHttpDriver` | `Bun.serve` | `node:http.createServer` |
+| `IWebSocket<T>` | `Bun.ServerWebSocket<T>` | `ws` package |
+
+---
+
+## Runtime Detection
+
+Platform is resolved at `Application` construction time following this priority chain:
+
+```
+1. Bootstrap config  →  new Application({ platform: 'node' })
+2. CLI argument      →  --platform=node
+3. Environment var   →  BUN_SERVER_PLATFORM=node
+4. Auto-detect       →  typeof Bun !== 'undefined' ? 'bun' : 'node'
+```
+
+Once resolved, the singleton is frozen for the lifetime of the process. Subsequent calls to `getRuntime()` return the same instance.
+
+---
+
+## Platform Configuration
+
+### Option 1 — Code (highest priority)
+
+```typescript
+import { Application } from '@dangao/bun-server';
+
+const app = new Application({ platform: 'node' }); // 'bun' | 'node'
+app.registerModule(AppModule);
+await app.listen(3000);
+```
+
+### Option 2 — CLI argument
+
+```bash
+# Bun runtime, but force Node.js adapter
+bun run src/main.ts --platform=node
+
+# Node.js runtime (auto-detected even without the flag)
+node dist/main.js
+```
+
+### Option 3 — Environment variable
+
+```bash
+BUN_SERVER_PLATFORM=node node dist/main.js
+```
+
+### Option 4 — Auto-detect (default)
+
+No configuration needed. If `typeof Bun !== 'undefined'`, `BunPlatform` is selected; otherwise `NodePlatform` is selected automatically.
+
+---
+
+## Support Matrix
+
+| Feature | Bun | Node.js 22+ |
+|---|---|---|
+| HTTP server | `Bun.serve` (native) | `node:http` |
+| WebSocket | `Bun.ServerWebSocket` (native) | `ws` package |
+| File I/O | `Bun.file / Bun.write` | `node:fs/promises` |
+| Crypto / JWT | `Bun.CryptoHasher` | `node:crypto` |
+| JSONC parsing | `Bun.JSONC` | `jsonc-parser` package |
+| JSON5 parsing | `Bun.JSON5` | `json5` package |
+| JSONL parsing | `Bun.JSONL` | Custom streaming parser |
+| Markdown render | `Bun.markdown` | `marked` package |
+| Cluster spawn | Bun `spawn` | `node:child_process` |
+| SQLite | `bun:sqlite` | `better-sqlite3` |
+| PostgreSQL | `Bun.SQL` | `postgres` package |
+| MySQL | `Bun.SQL` | `mysql2` package |
+| `idleTimeout` | Yes | Silently ignored |
+| `reusePort` | Yes | Silently ignored |
+| SSE TCP keepalive | Yes (via `server.timeout`) | Not available |
+| Overall performance | Optimal | Good |
+
+---
+
+## Database Auto-Adaptation
+
+`DatabaseModule` automatically selects drivers based on the detected platform. **No additional user configuration is required.**
+
+```
+Bun platform                     Node.js platform
+─────────────────────────────    ─────────────────────────────
+SQLite  →  bun:sqlite            SQLite  →  better-sqlite3
+PostgreSQL  →  Bun.SQL           PostgreSQL  →  postgres package
+MySQL  →  Bun.SQL                MySQL  →  mysql2 package
+```
+
+Your `DatabaseModule` configuration remains identical across platforms:
+
+```typescript
+DatabaseModule.forRoot({
+  connections: [
+    {
+      name: 'default',
+      type: 'sqlite',
+      database: './data/app.db',
+    },
+    {
+      name: 'pg',
+      type: 'postgres',
+      url: process.env.DATABASE_URL,
+    },
+  ],
+})
+```
+
+---
+
+## Public API Changes
+
+### `BunServer.getServer()`
+
+Returns `IServerHandle | undefined` (previously `Bun.Server | undefined`).
+
+```typescript
+const handle: IServerHandle | undefined = app.getServer();
+handle?.port;      // number
+handle?.hostname;  // string
+await handle?.stop();
+
+// Access the raw underlying server (not recommended — type is unknown)
+const native: unknown = app.getNativeServer();
+// Bun:    native as Bun.Server<any>
+// Node.js: native as import('node:http').Server
+```
+
+### `WsArgumentsHost.getClient()`
+
+Returns `IWebSocket<T>` instead of Bun's `ServerWebSocket<T>`. This is the only breaking WebSocket API change.
+
+```typescript
+import type { IWebSocket } from '@dangao/bun-server';
+
+@WebSocketGateway()
+class ChatGateway {
+  @OnMessage('chat')
+  onChat(client: IWebSocket<unknown>, data: unknown) {
+    client.send('pong');
+  }
+}
+```
+
+`IWebSocket<T>` exposes the same core methods as `ServerWebSocket<T>`:
+`send`, `close`, `data`, `readyState`, `remoteAddress`.
+
+---
+
+## Bun-Exclusive Features
+
+The following options are accepted in `ApplicationOptions` but only take effect on Bun. They are silently ignored on Node.js.
+
+| Option | Effect on Bun | Node.js |
+|---|---|---|
+| `idleTimeout` | TCP idle timeout via `Bun.serve` | Ignored |
+| `reusePort` | Port reuse via `Bun.serve` | Ignored |
+| `sseKeepAlive` | Uses `server.timeout(req, 0)` | Heartbeat injection only |
+
+If your application relies on these features, document the Bun runtime requirement explicitly.
+
+---
+
+## Node.js Startup Guide
+
+### 1. Install
+
+```bash
+npm install @dangao/bun-server
+# Node.js peer dependencies are included automatically
+```
+
+### 2. Build
+
+```bash
+# Compile TypeScript to plain JS targeting Node.js
+bun build src/main.ts --target=node --outdir=dist
+
+# Or use tsc:
+npx tsc
+```
+
+### 3. Run
+
+```bash
+node dist/main.js
+# Platform auto-detected as 'node' — no extra flags needed
+```
+
+### 4. Smoke test (verify bun build output runs on Node.js)
+
+```bash
+bun run test:node
+# Runs: vitest run tests/platform/node
+```
+
+---
+
+## Testing on Multiple Runtimes
+
+Shared test cases live in `tests/platform/shared/*.cases.ts`. Both Bun and Node.js runners import the same assertions, guaranteeing identical coverage.
+
+```
+tests/platform/
+├── shared/
+│   ├── suite.ts              ← TestSuite interface (test / expect / beforeEach)
+│   ├── fs.cases.ts
+│   ├── crypto.cases.ts
+│   ├── parser.cases.ts
+│   ├── process.cases.ts
+│   ├── websocket.cases.ts
+│   └── database.cases.ts
+├── bun/                      ← bun:test runners
+│   └── *.test.ts
+├── node/                     ← vitest runners
+│   ├── *.test.ts
+│   └── build-smoke.test.ts   ← verifies bun build --target=node output
+└── detector.test.ts          ← priority chain unit tests
+```
+
+### Run tests
+
+```bash
+# Bun platform tests
+bun run test:bun
+
+# Node.js platform tests
+bun run test:node
+
+# Both platforms
+bun run test:platform
+```
+
+---
+
+## Known Limitations
+
+| Limitation | Details |
+|---|---|
+| `idleTimeout` / `reusePort` | Bun-only; no Node.js equivalent |
+| SSE TCP keepalive (`server.timeout`) | Bun-only API; Node.js gets heartbeat injection only |
+| `Bun.SQL` features | Some advanced Bun.SQL options (e.g., prepared statement caching) are unavailable in `postgres` / `mysql2` |
+| Cluster mode on Node.js | Uses `node:child_process`; may behave differently from Bun's cluster |
+| `bun:sqlite` extensions | Bun SQLite supports extensions; `better-sqlite3` extension loading differs |
+| Performance | Bun native APIs outperform Node.js polyfills, especially for file I/O and crypto |

package/docs/testing.md

@@ -72,6 +72,66 @@ await client.close();
 
 Options support `headers`, `body`, and `query`.
 
+## Multi-Runtime Testing
+
+The framework ships with a shared test strategy that runs the same test cases on both Bun and Node.js.
+
+### Test Structure
+
+```
+tests/platform/
+├── shared/          ← platform-neutral assertion helpers
+│   ├── suite.ts     ← TestSuite interface (test / expect / beforeEach)
+│   ├── fs.cases.ts
+│   ├── crypto.cases.ts
+│   ├── parser.cases.ts
+│   ├── process.cases.ts
+│   ├── websocket.cases.ts
+│   └── database.cases.ts
+├── bun/             ← bun:test runners (initRuntime('bun'))
+│   └── *.test.ts
+└── node/            ← vitest runners (initRuntime('node'))
+    ├── *.test.ts
+    └── build-smoke.test.ts
+```
+
+### Running Platform Tests
+
+```bash
+# Bun platform tests only
+bun run test:bun
+
+# Node.js platform tests only (uses vitest)
+bun run test:node
+
+# Both platforms
+bun run test:platform
+```
+
+### Writing Tests that Work on Both Runtimes
+
+Always call `initRuntime()` at the start of your test file:
+
+```ts
+// tests/platform/bun/fs.test.ts
+import { describe, test, expect, beforeEach } from 'bun:test';
+import { initRuntime, _resetRuntime } from '../../../src/platform/runtime';
+import { runFsCases } from '../shared/fs.cases';
+
+initRuntime('bun');
+runFsCases({ test, expect, beforeEach });
+```
+
+```ts
+// tests/platform/node/fs.test.ts
+import { describe, test, expect, beforeEach } from 'vitest';
+import { initRuntime, _resetRuntime } from '../../../src/platform/runtime';
+import { runFsCases } from '../shared/fs.cases';
+
+beforeEach(() => { _resetRuntime(); initRuntime('node'); });
+runFsCases({ test, expect, beforeEach });
+```
+
 ## Example with bun:test
 
 ```ts

package/docs/zh/deployment.md

@@ -1,10 +1,11 @@
 # 生产部署指南
 
-本文档介绍将 Bun Server Framework 应用部署到生产环境的最佳实践。
+本文档介绍将 Bun Server Framework 应用部署到生产环境的最佳实践。框架同时支持 **Bun**（最优性能）和 **Node.js 22+** 运行时，请根据基础设施选择合适的方案。
 
 ## 目录
 
 - [前置要求](#前置要求)
+- [运行时选择](#运行时选择)
 - [环境设置](#环境设置)
 - [配置](#配置)
 - [进程管理](#进程管理)
@@ -15,23 +16,45 @@
 
 ## 前置要求
 
-- Bun runtime（最新稳定版本）
-- Node.js 18+（用于兼容性）
-- 生产级数据库（PostgreSQL、MySQL 等）
+- **Bun** >= 1.3.10（Bun 部署方案）**或** **Node.js** >= 22.0.0（Node.js 部署方案）
+- 生产级数据库（PostgreSQL、MySQL、SQLite 等）
 - 反向代理（Nginx、Caddy 等）
 
+## 运行时选择
+
+| 维度 | Bun | Node.js |
+|---|---|---|
+| 性能 | 最优（原生 API） | 良好 |
+| 生态成熟度 | 持续增长 | 成熟 |
+| Docker 镜像 | `oven/bun` | `node:22-alpine` |
+| `idleTimeout` / `reusePort` | 支持 | 不可用 |
+| 推荐场景 | 新项目、延迟敏感型应用 | 已有 Node.js 基础设施 |
+
+框架在启动时自动检测运行时。详见[平台适配指南](./platform.md)。
+
 ## 环境设置
 
-### 安装 Bun
+### 方案 A — Bun 运行时
 
 ```bash
-# 在 Linux/macOS 上
+# 安装 Bun（Linux/macOS）
 curl -fsSL https://bun.sh/install | bash
 
-# 验证安装
+# 验证
 bun --version
 ```
 
+### 方案 B — Node.js 运行时
+
+```bash
+# 使用 Node.js 22+（LTS）
+node --version  # 应为 v22+
+
+# 构建 TypeScript 为 JS
+bun build src/main.ts --target=node --outdir=dist
+# 或：npx tsc
+```
+
 ### 设置环境变量
 
 创建 `.env.production` 文件：

package/docs/zh/idle-timeout.md

@@ -1,13 +1,15 @@
 # idleTimeout 与 SSE 保活
 
+> **平台说明：** `idleTimeout`、`reusePort` 以及基于 `server.timeout` 的 SSE TCP 保活是 **Bun 独有**特性，在 Node.js 上会被静默忽略。`@IdleTimeout(ms)` 装饰器（handler 级超时）在两个平台均可用。详见[平台适配指南](./platform.md#bun-独有特性)。
+
 ## 两层超时机制
 
 Bun Server 有**两套独立的超时机制**——理解它们的区别对 SSE / 流式场景至关重要。
 
-| 层面 | 配置方式 | 作用域 | 机制 |
-|------|----------|--------|------|
-| **TCP 连接级** | `Application({ idleTimeout })` | Bun.serve 底层 | Bun 内核在连接无数据流动 N 秒后直接断开 socket |
-| **Handler 逻辑级** | `@IdleTimeout(ms)` 装饰器 | 路由粒度的 `Promise.race` | handler 未在指定时间内 resolve 则返回 `408 Request Timeout` |
+| 层面 | 配置方式 | 作用域 | 机制 | Bun | Node.js |
+|------|----------|--------|------|-----|---------|
+| **TCP 连接级** | `Application({ idleTimeout })` | Bun.serve 底层 | Bun 内核在连接无数据流动 N 秒后直接断开 socket | 支持 | 忽略 |
+| **Handler 逻辑级** | `@IdleTimeout(ms)` 装饰器 | 路由粒度的 `Promise.race` | handler 未在指定时间内 resolve 则返回 `408 Request Timeout` | 支持 | 支持 |
 
 > **关键：** 对于 SSE 响应，handler 会立即返回一个带流式 body 的 `Response`。此时 handler 层面的 `@IdleTimeout` 已经 resolve，**不会**保护或终止该流。只有 TCP 级别的 `idleTimeout` 才能断开 SSE 连接。
 

package/docs/zh/migration.md

@@ -2,6 +2,48 @@
 
 适用于从项目早期版本或其他框架迁移到最新 Bun Server Framework 的场景。
 
+## v2.x → v3.0（平台适配层）
+
+v3.0.0 引入 **Platform Adapter Layer**，在保留 Bun 最优性能的同时支持 Node.js 22+。
+
+### 破坏性变更
+
+| 变更点 | 之前 | 之后 |
+|---|---|---|
+| `BunServer.getServer()` 返回类型 | `Bun.Server \| undefined` | `IServerHandle \| undefined` |
+| `WsArgumentsHost.getClient()` 返回类型 | `ServerWebSocket<T>` | `IWebSocket<T>` |
+
+### 迁移步骤
+
+**1. 更新 WebSocket 守卫类型**
+
+```typescript
+// 之前
+import type { ServerWebSocket } from 'bun';
+getClient(): ServerWebSocket<unknown>
+
+// 之后
+import type { IWebSocket } from '@dangao/bun-server';
+getClient(): IWebSocket<unknown>
+```
+
+**2. 更新服务器句柄访问**
+
+```typescript
+// 之前
+const server: Bun.Server | undefined = app.getServer();
+
+// 之后
+import type { IServerHandle } from '@dangao/bun-server';
+const server: IServerHandle | undefined = app.getServer();
+// 原生访问（不推荐，类型为 unknown）：
+const native: unknown = app.getNativeServer();
+```
+
+**3. 其他均向后兼容。** 数据库配置、模块 API、控制器、服务和中间件无需修改。
+
+---
+
 ## 1. 项目结构调整
 
 - 统一入口到 `src/index.ts`，示例项目可放在 `examples/`。