@qlover/fe-corekit 1.2.1 → 1.2.5

package/dist/index.d.ts

@@ -551,7 +551,7 @@ declare abstract class Executor<ExecutorConfig = unknown> {
  *
  * @since 1.0.14
  */
-type RequestAdapterConfig<RequestData = unknown> = {
+interface RequestAdapterConfig<RequestData = unknown> {
     /**
      * Request URL path
      * Will be combined with baseURL if provided
@@ -637,7 +637,7 @@ type RequestAdapterConfig<RequestData = unknown> = {
      */
     requestId?: string;
     [key: string]: any;
-};
+}
 /**
  * Request adapter response
  *
@@ -647,7 +647,7 @@ type RequestAdapterConfig<RequestData = unknown> = {
  * @typeParam Req - The type of the request data.
  * @typeParam Res - The type of the response data.
  */
-type RequestAdapterResponse<Req = unknown, Res = unknown> = {
+interface RequestAdapterResponse<Req = unknown, Res = unknown> {
     data: Res;
     status: number;
     statusText: string;
@@ -657,7 +657,7 @@ type RequestAdapterResponse<Req = unknown, Res = unknown> = {
     config: RequestAdapterConfig<Req>;
     response: Response;
     [key: string]: unknown;
-};
+}
 /**
  * Request adapter interface
  *
@@ -754,6 +754,25 @@ declare enum RequestErrorID {
     URL_NONE = "URL_NONE"
 }
 
+/**
+ * Represents a transaction for a request.
+ *
+ * This interface defines a transaction that contains a request and a response.
+ * It can be used to track the request and response of a transaction.
+ *
+ * @since 1.2.2
+ */
+interface RequestTransactionInterface<Request, Response> {
+    /**
+     * The request object
+     */
+    request: Request;
+    /**
+     * The response object
+     */
+    response: Response;
+}
+
 /**
  * Generic interface for data serialization/deserialization operations
  * Provides a standard contract for implementing serialization strategies
@@ -1684,12 +1703,27 @@ declare class Logger {
  *
  * @since 1.0.14
  */
-type RequestAdapterFetchConfig<Request = unknown> = Omit<globalThis.RequestInit, 'headers'> & RequestAdapterConfig<Request> & {
+interface RequestAdapterFetchConfig<Request = unknown> extends RequestAdapterConfig<Request>, Omit<globalThis.RequestInit, 'headers'> {
+    /**
+     * The fetcher function
+     *
+     * You can override the default fetch function
+     *
+     * Some environments may not have a global fetch function, or you may want to override the default fetch logic.
+     *
+     * @example
+     * ```typescript
+     * const fetchRequest = new FetchRequest({ fetcher: customFetch });
+     * ```
+     *
+     * @example Or configure it for each request
+     * ```typescript
+     * const fetchRequest = new FetchRequest();
+     * fetchRequest.request({ url: '/data', fetcher: customFetch });
+     * ```
+     */
     fetcher?: typeof fetch;
-    onStreamProgress?: (progress: number) => void;
-    signal?: AbortSignal;
-    onAbort?(config: RequestAdapterFetchConfig): void;
-};
+}
 declare class RequestAdapterFetch implements RequestAdapterInterface<RequestAdapterFetchConfig> {
     readonly config: RequestAdapterFetchConfig;
     private executor;
@@ -1740,7 +1774,7 @@ declare class RequestAdapterFetch implements RequestAdapterInterface<RequestAdap
      * @param config The configuration used for the fetch request.
      * @returns A RequestAdapterResponse containing the processed response data.
      */
-    toAdapterResponse<Request>(data: unknown, response: Response, config: RequestAdapterFetchConfig<Request>): RequestAdapterResponse<Request>;
+    toAdapterResponse<Request, Res = unknown>(data: Res, response: Response, config: RequestAdapterFetchConfig<Request>): RequestAdapterResponse<Request, Res>;
     /**
      * Extracts headers from the fetch Response object and returns them as a record.
      *
@@ -2044,6 +2078,46 @@ declare class FetchURLPlugin implements ExecutorPlugin {
     onError({ error }: ExecutorContext): RequestError;
 }
 
+/**
+ * Represents a manager for handling HTTP requests.
+ *
+ * This interface defines a manager that contains an adapter and an executor.
+ * It provides methods for adding plugins to the executor and making requests.
+ *
+ * Why this is an abstract class?
+ *
+ * - Because the Executor can be overridden at runtime, the type cannot be fixed,
+ *   so we need to reasonably flexibly control it.
+ * - So we need to redefine the request type when implementing the current class.
+ *
+ * @since 1.2.2
+ */
+declare abstract class RequestManager<Config extends RequestAdapterConfig> {
+    protected readonly adapter: RequestAdapterInterface<Config>;
+    protected readonly executor: AsyncExecutor;
+    constructor(adapter: RequestAdapterInterface<Config>, executor?: AsyncExecutor);
+    /**
+     * Adds a plugin to the executor.
+     *
+     * @since 1.2.2
+     *
+     * @param plugin - The plugin to be used by the executor.
+     * @returns The current instance of RequestManagerInterface for chaining.
+     */
+    usePlugin(plugin: ExecutorPlugin | ExecutorPlugin[]): this;
+    /**
+     * Executes a request with the given configuration.
+     *
+     * This method need to be overridden by the subclass, override type definition of request method.
+     *
+     * Of course, you can also override its logic.
+     *
+     * @param config - The configuration for the request.
+     * @returns A promise that resolves to the response of the request.
+     */
+    request(config: unknown): Promise<unknown>;
+}
+
 /**
  * Represents a scheduler for managing HTTP requests.
  *
@@ -2098,31 +2172,13 @@ declare class FetchURLPlugin implements ExecutorPlugin {
  *
  * @template Config - The configuration type extending RequestAdapterConfig.
  */
-declare class RequestScheduler<Config extends RequestAdapterConfig> {
-    readonly adapter: RequestAdapterInterface<Config>;
-    readonly executor: AsyncExecutor;
-    /**
-     * Initializes a new instance of the RequestScheduler class.
-     *
-     * @since 1.0.14
-     *
-     * @param adapter - The request adapter interface to be used for making requests.
-     */
-    constructor(adapter: RequestAdapterInterface<Config>);
-    /**
-     * Adds a plugin to the request execution process.
-     *
-     * @since 1.0.14
-     *
-     * @param plugin - The plugin to be used by the executor.
-     * @returns The current instance of RequestScheduler for chaining.
-     */
-    usePlugin(plugin: ExecutorPlugin): this;
+declare class RequestScheduler<Config extends RequestAdapterConfig> extends RequestManager<Config> {
     /**
      * Executes a request with the given configuration.
      *
      * @since 1.0.14
      *
+     * @override
      * @param config - The configuration for the request.
      * @returns A promise that resolves to the response of the request.
      */
@@ -2192,6 +2248,213 @@ declare class RequestScheduler<Config extends RequestAdapterConfig> {
     connect<Request, Response>(url: string, config?: RequestAdapterConfig<Request>): Promise<RequestAdapterResponse<Response, Request>>;
 }
 
+/**
+ * Represents a transaction for managing HTTP requests.
+ *
+ * Now `RequestTransaction` and `RequestScheduler` have the same purpose, only different in form.
+ *
+ * If you want to override the return type of the request, you can use `RequestTransaction`.
+ *
+ * If you don't consider type, you can also use `requestScheduler`, just manually declare the return type.
+ *
+ * If you have the need to override the response or execution context, it is recommended to use `RequestTransaction`,
+ * because it can match the type through typescript.
+ *
+ * The `request` method of `RequestTransaction` can do the following:
+ * 1. Directly declare the return type through generics
+ * 2. Declare the config type through generics
+ * 3. Declare the request parameters and return values through `RequestTransactionInterface`
+ *
+ * Currently, it does not support passing parameters through generics, but you can use `RequestTransactionInterface`.
+ *
+ * @example Directly declare the return type through generics
+ * ```typescript
+ * const client = new RequestTransaction<CustomConfig>(new RequestAdapterFetch());
+ *
+ * client
+ *   .request<{
+ *     list: string[];
+ *   }>({ url: 'https://api.example.com/data', method: 'GET', hasCatchError: true })
+ *   .then((response) => {
+ *     console.log(response.data.list);
+ *   });
+ * ```
+ *
+ * @example Declare the config type through generics
+ * ```typescript
+ * const client = new RequestTransaction<
+ *   RequestAdapterConfig & { hasCatchError?: boolean }
+ * >(new RequestAdapterFetch());
+ *
+ * client.request({
+ *   url: 'https://api.example.com/data',
+ *   method: 'GET',
+ *   hasCatchError: true,
+ *   data: { name: 'John Doe' }
+ * });
+ * ```
+ *
+ * @example You can also extend the config type
+ *
+ * ```typescript
+ * interface CustomConfig extends RequestAdapterConfig {
+ *   hasCatchError?: boolean;
+ * }
+ *
+ * const client = new RequestTransaction<CustomConfig>(new RequestAdapterFetch());
+ *
+ * client.request({
+ *   url: 'https://api.example.com/data',
+ *   method: 'GET',
+ *   hasCatchError: true,
+ *   data: { name: 'John Doe' }
+ * });
+ * ```
+ *
+ * @example Directly declare the request parameters and return values through `RequestTransactionInterface`
+ * ```typescript
+ * interface CustomConfig extends RequestAdapterConfig {
+ *   hasCatchError?: boolean;
+ * }
+ * interface CustomResponse<T = unknown>
+ *   extends RequestAdapterResponse<unknown, T> {
+ *   catchError?: unknown;
+ * }
+ *
+ * const client = new RequestTransaction<CustomConfig>(new RequestAdapterFetch());
+ *
+ * client
+ *   .request<
+ *     RequestTransactionInterface<
+ *       CustomConfig,
+ *       CustomResponse<{ list?: string[] }>
+ *     >
+ *   >({ url: 'https://api.example.com/data', method: 'GET', hasCatchError: true })
+ *   .then((response) => {
+ *     console.log(response.catchError);
+ *     // => (property) CustomResponse<T = unknown>.catchError?: unknown
+ *     console.log(response.data.list);
+ *     // => (property) list?: string[] | undefined
+ *   });
+ * ```
+ *
+ * @example Finally, you can also use `RequestTransaction` to create a complete api client
+ * ```typescript
+ * // catch plugin
+ * interface CatchPluginConfig {
+ *   hasCatchError?: boolean;
+ * }
+ * interface CatchPluginResponseData {
+ *   catchError?: unknown;
+ * }
+ *
+ * // The main api client configuration
+ * // You can inherit multiple config types from other plugins
+ * interface ApiClientConfig extends RequestAdapterConfig, CatchPluginConfig {}
+ *
+ * // The main api client response type
+ * // You can inherit multiple response types from other plugins
+ * interface ApiClientResponse<T = unknown>
+ *   extends RequestAdapterResponse<unknown, T>,
+ *     CatchPluginResponseData {}
+ *
+ * // Independently declare a specific method Transaction
+ * interface ApiTestTransaction
+ *   extends RequestTransactionInterface<
+ *     ApiClientConfig,
+ *     ApiClientResponse<{ list: string[] }>
+ *   > {}
+ * class ApiClient extends RequestTransaction<ApiClientConfig> {
+ *   // If you don't require displaying the return type of the method
+ *   // Automatically deduce: Promise<ApiClientResponse<{ list: string[] }>>
+ *   test() {
+ *     return this.request<ApiTestTransaction>({
+ *       url: 'https://api.example.com/data',
+ *       method: 'GET',
+ *       hasCatchError: true
+ *     });
+ *   }
+ *
+ *   // Displayly declare
+ *   test2(data: ApiTestTransaction['request']): Promise<ApiTestTransaction['response']> {
+ *     return this.request({
+ *       url: 'https://api.example.com/data',
+ *       method: 'GET',
+ *       hasCatchError: true,
+ *       data
+ *     });
+ *   }
+ * }
+ *
+ * // Call the test method
+ *
+ * const req = new ApiClient(new RequestAdapterFetch());
+ *
+ * req.test().then((response) => {
+ *   console.log(response.catchError);
+ *   // => (property) CustomResponse<T = unknown>.catchError?: unknown
+ *   console.log(response.data.list);
+ *   // => (property) list?: string[] | undefined
+ * });
+ * ```
+ *
+ * If you are not satisfied with `RequestTransaction`, you can completely rewrite your own `RequestTransaction`.
+ *
+ * Only need to inherit `RequestManager` and override the `request` method.
+ *
+ * Finally, if you don't need typescript support, then it's basically the same as `RequestScheduler`,
+ * except that some of the shortcuts have different parameters.
+ *
+ * @since 1.2.2
+ */
+declare class RequestTransaction<Config extends RequestAdapterConfig<unknown>> extends RequestManager<Config> {
+    /**
+     * Makes an HTTP request with flexible type definitions
+     * @template Transaction - Can be either the direct response data type or a RequestTransactionInterface
+     * @param config - Request configuration object
+     * @returns Promise of response data
+     */
+    request<Transaction = unknown>(config: Transaction extends RequestTransactionInterface<Config, unknown> ? Transaction['request'] : Config): Promise<Transaction extends RequestTransactionInterface<Config, unknown> ? Transaction['response'] : RequestAdapterResponse<unknown, Transaction>>;
+    /**
+     * Sends a GET request
+     * @template Transaction - Response data type or RequestTransactionInterface
+     * @param {string} url - The URL to send the request to
+     * @param {Omit<Config, 'url' | 'method'>} [config] - Additional configuration options
+     */
+    get<Transaction = unknown>(url: string, config?: Omit<Config, 'url' | 'method'>): Promise<Transaction extends RequestTransactionInterface<Config, unknown> ? Transaction['response'] : RequestAdapterResponse<unknown, Transaction>>;
+    /**
+     * Sends a POST request
+     * @template Transaction - Response data type or RequestTransactionInterface
+     * @param {string} url - The URL to send the request to
+     * @param {Transaction extends RequestTransactionInterface<Config, unknown> ? Transaction['request']['data'] : Config['data']} [data] - The data to be sent in the request body
+     * @param {Omit<Config, 'url' | 'method' | 'data'>} [config] - Additional configuration options
+     */
+    post<Transaction = unknown>(url: string, data?: Transaction extends RequestTransactionInterface<Config, unknown> ? Transaction['request']['data'] : Config['data'], config?: Omit<Config, 'url' | 'method' | 'data'>): Promise<Transaction extends RequestTransactionInterface<Config, unknown> ? Transaction['response'] : RequestAdapterResponse<unknown, Transaction>>;
+    /**
+     * Sends a PUT request
+     * @template Transaction - Response data type or RequestTransactionInterface
+     * @param {string} url - The URL to send the request to
+     * @param {Transaction extends RequestTransactionInterface<Config, unknown> ? Transaction['request']['data'] : Config['data']} [data] - The data to be sent in the request body
+     * @param {Omit<Config, 'url' | 'method' | 'data'>} [config] - Additional configuration options
+     */
+    put<Transaction = unknown>(url: string, data?: Transaction extends RequestTransactionInterface<Config, unknown> ? Transaction['request']['data'] : Config['data'], config?: Omit<Config, 'url' | 'method' | 'data'>): Promise<Transaction extends RequestTransactionInterface<Config, unknown> ? Transaction['response'] : RequestAdapterResponse<unknown, Transaction>>;
+    /**
+     * Sends a DELETE request
+     * @template Transaction - Response data type or RequestTransactionInterface
+     * @param {string} url - The URL to send the request to
+     * @param {Omit<Config, 'url' | 'method'>} [config] - Additional configuration options
+     */
+    delete<Transaction = unknown>(url: string, config?: Omit<Config, 'url' | 'method'>): Promise<Transaction extends RequestTransactionInterface<Config, unknown> ? Transaction['response'] : RequestAdapterResponse<unknown, Transaction>>;
+    /**
+     * Sends a PATCH request
+     * @template Transaction - Response data type or RequestTransactionInterface
+     * @param {string} url - The URL to send the request to
+     * @param {Transaction extends RequestTransactionInterface<Config, unknown> ? Transaction['request']['data'] : Config['data']} [data] - The data to be sent in the request body
+     * @param {Omit<Config, 'url' | 'method' | 'data'>} [config] - Additional configuration options
+     */
+    patch<Transaction = unknown>(url: string, data?: Transaction extends RequestTransactionInterface<Config, unknown> ? Transaction['request']['data'] : Config['data'], config?: Omit<Config, 'url' | 'method' | 'data'>): Promise<Transaction extends RequestTransactionInterface<Config, unknown> ? Transaction['response'] : RequestAdapterResponse<unknown, Transaction>>;
+}
+
 /**
  * Enhanced JSON serialization implementation that combines standard JSON API with additional features
  *
@@ -2570,5 +2833,5 @@ declare class JSONStorage implements SyncStorage<string> {
     clear(): void;
 }
 
-export { AsyncExecutor, Base64Serializer, Executor, ExecutorError, FetchAbortPlugin, FetchURLPlugin, JSONSerializer, JSONStorage, LEVELS, Logger, RequestAdapterAxios, RequestAdapterFetch, RequestError, RequestErrorID, RequestScheduler, RetryPlugin, SyncExecutor };
-export type { AsyncStorage, Encryptor, ExecOptions, ExecutorContext, ExecutorPlugin, HookRuntimes, Intersection, LogArgument, LogLevel, PromiseTask, RequestAdapterConfig, RequestAdapterFetchConfig, RequestAdapterInterface, RequestAdapterResponse, RetryOptions, Serializer, SyncStorage, SyncTask, Task, ValueOf };
+export { AsyncExecutor, Base64Serializer, Executor, ExecutorError, FetchAbortPlugin, FetchURLPlugin, JSONSerializer, JSONStorage, LEVELS, Logger, RequestAdapterAxios, RequestAdapterFetch, RequestError, RequestErrorID, RequestManager, RequestScheduler, RequestTransaction, RetryPlugin, SyncExecutor };
+export type { AsyncStorage, Encryptor, ExecOptions, ExecutorContext, ExecutorPlugin, HookRuntimes, Intersection, LogArgument, LogLevel, PromiseTask, RequestAdapterConfig, RequestAdapterFetchConfig, RequestAdapterInterface, RequestAdapterResponse, RequestTransactionInterface, RetryOptions, Serializer, SyncStorage, SyncTask, Task, ValueOf };