@composy/sse-vue

@composy/sse-vue

@composy/sse-vue 是 @composy/sse-core 的 Vue 3 适配层。它不实现 SSE 协议细节，只负责 Vue 生命周期、响应式状态、App 注入和 Vue Engine 运行时绑定。

模块职责

src/
  composables/
    useSSE.ts          # 单连接响应式封装
    useSSEManager.ts   # 多连接管理器响应式封装
  context/
    injection-keys.ts  # SSEManager 注入 key
  plugin/
    create-sse-runtime.ts
    install-sse-app.ts
    native-plugin.ts
    types.ts
  plugins/
    engine-plugin.ts   # Vue Engine 薄适配，复用 core engine plugin

useSSE

useSSE(url, options) 会创建一个 SSEClient，并把最新事件、数据、错误和状态暴露为 Vue ref。

import { useSSE } from '@composy/sse-vue'

const { data, event, status, errorContext, on, close, reconnect } = useSSE('/api/events', {
  heartbeatTimeout: 30000,
  reconnect: true,
})

on('notice', nextEvent => {
  console.log(nextEvent.data)
})

行为说明：

• url 可以是 ref、getter 或普通字符串。
• URL 变化时会重建底层 SSEClient。
• 用户通过 on() 注册的处理器会在重建后重新绑定，并在 off() 或组件卸载时解除。
• autoConnect defaults to true; the default connectOn mode is mounted, so setup does not open a browser connection during SSR. Use connectOn: "immediate" for client-side eager connection or connectOn: "manual" for explicit connect() calls.
• enabled can be a ref/getter that gates an automatic connection; changing it to false closes the client and changing it back to true reconnects in automatic modes. resetOnUrlChange controls whether a URL change immediately reconnects. Manual connect() and reconnect() start a fresh retry budget.

useSSEManager

useSSEManager() 默认优先注入 Vue plugin 已安装的全局 SSEManager。没有全局 manager 时会创建本地 manager，并在组件卸载时按配置清理。

import { useSSEManager } from '@composy/sse-vue'

const { connect, connectionDetails, statusSummary, disconnectAll } = useSSEManager()

connect('notifications', '/api/notifications')

Vue Plugin

import { createApp } from 'vue'
import { createSSEPlugin } from '@composy/sse-vue'

const app = createApp(App)

app.use(
  createSSEPlugin({
    defaults: {
      reconnect: true,
    },
  })
)

安装后会：

• provide(SSE_MANAGER_KEY, manager)。
• 默认提供 'sseManager' 和 'sse' 两个字符串别名。
• 默认挂载 app.config.globalProperties.$sse。
• 可以通过 globalProperty 改名；改名后请在应用自己的 Vue ComponentCustomProperties 声明中补充对应类型，默认 $sse 已由本包提供类型声明。
• App 卸载时清理由插件创建的 manager。

Vue Engine Plugin

import { createSSEEnginePlugin } from '@composy/sse-vue'

engine.use(createSSEEnginePlugin())

Vue Engine 插件只做两件事：

• 复用或安装 Vue App 上的 SSERuntime。
• 把 runtime 中的 SSEManager 交给 @composy/sse-core 的 createSSEEnginePlugin() 处理 state、events 和 api。

这样可以保证 Vue 适配层不复制 core 的 Engine 同步逻辑。

维护约束

• 新增协议能力、重连策略、错误类型、快照字段时，优先修改 @composy/sse-core。
• Vue 包只能新增生命周期、响应式包装、注入或 App 安装相关逻辑。
• Vue type-check 使用 sibling source alias 指向 ../core/src，确保未构建状态下也能检查 core-first 边界。
• Vue 的 ESLint、生产 TypeScript、源码映射与测试 TypeScript 权威配置位于 .ldesign/；包根配置文件仅作为兼容 shim。