utils-uniapp 1.1.8 → 1.1.9

package/lib/cache/index.d.ts

@@ -5,6 +5,7 @@
  */
 type StorageMode = 'session' | 'local';
 
+
 /**
  * 底层存储适配器接口，抹平uni‑storage与sessionStorage API差异
  */
@@ -41,6 +42,7 @@ interface IStorageAdapter {
   clear(): void;
 }
 
+
 /**
  * StorageCache实例构造配置项
  */
@@ -51,11 +53,18 @@ interface StorageCacheOptions {
   version?: string | number;
   /** 实例隔离前缀，内部自动追加下划线分隔，默认空字符串 */
   prefix?: string;
+  /**
+   * 实例默认过期秒数；set不传expire时使用该值
+   * <=0代表永不过期，默认0
+   */
+  defaultExpire?: number;
 }
 
+
 /**
  * 多端缓存工具类
  * 特性：过期控制、版本校验、实例key隔离前缀；适配uni‑app、H5‑sessionStorage
+ * 优先级说明：set传入expire > 实例defaultExpire；仅不传参(undefined)才使用实例默认配置
  * 注意：
  * 1. 业务传入key为业务key，内部自动拼接实例prefix
  * 2. clear仅删除本实例前缀key，无prefix时不执行删除
@@ -72,7 +81,7 @@ export declare class StorageCache {
    * 设置缓存，支持过期
    * @param key 业务缓存key
    * @param data 缓存数据
-   * @param expire 过期时间，单位秒；<=0永不过期，默认3600
+   * @param expire 过期时间，单位秒；不传使用实例defaultExpire；<=0永不过期
    * @returns true成功，false异常失败
    */
   set(key: string, data: any, expire?: number): boolean;
@@ -113,16 +122,19 @@ export declare class StorageCache {
   removeByPrefix(prefix: string): boolean;
 }
 
+
 /**
- * 全局默认local缓存实例，无实例隔离前缀，直接操作原始key
+ * 全局默认local缓存实例，无实例隔离前缀，直接操作原始key，默认永不过期
  * @type {StorageCache}
  */
 export declare const localCache: StorageCache;
 
+
 /**
- * 全局默认session缓存实例，无实例隔离前缀；小程序/App自动降级为local
+ * 全局默认session缓存实例，无实例隔离前缀；小程序/App自动降级为local，默认永不过期
  * @type {StorageCache}
  */
 export declare const sessionCache: StorageCache;
 
+
 export default StorageCache;

package/lib/cache/index.js

@@ -1 +1 @@
-"use strict";var w=(i,t,r)=>{if(!t.has(i))throw TypeError("Cannot "+r)};var n=(i,t,r)=>(w(i,t,"read from private field"),r?r.call(i):t.get(i)),g=(i,t,r)=>{if(t.has(i))throw TypeError("Cannot add the same private member more than once");t instanceof WeakSet?t.add(i):t.set(i,r)},y=(i,t,r,s)=>(w(i,t,"write to private field"),s?s.call(i,r):t.set(i,r),r);var l=(i,t,r)=>(w(i,t,"access private method"),r);Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});var o,h,c,d,p,u,m;const v=class v{constructor(){g(this,u);g(this,o,void 0);g(this,h,void 0);g(this,c,void 0);var a;let t=arguments.length>0&&arguments[0]!==void 0?arguments[0]:{};const{mode:r="local",version:s="v1",prefix:e=""}=t;y(this,o,l(a=v,d,p).call(a,r)),y(this,h,String(s)),y(this,c,e?e+"_":""),Object.seal(this)}set(t,r){let s=arguments.length>2&&arguments[2]!==void 0?arguments[2]:3600;try{let e=Number(s);Number.isFinite(e)||(e=0);const a=e>0?Math.round(e)*1e3:e,S=l(this,u,m).call(this,t);return n(this,o).set(S,{time:Date.now(),expire:a,version:n(this,h),data:r}),!0}catch(e){return console.error(`设置缓存[${t}]失败：`,e),!1}}get(t){let r=arguments.length>1&&arguments[1]!==void 0?arguments[1]:null;try{const s=l(this,u,m).call(this,t),e=n(this,o).get(s);return!e||typeof e!="object"||Array.isArray(e)||!("time"in e)||!("expire"in e)||!("version"in e)?(e&&n(this,o).remove(s),r):e.version!==n(this,h)?(n(this,o).remove(s),r):e.expire>0&&Date.now()-e.time>=e.expire?(n(this,o).remove(s),r):e.data}catch(s){return console.error(`获取缓存[${t}]失败：`,s),r}}renew(t){try{const r=l(this,u,m).call(this,t),s=n(this,o).get(r);if(!s||typeof s!="object"||Array.isArray(s)||!("time"in s)||!("expire"in s)||!("version"in s))return!1;if(s.version!==n(this,h))return n(this,o).remove(r),!1;if(s.expire>0){if(Date.now()-s.time>=s.expire)return n(this,o).remove(r),!1;s.time=Date.now(),n(this,o).set(r,s)}return!0}catch(r){return console.error(`续期缓存[${t}]失败：`,r),!1}}remove(t){try{const r=l(this,u,m).call(this,t);return n(this,o).remove(r),!0}catch(r){return console.error(`删除缓存[${t}]失败：`,r),!1}}clear(){try{return n(this,o).keys().forEach(r=>{n(this,c)&&r.startsWith(n(this,c))&&n(this,o).remove(r)}),!0}catch(t){return console.error("清空实例缓存失败：",t),!1}}removeByPrefix(t){if(!t)return!1;if(!n(this,c))return console.warn("StorageCache: 当前实例无隔离前缀，禁止调用removeByPrefix，避免误删"),!1;try{const r=l(this,u,m).call(this,t);return n(this,o).keys().forEach(e=>{e.startsWith(r)&&n(this,o).remove(e)}),!0}catch(r){return console.error(`按前缀删除缓存[${t}]失败：`,r),!1}}};o=new WeakMap,h=new WeakMap,c=new WeakMap,d=new WeakSet,p=function(){let t=arguments.length>0&&arguments[0]!==void 0?arguments[0]:"local";const r=typeof window<"u"&&window.sessionStorage,s={set(e,a){uni.setStorageSync(e,a)},get(e){return uni.getStorageSync(e)},remove(e){uni.removeStorageSync(e)},keys(){try{return uni.getStorageInfoSync().keys||[]}catch(e){return console.error("uni getStorageInfoSync error",e),[]}},clear(){uni.clearStorageSync()}};return r&&t==="session"?{set(e,a){try{window.sessionStorage.setItem(e,JSON.stringify(a))}catch(S){console.error("sessionStorage set error",S)}},get(e){const a=window.sessionStorage.getItem(e);if(a===null)return null;try{return JSON.parse(a)}catch{return window.sessionStorage.removeItem(e),null}},remove(e){window.sessionStorage.removeItem(e)},keys(){return Object.keys(window.sessionStorage)},clear(){window.sessionStorage.clear()}}:s},u=new WeakSet,m=function(t){return n(this,c)+t},g(v,d);let f=v;const x=new f,I=new f({mode:"session"});exports.StorageCache=f;exports.default=f;exports.localCache=x;exports.sessionCache=I;
+"use strict";var p=(i,r,e)=>{if(!r.has(i))throw TypeError("Cannot "+e)};var n=(i,r,e)=>(p(i,r,"read from private field"),e?e.call(i):r.get(i)),l=(i,r,e)=>{if(r.has(i))throw TypeError("Cannot add the same private member more than once");r instanceof WeakSet?r.add(i):r.set(i,e)},y=(i,r,e,s)=>(p(i,r,"write to private field"),s?s.call(i,e):r.set(i,e),e);var h=(i,r,e)=>(p(i,r,"access private method"),e);Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});var o,f,c,v,S,x,u,m;const w=class w{constructor(){l(this,u);l(this,o,void 0);l(this,f,void 0);l(this,c,void 0);l(this,v,void 0);var g;let r=arguments.length>0&&arguments[0]!==void 0?arguments[0]:{};const{mode:e="local",version:s="v1",prefix:t="",defaultExpire:a=0}=r;y(this,o,h(g=w,S,x).call(g,e)),y(this,f,String(s)),y(this,c,t?t+"_":""),y(this,v,Number(a)),Object.seal(this)}set(r,e,s){try{const t=s!==void 0?s:n(this,v);let a=Number(t);Number.isFinite(a)||(a=0);const g=a>0?Math.round(a)*1e3:a,I=h(this,u,m).call(this,r);return n(this,o).set(I,{time:Date.now(),expire:g,version:n(this,f),data:e}),!0}catch(t){return console.error(`设置缓存[${r}]失败：`,t),!1}}get(r){let e=arguments.length>1&&arguments[1]!==void 0?arguments[1]:null;try{const s=h(this,u,m).call(this,r),t=n(this,o).get(s);return!t||typeof t!="object"||Array.isArray(t)||!("time"in t)||!("expire"in t)||!("version"in t)?(t&&n(this,o).remove(s),e):t.version!==n(this,f)?(n(this,o).remove(s),e):t.expire>0&&Date.now()-t.time>=t.expire?(n(this,o).remove(s),e):t.data}catch(s){return console.error(`获取缓存[${r}]失败：`,s),e}}renew(r){try{const e=h(this,u,m).call(this,r),s=n(this,o).get(e);if(!s||typeof s!="object"||Array.isArray(s)||!("time"in s)||!("expire"in s)||!("version"in s))return!1;if(s.version!==n(this,f))return n(this,o).remove(e),!1;if(s.expire>0){if(Date.now()-s.time>=s.expire)return n(this,o).remove(e),!1;s.time=Date.now(),n(this,o).set(e,s)}return!0}catch(e){return console.error(`续期缓存[${r}]失败：`,e),!1}}remove(r){try{const e=h(this,u,m).call(this,r);return n(this,o).remove(e),!0}catch(e){return console.error(`删除缓存[${r}]失败：`,e),!1}}clear(){try{return n(this,o).keys().forEach(e=>{n(this,c)&&e.startsWith(n(this,c))&&n(this,o).remove(e)}),!0}catch(r){return console.error("清空实例缓存失败：",r),!1}}removeByPrefix(r){if(!r)return!1;if(!n(this,c))return console.warn("StorageCache: 当前实例无隔离前缀，禁止调用removeByPrefix，避免误删"),!1;try{const e=h(this,u,m).call(this,r);return n(this,o).keys().forEach(t=>{t.startsWith(e)&&n(this,o).remove(t)}),!0}catch(e){return console.error(`按前缀删除缓存[${r}]失败：`,e),!1}}};o=new WeakMap,f=new WeakMap,c=new WeakMap,v=new WeakMap,S=new WeakSet,x=function(){let r=arguments.length>0&&arguments[0]!==void 0?arguments[0]:"local";const e=typeof window<"u"&&window.sessionStorage,s={set(t,a){uni.setStorageSync(t,a)},get(t){return uni.getStorageSync(t)},remove(t){uni.removeStorageSync(t)},keys(){try{return uni.getStorageInfoSync().keys||[]}catch(t){return console.error("uni getStorageInfoSync error",t),[]}},clear(){uni.clearStorageSync()}};return e&&r==="session"?{set(t,a){try{window.sessionStorage.setItem(t,JSON.stringify(a))}catch(g){console.error("sessionStorage set error",g)}},get(t){const a=window.sessionStorage.getItem(t);if(a===null)return null;try{return JSON.parse(a)}catch{return window.sessionStorage.removeItem(t),null}},remove(t){window.sessionStorage.removeItem(t)},keys(){return Object.keys(window.sessionStorage)},clear(){window.sessionStorage.clear()}}:s},u=new WeakSet,m=function(r){return n(this,c)+r},l(w,S);let d=w;const b=new d,K=new d({mode:"session"});exports.StorageCache=d;exports.default=d;exports.localCache=b;exports.sessionCache=K;

package/lib/http/index.d.ts

@@ -21,39 +21,86 @@ type UniUploadResult = UniApp.UploadFileSuccessCallbackResult;
 type UniDownloadResult = UniApp.DownloadFileSuccessCallbackResult;
 type UniAnyResult = UniRequestResult | UniUploadResult | UniDownloadResult;
 
+/**
+ * 请求失败载荷
+ */
 export type RequestFailPayload = {
   type: 'fail';
   res: UniApp.GeneralCallbackResult;
 };
 
+/**
+ * 缓存适配器抽象接口，对接外部缓存实现（如前面StorageCache）
+ */
 export interface CacheAdapter {
+  /**
+   * 获取缓存
+   * @param key 缓存key
+   * @returns 缓存值，不存在返回undefined
+   */
   get(key: string): unknown;
+  /**
+   * 设置缓存
+   * @param key 缓存key
+   * @param value 缓存存储内容
+   * @param expire 过期秒数，<=0永不过期
+   */
   set(key: string, value: unknown, expire: number): void;
 }
 
 /**
- * 外部传入缓存配置入参（仅调用方使用）
+ * 外部传入缓存配置入参（仅调用方使用，业务传入）
+ * @description 开启请求缓存 isCache=true 时，必须传入对应 mode 的适配器 localAdapter / sessionAdapter
  */
 export interface CacheConfigInput {
+  /**
+   * 自定义缓存业务key；不填默认由url生成，**不包含请求参数**，同URL不同参数务必手动指定key
+   */
   key?: string;
+  /**
+   * 缓存key前缀，用于业务隔离，会拼接在业务key前面
+   */
   prefix?: string;
+  /**
+   * 缓存存储模式
+   * - local：持久存储
+   * - session：会话存储(H5会话销毁；小程序降级持久)
+   */
   mode?: 'local' | 'session';
+  /**
+   * 缓存过期时间，单位秒；<=0代表永不过期，默认1小时过期
+   */
   expire?: number;
+  /**
+   * local模式对应的缓存适配器实例；mode=local且开启缓存时必填
+   */
   localAdapter?: CacheAdapter | null;
+  /**
+   * session模式对应的缓存适配器实例；mode=session且开启缓存时必填
+   */
   sessionAdapter?: CacheAdapter | null;
 }
 
 /**
  * normalizeOpts 之后内部运行时缓存配置对象
+ * @description adapter 字段由内部派生生成，外部禁止传入、禁止读取使用
  */
 export interface CacheConfig {
-  /** 缓存key；默认仅由url生成，**不包含请求参数**，同URL不同参数需手动指定key */
+  /**
+   * 缓存key；默认仅由url生成，**不包含请求参数**，同URL不同参数需手动指定key
+   */
   key: string;
-  /** 缓存key前缀 */
+  /**
+   * 缓存key前缀
+   */
   prefix: string;
-  /** 缓存模式 */
+  /**
+   * 缓存模式
+   */
   mode: 'local' | 'session';
-  /** 过期时间，单位秒 */
+  /**
+   * 过期时间，单位秒；<=0代表永不过期，默认1小时过期
+   */
   expire: number;
   /**
    * ⚠️ adapter 为内部运行时派生字段，**外部禁止传入、禁止访问**；
@@ -99,23 +146,23 @@ export type UserErrInterceptor = ErrInterceptor | ErrInterceptor[];
  * normalizeOpts标准化之后的请求额外配置对象【内部运行时】
  */
 export interface RequestOptions {
-  /** 是否使用表单编码 */
+  /** 是否使用url‑encoded表单编码 */
   qs: boolean;
-  /** 是否展示错误提示 */
+  /** 是否展示错误toast提示 */
   showError: boolean;
-  /** 是否开启缓存；开启时cacheConfig必须提供对应mode的适配器 */
+  /** 是否开启请求缓存；开启时cacheConfig必须提供对应mode的适配器 */
   isCache: boolean;
   /** 缓存配置；adapter为内部运行时派生字段，外部请勿传入、请勿访问；开启isCache:true，必须传入对应模式的适配器，否则运行时抛出异常 */
   cacheConfig: CacheConfig;
   /** loading提示文字 */
   loadingText: string;
-  /** 是否开启loading */
+  /** 是否开启全局loading弹窗 */
   loading: boolean;
-  /** 请求拦截器 */
+  /** 请求前置拦截器（已合并为单个函数） */
   reqInterceptor: ReqInterceptor;
-  /** 响应拦截器 */
+  /** 响应拦截器（已合并为单个函数） */
   resInterceptor: ResInterceptor;
-  /** 错误拦截器 */
+  /** 错误拦截器（已合并为单个函数） */
   errInterceptor: ErrInterceptor;
   /** 允许扩展自定义字段 */
   [key: string]: unknown;
@@ -127,17 +174,17 @@ export interface RequestOptions {
  * @description isCache 设置为 true 时，cacheConfig 需要传入对应 mode 的适配器 localAdapter / sessionAdapter，否则运行时抛出异常
  */
 export interface UserRequestOpts {
-  /** 是否使用表单编码 */
+  /** 是否使用url‑encoded表单编码 */
   qs?: boolean;
-  /** 是否展示错误提示 */
+  /** 是否展示错误toast提示 */
   showError?: boolean;
-  /** 是否开启缓存；开启时cacheConfig必须提供对应mode的适配器(localAdapter/sessionAdapter) */
+  /** 是否开启请求缓存；开启时cacheConfig必须提供对应mode的适配器(localAdapter/sessionAdapter) */
   isCache?: boolean;
   /** 缓存配置，用户传入部分字段即可；isCache=true必须传入对应mode适配器 */
   cacheConfig?: Partial<CacheConfigInput>;
   /** loading提示文字 */
   loadingText?: string;
-  /** 是否开启loading */
+  /** 是否开启全局loading弹窗 */
   loading?: boolean;
   /** 请求前置拦截器，支持单个函数或函数数组 */
   reqInterceptor?: UserReqInterceptor;
@@ -154,6 +201,7 @@ export interface UserRequestOpts {
  * 注意：当前实现token由请求内部source生成，**不支持外部传入自定义cancelToken**
  */
 export declare const CancelToken: {
+  /** 保存token与uni任务映射 */
   caches: Record<string, UniTask>;
 
   /**
@@ -187,7 +235,6 @@ export declare const CancelToken: {
   source(): { token: string; cancel: () => void };
 };
 
-
 /**
  * 包装uni异步API为Promise
  * @param type uni接口名称 request | uploadFile | downloadFile
@@ -198,24 +245,24 @@ export declare const CancelToken: {
 export declare function promisifyRequest<T = UniAnyResult>(type: 'request' | 'uploadFile' | 'downloadFile', opts: Record<string, unknown>): Promise<T>;
 
 /**
- * 底层展示loading
- * @param {string} title loading提示文字
+ * 底层直接展示loading，不做计数
+ * @param title loading提示文字
  */
 export declare function showLoading(title: string): void;
 
 /**
- * 底层隐藏loading
+ * 底层直接隐藏loading，不做计数
  */
 export declare function hideLoading(): void;
 
 /**
- * 开启loading计数，计数>0时展示loading
+ * 开启loading计数，计数>0时展示loading；多次调用会叠加计数
  * @param [title='加载中...'] loading提示文案
  */
 export declare function startLoading(title?: string): void;
 
 /**
- * 关闭loading计数，计数归0则隐藏loading
+ * 关闭loading计数，计数归0则真正隐藏loading弹窗
  */
 export declare function endLoading(): void;
 
@@ -224,12 +271,13 @@ export declare function endLoading(): void;
  */
 export interface RequestInstance {
   /**
+   * 基础请求调用
    * @param url 请求地址
-   * @param method get/post等http方法
+   * @param method http方法 get/post/put/delete等
    * @param params 请求参数
-   * @param [config] 当前请求配置，覆盖defaultConfig
-   * @param [options] 当前请求扩展选项，覆盖defaultOpts
-   * @returns {Promise<unknown>}
+   * @param [config] 当前请求配置，覆盖实例defaultConfig（baseURL、headers等）
+   * @param [options] 当前请求扩展选项，覆盖实例defaultOpts（loading、缓存、拦截器）
+   * @returns Promise业务响应数据
    */
   (url: string, method: string, params?: unknown, config?: Record<string, unknown>, options?: UserRequestOpts): Promise<unknown>;
 
@@ -256,7 +304,7 @@ export interface RequestInstance {
  * 创建常规http请求实例（get/post）
  * @param defaultConfig 实例默认配置(baseURL、headers等)
  * @param defaultOpts 实例默认扩展选项(loading、缓存、拦截器)
- * @returns {RequestInstance}
+ * @returns RequestInstance 请求实例
  */
 export declare function createRequest(defaultConfig: Record<string, unknown>, defaultOpts?: UserRequestOpts): RequestInstance;
 
@@ -264,7 +312,7 @@ export declare function createRequest(defaultConfig: Record<string, unknown>, de
  * 创建上传文件实例
  * @param defaultConfig 实例默认配置(baseURL、headers等)
  * @param defaultOpts 实例默认扩展选项
- * @returns 上传函数
+ * @returns 上传调用函数
  */
 export declare function createUploadFile(
   defaultConfig: Record<string, unknown>,
@@ -275,7 +323,7 @@ export declare function createUploadFile(
  * 创建下载文件实例
  * @param defaultConfig 实例默认配置(baseURL、headers等)
  * @param defaultOpts 实例默认扩展选项
- * @returns 下载函数
+ * @returns 下载调用函数
  */
 export declare function createDownloadFile(
   defaultConfig: Record<string, unknown>,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "utils-uniapp",
-  "version": "1.1.8",
+  "version": "1.1.9",
   "description": "aubyn's utils for uniapp",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",