@net-vert/core 0.5.1 → 1.2.0

package/dist/index.d.ts

@@ -1,17 +1,99 @@
+import { AnyRecord } from 'store-vert';
+import { EnhancedStore } from 'store-vert';
+import { Key as Key_2 } from 'store-vert';
+import { Store } from 'store-vert';
+import { StoreFactory } from 'store-vert';
+import { StoreKey } from 'store-vert';
 import { TaskQueue } from 'id-queue';
 
-declare type CachedData = {
-    value: any;
-    expiresAt: number;
+export declare type BaseRequestor = (config: RequestConfig<any>) => any;
+
+/**
+ * 缓存中间件
+ * 支持：
+ * - 自定义缓存 key 生成
+ * - 自定义缓存有效期（固定时长或动态计算）
+ * - 自定义缓存有效性校验
+ * - 自定义存储介质
+ */
+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?: R;
+}
+
+/**
+ * 缓存 + 幂等组合配置（扁平化）
+ */
+export declare type CachedIdempotentConfig<D = any, R = any> = FlattenWithInstanceKey<[
+CacheOptions<D, R>,
+IdempotencyOptions<D>
+]>;
+
+/** 缓存 key 类型 */
+export declare type CacheKey = string | number | symbol;
+
+/** 请求前上下文：生成缓存 key */
+declare interface CacheKeyContext<D = any> {
+    config: RequestConfig<D>;
+}
+
+/** 缓存中间件类型（带 storage 实例）*/
+declare type CacheMiddleware<D = any, R = any> = TypedMiddleware<MIDDLEWARE_TYPE.CACHE, false, D, R> & {
+    storage: CacheStorageInstance<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>;
+    /** 缓存介质 */
+    store: StoreDescriptor;
+}
+
+declare type CacheSchema<R> = Record<CacheKey, R>;
+
+declare type CacheStorageInstance<R = any> = ExpirableCacheStorage<R> & EnhancedStore<ExpirableSchema<CacheSchema<R>>>;
+
+/** 请求后上下文：更新缓存 */
+declare interface CacheUpdateContext<D = any, R = any> {
+    key: CacheKey;
+    config: RequestConfig<D>;
+    cachedData?: 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 +101,227 @@ 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 class ExpirableCacheStorage<R = any> {
+    store: EnhancedStore<ExpirableSchema<CacheSchema<R>>>;
+    constructor(store: StoreDescriptor);
+    /**
+     * 设置缓存（自动包装成 ExpirableValue）
+     * @param key 缓存 key
+     * @param value 要缓存的值
+     * @param duration 过期时长（毫秒），默认 24 小时
+     */
+    setCache(key: CacheKey, value: R, duration?: number): void;
+    /**
+     * 获取缓存值（检查过期，如果过期返回 undefined）
+     * @param key 缓存 key
+     * @returns 未过期返回值，已过期返回 undefined
+     */
+    getCache(key: CacheKey): Promise<R | undefined>;
+    /**
+     * 检查是否有有效的缓存（未过期）
+     * @param key 缓存 key
+     * @returns true 表示有有效缓存，false 表示无缓存或已过期
+     */
+    hasValidCache(key: CacheKey): Promise<boolean>;
+}
+
+/**
+ * 将 Schema 的所有值类型映射为 ExpirableValue 包装的版本
+ * 用于缓存存储的类型转换
+ */
+export declare type ExpirableSchema<Schema extends AnyRecord> = {
+    [K in keyof Schema]: ExpirableValue<Schema[K]>;
+};
 
-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]>;
+
+/**
+ * 组合工具：扁平化多个对象类型并添加 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 IsValidParams = {
-    key: string;
-    config: UnifiedConfig;
-    cachedData: CachedData;
+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;
+declare type IdempotencyOptions<D = any> = {
+    key: (params: IdempotencyContext<D>) => string;
+};
+
+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;
+
+export declare type Key = string | symbol | number;
+
+export declare type MaybePromise<IsSync, R> = IsSync extends true ? R : IsSync extends false ? Promise<R> : R | Promise<R>;
+
+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;
-    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;
-        };
-    };
-};
-
-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;
+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;
+
+export declare type StoreDescriptor = StoreKey | {
+    key: Key_2;
+    factory: StoreFactory<Store<AnyRecord>, any[]>;
+};
+
+/**
+ * 缓存中有数据则直接返回。
+ * 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 +332,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?: string) => Requestor;
+export declare const useRequestor: (instanceKey?: Key) => BaseRequestor;
 
-declare type WithDynamicProps<T, V = any> = T & Record<string, V>;
+/**
+ * 给类型添加可选的 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;
+};
+
+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 { }