hook-fetch 3.0.0-beta.0 → 3.0.0-beta.1

package/CHANGELOG.md

@@ -0,0 +1,263 @@
+# hook-fetch
+
+## 3.0.0-beta.1
+
+### Major Changes
+
+- ## v3.0.0 - Context-Based Plugin API
+
+  ### 💥 Breaking Changes
+  - **插件 API 全面重构**：所有插件钩子从直接参数改为统一的 Context 对象模式
+    - `beforeRequest(ctx)` - 接收 `{ config, resolve, reject }`
+    - `afterResponse(ctx)` - 接收 `{ config, response, resolve, reject }`
+    - `onError(ctx)` - 接收 `{ error, config, resolve, reject }`
+    - `onFinally(ctx)` - 接收 `{ config }`
+  - **Pipeline Decision 机制**：插件可通过 `resolve()` 短路返回数据或 `reject()` 提前中止请求
+  - **插件优先级系统**：通过 `priority` 字段控制插件执行顺序（升序，默认 0）
+
+  ### ✨ 新功能
+  - **Retry 插件** (`retryPlugin`)：支持指数退避、线性退避、自定义退避策略，可配置重试条件和最大重试次数
+  - **完整流式处理**：新增 `beforeStream`、`transformStreamChunk`、`afterStream` 生命周期钩子
+  - **onError 错误恢复**：`onError` 钩子中可调用 `resolve()` 返回降级数据或重试结果（如 401 Token 刷新 → 重试）
+  - **增强的泛型支持**：`HookFetchPlugin<T, E>`、`OnErrorContext<T, E, S>` 等全面支持状态泛型
+
+  ### 🔧 改进
+  - **架构重组**：新增 `decision.ts`（Pipeline 决策）、`pipeline.ts`（插件管道）、`request.ts`（请求生命周期）、`executor.ts`（HTTP 执行器）
+  - **PluginManager**：插件去重（同名插件取最后注册的）、优先级排序
+  - **ResponseError 增强**：携带完整请求配置上下文，支持泛型错误类型
+  - **SSE 插件改进**：集成 `transformStreamChunk` 钩子，支持自定义分隔符和 JSON 解析配置
+
+## 2.3.1
+
+### Patch Changes
+
+- 修改resolve后仍然会继续请求的问题
+
+## 2.3.0
+
+### Minor Changes
+
+- 发布 2.3，主要变化：
+  - 新增 BodyType 并应用到请求/插件泛型，支持 string/FormData/Blob/ArrayBuffer/ReadableStream 等原生 body 直传。
+  - 优化 upload：支持对象或 FormData 自动转换为 FormData，上传数据类型推导更准确。
+  - Content-Type 为 text/plain 时保持原始字符串 body，纯文本接口按预期提交。
+  - 补充本地文件上传与 text/plain 测试用例，覆盖多文件、请求头透传与流式上传中断场景。
+
+## 2.2.4
+
+### Patch Changes
+
+- Improve type safety for streaming API:
+  - Add generic parameter support to `stream<U = T>()` method, allowing type override at stream stage
+  - Improve TypeScript inference: recommend specifying response type at request method level (e.g., `post<T>()`) rather than stream level for better type safety
+  - Update internal type handling in stream implementation for more accurate type narrowing
+
+## 2.2.3
+
+### Patch Changes
+
+- 新增请求去重插件并改进错误处理
+
+  ## 新增功能
+  - **请求去重插件 (dedupePlugin)**: 新增 `dedupePlugin` 用于防止并发的相同请求。插件会根据 URL、HTTP 方法、参数和请求体数据生成唯一标识,当检测到相同标识的请求正在进行时,后续请求会抛出 `DedupeError`
+    - 提供 `isDedupeError` 辅助函数用于判断错误类型
+    - 支持通过 `extra.dedupeAble` 选项禁用特定请求的去重功能
+    - ⚠️ 官方不推荐在生产环境中使用,建议通过应用层设计(如禁用按钮、防抖节流、状态管理)来避免重复请求
+
+  ## 改进
+  - **类型定义完善**: 在 `RequestConfig`、`BaseRequestOptions` 和 `OptionProps` 中添加 `extra` 字段支持,允许传递额外的请求配置
+  - **错误处理优化**: 改进 React 和 Vue hooks 的错误处理逻辑,过滤 `AbortError` 和 JSON 解析错误,避免触发不必要的错误回调
+
+  ## 文档更新
+  - 添加请求去重插件的完整文档和使用示例
+  - 更新中英文文档
+
+## 2.2.2
+
+### Patch Changes
+
+- 1. 修复 vue 和 react 的 hooks 状态管理异常 bug
+  2. 允许使用的时候临时传入插件
+
+## 2.2.1
+
+### Patch Changes
+
+- 修改beforeRequest逻辑， 使其支持中断请求直接返回值
+
+  **_主要用途：_**
+  - 缓存请求
+
+  example：[cache.test.ts](https://github.com/JsonLee12138/hook-fetch/blob/main/packages/core/__test__/cache.test.ts)
+
+## 2.2.0
+
+### Minor Changes
+
+- ### Major Changes
+  - ### 💥 Breaking Changes
+    - 移除旧有的 `qsArrayFormat` 配置字段，现改为通过 `qsConfig` 提供完整的 `qs.stringify` 选项；依赖该字段的代码需迁移到新 API。
+
+    ### 更新内容
+    - 新增 `qsConfig` 全局配置，允许在 `hookFetch` create 阶段自定义传给 `qs.stringify` 的参数，默认仍为 `arrayFormat: 'repeat'`。
+    - 各类请求方法接收 `RequestOptions.qsConfig`，可在单次调用时覆盖全局设置，影响 URL 拼接与 `application/x-www-form-urlencoded` 体序列化。
+
+## 2.1.6
+
+### Patch Changes
+
+- 修复错误异常问题
+
+## 2.1.5
+
+### Patch Changes
+
+- 更新文档
+
+## 2.1.4
+
+### Patch Changes
+
+- 修复beforeRequest中不能抛错的问题
+
+## 2.1.3
+
+### Patch Changes
+
+- 修复stream方法的错误不会走plugin的错误生命周期的bug
+
+## 2.1.2
+
+### Patch Changes
+
+- 修复抛出的HookFetchRequest类型不支持泛型的问题
+
+## 2.1.1
+
+### Patch Changes
+
+- 8d4d6b6: 修复HookFetchRequest实例没有抛出的问题
+
+## 2.1.1-beta.0
+
+### Patch Changes
+
+- 修复HookFetchRequest实例没有抛出的问题
+
+## 3.0.0-beta.0
+
+### Major Changes
+
+- 4b15105: 修改changeset配置, 改用changeset进行发布
+
+## v2.1.0 💥
+
+**发布日期**: 2025-08-08
+
+#### 💔 破坏性变更
+
+- 泛型签名调整：`HookFetch` 与 `hookFetch.create` 的泛型从
+  `<R extends AnyObject = AnyObject, K extends keyof R = 'data', E = AnyObject>`
+  调整为
+  `<R extends AnyObject | null = null, K extends keyof R = never, E = AnyObject>`。
+  - 当 `R = null`（默认）时：`json<T>()` 的返回类型为 `T`，不做包裹映射（更贴近原生 fetch 的直觉）。
+  - 当你需要“包裹响应”并做键映射时：显式传入响应包裹类型和键名，例如 `hookFetch.create<ResponseVO, 'data'>(...)`，此时 `json<User>()` 的返回类型为 `ResponseVO` 且其中 `data` 为 `User`。
+
+#### 🔧 迁移指南
+
+- 旧代码：
+
+  ```ts
+  interface ResponseVO {
+    code: number;
+    message: string;
+    data: never;
+  }
+  const api = hookFetch.create<ResponseVO>({ baseURL: "..." });
+  const res = await api.get<User>("/user").json();
+  // res.data: User
+  ```
+
+  新代码需显式指定键名：
+
+  ```ts
+  const api = hookFetch.create<ResponseVO, "data">({ baseURL: "..." });
+  const res = await api.get<User>("/user").json();
+  // res.data: User
+  ```
+
+- 若无需包裹（直接拿到 `T`）：
+  ```ts
+  const api = hookFetch.create(); // 等价于 <null, never>
+  const user = await api.get<User>("/user").json(); // user: User
+  ```
+
+#### 🧰 其他
+
+- 同步更新文档：README 与 API 参考已更新示例，明确 `R | null` 与 `K` 的用法。
+
+### v2.0.7 🛠️
+
+**发布日期**: 2025-08-08
+
+#### 🐛 修复
+
+- 修复 `json`、`text`、`blob`、`arrayBuffer`、`formData`、`bytes` 方法的类型推断缺失问题（更完善的返回值类型提示）。
+
+#### 🧱 基础设施
+
+- 调整与修复发布 CI/CD 流程相关配置。
+
+### v2.0.6
+
+**发布日期**: 2025-08-07
+
+#### 🔧 变更
+
+- 发布流程与版本稳定性相关的调整。
+
+### v2.0.3 🎉
+
+**发布日期**: 2025-06-30
+
+#### 💔 破坏性变更
+
+- **移除默认JSON解析**: 不再自动解析JSON响应，需要显式调用 `.json()` 方法
+- **更明确的响应处理**: 提供更明确的响应数据处理方式，避免隐式行为
+
+#### 🔧 API 调整
+
+- 所有请求方法现在需要显式调用响应处理方法（如 `.json()`, `.text()` 等）
+- 提高了API的明确性和可预测性
+
+#### 📚 文档更新
+
+- 更新了所有示例代码，明确显示 `.json()` 调用
+- 改进了响应处理的文档说明
+
+### v1.0.x
+
+**发布日期**: 2025-04
+
+#### 🎯 首次发布
+
+- 基于原生 fetch API 的现代化 HTTP 请求库
+- **自动JSON解析**: 默认自动解析JSON响应
+- **完整插件系统**: 支持 `beforeRequest`, `afterResponse`, `beforeStream`, `transformStreamChunk`, `onError`, `onFinally` 生命周期钩子
+- **Vue Hooks 支持**: 提供 `useHookFetch` Vue 组合式 API
+- **React Hooks 支持**: 提供 `useHookFetch` React Hook
+- **多种响应处理**: 支持 `json()`, `text()`, `blob()`, `arrayBuffer()`, `formData()`, `bytes()` 方法
+- **请求重试机制**: 支持 `.retry()` 方法重试已中断的请求
+- **流式数据处理**: 强大的流式响应处理能力
+- **请求中断**: 支持 `.abort()` 方法中断请求
+- **插件优先级**: 支持插件优先级设置
+- **SSE 支持**: 提供 `sseTextDecoderPlugin` 插件
+- **完整 TypeScript 支持**: 提供完善的类型定义和泛型支持
+- **灵活配置**: 支持超时、baseURL、请求头、参数序列化等配置选项
+- **VSCode 智能提示**: 提供专门的类型声明文件
+
+### 即将发布
+
+- 更多内置插件
+- 更丰富的插件生态
+- 更多框架集成支持

package/README.en.md

@@ -1,11 +1,18 @@
-# Hook-Fetch 🚀
+<div align="center">
+   <a href="https://jsonlee12138.github.io/hook-fetch/"><img src="https://jsonlee12138.github.io/hook-fetch/img/logo.png" /></a><br>
+</div>
+<h1 align="center" style="margin-bottom: 0;">Hook-Fetch</h1>
+<div align="center">
 
-**[中文文档](https://github.com/JsonLee12138/hook-fetch/blob/main/README.md)**
+[![Build status](https://img.shields.io/github/actions/workflow/status/axios/axios/ci.yml?branch=v1.x&label=Release&logo=github&style=flat-square)](https://github.com/JsonLee12138/hook-fetch/actions/workflows/release.yml) [![install size](https://packagephobia.com/badge?p=hook-fetch)](https://packagephobia.com/result?p=hook-fetch) [![npm bundle size](https://img.shields.io/bundlephobia/minzip/hook-fetch?style=flat-square)](https://bundlephobia.com/package/hook-fetch@latest) [![npm downloads](https://img.shields.io/npm/dm/hook-fetch.svg?style=flat-square)](https://npm-stat.com/charts.html?package=hook-fetch) [![Discord](https://img.shields.io/badge/-Discord-5865F2?style=flat&logo=discord&logoColor=white)](https://discord.com/invite/666U6JTCQY)
 
-## Introduction
+**[DeepWiki](https://deepwiki.com/JsonLee12138/hook-fetch)** **·** **[中文文档](https://github.com/JsonLee12138/hook-fetch/blob/main/README.md)**
 
 Hook-Fetch is a powerful request library based on the native fetch API, offering a simpler syntax, richer features, and a more flexible plugin system. It supports request retries, streaming data processing, request cancellation, and more. With its Promise-based chaining style, API requests become simpler and more controllable.
 
+</div>
+<br />
+
 ## Installation
 
 ```bash
@@ -149,7 +156,7 @@ Hook-Fetch offers a robust plugin system allowing intervention at various stages
 ```typescript
 // Custom plugin example: SSE text decoding plugin
 // This is just an example. It's recommended to use the provided `sseTextDecoderPlugin` which has more comprehensive handling
-const ssePlugin = () => {
+function ssePlugin() {
   const decoder = new TextDecoder('utf-8');
   return {
     name: 'sse',
@@ -159,8 +166,8 @@ const ssePlugin = () => {
       }
       return chunk;
     }
-  }
-};
+  };
+}
 
 // Register the plugin
 api.use(ssePlugin());
@@ -176,7 +183,7 @@ for await (const chunk of req.stream<string>()) {
 
 ```typescript
 // Complete plugin example showing the usage of each lifecycle hook
-const examplePlugin = () => {
+function examplePlugin() {
   return {
     name: 'example',
     priority: 1, // Priority, lower numbers have higher priority
@@ -194,17 +201,18 @@ const examplePlugin = () => {
       // Can process response data. context.result is the result after being processed by methods like json()
       if (context.responseType === 'json') {
         // For example, determine if the request is truly successful based on the backend's business code
-        if(context.result.code === 200){
+        if (context.result.code === 200) {
           // Business success, return context directly
-          return context
-        }else{
+          return context;
+        }
+        else {
           // Business failure, actively throw a ResponseError, which will be caught in the onError hook
           throw new ResponseError({
             message: context.result.message, // Use the error message from the backend
-            status: context.result.code,     // Use the business code as the status
-            response: context.response,      // Original Response object
+            status: context.result.code, // Use the business code as the status
+            response: context.response, // Original Response object
             config: context.config,
-            name: 'BusinessError'            // Custom error name
+            name: 'BusinessError' // Custom error name
           });
         }
       }
@@ -233,7 +241,8 @@ const examplePlugin = () => {
       if (error.name === 'BusinessError') {
         // Handle custom business errors
         console.error(`Business Error: ${error.message}`);
-      } else if (error.status === 401) {
+      }
+      else if (error.status === 401) {
         // Handle unauthorized error
         console.error('Login has expired, please log in again');
         // window.location.href = '/login';
@@ -248,7 +257,7 @@ const examplePlugin = () => {
       console.log(`Request to ${config.url} completed`);
     }
   };
-};
+}
 ```
 
 All lifecycle hooks support both synchronous and asynchronous operations. They can return either a Promise or a direct value. Each hook function receives the current configuration object (config), which can be used to make decisions and handle different request scenarios.
@@ -355,17 +364,13 @@ interface HookFetchPlugin<T = unknown, E = unknown, P = unknown, D = unknown> {
 }
 ```
 
-
-
-
-
 ## Vue Hooks
 
 Hook-Fetch provides Vue Composition API support, making it easier to use in Vue components:
 
 ```typescript
-import { useHookFetch } from 'hook-fetch/vue';
 import hookFetch from 'hook-fetch';
+import { useHookFetch } from 'hook-fetch/vue';
 
 // Create request instance
 const api = hookFetch.create({
@@ -478,6 +483,7 @@ const YourComponent = () => {
 ```
 
 ### vscode hint plugin reference path
+
 ```typescript
 // Create a file hook-fetch.d.ts in src with the following content
 /// <reference types="hook-fetch/plugins" />
@@ -493,10 +499,12 @@ const YourComponent = () => {
 4. Plugins execute in order of priority.
 
 ## Upcoming Features
+
 - `umd` support
 - More plugin support
 
 ## 📝 Contribution Guide
+
 Feel free to submit `issues` or `pull requests` to help improve `Hook-Fetch`.
 
 ## 📄 License

package/README.md

@@ -1,11 +1,18 @@
-# Hook-Fetch 🚀
+<div align="center">
+   <a href="https://jsonlee12138.github.io/hook-fetch/"><img src="https://jsonlee12138.github.io/hook-fetch/img/logo.png" /></a><br>
+</div>
+<h1 align="center" style="margin-bottom: 0;">Hook-Fetch</h1>
+<div align="center">
 
-**[English document](https://github.com/JsonLee12138/hook-fetch/blob/main/README.en.md)**
+[![Build status](https://img.shields.io/github/actions/workflow/status/axios/axios/ci.yml?branch=v1.x&label=Release&logo=github&style=flat-square)](https://github.com/JsonLee12138/hook-fetch/actions/workflows/release.yml) [![install size](https://packagephobia.com/badge?p=hook-fetch)](https://packagephobia.com/result?p=hook-fetch) [![npm bundle size](https://img.shields.io/bundlephobia/minzip/hook-fetch?style=flat-square)](https://bundlephobia.com/package/hook-fetch@latest) [![npm downloads](https://img.shields.io/npm/dm/hook-fetch.svg?style=flat-square)](https://npm-stat.com/charts.html?package=hook-fetch) [![Discord](https://img.shields.io/badge/-Discord-5865F2?style=flat&logo=discord&logoColor=white)](https://discord.com/invite/666U6JTCQY)
 
-## 介绍
+**[DeepWiki](https://deepwiki.com/JsonLee12138/hook-fetch)** **·** **[English document](https://github.com/JsonLee12138/hook-fetch/blob/main/README.en.md)**
 
 Hook-Fetch 是一个强大的基于原生 fetch API 的请求库，提供了更简洁的语法、更丰富的功能和更灵活的插件系统。它支持请求重试、流式数据处理、中断请求等特性，并且采用Promise链式调用风格，使API请求变得更加简单和可控。
 
+</div>
+<br />
+
 ## 安装
 
 ```bash
@@ -149,7 +156,7 @@ Hook-Fetch 提供了强大的插件系统，可以在请求生命周期的各个
 ```typescript
 // 自定义插件示例：SSE文本解码插件
 // 当前只是示例, 建议使用当前库提供的`sseTextDecoderPlugin`插件, 那里做了更完善的处理
-const ssePlugin = () => {
+function ssePlugin() {
   const decoder = new TextDecoder('utf-8');
   return {
     name: 'sse',
@@ -159,8 +166,8 @@ const ssePlugin = () => {
       }
       return chunk;
     }
-  }
-};
+  };
+}
 
 // 注册插件
 api.use(ssePlugin());
@@ -176,7 +183,7 @@ for await (const chunk of req.stream<string>()) {
 
 ```typescript
 // 完整的插件示例，展示各个生命周期的使用
-const examplePlugin = () => {
+function examplePlugin() {
   return {
     name: 'example',
     priority: 1, // 优先级，数字越小优先级越高
@@ -194,17 +201,18 @@ const examplePlugin = () => {
       // 可以处理响应数据, context.result 是已经过 json() 等方法处理后的结果
       if (context.responseType === 'json') {
         // 例如，根据后端的业务码判断请求是否真正成功
-        if(context.result.code === 200){
+        if (context.result.code === 200) {
           // 业务成功，直接返回 context
-          return context
-        }else{
+          return context;
+        }
+        else {
           // 业务失败，主动抛出一个 ResponseError，它将在 onError 钩子中被捕获
           throw new ResponseError({
             message: context.result.message, // 使用后端的错误信息
-            status: context.result.code,     // 使用后端的业务码作为状态
-            response: context.response,      // 原始 Response 对象
+            status: context.result.code, // 使用后端的业务码作为状态
+            response: context.response, // 原始 Response 对象
             config: context.config,
-            name: 'BusinessError'            // 自定义错误名称
+            name: 'BusinessError' // 自定义错误名称
           });
         }
       }
@@ -233,7 +241,8 @@ const examplePlugin = () => {
       if (error.name === 'BusinessError') {
         // 处理自定义的业务错误
         console.error(`业务错误: ${error.message}`);
-      } else if (error.status === 401) {
+      }
+      else if (error.status === 401) {
         // 处理未授权错误
         console.error('登录已过期，请重新登录');
         // window.location.href = '/login';
@@ -248,14 +257,14 @@ const examplePlugin = () => {
       console.log(`Request to ${config.url} completed`);
     }
   };
-};
+}
 ```
 
 #### 业务场景封装示例
 
 ```typescript
 // 创建一个业务请求实例
-const createRequest = () => {
+function createRequest() {
   // 创建基础实例
   const request = hookFetch.create({
     baseURL: 'https://api.example.com',
@@ -322,24 +331,24 @@ const createRequest = () => {
   return {
     // 用户相关接口
     user: {
-          // 获取用户信息
-    getInfo: () => request.get('/user/info').json(),
-    // 更新用户信息
-    updateInfo: (data) => request.put('/user/info', data).json(),
-    // 修改密码
-    changePassword: (data) => request.post('/user/password', data).json()
+      // 获取用户信息
+      getInfo: () => request.get('/user/info').json(),
+      // 更新用户信息
+      updateInfo: data => request.put('/user/info', data).json(),
+      // 修改密码
+      changePassword: data => request.post('/user/password', data).json()
     },
     // 订单相关接口
     order: {
       // 获取订单列表
-      getList: (params) => request.get('/orders', params).json(),
+      getList: params => request.get('/orders', params).json(),
       // 创建订单
-      create: (data) => request.post('/orders', data).json(),
+      create: data => request.post('/orders', data).json(),
       // 取消订单
-      cancel: (id) => request.post(`/orders/${id}/cancel`).json()
+      cancel: id => request.post(`/orders/${id}/cancel`).json()
     }
   };
-};
+}
 
 // 使用示例
 const api = createRequest();
@@ -355,6 +364,7 @@ const order = await api.order.create({
 ```
 
 插件钩子函数：
+
 - `beforeRequest`: 请求发送前处理配置，可以返回新的配置或直接修改配置
 - `afterResponse`: 响应接收后处理数据，可以返回新的响应或直接修改响应
 - `beforeStream`: 流式请求开始时的处理，用于初始化或转换流
@@ -466,14 +476,13 @@ interface HookFetchPlugin<T = unknown, E = unknown, P = unknown, D = unknown> {
 }
 ```
 
-
 ## Vue Hooks
 
 Hook-Fetch 提供了 Vue 组合式 API 的支持，可以更方便地在 Vue 组件中使用：
 
 ```typescript
-import { useHookFetch } from 'hook-fetch/vue';
 import hookFetch from 'hook-fetch';
+import { useHookFetch } from 'hook-fetch/vue';
 
 // 创建请求实例
 const api = hookFetch.create({
@@ -586,6 +595,7 @@ const YourComponent = () => {
 ```
 
 ### vscode提示插件的引用路径
+
 ```typescript
 // 在 src 中创建文件 hook-fetch.d.ts, 内容如下
 /// <reference types="hook-fetch/plugins" />
@@ -601,10 +611,12 @@ const YourComponent = () => {
 4. 插件按照优先级顺序执行
 
 ## 预计开发内容
+
 - `umd` 支持
 - 更多的插件支持
 
 ## 📝 贡献指南
+
 欢迎提交`issue`或`pull request`，共同完善`Hook-Fetch`。
 
 ## 📄 许可证