@ahoo-wang/fetcher-react 2.13.10 → 2.15.0

package/dist/core/useExecutePromise.d.ts

@@ -1,39 +1,62 @@
 import { PromiseState, UsePromiseStateOptions } from './usePromiseState';
 import { FetcherError } from '@ahoo-wang/fetcher';
+/**
+ * Configuration options for the useExecutePromise hook.
+ * @template R - The type of the resolved value from the promise.
+ * @template E - The type of the error value, defaults to unknown.
+ */
 export interface UseExecutePromiseOptions<R, E = unknown> extends UsePromiseStateOptions<R, E> {
     /**
      * Whether to propagate errors thrown by the promise.
      * If true, the execute function will throw errors.
      * If false (default), the execute function will return the error as the result instead of throwing.
+     * @default false
      */
     propagateError?: boolean;
 }
 /**
- * Type definition for a function that returns a Promise
- * @template R - The type of value the promise will resolve to
+ * Type definition for a function that returns a Promise.
+ * This is used as input to the execute function, allowing lazy evaluation of promises.
+ * @template R - The type of value the promise will resolve to.
  */
 export type PromiseSupplier<R> = () => Promise<R>;
 /**
- * Interface defining the return type of useExecutePromise hook
- * @template R - The type of the result value
+ * Interface defining the return type of the useExecutePromise hook.
+ * Provides state management and control functions for asynchronous operations.
+ * @template R - The type of the result value.
+ * @template E - The type of the error value, defaults to FetcherError.
  */
 export interface UseExecutePromiseReturn<R, E = FetcherError> extends PromiseState<R, E> {
     /**
      * Function to execute a promise supplier or promise.
-     * Returns a promise that resolves to the result on success, or the error if propagateError is false.
+     * Manages the loading state, handles errors, and updates the result state.
+     * @param input - A function that returns a Promise or a Promise directly.
+     * @returns A Promise that resolves to the result on success, or the error if propagateError is false.
+     * @throws {Error} If the component is unmounted when execute is called.
+     * @throws {E} If propagateError is true and the promise rejects.
      */
     execute: (input: PromiseSupplier<R> | Promise<R>) => Promise<R | E>;
-    /** Function to reset the state to initial values */
+    /**
+     * Function to reset the state to initial values.
+     * Clears loading, result, error, and sets status to idle.
+     */
     reset: () => void;
 }
 /**
- * A React hook for managing asynchronous operations with proper state handling
- * @template R - The type of the result value
- * @template E - The type of the error value
- * @param options - Configuration options for the hook
- * @returns An object containing the current state and control functions
+ * A React hook for managing asynchronous operations with proper state handling.
+ * Provides a way to execute promises while automatically managing loading states,
+ * handling errors, and preventing state updates on unmounted components or stale requests.
+ *
+ * @template R - The type of the result value, defaults to unknown.
+ * @template E - The type of the error value, defaults to FetcherError.
+ * @param options - Optional configuration options for the hook behavior.
+ * @returns An object containing the current promise state and control functions.
+ *
+ * @throws {Error} When execute is called on an unmounted component.
+ * @throws {E} When propagateError is true and the executed promise rejects.
  *
  * @example
+ * Basic usage with state management:
  * ```typescript
  * import { useExecutePromise } from '@ahoo-wang/fetcher-react';
  *
@@ -63,14 +86,29 @@ export interface UseExecutePromiseReturn<R, E = FetcherError> extends PromiseSta
  *     </div>
  *   );
  * }
+ * ```
  *
- * // Example with propagateError set to true
+ * @example
+ * Using propagateError for try/catch error handling:
+ * ```typescript
  * const { execute } = useExecutePromise<string>({ propagateError: true });
- * try {
- *   await execute(fetchData);
- * } catch (err) {
- *   console.error('Error occurred:', err);
- * }
+ *
+ * const handleSubmit = async () => {
+ *   try {
+ *     const data = await execute(fetchUserData);
+ *     console.log('Success:', data);
+ *   } catch (err) {
+ *     console.error('Error occurred:', err);
+ *   }
+ * };
+ * ```
+ *
+ * @example
+ * Executing a promise directly instead of a supplier function:
+ * ```typescript
+ * const { execute } = useExecutePromise<number>();
+ * const promise = fetch('/api/count').then(r => r.json());
+ * const result = await execute(promise);
  * ```
  */
 export declare function useExecutePromise<R = unknown, E = FetcherError>(options?: UseExecutePromiseOptions<R, E>): UseExecutePromiseReturn<R, E>;

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

@@ -1 +1 @@
-{"version":3,"file":"useExecutePromise.d.ts","sourceRoot":"","sources":["../../src/core/useExecutePromise.ts"],"names":[],"mappings":"AAeA,OAAO,EAEL,YAAY,EACZ,sBAAsB,EACvB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,MAAM,WAAW,wBAAwB,CAAC,CAAC,EAAE,CAAC,GAAG,OAAO,CACtD,SAAQ,sBAAsB,CAAC,CAAC,EAAE,CAAC,CAAC;IACpC;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,IAAI,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC;AAElD;;;GAGG;AACH,MAAM,WAAW,uBAAuB,CAAC,CAAC,EAAE,CAAC,GAAG,YAAY,CAC1D,SAAQ,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC;IAC1B;;;OAGG;IACH,OAAO,EAAE,CAAC,KAAK,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACpE,oDAAoD;IACpD,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,YAAY,EAC7D,OAAO,CAAC,EAAE,wBAAwB,CAAC,CAAC,EAAE,CAAC,CAAC,GACvC,uBAAuB,CAAC,CAAC,EAAE,CAAC,CAAC,CA0D/B"}
+{"version":3,"file":"useExecutePromise.d.ts","sourceRoot":"","sources":["../../src/core/useExecutePromise.ts"],"names":[],"mappings":"AAeA,OAAO,EAEL,YAAY,EACZ,sBAAsB,EACvB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD;;;;GAIG;AACH,MAAM,WAAW,wBAAwB,CAAC,CAAC,EAAE,CAAC,GAAG,OAAO,CACtD,SAAQ,sBAAsB,CAAC,CAAC,EAAE,CAAC,CAAC;IACpC;;;;;OAKG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,IAAI,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC;AAElD;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB,CAAC,CAAC,EAAE,CAAC,GAAG,YAAY,CAC1D,SAAQ,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC;IAC1B;;;;;;;OAOG;IACH,OAAO,EAAE,CAAC,KAAK,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACpE;;;OAGG;IACH,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoEG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,YAAY,EAC7D,OAAO,CAAC,EAAE,wBAAwB,CAAC,CAAC,EAAE,CAAC,CAAC,GACvC,uBAAuB,CAAC,CAAC,EAAE,CAAC,CAAC,CAwE/B"}

package/dist/fetcher/index.d.ts

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

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/fetcher/index.ts"],"names":[],"mappings":"AAaA,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/fetcher/index.ts"],"names":[],"mappings":"AAaA,cAAc,cAAc,CAAC;AAC7B,cAAc,uBAAuB,CAAC"}

package/dist/fetcher/useDebouncedFetcher.d.ts

@@ -0,0 +1,92 @@
+import { UseFetcherOptions, UseFetcherReturn } from './useFetcher';
+import { FetcherError } from '@ahoo-wang/fetcher';
+import { DebounceCapable, UseDebouncedCallbackReturn } from '../core';
+/**
+ * Configuration options for the useDebouncedFetcher hook.
+ * Extends UseFetcherOptions with debouncing capabilities to control the rate
+ * at which fetch requests are executed.
+ *
+ * @template R - The type of the fetch result
+ * @template E - The type of the error (defaults to FetcherError)
+ */
+export interface UseDebouncedFetcherOptions<R, E = FetcherError> extends UseFetcherOptions<R, E>, DebounceCapable {
+}
+/**
+ * Return type of the useDebouncedFetcher hook.
+ * Provides the same state properties as useFetcher (except execute) along with
+ * debounced execution controls.
+ *
+ * @template R - The type of the fetch result
+ * @template E - The type of the error (defaults to FetcherError)
+ */
+export interface UseDebouncedFetcherReturn<R, E = FetcherError> extends Omit<UseFetcherReturn<R, E>, 'execute'>, UseDebouncedCallbackReturn<UseFetcherReturn<R, E>['execute']> {
+}
+/**
+ * A React hook that provides a debounced version of the useFetcher hook.
+ * This hook wraps the fetcher's execute function with debouncing to prevent
+ * excessive API calls during rapid user interactions, such as typing in a search field.
+ *
+ * The debouncing behavior is controlled by the `debounce` option, which specifies
+ * the delay and whether to execute on the leading edge, trailing edge, or both.
+ *
+ * @template R - The type of the fetch result
+ * @template E - The type of the error (defaults to FetcherError)
+ * @param options - Configuration options including fetcher settings and debounce parameters
+ * @returns An object containing the fetch state and debounced execution controls
+ *
+ * @throws {Error} If the debounce delay is not a positive number
+ * @throws {Error} If the fetcher configuration is invalid
+ *
+ * @example
+ * ```typescript
+ * import { useDebouncedFetcher } from '@ahoo-wang/fetcher-react';
+ *
+ * function SearchComponent() {
+ *   const { loading, result, error, run, cancel, isPending } = useDebouncedFetcher<string>({
+ *     debounce: { delay: 300, trailing: true },
+ *     onSuccess: (data) => console.log('Search results:', data),
+ *     onError: (err) => console.error('Search failed:', err),
+ *   });
+ *
+ *   const handleSearch = (query: string) => {
+ *     if (query.trim()) {
+ *       run({ url: `/api/search?q=${encodeURIComponent(query)}`, method: 'GET' });
+ *     } else {
+ *       cancel(); // Cancel any pending search
+ *     }
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <input
+ *         type="text"
+ *         placeholder="Search..."
+ *         onChange={(e) => handleSearch(e.target.value)}
+ *       />
+ *       {isPending() && <div>Searching...</div>}
+ *       {loading && <div>Loading...</div>}
+ *       {error && <div>Error: {error.message}</div>}
+ *       {result && <div>Results: {result}</div>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example Debounced form submission
+ * ```typescript
+ * const { run, cancel, isPending } = useDebouncedFetcher({
+ *   debounce: { delay: 500, leading: false, trailing: true },
+ *   onSuccess: () => console.log('Form submitted successfully'),
+ * });
+ *
+ * const handleSubmit = (formData: FormData) => {
+ *   run({
+ *     url: '/api/submit',
+ *     method: 'POST',
+ *     body: formData,
+ *   });
+ * };
+ * ```
+ */
+export declare function useDebouncedFetcher<R, E = FetcherError>(options: UseDebouncedFetcherOptions<R, E>): UseDebouncedFetcherReturn<R, E>;
+//# sourceMappingURL=useDebouncedFetcher.d.ts.map

package/dist/fetcher/useDebouncedFetcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useDebouncedFetcher.d.ts","sourceRoot":"","sources":["../../src/fetcher/useDebouncedFetcher.ts"],"names":[],"mappings":"AAaA,OAAO,EAAc,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAC/E,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EACL,eAAe,EAEf,0BAA0B,EAC3B,MAAM,SAAS,CAAC;AAGjB;;;;;;;GAOG;AACH,MAAM,WAAW,0BAA0B,CAAC,CAAC,EAAE,CAAC,GAAG,YAAY,CAC7D,SAAQ,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC,EAC7B,eAAe;CAAG;AAEtB;;;;;;;GAOG;AACH,MAAM,WAAW,yBAAyB,CAAC,CAAC,EAAE,CAAC,GAAG,YAAY,CAC5D,SAAQ,IAAI,CAAC,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,SAAS,CAAC,EAC7C,0BAA0B,CAAC,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;CAAG;AAEpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkEG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,CAAC,GAAG,YAAY,EACrD,OAAO,EAAE,0BAA0B,CAAC,CAAC,EAAE,CAAC,CAAC,GACxC,yBAAyB,CAAC,CAAC,EAAE,CAAC,CAAC,CAsBjC"}

package/dist/fetcher/useFetcher.d.ts

@@ -2,39 +2,124 @@ import { FetcherCapable, FetchExchange, FetchRequest, RequestOptions, FetcherErr
 import { PromiseState, UsePromiseStateOptions } from '../core';
 /**
  * Configuration options for the useFetcher hook.
- * Extends RequestOptions and FetcherCapable interfaces.
+ * Combines request configuration, fetcher selection, and promise state management options.
+ *
+ * @template R - The type of the expected result from the fetch operation
+ * @template E - The type of error that may be thrown (defaults to FetcherError)
  */
 export interface UseFetcherOptions<R, E = FetcherError> extends RequestOptions, FetcherCapable, UsePromiseStateOptions<R, E> {
 }
+/**
+ * Return type of the useFetcher hook.
+ * Provides access to the current fetch state, result data, and control functions.
+ *
+ * @template R - The type of the expected result from the fetch operation
+ * @template E - The type of error that may be thrown (defaults to FetcherError)
+ */
 export interface UseFetcherReturn<R, E = FetcherError> extends PromiseState<R, E> {
-    /** The FetchExchange object representing the ongoing fetch operation */
+    /**
+     * The FetchExchange object representing the current or most recent fetch operation.
+     * Contains request/response details, timing information, and extracted data.
+     * Undefined when no fetch operation has been performed.
+     */
     exchange?: FetchExchange;
+    /**
+     * Function to execute a fetch request.
+     * Automatically cancels any ongoing request before starting a new one.
+     *
+     * @param request - The fetch request configuration including URL, method, headers, etc.
+     * @returns Promise that resolves when the fetch operation completes (success or failure)
+     */
     execute: (request: FetchRequest) => Promise<void>;
 }
 /**
- * A React hook for managing asynchronous operations with proper state handling
- * @param options - Configuration options for the fetcher
- * @returns An object containing the current state and control functions
+ * A React hook for managing asynchronous HTTP fetch operations with comprehensive state handling,
+ * race condition protection, and automatic cleanup. Provides a clean interface for making API calls
+ * with loading states, error handling, and request cancellation.
+ *
+ * Key features:
+ * - Automatic request cancellation on component unmount or new requests
+ * - Race condition protection using request IDs
+ * - Comprehensive state management (idle, loading, success, error)
+ * - Type-safe result and error handling
+ * - Integration with fetcher ecosystem for advanced features
+ *
+ * @template R - The type of the expected result from the fetch operation
+ * @template E - The type of error that may be thrown (defaults to FetcherError)
+ * @param options - Configuration options for the fetcher including request settings,
+ *                  result extraction, error handling, and fetcher selection
+ * @returns An object containing the current fetch state, result data, error information,
+ *          and the execute function to trigger fetch operations
  *
- * @example
+ * @throws {FetcherError} When the fetch operation fails due to network issues,
+ *                        HTTP errors, or result extraction problems
+ * @throws {Error} When invalid options are provided or fetcher configuration is incorrect
+ *
+ * @example Basic GET request
  * ```typescript
  * import { useFetcher } from '@ahoo-wang/fetcher-react';
+ * import { ResultExtractors } from '@ahoo-wang/fetcher';
  *
- * function MyComponent() {
- *   const { loading, result, error, execute } = useFetcher<string>();
+ * function UserProfile({ userId }: { userId: string }) {
+ *   const { loading, result, error, execute } = useFetcher({
+ *     resultExtractor: ResultExtractors.Json,
+ *   });
  *
- *   const handleFetch = () => {
- *     execute({ url: '/api/data', method: 'GET' });
+ *   const fetchUser = () => {
+ *     execute({
+ *       url: `/api/users/${userId}`,
+ *       method: 'GET'
+ *     });
  *   };
  *
- *   if (loading) return <div>Loading...</div>;
- *   if (error) return <div>Error: {error.message}</div>;
- *   return (
- *     <div>
- *       <button onClick={handleFetch}>Fetch Data</button>
- *       {result && <p>{result}</p>}
- *     </div>
- *   );
+ *   // Handle loading, error, and success states in your component
+ * }
+ * ```
+ *
+ * @example POST request with error handling
+ * ```typescript
+ * import { useFetcher } from '@ahoo-wang/fetcher-react';
+ *
+ * function CreatePost() {
+ *   const { loading, result, error, execute } = useFetcher({
+ *     onSuccess: (data) => {
+ *       console.log('Post created:', data);
+ *       // Handle success (e.g., redirect, show notification)
+ *     },
+ *     onError: (error) => {
+ *       console.error('Failed to create post:', error);
+ *       // Handle error (e.g., show error message)
+ *     }
+ *   });
+ *
+ *   const handleSubmit = (postData: { title: string; content: string }) => {
+ *     execute({
+ *       url: '/api/posts',
+ *       method: 'POST',
+ *       body: JSON.stringify(postData),
+ *       headers: {
+ *         'Content-Type': 'application/json'
+ *       }
+ *     });
+ *   };
+ * }
+ * ```
+ *
+ * @example Using custom fetcher instance
+ * ```typescript
+ * import { useFetcher } from '@ahoo-wang/fetcher-react';
+ * import { getFetcher } from '@ahoo-wang/fetcher';
+ *
+ * // Using a named fetcher instance
+ * const customFetcher = getFetcher('my-custom-fetcher');
+ *
+ * function CustomApiComponent() {
+ *   const { loading, result, execute } = useFetcher({
+ *     fetcher: customFetcher,
+ *   });
+ *
+ *   // All requests will use the custom fetcher configuration
+ *   const fetchData = () => execute({ url: '/data', method: 'GET' });
  * }
  * ```
  */

package/dist/fetcher/useFetcher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useFetcher.d.ts","sourceRoot":"","sources":["../../src/fetcher/useFetcher.ts"],"names":[],"mappings":"AAaA,OAAO,EAEL,cAAc,EACd,aAAa,EACb,YAAY,EAEZ,cAAc,EAAE,YAAY,EAC7B,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EACL,YAAY,EAGZ,sBAAsB,EAEvB,MAAM,SAAS,CAAC;AAEjB;;;GAGG;AACH,MAAM,WAAW,iBAAiB,CAAC,CAAC,EAAE,CAAC,GAAG,YAAY,CACpD,SAAQ,cAAc,EACpB,cAAc,EACd,sBAAsB,CAAC,CAAC,EAAE,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,gBAAgB,CAAC,CAAC,EAAE,CAAC,GAAG,YAAY,CAAE,SAAQ,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC;IAC/E,wEAAwE;IACxE,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,OAAO,EAAE,CAAC,OAAO,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACnD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,CAAC,GAAG,YAAY,EAC5C,OAAO,CAAC,EAAE,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC,GAChC,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAC,CAsExB"}
+{"version":3,"file":"useFetcher.d.ts","sourceRoot":"","sources":["../../src/fetcher/useFetcher.ts"],"names":[],"mappings":"AAaA,OAAO,EAEL,cAAc,EACd,aAAa,EACb,YAAY,EAEZ,cAAc,EACd,YAAY,EACb,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EACL,YAAY,EAGZ,sBAAsB,EAEvB,MAAM,SAAS,CAAC;AAEjB;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB,CAAC,CAAC,EAAE,CAAC,GAAG,YAAY,CACpD,SAAQ,cAAc,EACpB,cAAc,EACd,sBAAsB,CAAC,CAAC,EAAE,CAAC,CAAC;CAE/B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC,EAAE,CAAC,GAAG,YAAY,CACnD,SAAQ,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,aAAa,CAAC;IAEzB;;;;;;OAMG;IACH,OAAO,EAAE,CAAC,OAAO,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACnD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0FG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,CAAC,GAAG,YAAY,EAC5C,OAAO,CAAC,EAAE,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC,GAChC,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAC,CA2FxB"}