vue-asyncx 1.11.2 → 1.11.3

package/dist/vue-asyncx.d.cts

@@ -0,0 +1,769 @@
+import { ComputedRef } from 'vue';
+import { Ref } from 'vue';
+import { ShallowRef } from 'vue';
+import { WatchCallback } from 'vue';
+import { WatchOptions } from 'vue';
+import { WatchSource } from 'vue';
+
+/**
+ * 插件（Addon）定义类型。
+ *
+ * @description
+ * 插件允许在核心流程执行的不同阶段注入逻辑和状态。它支持两种形式：
+ * 1. **基础插件**：返回对象，仅参与 setup 前的 fn 监听过程
+ * 2. **高级插件**：返回函数，参与 setup **前&后**流程，获取 setup 后的 method
+ *
+ * @template Method - 管道包装的核心函数类型。
+ * @template AddonResult - 插件的结果（对象/函数）。
+ *
+ * @param params - 注入的上下文对象。
+ * @param params.monitor - 监控与追踪工具，用于观测函数执行。
+ * @param params._types - 辅助类型占位符，用于在插件内部保留 Method 的类型上下文。
+ *
+ * @example
+ * // 1. 基础插件：仅参与 setup 前的监听
+ * function withAddonLoading(): (params: {
+ *   monitor: FunctionMonitor
+ * }) => { loading: Ref<boolean> } {
+ *   return
+ * }
+ * // 2. 高级插件：需要访问最终生成的方法
+ * function withAddonData<Config extends {
+ *   type?: 'function' | 'data'
+ *   shallow?: boolean,
+ *   initialData?: any
+ * }>(config?: Config):
+ * <T extends AddonTypes>(p: { _types: T }) => () => Config['type'] extends 'function'
+ *   ? {
+ *     __name__Data: Config['shallow'] extends true
+ *       ? ShallowRef<Awaited<ReturnType<T['Method']>>>
+ *       : Ref<Awaited<ReturnType<T['Method']>>>
+ *     __name__DataExpired: Ref<boolean>
+ *   }
+ *   : {
+ *     __name__: Config['shallow'] extends true
+ *       ? ShallowRef<Awaited<ReturnType<T['Method']>>>
+ *       : Ref<Awaited<ReturnType<T['Method']>>>
+ *     __name__Expired: Ref<boolean>
+ *   } {
+ *  return
+ * }
+ */
+declare type Addon<Method extends BaseFunction = any, AddonResult = any> = (params: {
+    monitor: FunctionMonitor;
+    _types: AddonTypes<Method>;
+}) => (AddonResult | ((params: {
+    method: Method;
+}) => AddonResult));
+
+declare type Addons<Fn extends BaseFunction, AddonResults extends any[]> = {
+    [K in keyof AddonResults]: Addon<Fn, AddonResults[K]>;
+};
+
+declare interface AddonTypes<M extends BaseFunction = any> {
+    Method: M;
+}
+
+/**
+ * @fileoverview 类型工具系统
+ *
+ * 该模块提供 TypeScript 类型工具，用于支持 Vue-AsyncX 的类型推导。
+ *
+ * 主要功能：
+ * - 基础类型定义（BaseFunction、Not 等）
+ * - 字符串处理工具（CamelReplace、NonEmptyString 等）
+ * - 对象处理工具（Merge、ObjectShape 等）
+ * - 类型判断工具（IsUnion 等）
+ *
+ * 这些工具主要用于：
+ * - 插件返回类型的合并和转换
+ * - 命名约定的类型推导
+ * - 类型安全的保障
+ *
+ * @module utils/types
+ */
+/**
+ * 基础函数类型
+ *
+ * @description 匹配任何具有任意参数和返回值的函数。
+ * 用于约束函数类型，确保类型安全。
+ *
+ * @example
+ * ```ts
+ * const fn: BaseFunction = () => {}
+ * const fn2: BaseFunction = (a: number) => a
+ * ```
+ */
+declare type BaseFunction = (...args: any) => any;
+
+/**
+ * 驼峰替换工具：将字符串中的 Pattern 替换为 Replacement，并自动处理驼峰命名。
+ * @param Input        - 原始字符串 (e.g., "get__name__")
+ * @param Pattern      - 待匹配的占位符模式 (e.g., "__name__")
+ * @param Replacement  - 替换后的目标内容 (e.g., "user")
+ * @param OnNoPattern  - 【配置项】若 Input 中完全不含 Pattern 时的返回结果。
+ * 默认为 Input (保留原样)；业务中可传入 never (丢弃)。
+ * @param IsSuffix     - 【内部状态】标记当前是否已处于匹配项之后的后缀部分。
+ */
+declare type CamelReplace<Input extends string, Pattern extends string, Replacement extends string, OnNoPattern = Input, IsSuffix extends boolean = false> = Input extends `${infer Prefix}${Pattern}${infer Suffix}` ? Prefix extends "" ? `${ToCamel<Replacement, Not<IsSuffix>>}${CamelReplace<Suffix, Pattern, Replacement, OnNoPattern, true>}` : `${Prefix}${Capitalize<Replacement>}${CamelReplace<Suffix, Pattern, Replacement, OnNoPattern, true>}` : (IsSuffix extends true ? Input : OnNoPattern);
+
+/**
+ * 对象属性名驼峰替换工具：将属性名中的 Pattern 替换为 Replacement
+ *
+ * @param T               - 目标对象
+ * @param Replacement     - 替换后的名称
+ * @param Pattern         - 占位符模式，默认 '__name__'
+ * @param KeepNoPattern   - 是否保留不含 Pattern 的属性，默认 false (移除)
+ */
+declare type CamelReplaceKeys<T, Replacement extends string, Pattern extends string = '__name__', KeepNoPattern extends boolean = false> = Simplify<{
+    [K in keyof T as K extends string ? CamelReplace<K, Pattern, Replacement, KeepNoPattern extends true ? K : never> : (KeepNoPattern extends true ? K : never)]: T[K];
+}>;
+
+/**
+ * @fileoverview 异步数据上下文管理
+ *
+ * 该模块提供异步数据上下文的全局管理机制。
+ * 上下文只在函数执行的同步部分可用，用于在函数执行过程中访问和更新数据。
+ *
+ * ## 工作原理
+ *
+ * 1. 在函数调用前（before 事件），通过 `prepareAsyncDataContext` 设置上下文
+ * 2. 在函数执行期间（同步部分），可以通过 `getAsyncDataContext` 获取上下文
+ * 3. 在函数执行后（after 事件），通过恢复函数移除上下文
+ *
+ * ## 限制
+ *
+ * - 上下文只在函数执行的同步部分可用
+ * - 在异步回调中无法获取上下文（会返回 null）
+ * - 嵌套调用必须按顺序恢复上下文
+ *
+ * @module addons/data/context
+ */
+/**
+ * 上下文获取器类型
+ *
+ * @description 用于获取上下文对象的函数类型。
+ *
+ * @template D - 数据类型
+ */
+declare type ContextGetter<D = any> = () => {
+    getData: () => D;
+    updateData: (v: D) => void;
+};
+
+/**
+ * 事件处理函数类型
+ *
+ * @template T - 事件类型
+ */
+declare type EventHandler<T extends keyof FunctionMonitorEventMap> = (event: FunctionMonitorEventMap[T]) => void;
+
+declare type FirstArgumentEnhanced<T = any, D = any> = {
+    [FLAG_FIRST_ARGUMENT_ENHANCED]: true;
+    firstArgument?: T;
+    getData: () => D;
+    updateData: (v: D) => void;
+};
+
+declare const FLAG_FIRST_ARGUMENT_ENHANCED = "__va_fae";
+
+/**
+ * 函数监控器接口
+ *
+ * @description 提供函数执行生命周期的事件监控能力。
+ */
+declare type FunctionMonitor = Pick<InternalFunctionMonitor, 'on' | 'off'>;
+
+/**
+ * 函数监控器事件映射
+ *
+ * @description 定义了所有可监听的事件类型及其数据结构。
+ */
+declare type FunctionMonitorEventMap = {
+    /** 函数调用初始化事件，用于准备上下文 */
+    'init': {
+        args: any[];
+        track: Track;
+    };
+    /** 函数执行前事件，用于观察逻辑。注：enhance-arguments 发生在 before 后 */
+    'before': {
+        args: any[];
+        track: Track;
+    };
+    /** 函数执行后事件（同步部分完成） */
+    'after': {
+        track: Track;
+    };
+    /** 函数成功完成事件 */
+    'fulfill': {
+        track: Track;
+        value: any;
+    };
+    /** 函数执行失败事件 */
+    'reject': {
+        track: Track;
+        error: any;
+    };
+    /** track 数据变化事件，当 track 的 setData 触发更新时转发 */
+    'track:updated': {
+        track: Track;
+    };
+};
+
+declare type GetAddonAdvanceResults<T extends readonly any[]> = T extends readonly [infer First, ...infer Rest] ? IsUnion<First> extends true ? [Exclude<First, BaseFunction>, ...GetAddonAdvanceResults<Rest>] : GetAddonAdvanceResults<Rest> : [];
+
+declare type GetAddonBasicResults<T extends readonly any[]> = T extends readonly [infer First, ...infer Rest] ? IsUnion<First> extends false ? [First, ...GetAddonBasicResults<Rest>] : GetAddonBasicResults<Rest> : [];
+
+/**
+ * 获取当前 `useAsyncData` 函数的上下文对象。
+ *
+ * 该函数返回当前执行上下文中的异步数据上下文。只有在 `useAsyncData` 函数执行期间（同步部分）才会返回有效的上下文对象，
+ * 在其他情况下（如外部调用、异步回调中）会返回 `null`。
+ *
+ * 上下文对象包含 `getData` 和 `updateData` 方法，用于在异步函数执行中访问和更新数据（竞态安全）。
+ *
+ * @returns 包含 `getData` 和 `updateData` 方法的上下文对象，如果当前不在 `useAsyncData` 执行上下文中则返回 `null`
+ *
+ * @example
+ * // 正确用法：在 useAsyncData 内部同步调用
+ * const { queryData } = useAsyncData((id = 1) => {
+ *   const { getData, updateData } = getAsyncDataContext()
+ *   // 使用 getData 获取当前数据
+ *   const currentData = getData()
+ *   // 执行异步操作
+ *   const newData = await fetch(`/api/data/${id}`)
+ *   // 使用 updateData 更新数据
+ *   updateData(newData)
+ *   return newData
+ * })
+ *
+ * @example
+ * // 在 useAsyncData 外部调用会返回 null
+ * const context = getAsyncDataContext() // context === null
+ *
+ * @example
+ * // 在异步回调中调用也会返回 null
+ * const { queryData } = useAsyncData((id) => {
+ *   setTimeout(() => {
+ *     const context = getAsyncDataContext() // context === null
+ *   }, 1000)
+ *   return fetch(`/api/data/${id}`)
+ * })
+ */
+export declare function getAsyncDataContext(): ReturnType<ContextGetter> | null;
+
+/**
+ * Group 类型（基于 Method 类型）
+ */
+declare type GroupType<M extends BaseFunction> = {
+    loading: boolean;
+    error: any;
+    arguments: Parameters<M> | undefined;
+    argumentFirst: Parameters<M>['0'] | undefined;
+    data: Awaited<ReturnType<M>> | undefined;
+    dataExpired: boolean;
+};
+
+/**
+ * 基础函数监控器接口
+ *
+ * @description 提供函数执行生命周期的事件发布订阅机制。
+ * 支持监听 init、before、after、fulfill、reject 等事件。
+ */
+declare interface InternalFunctionMonitor {
+    /* Excluded from this release type: use */
+    /* Excluded from this release type: get */
+    /**
+     * 注册事件监听器
+     *
+     * @template T - 事件类型
+     *
+     * @param event - 事件类型
+     * @param handler - 事件处理函数
+     */
+    on<T extends keyof FunctionMonitorEventMap>(event: T, handler: EventHandler<T>): void;
+    /**
+     * 移除事件监听器
+     *
+     * @template T - 事件类型
+     *
+     * @param event - 事件类型
+     * @param handler - 要移除的事件处理函数
+     */
+    off<T extends keyof FunctionMonitorEventMap>(event: T, handler: EventHandler<T>): void;
+    /**
+     * 触发事件
+     *
+     * @param event - 事件类型
+     * @param data - 事件数据
+     */
+    emit(event: 'init', data: FunctionMonitorEventMap['init']): void;
+    emit(event: 'before', data: FunctionMonitorEventMap['before']): void;
+    emit(event: 'fulfill', data: FunctionMonitorEventMap['fulfill']): void;
+    emit(event: 'reject', data: FunctionMonitorEventMap['reject']): void;
+    emit(event: 'after', data: FunctionMonitorEventMap['after']): void;
+    emit(event: 'track:updated', data: FunctionMonitorEventMap['track:updated']): void;
+}
+
+/**
+ * 调用追踪对象
+ *
+ * @description 表示单次函数调用的追踪信息，包含调用序号、状态和关联数据。
+ * 用于处理竞态条件，确保只有最新调用的状态才会更新到最终结果。
+ */
+declare type InternalTrack = {
+    /** 调用序号，唯一标识每次调用 */
+    readonly sn: number;
+    /** 检查当前是否处于指定状态 */
+    is: (state?: TrackQueryState) => boolean;
+    /** 标记为成功 */
+    fulfill: () => void;
+    /** 标记为失败 */
+    reject: () => void;
+    /** 存储关联数据（使用 Symbol 作为键） */
+    setData: (key: symbol, value?: any) => void;
+    /** 获取关联数据 */
+    getData: <V = any>(key: symbol) => V | undefined;
+};
+
+/**
+ * 判断一个类型是否为联合类型 (Union Type)。
+ *
+ * @template T - 待检查的类型。
+ * @example
+ * IsUnion<string | number> // true
+ * IsUnion<string> // false
+ */
+declare type IsUnion<T, U = T> = T extends U ? [U] extends [T] ? false : true : never;
+
+/**
+ * 两个类型的智能合并。
+ * 从 A 中剔除 B 已有的键，然后合并 B。若有同名键，B 的类型将覆盖 A。
+ * 支持联合类型分发：如果 A 是联合类型，合并操作将分别应用于每个成员。
+ * @template A - 基础类型。
+ * @template B - 覆盖类型（高优先级）。
+ * @example
+ * type Res = Merge<{ a: string, b: number }, { b: string }>; // { a: string, b: string }
+ */
+declare type Merge<A, B> = A extends any ? Simplify<Omit<A, keyof B> & B> : never;
+
+declare type MergeAddonResults<AddonResults extends any[]> = MergeTypes<ObjectShapeList<[
+...GetAddonBasicResults<AddonResults>,
+...GetAddonAdvanceResults<AddonResults>
+]>>;
+
+/**
+ * 递归合并元组/数组中的所有类型。
+ * 将数组中的每一项依次从左到右执行 Merge 操作。
+ * @template Items - 包含待合并项的只读数组/元组。
+ * @template Acc - 累加器，记录当前合并的结果，默认为空对象。
+ * @example
+ * type Merged = MergeTypes<[{a: 1}, {b: 2}, {a: 3}]>; // { a: 3, b: 2 }
+ */
+declare type MergeTypes<Items extends readonly any[], Acc = {}> = Items extends readonly [infer Item, ...infer Rest] ? MergeTypes<Rest, Merge<Acc, Item>> : Acc;
+
+/**
+ * 确保字符串非空。
+ * 如果输入字符串 `S` 为空字符串，则返回默认类型 `D`，否则返回 `S`。
+ * @template S - 输入的字符串字面量类型。
+ * @template D - 如果 S 为空时的回退默认值。
+ */
+declare type NonEmptyString<S extends string, D extends string> = S extends '' ? D : S;
+
+/**
+ * 基础逻辑工具：取反
+ */
+declare type Not<T extends boolean> = T extends true ? false : true;
+
+/**
+ * 提取类型的“对象形状”。
+ * 该工具旨在过滤掉非纯对象类型：
+ * 1. 识别并排除 `any`（转为 `{}`）。
+ * 2. 排除函数、数组、null、undefined 等（均转为 `{}`）。
+ * 3. 仅保留纯粹的对象结构。
+ * @template T - 待检查的类型。
+ */
+declare type ObjectShape<T> = 0 extends (1 & T) ? {} : T extends BaseFunction ? {} : T extends readonly any[] ? {} : T extends object ? T : {};
+
+/**
+ * 批量提取对象形状。
+ * 将数组或元组中的每一项转换为对应的 `ObjectShape`。
+ * @template List - 待转换的类型列表。
+ */
+declare type ObjectShapeList<List extends readonly any[]> = {
+    [K in keyof List]: ObjectShape<List[K]>;
+};
+
+/**
+ * 展平复杂的交叉类型，提升 IDE 的悬浮提示体验。
+ * 将 `A & B` 形式的交叉类型映射为单一的扁平对象结构，从而显著提升 IDE 悬浮提示的可读性。
+ *
+ * @template T - 待简化的对象类型。
+ */
+declare type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+
+/**
+ * 驼峰化工具：根据位置决定应用小驼峰还是大驼峰
+ * @param S - 待转换的字符串
+ * @param IsFirst - 是否作为结果字符串的起始词（起始词小写，后续词大写）
+ */
+declare type ToCamel<S extends string, IsFirst extends boolean> = IsFirst extends true ? Uncapitalize<S> : Capitalize<S>;
+
+declare type Track = Simplify<Pick<InternalTrack, 'sn' | 'is' | 'getData' | 'setData'> & {
+    takeData: <V = any>(key: symbol) => V | undefined;
+}>;
+
+/**
+ * Track 查询状态类型
+ *
+ * @description 用于查询 Track 状态，包括 'finished'（已完成，无论是成功还是失败）
+ */
+declare type TrackQueryState = TrackState | 'finished';
+
+/**
+ * Track 状态类型
+ *
+ * @description 表示调用追踪对象的状态：pending（等待中）、fulfilled（成功）、rejected（失败）
+ */
+declare type TrackState = 'pending' | 'fulfilled' | 'rejected';
+
+/**
+ * @deprecated 已废弃，请使用 getAsyncDataContext 替代
+ *
+ * 将增强的第一个参数解构为原始参数和上下文对象。
+ * 当 `options.enhanceFirstArgument = true` 时，传递给异步函数的第一个参数会被增强为包含原始参数和上下文方法的对象。
+ *
+ * @param arg 增强后的第一个参数
+ * @param defaultValue 当原始参数为 undefined 时的默认值
+ * @returns 包含原始参数和上下文方法的对象
+ *
+ * @example
+ * // 使用 unFirstArgumentEnhanced（已废弃）
+ * const { queryData } = useAsyncData((id) => {
+ *   const { firstArgument, getData, updateData } = unFirstArgumentEnhanced(id, 1)
+ *   // 使用 firstArgument, getData, updateData
+ *   return fetch(`/api/data/${firstArgument}`)
+ * }, { enhanceFirstArgument: true })
+ *
+ * @example
+ * // 迁移到 getAsyncDataContext
+ * const { queryData } = useAsyncData((id = 1) => {
+ *   const { getData, updateData } = getAsyncDataContext()
+ *   // 使用 id, getData, updateData
+ *   return fetch(`/api/data/${id}`)
+ * })
+ */
+export declare function unFirstArgumentEnhanced<Arg = any, Data = any>(arg: Arg, defaultValue?: Arg): Arg extends undefined ? FirstArgumentEnhanced<Arg, Data> : Required<FirstArgumentEnhanced<Arg, Data>>;
+
+/** useAsync 函数类型 */
+declare interface UseAsync {
+    /**
+     * 封装异步函数，提供 loading、error、arguments 等响应式状态。不指定名称时使用默认 'method'。
+     *
+     * @description
+     * 将异步函数包装为可调用的方法，并自动管理其执行状态。返回的函数保持原有签名，
+     * 可原样接收参数和返回 Promise。适用于提交、删除、确认等不关心返回数据的场景。
+     *
+     * @param fn - 要封装的异步函数
+     * @param options - 配置选项，支持 immediate、watch、setup 等
+     * @returns 默认 name='method'，映射为 method、methodLoading、methodArguments、methodArgumentFirst、methodError
+     *
+     * @example
+     * const { method, methodLoading } = useAsync(() => api.confirm())
+     * method()
+     *
+     * @see {@link useAsyncData} - 需要展示异步返回数据时使用
+     * @see {@link UseAsyncOptions} - 完整配置选项
+     * @see {@link UseAsyncResult} - 返回值类型定义
+     */
+    <Fn extends BaseFunction, AddonResults extends any[] = any[]>(fn: Fn, options?: UseAsyncOptions<Fn, AddonResults>): UseAsyncResult<Fn, UseAsyncNameDefault, AddonResults>;
+    /**
+     * 封装异步函数，提供 loading、error、arguments 等响应式状态。指定名称以自定义函数及关联状态的命名。
+     *
+     * @remarks 推荐用法。自定义名称可提升代码可读性。
+     *
+     * @description
+     * 将异步函数包装为可调用的方法，并自动管理其执行状态。返回的函数保持原有签名，
+     * 可原样接收参数和返回 Promise。适用于提交、删除、确认等不关心返回数据的场景。
+     *
+     * @param name - 函数及关联状态的名称。命名映射：`{name}`→函数，`{name}Loading`→加载状态，`{name}Arguments`→参数列表，`{name}ArgumentFirst`→首个参数，`{name}Error`→异常
+     * @param fn - 要封装的异步函数
+     * @param options - 配置选项，支持 immediate、watch、setup 等
+     * @returns 根据 name 映射：{name}、{name}Loading、{name}Arguments、{name}ArgumentFirst、{name}Error
+     *
+     * @example
+     * const { confirm, confirmLoading, confirmError } = useAsync('confirm', () => api.confirm())
+     * confirm()
+     *
+     * @example
+     * const { submit } = useAsync('submit', (id: string, payload: any) => api.submit(id, payload))
+     * submit('item1', { force: true }).then(result => console.log(result))
+     *
+     * @example
+     * const { init, initLoading } = useAsync('init', () => api.init(), { immediate: true })
+     *
+     * @example
+     * const { init } = useAsync('init', () => api.init(props.id), {
+     *   watch: () => props.id,
+     *   immediate: true
+     * })
+     *
+     * @example
+     * const { init } = useAsync('init', () => api.init(), {
+     *   setup: (fn) => debounce(fn, 500)
+     * })
+     *
+     * @see {@link useAsyncData} - 需要展示异步返回数据时使用
+     * @see {@link UseAsyncOptions} - 完整配置选项
+     * @see {@link UseAsyncResult} - 返回值类型定义
+     */
+    <Fn extends BaseFunction, Name extends string = string, AddonResults extends any[] = any[]>(name: Name, fn: Fn, options?: UseAsyncOptions<Fn, AddonResults>): UseAsyncResult<Fn, Name, AddonResults>;
+}
+
+/**
+ * 封装异步函数，提供 loading、error、arguments 等响应式状态。
+ *
+ * @remarks
+ * 调用方式（详见 {@link UseAsync}）：
+ * - `useAsync(fn, options?)` - 默认名称 'method'，返回 method、methodLoading 等
+ * - `useAsync(name, fn, options?)` - 自定义名称，如 'confirm' 返回 confirm、confirmLoading 等
+ *
+ * @see UseAsync - 完整 API 文档、示例、配置选项
+ */
+declare const useAsync: UseAsync;
+export { useAsync }
+export { useAsync as useAsyncFunction }
+
+/** useAsyncData 函数类型 */
+declare interface UseAsyncData {
+    /**
+     * 管理异步数据，提供响应式数据、查询函数及关联状态。不指定名称时使用默认 'data'。
+     *
+     * @description
+     * 将异步函数包装为查询方法，自动管理返回数据的响应式更新。返回 data、queryData、queryDataLoading、dataExpired 等。
+     *
+     * @param fn - 返回数据的异步函数
+     * @param options - 配置选项，支持 initialData、shallow、immediate、watch、setup 等
+     * @returns 默认 name='data'，映射为 data、queryData、queryDataLoading、queryDataArguments、queryDataError、dataExpired
+     *
+     * @example
+     * const { data, queryData, queryDataLoading } = useAsyncData(() => api.getUser())
+     * queryData()
+     *
+     * @see {@link useAsync} - 不需要展示数据时使用
+     * @see {@link getAsyncDataContext} - 在异步执行过程中更新数据
+     * @see {@link UseAsyncDataOptions} - 完整配置选项
+     * @see {@link UseAsyncDataResult} - 返回值类型定义
+     */
+    <Data = any, Fn extends (...args: any) => Data | Promise<Data> | PromiseLike<Data> = (...args: any) => Data | Promise<Data> | PromiseLike<Data>, Shallow extends boolean = false, AddonResults extends any[] = any[]>(fn: Fn, options?: UseAsyncDataOptions<Fn, Shallow, AddonResults>): UseAsyncDataResult<Fn, UseAsyncDataNameDefault, Shallow, AddonResults>;
+    /**
+     * 管理异步数据，提供响应式数据、查询函数及关联状态。指定名称以自定义数据及关联状态的命名。
+     *
+     * @remarks 推荐用法。自定义名称可提升代码可读性。
+     *
+     * @description
+     * 将异步函数包装为查询方法，自动管理返回数据的响应式更新。name='user' 时返回 user、queryUser、queryUserLoading、queryUserArguments、queryUserError、userExpired 等。
+     *
+     * @param name - 数据及关联状态的名称。命名映射：`{name}`→数据，`query{Name}`→查询函数，`query{Name}Loading`→加载状态，`query{Name}Arguments`→参数列表，`query{Name}Error`→异常，`{name}Expired`→数据过期
+     * @param fn - 返回数据的异步函数
+     * @param options - 配置选项，支持 initialData、shallow、immediate、watch、setup 等
+     * @returns 根据 name 映射：{name}、query{Name}、query{Name}Loading、query{Name}Arguments、query{Name}Error、{name}Expired
+     *
+     * @example
+     * const { user, queryUser, queryUserLoading } = useAsyncData('user', () => api.getUser())
+     * queryUser()
+     *
+     * @example
+     * const { user, queryUser } = useAsyncData('user', (id: string) => api.getUser(id))
+     * queryUser('user1')  // user.value 自动更新为结果
+     *
+     * @see {@link useAsync} - 不需要展示数据时使用
+     * @see {@link getAsyncDataContext} - 在异步执行过程中更新数据
+     * @see {@link UseAsyncDataOptions} - 完整配置选项
+     * @see {@link UseAsyncDataResult} - 返回值类型定义
+     */
+    <Data = any, Fn extends (...args: any) => Data | Promise<Data> | PromiseLike<Data> = (...args: any) => Data | Promise<Data> | PromiseLike<Data>, DataName extends string = string, Shallow extends boolean = false, AddonResults extends any[] = any[]>(name: DataName, fn: Fn, options?: UseAsyncDataOptions<Fn, Shallow, AddonResults>): UseAsyncDataResult<Fn, DataName, Shallow, AddonResults>;
+}
+
+/**
+ * 管理异步数据，提供响应式数据、查询函数及关联状态。
+ *
+ * @remarks
+ * 调用方式（详见 {@link UseAsyncData}）：
+ * - `useAsyncData(fn, options?)` - 默认名称 'data'，返回 data、queryData、dataExpired 等
+ * - `useAsyncData(name, fn, options?)` - 自定义名称，如 'user' 返回 user、queryUser、userExpired 等
+ *
+ * @see UseAsyncData - 完整 API 文档、示例、配置选项
+ */
+export declare const useAsyncData: UseAsyncData;
+
+declare type UseAsyncDataNameDefault = 'data';
+
+/**
+ * useAsyncData 配置选项
+ *
+ * @extends UseAsyncOptions - 继承 useAsync 的全部配置（immediate、watch、setup 等）
+ *
+ * @template Fn - 异步函数类型
+ * @template Shallow - 是否使用 shallowRef
+ * @template AddonResults - 插件扩展的返回值
+ */
+declare interface UseAsyncDataOptions<Fn extends BaseFunction, Shallow extends boolean, AddonResults extends any[] = any[]> extends UseAsyncOptions<Fn, AddonResults> {
+    /** 数据的初始值，在首次查询完成前使用 */
+    initialData?: Awaited<ReturnType<Fn>>;
+    /** 为 true 时使用 shallowRef 包裹数据，适用于大对象优化 */
+    shallow?: Shallow;
+    /** @deprecated 已废弃，请使用 getAsyncDataContext */
+    enhanceFirstArgument?: boolean;
+}
+
+/**
+ * useAsyncData 返回值类型
+ *
+ * @description
+ * 根据传入的 name 动态生成属性名。
+ *
+ * 命名映射规则（name 采用小驼峰，如 'user'；Name 为首字母大写，如 'User'）：
+ * - `{name}` → 异步返回的数据
+ * - `query{Name}` → 触发数据更新的查询函数
+ * - `query{Name}Loading` → 加载状态
+ * - `query{Name}Arguments` → 最近一次调用的参数列表
+ * - `query{Name}ArgumentFirst` → 参数列表的首个值
+ * - `query{Name}Error` → 查询时的异常
+ * - `{name}Expired` → 数据是否过期
+ *
+ * @template Fn - 异步函数类型
+ * @template Name - 数据名称，默认 'data'
+ * @template Shallow - 是否使用 shallowRef
+ * @template AddonResults - 插件扩展的返回值
+ */
+declare type UseAsyncDataResult<Fn extends BaseFunction, Name extends string, Shallow extends boolean = false, AddonResults extends any[] = any[]> = Simplify<UseAsyncResult<Fn, `query${Capitalize<(NonEmptyString<Name, UseAsyncDataNameDefault>)>}`, []> & {
+    [K in (NonEmptyString<Name, UseAsyncDataNameDefault>)]: Shallow extends true ? ShallowRef<Awaited<ReturnType<Fn>>> : Ref<Awaited<ReturnType<Fn>>>;
+} & {
+    [K in `${NonEmptyString<Name, UseAsyncDataNameDefault>}Expired`]: Ref<boolean>;
+} & CamelReplaceKeys<MergeAddonResults<AddonResults>, Name>>;
+
+declare type UseAsyncNameDefault = 'method';
+
+/**
+ * useAsync 配置选项
+ *
+ * @template Fn - 异步函数类型
+ * @template AddonResults - 插件扩展的返回值
+ */
+declare type UseAsyncOptions<Fn extends BaseFunction, AddonResults extends any[] = any[]> = {
+    /** 监听的数据源，变化时执行异步函数。支持 Vue WatchSource 的全部形式 */
+    watch?: WatchSource | WatchSource[];
+    /** watch 的配置项，如 immediate、deep、handlerCreator 等 */
+    watchOptions?: UseAsyncWatchOptions<Fn>;
+    /** 是否在创建时立即执行一次 */
+    immediate?: boolean;
+    /** 转换最终函数或注册外部监听（如 debounce、事件监听、轮询） */
+    setup?: (fn: Fn) => BaseFunction | void;
+    /** 自定义插件，扩展返回值 */
+    addons?: Addons<Fn, AddonResults>;
+};
+
+/**
+ * useAsync 返回值类型
+ *
+ * @description
+ * 根据传入的 name 动态生成属性名。
+ *
+ * 命名映射规则（name 采用小驼峰，如 'confirm'）：
+ * - `{name}` → 包装后的异步函数
+ * - `{name}Loading` → 加载状态
+ * - `{name}Arguments` → 最近一次调用的参数列表
+ * - `{name}ArgumentFirst` → 参数列表的首个值
+ * - `{name}Error` → 执行时的异常
+ *
+ * @template Fn - 异步函数类型
+ * @template Name - 名称，默认 'method'
+ * @template AddonResults - 插件扩展的返回值
+ */
+declare type UseAsyncResult<Fn extends BaseFunction, Name extends string, AddonResults extends any[] = any[]> = Simplify<{
+    [K in NonEmptyString<Name, UseAsyncNameDefault>]: Fn;
+} & {
+    [K in `${NonEmptyString<Name, UseAsyncNameDefault>}Loading`]: Ref<boolean>;
+} & {
+    [K in `${NonEmptyString<Name, UseAsyncNameDefault>}Arguments`]: ComputedRef<Parameters<Fn>>;
+} & {
+    [K in `${NonEmptyString<Name, UseAsyncNameDefault>}ArgumentFirst`]: ComputedRef<Parameters<Fn>['0']>;
+} & {
+    [K in `${NonEmptyString<Name, UseAsyncNameDefault>}Error`]: Ref<any>;
+} & CamelReplaceKeys<MergeAddonResults<AddonResults>, Name>>;
+
+/**
+ * watch 配置选项
+ *
+ * @extends WatchOptions - 继承 Vue watch 的全部配置（immediate、deep、flush、once 等）
+ */
+declare interface UseAsyncWatchOptions<Fn extends BaseFunction> extends WatchOptions {
+    /** 自定义 watch handler，用于过滤或转换监听源 */
+    handlerCreator?: (fn: Fn) => WatchCallback;
+}
+
+/**
+ * withAddonGroup addon
+ *
+ * @description 用于支持"并行、同源、同语义操作"场景，通过 key 分组管理状态。
+ *
+ * 核心特性：
+ * - 固定属性：`group[key]` 在被创建后始终包含 `loading`、`error`、`arguments`、`data`
+ * - 直接值：`group[key]?.loading` 是 `boolean`，不是 `Ref<boolean>`。注：group 本身是 ref，其属性在访问时会自动解包为直接值
+ * - 需要使用可选链：`group[key]` 可能为 `undefined`（当该 key 还没有被调用过时）
+ * - 自动同步：所有 addon 的 setData 操作自动同步到 group
+ * - 竞态处理：只有最新调用的状态才会更新到 group
+ *
+ * @param config - 配置对象
+ * @param config.key - 根据函数参数生成 group key 的函数
+ * @param config.scope - 根据函数参数获取请求的 scope（可选）
+ *
+ * @returns addon 函数
+ *
+ * @example
+ * ```ts
+ * const { confirm, confirmGroup } = useAsync('confirm', confirmApi, {
+ *   addons: [withAddonGroup({ key: (args) => args[0] })]
+ * })
+ *
+ * // 模板中使用
+ * <button
+ *   :loading="confirmGroup[item.id]?.loading"
+ *   @click="confirm(item.id)"
+ * >
+ *   确认
+ * </button>
+ * ```
+ */
+export declare function withAddonGroup(config: WithAddonGroupConfig): <T extends AddonTypes>(params: {
+    monitor: FunctionMonitor;
+    _types: T;
+}) => {
+    __name__Group: ComputedRef<Record<string | number, GroupType<T['Method']>>>;
+    clear__name__Group: (key?: string | number) => void;
+};
+
+/**
+ * withAddonGroup 配置
+ */
+declare interface WithAddonGroupConfig {
+    /**
+     * 根据函数参数生成 group key
+     *
+     * @param args - 函数调用参数
+     * @returns group key（string 或 number）
+     */
+    key: (args: any[]) => string | number;
+    /**
+     * 根据函数参数获取请求的 scope
+     *
+     * @param args - 函数调用参数
+     * @returns scope（string 或 number）
+     */
+    scope?: (args: any[]) => string | number;
+}
+
+export { }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vue-asyncx",
-  "version": "1.11.2",
+  "version": "1.11.3",
   "description": "让异步像写诗的 Vue 3 组合式工具库",
   "type": "module",
   "sideEffects": false,
@@ -12,7 +12,10 @@
   "types": "./dist/vue-asyncx.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/vue-asyncx.d.ts",
+      "types": {
+        "import": "./dist/vue-asyncx.d.ts",
+        "require": "./dist/vue-asyncx.d.cts"
+      },
       "import": "./dist/vue-asyncx.js",
       "require": "./dist/vue-asyncx.umd.cjs"
     }
@@ -55,7 +58,12 @@
     "docs:preview": "vitepress preview docs",
     "pack": "rm -rf ./dist-pack && pnpm pack --pack-destination ./dist-pack && mv ./dist-pack/*.tgz ./dist-pack/vue-asyncx.tgz",
     "build": "vite build && node scripts/post-build-dts.js",
-    "run:build-pack": "run-s build pack"
+    "run:build-pack": "run-s build pack",
+    "check:exports": "publint ./dist-pack/vue-asyncx.tgz",
+    "check:types": "attw ./dist-pack/vue-asyncx.tgz",
+    "check:all": "run-s run:build-pack check:exports check:types",
+    "prepublishOnly": "run-s check:all",
+    "release": "node scripts/release.js"
   },
   "keywords": [
     "vue",
@@ -77,22 +85,25 @@
     "provenance": true
   },
   "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.2",
+    "@inquirer/prompts": "^8.3.2",
     "@types/node": "^22.19.1",
-    "@vitest/browser-playwright": "^4.0.18",
-    "@vitest/coverage-v8": "^4.0.18",
-    "@vitest/ui": "4.0.18",
+    "@vitest/browser-playwright": "^4.1.0",
+    "@vitest/coverage-v8": "^4.1.0",
+    "@vitest/ui": "^4.1.0",
     "@vueuse/core": "^14.0.0",
     "es-toolkit": "^1.42.0",
     "jsdom": "^24.1.1",
     "npm-run-all2": "^8.0.4",
     "oxlint": "^1.0.0",
     "playwright": "^1.58.2",
+    "publint": "^0.3.18",
     "rolldown-plugin-dts": "^0.21.8",
     "typescript": "5.9.3",
-    "vite": "8.0.0-beta.18",
+    "vite": "^8.0.0",
     "vite-plugin-dts": "^4.5.4",
     "vitepress": "^1.6.3",
-    "vitest": "^4.0.18",
+    "vitest": "^4.1.0",
     "vitest-coverage-merge": "^0.2.0",
     "vue": "^3.0.0",
     "vue-demi": "^0.14.10",
@@ -101,4 +112,4 @@
   "peerDependencies": {
     "vue": "^2.7.0 || >=3.0.0"
   }
-}
+}