import { type QueryKey, type UseQueryResult } from '@tanstack/react-query';
import type { NostrEvent, NostrFilter } from '@nostrify/types';
export interface UseNostrQueryOpts {
    /**
     * TanStack Query key for this query. Defaults to `['nostr', 'query', filters]`.
     * Pass your own key if the same filters can produce different results in
     * different contexts (e.g. different relay sets).
     */
    queryKey?: QueryKey;
    /** Relays to use for this query, bypassing the pool's `reqRouter`. */
    relays?: string[];
    /**
     * Overall maximum time in milliseconds to keep listening for events.
     * Defaults to 10000ms. The query usually ends sooner, when all relays
     * have finished, but misbehaving relays may never send an `EOSE`.
     */
    timeout?: number;
    /**
     * How long in milliseconds to batch incoming events before updating the
     * result set. Defaults to 250ms. Lower values make results appear sooner,
     * higher values reduce re-renders while events are streaming in.
     */
    batch?: number;
    /**
     * How events that arrive *after* the initial batch are surfaced:
     *
     * - `'auto'` (default): they are merged into `events` immediately.
     * - `'manual'`: they are buffered; `hasMore` becomes `true` and calling
     *   `showMore()` reveals them. Useful for feeds where content jumping
     *   around is undesirable.
     */
    updates?: 'auto' | 'manual';
    /** Whether the query should run. Defaults to `true`. */
    enabled?: boolean;
    /** TanStack Query `staleTime`, passed through. */
    staleTime?: number;
}
export interface UseNostrQueryResult {
    /**
     * The visible events. In `'manual'` update mode, events that arrived after
     * the initial batch are excluded until `showMore()` is called.
     */
    events: NostrEvent[];
    /** Whether events arrived after the initial batch that aren't shown yet (`'manual'` mode only). */
    hasMore: boolean;
    /** Reveal buffered late-arriving events (no-op in `'auto'` mode). */
    showMore: () => void;
    /** `true` until the initial events have arrived. */
    isLoading: boolean;
    /** `true` while the subscription is still open and more events may arrive. */
    isFetching: boolean;
    /** The underlying TanStack Query result. Its `data` contains *all* events received so far. */
    query: UseQueryResult<NostrEvent[]>;
}
/**
 * Query Nostr events progressively.
 *
 * Instead of racing relays like `nostr.query()` — where the fastest relay
 * decides when the query ends, even if it has incomplete (or no) data — this
 * hook consumes `nostr.req()` directly. Events are shown as soon as they
 * arrive (batched to limit re-renders), and the subscription stays open until
 * every relay has finished or `timeout` elapses, so data from slower relays
 * still makes it to the UI.
 *
 * Events are deduplicated and sorted reverse-chronologically, replaceable
 * events and deletions are processed, and results of search filters keep
 * their relay-provided order.
 *
 * ```tsx
 * function Feed() {
 *   const { events, hasMore, showMore, isLoading } = useNostrQuery(
 *     [{ kinds: [1], limit: 20 }],
 *     { updates: 'manual' },
 *   );
 *
 *   if (isLoading) return <Spinner />;
 *
 *   return (
 *     <>
 *       {hasMore && <button onClick={showMore}>Show more</button>}
 *       {events.map((event) => <Note key={event.id} event={event} />)}
 *     </>
 *   );
 * }
 * ```
 *
 * Requires `@tanstack/react-query` and a `NostrContext` provider.
 */
export declare function useNostrQuery(filters: NostrFilter[], opts?: UseNostrQueryOpts): UseNostrQueryResult;
//# sourceMappingURL=useNostrQuery.d.ts.map