@songfreedom/sse-client 0.1.0 → 0.1.1

package/client.d.ts

@@ -1,97 +1,107 @@
 import { SSEError } from "./errors.js";
 import type { SSECloseReason, SSEEventMap, SSEMessage, SSEStatus, Unsubscribe } from "./types.js";
-/** 与 `fetch` 同形，便于注入自定义 transport（SSR、测试、带签名的请求） */
+/** Same shape as `fetch`; inject a custom transport for SSR, tests or signed requests. */
 export type FetchLike = (input: string, init: RequestInit) => Promise<Response>;
-/** 重试决策上下文 */
+/** Context passed to a retry policy. */
 export interface RetryContext {
-    /** 第几次重试，从 1 开始 */
+    /** Retry number, starting at 1. */
     attempt: number;
-    /** 触发重连的原因；服务端正常结束流时为 undefined */
+    /** Why the reconnect happens; `undefined` when the server closed the stream normally. */
     error?: SSEError;
-    /** 本次连接存活时长（毫秒） */
+    /** How long the attempt was alive, in milliseconds. */
     elapsed: number;
 }
 /**
- * 自定义重试策略：返回下次重连延迟（毫秒），返回 `false` 表示终止。
- * 支持 async，便于「401 → 先刷新 token → 再重试」这类需要等待的决策。
- * 不传则使用内置的「指数退避 + 抖动 + 最大次数」。
+ * Custom retry policy: return the delay in milliseconds before the next attempt,
+ * or `false` to give up. May be async, which makes flows such as
+ * "401 → refresh the token → retry" straightforward. When omitted, the built-in
+ * exponential backoff with jitter and a max attempt count is used.
  */
 export type RetryPolicy = (context: RetryContext) => number | false | Promise<number | false>;
-/** 客户端配置 */
+/** Client options. */
 export interface SSEClientOptions {
-    /** 请求地址（需自行带上网关前缀） */
+    /** Request URL (include your gateway prefix yourself). */
     url: string;
-    /** 请求方法，业务推送一般用 POST */
+    /** HTTP method; business push endpoints usually use POST. */
     method?: "GET" | "POST";
-    /** 请求体，非 GET 时按 JSON 序列化；也支持直接传字符串 / Blob / FormData */
+    /** Request body. Serialized as JSON, or passed through when it is a string / Blob / FormData. */
     body?: unknown;
     /**
-     * 额外请求头。传函数则每次（重）连都重新取，
-     * 便于拿到最新 token，因此推荐 `() => getCommonHeaders()`。
+     * Extra headers. Pass a function to recompute them before every (re)connect,
+     * which is the recommended way to pick up a refreshed token:
+     * `() => getAuthHeaders()`.
      */
     headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
-    /** data 解析，例如 `(raw) => JSON.parse(raw)`；不传则 data 为原始字符串 */
+    /** Payload decoder, e.g. `(raw) => JSON.parse(raw)`. Defaults to the raw string. */
     parse?: (raw: string) => unknown;
-    /** 空闲超时（毫秒）：多久没收到任何字节就断开重连，0 表示关闭。建议取心跳间隔的 2~3 倍 */
+    /**
+     * Idle timeout in milliseconds: reconnect when no bytes arrived for this long.
+     * `0` disables it. Two to three times the server heartbeat interval is a good value.
+     */
     idleTimeout?: number;
-    /** 主动轮换间隔（毫秒）：到点后主动重连，防止连接假活，0 表示关闭 */
+    /** Proactive rotation interval in milliseconds: reconnect on schedule to avoid zombie connections. `0` disables it. */
     rotateInterval?: number;
-    /** 自定义重试策略，覆盖内置退避 */
+    /** Custom retry policy, overrides the built-in backoff. */
     retry?: RetryPolicy;
-    /** 最大重试次数，默认无限（仅在未传 `retry` 时生效） */
+    /** Maximum retry count, unlimited by default (only used when `retry` is not provided). */
     maxRetry?: number;
-    /** 首次重连延迟（毫秒），默认 1000 */
+    /** Delay before the first retry in milliseconds, defaults to 1000. */
     retryBaseDelay?: number;
-    /** 重连延迟上限（毫秒），默认 30000 */
+    /** Upper bound for reconnect delays in milliseconds, defaults to 30000. */
     retryMaxDelay?: number;
-    /** 服务端正常结束流后是否自动重连，默认 true */
+    /** Reconnect when the server closes the stream normally, defaults to true. */
     reconnectOnEnd?: boolean;
-    /** 连接存活超过该时长即视为稳定，重置重试计数，默认 10000 */
+    /** An attempt that lived at least this long resets the retry counter, defaults to 10000. */
     stableAfter?: number;
     /**
-     * 强校验响应 `content-type` 必须是 `text/event-stream`，默认 true。
-     * 能拦住「网关/鉴权页返回 200 HTML」这类静默失败；后端不规范时可关闭。
+     * Require the response `content-type` to be `text/event-stream`, defaults to true.
+     * This catches silent failures such as a gateway returning a 200 HTML page;
+     * disable it for non-compliant backends.
      */
     strictContentType?: boolean;
-    /** 单条消息缓冲上限（字符数），默认 1MB，防止异常流撑爆内存 */
+    /** Cap for a single message buffer in characters, defaults to 1MB, guards against runaway streams. */
     maxBufferSize?: number;
     /**
-     * 流结束哨兵：data 等于该值时视为正常结束（OpenAI / AI SDK 风格用 `[DONE]`），
-     * 触发后按「正常结束」收尾且不再重连。默认不启用。
+     * Stream-end sentinel: when `data` equals this value the stream is treated as
+     * finished (OpenAI / AI SDK style `[DONE]`) and no reconnect happens.
+     * Disabled by default.
      */
     endSignal?: string;
-    /** 事件白名单：只投递这些事件名，缺省全部投递 */
+    /** Event allow-list: only these event names are dispatched. All events are dispatched when omitted. */
     events?: string[];
     /**
-     * 页面隐藏时挂起连接、回到前台自动重连，默认 false。
-     * WebView / 移动端建议开启（后台会被系统挂起，留着连接只会变僵尸）。
+     * Suspend the connection while the page is hidden and reconnect when it becomes
+     * visible again. Defaults to false; recommended for WebViews and mobile, where
+     * the OS freezes background pages and leaves zombie connections behind.
      */
     pauseWhenHidden?: boolean;
-    /** 是否在构造后立即连接，默认 true */
+    /** Connect in the constructor, defaults to true. */
     autoStart?: boolean;
-    /** 注入 fetch 实现，默认使用全局 fetch */
+    /** Inject a fetch implementation, defaults to the global `fetch`. */
     fetch?: FetchLike;
-    /** 事件处理函数抛错时的兜底，默认打到控制台 */
+    /** Fallback when a handler throws, defaults to `console.error`. */
     onHandlerError?: (error: unknown) => void;
-    /** 连接建立（已收到响应头）时触发，等价于 `client.onOpen()` */
+    /** Fired once the connection is established (response headers received). Same as `client.onOpen()`. */
     onOpen?: (response: Response) => void;
-    /** 所有消息都会触发，等价于 `client.onMessage()` */
+    /** Fired for every message. Same as `client.onMessage()`. */
     onMessage?: (message: SSEMessage) => void;
-    /** 状态变化，等价于 `client.onStatus()` */
+    /** Fired on every state change. Same as `client.onStatus()`. */
     onStatus?: (status: SSEStatus) => void;
-    /** 每次失败触发，等价于 `client.onError()` */
+    /** Fired for every failed attempt. Same as `client.onError()`. */
     onError?: (error: SSEError, attempt: number) => void;
-    /** 最终关闭时触发一次，等价于 `client.onClose()` */
+    /** Fired once when the connection is finally closed. Same as `client.onClose()`. */
     onClose?: (reason: SSECloseReason, error?: SSEError) => void;
 }
 /**
- * SSE 客户端。
+ * Server-Sent Events client.
  *
- * - 基于 `fetch` + `ReadableStream`，支持自定义请求头与 POST body
- * - 断线自动重连（指数退避 + 抖动），401 等不可重试错误直接终止
- * - 用 `Last-Event-ID` 做断点续传
- * - 按事件名路由到多个订阅者，一条连接服务多个组件
- * - 空闲看门狗、主动轮换、断网/切后台挂起、连接共享（见 `acquireSSEClient`）
+ * - Built on `fetch` + `ReadableStream`, so custom headers and POST bodies work
+ * - Reconnects automatically (exponential backoff with jitter); terminal errors
+ *   such as 401 stop immediately
+ * - Resumes with `Last-Event-ID`
+ * - Routes events by name to multiple subscribers, so one connection serves many components
+ * - Idle watchdog, proactive rotation, offline/background suspension, shared
+ *   connections (see `acquireSSEClient`)
  */
 export declare class SSEClient<E extends object = SSEEventMap> {
     private readonly options;
@@ -123,29 +133,29 @@ export declare class SSEClient<E extends object = SSEEventMap> {
     private readonly openHandlers;
     private readonly closeHandlers;
     constructor(options: SSEClientOptions);
-    /** 当前状态 */
+    /** Current state. */
     get status(): SSEStatus;
-    /** 是否已最终关闭（不会再重连） */
+    /** Whether the client is finally closed and will not reconnect. */
     get closed(): boolean;
-    /** 连续重试次数，连接稳定后归零 */
+    /** Consecutive retry count; resets once a connection proves stable. */
     get attempts(): number;
-    /** 最近一次事件 id，重连时通过 Last-Event-ID 带给服务端 */
+    /** Latest event id, sent back as `Last-Event-ID` on reconnect. */
     get lastEventId(): string;
-    /** 连接终止（无论正常关闭还是放弃重连）后 resolve，不会 reject */
+    /** Resolves when the connection terminates (closed or retries exhausted). Never rejects. */
     get done(): Promise<void>;
-    /** 建立连接；已连接或已挂起时调用无副作用 */
+    /** Open the connection. No-op while already running or suspended. */
     start(): this;
-    /** 主动关闭，不再重连 */
+    /** Close the connection and stop reconnecting. */
     close(): void;
-    /** 关闭后重新连接，保留 lastEventId 以便续传 */
+    /** Reconnect after closing, keeping `lastEventId` so the server can resume. */
     restart(): this;
-    /** 订阅指定事件名的消息，返回取消订阅函数 */
+    /** Subscribe to one event name; returns an unsubscribe function. */
     on<K extends Extract<keyof E, string>>(event: K, handler: (data: E[K], message: SSEMessage) => void): Unsubscribe;
-    /** 订阅所有消息（event 为 "*"） */
+    /** Subscribe to every message by passing `"*"`. */
     on(event: "*", handler: (data: unknown, message: SSEMessage) => void): Unsubscribe;
-    /** 只订阅一次，触发后自动退订 */
+    /** Subscribe to one event name for a single delivery. */
     once<K extends Extract<keyof E, string>>(event: K, handler: (data: E[K], message: SSEMessage) => void): Unsubscribe;
-    /** 订阅所有消息（不区分事件名） */
+    /** Subscribe to every message regardless of event name. */
     onMessage(handler: (message: SSEMessage) => void): Unsubscribe;
     onStatus(handler: (status: SSEStatus) => void): Unsubscribe;
     onError(handler: (error: SSEError, attempt: number) => void): Unsubscribe;
@@ -158,7 +168,7 @@ export declare class SSEClient<E extends object = SSEEventMap> {
     private get reconnectOnEnd();
     private reset;
     private connect;
-    /** 建立一次连接并持续读取，直到流结束（失败时抛错） */
+    /** Open one connection and read it until the stream ends (throws on failure). */
     private openOnce;
     private resolveHeaders;
     private handleParsedEvent;
@@ -167,7 +177,7 @@ export declare class SSEClient<E extends object = SSEEventMap> {
     private safeCall;
     private reportHandlerError;
     private decideDelay;
-    /** 重连延迟：服务端 `retry:` 优先，否则指数退避 + ±20% 抖动 */
+    /** Reconnect delay: the server's `retry:` wins, otherwise exponential backoff with ±20% jitter. */
     private nextDelay;
     private sleep;
     private waitForResume;
@@ -177,7 +187,7 @@ export declare class SSEClient<E extends object = SSEEventMap> {
     private clearRotate;
     private clearTimers;
     private setState;
-    /** 网络上下线始终启用：断网期间不重连，恢复后立即重连 */
+    /** Network state is always observed: no reconnects while offline, an immediate one when back online. */
     private bindLifecycle;
     private unbindLifecycle;
     private suspend;

package/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/client.js

@@ -1,16 +1,18 @@
 import { SSEError, isRetryableStatus, toSSEError } from "./errors.js";
 import { DEFAULT_MAX_BUFFER_SIZE, createSSEParser, } from "./parser.js";
 const EVENT_STREAM_CONTENT_TYPE = "text/event-stream";
-/** 防止「刚连上就断」时形成紧循环 */
+/** Prevents tight reconnect loops when the server drops the connection immediately. */
 const MIN_RETRY_DELAY = 200;
 /**
- * SSE 客户端。
+ * Server-Sent Events client.
  *
- * - 基于 `fetch` + `ReadableStream`，支持自定义请求头与 POST body
- * - 断线自动重连（指数退避 + 抖动），401 等不可重试错误直接终止
- * - 用 `Last-Event-ID` 做断点续传
- * - 按事件名路由到多个订阅者，一条连接服务多个组件
- * - 空闲看门狗、主动轮换、断网/切后台挂起、连接共享（见 `acquireSSEClient`）
+ * - Built on `fetch` + `ReadableStream`, so custom headers and POST bodies work
+ * - Reconnects automatically (exponential backoff with jitter); terminal errors
+ *   such as 401 stop immediately
+ * - Resumes with `Last-Event-ID`
+ * - Routes events by name to multiple subscribers, so one connection serves many components
+ * - Idle watchdog, proactive rotation, offline/background suspension, shared
+ *   connections (see `acquireSSEClient`)
  */
 export class SSEClient {
     options;
@@ -43,7 +45,7 @@ export class SSEClient {
     closeHandlers = new Set();
     constructor(options) {
         if (!options?.url) {
-            throw new Error("[sse-client] 缺少 url");
+            throw new Error("[sse-client] missing required option: url");
         }
         this.options = options;
         this.parser = createSSEParser({
@@ -68,27 +70,27 @@ export class SSEClient {
             this.start();
         }
     }
-    /** 当前状态 */
+    /** Current state. */
     get status() {
         return this.state;
     }
-    /** 是否已最终关闭（不会再重连） */
+    /** Whether the client is finally closed and will not reconnect. */
     get closed() {
         return this.finished;
     }
-    /** 连续重试次数，连接稳定后归零 */
+    /** Consecutive retry count; resets once a connection proves stable. */
     get attempts() {
         return this.attempt;
     }
-    /** 最近一次事件 id，重连时通过 Last-Event-ID 带给服务端 */
+    /** Latest event id, sent back as `Last-Event-ID` on reconnect. */
     get lastEventId() {
         return this.lastEventIdValue;
     }
-    /** 连接终止（无论正常关闭还是放弃重连）后 resolve，不会 reject */
+    /** Resolves when the connection terminates (closed or retries exhausted). Never rejects. */
     get done() {
         return this.runPromise ?? Promise.resolve();
     }
-    /** 建立连接；已连接或已挂起时调用无副作用 */
+    /** Open the connection. No-op while already running or suspended. */
     start() {
         if (this.running || this.suspended) {
             return this;
@@ -96,7 +98,8 @@ export class SSEClient {
         if (this.finished) {
             this.reset();
         }
-        // 页面本来就不可见时先不发请求，等 visibilitychange 再建连（WebView 预加载场景常见）
+        // Do not request anything while the page is hidden; wait for visibilitychange.
+        // This is the usual case for WebView preloading.
         if (this.options.pauseWhenHidden &&
             typeof document !== "undefined" &&
             document.hidden) {
@@ -108,7 +111,7 @@ export class SSEClient {
         this.bindLifecycle();
         this.runPromise = this.connect()
             .catch((error) => {
-            // 兜底：调用方回调抛错也不能变成未处理的 Promise 拒绝
+            // Safety net: a throwing callback must not become an unhandled rejection.
             this.finish("error", toSSEError(error));
         })
             .finally(() => {
@@ -116,14 +119,14 @@ export class SSEClient {
         });
         return this;
     }
-    /** 主动关闭，不再重连 */
+    /** Close the connection and stop reconnecting. */
     close() {
         if (this.finished) {
             return;
         }
         this.finish("user");
     }
-    /** 关闭后重新连接，保留 lastEventId 以便续传 */
+    /** Reconnect after closing, keeping `lastEventId` so the server can resume. */
     restart() {
         this.close();
         return this.start();
@@ -146,7 +149,7 @@ export class SSEClient {
             }
         };
     }
-    /** 只订阅一次，触发后自动退订 */
+    /** Subscribe to one event name for a single delivery. */
     once(event, handler) {
         const off = this.on(event, (data, message) => {
             off();
@@ -154,7 +157,7 @@ export class SSEClient {
         });
         return off;
     }
-    /** 订阅所有消息（不区分事件名） */
+    /** Subscribe to every message regardless of event name. */
     onMessage(handler) {
         return subscribe(this.messageHandlers, handler);
     }
@@ -171,7 +174,7 @@ export class SSEClient {
         return subscribe(this.closeHandlers, handler);
     }
     // ---------------------------------------------------------------------------
-    // 内部实现
+    // Internals
     // ---------------------------------------------------------------------------
     get retryBaseDelay() {
         return this.options.retryBaseDelay ?? 1000;
@@ -203,7 +206,7 @@ export class SSEClient {
     async connect() {
         while (!this.finished) {
             if (this.suspended) {
-                // 挂起期间不重连，等 resume() 唤醒
+                // Do not reconnect while suspended; wait for resume() to wake us up.
                 await this.waitForResume();
                 continue;
             }
@@ -227,19 +230,24 @@ export class SSEClient {
                 this.setState("idle");
                 continue;
             }
-            // 主动轮换：立即重连并保留 lastEventId，不走退避
+            // Proactive rotation: reconnect immediately, keeping lastEventId and skipping backoff.
             if (this.rotating) {
                 this.rotating = false;
                 this.attempt = 0;
                 continue;
             }
-            // 空闲超时按「可重试的网络异常」处理，避免心跳缺失时连接假死
+            // Treat an idle timeout as a retryable network error so a missing
+            // heartbeat cannot leave a zombie connection behind.
             if (this.idleTimedOut) {
                 this.idleTimedOut = false;
-                failure = new SSEError("SSE 连接空闲超时，准备重连", { kind: "heartbeat", retryable: true });
+                failure = new SSEError("SSE idle timeout, reconnecting", {
+                    kind: "heartbeat",
+                    retryable: true,
+                });
             }
             const elapsed = Date.now() - startedAt;
-            // 连接存活足够久，说明本次失败是偶发的，重置重试计数
+            // A connection that lived long enough means the failure was transient,
+            // so reset the retry budget.
             if (elapsed >= this.stableAfter) {
                 this.attempt = 0;
             }
@@ -264,7 +272,7 @@ export class SSEClient {
             await this.sleep(delay);
         }
     }
-    /** 建立一次连接并持续读取，直到流结束（失败时抛错） */
+    /** Open one connection and read it until the stream ends (throws on failure). */
     async openOnce(signal) {
         const { url, method = "POST", body, fetch: fetchImpl } = this.options;
         const init = {
@@ -277,7 +285,7 @@ export class SSEClient {
         };
         const response = fetchImpl ? await fetchImpl(url, init) : await fetch(url, init);
         if (!response.ok) {
-            throw new SSEError(`SSE 请求失败：HTTP ${response.status}`, {
+            throw new SSEError(`SSE request failed: HTTP ${response.status}`, {
                 kind: "http",
                 status: response.status,
                 retryable: isRetryableStatus(response.status),
@@ -286,12 +294,13 @@ export class SSEClient {
         if (this.options.strictContentType !== false) {
             const contentType = (response.headers.get("content-type") ?? "").toLowerCase();
             if (!contentType.startsWith(EVENT_STREAM_CONTENT_TYPE)) {
-                // 最典型的两种原因：被网关/鉴权页拦截返回 HTML，或后端没设 produces
-                throw new SSEError(`SSE 响应的 content-type 不是 ${EVENT_STREAM_CONTENT_TYPE}，实际为 "${contentType || "(空)"}"`, { kind: "protocol", status: response.status, retryable: false });
+                // Two usual causes: a gateway/auth page returned HTML, or the backend
+                // did not declare produces.
+                throw new SSEError(`SSE response content-type is not ${EVENT_STREAM_CONTENT_TYPE} (got "${contentType || "(empty)"}")`, { kind: "protocol", status: response.status, retryable: false });
             }
         }
         if (!response.body) {
-            throw new SSEError("当前环境不支持流式响应读取（response.body 为空）", {
+            throw new SSEError("Streaming is not supported in this environment (response.body is null)", {
                 kind: "protocol",
                 status: response.status,
                 retryable: false,
@@ -302,7 +311,7 @@ export class SSEClient {
         this.emit(this.openHandlers, response);
         this.parser.reset();
         const reader = response.body.getReader();
-        // 用 stream 模式解码，避免多字节字符被切在两个 chunk 之间时出现乱码
+        // Decode in streaming mode so multi-byte characters split across chunks survive.
         const decoder = new TextDecoder("utf-8");
         this.armIdle();
         try {
@@ -314,8 +323,9 @@ export class SSEClient {
                 this.armIdle();
                 this.parser.feed(decoder.decode(value, { stream: true }));
                 if (this.parser.overflowed) {
-                    // 服务端从不发空行或单条消息过大，重连也不会好转
-                    throw new SSEError("SSE 数据超出解析缓冲上限，已重置连接", {
+                    // The server never terminates a line, or a single message is huge;
+                    // reconnecting would not help.
+                    throw new SSEError("SSE buffer size limit exceeded, connection reset", {
                         kind: "protocol",
                         retryable: false,
                     });
@@ -328,7 +338,7 @@ export class SSEClient {
                 reader.releaseLock();
             }
             catch {
-                // abort 之后 releaseLock 可能抛错，忽略即可
+                // releaseLock can throw after an abort; that is fine.
             }
             this.clearIdle();
             this.clearRotate();
@@ -350,7 +360,8 @@ export class SSEClient {
         return resolved;
     }
     handleParsedEvent(event) {
-        // 结束哨兵要在 parse 之前判断：`[DONE]` 不是合法 JSON，先解析会直接报错
+        // Check the end sentinel before parsing: `[DONE]` is not valid JSON and
+        // would make the parser throw.
         if (this.options.endSignal !== undefined && event.data === this.options.endSignal) {
             this.finish("end");
             return;
@@ -370,7 +381,7 @@ export class SSEClient {
             this.lastEventIdValue = id;
         }
         const name = event.event || "message";
-        // 白名单过滤放在 id 更新之后，保证续传位置不回退
+        // Filter after updating the id so the resume position never moves backwards.
         if (this.eventFilter && !this.eventFilter.has(name)) {
             return;
         }
@@ -417,7 +428,7 @@ export class SSEClient {
             this.options.onHandlerError(error);
             return;
         }
-        console.error("[sse-client] 回调函数抛出异常", error);
+        console.error("[sse-client] a callback threw", error);
     }
     async decideDelay(context) {
         if (this.options.retry) {
@@ -431,7 +442,7 @@ export class SSEClient {
         }
         return this.nextDelay(context.attempt);
     }
-    /** 重连延迟：服务端 `retry:` 优先，否则指数退避 + ±20% 抖动 */
+    /** Reconnect delay: the server's `retry:` wins, otherwise exponential backoff with ±20% jitter. */
     nextDelay(attempt) {
         if (this.serverRetryDelay !== undefined) {
             return Math.max(Math.min(this.serverRetryDelay, this.retryMaxDelay), MIN_RETRY_DELAY);
@@ -462,7 +473,7 @@ export class SSEClient {
             return Promise.resolve();
         }
         return new Promise((resolve) => {
-            // 只由 resume() / finish() 唤醒，循环因此不会在挂起时退出
+            // Only resume() / finish() wake this up, so the loop never exits while suspended.
             this.resumeWaiter = resolve;
         });
     }
@@ -512,9 +523,9 @@ export class SSEClient {
         this.emit(this.statusHandlers, next);
     }
     // ---------------------------------------------------------------------------
-    // 断网 / 切后台
+    // Offline / background handling
     // ---------------------------------------------------------------------------
-    /** 网络上下线始终启用：断网期间不重连，恢复后立即重连 */
+    /** Network state is always observed: no reconnects while offline, an immediate one when back online. */
     bindLifecycle() {
         if (this.lifecycleBound) {
             return;
@@ -590,21 +601,21 @@ export class SSEClient {
         this.unbindLifecycle();
         this.cancelController.abort();
         this.attemptController?.abort();
-        // 唤醒可能卡在「挂起等待」里的连接循环
+        // Wake the connection loop in case it is waiting on a suspended state.
         this.resumeWaiter?.();
         this.resumeWaiter = null;
         this.setState("closed");
         this.emit(this.closeHandlers, reason, error);
     }
 }
-/** 请求体序列化：字符串 / Blob / FormData 原样发送，其余按 JSON */
+/** Serialize the body: strings / Blob / FormData pass through, everything else becomes JSON. */
 function serializeBody(body) {
     if (typeof body === "string" || body instanceof Blob || body instanceof FormData) {
         return body;
     }
     return JSON.stringify(body);
 }
-/** 统一的订阅/退订实现 */
+/** Shared subscribe/unsubscribe implementation. */
 function subscribe(handlers, handler) {
     handlers.add(handler);
     return () => {