@anjianshi/utils 3.2.1 → 3.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anjianshi/utils",
-  "version": "3.2.1",
+  "version": "3.4.0",
   "description": "Common JavaScript Utils",
   "homepage": "https://github.com/anjianshi/js-packages/utils",
   "bugs": {
@@ -31,11 +31,11 @@
     "redis": "^5.5.6",
     "typescript": "^5.8.3",
     "vconsole": "^3.15.1",
-    "@anjianshi/presets-prettier": "3.0.5",
-    "@anjianshi/presets-eslint-react": "6.0.0",
-    "@anjianshi/presets-eslint-node": "6.0.0",
     "@anjianshi/presets-eslint-base": "6.0.0",
+    "@anjianshi/presets-eslint-node": "6.0.0",
     "@anjianshi/presets-eslint-typescript": "6.0.0",
+    "@anjianshi/presets-eslint-react": "6.0.0",
+    "@anjianshi/presets-prettier": "3.0.5",
     "@anjianshi/presets-typescript": "3.2.5"
   },
   "peerDependencies": {

package/request/client.d.ts

@@ -1,4 +1,4 @@
-import { type Result, type Failed } from '../lang/result.js';
+import { type Result, type Success, type Failed } from '../lang/result.js';
 import { type Logger } from '../logging/index.js';
 import { type RequestFailed } from './error.js';
 import type { Options, PredefinedOptions, FormattedOptions } from './options.js';
@@ -10,8 +10,8 @@ export declare abstract class BaseRequestClient<FailedT extends Failed> {
         loggerName?: string;
     });
     /** 生成一个快捷方式函数，调用它相当于调用 client.request() */
-    asFunction(): <T>(inputUrl: string, inputOptions?: Options<T>) => Promise<Result<T, FailedT>>;
-    request<T>(inputUrl: string, inputOptions?: Options<T>): Promise<Result<T, FailedT>>;
+    asFunction(): <T>(inputUrl: string, inputOptions?: Options) => Promise<Result<T, FailedT>>;
+    request<T>(inputUrl: string, inputOptions?: Options): Promise<Result<T, FailedT>>;
     formatOptions(input: Options): Promise<FormattedOptions>;
     /** 请求发起前调用此方法补充 Headers 内容 */
     protected getHeaders(options: FormattedOptions, inputOptions: Options): Record<string, string> | undefined | Promise<Record<string, string> | undefined>;
@@ -28,6 +28,14 @@ export declare abstract class BaseRequestClient<FailedT extends Failed> {
     protected handleError(result: RequestFailed): FailedT;
     /** 生成符合 FailedT 约定的失败结果 */
     protected abstract makeFailedResult(result: RequestFailed): FailedT;
+    /**
+     * 对请求成功得到的数据进行格式化。
+     *
+     * - 此步骤在 applyInputFormat() 之前运行，子类可在此进行一些通用的格式化工作，
+     * - 输出 Success 或 Failed 结果均可，但输出的 Failed 结果不会交给 makeFailedResult() 进行格式化，需自行保证符合 FailedT 约定。
+     * - 若此方法抛出异常，会生成 FormatResponseDataFailed，此错误会照常交给 makeFailedResult() 处理。
+     */
+    protected formatSuccessResult(result: Success<unknown>): Result<unknown, FailedT>;
 }
 /** 默认的 RequestClient 实现。出现错误时，会把错误对象原样放入错误信息中。 */
 export declare class RequestClient extends BaseRequestClient<RequestFailed> {

package/request/client.js

@@ -3,7 +3,7 @@
  * 可通过继承子类来扩展其功能。
  */
 import pick from 'lodash/pick.js';
-import { success, failed, formatSuccess, formatFailed, exceptionToFailed, } from '../lang/result.js';
+import { success, failed, formatFailed, exceptionToFailed, } from '../lang/result.js';
 import { getLogger } from '../logging/index.js';
 import { combineUrl } from '../url.js';
 /** 此基类不可直接使用，因其未对错误格式进行具体约定 */
@@ -38,7 +38,7 @@ export class BaseRequestClient {
         }
         catch (error) {
             // 失败情形“手动取消”
-            if (manualSignal && manualSignal.aborted && manualSignal.reason === error) {
+            if (manualSignal?.aborted && manualSignal.reason === error) {
                 const reason = error instanceof DOMException && error.name === 'AbortError' ? null : error;
                 return this.handleError(failed('Request Aborted', 'RequestAborted', { options, reason }));
             }
@@ -52,6 +52,7 @@ export class BaseRequestClient {
         // 失败情形“失败状态码”
         if (!response.status.toString().startsWith('2')) {
             // 此时服务端仍可能输出一些内容，试着解析出来
+            // 但因此情况下后端输出数据往往和成功时不同，因此不调用用户提供的 format() 函数来格式化
             const responseDataRes = await this.parseResponse(options, response);
             const responseData = responseDataRes.success ? responseDataRes.data : undefined;
             return this.handleError(failed('Non-Success Status', 'NonSuccessStatus', {
@@ -62,15 +63,43 @@ export class BaseRequestClient {
             }));
         }
         // 解析响应内容
-        const result = await this.parseResponse(options, response);
-        return formatSuccess(result, data => (format ? format(data) : data));
+        let result = await this.parseResponse(options, response);
+        // 格式化响应数据
+        if (result.success) {
+            try {
+                result = this.formatSuccessResult(result);
+            }
+            catch (error) {
+                return this.handleError(failed('Format Response Data Failed', 'FormatResponseDataFailed', {
+                    options,
+                    originalError: error,
+                    response,
+                    responseData: result.data,
+                }));
+            }
+        }
+        if (result.success && format) {
+            try {
+                const formattedData = format(result.data);
+                result = success(formattedData);
+            }
+            catch (error) {
+                return this.handleError(failed('Format Response Data By options.format Failed', 'FormatResponseDataFailed', {
+                    options,
+                    originalError: error,
+                    response,
+                    responseData: result.data,
+                }));
+            }
+        }
+        return result;
     }
     // -------------------------------
     // 请求预处理
     // -------------------------------
     async formatOptions(input) {
         const predefined = this.prefefinedOptions;
-        const { urlPrefix = predefined.urlPrefix ?? '', url: rawUrl, query = {}, method = predefined.method ?? 'GET', headers: rawHeaders = {}, body: rawBody = null, data, timeout = predefined.timeout ?? 0, binary = false, signal, } = input;
+        const { urlPrefix = predefined.urlPrefix ?? '', url: rawUrl, query = {}, method = predefined.method ?? 'GET', headers: rawHeaders = {}, body: rawBody = null, data, timeout = predefined.timeout ?? 0, binary = false, signal, format, } = input;
         const headers = {
             ...(predefined.headers ?? {}),
             ...rawHeaders,
@@ -94,6 +123,7 @@ export class BaseRequestClient {
             timeout,
             binary,
             signal,
+            format,
         };
         Object.assign(options.headers, await this.getHeaders(options, input));
         return options;
@@ -164,6 +194,16 @@ export class BaseRequestClient {
         this.logger.error(result.code, info);
         return this.makeFailedResult(result);
     }
+    /**
+     * 对请求成功得到的数据进行格式化。
+     *
+     * - 此步骤在 applyInputFormat() 之前运行，子类可在此进行一些通用的格式化工作，
+     * - 输出 Success 或 Failed 结果均可，但输出的 Failed 结果不会交给 makeFailedResult() 进行格式化，需自行保证符合 FailedT 约定。
+     * - 若此方法抛出异常，会生成 FormatResponseDataFailed，此错误会照常交给 makeFailedResult() 处理。
+     */
+    formatSuccessResult(result) {
+        return result;
+    }
 }
 /** 默认的 RequestClient 实现。出现错误时，会把错误对象原样放入错误信息中。 */
 export class RequestClient extends BaseRequestClient {

package/request/error.d.ts

@@ -8,7 +8,7 @@
  */
 import { type Failed } from '../lang/result.js';
 import { type FormattedOptions } from './options.js';
-export type RequestFailed = SendRequestFailed | RequestAborted | RequestTimedOut | NonSuccessStatus | ParseResponseBodyFailed;
+export type RequestFailed = SendRequestFailed | RequestAborted | RequestTimedOut | NonSuccessStatus | ParseResponseBodyFailed | FormatResponseDataFailed;
 export interface RequestFailedInfo {
     options: FormattedOptions;
 }
@@ -46,3 +46,13 @@ export interface ParseResponseBodyFailedInfo extends RequestFailedInfo {
     /** Response 对象 */
     response: Response;
 }
+/** 响应体解析失败 */
+export type FormatResponseDataFailed = Failed<'FormatResponseDataFailed', FormatResponseDataFailedInfo>;
+export interface FormatResponseDataFailedInfo extends RequestFailedInfo {
+    /** 原始错误对象 */
+    originalError: unknown;
+    /** Response 对象 */
+    response: Response;
+    /** 未经格式化的响应数据 */
+    responseData: unknown;
+}

package/request/instance.d.ts

@@ -1,4 +1,4 @@
 import { RequestClient } from './client.js';
 /** 提供一个即取即用的 RequestClient 实例及其函数版本 */
 export declare const client: RequestClient;
-export declare const request: <T>(inputUrl: string, inputOptions?: import("./options.js").Options<T> | undefined) => Promise<import("../index.js").Result<T, import("./error.js").RequestFailed>>;
+export declare const request: <T>(inputUrl: string, inputOptions?: import("./options.js").Options) => Promise<import("../index.js").Result<T, import("./error.js").RequestFailed>>;

package/request/options.d.ts

@@ -1,7 +1,7 @@
 /**
  * 请求参数
  */
-export interface Options<T = unknown> {
+export interface Options {
     urlPrefix?: string;
     url?: string;
     query?: Record<string, string | number | undefined>;
@@ -19,7 +19,8 @@ export interface Options<T = unknown> {
     timeout?: number;
     /** 可通过此信号手动终止请求 */
     signal?: AbortSignal;
-    format?: (responseData: unknown) => T;
+    /** 对请求成功时得到的数据进行最终格式化 */
+    format?: (responseData: any) => any;
 }
 /** 可预指定的请求参数 */
 export type PredefinedOptions = Pick<Options, 'urlPrefix' | 'method' | 'headers' | 'timeout'>;