@stdex/request 1.0.1 → 1.2.0

package/README.md

@@ -1 +1 @@
-# 可靠、简洁的网络请求模块
+# 可靠、可定制的 HTTP 请求库

package/dist/client.d.ts

@@ -2,17 +2,13 @@
  * 实现一个功能完善、异常处理逻辑全面的请求发起器。
  * 可通过继承子类来扩展其功能。
  */
-import { type Logger } from '@stdex/logging';
 import { type Result, type Success, type Failure } from '@stdex/utils/result.js';
 import { type RequestFailure } from './error.js';
 import type { Options, PredefinedOptions, FormattedOptions } from './options.js';
 /** 此基类不可直接使用，因其未对错误格式进行具体约定 */
 export declare abstract class BaseRequestClient<FailureT extends Failure> {
-    logger: Logger;
     prefefinedOptions: PredefinedOptions;
-    constructor(options?: PredefinedOptions & {
-        logger?: string | Logger;
-    });
+    constructor(options?: PredefinedOptions);
     /** 生成一个快捷方式函数，调用它相当于调用 client.request() */
     asFunction(): <T>(inputUrl: string, inputOptions?: Options<T>) => Promise<Result<T, FailureT>>;
     request<T>(inputUrl: string, inputOptions?: Options<T>): Promise<Result<T, FailureT>>;
@@ -30,7 +26,7 @@ export declare abstract class BaseRequestClient<FailureT extends Failure> {
      *   - 其他情况，返回纯文本结果
      */
     protected parseResponse(options: FormattedOptions, response: Response): Promise<Result<unknown, FailureT>>;
-    protected handleError(result: RequestFailure): FailureT;
+    protected handleError(result: RequestFailure, options: FormattedOptions): FailureT;
     /** 生成符合 FailureT 约定的失败结果 */
     protected abstract makeFailureResult(result: RequestFailure): FailureT;
     /**

package/dist/client.js

@@ -2,21 +2,14 @@
  * 实现一个功能完善、异常处理逻辑全面的请求发起器。
  * 可通过继承子类来扩展其功能。
  */
-import { getLogger } from '@stdex/logging';
 import { success, failure, formatFailure, exceptionToFailure, } from '@stdex/utils/result.js';
 import { combineUrl } from '@stdex/utils/url.js';
 import isPlainObject from 'lodash/isPlainObject.js';
 import pick from 'lodash/pick.js';
 /** 此基类不可直接使用，因其未对错误格式进行具体约定 */
 export class BaseRequestClient {
-    logger;
     prefefinedOptions;
     constructor(options = {}) {
-        this.logger = !options.logger
-            ? getLogger('request')
-            : typeof options.logger === 'string'
-                ? getLogger(options.logger)
-                : options.logger;
         this.prefefinedOptions = options;
     }
     /** 生成一个快捷方式函数，调用它相当于调用 client.request() */
@@ -36,7 +29,7 @@ export class BaseRequestClient {
         do {
             tryCount += 1;
             if (tryCount > 1) {
-                this.logger.warn('Retrying Request', { ...options, tryCount });
+                options.logger?.warn('Retrying Request', { ...options, tryCount });
             }
             result = await this.realRequest(options);
         } while (!result.success && tryCount < options.retry + 1);
@@ -57,14 +50,14 @@ export class BaseRequestClient {
             // 失败情形“手动取消”
             if (manualSignal?.aborted && manualSignal.reason === error) {
                 const reason = error instanceof DOMException && error.name === 'AbortError' ? null : error;
-                return this.handleError(failure('Request Was Canceled', 'RequestAborted', { options, reason }));
+                return this.handleError(failure('Request Was Canceled', 'RequestAborted', { options, reason }), options);
             }
             // 失败情形“请求超时”
             if (error instanceof DOMException && error.name === 'TimeoutError') {
-                return this.handleError(failure('Request Timed Out', 'RequestTimeout', { options }));
+                return this.handleError(failure('Request Timed Out', 'RequestTimeout', { options }), options);
             }
             // 失败情形“请求发起失败”
-            return this.handleError(failure("Couldn't Send Request", 'RequestSendFailed', { options, originalError: error }));
+            return this.handleError(failure("Couldn't Send Request", 'RequestSendFailed', { options, originalError: error }), options);
         }
         // 失败情形“失败状态码”
         if (!response.status.toString().startsWith('2')) {
@@ -77,7 +70,7 @@ export class BaseRequestClient {
                 status: response.status,
                 response,
                 responseData,
-            }));
+            }), options);
         }
         // 解析响应内容
         let result = await this.parseResponse(options, response);
@@ -92,7 +85,7 @@ export class BaseRequestClient {
                     originalError: error,
                     response,
                     responseData: result.data,
-                }));
+                }), options);
             }
         }
         if (result.success && format) {
@@ -106,7 +99,7 @@ export class BaseRequestClient {
                     originalError: error,
                     response,
                     responseData: result.data,
-                }));
+                }), options);
             }
         }
         return result;
@@ -117,7 +110,7 @@ export class BaseRequestClient {
     async formatOptions(input) {
         const predefined = this.prefefinedOptions;
         const { urlPrefix = predefined.urlPrefix ?? '', url: rawUrl, query = {}, method = predefined.method ?? 'GET', headers: rawHeaders = {}, body: rawBody = null, data, // eslint-disable-line @typescript-eslint/no-unsafe-assignment
-        binary = false, timeout = predefined.timeout ?? 0, signal, retry = predefined.retry ?? 0, format, } = input;
+        binary = false, timeout = predefined.timeout ?? 0, signal, retry = predefined.retry ?? 0, format, logger = predefined.logger, } = input;
         const headers = {
             ...(predefined.headers ?? {}),
             ...rawHeaders,
@@ -145,6 +138,7 @@ export class BaseRequestClient {
             signal,
             format,
             retry,
+            logger,
         };
         Object.assign(options.headers, await this.getHeaders(options, input));
         return options;
@@ -178,7 +172,7 @@ export class BaseRequestClient {
                 status: response.status,
                 originalError: result.data,
                 response,
-            })));
+            }), options));
         }
         const textResult = await exceptionToFailure(response.text());
         if (contentType.startsWith('text/') || !textResult.success) {
@@ -187,7 +181,7 @@ export class BaseRequestClient {
                 status: response.status,
                 originalError: result.data,
                 response,
-            })));
+            }), options));
         }
         let jsonParseError;
         try {
@@ -202,17 +196,17 @@ export class BaseRequestClient {
                 status: response.status,
                 originalError: jsonParseError,
                 response,
-            }));
+            }), options);
         }
         return textResult;
     }
-    handleError(result) {
+    handleError(result, options) {
         const info = pick(result.data.options, ['url', 'method']);
         for (const key of ['originalError', 'status', 'responseData']) {
             if (key in result.data)
                 Object.assign(info, pick(result.data, [key]));
         }
-        this.logger.error(result.code, info);
+        options.logger?.error(result.code, info);
         return this.makeFailureResult(result);
     }
     /**

package/dist/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("@stdex/utils/result.js").Result<T, import("./error.js").RequestFailure>>;
+export declare const request: <T>(inputUrl: string, inputOptions?: import("./options.js").Options<T> | undefined) => Promise<import("@stdex/utils").Result<T, import("./error.js").RequestFailure>>;

package/dist/options.d.ts

@@ -1,3 +1,4 @@
+import { type GeneralLogger } from '@stdex/utils';
 /**
  * 请求参数
  */
@@ -26,8 +27,10 @@ export interface Options<T = unknown> {
     retry?: number;
     /** 对请求成功时得到的数据进行最终格式化 */
     format?: (responseData: any) => T;
+    /** 记录请求相关日志 */
+    logger?: GeneralLogger;
 }
 /** 可预指定的请求参数 */
-export type PredefinedOptions = Pick<Options, 'urlPrefix' | 'method' | 'headers' | 'timeout' | 'retry'>;
+export type PredefinedOptions = Pick<Options, 'urlPrefix' | 'method' | 'headers' | 'timeout' | 'retry' | 'logger'>;
 /** 经过整理的请求参数（client 内部使用） */
-export type FormattedOptions<T = unknown> = Required<Pick<Options, 'url' | 'method' | 'headers' | 'body' | 'binary' | 'timeout' | 'retry'>> & Pick<Options<T>, 'signal' | 'format'>;
+export type FormattedOptions<T = unknown> = Required<Pick<Options, 'url' | 'method' | 'headers' | 'body' | 'binary' | 'timeout' | 'retry'>> & Pick<Options<T>, 'signal' | 'format' | 'logger'>;

package/package.json

@@ -1,17 +1,17 @@
 {
   "name": "@stdex/request",
-  "version": "1.0.1",
-  "description": "可靠、简洁的网络请求模块",
-  "homepage": "https://github.com/anjianshi/stdex-request",
+  "version": "1.2.0",
+  "description": "可靠、可定制的 HTTP 请求库",
+  "homepage": "https://github.com/anjianshi/stdex-packages/request",
   "bugs": {
-    "url": "https://github.com/anjianshi/stdex-request/issues",
+    "url": "https://github.com/anjianshi/stdex-packages/issues",
     "email": "anjianshi@gmail.com"
   },
   "license": "MIT",
   "author": "anjianshi <anjianshi@gmail.com>",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/anjianshi/stdex-request.git"
+    "url": "git+https://github.com/anjianshi/stdex-packages.git"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
@@ -25,14 +25,13 @@
     "dist/"
   ],
   "dependencies": {
-    "@stdex/logging": "^1.1.0",
-    "@stdex/utils": "^1.0.2",
+    "@stdex/utils": "1.2.0",
     "lodash": "^4.18.1"
   },
   "devDependencies": {
-    "@stdex/presets-eslint-typescript": "^1.0.2",
-    "@stdex/presets-prettier": "^1.0.2",
-    "@stdex/presets-typescript": "^1.0.2",
+    "@stdex/presets-eslint-typescript": "1.2.0",
+    "@stdex/presets-prettier": "1.2.0",
+    "@stdex/presets-typescript": "1.2.0",
     "@types/lodash": "^4.17.27",
     "eslint": "^10.6.0",
     "typescript": "^6.0.3"

package/src/client.ts

@@ -2,7 +2,6 @@
  * 实现一个功能完善、异常处理逻辑全面的请求发起器。
  * 可通过继承子类来扩展其功能。
  */
-import { getLogger, type Logger } from '@stdex/logging'
 import {
   success,
   failure,
@@ -20,15 +19,9 @@ import type { Options, PredefinedOptions, FormattedOptions } from './options.js'
 
 /** 此基类不可直接使用，因其未对错误格式进行具体约定 */
 export abstract class BaseRequestClient<FailureT extends Failure> {
-  logger: Logger
   prefefinedOptions: PredefinedOptions
 
-  constructor(options: PredefinedOptions & { logger?: string | Logger } = {}) {
-    this.logger = !options.logger
-      ? getLogger('request')
-      : typeof options.logger === 'string'
-        ? getLogger(options.logger)
-        : options.logger
+  constructor(options: PredefinedOptions = {}) {
     this.prefefinedOptions = options
   }
 
@@ -53,7 +46,7 @@ export abstract class BaseRequestClient<FailureT extends Failure> {
     do {
       tryCount += 1
       if (tryCount > 1) {
-        this.logger.warn('Retrying Request', { ...options, tryCount })
+        options.logger?.warn('Retrying Request', { ...options, tryCount })
       }
       result = await this.realRequest<T>(options)
     } while (!result.success && tryCount < options.retry + 1)
@@ -79,15 +72,17 @@ export abstract class BaseRequestClient<FailureT extends Failure> {
         const reason = error instanceof DOMException && error.name === 'AbortError' ? null : error
         return this.handleError(
           failure('Request Was Canceled', 'RequestAborted', { options, reason }),
+          options
         )
       }
       // 失败情形“请求超时”
       if (error instanceof DOMException && error.name === 'TimeoutError') {
-        return this.handleError(failure('Request Timed Out', 'RequestTimeout', { options }))
+        return this.handleError(failure('Request Timed Out', 'RequestTimeout', { options }), options)
       }
       // 失败情形“请求发起失败”
       return this.handleError(
         failure("Couldn't Send Request", 'RequestSendFailed', { options, originalError: error }),
+        options
       )
     }
 
@@ -104,6 +99,7 @@ export abstract class BaseRequestClient<FailureT extends Failure> {
           response,
           responseData,
         }),
+        options
       )
     }
 
@@ -122,6 +118,7 @@ export abstract class BaseRequestClient<FailureT extends Failure> {
             response,
             responseData: result.data,
           }),
+          options
         )
       }
     }
@@ -141,6 +138,7 @@ export abstract class BaseRequestClient<FailureT extends Failure> {
               responseData: result.data,
             },
           ),
+          options
         )
       }
     }
@@ -166,6 +164,7 @@ export abstract class BaseRequestClient<FailureT extends Failure> {
       signal,
       retry = predefined.retry ?? 0,
       format,
+      logger = predefined.logger,
     } = input
 
     const headers = {
@@ -197,6 +196,7 @@ export abstract class BaseRequestClient<FailureT extends Failure> {
       signal,
       format,
       retry,
+      logger,
     }
     Object.assign(options.headers, await this.getHeaders(options, input))
     return options
@@ -241,6 +241,7 @@ export abstract class BaseRequestClient<FailureT extends Failure> {
             originalError: result.data,
             response,
           }),
+          options,
         ),
       )
     }
@@ -255,6 +256,7 @@ export abstract class BaseRequestClient<FailureT extends Failure> {
             originalError: result.data,
             response,
           }),
+          options,
         ),
       )
     }
@@ -273,17 +275,18 @@ export abstract class BaseRequestClient<FailureT extends Failure> {
           originalError: jsonParseError,
           response,
         }),
+        options
       )
     }
     return textResult
   }
 
-  protected handleError(result: RequestFailure) {
+  protected handleError(result: RequestFailure, options: FormattedOptions) {
     const info: Record<string, unknown> = pick(result.data.options, ['url', 'method'])
     for (const key of ['originalError', 'status', 'responseData'] as const) {
       if (key in result.data) Object.assign(info, pick(result.data, [key]))
     }
-    this.logger.error(result.code, info)
+    options.logger?.error(result.code, info)
     return this.makeFailureResult(result)
   }
 

package/src/options.ts

@@ -1,3 +1,5 @@
+import { type GeneralLogger } from '@stdex/utils'
+
 /**
  * 请求参数
  */
@@ -34,16 +36,19 @@ export interface Options<T = unknown> {
   /** 对请求成功时得到的数据进行最终格式化 */
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   format?: (responseData: any) => T
+
+  /** 记录请求相关日志 */
+  logger?: GeneralLogger
 }
 
 /** 可预指定的请求参数 */
 export type PredefinedOptions = Pick<
   Options,
-  'urlPrefix' | 'method' | 'headers' | 'timeout' | 'retry'
+  'urlPrefix' | 'method' | 'headers' | 'timeout' | 'retry' | 'logger'
 >
 
 /** 经过整理的请求参数（client 内部使用） */
 export type FormattedOptions<T = unknown> = Required<
   Pick<Options, 'url' | 'method' | 'headers' | 'body' | 'binary' | 'timeout' | 'retry'>
 > &
-  Pick<Options<T>, 'signal' | 'format'>
+  Pick<Options<T>, 'signal' | 'format' | 'logger'>