@base-web-kits/base-tools-ts 1.3.4 → 1.3.5

package/dist/buffer/PolyfillTextDecoder.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 模拟 TextDecoder 的简单实现
+ * @description 用于在不支持 TextDecoder 的环境（如小程序）中进行流式解码
+ */
+declare class PolyfillTextDecoder {
+    private leftOver;
+    decode(input?: ArrayBuffer | Uint8Array, options?: {
+        stream?: boolean;
+    }): string;
+}
+export default PolyfillTextDecoder;
+//# sourceMappingURL=PolyfillTextDecoder.d.ts.map

package/dist/buffer/PolyfillTextDecoder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PolyfillTextDecoder.d.ts","sourceRoot":"","sources":["../../src/ts/buffer/PolyfillTextDecoder.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,cAAM,mBAAmB;IACvB,OAAO,CAAC,QAAQ,CAAiC;IAEjD,MAAM,CAAC,KAAK,CAAC,EAAE,WAAW,GAAG,UAAU,EAAE,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,MAAM;CAmIjF;AAED,eAAe,mBAAmB,CAAC"}

package/dist/buffer/SSEParser.d.ts

@@ -0,0 +1,81 @@
+/** 流式数据消息 */
+export type SSEMessage = {
+    /**
+     * SSE 消息类型
+     * - 'DONE' 流式数据接收完毕
+     * - 'thinking' 思考中
+     * - 'text' 文本内容
+     * - 其他业务类型
+     */
+    type?: string;
+    /** SSE 事件 ID (如 'id:123') */
+    id?: string;
+    /** SSE 建议重连时间 (毫秒, 如 'retry:5000') */
+    retry?: number;
+    /** SSE 事件类型 (如 'event:customEvent') */
+    event?: string;
+    /**
+     * 除type之外的其他data数据
+     * - 思考中 'data:{"type": "thinking", "content": "xx"}' -> {type: 'thinking', content: 'xx'}
+     * - JSON数据 'data:{"type": "text", "content": "xx"}' -> {type: 'text', content: 'xx'}
+     * - 非JSON数据 'data:xx' -> {raw: 'xx'}
+     * - 接收完毕 'data:[DONE]' -> {type: 'DONE'}
+     */
+    [key: string]: any;
+};
+/** 流式数据消息回调 */
+export type MessageCallback = (msg: SSEMessage) => void;
+/**
+ * 流式数据解析器
+ * - 对于不支持TextDecoder的环境，使用PolyfillTextDecoder (bufferToText流式增强版)
+ * @description 用于解析 SSE 流式数据，将其转换为 SSEMessage 格式并调用回调函数处理
+ * @param onMessage 消息回调
+ * @example
+ * const parser = new SSEParser((msg) => {
+ *   console.log(msg);
+ * });
+ * parser.receive(arrayBuffer);
+ */
+export declare class SSEParser {
+    private buffer;
+    private onMessage;
+    private decoder;
+    private eventDataLines;
+    private eventType?;
+    private eventId?;
+    private eventRetry?;
+    constructor(onMessage: MessageCallback);
+    /**
+     * 接收流式数据
+     * @param buffer ArrayBuffer
+     */
+    receive(buffer: ArrayBuffer): void;
+    /**
+     * 刷新解码器残留数据并处理尾部未换行的内容
+     */
+    flush(): void;
+    /**
+     * 追加文本并按行拆分处理，保留不完整尾行
+     * @param text 新到达的文本片段
+     */
+    private appendText;
+    /**
+     * 处理缓冲区中剩余的尾行内容
+     */
+    private flushRemainder;
+    /**
+     * 解析每行 SSE 数据并触发回调
+     * @param lines 以换行切分后的行内容
+     */
+    private processLines;
+    /**
+     * 将当前缓存的一次 SSE 事件分发给回调
+     * @description 以空行作为事件边界，将多行 data 合并后再解析；处理 "[DONE]" 结束标记；分发完成后会重置事件缓存
+     */
+    private dispatchEvent;
+    /** 安全调用 onMessage 回调，捕获并打印错误 */
+    private safeOnMessage;
+    /** 重置当前 SSE 事件的临时缓存 */
+    private resetEvent;
+}
+//# sourceMappingURL=SSEParser.d.ts.map

package/dist/buffer/SSEParser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SSEParser.d.ts","sourceRoot":"","sources":["../../src/ts/buffer/SSEParser.ts"],"names":[],"mappings":"AAGA,aAAa;AACb,MAAM,MAAM,UAAU,GAAG;IACvB;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,6BAA6B;IAC7B,EAAE,CAAC,EAAE,MAAM,CAAC;IAEZ,sCAAsC;IACtC,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,uCAAuC;IACvC,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;;;OAMG;IACH,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB,CAAC;AAEF,eAAe;AACf,MAAM,MAAM,eAAe,GAAG,CAAC,GAAG,EAAE,UAAU,KAAK,IAAI,CAAC;AAExD;;;;;;;;;;GAUG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,SAAS,CAAkB;IACnC,OAAO,CAAC,OAAO,CAAoC;IACnD,OAAO,CAAC,cAAc,CAAgB;IACtC,OAAO,CAAC,SAAS,CAAC,CAAS;IAC3B,OAAO,CAAC,OAAO,CAAC,CAAS;IACzB,OAAO,CAAC,UAAU,CAAC,CAAS;gBAEhB,SAAS,EAAE,eAAe;IAMtC;;;OAGG;IACH,OAAO,CAAC,MAAM,EAAE,WAAW;IAK3B;;OAEG;IACH,KAAK;IAOL;;;OAGG;IACH,OAAO,CAAC,UAAU;IASlB;;OAEG;IACH,OAAO,CAAC,cAAc;IAUtB;;;OAGG;IACH,OAAO,CAAC,YAAY;IAqCpB;;;OAGG;IACH,OAAO,CAAC,aAAa;IAyCrB,gCAAgC;IAChC,OAAO,CAAC,aAAa;IAQrB,uBAAuB;IACvB,OAAO,CAAC,UAAU;CAMnB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base-web-kits/base-tools-ts",
-  "version": "1.3.4",
+  "version": "1.3.5",
   "sideEffects": false,
   "description": "Independent TS utilities package built from src/ts.",
   "keywords": [

package/src/ts/buffer/PolyfillTextDecoder.ts

@@ -0,0 +1,141 @@
+/**
+ * 模拟 TextDecoder 的简单实现
+ * @description 用于在不支持 TextDecoder 的环境（如小程序）中进行流式解码
+ */
+class PolyfillTextDecoder {
+  private leftOver: Uint8Array = new Uint8Array(0);
+
+  decode(input?: ArrayBuffer | Uint8Array, options?: { stream?: boolean }): string {
+    const stream = options?.stream ?? false;
+    let bytes: Uint8Array;
+
+    if (!input) {
+      bytes = new Uint8Array(0);
+    } else if (input instanceof ArrayBuffer) {
+      bytes = new Uint8Array(input);
+    } else {
+      bytes = input;
+    }
+
+    if (this.leftOver.length > 0) {
+      const merged = new Uint8Array(this.leftOver.length + bytes.length);
+      merged.set(this.leftOver);
+      merged.set(bytes, this.leftOver.length);
+      bytes = merged;
+      this.leftOver = new Uint8Array(0);
+    }
+
+    const len = bytes.length;
+    if (len === 0) return '';
+
+    const parts: string[] = [];
+    let i = 0;
+    const replacement = '\uFFFD';
+    const isContinuationByte = (b: number) => (b & 0xc0) === 0x80;
+
+    while (i < len) {
+      const byte1 = bytes[i];
+
+      // 1字节字符 (0xxxxxxx)
+      if (byte1 < 0x80) {
+        parts.push(String.fromCharCode(byte1));
+        i += 1;
+      }
+      // 2字节字符 (110xxxxx 10xxxxxx)
+      else if (byte1 >= 0xc2 && byte1 < 0xe0) {
+        if (i + 1 >= len) {
+          if (stream) {
+            this.leftOver = bytes.slice(i);
+            break;
+          }
+          parts.push(replacement);
+          break;
+        }
+        const byte2 = bytes[i + 1];
+        if (!isContinuationByte(byte2)) {
+          parts.push(replacement);
+          i += 1;
+          continue;
+        }
+        parts.push(String.fromCharCode(((byte1 & 0x1f) << 6) | (byte2 & 0x3f)));
+        i += 2;
+      }
+      // 3字节字符 (1110xxxx 10xxxxxx 10xxxxxx)
+      else if (byte1 >= 0xe0 && byte1 < 0xf0) {
+        if (i + 2 >= len) {
+          if (stream) {
+            this.leftOver = bytes.slice(i);
+            break;
+          }
+          parts.push(replacement);
+          break;
+        }
+        const byte2 = bytes[i + 1];
+        const byte3 = bytes[i + 2];
+        if (!isContinuationByte(byte2) || !isContinuationByte(byte3)) {
+          parts.push(replacement);
+          i += 1;
+          continue;
+        }
+        if (byte1 === 0xe0 && byte2 < 0xa0) {
+          parts.push(replacement);
+          i += 3;
+          continue;
+        }
+        if (byte1 === 0xed && byte2 >= 0xa0) {
+          parts.push(replacement);
+          i += 3;
+          continue;
+        }
+        const codeUnit = ((byte1 & 0x0f) << 12) | ((byte2 & 0x3f) << 6) | (byte3 & 0x3f);
+        parts.push(String.fromCharCode(codeUnit));
+        i += 3;
+      }
+      // 4字节字符 (11110xxx 10xxxxxx 10xxxxxx 10xxxxxx) - 处理emoji等
+      else if (byte1 >= 0xf0 && byte1 <= 0xf4) {
+        if (i + 3 >= len) {
+          if (stream) {
+            this.leftOver = bytes.slice(i);
+            break;
+          }
+          parts.push(replacement);
+          break;
+        }
+        const byte2 = bytes[i + 1];
+        const byte3 = bytes[i + 2];
+        const byte4 = bytes[i + 3];
+        if (
+          !isContinuationByte(byte2) ||
+          !isContinuationByte(byte3) ||
+          !isContinuationByte(byte4)
+        ) {
+          parts.push(replacement);
+          i += 1;
+          continue;
+        }
+        if (byte1 === 0xf0 && byte2 < 0x90) {
+          parts.push(replacement);
+          i += 4;
+          continue;
+        }
+        if (byte1 === 0xf4 && byte2 >= 0x90) {
+          parts.push(replacement);
+          i += 4;
+          continue;
+        }
+        const codepoint =
+          ((byte1 & 0x07) << 18) | ((byte2 & 0x3f) << 12) | ((byte3 & 0x3f) << 6) | (byte4 & 0x3f);
+        const offset = codepoint - 0x10000;
+        parts.push(String.fromCharCode(0xd800 + (offset >> 10), 0xdc00 + (offset & 0x3ff)));
+        i += 4;
+      } else {
+        parts.push(replacement);
+        i += 1;
+      }
+    }
+
+    return parts.join('');
+  }
+}
+
+export default PolyfillTextDecoder;

package/src/ts/buffer/SSEParser.ts

@@ -0,0 +1,210 @@
+import { isPlainObject } from 'es-toolkit';
+import PolyfillTextDecoder from './PolyfillTextDecoder';
+
+/** 流式数据消息 */
+export type SSEMessage = {
+  /**
+   * SSE 消息类型
+   * - 'DONE' 流式数据接收完毕
+   * - 'thinking' 思考中
+   * - 'text' 文本内容
+   * - 其他业务类型
+   */
+  type?: string;
+
+  /** SSE 事件 ID (如 'id:123') */
+  id?: string;
+
+  /** SSE 建议重连时间 (毫秒, 如 'retry:5000') */
+  retry?: number;
+
+  /** SSE 事件类型 (如 'event:customEvent') */
+  event?: string;
+
+  /**
+   * 除type之外的其他data数据
+   * - 思考中 'data:{"type": "thinking", "content": "xx"}' -> {type: 'thinking', content: 'xx'}
+   * - JSON数据 'data:{"type": "text", "content": "xx"}' -> {type: 'text', content: 'xx'}
+   * - 非JSON数据 'data:xx' -> {raw: 'xx'}
+   * - 接收完毕 'data:[DONE]' -> {type: 'DONE'}
+   */
+  [key: string]: any;
+};
+
+/** 流式数据消息回调 */
+export type MessageCallback = (msg: SSEMessage) => void;
+
+/**
+ * 流式数据解析器
+ * - 对于不支持TextDecoder的环境，使用PolyfillTextDecoder (bufferToText流式增强版)
+ * @description 用于解析 SSE 流式数据，将其转换为 SSEMessage 格式并调用回调函数处理
+ * @param onMessage 消息回调
+ * @example
+ * const parser = new SSEParser((msg) => {
+ *   console.log(msg);
+ * });
+ * parser.receive(arrayBuffer);
+ */
+export class SSEParser {
+  private buffer: string = '';
+  private onMessage: MessageCallback;
+  private decoder: TextDecoder | PolyfillTextDecoder;
+  private eventDataLines: string[] = [];
+  private eventType?: string;
+  private eventId?: string;
+  private eventRetry?: number;
+
+  constructor(onMessage: MessageCallback) {
+    this.onMessage = onMessage;
+    this.decoder =
+      typeof TextDecoder !== 'undefined' ? new TextDecoder('utf-8') : new PolyfillTextDecoder();
+  }
+
+  /**
+   * 接收流式数据
+   * @param buffer ArrayBuffer
+   */
+  receive(buffer: ArrayBuffer) {
+    const text = this.decoder.decode(new Uint8Array(buffer), { stream: true });
+    this.appendText(text);
+  }
+
+  /**
+   * 刷新解码器残留数据并处理尾部未换行的内容
+   */
+  flush() {
+    const tail = this.decoder.decode(undefined, { stream: false });
+    if (tail) this.appendText(tail);
+
+    this.flushRemainder();
+  }
+
+  /**
+   * 追加文本并按行拆分处理，保留不完整尾行
+   * @param text 新到达的文本片段
+   */
+  private appendText(text: string) {
+    this.buffer += text;
+
+    const lines = this.buffer.split(/\r?\n/);
+    this.buffer = lines.pop() || '';
+
+    this.processLines(lines);
+  }
+
+  /**
+   * 处理缓冲区中剩余的尾行内容
+   */
+  private flushRemainder() {
+    if (!this.buffer.trim()) {
+      this.buffer = '';
+      return;
+    }
+    const rest = this.buffer;
+    this.buffer = '';
+    this.processLines([rest, '']);
+  }
+
+  /**
+   * 解析每行 SSE 数据并触发回调
+   * @param lines 以换行切分后的行内容
+   */
+  private processLines(lines: string[]) {
+    for (const line of lines) {
+      if (!line.trim()) {
+        this.dispatchEvent();
+        continue;
+      }
+
+      if (line.startsWith(':')) continue;
+
+      const colonIndex = line.indexOf(':');
+      const field = colonIndex === -1 ? line : line.slice(0, colonIndex);
+      let value = colonIndex === -1 ? '' : line.slice(colonIndex + 1);
+      if (value.startsWith(' ')) value = value.slice(1);
+
+      if (field === 'data') {
+        this.eventDataLines.push(value);
+        continue;
+      }
+
+      if (field === 'event') {
+        this.eventType = value || undefined;
+        continue;
+      }
+
+      if (field === 'id') {
+        this.eventId = value || undefined;
+        continue;
+      }
+
+      if (field === 'retry') {
+        const retry = Number(value);
+        this.eventRetry = Number.isFinite(retry) ? retry : undefined;
+        continue;
+      }
+    }
+  }
+
+  /**
+   * 将当前缓存的一次 SSE 事件分发给回调
+   * @description 以空行作为事件边界，将多行 data 合并后再解析；处理 "[DONE]" 结束标记；分发完成后会重置事件缓存
+   */
+  private dispatchEvent() {
+    if (!this.eventDataLines.length) {
+      this.resetEvent();
+      return;
+    }
+
+    const data = this.eventDataLines.join('\n');
+
+    if (!data) {
+      this.resetEvent();
+      return;
+    }
+
+    if (data.trim() === '[DONE]') {
+      this.safeOnMessage({ type: 'DONE' });
+      this.resetEvent();
+      return;
+    }
+
+    let msg: SSEMessage;
+
+    try {
+      // 尝试解析 JSON 数据
+      const json = JSON.parse(data);
+      // 'data:{"type": "text", "content": "xx"}' -> {type: 'text', content: 'xx'}
+      // 'data:[1,2,3]' -> {data: [1,2,3]}
+      msg = isPlainObject(json) ? json : { data: json };
+    } catch (e) {
+      // 解析失败时，返回原始数据。'data:xx' -> {raw: 'xx'}
+      msg = { raw: data };
+    }
+
+    if (this.eventType && msg.event === undefined) msg.event = this.eventType;
+    if (this.eventType && msg.type === undefined) msg.type = this.eventType;
+    if (this.eventId && msg.id === undefined) msg.id = this.eventId;
+    if (this.eventRetry !== undefined && msg.retry === undefined) msg.retry = this.eventRetry;
+
+    this.safeOnMessage(msg);
+    this.resetEvent();
+  }
+
+  /** 安全调用 onMessage 回调，捕获并打印错误 */
+  private safeOnMessage(msg: SSEMessage) {
+    try {
+      this.onMessage(msg);
+    } catch (onMessageError) {
+      console.error('SSEParser onMessage error:', onMessageError);
+    }
+  }
+
+  /** 重置当前 SSE 事件的临时缓存 */
+  private resetEvent() {
+    this.eventDataLines = [];
+    this.eventType = undefined;
+    this.eventId = undefined;
+    this.eventRetry = undefined;
+  }
+}