fetch-stream-reader/dist/index.d.ts

A lightweight client for reading streaming HTTP responses using Fetch and ReadableStream.

/**
 * 基于浏览器原生 EventTarget 的事件分发器封装类
 *
 * 主要用途：
 * - 轻松实现自定义事件机制
 * - 方便在类中进行事件通信和状态通知
 */
declare class EventDispatcher {
    private target;
    /**
     * 添加事件监听器
     * @param {string} eventName 事件名称，表示将要监听的事件
     * @param {EventListener} handler 事件处理函数，接收事件对象作为参数
     */
    on(eventName: string, handler: EventListener): void;
    /**
     * 移除事件监听器
     * @param {string} eventName 事件名称
     * @param {EventListener} handler - 事件处理函数
     */
    off(eventName: string, handler?: EventListener): void;
    /**
     * 统一的事件触发方法
     * @param {string} eventName 事件名称
     * @param {T} [detail] 事件携带的数据（可选）
     */
    emit<T = unknown>(eventName: string, detail?: T): void;
}

/**
 * 基于 Fetch API 和 ReadableStream 实现的流式数据读取器。
 *
 * 它继承自自定义的 EventDispatcher，支持以事件形式发布以下流生命周期事件：
 *
 * - 'stream-start'：开始建立连接和读取流
 * - 'stream-message'：成功解析的一条数据消息（通常为 JSON 对象）
 * - 'stream-error'：请求或解析过程中发生的错误
 * - 'stream-end'：服务端正常关闭流
 * - 'stream-abort'：客户端手动中断流
 *
 * 支持传入请求头和 payload，并封装了自动处理 buffer 和 chunk 拼接的逻辑。
 */
declare class FetchStreamReader extends EventDispatcher {
    private readonly requestUrl;
    private readonly requestHeaders;
    /**
     * UTF-8 解码器（静态共享），用于将 Uint8Array 解码成字符串，适用于 ReadableStream 的 chunk 处理
     */
    private static readonly utf8Decoder;
    /**
     * SSE（Server-Sent Events）或其他文本流协议中常用的数据前缀定义
     */
    private static readonly PROTOCOL;
    /**
     * 流式读取器，用于读取 fetch 的 response.body（如流式响应、SSE、chunked 数据）
     */
    private streamReader;
    /**
     * 控制器对象，用于中止当前 fetch 请求（适用于用户取消、超时等场景）
     */
    private abortController;
    /**
     * 数据缓冲区，在读取过程中临时存储流式内容（通常是字符串拼接）
     */
    private buffer;
    /**
     * 创建 FetchStreamReader 实例，用于初始化请求地址和请求头，在后续的流式请求中使用
     * @param requestUrl - 流式请求的目标 URL
     * @param requestHeaders - 请求头，用于添加认证信息、Content-Type 等
     */
    constructor(requestUrl: string, requestHeaders?: HeadersInit);
    /**
     * 启动流请求
     * @param payload - 请求体参数，会作为 POST 的 JSON body 发送
     */
    start(payload?: Record<string, unknown>): Promise<void>;
    /**
     * 发起带流式响应的 HTTP 请求（默认使用 POST 方法）
     * @param signal - 用于外部控制请求中断
     * @param payload - 请求体参数，作为 JSON 发送
     * @returns 返回 Promise 对象，解析为原始 Response 对象（含可读流）
     */
    private _fetchStream;
    /**
     * 从响应体流中逐步读取数据并解码处理
     */
    private _readStreamChunks;
    /**
     * 处理 buffer 中的完整数据块
     */
    private _processBuffer;
    /**
     * 停止当前的流请求和数据读取
     */
    stop(): void;
    /**
     * 清理内部状态和资源，防止内存泄漏
     */
    private _cleanup;
}

export { FetchStreamReader as default };