js-rpc2 2.4.0 → 2.4.1

package/doc/http.md

@@ -0,0 +1,202 @@
+# HTTP 使用文档
+
+## 概述
+
+js-rpc 支持通过 HTTP 协议进行 RPC 调用，使用 Koa 框架作为服务器端实现。HTTP 传输适用于 Web 应用、微服务通信等场景。
+
+## 核心组件
+
+### 服务器端
+
+1. [createRpcServerKoaRouter](../src/server.js#L73) - 在 Koa 路由中创建 RPC 服务器
+2. [createRpcServerHelper](../src/lib.js#L467) - 创建 RPC 服务器助手（内部使用）
+
+### 客户端
+
+1. [createRpcClientHttp](../src/lib.js#L726) - 创建 HTTP RPC 客户端
+
+## 完整示例
+
+### 1. 服务器端代码 (server.js)
+
+```js
+import { createServer } from 'http'
+import Koa from 'koa'
+import Router from '@koa/router'
+import { createRpcServerKoaRouter } from 'js-rpc2/src/server.js'
+
+// 创建 Koa 应用和路由
+const app = new Koa()
+const router = new Router()
+
+// 应用中间件
+app.use(router.routes())
+app.use(router.allowedMethods())
+
+// 启动 HTTP 服务器
+const server = createServer(app.callback()).listen(9000)
+console.log('Server listening on port 9000')
+
+// 定义可远程调用的函数
+class RpcApi {
+    /**
+     * 示例方法：带回调的异步函数
+     * @param {string} name - 名称参数
+     * @param {(data: string) => void} update - 回调函数，用于报告进度
+     */
+    async hello(name, update) {
+        for (let i = 0; i < 3; i++) {
+            // 调用回调函数报告进度
+            update(`progress ${i}`)
+            await new Promise((resolve) => setTimeout(resolve, 1000))
+        }
+        return `hello ${name}`
+    }
+
+    /**
+     * 示例方法：处理二进制数据
+     * @param {Uint8Array} buffer - 二进制数据
+     */
+    async processBuffer(buffer) {
+        // 对数据进行处理，例如截取部分数据
+        return buffer.slice(0, Math.min(100, buffer.length))
+    }
+
+    /**
+     * 示例方法：处理复杂对象
+     * @param {Object} data - 复杂对象
+     */
+    async processData(data) {
+        return {
+            received: data,
+            timestamp: new Date().toISOString(),
+            processed: true
+        }
+    }
+}
+
+// 创建 API 实例
+const extension = new RpcApi()
+
+// 创建 RPC 服务器
+createRpcServerKoaRouter({
+    path: '/rpc',           // RPC 服务路径
+    router: router,         // Koa 路由实例
+    extension: extension,   // 可调用的函数集合
+    rpcKey: 'optional-secret-key' // 可选的安全密钥
+})
+```
+
+### 2. 客户端代码 (client.js)
+
+```js
+import { createRpcClientHttp } from 'js-rpc2/src/client.js'
+
+// 创建 RPC 客户端
+/** @type{RpcApi} */
+const rpc = createRpcClientHttp({
+    url: 'http://127.0.0.1:9000/rpc',  // RPC 服务地址
+    rpcKey: 'optional-secret-key'      // 可选的安全密钥（需与服务端一致）
+})
+
+// 使用示例
+async function example() {
+    try {
+        // 调用带回调的异步函数
+        const result = await rpc.hello('World', (progress) => {
+            console.log('Progress:', progress)
+        })
+        console.log('Result:', result)
+
+        // 调用处理二进制数据的函数
+        const buffer = new Uint8Array([1, 2, 3, 4, 5])
+        const processedBuffer = await rpc.processBuffer(buffer)
+        console.log('Processed buffer:', processedBuffer)
+
+        // 调用处理复杂对象的函数
+        const data = { name: 'test', value: 42 }
+        const processedData = await rpc.processData(data)
+        console.log('Processed data:', processedData)
+
+    } catch (error) {
+        console.error('RPC call failed:', error)
+    }
+}
+
+// 执行示例
+example()
+```
+
+## API 说明
+
+### 服务器端 API
+
+#### createRpcServerKoaRouter
+
+在 Koa 路由中创建 RPC 服务器。
+
+```js
+/**
+ * @param {{
+ * path: string; 
+ * router: Router<any, {}>; 
+ * rpcKey?:string;
+ * logger?:(msg:string)=>void;
+ * extension: {asyncLocalStorage:AsyncLocalStorage;}; 
+ * }} param 
+ */
+export function createRpcServerKoaRouter(param)
+```
+
+参数说明：
+- `path`: RPC 服务的路由路径
+- `router`: Koa 路由实例
+- `rpcKey`: 可选的安全密钥，用于验证客户端请求
+- `logger`: 可选的日志函数
+- `extension`: 包含可远程调用函数的对象
+
+### 客户端 API
+
+#### createRpcClientHttp
+
+创建 HTTP RPC 客户端。
+
+```js
+/**
+ * @param {{
+ * url:string;
+ * rpcKey?:string;
+ * signal?:AbortSignal;
+ * intercept?:(res:Response)=>void;
+ * }} param
+ */
+export function createRpcClientHttp(param)
+```
+
+参数说明：
+- `url`: RPC 服务的完整 URL
+- `rpcKey`: 可选的安全密钥，需与服务端一致
+- `signal`: 可选的 AbortSignal，用于取消请求
+- `intercept`: 可选的响应拦截函数
+
+## 特性
+
+1. **跨域支持**: 客户端可以调用不同域上的 RPC 服务
+2. **类型安全**: 通过 JSDoc 注解提供完整的类型支持
+3. **异步回调**: 支持在远程调用过程中传递回调函数
+4. **二进制数据**: 原生支持 Uint8Array 等二进制数据类型
+5. **错误处理**: 完善的错误处理和传播机制
+6. **安全验证**: 可选的 rpcKey 参数提供基本的安全验证
+
+## 使用场景
+
+1. **Web 应用**: 浏览器前端调用后端服务
+2. **微服务**: 服务间通过 HTTP 进行 RPC 调用
+3. **混合架构**: 不同技术栈的服务间通信
+
+## 注意事项
+
+1. 确保服务端正确配置 CORS（跨域资源共享）策略
+2. 大数据传输可能影响性能，考虑使用流式传输
+3. HTTP 是无状态协议，需要通过 rpcKey 或其他机制实现身份验证
+4. 服务端需要正确处理 Koa 中间件的顺序

package/doc/other_environments.md

@@ -0,0 +1,467 @@
+# 其他环境使用文档
+
+## 概述
+
+js-rpc 除了支持 Node.js Worker Threads、HTTP 和 WebSocket 外，还支持多种其他环境，包括 Electron、Chrome 扩展和 MessagePort 等。这些环境都基于消息传递机制实现 RPC 调用。
+
+## 支持的环境
+
+### 1. Electron
+
+Electron 环境中可以使用 MessagePort 进行主进程和渲染进程之间的通信。
+
+#### 服务器端 API
+
+- [createRpcServerElectronMessagePort](../src/lib.js#L796)
+
+#### 客户端 API
+
+暂无专用客户端，可使用通用 MessagePort 客户端。
+
+### 2. Chrome 扩展
+
+Chrome 扩展中可以使用 chrome.runtime API 进行不同组件之间的通信。
+
+#### 服务器端 API
+
+- [createRpcServerChromeExtensions](../src/lib.js#L868)
+
+#### 客户端 API
+
+- [createRpcClientChromeExtensions](../src/lib.js#L929)
+
+### 3. MessagePort
+
+通用 MessagePort 环境，如 Web Workers 或其他支持 MessagePort API 的环境。
+
+#### 服务器端 API
+
+- [createRpcServerMessagePort](../src/lib.js#L760)
+
+#### 客户端 API
+
+- [createRpcClientMessagePort](../src/lib.js#L819)
+
+## 完整示例
+
+### 1. Electron 示例
+
+#### 主进程代码 (main.js)
+
+```js
+import { app, BrowserWindow, ipcRenderer } from 'electron'
+import { createRpcServerElectronMessagePort } from 'js-rpc2/src/lib.js'
+
+// 主进程服务函数
+class MainProcessApi {
+    /**
+     * 获取系统信息
+     */
+    async getSystemInfo() {
+        return {
+            platform: process.platform,
+            arch: process.arch,
+            version: process.version,
+            uptime: process.uptime()
+        }
+    }
+
+    /**
+     * 执行计算密集型任务
+     * @param {number} n - 计算参数
+     */
+    async computeIntensiveTask(n) {
+        let result = 0
+        for (let i = 0; i < n; i++) {
+            result += Math.sin(i) * Math.cos(i)
+        }
+        return result
+    }
+}
+
+// 创建窗口时建立 RPC 连接
+app.whenReady().then(() => {
+    const mainWindow = new BrowserWindow({
+        webPreferences: {
+            nodeIntegration: true,
+            contextIsolation: false
+        }
+    })
+
+    // 当需要建立 RPC 连接时
+    mainWindow.webContents.once('did-finish-load', () => {
+        // 创建 MessagePort 通道
+        const { port1, port2 } = new MessageChannelMain()
+        
+        // 在主进程端创建 RPC 服务器
+        createRpcServerElectronMessagePort({
+            port: port1,
+            extension: new MainProcessApi()
+        })
+        
+        // 将 port2 发送到渲染进程
+        mainWindow.webContents.postMessage('rpc-port', null, [port2])
+    })
+
+    mainWindow.loadFile('index.html')
+})
+```
+
+#### 渲染进程代码 (renderer.js)
+
+```js
+import { createRpcClientMessagePort } from 'js-rpc2/src/lib.js'
+
+// 等待主进程发送 MessagePort
+window.addEventListener('message', async (event) => {
+    if (event.data === 'rpc-port' && event.ports.length > 0) {
+        const port = event.ports[0]
+        
+        // 创建 RPC 客户端
+        /** @type{MainProcessApi} */
+        const rpc = createRpcClientMessagePort({
+            port: port
+        })
+        
+        // 使用 RPC 调用主进程函数
+        try {
+            const systemInfo = await rpc.getSystemInfo()
+            console.log('System info:', systemInfo)
+            
+            const result = await rpc.computeIntensiveTask(1000000)
+            console.log('Computation result:', result)
+        } catch (error) {
+            console.error('RPC call failed:', error)
+        }
+    }
+})
+```
+
+### 2. Chrome 扩展示例
+
+#### Background 脚本 (background.js)
+
+```js
+import { createRpcServerChromeExtensions } from 'js-rpc2/src/lib.js'
+
+// Background 脚本服务函数
+class BackgroundApi {
+    /**
+     * 获取浏览器标签页信息
+     */
+    async getTabsInfo() {
+        const tabs = await chrome.tabs.query({})
+        return tabs.map(tab => ({
+            id: tab.id,
+            title: tab.title,
+            url: tab.url,
+            active: tab.active
+        }))
+    }
+
+    /**
+     * 创建新标签页
+     * @param {string} url - 标签页 URL
+     */
+    async createTab(url) {
+        const tab = await chrome.tabs.create({ url })
+        return {
+            id: tab.id,
+            url: tab.url
+        }
+    }
+
+    /**
+     * 带回调的长时间运行任务
+     * @param {(progress: string) => void} callback - 进度回调
+     */
+    async longRunningTask(callback) {
+        for (let i = 1; i <= 10; i++) {
+            await new Promise(resolve => setTimeout(resolve, 1000))
+            callback(`Step ${i} completed`)
+        }
+        return 'Task finished'
+    }
+}
+
+// 创建 RPC 服务器
+createRpcServerChromeExtensions({
+    chrome: chrome,
+    key: 'background-rpc',
+    extension: new BackgroundApi()
+})
+```
+
+#### Popup 脚本 (popup.js)
+
+```js
+import { createRpcClientChromeExtensions } from 'js-rpc2/src/lib.js'
+
+// 创建 RPC 客户端
+const rpc = createRpcClientChromeExtensions({
+    chrome: chrome,
+    key: 'background-rpc'
+})
+
+// DOM 元素
+const tabsList = document.getElementById('tabs-list')
+const urlInput = document.getElementById('url-input')
+const createTabButton = document.getElementById('create-tab-button')
+const progressDiv = document.getElementById('progress')
+
+// 获取标签页信息
+async function getTabsInfo() {
+    try {
+        const tabsInfo = await rpc.getTabsInfo()
+        tabsList.innerHTML = tabsInfo.map(tab => 
+            `<div class="tab-item ${tab.active ? 'active' : ''}">
+                <strong>${tab.title}</strong><br>
+                ${tab.url}
+            </div>`
+        ).join('')
+    } catch (error) {
+        console.error('Failed to get tabs info:', error)
+    }
+}
+
+// 创建新标签页
+async function createTab() {
+    const url = urlInput.value
+    if (!url) return
+    
+    try {
+        const result = await rpc.createTab(url)
+        console.log('Created tab:', result)
+        urlInput.value = ''
+        getTabsInfo() // 刷新标签页列表
+    } catch (error) {
+        console.error('Failed to create tab:', error)
+    }
+}
+
+// 执行长时间运行任务
+async function runLongTask() {
+    try {
+        const result = await rpc.longRunningTask((progress) => {
+            progressDiv.textContent = progress
+        })
+        progressDiv.textContent = result
+    } catch (error) {
+        console.error('Task failed:', error)
+        progressDiv.textContent = 'Task failed'
+    }
+}
+
+// 绑定事件
+createTabButton.addEventListener('click', createTab)
+document.getElementById('refresh-button').addEventListener('click', getTabsInfo)
+document.getElementById('run-task-button').addEventListener('click', runLongTask)
+
+// 初始化
+getTabsInfo()
+```
+
+### 3. Web Worker 示例
+
+#### 主线程代码 (main.js)
+
+```js
+import { createRpcClientMessagePort } from 'js-rpc2/src/lib.js'
+
+// 创建 Web Worker
+const worker = new Worker('./worker.js')
+
+// 创建 RPC 客户端
+/** @type{WorkerApi} */
+const rpc = createRpcClientMessagePort({
+    port: worker
+})
+
+// 使用示例
+async function example() {
+    try {
+        // 调用 Worker 中的函数
+        const result = await rpc.calculateFibonacci(40)
+        console.log('Fibonacci result:', result)
+        
+        // 调用带进度更新的函数
+        const processDataResult = await rpc.processDataWithProgress(10000, (progress) => {
+            console.log(`Processing: ${progress}%`)
+        })
+        console.log('Process data result:', processDataResult)
+        
+    } catch (error) {
+        console.error('RPC call failed:', error)
+    }
+}
+
+example()
+```
+
+#### Worker 线程代码 (worker.js)
+
+```js
+import { createRpcServerMessagePort } from 'js-rpc2/src/lib.js'
+
+// Worker 中的服务函数
+class WorkerApi {
+    /**
+     * 计算斐波那契数
+     * @param {number} n - 数列位置
+     */
+    async calculateFibonacci(n) {
+        if (n <= 1) return n
+        let a = 0, b = 1
+        for (let i = 2; i <= n; i++) {
+            const temp = a + b
+            a = b
+            b = temp
+        }
+        return b
+    }
+    
+    /**
+     * 带进度更新的数据处理
+     * @param {number} dataSize - 数据大小
+     * @param {(progress: number) => void} progressCallback - 进度回调
+     */
+    async processDataWithProgress(dataSize, progressCallback) {
+        const data = new Array(dataSize).fill(0).map(() => Math.random())
+        
+        let processed = 0
+        const step = Math.max(1, Math.floor(dataSize / 100)) // 每1%报告一次进度
+        
+        for (let i = 0; i < dataSize; i++) {
+            // 模拟处理过程
+            data[i] = Math.pow(data[i], 2) + Math.sqrt(data[i])
+            
+            processed++
+            if (processed % step === 0 || processed === dataSize) {
+                const progress = Math.round((processed / dataSize) * 100)
+                progressCallback(progress)
+            }
+        }
+        
+        return {
+            processedItems: processed,
+            average: data.reduce((sum, val) => sum + val, 0) / dataSize
+        }
+    }
+}
+
+// 创建 RPC 服务器
+createRpcServerMessagePort({
+    port: self,
+    extension: new WorkerApi()
+})
+```
+
+## API 说明
+
+### Electron
+
+#### createRpcServerElectronMessagePort
+
+在 Electron 主进程中创建 RPC 服务器。
+
+```js
+/**
+ * @param {{
+ * port:Electron.MessagePortMain;
+ * rpcKey:string;
+ * extension: object; 
+ * logger?:(msg:string)=>void;
+ * }} param 
+ */
+export function createRpcServerElectronMessagePort(param)
+```
+
+### Chrome 扩展
+
+#### createRpcServerChromeExtensions
+
+在 Chrome 扩展中创建 RPC 服务器。
+
+```js
+/**
+ * @param {{
+ * chrome:Chrome;
+ * key: string;
+ * extension: ExtensionApi<Chrome.runtime.MessageSender>
+ * logger?:(msg:string)=>void;
+ * }} param 
+ */
+export function createRpcServerChromeExtensions(param)
+```
+
+#### createRpcClientChromeExtensions
+
+在 Chrome 扩展中创建 RPC 客户端。
+
+```js
+/**
+ * @param {{ 
+ * chrome:Chrome;
+ * key:string;
+ * tabId?: number;
+ * }} param
+ */
+export function createRpcClientChromeExtensions(param)
+```
+
+### MessagePort
+
+#### createRpcServerMessagePort
+
+在任意支持 MessagePort 的环境中创建 RPC 服务器。
+
+```js
+/**
+ * @param {{
+ * port:MessagePort;
+ * rpcKey:string;
+ * extension: object;
+ * logger?:(msg:string)=>void;
+ * }} param 
+ */
+export function createRpcServerMessagePort(param)
+```
+
+#### createRpcClientMessagePort
+
+在任意支持 MessagePort 的环境中创建 RPC 客户端。
+
+```js
+/**
+ * @param {{
+ * port:MessagePort;
+ * rpcKey:string;
+ * }} param
+ */
+export function createRpcClientMessagePort(param)
+```
+
+## 特性
+
+1. **跨环境兼容**: 支持多种基于消息传递的环境
+2. **类型安全**: 通过 JSDoc 注解提供完整的类型支持
+3. **异步回调**: 支持在远程调用过程中传递回调函数
+4. **二进制数据**: 原生支持 Uint8Array 等二进制数据类型
+5. **错误处理**: 完善的错误处理和传播机制
+6. **灵活部署**: 可根据不同环境特点灵活部署
+
+## 使用场景
+
+1. **Electron 应用**: 主进程与渲染进程通信
+2. **Chrome 扩展**: 不同组件间通信（popup、content scripts、background）
+3. **Web Workers**: 主线程与 Worker 线程通信
+4. **Shared Workers**: 多页面共享 Worker
+5. **iframe 通信**: 不同源页面间通信
+
+## 注意事项
+
+1. 不同环境的 MessagePort 实现可能略有差异
+2. Chrome 扩展需要正确配置 manifest 权限
+3. Electron 环境需要正确设置 webPreferences
+4. 注意处理跨域和安全限制
+5. 合理管理 MessagePort 的生命周期

package/doc/websocket.md

@@ -0,0 +1,223 @@
+# WebSocket 使用文档
+
+## 概述
+
+js-rpc 支持通过 WebSocket 协议进行 RPC 调用，提供了比 HTTP 更高效的双向通信能力。WebSocket 传输适用于需要实时通信、频繁交互或长时间连接的应用场景。
+
+## 核心组件
+
+### 服务器端
+
+1. [createRpcServerWebSocket](../src/server.js#L37) - 创建 WebSocket RPC 服务器
+2. [createRpcServerHelper](../src/lib.js#L467) - 创建 RPC 服务器助手（内部使用）
+
+### 客户端
+
+1. [createRpcClientWebSocket](../src/lib.js#L656) - 创建 WebSocket RPC 客户端
+
+## 完整示例
+
+### 1. 服务器端代码 (server.js)
+
+```js
+import { createServer } from 'http'
+import { WebSocketServer } from 'ws'
+import { createRpcServerWebSocket } from 'js-rpc2/src/server.js'
+
+// 创建 HTTP 服务器
+const server = createServer()
+
+// 创建 WebSocket 服务器
+const wss = new WebSocketServer({ server })
+
+// 定义可远程调用的函数
+class RpcApi {
+    /**
+     * 示例方法：带回调的异步函数
+     * @param {string} name - 名称参数
+     * @param {(data: string) => void} update - 回调函数，用于报告进度
+     */
+    async hello(name, update) {
+        for (let i = 0; i < 5; i++) {
+            // 调用回调函数报告进度
+            update(`progress ${i}`)
+            await new Promise((resolve) => setTimeout(resolve, 500))
+        }
+        return `Hello, ${name}!`
+    }
+
+    /**
+     * 示例方法：处理二进制数据
+     * @param {Uint8Array} buffer - 二进制数据
+     */
+    async processBuffer(buffer) {
+        // 模拟处理过程
+        await new Promise((resolve) => setTimeout(resolve, 1000))
+        // 返回处理后的数据
+        return new Uint8Array(buffer.map(b => b * 2))
+    }
+
+    /**
+     * 示例方法：实时数据推送
+     * @param {(data: object) => void} callback - 数据推送回调
+     */
+    async subscribeToData(callback) {
+        // 模拟实时数据推送
+        for (let i = 0; i < 10; i++) {
+            await new Promise((resolve) => setTimeout(resolve, 1000))
+            callback({
+                timestamp: Date.now(),
+                value: Math.random(),
+                index: i
+            })
+        }
+        return 'Subscription ended'
+    }
+}
+
+// 创建 API 实例
+const extension = new RpcApi()
+
+// 创建 RPC 服务器
+createRpcServerWebSocket({
+    path: '/rpc',           // RPC 服务路径
+    wss: wss,               // WebSocket 服务器实例
+    extension: extension,   // 可调用的函数集合
+    rpcKey: 'optional-secret-key' // 可选的安全密钥
+})
+
+// 启动服务器
+server.listen(9000, () => {
+    console.log('WebSocket RPC server listening on port 9000')
+})
+```
+
+### 2. 客户端代码 (client.js)
+
+```js
+import { createRpcClientWebSocket } from 'js-rpc2/src/client.js'
+
+// 创建 AbortController 用于控制连接
+const ac = new AbortController()
+
+// 创建 RPC 客户端
+/** @type{RpcApi} */
+const rpc = createRpcClientWebSocket({
+    url: 'ws://127.0.0.1:9000/rpc',    // WebSocket RPC 服务地址
+    rpcKey: 'optional-secret-key',     // 可选的安全密钥（需与服务端一致）
+    signal: ac.signal                  // 用于控制连接的信号
+})
+
+// 使用示例
+async function example() {
+    try {
+        // 调用带回调的异步函数
+        console.log('Calling hello with progress updates...')
+        const result = await rpc.hello('WebSocket User', (progress) => {
+            console.log('Progress update:', progress)
+        })
+        console.log('Hello result:', result)
+
+        // 调用处理二进制数据的函数
+        console.log('Processing binary data...')
+        const buffer = new Uint8Array([1, 2, 3, 4, 5])
+        const processedBuffer = await rpc.processBuffer(buffer)
+        console.log('Processed buffer:', processedBuffer)
+
+        // 订阅实时数据
+        console.log('Subscribing to real-time data...')
+        const subscriptionResult = await rpc.subscribeToData((data) => {
+            console.log('Real-time data:', data)
+        })
+        console.log('Subscription result:', subscriptionResult)
+
+    } catch (error) {
+        console.error('RPC call failed:', error)
+    }
+}
+
+// 执行示例
+example()
+
+// 在需要时断开连接
+// ac.abort()
+```
+
+## API 说明
+
+### 服务器端 API
+
+#### createRpcServerWebSocket
+
+创建 WebSocket RPC 服务器。
+
+```js
+/**
+ * @param {{
+ * path: string; 
+ * wss: WebSocketServer; 
+ * rpcKey:string;
+ * extension: {asyncLocalStorage:AsyncLocalStorage<IncomingMessage>;}; 
+ * logger?:(msg:string)=>void;
+ * }} param
+ */
+export function createRpcServerWebSocket(param)
+```
+
+参数说明：
+- `path`: RPC 服务的路径，用于区分不同的服务
+- `wss`: WebSocketServer 实例
+- `rpcKey`: 可选的安全密钥，用于验证客户端连接
+- `extension`: 包含可远程调用函数的对象
+- `logger`: 可选的日志函数
+
+### 客户端 API
+
+#### createRpcClientWebSocket
+
+创建 WebSocket RPC 客户端。
+
+```js
+/**
+ * @param {{
+ * url:string;
+ * rpcKey:string;
+ * signal:AbortSignal;
+ * intercept?:(e:Event)=>void;
+ * }} param
+ */
+export function createRpcClientWebSocket(param)
+```
+
+参数说明：
+- `url`: WebSocket RPC 服务的完整 URL
+- `rpcKey`: 可选的安全密钥，需与服务端一致
+- `signal`: AbortSignal，用于控制连接的生命周期
+- `intercept`: 可选的事件拦截函数
+
+## 特性
+
+1. **双向通信**: WebSocket 提供全双工通信，服务器也可以主动向客户端推送数据
+2. **实时性**: 低延迟通信，适用于实时应用
+3. **连接保持**: 长连接减少重复握手开销
+4. **类型安全**: 通过 JSDoc 注解提供完整的类型支持
+5. **异步回调**: 支持在远程调用过程中传递回调函数
+6. **二进制数据**: 原生支持 Uint8Array 等二进制数据类型
+7. **自动重连**: 客户端具备自动重连机制
+8. **错误处理**: 完善的错误处理和传播机制
+
+## 使用场景
+
+1. **实时应用**: 聊天应用、实时游戏、协作编辑等
+2. **数据推送**: 实时数据监控、股票价格更新等
+3. **频繁交互**: 需要频繁通信的应用，避免 HTTP 请求的开销
+4. **长时间连接**: 需要保持连接状态的应用
+
+## 注意事项
+
+1. WebSocket 连接需要正确处理断开和重连逻辑
+2. 服务器需要合理管理并发连接数
+3. 注意处理网络异常和超时情况
+4. 对于大规模部署，考虑使用负载均衡器
+5. 安全方面，确保使用 WSS（WebSocket Secure）进行加密传输
+6. 在防火墙环境中，确保 WebSocket 端口未被阻止

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "js-rpc2",
-  "version": "2.4.0",
+  "version": "2.4.1",
   "description": "js web websocket http rpc",
   "main": "index.js",
   "type": "module",