npm - @songfreedom/sse-client - Versions diffs - 0.1.0 → 0.1.2 - Mend

@songfreedom/sse-client 0.1.0 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (31) hide show

package/README.md CHANGED Viewed

@@ -1,295 +1,318 @@
 # @songfreedom/sse-client
-零依赖的 SSE 客户端：核心只有 `fetch` + `ReadableStream` + 自研帧解析，Vue 适配层单独入口。
+[![npm version](https://img.shields.io/npm/v/%40songfreedom%2Fsse-client)](https://www.npmjs.com/package/@songfreedom/sse-client)
+[![license](https://img.shields.io/npm/l/%40songfreedom%2Fsse-client)](./LICENSE)
+[![minzip size](https://img.shields.io/bundlephobia/minzip/%40songfreedom%2Fsse-client)](https://bundlephobia.com/package/@songfreedom/sse-client)
-## 安装
+A small, dependency-free Server-Sent Events client for the browser.
+`fetch` transport, typed event routing, automatic reconnection with `Last-Event-ID` resume,
+an idle watchdog and shared connections.
-```bash
-pnpm add @songfreedom/sse-client
-```
+```ts
+import { SSEClient } from "@songfreedom/sse-client";
-Vue 入口需要项目里已有 `vue`（可选 peer，非 Vue 项目不会被强制拉取）：
+const client = new SSEClient({
+  url: "/api/push/subscribe",
+  body: { topics: ["alarm"] },
+  headers: () => ({ authorization: `Bearer ${getToken()}` }),
+  parse: (raw) => JSON.parse(raw),
+});
-```bash
-pnpm add @songfreedom/sse-client vue
+client.on("ALARM", (alarm) => console.log(alarm.level));
 ```
-```ts
-import { SSEClient, createBatcher } from "@songfreedom/sse-client";      // 框架无关
-import { useSSE } from "@songfreedom/sse-client/vue";                    // Vue 入口
-```
+## Why not `EventSource`?
+| Option | Problem |
+| --- | --- |
+| Native `EventSource` | Cannot set request headers (no way to send an auth token), GET only, no request body, no control over reconnection |
+| [`@microsoft/fetch-event-source`](https://github.com/Azure/fetch-event-source) | Archived. Non-2xx responses must be rejected by hand in `onopen`, otherwise it silently reconnects forever; fixed retry interval; no `Last-Event-ID` persistence |
+| `axios` | Cannot read a streaming response in the browser (`responseType: "stream"` is Node-only). Concatenating `responseText` in `onDownloadProgress` corrupts multi-byte characters |
-零运行时依赖；核心只有 `fetch` + `ReadableStream` + 自研帧解析。
+This library is roughly 3 kB gzipped, has no runtime dependencies, and only needs `fetch`
+and `ReadableStream`.
-## 为什么不用现成库
+## Features
-| 方案 | 问题 |
-| --- | --- |
-| 原生 `EventSource` | 不能自定义请求头（鉴权 token 无处安放）、只能 GET、不能带 body、重连策略不可控 |
-| `@microsoft/fetch-event-source` | 已归档；`onopen` 里非 2xx 必须手动抛错，否则静默死循环重连；重连间隔固定；无 `Last-Event-ID` 持久化 |
-| axios | 浏览器端读不到流式响应（`responseType: "stream"` 仅 Node 有效），`onDownloadProgress` 拼字符串会在多字节字符边界处截断 |
+- **POST + JSON body**, arbitrary headers, and header functions re-evaluated on every reconnect
+- **Reconnects** with exponential backoff and jitter; terminal errors (401/403/404) stop immediately
+- **Resume** with `Last-Event-ID`, so a reconnect can pick up where it left off
+- **Typed event routing**: one connection serves many subscribers, `on()` infers payload types from an event map
+- **Idle watchdog** for streams that go quiet, and **proactive rotation** for connections that stay open but stop receiving data
+- **Offline-aware**: pauses while the network is down, reconnects as soon as it is back
+- **Pluggable retry policy**, including async policies such as "refresh the token, then retry"
+- **Shared connections** by key with reference counting
+- Optional **Vue 3** composable in a separate entry point
-## 设计分层
+## Installation
+```bash
+pnpm add @songfreedom/sse-client
+# or
+npm install @songfreedom/sse-client
 ```
-parser.ts    纯函数：字节流 → 事件（data/event/id/retry、CRLF、注释行、跨块半行）
-client.ts    连接生命周期：建连、重连退避、空闲超时、主动轮换、事件路由、多订阅者
-share.ts     按 key 共享连接（引用计数）
-vue.ts       useSSE：状态/事件缓存 + 作用域自动清理（peer: vue，可选）
+The Vue entry needs `vue` as a peer dependency (it is optional, so non-Vue users do not install it):
+```bash
+pnpm add @songfreedom/sse-client vue
 ```
-库本身不知道 token、不知道 store、不弹 toast、不打日志（除回调抛错的兜底）。业务侧的鉴权头由调用方通过 `headers` 注入。
+Requires a browser with `fetch` and `ReadableStream` (all evergreen browsers), or Node 18+ for SSR and tests.
-## 快速开始
+## Quick start
+### Framework-agnostic
 ```ts
 import { SSEClient } from "@songfreedom/sse-client";
-interface AlarmEvent { ALARM: { level: "high" | "low"; deviceId: string } }
+interface Events {
+  ALARM: { level: "high" | "low"; deviceId: string };
+  IOT: { objectId: string; value: string };
+}
-const client = new SSEClient<AlarmEvent>({
-  url: "/api/push/alarm/subscribe",
-  body: { topics: ["alarm"] },
-  headers: () => ({ token: localStorage.getItem("token") ?? "" }), // 每次重连都重新取
+const client = new SSEClient<Events>({
+  url: `${gateway}/server-event/sse/subscribe`,
+  method: "POST",
+  body: [{ subscribeType: "SE", instanceType: "PROJECT" }],
+  headers: () => authHeaders(),          // re-evaluated before every attempt
   parse: (raw) => JSON.parse(raw),
-  idleTimeout: 45_000, // 服务端心跳 15s 时取 3 倍
+  idleTimeout: 45_000,                   // if the server sends a heartbeat every 15s
 });
-// 按事件名订阅，一条连接服务多个业务方
-const off = client.on("ALARM", (alarm) => console.log(alarm.level));
-client.on("*", (data, message) => console.log(message.event, data));
+const off = client.on("ALARM", (alarm) => {
+  // `alarm` is typed as Events["ALARM"]
+  console.log(alarm.deviceId);
+});
-// 组件卸载时
+// Later
 off();
 client.close();
 ```
-### Vue
+### Vue 3
-```ts
+```vue
+<script setup lang="ts">
+import { computed } from "vue";
 import { useSSE } from "@songfreedom/sse-client/vue";
-const { status, lastEvent, on } = useSSE<{ ALARM: AlarmEvent }>({
-  url: "/api/push/alarm/subscribe",
+interface Events {
+  ALARM: { level: "high" | "low"; deviceId: string };
+}
+const { status, lastEvent, on } = useSSE<Events>({
+  url: "/api/push/alarm",
   body: { topics: ["alarm"] },
   parse: (raw) => JSON.parse(raw),
 });
-on("ALARM", (alarm) => { /* 组件卸载时自动退订 */ });
+on("ALARM", (alarm) => {
+  // unsubscribed automatically on unmount
+  console.log(alarm.level);
+});
+const connected = computed(() => status.value === "open");
+</script>
 ```
+`useSSE` adds two things on top of the client: a ring buffer of recent messages
+(`lastEvent`, `events`, `maxEvents`) and scope-bound cleanup — unmounting the component,
+or a qiankun sub-app, closes the connection.
 ## API
 ### `new SSEClient(options)`
-| 选项 | 说明 |
-| --- | --- |
-| `url` / `method` / `body` | 请求目标，默认 `POST` + JSON body；body 支持对象、字符串、Blob、FormData |
-| `headers` | `HeadersInit` 或返回它的函数；传函数则每次（重）连重新取，token 刷新后自动生效 |
-| `parse` | `data` 解析函数，默认原样字符串 |
-| `idleTimeout` | 多久没收到任何字节就重连，`0` 关闭（服务端有心跳时建议设成心跳间隔的 3 倍） |
-| `rotateInterval` | 主动轮换间隔，`0` 关闭（见下） |
-| `retry` | 自定义重试策略 `(ctx) => 延迟ms \| false`，覆盖内置退避 |
-| `maxRetry` / `retryBaseDelay` / `retryMaxDelay` | 内置退避参数（初始化 1s，上限 30s，±20% 抖动，下限 200ms） |
-| `reconnectOnEnd` | 服务端正常结束流后是否重连，默认 `true` |
-| `strictContentType` | 强校验响应必须是 `text/event-stream`，默认 `true`；可拦住「网关返回 200 HTML」 |
-| `maxBufferSize` | 单条消息缓冲上限（字符数），默认 1MB，超过直接判定协议错误 |
-| `endSignal` | 流结束哨兵，data 等于该值（如 `[DONE]`）时按正常结束收尾且不重连 |
-| `events` | 事件白名单，只投递这些事件名；缺省全投 |
-| `pauseWhenHidden` | 页面隐藏时挂起、回前台自动重连，默认 `false`；WebView / 移动端建议开 |
-| `fetch` | 注入 fetch 实现，便于 SSR / 测试 / 自定义 transport |
-| `onHandlerError` | 回调抛错兜底，默认 `console.error`（不会中断连接） |
-实例方法：`on(event, handler)`（返回退订函数）、`once(event, handler)`、`on("*")`、`onMessage`、`onStatus`、`onError`、`onOpen`、`onClose`、`start`、`close`、`restart`；getter：`status`、`closed`、`attempts`、`lastEventId`、`done`。
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `url` | `string` | — | Request URL, including your gateway prefix |
+| `method` | `"GET" \| "POST"` | `"POST"` | HTTP method |
+| `body` | `unknown` | — | Serialized as JSON; strings, `Blob` and `FormData` are sent as-is |
+| `headers` | `HeadersInit \| () => HeadersInit \| Promise<HeadersInit>` | — | Pass a function to recompute headers on every (re)connect |
+| `parse` | `(raw: string) => unknown` | identity | Payload decoder |
+| `idleTimeout` | `number` | `0` | Reconnect when no bytes arrive for this long. Set it to ~3× the heartbeat interval |
+| `rotateInterval` | `number` | `0` | Reconnect on a schedule, even if the connection looks healthy |
+| `retry` | `(ctx) => number \| false \| Promise<number \| false>` | — | Custom retry policy, overrides the built-in backoff |
+| `maxRetry` | `number` | `Infinity` | Retry limit (only when `retry` is omitted) |
+| `retryBaseDelay` | `number` | `1000` | Delay before the first retry (ms) |
+| `retryMaxDelay` | `number` | `30000` | Upper bound for backoff (ms) |
+| `reconnectOnEnd` | `boolean` | `true` | Reconnect when the server ends the stream normally |
+| `stableAfter` | `number` | `10000` | An attempt that lived this long resets the retry counter |
+| `strictContentType` | `boolean` | `true` | Require `content-type: text/event-stream` |
+| `maxBufferSize` | `number` | `1MB` | Cap for a single message buffer (characters) |
+| `endSignal` | `string` | — | Treat this `data` value as end-of-stream, e.g. `"[DONE]"` |
+| `events` | `string[]` | — | Allow-list of event names |
+| `pauseWhenHidden` | `boolean` | `false` | Suspend while the page is hidden, reconnect when visible |
+| `autoStart` | `boolean` | `true` | Connect in the constructor |
+| `fetch` | `FetchLike` | global `fetch` | Custom transport |
+| `onHandlerError` | `(error) => void` | `console.error` | Fallback when a callback throws |
+Lifecycle hooks can be passed as options (`onOpen`, `onMessage`, `onStatus`, `onError`,
+`onClose`) or subscribed later; both forms are equivalent.
+#### Properties
+| Property | Type | Description |
+| --- | --- | --- |
+| `status` | `SSEStatus` | `idle` · `connecting` · `open` · `reconnecting` · `closed` |
+| `closed` | `boolean` | Terminal state; the client will not reconnect |
+| `attempts` | `number` | Consecutive retries; resets after a stable connection |
+| `lastEventId` | `string` | Latest event id, sent back on reconnect |
+| `done` | `Promise<void>` | Resolves when the connection terminates; never rejects |
-消息结构：`{ id, event, data, raw, receivedAt }`，`receivedAt` 便于做本地过期判断。
+#### Methods
-状态流转：`idle → connecting → open → reconnecting → closed`，`connecting/open/closed` 可直接绑 UI；断网或切后台挂起时回到 `idle`。
+| Method | Description |
+| --- | --- |
+| `start()` | Open the connection (no-op while running or suspended) |
+| `close()` | Close and stop reconnecting |
+| `restart()` | Close, then reconnect while keeping `lastEventId` |
+| `on(event, handler)` | Subscribe to one event name; returns an unsubscribe function |
+| `on("*", handler)` | Subscribe to every message |
+| `once(event, handler)` | Subscribe for a single delivery |
+| `onMessage` / `onStatus` / `onError` / `onOpen` / `onClose` | Lifecycle subscriptions |
-### 断网与前后台（默认行为）
+### `SSEMessage`
-- **断网**（`offline` 事件）：立即中断当前连接并停止重连，不再打服务端；`online` 后立刻重连（带 `Last-Event-ID`）。避免离线期间的重试风暴。
-- **切后台**：默认不影响连接；`pauseWhenHidden: true` 时页面隐藏即挂起、回到前台重连。WebView 后台会被系统挂起，留着连接只会变僵尸，移动端建议开启。
-- 主动 `close()` 会解绑这些全局监听，不留残留。
+```ts
+interface SSEMessage<T = unknown> {
+  id: string;          // event id, inherited from the previous event when omitted
+  event: string;       // "message" when the server sends no `event:` field
+  data: T;             // `parse` output
+  raw: string;         // raw payload text
+  receivedAt: number;  // client receive timestamp
+}
+```
-### 错误分类
+### Error kinds
-`SSEError.kind` 用于日志聚合和策略分支：
+`SSEError.kind` is meant for logging and for branching inside a retry policy:
-| kind | 含义 | 默认是否重连 |
+| `kind` | Meaning | Retried by default |
 | --- | --- | --- |
-| `http` | 非 2xx（`status` 有值） | 408/425/429/5xx 重连，其余终止 |
-| `network` | DNS / 连接重置等 | 是 |
-| `heartbeat` | 静默超时，连接疑似僵死 | 是 |
-| `protocol` | content-type 不符、缓冲溢出、body 不可读 | 否 |
-| `aborted` | 被中断（切后台、断网、主动关闭） | 否 |
-| `retry-exhausted` | 重试次数耗尽 | 否 |
+| `http` | Non-2xx response (`status` is set) | Yes for 408/425/429/5xx, otherwise no |
+| `network` | DNS failure, connection reset, … | Yes |
+| `heartbeat` | Idle timeout, the connection looks zombie | Yes |
+| `protocol` | Wrong `content-type`, buffer overflow, unreadable body | No |
+| `aborted` | Interrupted (hidden page, offline, manual close) | No |
+| `retry-exhausted` | Retry budget spent | No |
-### 重试策略（扩展点）
+## Recipes
-内置策略对 401/403/404 等 4xx 直接终止，只重试 408/425/429/5xx 与网络异常。需要「401 刷新 token 再重试」这类逻辑时：
+### Refresh the token on 401
+A retry policy may be async, so the refresh can complete before the next attempt:
 ```ts
 let refreshed = false;
 const client = new SSEClient({
   url,
-  // 支持 async：401 时先真正刷新 token，再决定是否重连
   retry: async ({ error, attempt }) => {
     if (error?.status === 401 && !refreshed) {
       await refreshToken();
       refreshed = true;
-      return 0; // 立即重试
+      return 0; // retry immediately
     }
     return attempt > 5 ? false : Math.min(30_000, 1000 * 2 ** attempt);
   },
 });
 ```
-## 与 AI SDK 的对照
+### Share one connection
-AI SDK（[Stream Protocols](https://ai-sdk.dev/docs/ai-sdk-ui/stream-protocol)）的流是「一条 SSE 承载多种 `data.type` part」，客户端按 part 建状态机；业务推送是「按 `event:` 路由 + 业务归并」。目标不同，但有几处可以直接借：
-| AI SDK 的做法 | 这里怎么处理 |
-| --- | --- |
-| `[DONE]` 终止哨兵 | 提供 `endSignal: "[DONE]"`。差异：AI SDK 只是**丢弃**这条、等连接关闭；我们**主动结束**，避免 `reconnectOnEnd` 下反复重连 |
-| 每条 data 过 schema 校验，失败不抛而是作为值下传 | 用 `parse` 抛错即可：只丢这一条并回调 `onHandlerError`，流不中断；不引入 zod |
-| `pipeThrough` 组合式（`TextDecoderStream` → `EventSourceParserStream` → `TransformStream`） | 提供 `createSSEMessageStream()`，用于自定义 transport / Service Worker / Edge |
-| `retryWithExponentialBackoff`：`shouldRetry` 可 async、延迟可插拔、耗尽时聚合 errors | `RetryPolicy` 支持 async 与完全自定义延迟；错误不聚合，靠 `SSEError.kind` 区分 |
-| `text-start/delta/end` 按 id 合并成 part | 推送不是 delta 协议；等价的「按 key 合并取最新」用 `createBatcher()` |
-| `useChat` 的 `status` 状态机 + `onData` 瞬时数据 | 已有 `status` 枚举 + 事件路由 |
-| transport 抽象（`prepareSendMessagesRequest` 等） | `fetch` 注入 + `headers` 函数足够 |
-| `smoothStream`、断点重放、message parts 持久化 | 未采纳——属于聊天产品语义，不是连接层能力 |
-### 连接共享
-同一份订阅被多个组件消费时，只建一条连接：
+HTTP/1.1 allows six connections per origin, and a push channel holds one open indefinitely.
+Share it instead of opening one per component:
 ```ts
+import { acquireSSEClient } from "@songfreedom/sse-client";
 const { client, release } = acquireSSEClient("alarm", () => new SSEClient({ url, body }));
-onScopeDispose(release); // 最后一个引用释放时自动 close
+onScopeDispose(release); // closes when the last consumer releases
 ```
-## 数据层放哪
-库只负责连接，**不持有业务数据**。`meos-control-web` 的做法可以拿来对照：
-| 维度 | meos-control-web | 本库 + 应用层建议 |
-| --- | --- | --- |
-| 连接 | 每个组件 `new SSEClient`，N 个组件 = N 条连接 | `acquireSSEClient(key)` 引用计数，同 key 只有一条 |
-| 数据 | 模块级单例 `DockSingleton`（内部一个全局 `ref`，按 objectId 归并） | pinia store，按业务域拆分 |
-| 过期 | 单例 `IotExpireManager` + 15s 轮询 + `expire` 事件 | 用消息上的 `receivedAt` 在 getter 里算，或 store 内自己的定时器 |
-| 合并 | `useResponsiveDockSSEHandle` 里 300ms 窗口，按 `objectId::infoCode` 去重取最新 | `createBatcher()` |
-| 生命周期 | `onMounted` 注册、`onBeforeUnmount` 反注册，手动配对 | `onScopeDispose` + 引用计数自动配对 |
-**值得借的三点**
-1. 按业务 key 增量合并（`Object.assign` 覆盖字段），避免整对象替换导致组件全量重渲染。
-2. 合并窗口（300ms）——高频推送下这是必须的，否则每次推都是「写库 → 触发渲染」。
-3. 数据过期标记：推送类数据一定有「多久没更新就算失效」的语义，UI 要能显示「暂无数据」而不是永远显示上次的值。
-**不要照搬的四点**
+### Batch high-frequency updates
-1. 全局单例当数据总线：qiankun 子应用卸载后模块级 `ref` 还在，重新挂载会带着上次的脏数据；而且没有引用计数，谁都能写、没人负责清。
-2. `window.iotHandle = ...` 这类调试钩子——应该由调试工具或 devtools 提供。
-3. 模块导入即启动定时器（`IotExpireManager.getInstance()` 在 import 时就 `startExpireCheck()`），副作用不可控。
-4. 每组件一条连接：HTTP/1.1 同域只有 6 个并发，推送通道很容易把其他接口挤排队。
-推荐的组合是 pinia（数据域）+ 本库（连接）+ 消费者引用计数（谁用谁 retain）：
+When the same entity is pushed every few hundred milliseconds, coalesce before writing to state:
 ```ts
-// stores/alarm.ts
-export const useAlarmStore = defineStore("alarm", () => {
-  const items = shallowRef<Map<string, Alarm>>(new Map());
-  const batcher = createBatcher<string, Alarm>({
-    key: (alarm) => alarm.id,
-    interval: 300,
-    onFlush: (list) => {
-      const next = new Map(items.value);
-      list.forEach((alarm) => next.set(alarm.id, alarm));
-      items.value = next; // 替换引用，shallowRef 才会触发更新
-    },
-  });
-  const client = new SSEClient<{ ALARM: Alarm }>({ url, body, autoStart: false });
-  client.on("ALARM", (alarm) => batcher.push(alarm));
-  let refs = 0;
-  function retain() {
-    refs += 1;
-    if (refs === 1) client.start();
-  }
-  function release() {
-    refs = Math.max(0, refs - 1);
-    if (refs === 0) {
-      batcher.dispose(); // 冲刷窗口内剩余数据
-      client.close();
-    }
-  }
+import { createBatcher } from "@songfreedom/sse-client";
-  return { items, retain, release };
+const batcher = createBatcher<string, Point>({
+  key: (point) => `${point.objectId}::${point.code}`,
+  interval: 300,
+  onFlush: (points) => store.applyPoints(points),
 });
-// 组件里
-const alarmStore = useAlarmStore();
-alarmStore.retain();
-onScopeDispose(() => alarmStore.release());
+client.on("IOT", (payload) => payload.data.forEach((p) => batcher.push(p)));
 ```
-如果同一条订阅要跨多个 store / 模块共享，把 `new SSEClient` 换成 `acquireSSEClient(key, factory)`，它的引用计数语义相同、且按 key 全局唯一。
+### Rotation vs reconnect
-## 服务端与网关约定
+A connection can stay alive while the server-side subscription is already gone. Rotation
+reconnects on a schedule (`rotateInterval`) to avoid such zombie connections, keeping
+`lastEventId` so nothing is missed:
-- 响应头必须是 `Content-Type: text/event-stream`（可能带 `;charset=UTF-8`，校验按前缀匹配），并且 **不能被代理层缓冲**：`proxy_buffering off; proxy_cache off;`，该路径不要开 gzip。
-- 建议每 15s 发一次 `: ping\n\n` 心跳，否则多数云 LB 的 60s idle 会断开；配合 `idleTimeout` 使用。
-- 事件 id 建议单调递增（或至少唯一）。重连时客户端会带 `Last-Event-ID`，服务端按语义只补发其后的消息；客户端不做去重。
-- 事件类型通过 `event:` 字段下发，客户端按该字段路由。
+```ts
+new SSEClient({ url, rotateInterval: 30 * 60_000 });
+```
-## 主动轮换 vs 断线重连
+This relies on the server honouring `Last-Event-ID`. An alternative is overlapping
+connections (open a replacement, then close the old one), which avoids the gap but can
+deliver duplicates when the server pushes per connection.
-轮换是为了防止「TCP 活着、心跳还在，但服务端订阅已失效」的假活连接：到 `rotateInterval` 后客户端主动断开并立即重连（保留 `lastEventId`，不走退避）。
+## Low-level building blocks
-对比双连接 overlap 方案（新连接 open 后再切旧连接）：overlap 能消除重连窗口，但要求服务端按连接推送而非按事件流推送，否则同一事件会被两条连接各推一次；本实现选择「断开 + `Last-Event-ID` 续传」，实现简单且不产生重复推送，代价是需要服务端支持续传语义。
+The client is assembled from small pieces that are exported for advanced use:
-## 开发
+```ts
+import { createSSEParser, createSSEMessageStream, createBatcher } from "@songfreedom/sse-client";
-```bash
-pnpm --filter @songfreedom/sse-client test
-pnpm --filter @songfreedom/sse-client typecheck
-pnpm --filter @songfreedom/sse-client lint
+// bytes → messages, as a standard TransformStream
+const messages = response.body!.pipeThrough(createSSEMessageStream({ parse: JSON.parse }));
+// raw frames, if you want to drive the loop yourself
+const parser = createSSEParser({ onEvent: (event) => console.log(event) });
+parser.feed("event: ping\ndata: 1\n\n");
 ```
-## 构建与发布
+## Server requirements
-**双入口设计**，开发时零构建、发布时只发产物：
+- Respond with `Content-Type: text/event-stream` (a `;charset=UTF-8` suffix is fine).
+- Do not buffer the response: `proxy_buffering off; proxy_cache off;` at the gateway,
+  and do not gzip the stream.
+- Send a heartbeat comment (`: ping\n\n`) every 15–30s, otherwise most load balancers
+  close the connection after 60s of silence. Pair it with `idleTimeout`.
+- Support `Last-Event-ID` if you want gap-free reconnects; the client sends the header but
+  does not de-duplicate events.
-| 场景 | 走哪里 | 原因 |
-| --- | --- | --- |
-| 仓库内（`apps/web` 等） | `exports` → `./src/*.ts` | Vite 直接编译源码，改库代码立即 HMR |
-| npm 包 | `dist/` + `dist/package.json` | 消费方拿到 JS + `.d.ts`，不需要编译 TS |
+## Design notes
-`pnpm build` 做两件事：`tsc` 把 `src` 编译成 ESM + `.d.ts` + sourcemap 到 `dist/`，然后由 `scripts/build-package.mjs` 生成 `dist/package.json` 并拷入 README。
+- No business logic: the client does not know about tokens, stores, toasts or routing.
+  Authentication is injected through `headers`.
+- Errors never escape as exceptions from callbacks; a throwing handler is isolated and
+  reported through `onHandlerError` while the stream keeps flowing.
+- Timers are always cleared on close, and the connection loop only exits when the client is
+  finally closed, so suspending and resuming cannot leak a loop.
-发布到 npmjs（`publishConfig` 已指向 `registry.npmjs.org` + `access: public`）：
+## Development
 ```bash
-npm login --registry https://registry.npmjs.org   # 只需一次
-pnpm --filter @songfreedom/sse-client publish:npm  # build + publish
+pnpm install
+pnpm test         # vitest
+pnpm typecheck    # tsc --noEmit
+pnpm lint         # eslint
+pnpm build        # dist/ + dist/package.json
 ```
-只想先看打包内容不发布：
+Releasing: bump the version, then
 ```bash
-pnpm --filter @songfreedom/sse-client publish --dry-run --no-git-checks
+pnpm publish:npm  # build + publish to npmjs (access: public)
 ```
-约定：
-- 发布走 `publishConfig.directory: dist`，所以**必须先 build**（`publish:npm` 已包含）。
-- `vue` 是 **optional peer**，非 Vue 项目安装不会被迫拉 vue。
-- `sideEffects: false`，消费方可 tree-shaking。
-- 版本号每次发布必须递增，npm 不允许覆盖已有版本。
 ## License
 [MIT](./LICENSE)

package/batch.d.ts CHANGED Viewed

@@ -1,8 +1,10 @@
 /**
- * 高频推送的合并窗口。
+ * Coalescing window for high-frequency streams.
  *
- * 业务推送常见「同一对象在几百毫秒内连推多次」的场景（IOT 点位、设备状态），
- * 逐条写库会引发渲染风暴。这里按业务 key 合并、保留最新值，在一个时间窗后统一回调。
+ * A single entity is often pushed several times within a few hundred
+ * milliseconds (IoT points, device state). Writing every message to state
+ * causes render storms, so messages are merged by a business key while keeping
+ * the latest value, and flushed once per window.
  *
  * ```ts
  * const batcher = createBatcher<number, Point>({
@@ -14,23 +16,23 @@
  * ```
  */
 export interface BatcherOptions<K, V> {
-    /** 合并用的业务键，同一 key 只保留最后一次的值 */
+    /** Business key used to merge values; only the last value per key survives. */
     key: (value: V) => K;
-    /** 合并窗口（毫秒），默认 300 */
+    /** Coalescing window in milliseconds (default 300). */
     interval?: number;
-    /** 窗口结束时的回调，按首次出现的顺序给出每个 key 的最新值 */
+    /** Called once per window with the latest value per key, in first-seen order. */
     onFlush: (values: V[]) => void;
 }
 export interface Batcher<V> {
-    /** 写入一条数据；同一 key 覆盖旧值 */
+    /** Accept a value; replaces any pending value with the same key. */
     push: (value: V) => void;
-    /** 立即冲刷并取消本次窗口 */
+    /** Flush immediately and cancel the pending window. */
     flush: () => void;
-    /** 丢弃尚未冲刷的数据 */
+    /** Drop pending values without flushing. */
     clear: () => void;
-    /** 冲刷并释放定时器（组件卸载时调用） */
+    /** Flush and release the timer (call on unmount). */
     dispose: () => void;
-    /** 待冲刷的数据条数 */
+    /** Number of values waiting to be flushed. */
     readonly pending: number;
 }
 export declare function createBatcher<K, V>(options: BatcherOptions<K, V>): Batcher<V>;

package/batch.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"batch.d.ts","sourceRoot":"","sources":["../src/batch.ts"],"names":[],"mappings":"AAAA~~;;;;;;;;;;;;;;GAcG~~;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,EAAE,CAAC;IAClC,+~~BAA~~+B;IAC/B,GAAG,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,CAAC;IACrB,~~sBAAsB~~;~~IACtB~~,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,~~qCAAqC~~;~~IACrC~~,OAAO,EAAE,CAAC,MAAM,EAAE,CAAC,EAAE,KAAK,IAAI,CAAC;CAChC;AAED,MAAM,WAAW,OAAO,CAAC,CAAC;IACxB,~~yBAAyB~~;~~IACzB~~,IAAI,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;IACzB,~~kBAAkB~~;~~IAClB~~,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,~~gBAAgB~~;~~IAChB~~,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,~~wBAAwB~~;~~IACxB~~,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,~~eAAe~~;~~IACf~~,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,wBAAgB,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CA4C7E"}
1	+ {"version":3,"file":"batch.d.ts","sourceRoot":"","sources":["../src/batch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,EAAE,CAAC;IAClC,+EAA+E;IAC/E,GAAG,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,CAAC;IACrB,uDAAuD;IACvD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iFAAiF;IACjF,OAAO,EAAE,CAAC,MAAM,EAAE,CAAC,EAAE,KAAK,IAAI,CAAC;CAChC;AAED,MAAM,WAAW,OAAO,CAAC,CAAC;IACxB,oEAAoE;IACpE,IAAI,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;IACzB,uDAAuD;IACvD,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,4CAA4C;IAC5C,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,qDAAqD;IACrD,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,8CAA8C;IAC9C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,wBAAgB,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CA4C7E"}

package/batch.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"batch.js","sourceRoot":"","sources":["../src/batch.ts"],"names":[],"mappings":"~~AAqCA~~,MAAM,UAAU,aAAa,CAAO,OAA6B;IAC/D,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,GAAG,CAAC;IACzC,MAAM,MAAM,GAAG,IAAI,GAAG,EAAQ,CAAC;IAC/B,IAAI,KAAK,GAAyC,IAAI,CAAC;IAEvD,MAAM,KAAK,GAAG,GAAG,EAAE;QACjB,IAAI,KAAK,EAAE,CAAC;YACV,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,KAAK,GAAG,IAAI,CAAC;QACf,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;YACjB,OAAO;QACT,CAAC;QACD,MAAM,MAAM,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;QACpC,MAAM,CAAC,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAC1B,CAAC,CAAC;IAEF,OAAO;QACL,IAAI,CAAC,KAAQ;YACX,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,CAAC;YACtC,IAAI,KAAK,EAAE,CAAC;gBACV,OAAO;YACT,CAAC;YACD,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;gBACtB,KAAK,GAAG,IAAI,CAAC;gBACb,KAAK,EAAE,CAAC;YACV,CAAC,EAAE,QAAQ,CAAC,CAAC;QACf,CAAC;QACD,KAAK;QACL,KAAK;YACH,IAAI,KAAK,EAAE,CAAC;gBACV,YAAY,CAAC,KAAK,CAAC,CAAC;gBACpB,KAAK,GAAG,IAAI,CAAC;YACf,CAAC;YACD,MAAM,CAAC,KAAK,EAAE,CAAC;QACjB,CAAC;QACD,OAAO;YACL,KAAK,EAAE,CAAC;QACV,CAAC;QACD,IAAI,OAAO;YACT,OAAO,MAAM,CAAC,IAAI,CAAC;QACrB,CAAC;KACF,CAAC;AACJ,CAAC"}
1	+ {"version":3,"file":"batch.js","sourceRoot":"","sources":["../src/batch.ts"],"names":[],"mappings":"AAuCA,MAAM,UAAU,aAAa,CAAO,OAA6B;IAC/D,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,GAAG,CAAC;IACzC,MAAM,MAAM,GAAG,IAAI,GAAG,EAAQ,CAAC;IAC/B,IAAI,KAAK,GAAyC,IAAI,CAAC;IAEvD,MAAM,KAAK,GAAG,GAAG,EAAE;QACjB,IAAI,KAAK,EAAE,CAAC;YACV,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,KAAK,GAAG,IAAI,CAAC;QACf,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;YACjB,OAAO;QACT,CAAC;QACD,MAAM,MAAM,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;QACpC,MAAM,CAAC,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAC1B,CAAC,CAAC;IAEF,OAAO;QACL,IAAI,CAAC,KAAQ;YACX,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,CAAC;YACtC,IAAI,KAAK,EAAE,CAAC;gBACV,OAAO;YACT,CAAC;YACD,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;gBACtB,KAAK,GAAG,IAAI,CAAC;gBACb,KAAK,EAAE,CAAC;YACV,CAAC,EAAE,QAAQ,CAAC,CAAC;QACf,CAAC;QACD,KAAK;QACL,KAAK;YACH,IAAI,KAAK,EAAE,CAAC;gBACV,YAAY,CAAC,KAAK,CAAC,CAAC;gBACpB,KAAK,GAAG,IAAI,CAAC;YACf,CAAC;YACD,MAAM,CAAC,KAAK,EAAE,CAAC;QACjB,CAAC;QACD,OAAO;YACL,KAAK,EAAE,CAAC;QACV,CAAC;QACD,IAAI,OAAO;YACT,OAAO,MAAM,CAAC,IAAI,CAAC;QACrB,CAAC;KACF,CAAC;AACJ,CAAC"}