@net-vert/core 0.5.1 → 1.0.0

package/dist/index.d.ts

@@ -1,17 +1,187 @@
 import { TaskQueue } from 'id-queue';
 
-declare type CachedData = {
-    value: any;
-    expiresAt: number;
+declare type AnyRecord = Record<string | number | symbol, any>;
+
+declare type AnyRecord_2 = Record<string, any>;
+
+/**
+ * 缓存存储基类
+ * 提供针对缓存场景的快捷方法，自动处理 ExpirableValue 的封装和解封
+ */
+declare abstract class BaseCacheStorage<K extends string | number | symbol, R> {
+    abstract getItem(key: K): ExpirableValue<R> | undefined;
+    abstract setItem(key: K, value: ExpirableValue<R>): ExpirableValue<R>;
+    abstract removeItem(key: K): void;
+    abstract clear(): void;
+    abstract length(): number;
+    abstract keys(): K[];
+    abstract iterate(iteratee: (value: ExpirableValue<R>, key: K, iterationNumber: number) => void): void;
+    /**
+     * 获取缓存值（自动处理过期检查和解包）
+     * @param key 缓存键
+     * @returns 缓存的原始值，如果不存在或已过期返回 undefined
+     */
+    get(key: K): R | undefined;
+    /**
+     * 设置缓存值（自动包装为 ExpirableValue）
+     * @param key 缓存键
+     * @param value 要缓存的值
+     * @param duration 有效期（毫秒），默认 24 小时
+     */
+    set(key: K, value: R, duration?: number): void;
+    /**
+     * 删除指定缓存（别名方法，等同于 removeItem）
+     * @param key 缓存键
+     */
+    delete(key: K): void;
+    /**
+     * 检查缓存是否存在且未过期
+     * @param key 缓存键
+     */
+    has(key: K): boolean;
+    /**
+     * 获取缓存数量（别名方法，等同于 length）
+     */
+    size(): number;
+    /**
+     * 遍历所有有效的缓存（自动跳过已过期的，并解包值）
+     * @param callback 回调函数，接收解包后的值、键和索引
+     */
+    forEach(callback: (value: R, key: K, index: number) => void): void;
+    /**
+     * 清理所有过期的缓存
+     * @returns 清理的缓存数量
+     */
+    clearExpired(): number;
+    /**
+     * 更新缓存的过期时间（不改变值）
+     * @param key 缓存键
+     * @param duration 新的有效期（毫秒）
+     * @returns 是否更新成功
+     */
+    touch(key: K, duration: number): boolean;
+}
+
+export declare type BaseRequestor = (config: RequestConfig<any>) => any;
+
+/**
+ * 缓存中间件
+ * 支持：
+ * - 自定义缓存 key 生成
+ * - 自定义缓存有效期（固定时长或动态计算）
+ * - 自定义缓存有效性校验
+ * - 持久化存储（LocalStorage）或内存存储
+ */
+export declare const cache: <D = any, R = any>(options?: Partial<CacheOptions<D, R>>) => CacheMiddleware<D, R>;
+
+/** 请求前上下文：检查缓存是否有效 */
+declare interface CacheCheckContext<D = any, R = any> {
+    key: CacheKey;
+    config: RequestConfig<D>;
+    cachedData?: ExpirableValue<R>;
+}
+
+/**
+ * 缓存 + 幂等组合配置（扁平化）
+ */
+export declare type CachedIdempotentConfig<D = any, R = any> = FlattenWithInstanceKey<[
+CacheOptions<D, R>,
+IdempotencyOptions<D>
+]>;
+
+/** 缓存 key 类型 */
+declare type CacheKey = string | number | symbol;
+
+/** 请求前上下文：生成缓存 key */
+declare interface CacheKeyContext<D = any> {
+    config: RequestConfig<D>;
+}
+
+/**
+ * 基于 LocalStorage 的缓存存储
+ * 继承 LocalStorage 并扩展缓存快捷方法
+ */
+declare class CacheLocalStorage<K extends string | number | symbol = string, R = any> extends LocalStorage<Record<K, ExpirableValue<R>>> implements BaseCacheStorage<K, R> {
+    get: (key: any) => any;
+    set: (key: any, value: any, duration?: number) => void;
+    delete: (key: any) => void;
+    has: (key: any) => boolean;
+    size: () => number;
+    forEach: (callback: (value: any, key: any, index: number) => void) => void;
+    clearExpired: () => number;
+    touch: (key: any, duration: number) => boolean;
+}
+
+/**
+ * 基于内存的缓存存储
+ * 继承 MemoryStorage 并扩展缓存快捷方法
+ */
+declare class CacheMemoryStorage<K extends string | number | symbol = string, R = any> extends MemoryStorage<Record<K, ExpirableValue<R>>> implements BaseCacheStorage<K, R> {
+    get: (key: any) => any;
+    set: (key: any, value: any, duration?: number) => void;
+    delete: (key: any) => void;
+    has: (key: any) => boolean;
+    size: () => number;
+    forEach: (callback: (value: any, key: any, index: number) => void) => void;
+    clearExpired: () => number;
+    touch: (key: any, duration: number) => boolean;
+}
+
+/** 缓存中间件类型（带 storage 实例）*/
+declare type CacheMiddleware<D = any, R = any> = TypedMiddleware<MIDDLEWARE_TYPE.CACHE, false, D, R> & {
+    storage: CacheStorage_2<CacheKey, R>;
+};
+
+/** 缓存模块配置 */
+declare interface CacheOptions<D = any, R = any> {
+    /**
+     * 缓存 key 生成函数
+     * 默认使用 method + url 哈希
+     */
+    key: (ctx: CacheKeyContext<D>) => CacheKey;
+    /**
+     * 缓存有效期
+     * - number: 固定毫秒数
+     * - function: 可根据请求或响应动态计算
+     */
+    duration: number | ((ctx: CacheUpdateContext<D, R>) => number);
+    /**
+     * 判断缓存是否有效（请求前）
+     * - 可以根据现有缓存数据或其他条件动态判断
+     * - 返回 boolean 或 Promise<boolean>
+     */
+    isValid: (ctx: CacheCheckContext<D, R>) => boolean | Promise<boolean>;
+    /** 缓存介质, 待开发, 目前只支持内存和持久化 */
+    persist: boolean;
+}
+
+/**
+ * CacheStorage 类型别名
+ * 可以是 CacheMemoryStorage 或 CacheLocalStorage
+ */
+declare type CacheStorage_2<K extends string | number | symbol = string, R = any> = CacheMemoryStorage<K, R> | CacheLocalStorage<K, R>;
+
+/** 请求后上下文：更新缓存 */
+declare interface CacheUpdateContext<D = any, R = any> {
+    key: CacheKey;
+    config: RequestConfig<D>;
+    cachedData?: ExpirableValue<R>;
+    response: R;
+}
+
+export declare const concurrent: <D = any, R = any>(options?: Partial<ConcurrentOptions<D>>) => ConcurrentMiddleware<D, R>;
+
+declare type ConcurrentContext<D = any> = {
+    config: RequestConfig<D>;
+};
+
+declare type ConcurrentMiddleware<D = any, R = any> = TypedMiddleware<MIDDLEWARE_TYPE.CONCURRENT, false, D, R> & {
+    pool: ConcurrentPool;
 };
 
-declare type CacheRequestor<P extends boolean, S extends boolean> = {
-    key?: (config: UnifiedConfig) => string;
-    duration?: Duration;
-    sync?: S;
-    persist?: P;
-    name?: [P, S] extends [true, false] ? string : undefined;
-    isValid?: S extends true ? (params: IsValidParams) => boolean : (params: IsValidParams) => boolean | Promise<boolean>;
+declare type ConcurrentOptions<D = any> = {
+    parallelCount: number;
+    createId: (params: ConcurrentContext<D>) => Id;
 };
 
 declare class ConcurrentPool<T extends any = any> {
@@ -19,141 +189,251 @@ declare class ConcurrentPool<T extends any = any> {
     tasks: TaskItemList<T>;
     runningCount: number;
     constructor(parallelCount?: number);
-    add(id: string, task: Task<T>): Promise<unknown>;
-    remove(id: string): void;
+    add(id: Id, task: Task<T>): Promise<T>;
+    remove(id: Id): void;
     execute(currentTask: TaskItem<T>): Promise<void>;
     _run(): void;
 }
 
-declare type Duration = number | (({ key, config, response }: {
-    key: string;
-    config: UnifiedConfig;
-    response: any;
-}) => number);
+/**
+ * 并发 + 重试组合配置（扁平化）
+ */
+export declare type ConcurrentRetryConfig<D = any> = FlattenWithInstanceKey<[
+ConcurrentOptions<D>,
+RetryOptions<D>
+]>;
+
+/**
+ * 创建带缓存和幂等的请求器
+ * 适用场景：数据查询接口，既需要缓存提升性能，又要避免重复请求
+ * @param config 组合配置对象
+ */
+export declare function createCachedIdempotentRequestor<D = any, R = any>(config: CachedIdempotentConfig<D, R>): Requestor<false>;
+
+/**
+ * 创建带并发控制和重试的请求器
+ * 适用场景：批量请求场景，需要控制并发数量，失败后自动重试
+ * @param config 组合配置对象
+ */
+export declare function createConcurrentRetryRequestor<D = any>(config: ConcurrentRetryConfig<D>): Requestor<false>;
+
+declare const createPromiseCache: () => {
+    getPromise: <T = unknown>(key: SafeKey) => Promise<T> | undefined;
+    setPromise: <T = unknown>(key: SafeKey, promise: Promise<T>) => void;
+    delPromise: (key: SafeKey) => boolean;
+    clearCache: () => void;
+};
+
+export declare function createRequestor<const Extensions extends readonly Middleware[]>(config: CreateRequestorConfig<Extensions> & {
+    extensions: Extensions;
+}): Requestor<HasSyncMiddleware<Extensions>>;
+
+export declare function createRequestor(config?: CreateRequestorConfig): Requestor<false>;
+
+export declare interface CreateRequestorConfig<Extensions extends readonly Middleware[] = readonly Middleware[]> {
+    extensions?: Extensions;
+    instanceKey?: Key;
+}
 
-declare type IdempotencyOptions = {
-    key?: (config: UnifiedConfig) => string;
-    duration?: number;
+/**
+ * 带过期时间的值类型（通用型）
+ * 可用于缓存、幂等、同步等需要时间控制的场景
+ */
+export declare type ExpirableValue<T = any> = {
+    value: T;
+    expireAt: number;
 };
 
-export declare const inject: (requestor: UnifiedRequestor, instanceKey?: string) => void;
+/**
+ * 扁平化多个对象类型
+ * @template Types - 需要扁平化的对象类型元组
+ * @example
+ * ```ts
+ * type Result = Flatten<[{ a: string }, { b: number }, { c: boolean }]>
+ * // Result = { a: string } & { b: number } & { c: boolean }
+ * ```
+ */
+export declare type Flatten<Types extends readonly any[]> = UnionToIntersection<Types[number]>;
 
-declare type IsValidParams = {
-    key: string;
-    config: UnifiedConfig;
-    cachedData: CachedData;
+/**
+ * 组合工具：扁平化多个对象类型并添加 instanceKey
+ * @template Types - 需要扁平化的对象类型元组
+ * @example
+ * ```ts
+ * type Result = FlattenWithInstanceKey<[TypeA, TypeB, TypeC]>
+ * // Result = TypeA & TypeB & TypeC & { instanceKey?: Key }
+ * ```
+ */
+export declare type FlattenWithInstanceKey<Types extends readonly any[]> = WithInstanceKey<Flatten<Types>>;
+
+export declare type HandlerParams<T extends keyof Requestor> = Parameters<Requestor[T]>;
+
+export declare type HasSyncMiddleware<T extends readonly any[]> = T extends readonly [infer First, ...infer Rest] ? First extends TypedMiddleware<MIDDLEWARE_TYPE.SYNC, true, any, any> ? true : HasSyncMiddleware<Rest> : false;
+
+declare type Id = string | number;
+
+declare type IdempotencyContext<D = any> = {
+    config: RequestConfig<D>;
 };
 
-declare interface RequestConfig<D = any> {
-    url?: string;
-    method?: Exclude<keyof Requestor, "request">;
-    baseURL?: string;
-    headers?: Record<string, any>;
-    params?: Record<string, any> | string;
-    data?: D;
-    timeout?: number;
-    onUploadProgress?: <P extends ProgressEvent>(progressEvent: P) => void;
-    onDownloadProgress?: <P extends ProgressEvent>(progressEvent: P) => void;
-    validateStatus?: ((status: number) => boolean) | null;
-    signal?: AbortSignal;
-}
-
-export declare const requestExtender: {
-    cacheRequestor: <P extends boolean = false, S extends boolean = false>(config?: CacheRequestor<P, S>) => {
-        requestor: Requestor;
-        store: {
-            has(key: string): boolean;
-            get<T>(key: string): T | undefined;
-            set<T>(key: string, value: T): T;
-            remove(key: string): void;
-            clear(): void;
-        } | {
-            has: (key: string) => Promise<boolean>;
-            get: <T>(key: string) => Promise<T | null>;
-            set: <T>(key: string, value: T) => Promise<T>;
-            remove: (key: string) => Promise<void>;
-            clear: () => Promise<void>;
-        } | {
-            has: (key: string) => boolean;
-            get: (key: string) => any;
-            set: <T>(key: string, value: T) => Map<string, any>;
-            remove: (key: string) => boolean;
-            clear: () => void;
-        };
-    };
-    idempotencyRequestor: (config?: IdempotencyOptions) => {
-        requestor: Requestor;
-        store: {
-            has(key: string): boolean;
-            get<T>(key: string): T | undefined;
-            set<T>(key: string, value: T): T;
-            remove(key: string): void;
-            clear(): void;
-        } | {
-            has: (key: string) => Promise<boolean>;
-            get: <T>(key: string) => Promise<T | null>;
-            set: <T>(key: string, value: T) => Promise<T>;
-            remove: (key: string) => Promise<void>;
-            clear: () => Promise<void>;
-        } | {
-            has: (key: string) => boolean;
-            get: (key: string) => any;
-            set: <T>(key: string, value: T) => Map<string, any>;
-            remove: (key: string) => boolean;
-            clear: () => void;
-        };
-    };
-    retryRequestor: (config?: RetryOptions) => {
-        requestor: Requestor;
-    };
-    concurrentPoolRequestor: (config?: {
-        parallelCount?: number;
-        createId?: (config: UnifiedConfig) => string;
-    } & RetryOptions) => {
-        requestor: Requestor;
-        concurrentPool: ConcurrentPool<any>;
-    };
-    syncRequestor: (config?: {
-        persist?: false;
-        sync?: true;
-    } & CacheRequestor<false, true>) => {
-        requestor: Requestor;
-        store: {
-            has(key: string): boolean;
-            get<T>(key: string): T | undefined;
-            set<T>(key: string, value: T): T;
-            remove(key: string): void;
-            clear(): void;
-        } | {
-            has: (key: string) => Promise<boolean>;
-            get: <T>(key: string) => Promise<T | null>;
-            set: <T>(key: string, value: T) => Promise<T>;
-            remove: (key: string) => Promise<void>;
-            clear: () => Promise<void>;
-        } | {
-            has: (key: string) => boolean;
-            get: (key: string) => any;
-            set: <T>(key: string, value: T) => Map<string, any>;
-            remove: (key: string) => boolean;
-            clear: () => void;
-        };
-    };
+declare type IdempotencyOptions<D = any> = {
+    key: (params: IdempotencyContext<D>) => string;
 };
 
-export declare interface Requestor {
-    get<R = any, D = any>(url: string, config?: WithDynamicProps<RequestConfig<D>>): R;
-    post<R = any, D = any>(url: string, data?: D, config?: RequestConfig<D>): R;
-    delete<R = any, D = any>(url: string, config?: WithDynamicProps<RequestConfig<D>>): R;
-    put<R = any, D = any>(url: string, data?: D, config?: WithDynamicProps<RequestConfig<D>>): R;
-    request<R = any, D = any>(config: WithDynamicProps<UnifiedConfig<D>>): R;
+export declare const idempotent: <D = any, R = any>(options?: Partial<IdempotencyOptions<D>>) => IdempotentMiddleware<D, R>;
+
+declare type IdempotentMiddleware<D = any, R = any> = TypedMiddleware<MIDDLEWARE_TYPE.IDEMPOTENT, false, D, R> & {
+    promiseCache: PromiseCache;
+};
+
+export declare const inject: (requestor: BaseRequestor, instanceKey?: string) => void;
+
+/**
+ * Storage 接口
+ * 定义存储器的基本操作
+ */
+export declare interface IStorage<Schema extends Record<string, any> = Record<string, any>> {
+    /**
+     * 获取存储项
+     */
+    getItem<K extends keyof Schema>(key: K): Schema[K] | undefined;
+    /**
+     * 设置存储项
+     */
+    setItem<K extends keyof Schema>(key: K, value: Schema[K]): Schema[K];
+    /**
+     * 删除存储项
+     */
+    removeItem<K extends keyof Schema>(key: K): void;
+    /**
+     * 清空所有存储项
+     */
+    clear(): void;
+    /**
+     * 获取存储项数量
+     */
+    length(): number;
+    /**
+     * 获取所有 key
+     */
+    keys(): (keyof Schema)[];
+    /**
+     * 遍历所有存储项
+     */
+    iterate(iteratee: <K extends keyof Schema>(value: Schema[K], key: K, iterationNumber: number) => void): void;
+}
+
+export declare type Key = string | symbol | number;
+
+/**
+ * LocalStorage 存储类
+ * 基于浏览器的 localStorage 实现
+ */
+declare class LocalStorage<Schema extends AnyRecord_2 = AnyRecord_2> implements IStorage<Schema> {
+    constructor();
+    getItem<K extends keyof Schema>(key: K): Schema[K] | undefined;
+    setItem<K extends keyof Schema>(key: K, value: Schema[K]): Schema[K];
+    removeItem<K extends keyof Schema>(key: K): void;
+    clear(): void;
+    length(): number;
+    keys(): (keyof Schema)[];
+    iterate(iteratee: <K extends keyof Schema>(value: Schema[K], key: K, iterationNumber: number) => void): void;
+}
+
+export declare type MaybePromise<IsSync, R> = IsSync extends true ? R : IsSync extends false ? Promise<R> : R | Promise<R>;
+
+declare class MemoryStorage<Schema extends AnyRecord = AnyRecord> implements IStorage<Schema> {
+    private store;
+    getItem<K extends keyof Schema>(key: K): Schema[K] | undefined;
+    setItem<K extends keyof Schema>(key: K, value: Schema[K]): Schema[K];
+    removeItem<K extends keyof Schema>(key: K): void;
+    clear(): void;
+    length(): number;
+    keys(): (keyof Schema)[];
+    iterate(iteratee: <K extends keyof Schema>(value: Schema[K], key: K, iterationNumber: number) => void): void;
+}
+
+export declare type Middleware<IsSync extends boolean = false, D = any, R = any> = (context: {
+    config: RequestConfig<D>;
+    next: () => MaybePromise<IsSync, R>;
+    ctx: MiddlewareContext;
+}) => MaybePromise<IsSync, R>;
+
+declare enum MIDDLEWARE_TYPE {
+    CACHE = "cache",
+    RETRY = "retry",
+    IDEMPOTENT = "idempotent",
+    CONCURRENT = "concurrent",
+    SYNC = "sync"
+}
+
+export declare interface MiddlewareContext extends Record<string, any> {
+}
+
+declare type MiddlewareType = MIDDLEWARE_TYPE;
+
+declare type PromiseCache = ReturnType<typeof createPromiseCache>;
+
+declare enum REQUEST_METHOD {
+    GET = "get",
+    POST = "post",
+    PUT = "put",
+    DELETE = "delete"
+}
+
+export declare interface RequestConfig<D = any> extends Record<string, any> {
+    url: string;
+    method: RequestMethod;
+    data?: D;
+}
+
+declare type RequestMethod = REQUEST_METHOD;
+
+export declare interface Requestor<IsSync extends boolean = false> {
+    request: <R = any, D = any>(config: RequestConfig<D>) => MaybePromise<IsSync, R>;
+    get: <R = any, D = any>(url: string, config?: WithoutMethod<D>) => MaybePromise<IsSync, R>;
+    post: <R = any, D = any>(url: string, data?: D, config?: WithoutMethod<D>) => MaybePromise<IsSync, R>;
+    put: <R = any, D = any>(url: string, data?: D, config?: WithoutMethod<D>) => MaybePromise<IsSync, R>;
+    delete: <R = any, D = any>(url: string, config?: WithoutMethod<D>) => MaybePromise<IsSync, R>;
 }
 
-declare type RetryOptions = {
-    retries?: number;
-    delay?: number | ((attempt: number) => number);
-    retryCondition?: (error: any) => boolean;
+export declare const retry: <D = any, R = any>(options?: Partial<RetryOptions<D>>) => TypedMiddleware<MIDDLEWARE_TYPE.RETRY, false, D, R>;
+
+declare type RetryContext<D = any> = {
+    config: RequestConfig<D>;
+    lastResponse: any;
+    attempt: number;
 };
 
+declare type RetryOptions<D = any> = {
+    retries: number;
+    delay: number | ((params: RetryContext<D>) => number);
+    retryCondition: (params: RetryContext<D>) => boolean;
+};
+
+declare type SafeKey = string | number | symbol;
+
+/**
+ * 缓存中有数据则直接返回。
+ * suspense 为 true 时，会抛出一个 Promise（而不是普通错误），Promise resolve 后得到数据。
+ * suspense 为 false 时，会返回一个 Promise，Promise resolve 后得到数据，调用者需要用 await 或 .then 捕获。
+ */
+export declare function sync<D = any, R = any>(options: Partial<SyncOptions<D>> & {
+    suspense: true;
+}): TypedMiddleware<MIDDLEWARE_TYPE.SYNC, true, D, R>;
+
+export declare function sync<D = any, R = any>(options: Partial<SyncOptions<D>> & {
+    suspense: false;
+}): TypedMiddleware<MIDDLEWARE_TYPE.SYNC, any, D, R>;
+
+export declare function sync<D = any, R = any>(options?: Partial<SyncOptions<D>>): TypedMiddleware<MIDDLEWARE_TYPE.SYNC, true, D, R>;
+
+declare interface SyncOptions<D = any, R = any> extends CacheOptions<D, R> {
+    isValid: (ctx: CacheCheckContext<D, R>) => boolean;
+    suspense: boolean;
+    wrapSuspense?: (params: WrapSuspense<D, R>) => any;
+}
+
 declare type Task<T> = () => Promise<T>;
 
 declare type TaskItem<T> = {
@@ -164,15 +444,35 @@ declare type TaskItem<T> = {
 
 declare type TaskItemList<T> = TaskQueue<TaskItem<T>>;
 
-export declare type UnifiedConfig<D = any> = RequestConfig<D> & {
-    url: string;
-    method: Exclude<keyof Requestor, "request">;
+export declare type TypedMiddleware<Type extends MiddlewareType, IsSync extends boolean = false, D = any, R = any> = Middleware<IsSync, D, R> & {
+    __middlewareType: Type;
 };
 
-export declare type UnifiedRequestor = <R = any, D = any>(config: UnifiedConfig<D>) => Promise<R>;
+/* Excluded from this release type: UnionToIntersection */
+
+export declare const useRequestor: (instanceKey?: Key) => BaseRequestor;
 
-export declare const useRequestor: (instanceKey?: string) => Requestor;
+/**
+ * 给类型添加可选的 instanceKey 字段
+ * @template T - 源对象类型
+ * @example
+ * ```ts
+ * type Config = { timeout: number }
+ * type Result = WithInstanceKey<Config>
+ * // Result = { timeout: number; instanceKey?: Key }
+ * ```
+ */
+export declare type WithInstanceKey<T> = T & {
+    /** 请求器实例 key（可选） */
+    instanceKey?: Key;
+};
 
-declare type WithDynamicProps<T, V = any> = T & Record<string, V>;
+export declare type WithoutMethod<D = any> = Omit<RequestConfig<D>, 'method' | 'url'>;
+
+declare type WrapSuspense<D = any, R = any> = {
+    key: CacheKey;
+    config: RequestConfig<D>;
+    p: Promise<R>;
+};
 
 export { }