npm package: @holix/ipc
Description: Inter-process communication utilities for Holix
Author: zhaogongchengsi
Latest version: 1.0.0

# @holix/ipc

进程间通信工具库，提供基于 JSON-RPC 2.0 协议的通信能力。

## 特性

- ✅ **单例模式**：确保只有一个进程监听器，节省内存
- ✅ **多处理器支持**：同一方法可以注册多个处理器
- ✅ **自动启动**：首次注册处理器时自动启动服务
- ✅ **类型安全**：完整的 TypeScript 类型定义
- ✅ **支持请求/响应和通知**：灵活的通信模式

## 安装

```bash
pnpm add @holix/ipc
```

## 使用方法

### 在 Electron 主进程中使用

```ts
import { getJsonRpcServer } from '@holix/ipc'
import { app, BrowserWindow } from 'electron'

let mainWindow: BrowserWindow

function createWindow() {
  mainWindow = new BrowserWindow({
    width: 800,
    height: 600
  })
}

// 获取 RPC 服务端单例
const rpcServer = getJsonRpcServer()

// 注册文件变更处理器
const unsubscribe = rpcServer.handle('file:changed', (params) => {
  console.log('File changed:', params.path)
  if (mainWindow && !mainWindow.isDestroyed()) {
    mainWindow.webContents.reload()
  }
})

// 稍后可以取消注册
// unsubscribe()

app.whenReady().then(createWindow)
```

### 在不同模块中注册处理器

```ts
// module-a.ts
import { getJsonRpcServer } from '@holix/ipc'

// module-b.ts
import { getJsonRpcServer } from '@holix/ipc'

const rpcServer = getJsonRpcServer()
rpcServer.handle('module-a:action', (params) => {
  console.log('Module A handling:', params)
})

const rpcServer = getJsonRpcServer()
rpcServer.handle('module-b:action', (params) => {
  console.log('Module B handling:', params)
})

// 两个模块共享同一个监听器，不会创建多个进程监听
```

### 同一方法注册多个处理器

```ts
import { getJsonRpcServer } from '@holix/ipc'

const rpcServer = getJsonRpcServer()

// 处理器 1：记录日志
rpcServer.handle('file:changed', (params) => {
  console.log('Logger: File changed', params.path)
})

// 处理器 2：刷新窗口
rpcServer.handle('file:changed', (params) => {
  mainWindow.webContents.reload()
})

// 处理器 3：发送通知
rpcServer.handle('file:changed', (params) => {
  notifier.notify({
    title: 'File Changed',
    message: params.path
  })
})

// 所有处理器都会被执行
```

## API

### `getJsonRpcServer(): JsonRpcServer`

获取 JSON-RPC 服务端单例。

### `JsonRpcServer`

#### `handle(method: string, handler: (params?: any) => any): () => void`

注册方法处理器。返回取消注册的函数。

- **method**: 方法名
- **handler**: 处理器函数，可以是同步或异步的

```ts
const unsubscribe = rpcServer.handle('my:method', (params) => {
  return { success: true }
})

// 取消注册
unsubscribe()
```

#### `removeHandler(method: string, handler?: JsonRpcHandler): void`

移除方法处理器。

- 如果提供 `handler`，只移除该处理器
- 如果不提供 `handler`，移除该方法的所有处理器

```ts
rpcServer.removeHandler('my:method', specificHandler)
rpcServer.removeHandler('my:method') // 移除所有
```

#### `getRegisteredMethods(): string[]`

获取所有已注册的方法名。

```ts
const methods = rpcServer.getRegisteredMethods()
console.log('Registered methods:', methods)
```

#### `start(): void`

手动启动服务端。通常不需要调用，首次注册处理器时会自动启动。

#### `stop(): void`

停止服务端。

#### `reset(): void`

重置服务端（停止服务并清除所有处理器）。

#### `isStarted(): boolean`

检查服务端是否已启动。

## 通信协议

使用 JSON-RPC 2.0 协议，通过标准输入/输出进行通信。

### 消息格式

所有消息以 `__HOLIX_RPC__:` 为前缀，后跟 JSON 数据。

**请求**：
```json
__HOLIX_RPC__:{"jsonrpc":"2.0","method":"file:changed","params":{"path":"src/index.ts"},"id":1}
```

**通知**（无需响应）：
```json
__HOLIX_RPC__:{"jsonrpc":"2.0","method":"file:changed","params":{"path":"src/index.ts"}}
```

**响应**：
```json
__HOLIX_RPC__:{"jsonrpc":"2.0","result":{"success":true},"id":1}
```

## 最佳实践

1. **使用方法命名空间**：使用 `:` 分隔命名空间，如 `module:action`
2. **返回取消函数**：保存 `handle()` 返回的函数，在组件卸载时调用
3. **错误处理**：在处理器中捕获并处理错误
4. **避免阻塞**：处理器应该快速执行，耗时操作使用异步

```ts
const unsubscribe = rpcServer.handle('heavy:task', async (params) => {
  try {
    // 异步处理耗时任务
    const result = await processHeavyTask(params)
    return result
  }
  catch (error) {
    console.error('Error processing task:', error)
    throw error
  }
})

// 清理时取消注册
process.on('beforeExit', () => {
  unsubscribe()
})
```

## License

MIT