@etoile-dev/react 1.0.0 → 1.0.1

package/README.md

@@ -481,10 +481,13 @@ const { results, isLoading } = useEtoileSearch({
   apiKey: process.env.ETOILE_API_KEY!,
   collections: ["paintings"],
   query,
+  shouldRetryOnError: true,
+  errorRetryCount: 2,
+  errorRetryInterval: 1000,
 });
 ```
 
-Returns `results`, `isLoading`, `error`, `appliedFilters`, and `refinedQuery`.
+Returns `results`, `isLoading`, `error`, `isError`, `appliedFilters`, and `refinedQuery`.
 
 ---
 

package/dist/hooks/useEtoileSearch.d.ts

@@ -12,6 +12,15 @@ export type UseEtoileSearchOptions = {
     offset?: number;
     /** Debounce delay in ms before firing the request (default: 100) */
     debounceMs?: number;
+    /**
+     * Whether failed requests should retry automatically (default: true).
+     * Uses `errorRetryCount` and `errorRetryInterval`.
+     */
+    shouldRetryOnError?: boolean;
+    /** Maximum number of retries after a failed request (default: 2). */
+    errorRetryCount?: number;
+    /** Delay between retries in ms (default: 1000). */
+    errorRetryInterval?: number;
     /**
      * Explicit metadata filters applied to results.
      * Mutually exclusive with `autoFilters`.
@@ -48,6 +57,8 @@ export type UseEtoileSearchReturn = {
     isLoading: boolean;
     /** Set when the last request failed; null otherwise. */
     error: unknown;
+    /** True when `error` is set. */
+    isError: boolean;
     /** Filters that were applied. Populated when `filters` or `autoFilters` is used. */
     appliedFilters?: SearchFilter[];
     /**
@@ -69,9 +80,12 @@ export type UseEtoileSearchReturn = {
  * @param options.limit - Maximum results to return (default: `10`).
  * @param options.offset - Number of results to skip for pagination (default: `0`).
  * @param options.debounceMs - Debounce delay in ms before firing the request (default: `100`).
+ * @param options.shouldRetryOnError - Retry failed requests automatically (default: `true`).
+ * @param options.errorRetryCount - Maximum retries after a failed request (default: `2`).
+ * @param options.errorRetryInterval - Delay between retries in ms (default: `1000`).
  * @param options.filters - Explicit metadata filters. Mutually exclusive with `autoFilters`.
  * @param options.autoFilters - When `true`, the AI extracts filters from the query automatically.
- * @returns Current search state: `results`, `isLoading`, `error`, `appliedFilters`, `refinedQuery`.
+ * @returns Current search state: `results`, `isLoading`, `error`, `isError`, `appliedFilters`, `refinedQuery`.
  *
  * @example Basic usage
  * ```tsx
@@ -106,7 +120,7 @@ export type UseEtoileSearchReturn = {
  * });
  * ```
  */
-export declare function useEtoileSearch({ apiKey, collections, query, limit, offset, debounceMs, filters, autoFilters, baseUrl, }: UseEtoileSearchOptions): UseEtoileSearchReturn;
+export declare function useEtoileSearch({ apiKey, collections, query, limit, offset, debounceMs, shouldRetryOnError, errorRetryCount, errorRetryInterval, filters, autoFilters, baseUrl, }: UseEtoileSearchOptions): UseEtoileSearchReturn;
 /**
  * Alias of `useEtoileSearch` for ergonomic imports in examples.
  *

package/dist/hooks/useEtoileSearch.js

@@ -13,9 +13,12 @@ import { Etoile } from "@etoile-dev/client";
  * @param options.limit - Maximum results to return (default: `10`).
  * @param options.offset - Number of results to skip for pagination (default: `0`).
  * @param options.debounceMs - Debounce delay in ms before firing the request (default: `100`).
+ * @param options.shouldRetryOnError - Retry failed requests automatically (default: `true`).
+ * @param options.errorRetryCount - Maximum retries after a failed request (default: `2`).
+ * @param options.errorRetryInterval - Delay between retries in ms (default: `1000`).
  * @param options.filters - Explicit metadata filters. Mutually exclusive with `autoFilters`.
  * @param options.autoFilters - When `true`, the AI extracts filters from the query automatically.
- * @returns Current search state: `results`, `isLoading`, `error`, `appliedFilters`, `refinedQuery`.
+ * @returns Current search state: `results`, `isLoading`, `error`, `isError`, `appliedFilters`, `refinedQuery`.
  *
  * @example Basic usage
  * ```tsx
@@ -50,7 +53,7 @@ import { Etoile } from "@etoile-dev/client";
  * });
  * ```
  */
-export function useEtoileSearch({ apiKey, collections, query, limit = 10, offset, debounceMs = 100, filters, autoFilters, baseUrl, }) {
+export function useEtoileSearch({ apiKey, collections, query, limit = 10, offset, debounceMs = 100, shouldRetryOnError = true, errorRetryCount = 2, errorRetryInterval = 1000, filters, autoFilters, baseUrl, }) {
     const [results, setResults] = React.useState([]);
     const [isLoading, setIsLoading] = React.useState(false);
     const [error, setError] = React.useState(null);
@@ -62,6 +65,18 @@ export function useEtoileSearch({ apiKey, collections, query, limit = 10, offset
     filtersRef.current = filters;
     const autoFiltersRef = React.useRef(autoFilters);
     autoFiltersRef.current = autoFilters;
+    const collectionsRef = React.useRef(collections);
+    collectionsRef.current = collections;
+    // Compare value-based inputs by value so inline objects/arrays don't retrigger endlessly.
+    const collectionsKey = React.useMemo(() => collections.join("\u001f"), [collections]);
+    const filtersKey = React.useMemo(() => JSON.stringify(filters ?? null), [filters]);
+    const autoFiltersKey = autoFilters === undefined ? "unset" : autoFilters ? "true" : "false";
+    const retryCount = Number.isFinite(errorRetryCount)
+        ? Math.max(0, Math.floor(errorRetryCount))
+        : 0;
+    const retryInterval = Number.isFinite(errorRetryInterval)
+        ? Math.max(0, errorRetryInterval)
+        : 0;
     // Debounce the raw query
     const [debouncedQuery, setDebouncedQuery] = React.useState(query);
     React.useEffect(() => {
@@ -77,10 +92,10 @@ export function useEtoileSearch({ apiKey, collections, query, limit = 10, offset
             setIsLoading(false);
         }
     }, [query]);
-    // Fetch on debounced query / filter change
+    // Fetch on debounced query / collection / filter / retry option change
     React.useEffect(() => {
         if (debouncedQuery.trim() === "") {
-            setResults([]);
+            setResults((prev) => (prev.length === 0 ? prev : []));
             setAppliedFilters(undefined);
             setRefinedQuery(undefined);
             setIsLoading(false);
@@ -88,40 +103,74 @@ export function useEtoileSearch({ apiKey, collections, query, limit = 10, offset
             return;
         }
         let active = true;
-        setError(null);
-        client
-            .search({
-            collections,
-            query: debouncedQuery,
-            limit,
-            ...(offset !== undefined && { offset }),
-            ...(filtersRef.current !== undefined && { filters: filtersRef.current }),
-            ...(autoFiltersRef.current !== undefined && { autoFilters: autoFiltersRef.current }),
-        })
-            .then((res) => {
-            if (!active)
-                return;
-            setResults(Array.isArray(res.results) ? res.results : []);
-            setAppliedFilters(res.appliedFilters);
-            setRefinedQuery(res.refinedQuery);
-        })
-            .catch((err) => {
+        let retryTimer;
+        let retryAttempt = 0;
+        const runSearch = () => {
             if (!active)
                 return;
-            setResults([]);
-            setAppliedFilters(undefined);
-            setRefinedQuery(undefined);
-            setError(err);
-        })
-            .finally(() => {
-            if (active)
+            setIsLoading(true);
+            client
+                .search({
+                collections: collectionsRef.current,
+                query: debouncedQuery,
+                limit,
+                ...(offset !== undefined && { offset }),
+                ...(filtersRef.current !== undefined && { filters: filtersRef.current }),
+                ...(autoFiltersRef.current !== undefined && { autoFilters: autoFiltersRef.current }),
+            })
+                .then((res) => {
+                if (!active)
+                    return;
+                setResults(Array.isArray(res.results) ? res.results : []);
+                setAppliedFilters(res.appliedFilters);
+                setRefinedQuery(res.refinedQuery);
+                setError(null);
+                setIsLoading(false);
+            })
+                .catch((err) => {
+                if (!active)
+                    return;
+                const canRetry = shouldRetryOnError && retryAttempt < retryCount;
+                if (canRetry) {
+                    retryAttempt += 1;
+                    retryTimer = setTimeout(runSearch, retryInterval);
+                    return;
+                }
+                setResults([]);
+                setAppliedFilters(undefined);
+                setRefinedQuery(undefined);
+                setError(err);
                 setIsLoading(false);
-        });
+            });
+        };
+        setError(null);
+        runSearch();
         return () => {
             active = false;
+            if (retryTimer) {
+                clearTimeout(retryTimer);
+            }
         };
-    }, [client, collections, debouncedQuery, limit, offset]);
-    return { results, isLoading, error, appliedFilters, refinedQuery };
+    }, [
+        client,
+        collectionsKey,
+        filtersKey,
+        autoFiltersKey,
+        debouncedQuery,
+        limit,
+        offset,
+        shouldRetryOnError,
+        retryCount,
+        retryInterval,
+    ]);
+    return {
+        results,
+        isLoading,
+        error,
+        isError: error != null,
+        appliedFilters,
+        refinedQuery,
+    };
 }
 /**
  * Alias of `useEtoileSearch` for ergonomic imports in examples.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@etoile-dev/react",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Official React primitives for Etoile - Headless, composable search components",
   "keywords": [
     "etoile",