com-tools/dist/function.d.ts

com-tools 提供了一些通用的工具函数；

import type { AnyFunction } from "type-tls";
/**
 * 函数包装的基础选项
 */
export interface FrequencyWrapOptions<T extends AnyFunction = AnyFunction> {
    /** 要包装的函数 */
    fn: T;
    /** 时间间隔，单位：毫秒 */
    interval: number;
}
/**
 * throttle 的选项
 */
export interface ThrottleOptions<T extends AnyFunction = AnyFunction> extends FrequencyWrapOptions<T> {
    /** 是否在间隔结束后执行最后一次调用，默认 true */
    trailing?: boolean | null;
}
/**
 * 节流函数：在指定时间间隔内，函数最多执行一次
 * @param options - 选项，创建后修改选项值会立即生效
 */
export declare function throttle<T extends AnyFunction>(options: ThrottleOptions<T>): T;
/**
 * debounce 的选项
 */
export interface DebounceOptions<T extends AnyFunction = AnyFunction> extends FrequencyWrapOptions<T> {
    /** 是否在等待开始时立即执行，默认 false */
    leading?: boolean | null;
}
/**
 * 防抖函数：在最后一次调用后等待指定时间，若期间无新调用则执行
 * @param options - 选项，创建后修改选项值会立即生效
 */
export declare function debounce<T extends AnyFunction>(options: DebounceOptions<T>): T;
/**
 * cachedCall 的选项
 */
export interface CachedFrequencyWrapOptions<Fun extends AnyFunction = AnyFunction> extends FrequencyWrapOptions<Fun> {
    /** 是否在缓存值为空时重新调用 fn，默认 false */
    nonNull?: boolean | null;
}
/**
 * 缓存调用：在指定时间间隔内重复调用时返回上一次的返回值，间隔过后重新执行并缓存新结果
 * @param options - 选项，创建后修改选项值会立即生效
 */
export declare function cachedCall<Fun extends AnyFunction>(options: CachedFrequencyWrapOptions<Fun>): Fun;
/**
 * asyncCachedCall 的选项
 */
export interface AsyncCachedCallOptions<Fun extends (...args: any) => Promise<any> = (...args: any) => Promise<any>> extends FrequencyWrapOptions<Fun> {
    /** fn 调用失败时是否忽略错误，为 true 时回退返回上一次成功的缓存值（若尚无缓存值仍会抛出错误），默认 false */
    ignoreError?: boolean | null;
}
/**
 * 异步缓存调用：到达间隔后调用 fn 获取新值并缓存；未到达间隔时直接返回上一次成功的缓存值
 * 在 fn 的异步结果到达之前重复调用会等待同一个进行中的调用，返回相同的结果，不会拿到旧的缓存值也不会重复触发 fn；fn 调用失败时不推进间隔，下一次调用会立即重试
 * @param options - 选项，创建后修改选项值会立即生效
 */
export declare function asyncCachedCall<Fun extends (...args: any) => Promise<any>>(options: AsyncCachedCallOptions<Fun>): Fun;
/**
 * sharedCachedCall 的选项
 */
export interface SharedCachedCallOptions<Fun extends AnyFunction = AnyFunction> extends FrequencyWrapOptions<Fun> {
    /** 获取缓存值的函数，在未到达调用间隔时用来获取最后一次调用的值；入参为本次调用的 this */
    getValue: (this: ThisParameterType<Fun>, thisArg: ThisParameterType<Fun>) => Awaited<ReturnType<Fun>>;
    /** 判断本次调用是否应当（重新）开始计时的函数，入参依次为 fn 刚获取的值、本次调用的 this；省略时总是重新计时（等价于返回 true）。适用于 fn 自身返回值带有起点未知的有效期（如内部已有缓存）的场景，通过该函数探测有效期的起点，使自身计时和 fn 内部周期对齐 */
    shouldRestart?: ((this: ThisParameterType<Fun>, value: Awaited<ReturnType<Fun>>, thisArg: ThisParameterType<Fun>) => boolean | null | undefined) | null;
}
/**
 * 共享缓存调用：目标值可能由多个函数获取，每个函数各自限制调用间隔，缓存值由外部（如共享变量）统一维护
 * 未到达间隔时调用 getValue 获取最后一次调用的值；到达间隔后调用 fn 获取新值并返回；若指定了 shouldRestart，只有其返回 true 时才会以本次调用为起点重新计时，否则不推进间隔，下一次调用会立即重试 fn
 * @param options - 选项，创建后修改选项值会立即生效
 */
export declare function sharedCachedCall<Fun extends AnyFunction>(options: SharedCachedCallOptions<Fun>): Fun;
/**
 * asyncSharedCachedCall 的选项
 */
export interface AsyncSharedCachedCallOptions<Fun extends (...args: any) => Promise<any> = (...args: any) => Promise<any>> extends SharedCachedCallOptions<Fun> {
    /** fn 调用失败时是否忽略错误，为 true 时回退调用 getValue 获取缓存值，默认 false */
    ignoreError?: boolean | null;
}
/**
 * 异步共享缓存调用：目标值可能由多个函数获取，每个函数各自限制调用间隔，缓存值由外部（如共享变量）统一维护
 * 未到达间隔时调用 getValue 获取最后一次调用的值；到达间隔后调用 fn 获取新值；在 fn 的异步结果到达之前重复调用会等待同一个进行中的调用，防止误读旧缓存值或重复发起调用
 * 若指定了 shouldRestart，只有其返回 true 时才会以本次调用为起点重新计时；fn 调用失败或 shouldRestart 返回 false 时都不推进间隔，下一次调用会立即重试
 * @param options - 选项，创建后修改选项值会立即生效
 */
export declare function asyncSharedCachedCall<Fun extends (...args: any) => Promise<any>>(options: AsyncSharedCachedCallOptions<Fun>): Fun;
//# sourceMappingURL=function.d.ts.map