@ahoo-wang/fetcher 0.6.0 → 0.6.1

package/README.md

@@ -6,6 +6,7 @@
 [![License](https://img.shields.io/npm/l/@ahoo-wang/fetcher.svg)](https://github.com/Ahoo-Wang/fetcher/blob/main/LICENSE)
 [![npm downloads](https://img.shields.io/npm/dm/@ahoo-wang/fetcher.svg)](https://www.npmjs.com/package/@ahoo-wang/fetcher)
 [![npm bundle size](https://img.shields.io/bundlephobia/minzip/%40ahoo-wang%2Ffetcher)](https://www.npmjs.com/package/@ahoo-wang/fetcher)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/Ahoo-Wang/fetcher)
 
 A modern, ultra-lightweight (1.9kB) HTTP client with built-in path parameters, query parameters, and Axios-like API. 86%
 smaller than Axios while providing the same powerful features.
@@ -53,7 +54,7 @@ const response = await fetcher.get('/users/{id}', {
   path: { id: 123 },
   query: { include: 'profile' },
 });
-const userData = await response.json();
+const userData = await response.json<User>();
 
 // POST request with automatic JSON conversion
 const createUserResponse = await fetcher.post('/users', {
@@ -100,12 +101,46 @@ import { fetcher } from '@ahoo-wang/fetcher';
 
 // Use the default fetcher directly
 const response = await fetcher.get('/users');
-const data = await response.json();
+const data = await response.json<User>();
 ```
 
 ## 🔗 Interceptor System
 
-### Request Interceptors
+### Interceptor
+
+Interceptor interface that defines the basic structure of interceptors.
+
+**Properties:**
+
+- `name: string` - The name of the interceptor, used to identify it, must be unique
+- `order: number` - The execution order of the interceptor, smaller values have higher priority
+
+**Methods:**
+
+- `intercept(exchange: FetchExchange): FetchExchange | Promise<FetchExchange>` - Intercept and process data
+
+### InterceptorManager
+
+Interceptor manager for managing multiple interceptors of the same type.
+
+**Methods:**
+
+- `use(interceptor: Interceptor): boolean` - Add interceptor, returns whether the addition was successful
+- `eject(name: string): boolean` - Remove interceptor by name, returns whether the removal was successful
+- `clear(): void` - Clear all interceptors
+- `intercept(exchange: FetchExchange): Promise<FetchExchange>` - Execute all interceptors in sequence
+
+### FetcherInterceptors
+
+Fetcher interceptor collection, including request, response, and error interceptor managers.
+
+**Properties:**
+
+- `request: InterceptorManager` - Request interceptor manager
+- `response: InterceptorManager` - Response interceptor manager
+- `error: InterceptorManager` - Error interceptor manager
+
+### Using Interceptors
 
 ```typescript
 import { Fetcher } from '@ahoo-wang/fetcher';
@@ -113,7 +148,9 @@ import { Fetcher } from '@ahoo-wang/fetcher';
 const fetcher = new Fetcher({ baseURL: 'https://api.example.com' });
 
 // Add request interceptor (e.g., for authentication)
-const interceptorId = fetcher.interceptors.request.use({
+const success = fetcher.interceptors.request.use({
+  name: 'auth-interceptor',
+  order: 100,
   intercept(exchange) {
     return {
       ...exchange,
@@ -128,8 +165,84 @@ const interceptorId = fetcher.interceptors.request.use({
   },
 });
 
-// Remove interceptor
-fetcher.interceptors.request.eject(interceptorId);
+// Add response interceptor (e.g., for logging)
+fetcher.interceptors.response.use({
+  name: 'logging-interceptor',
+  order: 10,
+  intercept(exchange) {
+    console.log('Response received:', exchange.response?.status);
+    return exchange;
+  },
+});
+
+// Add error interceptor (e.g., for unified error handling)
+fetcher.interceptors.error.use({
+  name: 'error-interceptor',
+  order: 50,
+  intercept(exchange) {
+    if (exchange.error?.name === 'FetchTimeoutError') {
+      console.error('Request timeout:', exchange.error.message);
+    } else {
+      console.error('Network error:', exchange.error?.message);
+    }
+    return exchange;
+  },
+});
+
+// Remove interceptor by name
+fetcher.interceptors.request.eject('auth-interceptor');
+```
+
+### Ordered Execution
+
+The `OrderedCapable` system allows you to control the execution order of interceptors and other components.
+
+#### Ordering Concept
+
+```typescript
+import { OrderedCapable } from '@ahoo-wang/fetcher';
+
+// Lower order values have higher priority
+const highPriority: OrderedCapable = { order: 1 }; // Executes first
+const mediumPriority: OrderedCapable = { order: 10 }; // Executes second
+const lowPriority: OrderedCapable = { order: 100 }; // Executes last
+```
+
+#### Interceptor Ordering
+
+```typescript
+// Add interceptors with different orders
+fetcher.interceptors.request.use({
+  name: 'timing-interceptor',
+  order: 5, // Executes very early
+  intercept(exchange) {
+    console.log('Very early timing');
+    return exchange;
+  },
+});
+
+fetcher.interceptors.request.use({
+  name: 'logging-interceptor',
+  order: 10, // Executes early
+  intercept(exchange) {
+    console.log('Early logging');
+    return exchange;
+  },
+});
+
+fetcher.interceptors.request.use({
+  name: 'auth-interceptor',
+  order: 50, // Executes later
+  intercept(exchange) {
+    // Add auth headers
+    return exchange;
+  },
+});
+
+// Execution order will be:
+// 1. timing-interceptor (order: 5)
+// 2. logging-interceptor (order: 10)
+// 3. auth-interceptor (order: 50)
 ```
 
 ### Response Interceptors
@@ -189,6 +302,109 @@ new Fetcher(options ? : FetcherOptions);
 - `head(url: string, request?: Omit<FetcherRequest, 'method' | 'body'>): Promise<Response>` - HEAD request
 - `options(url: string, request?: Omit<FetcherRequest, 'method' | 'body'>): Promise<Response>` - OPTIONS request
 
+### Response Extension
+
+To provide better TypeScript support, we extend the native Response interface with a type-safe json() method:
+
+```typescript
+// Now you can use it with type safety
+const response = await fetcher.get('/users/123');
+const userData = await response.json<User>(); // Type is Promise<User>
+```
+
+### NamedFetcher Class
+
+An extension of the Fetcher class that automatically registers itself with the global fetcherRegistrar.
+
+#### Constructor
+
+```typescript
+new NamedFetcher(name
+:
+string, options ? : FetcherOptions
+)
+;
+```
+
+### FetcherRegistrar
+
+Global instance for managing multiple Fetcher instances by name.
+
+#### Properties
+
+- `default`: Get or set the default fetcher instance
+
+#### Methods
+
+- `register(name: string, fetcher: Fetcher): void` - Register a fetcher with a name
+- `unregister(name: string): boolean` - Unregister a fetcher by name
+- `get(name: string): Fetcher | undefined` - Get a fetcher by name
+- `requiredGet(name: string): Fetcher` - Get a fetcher by name, throws if not found
+- `fetchers: Map<string, Fetcher>` - Get all registered fetchers
+
+### Interceptor System
+
+#### Interceptor
+
+Interceptor interface that defines the basic structure of interceptors.
+
+**Properties:**
+
+- `name: string` - The name of the interceptor, used to identify it, must be unique
+- `order: number` - The execution order of the interceptor, smaller values have higher priority
+
+**Methods:**
+
+- `intercept(exchange: FetchExchange): FetchExchange | Promise<FetchExchange>` - Intercept and process data
+
+#### InterceptorManager
+
+Interceptor manager for managing multiple interceptors of the same type.
+
+**Methods:**
+
+- `use(interceptor: Interceptor): boolean` - Add interceptor, returns whether the addition was successful
+- `eject(name: string): boolean` - Remove interceptor by name, returns whether the removal was successful
+- `clear(): void` - Clear all interceptors
+- `intercept(exchange: FetchExchange): Promise<FetchExchange>` - Execute all interceptors in sequence
+
+#### FetcherInterceptors
+
+Fetcher interceptor collection, including request, response, and error interceptor managers.
+
+**Properties:**
+
+- `request: InterceptorManager` - Request interceptor manager
+- `response: InterceptorManager` - Response interceptor manager
+- `error: InterceptorManager` - Error interceptor manager
+
+**Options:**
+
+- `baseURL`: Base URL for all requests
+- `timeout`: Request timeout in milliseconds
+- `headers`: Default request headers
+
+#### Methods
+
+- `fetch(url: string, request?: FetcherRequest): Promise<Response>` - Generic HTTP request method
+- `get(url: string, request?: Omit<FetcherRequest, 'method' | 'body'>): Promise<Response>` - GET request
+- `post(url: string, request?: Omit<FetcherRequest, 'method'>): Promise<Response>` - POST request
+- `put(url: string, request?: Omit<FetcherRequest, 'method'>): Promise<Response>` - PUT request
+- `delete(url: string, request?: Omit<FetcherRequest, 'method'>): Promise<Response>` - DELETE request
+- `patch(url: string, request?: Omit<FetcherRequest, 'method'>): Promise<Response>` - PATCH request
+- `head(url: string, request?: Omit<FetcherRequest, 'method' | 'body'>): Promise<Response>` - HEAD request
+- `options(url: string, request?: Omit<FetcherRequest, 'method' | 'body'>): Promise<Response>` - OPTIONS request
+
+### Response Extension
+
+To provide better TypeScript support, we extend the native Response interface with a type-safe json() method:
+
+```typescript
+// Now you can use it with type safety
+const response = await fetcher.get('/users/123');
+const userData = await response.json<User>(); // Type is Promise<User>
+```
+
 ### NamedFetcher Class
 
 An extension of the Fetcher class that automatically registers itself with the global fetcherRegistrar.
@@ -221,6 +437,40 @@ Global instance for managing multiple Fetcher instances by name.
 
 ### Interceptor System
 
+#### Interceptor
+
+Interceptor interface that defines the basic structure of interceptors.
+
+**Properties:**
+
+- `name: string` - The name of the interceptor, used to identify it, must be unique
+- `order: number` - The execution order of the interceptor, smaller values have higher priority
+
+**Methods:**
+
+- `intercept(exchange: FetchExchange): FetchExchange | Promise<FetchExchange>` - Intercept and process data
+
+#### InterceptorManager
+
+Interceptor manager for managing multiple interceptors of the same type.
+
+**Methods:**
+
+- `use(interceptor: Interceptor): boolean` - Add interceptor, returns whether the addition was successful
+- `eject(name: string): boolean` - Remove interceptor by name, returns whether the removal was successful
+- `clear(): void` - Clear all interceptors
+- `intercept(exchange: FetchExchange): Promise<FetchExchange>` - Execute all interceptors in sequence
+
+#### FetcherInterceptors
+
+Fetcher interceptor collection, including request, response, and error interceptor managers.
+
+**Properties:**
+
+- `request: InterceptorManager` - Request interceptor manager
+- `response: InterceptorManager` - Response interceptor manager
+- `error: InterceptorManager` - Error interceptor manager
+
 #### Request Interceptors
 
 ```typescript
@@ -229,7 +479,7 @@ import { Fetcher } from '@ahoo-wang/fetcher';
 const fetcher = new Fetcher({ baseURL: 'https://api.example.com' });
 
 // Add request interceptor (e.g., for authentication)
-const interceptorId = fetcher.interceptors.request.use({
+const success = fetcher.interceptors.request.use({
   name: 'auth-interceptor',
   order: 100,
   intercept(exchange) {

package/README.zh-CN.md

@@ -6,6 +6,7 @@
 [![License](https://img.shields.io/npm/l/@ahoo-wang/fetcher.svg)](https://github.com/Ahoo-Wang/fetcher/blob/main/LICENSE)
 [![npm downloads](https://img.shields.io/npm/dm/@ahoo-wang/fetcher.svg)](https://www.npmjs.com/package/@ahoo-wang/fetcher)
 [![npm bundle size](https://img.shields.io/bundlephobia/minzip/%40ahoo-wang%2Ffetcher)](https://www.npmjs.com/package/@ahoo-wang/fetcher)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/Ahoo-Wang/fetcher)
 
 一个现代、超轻量级（1.9kB）的 HTTP 客户端，内置路径参数、查询参数和类似 Axios 的 API。比 Axios 小 86%，同时提供相同的强大功能。
 
@@ -52,7 +53,7 @@ const response = await fetcher.get('/users/{id}', {
   path: { id: 123 },
   query: { include: 'profile' },
 });
-const userData = await response.json();
+const userData = await response.json<User>();
 
 // 带自动 JSON 转换的 POST 请求
 const createUserResponse = await fetcher.post('/users', {
@@ -99,12 +100,46 @@ import { fetcher } from '@ahoo-wang/fetcher';
 
 // 直接使用默认 fetcher
 const response = await fetcher.get('/users');
-const data = await response.json();
+const data = await response.json<User>();
 ```
 
 ## 🔗 拦截器系统
 
-### 请求拦截器
+### Interceptor
+
+拦截器接口，定义了拦截器的基本结构。
+
+**属性：**
+
+- `name: string` - 拦截器的名称，用于标识拦截器，不可重复
+- `order: number` - 拦截器的执行顺序，数值越小优先级越高
+
+**方法：**
+
+- `intercept(exchange: FetchExchange): FetchExchange | Promise<FetchExchange>` - 拦截并处理数据
+
+### InterceptorManager
+
+用于管理同一类型多个拦截器的拦截器管理器。
+
+**方法：**
+
+- `use(interceptor: Interceptor): boolean` - 添加拦截器，返回是否添加成功
+- `eject(name: string): boolean` - 按名称移除拦截器，返回是否移除成功
+- `clear(): void` - 清除所有拦截器
+- `intercept(exchange: FetchExchange): Promise<FetchExchange>` - 顺序执行所有拦截器
+
+### FetcherInterceptors
+
+Fetcher 拦截器集合，包括请求、响应和错误拦截器管理器。
+
+**属性：**
+
+- `request: InterceptorManager` - 请求拦截器管理器
+- `response: InterceptorManager` - 响应拦截器管理器
+- `error: InterceptorManager` - 错误拦截器管理器
+
+### 使用拦截器
 
 ```typescript
 import { Fetcher } from '@ahoo-wang/fetcher';
@@ -112,7 +147,9 @@ import { Fetcher } from '@ahoo-wang/fetcher';
 const fetcher = new Fetcher({ baseURL: 'https://api.example.com' });
 
 // 添加请求拦截器（例如用于认证）
-const interceptorId = fetcher.interceptors.request.use({
+const success = fetcher.interceptors.request.use({
+  name: 'auth-interceptor',
+  order: 100,
   intercept(exchange) {
     return {
       ...exchange,
@@ -127,27 +164,20 @@ const interceptorId = fetcher.interceptors.request.use({
   },
 });
 
-// 移除拦截器
-fetcher.interceptors.request.eject(interceptorId);
-```
-
-### 响应拦截器
-
-```typescript
 // 添加响应拦截器（例如用于日志记录）
 fetcher.interceptors.response.use({
+  name: 'logging-interceptor',
+  order: 10,
   intercept(exchange) {
-    console.log('收到响应:', exchange.response.status);
+    console.log('收到响应:', exchange.response?.status);
     return exchange;
   },
 });
-```
-
-### 错误拦截器
 
-```typescript
 // 添加错误拦截器（例如用于统一错误处理）
 fetcher.interceptors.error.use({
+  name: 'error-interceptor',
+  order: 50,
   intercept(exchange) {
     if (exchange.error?.name === 'FetchTimeoutError') {
       console.error('请求超时:', exchange.error.message);
@@ -157,89 +187,62 @@ fetcher.interceptors.error.use({
     return exchange;
   },
 });
-```
-
-## 📚 API 参考
 
-### Fetcher 类
-
-提供各种 HTTP 方法的核心 HTTP 客户端类。
-
-#### 构造函数
-
-```typescript
-new Fetcher(options ? : FetcherOptions);
+// 按名称移除拦截器
+fetcher.interceptors.request.eject('auth-interceptor');
 ```
 
-**选项：**
+### 有序执行
 
-- `baseURL`：基础 URL
-- `timeout`：以毫秒为单位的请求超时
-- `headers`：默认请求头部
+`OrderedCapable` 系统允许您控制拦截器和其他组件的执行顺序。
 
-#### 方法
-
-- `fetch(url: string, request?: FetcherRequest): Promise<Response>` - 通用 HTTP 请求方法
-- `get(url: string, request?: Omit<FetcherRequest, 'method' | 'body'>): Promise<Response>` - GET 请求
-- `post(url: string, request?: Omit<FetcherRequest, 'method'>): Promise<Response>` - POST 请求
-- `put(url: string, request?: Omit<FetcherRequest, 'method'>): Promise<Response>` - PUT 请求
-- `delete(url: string, request?: Omit<FetcherRequest, 'method'>): Promise<Response>` - DELETE 请求
-- `patch(url: string, request?: Omit<FetcherRequest, 'method'>): Promise<Response>` - PATCH 请求
-- `head(url: string, request?: Omit<FetcherRequest, 'method' | 'body'>): Promise<Response>` - HEAD 请求
-- `options(url: string, request?: Omit<FetcherRequest, 'method' | 'body'>): Promise<Response>` - OPTIONS 请求
-
-### NamedFetcher 类
-
-Fetcher 类的扩展，它会自动使用提供的名称在全局 fetcherRegistrar 中注册自己。
-
-#### 构造函数
+#### 排序概念
 
 ```typescript
-new NamedFetcher(name
-:
-string, options ? : FetcherOptions
-)
-;
-```
-
-### FetcherRegistrar
-
-用于按名称管理多个 Fetcher 实例的全局实例。
-
-#### 属性
-
-- `default`：获取或设置默认 fetcher 实例
-
-#### 方法
+import { OrderedCapable } from '@ahoo-wang/fetcher';
 
-- `register(name: string, fetcher: Fetcher): void` - 使用名称注册 fetcher
-- `unregister(name: string): boolean` - 按名称注销 fetcher
-- `get(name: string): Fetcher | undefined` - 按名称获取 fetcher
-- `requiredGet(name: string): Fetcher` - 按名称获取 fetcher，如果未找到则抛出错误
-- `fetchers: Map<string, Fetcher>` - 获取所有已注册的 fetcher
-
-### 拦截器系统
-
-#### InterceptorManager
-
-用于管理同一类型多个拦截器的拦截器管理器。
-
-**方法：**
+// 数值越小优先级越高
+const highPriority: OrderedCapable = { order: 1 }; // 首先执行
+const mediumPriority: OrderedCapable = { order: 10 }; // 其次执行
+const lowPriority: OrderedCapable = { order: 100 }; // 最后执行
+```
 
-- `use(interceptor: Interceptor): number` - 添加拦截器，返回拦截器 ID
-- `eject(index: number): void` - 按 ID 移除拦截器
-- `clear(): void` - 清除所有拦截器
-- `intercept(exchange: FetchExchange): Promise<FetchExchange>` - 顺序执行所有拦截器
+#### 拦截器排序
 
-#### FetcherInterceptors
+```typescript
+// 添加具有不同顺序的拦截器
+fetcher.interceptors.request.use({
+  name: 'timing-interceptor',
+  order: 5, // 很早执行
+  intercept(exchange) {
+    console.log('很早的计时');
+    return exchange;
+  },
+});
 
-Fetcher 拦截器集合，包括请求、响应和错误拦截器管理器。
+fetcher.interceptors.request.use({
+  name: 'logging-interceptor',
+  order: 10, // 较早执行
+  intercept(exchange) {
+    console.log('较早的日志');
+    return exchange;
+  },
+});
 
-**属性：**
+fetcher.interceptors.request.use({
+  name: 'auth-interceptor',
+  order: 50, // 较晚执行
+  intercept(exchange) {
+    // 添加认证头部
+    return exchange;
+  },
+});
 
-- `request: InterceptorManager` - 请求拦截器管理器
-- `response: InterceptorManager` - 响应拦截器管理器
-- `error: InterceptorManager` - 错误拦截器管理器
+// 执行顺序将是：
+// 1. timing-interceptor (order: 5)
+// 2. logging-interceptor (order: 10)
+// 3. auth-interceptor (order: 50)
+```
 
 ## 🛠️ 开发
 

package/dist/types.d.ts

@@ -42,4 +42,18 @@ export interface NamedCapable {
      */
     name: string;
 }
+/**
+ * Global extension of Response interface
+ * Adds type-safe json() method support to Response objects
+ */
+declare global {
+    interface Response {
+        /**
+         * Parse response body as JSON in a type-safe manner
+         * @template T The type of returned data, defaults to any
+         * @returns Promise<T> The parsed JSON data
+         */
+        json<T = any>(): Promise<T>;
+    }
+}
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAaA,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED;;GAEG;AACH,oBAAY,UAAU;IACpB,GAAG,QAAQ;IACX,IAAI,SAAS;IACb,GAAG,QAAQ;IACX,MAAM,WAAW;IACjB,KAAK,UAAU;IACf,IAAI,SAAS;IACb,OAAO,YAAY;CACpB;AAED,oBAAY,YAAY;IACtB,MAAM,WAAW;IACjB,IAAI,SAAS;CACd;AAED,eAAO,MAAM,iBAAiB,iBAAiB,CAAC;AAEhD,oBAAY,iBAAiB;IAC3B,gBAAgB,qBAAqB;IACrC,iBAAiB,sBAAsB;CACxC;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;CACd"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAaA,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED;;GAEG;AACH,oBAAY,UAAU;IACpB,GAAG,QAAQ;IACX,IAAI,SAAS;IACb,GAAG,QAAQ;IACX,MAAM,WAAW;IACjB,KAAK,UAAU;IACf,IAAI,SAAS;IACb,OAAO,YAAY;CACpB;AAED,oBAAY,YAAY;IACtB,MAAM,WAAW;IACjB,IAAI,SAAS;CACd;AAED,eAAO,MAAM,iBAAiB,iBAAiB,CAAC;AAEhD,oBAAY,iBAAiB;IAC3B,gBAAgB,qBAAqB;IACrC,iBAAiB,sBAAsB;CACxC;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;GAGG;AACH,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,QAAQ;QAChB;;;;WAIG;QACH,IAAI,CAAC,CAAC,GAAG,GAAG,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;KAC7B;CACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahoo-wang/fetcher",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Ultra-lightweight (1.9kB) HTTP client with built-in path parameters and Axios-like API",
   "keywords": [
     "fetch",