stream-axios 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 zovop
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,148 @@
+# axios-stream
+
+[English](./README.md) | [简体中文](./README.zh-CN.md)
+
+A wrapper library based on axios that retains the original configuration capabilities while providing out-of-the-box streaming request interfaces to improve development efficiency.
+
+## Features
+
+- 🚀 **Fully Compatible**: Based on axios, retaining all features like interceptors and configurations.
+- 🌊 **Streaming Support**: Built-in `stream` method to easily handle streaming responses (e.g., LLM typewriter effect).
+- 🛠 **Out of the Box**: Provides a default instance and supports creating custom instances.
+- 📦 **SSE Helper**: Built-in SSE parsing tool for easy handling of Server-Sent Events.
+
+## Installation
+
+```bash
+npm install axios-stream
+```
+
+## Usage Guide
+
+### 1. Basic Request (Same as axios)
+
+```javascript
+import request from "axios-stream";
+
+// GET request
+request
+  .get("/user?ID=12345")
+  .then(function (response) {
+    console.log(response);
+  })
+  .catch(function (error) {
+    console.log(error);
+  });
+
+// POST request
+request
+  .post("/user", {
+    firstName: "Fred",
+    lastName: "Flintstone",
+  })
+  .then(function (response) {
+    console.log(response);
+  })
+  .catch(function (error) {
+    console.log(error);
+  });
+```
+
+### 2. Streaming Request
+
+Suitable for scenarios like receiving large files or AI conversation streams.
+
+```javascript
+import request from "axios-stream";
+
+const cancel = request.stream(
+  {
+    url: "/api/chat",
+    method: "POST",
+    data: { message: "Hello" },
+  },
+  (chunk) => {
+    // Received data chunk
+    console.log("Received chunk:", chunk);
+  },
+  () => {
+    // Stream completed
+    console.log("Stream completed");
+  },
+  (error) => {
+    // Error occurred
+    console.error("Stream error:", error);
+  },
+);
+
+// If you need to cancel the request
+// cancel();
+```
+
+### 3. Custom Instance
+
+If you need independent configuration or interceptors:
+
+```javascript
+import { createInstance } from "axios-stream";
+
+const myRequest = createInstance({
+  baseURL: "https://api.mydomain.com",
+  timeout: 5000,
+});
+
+// Add custom interceptor
+myRequest.interceptors.request.use((config) => {
+  config.headers["Authorization"] = "Bearer token";
+  return config;
+});
+
+// Use stream method
+myRequest.stream({ url: "/stream" }, (chunk) => console.log(chunk));
+```
+
+### 4. SSE Parsing Helper
+
+If you are handling SSE (Server-Sent Events) format data:
+
+```javascript
+import request, { parseSSEChunk } from "axios-stream";
+
+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
+
+If you already have a configured axios instance in your project, you can attach the stream method to it:
+
+```javascript
+import axios from "axios";
+import { attachStream } from "axios-stream";
+
+// Your existing axios instance
+const myAxios = axios.create({
+  baseURL: "https://api.myproject.com",
+  headers: { "X-Custom-Header": "foobar" },
+});
+
+// Attach stream method
+attachStream(myAxios);
+
+// Now you can use .stream() on your instance
+myAxios.stream({ url: "/chat" }, (chunk) => {
+  console.log(chunk);
+});
+```
+
+## License
+
+MIT
+
+## Acknowledgement
+
+This project is based on [Axios](https://github.com/axios/axios).

package/README.zh-CN.md

@@ -0,0 +1,149 @@
+# axios-stream
+
+[English](./README.md) | [简体中文](./README.zh-CN.md)
+
+这是一个基于 axios 的二次封装库，保留了 axios 的原始配置能力，并提供了开箱即用的流式请求（Streaming）接口，旨在提升开发效率。
+
+## 特性
+
+- 🚀 **完全兼容**：基于 axios，保留原有拦截器、配置项等所有特性。
+- 🌊 **流式支持**：内置 `stream` 方法，轻松处理流式响应（如 LLM 打字机效果）。
+- 🛠 **开箱即用**：提供默认实例，也支持创建自定义实例。
+- 📦 **SSE 助手**：内置 SSE 解析工具，方便处理 Server-Sent Events。
+
+## 安装
+
+```bash
+npm install axios-stream
+```
+
+## 使用指南
+
+### 1. 基础请求 (同 axios)
+
+```javascript
+import request from 'axios-stream';
+
+// GET 请求
+request.get('/user?ID=12345')
+  .then(function (response) {
+    console.log(response);
+  })
+  .catch(function (error) {
+    console.log(error);
+  });
+
+// POST 请求
+request.post('/user', {
+    firstName: 'Fred',
+    lastName: 'Flintstone'
+  })
+  .then(function (response) {
+    console.log(response);
+  })
+  .catch(function (error) {
+    console.log(error);
+  });
+```
+
+### 2. 流式请求 (Streaming)
+
+适用于接收大文件或 AI 对话流等场景。
+
+```javascript
+import request from 'axios-stream';
+
+const cancel = request.stream(
+  {
+    url: '/api/chat',
+    method: 'POST',
+    data: { message: 'Hello' }
+  },
+  (chunk) => {
+    // 收到数据片段
+    console.log('Received chunk:', chunk);
+  },
+  () => {
+    // 请求完成
+    console.log('Stream completed');
+  },
+  (error) => {
+    // 发生错误
+    console.error('Stream error:', error);
+  }
+);
+
+// 如果需要取消请求
+// cancel();
+```
+
+### 3. 自定义实例
+
+如果你需要独立的配置或拦截器：
+
+```javascript
+import { createInstance } from 'axios-stream';
+
+const myRequest = createInstance({
+  baseURL: 'https://api.mydomain.com',
+  timeout: 5000
+});
+
+// 添加自定义拦截器
+myRequest.interceptors.request.use(config => {
+  config.headers['Authorization'] = 'Bearer token';
+  return config;
+});
+
+// 使用流式方法
+myRequest.stream({ url: '/stream' }, (chunk) => console.log(chunk));
+```
+
+### 4. SSE 解析助手
+
+如果你处理的是 SSE (Server-Sent Events) 格式的数据：
+
+```javascript
+import request, { parseSSEChunk } from 'axios-stream';
+
+request.stream(
+  { url: '/sse-endpoint', method: 'GET' },
+  (chunk) => {
+    // 解析 SSE 数据
+    parseSSEChunk(chunk, (content) => {
+      console.log('SSE Message:', content);
+    });
+  }
+);
+```
+
+### 5. 使用现有的 Axios 实例
+
+如果你项目中已经有了配置好的 axios 实例，你可以将 stream 方法挂载到该实例上：
+
+```javascript
+import axios from 'axios';
+import { attachStream } from 'axios-stream';
+
+// 你现有的 axios 实例
+const myAxios = axios.create({
+  baseURL: 'https://api.myproject.com',
+  headers: { 'X-Custom-Header': 'foobar' }
+});
+
+// 挂载 stream 方法
+attachStream(myAxios);
+
+// 现在你可以在实例上使用 .stream() 方法了
+myAxios.stream({ url: '/chat' }, (chunk) => {
+  console.log(chunk);
+});
+```
+
+## License
+
+MIT
+
+## 致谢
+
+本项目基于 [Axios](https://github.com/axios/axios) 开发。

package/dist/index.cjs

@@ -0,0 +1,190 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var axios = require('axios');
+
+const defaultConfig = {
+  timeout: 10000,
+  headers: {
+    "Content-Type": "application/json",
+  },
+};
+
+/**
+ * Setup request interceptor
+ * @param {import('axios').AxiosInstance} instance
+ */
+const setupRequestInterceptor = (instance) => {
+  instance.interceptors.request.use(
+    (config) => {
+      // Add custom headers if needed
+      // config.headers["test"] = "testHEADER";
+      return config;
+    },
+    (error) => {
+      console.error("Request error:", error);
+      return Promise.reject(error);
+    },
+  );
+};
+
+/**
+ * Setup response interceptor
+ * @param {import('axios').AxiosInstance} instance
+ */
+const setupResponseInterceptor = (instance) => {
+  instance.interceptors.response.use(
+    (response) => {
+      // If stream request, return response directly
+      if (response.config.isStream) {
+        return response;
+      }
+
+      // Normal response handling
+      return response.data;
+    },
+    (error) => {
+      console.error("Response error:", error);
+      return Promise.reject(error);
+    },
+  );
+};
+
+const setupInterceptors = (instance) => {
+  setupRequestInterceptor(instance);
+  setupResponseInterceptor(instance);
+};
+
+/**
+ * Parse SSE data chunk
+ * @param {string} sseText
+ * @param {Function} onMessage
+ */
+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);
+      }
+    }
+  }
+}
+
+/**
+ * Create a stream request function bound to an axios instance
+ * @param {import('axios').AxiosInstance} instance
+ */
+const createStreamRequest = (instance) => {
+  return async (options = {}, onChunk, onComplete, onError) => {
+    const controller = new AbortController();
+    let reader = null;
+
+    const cancelRequest = () => {
+      try {
+        controller.abort();
+        reader?.releaseLock();
+        if (onError) onError("Stream request cancelled manually");
+      } catch (err) {
+        console.error("Failed to cancel stream request:", err);
+      }
+    };
+
+    try {
+      const response = await instance({
+        ...options,
+        isStream: true,
+        // Force critical config for streaming
+        adapter: "fetch",
+        responseType: "stream",
+        timeout: 0,
+        signal: controller.signal,
+      });
+
+      // Handle both standard axios response and unwrapped response (by user interceptors)
+      // If user's interceptor returned response.data, 'response' itself might be the stream
+      const readableStream =
+        response.data ||
+        response.body ||
+        (response.getReader ? response : null);
+
+      if (!readableStream || typeof readableStream.getReader !== "function") {
+        throw new Error(
+          "Browser does not support stream response, API did not return stream, or response was transformed incorrectly",
+        );
+      }
+
+      const decoder = new TextDecoder("utf-8");
+      reader = readableStream.getReader();
+
+      const readStreamChunk = async () => {
+        try {
+          const { done, value } = await reader.read();
+          if (done) {
+            if (onComplete) onComplete();
+            return;
+          }
+          const chunk = decoder.decode(value, { stream: true });
+
+          if (onChunk) onChunk(chunk);
+          await readStreamChunk();
+        } catch (err) {
+          if (err.name === "AbortError") return;
+          if (onError) onError(`Read stream failed: ${err.message}`);
+        }
+      };
+
+      readStreamChunk();
+    } catch (err) {
+      if (err.name === "CanceledError" || err.code === "ERR_CANCELED") {
+        // Handle axios cancellation if needed
+        return cancelRequest;
+      }
+      const errorMsg = err.message || "Stream request failed";
+      if (onError) onError(errorMsg);
+      console.error("Stream request failed:", errorMsg);
+    }
+
+    return cancelRequest;
+  };
+};
+
+/**
+ * Create Axios instance with custom configuration
+ * @param {import('axios').AxiosRequestConfig} config
+ * @returns {import('axios').AxiosInstance}
+ */
+const createInstance = (config = {}) => {
+  const finalConfig = { ...defaultConfig, ...config };
+  const instance = axios.create(finalConfig);
+
+  // Setup interceptors
+  setupInterceptors(instance);
+
+  // Attach stream method
+  instance.stream = createStreamRequest(instance);
+
+  return instance;
+};
+
+// Create a default instance
+const service = createInstance();
+
+/**
+ * Attach stream method to an existing axios instance
+ * @param {import('axios').AxiosInstance} instance
+ * @returns {import('axios').AxiosInstance}
+ */
+const attachStream = (instance) => {
+  instance.stream = createStreamRequest(instance);
+  return instance;
+};
+
+exports.attachStream = attachStream;
+exports.createInstance = createInstance;
+exports.createStreamRequest = createStreamRequest;
+exports.default = service;
+exports.parseSSEChunk = parseSSEChunk;

package/dist/index.js

@@ -0,0 +1,182 @@
+import axios from 'axios';
+
+const defaultConfig = {
+  timeout: 10000,
+  headers: {
+    "Content-Type": "application/json",
+  },
+};
+
+/**
+ * Setup request interceptor
+ * @param {import('axios').AxiosInstance} instance
+ */
+const setupRequestInterceptor = (instance) => {
+  instance.interceptors.request.use(
+    (config) => {
+      // Add custom headers if needed
+      // config.headers["test"] = "testHEADER";
+      return config;
+    },
+    (error) => {
+      console.error("Request error:", error);
+      return Promise.reject(error);
+    },
+  );
+};
+
+/**
+ * Setup response interceptor
+ * @param {import('axios').AxiosInstance} instance
+ */
+const setupResponseInterceptor = (instance) => {
+  instance.interceptors.response.use(
+    (response) => {
+      // If stream request, return response directly
+      if (response.config.isStream) {
+        return response;
+      }
+
+      // Normal response handling
+      return response.data;
+    },
+    (error) => {
+      console.error("Response error:", error);
+      return Promise.reject(error);
+    },
+  );
+};
+
+const setupInterceptors = (instance) => {
+  setupRequestInterceptor(instance);
+  setupResponseInterceptor(instance);
+};
+
+/**
+ * Parse SSE data chunk
+ * @param {string} sseText
+ * @param {Function} onMessage
+ */
+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);
+      }
+    }
+  }
+}
+
+/**
+ * Create a stream request function bound to an axios instance
+ * @param {import('axios').AxiosInstance} instance
+ */
+const createStreamRequest = (instance) => {
+  return async (options = {}, onChunk, onComplete, onError) => {
+    const controller = new AbortController();
+    let reader = null;
+
+    const cancelRequest = () => {
+      try {
+        controller.abort();
+        reader?.releaseLock();
+        if (onError) onError("Stream request cancelled manually");
+      } catch (err) {
+        console.error("Failed to cancel stream request:", err);
+      }
+    };
+
+    try {
+      const response = await instance({
+        ...options,
+        isStream: true,
+        // Force critical config for streaming
+        adapter: "fetch",
+        responseType: "stream",
+        timeout: 0,
+        signal: controller.signal,
+      });
+
+      // Handle both standard axios response and unwrapped response (by user interceptors)
+      // If user's interceptor returned response.data, 'response' itself might be the stream
+      const readableStream =
+        response.data ||
+        response.body ||
+        (response.getReader ? response : null);
+
+      if (!readableStream || typeof readableStream.getReader !== "function") {
+        throw new Error(
+          "Browser does not support stream response, API did not return stream, or response was transformed incorrectly",
+        );
+      }
+
+      const decoder = new TextDecoder("utf-8");
+      reader = readableStream.getReader();
+
+      const readStreamChunk = async () => {
+        try {
+          const { done, value } = await reader.read();
+          if (done) {
+            if (onComplete) onComplete();
+            return;
+          }
+          const chunk = decoder.decode(value, { stream: true });
+
+          if (onChunk) onChunk(chunk);
+          await readStreamChunk();
+        } catch (err) {
+          if (err.name === "AbortError") return;
+          if (onError) onError(`Read stream failed: ${err.message}`);
+        }
+      };
+
+      readStreamChunk();
+    } catch (err) {
+      if (err.name === "CanceledError" || err.code === "ERR_CANCELED") {
+        // Handle axios cancellation if needed
+        return cancelRequest;
+      }
+      const errorMsg = err.message || "Stream request failed";
+      if (onError) onError(errorMsg);
+      console.error("Stream request failed:", errorMsg);
+    }
+
+    return cancelRequest;
+  };
+};
+
+/**
+ * Create Axios instance with custom configuration
+ * @param {import('axios').AxiosRequestConfig} config
+ * @returns {import('axios').AxiosInstance}
+ */
+const createInstance = (config = {}) => {
+  const finalConfig = { ...defaultConfig, ...config };
+  const instance = axios.create(finalConfig);
+
+  // Setup interceptors
+  setupInterceptors(instance);
+
+  // Attach stream method
+  instance.stream = createStreamRequest(instance);
+
+  return instance;
+};
+
+// Create a default instance
+const service = createInstance();
+
+/**
+ * Attach stream method to an existing axios instance
+ * @param {import('axios').AxiosInstance} instance
+ * @returns {import('axios').AxiosInstance}
+ */
+const attachStream = (instance) => {
+  instance.stream = createStreamRequest(instance);
+  return instance;
+};
+
+export { attachStream, createInstance, createStreamRequest, service as default, parseSSEChunk };

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "stream-axios",
+  "version": "1.0.0",
+  "description": "二次封装 axios，保留原始配置，提供流式接口，提升开发效率",
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "README.zh-CN.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "axios",
+    "stream",
+    "fetch",
+    "sse",
+    "openai",
+    "llm",
+    "streaming"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rollup -c",
+    "prepublishOnly": "npm run build",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zOvOp/axios-stream.git"
+  },
+  "bugs": {
+    "url": "https://github.com/zOvOp/axios-stream/issues"
+  },
+  "homepage": "https://github.com/zOvOp/axios-stream#readme",
+  "author": "zovop",
+  "license": "MIT",
+  "dependencies": {
+    "axios": "^1.13.4"
+  },
+  "devDependencies": {
+    "@rollup/plugin-commonjs": "^29.0.0",
+    "@rollup/plugin-node-resolve": "^16.0.3",
+    "rollup": "^4.57.1"
+  }
+}