@ahoo-wang/fetcher-react 3.9.2 → 3.9.5

package/README.zh-CN.md

@@ -19,6 +19,7 @@
 - ⚡ **性能优化**: 使用 useMemo、useCallback 和智能依赖管理进行优化
 - 🎯 **选项灵活性**: 支持静态选项和动态选项供应商
 - 🔧 **开发者体验**: 内置加载状态、错误处理和自动重新渲染
+- 🏗️ **API Hooks 生成**: 从 API 对象自动生成类型安全的 React hooks
 - 📊 **高级查询 Hooks**: 专门用于列表、分页、单个、计数和流查询的 hooks，具有状态管理功能
 
 ## 目录
@@ -26,6 +27,7 @@
 - [安装](#安装)
 - [快速开始](#快速开始)
 - [使用方法](#使用方法)
+  - [API Hooks](#api-hooks)
   - [核心 Hooks](#核心-hooks)
     - [useExecutePromise](#useexecutepromise)
     - [usePromiseState](#usepromisestate)
@@ -109,6 +111,369 @@ function App() {
 
 ## 使用方法
 
+### API Hooks
+
+#### createExecuteApiHooks
+
+🚀 **自动类型安全 API Hooks 生成** - 从 API 对象自动生成完全类型化的 React hooks，具有自动方法发现、类方法支持和高级执行控制。
+
+`createExecuteApiHooks` 函数自动发现 API 对象中的所有函数方法（包括类实例的原型链），并使用命名模式 `use{首字母大写的方法名}` 创建相应的 React hooks。每个生成的 hook 都提供完整的状态管理、错误处理，并支持具有类型安全参数访问的自定义执行回调。
+
+**主要特性：**
+
+- **自动方法发现**：遍历对象属性和原型链
+- **类型安全 Hook 生成**：参数和返回类型的完整 TypeScript 推断
+- **类方法支持**：处理静态方法和具有 `this` 绑定的类实例
+- **执行控制**：`onBeforeExecute` 回调用于参数检查/修改和中止控制器访问
+- **自定义错误类型**：支持指定超出默认 `FetcherError` 的错误类型
+
+```typescript jsx
+import { createExecuteApiHooks } from '@ahoo-wang/fetcher-react';
+import { api, get, post, patch, path, body, autoGeneratedError } from '@ahoo-wang/fetcher-decorator';
+
+// 使用装饰器定义您的 API 服务
+import { api, get, post, patch, path, body, autoGeneratedError } from '@ahoo-wang/fetcher-decorator';
+
+@api('/users')
+class UserApi {
+  @get('/{id}')
+  getUser(@path('id') id: string): Promise<User> {
+    throw autoGeneratedError(id);
+  }
+
+  @post('')
+  createUser(@body() data: { name: string; email: string }): Promise<User> {
+    throw autoGeneratedError(data);
+  }
+
+  @patch('/{id}')
+  updateUser(@path('id') id: string, @body() updates: Partial<User>): Promise<User> {
+    throw autoGeneratedError(id, updates);
+  }
+}
+
+const userApi = new UserApi();
+
+// 生成类型安全的 hooks
+const apiHooks = createExecuteApiHooks({ api: userApi });
+
+function UserComponent() {
+  // Hooks 自动生成，具有正确的类型
+  const { loading: getLoading, result: user, error: getError, execute: getUser } = apiHooks.useGetUser();
+  const { loading: createLoading, result: createdUser, error: createError, execute: createUser } = apiHooks.useCreateUser({
+    onBeforeExecute: (abortController, args) => {
+      // args 完全类型化为 [data: { name: string; email: string }]
+      const [data] = args;
+      // 如果需要，可以就地修改参数
+      data.email = data.email.toLowerCase();
+      // 访问中止控制器以进行自定义取消
+      abortController.signal.addEventListener('abort', () => {
+        console.log('用户创建已取消');
+      });
+    },
+  });
+
+  const handleFetchUser = (userId: string) => {
+    getUser(userId); // 完全类型化 - 仅接受字符串参数
+  };
+
+  const handleCreateUser = (userData: { name: string; email: string }) => {
+    createUser(userData); // 完全类型化 - 仅接受正确的数据形状
+  };
+
+  return (
+    <div>
+      <button onClick={() => handleFetchUser('123')}>
+        获取用户
+      </button>
+      {getLoading && <div>正在加载用户...</div>}
+      {getError && <div>错误: {getError.message}</div>}
+      {user && <div>用户: {user.name}</div>}
+
+      <button onClick={() => handleCreateUser({ name: 'John', email: 'john@example.com' })}>
+        创建用户
+      </button>
+      {createLoading && <div>正在创建用户...</div>}
+      {createError && <div>错误: {createError.message}</div>}
+      {createdUser && <div>已创建: {createdUser.name}</div>}
+    </div>
+  );
+}
+```
+
+**自定义错误类型：**
+
+```typescript jsx
+import { createExecuteApiHooks } from '@ahoo-wang/fetcher-react';
+
+// 定义自定义错误类型
+class ApiError extends Error {
+  constructor(
+    public statusCode: number,
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+// 使用自定义错误类型生成 hooks
+@api('/data')
+class DataApi {
+  @get('/{id}')
+  getData(@path('id') id: string): Promise<Data> {
+    throw autoGeneratedError(id);
+  }
+}
+
+const apiHooks = createExecuteApiHooks<
+  { getData: (id: string) => Promise<Data> },
+  ApiError
+>({
+  api: new DataApi(),
+  errorType: ApiError,
+});
+
+function MyComponent() {
+  const { error, execute } = apiHooks.useGetData();
+
+  // error 现在类型化为 ApiError | undefined
+  if (error) {
+    console.log('状态码:', error.statusCode); // TypeScript 知道 statusCode
+  }
+}
+```
+
+**具有类方法的高级用法：**
+
+```typescript jsx
+import { createExecuteApiHooks } from '@ahoo-wang/fetcher-react';
+
+class ApiClient {
+  private baseUrl: string;
+
+  constructor(baseUrl: string) {
+    this.baseUrl = baseUrl;
+  }
+
+  async get(endpoint: string): Promise<any> {
+    const response = await fetch(`${this.baseUrl}${endpoint}`);
+    return response.json();
+  }
+
+  async post(endpoint: string, data: any): Promise<any> {
+    const response = await fetch(`${this.baseUrl}${endpoint}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(data),
+    });
+    return response.json();
+  }
+
+  // 静态方法示例
+  static async healthCheck(): Promise<{ status: string }> {
+    const response = await fetch('/api/health');
+    return response.json();
+  }
+}
+
+const apiClient = new ApiClient('/api');
+const apiHooks = createExecuteApiHooks({ api: apiClient });
+
+// 生成的 hooks: useGet, usePost
+// 静态方法也会被发现: useHealthCheck
+
+function ApiComponent() {
+  const { execute: getData } = apiHooks.useGet();
+  const { execute: postData } = apiHooks.usePost();
+  const { execute: healthCheck } = apiHooks.useHealthCheck();
+
+  return (
+    <div>
+      <button onClick={() => getData('/users')}>获取用户</button>
+      <button onClick={() => postData('/users', { name: '新用户' })}>创建用户</button>
+      <button onClick={() => healthCheck()}>健康检查</button>
+    </div>
+  );
+}
+```
+
+#### createQueryApiHooks
+
+🚀 **自动类型安全查询 API Hooks 生成** - 从 API 对象自动生成完全类型化的 React 查询 hooks，具有自动查询状态管理、自动执行和高级执行控制。
+
+`createQueryApiHooks` 函数自动发现 API 对象中的查询方法，并创建相应的扩展 `useQuery` 的 React hooks。每个生成的 hook 都提供自动查询参数管理、状态管理和对具有类型安全查询访问的自定义执行回调的支持。
+
+**主要特性：**
+
+- **自动方法发现**：遍历对象属性和原型链
+- **类型安全查询 Hooks**：查询参数和返回类型的完整 TypeScript 推断
+- **查询状态管理**：内置 `setQuery` 和 `getQuery` 进行参数管理
+- **自动执行**：查询参数更改时可选的自动执行
+- **执行控制**：`onBeforeExecute` 回调用于查询检查/修改和中止控制器访问
+- **自定义错误类型**：支持指定超出默认 `FetcherError` 的错误类型
+
+```typescript jsx
+import { createQueryApiHooks } from '@ahoo-wang/fetcher-react';
+import { api, get, post, patch, path, body, autoGeneratedError } from '@ahoo-wang/fetcher-decorator';
+
+// 使用装饰器定义您的 API 服务
+@api('/users')
+class UserApi {
+  @get('')
+  getUsers(query: UserListQuery, attributes?: Record<string, any>): Promise<User[]> {
+    throw autoGeneratedError(query, attributes);
+  }
+
+  @get('/{id}')
+  getUser(query: { id: string }, attributes?: Record<string, any>): Promise<User> {
+    throw autoGeneratedError(query, attributes);
+  }
+
+  @post('')
+  createUser(query: { name: string; email: string }, attributes?: Record<string, any>): Promise<User> {
+    throw autoGeneratedError(query, attributes);
+  }
+}
+
+const apiHooks = createQueryApiHooks({ api: new UserApi() });
+
+function UserListComponent() {
+  const { loading, result, error, execute, setQuery, getQuery } = apiHooks.useGetUsers({
+    initialQuery: { page: 1, limit: 10 },
+    autoExecute: true,
+    onBeforeExecute: (abortController, query) => {
+      // query 是完全类型化的 UserListQuery
+      console.log('正在执行查询:', query);
+      // 如果需要，可以就地修改查询参数
+      query.page = Math.max(1, query.page);
+    },
+  });
+
+  const handlePageChange = (page: number) => {
+    // 自动更新查询并触发执行（如果 autoExecute: true）
+    setQuery({ ...getQuery(), page });
+  };
+
+  if (loading) return <div>正在加载...</div>;
+  if (error) return <div>错误: {error.message}</div>;
+
+  return (
+    <div>
+      <button onClick={() => handlePageChange(2)}>转到第2页</button>
+      {result?.map(user => (
+        <div key={user.id}>{user.name}</div>
+      ))}
+    </div>
+  );
+}
+
+function UserDetailComponent() {
+  const { result: user, execute } = apiHooks.useGetUser({
+    initialQuery: { id: '123' },
+  });
+
+  return (
+    <div>
+      <button onClick={execute}>加载用户</button>
+      {user && <div>用户: {user.name}</div>}
+    </div>
+  );
+}
+```
+
+**自定义错误类型：**
+
+```typescript jsx
+import { createQueryApiHooks } from '@ahoo-wang/fetcher-react';
+
+// 定义自定义错误类型
+class ApiError extends Error {
+  constructor(
+    public statusCode: number,
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+// 使用自定义错误类型生成查询 hooks
+@api('/data')
+class DataApi {
+  @get('/{id}')
+  getData(
+    query: { id: string },
+    attributes?: Record<string, any>,
+  ): Promise<Data> {
+    throw autoGeneratedError(query, attributes);
+  }
+}
+
+const apiHooks = createQueryApiHooks<
+  {
+    getData: (
+      query: { id: string },
+      attributes?: Record<string, any>,
+    ) => Promise<Data>;
+  },
+  ApiError
+>({
+  api: new DataApi(),
+  errorType: ApiError,
+});
+
+function MyComponent() {
+  const { error, execute } = apiHooks.useGetData();
+
+  // error 现在类型化为 ApiError | undefined
+  if (error) {
+    console.log('状态码:', error.statusCode); // TypeScript 知道 statusCode
+  }
+}
+```
+
+**高级用法与手动查询管理：**
+
+```typescript jsx
+import { createQueryApiHooks } from '@ahoo-wang/fetcher-react';
+
+const apiHooks = createQueryApiHooks({ api: userApi });
+
+function SearchComponent() {
+  const { loading, result, setQuery, getQuery } = apiHooks.useGetUsers({
+    initialQuery: { search: '', page: 1 },
+    autoExecute: false, // 手动执行控制
+  });
+
+  const handleSearch = (searchTerm: string) => {
+    // 更新查询而不自动执行
+    setQuery({ search: searchTerm, page: 1 });
+  };
+
+  const handleSearchSubmit = () => {
+    // 使用当前查询手动执行
+    apiHooks.useGetUsers().execute();
+  };
+
+  const currentQuery = getQuery(); // 访问当前查询参数
+
+  return (
+    <div>
+      <input
+        value={currentQuery.search}
+        onChange={(e) => handleSearch(e.target.value)}
+        placeholder="搜索用户..."
+      />
+      <button onClick={handleSearchSubmit} disabled={loading}>
+        {loading ? '搜索中...' : '搜索'}
+      </button>
+      {result?.map(user => (
+        <div key={user.id}>{user.name}</div>
+      ))}
+    </div>
+  );
+}
+```
+
 ### 核心 Hooks
 
 #### useExecutePromise

package/dist/api/apiHooks.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Shared utilities and types for API hooks generation.
+ */
+/**
+ * Converts a method name to a React hook name by prefixing with 'use' and capitalizing the first letter.
+ * @param methodName - The method name to convert.
+ * @returns The converted hook name.
+ * @throws {Error} If methodName is empty or null.
+ * @example
+ * methodNameToHookName('getUser') // 'useGetUser'
+ * methodNameToHookName('createPost') // 'useCreatePost'
+ * methodNameToHookName('APIGetData') // 'useAPIGetData'
+ */
+export declare function methodNameToHookName(methodName: string): string;
+/**
+ * Collects all function methods from an object and its prototype chain.
+ * @param obj - The object to collect methods from.
+ * @returns A map of method names to bound methods.
+ */
+export declare function collectMethods<T extends (...args: any[]) => Promise<any>>(obj: Record<string, any>): Map<string, T>;
+/**
+ * Common configuration options for API hooks creation functions.
+ * @template API - The API object type.
+ */
+export interface CreateApiHooksOptions<API extends Record<string, any>> {
+    /**
+     * The API object containing methods to be wrapped into hooks.
+     */
+    api: API;
+}
+/**
+ * Utility type to extract the hook name from a method name.
+ * @template K - The method name key.
+ */
+export type HookName<K extends string> = `use${Capitalize<K>}`;
+/**
+ * Utility type to check if a value is a function that returns a Promise.
+ * @template T - The value to check.
+ */
+export type IsPromiseFunction<T> = T extends (...args: any[]) => Promise<any> ? true : false;
+/**
+ * Utility type to extract the parameters of a promise-returning function.
+ * @template T - The function type.
+ */
+export type FunctionParameters<T> = T extends (...args: infer P) => Promise<any> ? P : never;
+/**
+ * Utility type to extract the resolved return type of a promise-returning function.
+ * @template T - The function type.
+ */
+export type FunctionReturnType<T> = T extends (...args: any[]) => Promise<infer R> ? Awaited<R> : never;
+/**
+ * Utility type for API method signatures.
+ * @template TArgs - Parameter types.
+ * @template TReturn - Return type.
+ */
+export type ApiMethod<TArgs extends any[] = any[], TReturn = any> = (...args: TArgs) => Promise<TReturn>;
+/**
+ * Utility type for query method signatures (with query, attributes, abortController).
+ * @template Q - Query type.
+ * @template TReturn - Return type.
+ */
+export type QueryMethod<Q = any, TReturn = any> = (query: Q, attributes?: Record<string, any>, abortController?: AbortController) => Promise<TReturn>;
+/**
+ * Common callback type for pre-execution hooks.
+ * @template TParams - The parameters type passed to the callback.
+ */
+export type OnBeforeExecuteCallback<TParams> = (abortController: AbortController | undefined, params: TParams) => void;
+/**
+ * Utility type to create API hooks mapping.
+ * @template API - The API object type.
+ * @template MethodType - The method signature type.
+ * @template HookType - The hook function type.
+ * @template E - Error type.
+ */
+export type ApiHooksMapping<API extends Record<string, any>, MethodType extends (...args: any[]) => Promise<any>, HookType> = {
+    [K in keyof API as API[K] extends MethodType ? HookName<string & K> : never]: API[K] extends MethodType ? HookType : never;
+};
+//# sourceMappingURL=apiHooks.d.ts.map

package/dist/api/apiHooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiHooks.d.ts","sourceRoot":"","sources":["../../src/api/apiHooks.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAQ/D;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,EACvE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GACvB,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CA6BhB;AAMD;;;GAGG;AACH,MAAM,WAAW,qBAAqB,CAAC,GAAG,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IACpE;;OAEG;IACH,GAAG,EAAE,GAAG,CAAC;CACV;AAED;;;GAGG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,SAAS,MAAM,IAAI,MAAM,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC;AAE/D;;;GAGG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,GACzE,IAAI,GACJ,KAAK,CAAC;AAEV;;;GAGG;AACH,MAAM,MAAM,kBAAkB,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,KAAK,OAAO,CAAC,GAAG,CAAC,GAC5E,CAAC,GACD,KAAK,CAAC;AAEV;;;GAGG;AACH,MAAM,MAAM,kBAAkB,CAAC,CAAC,IAAI,CAAC,SAAS,CAC5C,GAAG,IAAI,EAAE,GAAG,EAAE,KACX,OAAO,CAAC,MAAM,CAAC,CAAC,GACjB,OAAO,CAAC,CAAC,CAAC,GACV,KAAK,CAAC;AAEV;;;;GAIG;AACH,MAAM,MAAM,SAAS,CAAC,KAAK,SAAS,GAAG,EAAE,GAAG,GAAG,EAAE,EAAE,OAAO,GAAG,GAAG,IAAI,CAClE,GAAG,IAAI,EAAE,KAAK,KACX,OAAO,CAAC,OAAO,CAAC,CAAC;AAEtB;;;;GAIG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,GAAG,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,CAChD,KAAK,EAAE,CAAC,EACR,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAChC,eAAe,CAAC,EAAE,eAAe,KAC9B,OAAO,CAAC,OAAO,CAAC,CAAC;AAEtB;;;GAGG;AACH,MAAM,MAAM,uBAAuB,CAAC,OAAO,IAAI,CAC7C,eAAe,EAAE,eAAe,GAAG,SAAS,EAC5C,MAAM,EAAE,OAAO,KACZ,IAAI,CAAC;AAEV;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,CACzB,GAAG,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC/B,UAAU,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,EACnD,QAAQ,IACN;KACD,CAAC,IAAI,MAAM,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,SAAS,UAAU,GACxC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,GACpB,KAAK,GAAG,GAAG,CAAC,CAAC,CAAC,SAAS,UAAU,GAAG,QAAQ,GAAG,KAAK;CACzD,CAAC"}

package/dist/api/createExecuteApiHooks.d.ts

@@ -0,0 +1,105 @@
+import { UseExecutePromiseReturn, UseExecutePromiseOptions } from '../core';
+import { FetcherError } from '@ahoo-wang/fetcher';
+import { CreateApiHooksOptions, HookName, ApiMethod, FunctionParameters, FunctionReturnType, OnBeforeExecuteCallback } from './apiHooks';
+/**
+ * Configuration options for createExecuteApiHooks.
+ * @template API - The API object type containing methods that return promises.
+ */
+export interface CreateExecuteApiHooksOptions<API extends Record<string, any>> extends CreateApiHooksOptions<API> {
+}
+/**
+ * Configuration options for createQueryApiHooks.
+ * @template API - The API object type containing query methods.
+ */
+export interface CreateQueryApiHooksOptions<API extends Record<string, any>> extends CreateApiHooksOptions<API> {
+}
+/**
+ * Options for useApiMethodExecute hook.
+ * @template TArgs - The parameter types of the API method.
+ * @template TData - The return type of the API method (resolved).
+ * @template E - The error type.
+ */
+export interface UseApiMethodExecuteOptions<TArgs = any[], TData = any, E = FetcherError> extends UseExecutePromiseOptions<TData, E> {
+    /**
+     * Callback executed before method invocation.
+     * Allows users to handle abortController and inspect/modify parameters.
+     * Note: Parameters can be modified in place for objects/arrays.
+     * @param abortController - The AbortController for the request.
+     * @param args - The arguments passed to the API method (type-safe).
+     *
+     * @example
+     * onBeforeExecute: (abortController, args) => {
+     *   // args is now typed as Parameters<TMethod>
+     *   const [id, options] = args;
+     *   // Modify parameters in place
+     *   if (options && typeof options === 'object') {
+     *     options.timestamp = Date.now();
+     *   }
+     * }
+     */
+    onBeforeExecute?: OnBeforeExecuteCallback<TArgs>;
+}
+/**
+ * The return type of createExecuteApiHooks.
+ * Creates a hook for each function method in the API object, prefixed with 'use' and capitalized.
+ * Each hook accepts optional useExecutepromise options and returns the useExecutepromise interface
+ * with a modified execute function that takes the API method parameters instead of a promise supplier.
+ * @template API - The API object type.
+ * @template E - The error type for all hooks (defaults to FetcherError).
+ */
+export type APIHooks<API extends Record<string, any>, E = FetcherError> = {
+    [K in keyof API as API[K] extends ApiMethod ? HookName<string & K> : never]: API[K] extends ApiMethod ? (options?: UseApiMethodExecuteOptions<FunctionParameters<API[K]>, FunctionReturnType<API[K]>, E>) => UseExecutePromiseReturn<FunctionReturnType<API[K]>, E> & {
+        execute: (...params: FunctionParameters<API[K]>) => Promise<void>;
+    } : never;
+};
+/**
+ * Creates type-safe React hooks for API methods.
+ * Each API method that returns a Promise is wrapped into a hook that extends useExecutePromise.
+ * The generated hooks provide automatic state management, abort support, and error handling.
+ *
+ * @template API - The API object type containing methods that return promises.
+ * @param options - Configuration options including the API object.
+ * @returns An object containing hooks for each API method.
+ *
+ * @example
+ * ```typescript
+ * // Default behavior (no onBeforeExecute)
+ * const userApi = {
+ *   getUser: (id: string) => fetch(`/api/users/${id}`).then(res => res.json()),
+ *   createUser: (data: UserInput) => fetch('/api/users', {
+ *     method: 'POST',
+ *     body: JSON.stringify(data),
+ *   }).then(res => res.json()),
+ * };
+ *
+ * const apiHooks = createExecuteApiHooks({ api: userApi });
+ *
+ * function UserComponent() {
+ *   const { loading, result, error, execute } = apiHooks.useGetUser();
+ *
+ *   const handleFetchUser = (userId: string) => {
+ *     execute(userId); // Calls getUser(userId) directly
+ *   };
+ *
+ *   // Custom onBeforeExecute to handle abortController and modify parameters
+ *   const { execute: customExecute } = apiHooks.useCreateUser({
+ *     onBeforeExecute: (abortController, args) => {
+ *       // args is now fully type-safe as Parameters<createUser>
+ *       const [data] = args;
+ *       // Modify parameters in place (assuming data is mutable)
+ *       if (data && typeof data === 'object') {
+ *         (data as any).timestamp = Date.now();
+ *       }
+ *       // Could also set up abortController.signal
+ *       abortController.signal.addEventListener('abort', () => {
+ *         console.log('Request aborted');
+ *       });
+ *     },
+ *   });
+ *
+ *   // ... component logic
+ * }
+ * ```
+ */
+export declare function createExecuteApiHooks<API extends Record<string, any>, E = FetcherError>(options: CreateExecuteApiHooksOptions<API>): APIHooks<API, E>;
+//# sourceMappingURL=createExecuteApiHooks.d.ts.map

package/dist/api/createExecuteApiHooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createExecuteApiHooks.d.ts","sourceRoot":"","sources":["../../src/api/createExecuteApiHooks.ts"],"names":[],"mappings":"AAcA,OAAO,EAEL,uBAAuB,EACvB,wBAAwB,EAEzB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAGL,qBAAqB,EACrB,QAAQ,EACR,SAAS,EACT,kBAAkB,EAClB,kBAAkB,EAClB,uBAAuB,EACxB,MAAM,YAAY,CAAC;AAEpB;;;GAGG;AACH,MAAM,WAAW,4BAA4B,CAC3C,GAAG,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAC/B,SAAQ,qBAAqB,CAAC,GAAG,CAAC;CAAG;AAEvC;;;GAGG;AACH,MAAM,WAAW,0BAA0B,CACzC,GAAG,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAC/B,SAAQ,qBAAqB,CAAC,GAAG,CAAC;CAAG;AAEvC;;;;;GAKG;AACH,MAAM,WAAW,0BAA0B,CACzC,KAAK,GAAG,GAAG,EAAE,EACb,KAAK,GAAG,GAAG,EACX,CAAC,GAAG,YAAY,CAChB,SAAQ,wBAAwB,CAAC,KAAK,EAAE,CAAC,CAAC;IAC1C;;;;;;;;;;;;;;;;OAgBG;IACH,eAAe,CAAC,EAAE,uBAAuB,CAAC,KAAK,CAAC,CAAC;CAClD;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,QAAQ,CAAC,GAAG,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC,GAAG,YAAY,IAAI;KACvE,CAAC,IAAI,MAAM,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,SAAS,SAAS,GACvC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,GACpB,KAAK,GAAG,GAAG,CAAC,CAAC,CAAC,SAAS,SAAS,GAChC,CACE,OAAO,CAAC,EAAE,0BAA0B,CAClC,kBAAkB,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAC1B,kBAAkB,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAC1B,CAAC,CACF,KACE,uBAAuB,CAAC,kBAAkB,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG;QAC5D,OAAO,EAAE,CAAC,GAAG,MAAM,EAAE,kBAAkB,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;KACnE,GACD,KAAK;CACV,CAAC;AA4DF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC/B,CAAC,GAAG,YAAY,EAChB,OAAO,EAAE,4BAA4B,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAC,CAa9D"}

package/dist/api/createQueryApiHooks.d.ts

@@ -0,0 +1,97 @@
+import { UseQueryReturn, UseQueryOptions } from '../core';
+import { FetcherError } from '@ahoo-wang/fetcher';
+import { CreateQueryApiHooksOptions } from './createExecuteApiHooks';
+import { HookName, QueryMethod, OnBeforeExecuteCallback } from './apiHooks';
+/**
+ * Options for useApiMethodQuery hook.
+ * @template Q - The query type.
+ * @template TData - The return type of the API method (resolved).
+ * @template E - The error type.
+ */
+export interface UseApiMethodQueryOptions<Q, TData = any, E = FetcherError> extends Omit<UseQueryOptions<Q, TData, E>, 'execute'> {
+    /**
+     * Callback executed before query execution.
+     * Allows users to handle abortController and inspect/modify query parameters.
+     * Note: Query parameters can be modified in place for objects.
+     * @param abortController - The AbortController for the request.
+     * @param query - The query parameters passed to the API method (type-safe).
+     *
+     * @example
+     * onBeforeExecute: (abortController, query) => {
+     *   // query is now typed as Q
+     *   if (query && typeof query === 'object') {
+     *     query.timestamp = Date.now();
+     *   }
+     * }
+     */
+    onBeforeExecute?: OnBeforeExecuteCallback<Q>;
+}
+/**
+ * The return type of createQueryApiHooks.
+ * Creates a hook for each function method in the API object, prefixed with 'use' and capitalized.
+ * Each hook accepts query options and returns the useQuery interface with type-safe query management.
+ * @template API - The API object type.
+ * @template E - The error type for all hooks (defaults to FetcherError).
+ */
+export type QueryAPIHooks<API extends Record<string, any>, E = FetcherError> = {
+    [K in keyof API as API[K] extends QueryMethod ? HookName<string & K> : never]: API[K] extends QueryMethod<infer Q, infer R> ? (options?: UseApiMethodQueryOptions<Q, R, E>) => UseQueryReturn<Q, R, E> : never;
+};
+/**
+ * Creates type-safe React hooks for API query methods.
+ * Each API method that follows the query pattern is wrapped into a hook that extends useQuery.
+ * The generated hooks provide automatic query state management, auto-execution, and error handling.
+ *
+ * @template API - The API object type containing query methods.
+ * @param options - Configuration options including the API object.
+ * @returns An object containing hooks for each API query method.
+ *
+ * @example
+ * ```typescript
+ * // Define your API service using decorators
+ * import { api, get, post, patch, path, body, autoGeneratedError } from '@ahoo-wang/fetcher-decorator';
+ *
+ * @api('/users')
+ * class UserApi {
+ *   @get('')
+ *   getUsers(query: UserListQuery, attributes?: Record<string, any>): Promise<User[]> {
+ *     throw autoGeneratedError(query, attributes);
+ *   }
+ *
+ *   @get('/{id}')
+ *   getUser(query: { id: string }, attributes?: Record<string, any>): Promise<User> {
+ *     throw autoGeneratedError(query, attributes);
+ *   }
+ * }
+ *
+ * const apiHooks = createQueryApiHooks({ api: new UserApi() });
+ *
+ * function UserListComponent() {
+ *   const { loading, result, error, execute, setQuery, getQuery } = apiHooks.useGetUsers({
+ *     initialQuery: { page: 1, limit: 10 },
+ *     autoExecute: true,
+ *     onBeforeExecute: (abortController, query) => {
+ *       // query is fully typed as UserListQuery
+ *       console.log('Executing query:', query);
+ *     },
+ *   });
+ *
+ *   const handlePageChange = (page: number) => {
+ *     setQuery({ ...getQuery(), page }); // Automatically executes
+ *   };
+ *
+ *   if (loading) return <div>Loading...</div>;
+ *   if (error) return <div>Error: {error.message}</div>;
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={() => handlePageChange(2)}>Go to page 2</button>
+ *       {result?.map(user => (
+ *         <div key={user.id}>{user.name}</div>
+ *       ))}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function createQueryApiHooks<API extends Record<string, any>, E = FetcherError>(options: CreateQueryApiHooksOptions<API>): QueryAPIHooks<API, E>;
+//# sourceMappingURL=createQueryApiHooks.d.ts.map

package/dist/api/createQueryApiHooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createQueryApiHooks.d.ts","sourceRoot":"","sources":["../../src/api/createQueryApiHooks.ts"],"names":[],"mappings":"AAcA,OAAO,EAAY,cAAc,EAAE,eAAe,EAAa,MAAM,SAAS,CAAC;AAC/E,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,0BAA0B,EAAE,MAAM,yBAAyB,CAAC;AACrE,OAAO,EAGL,QAAQ,EACR,WAAW,EACX,uBAAuB,EACxB,MAAM,YAAY,CAAC;AAEpB;;;;;GAKG;AACH,MAAM,WAAW,wBAAwB,CACvC,CAAC,EACD,KAAK,GAAG,GAAG,EACX,CAAC,GAAG,YAAY,CAChB,SAAQ,IAAI,CAAC,eAAe,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,EAAE,SAAS,CAAC;IACrD;;;;;;;;;;;;;;OAcG;IACH,eAAe,CAAC,EAAE,uBAAuB,CAAC,CAAC,CAAC,CAAC;CAC9C;AAED;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,CAAC,GAAG,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC,GAAG,YAAY,IAAI;KAC5E,CAAC,IAAI,MAAM,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,SAAS,WAAW,GACzC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,GACpB,KAAK,GAAG,GAAG,CAAC,CAAC,CAAC,SAAS,WAAW,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,GACpD,CAAC,OAAO,CAAC,EAAE,wBAAwB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,cAAc,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GACxE,KAAK;CACV,CAAC;AAyCF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC/B,CAAC,GAAG,YAAY,EAChB,OAAO,EAAE,0BAA0B,CAAC,GAAG,CAAC,GAAG,aAAa,CAAC,GAAG,EAAE,CAAC,CAAC,CAoBjE"}

package/dist/api/index.d.ts

@@ -0,0 +1,4 @@
+export * from './apiHooks';
+export * from './createExecuteApiHooks';
+export * from './createQueryApiHooks';
+//# sourceMappingURL=index.d.ts.map