@ahoo-wang/fetcher-react 2.13.10 → 2.15.0

package/README.md

@@ -27,6 +27,10 @@ robust data fetching capabilities.
 - [Installation](#installation)
 - [Usage](#usage)
   - [useFetcher Hook](#usefetcher-hook)
+  - [Debounced Hooks](#debounced-hooks)
+    - [useDebouncedCallback](#usedebouncedcallback)
+    - [useDebouncedExecutePromise](#usedebouncedexecutepromise)
+    - [useDebouncedFetcher](#usedebouncedfetcher)
   - [useExecutePromise Hook](#useexecutepromise-hook)
   - [usePromiseState Hook](#usepromisestate-hook)
   - [useRequestId Hook](#userequestid-hook)
@@ -125,6 +129,133 @@ const MyComponent = () => {
 };
 ```
 
+### Debounced Hooks
+
+🚀 **Advanced Debouncing for React Applications** - Powerful hooks that combine debouncing with async operations, providing seamless rate limiting for API calls, user interactions, and promise execution.
+
+#### useDebouncedCallback
+
+A React hook that provides a debounced version of any callback function with leading/trailing edge execution options.
+
+```typescript jsx
+import { useDebouncedCallback } from '@ahoo-wang/fetcher-react';
+
+const SearchComponent = () => {
+  const { run: debouncedSearch, cancel, isPending } = useDebouncedCallback(
+    async (query: string) => {
+      const response = await fetch(`/api/search?q=${query}`);
+      const results = await response.json();
+      console.log('Search results:', results);
+    },
+    { delay: 300 }
+  );
+
+  const handleSearch = (query: string) => {
+    if (query.trim()) {
+      debouncedSearch(query);
+    } else {
+      cancel(); // Cancel any pending search
+    }
+  };
+
+  return (
+    <div>
+      <input
+        type="text"
+        placeholder="Search..."
+        onChange={(e) => handleSearch(e.target.value)}
+      />
+      {isPending() && <div>Searching...</div>}
+    </div>
+  );
+};
+```
+
+**Configuration Options:**
+
+- `delay`: Delay in milliseconds before execution (required, positive number)
+- `leading`: Execute immediately on first call (default: false)
+- `trailing`: Execute after delay on last call (default: true)
+
+#### useDebouncedExecutePromise
+
+Combines promise execution with debouncing functionality, perfect for API calls and async operations.
+
+```typescript jsx
+import { useDebouncedExecutePromise } from '@ahoo-wang/fetcher-react';
+
+const DataFetcher = () => {
+  const { loading, result, error, run } = useDebouncedExecutePromise({
+    promise: async (userId: string) => {
+      const response = await fetch(`/api/users/${userId}`);
+      return response.json();
+    },
+    debounce: { delay: 300 },
+    onSuccess: (user) => console.log('User loaded:', user),
+    onError: (error) => console.error('Failed to load user:', error),
+  });
+
+  return (
+    <div>
+      <button onClick={() => run('user123')}>
+        Load User
+      </button>
+      {loading && <div>Loading...</div>}
+      {error && <div>Error: {error.message}</div>}
+      {result && <div>User: {result.name}</div>}
+    </div>
+  );
+};
+```
+
+#### useDebouncedFetcher
+
+Specialized hook combining HTTP fetching with debouncing, built on top of the core fetcher library.
+
+```typescript jsx
+import { useDebouncedFetcher } from '@ahoo-wang/fetcher-react';
+
+const SearchInput = () => {
+  const [query, setQuery] = useState('');
+  const { loading, result, error, run } = useDebouncedFetcher({
+    debounce: { delay: 300 },
+    onSuccess: (data) => {
+      setSearchResults(data.results);
+    }
+  });
+
+  const handleChange = (value: string) => {
+    setQuery(value);
+    if (value.trim()) {
+      run({
+        url: '/api/search',
+        method: 'GET',
+        params: { q: value }
+      });
+    }
+  };
+
+  return (
+    <div>
+      <input
+        value={query}
+        onChange={(e) => handleChange(e.target.value)}
+        placeholder="Search..."
+      />
+      {loading && <div>Searching...</div>}
+      {error && <div>Error: {error.message}</div>}
+      {result && <SearchResults data={result} />}
+    </div>
+  );
+};
+```
+
+**Debouncing Strategies:**
+
+- **Leading Edge**: Execute immediately on first call, then debounce subsequent calls
+- **Trailing Edge**: Execute after delay on last call (default behavior)
+- **Leading + Trailing**: Execute immediately, then again after delay if called again
+
 ### useExecutePromise Hook
 
 The `useExecutePromise` hook manages asynchronous operations with automatic state handling, built-in race condition
@@ -1259,6 +1390,107 @@ describe('useListQuery', () => {
 
 ## API Reference
 
+### Debounced Hooks
+
+#### useDebouncedCallback
+
+```typescript
+function useDebouncedCallback<T extends (...args: any[]) => any>(
+  callback: T,
+  options: UseDebouncedCallbackOptions,
+): UseDebouncedCallbackReturn<T>;
+```
+
+A React hook that provides a debounced version of a callback function with leading/trailing edge execution options.
+
+**Type Parameters:**
+
+- `T`: The type of the callback function
+
+**Parameters:**
+
+- `callback`: The function to debounce
+- `options`: Configuration object
+  - `delay`: Delay in milliseconds before execution (required, positive number)
+  - `leading?`: Execute immediately on first call (default: false)
+  - `trailing?`: Execute after delay on last call (default: true)
+
+**Returns:**
+
+An object containing:
+
+- `run`: Function to execute the debounced callback with arguments
+- `cancel`: Function to cancel any pending debounced execution
+- `isPending`: Function that returns true if a debounced execution is currently pending
+
+#### useDebouncedExecutePromise
+
+```typescript
+function useDebouncedExecutePromise<R = unknown, E = FetcherError>(
+  options: UseDebouncedExecutePromiseOptions<R, E>,
+): UseDebouncedExecutePromiseReturn<R, E>;
+```
+
+Combines promise execution with debouncing functionality.
+
+**Type Parameters:**
+
+- `R`: The type of the promise result (defaults to unknown)
+- `E`: The type of the error (defaults to FetcherError)
+
+**Parameters:**
+
+- `options`: Configuration object containing promise execution options and debounce settings
+  - `debounce`: Debounce configuration (delay, leading, trailing)
+  - All options from `UseExecutePromiseOptions`
+
+**Returns:**
+
+An object containing:
+
+- `loading`: Boolean indicating if the promise is currently executing
+- `result`: The resolved value of the promise
+- `error`: Any error that occurred during execution
+- `status`: Current execution status
+- `run`: Debounced function to execute the promise with provided arguments
+- `cancel`: Function to cancel any pending debounced execution
+- `isPending`: Boolean indicating if a debounced call is pending
+- `reset`: Function to reset the hook state to initial values
+
+#### useDebouncedFetcher
+
+```typescript
+function useDebouncedFetcher<R, E = FetcherError>(
+  options: UseDebouncedFetcherOptions<R, E>,
+): UseDebouncedFetcherReturn<R, E>;
+```
+
+Specialized hook combining HTTP fetching with debouncing.
+
+**Type Parameters:**
+
+- `R`: The type of the fetch result
+- `E`: The type of the error (defaults to FetcherError)
+
+**Parameters:**
+
+- `options`: Configuration object extending `UseFetcherOptions` and `DebounceCapable`
+  - HTTP request options (method, headers, timeout, etc.)
+  - `debounce`: Debounce configuration (delay, leading, trailing)
+
+**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
+- `exchange`: The FetchExchange object representing the ongoing fetch operation
+- `run`: Function to execute the debounced fetch with request parameters
+- `cancel`: Function to cancel any pending debounced execution
+- `isPending`: Boolean indicating if a debounced call is pending
+
 ### useFetcher
 
 ```typescript

package/README.zh-CN.md

@@ -26,6 +26,10 @@
 - [快速开始](#快速开始)
 - [使用方法](#使用方法)
   - [useFetcher Hook](#usefetcher-hook)
+  - [防抖 Hooks](#防抖-hooks)
+    - [useDebouncedCallback](#usedebouncedcallback)
+    - [useDebouncedExecutePromise](#usedebouncedexecutepromise)
+    - [useDebouncedFetcher](#usedebouncedfetcher)
   - [useExecutePromise Hook](#useexecutepromise-hook)
   - [usePromiseState Hook](#usepromisestate-hook)
   - [useRequestId Hook](#userequestid-hook)
@@ -123,6 +127,133 @@ const MyComponent = () => {
 };
 ```
 
+### 防抖 Hooks
+
+🚀 **高级 React 防抖库** - 强大的 hooks 将防抖与异步操作相结合，为 API 调用、用户交互和 Promise 执行提供无缝的速率限制。
+
+#### useDebouncedCallback
+
+一个 React hook，为任何回调函数提供防抖版本，支持前缘/后缘执行选项。
+
+```typescript jsx
+import { useDebouncedCallback } from '@ahoo-wang/fetcher-react';
+
+const SearchComponent = () => {
+  const { run: debouncedSearch, cancel, isPending } = useDebouncedCallback(
+    async (query: string) => {
+      const response = await fetch(`/api/search?q=${query}`);
+      const results = await response.json();
+      console.log('搜索结果:', results);
+    },
+    { delay: 300 }
+  );
+
+  const handleSearch = (query: string) => {
+    if (query.trim()) {
+      debouncedSearch(query);
+    } else {
+      cancel(); // 取消任何待处理的搜索
+    }
+  };
+
+  return (
+    <div>
+      <input
+        type="text"
+        placeholder="搜索..."
+        onChange={(e) => handleSearch(e.target.value)}
+      />
+      {isPending() && <div>搜索中...</div>}
+    </div>
+  );
+};
+```
+
+**配置选项：**
+
+- `delay`: 执行前的延迟毫秒数（必需，正数）
+- `leading`: 第一次调用时立即执行（默认: false）
+- `trailing`: 最后一次调用后延迟执行（默认: true）
+
+#### useDebouncedExecutePromise
+
+将 Promise 执行与防抖功能相结合，非常适合 API 调用和异步操作。
+
+```typescript jsx
+import { useDebouncedExecutePromise } from '@ahoo-wang/fetcher-react';
+
+const DataFetcher = () => {
+  const { loading, result, error, run } = useDebouncedExecutePromise({
+    promise: async (userId: string) => {
+      const response = await fetch(`/api/users/${userId}`);
+      return response.json();
+    },
+    debounce: { delay: 300 },
+    onSuccess: (user) => console.log('用户加载:', user),
+    onError: (error) => console.error('加载用户失败:', error),
+  });
+
+  return (
+    <div>
+      <button onClick={() => run('user123')}>
+        加载用户
+      </button>
+      {loading && <div>加载中...</div>}
+      {error && <div>错误: {error.message}</div>}
+      {result && <div>用户: {result.name}</div>}
+    </div>
+  );
+};
+```
+
+#### useDebouncedFetcher
+
+专门的 hook，将 HTTP 获取与防抖相结合，建立在核心获取器库之上。
+
+```typescript jsx
+import { useDebouncedFetcher } from '@ahoo-wang/fetcher-react';
+
+const SearchInput = () => {
+  const [query, setQuery] = useState('');
+  const { loading, result, error, run } = useDebouncedFetcher({
+    debounce: { delay: 300 },
+    onSuccess: (data) => {
+      setSearchResults(data.results);
+    }
+  });
+
+  const handleChange = (value: string) => {
+    setQuery(value);
+    if (value.trim()) {
+      run({
+        url: '/api/search',
+        method: 'GET',
+        params: { q: value }
+      });
+    }
+  };
+
+  return (
+    <div>
+      <input
+        value={query}
+        onChange={(e) => handleChange(e.target.value)}
+        placeholder="搜索..."
+      />
+      {loading && <div>搜索中...</div>}
+      {error && <div>错误: {error.message}</div>}
+      {result && <SearchResults data={result} />}
+    </div>
+  );
+};
+```
+
+**防抖策略：**
+
+- **前缘执行**: 第一次调用时立即执行，然后对后续调用进行防抖
+- **后缘执行**: 最后一次调用后延迟执行（默认行为）
+- **前缘 + 后缘**: 立即执行，如果再次调用则在延迟后再次执行
+
 ### useExecutePromise Hook
 
 `useExecutePromise` hook 管理异步操作，具有自动状态处理、竞态条件保护和 promise 状态选项支持。
@@ -632,6 +763,107 @@ const MyComponent = () => {
 
 ## API 参考
 
+### 防抖 Hooks
+
+#### useDebouncedCallback
+
+```typescript
+function useDebouncedCallback<T extends (...args: any[]) => any>(
+  callback: T,
+  options: UseDebouncedCallbackOptions,
+): UseDebouncedCallbackReturn<T>;
+```
+
+一个 React hook，为回调函数提供防抖版本，支持前缘/后缘执行选项。
+
+**类型参数:**
+
+- `T`: 回调函数的类型
+
+**参数:**
+
+- `callback`: 要防抖的函数
+- `options`: 配置对象
+  - `delay`: 执行前的延迟毫秒数（必需，正数）
+  - `leading?`: 第一次调用时立即执行（默认: false）
+  - `trailing?`: 最后一次调用后延迟执行（默认: true）
+
+**返回:**
+
+包含以下内容的对象：
+
+- `run`: 使用参数执行防抖回调的函数
+- `cancel`: 取消任何待处理防抖执行的函数
+- `isPending`: 返回布尔值表示防抖执行当前是否待处理的函数
+
+#### useDebouncedExecutePromise
+
+```typescript
+function useDebouncedExecutePromise<R = unknown, E = FetcherError>(
+  options: UseDebouncedExecutePromiseOptions<R, E>,
+): UseDebouncedExecutePromiseReturn<R, E>;
+```
+
+将 Promise 执行与防抖功能相结合。
+
+**类型参数:**
+
+- `R`: Promise 结果的类型（默认为 unknown）
+- `E`: 错误的类型（默认为 FetcherError）
+
+**参数:**
+
+- `options`: 包含 Promise 执行选项和防抖设置的配置对象
+  - `debounce`: 防抖配置（delay、leading、trailing）
+  - `UseExecutePromiseOptions` 的所有选项
+
+**返回:**
+
+包含以下内容的对象：
+
+- `loading`: 布尔值，表示 Promise 当前是否正在执行
+- `result`: Promise 的解析值
+- `error`: 执行期间发生的任何错误
+- `status`: 当前执行状态
+- `run`: 使用提供的参数执行防抖 Promise 的函数
+- `cancel`: 取消任何待处理防抖执行的函数
+- `isPending`: 布尔值，表示防抖调用是否待处理
+- `reset`: 将 hook 状态重置为初始值的函数
+
+#### useDebouncedFetcher
+
+```typescript
+function useDebouncedFetcher<R, E = FetcherError>(
+  options: UseDebouncedFetcherOptions<R, E>,
+): UseDebouncedFetcherReturn<R, E>;
+```
+
+专门的 hook，将 HTTP 获取与防抖相结合。
+
+**类型参数:**
+
+- `R`: 获取结果的类型
+- `E`: 错误的类型（默认为 FetcherError）
+
+**参数:**
+
+- `options`: 扩展 `UseFetcherOptions` 和 `DebounceCapable` 的配置对象
+  - HTTP 请求选项（method、headers、timeout 等）
+  - `debounce`: 防抖配置（delay、leading、trailing）
+
+**返回:**
+
+包含以下内容的对象：
+
+- `loading`: 布尔值，表示获取当前是否正在执行
+- `result`: 获取的解析值
+- `error`: 执行期间发生的任何错误
+- `status`: 当前执行状态
+- `exchange`: 表示正在进行的获取操作的 FetchExchange 对象
+- `run`: 使用请求参数执行防抖获取的函数
+- `cancel`: 取消任何待处理防抖执行的函数
+- `isPending`: 布尔值，表示防抖调用是否待处理
+
 ### useFetcher
 
 ```typescript

package/dist/core/index.d.ts

@@ -4,4 +4,6 @@ export * from './useRequestId';
 export * from './useLatest';
 export * from './useMounted';
 export * from './useRefs';
+export * from './useDebouncedCallback';
+export * from './useDebouncedExecutePromise';
 //# sourceMappingURL=index.d.ts.map

package/dist/core/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAaA,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAaA,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,wBAAwB,CAAC;AACvC,cAAc,8BAA8B,CAAC"}

package/dist/core/useDebouncedCallback.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Options for configuring the debounced callback behavior.
+ */
+export interface UseDebouncedCallbackOptions {
+    /** The delay in milliseconds before the callback is invoked. Must be a positive number. */
+    delay: number;
+    /** Whether to invoke the callback immediately on the leading edge of the timeout. Defaults to false. */
+    leading?: boolean;
+    /** Whether to invoke the callback on the trailing edge of the timeout. Defaults to true. */
+    trailing?: boolean;
+}
+/**
+ * Return type of the useDebouncedCallback hook.
+ * @template T - The type of the original callback function.
+ */
+export interface UseDebouncedCallbackReturn<T extends (...args: any[]) => any> {
+    /** Function to execute the debounced callback with the provided arguments. */
+    readonly run: (...args: Parameters<T>) => void;
+    /** Function to cancel any pending debounced execution. */
+    readonly cancel: () => void;
+    /** Function to check if a debounced execution is currently pending. */
+    readonly isPending: () => boolean;
+}
+/**
+ * A React hook that provides a debounced version of a callback function.
+ * The callback will be invoked after a specified delay, with options for leading and trailing edge execution.
+ * This is useful for optimizing performance in scenarios like search input handling or window resizing.
+ *
+ * @template T - The type of the callback function.
+ * @param callback - The function to debounce. It can accept any number of arguments.
+ * @param options - Configuration object for debouncing behavior.
+ * @param options.delay - The delay in milliseconds before the callback is invoked. Must be a positive number.
+ * @param options.leading - If true, the callback is invoked immediately on the first call, then debounced. Defaults to false.
+ * @param options.trailing - If true, the callback is invoked after the delay on the last call. Defaults to true.
+ * @returns An object containing:
+ *   - `run`: Function to execute the debounced callback with arguments.
+ *   - `cancel`: Function to cancel any pending debounced execution.
+ *   - `isPending`: Function that returns true if a debounced execution is currently pending.
+ *
+ * @example
+ * ```typescript
+ * const { run, cancel } = useDebouncedCallback(
+ *   (query: string) => {
+ *     console.log('Searching for:', query);
+ *     // Perform search API call
+ *   },
+ *   { delay: 300 }
+ * );
+ *
+ * // Call the debounced function
+ * run('search term');
+ *
+ * // Cancel if needed
+ * cancel();
+ * ```
+ *
+ * @example With leading edge execution:
+ * ```typescript
+ * const { run } = useDebouncedCallback(
+ *   () => console.log('Immediate and debounced'),
+ *   { delay: 500, leading: true, trailing: true }
+ * );
+ *
+ * run(); // Logs immediately, then again after 500ms if called again
+ * ```
+ *
+ * @throws {Error} Throws an error if both `leading` and `trailing` options are set to false, as at least one must be true for the debounce to function.
+ * @throws Exceptions from the callback function itself should be handled by the caller.
+ */
+export declare function useDebouncedCallback<T extends (...args: any[]) => any>(callback: T, options: UseDebouncedCallbackOptions): UseDebouncedCallbackReturn<T>;
+//# sourceMappingURL=useDebouncedCallback.d.ts.map

package/dist/core/useDebouncedCallback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useDebouncedCallback.d.ts","sourceRoot":"","sources":["../../src/core/useDebouncedCallback.ts"],"names":[],"mappings":"AAeA;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C,2FAA2F;IAC3F,KAAK,EAAE,MAAM,CAAC;IACd,wGAAwG;IACxG,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,4FAA4F;IAC5F,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,0BAA0B,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG;IAC3E,8EAA8E;IAC9E,QAAQ,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;IAC/C,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,EAAE,MAAM,IAAI,CAAC;IAC5B,uEAAuE;IACvE,QAAQ,CAAC,SAAS,EAAE,MAAM,OAAO,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EACpE,QAAQ,EAAE,CAAC,EACX,OAAO,EAAE,2BAA2B,GACnC,0BAA0B,CAAC,CAAC,CAAC,CAwE/B"}

package/dist/core/useDebouncedExecutePromise.d.ts

@@ -0,0 +1,93 @@
+import { UseExecutePromiseOptions, UseExecutePromiseReturn } from './useExecutePromise';
+import { UseDebouncedCallbackOptions, UseDebouncedCallbackReturn } from './useDebouncedCallback';
+import { FetcherError } from '@ahoo-wang/fetcher';
+/**
+ * Interface for objects that support debouncing configuration.
+ * This interface defines the structure for debounce settings that can be applied
+ * to promise execution to control the timing and behavior of debounced calls.
+ */
+export interface DebounceCapable {
+    /**
+     * Debounce options for execute calls, including delay and leading/trailing behavior.
+     * Specifies how the debouncing should work, such as the delay duration and whether
+     * to execute on the leading edge, trailing edge, or both.
+     */
+    debounce: UseDebouncedCallbackOptions;
+}
+/**
+ * Options for configuring the useDebouncedExecutePromise hook.
+ * Combines promise execution options with debouncing capabilities to provide
+ * fine-grained control over asynchronous operations with rate limiting.
+ *
+ * @template R - The type of the promise result
+ * @template E - The type of the error (defaults to unknown)
+ */
+export interface UseDebouncedExecutePromiseOptions<R, E = unknown> extends UseExecutePromiseOptions<R, E>, DebounceCapable {
+}
+/**
+ * Return type for the useDebouncedExecutePromise hook.
+ * Provides access to the promise execution state and debounced execution controls,
+ * allowing components to trigger debounced promises and monitor their progress.
+ *
+ * @template R - The type of the promise result
+ * @template E - The type of the error (defaults to unknown)
+ */
+export interface UseDebouncedExecutePromiseReturn<R, E = unknown> extends Omit<UseExecutePromiseReturn<R, E>, 'execute'>, UseDebouncedCallbackReturn<UseExecutePromiseReturn<R, E>['execute']> {
+}
+/**
+ * A React hook that combines promise execution with debouncing functionality.
+ * This hook prevents excessive API calls by debouncing the execution of promises,
+ * which is particularly useful for scenarios like search inputs, form submissions,
+ * or any rapid user interactions that trigger asynchronous operations.
+ *
+ * The hook integrates the useExecutePromise hook for promise management with
+ * useDebouncedCallback for rate limiting, providing a seamless way to handle
+ * debounced asynchronous operations in React components.
+ *
+ * @template R - The type of the promise result (defaults to unknown)
+ * @template E - The type of the error (defaults to FetcherError)
+ * @param options - Configuration object containing:
+ *   - All options from UseExecutePromiseOptions (promise execution settings)
+ *   - debounce: Debounce configuration including delay, leading/trailing behavior
+ * @returns An object containing:
+ *   - loading: Boolean indicating if the promise is currently executing
+ *   - result: The resolved value of the promise (R)
+ *   - error: Any error that occurred during execution (E)
+ *   - status: Current execution status ('idle' | 'pending' | 'fulfilled' | 'rejected')
+ *   - run: Debounced function to execute the promise with provided arguments
+ *   - cancel: Function to cancel any pending debounced execution
+ *   - isPending: Boolean indicating if a debounced call is pending
+ *   - reset: Function to reset the hook state to initial values
+ * @throws {FetcherError} When the underlying promise execution fails and no custom error handler is provided
+ * @throws {Error} When invalid options are provided or debounce configuration is malformed
+ *
+ * @example
+ * ```tsx
+ * import { useDebouncedExecutePromise } from '@ahoo-wang/react';
+ *
+ * function SearchComponent() {
+ *   const { loading, result, error, run } = useDebouncedExecutePromise({
+ *     promise: async (query: string) => {
+ *       const response = await fetch(`/api/search?q=${query}`);
+ *       return response.json();
+ *     },
+ *     debounce: { delay: 300 },
+ *   });
+ *
+ *   const handleSearch = (query: string) => {
+ *     run(query);
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <input onChange={(e) => handleSearch(e.target.value)} />
+ *       {loading && <p>Searching...</p>}
+ *       {result && <ul>{result.map(item => <li key={item.id}>{item.name}</li>)}</ul>}
+ *       {error && <p>Error: {error.message}</p>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useDebouncedExecutePromise<R = unknown, E = FetcherError>(options: UseDebouncedExecutePromiseOptions<R, E>): UseDebouncedExecutePromiseReturn<R, E>;
+//# sourceMappingURL=useDebouncedExecutePromise.d.ts.map

package/dist/core/useDebouncedExecutePromise.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useDebouncedExecutePromise.d.ts","sourceRoot":"","sources":["../../src/core/useDebouncedExecutePromise.ts"],"names":[],"mappings":"AAaA,OAAO,EAEL,wBAAwB,EACxB,uBAAuB,EACxB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAEL,2BAA2B,EAC3B,0BAA0B,EAC3B,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAGlD;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,QAAQ,EAAE,2BAA2B,CAAC;CACvC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,iCAAiC,CAAC,CAAC,EAAE,CAAC,GAAG,OAAO,CAC/D,SAAQ,wBAAwB,CAAC,CAAC,EAAE,CAAC,CAAC,EACpC,eAAe;CAClB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,gCAAgC,CAAC,CAAC,EAAE,CAAC,GAAG,OAAO,CAC9D,SAAQ,IAAI,CAAC,uBAAuB,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,SAAS,CAAC,EACpD,0BAA0B,CAAC,uBAAuB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;CACvE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,wBAAgB,0BAA0B,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,YAAY,EACtE,OAAO,EAAE,iCAAiC,CAAC,CAAC,EAAE,CAAC,CAAC,GAC/C,gCAAgC,CAAC,CAAC,EAAE,CAAC,CAAC,CAqBxC"}