@cloudcome/utils-core/dist/async.d.ts

cloudcome core utils

import { AnyArray } from './types';
/**
 * 异步任务队列的配置选项
 */
export type AsyncQueueOptions = {
    /**
     * 并发限制数，0 表示无限制
     * @default 0
     */
    limit?: number;
};
/**
 * 异步任务队列，用于管理和控制异步任务的执行
 * @template T - 任务返回值的类型
 */
export declare class AsyncQueue<T> {
    #private;
    readonly options?: AsyncQueueOptions | undefined;
    /**
     * 创建一个异步任务队列
     * @param asyncFns - 要执行的异步函数数组
     * @param options - 队列配置选项
     */
    constructor(asyncFns: Array<() => Promise<T>>, options?: AsyncQueueOptions | undefined);
    get length(): number;
    get limit(): number;
    push(afn: () => Promise<T>): Promise<T>;
    unshift(afn: () => Promise<T>): Promise<T>;
    get startSettled(): boolean;
    /**
     * 启动队列中的任务执行
     * @returns 返回一个 Promise，在所有启动任务完成后解析为结果数组
     */
    start(): Promise<T[]>;
    get stopSettled(): boolean;
    /**
     * 终止队列中的任务执行，终止队列后不再可以追加异步任务
     * @returns 返回一个 Promise，在所有启动任务完成后解析为结果数组
     */
    stop(): Promise<T[]>;
}
/**
 * 使用给定的并发限制执行异步函数
 *
 * 此函数的目的是控制一组异步函数的并发执行数量，通过创建一个AsyncQueue实例来管理这些异步函数的执行
 * 它确保在任何给定时间只有最多`limit`数量的异步函数被执行，以避免潜在的性能问题或资源竞争
 *
 * @param asyncFns 一个包含异步函数的数组，每个异步函数都不需要参数，并返回一个Promise
 * @param limit 并发限制的数量，表示同时执行的异步函数的最大数量，0 表示不限制
 * @returns 返回一个Promise，当所有异步函数都执行完毕后，该Promise将被解析
 */
export declare function asyncLimit<T>(asyncFns: Array<() => Promise<T>>, limit: number): Promise<T[]>;
/**
 * 异步共享函数的配置选项
 */
export type AsyncSharedOptions<I extends AnyArray, O> = {
    /**
     * 是否在调用结束后再执行（只在运行期间有再次调用时才会生效）
     * @type {boolean}
     * @default false
     * @example
     * const sharedFn = asyncShared(fetchData, { trailing: true });
     * // 如果在 fetchData 执行期间多次调用 sharedFn，则会在 fetchData 结束后再次执行
     */
    trailing?: boolean;
    /**
     * 缓存结果的最大有效期（毫秒）
     * @type {number}
     * @example
     * const sharedFn = asyncShared(fetchData, { maxAge: 1000 });
     * // 在 1 秒内调用 sharedFn 会直接返回缓存结果
     */
    maxAge?: number;
    /**
     * 在调用共享函数时触发的回调函数
     * @param inputs - 传递给共享函数的参数
     * @example
     * const options: AsyncSharedOptions<typeof fetchData> = {
     *   onTrigger: (...args) => console.log('Calling with:', args)
     * };
     */
    onTrigger?: (...inputs: I) => unknown;
    /**
     * 在执行异步函数时触发的回调函数
     * @param args - 传递给异步函数的参数
     * @example
     * const options: AsyncSharedOptions<typeof fetchData> = {
     *   onExecute: (...args) => console.log('Executing with:', args)
     * };
     */
    onExecute?: (...args: I) => unknown;
    /**
     * 在异步函数成功执行后触发的回调函数
     * @param output - 异步函数的返回结果
     * @example
     * const options: AsyncSharedOptions<typeof fetchData> = {
     *   onSuccess: (result) => console.log('Success:', result)
     * };
     */
    onSuccess?: (output: O) => unknown;
    /**
     * 在异步函数执行失败时触发的回调函数
     * @param error - 异步函数抛出的错误
     * @example
     * const options: AsyncSharedOptions<typeof fetchData> = {
     *   onError: (error) => console.error('Error:', error)
     * };
     */
    onError?: (error: unknown) => unknown;
    /**
     * 在异步函数执行完成（无论成功或失败）时触发的回调函数
     * @example
     * const options: AsyncSharedOptions<typeof fetchData> = {
     *   onFinally: () => console.log('Execution completed')
     * };
     */
    onFinally?: () => unknown;
};
/**
 * 创建一个共享执行结果的异步函数
 * @template F - 异步函数类型
 * @param {F} af - 要共享的异步函数
 * @param {AsyncSharedOptions} [options] - 配置选项
 * @returns {F} 返回一个新的异步函数，该函数会共享执行结果
 * @example
 * const fetchData = async (id) => {
 *   // 模拟异步操作
 *   return await fetch(`/api/data/${id}`);
 * };
 *
 * const sharedFetch = asyncShared(fetchData, { maxAge: 1000 });
 *
 * // 多次调用会共享同一个请求
 * const result1 = await sharedFetch(1);
 * const result2 = await sharedFetch(1); // 上次请求完成后 1000ms 内直接返回缓存结果
 */
export declare function asyncShared<I extends AnyArray, O>(af: (...inputs: I) => Promise<O>, options?: AsyncSharedOptions<I, O>): (...inputs: I) => Promise<O>;