@omnitron-dev/prism 0.2.0 → 0.3.1

package/dist/hooks/use-infinite-scroll.d.ts

@@ -0,0 +1,204 @@
+/**
+ * Page info returned from fetch function.
+ */
+export interface PageInfo {
+    /** Whether there are more pages */
+    hasNextPage: boolean;
+    /** Cursor or token for next page */
+    endCursor?: string | number;
+    /** Total count (optional) */
+    totalCount?: number;
+}
+/**
+ * Page data structure.
+ */
+export interface InfinitePage<TData> {
+    /** Items in this page */
+    items: TData[];
+    /** Page information */
+    pageInfo: PageInfo;
+}
+/**
+ * State for infinite scroll.
+ */
+export interface InfiniteScrollState<TData, TError> {
+    /** All loaded items (flattened) */
+    items: TData[];
+    /** All pages */
+    pages: InfinitePage<TData>[];
+    /** Error from last fetch */
+    error: TError | undefined;
+    /** Whether initial load is in progress */
+    isLoading: boolean;
+    /** Whether more data is being fetched */
+    isFetchingMore: boolean;
+    /** Whether there are more pages to fetch */
+    hasNextPage: boolean;
+    /** Whether any data has been loaded */
+    isEmpty: boolean;
+    /** Total count if available */
+    totalCount: number | undefined;
+}
+/**
+ * Options for useInfiniteScroll hook.
+ */
+export interface UseInfiniteScrollOptions<TData, TError> {
+    /** Called on successful fetch */
+    onSuccess?: (page: InfinitePage<TData>) => void | Promise<void>;
+    /** Called on fetch error */
+    onError?: (error: TError) => void | Promise<void>;
+    /** Initial cursor/offset */
+    initialCursor?: string | number;
+    /** Initial page size */
+    pageSize?: number;
+    /** Retry count on failure */
+    retry?: number | boolean;
+    /** Retry delay in ms */
+    retryDelay?: number | ((attempt: number) => number);
+    /** Intersection observer options for auto-loading */
+    observerOptions?: IntersectionObserverInit;
+}
+/**
+ * Return type for useInfiniteScroll hook.
+ */
+export interface UseInfiniteScrollReturn<TData, TError> {
+    /** All loaded items (flattened) */
+    items: TData[];
+    /** All pages */
+    pages: InfinitePage<TData>[];
+    /** Error from last fetch */
+    error: TError | undefined;
+    /** Whether initial load is in progress */
+    isLoading: boolean;
+    /** Whether more data is being fetched */
+    isFetchingMore: boolean;
+    /** Whether there are more pages to fetch */
+    hasNextPage: boolean;
+    /** Whether list is empty */
+    isEmpty: boolean;
+    /** Total count if available */
+    totalCount: number | undefined;
+    /** Fetch the next page */
+    fetchNextPage: () => Promise<void>;
+    /** Fetch first page (refresh) */
+    refresh: () => Promise<void>;
+    /** Reset to initial state */
+    reset: () => void;
+    /** Ref to attach to sentinel element for auto-loading */
+    sentinelRef: React.RefCallback<HTMLElement>;
+    /** Manually prepend items */
+    prependItems: (items: TData[]) => void;
+    /** Manually append items */
+    appendItems: (items: TData[]) => void;
+    /** Remove item by predicate */
+    removeItem: (predicate: (item: TData) => boolean) => void;
+    /** Update item by predicate */
+    updateItem: (predicate: (item: TData) => boolean, update: Partial<TData> | ((item: TData) => TData)) => void;
+}
+/**
+ * Fetch function signature.
+ */
+export type InfiniteFetchFn<TData> = (params: {
+    cursor?: string | number;
+    pageSize: number;
+}) => Promise<InfinitePage<TData>>;
+/**
+ * Hook for infinite scrolling with paginated data.
+ *
+ * @param fetchFn - Function to fetch a page of data
+ * @param options - Configuration options
+ * @returns Infinite scroll state and controls
+ *
+ * @example
+ * ```tsx
+ * function UserList() {
+ *   const {
+ *     items,
+ *     isLoading,
+ *     isFetchingMore,
+ *     hasNextPage,
+ *     fetchNextPage,
+ *     sentinelRef,
+ *   } = useInfiniteScroll<User>(
+ *     async ({ cursor, pageSize }) => {
+ *       const response = await fetch(
+ *         `/api/users?cursor=${cursor ?? ''}&limit=${pageSize}`
+ *       );
+ *       const data = await response.json();
+ *       return {
+ *         items: data.users,
+ *         pageInfo: {
+ *           hasNextPage: data.hasMore,
+ *           endCursor: data.nextCursor,
+ *           totalCount: data.total,
+ *         },
+ *       };
+ *     },
+ *     { pageSize: 20 }
+ *   );
+ *
+ *   if (isLoading) return <Spinner />;
+ *
+ *   return (
+ *     <div>
+ *       {items.map((user) => (
+ *         <UserCard key={user.id} user={user} />
+ *       ))}
+ *       {hasNextPage && (
+ *         <div ref={sentinelRef}>
+ *           {isFetchingMore ? <Spinner /> : 'Load more'}
+ *         </div>
+ *       )}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Manual loading
+ * function ProductList() {
+ *   const { items, hasNextPage, fetchNextPage, isFetchingMore } = useInfiniteScroll(
+ *     fetchProducts,
+ *     { pageSize: 10 }
+ *   );
+ *
+ *   return (
+ *     <>
+ *       <ProductGrid items={items} />
+ *       {hasNextPage && (
+ *         <Button onClick={fetchNextPage} loading={isFetchingMore}>
+ *           Load More
+ *         </Button>
+ *       )}
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With optimistic updates
+ * const { items, removeItem, updateItem, prependItems } = useInfiniteScroll(
+ *   fetchComments,
+ *   { pageSize: 20 }
+ * );
+ *
+ * // Add new comment at top
+ * const handleNewComment = (comment: Comment) => {
+ *   prependItems([comment]);
+ * };
+ *
+ * // Delete comment
+ * const handleDelete = (id: string) => {
+ *   removeItem((c) => c.id === id);
+ * };
+ *
+ * // Update comment
+ * const handleEdit = (id: string, text: string) => {
+ *   updateItem((c) => c.id === id, { text });
+ * };
+ * ```
+ */
+export declare function useInfiniteScroll<TData = unknown, TError = Error>(fetchFn: InfiniteFetchFn<TData>, options?: UseInfiniteScrollOptions<TData, TError>): UseInfiniteScrollReturn<TData, TError>;
+//# sourceMappingURL=use-infinite-scroll.d.ts.map

package/dist/hooks/use-infinite-scroll.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-infinite-scroll.d.ts","sourceRoot":"","sources":["../../src/hooks/use-infinite-scroll.ts"],"names":[],"mappings":"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"}

package/dist/hooks/use-intersection-observer.d.ts

@@ -0,0 +1,93 @@
+export interface UseIntersectionObserverOptions {
+    /** Root element for intersection (default: viewport) */
+    root?: Element | Document | null;
+    /** Root margin (default: '0px') */
+    rootMargin?: string;
+    /** Threshold(s) at which to trigger (default: 0) */
+    threshold?: number | number[];
+    /** Whether to disconnect after first intersection (default: false) */
+    triggerOnce?: boolean;
+    /** Whether to start observing immediately (default: true) */
+    enabled?: boolean;
+}
+export interface UseIntersectionObserverReturn {
+    /** Ref to attach to the target element */
+    ref: (element: Element | null) => void;
+    /** Current intersection entry */
+    entry: IntersectionObserverEntry | null;
+    /** Whether the element is intersecting */
+    isIntersecting: boolean;
+    /** Manually disconnect the observer */
+    disconnect: () => void;
+}
+/**
+ * useIntersectionObserver - Observe element visibility.
+ *
+ * Uses the Intersection Observer API to track when an element
+ * enters or exits the viewport (or a custom root element).
+ *
+ * @example
+ * ```tsx
+ * // Lazy loading images
+ * function LazyImage({ src }: { src: string }) {
+ *   const { ref, isIntersecting } = useIntersectionObserver({
+ *     triggerOnce: true,
+ *   });
+ *
+ *   return (
+ *     <div ref={ref}>
+ *       {isIntersecting ? (
+ *         <img src={src} alt="" />
+ *       ) : (
+ *         <Skeleton variant="rectangular" height={200} />
+ *       )}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Infinite scroll
+ * function InfiniteList({ items, onLoadMore }) {
+ *   const { ref, isIntersecting } = useIntersectionObserver({
+ *     threshold: 0.5,
+ *   });
+ *
+ *   useEffect(() => {
+ *     if (isIntersecting) {
+ *       onLoadMore();
+ *     }
+ *   }, [isIntersecting, onLoadMore]);
+ *
+ *   return (
+ *     <Box>
+ *       {items.map((item) => <Item key={item.id} {...item} />)}
+ *       <div ref={ref} style={{ height: 1 }} />
+ *     </Box>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Animate on scroll
+ * function AnimatedSection({ children }) {
+ *   const { ref, isIntersecting } = useIntersectionObserver({
+ *     threshold: 0.1,
+ *     triggerOnce: true,
+ *   });
+ *
+ *   return (
+ *     <Fade in={isIntersecting}>
+ *       <Box ref={ref}>{children}</Box>
+ *     </Fade>
+ *   );
+ * }
+ * ```
+ *
+ * @param options - Observer options
+ * @returns Ref, entry, intersection state, and disconnect function
+ */
+export declare function useIntersectionObserver(options?: UseIntersectionObserverOptions): UseIntersectionObserverReturn;
+//# sourceMappingURL=use-intersection-observer.d.ts.map

package/dist/hooks/use-intersection-observer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-intersection-observer.d.ts","sourceRoot":"","sources":["../../src/hooks/use-intersection-observer.ts"],"names":[],"mappings":"AAgBA,MAAM,WAAW,8BAA8B;IAC7C,wDAAwD;IACxD,IAAI,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,IAAI,CAAC;IACjC,mCAAmC;IACnC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oDAAoD;IACpD,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC9B,sEAAsE;IACtE,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,6DAA6D;IAC7D,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,6BAA6B;IAC5C,0CAA0C;IAC1C,GAAG,EAAE,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,KAAK,IAAI,CAAC;IACvC,iCAAiC;IACjC,KAAK,EAAE,yBAAyB,GAAG,IAAI,CAAC;IACxC,0CAA0C;IAC1C,cAAc,EAAE,OAAO,CAAC;IACxB,uCAAuC;IACvC,UAAU,EAAE,MAAM,IAAI,CAAC;CACxB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoEG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,GAAE,8BAAmC,GAAG,6BAA6B,CAuFnH"}

package/dist/hooks/use-isomorphic-layout-effect.d.ts

@@ -0,0 +1,34 @@
+/**
+ * useIsomorphicLayoutEffect Hook
+ *
+ * SSR-safe version of useLayoutEffect.
+ * Uses useLayoutEffect on client, useEffect on server.
+ *
+ * @module @omnitron-dev/prism/hooks
+ */
+import { useLayoutEffect } from 'react';
+/**
+ * Isomorphic layout effect that works in both SSR and CSR environments.
+ *
+ * - On the client: Uses useLayoutEffect for synchronous DOM operations
+ * - On the server: Uses useEffect to avoid SSR warnings
+ *
+ * @example
+ * ```tsx
+ * function Tooltip({ position }) {
+ *   const ref = useRef<HTMLDivElement>(null);
+ *
+ *   // Synchronously measure and position on client
+ *   useIsomorphicLayoutEffect(() => {
+ *     if (ref.current) {
+ *       const rect = ref.current.getBoundingClientRect();
+ *       // Position tooltip based on measurements
+ *     }
+ *   }, [position]);
+ *
+ *   return <div ref={ref}>Tooltip</div>;
+ * }
+ * ```
+ */
+export declare const useIsomorphicLayoutEffect: typeof useLayoutEffect;
+//# sourceMappingURL=use-isomorphic-layout-effect.d.ts.map

package/dist/hooks/use-isomorphic-layout-effect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-isomorphic-layout-effect.d.ts","sourceRoot":"","sources":["../../src/hooks/use-isomorphic-layout-effect.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AAEH,OAAO,EAAa,eAAe,EAAE,MAAM,OAAO,CAAC;AAMnD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,yBAAyB,wBAA8D,CAAC"}

package/dist/hooks/use-keyboard-shortcut.d.ts

@@ -0,0 +1,112 @@
+export interface KeyboardShortcut {
+    /** Main key (e.g., 'k', 'Enter', 'Escape') */
+    key: string;
+    /** Require Ctrl/Cmd key */
+    ctrl?: boolean;
+    /** Require Shift key */
+    shift?: boolean;
+    /** Require Alt key */
+    alt?: boolean;
+    /** Require Meta key (Cmd on Mac) */
+    meta?: boolean;
+}
+export interface UseKeyboardShortcutOptions {
+    /** Whether the shortcut is enabled (default: true) */
+    enabled?: boolean;
+    /** Prevent default browser behavior (default: true) */
+    preventDefault?: boolean;
+    /** Stop event propagation (default: false) */
+    stopPropagation?: boolean;
+    /** Target element (default: document) */
+    target?: EventTarget | null;
+    /** Event type (default: 'keydown') */
+    event?: 'keydown' | 'keyup' | 'keypress';
+    /** Ignore when focus is in input/textarea/contenteditable (default: false) */
+    ignoreInputs?: boolean;
+}
+/**
+ * useKeyboardShortcut - Handle keyboard shortcuts.
+ *
+ * Listens for keyboard events matching the specified shortcut
+ * and invokes the callback when matched.
+ *
+ * @example
+ * ```tsx
+ * // Simple shortcut
+ * function SearchDialog() {
+ *   const [open, setOpen] = useState(false);
+ *
+ *   useKeyboardShortcut({ key: 'k', ctrl: true }, () => {
+ *     setOpen(true);
+ *   });
+ *
+ *   return <Dialog open={open} onClose={() => setOpen(false)} />;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Save with Ctrl+S
+ * function Editor({ onSave }) {
+ *   useKeyboardShortcut(
+ *     { key: 's', ctrl: true },
+ *     () => onSave(),
+ *     { preventDefault: true }
+ *   );
+ *
+ *   return <TextField multiline />;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Escape to close
+ * function Modal({ onClose }) {
+ *   useKeyboardShortcut({ key: 'Escape' }, onClose);
+ *
+ *   return <div>Modal content</div>;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Multiple shortcuts
+ * function App() {
+ *   useKeyboardShortcut({ key: 'k', ctrl: true }, openSearch);
+ *   useKeyboardShortcut({ key: 'n', ctrl: true }, createNew);
+ *   useKeyboardShortcut({ key: '/', ctrl: true }, toggleHelp);
+ *
+ *   return <div>...</div>;
+ * }
+ * ```
+ *
+ * @param shortcut - Keyboard shortcut definition
+ * @param callback - Function to call when shortcut is triggered
+ * @param options - Hook options
+ */
+export declare function useKeyboardShortcut(shortcut: KeyboardShortcut, callback: (event: KeyboardEvent) => void, options?: UseKeyboardShortcutOptions): void;
+/**
+ * useEscapeKey - Convenience hook for Escape key handling.
+ *
+ * @example
+ * ```tsx
+ * function Modal({ onClose }) {
+ *   useEscapeKey(onClose);
+ *   return <div>Modal content</div>;
+ * }
+ * ```
+ */
+export declare function useEscapeKey(callback: (event: KeyboardEvent) => void, options?: Omit<UseKeyboardShortcutOptions, 'ignoreInputs'>): void;
+/**
+ * useEnterKey - Convenience hook for Enter key handling.
+ *
+ * @example
+ * ```tsx
+ * function SearchField({ onSearch }) {
+ *   useEnterKey(onSearch, { ignoreInputs: false });
+ *   return <TextField />;
+ * }
+ * ```
+ */
+export declare function useEnterKey(callback: (event: KeyboardEvent) => void, options?: UseKeyboardShortcutOptions): void;
+//# sourceMappingURL=use-keyboard-shortcut.d.ts.map

package/dist/hooks/use-keyboard-shortcut.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-keyboard-shortcut.d.ts","sourceRoot":"","sources":["../../src/hooks/use-keyboard-shortcut.ts"],"names":[],"mappings":"AAgBA,MAAM,WAAW,gBAAgB;IAC/B,8CAA8C;IAC9C,GAAG,EAAE,MAAM,CAAC;IACZ,2BAA2B;IAC3B,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,wBAAwB;IACxB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,sBAAsB;IACtB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,oCAAoC;IACpC,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,0BAA0B;IACzC,sDAAsD;IACtD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,uDAAuD;IACvD,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,8CAA8C;IAC9C,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,yCAAyC;IACzC,MAAM,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAC5B,sCAAsC;IACtC,KAAK,CAAC,EAAE,SAAS,GAAG,OAAO,GAAG,UAAU,CAAC;IACzC,8EAA8E;IAC9E,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAgDD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,gBAAgB,EAC1B,QAAQ,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,EACxC,OAAO,GAAE,0BAA+B,GACvC,IAAI,CAiDN;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,EACxC,OAAO,GAAE,IAAI,CAAC,0BAA0B,EAAE,cAAc,CAAM,GAC7D,IAAI,CAKN;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,EAAE,OAAO,GAAE,0BAA+B,GAAG,IAAI,CAEpH"}

package/dist/hooks/use-lazy-query.d.ts

@@ -0,0 +1,132 @@
+/**
+ * State for a lazy query.
+ */
+export interface LazyQueryState<TData, TError> {
+    /** Query result data */
+    data: TData | undefined;
+    /** Error from query */
+    error: TError | undefined;
+    /** Whether query is currently executing */
+    isLoading: boolean;
+    /** Whether query has succeeded at least once */
+    isSuccess: boolean;
+    /** Whether query has failed */
+    isError: boolean;
+    /** Whether query has been called at least once */
+    isCalled: boolean;
+    /** Whether query is fetching (includes refetch) */
+    isFetching: boolean;
+    /** Whether this is a refetch */
+    isRefetching: boolean;
+}
+/**
+ * Options for useLazyQuery hook.
+ */
+export interface UseLazyQueryOptions<TData, TError, TVariables> {
+    /** Called on successful query */
+    onSuccess?: (data: TData, variables: TVariables) => void | Promise<void>;
+    /** Called on query error */
+    onError?: (error: TError, variables: TVariables) => void | Promise<void>;
+    /** Called after query settles (success or error) */
+    onSettled?: (data: TData | undefined, error: TError | undefined, variables: TVariables) => void | Promise<void>;
+    /** Cache time in ms (0 = no cache) */
+    cacheTime?: number;
+    /** Stale time in ms (data considered fresh for this duration) */
+    staleTime?: number;
+    /** Retry count on failure */
+    retry?: number | boolean;
+    /** Delay between retries in ms */
+    retryDelay?: number | ((attempt: number) => number);
+    /** Initial data */
+    initialData?: TData;
+}
+/**
+ * Return type for useLazyQuery hook.
+ */
+export interface UseLazyQueryReturn<TData, TError, TVariables> {
+    /** Current query state */
+    data: TData | undefined;
+    error: TError | undefined;
+    isLoading: boolean;
+    isSuccess: boolean;
+    isError: boolean;
+    isCalled: boolean;
+    isFetching: boolean;
+    isRefetching: boolean;
+    /** Execute the query */
+    query: (variables: TVariables) => Promise<TData>;
+    /** Refetch with last variables */
+    refetch: () => Promise<TData | undefined>;
+    /** Reset query state */
+    reset: () => void;
+    /** Manually set data */
+    setData: (data: TData | ((prev: TData | undefined) => TData)) => void;
+}
+/**
+ * Hook for manual query execution with caching support.
+ *
+ * @param queryFn - Async function to execute
+ * @param options - Configuration options
+ * @returns Query state and control methods
+ *
+ * @example
+ * ```tsx
+ * function UserSearch() {
+ *   const users = useLazyQuery(
+ *     async (query: string) => {
+ *       const response = await fetch(`/api/users?q=${query}`);
+ *       if (!response.ok) throw new Error('Search failed');
+ *       return response.json();
+ *     },
+ *     {
+ *       onSuccess: (data) => console.log('Found users:', data.length),
+ *       cacheTime: 5 * 60 * 1000, // 5 minutes
+ *     }
+ *   );
+ *
+ *   const handleSearch = async (query: string) => {
+ *     const results = await users.query(query);
+ *     console.log('Results:', results);
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <SearchInput onSearch={handleSearch} />
+ *       {users.isLoading && <Spinner />}
+ *       {users.isError && <div>Error: {String(users.error)}</div>}
+ *       {users.data?.map((user) => <UserCard key={user.id} user={user} />)}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With caching
+ * const userDetails = useLazyQuery(
+ *   async (id: string) => fetchUser(id),
+ *   {
+ *     cacheTime: 10 * 60 * 1000, // Keep in cache for 10 min
+ *     staleTime: 60 * 1000, // Consider fresh for 1 min
+ *   }
+ * );
+ *
+ * // First call fetches, subsequent calls within staleTime return cache
+ * await userDetails.query('123');
+ * await userDetails.query('123'); // Returns from cache if not stale
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Manual data management
+ * const { data, setData, reset } = useLazyQuery(fetchData);
+ *
+ * // Optimistic update
+ * setData((prev) => prev ? { ...prev, count: prev.count + 1 } : prev);
+ *
+ * // Reset to clean state
+ * reset();
+ * ```
+ */
+export declare function useLazyQuery<TData = unknown, TError = Error, TVariables = void>(queryFn: (variables: TVariables) => Promise<TData>, options?: UseLazyQueryOptions<TData, TError, TVariables>): UseLazyQueryReturn<TData, TError, TVariables>;
+//# sourceMappingURL=use-lazy-query.d.ts.map

package/dist/hooks/use-lazy-query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-lazy-query.d.ts","sourceRoot":"","sources":["../../src/hooks/use-lazy-query.ts"],"names":[],"mappings":"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"}