iota-fetch 0.1.0 → 0.1.1

package/README.md

@@ -1,107 +1,206 @@
-## iota-fetch
+# iota-fetch
 
-基于 **axios** 的二次封装请求库，提供统一的 `fetch.get/post/delete/put/patch` 调用方式，并内置**请求队列**能力（可按 key 取消单个请求或取消全部请求）。本项目为 **纯 JS 版本**（不包含 TypeScript 类型声明）。
+一个基于 **axios** 的二次封装请求库，提供统一的 `get/post/delete/put/patch` 调用方式，并内置**请求队列**能力（可按 key 中断单个请求或中断全部请求）。支持自定义 axios 默认配置、请求/响应拦截器，以及可选的 loading 显示/隐藏钩子。
 
-### 安装
+## 安装
 
 ```bash
 npm i iota-fetch axios
 ```
 
-> `iota-fetch` 运行时依赖 `axios`。如果你的业务项目里已经安装了 axios，可以只安装 `iota-fetch`，但建议保证 axios 版本满足本包要求。
+> 本项目本身依赖 `axios`，如果你在业务工程里已安装 axios，可按你的依赖管理策略处理（避免重复安装/版本冲突）。
 
-### 使用  ①
+## 快速开始
 
-```js
+```ts
 import { createFetch } from "iota-fetch";
 
-// requestConfig：axios.create 的配置
-const requestConfig = {
-  baseURL: "https://api.example.com",
-  headers: { "Content-Type": "application/json;charset=utf-8" },
-};
+const fetch = createFetch({
+  requestConfig: {
+    baseURL: "https://api.example.com",
+    headers: {
+      "Content-Type": "application/json;charset=utf-8",
+    },
+  },
+});
 
-// 请求拦截
-function requestIntercept() {
-  const intercept = (config) => config;
-  const error = (error) => Promise.reject(error);
-  return [intercept, error];
-}
+// GET：第二个参数会作为 query params
+const list = await fetch.get("/items", { page: 1, pageSize: 10 });
 
-// 响应拦截
-function responseIntercept() {
-  const intercept = (response) => response;
-  const error = (error) => Promise.reject(error);
-  return [intercept, error];
-}
+// POST：第二个参数会作为 body data
+const created = await fetch.post("/items", { name: "foo" });
+```
 
-// createFetch 返回 { fetch, instance }
-const { fetch } = createFetch({ requestIntercept, responseIntercept, requestConfig });
+## API
 
-// GET/DELETE：第二个参数作为 query params
-fetch.get("/list", { page: 1 });
+### `createFetch(options)`
 
-// POST/PUT/PATCH：第二个参数作为 body data
-fetch.post("/create", { name: "foo" });
-```
+创建一个包含 `get/post/delete/put/patch` 的请求对象。
+
+#### 参数 `options`
+
+- **`requestConfig`**: `CreateAxiosDefaults`
+  - axios 实例默认配置（如 `baseURL`、`timeout`、`headers` 等）
+- **`requestIntercept?`**: `() => { onFulfilled, onRejected }`
+  - 请求拦截器工厂函数（内部会 `instance.interceptors.request.use(...)`）
+- **`responseIntercept?`**: `() => { onFulfilled, onRejected }`
+  - 响应拦截器工厂函数（内部会 `instance.interceptors.response.use(...)`）
+- **`loading?`**: `{ show(): void; hide(): void }`
+  - 传入后可配合单次请求的 `config.loading` 控制显示/隐藏
+
+#### 返回值
 
-### 使用 ②
+返回 `fetch` 对象：
 
-```js
+- **`fetch.get(url, data?, config?)`**
+- **`fetch.delete(url, data?, config?)`**
+- **`fetch.post(url, data?, config?)`**
+- **`fetch.put(url, data?, config?)`**
+- **`fetch.patch(url, data?, config?)`**
+
+其中：
+- `url: string`
+- `data?: any`
+- `config?: AxiosRequestConfig & { loading?: boolean }`
+
+行为规则：
+- `get/delete`：`data` 会被放到 `params`
+- `post/put/patch`：`data` 会被放到 `data`
+- 返回值：默认 `Promise<R>`，内部 `resolve(res.data)`
+
+### 拦截器示例
+
+```ts
+import type { AxiosError, AxiosResponse, InternalAxiosRequestConfig } from "axios";
 import { createFetch } from "iota-fetch";
 
-// requestConfig：axios.create 的配置
-const requestConfig = {};
+const fetch = createFetch({
+  requestConfig: { baseURL: "https://api.example.com" },
+  requestIntercept: () => ({
+    onFulfilled: (config: InternalAxiosRequestConfig) => {
+      config.headers.set("X-Token", "your-token");
+      return config;
+    },
+    onRejected: (error: AxiosError) => Promise.reject(error),
+  }),
+  responseIntercept: () => ({
+    onFulfilled: (resp: AxiosResponse) => resp,
+    onRejected: (error: AxiosError) => Promise.reject(error),
+  }),
+});
+```
+
+### Loading 示例
+
+```ts
+import { createFetch } from "iota-fetch";
 
-// loading：实现 loading.show() / loading.hide()
 const loading = {
   show: () => console.log("loading show"),
   hide: () => console.log("loading hide"),
 };
 
-const { fetch, instance } = createFetch({ requestConfig, loading });
-
-// fetch 请求方法 fetch.get fetch.post fetch.put ...
-// 创建的axios 实例 instance 添加拦截器
-
-// 添加请求拦截器
-instance.interceptors.request.use(function (config) {
-    // 在发送请求之前做些什么
-    return config;
-  }, function (error) {
-    // 对请求错误做些什么
-    return Promise.reject(error);
-  });
-
-// 添加响应拦截器
-instance.interceptors.response.use(function (response) {
-    // 2xx 范围内的状态码都会触发该函数。
-    return response;
-  }, function (error) {
-    // 超出 2xx 范围的状态码都会触发该函数。
-    return Promise.reject(error);
-  });
-
-// 单次请求开启 loading：第三个参数 config 传入 { loading: true }
-fetch.get("/list", { page: 1 }, { loading: true });
+const fetch = createFetch({
+  requestConfig: { baseURL: "https://api.example.com" },
+  loading,
+});
+
+// 只有当 config.loading 为 true 才会触发 show/hide
+await fetch.get("/items", { page: 1 }, { loading: true });
 ```
 
-### 取消请求
+## 请求队列与取消请求
+
+包对外导出 `requestQueue`，内部用 `AbortController` 管理请求。
 
-```js
+```ts
 import { requestQueue } from "iota-fetch";
 
-// 生成 key（method + url + data(JSON.stringify)）
-const key = requestQueue.createMapKey("get", "/list", { page: 1 });
+// 获取当前队列（Map<key, AbortController>）
+const q = requestQueue.getQueue();
+```
+
+### key 规则
+
+key 默认由以下规则生成：
+
+1. 基础部分：`method + "-" + url`
+2. 数据部分：如果存在 `data`，则对其进行以下处理：
+   - 递归排序对象键
+   - 清洗数据（过滤 `undefined` 和函数）
+   - 将处理后的数据转换为 JSON 字符串
+   - 使用 MD5 生成哈希值
+3. 最终 key：`基础部分 + "-" + MD5哈希值`
+
+这样处理的好处是：
+- 相同的请求参数（无论顺序如何）会生成相同的 key
+- 避免了复杂参数导致 key 过长的问题
+- 提高了 key 的唯一性和安全性
 
-// 取消单个请求
+你也可以手动生成：
+
+```ts
+const key = requestQueue.createKey("get", "/items", { page: 1 });
+```
+
+示例：
+```ts
+// 以下两个请求会生成相同的 key
+const key1 = requestQueue.createKey("get", "/items", { page: 1, size: 10 });
+const key2 = requestQueue.createKey("get", "/items", { size: 10, page: 1 });
+
+// 输出示例："get-/items-5f4dcc3b5aa765d61d8327deb882cf99"
+```
+
+### 中断单个请求
+
+```ts
 requestQueue.abortive(key);
+```
+
+### 中断所有请求
 
-// 取消全部请求
+```ts
 requestQueue.removeResAll();
 ```
 
 ### 同 key 自动取消旧请求（内置行为）
 
-当你发起新请求时，如果队列里已存在相同 key 的请求，会先取消旧请求再登记新请求，避免相同请求并发造成浪费。
+当发起新请求时，如果队列里已存在同一个 key，会先取消旧请求再登记新请求（避免相同请求并发造成的覆盖与浪费）。
+
+> 注意：是否算“同一个请求”取决于 key（包含 `method/url/data` 的 JSON 字符串）。
+
+## 开发与构建
+
+```bash
+# 构建产物到 lib/（CJS + ESM + d.ts）
+npm run build
+
+# 开发模式（watch + 本地静态服务 + livereload）
+npm run start
+
+# 自动发布脚本（检查代码更新、npm 登录状态、版本管理）
+npm run release
+```
+
+构建输出（默认）：
+- `lib/bundle.cjs.js`
+- `lib/bundle.esm.js`
+- `lib/main.d.ts`
+
+## 发布流程
+
+1. 运行 `npm run release` 启动发布流程
+2. 脚本会检查代码是否有更新
+3. 检查 npm 是否登录
+4. 显示当前版本和仓库版本
+5. 选择版本升级类型（小版本/中版本/大版本）
+6. 执行构建和发布
+7. 显示远程包的最新版本
+
+## 版本管理
+
+- **小版本**：修复 bug，向后兼容
+- **中版本**：添加新功能，向后兼容
+- **大版本**：不向后兼容的变更
 

package/lib/axios/fetch.d.ts

@@ -0,0 +1,6 @@
+import type { FetchSturt, Loading, Options } from "./models";
+declare const createFetch: ({ requestConfig, requestIntercept, responseIntercept, loading, }: Options & {
+    loading?: Loading;
+}) => FetchSturt;
+export { createFetch };
+//# sourceMappingURL=fetch.d.ts.map

package/lib/axios/fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch.d.ts","sourceRoot":"","sources":["../../src/axios/fetch.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAa,UAAU,EAAY,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAElF,QAAA,MAAM,WAAW,GAAI,kEAKlB,OAAO,GAAG;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,eAiBjC,CAAC;AAEF,OAAO,EAAE,WAAW,EAAE,CAAC"}

package/lib/axios/fetchFun.d.ts

@@ -0,0 +1,5 @@
+import type { AxiosInstance } from "axios";
+import { Loading, RequestConfig } from "./models";
+declare const fetchData: <D, R = Record<string, any> | any>(instance: AxiosInstance, { url, method, data, config }: RequestConfig<D>, loading?: Loading) => Promise<R>;
+export default fetchData;
+//# sourceMappingURL=fetchFun.d.ts.map

package/lib/axios/fetchFun.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetchFun.d.ts","sourceRoot":"","sources":["../../src/axios/fetchFun.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAsB,MAAM,OAAO,CAAC;AAC/D,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAGlD,QAAA,MAAM,SAAS,GAAI,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,GAAG,EACjD,UAAU,aAAa,EACvB,+BAA+B,aAAa,CAAC,CAAC,CAAC,EAC/C,UAAU,OAAO,KAChB,OAAO,CAAC,CAAC,CAoCX,CAAC;AAEF,eAAe,SAAS,CAAC"}

package/lib/axios/instance.d.ts

@@ -0,0 +1,5 @@
+import { type AxiosInstance } from "axios";
+import { Options } from "./models";
+declare const createInstance: ({ requestConfig, requestIntercept, responseIntercept }: Options) => AxiosInstance;
+export default createInstance;
+//# sourceMappingURL=instance.d.ts.map

package/lib/axios/instance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance.d.ts","sourceRoot":"","sources":["../../src/axios/instance.ts"],"names":[],"mappings":"AAAA,OAAc,EAAE,KAAK,aAAa,EAAE,MAAM,OAAO,CAAC;AAClD,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAEnC,QAAA,MAAM,cAAc,GAAI,wDAAwD,OAAO,KAAG,aAkBzF,CAAC;AAEF,eAAe,cAAc,CAAC"}

package/lib/axios/models.d.ts

@@ -0,0 +1,32 @@
+import type { AxiosError, AxiosRequestConfig, AxiosResponse, CreateAxiosDefaults, InternalAxiosRequestConfig, Method } from "axios";
+export interface Options {
+    requestConfig: CreateAxiosDefaults;
+    requestIntercept?: () => {
+        onFulfilled: (config: InternalAxiosRequestConfig) => InternalAxiosRequestConfig;
+        onRejected: (error: AxiosError) => Promise<AxiosError>;
+    };
+    responseIntercept?: () => {
+        onFulfilled: (response: AxiosResponse) => AxiosResponse;
+        onRejected: (error: AxiosError) => Promise<AxiosError>;
+    };
+}
+export type ConfigPorps = {
+    loading?: boolean;
+} & AxiosRequestConfig;
+export interface RequestConfig<D = any> {
+    url: string;
+    method: Method;
+    data?: D;
+    loading?: boolean;
+    config?: ConfigPorps;
+}
+export type Loading = {
+    show: () => void;
+    hide: () => void;
+};
+export type FuncName = "get" | "post" | "delete" | "put" | "patch";
+export type FetchFunc = {
+    <D = any, R = Record<string, any>>(url: string, data?: D, config?: ConfigPorps): Promise<R>;
+};
+export type FetchSturt = Record<FuncName, FetchFunc>;
+//# sourceMappingURL=models.d.ts.map

package/lib/axios/models.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"models.d.ts","sourceRoot":"","sources":["../../src/axios/models.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,UAAU,EACV,kBAAkB,EAClB,aAAa,EACb,mBAAmB,EACnB,0BAA0B,EAC1B,MAAM,EACP,MAAM,OAAO,CAAC;AAEf,MAAM,WAAW,OAAO;IACtB,aAAa,EAAE,mBAAmB,CAAC;IAEnC,gBAAgB,CAAC,EAAE,MAAM;QACvB,WAAW,EAAE,CAAC,MAAM,EAAE,0BAA0B,KAAK,0BAA0B,CAAC;QAChF,UAAU,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;KACxD,CAAC;IAEF,iBAAiB,CAAC,EAAE,MAAM;QACxB,WAAW,EAAE,CAAC,QAAQ,EAAE,aAAa,KAAK,aAAa,CAAC;QACxD,UAAU,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;KACxD,CAAC;CACH;AAED,MAAM,MAAM,WAAW,GAAG;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,kBAAkB,CAAC;AAErE,MAAM,WAAW,aAAa,CAAC,CAAC,GAAG,GAAG;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,CAAC,CAAC;IACT,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,MAAM,OAAO,GAAG;IACpB,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,IAAI,EAAE,MAAM,IAAI,CAAC;CAClB,CAAC;AAGF,MAAM,MAAM,QAAQ,GAAG,KAAK,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,GAAG,OAAO,CAAC;AAEnE,MAAM,MAAM,SAAS,GAAG;IACtB,CAAC,CAAC,GAAG,GAAG,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAC7F,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC"}

package/lib/axios/requestQueue.d.ts

@@ -0,0 +1,16 @@
+declare class RequestQueue {
+    private static instance;
+    private queue;
+    constructor();
+    private sortObjectKeys;
+    getQueue(): Map<string, AbortController>;
+    createKey<T>(method: string, path: string, data?: T): string;
+    setQueue(key: string, controller: AbortController): void;
+    deleteQueue(key: string): void;
+    hasQueue(key: string): boolean;
+    abortive(key: string): void;
+    removeResAll(): void;
+}
+declare let requestQueue: RequestQueue;
+export { requestQueue };
+//# sourceMappingURL=requestQueue.d.ts.map

package/lib/axios/requestQueue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"requestQueue.d.ts","sourceRoot":"","sources":["../../src/axios/requestQueue.ts"],"names":[],"mappings":"AAEA,cAAM,YAAY;IAChB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAe;IACtC,OAAO,CAAC,KAAK,CAA+B;;IAe5C,OAAO,CAAC,cAAc;IAkBf,QAAQ,IAAI,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC;IAKxC,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,CAAC,GAAG,MAAM;IAU5D,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,eAAe;IAKjD,WAAW,CAAC,GAAG,EAAE,MAAM;IAKvB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAK9B,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAO3B,YAAY,IAAI,IAAI;CAI5B;AAED,QAAA,IAAI,YAAY,cAAqB,CAAC;AAEtC,OAAO,EAAE,YAAY,EAAE,CAAC"}