@base-web-kits/base-tools-web 1.1.18-alpha.1 → 1.2.0

package/dist/network/request.d.ts

@@ -39,22 +39,24 @@ export type RequestConfigBase<D extends RequestData = RequestData> = {
     successCode: (number | string)[];
     /** 登录过期状态码 */
     reloginCode: (number | string)[];
-    /** 是否显示进度条: 支持字符串,自定义文本 (默认true) */
-    showLoading?: boolean | string;
-    /** 是否提示接口异常 (默认true) */
-    toastError?: boolean;
-    /** 是否输出日志 (默认true) */
-    isLog?: boolean;
-    /** 额外输出的日志数据 */
-    extraLog?: Record<string, unknown>;
-    /** 响应数据的缓存时间, 单位毫秒。仅在成功时缓存；仅缓存在内存，应用退出,缓存消失。(默认0,不开启缓存) */
-    cacheTime?: number;
     /** 是否开启流式传输 (如 SSE) */
     enableChunked?: boolean;
     /** 响应类型 (默认 json, enableChunked为true时忽略) */
     responseType?: 'text' | 'arraybuffer' | 'json';
+    /** 响应数据的缓存时间, 单位毫秒。仅在成功时缓存；仅缓存在内存，应用退出,缓存消失。(默认0,不开启缓存) */
+    cacheTime?: number;
+    /** 是否提示接口异常 (默认true) */
+    toastError?: boolean;
+    /** 是否显示进度条: 支持字符串,自定义文本 (默认true) */
+    showLoading?: boolean | string;
+    /** 是否输出日志 (默认true) */
+    showLog?: boolean;
+    /** 成功和失败时,额外输出的日志数据 (可覆盖内部log参数,如'name') */
+    logExtra?: Record<string, unknown>;
     /** 响应拦截 */
-    responseInterceptor?: (data: ResponseData) => ResponseData;
+    resMap?: (data: ResponseData) => ResponseData;
+    /** 获取task对象, 用于取消请求或监听流式数据 */
+    onTaskReady?: (task: RequestTask) => void;
 };
 /**
  * 请求任务对象 (用于取消请求或监听流式数据)
@@ -77,7 +79,6 @@ export type ChunkCallback = (response: {
  * 基础请求 (返回 Promise 和 Task 对象)
  * 基于 fetch API 封装，支持流式请求
  * @param config 请求配置
- * @returns Promise<T> & { task?: RequestTask }
  * @example
  * // 在入口文件完成配置 (确保请求失败有toast提示,登录过期能够触发重新登录,log有日志输出)
  * setBaseToolsConfig({
@@ -100,7 +101,7 @@ export type ChunkCallback = (response: {
  * export function requestApi<T>(config: RequestConfig) {
  *    return request<T>({
  *      header: { token: 'xx', version: 'xx', tid: 'xx' }, // 会自动过滤空值
- *      // responseInterceptor: (res) => res, // 响应拦截，可预处理响应数据，如解密 (可选)
+ *      // resMap: (res) => res, // 响应拦截，可预处理响应数据，如解密 (可选)
  *      resKey: 'data',
  *      msgKey: 'message',
  *      codeKey: 'status',
@@ -122,32 +123,36 @@ export type ChunkCallback = (response: {
  *   return requestApi<GoodItem[]>({ url: '/goods/list', resKey: 'data.list', ...config });
  * }
  *
- * const goodList = await apiGoodList({ data: { page:1, size:10 }, showLoading: false });
+ * const goodList = await apiGoodList({ data: { page:1, size:10 } });
  *
  * // 3. 基于上面 requestApi 的流式接口
- * export function apiChatStream(data: { question: string }) {
- *   return requestApi<T>({
+ * export function apiChatStream(config: RequestConfig) {
+ *   return requestApi({
+ *     ...config,
  *     url: '/sse/chatStream',
- *     data,
  *     resKey: false,
  *     showLoading: false,
- *     responseType: 'arraybuffer',
- *     enableChunked: true,
+ *     responseType: 'arraybuffer', // 流式响应类型
+ *     enableChunked: true, // 开启分块传输
  *   });
  * }
  *
- * const { task } = apiChatStream({question: '你好'}); // 发起流式请求
+ * // 流式监听
+ * const onTaskReady = (task: RequestTask) => {
+ *    task.onChunkReceived((res) => {
+ *      console.log('ArrayBuffer', res.data);
+ *    });
+ * }
  *
- * task.onChunkReceived((res) => {
- *   console.log('ArrayBuffer', res.data); // 接收流式数据
- * });
+ * // 流式发起
+ * const data: ChatData = { content: '你好', conversationId: 123 };
+ * await apiChatStream({ data, onTaskReady });
  *
- * task.offChunkReceived(); // 取消监听,中断流式接收 (调用时机:流式结束,组件销毁,页面关闭)
- * task.abort(); // 取消请求 (若流式传输中,会中断流并抛出异常)
+ * // 流式取消 (在组件销毁或页面关闭时调用)
+ * task?.offChunkReceived(); // 取消监听,中断流式接收
+ * task?.abort(); // 取消请求 (若流式已生成,此时abort无效,因为请求已成功)
  */
-export declare function request<T, D extends RequestData = RequestData>(config: RequestConfigBase<D>): Promise<T> & {
-    task?: RequestTask;
-};
+export declare function request<T, D extends RequestData = RequestData>(config: RequestConfigBase<D>): Promise<T>;
 /**
  * 参数过滤undefined, 避免接口处理异常 (不可过滤 null 、 "" 、 false 、 0 这些有效值)
  */

package/dist/network/request.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../../src/web/network/request.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../../src/web/network/request.ts"],"names":[],"mappings":"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"}

package/dist/storage/index.d.ts

@@ -1,9 +1,7 @@
 /**
  * 写入 localStorage（自动 JSON 序列化）
- * 当 `value` 为 `null` 或 `undefined` 时，会移除该键。
- * 支持保存：对象、数组、字符串、数字、布尔值。
  * @param key 键名
- * @param value 任意可序列化的值
+ * @param value 任意可序列化的值：对象、数组、字符串、数字、布尔值。(`null` 或 `undefined` 会自动移除该键)
  * @param days 过期天数（从当前时间起算）
  * @example
  * setLocalStorage('user', { id: 1, name: 'Alice' }); // 对象

package/dist/storage/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/web/storage/index.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,MAAM,QAiBzE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI,CAiBlE;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,QAE7C"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/web/storage/index.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,MAAM,QAiBzE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI,CAiBlE;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,QAE7C"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base-web-kits/base-tools-web",
-  "version": "1.1.18-alpha.1",
+  "version": "1.2.0",
   "sideEffects": false,
   "description": "Independent Web utilities package built from src/web.",
   "keywords": [
@@ -25,7 +25,7 @@
     "src"
   ],
   "dependencies": {
-    "@base-web-kits/base-tools-ts": "^1.1.11"
+    "@base-web-kits/base-tools-ts": "^1.2.0"
   },
   "peerDependencies": {
     "axios": ">=0.18.0"

package/src/web/async/index.ts

@@ -1,4 +1,6 @@
+import { cloneDeep } from '@base-web-kits/base-tools-ts';
 import { getBaseToolsConfig } from '../index';
+import type { AppLogInfo } from '../index';
 
 type WebApi<Option = any, Res = any, Config = any> = (
   option: Option,
@@ -20,6 +22,12 @@ export type WebApiConfig<Res = any, Err = any> = {
 
   /** 是否显示日志, 默认 true */
   showLog?: boolean;
+
+  /** 成功响应数据的处理, 如解密操作 (返回值在成功日志中输出'resMap'字段) */
+  resMap?: (res: any) => Res;
+
+  /** 成功和失败时,额外输出的日志数据 (可覆盖内部log参数,如'name') */
+  logExtra?: Record<string, unknown>;
 };
 
 /**
@@ -42,7 +50,10 @@ export function enhanceWebApi<Option = any, Res = any, Err = any, Config = any>(
       toastSuccess = false,
       toastError = true,
       showLog = true,
+      resMap,
+      logExtra,
     } = finalConfig;
+
     const {
       log,
       toast,
@@ -60,15 +71,30 @@ export function enhanceWebApi<Option = any, Res = any, Err = any, Config = any>(
       webApi(option, finalConfig)
         .then((res) => {
           if (showLoading) hideLoadingFn?.();
-          if (showLog) log?.('info', { name: fname, status: 'success', option, res });
-          resolve(res);
 
-          const msg = typeof toastSuccess === 'function' ? toastSuccess(res) : toastSuccess;
+          const finalRes = resMap ? resMap(res) : res;
+
+          if (showLog) {
+            const logData: AppLogInfo = { name: fname, status: 'success', option, ...logExtra };
+
+            if (resMap) {
+              logData.res = res; // 输出原始数据
+              logData.resMap = cloneDeep(finalRes); // 深拷贝处理后数据,避免外部修改对象,造成输出不一致
+            } else {
+              logData.res = cloneDeep(res); // 深拷贝原始数据,避免外部修改对象,造成输出不一致
+            }
+
+            log?.('info', logData);
+          }
+
+          resolve(finalRes);
+
+          const msg = typeof toastSuccess === 'function' ? toastSuccess(finalRes) : toastSuccess;
           if (msg) toast?.({ msg, status: 'success' });
         })
         .catch((e) => {
           if (showLoading) hideLoadingFn?.();
-          if (showLog) log?.('error', { name: fname, status: 'fail', option, e });
+          if (showLog) log?.('error', { name: fname, status: 'fail', option, e, ...logExtra });
 
           const msg = typeof toastError === 'function' ? toastError(e) : toastError;
           if (msg) {

package/src/web/network/request.ts

@@ -52,12 +52,16 @@ export type RequestConfig<D extends RequestData = RequestData> = Partial<Request
 export type RequestConfigBase<D extends RequestData = RequestData> = {
   /** 接口地址 */
   url: string;
+
   /** 请求方法 */
   method?: RequestMethod;
+
   /** 请求头(会自动过滤undefined, null, "";不过滤0和false; 数字和布尔值会自动转换为字符串) */
   header?: Record<string, string | number | boolean | null | undefined>;
+
   /** 请求参数 */
   data?: D;
+
   /** 超时时间 (毫秒), 默认 60000 */
   timeout?: number;
 
@@ -79,29 +83,32 @@ export type RequestConfigBase<D extends RequestData = RequestData> = {
   /** 登录过期状态码 */
   reloginCode: (number | string)[];
 
-  /** 是否显示进度条: 支持字符串,自定义文本 (默认true) */
-  showLoading?: boolean | string;
-
-  /** 是否提示接口异常 (默认true) */
-  toastError?: boolean;
-
-  /** 是否输出日志 (默认true) */
-  isLog?: boolean;
+  /** 是否开启流式传输 (如 SSE) */
+  enableChunked?: boolean;
 
-  /** 额外输出的日志数据 */
-  extraLog?: Record<string, unknown>;
+  /** 响应类型 (默认 json, enableChunked为true时忽略) */
+  responseType?: 'text' | 'arraybuffer' | 'json';
 
   /** 响应数据的缓存时间, 单位毫秒。仅在成功时缓存；仅缓存在内存，应用退出,缓存消失。(默认0,不开启缓存) */
   cacheTime?: number;
 
-  /** 是否开启流式传输 (如 SSE) */
-  enableChunked?: boolean;
+  /** 是否提示接口异常 (默认true) */
+  toastError?: boolean;
 
-  /** 响应类型 (默认 json, enableChunked为true时忽略) */
-  responseType?: 'text' | 'arraybuffer' | 'json';
+  /** 是否显示进度条: 支持字符串,自定义文本 (默认true) */
+  showLoading?: boolean | string;
+
+  /** 是否输出日志 (默认true) */
+  showLog?: boolean;
+
+  /** 成功和失败时,额外输出的日志数据 (可覆盖内部log参数,如'name') */
+  logExtra?: Record<string, unknown>;
 
   /** 响应拦截 */
-  responseInterceptor?: (data: ResponseData) => ResponseData;
+  resMap?: (data: ResponseData) => ResponseData;
+
+  /** 获取task对象, 用于取消请求或监听流式数据 */
+  onTaskReady?: (task: RequestTask) => void;
 };
 
 /**
@@ -130,7 +137,6 @@ const requestCache = new Map<string, { res: unknown; expire: number }>();
  * 基础请求 (返回 Promise 和 Task 对象)
  * 基于 fetch API 封装，支持流式请求
  * @param config 请求配置
- * @returns Promise<T> & { task?: RequestTask }
  * @example
  * // 在入口文件完成配置 (确保请求失败有toast提示,登录过期能够触发重新登录,log有日志输出)
  * setBaseToolsConfig({
@@ -153,7 +159,7 @@ const requestCache = new Map<string, { res: unknown; expire: number }>();
  * export function requestApi<T>(config: RequestConfig) {
  *    return request<T>({
  *      header: { token: 'xx', version: 'xx', tid: 'xx' }, // 会自动过滤空值
- *      // responseInterceptor: (res) => res, // 响应拦截，可预处理响应数据，如解密 (可选)
+ *      // resMap: (res) => res, // 响应拦截，可预处理响应数据，如解密 (可选)
  *      resKey: 'data',
  *      msgKey: 'message',
  *      codeKey: 'status',
@@ -175,30 +181,57 @@ const requestCache = new Map<string, { res: unknown; expire: number }>();
  *   return requestApi<GoodItem[]>({ url: '/goods/list', resKey: 'data.list', ...config });
  * }
  *
- * const goodList = await apiGoodList({ data: { page:1, size:10 }, showLoading: false });
+ * const goodList = await apiGoodList({ data: { page:1, size:10 } });
  *
  * // 3. 基于上面 requestApi 的流式接口
- * export function apiChatStream(data: { question: string }) {
- *   return requestApi<T>({
+ * export function apiChatStream(config: RequestConfig) {
+ *   return requestApi({
+ *     ...config,
  *     url: '/sse/chatStream',
- *     data,
  *     resKey: false,
  *     showLoading: false,
- *     responseType: 'arraybuffer',
- *     enableChunked: true,
+ *     responseType: 'arraybuffer', // 流式响应类型
+ *     enableChunked: true, // 开启分块传输
  *   });
  * }
  *
- * const { task } = apiChatStream({question: '你好'}); // 发起流式请求
+ * // 流式监听
+ * const onTaskReady = (task: RequestTask) => {
+ *    task.onChunkReceived((res) => {
+ *      console.log('ArrayBuffer', res.data);
+ *    });
+ * }
  *
- * task.onChunkReceived((res) => {
- *   console.log('ArrayBuffer', res.data); // 接收流式数据
- * });
+ * // 流式发起
+ * const data: ChatData = { content: '你好', conversationId: 123 };
+ * await apiChatStream({ data, onTaskReady });
  *
- * task.offChunkReceived(); // 取消监听,中断流式接收 (调用时机:流式结束,组件销毁,页面关闭)
- * task.abort(); // 取消请求 (若流式传输中,会中断流并抛出异常)
+ * // 流式取消 (在组件销毁或页面关闭时调用)
+ * task?.offChunkReceived(); // 取消监听,中断流式接收
+ * task?.abort(); // 取消请求 (若流式已生成,此时abort无效,因为请求已成功)
  */
 export function request<T, D extends RequestData = RequestData>(config: RequestConfigBase<D>) {
+  const {
+    url,
+    data,
+    header,
+    method = 'GET',
+    resKey,
+    msgKey,
+    codeKey,
+    successKey,
+    successCode,
+    reloginCode,
+    showLoading = true,
+    toastError = true,
+    enableChunked = false,
+    cacheTime,
+    resMap,
+    responseType = 'json',
+    timeout = 60000,
+    onTaskReady,
+  } = config;
+
   // 1. 初始化控制对象
   const controller = new AbortController();
   const signal = controller.signal;
@@ -214,30 +247,11 @@ export function request<T, D extends RequestData = RequestData>(config: RequestC
       chunkCallback = null;
     },
   };
+  onTaskReady?.(task);
 
   // 2. 创建 Promise
-  const promise = new Promise<T>((resolve, reject) => {
+  return new Promise<T>((resolve, reject) => {
     const execute = async () => {
-      const {
-        url,
-        data,
-        header,
-        method = 'GET',
-        resKey,
-        msgKey,
-        codeKey,
-        successKey,
-        successCode,
-        reloginCode,
-        showLoading = true,
-        toastError = true,
-        enableChunked = false,
-        cacheTime,
-        responseInterceptor,
-        responseType = 'json',
-        timeout = 60000,
-      } = config;
-
       const isGet = method === 'GET';
       const isObjectData = isPlainObject(data);
       const isArrayData = !isObjectData && Array.isArray(data);
@@ -349,7 +363,7 @@ export function request<T, D extends RequestData = RequestData>(config: RequestC
         if (showLoading) appConfig.hideLoading?.();
 
         // 响应拦截
-        const res = responseInterceptor ? responseInterceptor(resData) : resData;
+        const res = resMap ? resMap(resData) : resData;
 
         // 2.10 业务状态码解析
         const code = getObjectValue(res, codeKey);
@@ -395,12 +409,7 @@ export function request<T, D extends RequestData = RequestData>(config: RequestC
     };
 
     execute();
-  }) as Promise<T> & { task?: RequestTask };
-
-  // 3. 挂载 Task
-  promise.task = task;
-
-  return promise;
+  });
 }
 
 /**
@@ -439,12 +448,12 @@ function logRequestInfo(options: {
   e?: unknown;
 }) {
   const { log } = getBaseToolsConfig();
-  const { isLog = true } = options.config;
+  const { showLog = true } = options.config;
 
-  if (!log || !isLog) return;
+  if (!log || !showLog) return;
 
   const { config, res, fromCache = false, startTime, status, e } = options;
-  const { url, data, header, method, extraLog } = config;
+  const { url, data, header, method, logExtra } = config;
   const endTime = Date.now();
   const fmt = 'YYYY-MM-DD HH:mm:ss.SSS';
 
@@ -459,7 +468,7 @@ function logRequestInfo(options: {
     startTime: toDayjs(startTime).format(fmt),
     endTime: toDayjs(endTime).format(fmt),
     duration: endTime - startTime,
-    ...extraLog,
+    ...logExtra,
   };
 
   if (status === 'success') {

package/src/web/storage/index.ts

@@ -6,10 +6,8 @@ const WK = {
 
 /**
  * 写入 localStorage（自动 JSON 序列化）
- * 当 `value` 为 `null` 或 `undefined` 时，会移除该键。
- * 支持保存：对象、数组、字符串、数字、布尔值。
  * @param key 键名
- * @param value 任意可序列化的值
+ * @param value 任意可序列化的值：对象、数组、字符串、数字、布尔值。(`null` 或 `undefined` 会自动移除该键)
  * @param days 过期天数（从当前时间起算）
  * @example
  * setLocalStorage('user', { id: 1, name: 'Alice' }); // 对象