@dangao/bun-server 1.12.1 → 2.0.1

package/docs/best-practices.md

@@ -1,12 +1,87 @@
-# Best Practices (English Draft)
+# Best Practices
 
-The Chinese document (`docs/best-practices.md`) is the source of truth. This file lists the
-main topics that still need translation:
+**English** | [中文](./zh/best-practices.md)
 
-- Coding conventions & comment style
-- Logger usage (English-only requirement)
-- Recommended middleware layering
+---
+
+## AI Best Practices (v2.0.0)
+
+### Use Ollama for Local Development
+
+Avoid API costs during development by defaulting to Ollama:
+
+```typescript
+AiModule.forRoot({
+  providers: [
+    { name: 'ollama', provider: OllamaProvider, config: {}, default: true },  // Free, local
+    { name: 'openai', provider: OpenAIProvider, config: { apiKey: env.OPENAI_API_KEY! } },
+  ],
+  fallback: true,  // Fallback to OpenAI if Ollama unavailable
+});
+```
+
+### Cache AI Responses
+
+Combine AiModule with CacheModule to reduce redundant LLM calls:
+
+```typescript
+const cacheKey = `ai:${createHash('md5').update(JSON.stringify(messages)).digest('hex')}`;
+const cached = await cacheService.getOrSet(cacheKey, () => aiService.complete({ messages }), 300_000);
+```
+
+### Track Token Usage
+
+Monitor costs by logging `response.usage`:
+
+```typescript
+const response = await aiService.complete({ messages });
+metricsService.increment('ai.tokens.total', response.usage.totalTokens);
+metricsService.gauge('ai.cost.usd', response.usage.estimatedCostUsd ?? 0);
+```
+
+### Always Guard User Input in Production
+
+```typescript
+// Check before processing
+const safeInput = await guardService.checkOrThrow(userMessage);
+
+// Or at the controller level
+@POST('/chat')
+@AiGuard({ piiDetection: true, promptInjection: true })
+async chat(@Body() body: { message: string }) { ... }
+```
+
+### Streaming Pattern
+
+Keep streaming responses consistent:
+
+```typescript
+@POST('/stream')
+stream(@Body() body: { message: string }): Response {
+  return new Response(
+    this.aiService.stream({ messages: [{ role: 'user', content: body.message }] }),
+    { headers: { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache' } },
+  );
+}
+```
+
+### RAG Chunking Strategy
+
+Choose chunker based on content type:
+
+- **`TextChunker`** — plain text, prose documents
+- **`MarkdownChunker`** — `.md`/`.mdx` files (splits by headings)
+
+Tune `chunkSize` (512 chars recommended) and `topK` (3-5 usually sufficient).
+
+---
+
+## General Best Practices
+
+See [Chinese best-practices.md](./zh/best-practices.md) for the full guide covering:
+
+- Coding conventions and comment style
+- Logger usage recommendations
+- Middleware layering patterns
 - Testing strategy
 - Benchmark workflow
-
-Help us by submitting translations or summaries for each section.

package/docs/database.md

@@ -0,0 +1,23 @@
+# Database
+
+This page summarizes database-related documentation in Bun Server Framework.
+
+## Core Database Capabilities
+
+- `DatabaseModule`: connection management, health checks, and SQL access.
+- ORM support: entity metadata, repositories, and query helpers.
+- Transactions: declarative transaction boundaries and rollback handling.
+
+## Recommended Reading
+
+- [API Reference](./api.md)
+- [Best Practices](./best-practices.md)
+- [Testing](./testing.md)
+- [Migration Guide](./migration.md)
+
+## Typical Setup
+
+1. Configure `DatabaseModule.forRoot(...)` in the root module.
+2. Define entities/repositories per feature module.
+3. Use transactions for multi-step write operations.
+4. Add health checks and monitor connection pool metrics.

package/docs/guide.md

@@ -4,13 +4,15 @@ Covers key steps for building Bun Server applications from scratch.
 
 ## Request Lifecycle Overview
 
-Before diving into implementation details, it's helpful to understand how Bun Server processes requests:
+Before diving into implementation details, it's helpful to understand how Bun
+Server processes requests:
 
 ```
 HTTP Request → Middleware → Security → Router → Interceptors(Pre) → Validation → Handler → Interceptors(Post) → Exception Filter → HTTP Response
 ```
 
-For detailed lifecycle documentation, see [Request Lifecycle](./request-lifecycle.md).
+For detailed lifecycle documentation, see
+[Request Lifecycle](./request-lifecycle.md).
 
 ## 1. Initialize Application
 
@@ -48,8 +50,8 @@ Use `ContextService` to access the current request context in services:
 
 ```ts
 import {
-  ContextService,
   CONTEXT_SERVICE_TOKEN,
+  ContextService,
   Inject,
   Injectable,
 } from "@dangao/bun-server";
@@ -57,7 +59,8 @@ import {
 @Injectable()
 class UserService {
   public constructor(
-    @Inject(CONTEXT_SERVICE_TOKEN) private readonly contextService: ContextService,
+    @Inject(CONTEXT_SERVICE_TOKEN) private readonly contextService:
+      ContextService,
   ) {}
 
   public getCurrentUser() {
@@ -779,7 +782,8 @@ class UserController {
 
 ## 16. Guards
 
-Guards provide fine-grained access control for your routes. They execute after middleware and before interceptors, deciding whether a request should proceed.
+Guards provide fine-grained access control for your routes. They execute after
+middleware and before interceptors, deciding whether a request should proceed.
 
 ### Built-in Guards
 
@@ -848,17 +852,18 @@ For detailed documentation, see [Guards](./guards.md).
 
 ## 17. Event System
 
-The Event Module provides a powerful event-driven architecture for building loosely coupled applications.
+The Event Module provides a powerful event-driven architecture for building
+loosely coupled applications.
 
 ### Basic Usage
 
 ```ts
 import {
+  EVENT_EMITTER_TOKEN,
   EventModule,
-  Injectable,
   Inject,
+  Injectable,
   OnEvent,
-  EVENT_EMITTER_TOKEN,
 } from "@dangao/bun-server";
 import type { EventEmitter } from "@dangao/bun-server";
 
@@ -958,7 +963,9 @@ For detailed documentation, see [Event System](./events.md).
 
 ## 18. Global Modules
 
-Global modules allow you to share providers across all modules without explicit imports. This is useful for commonly used services like configuration, logging, or caching.
+Global modules allow you to share providers across all modules without explicit
+imports. This is useful for commonly used services like configuration, logging,
+or caching.
 
 ### Creating a Global Module
 
@@ -991,7 +998,8 @@ class GlobalConfigModule {}
 
 ### Using Global Module Exports
 
-Other modules can use the exported providers without importing the global module:
+Other modules can use the exported providers without importing the global
+module:
 
 ```ts
 @Injectable()
@@ -1014,7 +1022,8 @@ class UserModule {}
 
 ### Registering Global Modules
 
-Global modules must be registered with the application, typically in your root module:
+Global modules must be registered with the application, typically in your root
+module:
 
 ```ts
 @Module({
@@ -1033,10 +1042,14 @@ app.registerModule(AppModule);
 
 ### Key Points
 
-- **Single Registration**: Global modules only need to be registered once (usually in the root module)
-- **Automatic Availability**: Exports from global modules are available to all other modules
-- **Singleton Sharing**: Global module providers maintain singleton behavior across the application
-- **No Import Required**: Other modules don't need to add global modules to their `imports` array
+- **Single Registration**: Global modules only need to be registered once
+  (usually in the root module)
+- **Automatic Availability**: Exports from global modules are available to all
+  other modules
+- **Singleton Sharing**: Global module providers maintain singleton behavior
+  across the application
+- **No Import Required**: Other modules don't need to add global modules to
+  their `imports` array
 
 ### Use Cases
 
@@ -1077,14 +1090,16 @@ class AppService {
 
 ## 19. Microservice Support
 
-Bun Server provides comprehensive microservice architecture support, including configuration center, service registry, service client, governance, and observability.
+Bun Server provides comprehensive microservice architecture support, including
+configuration center, service registry, service client, governance, and
+observability.
 
 ### Configuration Center
 
 ```ts
 import {
-  ConfigCenterModule,
   CONFIG_CENTER_TOKEN,
+  ConfigCenterModule,
   Inject,
   Injectable,
 } from "@dangao/bun-server";
@@ -1119,10 +1134,7 @@ class ConfigService {
 ### Service Registry
 
 ```ts
-import {
-  RegisterService,
-  ServiceRegistryModule,
-} from "@dangao/bun-server";
+import { RegisterService, ServiceRegistryModule } from "@dangao/bun-server";
 
 ServiceRegistryModule.forRoot({
   provider: "nacos",
@@ -1149,11 +1161,7 @@ class MyService {
 ### Service Client
 
 ```ts
-import {
-  ServiceClient,
-  ServiceCall,
-  Injectable,
-} from "@dangao/bun-server";
+import { Injectable, ServiceCall, ServiceClient } from "@dangao/bun-server";
 
 @Injectable()
 class OrderService {
@@ -1169,7 +1177,62 @@ class OrderService {
 
 For detailed documentation, see [Microservice Architecture](./microservice.md).
 
-## 20. Testing Recommendations
+## 20. AI Modules (v2.0.0)
+
+Starting from v2.0.0, the framework includes 9 official AI modules for building
+LLM-powered applications.
+
+### Quick Setup
+
+```typescript
+import {
+  AiGuardModule, // Content safety
+  AiModule,
+  ConversationModule,
+  MemoryConversationStore, // Conversation memory
+  OllamaProvider, // LLM access
+  RagModule, // RAG pipeline
+} from "@dangao/bun-server";
+
+AiModule.forRoot({
+  providers: [{
+    name: "ollama",
+    provider: OllamaProvider,
+    config: {},
+    default: true,
+  }],
+  fallback: true,
+});
+
+ConversationModule.forRoot({
+  store: new MemoryConversationStore(),
+  maxMessages: 50,
+});
+AiGuardModule.forRoot({
+  piiDetection: true,
+  promptInjection: { sensitivity: "medium" },
+});
+```
+
+See [AI Modules Documentation](./ai.md) for the complete guide covering all 9
+modules.
+
+### AI Modules at a Glance
+
+| Module               | Purpose                                      |
+| -------------------- | -------------------------------------------- |
+| `AiModule`           | LLM providers, streaming, Tool Calling       |
+| `ConversationModule` | Multi-turn conversation memory               |
+| `PromptModule`       | Prompt templates with variable interpolation |
+| `EmbeddingModule`    | Text embedding generation                    |
+| `VectorStoreModule`  | Vector similarity search                     |
+| `RagModule`          | Full RAG pipeline                            |
+| `McpModule`          | MCP protocol server                          |
+| `AiGuardModule`      | PII detection, content moderation            |
+
+---
+
+## 21. Testing Recommendations
 
 - Use `tests/utils/test-port.ts` to get auto-incrementing ports, avoiding local
   conflicts.

package/docs/migration.md

@@ -1,10 +1,84 @@
-# Migration Guide (English Draft)
+# Migration Guide
 
-A full translation of `docs/migration.md` is in progress. Planned sections:
+**English** | [中文](./zh/migration.md)
 
-- Migrating from Express / Koa / NestJS
-- Moving from Node.js to Bun
-- Updating legacy middleware
-- Breaking changes per release
+---
 
-Please consult the Chinese version for now. If you would like to help, open an issue or PR.
+## v1.x → v2.0
+
+v2.0.0 is **fully backward compatible** with v1.x. All existing modules, APIs, and patterns continue to work without changes.
+
+### What's New
+
+v2.0.0 adds 9 official AI modules as purely additive features:
+
+- `AiModule` — LLM unified access + Tool Calling + streaming
+- `ConversationModule` — Multi-turn conversation history
+- `PromptModule` — Prompt templates + versioning
+- `EmbeddingModule` — Text embedding generation
+- `VectorStoreModule` — Vector similarity search
+- `RagModule` — Full RAG pipeline
+- `McpModule` — MCP protocol server
+- `AiGuardModule` — Content safety
+
+See [AI Modules Guide](./ai.md) for full documentation.
+
+### No Breaking Changes
+
+No existing code needs modification. Simply update the package:
+
+```bash
+bun add @dangao/bun-server@2.0.0
+```
+
+---
+
+## Migrating from Express / Koa / NestJS
+
+Please see the Chinese migration guide (`docs/zh/migration.md`) for detailed migration instructions from:
+
+- Express.js
+- Koa.js
+- NestJS
+- Node.js (to Bun Runtime)
+
+---
+
+## Migrating from Node.js to Bun Runtime
+
+Key differences when switching from Node.js:
+
+1. **No `require()` / CommonJS** — use `import` / ESM exclusively
+2. **Use Bun APIs** — prefer `Bun.file()`, `Bun.serve()`, `Bun.SQL` over Node equivalents
+3. **TypeScript natively supported** — no compilation step needed for development
+4. **Engine**: JavaScriptCore instead of V8 — performance characteristics differ
+5. **Package manager**: use `bun install` instead of `npm install`
+
+```bash
+# Install Bun
+curl -fsSL https://bun.sh/install | bash
+
+# Convert project
+bun install  # reads existing package.json
+bun run src/index.ts  # runs TypeScript directly
+```
+
+---
+
+## Breaking Changes by Release
+
+### v2.0.0
+
+No breaking changes. Purely additive AI module additions.
+
+### v1.9.0
+
+- `EventModule`: `@OnEvent()` listener classes are now auto-scanned at `app.listen()`. Remove manual calls to `EventModule.initializeListeners()` if present.
+
+### v1.8.0
+
+- `ClusterManager` API: `ClusterManager.start()` now accepts options object instead of positional arguments.
+
+### v1.2.0
+
+- `ContextService.getContext()` now returns `Context | undefined` instead of throwing. Update callers to handle `undefined`.

package/docs/security.md

@@ -0,0 +1,23 @@
+# Security
+
+This page summarizes security-related documentation in Bun Server Framework.
+
+## Core Security Modules
+
+- `SecurityModule`: authentication flow, authorization checks, guard integration.
+- `auth` module: JWT/OAuth2 providers and token processing.
+- Guards: route-level access control and role checks.
+
+## Recommended Reading
+
+- [API Reference](./api.md)
+- [Guards](./guards.md)
+- [Best Practices](./best-practices.md)
+- [Error Handling](./error-handling.md)
+
+## Typical Setup
+
+1. Configure `SecurityModule.forRoot(...)` in the root module.
+2. Apply `@Auth()` / guards on protected routes.
+3. Keep secrets in environment variables, never in source code.
+4. Add request logging and rate limiting for sensitive endpoints.