@ahoo-wang/fetcher-react 3.4.1 → 3.4.2

package/dist/wow/debounce/index.d.ts

@@ -1,2 +1,3 @@
+export * from './useDebouncedFetcherQuery';
 export * from './useDebouncedQuery';
 //# sourceMappingURL=index.d.ts.map

package/dist/wow/debounce/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/wow/debounce/index.ts"],"names":[],"mappings":"AAaA,cAAc,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/wow/debounce/index.ts"],"names":[],"mappings":"AAaA,cAAc,4BAA4B,CAAC;AAC3C,cAAc,qBAAqB,CAAC"}

package/dist/wow/debounce/useDebouncedFetcherQuery.d.ts

@@ -0,0 +1,112 @@
+import { FetcherError } from '@ahoo-wang/fetcher';
+import { DebounceCapable, UseDebouncedCallbackReturn } from '../../core';
+import { UseFetcherQueryOptions, UseFetcherQueryReturn } from '../useFetcherQuery';
+/**
+ * Configuration options for the useDebouncedFetcherQuery hook
+ * @template Q - The type of the query parameters
+ * @template R - The type of the result value
+ * @template E - The type of the error value (defaults to FetcherError)
+ */
+export interface UseDebouncedFetcherQueryOptions<Q, R, E = FetcherError> extends UseFetcherQueryOptions<Q, R, E>, DebounceCapable {
+}
+/**
+ * Return type of the useDebouncedFetcherQuery hook
+ * @template Q - The type of the query parameters
+ * @template R - The type of the result value
+ * @template E - The type of the error value (defaults to FetcherError)
+ */
+export interface UseDebouncedFetcherQueryReturn<Q, R, E = FetcherError> extends Omit<UseFetcherQueryReturn<Q, R, E>, 'execute'>, UseDebouncedCallbackReturn<UseFetcherQueryReturn<Q, R, E>['execute']> {
+}
+/**
+ * A React hook for managing debounced query-based HTTP requests with automatic execution
+ *
+ * This hook combines the fetcher query functionality with debouncing to provide
+ * a convenient way to make POST requests where query parameters are sent as the request body,
+ * with built-in debouncing to prevent excessive API calls during rapid user interactions.
+ *
+ * The hook supports automatic execution on mount and when query parameters change,
+ * but wraps the execution in a debounced callback to optimize performance.
+ *
+ * @template Q - The type of the query parameters
+ * @template R - The type of the result value
+ * @template E - The type of the error value (defaults to FetcherError)
+ * @param options - Configuration options for the hook
+ * @returns An object containing fetcher state, query management functions, and debounced execution controls
+ *
+ * @example
+ * ```typescript
+ * 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;
+ * }
+ *
+ * function 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>
+ *   );
+ * }
+ * ```
+ *
+ * @throws This hook may throw exceptions related to network requests, which should be
+ * handled by the caller. The underlying fetcher may throw FetcherError or other network-related errors.
+ * Invalid URL or malformed request options may also cause exceptions.
+ */
+export declare function useDebouncedFetcherQuery<Q, R, E = FetcherError>(options: UseDebouncedFetcherQueryOptions<Q, R, E>): UseDebouncedFetcherQueryReturn<Q, R, E>;
+//# sourceMappingURL=useDebouncedFetcherQuery.d.ts.map

package/dist/wow/debounce/useDebouncedFetcherQuery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useDebouncedFetcherQuery.d.ts","sourceRoot":"","sources":["../../../src/wow/debounce/useDebouncedFetcherQuery.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EACL,eAAe,EAEf,0BAA0B,EAC3B,MAAM,YAAY,CAAC;AAEpB,OAAO,EAEL,sBAAsB,EACtB,qBAAqB,EACtB,MAAM,oBAAoB,CAAC;AAE5B;;;;;GAKG;AACH,MAAM,WAAW,+BAA+B,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,YAAY,CACrE,SAAQ,sBAAsB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,eAAe;CAAG;AAE7D;;;;;GAKG;AACH,MAAM,WAAW,8BAA8B,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,YAAY,CACpE,SACE,IAAI,CAAC,qBAAqB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,SAAS,CAAC,EAC/C,0BAA0B,CAAC,qBAAqB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;CAAG;AAE5E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0FG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,YAAY,EAC7D,OAAO,EAAE,+BAA+B,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAChD,8BAA8B,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CA4CzC"}

package/dist/wow/debounce/useDebouncedQuery.d.ts

@@ -2,46 +2,118 @@ import { FetcherError } from '@ahoo-wang/fetcher';
 import { UseQueryOptions, UseQueryReturn } from '../useQuery';
 import { DebounceCapable, UseDebouncedCallbackReturn } from '../../core';
 /**
- * Options for the useDebouncedQuery hook, extending UseQueryOptions with debouncing capabilities.
- * @template Q - The query type
- * @template R - The result type
- * @template E - The error type, defaults to FetcherError
+ * Configuration options for the useDebouncedQuery hook
+ * @template Q - The type of the query parameters
+ * @template R - The type of the result value
+ * @template E - The type of the error value (defaults to FetcherError)
  */
 export interface UseDebouncedQueryOptions<Q, R, E = FetcherError> extends UseQueryOptions<Q, R, E>, DebounceCapable {
 }
 /**
- * Return type for the useDebouncedQuery hook, including query state and debounced execution methods.
- * @template Q - The query type
- * @template R - The result type
- * @template E - The error type, defaults to FetcherError
+ * Return type of the useDebouncedQuery hook
+ * @template Q - The type of the query parameters
+ * @template R - The type of the result value
+ * @template E - The type of the error value (defaults to FetcherError)
  */
 export interface UseDebouncedQueryReturn<Q, R, E = FetcherError> extends Omit<UseQueryReturn<Q, R, E>, 'execute'>, UseDebouncedCallbackReturn<UseQueryReturn<Q, R, E>['execute']> {
 }
 /**
- * A React hook that provides debounced query execution, combining the useQuery hook with debouncing functionality
- * to prevent excessive API calls during rapid query changes.
+ * A React hook for managing debounced query execution with automatic state management
  *
- * @template Q - The query type
- * @template R - The result type
- * @template E - The error type, defaults to FetcherError
- * @param options - Configuration options for the query and debouncing behavior, including debounce settings
- * @returns An object containing query state (loading, result, error, status) and debounced execution methods (run, cancel, isPending)
+ * This hook combines the query functionality with debouncing to provide
+ * a convenient way to execute queries with built-in debouncing to prevent excessive
+ * operations during rapid query changes, such as in search inputs or dynamic filtering.
+ *
+ * The hook supports automatic execution on mount and when query parameters change,
+ * but wraps the execution in a debounced callback to optimize performance.
+ *
+ * @template Q - The type of the query parameters
+ * @template R - The type of the result value
+ * @template E - The type of the error value (defaults to FetcherError)
+ * @param options - Configuration options for the hook
+ * @returns An object containing query state, query management functions, and debounced execution controls
  *
  * @example
  * ```typescript
- * const { loading, result, error, run, cancel, isPending } = useDebouncedQuery({
- *   url: '/api/search',
- *   debounce: 300,
- * });
+ * 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;
+ * }
+ *
+ * function 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
+ *   };
  *
- * // Trigger debounced query
- * run({ q: 'search term' });
+ *   if (loading) return <div>Searching...</div>;
+ *   if (error) return <div>Error: {error.message}</div>;
  *
- * // Cancel pending debounced query
- * cancel();
+ *   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>
+ *   );
+ * }
  * ```
  *
- * @throws {FetcherError} When the underlying query execution fails
+ * @throws This hook may throw exceptions related to query execution, which should be
+ * handled by the caller. The execute function may throw FetcherError or other errors.
+ * Invalid query parameters or execution function errors may also cause exceptions.
  */
 export declare function useDebouncedQuery<Q, R, E = FetcherError>(options: UseDebouncedQueryOptions<Q, R, E>): UseDebouncedQueryReturn<Q, R, E>;
 //# sourceMappingURL=useDebouncedQuery.d.ts.map

package/dist/wow/debounce/useDebouncedQuery.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useDebouncedQuery.d.ts","sourceRoot":"","sources":["../../../src/wow/debounce/useDebouncedQuery.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAY,eAAe,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AACxE,OAAO,EACL,eAAe,EAEf,0BAA0B,EAC3B,MAAM,YAAY,CAAC;AAGpB;;;;;GAKG;AACH,MAAM,WAAW,wBAAwB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,YAAY,CAC9D,SAAQ,eAAe,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAC9B,eAAe;CAAG;AAEtB;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,YAAY,CAC7D,SAAQ,IAAI,CAAC,cAAc,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,SAAS,CAAC,EAC9C,0BAA0B,CAAC,cAAc,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;CAAG;AAErE;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,YAAY,EACtD,OAAO,EAAE,wBAAwB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GACzC,uBAAuB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CA4ClC"}
+{"version":3,"file":"useDebouncedQuery.d.ts","sourceRoot":"","sources":["../../../src/wow/debounce/useDebouncedQuery.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAY,eAAe,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AACxE,OAAO,EACL,eAAe,EAEf,0BAA0B,EAC3B,MAAM,YAAY,CAAC;AAGpB;;;;;GAKG;AACH,MAAM,WAAW,wBAAwB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,YAAY,CAC9D,SAAQ,eAAe,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,eAAe;CAAG;AAEtD;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,YAAY,CAC7D,SACE,IAAI,CAAC,cAAc,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,SAAS,CAAC,EACxC,0BAA0B,CAAC,cAAc,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;CAAG;AAErE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiGG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,YAAY,EACtD,OAAO,EAAE,wBAAwB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GACzC,uBAAuB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CA4ClC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahoo-wang/fetcher-react",
-  "version": "3.4.1",
+  "version": "3.4.2",
   "description": "React integration for Fetcher HTTP client. Provides React Hooks and components for seamless data fetching with automatic re-rendering and loading states.",
   "keywords": [
     "fetch",