@ahoo-wang/fetcher-react 3.4.1 → 3.4.2

package/README.md

@@ -26,31 +26,41 @@ robust data fetching capabilities.
 ## Table of Contents
 
 - [Installation](#installation)
+- [Quick Start](#quick-start)
 - [Usage](#usage)
-  - [useFetcher Hook](#usefetcher-hook)
+  - [Core Hooks](#core-hooks)
+    - [useFetcher](#usefetcher-hook)
+    - [useExecutePromise](#useexecutepromise-hook)
+    - [usePromiseState](#usepromisestate-hook)
   - [Debounced Hooks](#debounced-hooks)
     - [useDebouncedCallback](#usedebouncedcallback)
     - [useDebouncedExecutePromise](#usedebouncedexecutepromise)
     - [useDebouncedFetcher](#usedebouncedfetcher)
-  - [useExecutePromise Hook](#useexecutepromise-hook)
-  - [usePromiseState Hook](#usepromisestate-hook)
-  - [useRequestId Hook](#userequestid-hook)
-  - [useLatest Hook](#uselatest-hook)
-- [useRefs Hook](#userefs-hook)
-- [useEventSubscription Hook](#useeventsubscription-hook)
-- [useKeyStorage Hook](#usekeystorage-hook)
-  - [useImmerKeyStorage Hook](#useimmerkeystorage-hook)
-- [Wow Query Hooks](#wow-query-hooks)
-  - [useListQuery Hook](#uselistquery-hook)
-  - [usePagedQuery Hook](#usepagedquery-hook)
-  - [useSingleQuery Hook](#usesinglequery-hook)
-  - [useCountQuery Hook](#usecountquery-hook)
-  - [useFetcherCountQuery Hook](#usefetchercountquery-hook)
-  - [useFetcherPagedQuery Hook](#usefetcherpagedquery-hook)
-  - [useFetcherListQuery Hook](#usefetcherlistquery-hook)
-  - [useFetcherListStreamQuery Hook](#usefetcherliststreamquery-hook)
-  - [useFetcherSingleQuery Hook](#usefetchersinglequery-hook)
-  - [useListStreamQuery Hook](#useliststreamquery-hook)
+    - [useDebouncedFetcherQuery](#usedebouncedfetcherquery)
+    - [useDebouncedQuery](#usedebouncedquery)
+  - [Utility Hooks](#utility-hooks)
+    - [useRequestId](#userequestid-hook)
+    - [useLatest](#uselatest-hook)
+    - [useRefs](#userefs-hook)
+  - [Storage Hooks](#storage-hooks)
+    - [useKeyStorage](#usekeystorage-hook)
+    - [useImmerKeyStorage](#useimmerkeystorage-hook)
+  - [Event Hooks](#event-hooks)
+    - [useEventSubscription](#useeventsubscription-hook)
+  - [Wow Query Hooks](#wow-query-hooks)
+    - [Basic Query Hooks](#basic-query-hooks)
+      - [useListQuery](#uselistquery-hook)
+      - [usePagedQuery](#usepagedquery-hook)
+      - [useSingleQuery](#usesinglequery-hook)
+      - [useCountQuery](#usecountquery-hook)
+    - [Fetcher Query Hooks](#fetcher-query-hooks)
+      - [useFetcherListQuery](#usefetcherlistquery-hook)
+      - [useFetcherPagedQuery](#usefetcherpagedquery-hook)
+      - [useFetcherSingleQuery](#usefetchersinglequery-hook)
+      - [useFetcherCountQuery](#usefetchercountquery-hook)
+    - [Stream Query Hooks](#stream-query-hooks)
+      - [useListStreamQuery](#useliststreamquery-hook)
+      - [useFetcherListStreamQuery](#usefetcherliststreamquery-hook)
 - [Best Practices](#best-practices)
 - [API Reference](#api-reference)
 - [License](#license)
@@ -63,7 +73,7 @@ npm install @ahoo-wang/fetcher-react
 
 ### Requirements
 
-- React 16.8+ (hooks support)
+- React 19.0+ (hooks support)
 - TypeScript 4.0+ (for full type safety)
 
 ## Quick Start
@@ -91,7 +101,9 @@ function App() {
 
 ## Usage
 
-### useFetcher Hook
+### Core Hooks
+
+#### useFetcher Hook
 
 The `useFetcher` hook provides complete data fetching capabilities with automatic state management, race condition
 protection, and flexible configuration options. It includes built-in AbortController support inherited from `useExecutePromise`.
@@ -273,6 +285,178 @@ const SearchInput = () => {
 - **Trailing Edge**: Execute after delay on last call (default behavior)
 - **Leading + Trailing**: Execute immediately, then again after delay if called again
 
+#### useDebouncedFetcherQuery
+
+Combines query-based HTTP fetching with debouncing, perfect for search inputs and dynamic query scenarios where you want to debounce API calls based on query parameters.
+
+```typescript jsx
+import { useDebouncedFetcherQuery } from '@ahoo-wang/fetcher-react';
+
+interface SearchQuery {
+  keyword: string;
+  limit: number;
+  filters?: { category?: string };
+}
+
+interface SearchResult {
+  items: Array<{ id: string; title: string }>;
+  total: number;
+}
+
+const SearchComponent = () => {
+  const {
+    loading,
+    result,
+    error,
+    run,
+    cancel,
+    isPending,
+    setQuery,
+    getQuery,
+  } = useDebouncedFetcherQuery<SearchQuery, SearchResult>({
+    url: '/api/search',
+    initialQuery: { keyword: '', limit: 10 },
+    debounce: { delay: 300 }, // Debounce for 300ms
+    autoExecute: false, // Don't execute on mount
+  });
+
+  const handleSearch = (keyword: string) => {
+    setQuery({ keyword, limit: 10 }); // This will trigger debounced execution if autoExecute was true
+  };
+
+  const handleManualSearch = () => {
+    run(); // Manual debounced execution with current query
+  };
+
+  const handleCancel = () => {
+    cancel(); // Cancel any pending debounced execution
+  };
+
+  if (loading) return <div>Searching...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+
+  return (
+    <div>
+      <input
+        type="text"
+        onChange={(e) => handleSearch(e.target.value)}
+        placeholder="Search..."
+      />
+      <button onClick={handleManualSearch} disabled={isPending()}>
+        {isPending() ? 'Searching...' : 'Search'}
+      </button>
+      <button onClick={handleCancel}>Cancel</button>
+      {result && (
+        <div>
+          Found {result.total} items:
+          {result.items.map(item => (
+            <div key={item.id}>{item.title}</div>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+};
+```
+
+**Key Features:**
+
+- **Query State Management**: Automatic query parameter handling with `setQuery` and `getQuery`
+- **Debounced Execution**: Prevents excessive API calls during rapid user input
+- **Auto-Execution**: Optional automatic execution when query parameters change
+- **Manual Control**: `run()` for manual execution, `cancel()` for cancellation
+- **Pending State**: `isPending()` to check if a debounced call is queued
+
+#### useDebouncedQuery
+
+Combines general query execution with debouncing, perfect for custom query operations where you want to debounce execution based on query parameters.
+
+```typescript jsx
+import { useDebouncedQuery } from '@ahoo-wang/fetcher-react';
+
+interface SearchQuery {
+  keyword: string;
+  limit: number;
+  filters?: { category?: string };
+}
+
+interface SearchResult {
+  items: Array<{ id: string; title: string }>;
+  total: number;
+}
+
+const SearchComponent = () => {
+  const {
+    loading,
+    result,
+    error,
+    run,
+    cancel,
+    isPending,
+    setQuery,
+    getQuery,
+  } = useDebouncedQuery<SearchQuery, SearchResult>({
+    initialQuery: { keyword: '', limit: 10 },
+    execute: async (query) => {
+      const response = await fetch('/api/search', {
+        method: 'POST',
+        body: JSON.stringify(query),
+        headers: { 'Content-Type': 'application/json' },
+      });
+      return response.json();
+    },
+    debounce: { delay: 300 }, // Debounce for 300ms
+    autoExecute: false, // Don't execute on mount
+  });
+
+  const handleSearch = (keyword: string) => {
+    setQuery({ keyword, limit: 10 }); // This will trigger debounced execution if autoExecute was true
+  };
+
+  const handleManualSearch = () => {
+    run(); // Manual debounced execution with current query
+  };
+
+  const handleCancel = () => {
+    cancel(); // Cancel any pending debounced execution
+  };
+
+  if (loading) return <div>Searching...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+
+  return (
+    <div>
+      <input
+        type="text"
+        onChange={(e) => handleSearch(e.target.value)}
+        placeholder="Search..."
+      />
+      <button onClick={handleManualSearch} disabled={isPending()}>
+        {isPending() ? 'Searching...' : 'Search'}
+      </button>
+      <button onClick={handleCancel}>Cancel</button>
+      {result && (
+        <div>
+          Found {result.total} items:
+          {result.items.map(item => (
+            <div key={item.id}>{item.title}</div>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+};
+```
+
+**Key Features:**
+
+- **Query State Management**: Automatic query parameter handling with `setQuery` and `getQuery`
+- **Debounced Execution**: Prevents excessive operations during rapid query changes
+- **Auto-Execution**: Optional automatic execution when query parameters change
+- **Manual Control**: `run()` for manual execution, `cancel()` for cancellation
+- **Pending State**: `isPending()` to check if a debounced call is queued
+- **Custom Execution**: Flexible execute function for any query operation
+
 ### useExecutePromise Hook
 
 The `useExecutePromise` hook manages asynchronous operations with automatic state handling, built-in race condition
@@ -387,7 +571,9 @@ const MyComponent = () => {
 };
 ```
 
-### useRequestId Hook
+### Utility Hooks
+
+#### useRequestId Hook
 
 The `useRequestId` hook provides request ID management for preventing race conditions in async operations.
 
@@ -482,7 +668,9 @@ Key features:
 - **Automatic Cleanup**: Refs are cleared when component unmounts
 - **Type Safety**: Full TypeScript support for ref types
 
-### useEventSubscription Hook
+### Event Hooks
+
+#### useEventSubscription Hook
 
 The `useEventSubscription` hook provides a React interface for subscribing to typed event buses. It automatically manages subscription lifecycle while offering manual control functions for additional flexibility.
 
@@ -523,7 +711,9 @@ Key features:
 - **Error Handling**: Logs warnings for failed subscription attempts
 - **Event Bus Integration**: Works seamlessly with `@ahoo-wang/fetcher-eventbus` TypedEventBus instances
 
-### useKeyStorage Hook
+### Storage Hooks
+
+#### useKeyStorage Hook
 
 The `useKeyStorage` hook provides reactive state management for a KeyStorage instance. It subscribes to storage changes and returns the current value along with a setter function. Optionally accepts a default value to use when the storage is empty.
 
@@ -863,7 +1053,9 @@ The Wow Query Hooks provide advanced data querying capabilities with built-in st
 projections, sorting, pagination, and limits. These hooks are designed to work with the `@ahoo-wang/fetcher-wow` package
 for complex query operations.
 
-### useListQuery Hook
+### Basic Query Hooks
+
+#### useListQuery Hook
 
 The `useListQuery` hook manages list queries with state management for conditions, projections, sorting, and limits.
 
@@ -1134,7 +1326,9 @@ const MyComponent = () => {
 };
 ```
 
-### useFetcherCountQuery Hook
+### Fetcher Query Hooks
+
+#### useFetcherCountQuery Hook
 
 The `useFetcherCountQuery` hook is a specialized React hook for performing count queries using the Fetcher library. It is designed for scenarios where you need to retrieve the count of records that match a specific condition, returning a number representing the count.
 
@@ -1575,7 +1769,9 @@ const MyComponent = () => {
 };
 ```
 
-### useListStreamQuery Hook
+### Stream Query Hooks
+
+#### useListStreamQuery Hook
 
 The `useListStreamQuery` hook manages list stream queries that return a readable stream of server-sent events.
 
@@ -2266,6 +2462,88 @@ An object containing:
 - `cancel`: Function to cancel any pending debounced execution
 - `isPending`: Boolean indicating if a debounced call is pending
 
+#### useDebouncedFetcherQuery
+
+```typescript
+function useDebouncedFetcherQuery<Q, R, E = FetcherError>(
+  options: UseDebouncedFetcherQueryOptions<Q, R, E>,
+): UseDebouncedFetcherQueryReturn<Q, R, E>;
+```
+
+Combines query-based HTTP fetching with debouncing, perfect for search inputs and dynamic query scenarios.
+
+**Type Parameters:**
+
+- `Q`: The type of the query parameters
+- `R`: The type of the fetch result
+- `E`: The type of the error (defaults to FetcherError)
+
+**Parameters:**
+
+- `options`: Configuration object extending `UseFetcherQueryOptions` and `DebounceCapable`
+  - `url`: The API endpoint URL (required)
+  - `initialQuery`: Initial query parameters (required)
+  - `autoExecute?`: Whether to execute automatically on mount or query changes
+  - `debounce`: Debounce configuration (delay, leading, trailing)
+  - HTTP request options (method, headers, timeout, etc.)
+
+**Returns:**
+
+An object containing:
+
+- `loading`: Boolean indicating if the fetch is currently executing
+- `result`: The resolved value of the fetch
+- `error`: Any error that occurred during execution
+- `status`: Current execution status
+- `reset`: Function to reset the fetcher state
+- `abort`: Function to abort the current operation
+- `getQuery`: Function to get the current query parameters
+- `setQuery`: Function to update query parameters
+- `run`: Function to execute the debounced fetch with current query
+- `cancel`: Function to cancel any pending debounced execution
+- `isPending`: Function that returns true if a debounced execution is currently pending
+
+#### useDebouncedQuery
+
+```typescript
+function useDebouncedQuery<Q, R, E = FetcherError>(
+  options: UseDebouncedQueryOptions<Q, R, E>,
+): UseDebouncedQueryReturn<Q, R, E>;
+```
+
+Combines general query execution with debouncing, perfect for custom query operations.
+
+**Type Parameters:**
+
+- `Q`: The type of the query parameters
+- `R`: The type of the result
+- `E`: The type of the error (defaults to FetcherError)
+
+**Parameters:**
+
+- `options`: Configuration object extending `UseQueryOptions` and `DebounceCapable`
+  - `initialQuery`: Initial query parameters (required)
+  - `execute`: Function to execute the query with parameters
+  - `autoExecute?`: Whether to execute automatically on mount or query changes
+  - `debounce`: Debounce configuration (delay, leading, trailing)
+  - All options from `UseExecutePromiseOptions`
+
+**Returns:**
+
+An object containing:
+
+- `loading`: Boolean indicating if the query is currently executing
+- `result`: The resolved value of the query
+- `error`: Any error that occurred during execution
+- `status`: Current execution status
+- `reset`: Function to reset the query state
+- `abort`: Function to abort the current operation
+- `getQuery`: Function to get the current query parameters
+- `setQuery`: Function to update query parameters
+- `run`: Function to execute the debounced query with current parameters
+- `cancel`: Function to cancel any pending debounced execution
+- `isPending`: Function that returns true if a debounced execution is currently pending
+
 ### useFetcher
 
 ```typescript