@songfreedom/sse-client 0.1.0 → 0.1.1

package/README.md

@@ -1,295 +1,302 @@
 # @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`?
 
-零运行时依赖；核心只有 `fetch` + `ReadableStream` + 自研帧解析。
+| 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 |
 
-## 为什么不用现成库
+This library is roughly 3 kB gzipped, has no runtime dependencies, and only needs `fetch`
+and `ReadableStream`.
 
-| 方案 | 问题 |
-| --- | --- |
-| 原生 `EventSource` | 不能自定义请求头（鉴权 token 无处安放）、只能 GET、不能带 body、重连策略不可控 |
-| `@microsoft/fetch-event-source` | 已归档；`onopen` 里非 2xx 必须手动抛错，否则静默死循环重连；重连间隔固定；无 `Last-Event-ID` 持久化 |
-| axios | 浏览器端读不到流式响应（`responseType: "stream"` 仅 Node 有效），`onDownloadProgress` 拼字符串会在多字节字符边界处截断 |
+## Features
 
-## 设计分层
+- **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 的对照
-
-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 持久化 | 未采纳——属于聊天产品语义，不是连接层能力 |
-
-### 连接共享
+### Share one connection
 
-同一份订阅被多个组件消费时，只建一条连接：
+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 全局唯一。
-
-## 服务端与网关约定
-
-- 响应头必须是 `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:` 字段下发，客户端按该字段路由。
-
-## 主动轮换 vs 断线重连
-
-轮换是为了防止「TCP 活着、心跳还在，但服务端订阅已失效」的假活连接：到 `rotateInterval` 后客户端主动断开并立即重连（保留 `lastEventId`，不走退避）。
-
-对比双连接 overlap 方案（新连接 open 后再切旧连接）：overlap 能消除重连窗口，但要求服务端按连接推送而非按事件流推送，否则同一事件会被两条连接各推一次；本实现选择「断开 + `Last-Event-ID` 续传」，实现简单且不产生重复推送，代价是需要服务端支持续传语义。
+### 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:
 
-```bash
-pnpm --filter @songfreedom/sse-client test
-pnpm --filter @songfreedom/sse-client typecheck
-pnpm --filter @songfreedom/sse-client lint
+```ts
+new SSEClient({ url, rotateInterval: 30 * 60_000 });
 ```
 
-## 构建与发布
+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.
 
-**双入口设计**，开发时零构建、发布时只发产物：
+## Low-level building blocks
 
-| 场景 | 走哪里 | 原因 |
-| --- | --- | --- |
-| 仓库内（`apps/web` 等） | `exports` → `./src/*.ts` | Vite 直接编译源码，改库代码立即 HMR |
-| npm 包 | `dist/` + `dist/package.json` | 消费方拿到 JS + `.d.ts`，不需要编译 TS |
+The client is assembled from small pieces that are exported for advanced use:
 
-`pnpm build` 做两件事：`tsc` 把 `src` 编译成 ESM + `.d.ts` + sourcemap 到 `dist/`，然后由 `scripts/build-package.mjs` 生成 `dist/package.json` 并拷入 README。
+```ts
+import { createSSEParser, createSSEMessageStream, createBatcher } from "@songfreedom/sse-client";
 
-发布到 npmjs（`publishConfig` 已指向 `registry.npmjs.org` + `access: public`）：
+// bytes → messages, as a standard TransformStream
+const messages = response.body!.pipeThrough(createSSEMessageStream({ parse: JSON.parse }));
 
-```bash
-npm login --registry https://registry.npmjs.org   # 只需一次
-pnpm --filter @songfreedom/sse-client publish:npm  # build + publish
+// 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
 
-```bash
-pnpm --filter @songfreedom/sse-client publish --dry-run --no-git-checks
-```
+- 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.
 
-约定：
+## Design notes
 
-- 发布走 `publishConfig.directory: dist`，所以**必须先 build**（`publish:npm` 已包含）。
-- `vue` 是 **optional peer**，非 Vue 项目安装不会被迫拉 vue。
-- `sideEffects: false`，消费方可 tree-shaking。
-- 版本号每次发布必须递增，npm 不允许覆盖已有版本。
+- 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.
 
 ## License
 
 [MIT](./LICENSE)
-

package/batch.d.ts

@@ -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

@@ -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"}
+{"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

@@ -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"}
+{"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"}