rxtutils 1.1.4-beta.9 → 1.1.6

package/README.md

@@ -12,6 +12,12 @@ yarn add rxtutils
 pnpm add rxtutils
 ```
 
+也支持按需导入子模块（如 `rxtutils/cache`, `rxtutils/hooks` 等）。
+
+### ⚠️ 环境要求
+
+本库的构建目标为 **ES2020**。如果在低版本环境中使用，请确保配置了相应的 Polyfill 或构建转译。
+
 ## 🚀 功能特性
 
 - **缓存管理** - 支持内存、localStorage、sessionStorage 和 IndexedDB 多种存储方式
@@ -67,7 +73,7 @@ const customCache = new Cache<{ id: number; name: string }, any>(
   'customCache',
   300,
   'customDB',
-  (prev, next) => prev.id === next.id // 只比较 id 字段
+  (prev, next) => prev.id === next.id, // 只比较 id 字段
 );
 ```
 
@@ -84,13 +90,13 @@ import { createBaseRequest } from 'rxtutils';
 const request = createBaseRequest({
   baseURL: 'https://api.example.com',
   throwError: true,
-  defaultMessageShower: (message) => console.log(message)
+  defaultMessageShower: (message) => console.log(message),
 });
 
 // 创建具体请求
 const getUserInfo = request<{ id: number }, { name: string; email: string }>({
   method: 'GET',
-  url: '/user/:id'
+  url: '/user/:id',
 });
 
 // 发送请求
@@ -107,13 +113,13 @@ const request = createBaseRequest({
     '401': '未授权，请重新登录',
     '500': (code, data, res) => ({
       replaceResData: { error: '服务器内部错误' },
-      throwError: false
-    })
+      throwError: false,
+    }),
   },
   httpErrorCodeMap: {
     404: '资源不存在',
-    500: '服务器错误'
-  }
+    500: '服务器错误',
+  },
 });
 ```
 
@@ -126,7 +132,7 @@ const request = createBaseRequest({
   cacheData: true,
   cacheDataInStorage: 'localStorage',
   cacheDataKey: 'api-cache',
-  cacheTime: 300
+  cacheTime: 300,
 });
 
 // 第一次请求会从服务器获取数据
@@ -158,7 +164,7 @@ const userStore = createStateStore({
 // 在组件中使用
 function UserComponent() {
   const [user, setUser] = userStore.use();
-  
+
   const handleLogin = () => {
     setUser({
       name: 'John Doe',
@@ -166,7 +172,7 @@ function UserComponent() {
       isLoggedIn: true
     });
   };
-  
+
   return (
     <div>
       <p>用户名: {user.name}</p>
@@ -274,12 +280,10 @@ console.log(allErrors); // 返回所有验证错误
 import { BaseValidator } from 'rxtutils';
 
 // 创建自定义验证装饰器
-const VCustom = BaseValidator.decoratorCreator(
-  (val) => {
-    // 自定义验证逻辑
-    return typeof val === 'string' && val.startsWith('custom-');
-  }
-);
+const VCustom = BaseValidator.decoratorCreator((val) => {
+  // 自定义验证逻辑
+  return typeof val === 'string' && val.startsWith('custom-');
+});
 
 // 使用自定义验证装饰器
 class Product extends BaseValidator {
@@ -329,7 +333,7 @@ form.password = '123456';
 
 // 验证单个字段的所有规则
 const usernameErrors = form.validate('username', true);
-console.log(usernameErrors); 
+console.log(usernameErrors);
 // [{ status: false, message: '用户名长度不能少于3位' }]
 
 // 验证所有字段，每个字段遇到第一个错误就停止
@@ -379,7 +383,7 @@ const useUserGetters = createStoreGetterMemo(userStore, getters, getterNameMaps)
 
 function UserProfile() {
   const { fullName, isAdult, displayName } = useUserGetters();
-  
+
   return (
     <div>
       <h1>{fullName}</h1>
@@ -394,26 +398,26 @@ function UserProfile() {
 
 ### Cache 配置
 
-| 参数 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| `storageType` | `'sessionStorage' \| 'localStorage' \| 'indexedDB'` | `undefined` | 存储类型 |
-| `cacheKey` | `string` | `undefined` | 缓存键名 |
-| `cacheTime` | `number` | `60` | 缓存时间（秒） |
-| `indexDBName` | `string` | `'__apiCacheDatabase__'` | IndexedDB 数据库名称 |
-| `cacheKeyEquals` | `function` | `defaultEquals` | 缓存键比较函数 |
+| 参数             | 类型                                                | 默认值                   | 说明                 |
+| ---------------- | --------------------------------------------------- | ------------------------ | -------------------- |
+| `storageType`    | `'sessionStorage' \| 'localStorage' \| 'indexedDB'` | `undefined`              | 存储类型             |
+| `cacheKey`       | `string`                                            | `undefined`              | 缓存键名             |
+| `cacheTime`      | `number`                                            | `60`                     | 缓存时间（秒）       |
+| `indexDBName`    | `string`                                            | `'__apiCacheDatabase__'` | IndexedDB 数据库名称 |
+| `cacheKeyEquals` | `function`                                          | `defaultEquals`          | 缓存键比较函数       |
 
 ### Request 配置
 
-| 参数 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| `baseURL` | `string` | `''` | 请求基础URL |
-| `throwError` | `boolean` | `true` | 是否抛出错误 |
-| `enableCache` | `boolean` | `false` | 是否启用缓存 |
-| `cacheData` | `boolean` | `false` | 是否缓存数据 |
-| `cacheTime` | `number` | `60` | 缓存时间（秒） |
-| `cacheDataInStorage` | `StorageType` | `undefined` | 缓存存储类型 |
-| `errorCodePath` | `string` | `'code'` | 错误码路径 |
-| `successCodes` | `string[]` | `['0', '200']` | 成功状态码 |
+| 参数                 | 类型          | 默认值         | 说明           |
+| -------------------- | ------------- | -------------- | -------------- |
+| `baseURL`            | `string`      | `''`           | 请求基础URL    |
+| `throwError`         | `boolean`     | `true`         | 是否抛出错误   |
+| `enableCache`        | `boolean`     | `false`        | 是否启用缓存   |
+| `cacheData`          | `boolean`     | `false`        | 是否缓存数据   |
+| `cacheTime`          | `number`      | `60`           | 缓存时间（秒） |
+| `cacheDataInStorage` | `StorageType` | `undefined`    | 缓存存储类型   |
+| `errorCodePath`      | `string`      | `'code'`       | 错误码路径     |
+| `successCodes`       | `string[]`    | `['0', '200']` | 成功状态码     |
 
 ## 📝 类型定义
 
@@ -487,12 +491,12 @@ const apiRequest = createBaseRequest({
   enableCache: true,
   cacheData: true,
   cacheDataInStorage: 'localStorage',
-  cacheTime: 300
+  cacheTime: 300,
 });
 
 const getProductList = apiRequest<{ page: number }, { products: Product[] }>({
   method: 'GET',
-  url: '/products'
+  url: '/products',
 });
 ```
 
@@ -503,19 +507,23 @@ const getProductList = apiRequest<{ page: number }, { products: Product[] }>({
 const userStore = createStateStore({
   user: null,
   permissions: [],
-  theme: 'light'
+  theme: 'light',
 });
 
 // 创建用户相关的计算属性
-const userGetters = createStoreGetter(userStore, {
-  isLoggedIn: (state) => !!state.user,
-  canEdit: (state) => state.permissions.includes('edit'),
-  isDarkTheme: (state) => state.theme === 'dark'
-}, {
-  isLoggedIn: 'isLoggedIn',
-  canEdit: 'canEdit',
-  isDarkTheme: 'isDarkTheme'
-});
+const userGetters = createStoreGetter(
+  userStore,
+  {
+    isLoggedIn: (state) => !!state.user,
+    canEdit: (state) => state.permissions.includes('edit'),
+    isDarkTheme: (state) => state.theme === 'dark',
+  },
+  {
+    isLoggedIn: 'isLoggedIn',
+    canEdit: 'canEdit',
+    isDarkTheme: 'isDarkTheme',
+  },
+);
 ```
 
 ### 3. 表单数据缓存
@@ -531,9 +539,69 @@ formCache.setCache('user-form', formData);
 const savedData = formCache.getCache('user-form');
 ```
 
+## 🛠 开发
+
+本项目包含一个 playground 用于调试和预览。
+
+```bash
+# 安装依赖
+pnpm install --frozen-lockfile
+
+# 启动开发服务器
+pnpm dev
+
+# 运行测试
+pnpm test
+
+# 代码检查
+pnpm lint
+
+# 代码格式化
+pnpm format
+
+# 类型检查
+pnpm typecheck
+
+# 构建
+pnpm build
+```
+
 ## 🤝 贡献
 
-欢迎提交 Issue 和 Pull Request 来帮助改进这个项目。
+欢迎提交 Issue 和 Pull Request 来帮助改进这个项目。提交前建议先执行：
+
+```bash
+pnpm format:check
+pnpm lint
+pnpm typecheck
+pnpm test
+pnpm build
+```
+
+## 🔧 Git Alias（可选）
+
+如果你习惯使用 Git alias，建议配置到个人环境（`~/.gitconfig`），而不是放在仓库中。
+
+方式一：逐条命令配置
+
+```bash
+git config --global alias.cm commit
+git config --global alias.cc checkout
+git config --global alias.bc branch
+git config --global alias.df diff
+git config --global alias.lg log
+```
+
+方式二：直接追加配置片段到 `~/.gitconfig`
+
+```ini
+[alias]
+  cm = commit
+  cc = checkout
+  bc = branch
+  df = diff
+  lg = log
+```
 
 ## 📄 许可证
 
@@ -544,4 +612,4 @@ MIT License
 - [TypeScript](https://www.typescriptlang.org/)
 - [React](https://reactjs.org/)
 - [Axios](https://axios-http.com/)
-- [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API)
+- [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API)

package/cjs/_utils/defaultEquals.cjs

@@ -1,21 +1,6 @@
-'use strict';
-
-/**
- * 默认的相等性比较函数
- * 通过将两个值序列化为 JSON 字符串来比较它们是否相等
- *
- * @template Param 比较值的类型，默认为 any
- * @param prev 前一个值
- * @param next 后一个值
- * @returns {boolean} 如果两个值相等则返回 true，否则返回 false
- *
- * @remarks
- * - 这个函数通过 JSON.stringify 进行比较，适用于大多数简单的数据结构
- * - 不适用于包含函数、undefined、Symbol 等无法序列化的值
- * - 对于循环引用的对象会抛出错误
- */
+"use strict";
+Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toStringTag]: { value: "Module" } });
 function defaultEquals(prev, next) {
-    return JSON.stringify(prev) === JSON.stringify(next);
+  return JSON.stringify(prev) === JSON.stringify(next);
 }
-
-module.exports = defaultEquals;
+exports.default = defaultEquals;

package/cjs/cache/index.cjs

@@ -1,170 +1,137 @@
-'use strict';
-
-Object.defineProperty(exports, '__esModule', { value: true });
-
-var tslib = require('tslib');
-var moment = require('moment');
-var indexDB = require('./indexDB.cjs');
-var defaultEquals = require('../_utils/defaultEquals.cjs');
-
-/** 存储类型映射表 */
-var StorageMap = {
-    localStorage: localStorage,
-    sessionStorage: sessionStorage,
+"use strict";
+Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toStringTag]: { value: "Module" } });
+const dateFns = require("date-fns");
+const indexDB = require("./indexDB.cjs");
+const defaultEquals = require("../_utils/defaultEquals.cjs");
+const StorageMap = {
+  localStorage,
+  sessionStorage
 };
-/**
- * 缓存类
- * @template Param 缓存参数类型
- * @template Data 缓存数据类型
- */
-var Cache = /** @class */ (function () {
-    /**
-     * 构造函数
-     * @param cacheType 存储类型
-     * @param cacheKey 缓存键名
-     * @param cacheTime 缓存时间（秒）
-     * @param indexDBName IndexedDB 数据库名称，默认值为 '__apiCacheDatabase__'
-     * @param cacheKeyEquals 缓存键比较函数，默认使用 defaultEquals
-     */
-    function Cache(cacheType, cacheKey, cacheTime, indexDBName, cacheKeyEquals) {
-        if (indexDBName === void 0) { indexDBName = "__apiCacheDatabase__"; }
-        if (cacheKeyEquals === void 0) { cacheKeyEquals = defaultEquals; }
-        /** 内存中的缓存数组 */
-        this.cache = [];
-        this.cacheOptions = {
-            storageType: cacheType,
-            cacheKey: cacheKey,
-            cacheTime: cacheTime,
-            indexDBName: indexDBName,
-            cacheKeyEquals: cacheKeyEquals,
-        };
-        if (cacheType === "indexedDB") {
-            this.storage = new indexDB.IndexedDBStorage(indexDBName, "cacheStore");
-        }
-        else if (typeof cacheType === "string") {
-            this.storage = StorageMap[cacheType];
-        }
-        this._init();
-    }
-    /**
-     * 初始化缓存
-     * 从存储中加载已保存的缓存数据，并进行解析和过期处理
-     * @private
-     */
-    Cache.prototype._init = function () {
-        return tslib.__awaiter(this, void 0, void 0, function () {
-            var _a, cacheType, cacheKey, _b, _c, _d;
-            return tslib.__generator(this, function (_e) {
-                switch (_e.label) {
-                    case 0:
-                        _a = this.cacheOptions, cacheType = _a.storageType, cacheKey = _a.cacheKey;
-                        if (!(this.storage instanceof indexDB.IndexedDBStorage)) return [3 /*break*/, 2];
-                        _b = this;
-                        _d = (_c = JSON).parse;
-                        return [4 /*yield*/, this.storage.getItem(cacheKey)];
-                    case 1:
-                        _b.cache = _d.apply(_c, [(_e.sent()) || "[]"]);
-                        return [3 /*break*/, 3];
-                    case 2:
-                        if (this.storage instanceof Storage) {
-                            this.storage = StorageMap[cacheType];
-                            if (this.storage) {
-                                if (typeof cacheKey === "string") {
-                                    try {
-                                        this.cache = JSON.parse(this.storage.getItem(cacheKey) || "[]");
-                                    }
-                                    catch (e) {
-                                        this.cache = [];
-                                        console.error("\u7F13\u5B58\u6570\u636E\u89E3\u6790\u5931\u8D25\uFF0Ckey:".concat(cacheKey));
-                                    }
-                                }
-                            }
-                        }
-                        _e.label = 3;
-                    case 3:
-                        this._filterExpired();
-                        this._saveToStorage();
-                        return [2 /*return*/];
-                }
-            });
-        });
-    };
-    /**
-     * 过滤掉已过期的缓存项
-     * 通过比较当前时间和过期时间，移除过期的缓存项
-     * @private
-     */
-    Cache.prototype._filterExpired = function () {
-        var newCache = this.cache.filter(function (item) {
-            return moment(item.expireTime).isAfter(moment());
-        });
-        this.cache = newCache;
+class Cache {
+  /**
+   * 构造函数
+   * @param cacheType 存储类型
+   * @param cacheKey 缓存键名
+   * @param cacheTime 缓存时间（秒）
+   * @param indexDBName IndexedDB 数据库名称，默认值为 '__apiCacheDatabase__'
+   * @param cacheKeyEquals 缓存键比较函数，默认使用 defaultEquals
+   */
+  constructor(cacheType, cacheKey, cacheTime, indexDBName = "__apiCacheDatabase__", cacheKeyEquals = defaultEquals.default) {
+    this.cache = [];
+    this.cacheOptions = {
+      storageType: cacheType,
+      cacheKey,
+      cacheTime,
+      indexDBName,
+      cacheKeyEquals
     };
-    /**
-     * 将当前缓存数据保存到存储中
-     * 如果设置了缓存键名且存储实例存在，则将缓存数据序列化后保存
-     * @private
-     */
-    Cache.prototype._saveToStorage = function () {
-        if (this.storage) {
-            if (typeof this.cacheOptions.cacheKey === "string") {
-                this.storage.setItem(this.cacheOptions.cacheKey, JSON.stringify(this.cache));
-            }
-        }
-    };
-    /**
-     * 设置缓存数据
-     * @param params 缓存的参数
-     * @param data 要缓存的数据
-     * @param cacheOptions 可选的缓存配置，可以覆盖默认的缓存时间
-     */
-    Cache.prototype.setCache = function (params, data, cacheOptions) {
-        var _a = tslib.__assign(tslib.__assign({}, this.cacheOptions), cacheOptions), cacheTime = _a.cacheTime, _b = _a.cacheKeyEquals, cacheKeyEquals = _b === void 0 ? defaultEquals : _b;
-        var cacheItemIndex = this.cache.findIndex(function (item) {
-            return cacheKeyEquals(item.params, params);
-        });
-        if (cacheItemIndex > -1) {
-            this.cache.splice(cacheItemIndex, 1);
-        }
-        this.cache.push({
-            params: params,
-            data: data,
-            expireTime: moment().add(cacheTime, "seconds").toJSON(),
-        });
-        this._saveToStorage();
-    };
-    /**
-     * 获取缓存数据
-     * @param params 查询参数
-     * @returns 如果找到有效的缓存数据则返回数据，否则返回 null
-     */
-    Cache.prototype.getCache = function (params) {
-        var _this = this;
-        var itemIndex = this.cache.findIndex(function (item) {
-            return _this.cacheOptions.cacheKeyEquals(item.params, params);
-        });
-        var item = this.cache[itemIndex];
-        if (item) {
-            if (moment(item.expireTime).isAfter(moment())) {
-                return item.data;
-            }
-            else {
-                this.cache.splice(itemIndex, 1);
-                this._saveToStorage();
-            }
+    if (cacheType === "indexedDB") {
+      this.storage = new indexDB.IndexedDBStorage(indexDBName, "cacheStore");
+    } else if (typeof cacheType === "string") {
+      this.storage = StorageMap[cacheType];
+    }
+    this._init();
+  }
+  /**
+   * 初始化缓存
+   * 从存储中加载已保存的缓存数据，并进行解析和过期处理
+   * @private
+   */
+  async _init() {
+    const { storageType: cacheType, cacheKey } = this.cacheOptions;
+    if (this.storage instanceof indexDB.IndexedDBStorage) {
+      this.cache = JSON.parse(await this.storage.getItem(cacheKey) || "[]");
+    } else if (this.storage instanceof Storage) {
+      this.storage = StorageMap[cacheType];
+      if (this.storage) {
+        if (typeof cacheKey === "string") {
+          try {
+            this.cache = JSON.parse(this.storage.getItem(cacheKey) || "[]");
+          } catch (e) {
+            this.cache = [];
+            console.error(`缓存数据解析失败，key:${cacheKey}`);
+          }
         }
-        return null;
+      }
+    }
+    this._filterExpired();
+    this._saveToStorage();
+  }
+  /**
+   * 过滤掉已过期的缓存项
+   * 通过比较当前时间和过期时间，移除过期的缓存项
+   * @private
+   */
+  _filterExpired() {
+    const newCache = this.cache.filter((item) => {
+      return dateFns.isAfter(dateFns.parseISO(item.expireTime), /* @__PURE__ */ new Date());
+    });
+    this.cache = newCache;
+  }
+  /**
+   * 将当前缓存数据保存到存储中
+   * 如果设置了缓存键名且存储实例存在，则将缓存数据序列化后保存
+   * @private
+   */
+  _saveToStorage() {
+    if (this.storage) {
+      if (typeof this.cacheOptions.cacheKey === "string") {
+        this.storage.setItem(this.cacheOptions.cacheKey, JSON.stringify(this.cache));
+      }
+    }
+  }
+  /**
+   * 设置缓存数据
+   * @param params 缓存的参数
+   * @param data 要缓存的数据
+   * @param cacheOptions 可选的缓存配置，可以覆盖默认的缓存时间
+   */
+  setCache(params, data, cacheOptions) {
+    const { cacheTime, cacheKeyEquals = defaultEquals.default } = {
+      ...this.cacheOptions,
+      ...cacheOptions
     };
-    /**
-     * 清空所有缓存数据
-     * 清空内存中的缓存数组并同步到存储中
-     */
-    Cache.prototype.clear = function () {
-        this.cache = [];
+    const cacheItemIndex = this.cache.findIndex((item) => {
+      return cacheKeyEquals(item.params, params);
+    });
+    if (cacheItemIndex > -1) {
+      this.cache.splice(cacheItemIndex, 1);
+    }
+    this.cache.push({
+      params,
+      data,
+      expireTime: dateFns.addSeconds(/* @__PURE__ */ new Date(), cacheTime ?? 0).toISOString()
+    });
+    this._saveToStorage();
+  }
+  /**
+   * 获取缓存数据
+   * @param params 查询参数
+   * @returns 如果找到有效的缓存数据则返回数据，否则返回 null
+   */
+  getCache(params) {
+    const itemIndex = this.cache.findIndex((item2) => {
+      return this.cacheOptions.cacheKeyEquals(item2.params, params);
+    });
+    const item = this.cache[itemIndex];
+    if (item) {
+      if (dateFns.isAfter(dateFns.parseISO(item.expireTime), /* @__PURE__ */ new Date())) {
+        return item.data;
+      } else {
+        this.cache.splice(itemIndex, 1);
         this._saveToStorage();
-    };
-    return Cache;
-}());
-
+      }
+    }
+    return null;
+  }
+  /**
+   * 清空所有缓存数据
+   * 清空内存中的缓存数组并同步到存储中
+   */
+  clear() {
+    this.cache = [];
+    this._saveToStorage();
+  }
+}
 exports.StorageMap = StorageMap;
 exports.default = Cache;