@ahoo-wang/fetcher-react 3.9.2 → 3.9.5

package/README.md

@@ -21,6 +21,7 @@ robust data fetching capabilities.
 - ⚡ **Performance**: Optimized with useMemo, useCallback, and smart dependency management
 - 🎯 **Options Flexibility**: Support for both static options and dynamic option suppliers
 - 🔧 **Developer Experience**: Built-in loading states, error handling, and automatic re-rendering
+- 🏗️ **API Hooks Generation**: Automatic type-safe React hooks generation from API objects
 - 📊 **Advanced Query Hooks**: Specialized hooks for list, paged, single, count, and stream queries with state management
 
 ## Table of Contents
@@ -28,6 +29,7 @@ robust data fetching capabilities.
 - [Installation](#installation)
 - [Quick Start](#quick-start)
 - [Usage](#usage)
+  - [API Hooks](#api-hooks)
   - [Core Hooks](#core-hooks)
     - [useExecutePromise](#useexecutepromise-hook)
     - [usePromiseState](#usepromisestate-hook)
@@ -111,6 +113,369 @@ function App() {
 
 ## Usage
 
+### API Hooks
+
+#### createExecuteApiHooks
+
+🚀 **Automatic Type-Safe API Hooks Generation** - Generate fully typed React hooks from API objects with automatic method discovery, class method support, and advanced execution control.
+
+The `createExecuteApiHooks` function automatically discovers all function methods from an API object (including prototype chains for class instances) and creates corresponding React hooks with the naming pattern `use{CapitalizedMethodName}`. Each generated hook provides full state management, error handling, and supports custom execution callbacks with type-safe parameter access.
+
+**Key Features:**
+
+- **Automatic Method Discovery**: Traverses object properties and prototype chains
+- **Type-Safe Hook Generation**: Full TypeScript inference for parameters and return types
+- **Class Method Support**: Handles both static methods and class instances with `this` binding
+- **Execution Control**: `onBeforeExecute` callback for parameter inspection/modification and abort controller access
+- **Custom Error Types**: Support for specifying error types beyond the default `FetcherError`
+
+```typescript jsx
+import { createExecuteApiHooks } from '@ahoo-wang/fetcher-react';
+import { api, get, post, patch, path, body, autoGeneratedError } from '@ahoo-wang/fetcher-decorator';
+
+// Define your API service using decorators
+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();
+
+// Generate type-safe hooks
+const apiHooks = createExecuteApiHooks({ api: userApi });
+
+function UserComponent() {
+  // Hooks are automatically generated with proper typing
+  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 is fully typed as [data: { name: string; email: string }]
+      const [data] = args;
+      // Modify parameters in place if needed
+      data.email = data.email.toLowerCase();
+      // Access abort controller for custom cancellation
+      abortController.signal.addEventListener('abort', () => {
+        console.log('User creation cancelled');
+      });
+    },
+  });
+
+  const handleFetchUser = (userId: string) => {
+    getUser(userId); // Fully typed - only accepts string parameter
+  };
+
+  const handleCreateUser = (userData: { name: string; email: string }) => {
+    createUser(userData); // Fully typed - only accepts correct data shape
+  };
+
+  return (
+    <div>
+      <button onClick={() => handleFetchUser('123')}>
+        Fetch User
+      </button>
+      {getLoading && <div>Loading user...</div>}
+      {getError && <div>Error: {getError.message}</div>}
+      {user && <div>User: {user.name}</div>}
+
+      <button onClick={() => handleCreateUser({ name: 'John', email: 'john@example.com' })}>
+        Create User
+      </button>
+      {createLoading && <div>Creating user...</div>}
+      {createError && <div>Error: {createError.message}</div>}
+      {createdUser && <div>Created: {createdUser.name}</div>}
+    </div>
+  );
+}
+```
+
+**Custom Error Types:**
+
+```typescript jsx
+import { createExecuteApiHooks } from '@ahoo-wang/fetcher-react';
+
+// Define custom error type
+class ApiError extends Error {
+  constructor(
+    public statusCode: number,
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+// Generate hooks with custom error type
+@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 is now typed as ApiError | undefined
+  if (error) {
+    console.log('Status code:', error.statusCode); // TypeScript knows about statusCode
+  }
+}
+```
+
+**Advanced Usage with Class Methods:**
+
+```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 method example
+  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 });
+
+// Generated hooks: useGet, usePost
+// Static methods are also discovered: useHealthCheck
+
+function ApiComponent() {
+  const { execute: getData } = apiHooks.useGet();
+  const { execute: postData } = apiHooks.usePost();
+  const { execute: healthCheck } = apiHooks.useHealthCheck();
+
+  return (
+    <div>
+      <button onClick={() => getData('/users')}>Get Users</button>
+      <button onClick={() => postData('/users', { name: 'New User' })}>Create User</button>
+      <button onClick={() => healthCheck()}>Health Check</button>
+    </div>
+  );
+}
+```
+
+#### createQueryApiHooks
+
+🚀 **Automatic Type-Safe Query API Hooks Generation** - Generate fully typed React query hooks from API objects with automatic query state management, auto-execution, and advanced execution control.
+
+The `createQueryApiHooks` function automatically discovers query methods from an API object and creates corresponding React hooks that extend `useQuery`. Each generated hook provides automatic query parameter management, state management, and supports custom execution callbacks with type-safe query access.
+
+**Key Features:**
+
+- **Automatic Method Discovery**: Traverses object properties and prototype chains
+- **Type-Safe Query Hooks**: Full TypeScript inference for query parameters and return types
+- **Query State Management**: Built-in `setQuery` and `getQuery` for parameter management
+- **Auto-Execution**: Optional automatic execution when query parameters change
+- **Execution Control**: `onBeforeExecute` callback for query inspection/modification and abort controller access
+- **Custom Error Types**: Support for specifying error types beyond the default `FetcherError`
+
+```typescript jsx
+import { createQueryApiHooks } from '@ahoo-wang/fetcher-react';
+import { api, get, post, patch, path, body, autoGeneratedError } from '@ahoo-wang/fetcher-decorator';
+
+// Define your API service using decorators
+@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 is fully typed as UserListQuery
+      console.log('Executing query:', query);
+      // Modify query parameters in place if needed
+      query.page = Math.max(1, query.page);
+    },
+  });
+
+  const handlePageChange = (page: number) => {
+    // Automatically updates query and triggers execution (if autoExecute: true)
+    setQuery({ ...getQuery(), page });
+  };
+
+  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>
+  );
+}
+
+function UserDetailComponent() {
+  const { result: user, execute } = apiHooks.useGetUser({
+    initialQuery: { id: '123' },
+  });
+
+  return (
+    <div>
+      <button onClick={execute}>Load User</button>
+      {user && <div>User: {user.name}</div>}
+    </div>
+  );
+}
+```
+
+**Custom Error Types:**
+
+```typescript jsx
+import { createQueryApiHooks } from '@ahoo-wang/fetcher-react';
+
+// Define custom error type
+class ApiError extends Error {
+  constructor(
+    public statusCode: number,
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+// Generate query hooks with custom error type
+@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 is now typed as ApiError | undefined
+  if (error) {
+    console.log('Status code:', error.statusCode); // TypeScript knows about statusCode
+  }
+}
+```
+
+**Advanced Usage with Manual Query Management:**
+
+```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, // Manual execution control
+  });
+
+  const handleSearch = (searchTerm: string) => {
+    // Update query without automatic execution
+    setQuery({ search: searchTerm, page: 1 });
+  };
+
+  const handleSearchSubmit = () => {
+    // Manually execute with current query
+    apiHooks.useGetUsers().execute();
+  };
+
+  const currentQuery = getQuery(); // Access current query parameters
+
+  return (
+    <div>
+      <input
+        value={currentQuery.search}
+        onChange={(e) => handleSearch(e.target.value)}
+        placeholder="Search users..."
+      />
+      <button onClick={handleSearchSubmit} disabled={loading}>
+        {loading ? 'Searching...' : 'Search'}
+      </button>
+      {result?.map(user => (
+        <div key={user.id}>{user.name}</div>
+      ))}
+    </div>
+  );
+}
+```
+
 ### Core Hooks
 
 #### useExecutePromise Hook