@net-vert/core 0.0.5 → 0.0.6

package/README.md

@@ -0,0 +1,318 @@
+
+---
+
+# @net-vert/core
+
+**轻量级依赖倒置网络请求库，专为扩展和易用而设计。**
+
+GitHub 开源仓库 👉 [https://github.com/yvygyyth/net-vert](https://github.com/yvygyyth/net-vert)
+
+---
+
+## ✨ 核心特性
+
+✅ 解耦网络层，按需注入 axios、fetch 或自定义请求器  
+✅ 支持缓存、幂等、重试等扩展  
+✅ TypeScript 全类型提示，开发更丝滑  
+✅ 内置幂等、缓存、重试等扩展
+✅ 零配置上手，API 极简  
+
+---
+
+## 📦 安装
+
+```bash
+npm install @net-vert/core
+```
+
+---
+
+## 🚀 快速上手
+
+### 1️⃣ 注入请求器（以 axios 为例）
+
+```typescript
+import axios from 'axios';
+import { inject, useRequestor } from '@net-vert/core';
+
+const instance = axios.create({ baseURL: '/api', timeout: 60000 });
+const axiosAdapter = (config) => instance.request(config);
+
+inject(axiosAdapter); // 注入 axios 实例
+```
+
+---
+
+### 2️⃣ 发起请求
+
+```typescript
+const api = useRequestor();
+
+api.get('/user/info', { params: { id: 1 } }).then(console.log);
+api.post('/user/create', { name: 'Alice' }).then(console.log);
+```
+
+---
+
+## 🛠 扩展能力（requestExtender）
+
+```typescript
+import { requestExtender } from '@net-vert/core';
+```
+
+✅ **缓存请求**
+```typescript
+const cachedApi = requestExtender.cacheRequestor();
+cachedApi.get('/user/info', { params: { id: 1 } });
+```
+
+✅ **幂等请求**
+```typescript
+const idempotentApi = requestExtender.idempotencyRequestor();
+idempotentApi.post('/user/create', { name: 'Alice' });
+```
+
+✅ **自动重试**
+```typescript
+const retryApi = requestExtender.retryRequestor({ retries: 3, delay: 1000 });
+retryApi.get('/unstable-api');
+```
+
+---
+
+## 🔎 缓存设计说明
+
+- 本库默认内置缓存支持
+- **后续将完全依赖官方独立包：`@net-vert/cache`**
+- 用户无需关注存储机制，专注请求本身
+
+---
+
+## 🧩 核心 API
+
+| 方法 | 描述 |
+|-----|------|
+| `inject(adapter, instanceKey?)` | 注入请求适配器,不填默认为'default' |
+| `useRequestor(instanceKey?)` | 获取请求实例 |
+| `requestExtender.cacheRequestor(options)` | 创建带缓存能力的请求器 |
+| `requestExtender.idempotencyRequestor(options)` | 创建幂等请求器 |
+| `requestExtender.retryRequestor(options)` | 创建重试请求器 |
+
+非常专业！以下是针对你这份缓存扩展的专属文档（带源码思路和示例）：  
+
+---
+
+## 🗂 缓存扩展 `requestExtender.cacheRequestor(options)`
+
+`cacheRequestor` 是 `@net-vert/core` 内置的缓存增强器，为请求增加缓存命中机制，避免重复请求，提升性能。
+
+### ✅ 核心特性
+
+- 支持本地缓存或内存缓存（未来由 `@net-vert/cache` 提供存储支持）
+- 同一请求中的并发合并（Promise 复用）
+- 支持缓存过期时间配置
+- 支持缓存 key 自定义生成逻辑
+- 自动处理 Promise 缓存清理
+
+---
+
+### ⚙️ 配置参数（可选）
+
+| 参数         | 类型                                             | 说明                                           | 默认值         |
+| ------------ | ----------------------------------------------- | ---------------------------------------------- | -------------- |
+| `key`        | `(config: UnifiedConfig) => string`              | 自定义缓存 key 生成规则                        | `config.url`   |
+| `persist`    | `boolean`                                       | 是否持久化缓存（默认走内存）                   | `false`        |
+| `cacheTime`  | `number` 或 `({config, response}) => number`    | 缓存有效期（毫秒）或动态计算缓存时间           | `Infinity`     |
+
+---
+
+### 📥 使用示例
+
+```typescript
+import { requestExtender } from '@net-vert/core';
+
+const cachedApi = requestExtender.cacheRequestor({
+  cacheTime: 5000, // 缓存 5 秒
+  key: (config) => `${config.method}-${config.url}` // 自定义缓存 key
+});
+
+// 第一次请求发出
+cachedApi.get('/user/info', { params: { id: 1 } }).then(console.log);
+
+// 5 秒内相同请求直接走缓存
+cachedApi.get('/user/info', { params: { id: 1 } }).then(console.log);
+```
+
+---
+
+### 🔥 示例动态缓存时间计算
+
+```typescript
+const dynamicCachedApi = requestExtender.cacheRequestor({
+  cacheTime: ({ config, response }) => {
+    // 根据接口返回决定缓存时间
+    return response.isHot ? 10000 : 3000;
+  }
+});
+```
+
+## ♻️ 幂等扩展 `requestExtender.idempotencyRequestor(options)`
+
+`idempotencyRequestor` 是基于 `cacheRequestor` 封装的幂等增强器，确保同一参数的请求，在请求未完成前只发送一次，自动合并并发请求，避免重复提交和资源浪费。
+
+---
+
+### ✅ 核心特性
+
+- 采用 **哈希生成请求唯一标识**，自动识别重复请求
+- 请求未完成时直接复用 Promise，避免短时间内重复请求接口
+- 请求完成自动清理，确保后续请求正常发起
+- 内存缓存（`persist: false`），适合表单提交、按钮防抖等场景
+
+---
+
+### ⚙️ 内部默认的哈希算法（hashRequest）
+
+```typescript
+const hashRequest = (config: UnifiedConfig) => {
+  const { method, url, params, data } = config
+  return [method, url, JSON.stringify(params), JSON.stringify(data)].join('|')
+}
+```
+支持用户传入自定义生成规则：
+
+```typescript
+const idempotentApi = requestExtender.idempotencyRequestor((config) => {
+  return `custom-key-${config.url}`;
+});
+```
+
+---
+
+## 🔁 重试扩展 `requestExtender.retryRequestor(options)`
+
+`retryRequestor` 是基于 `Requestor` 增强的请求重试器，提供自动重试机制，确保请求失败时自动重试，提升请求稳定性。
+
+---
+
+### ✅ 核心特性
+
+- 支持 **最大重试次数**，可避免无限重试
+- 支持 **延迟重试**，延迟时间可自定义，默认 1000ms
+- 支持 **重试条件**，根据特定错误判断是否重试
+- 自动处理请求失败，符合幂等性原则，保证稳定性
+
+---
+
+### ⚙️ 配置选项
+
+| 参数              | 类型                                       | 说明                                             | 默认值       |
+| ----------------- | ------------------------------------------ | ------------------------------------------------ | ------------ |
+| `retries`         | `number`                                   | 最大重试次数                                     | `3`          |
+| `delay`           | `number` 或 `({attempt: number}) => number` | 延迟重试时间（默认延迟 1000ms）                  | `1000ms`     |
+| `retryCondition`  | `(error: any) => boolean`                  | 重试条件，返回 `true` 时触发重试（默认对所有错误重试） | `() => true`  |
+
+---
+
+### 📥 使用示例
+
+```typescript
+import { requestExtender } from '@net-vert/core';
+
+// 配置最大重试次数为 5 次，延迟 2 秒
+const retryApi = requestExtender.retryRequestor({
+  retries: 5,
+  delay: 2000
+});
+
+// 请求失败时自动重试
+retryApi.get('/unstable-api').then(console.log).catch(console.error);
+```
+
+---
+
+### 🔎 重试逻辑解析
+
+1. **最大重试次数 (`retries`)**：当请求失败时，最多重试 `retries` 次。
+2. **延迟策略 (`delay`)**：每次重试之间等待一段时间，支持固定时间或动态计算。
+   - 默认：1000ms（1秒）
+   - 可以根据重试次数动态调整延迟时间：
+     ```typescript
+     delay: (attempt) => attempt * 1000 // 每次重试延迟递增
+     ```
+3. **重试条件 (`retryCondition`)**：只有当错误符合重试条件时才会进行重试，默认为所有错误都重试。
+
+---
+
+### ⚠️ 使用建议
+
+- **避免无限重试**：设置合适的最大重试次数（`retries`）和延迟时间（`delay`），防止请求卡死。
+- **根据错误类型重试**：可以根据特定的错误类型或者状态码设定 `retryCondition`，例如：
+  ```typescript
+  retryCondition: (error) => error.response.status === 500
+  ```
+  这样仅在服务器错误时才会进行重试。
+
+---
+
+### 🔥 典型应用场景
+
+- **API 请求失败重试**：对那些偶尔会失败的网络请求，提供自动重试能力，提升成功率。
+- **避免因瞬时网络问题而导致的请求失败**。
+- **服务宕机恢复后自动重新发起请求**。
+
+---
+
+### 📥 使用示例
+
+```typescript
+import { requestExtender } from '@net-vert/core';
+
+const idempotentApi = requestExtender.idempotencyRequestor();
+
+// 短时间内连续点击两次，只会发出一次请求
+idempotentApi.post('/user/create', { name: 'Alice' }).then(console.log);
+idempotentApi.post('/user/create', { name: 'Alice' }).then(console.log);
+```
+
+控制台：
+```
+===> 已存在该请求: POST|/user/create|{}|{"name":"Alice"}
+```
+
+---
+
+### 🔎 典型应用场景
+
+✅ 表单防重复提交  
+✅ 提交按钮多次点击防抖  
+✅ 防止接口雪崩（接口短时间被高频调用）
+
+---
+
+### ⚠️ 使用注意
+
+- 本功能专为短时防重复设计，**缓存不持久化**
+- 推荐用于 POST、PUT 等存在副作用的接口
+- 自动清理缓存，确保下一次请求正常发出
+
+---
+
+## 📤 开源信息
+
+- 仓库地址：[https://github.com/yvygyyth/net-vert](https://github.com/yvygyyth/net-vert)
+- 许可证：MIT
+- 支持 Tree-Shaking
+- 无副作用 (`sideEffects: false`)
+
+---
+
+## 🔥 设计理念
+
+- 网络层完全解耦，未来自由扩展
+- 内置强大的请求能力，零上手成本
+- 存储与缓存拆分，保持核心轻量纯粹
+
+---
+
+如果你确定了包名是 `@net-vert/cache`，我可以直接帮你生成一段未来文档里的“缓存插件使用示例”，随时告诉我！

package/dist/index.d.ts

@@ -3,23 +3,6 @@ declare interface BasicCredentials {
     password: string;
 }
 
-export declare const extendRequestor: {
-    createCacheRequestor: (config?: {
-        key?: (config: UnifiedConfig) => string;
-        persist?: boolean;
-        cacheTime?: number | (({ config, response }: {
-            config: UnifiedConfig;
-            response: any;
-        }) => number);
-    }) => Requestor;
-    createIdempotencyRequestor: (genKey?: (config: UnifiedConfig) => string) => Requestor;
-    createRetryRequestor: (config?: {
-        retries?: number;
-        delay?: number | ((attempt: number) => number);
-        retryCondition?: (error: any) => boolean;
-    }) => Requestor;
-};
-
 export declare const inject: (requestor: UnifiedRequestor, instanceKey?: string) => void;
 
 declare interface RequestConfig<D = any> {
@@ -38,6 +21,23 @@ declare interface RequestConfig<D = any> {
     signal?: AbortSignal;
 }
 
+export declare const requestExtender: {
+    cacheRequestor: (config?: {
+        key?: (config: UnifiedConfig) => string;
+        persist?: boolean;
+        cacheTime?: number | (({ config, response }: {
+            config: UnifiedConfig;
+            response: any;
+        }) => number);
+    }) => Requestor;
+    idempotencyRequestor: (genKey?: (config: UnifiedConfig) => string) => Requestor;
+    retryRequestor: (config?: {
+        retries?: number;
+        delay?: number | ((attempt: number) => number);
+        retryCondition?: (error: any) => boolean;
+    }) => Requestor;
+};
+
 export declare interface Requestor {
     get<R = any, D = any>(url: string, config?: RequestConfig<D>): Promise<R>;
     post<R = any, D = any>(url: string, data?: D, config?: RequestConfig<D>): Promise<R>;

package/dist/index.js

@@ -26,7 +26,7 @@ const y = {
   }),
   request: (t) => t
 };
-function R(t) {
+function x(t) {
   const e = {};
   return Object.keys(y).forEach(
     (r) => {
@@ -40,14 +40,14 @@ function R(t) {
     request: t
   };
 }
-const q = /* @__PURE__ */ new Map(), z = (t, e = "default") => {
-  q.set(e, R(t));
-}, f = (t = "default") => {
-  const e = q.get(t);
+const P = "default", f = /* @__PURE__ */ new Map(), N = (t, e = P) => {
+  f.set(e, x(t));
+}, w = (t = P) => {
+  const e = f.get(t);
   if (!e) throw new Error(`Requestor实例 ${t} 未注册`);
   return e;
 };
-class x {
+class E {
   // 是否存在
   has(e) {
     return !!localStorage.getItem(e);
@@ -82,7 +82,7 @@ class x {
     localStorage.clear();
   }
 }
-const M = new x(), T = /* @__PURE__ */ new Map(), v = (t) => t ? M : T, j = () => {
+const T = new E(), M = /* @__PURE__ */ new Map(), v = (t) => t ? T : M, j = () => {
   const t = /* @__PURE__ */ new Map();
   return {
     getPromise: (o) => t.get(o),
@@ -96,51 +96,51 @@ const M = new x(), T = /* @__PURE__ */ new Map(), v = (t) => t ? M : T, j = () =
       t.clear();
     }
   };
-}, E = {
+}, I = {
   key: (t) => t.url,
   persist: !1,
   cacheTime: 1 / 0
-}, P = (t, e) => ({
+}, C = (t, e) => ({
   value: t,
   expiresAt: Date.now() + e
-}), I = (t) => Date.now() > t.expiresAt, w = (t = {}) => {
-  const e = { ...E, ...t }, r = v(e.persist), { getPromise: s, setPromise: a, delPromise: o } = j(), i = {
+}), O = (t) => Date.now() > t.expiresAt, R = (t = {}) => {
+  const e = { ...I, ...t }, r = v(e.persist), { getPromise: s, setPromise: a, delPromise: o } = j(), i = {
     get(d, c) {
       return (...l) => {
-        const h = y[c](...l), n = e.key(h), g = s(n);
-        if (g)
-          return console.log(`===> 已存在该请求: ${n}`), g;
+        const h = y[c](...l), n = e.key(h), q = s(n);
+        if (q)
+          return console.log(`===> 已存在该请求: ${n}`), q;
         const p = r.get(n);
-        if (p && !I(p))
+        if (p && !O(p))
           return p.value;
         {
-          const C = Reflect.apply(d[c], d, l).then((u) => (typeof e.cacheTime == "number" ? r.set(n, P(u, e.cacheTime)) : r.set(
+          const g = Reflect.apply(d[c], d, l).then((u) => (typeof e.cacheTime == "number" ? r.set(n, C(u, e.cacheTime)) : r.set(
             n,
-            P(
+            C(
               u,
               e.cacheTime({ config: h, response: u })
             )
           ), console.log("===>cache", "成功", n, u), u)).finally(() => {
             o(n);
           });
-          return a(n, C), C;
+          return a(n, g), g;
         }
       };
     }
   };
-  return new Proxy(f(), i);
-}, O = (t) => {
+  return new Proxy(w(), i);
+}, k = (t) => {
   const { method: e, url: r, params: s, data: a } = t;
   return [e, r, JSON.stringify(s), JSON.stringify(a)].join("|");
-}, k = (t) => w({
-  key: (e) => t ? t(e) : O(e),
+}, A = (t) => R({
+  key: (e) => t ? t(e) : k(e),
   persist: !1
-}), J = {
+}), D = {
   retries: 3,
   delay: 1e3,
   retryCondition: () => !0
-}, N = (t = {}) => {
-  const { retries: e, delay: r, retryCondition: s } = { ...J, ...t }, a = {
+}, J = (t = {}) => {
+  const { retries: e, delay: r, retryCondition: s } = { ...D, ...t }, a = {
     get(o, i) {
       return (...d) => {
         let c = 0;
@@ -158,14 +158,14 @@ const M = new x(), T = /* @__PURE__ */ new Map(), v = (t) => t ? M : T, j = () =
       };
     }
   };
-  return new Proxy(f(), a);
-}, A = {
-  createCacheRequestor: w,
-  createIdempotencyRequestor: k,
-  createRetryRequestor: N
+  return new Proxy(w(), a);
+}, z = {
+  cacheRequestor: R,
+  idempotencyRequestor: A,
+  retryRequestor: J
 };
 export {
-  A as extendRequestor,
-  z as inject,
-  f as useRequestor
+  N as inject,
+  z as requestExtender,
+  w as useRequestor
 };

package/dist/index.umd.cjs

@@ -1 +1 @@
-(function(a,i){typeof exports=="object"&&typeof module<"u"?i(exports):typeof define=="function"&&define.amd?define(["exports"],i):(a=typeof globalThis<"u"?globalThis:a||self,i(a["net-vert/core"]={}))})(this,function(a){"use strict";const i={get:(t,e)=>({url:t,method:"get",...e,params:e==null?void 0:e.params}),post:(t,e,r)=>({url:t,method:"post",data:e,headers:{"Content-Type":"application/json",...r==null?void 0:r.headers},...r}),delete:(t,e)=>({url:t,method:"delete",...e}),put:(t,e,r)=>({url:t,method:"put",data:e,headers:{"Content-Type":"application/json",...r==null?void 0:r.headers},...r}),request:t=>t};function w(t){const e={};return Object.keys(i).forEach(r=>{e[r]=(...o)=>{const c=i[r](...o);return t(c)}}),{...e,request:t}}const q=new Map,T=(t,e="default")=>{q.set(e,w(t))},y=(t="default")=>{const e=q.get(t);if(!e)throw new Error(`Requestor实例 ${t} 未注册`);return e};class j{has(e){return!!localStorage.getItem(e)}get(e){const r=localStorage.getItem(e);if(r)try{return JSON.parse(r)}catch(o){console.error("Error parsing cached data",o);return}}set(e,r){try{const o=JSON.stringify(r);localStorage.setItem(e,o)}catch(o){console.error("Error saving data to localStorage",o)}return r}delete(e){localStorage.removeItem(e)}clear(){localStorage.clear()}}const v=new j,x=new Map,M=t=>t?v:x,O=()=>{const t=new Map;return{getPromise:s=>t.get(s),setPromise:(s,l)=>{t.set(s,l)},delPromise:s=>{t.delete(s)},clearCache:()=>{t.clear()}}},E={key:t=>t.url,persist:!1,cacheTime:1/0},P=(t,e)=>({value:t,expiresAt:Date.now()+e}),I=t=>Date.now()>t.expiresAt,C=(t={})=>{const e={...E,...t},r=M(e.persist),{getPromise:o,setPromise:c,delPromise:s}=O(),l={get(m,u){return(...d)=>{const p=i[u](...d),n=e.key(p),S=o(n);if(S)return console.log(`===> 已存在该请求: ${n}`),S;const g=r.get(n);if(g&&!I(g))return g.value;{const R=Reflect.apply(m[u],m,d).then(h=>(typeof e.cacheTime=="number"?r.set(n,P(h,e.cacheTime)):r.set(n,P(h,e.cacheTime({config:p,response:h}))),console.log("===>cache","成功",n,h),h)).finally(()=>{s(n)});return c(n,R),R}}}};return new Proxy(y(),l)},b=t=>{const{method:e,url:r,params:o,data:c}=t;return[e,r,JSON.stringify(o),JSON.stringify(c)].join("|")},k=t=>C({key:e=>t?t(e):b(e),persist:!1}),J={retries:3,delay:1e3,retryCondition:()=>!0},N={createCacheRequestor:C,createIdempotencyRequestor:k,createRetryRequestor:(t={})=>{const{retries:e,delay:r,retryCondition:o}={...J,...t},c={get(s,l){return(...m)=>{let u=0;const f=()=>Reflect.apply(s[l],s,m).catch(d=>{if(u<e&&o(d)){u++;const p=typeof r=="function"?r(u):r;return new Promise(n=>{setTimeout(()=>n(f()),p)})}return Promise.reject(d)});return f()}}};return new Proxy(y(),c)}};a.extendRequestor=N,a.inject=T,a.useRequestor=y,Object.defineProperty(a,Symbol.toStringTag,{value:"Module"})});
+(function(c,i){typeof exports=="object"&&typeof module<"u"?i(exports):typeof define=="function"&&define.amd?define(["exports"],i):(c=typeof globalThis<"u"?globalThis:c||self,i(c["net-vert/core"]={}))})(this,function(c){"use strict";const i={get:(t,e)=>({url:t,method:"get",...e,params:e==null?void 0:e.params}),post:(t,e,r)=>({url:t,method:"post",data:e,headers:{"Content-Type":"application/json",...r==null?void 0:r.headers},...r}),delete:(t,e)=>({url:t,method:"delete",...e}),put:(t,e,r)=>({url:t,method:"put",data:e,headers:{"Content-Type":"application/json",...r==null?void 0:r.headers},...r}),request:t=>t};function T(t){const e={};return Object.keys(i).forEach(r=>{e[r]=(...o)=>{const a=i[r](...o);return t(a)}}),{...e,request:t}}const g="default",P=new Map,j=(t,e=g)=>{P.set(e,T(t))},y=(t=g)=>{const e=P.get(t);if(!e)throw new Error(`Requestor实例 ${t} 未注册`);return e};class v{has(e){return!!localStorage.getItem(e)}get(e){const r=localStorage.getItem(e);if(r)try{return JSON.parse(r)}catch(o){console.error("Error parsing cached data",o);return}}set(e,r){try{const o=JSON.stringify(r);localStorage.setItem(e,o)}catch(o){console.error("Error saving data to localStorage",o)}return r}delete(e){localStorage.removeItem(e)}clear(){localStorage.clear()}}const x=new v,E=new Map,M=t=>t?x:E,O=()=>{const t=new Map;return{getPromise:s=>t.get(s),setPromise:(s,l)=>{t.set(s,l)},delPromise:s=>{t.delete(s)},clearCache:()=>{t.clear()}}},I={key:t=>t.url,persist:!1,cacheTime:1/0},C=(t,e)=>({value:t,expiresAt:Date.now()+e}),b=t=>Date.now()>t.expiresAt,R=(t={})=>{const e={...I,...t},r=M(e.persist),{getPromise:o,setPromise:a,delPromise:s}=O(),l={get(m,u){return(...d)=>{const p=i[u](...d),n=e.key(p),S=o(n);if(S)return console.log(`===> 已存在该请求: ${n}`),S;const q=r.get(n);if(q&&!b(q))return q.value;{const w=Reflect.apply(m[u],m,d).then(h=>(typeof e.cacheTime=="number"?r.set(n,C(h,e.cacheTime)):r.set(n,C(h,e.cacheTime({config:p,response:h}))),console.log("===>cache","成功",n,h),h)).finally(()=>{s(n)});return a(n,w),w}}}};return new Proxy(y(),l)},k=t=>{const{method:e,url:r,params:o,data:a}=t;return[e,r,JSON.stringify(o),JSON.stringify(a)].join("|")},A=t=>R({key:e=>t?t(e):k(e),persist:!1}),D={retries:3,delay:1e3,retryCondition:()=>!0},J={cacheRequestor:R,idempotencyRequestor:A,retryRequestor:(t={})=>{const{retries:e,delay:r,retryCondition:o}={...D,...t},a={get(s,l){return(...m)=>{let u=0;const f=()=>Reflect.apply(s[l],s,m).catch(d=>{if(u<e&&o(d)){u++;const p=typeof r=="function"?r(u):r;return new Promise(n=>{setTimeout(()=>n(f()),p)})}return Promise.reject(d)});return f()}}};return new Proxy(y(),a)}};c.inject=j,c.requestExtender=J,c.useRequestor=y,Object.defineProperty(c,Symbol.toStringTag,{value:"Module"})});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@net-vert/core",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "description": "Dependency Inversion Network Library with Type-Safe Injection.",
   "main": "dist/index",
   "type": "module",