stream-axios 1.1.0 → 1.2.0

package/README.md

@@ -22,7 +22,9 @@ npm install stream-axios
 ### 1. Basic Request (Same as axios)
 
 ```javascript
-import request from "stream-axios";
+import { createInstance } from "stream-axios";
+
+const request = createInstance();
 
 // GET request
 request
@@ -53,7 +55,9 @@ request
 Suitable for scenarios like receiving large files or AI conversation streams.
 
 ```javascript
-import request from "stream-axios";
+import { createInstance } from "stream-axios";
+
+const request = createInstance();
 
 const cancel = await request.stream(
   {
@@ -106,17 +110,70 @@ myRequest.stream({ url: "/stream" }, (chunk) => console.log(chunk));
 If you are handling SSE (Server-Sent Events) format data:
 
 ```javascript
-import request, { parseSSEChunk } from "stream-axios";
+import { createInstance, parseSSEChunk } from "stream-axios";
 
+const request = createInstance();
+
+// Simple usage - parse data field only
 request.stream({ url: "/sse-endpoint", method: "GET" }, (chunk) => {
-  // Parse SSE data
   parseSSEChunk(chunk, (content) => {
     console.log("SSE Message:", content);
   });
 });
 ```
 
-### 5. Use with Existing Axios Instance
+For production environments, use `createSSEParser` which handles chunks that may be split across multiple packets:
+
+```javascript
+import { createInstance, createSSEParser } from "stream-axios";
+
+const request = createInstance();
+
+// Create a stateful parser with buffer
+const parser = createSSEParser((event) => {
+  // event object contains: { event?, data?, id?, retry? }
+  console.log("Event type:", event.event);
+  console.log("Data:", event.data);
+  console.log("ID:", event.id);
+});
+
+request.stream(
+  { url: "/sse-endpoint", method: "GET" },
+  parser,
+  () => console.log("Completed"),
+  (error) => console.error("Error:", error),
+);
+```
+
+### 5. Cancel with External AbortSignal
+
+You can pass an external `AbortSignal` to control the stream request:
+
+```javascript
+import { createInstance } from "stream-axios";
+
+const request = createInstance();
+const controller = new AbortController();
+
+request.stream(
+  {
+    url: "/api/chat",
+    method: "POST",
+    data: { message: "Hello" },
+    signal: controller.signal, // Pass external signal
+  },
+  (chunk) => console.log(chunk),
+  () => console.log("Completed"),
+  (error) => console.error(error),
+);
+
+// Cancel from external controller
+setTimeout(() => {
+  controller.abort();
+}, 5000);
+```
+
+### 6. Use with Existing Axios Instance
 
 If you already have a configured axios instance in your project, you can attach the stream method to it:
 

package/README.zh-CN.md

@@ -22,7 +22,9 @@ npm install stream-axios
 ### 1. 基础请求 (同 axios)
 
 ```javascript
-import request from "stream-axios";
+import { createInstance } from "stream-axios";
+
+const request = createInstance();
 
 // GET 请求
 request
@@ -106,17 +108,70 @@ myRequest.stream({ url: "/stream" }, (chunk) => console.log(chunk));
 如果你处理的是 SSE (Server-Sent Events) 格式的数据：
 
 ```javascript
-import request, { parseSSEChunk } from "stream-axios";
+import { createInstance, parseSSEChunk } from "stream-axios";
+
+const request = createInstance();
 
+// 简单用法 - 仅解析 data 字段
 request.stream({ url: "/sse-endpoint", method: "GET" }, (chunk) => {
-  // 解析 SSE 数据
   parseSSEChunk(chunk, (content) => {
     console.log("SSE Message:", content);
   });
 });
 ```
 
-### 5. 使用现有的 Axios 实例
+对于生产环境，建议使用 `createSSEParser`，它可以处理跨数据包拆分的 chunk：
+
+```javascript
+import { createInstance, createSSEParser } from "stream-axios";
+
+const request = createInstance();
+
+// 创建带缓冲区的有状态解析器
+const parser = createSSEParser((event) => {
+  // event 对象包含: { event?, data?, id?, retry? }
+  console.log("事件类型:", event.event);
+  console.log("数据:", event.data);
+  console.log("ID:", event.id);
+});
+
+request.stream(
+  { url: "/sse-endpoint", method: "GET" },
+  parser,
+  () => console.log("完成"),
+  (error) => console.error("错误:", error),
+);
+```
+
+### 5. 使用外部 AbortSignal 取消请求
+
+你可以传入外部的 `AbortSignal` 来控制流式请求：
+
+```javascript
+import { createInstance } from "stream-axios";
+
+const request = createInstance();
+const controller = new AbortController();
+
+request.stream(
+  {
+    url: "/api/chat",
+    method: "POST",
+    data: { message: "Hello" },
+    signal: controller.signal, // 传入外部信号
+  },
+  (chunk) => console.log(chunk),
+  () => console.log("完成"),
+  (error) => console.error(error),
+);
+
+// 从外部控制器取消请求
+setTimeout(() => {
+  controller.abort();
+}, 5000);
+```
+
+### 6. 使用现有的 Axios 实例
 
 如果你项目中已经有了配置好的 axios 实例，你可以将 stream 方法挂载到该实例上：
 

package/dist/index.cjs

@@ -1,7 +1,5 @@
 'use strict';
 
-Object.defineProperty(exports, '__esModule', { value: true });
-
 var axios = require('axios');
 
 const defaultConfig = {
@@ -12,23 +10,79 @@ const defaultConfig = {
 };
 
 /**
- * Parse SSE data chunk
- * @param {string} sseText
- * @param {Function} onMessage
+ * Parse a single SSE event block
+ * @param {string} eventBlock - A single SSE event (lines separated by \n)
+ * @returns {{ event?: string, data?: string, id?: string, retry?: number } | null}
+ */
+function parseSSEEvent(eventBlock) {
+  const lines = eventBlock.split("\n");
+  const result = {};
+  const dataLines = [];
+
+  for (const line of lines) {
+    if (line.startsWith("data:")) {
+      // Support both "data: content" and "data:content"
+      const content = line.slice(5);
+      dataLines.push(content.startsWith(" ") ? content.slice(1) : content);
+    } else if (line.startsWith("event:")) {
+      result.event = line.slice(6).trim();
+    } else if (line.startsWith("id:")) {
+      result.id = line.slice(3).trim();
+    } else if (line.startsWith("retry:")) {
+      const retry = parseInt(line.slice(6).trim(), 10);
+      if (!isNaN(retry)) result.retry = retry;
+    }
+    // Ignore comments (lines starting with :) and unknown fields
+  }
+
+  // Join multiple data lines with newline (per SSE spec)
+  if (dataLines.length > 0) {
+    result.data = dataLines.join("\n");
+  }
+
+  return Object.keys(result).length > 0 ? result : null;
+}
+
+/**
+ * Parse SSE data chunk (simple, stateless version)
+ * @param {string} sseText - Raw SSE text chunk
+ * @param {Function} onMessage - Callback receiving data content string
  */
 function parseSSEChunk(sseText, onMessage) {
-  const sseLines = sseText.split("\n\n").filter(Boolean);
-  for (const line of sseLines) {
-    const dataPrefix = "data: ";
-    if (line.startsWith(dataPrefix)) {
-      const validContent = line.slice(dataPrefix.length).trim();
-      if (validContent) {
-        onMessage(validContent);
-      }
+  const events = sseText.split("\n\n").filter(Boolean);
+  for (const eventBlock of events) {
+    const parsed = parseSSEEvent(eventBlock);
+    if (parsed?.data) {
+      onMessage(parsed.data);
     }
   }
 }
 
+/**
+ * Create a stateful SSE parser with buffer for handling chunks that may be split
+ * @param {Function} onMessage - Callback receiving parsed SSE event object { event?, data?, id?, retry? }
+ * @returns {Function} Parser function that accepts raw chunk string
+ */
+function createSSEParser(onMessage) {
+  let buffer = "";
+
+  return (chunk) => {
+    buffer += chunk;
+    // Split by double newline (SSE event separator)
+    const parts = buffer.split("\n\n");
+    // Keep the last incomplete part in buffer
+    buffer = parts.pop() || "";
+
+    for (const eventBlock of parts) {
+      if (!eventBlock.trim()) continue;
+      const parsed = parseSSEEvent(eventBlock);
+      if (parsed) {
+        onMessage(parsed);
+      }
+    }
+  };
+}
+
 /**
  * Create a stream request function bound to an axios instance
  * @param {import('axios').AxiosInstance} instance
@@ -37,9 +91,28 @@ const createStreamRequest = (instance) => {
   return async (options = {}, onChunk, onComplete, onError) => {
     const controller = new AbortController();
     let reader = null;
+    let externalSignalHandler = null;
+
+    // Handle external signal
+    if (options.signal) {
+      if (options.signal.aborted) {
+        controller.abort();
+      } else {
+        externalSignalHandler = () => controller.abort();
+        options.signal.addEventListener("abort", externalSignalHandler);
+      }
+    }
+
+    const cleanup = () => {
+      if (options.signal && externalSignalHandler) {
+        options.signal.removeEventListener("abort", externalSignalHandler);
+        externalSignalHandler = null;
+      }
+    };
 
     const cancelRequest = () => {
       try {
+        cleanup();
         controller.abort();
         reader?.releaseLock();
         if (onError) onError("Stream request cancelled manually");
@@ -79,6 +152,7 @@ const createStreamRequest = (instance) => {
         try {
           const { done, value } = await reader.read();
           if (done) {
+            cleanup();
             if (onComplete) onComplete();
             return;
           }
@@ -87,6 +161,7 @@ const createStreamRequest = (instance) => {
           if (onChunk) onChunk(chunk);
           await readStreamChunk();
         } catch (err) {
+          cleanup();
           if (err.name === "AbortError") return;
           if (onError) onError(`Read stream failed: ${err.message}`);
         }
@@ -122,9 +197,6 @@ const createInstance = (config = {}) => {
   return instance;
 };
 
-// Create a default instance
-const service = createInstance();
-
 /**
  * Attach stream method to an existing axios instance
  * @param {import('axios').AxiosInstance} instance
@@ -137,6 +209,5 @@ const attachStream = (instance) => {
 
 exports.attachStream = attachStream;
 exports.createInstance = createInstance;
-exports.createStreamRequest = createStreamRequest;
-exports.default = service;
+exports.createSSEParser = createSSEParser;
 exports.parseSSEChunk = parseSSEChunk;

package/dist/index.js

@@ -8,23 +8,79 @@ const defaultConfig = {
 };
 
 /**
- * Parse SSE data chunk
- * @param {string} sseText
- * @param {Function} onMessage
+ * Parse a single SSE event block
+ * @param {string} eventBlock - A single SSE event (lines separated by \n)
+ * @returns {{ event?: string, data?: string, id?: string, retry?: number } | null}
+ */
+function parseSSEEvent(eventBlock) {
+  const lines = eventBlock.split("\n");
+  const result = {};
+  const dataLines = [];
+
+  for (const line of lines) {
+    if (line.startsWith("data:")) {
+      // Support both "data: content" and "data:content"
+      const content = line.slice(5);
+      dataLines.push(content.startsWith(" ") ? content.slice(1) : content);
+    } else if (line.startsWith("event:")) {
+      result.event = line.slice(6).trim();
+    } else if (line.startsWith("id:")) {
+      result.id = line.slice(3).trim();
+    } else if (line.startsWith("retry:")) {
+      const retry = parseInt(line.slice(6).trim(), 10);
+      if (!isNaN(retry)) result.retry = retry;
+    }
+    // Ignore comments (lines starting with :) and unknown fields
+  }
+
+  // Join multiple data lines with newline (per SSE spec)
+  if (dataLines.length > 0) {
+    result.data = dataLines.join("\n");
+  }
+
+  return Object.keys(result).length > 0 ? result : null;
+}
+
+/**
+ * Parse SSE data chunk (simple, stateless version)
+ * @param {string} sseText - Raw SSE text chunk
+ * @param {Function} onMessage - Callback receiving data content string
  */
 function parseSSEChunk(sseText, onMessage) {
-  const sseLines = sseText.split("\n\n").filter(Boolean);
-  for (const line of sseLines) {
-    const dataPrefix = "data: ";
-    if (line.startsWith(dataPrefix)) {
-      const validContent = line.slice(dataPrefix.length).trim();
-      if (validContent) {
-        onMessage(validContent);
-      }
+  const events = sseText.split("\n\n").filter(Boolean);
+  for (const eventBlock of events) {
+    const parsed = parseSSEEvent(eventBlock);
+    if (parsed?.data) {
+      onMessage(parsed.data);
     }
   }
 }
 
+/**
+ * Create a stateful SSE parser with buffer for handling chunks that may be split
+ * @param {Function} onMessage - Callback receiving parsed SSE event object { event?, data?, id?, retry? }
+ * @returns {Function} Parser function that accepts raw chunk string
+ */
+function createSSEParser(onMessage) {
+  let buffer = "";
+
+  return (chunk) => {
+    buffer += chunk;
+    // Split by double newline (SSE event separator)
+    const parts = buffer.split("\n\n");
+    // Keep the last incomplete part in buffer
+    buffer = parts.pop() || "";
+
+    for (const eventBlock of parts) {
+      if (!eventBlock.trim()) continue;
+      const parsed = parseSSEEvent(eventBlock);
+      if (parsed) {
+        onMessage(parsed);
+      }
+    }
+  };
+}
+
 /**
  * Create a stream request function bound to an axios instance
  * @param {import('axios').AxiosInstance} instance
@@ -33,9 +89,28 @@ const createStreamRequest = (instance) => {
   return async (options = {}, onChunk, onComplete, onError) => {
     const controller = new AbortController();
     let reader = null;
+    let externalSignalHandler = null;
+
+    // Handle external signal
+    if (options.signal) {
+      if (options.signal.aborted) {
+        controller.abort();
+      } else {
+        externalSignalHandler = () => controller.abort();
+        options.signal.addEventListener("abort", externalSignalHandler);
+      }
+    }
+
+    const cleanup = () => {
+      if (options.signal && externalSignalHandler) {
+        options.signal.removeEventListener("abort", externalSignalHandler);
+        externalSignalHandler = null;
+      }
+    };
 
     const cancelRequest = () => {
       try {
+        cleanup();
         controller.abort();
         reader?.releaseLock();
         if (onError) onError("Stream request cancelled manually");
@@ -75,6 +150,7 @@ const createStreamRequest = (instance) => {
         try {
           const { done, value } = await reader.read();
           if (done) {
+            cleanup();
             if (onComplete) onComplete();
             return;
           }
@@ -83,6 +159,7 @@ const createStreamRequest = (instance) => {
           if (onChunk) onChunk(chunk);
           await readStreamChunk();
         } catch (err) {
+          cleanup();
           if (err.name === "AbortError") return;
           if (onError) onError(`Read stream failed: ${err.message}`);
         }
@@ -118,9 +195,6 @@ const createInstance = (config = {}) => {
   return instance;
 };
 
-// Create a default instance
-const service = createInstance();
-
 /**
  * Attach stream method to an existing axios instance
  * @param {import('axios').AxiosInstance} instance
@@ -131,4 +205,4 @@ const attachStream = (instance) => {
   return instance;
 };
 
-export { attachStream, createInstance, createStreamRequest, service as default, parseSSEChunk };
+export { attachStream, createInstance, createSSEParser, parseSSEChunk };

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "stream-axios",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "二次封装 axios，保留原始配置，提供流式接口，提升开发效率",
   "type": "module",
   "main": "dist/index.cjs",
   "module": "dist/index.js",
+  "types": "index.d.ts",
   "exports": {
     ".": {
       "import": "./dist/index.js",