message-nexus 1.0.0 → 1.1.0

package/README.md

@@ -1,8 +1,8 @@
 # message-nexus
 
-一个统一、类型安全、支持多种传输协议的跨上下文消息通信库。
+A unified, type-safe cross-context message communication library supporting multiple transport protocols.
 
-## 安装
+## Installation
 
 ```bash
 npm install message-nexus
@@ -10,170 +10,198 @@ npm install message-nexus
 pnpm add message-nexus
 ```
 
-## 特性
+## Features
 
-- **统一接口**: 支持 Mitt（进程内）、PostMessage（iframe/window 间）、BroadcastChannel（跨标签页）、WebSocket（网络通信）
-- **类型安全**: 完整的 TypeScript 支持，泛型类型推断
-- **请求-响应模式**: Promise 风格的异步通信，内置超时保护
-- **自动重连**: WebSocket 自动重连机制，支持指数退避
-- **消息队列**: 离线消息缓存，连接恢复后自动发送
-- **重试机制**: 请求失败自动重试，可配置重试次数和延迟
-- **消息验证**: 运行时消息格式验证，防止非法消息
-- **监控指标**: 内置消息统计和性能监控
-- **结构化日志**: 支持自定义日志处理器，便于调试和生产监控
-- **资源管理**: 所有 Driver 支持 `destroy()` 方法，正确清理资源
+- **Unified Interface**: Supports Mitt (in-process), PostMessage (iframe/window), BroadcastChannel (cross-tab), and WebSocket (network communication)
+- **JSON-RPC 2.0 Compliance**: Strict adherence to the JSON-RPC 2.0 specification for standardized communication
+- **Envelope Pattern**: Extensible message envelope containing routing information (from, to) and metadata
+- **Type Safety**: Full TypeScript support with generic type inference
+- **Request-Response Pattern**: Promise-style asynchronous communication with built-in timeout protection
+- **Auto Reconnect**: WebSocket automatic reconnection mechanism with exponential backoff support
+- **Message Queue**: Offline message caching, automatically sent after connection recovery
+- **Retry Mechanism**: Automatic retry on request failure, configurable retry counts and delays
+- **Message Validation**: Runtime message format validation to prevent illegal messages
+- **Monitoring Metrics**: Built-in message statistics and performance monitoring
+- **Structured Logging**: Supports custom log handlers for easy debugging and production monitoring
+- **Resource Management**: All drivers support the `destroy()` method to properly clean up resources.
 
-## 快速开始
+## Quick Start
 
-### 1. 进程内通信（Mitt）
+### 1. In-Process Communication (Mitt)
 
 ```typescript
-import mitt from 'mitt'
-import { MittDriver, MessageBridge } from 'message-nexus'
+import MessageNexus, { MittDriver, createEmitter } from 'message-nexus'
+
+// Shared emitter
+const emitter = createEmitter()
 
-const emitter = mitt()
 const driver = new MittDriver(emitter)
-const bridge = new MessageBridge(driver)
+const nexus = new MessageNexus(driver)
 
-// 发送请求
-const response = await bridge.request('GET_DATA', { id: 123 })
+// Send request
+const response = await nexus.invoke('GET_DATA', { id: 123 })
 console.log(response)
 
-// 监听命令
-const unsubscribe = bridge.onCommand((data) => {
-  if (data.type === 'GET_DATA') {
-    bridge.reply(data.id, { name: 'test', value: 42 })
-  }
+// Send one-way notification
+nexus.notify('UPDATE_STATUS', { status: 'active' })
+
+// Listen for commands
+const receiverDriver = new MittDriver(emitter)
+const receiverNexus = new MessageNexus(receiverDriver)
+const unsubscribe = receiverNexus.handle('GET_DATA', (params, context) => {
+  return { name: 'test', value: 42 }
+})
+
+// Listen for notifications
+const unsubscribeNotify = receiverNexus.onNotification('UPDATE_STATUS', (params, context) => {
+  console.log('Notification received:', params)
 })
 ```
 
-### 2. iframe/Window 通信（PostMessage）
+### 2. iframe/Window Communication (PostMessage)
 
 ```typescript
-import { PostMessageDriver, MessageBridge } from 'message-nexus'
+import MessageNexus, { PostMessageDriver } from 'message-nexus'
 
-// 发送方
+// Sender
 const driver = new PostMessageDriver(window.parent, 'https://example.com')
-const bridge = new MessageBridge(driver)
+const nexus = new MessageNexus(driver)
 
-const response = await bridge.request('PING')
+const response = await nexus.invoke('PING')
 console.log('Pong:', response)
 
-// 接收方
+// Receiver
 const iframeDriver = new PostMessageDriver(iframe.contentWindow, 'https://example.com')
-const iframeBridge = new MessageBridge(iframeDriver)
+const iframeNexus = new MessageNexus(iframeDriver)
 
-iframeBridge.onCommand((data) => {
-  if (data.type === 'PING') {
-    bridge.reply(data.id, { time: Date.now() })
-  }
+iframeNexus.handle('PING', (params, context) => {
+  return { time: Date.now() }
 })
 ```
 
-### 3. 跨标签页通信（BroadcastChannel）
+### 3. Cross-Tab Communication (BroadcastChannel)
 
 ```typescript
-import { BroadcastDriver, MessageBridge } from 'message-nexus'
+import MessageNexus, { BroadcastDriver } from 'message-nexus'
 
-// 创建 BroadcastDriver，指定频道名称
+// Create BroadcastDriver, specifying the channel name
 const driver = new BroadcastDriver({ channel: 'my-app-channel' })
-const bridge = new MessageBridge(driver)
+const nexus = new MessageNexus(driver)
 
-// 监听命令
-bridge.onCommand((data) => {
-  console.log('Received:', data.type, data.payload)
-  bridge.reply(data.id, { result: 'success' })
+// Listen for commands
+nexus.handle('SYNC_STATE', (params, context) => {
+  console.log('Received:', params)
+  return { result: 'success' }
 })
 
-// 发送请求（会在所有同频道的标签页中广播）
-const response = await bridge.request({
-  type: 'SYNC_STATE',
-  payload: { state: '...' },
+// Send request (will be broadcast to all tabs on the same channel)
+const response = await nexus.invoke({
+  method: 'SYNC_STATE',
+  params: { state: '...' },
 })
 
-// 清理资源
-bridge.destroy()
+// Receiver
+const receiverDriver = new BroadcastDriver({ channel: 'my-app-channel' })
+const receiverNexus = new MessageNexus(receiverDriver)
+receiverNexus.handle('SYNC_STATE', (params, context) => {
+  console.log('Received:', params)
+  return { result: 'success' }
+})
 ```
 
-### 4. WebSocket 通信
+### 4. WebSocket Communication
 
 ```typescript
-import { WebSocketDriver, MessageBridge } from 'message-nexus'
+import MessageNexus, { WebSocketDriver } from 'message-nexus'
 
-// 自动重连配置
+// Automatic reconnection configuration
 const driver = new WebSocketDriver({
   url: 'wss://api.example.com/ws',
   reconnect: {
-    maxRetries: 5, // 最大重试次数
-    retryInterval: 3000, // 重试间隔（毫秒）
+    maxRetries: 5, // Maximum retry count
+    retryInterval: 3000, // Retry interval (milliseconds)
   },
 })
 
-const bridge = new MessageBridge(driver)
+const nexus = new MessageNexus(driver)
 
-// 发送请求
-const response = await bridge.request({
-  type: 'GET_USER',
-  payload: { userId: 123 },
+// Send request
+const response = await nexus.invoke({
+  method: 'GET_USER',
+  params: { userId: 123 },
   timeout: 5000,
-  retryCount: 3, // 失败重试 3 次
-  retryDelay: 1000, // 重试延迟
+  retryCount: 3, // Retry 3 times on failure
+  retryDelay: 1000, // Retry delay
+})
+
+// Receiver
+const receiverDriver = new WebSocketDriver({
+  url: 'wss://api.example.com/ws',
+  reconnect: {
+    maxRetries: 5, // Maximum retry count
+    retryInterval: 3000, // Retry interval (milliseconds)
+  },
+})
+const receiverNexus = new MessageNexus(receiverDriver)
+receiverNexus.handle('SYNC_STATE', (params, context) => {
+  console.log('Received:', params)
+  return { result: 'success' }
 })
 ```
 
-## API 文档
+## API Documentation
 
-### MessageBridge
+### MessageNexus
 
-#### 构造函数
+#### Constructor
 
 ```typescript
-new MessageBridge<RequestPayload, ResponsePayload>(
+new MessageNexus<RequestPayload, ResponsePayload>(
   driver: BaseDriver,
-  options?: MessageBridgeOptions
+  options?: MessageNexusOptions
 )
 ```
 
 **Options:**
 
-| 参数       | 类型   | 默认值         | 说明                  |
-| ---------- | ------ | -------------- | --------------------- |
-| instanceId | string | auto-generated | 实例 ID，用于消息路由 |
-| timeout    | number | 10000          | 请求超时时间（毫秒）  |
-| logger     | Logger | new Logger()   | 日志实例              |
+| Parameter  | Type   | Default Value  | Description                           |
+| ---------- | ------ | -------------- | ------------------------------------- |
+| instanceId | string | auto-generated | Instance ID, used for message routing |
+| timeout    | number | 10000          | Request timeout (milliseconds)        |
+| logger     | Logger | new Logger()   | Logger instance                       |
 
-#### 方法
+#### Methods
 
-##### request()
+##### invoke()
 
-发送请求并等待响应。
+Send request and wait for response.
 
 ```typescript
-bridge.request(typeOrOptions: string | RequestOptions): Promise<ResponsePayload>
+nexus.invoke<T>(methodOrOptions: string | InvokeOptions): Promise<T>
 ```
 
 **Options:**
 
-| 参数       | 类型                    | 必填 | 说明                 |
-| ---------- | ----------------------- | ---- | -------------------- |
-| type       | string                  | 是   | 消息类型             |
-| payload    | unknown                 | 否   | 请求数据             |
-| to         | string                  | 否   | 目标实例 ID          |
-| metadata   | Record<string, unknown> | 否   | 元数据               |
-| timeout    | number                  | 否   | 超时时间（覆盖全局） |
-| retryCount | number                  | 否   | 失败重试次数         |
-| retryDelay | number                  | 否   | 重试延迟（毫秒）     |
+| Parameter  | Type                    | Required | Description                  |
+| ---------- | ----------------------- | -------- | ---------------------------- |
+| method     | string                  | Yes      | Message method               |
+| params     | unknown                 | No       | Request data                 |
+| to         | string                  | No       | Target instance ID           |
+| metadata   | Record<string, unknown> | No       | Metadata                     |
+| timeout    | number                  | No       | Timeout (overrides global)   |
+| retryCount | number                  | No       | Number of retries on failure |
+| retryDelay | number                  | No       | Retry delay (milliseconds)   |
 
-**示例：**
+**Example:**
 
 ```typescript
-// 简单请求
-const result = await bridge.request('FETCH_DATA')
+// Simple request
+const result = await nexus.invoke('FETCH_DATA')
 
-// 完整配置
-const result = await bridge.request({
-  type: 'FETCH_DATA',
-  payload: { id: 123 },
+// Full configuration
+const result = await nexus.invoke({
+  method: 'FETCH_DATA',
+  params: { id: 123 },
   to: 'target-instance',
   timeout: 5000,
   retryCount: 3,
@@ -181,90 +209,134 @@ const result = await bridge.request({
 })
 ```
 
-##### onCommand()
+##### notify()
+
+Send a one-way notification (Fire-and-Forget). Does not wait for a response and does not generate an ID. Complies with JSON-RPC 2.0 Notification specification.
+
+```typescript
+nexus.notify(methodOrOptions: string | Omit<InvokeOptions, 'timeout' | 'retryCount' | 'retryDelay'>): void
+```
+
+**Options:**
+
+| Parameter | Type                    | Required | Description         |
+| --------- | ----------------------- | -------- | ------------------- |
+| method    | string                  | Yes      | Notification method |
+| params    | unknown                 | No       | Notification data   |
+| to        | string                  | No       | Target instance ID  |
+| metadata  | Record<string, unknown> | No       | Metadata            |
 
-注册消息处理器。
+**Example:**
 
 ```typescript
-bridge.onCommand(handler: (data: CommandMessage) => void): () => void
+// Simple notification
+nexus.notify('HEARTBEAT')
+
+// Full configuration
+nexus.notify({
+  method: 'UPDATE_STATE',
+  params: { state: 'ready' },
+  to: 'target-instance',
+})
 ```
 
-**返回值:** 取消监听的函数
+##### handle()
 
-**示例：**
+Register a request handler for a specific method. The return value (or resolved value of a returned Promise) is automatically sent back as the response.
 
 ```typescript
-const unsubscribe = bridge.onCommand((data) => {
-  console.log('Received:', data.type, data.payload)
+nexus.handle<Params, Result>(method: string, handler: InvokeHandler<Params, Result>): () => void
+```
 
-  if (data.type === 'ECHO') {
-    bridge.reply(data.id, { echoed: data.payload })
-  }
+**Parameters:**
+
+- `method`: The method name to handle.
+- `handler`: A function that receives `(params, context)` and returns a result or a Promise.
+
+**InvokeContext:**
+
+| Property    | Type                      | Description                                     |
+| ----------- | ------------------------- | ----------------------------------------------- |
+| `messageId` | `string`                  | Unique identifier for the request (JSON-RPC ID) |
+| `from`      | `string`                  | Instance ID of the sender                       |
+| `to`        | `string`                  | Instance ID of the receiver (your instance ID)  |
+| `metadata`  | `Record<string, unknown>` | Custom metadata sent with the envelope          |
+
+**Example:**
+
+```typescript
+const unsubscribe = nexus.handle('ECHO', (params, context) => {
+  console.log(`Received ECHO from ${context.from}`)
+  return { echoed: params }
 })
 
-// 取消监听
+// Unsubscribe
 unsubscribe()
 ```
 
-##### reply()
+##### onNotification()
 
-回复传入消息。
+Register a handler for a specific notification method (one-way messages).
 
 ```typescript
-bridge.reply(messageId: string, payload: unknown, error?: unknown)
+nexus.onNotification<Params>(method: string, handler: NotificationHandler<Params>): () => void
 ```
 
-**示例：**
+**Example:**
 
 ```typescript
-bridge.reply('message-id-123', { success: true })
-bridge.reply('message-id-456', null, new Error('Invalid request'))
+const unsubscribe = nexus.onNotification('HEARTBEAT', (params, context) => {
+  console.log(`Heartbeat from ${context.from}`)
+})
+
+// Unsubscribe
+unsubscribe()
 ```
 
 ##### onError()
 
-注册错误处理器。
+Register error handler.
 
 ```typescript
-bridge.onError(handler: ErrorHandler): () => void
+nexus.onError(handler: ErrorHandler): () => void
 ```
 
-**示例：**
+**Example:**
 
 ```typescript
-bridge.onError((error, context) => {
+nexus.onError((error, context) => {
   console.error('Bridge error:', error.message, context)
-  // 发送到错误追踪服务
+  // Send to error tracking service
   Sentry.captureException(error, { extra: context })
 })
 ```
 
 ##### getMetrics()
 
-获取监控指标。
+Get monitoring metrics.
 
 ```typescript
-bridge.getMetrics(): Metrics
+nexus.getMetrics(): Metrics
 ```
 
-**返回值:**
+**Return Value:**
 
 ```typescript
 {
-  messagesSent: number // 发送消息数
-  messagesReceived: number // 接收消息数
-  messagesFailed: number // 失败消息数
-  pendingMessages: number // 待处理消息数
-  queuedMessages: number // 队列消息数
-  totalLatency: number // 总延迟（毫秒）
-  averageLatency: number // 平均延迟（毫秒）
+  messagesSent: number // Messages sent
+  messagesReceived: number // Messages received
+  messagesFailed: number // Messages failed
+  pendingMessages: number // Pending messages
+  queuedMessages: number // Queued messages
+  totalLatency: number // Total latency (milliseconds)
+  averageLatency: number // Average latency (milliseconds)
 }
 ```
 
-**示例：**
+**Example:**
 
 ```typescript
-const metrics = bridge.getMetrics()
+const metrics = nexus.getMetrics()
 console.log(`Avg latency: ${metrics.averageLatency}ms`)
 console.log(
   `Success rate: ${((metrics.messagesReceived / metrics.messagesSent) * 100).toFixed(2)}%`,
@@ -273,42 +345,42 @@ console.log(
 
 ##### onMetrics()
 
-注册指标变更回调。
+Register metrics change callback.
 
 ```typescript
-bridge.onMetrics(callback: MetricsCallback): () => void
+nexus.onMetrics(callback: MetricsCallback): () => void
 ```
 
-**示例：**
+**Example:**
 
 ```typescript
-const unsubscribe = bridge.onMetrics((metrics) => {
-  // 发送到监控系统
+const unsubscribe = nexus.onMetrics((metrics) => {
+  // Send to monitoring system
   metricsService.report(metrics)
 })
 ```
 
 ##### flushQueue()
 
-刷新消息队列，发送所有缓存的消息。
+Flush the message queue, sending all cached messages.
 
 ```typescript
-bridge.flushQueue()
+nexus.flushQueue()
 ```
 
 ##### destroy()
 
-销毁实例，清理资源。
+Destroy the instance and clean up resources.
 
 ```typescript
-bridge.destroy()
+nexus.destroy()
 ```
 
-**注意**: `destroy()` 方法会自动调用驱动的 `destroy()` 方法来清理事件监听器等资源。建议在组件卸载时调用此方法以避免内存泄漏。
+**Note**: The `destroy()` method automatically calls the driver's `destroy()` method to clean up resources like event listeners. It is recommended to call this method when the component is unmounted to avoid memory leaks.
 
 ### WebSocketDriver
 
-#### 构造函数
+#### Constructor
 
 ```typescript
 new WebSocketDriver(options: WebSocketDriverOptions)
@@ -316,20 +388,20 @@ new WebSocketDriver(options: WebSocketDriverOptions)
 
 **Options:**
 
-| 参数      | 类型                        | 默认值       | 说明          |
-| --------- | --------------------------- | ------------ | ------------- |
-| url       | string                      | 必填         | WebSocket URL |
-| reconnect | boolean \| ReconnectOptions | true         | 是否自动重连  |
-| logger    | Logger                      | new Logger() | 日志实例      |
+| Parameter | Type                        | Default Value | Description                        |
+| --------- | --------------------------- | ------------- | ---------------------------------- |
+| url       | string                      | Required      | WebSocket URL                      |
+| reconnect | boolean \| ReconnectOptions | true          | Whether to automatically reconnect |
+| logger    | Logger                      | new Logger()  | Logger instance                    |
 
 **ReconnectOptions:**
 
-| 参数          | 类型   | 默认值   | 说明             |
-| ------------- | ------ | -------- | ---------------- |
-| maxRetries    | number | Infinity | 最大重试次数     |
-| retryInterval | number | 5000     | 重试间隔（毫秒） |
+| Parameter     | Type   | Default Value | Description                   |
+| ------------- | ------ | ------------- | ----------------------------- |
+| maxRetries    | number | Infinity      | Maximum retry count           |
+| retryInterval | number | 5000          | Retry interval (milliseconds) |
 
-**示例：**
+**Example:**
 
 ```typescript
 const driver = new WebSocketDriver({
@@ -341,11 +413,11 @@ const driver = new WebSocketDriver({
 })
 ```
 
-#### 方法
+#### Methods
 
 ##### close()
 
-关闭连接并停止重连。
+Close connection and stop reconnection.
 
 ```typescript
 driver.close()
@@ -353,20 +425,20 @@ driver.close()
 
 ### PostMessageDriver
 
-#### 构造函数
+#### Constructor
 
 ```typescript
 new PostMessageDriver(targetWindow: Window, targetOrigin: string)
 ```
 
-**参数:**
+**Parameters:**
 
-| 参数         | 类型   | 必填 | 说明                                  |
-| ------------ | ------ | ---- | ------------------------------------- |
-| targetWindow | Window | 是   | 目标窗口对象                          |
-| targetOrigin | string | 是   | 目标源地址（安全要求，不能使用 '\*'） |
+| Parameter    | Type   | Required | Description                                                       |
+| ------------ | ------ | -------- | ----------------------------------------------------------------- |
+| targetWindow | Window | Yes      | Target window object                                              |
+| targetOrigin | string | Yes      | Target origin address (security requirement, '\*' cannot be used) |
 
-**示例：**
+**Example:**
 
 ```typescript
 const driver = new PostMessageDriver(window.parent, 'https://app.example.com')
@@ -374,27 +446,27 @@ const driver = new PostMessageDriver(window.parent, 'https://app.example.com')
 
 ### MittDriver
 
-#### 构造函数
+#### Constructor
 
 ```typescript
 new MittDriver(emitter: Emitter<Record<string, Message>>)
 ```
 
-**示例：**
+**Example:**
 
 ```typescript
 import { createEmitter, MittDriver } from 'message-nexus'
 
-// 使用工厂函数创建独立的 emitter 实例
+// Use the factory function to create an independent emitter instance
 const emitter = createEmitter()
 const driver = new MittDriver(emitter)
 ```
 
-**注意**: 推荐使用 `createEmitter()` 工厂函数创建独立的 emitter 实例。
+**Note**: It is recommended to use the `createEmitter()` factory function to create an independent emitter instance.
 
 ### BroadcastDriver
 
-#### 构造函数
+#### Constructor
 
 ```typescript
 new BroadcastDriver(options: BroadcastDriverOptions)
@@ -402,83 +474,80 @@ new BroadcastDriver(options: BroadcastDriverOptions)
 
 **BroadcastDriverOptions:**
 
-| 参数    | 类型   | 默认值 | 说明         |
-| ------- | ------ | ------ | ------------ |
-| channel | string | 必填   | 广播频道名称 |
+| Parameter | Type   | Default Value | Description            |
+| --------- | ------ | ------------- | ---------------------- |
+| channel   | string | Required      | Broadcast channel name |
 
-**示例：**
+**Example:**
 
 ```typescript
-import { BroadcastDriver, MessageBridge } from 'message-nexus'
+import { BroadcastDriver, MessageNexus } from 'message-nexus'
 
 const driver = new BroadcastDriver({ channel: 'my-app-channel' })
-const bridge = new MessageBridge(driver)
+const nexus = new MessageNexus(driver)
 
-// 监听来自其他标签页的消息
-bridge.onCommand((data) => {
-  console.log('Received from another tab:', data)
-  bridge.reply(data.id, { received: true })
+// Listen for messages from other tabs
+nexus.handle('SOME_METHOD', (params, context) => {
+  console.log('Received from another tab:', params)
+  return { received: true }
 })
 
-// 清理资源
-bridge.destroy()
+// Clean up resources
+nexus.destroy()
 ```
 
-**特性：**
-
-- 同一源下的多个标签页可以通过相同频道名进行通信
-- 自动添加协议标识符，过滤非 MessageBridge 消息
-- 支持动态切换频道
+**Features:**
 
-## Logger 日志
+- Multiple tabs under the same origin can communicate via the same channel name
+- Automatically adds a protocol identifier to filter non-MessageNexus messages
+- Supports dynamic channel switching
 
-### 基本使用
+## Advanced Usage / Techniques
 
-```typescript
-import { Logger, createConsoleHandler, LogLevel } from 'message-nexus/utils/logger'
+### Asynchronous Handlers
 
-const logger = new Logger('MyApp', LogLevel.DEBUG)
-logger.addHandler(createConsoleHandler())
-
-logger.debug('Debug message', { data: 123 })
-logger.info('Info message')
-logger.warn('Warning message')
-logger.error('Error message', { error: new Error('test') })
-```
-
-### 自定义日志处理器
+Handlers registered via `handle()` can be `async` functions or return a `Promise`. MessageNexus will wait for the Promise to resolve before sending the response back to the caller.
 
 ```typescript
-const apiHandler = (entry) => {
-  fetch('/api/logs', {
-    method: 'POST',
-    body: JSON.stringify(entry),
-  })
-}
-
-logger.addHandler(apiHandler)
+nexus.handle('FETCH_REMOTE', async (params) => {
+  const data = await fetch(`https://api.example.com/items/${params.id}`)
+  return await data.json()
+})
 ```
 
-### 设置日志级别
+### Suspending Responses (Manual Reply Simulation)
+
+In some cases, you may need to wait for a user action (like clicking a button in the UI) before replying to a request. You can achieve this by returning a Promise and storing its `resolve` function.
 
 ```typescript
-logger.setMinLevel(LogLevel.WARN) // 只输出 WARN 和 ERROR
-```
+const pendingResolvers = new Map<string, (value: any) => void>()
 
-### 在 Bridge 中使用
+nexus.handle('user.confirm', (params, context) => {
+  return new Promise((resolve) => {
+    // Store the resolve function indexed by messageId
+    const id = context.messageId!
+    pendingResolvers.set(id, resolve)
 
-```typescript
-import { Logger } from 'message-nexus/utils/logger'
+    // Trigger some UI to show a confirmation dialog
+    showDialog(params.message)
+  })
+})
 
-const logger = new Logger('MyBridge')
-const bridge = new MessageBridge(driver, { logger })
+// Later, when the user clicks "Confirm"
+function onUserConfirm(id: string) {
+  const resolve = pendingResolvers.get(id)
+  if (resolve) {
+    resolve({ confirmed: true })
+    pendingResolvers.delete(id)
+  }
+}
 ```
 
-## 设计亮点
+## Design Highlights
 
-### 1. 类型安全
+### 1. Type Safety
 
-MessageBridge 使用 TypeScript 泛型提供完整的类型推断：
+MessageNexus uses TypeScript generics to provide full type inference:
 
 ```typescript
 interface UserRequest {
@@ -490,47 +559,48 @@ interface UserResponse {
   name: string
 }
 
-const bridge = new MessageBridge<UserRequest, UserResponse>(driver)
+const nexus = new MessageNexus<UserRequest, UserResponse>(driver)
 
-// 完整的类型推断
-const response = await bridge.request({
-  type: 'GET_USER',
-  payload: { userId: 123 }, // 类型: UserRequest
+// Full type inference
+const response = await nexus.invoke({
+  method: 'GET_USER',
+  params: { userId: 123 }, // Type: UserRequest
 })
 
-// response 类型: UserResponse
+// response Type: UserResponse
 console.log(response.name)
 ```
 
-### 2. 内存安全
+### 2. Memory Safety
 
-- **自动清理**: 定期清理过期的消息记录
-- **手动清理**: `reply()` 后立即删除记录
-- **资源释放**: `destroy()` 方法清理所有定时器和事件监听器
-- **队列限制**: 消息队列有最大大小限制，防止无限增长
-- **Driver 生命周期**: 每个 Driver 实现 `destroy()` 方法，正确释放资源
-- **Emitter 隔离**: 推荐使用 `createEmitter()` 创建独立实例，避免共享单例导致的内存泄漏
+- **Auto Cleanup**: Regularly clean up expired message records
+- **Manual Cleanup**: Internal request records are deleted immediately after the response is received or timed out
+- **Auto-Reply**: Handlers automatically send responses when the return value is resolved, ensuring no orphaned requests
+- **Resource Release**: The `destroy()` method cleans up all timers and event listeners
+- **Queue Limits**: The message queue has a maximum size limit to prevent infinite growth
+- **Driver Lifecycle**: Each driver implements the `destroy()` method to correctly release resources
+- **Emitter Isolation**: Recommended to use `createEmitter()` to create independent instances, avoiding memory leaks caused by shared singletons
 
-### 3. 错误恢复
+### 3. Error Recovery
 
-- **自动重连**: WebSocket 断线自动重连，指数退避策略
-- **请求重试**: 失败请求自动重试，可配置次数和延迟
-- **消息队列**: 离线消息缓存，连接恢复后自动发送
-- **错误回调**: 统一的错误处理机制
+- **Auto Reconnect**: WebSocket automatic reconnection mechanism with exponential backoff strategy
+- **Request Retry**: Automatic retry on request failure, configurable retry counts and delays
+- **Message Queue**: Offline message caching, automatically sent after connection recovery
+- **Error Callback**: Unified error handling mechanism
 
-### 4. 安全加固
+### 4. Security Hardening
 
-- **PostMessage**: 禁止使用 `'*'` 作为 targetOrigin，必须明确指定源地址
-- **BroadcastChannel**: 使用协议标识符 `__messageBridge` 区分 MessageBridge 消息和用户自定义消息
-- **消息验证**: 运行时验证消息格式，防止非法消息导致崩溃
-- **来源过滤**: 自动过滤非目标消息
+- **PostMessage**: Prohibit using `'*'` as targetOrigin; the origin address must be explicitly specified
+- **BroadcastChannel**: Use the protocol identifier `__messageBridge` to distinguish MessageNexus messages from user-defined messages
+- **Message Validation**: Runtime validation of message format to prevent crashes from illegal messages
+- **Source Filtering**: Automatically filters non-target messages
 
-### 5. 可观测性
+### 5. Observability
 
-内置监控指标，便于生产环境监控：
+Built-in monitoring metrics for easy production environment monitoring:
 
 ```typescript
-const metrics = bridge.getMetrics()
+const metrics = nexus.getMetrics()
 
 console.log(`Messages: ${metrics.messagesSent} sent, ${metrics.messagesReceived} received`)
 console.log(
@@ -540,34 +610,15 @@ console.log(`Avg latency: ${metrics.averageLatency}ms`)
 console.log(`Pending: ${metrics.pendingMessages}, Queued: ${metrics.queuedMessages}`)
 ```
 
-### 6. 结构化日志
-
-统一的日志接口，支持多种输出方式：
-
-```typescript
-// 控制台输出
-logger.addHandler(createConsoleHandler())
-
-// 发送到 API
-logger.addHandler((entry) => {
-  fetch('/api/logs', { body: JSON.stringify(entry) })
-})
-
-// 发送到 ELK
-logger.addHandler((entry) => {
-  elk.send(entry)
-})
-```
-
-## 测试
+## Testing
 
-运行单元测试：
+Run unit tests:
 
 ```bash
 cd packages/message-nexus
 pnpm test:run
 ```
 
-## 许可证
+## License
 
 MIT